docs(qa): name the condition that selects the OWD gate's answering layer (#9477)

[os-warren]

Fixes#9477

Measurement-first card: the deliverable is the differential diagnosis, and the only file touched is docs/qa/platform-checklist/areas/access-security.json. No plugin-security code was edited.

Outcome 3. Both refusals are real on the same stock deploy; the checklist's knownGap named the wrong one as "earlier". #9453 CF-3 was right, and the revision-2 note that rejected it is overturned.

The three answers

1. Was OS_METADATA_WRITABLE set? — No. Proven from the server process's own environ.

The stock leg was booted with pnpm -C examples/app-showcase exec objectstack dev --ui --seed-admin -p 3477 -d file:<tmp>/data.db, then its /proc/<pid>/environ was read directly rather than trusting the shell:

server pid: 16208
cmdline: node .../@objectstack/cli/bin/run.js serve --dev --port 3477 --ui
every OS_* / OBJECTSTACK_* / *METADATA* var in /proc/16208/environ:
OS_INTERNAL_ARTIFACT_PATH=.../examples/app-showcase/dist/objectstack.json
OS_ENVIRONMENT_ID=env_local
OS_SEED_ADMIN=1
OS_SEED_ADMIN_EMAIL=admin@objectos.ai
OS_SEED_ADMIN_PASSWORD=admin123
OS_DATABASE_URL=file:<tmp>/run9477/data.db
METADATA_WRITABLE occurrences in server environ: 0
env vars readable: 147 # sanity: environ was read, not empty

No .env / .env.local exists at the repo root or in examples/app-showcase. Framework 90417a8, objectui pin 82a9417.

2. Was the target artifact-backed? — Yes. Read from the protocol's own layered answer.

isArtifactBacked resolves through lookupArtifactItem → SchemaRegistry.getArtifactItem, which is the same source the layered read reports as its code layer. GET /api/v1/meta/object/showcase_announcement?layers=true → 200:

code: PRESENT (13 keys) sharingModel='public_read' _packageId='com.example.showcase'
overlay: None
overlayScope: None

A populated code layer with a genuine package id is exactly the condition isArtifactBacked returns true for; overlay: null confirms nothing had been overlaid first. The shipped source agrees (announcement.object.ts: sharingModel: 'public_read', externalSharingModel: 'private').

3. Which layer produced the 403? — object-posture-gate.ts's R1, on the stock deploy.

PUT /api/v1/meta/object/showcase_announcement with the packaged body and sharingModel widened public_read→public_read_write (externalSharingModel left 'private', so the D11 lint cannot answer instead):

HTTP_STATUS=403
{"error":"[owd_widening_forbidden] object/showcase_announcement: an environment overlay may only
TIGHTEN a packaged object's OWD, never widen it (sharingModel 'public_read_write' > declared
'public_read'). Widen it in the package source and publish through the package pipeline
(ADR-0090 D7) instead of an environment overlay (ADR-0086 D1).",
"code":"PERMISSION_DENIED","declaredCode":"owd_widening_forbidden"}

Reproduced twice on fresh requests. GET before and after is byte-identical, so the refused write is inert.

The control leg — what makes this a diagnosis rather than one observation

A gate that fires proves the probe arrived, but not that the layer the checklist named is absent. So the same body was re-sent tightened (public_read→private), which R1 passes by construction — whatever answers next is the next door:

posture	?package=	body	status	code	answering layer
stock	absent	widening	403	owd_widening_forbidden	object-posture-gate.ts R1
stock	absent	tightening	403	NOT_OVERRIDABLE	SysMetadataRepository.assertAllowed, registry limb
stock	named	widening	403	owd_widening_forbidden	object-posture-gate.ts R1
stock	named	tightening	403	ITEM_LOCKED	SysMetadataRepository.readOnlyBaseOverrideError, package door
OS_METADATA_WRITABLE=object	absent	widening	403	owd_widening_forbidden	object-posture-gate.ts R1
OS_METADATA_WRITABLE=object	absent	tightening	200	—	admitted

The hatch leg was a second, independently booted server on port 3478 with its own DB; its /proc/<pid>/environ shows OS_METADATA_WRITABLE=object.

Three things fall out, none of which the old text allowed for:

• The direction of the body selects the answering layer — not the deploy posture. A widening body meets R1 first on every leg, hatch or no hatch, package named or not.
• The door the knownGap called "earlier" is in fact later. It answers only for bodies R1 lets through.
• WRITABLE_PACKAGE_REQUIRED — the code the knownGap names — appeared on none of the six legs. The real codes are NOT_OVERRIDABLE and ITEM_LOCKED.

The mechanism is already recorded in the framework, one file over: saveMetaItem calls runAuthoringGateahead of the overlay and package doors, and its #7674 note states that the CLI's host-config assembler leaves environmentId undefined and that this "is the flagship showcase's own boot shape". With environmentId undefined the env-partitioned NOT_OVERRIDABLE branch never arms, so nothing stands between a stock PUT and R1.

Why this is not a product defect

Every widening leg refused, and the object was byte-identical after each. object-posture-gate.ts behaved exactly as its executable guard specifies — if (!ctx.isArtifactBacked) return; did not return because the target is artifact-backed. Nothing was admitted that should have been refused, and the gate's verdict is the correct one. What was wrong is a prose prediction about door ordering, in two places: this checklist item (fixed here) and the gate header's parenthetical "the default deploy already 403s these before this gate runs", which belongs to the plugin-security lane and is left untouched per the dispatch.

The change

access-security.owd-save-gate revision 2 → 3:

• fixtures.knownGaps[1] — the deliverable. Now names the distinguishing condition (body direction), the mechanism, all six measured legs, and the fact that WRITABLE_PACKAGE_REQUIRED is not among them.
• steps[4] and acceptance[3] (clause + verify) — carried the identical wrong posture→code mapping; corrected so the item is not self-contradictory. steps[4] also gains the tightening control leg, so the next runner can tell "gate didn't fire" from "probe didn't arrive".
• New: read the code from declaredCode, not code. The dispatcher answers {code: 'PERMISSION_DENIED', declaredCode: 'owd_widening_forbidden'} on the live REST route, so a check keyed on code alone misses the gate it is looking for.
• history — a revision-3 entry recording the overturn of the revision-2 note.

pnpm check:platform-checklist → OK — 15 areas, 190 items (190 active); coverage: 30 kinds mapped, 0 waived.

---

Generated by Claude Code