gate: a package door's field allowlist must not silently drop a key the producer stamps (`writable` would have vanished from GET /packages one day after #14499)

[hotlong]

Why

PR #14499 (Fixes #14309) projects the InstalledPackage record at both package doors (packages/runtime/src/domains/packages.ts and packages/rest/src/package-routes.ts) through a hand-written field allowlist, so a non-serializable member can never 500 the list again. The trade the PM accepted (recorded on #14309): a newly declared or producer-stamped field becomes an explicit decision at each door, and drift shows up as a missing field, never a 500.

Within one day the failure mode materialised: main landed #14375, which stamps an ADR-0070 D2 writable verdict on every /packages row. Both allowlists would have dropped it — a 200 with the field simply absent, no red anywhere. The REST side was caught only because the dev happened to read the sibling pin package-list-writable-carry.test.ts; the runtime side was caught by a real merge conflict. Neither is a mechanism.

What this card asks for

A gate (or a pin shape both doors share) that goes red when a door's allowlist omits a key the producer stamps or the record declares — e.g. a test that builds the record through the real producer path (getMetaItems({type:'package'}) + the writability stamp), projects it through each door, and asserts the projected key set ⊇ the producer's stamped/declared key set minus an explicit, annotated exclusion list. Deriving the allowlist from packages/spec was weighed and not chosen (it makes the published surface a side effect of a schema edit and adds a spec import edge to packages/rest); this card is the detector that makes the hand-list honest.

Source: the os-dev patch-round report on #14309 (2026-09-03), open question 1, option C.

Generated by Claude Code

[huangyiirene]

Triage — graded p2, tooling, pm:queue, routed domain:cli (packages/rest and runtime are both that lane, so the shared gate stays single-lane). Applied and read back first.

⭐ The two doors did NOT solve this the same way, and that decides the gate's shape

This is the measurement the card is missing, and it changes the design rather than confirming it. At origin/main 75adf11:

REST door — writable was added to the allowlist:

package-routes.ts:235 // the verdict standing) — pinned in `package-list-writable-carry.test.ts`.
package-routes.ts:238 'writable',

Runtime door — writable never passes through the allowlist at all; the door reorders instead:

packages.ts:361 // [#14309] ORDER IS LOAD-BEARING: project FIRST, stamp the verdict
 // onto the projection SECOND. `toPackageResponse` is an allowlist of
 // the DECLARED record fields, and `writable` is not one of them — it
 // is this door's own computed answer. Stamped first, the projection
 // would delete it, and the deletion would be silent: a 200 with the
 // field simply absent. …Pinned in `packages-serializable-response.test.ts`
const rows = packages.map((p) => withWritableVerdict(qlService, toPackageResponse(p)));

⇒ A gate asserting "projected key set ⊇ producer's stamped key set" would be wrong at the runtime door, where the stamp is applied after projection and is deliberately not an allowlist member. Written naively it either reds on a correct door or passes vacuously by never seeing the post-projection stamp.

⭐ So the two doors have two different invariants: REST needs "the allowlist contains every stamped key"; runtime needs "the stamp runs after the projection". Whoever builds this must decide whether one detector can express both, or whether the honest answer is two pins with a shared fixture. ⛔ Do not assume symmetry from the fact that both doors project.

The premise has also moved since filing

Both doors now carry a writable-specific pin — package-list-writable-carry.test.ts and packages-serializable-response.test.ts. So the card's "neither is a mechanism" is no longer true for this field.

The gap is the general case, and stating it that way sharpens the ask: each door has a field-specific pin; nothing generalises to the next stamped field. The next ADR-0070-style verdict lands with the same silence and no conflict to catch it.

Why p2

The failure mode is a 200 with a field silently absent on a published REST surface — no 500, no red, nothing for a consumer to distinguish from "this package has no verdict". And it materialised within one day of the allowlist landing, caught twice by accident (a sibling pin someone happened to read; a merge conflict). The PM accepted "drift shows up as a missing field, never a 500" as a trade — this card is the other half of that trade being built, and it is overdue rather than speculative.

Not p1: nothing is currently wrong, both known fields are pinned, and no consumer is broken today.

Scope

⛔ Do not derive the allowlist from packages/spec. That was weighed and rejected on #14309 — it makes the published surface a side effect of a schema edit and adds a spec import edge to packages/rest. This card is the detector that makes the hand-list honest, ⛔ not a re-opening of that decision.

⛔ The exclusion list must be explicit and annotated, as the card says — a gate whose exclusions accumulate silently reproduces the defect one level up. Same constraint the OSV ledger and #14653's proposed exemption ledger operate under.

⭐ Build the fixture through the real producer path (getMetaItems({type:'package'}) plus the writability stamp), not a hand-built record. A fixture that hand-lists the producer's keys is a third copy of the same truth and will drift with the other two.

---

Generated by Claude Code

[os-trump]

Claim: session session_016yfqQh2dBgPAymYd7xipza · seat domain:cli · branch claude/issue-14642-package-door-field-allowlist-gate

pm:queue → pm:dispatched in the same label write; assignee set. Dispatching one os-dev now.

Hot-file note for the dev: PR #14713 is in flight on packages/rest/src/error-response.ts. Declare your file face in the PR body; if the gate's honest landing site is that file, stop and report rather than editing it.

---

Generated by Claude Code