Skip to content
KN-86 Deckline

ADR-0061: Gate values: deck-wide state outside the four-element economy

authority this ADR adds a category beside), ADR-0042 (enrich-never-gate), ADR-0055 (engine-priced awards: the payout path a gate value may not touch), ADR-0056 (the UDS budget and its 2026-07-27 amendment), ADR-0059 (the migrating loader that makes an appended field cheap), deck-state.md, the-vault.md, docs/_meta/cartridge-premise-audit-2026-07.md

Amendment (2026-07-30). Decision 9 deferred the struct append to The Vault’s re-anchoring, on the reasoning that persisting a field ahead of the cart that defines it fixes a shape still moving. Josh called it in the other direction, so the field landed on its own: DeckState gains uint8_t knowledge_index at DECK_STRUCT_VERSION 7. The rest of decision 9 holds, including that no writer exists yet; the re-anchoring still brings the one that raises the value. Measured after the append: sizeof(DeckState) is 4128 (the byte plus 3 alignment bytes), against the 8192 ceiling. No donor field was touched.

Context

Section titled “Context”

Josh’s premise for The Vault, recorded verbatim in cart-inspiration-map.md:

Six knowledge domains gated by a knowledge_index stat in Deck State; other cartridges can read that stat.

The economy authority defines four element classes (currency, standing, resource, goods). None of them covers a stat that is earned by reading and spent on nothing. The July 2026 premise audit recorded the conflict as open and ruled that the premise is authoritative, which makes the economy model the document that has to change.

Forcing functions

Section titled “Forcing functions”

The Vault is queued for re-anchoring, and DYNAMO (concept, named 2026-07-29) proposes a shared quantity in the same shape. Both need to know whether the deck has a sanctioned home for a stat like this before either one is designed, or two carts invent two mechanisms.

Constraints

Section titled “Constraints”
  • Universal Deck State is a file on the device’s microSD (deck.state, written by deck.c). The Canonical Hardware Specification records no deck-state size, and ADR-0056’s 2026-07-27 amendment retracts the 4 KB “region” its own body reasoned from. The enforcement point is the _Static_assert(sizeof(DeckState) <= 8192) in runtime/src/types.h, a number this project picks and raises when a field earns it.
  • Fields are appended. deck_state_load migrates an older file by copying the shared prefix and zero-filling what the newer layout added (ADR-0059), so an append costs a DECK_STRUCT_VERSION bump and nothing else.
  • Reputation already gates. Whatever this decision adds has to stay distinct from it.

Decision

Section titled “Decision”

knowledge_index becomes a gate value: deck-wide state that decides what a cartridge makes visible, sitting outside the four element classes rather than joining them as a fifth. Josh, on 2026-07-29: “i’m not a super huge fan of adding a 5th item to the economy, i understand knowledge_index is supposed to gate functionality. but if we can then progressively disclose/expose functionality in cartridges, gated solely by this value”.

  1. The four element classes are unchanged. Currency, standing, resource, and goods describe what the operator earns, holds, and spends. A gate value has no price, no payout, and no balance to draw down, so it never enters that circulation.
  2. economy-model.md gains a Gate values section naming the category, its one member, and the read-side rules below. The economy model stays the authority.
  3. knowledge_index is monotonic, and the model says so out loud. Faucet: research work in The Vault. Sink: none.
  4. Monotonic is safe here because the value is firewalled from the wallet. Its only sanctioned read is disclosure: a product tier, a supply option, or a knowledge domain becomes visible once the value crosses a threshold. It never multiplies a payout, never lowers a contract’s threat level, and never discounts a price. An unbounded rise therefore cannot inflate the economy, which is the job a paired sink exists to do.
  5. Progressive disclosure is the read side, and a fourth acquisition channel. Beside bought, discovered, and granted, the model now lists disclosed: capability a cartridge exposes at a threshold, never sold and never granted at boot.
  6. Thresholds are per-cart authoring data. The career simulators (tools/economy_sim.py, tools/economy-sim.lsp) model credits and reputation and gain no gate-value knob.
  7. A gate value never gates a first-party program. ADR-0042’s enrich-never-gate rule holds unchanged: programs are always present, and a cart enriches their data without gating access.
  8. One gate value is sanctioned by this ADR. DYNAMO’s proposed facility stock is a decaying, borrowable quantity, which is a different mechanism wearing the same clothes; Josh flagged it on 2026-07-29 as possibly reducing to an enhancer relationship between two carts. It stays parked in future-concepts.md §13 and is not sanctioned here. Each further gate value is its own decision.
  9. The UDS field is uint8_t knowledge_index (0-255), appended, at a DECK_STRUCT_VERSION 6 -> 7 bump. The append lands with the writer, in the engineering task for The Vault’s re-anchoring; declaring a persisted field ahead of a cart whose job Josh is still ideating would fix a shape that is still moving. The ceiling in types.h has ample room for one byte and is raised rather than donated against if it ever does not.

Options Considered

Section titled “Options Considered”

Option A: A fifth element class (REJECTED)

Section titled “Option A: A fifth element class (REJECTED)”

Add knowledge_index to the element table as its own class beside currency, standing, resource, and goods. Rejected by Josh directly. It also fails on its own terms: the four classes classify things the economy circulates, and a class whose members are never priced, paid, or spent describes something the economy does not touch.

Option B: Fold it into standing (reputation) (REJECTED)

Section titled “Option B: Fold it into standing (reputation) (REJECTED)”

Reputation is already a deck-wide non-spendable stat that gates, so the machinery exists (reputation_tier_for in mission_board.c). Rejected because the two have different faucets and different read sides: reputation is earned from mission outcomes and read as the board’s threat ceiling, while knowledge_index is earned by study inside one cartridge and read as capability disclosure inside others. Folding them would make an hour in the archive raise the mission board’s threat ceiling.

Option C: A gate value outside the element classes (ACCEPTED)

Section titled “Option C: A gate value outside the element classes (ACCEPTED)”

Name the category, keep the economy at four elements, and constrain the read side to disclosure. Chosen because it matches what the stat does, satisfies the premise (other cartridges read it), and adds no pressure on credit balancing.

Option D: Per-cart save data, no deck-wide stat (REJECTED)

Section titled “Option D: Per-cart save data, no deck-wide stat (REJECTED)”

Keep the value on The Vault’s cartridge. Rejected because the premise’s whole point is that other cartridges read it, and per-cart saves are unreachable with a different cart inserted.

Trade-off Analysis

Section titled “Trade-off Analysis”

Against Option A, the accepted option costs one extra concept: a reader of economy-model.md now has to learn that the element table is the economy and not the whole of deck-wide state. The section says so explicitly. In exchange the four-class taxonomy stays clean, and the faucet/sink discipline that governs the elements is not weakened by an exception carved inside it.

Against Option B, the cost is a second gating mechanism to implement and test where one already exists. The alternative was worse: a single blended stat would couple archive reading to board threat, and unpicking that later means a migration.

Against Option D, the cost is a UDS field and a version bump. That is cheap since ADR-0059 (prefix copy plus zero-fill), and it is the only option that satisfies the premise.

The real cost of the accepted option is a constraint on cart authors: the natural first instinct for a research stat is a payout bonus, and that is exactly what rule 4 forbids. The Vault’s current spec is built on those bonuses, so the re-anchoring has real conversion work.

Consequences

Section titled “Consequences”

Positive

Section titled “Positive”
  • The Vault has a sanctioned deck-wide stat to write to, and the audit’s open item closes.
  • The read-side rule gives cart authors one shape to follow: capabilities appear, payouts hold steady. That keeps the currency’s balance under the simulators’ control.
  • A monotonic stat is now a stated design choice with a recorded reason, and no longer reads as an oversight in the faucet/sink table.

Negative / Accepted costs

Section titled “Negative / Accepted costs”
  • Two gating mechanisms exist where one might have served.
  • The Vault’s Tier-2 spec is non-conformant until its re-anchoring: the-vault.md §4 pays +5% per 50 knowledge in ICE Breaker, +10% per 50 in Black Ledger, +20% and threat -1 on the VAULT DEEP DIG campaign archetype. Every one of those is the multiplier form rule 4 forbids. Recorded there as a seam; the conversion belongs to the re-anchoring.
  • One more UDS version bump is queued behind ADR-0056’s ownership blob (v7 here assumes the ownership append has not already claimed it; whichever lands first takes v7).

Follow-on work this ADR creates

Section titled “Follow-on work this ADR creates”
  • The Vault re-anchoring: convert the §4 multipliers to disclosure thresholds, and land uint8_t knowledge_index with the writer that raises it.
  • DYNAMO: decide its shared quantity on its own merits when the cart leaves concept.

Documentation Updates

Section titled “Documentation Updates”

Part of the decision. A PR that lands this ADR without these edits fails review.

Narrative (for the design history)

Section titled “Narrative (for the design history)”

The economy had four kinds of thing in it: money, a career record, investigation output, and goods to buy. The Vault’s premise called for a fifth, a knowledge score that rises as the operator reads and that every other cartridge can see, and the obvious move was to widen the taxonomy to hold it. Josh declined that widening, and the better answer turned out to be that the score was never an economic quantity at all. Nothing buys it and nothing buys anything with it. What it does is decide which options a cartridge shows: study the archive long enough and SynthFence lists product tiers it never listed before. That reframing pays for itself twice. It keeps the four-class economy intact, and it explains why a score that only ever rises needs no drain: because the score cannot touch money, no amount of it can unbalance the wallet. The rule that falls out is the one cart authors will feel, and it is the opposite of the usual reflex: research earns new capabilities, and it does not earn a bigger cut.