amethyst/quartz/plans/2026-09-22-cyberspace-region-bags.md

Cyberspace §7 — opening a region bag

Written 2026-09-22, after DECK-0003 (SNO) shipped its reader and left kind 33330 closed. This is the plan for opening it.

Source: CYBERSPACE_V2.md §2 (coordinates), §4 (Cantor trees), §7 (location-based encryption and discovery), §8.6 (the bag event). Reference implementations: arkin0x/cyberspace-cli (Python) and arkin0x/cyberspace-cli-js (TypeScript, published as cyberspace-core), plus arkin0x/ONOSENDAI as the only client that does this today.

Decisions taken up front: all three layers ship (protocol, CLI, UI), and every sweep is a tap — no background CPU is ever spent on a stranger's puzzle, however cheap it looks.

---

1. What this reverses

amethyst/plans/2026-09-21-deck-0003-sno.md deferred bags as decision D2, on a reason that turned out to be wrong twice over.

The first version said opening a bag needs "§7.4 discovery scanning", and leaned on Amethyst having no position in cyberspace to scan from. §7.7 says the opposite in as many words:

The seeker's own position never enters this cost, because §7.1 makes looking and walking equivalent: a region key can be computed for any coordinate without traveling there.

Scanning your own neighbourhood is the opportunistic half, and §7.7 is blunt about what it is worth alone: "a bag is found only by intentionally deep scanning and/or wandering. With no additional information, any given bag is equally likely to be at any point in the full 2^256 coordinate space: an impossibly hardened secret." ONOSENDAI's own code agrees — destinationKeys.ts opens with "Things are hidden in cubes, so that key almost never fits a lock."

What finds a bag is a hint: the hider publishes an aligned box, and a seeker sweeps the candidate regions inside it. A client with no avatar, no position and no movement chain can do that.

The second wrong reason was that it would cost too much. It does not, at the heights anyone actually hides at. §3 measures it.

2. What a bag is, end to end

1. A hider picks a coordinate and a height h, and derives the region key: three per-axis Cantor roots of the aligned subtrees at h (§4.5, §4.6), combined by nested Cantor pairing into region_n (§4.7), then key = sha256(region_n) and lookup_id = sha256(key) (§7.2).
2. They encrypt everything they have hidden in that region — a JSON array of nostr events — with AES-256-GCM under that key, and publish it as a kind 33330 addressable by d = lookup_id (§7.6, §8.6).
3. They MAY attach a hint tag naming an aligned box the region lies in, one height per axis (§7.7).
4. A seeker sweeps the box: for each candidate region derive the key, hash to the lookup_id, and ask a relay for a bag with that d. Found, decrypt, verify the items, render by inner kind.

The two-layer hash is the whole trick: lookup_id is safe to publish because it is a hash of the key, so seeing it buys nothing without the region preimage.

3. What it costs, measured

A region key is three O(2^h) folds of BigInts that double in width at every level, plus one combine. Measured on this JVM against the same leaf-by-leaf fold cyberspace-core uses:

bag height h	one axis root	one combine + 2 SHA-256
5	0.03 ms	0.033 ms
8	0.18 ms	0.48 ms
12	9.2 ms	32 ms
16	555 ms	1,873 ms

Per key (three axes plus a combine) that is 1.2 ms at h8 and 2.1 s at h16, against the spec's own figures in §7.7 of 1.3 ms and 816 ms on one desktop core — within 2 to 3x, which is what a JVM BigInteger (Karatsuba and Toom-Cook, no FFT) should give against C.

A sweep decomposes per axis. The axes are independent all the way to the combine (§4.7), so a box of gap G costs 3 · 2^(G/3) tree builds and 2^G combines, not 2^G full keys. The combine term dominates above h8:

	gap 0	gap 6	gap 12	gap 18
h5	instant	2 ms	0.14 s	9 s
h8	2 ms	31 ms	2 s	2 min
h12	60 ms	2 s	2 min	2.3 h
h16	3.5 s	2 min	2 h	—

This agrees with §7.7's own table (gap 12 at h≤8 is "seconds", gap 24 is "hours"), and it says the affordable corner is most of the corner anyone uses. Android will be slower — measure it before quoting a number in the UI.

The growth ratio is ~2.2x per height, not 2x, in the spec's figures and in the measurement, because a pairing doubles the leaf count and the operand width. A GROWTH_RATIO_FLOOR of that shape is what ONOSENDAI's own calibration fits.

4. Layer 1 — quartz, protocol only

New package quartz/.../cyberspace/, beside the CyberspaceScale and CyberspaceCoordinate the SNO work already put there.

Piece	What	Pinned by
CyberspaceCoordinate	§2.2 in full: interleave and de-interleave X/Y/Z/plane. Fixed 256 bits, so a ByteArray(32); no bignum, no allocation per axis	§9.8's six vectors round-tripped, §7.7's three hint vectors
CantorTree	§4.5/§4.6: cantorPair, alignedBase, subtreeRoot(base, height), with the reference's maxComputeHeight refusal	cyberspace-cli's own roots, through the CLI harness
RegionKey	§7.2's two hashes over int_to_bytes_be_min	the same
CyberspaceHint	§7.7 tag parse with every MUST: arity, lowercase hex, aligned base, H in [0,85], canonical integers, H >= h, sector-tag agreement — and a malformed hint is absent, never a rejection of the bag	§7.7's three golden vectors
CyberspaceBagEvent	kind 33330: d/h/encrypted/hint/sector tags, AES-256-GCM open, §7.6's plaintext rules	round trip against the reference CLI's encrypt
RegionSweep	the axis-decomposed enumeration, as a cold sequence a caller pulls with its own budget	a unit test that a gap-0 hint is one candidate and equals the direct derivation

Two things need an expect/actual: arbitrary-precision integers (java.math.BigInteger on jvmAndroid) and AES-256-GCM (javax.crypto). iOS gets neither for now and the module declares it.

The rules that are easy to get wrong, all normative, all worth a test each:

• A failed decryption "MUST NOT be treated as an error in the bag" (§7.6) — it means only that this reader lacks the key.
• Items MAY be unsigned. A signed item must have the canonical id and a verifying signature or it is dropped, and only it: "one corrupt or forged item says nothing about the others". An unsigned item's pubkey is a claim and MUST NOT be shown as verified authorship.
• Placement is attributable to the bag's author; authorship of an item only to the item's own pubkey, and only when signed.
• An item's C tag must lie inside the bag's region, and a reader MAY drop one that does not.
• A reader that does not understand an item's kind skips it and renders the rest.

5. Layer 2 — amy

Thin assembly over Layer 1, which is where interop is proven. The SNO conformance harness already runs 11 of 11 against the reference implementations; these extend it.

amy cyberspace coord <hex>                 # x, y, z, plane
amy cyberspace region <hex> <height>       # region_n, key, lookup_id
amy cyberspace hint <bag.json>             # box, candidates, estimated cost
amy cyberspace sweep <bag.json> [--budget] # the lookup_ids, or the key when found
amy cyberspace open <bag.json> --key <hex> # decrypt, verify items, dump

region and open are directly diffable against cyberspace-cli; hint against hint-reference.py's golden vectors. No UI decision touches any of it.

6. Layer 3 — Amethyst

Only for a bag someone put in front of you: quoted in a note, or in a thread. Nothing sweeps the network on its own, and nothing sweeps on arrival.

A kind 33330 in a feed renders a card that has already parsed its hint and priced it, and says so: "Hidden in a 4,096-region box — about 2 minutes of searching." A button starts it. While it runs, progress and a cancel. Found, the items render through the cards that already exist: 3330 through SnoObjectCard, 1 as a note, anything else skipped.

Every sweep is a tap, including a gap-0 hint that the spec itself calls "a destination the seeker can compute or walk to directly, not a search" and which costs 60 ms. The consistency is the point: a reader never learns that some bags open themselves, so a hostile bag cannot hide inside that expectation.

Price before you spend. The budget comes from the hint tag and the h tag before a single tree is built, and it is a hard cap, because a bag can carry a gap-30 hint precisely to burn a day of a reader's battery. A sweep that would exceed the cap is not offered as a button at all — it is reported as out of reach.

7. Not in scope

• §7.4 position scanning. We have nowhere to stand, and §7.7 says it is not how things are found.
• §4–§6 movement chains, §8.3 spawn, DECK-0001 hyperspace. That is a client for cyberspace; this is a Nostr client reading an event.
• Publishing, hiding, or holding a region (§7.8). Read-only, like the rest of SNO.
• §9.7's GPS mapping: 96-digit decimal arithmetic with a hand-rolled deterministic trig series, carried so every client agrees where a place on Earth is. Amethyst has no Earth to agree about.

8. Order

1. Coordinates. CyberspaceCoordinate in full, §9.8 and §7.7 vectors. No bignum and no new dependency: an 85-bit axis splits at 64 into a 21-bit high half and an unsigned low Long, which is enough for the bit layout, the plane, the sector shift of §10 and alignedBase — and alignedBase is exactly what a sweep enumerates, so this is the foundation the rest stands on. Done, 8 tests, every vector the spec publishes.

   It does not improve the shard card, which was the claim when this was written. The thought was to upgrade the C tag line from a plane to a place, but the only human-readable thing a decode adds is the sector triple, and at 55 bits an axis that is a fifty-character string for a 12 cm cube — worse than the abbreviated coordinate already there, which at least copies. Two shards in one sector would be worth saying; there are 21 reachable 3330s and one author, so there is nothing to compare. Revisit when there is.

2. Cantor + region key, with the big integer and the height refusal. amy cyberspace region, diffed against cyberspace-cli. Done — see §9.

3. Hints. Parse, validate, price. amy cyberspace hint. The three golden vectors. Done — see §10.

4. The bag. AES-256-GCM, plaintext shapes, item verification. amy cyberspace open, round-tripped against the reference CLI's encrypt. Done — see §11.

5. The sweep, as a budgeted cold sequence. amy cyberspace sweep. Done — see §11.

6. The card, last, once every number it quotes is measured on a device. Done — see §12, which measures them on the device at the tap rather than baking in a constant.

Steps 1 to 5 have no product risk and every one of them is diffable against a reference implementation. Step 6 is the only judgement call, and it is small.

9. Step 2 as built

CantorTree, RegionKey, UBigInt, amy cyberspace coord|region. The conformance harness is now 12 of 12, the new section comparing 16 region keys and their coordinate decodes against cyberspace-cli — four coordinates (§9.8's london, nyc and origin, plus §7.7's ideaspace point) at heights 0, 1, 4 and 8. Amethyst derives the keys the rest of the network derives.

The big integer, and why there are two of them

The plan said "an expect/actual over java.math.BigInteger". The first attempt went the other way — one portable implementation everywhere — on the argument that a region key is a consensus value, since §7.2 turns it into an AES key, so two implementations is two chances to disagree and an object that opens on a desktop and not on a phone.

Measurement reversed that. Portable Kotlin came in 3 to 10 times slower than java.math.BigInteger on the operands a Cantor tree reaches, because BigInteger.multiplyToLen is a HotSpot intrinsic and the JDK adds Toom-Cook above a few hundred limbs. §7's whole feasibility is a number, and that factor is the difference between a search a reader waits for and one they abandon.

So: UBigInt is an expect class, aliased through a thin wrapper to java.math.BigInteger on jvmAndroid, and backed by PortableUBigInt on nativeMain — which covers Apple and Linux together, so there are two actuals and not three. A wrapper rather than a typealias for one reason: toMinimalBytes. The reference hashes int_to_bytes_be_min, and BigInteger.toByteArray() is two's complement, so it grows a 0x00 sign byte whenever the top bit is set — half of all numbers — and aliasing would have put that byte into a SHA-256 and produced a key nobody else derives.

What makes two implementations safe is that the disagreement is testable, and tested. PortableUBigIntDifferentialTest runs every operation against java.math.BigInteger over random inputs at fifteen widths from 0 to 352,000 bits, straddling the Karatsuba threshold in both directions, and a ninth test asserts the two actuals agree with each other on the same inputs — including the bytes, which is the one place aliasing would have gone wrong silently. CantorTreeBenchmark then folds a whole subtree both ways and compares the roots, which is where an off-by-one in the fold's stack would live rather than in the arithmetic.

What it costs, on the shipped path

The §3 table was measured on java.math.BigInteger, which is what now ships on JVM and Android, so it stands. Apple and Linux pay the portable multiplier on top; nothing there opens a bag yet.

Corrections to §3 worth carrying forward

The earlier measurement said a sweep decomposes per axis, 3 · 2^(G/3) tree builds and 2^G combines. Building it confirmed the decomposition and also that the combine dominates above about height 8 — a combine at height 12 is roughly ten times an axis root at the same height, because it multiplies two numbers the size of the root rather than folding up to one. A budget model that prices a sweep by its tree builds will under-quote badly; price it by 2^G combines and add the trees.

10. Step 3 as built

CyberspaceHint, amy cyberspace hint, and a harness section that runs §7.7's three golden vectors through the CLI and diffs them against the spec's own hint-reference.py. The harness is 13 of 13.

The vectors pin more than a parser. Each states a point, a bag height and three hint heights, then gives the coordinate the aligned base must come out as and the sector tags the bag must carry — so building a hint from the point has to reproduce the published tag byte for byte, and london_h5_box11, london_h5_x_exact and ideaspace_h8_y_open all do.

What the type says, and why

A hint is the hider's difficulty knob, so the number that matters is gapBits — (Hx - h) + (Hy - h) + (Hz - h) — and it is reported as an exponent rather than a count because it runs to 255 when all three axes are left open and nothing holds 2^255. §7.7's own table reads in those terms: 12 is seconds, 24 is hours, 30 or more is "days to never".

axisTrees is reported apart from candidates, and the asymmetry is the point. A sweep needs one Cantor tree per distinct base per axis and then one combine per candidate, so a sector-only hint on a height-5 bag is a hundred million trees against 2^75 combines: both say hopeless, only one of them can say it with a number. A budget that prices a sweep by its trees under-quotes by the same margin §9 warned about.

The rule that shapes the API

§7.7: "A hint tag that breaks any rule above MUST be treated as absent... A bad hint never invalidates the bag, because hints are advisory metadata about where to look; whether a bag is valid is decided by §7.2 and §7.6 alone."

So read returns null and never throws, for every one of: wrong arity, bad hex, uppercase hex, an unaligned base, a height outside [0, 85], a non-canonical integer ("011" is not "11"), a height below the bag's h, and — the one the spec states as a publisher rule without saying what a reader does — more than one hint tag, which is read the same way because a bag whose author cannot be read literally is exactly the case §7.7's remedy is for.

The canonical-integer rule is worth keeping for the same reason the aligned base is: both exist so that two hiders who hint the same box publish the same bytes, and a reader that accepts "05" alongside "5" lets one box have two spellings and breaks comparison by equality.

11. Steps 4 and 5 as built

CyberspaceBagEvent and RegionSweep in quartz, amy cyberspace open and amy cyberspace sweep over them, and two more harness sections. The harness is 15 of 15.

What the two new sections actually prove

Everything before this diffed a number against the reference — a key, a lookup id, a hint tag. These diff a ciphertext, which is the only test that catches a chain that agrees at every step and still cannot open a bag. cyberspace-cli derives the region key with location_encryption, seals the plaintext with encrypt_with_location_key, and writes the §8.6 tags with make_encrypted_content_event. amy is handed the event and a coordinate and has to reach the same 32 bytes: §2.2's interleave, §4.7's three Cantor roots, §7.2's two hashes, §7.6's nonce || ciphertext || tag. Section 8 then takes the coordinate away and makes it find the same bag from its hint box alone.

The box in section 8 comes from the reference's own coord_to_xyz / xyz_to_coord rather than from ours, so a disagreement about alignment shows up as a bag that is not in the box we were handed — not as a test grading its own arithmetic.

The two design decisions worth recording

open exits 0 on the wrong key. §7.6: "A failed decryption therefore means only that the reader does not hold this region's key; it MUST NOT be treated as an error in the bag." So a wrong key is a verdict (opened: false), the way sno parse reports an invalid payload, and the harness asserts the exit code as well as the field. What does fail is a bag that cannot be attempted at all: an unknown version (§8.6 says ignore it) or no aes-256-gcm payload to try.

sweep refuses before it spends. The gap is read from the hint and h tags and checked against --max-gap (default 20) before a single tree is built, and the refusal quotes the exponent and names the flag that would buy it. A harness case pins it: a gap-33 hint is declined rather than swept. This is the same shape the card needs, which is why it lives in the CLI first — a budget that can be tested in a shell script is a budget that can be trusted in a feed.

A shell trap worth remembering

jq's // treats false as empty, so .opened // "null" turns a correct false into "null" and fails a passing test. Read booleans with a plain jq -r .field.

12. Step 6 as built

BagSweep in commons/cyberspace/ (headless: the quote, the budget and the cold flow) and RenderCyberspaceBag in amethyst/ui/note/types/ (the card), wired into NoteCompose and ThreadFeedView, with kind 33330 routed through EventCache's addressable path. Nine tests in commons.

Pricing without a constant

§3 of this plan ended with "Android will be slower — measure it before quoting a number in the UI". What shipped measures it at the moment of the tap, on the device that is about to pay, which is the same answer without a constant that goes stale on the next handset. The order is:

1. Free, while the row composes. BagSweep.quote reads two tags and does three subtractions. A box past MAX_GAP_BITS (20) or a bag deeper than MAX_BAG_HEIGHT (12, the ceiling ONOSENDAI puts on its own discovery scan) is reported as out of reach and never becomes a button. No Cantor tree is built for a hint the reader has already declined — a test pins that the flow emits nothing at all in that case.
2. One candidate, timed. On the tap, the box's own base region is derived and the elapsed time recorded. That candidate is never wasted work: a gap-0 hint names exactly it, so the measurement is the search for a destination hint.
3. The estimate, then the rest. perCandidate × candidates against a two-minute budget. It over-quotes — the first candidate is three axis roots plus a combine and every later one is a combine, so by about 4x at shallow heights and 2x at deep ones — and over-quoting is the safe direction for a number whose only job is to decide whether to spend somebody's battery.

A slower phone therefore refuses boxes a faster one accepts. That asymmetry is correct: the cost is the reader's, so the reader's hardware should decide.

What the card says, and what it never does

Every sweep is a tap, including a gap-0 hint, which §7.7 itself calls "a destination the seeker can compute or walk to directly, not a search" and which costs about a frame. A reader who learned that some bags open themselves would have learned an expectation a hostile bag could hide inside, so the one candidate is offered exactly like the million. A test pins it.

Scrolling the row away cancels: the flow is cold over a cold sequence and the card disposes its job, so a sweep never outlives the card that asked for it.

Items render through the cards that already exist — a 3330 shard through SnoObjectCard (palette fetched by WithSnoPalette, as a standalone object would be), a kind 1 as its text, anything else named and skipped, because §7.6 says a reader that does not understand an item's kind "skips it and renders the rest". The attribution is the non-obvious part and §7.6 fixes it: placement belongs to the bag's author, authorship only to a signed item's own pubkey. An unsigned item therefore carries a line saying its author is a claim, rather than borrowing either name.

One correction carried back into quartz

SnoShardEvent's KDoc said Amethyst "implements none of it" and that a reader without the key sees base64 and nothing else. Both were true when it was written. The class now points at RegionSweep and says what actually decides whether a bag opens — whether its own hint prices the search into reach.