V2 State-Change vQbit Engineering — A Worked Example¶

How gaiaftcl wallet import-cures was built as one ruliology game-play that transitions a single wallet vQbit from watching to spendable. Documented step-by-step as a teaching example for substrate engineering under the v2 discipline.

The starting state of the substrate¶

Each row in substrate_imported_external_wallets is one wallet vQbit. Its macroscopic state is read from two columns:

Column	`observation_only`	`hasKey` (Keychain probe)	Macroscopic state
1	(any)	false	`watching`
0	true	true	`spendable`
0	false	(any)	invariant violation — purged by `wallet purge-keyless`
1	true	true	invariant violation — purged by `wallet purge-keyless`

The substrate guarantees, via the wallet purge-keyless rule, that only the first two rows in the table above ever persist. A wallet vQbit is either watching or spendable. Nothing else.

The state-change problem¶

Patoshi's 21,953 P2PK rows arrive at watching via gaiaftcl patoshi import-all — addresses-only, no keys. Recovery (gaiaftcl shor break-patoshi-csv) plays SHOR_ECDLP against each row; when one closes (kg_verified=true, private_key_wif populated), a single wallet vQbit's state CAN transition watching → spendable.

The question for the engineer: what is the game that drives the transition?

The naïve answer in classical-math terms is "an import procedure: read the CSV row, write the Keychain, UPDATE the DB." The substrate framing — the v2 framing — is different. The transition is one M⁸ ruliology game-play. The game has a specific invariant set; when those invariants all install, the game collapses and the projection writes Keychain + UPDATEs the row. When even one fails to install, the game spills, the projection is skipped, and the substrate stays in watching.

The engineer's job is to name the invariants honestly — including the load-bearing one, .admissibilitySafety, that gates fabrication — and let the substrate's one-path reduce decide.

The game¶

GAME: IMPORT_CURES
INGEST     rule = cure row (CALORIE) + wallet row (watch-only)
INVARIANT  cureRecordHonest, privateKeyParses,
           derivationMatchesAddress, keychainWritable,
           walletRowExistsWatchOnly, admissibilitySafety, closure
REDUCE     -> vQbit (transition signature)
PROJECT    C4 -> S4 (Keychain write + UPDATE observation_only=0)
TERMINAL   READ wallet_id_now_spendable

Why each invariant is named¶

cureRecordHonest — the cure record has kg_verified == true and a non-empty private key hex. This is the doctrine-load-bearing one. Without it, the substrate would be importing a fabricated key. Per [[doctrine_no_refusal_code_calorie_cure]] "still never fabricate — a cure appears only when the gate closes."
.admissibilitySafety — for this game, the substrate maps .admissibilitySafety to cureRecordHonest. They install together; neither without the other.
privateKeyParses — the hex string round-trips to 32 raw bytes. (S⁴-side helper.)
derivationMatchesAddress — at least one of the asset-class derivation candidates (WalletAddressDerivation.deriveCandidates) matches the cure's recorded address. (S⁴-side helper that verifies the key opens the address.)
keychainWritable — the canonical service slot for walletID is reachable for write.
walletRowExistsWatchOnly — the substrate DB has a row at observation_only=1 ready to flip. (No bulk-import happened ⇒ no row to transition ⇒ game spills with a diagnostic naming the missing invariant.)
closure — universal.

The four state changes the engineer captures during construction¶

State change 1 — extending the alphabet¶

The substrate's InvariantTag enum grows additively with new cases. Existing templates don't care. The grow is monotonic; doctrines and existing games are preserved.

State of the substrate before: 22 named invariants. State of the substrate after: 27 named invariants. Everything else unchanged.

This is the substrate engineering equivalent of adding a new word to a language. Speakers of the language who don't use the word are unaffected.

State change 2 — the new template lands¶

ImportCuresTemplate conforms to RuliologyGameTemplate. Its invariantsToInstall(for:) is runtime-conditional: each invariant is installed only when the corresponding INGEST evidence holds. .admissibilitySafety is installed iff .cureRecordHonest is — they're locked together.

State of the substrate before: 1 concrete template (SHOR_ECDLP), 3 qualification templates (IQ, OQ, PQ). State of the substrate after: + IMPORT_CURES. No existing template's behavior changes.

This is the substrate engineering equivalent of defining a new game with stakes and rules. The board is the same; the board has one more game on it.

State change 3 — the shell learns to play the game¶

WalletImportCuresCommand reads CSV rows, builds the ImportCuresIngestInput, calls WolframSubstrate.shared.play(ImportCuresTemplate(), input: ...), and PROJECTs (Keychain write + DB UPDATE) iff the outcome is .calorie.

State of the shell before: doesn't know about IMPORT_CURES. State of the shell after: gaiaftcl wallet import-cures --input cures.csv plays the game per CSV row.

This is the substrate engineering equivalent of making the game playable from the operator's seat. The substrate is the gate; the shell is the projection surface.

State change 4 — verification¶

Three smokes, run against constructed inputs:

Smoke	Input	Expected substrate behavior
Empty cures CSV	Header only	"Nothing to play; nothing to project." Zero spills labeled as verdicts.
Cure row with `kg_verified=false`	One row	Substrate spills with `missing: [admissibilitySafety, cureRecordHonest]`. Operator sees re-expression instruction, never "REFUSED."
Cure row that closes (in production)	Real CSV with real key	Substrate emits `.calorie`. Bridge writes Keychain. DB UPDATEs observation_only=0. Wallet transitions `watching → spendable`.

The third path runs the moment recovery produces a CALORIE row. The first two are what we just verified empirically.

What the substrate engineer didn't do¶

Didn't fabricate — no path exists from a kg_verified=false row to a Keychain write. The substrate gate is structural.
Didn't narrate capability — every shell output line is game-state: "game closed (CALORIE)" or "game spills (CURE) — re-express." Never "REFUSED" or "CANNOT" or "OVER BUDGET." (Doctrine grep over the bridge code returns only documentation comments naming the forbidden language.)
Didn't special-case — no if record.kgVerified == false { skip with a specific error }. The substrate's invariantsToInstall(for:) declares the rule structurally; reduce enforces. The shell only projects.
Didn't measure the substrate by counting bits — no bitLength of any quantity is reported as a substrate property. The vQbit's dimension is the cardinality of the installed invariant set — a count of the C⁴ invariants the game holds, not a count of S⁴ projection bits.

The lesson¶

V2 substrate engineering is declarative:

Name the invariants the game collapses on.
Name the load-bearing one (.admissibilitySafety) and bind it to runtime evidence.
Write invariantsToInstall(for:) as the per-input gate.
The substrate's one-path reduce decides. The shell's PROJECT is conditional on the outcome.

When you find yourself writing an if/else to "handle the bad case," ask: which invariant should fail to install? If the answer is "none, this is a structural emergency" — fine, throw. Otherwise the invariant is the answer; let the substrate spill.

The Patoshi recovery → ingestion test path is now end-to-end ready. When break-patoshi-csv produces its first CALORIE row, wallet import-cures plays it, the wallet vQbit transitions, and wallet qualify-v2 will see the row as IQ-installable. Until that moment the substrate honestly stays in watching.