feat(spec,plugin-auth): a demoStaff entry names its line manager, and os dev links it - #26763

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/plugin-auth, @objectstack/spec, touching 12 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/spec/authorable-surface/system.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/automation/approvals.mdx (via manager_id (literal, a string literal in linkDemoStaffManagers), /api/v1/auth/admin/set-user-manager (route, a path literal in a comment on a changed line))
• content/docs/capabilities/approvals.mdx (via manager_id (literal, a string literal in linkDemoStaffManagers), /api/v1/auth/admin/set-user-manager (route, a path literal in a comment on a changed line))
• content/docs/protocol/objectql/query-syntax.mdx (via manager_id (literal, a string literal in linkDemoStaffManagers))

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

• content/docs/releases/v17/17-5.mdx (via manager_id (literal, a string literal in linkDemoStaffManagers), /api/v1/auth/admin/set-user-manager (route, a path literal in a comment on a changed line))

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 9c21e4dc9054fe1a95c93336c58a51f24d1b8efc && git checkout 9c21e4dc9054fe1a95c93336c58a51f24d1b8efc
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin a485b5a3e28d84550e8a33bbb5cfc2d52c82ff9e 53d29e263c2573b2442cd17af01eedab1e2c8d4b && git checkout -B drift-repro a485b5a3e28d84550e8a33bbb5cfc2d52c82ff9e && git merge --no-ff 53d29e263c2573b2442cd17af01eedab1e2c8d4b

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

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 a485b5a3e28d84550e8a33bbb5cfc2d52c82ff9e → pass the list as
args.docs, on the commit named under Which tree this was computed on.

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: a516ef70932a183ab3d4b04336ebef8381655a2b
Local-runs: none
Scope: packages/spec/src/stack.zod.ts, packages/spec/src/system/demo-staff.zod.ts + packages/plugins/plugin-auth/src/demo-staff.ts, packages/plugins/plugin-auth/src/admin-set-user-manager.ts, packages/plugins/plugin-auth/src/auth-plugin.ts, packages/spec/src/shared/alias-probe.ts, packages/spec/src/api/error-code-ledger.zod.ts, scripts/check-skills-token-ratchet.mjs

Inputs read: card #26616 (body, the re-lane note, the triage grade, the claim, the os-dev-report); PR #26763 body and file list; the net diff 43731031..a516ef70 (11 files, +513/−9); the check-runs on the head. The PR body's account was read and then set aside; every judgment below is on the tree.

Gate verdicts on the head (check-run conclusions, read 2026-10-27 at the time of this record): green — Lint & Repo Gates, Governed Surface Queue Guard, Type Check · source gates (the lane carrying check:authorable-surface and check:docs), Lint · ESLint (carrying check:engine-double-contract), Check Changeset, PR-body guards, Spec property liveness, Dogfood Regression Gate, Test UI, Build Docs, Build UI Deps, Check PR Size. Still in_progress when this record was closed: Test Core (1–8/8), Build Core, Type Check · consumer gates (carries check:api-surface), Type Check · debt ledger, Type Check · workspace, Type Check UI, Build & E2E UI. The verdict below is on the tree; the seat posts it only once those required lanes report success, and a red there re-opens this record rather than being adopted.

① Derived judgments

• Accept-set, DemoStaffSchema (demo-staff.zod.ts): one new optional key manager: z.string().email(). A key the strict shape refused is now accepted; nothing accepted before is refused now (a manager-less list parses as it did). ⇒ Metadata-protocol: added, Clause-②: yes (widening). Right.
• Aliases managerEmail, managerId, reportsTo, supervisor → manager: each filed key is one the shape rejects and each target is one it accepts (the alias-integrity claims hold). aliasProbe (alias-probe.ts:21) lowercases and strips _ - space, so manager_id, manager_email, reports_to reach the same entries; the manager_id row that shared managerId's probe was rightly dropped in 8e1dde38 rather than kept as a dead second spelling. Right.
• Stack check (stack.zod.ts): collectDemoStaffManagerErrors is called from collectDemoStaffErrors, which validateCrossReferences runs BEFORE its objectNames.size === 0 early return, and defineStack runs validateCrossReferences unconditionally in strict mode (the default) on the parsed result.data. Nothing conditions it; the only skip is strict: false, which skips every cross-reference check and predates this PR. "At load, never silently skipped" holds for defineStack, os validate, os build and every host config. Right.
• Error code: STACK_CROSS_REFERENCE_INVALID is an existing ledger row (error-code-ledger.zod.ts:1576, "items name objects the stack does not define" plus the aggregate's other findings); the class StackCrossReferenceError extends StackRefusalError carries 422. A manager naming no entry is exactly a stack-level reference the stack does not define; self-reference and loops ride the same aggregate the duplicate-name and duplicate-address findings already ride. Right, and no new code was minted outside the ledger.
• Compose: COMPOSE_KEY_DISPOSITIONS.demoStaff = 'concat'; composeStacks refuses an input not built by defineStack, and collectArtifactCrossReferenceErrors does not re-judge managers on the composed list — so a manager resolves within the list its own defineStack saw, and a cross-publisher manager is refused at its input. Matches the card ("another entry" of the same list) and the acceptance note. Right.
• Identity key = email, folded the same way on both sides: the stack check keys indicesByEmail on email.trim().toLowerCase() and looks manager.trim().toLowerCase() up in it; the provisioning folds entry.manager the same way and resolves it through findUserIdByEmail → addressSpellings([lowercased]), the same read the first pass used to find or create every account — so if the first pass found the manager's account the second pass finds it by construction. .email() refuses whitespace, so trim() is inert; toLowerCase() is the fold the duplicate-address refusal and sign-up storage already use. Choosing the address over the card's "by name or email" is right: name is a Tier-1 self-editable label and is the SEED's key, not the account's. Right.
• Public surface, plugin-auth: DemoStaffOutcome gains managersLinked and managersKept (required, readonly); the only producer is provisionDemoStaff, so for every reader it is a widening. Right.
• Generated artifacts: authorable-surface/system.json (+system/DemoStaff:manager, in sorted position) and content/docs/references/system/demo-staff.mdx (+1 row in schema key order) are generator outputs; the lane that runs check:authorable-surface and check:docs is Type Check · source gates, green on this head, so they are certified regenerated, not taken on the body's word. scripts/engine-double-contract.pinned.json pinned: 1 → 2 for demo-staff.test.ts is the check:engine-double-contract --write output for the second update double the new tests add; that gate runs in Lint · ESLint, green. A pinned count growing is coverage growth, the ledger's ordinary direction.

② Semver level

Changeset .changeset/26616-demo-staff-manager.md: @objectstack/spec: minor, @objectstack/plugin-auth: minor. The kind is added, and a kind takes at least minor on every package the diff moves (Post-Task Checklist step 3); both packages move. Both declaration lines are present in the PR body and in the changeset body: Clause-②: yes (widening) and Metadata-protocol: added. Not breaking, so no ADR-0087 marker is owed. Check Changeset green. Right.

③ Boundary flags

• open_questions: [] — none to answer.
• Out-of-scope finding 1 (depth cap not checked at load): the dev's note says a chain longer than 20 "is refused by the set-manager write at the boot and reported, never skipped". Read against walkChain that is only true for SOME declaration orders: the walk goes UPWARD from the proposed manager, so a chain declared subordinate-first (E1→E2, E2→E3, …) is written link by link, each walk seeing only the short chain above, and a 21-link chain lands unrefused; declared top-first it is refused at the last write. No file in hits claims the cap (the TSDoc names three refusals only), so it is not a declared≠enforced defect of this diff; it is a wrong sentence in the acceptance note. Should-fix: correct the note (or carry the cap into the load-time walk, which already has the path length, once MAX_MANAGER_CHAIN_DEPTH has a home in spec — a card, not this PR).
• Out-of-scope finding 2 / Skills-docs: follow-up owed — FILES: under ruling [Decision] pm-dispatch: which PRs owe a Skills-docs: line (the #26184 audit Part B rule draft) — protocol-kind only, protocol-kind plus narrowing, or not adopted #26369 B that value is a permitted form; the seat files the owed card and rewrites the line to #N before ACCEPT (pm-dispatch SKILL.md:313, review-checklist.md:18) — a seat act, not a contract-review verdict. The zero-headroom claim is TRUE on this head: skills/objectstack-platform/SKILL.md is 24005 bytes, priced 23985 → 5997 tokens = its ceiling; evals/config-plugins-ops.json is 5873 bytes → 1469 = its ceiling. One correction to the note: "raising a ceiling is not this card's call" is half right — the standing ruling 「A:先削重复,余额按实测提高」 (card skills(objectstack-platform): teach demoStaff and when to pick it over devLogins #26302, same row) is the payment path, so the follow-up card should cite it and pay in that order (cut restatements first, then raise AT the measurement). Deferral acceptable.
• Attribution at boot: authSystemWriteContext() with no request resolves no attributedUserId and answers { isSystem: true } — the same system write the first pass's email_verified update is. Right.
• Hand-cleared manager re-written: consistent with the module's existing idempotency, where a hand-removed position or permission-set assignment is also re-added ("only its missing assignments are added"); the declaration wins over absence only, the boot is development-only, and the count is logged. Acceptable; see ④ should-fix on the schema TSDoc.
• Governed surfaces: none in the file list; Governed Surface Queue Guard green; 522 changed lines. Premise (a demoStaff entry carries name, email, position?, permissionSets? only) holds on 43731031.

④ Design judgment

packages/spec/src/system/demo-staff.zod.ts — holds.

• Tried: a manager written as a display name → refused at demoStaff.N.manager by .email() with a message that names the fix. A manager written as a user id via managerId: 'usr_…' → alias to manager, then .email() refuses the id, two loud steps, no silent strip. Mixed-case address → accepted here, folded in the stack check and the provisioning identically (①).
• Should-fix (docs, one clause): the key's TSDoc says "A manager someone already set on that account is left as it is" but not that a CLEARED one is written again — the one case an operator can be surprised by. The module header and the changeset say it; the authorable TSDoc, which an IDE shows the author, does not. Add the clause there (the describe and the mdx row need not change).

packages/spec/src/stack.zod.ts — holds.

• Cycle detection is complete for this graph: out-degree is at most one (one manager per entry), so from any unsettled start the walk either reaches an entry with no manager, a settled entry, or revisits the current path. A revisit is a loop, reported once with path.slice(indexOf(cursor)) (the tail an entry hangs from is excluded, as the test pins); every entry on the path is then settled, so a later start reaching the same loop stops at a settled node and does not report it twice; a second, disjoint loop is found from its own unsettled start; a long loop is only a longer path. A self-reference is diverted to its own refusal before managerOf.set, so a self-loop never enters the walk. Tried the duplicate-address edge: an entry whose own email is a repeat and that names that address resolves to the FIRST occurrence (?.[0]), so it is reported as a link beside the duplicate-address refusal rather than as self-reference — both loud, acceptable.
• Runs at load, unconditionally, in strict defineStack; status 422 under an existing ledger code (①). Messages carry no tracker number (the check:doc-authoring rule) and each names the remedy.
• The manager-is-not-a-string skip is moot: in strict mode the check reads the parsed result.data, where manager is already a valid address.

Cited code, read to judge the above (not reviewed; for the lane seat's ACCEPT at TIER_DEFAULT):

• demo-staff.ts: the second pass runs after the first pass's loop, inside the same provisionDemoStaff call, on the same kernel:ready hook, and AppPlugin seeds at kernel:bootstrapped — so "after every entry exists, before the seed" holds. Each entry is its own try/catch; a thrown find/update or a refusal is pushed to outcome.failed and auth-plugin.ts logs every failed row at warn — it cannot fail half-way in silence. The refusals (self, cycle, depth, cross-org, directory-owned) are applyUserManagerLink's own; the module carries no copy.
• Should-fix (lane): linkDeps passes no logger, so membershipOrgIds's "the cross-organization screen could not read sys_member, so the link was accepted without it" warning is dropped on this path — the one degradation that module promises to say once is silent here. Pass ctx.logger through DemoStaffProvisioningDeps. Not a must-fix: the fail-open posture is the endpoint's own and the read's failure at boot is improbable.

Must-fixes: none. Should-fixes: three (the schema TSDoc clause; the depth-cap sentence in the acceptance note; the dropped logger on linkDeps).

Implemented-by: claude/project-thread-9ycve3
Reviewed-by: session_01WGufzfhobWEgUUrjz4rrbh

VERDICT: PASS

席位核对 · ACCEPT · domain:spec seat 1 (#6017) · session session_01WGufzfhobWEgUUrjz4rrbh · 2026-10-27T15:51Z

Head 53d29e263c2573b2442cd17af01eedab1e2c8d4b. Card #26616, claim 6442804755, dev report 6445286003.

• Contract review: owed at CONTRACT_REVIEW_TIER for system/demo-staff.zod.ts and stack.zod.ts. PASS 6445518048 at a516ef70, with no must-fixes. The one commit since then, 53d29e26, lands should-fixes (a) and (c) only: the diff from a516ef70 to 53d29e26 is 4 files, +39/−4.
  • (a) The manager TSDoc now says that a cleared manager is written again on the next boot.
  • (c) DemoStaffProvisioningDeps.logger is passed into linkDeps (auth-plugin passes ctx.logger). A new unit case makes sys_member unreachable and pins that the warning lands once while the link is still written.
• (b): the PR body's depth-cap note now says what the tree does. A declared chain is bounded only when written top-first. The same order hole in POST /api/v1/auth/admin/set-user-manager predates this PR and is filed as plugin-auth: set-user-manager's depth cap counts only the chain above the new manager, so linking bottom-up builds a manager chain past MAX_MANAGER_CHAIN_DEPTH (each link 200) #26775 (domain:server).
• Lane seat (rest of the diff, TIER_DEFAULT):
  • manager names another entry by email, folded with trim().toLowerCase() on both the stack and the provisioning side.
  • The stack refuses a manager that names no entry, a self-reference and a loop with STACK_CROSS_REFERENCE_INVALID (422), at load.
  • The second provisioning pass runs after every entry exists, through applyUserManagerLink. It writes only a null manager_id, and each entry fails loudly to warn.
  • No example app declares demoStaff.
• Skills-docs: #26764. Both skills files are at zero headroom, and the card cites the skills(objectstack-platform): teach demoStaff and when to pick it over devLogins #26302 payment path.
• Shape: Fixes #26616, 11 files. @objectstack/spec and @objectstack/plugin-auth are minor. Clause-②: yes (widening) and Metadata-protocol: added. check-governed-merges --pr 26763: NOT governed, 557 changed lines.
• Gates: check-runs on this head are 42 success, 9 skipped and 0 red. mergeable_state is clean.
• Landing: Tier S. pr_ready + automerge_enable in this act.