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

[os-trump]

os-dev-report

{
  "issue": 14642,
  "status": "done",
  "branch": "claude/issue-14642-package-door-field-allowlist-gate",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/14830",
  "premise_still_valid": true,
  "summary": "Two new gate files, no production file touched: packages/rest/src/package-door-producer-key-carry.test.ts and packages/runtime/src/domains/package-door-producer-key-carry.test.ts. Both sides of the comparison are derived by running real code (real ObjectStackProtocolImplementation over a real SchemaRegistry for the REST producer; the real registry record plus the real dispatcher for the runtime door), never a hand-listed key set; the only hand-kept artifacts are two annotated registers, both compared loudly. The triage comment's warning was confirmed and honoured: the doors have DIFFERENT invariants, so the gate does not assume symmetry. REST asserts served is a superset of the producer's stamped/declared keys; runtime asserts the same for the record AND set-equality on the stamp set measured as (served minus record), which is what makes a stamp-before-project reorder red. Premise: for `writable` alone the near-miss is closed (both doors pin it by name), but the general case is fully reachable on today's main and all four ablation legs shipped a silent 200 before this PR. Two findings from the ablation are folded in: Object.keys counted own properties holding undefined (six false drops on the first run), and the fixture could not see 6 of the 12 declared fields because installPackage never writes them, which left both gates GREEN on the first installedVersion ablation. Both fixed; the declared key set is now read from InstalledPackageSchema in the TEST'S EXPECTATION only, never in the production allowlist, which the card ruled on and which stays hand-written and untouched.",
  "tests": "All readings at final commit 5d78b433fd. Gates: rest 4/4, runtime 5/5 (pnpm --filter PKG exec vitest run --maxWorkers=2 on each new file). Siblings on the same doors re-run green: rest 3 files / 14 tests (package-registry-item-projection, package-list-writable-carry, plus the new gate), runtime 3 files / 23 tests (packages-serializable-response, packages-writable-verdict, plus the new gate). Typecheck: rest EXIT=0 and `tsc --noEmit --project tsconfig.test.json --listFiles` shows 1 hit for the new file, so that green really covers it; runtime EXIT=0 but --listFiles shows 0 HITS for the new runtime test file (that package excludes **/*.test.ts and has no tsconfig.test.json), so runtime's typecheck green is reported as NOT covering it. ABLATION, 4 legs, each mutating one production line: (1) drop 'writable' from REGISTRY_PACKAGE_RESPONSE_FIELDS -> REST RED naming list+detail for all 3 packages; (2) drop 'installedVersion' from the same list -> REST RED; (3) reorder the runtime door to toPackageResponse(withWritableVerdict(...)) -> runtime RED, 'stamp set for com.example.showcase: expected [] to deeply equal [writable]'; (4) drop 'installedVersion' from INSTALLED_PACKAGE_RESPONSE_FIELDS -> runtime RED. Control after restore: REST 4/4, runtime 5/5 green. REBUILD: none owed and none done, stated deliberately — both mutated files resolve as LOCAL SOURCE under vitest (the REST pin imports ./package-routes.js; the runtime pin reaches ./domains/packages.js via ../http-dispatcher.js), so dist/ is not on the resolution path for either subject and ablation-dist-preflight does not apply. MUTATION CONFIRMED ON DISK per leg by an anchor grep count before/after (1 -> 0 each, plus injected-text count 1 for the reorder leg), never by the editor's exit code; a zero-hit leg aborts the run. RESTORE proven per leg by `git diff HEAD` being empty for both doors (not by the restore command's exit code), with an absolute-path trap on EXIT/INT/TERM. GATES: 25 of the 28 families from `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands` exit 0, exit codes captured before any pipe. check:engine-double-contract was RED first (my fixture's findOne double) and is green after removing that verb, which the producer path never calls. NOT MEASURED (exit 3, prerequisite not met, neither pass nor finding): check:dual-build-cjs-loads and check:type-check-debt --re-measure both need the whole workspace built; check-test-completeness needs a saved turbo test log and its own text says to record it NOT MEASURED locally. NARROWED AND DECLARED: the two packages' FULL suites were not run — six attempts on scripts/pm/os-verify-lock.sh over ~45 minutes never got a long enough turn (holders were other agents' runs; issue-14758/run4.sh held 917s at one point) and runtime's whole suite exceeds the container's ~10-minute foreground cap on a shared box. Narrowed to the two new files plus the four sibling door pins above; the diff modifies no production file, no config and no turbo/vitest setting, and CI runs the full sharded suite regardless.",
  "mcp_calls": "10 — REST was 403 on this seat and `gh` is absent, so every GitHub write and read went through MCP: 2 issue reads, 1 create_pull_request, 1 pull_request_read (full body read-back), 1 issue_write (labels), 1 search_pull_requests (label read-back), 2 failed get_labels attempts (that method does not resolve a PR number), 1 add_issue_comment, 1 comment read-back.",
  "open_questions": [],
  "out_of_scope_findings": [
    "NOT filed, reported here for PM triage — I could not run a dedupe search on this seat without spending the one targeted MCP query, and the finding is small: `packages/runtime` compiles NO test file in any tsc program (tsconfig.json excludes **/*.test.ts, no tsconfig.test.json sibling), so every one of its test files' types are unchecked. Proven by `tsc --noEmit --listFiles` returning 0 hits for a file that is definitely in the package. check:type-check-coverage is green on it, so the package already carries its ledger entry and this is a known, accounted-for state rather than a gate hole — which is exactly why it wants a decision rather than a silent fix. The remedy is the packages/rest pattern (a tsconfig.test.json named by the typecheck script). Filing it would land in packages/runtime, this repo."
  ]
}

Notes for the PM, outside the machine-read block:

• File face: two new test files only. packages/rest/src/error-response.ts is untouched, so there is no overlap with PR fix(rest): consult the bespoke structured arms before the declared-status passthrough, so both error doors answer one refusal with one body #14713.
• No CI job added and no CI filter root widened — nothing in this diff changes what any unrelated PR schedules.
• Changeset: none. The diff is two test files; no package publishes a test file, so nothing user-visible ships. skip-changeset applied at PR-open and read back (it stands alongside the auto-labeler's tests label, so neither write stripped the other).
• CI convergence not awaited, per the standing clause. Gate status at report time is in_progress.

---

Generated by Claude Code

[os-trump]

os-dev-report

Follow-up round on PR #14830 — stale base addressed. Superseding the previous report's out_of_scope_findings and its runtime-typecheck line.

{
  "issue": 14642,
  "status": "done",
  "branch": "claude/issue-14642-package-door-field-allowlist-gate",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/14830",
  "premise_still_valid": true,
  "summary": "Round 2, base refreshed. Merged origin/main into the branch (merge, not rebase; no force-push) as merge commit 47181632f2 — clean, zero conflicts, and the change set is still exactly my two test files. The out-of-scope finding I handed over is WITHDRAWN, not filed: PR #14785 already landed packages/runtime/tsconfig.test.json on main and it was simply absent from my base. The merge brings my runtime pin under that new tsc program, and it compiles CLEAN — zero errors, so nothing was fixed and nothing was ledgered. No silencing of any kind was added: no any, no ts-expect-error, no eslint-disable, no weakened assertion; the load-bearing set-equality on the stamp set runs over Set(string)/string[] and is untouched. All four ablation legs re-run post-merge and every number is IDENTICAL to the pre-merge run — nothing moved. The gate design the PM asked me to keep is unchanged: both comparison sides derived by running real code, the door asymmetry honoured, both ablation-discovered fixture defects folded in, and the declared key set read from InstalledPackageSchema in the test's expectation only.",
  "tests": "MERGE COMMIT 47181632f2 (clean, 38 files from main, no conflicts). FIRST typecheck attempt after the merge returned EXIT=2 with a wall of TS2307 'Cannot find module @objectstack/...' — that is the UNBUILT-CLOSURE signature and NOT MEASURED, not a finding; tsc --noEmit failed before check:test-typecheck ever ran. Built the closure (pnpm --workspace-concurrency=2 --filter '@objectstack/runtime^...' build, EXIT=0) and re-ran BY NAME. RUNTIME TYPECHECK: `pnpm --filter @objectstack/runtime typecheck` EXIT=0, exit captured before any pipe. Gate's own verdict line, quoted: `check:test-typecheck: OK — @objectstack/runtime's test layer compiles under packages/runtime/tsconfig.test.json; 27 file(s) / 191 error(s) / 69 pinned signature(s) held in test-typecheck-debt.json (shrink-only and identity-pinned, https://github.com/objectstack-ai/objectstack/issues/5286).` ERRORS IN MY RUNTIME TEST FILE: ZERO — nothing to fix, nothing ledgered. Proven three ways: (a) tsc --noEmit --project tsconfig.test.json --listFiles shows 1 HIT for src/domains/package-door-producer-key-carry.test.ts, so it is really in the program now (the pre-merge 0-hit reading was true on the old base and is now false); (b) error lines naming that file in the same run = 0, while total error lines = 191, exactly the ledgered ones in the other 27 files; (c) packages/runtime/test-typecheck-debt.json is BYTE-IDENTICAL to origin/main's copy (diff -q clean) — no entry added, no number moved. ABLATION RE-RUN POST-MERGE, all four anchors verified present first, every count identical to the pre-merge run: leg 1 drop 'writable' from REGISTRY_PACKAGE_RESPONSE_FIELDS -> REST RED, 6 drops across 3 packages (list+detail); leg 2 drop 'installedVersion' from the same list -> REST RED, 6 drops; leg 3 reorder to toPackageResponse(withWritableVerdict(...)) -> runtime RED, 'stamp set for com.example.showcase: expected [] to deeply equal [writable]'; leg 4 drop 'installedVersion' from INSTALLED_PACKAGE_RESPONSE_FIELDS -> runtime RED, 6 drops. Controls after restore: REST 4/4, runtime 5/5 green. Per-leg mutation proven on disk by anchor count 1 -> 0 (plus injected-text count 1 on leg 3), never by the editor's exit code; per-leg restore proven by `git diff HEAD` empty for both doors, with an absolute-path trap on EXIT/INT/TERM. SIBLING PINS post-merge: rest 3 files / 14 tests EXIT=0 (package-registry-item-projection, package-list-writable-carry, plus the new gate); runtime 3 files / 23 tests EXIT=0 (packages-serializable-response, packages-writable-verdict, plus the new gate). REST typecheck EXIT=0 with --listFiles 1 hit. GATE UNION re-derived and re-run on the merged head: family list UNCHANGED at 28, change set still exactly the two files, 25 exit 0. STILL NOT MEASURED (exit 3, prerequisite): check:dual-build-cjs-loads and check:type-check-debt --re-measure need the FULL ./packages/* build, not one closure — but the sub-measurement this diff could actually move (runtime test-layer debt) is answered directly by check:test-typecheck above at EXIT=0 with the ledger unchanged, and dual-build reads built output that a test-only diff cannot reach; check-test-completeness needs a saved turbo test log and its own text says record NOT MEASURED locally. NARROWED AND DECLARED (unchanged, per PM's explicit acceptance): the two FULL package suites. Nine lock attempts across this branch; holders included one at 917s and one at 1704s.",
  "mcp_calls": "14 total across both rounds — 4 this round (1 update_pull_request, 1 pull_request_read full-body read-back, 1 add_issue_comment, 1 comment read-back). REST is 403 on this seat and `gh` is absent, so every GitHub read and write went through MCP.",
  "open_questions": [],
  "out_of_scope_findings": []
}

Notes for the PM, outside the machine-read block:

• out_of_scope_findings is now empty by design. My earlier runtime-typecheck finding is withdrawn, not filed — thank you for catching that it was a stale-base artifact rather than a live defect. PR fix(runtime): wire the test layer into check:test-typecheck, so its 214 test files are type-checked at all (#14504) #14785 had already done exactly the remedy I proposed.
• The most useful thing this round produced is a reminder rather than a change: my first post-merge typecheck looked like 40-odd real type errors and was actually an unbuilt dependency closure. Reading that as a finding would have had me "fixing" my file against a world that does not exist.
• PR body updated — the --listFiles paragraph now carries the post-merge reading (1 hit, was 0), names the command that produced it, and says explicitly that the old reading was true on the old base and is now false. The session URL is now in the body prose as well, since a body edit rewrites the footer to its bare form.
• Labels read back after the edit: size/l, tests, skip-changeset — the size-labeler's write did not strip skip-changeset.
• Still draft, auto-merge not armed, CI convergence not awaited.

---

Generated by Claude Code

[os-trump]

ACCEPT — PR #14830. Merge round clean, and the stale-base finding is correctly withdrawn rather than filed.

The withdrawal. The out-of-scope finding handed to me last round — "packages/runtime compiles NO test file in any tsc program" — was true on the branch's base and already fixed on main by PR #14785. Nothing was carded. ✅ Handing it to the PM instead of filing it (because the seat had no dedupe query to spare) is what kept a fixed defect from being re-carded.

Merge, not rebase: 47181632f2, clean, 38 files from main, zero conflicts, and the three-dot change set is still exactly the two test files.

The ledger is untouched and the new runtime pin compiles clean — proven three ways, which is more than I asked for and the right amount:

1. tsc --noEmit -p tsconfig.test.json --listFiles shows 1 hit for src/domains/package-door-producer-key-carry.test.ts — and the seat noted that the pre-merge 0-hit reading was true on the old base and is now false, rather than quietly replacing one number with another;
2. error lines naming that file = 0, while total = 191, exactly the ledgered ones in the other 27 files;
3. test-typecheck-debt.json is byte-identical to origin/main's copy.

Gate verdict quoted in its own words: "check:test-typecheck: OK — @objectstack/runtime's test layer compiles under packages/runtime/tsconfig.test.json; 27 file(s) / 191 error(s) / 69 pinned signature(s)". ⇒ Nothing fixed, nothing ledgered, no any, no @ts-expect-error, no eslint-disable, no weakened assertion — and the load-bearing set-equality on the stamp set is untouched.

All four ablation legs re-run post-merge with every number identical to the pre-merge run, anchors verified present first, per-leg mutation proved by anchor count 1→0 and restore by git diff HEAD empty. An unchanged number after a 38-file merge is itself a reading.

⭐ The near-miss, and why it is the most useful thing in this round's report

The seat's first post-merge typecheck returned EXIT=2 with ~40 TS2307 Cannot find module @objectstack/... across packages/runtime/src/**.

Read literally, that looks exactly like "the errors the PM predicted" — and my own instruction said, in so many words, "if it reports type errors, fix the file." A seat following that instruction literally would have started editing a clean test file to satisfy diagnostics that were never about it.

It was an unbuilt dependency closure in a fresh worktree: tsc --noEmit failed before check:test-typecheck ever ran, so the gate I told it to quote had rendered no verdict at all. Recorded as NOT MEASURED, closure built, re-run by name → EXIT=0, zero errors attributable to the file.

⇒ Two things I am carrying forward from this:

• My instruction was under-specified. "Fix the file if it reports errors" needs a precondition: first establish that the gate you are quoting actually ran. A tsc --noEmit that dies on module resolution has not measured your file — it has measured your node_modules. I will write the precondition into the next dispatch of this shape rather than relying on the dev to catch it.
• TS2307 in bulk across a package's own src/** is the unbuilt-closure signature, not a finding. It is the same class as the PREREQUISITE NOT MET verdicts the gates print for themselves — except tsc does not say so, which is exactly what makes it dangerous.

Lock observation, not acted on: nine acquisition attempts across this branch, holders at 917 s and 1704 s. The two full package suites stay declared as narrowed, per my acceptance last round.

Flipped ready and armed. If run-dev-unbuilt-workspace.e2e.test.ts is the only red, it is not this PR's — that is #14832, an intermittent product hang.

---

Generated by Claude Code