fix(lint): inspect runAs:'system' flows on the readonlyWhen branch (#14201)

[claude]

Fixes #14201

What changed

packages/lint/src/validate-readonly-flow-writes.ts carried the runAs:'system'
exemption as a single flow-level early return, so an elevated flow left the walk
before either branch of the rule could judge it. That skip now gates the static
readonly branch only; the readonlyWhen branch inspects a runAs:'system' flow
like any other, at its existing warning severity. Rule ids and severities are
untouched.

-    if (flow.runAs === 'system') return;
     const runAs = flow.runAs === 'user' || flow.runAs === 'system' ? flow.runAs : 'user';
+    const isSystemRun = runAs === 'system';
...
-        if (meta.readonly) {
+        if (meta.readonly && !isSystemRun) {

A field declaring both flags therefore falls through to the conditional branch
under runAs:'system' — which is the truth about that write: the static strip is
skipped, the conditional one is not.

Engine authority (verified on origin/main, not recalled)

packages/objectql/src/engine.ts, the by-id update path — the conditional strip runs
with no guard, and the note at the call site says so:

// [#9107] ... The API-boundary lock is unchanged - a caller cannot make its own
// value look hook-written (see `ReadonlyWhenStripOptions`) - and `isSystem`
// is still NOT an exemption here, unlike the static strip below.
hookContext.input.data = stripReadonlyWhenFields(updateSchema as any, preRoWhen, priorRecord, this.logger, roWhenParent, { supplied: suppliedValues }) as any;

The static strip, twenty lines below, is the one an elevated caller really does bypass:

if (!opCtx.context?.isSystem) {
    const preRo = hookContext.input.data as Record...;   // elided: a generic type argument, spelled out here to keep angle brackets out of this body
    hookContext.input.data = stripReadonlyFields(updateSchema as any, preRo, suppliedValues, this.logger, { ... }) as any;

The bulk path (stripReadonlyWhenFieldsMulti / stripReadonlyFields) is split the
same way, so the asymmetry is not a by-id accident. Pinned from both sides:
engine-readonly-when-derived-writes.test.ts line 195, "LOCK 2 - isSystem does NOT
exempt a caller-supplied value (Option B stays rejected)", and
engine-readonly-strict-writes.test.ts.

The rule's own header already recorded this gap ("the skip above is therefore WIDER
than the conditional lock warrants ... Left as-is deliberately") — that paragraph is
now rewritten to describe the split it documents. The action sibling
validate-readonly-action-writes.ts was born with exactly this shape: an action body
is system-elevated by design, so it carries the conditional half and only that half.

Tests

packages/lint/src/validate-readonly-flow-writes.test.ts — 5 new cases, existing ones
kept:

• positive: a runAs:'system' flow whose update_record writes a readonlyWhen
  field ⇒ one warning on flow-update-readonly-when-field, message naming the run
  identity it was judged under;
• negative kept and re-titled: a runAs:'system' flow writing a static
  readonly:true field ⇒ still silent;
• a system node writing both kinds plus a plain field in one payload ⇒ the conditional
  half only, no error;
• a field declaring readonly and readonlyWhen ⇒ warning under system, error
  under user;
• nested-region reach and create_record exemption, both under runAs:'system'.

Commands run (all at head 8b99b5c2d, exit codes captured before any pipe)

command	exit
pnpm --filter '@objectstack/lint^...' build	0
pnpm --filter @objectstack/lint test	0 — 93 files, 2720 passed / 5 skipped
pnpm --filter @objectstack/lint typecheck	0
node scripts/pm/dispatch-gates.mjs --commands union (33 families)	30 exit 0, 3 exit 3
node scripts/pm/dispatch-gates.mjs --ran	0 — 33 derived, 33 run, 0 UNRUN

The three exit-3 rows are prerequisite-not-met, i.e. NOT MEASURED locally and not
findings, each saying so in its own verdict text: check-test-completeness.mjs (grades
a saved turbo run test log CI tees), check:dual-build-cjs-loads and
check:type-check-debt (both need the whole workspace built).

Reverse verification: with the flow-level return re-injected and the rest of the
change left in place, the rule test file goes 4 failed / 20 passed — exactly the
four new runAs:system cases — and back to 24 passed restored. The mutation was
confirmed on disk (unique anchor asserted, injected-marker grep -c = 1, mutated
git hash-object differs from the HEAD blob) and the restore proved by hash equality
with the HEAD blob plus an empty git diff HEAD; no build was involved because the
test imports the rule module by relative source path, not through dist/.

ESLint was run narrowed rather than repo-wide, and the narrowing is measured: this
repo runs one eslint.config.mjs that never enables type-aware linting for any file
(no parserOptions.project, no typed @typescript-eslint rules — stated and measured
in that config's own header), so no file's verdict depends on a file outside itself and
a two-file diff cannot move an untouched file's result. eslint --no-inline-config --format json over the diff reports 3 result entries: 0 errors / 0 warnings on both
.ts files, and the changeset .md reported as ignored (no matching configuration),
so 2 lintable files, both clean. The repo-wide sweep is CI's Lint & Repo Gates run.

Not in scope

The readonlyWhen hint text is left exactly as #14202 landed it. It reads correctly
under an elevated run too — "the conditional lock is NOT waived by a system context" is
precisely what a runAs:'system' author needs told — and message text is that card's
fence, not this one's.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

1 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 5 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json d62f990a985eb15152579ad34c99f43e76e3657a → packageMentionDocs.

Which tree this was computed on

This run read content/docs from e8cc6a53793d2fb2a4debec4a1275eb13d0c59e2 — the merge of head 8b99b5c2dda048511ebde049bb0311052bb6b81b into base d62f990a985eb15152579ad34c99f43e76e3657a, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin e8cc6a53793d2fb2a4debec4a1275eb13d0c59e2 && git checkout e8cc6a53793d2fb2a4debec4a1275eb13d0c59e2
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin d62f990a985eb15152579ad34c99f43e76e3657a 8b99b5c2dda048511ebde049bb0311052bb6b81b && git checkout -B drift-repro d62f990a985eb15152579ad34c99f43e76e3657a && git merge --no-ff 8b99b5c2dda048511ebde049bb0311052bb6b81b

node scripts/docs-audit/affected-docs.mjs --json d62f990a985eb15152579ad34c99f43e76e3657a

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.