feat(lint): cross validateRetiredPermissionResidue onto the runtime authoring door (permission writes, advisory) - #18722

Fixes #17936
Clause-②: no

Out of #17425's class-one ruling D. validateRetiredPermissionResidue now runs at the runtime authoring door on permission writes, at advisory tier, so the population ruling D named — an author who writes permission metadata as JSON through Studio / REST /meta / MCP and never runs os lint — gets the same signal at the only door they have.

The tension this card turned on, and how it was settled

The rule's registry entry was CLI_ONLY with a surfaceReason that did not say "never", it said "not measured":

Crossing it needs a measurement this round did not take — whether the gate's body reaches it BEFORE the per-type safeParse, whose residue stage strips the only evidence this rule reads. Post-parse the rule is structurally silent, so wiring it there without that reading would publish a phantom check, not coverage.

The card asserted the crossing was feasible. Both could be true at once, so the first act of this PR was to take that measurement rather than assume either side.

Measured: the residue does reach the rule. At packages/metadata-protocol/src/protocol.ts, saveMetaItem runs the per-type safeParse and then deliberately keeps the authored body — parsed.data would strip the Studio-only auxiliary fields an overlay rides with — grafting back exactly two normalizations (graftNormalizedOperators for filter operator spellings, graftFoldedFormSections for the form groups to sections key move). Each is a walk over the authored keys that adds nothing and removes nothing else. So assertRuntimeAuthoringRules is handed the raw document; evaluateRuntimeAuthoringGate passes it straight through as item: args.body; and buildRuntimeWriteSnapshots puts that same object into candidate.permissions, which is exactly what the rule reads. input: 'normalized' therefore stays load-bearing rather than becoming a contradiction — the gate's snapshot is an unparsed body.

That is not argued in the PR text alone: a pin at the door reads the persisted row back and asserts allowRestore: false survived the parse, and it is green both before and after the registration change, because it measures the door's body handling and not the crossing.

What changed

• packages/lint/src/authoring-rules.ts — the residue entry moves to surfaces: CLI_AND_RUNTIME with runtimeTypes: ['permission']. tier: 'advisory', input: 'normalized' and commands: ALL are untouched.
• The stale surfaceReason is removed rather than reworded. That field answers "why the runtime gate does NOT run this rule"; once it does, no wording of it is true. The reasoning moves into the entry's comment, beside the measurement that settled it.
• ⛔ The rule body (validate-retired-permission-residue.ts) is not touched — this card changes which surfaces it is registered for.
• ⛔ No accept-set change, and never a refusal: an advisory rides the 2xx the write earns. A value that is not the retired default (true, 0, null) is still refused by the tombstone at the parse, with its prescription attached, exactly as before.
• permission is the only declared type, because stack.permissions is the only collection the rule reads.
• Pins: packages/lint/src/runtime-gate.permission-residue.test.ts (dispatch, wire path, the baseline/candidate differential, the CLI-door control) and a #17936 block in packages/metadata-protocol/src/protocol.runtime-authoring-gate.test.ts (the door, end to end through saveMetaItem).

Evidence

Red before green — ablation, with on-disk proof and a hash-verified restore

Run from the committed implementation (670efa9cbe), mutating the crossing back out.

Direction was as predicted: red, not "more diagnostics" and not a reversal.

LIT control — the advisory must actually fire

• At the gate: runRuntimeAuthoringRules({ type: 'permission', item }) on a set carrying allowRestore: false returns errors: [] and advisories whose rule list is exactly ['permission-retired-lifecycle-residue'] — severity warning, path permissions.sales_team.objects.crm_ticket.allowRestore (the finding: a publish refusal's issues[].path carries an array index into the gate's private snapshot (objects[417].sharingModel) that no caller can resolve #10064 name-keyed wire shape), hint non-empty because it resolves from the tombstone's own description.
• At the door: saveMetaItem({ type: 'permission', … }) returns success: true, the row lands, and advisories[] carries the same six-key entry with path permissions.sales_team.objects.leave_request.allowRestore. Both keys present advises twice.
• Ablated, both read zero. That is what makes the green a measurement.

DARK controls — both read 0, as readings and not as expectations

• A clean write advises nothing. At the door, 'advisories' in result is false — the whole key is absent, not an empty array. At the gate, result.advisories deep-equals []. ⚠️ The fixtures author readScope on purpose: without it the pre-existing security-private-no-readscope info advisory rides every one of these writes and the reading would be "one instead of two" rather than a true zero. This arm is green in both the ablated and the restored run — it reads 0 either way.
• The CLI door is unchanged. Both CLI-door cases are among the 4 that pass in the ablated run as well as the restored one. Their readings: on each of validate / build / lint, exactly 1 finding, path permissions[0].objects.crm_ticket.allowRestore (positional — the name-keying did not leak onto the commands), severity warning, message and hint byte-identical to the rule's own direct output; on a clean stack, 0 findings on each of the three.
• No other metadata type reaches the rule: every runtime-gated type other than permission is asserted not to dispatch it.
• A stored set's residue is not charged to this write: with a residue-carrying sibling in context.permissions, a clean write reads 0 and a dirty one still reports exactly its own one path ([runtime/metadata] 作者时规则只存在于 CLI:Studio/REST/MCP 的运行时授权面是第四扇门,26 条规则一条不跑——#4409 修完后最大的敞口 #4463 D4's differential, non-vacuous in both directions).

Suites and gates, at 3bee0e438e

• pnpm --filter @objectstack/lint test — 104 files, 3882 tests, all passed.
• pnpm --filter @objectstack/metadata-protocol test — 178 passed / 3 skipped (181 files), 2554 passed / 19 skipped.
• pnpm --filter @objectstack/lint typecheck (which also runs check:test-typecheck) and pnpm --filter @objectstack/metadata-protocol typecheck — both exit 0.
• Gate families derived from the real change set with scripts/pm/dispatch-gates.mjs (never a hand list) and reconciled with --ran: 59 derived, 56 run green, 0 UNRUN, 3 NOT MEASURED. The three are check:dual-build-cjs-loads, check:lean-entry-closure and check:type-check-debt, each exiting 3 — PREREQUISITE NOT MET: they read built output for the whole monorepo, which this worktree does not have. Exit 3 is neither a pass nor a finding; CI builds the closure and measures them.
• pnpm lint (eslint . --no-inline-config) — the whole-repo union, not a narrowing — exit 0, re-run at the final commit 3bee0e438e.

Acceptance notes

Noted, not filed:

• A crossed rule can still carry a stale surfaceReason. authoring-rule-wiring.test.ts requires a substantive surfaceReason when surfaces omits runtime-publish, but nothing refuses one that is still present when it does not — so a "why the gate does not run this" sentence can outlive the crossing it contradicts. Removed by hand here and pinned for this entry in the new lint test. Not a reproducible defect, a declared-contract violation or a metadata-authoring trap, so it is not a card. Who meets it next: the seat that crosses the next CLI_ONLY rule — sibling card cross validateRetiredPermissionResidue to the runtime publish door — the CLI door cannot reach the AI/Studio JSON authors ruling D named #17944 (the PUBLISH door) is the nearest named candidate.
• The security-private-no-readscope info advisory already rides permission writes that grant allowRead on a private object with no readScope. Pre-existing and correct; recorded here only because it is why the new fixtures author readScope, and because it is the reason a "no advisories at all" reading has to be built rather than assumed.
• _advisoryWarned dedupes per process, keyed type|name|rule|path, so a second test reusing one permission-set name reads zero log lines from a gate that is working exactly as designed. By design, not a defect; the new operator-log case carries its own name and says why in place.

For the reviewing seat: this diff adds a key to an AUTHORING_RULES registry entry, which the clause-② C5 widening tell can match on shape. It is not a contract widening — no schema key, no closed-set member, no new published export, no accept-set change, and the added judgement can only advise, never refuse. The card and the claim both declare Clause-②: no.

⛔ Not in this PR: the PUBLISH-door half of the same file (#17944, still pm:queue and unclaimed) is not addressed here and remains open.

Generated by Claude Code