fix(lint): make validateSecurityPosture's surfaceReason a measured claim (#7576)

[os-zhuang]

Part of #7576

Not Fixes, deliberately. The card's stage 2 — moving the block onto the runtime publish surface — did not land, on measurement rather than preference. The card must stay open while that remainder escalates as its own strictness-rollout card. See Stage 1 measurement below for what made that call.

What changed

file	change	behaviour
packages/lint/src/authoring-rules.ts	validateSecurityPosture's surfaceReason rewritten to a measured claim (+ the measurement as a docblock above the entry)	none — still surfaces: CLI_ONLY
packages/lint/src/runtime-gate.ts	TYPE_TO_STACK_KEYseed: 'seeds' → seed: 'data'	none today (no rule declares seed)
packages/lint/src/validate-security-posture.runtime-surface.test.ts	new — keeps every load-bearing number in the reason executable	new tests

The claim that was false

The block is registered once, so all 13 rule ids inherit one surfaces / surfaceReason. The reason read:

Already gated at this surface by a DIFFERENT mechanism: plugin-security registers an ADR-0094 authoring gate on object (registerAuthoringGate) that enforces the same OWD posture rules on every runtime write. Running the linter here as well would double-report one refusal in two vocabularies.

Both halves are false, and both were re-measured at work time on origin/mainbcea363:

• Coverage — 1 of 13.object-posture-gate.ts (141 lines) reads exactly sharingModel and externalSharingModel through a local OWD_WIDTH, and never fields, permissions, books or data. It covers security-external-wider-than-internal (its R2) and nothing else. Its other half, R1 (env-tighten-only, ADR-0086 D1), corresponds to no lint rule, so it is not coverage in the other direction either. The card's table reproduced exactly.
• Double-reporting is structurally impossible.saveMetaItem runs assertRuntimeAuthoringRules (this table → 422 invalid_metadata, protocol.ts:10105) beforerunAuthoringGate (the ADR-0094 gate → 403 owd_external_wider, protocol.ts:10146), and both refuse by throwing. The first to fire ends the write, so an author earns one refusal either way — and where they overlap the two are complementary, not duplicate: the posture gate's R2 additionally catches an external dial wider than an unset internal (it baselines to private), where this block reports security-owd-unset instead.

So the stated cost of moving was imaginary. The reasons it has not moved are the measured ones below, and they are now what the field says.

Stage 1 measurement (the triage care note's first deliverable)

Corpus scanned — the four shipped stacks, loaded through their real objectstack.config.ts and judged by the real rule:

stack	objects	permissions	books	positions	apps	seeds (records)
examples/app-showcase	23 (202 fields)	8	1	9	1	18 (130)
examples/app-crm	6 (49 fields)	2	0	3	1	5 (28)
examples/app-todo	1 (20 fields)	0	0	0	1	1 (8)
packages/create-objectstack/src/templates/blank	1	0	0	0	0	0

packages/platform-objects ships no seed metadata (grep for records: / SeedSchema under its src/ returns nothing), so it contributes no rows to the two ADR-0091 rules.

Two probes over that corpus: A = the whole-stack call the three CLI commands already make; B = the per-write differential the runtime gate performs (runtime-gate.ts), one simulated write per item per collection.

rule id	severity	A (CLI, whole stack)	B (runtime, per write)
security-owd-unset	error	0	0
security-owd-alias	error	0	0
security-external-wider-than-internal	error	0	0
security-controlled-by-parent-no-relation	error	0	0
security-wildcard-vama	error	0	0
security-anchor-high-privilege	error	0	0
security-role-word	error	0	0
security-fls-unqualified-key	error	0	0
security-grant-expired-at-authoring	error	0	0
security-delegation-missing-reason	error	0	0
security-master-detail-ungranted	warning	4	38 (all on permission writes)
security-private-no-readscope	info	2	2 (on permission writes)
security-book-audience-unknown-set	warning	0	0

Zero error findings anywhere. No shipped app trips, so the #4001 rollout pattern is not engaged by the corpus.

Every zero row has a positive control — the probe does catch these when they are there. validate-security-posture.test.ts's REACHABILITY_CORPUS already carries one deliberately-violating fixture per rule id and proves all 16 emit sites reachable; this PR adds the runtime-shaped controls (an OWD-less object write refused, an expired seed grant refused, an undocumented delegation refused, a controlled_by_parent object with no relation refused) so the zeros are measured silence, not an unfired probe. The single row with no shipped instance either way is security-book-audience-unknown-set: the one shipped book (app-showcase) declares audience: 'public', not { permissionSet }, so nothing in the corpus can reach it — its control is the fixture.

Why stage 2 did not land

Blocker 1 — object is a strictness rollout, and its repair sites are outside this package.

Declaring object in runtimeTypes puts security-owd-unset on the write path. ObjectSchema.sharingModel is .optional() with no default, so any object published without an authored OWD is refused 422. Measured by actually making the change and running the suite:

26 refusals → 48 failing tests across 8 files of @objectstack/metadata-protocol's own suite (protocol.read-decorations, protocol.save-receipt-wording, protocol.injected-system-columns, protocol.audit-field-governance, protocol.org-scoped-write-refused, protocol.runtime-authoring-gate, protocol-publish-drafts-endpoint-gate, protocol-publish-drafts-org-scope) — every one from that single rule id, nothing else fired.

That is not stale fixtures: METADATA_CREATE_SEEDS.object — the spec's own "authoritative minimal shape a freshly-created item should carry", the body Studio's create-object flow starts from — is { name, label, pluralLabel, fields: {} } with no sharingModel. The platform's runtime create door emits exactly the shape the rule would refuse.

The refusal is arguably correct (os build has rejected that body since ADR-0090 D7, and the wiring guard's own words are "the two publish verbs must not disagree") — which is precisely why it is a rollout and not a wiring fix. Its repair sites are packages/spec/src/kernel/metadata-create-seeds.ts and eight metadata-protocol test files, both ⛔ outside this card's charter.

Blocker 2 — permission / book need a snapshot the gate does not build.

RuntimeStackContext carries objects and nothing else. Three rules compare one collection against another:

rule	reads	missing at the gate
security-master-detail-ungranted	objects × permission sets	all sibling permission sets
security-private-no-readscope	objects × permission sets	same
security-book-audience-unknown-set	books × permission sets	same

The per-write verdict is therefore not a narrower version of the whole-stack verdict — it is a different and wrong one: with a single permission set in the snapshot, every detail object the tenant's other sets grant reads as ungranted. Hence 38 against 4. security-book-audience-unknown-set fails identically and would flag every { permissionSet } audience ever written at runtime, since the snapshot declares no sets at all. That is the existing RUNTIME_NEEDS_FULL_SNAPSHOT reason, tracked as #4463 P2 — a snapshot change in the protocol package, not a runtimeTypes edit here.

A second, independent confirmation: permission and book have no TYPE_TO_STACK_KEY entry at all, so declaring either without adding one fails the wiring guard's every runtime-gated metadata type maps to a stack key case. Pinned as a test.

On the PM's load-bearing premise. It survives, with a correction. The plumbing can reach non-object collections — all six candidate types (object, permission, position, app, book, seed) carry allowRuntimeCreate: true, and runtime-gate.ts's snapshot builder is written generically ({ objects, [stackKey]: [item] }). What it cannot do is carry the sibling collections three of the rules compare against. So this is not "the plumbing cannot reach them"; it is a bounded, named context gap, and the fork is reported rather than forced.

Why not land a partial slice anyway. The two ADR-0091 seed rules (security-grant-expired-at-authoring, security-delegation-missing-reason) read only stack.data[], are fully self-contained, trip nothing measured, and would cross the wall together as a whole sub-family — a genuinely ready one-line runtimeTypes: ['seed'] edit. It is left for the rollout card rather than taken here so the block crosses in one deliberate decision. What is not available at any point is adding position / app for security-role-word: that rule judges six collections, and wiring the two that need no snapshot would split one rule id across the wall — a door where a position named sales_role is refused and an object named sales_role is waved through. That is the #7220 failure this table already refuses to build.

The latent defect the measurement found

TYPE_TO_STACK_KEY mapped seed → 'seeds'. A stack has noseeds key — seeds live on data (ObjectStackDefinitionSchema.data: z.array(SeedSchema)), which is also what the two ADR-0091 rules read and what PLURAL_TO_SINGULAR declares (no mapping onto seeds exists at all).

It was inert rather than harmless, and it is the #4449 shape one surface over: the wiring guard asks only that a declared type has a mapping, never that the mapping names a key some rule reads. It would have stayed green while the gate built { objects, seeds: [item] } for every seed write, every rule reading stack.data saw nothing, and rulesRun reported the rules as having run. Corrected here, with the measurement that found it, rather than left for the rollout card to trip over. Inert today — nothing declares seed in runtimeTypes.

Layer-sensitivity (#7815) — measured, not assumed

The dispatch asked this to be measured rather than presumed nil, and it is nil, structurally:

• validateSecurityPosture(stack, opts?) accepts exactly one option, nowMs (the injected clock for the ADR-0091 expiry rule). There is no layer parameter to mis-set.
• The registry adapter is run: (stack) => validateSecurityPosture(stack) — it passes no options at all, so even nowMs takes its production default.
• The rules judge sharing posture, permission-set bits, vocabulary and seed-grant lifecycle. None resolves a predicate binding root, which is the axis [finding] The runtime gate runs validateVisibilityPredicates at its runtime layer default for schema-bound metadata forms, so a correctly data.-rooted form is told to use record. #7815 is about.

⛔ #7815 is untouched here — it remains a separate, ungraded finding.

Tests

• pnpm --filter @objectstack/lint run test — 71 files / 1929 tests, all pass (was 70/1922; +1 file, +7 tests). authoring-rule-wiring.test.ts and validate-security-posture.test.ts both green unchanged.
• pnpm --filter @objectstack/lint run typecheck — clean.
• pnpm --filter @objectstack/metadata-protocol run test — 72 files / 1066 tests, all pass, against a rebuilt @objectstack/lint dist. This is the behaviour-neutrality proof: the same suite showed 48 failures with the surface move in, and zero with only what this PR lands.
• eslint --no-inline-config on the three touched files — clean.

No suite pin was weakened.validate-security-posture.test.ts's expect(pushedRuleIds()).toHaveLength(16) (16 emit sites, 13 distinct rule ids) and the wiring test's runtime publish surface block are untouched and still green — this PR changes no rule behaviour and no surface, so neither pin had anything to say about it. The new file's assertions name the rule id and the severity explicitly, never a bare count.

The new test deliberately mirrors the gate's differential rather than calling it, because no rule declares these types — that is the state the card is about, so runRuntimeAuthoringRules correctly answers "nothing". the mirror still matches the real gate pins the mirror against a type that is wired (flow), so a snapshot change in runtime-gate.ts that the mirror did not follow fails loudly instead of silently invalidating the measurement.

Not touched

• ⛔ packages/plugins/plugin-security/**, packages/metadata*/**, packages/spec/src/** — other lanes' charters. Read for measurement only.
• ⛔ [P3] Generalise the lint rule surfaces axis to an open N-surface dimension (#4463 P1 introduced a closed two-value one) #7443 stays pm:on-hold. AUTHORING_SURFACES is unchanged and no third value is proposed; its restart condition is not tripped.
• ⛔ content/docs/releases/ — untouched; the changeset is this PR's input to the release notes.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 12, 2026 2:25am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint.

3 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/automation/hook-bodies.mdx(via @objectstack/lint)
• content/docs/deployment/validating-metadata.mdx(via packages/lint)
• content/docs/permissions/authorization.mdx(via @objectstack/lint)

⛔ 1 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/v17.mdx(via @objectstack/lint)

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.