feat(spec,types,triggers)!: group runs package-authored scheduled work without a declaration, owning each run's writes per record - #18420

📓 Docs Drift Check

This PR changes 5 package(s): @objectstack/cli, @objectstack/lint, @objectstack/spec, @objectstack/trigger-schedule, @objectstack/types, touching 14 documentable anchor(s). ⚠️ 3 changed file(s) yielded no anchor (packages/triggers/trigger-schedule/package.json, packages/triggers/trigger-schedule/tsconfig.json, packages/triggers/trigger-schedule/vitest.config.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

9 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/flows.mdx (via os doctor (command, read off packages/cli/src/commands/doctor.ts))
• content/docs/automation/jobs.mdx (via os doctor (command, read off packages/cli/src/commands/doctor.ts))
• content/docs/data-modeling/indexing.mdx (via os doctor (command, read off packages/cli/src/commands/doctor.ts))
• content/docs/deployment/cli.mdx (via os doctor (command, read off packages/cli/src/commands/doctor.ts))
• content/docs/deployment/environment-variables.mdx (via os doctor (command, read off packages/cli/src/commands/doctor.ts))
• content/docs/deployment/production-readiness.mdx (via os doctor (command, read off packages/cli/src/commands/doctor.ts))
• content/docs/protocol/backward-compatibility.mdx (via os doctor (command, read off packages/cli/src/commands/doctor.ts))
• content/docs/protocol/kernel/config-resolution.mdx (via os doctor (command, read off packages/cli/src/commands/doctor.ts))
• content/docs/protocol/kernel/http-protocol.mdx (via os doctor (command, read off packages/cli/src/commands/doctor.ts))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v16.mdx (via os doctor (command, read off packages/cli/src/commands/doctor.ts))

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.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin d96619c86eab8f5be6f221a5cf859a5155bec6c6 && git checkout d96619c86eab8f5be6f221a5cf859a5155bec6c6
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 51297e9ee17db23f50d38c1431f5a4dcc47632ff 0752431da60deb0ec97650515ac08550d967c03f && git checkout -B drift-repro 51297e9ee17db23f50d38c1431f5a4dcc47632ff && git merge --no-ff 0752431da60deb0ec97650515ac08550d967c03f

node scripts/docs-audit/affected-docs.mjs --json 51297e9ee17db23f50d38c1431f5a4dcc47632ff

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 51297e9ee17db23f50d38c1431f5a4dcc47632ff → pass the list as
args.docs, on the commit named under Which tree this was computed on.

Ready for review — all seven required contexts green on e856c009

⚠️ Lint & Repo Gates is called out deliberately: on its two earlier failures it stopped at step #158 of 180, leaving 22 gates unmeasured — its own tail reporter says that is NOT MEASURED, not "passed". This run completed the job, so those 22 have now actually executed.

Local, on the same tree: pnpm lint && pnpm test → 146/146 tasks, pnpm typecheck → 0 errors across 143 packages, check:generated → 15/15 up to date.

Three defects CI caught that local work had not

Recorded because two of them are the kind that ship silently.

1. Check Changeset — the ADR-0087 marker was malformed twice: prose written where the grammar takes entry ids, then already-registered used as a top-level arm when it is a category of not-required. Fixed; disposition is now not-required (already-registered schedule-flow-acting-organization-required), which is the honest arm — the entry predates this diff at the merge base, so registered would claim a registration this PR did not make.

2. check:test-source-alias — the new @objectstack/metadata-core dependency resolved through dist/ in tests, so the group pins asserting "each run is stamped from its own swept record" were a verdict about a built artifact rather than about resolveRecordOrganizationField's precedence in this checkout — which is exactly what those pins exist to hold. The gate's framing is the point: the dangerous case is a test that PASSES. Mine did. Aliased to source, re-run: 106 pass.

3. check:type-source-resolution — the same defect on the type side. Two routes existed and one was closed: that registry's docblock records this package's @objectstack/types row as admitted by maintainer ruling on [Decision] 平台自带的四个定时示例流一个都声明不了组织 —— 而新规则要求它们必须声明 #17396 and says in as many words that the row "is not a door, it is a signature". So this took the paths route, which needs rootDir widened to ../... That route is not always available — service-automation measured 647 TS6059 and ruled it out — so it was measured first: 0 TS6059 here. Verified after: gate green, typecheck clean, emit unaffected (1/1 declaration file; the package builds with tsup and typechecks with --noEmit).

One correction to this PR's own earlier text

The title carries ! while the body originally said "Not BREAKING". Both facts are real and the body now states them together: the accept set widens and nothing admitted becomes refused, but on a group deployment with the switch already on, flows that were refused at bind now arm and run — clock-driven work appearing where an operator had none is what earns the banner.

⛔ Not armed for auto-merge, deliberately

This changeset declares Clause-②: yes (widening) — it adds an exported symbol (ScheduledRunOwnership, describeScheduleRunOwnership) and a new key on a published payload (ScheduledWorkPolicy.runOwnership), which the mechanical floor makes yes unconditionally. That owes an in-seat contract review before landing, and a review by the seat that produced the diff would be recorded as SELF-REVIEW. Landing waits on that review.

Generated by Claude Code

⛔ Blocked — independent contract review returned FAIL, and one finding is a contract violation this PR cannot self-approve past

An independent Clause-② review (a separate session, so the machine-read independence pair genuinely differs) returned FAIL. It could not post its own verdict from its container — a 403 on repo scope — so its full text is still in that session's transcript. This comment records what the seat that wrote the diff has independently verified against the code, not a relay of its summary.

⚠️ Two of its three findings are named here; the third is stated but not yet verified by this seat, and is not being characterised either way.

Finding 1 — ⛔ a fourth consumer of tenancy.organizationField. Verified, and it blocks this PR.

TimeRelativeTrigger.organizationOfRecord() reads per-record ownership through createRecordOrganizationResolver (@objectstack/metadata-core). That resolver's own docblock pins the key it reads:

⛔ The tenancy.organizationField key this resolver reads stays scope-pinned (#8778, widened by name on cloud#1395 …): exactly THREE consumers are sanctioned — audit stamping, the approval-row writer, and the automation-run recorder — and no others. A fourth consumer needs its own maintainer ruling before reading the key, exactly as #8778 required.

and limb 0 repeats it:

⛔ Stamp-only cuts both ways: the key's consumers are pinned to the THREE platform-row writers the cloud#1395 ruling names — a fourth consumer, or any read path, needs its own ruling first.

This trigger is a fourth consumer and a read path. Both prohibitions apply.

The escalation, concretely. tenancy.organizationField is a STAMP-ONLY declaration answering "which column says who this row is ABOUT", and limb 0 makes it win over everything below it, the ADR-0066 tenancy: { enabled: false } opt-out included — which is exactly why it is legitimately declared on objects that are deliberately not org-walled (sys_api_key's active_organization_id, #8287). This diff takes that value and makes it the run's acting identity (ctx.tenantId), so a sweep over such an object would launch runs acting as an organization derived from an annotation that never meant "act as this". "Who this row is about" and "who this run acts as" are two different questions, and this diff answers the second with the first.

It also explains the shape of the test. The tenancy: { enabled: false } resolves nothing pin passes only because its fixture declares no organizationField; add one and limb 0 wins. And this PR's own trigger TSDoc spells the precedence out as "tenancy.organizationField → tenancy.tenantField → default" — this diff documented that it reads limb 0 while the key's contract forbids it from being a consumer at all.

Remedy is not this seat's to choose. Either (a) a maintainer ruling admitting a fourth consumer, which the contract explicitly requires, or (b) a read-side resolver that starts at limb 1 — skip organizationField, honour tenancy.enabled: false → null, then tenantField, then the default column. ⛔ Not a local column read in the trigger: a second implementation of that precedence is the drift the shared resolver exists to end. (b) looks right on the merits — A′ asks "which plant does this record belong to", which is the wall question, not the stamp question — but it adds public surface to metadata-core and touches a key with a ruling on it, so it is being put to the maintainer rather than decided here.

Finding 2 — the changeset's export claim was false. Fixed in 5ddc993.

describeScheduleRunOwnership is not re-exported from packages/triggers/trigger-schedule/src/index.ts. The changeset claimed the package exports it. The code is right — the barrel's own note says an export whose only consumers live inside its own package belongs in a non-barrel module — and the claim was wrong. It mattered beyond wording: that false export was cited as part of the Clause-②: yes basis.

⚠️ The same false claim is in this PR's earlier comment, which says the change "adds an exported symbol (ScheduledRunOwnership, describeScheduleRunOwnership)". Correcting it here rather than editing that comment: only ScheduledRunOwnership and the runOwnership key — both on @objectstack/types — are public, and those alone carry Clause-②: yes.

Finding 3 — stated, not yet verified here

The review also reports a TSDoc/test contradiction. Beyond the precedence-docblock point folded into Finding 1 above, this seat has not pinned down what else it refers to and is not guessing at it or calling it benign. It stands open until the full verdict text is read.

Status correction

The earlier "Ready for review — all seven required contexts green" comment is superseded. CI being green was true and is beside the point: this is a prose contract in a docblock, which no gate reads. Seven required contexts, a local pnpm lint && pnpm test at 146/146, a full typecheck, and an ablation-verified pin set all passed over Finding 1 without noticing it.

⛔ This PR should not land until Finding 1 has a ruling or a redesign, and Finding 3 has been read. Not armed for auto-merge; not requesting review.

Generated by Claude Code

Review finding ② is fixed — 0752431d. Finding ① still blocks, and it is a ruling, not a patch.

This supersedes the body's "Status — ready, green" section: the PR is back in draft and the independent Clause-② review returned FAIL with two findings.

② Fixed (doc-only). ScheduledWorkPolicy documented runOwnership backwards for the switch-OFF state, in two places: the state table's OFF row printed 'unscoped' (moot), and the field's own docblock said "when the switch is off nothing binds, so this reports 'unscoped'". The code does no such thing — resolveScheduledWorkPolicy computes it as scheduledRunOwnershipFor(posture), posture only, never gated on enabled, so OFF + group is 'per-record' and OFF + isolated is 'declared'. The pins in env.test.ts already asserted the true behaviour, so documentation was the only half asserting the opposite, and documentation is the half that changed. The code is deliberately left alone: runOwnership answers a question about the posture, requiresActingOrganization is the switch-gated half, and both consumers return early on !policy.enabled (schedule-trigger.ts:643, time-relative-trigger.ts:313) long before they read it. pnpm typecheck clean, 52/52 in env.test.ts.

① Blocking, unchanged — a fourth consumer of tenancy.organizationField. Verified against the contract rather than taken on the reviewer's word: packages/metadata-core/src/record-organization.ts pins that key to exactly THREE sanctioned consumers (audit stamping, the approval-row writer, the automation-run recorder) and says a fourth needs its own maintainer ruling first. The per-record sweep in time-relative-trigger.ts is a fourth, and it reads through limb 0, where the stamp key also outranks tenancy: { enabled: false }. ⛔ I am not touching that code until the maintainer rules; the two shapes on the table are (a) admit a fourth consumer, or (b) add a read-side resolver in metadata-core starting at limb 1. I recommend (b) and have not decided it.

One clarification on the review's own summary line, which compresses ① as "org-scoped credential read + stamp-only key priority conflict": there is no credential read in this diff. credential/secret/password/apiKey appear zero times across all 21 changed files. The second clause is the finding; the first does not correspond to anything here.

CI: the seven required contexts were green on e856c009; 0752431d is doc-only and is re-running now.

Generated by Claude Code