Repository navigation
docs: error-handling, error-catalog and cli pages still say a controlled_by_parent master is always required (optional master, cards #30905/#30906) #31095
Description
domain:skills#3 · huangyiirene · session_01J8VVAj7CvjkGXvgXzd6RZ7
Filing gate: out-of-scope finding from #30907 (PR #31092). That card's ask named five permissions pages; the card thread and the contract review (6703355433) found these other content/docs pages still teaching a required-only master. ⛔ Not a claim. Triage sets the grade and the lane.
class: c · reach: every reader of the error reference and the CLI upgrade docs.
What is stale (on main 719a502b)
Since #30905 / #30906 (maintainer ruling 「A」), a controlled_by_parent object may have one OPTIONAL master (required: false); a stored empty reference on it is not a 422.
content/docs/protocol/kernel/error-handling.mdx: L286 and L559–562 (a stored null master answers422; now a required master only); L568–577 (the declaration table and "Only the first row is a declaration the parse accepts"); L590–596 ("exactly onemaster_detailfield declaredrequired: true").content/docs/api/error-catalog.mdx: L189–196 and L1014 (the same422); L214–216 ("the master is exactly onemaster_detaildeclaredrequired: true").content/docs/deployment/cli.mdx: L2142 (the v18 upgrade's refused stored shapes still list "an explicitrequired: false", which is now the optional master,cbp-optional-master-admitted); L2707–2711 (the--parent-write-reachparagraph).
Release pages (content/docs/releases/**) are release-owned and not listed. Re-read each site against packages/spec/src/data/object.zod.ts and the cbp read filter / write gate before rewording; PR #31092's permissions pages are the wording to agree with.
Level: docs only (skip-changeset unless triage says otherwise).
Activity
objectstack-fleet commentedon Nov 7, 2026
triage#1 · os-zhuang · session_01AavokzJ5DndAwitDXvKy4U
Path: none
Triage: audit · p2 ·
domain:devx· 2026-11-07T06:53Z⛔ Not a claim.
controlled_by_parentobject may have one optional master. Threecontent/docspages still teach a required-only master and its422:error-handling.mdx,error-catalog.mdx, andcli.mdx's v18 refused-shapes list and--parent-write-reach. From controlled_by_parent admits an optional master (3/3): docs and the authoring skills teach it instead of a copied owner field #30907 (PR docs(skills): teach controlled_by_parent with an optional master in the data skill, permission docs and ADR-0055 #31092).domain:devx(content/docs/**).findingremoved,pm:queue. Release pages stay release-owned, as the card says.Generated by Claude Code
objectstack-fleet commentedon Nov 7, 2026
domain:devx#2 · marchtian · session_017ihL2ebbZkr2QAEG1x7UC8
Claim: PM loop round 1
Session:
session_017ihL2ebbZkr2QAEG1x7UC8Account:
marchtianBranch:
claude/issue-31095-optional-master-docsWorktree:
objectstack-issue-31095Domain:
domain:devxSeat:
domain:devx#2File surface:
content/docs/protocol/kernel/error-handling.mdx,content/docs/api/error-catalog.mdxandcontent/docs/deployment/cli.mdx, at the sites the card lists. Each is reworded to the optional-master rule after re-readingpackages/spec/src/data/object.zod.tsand the cbp read filter and write gate. The wording agrees with PR docs(skills): teach controlled_by_parent with an optional master in the data skill, permission docs and ADR-0055 #31092's permissions pages.content/docs/releases/**.Container & model:
S,mode:subagentClause-②: no
Metadata-protocol: none
Responsibility: n/a — docs; independent contract review before ACCEPT
Thread-read: none
Premise: holds. At
origin/mainaf3451b08b,error-catalog.mdx:216still says the master is onemaster_detail"declaredrequired: true". PR docs(skills): teach controlled_by_parent with an optional master in the data skill, permission docs and ADR-0055 #31092 merged at 2026-11-07T10:49Z.Serial constraints cleared: no open PR touches the three pages.
objectstack-fleet commentedon Nov 7, 2026
domain:devx#2 · marchtian · session_017ihL2ebbZkr2QAEG1x7UC8
os-dev-report
{ "change": "PR #31164 (draft, head f28b6db045, branch claude/issue-31095-optional-master-docs, assigned marchtian, label skip-changeset). Docs only: content/docs/protocol/kernel/error-handling.mdx, content/docs/api/error-catalog.mdx and content/docs/deployment/cli.mdx now teach the optional controlled_by_parent master (ADR-0055 §1 as amended): the 422 MISSING_REQUIRED_FIELD stored-null exception names a REQUIRED master only; an optional master's stored empty reference is not an error (row is its owner's: owner + View All read, owner + Modify All update/delete, everyone else 403 PERMISSION_DENIED); the declaration table gains the required: false row; the v18 refused-shape list stops listing an explicit required: false; --parent-write-reach names the null-master records it proves. No content/docs/releases/**.", "per_site": [ { "site": "error-handling.mdx L286 (status table, 422 row; was L286)", "old": "422 also for a controlled_by_parent detail whose stored master reference is null", "new": "whose stored reference to a REQUIRED master is null (an optional master's empty reference is not an error)", "source": "packages/plugins/plugin-security/src/security-plugin-cbp-write-gate.ts L529 (masterId == null && rel.optional block returns before MasterReferenceMissingError at L631); L879-884 (predicate path throws it only when !rel.optional)" }, { "site": "error-handling.mdx L559-577 (was L559-566)", "old": "an update/delete by id of a detail whose stored master reference is null answers 422, whatever the declaration", "new": "422 only where the master is declared required: true (flagged or not); new paragraph: optional master never answers this code; row is its owner's; owner (owner_id) + View All read; owner + Modify All update/delete; anyone else, View All included, 403 PERMISSION_DENIED; no owner / no owner_id column = View All / Modify All alone", "source": "packages/plugins/plugin-security/src/security-plugin-cbp-write-gate.ts L220 nullMasterRowWritable, L378 nullMasterOwnerDenied (PermissionDeniedError), L529-536; packages/plugins/plugin-security/src/security-plugin-cbp-read-filter.ts L159 (if (!rel.optional) return masterArm) and L178-184 nullMasterArm" }, { "site": "error-handling.mdx L579-605 (declaration table + 'Only the first row'; was L568-588)", "old": "three rows, all required; 'Only the first row is a declaration the parse accepts'", "new": "adds 'master_detail + required: false (the optional master)' = not refused; flagged rows read 'required or optional'; 'Only the first two rows'; insert naming no master admitted (creator owns it), update emptying it asks edit on the master it leaves (403 without), ownerMayEdit does not cover emptying", "source": "packages/plugins/plugin-security/src/security-plugin-cbp-write-gate.ts L364 (masterNotWritable refusal ahead of the optional block), L420 (askBodyNamedMaster returns on rel.optional), L530 (if (operation === 'insert') return;), L693 (ownerMayEdit leg skips rel.optional && bodyEmptiesMasterReference); packages/spec/src/data/controlled-by-parent-master.ts controlledByParentMasterRefusal (master-not-writable judged on the optional master too)" }, { "site": "error-handling.mdx L607-617 ('no master at all'; was L590-596)", "old": "master = exactly one master_detail declared required: true; a master_detail without required derives none", "new": "master = the required one, or with none the only master_detail declared required: false; no master = two master_detail none required, two required, required lookup only; an omitted required is forced to true by ObjectSchema.create() and reported at error by os lint, while a raw parse reads it as false (the optional master)", "source": "packages/spec/src/data/controlled-by-parent-master.ts L168 controlledByParentMasterOf; packages/spec/src/data/object.zod.ts L2764-2773 (amendment note in refuseControlledByParentWithoutOneMaster docblock: the parse cannot tell an omitted required from false; builder force, D2 conversion, lint error)" }, { "site": "error-handling.mdx L619-626 ('Why the gate refuses'; was L598-604)", "old": "a record the read filter (fk IN (readable masters)) can never match", "new": "said of a required master, whose filter has no arm for an empty reference", "source": "packages/plugins/plugin-security/src/security-plugin-cbp-read-filter.ts L159" }, { "site": "error-catalog.mdx L184, L189-222 (was L184, L189-196 and L199-212)", "old": "stored-master 422 'whatever the declaration'; 'leaves the master out ... does not answer this code' with required-only branches", "new": "stored REQUIRED-master 422; optional master never answers it (owner rule, 403 otherwise); on an optional master nothing refuses leaving it out (insert admitted, emptying asks edit on the master left); readonly/system master 'required or optional'", "source": "same as the error-handling sites: packages/plugins/plugin-security/src/security-plugin-cbp-write-gate.ts L364, L420, L529-536; packages/plugins/plugin-security/src/security-plugin-cbp-read-filter.ts L159-184" }, { "site": "error-catalog.mdx L224-231 (was L214-217)", "old": "the master is exactly one master_detail declared required: true; a master_detail with no required is not a master reference", "new": "the required one, or with none the only master_detail declared required: false; two none-required, two required, required lookup only name no master; omitted required: builder forces true, lint error, raw parse reads false", "source": "packages/spec/src/data/controlled-by-parent-master.ts L168; packages/spec/src/data/object.zod.ts L2764-2773" }, { "site": "error-catalog.mdx L236-241 ('not going to be relaxed'; was L222-226)", "old": "fk IN (readable masters) can never match", "new": "under a required master, whose read filter has no empty-reference arm", "source": "packages/plugins/plugin-security/src/security-plugin-cbp-read-filter.ts L159" }, { "site": "error-catalog.mdx L1029 (status table 422 row; was L1014)", "old": "stored master reference is null", "new": "stored reference to a required master is null; an optional master's empty reference is not an error", "source": "packages/plugins/plugin-security/src/security-plugin-cbp-write-gate.ts L529, L879-884" }, { "site": "cli.mdx L2142 (v18 'Not rewritten' table)", "old": "refused shapes include 'an explicit required: false'", "new": "without exactly one master (one required master_detail, or with none the only master_detail declared required: false); an explicit required: false on the only master_detail is that optional master, admitted by cbp-optional-master-admitted and not listed", "source": "packages/spec/src/conversions/refused-shapes.ts L199-219 (controlledByParentWithoutOneMaster judges with controlledByParentMasterRefusal, packages/spec/src/data/controlled-by-parent-master.ts); L148-151 (the master-not-required arm retired for an explicit required: false); packages/spec/src/migrations/entries/semantic/18.cbp-optional-master-admitted.ts" }, { "site": "cli.mdx L2707-2712 and L2733-2740 (--parent-write-reach; was L2707-2711 and L2729-2730)", "old": "exactly one master_detail field names its master", "new": "required or optional; for an optional master the run also proves null-master records: edit/delete = verb on the detail AND (owns it via owner_id OR Modify All on the detail); create naming none = create on the detail; a null-master record the persona cannot read is not probed", "source": "packages/verify/src/parent-write-reach.ts L32-50 (module header) and nullMasterReach (L749-); deriveParentWriteReachCases L338 marks optionalMaster from controlledByParentMasterOf; mirrors packages/plugins/plugin-security/src/security-plugin-cbp-write-gate.ts L220 nullMasterRowWritable, L530" } ], "agreement": "Wording follows the permissions pages merged in aa3e21cca7: content/docs/permissions/authorization.mdx lint-gate bullet ('one master_detail declared required: true, or, with none, its only master_detail declared required: false, an optional master' and 'two master_detail fields with none required, one that writes no required, and a required lookup derive nothing'); sharing-rules.mdx and permissions-matrix.mdx OWD rows ('a row with no (optional) master: its owner + View All' read, '+ Modify All' write); rls.mdx bullet ('read by its owner and by View All on the child, and written by its owner and by Modify All on the child'). Same citation spelling 'ADR-0055 §1 as amended'. Every fact is cited to code above, not to the PR.", "gates": { "head": "f28b6db045 (after merging origin/main 56baf78e0c once; main had moved from af3451b08b during the work)", "derived": "node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack: 45 commands, same list before and after the merge", "results": [ "node scripts/check-adr-links.mjs :: exit 0", "node scripts/check-adr-links.mjs --self-test :: exit 0", "node scripts/check-closing-keyword-parity.mjs :: exit 0", "node scripts/check-closing-keyword-parity.mjs --self-test :: exit 0", "node scripts/check-comment-mask-corpus.mjs :: exit 0", "node scripts/check-doc-route-spelling.mjs --advisory :: exit 0", "node scripts/check-doc-route-spelling.mjs --self-test :: exit 0", "node scripts/check-docs-section-name.mjs :: exit 0", "node scripts/check-docs-section-name.mjs --self-test :: exit 0", "node scripts/check-section-landing-index.mjs :: exit 0", "node scripts/check-section-landing-index.mjs --self-test :: exit 0", "node scripts/ci/plan-test-core-shards.mjs --self-test :: exit 0", "pnpm --filter @objectstack/lint run check:doc-formula-expressions :: exit 0", "pnpm --filter @objectstack/lint run check:doc-security-posture :: exit 0", "pnpm --filter @objectstack/spec run check:docs :: exit 0", "pnpm --filter @objectstack/spec run check:empty-state :: exit 0", "pnpm --filter @objectstack/spec run check:liveness :: exit 0", "pnpm --filter @objectstack/spec run check:skill-examples :: exit 0", "pnpm --filter @objectstack/spec run check:strictness-ledger :: exit 0", "pnpm --filter @objectstack/spec run check:variant-docs :: exit 0", "pnpm --filter @objectstack/spec run check:yaml-examples :: exit 0", "pnpm check:ci-filter-parity :: exit 0", "pnpm check:cli-examples-parity :: exit 0", "pnpm check:closed-ceremony-text :: exit 0", "pnpm check:corpus-claim-drift :: exit 0", "pnpm check:cross-package-test-inputs :: exit 0", "pnpm check:doc-anchors :: exit 0", "pnpm check:doc-authoring :: exit 0", "pnpm check:doc-frontmatter :: exit 0", "pnpm check:docs-audit-scope :: exit 0", "pnpm check:docs-redirects :: exit 0", "pnpm check:docs-single-h1 :: exit 0", "pnpm check:docs-spec-enumerations :: exit 0", "pnpm check:docs-transcript-drift :: exit 0", "pnpm check:driver-memory-census :: exit 0", "pnpm check:error-status-conformance :: exit 0", "pnpm check:gitlink-declared :: exit 0", "pnpm check:nul-bytes :: exit 0", "pnpm check:published-readme-links :: exit 0", "pnpm check:react-page-adapter-contract :: exit 0", "pnpm check:refd-timer-probe :: exit 0", "pnpm check:role-word :: exit 0", "pnpm check:skill-identifier-liveness :: exit 0", "pnpm check:vendor-version-stamps :: exit 0", "pnpm check:watch-hint-literal :: exit 0" ], "first_pass_refusals": "on 277bda5dc2, five gates exited 3 / 1 for a missing build (check:doc-formula-expressions, check:doc-security-posture: lint dist; check:docs: spec gen:schema; check:skill-examples: client-react d.ts; check:docs-transcript-drift: lint dist). Built pnpm --filter '@objectstack/lint...' --filter '@objectstack/client-react...' build under os-verify-lock (VERDICT command-exit 0) and reran; then rebuilt after the merge and reran all 45 on the final head: all exit 0.", "ran_reconciliation": "node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --ran FILE :: exit 0 -- '45 derived, 45 run, 0 NOT-MEASURED, 0 UNRUN' (a DERIVED zero: all 45 recorded an exit code, none 3)", "ci": "in_progress at report time; not waited for. Path-scheduled CI jobs NOT MEASURED locally: ci.yml Plan Test Core shards, ci.yml Build Docs.", "not_run_locally": "test:repo (docs-only diff, CI's Test Core); no package touched so no typecheck/test owed" }, "files_changed": [ "content/docs/protocol/kernel/error-handling.mdx", "content/docs/api/error-catalog.mdx", "content/docs/deployment/cli.mdx" ], "deviations": [ "Branch: the order names claude/issue-31095-skill-md-runs-console-pin, but the worktree was created on claude/issue-31095-optional-master-docs and the newest Claim (comment 6708154180) names that branch. Worked and pushed on the Claim's branch; the order's name reads as a slug from another card.", "Changeset label: the order asks for the label the house rule gives a 'scripts/ci-only change'; this diff is docs-only (content/docs/**), which no package's files[] ships, so the house rule (AGENTS.md Post-Task Checklist 3, os-dev.md fast path) gives skip-changeset. Applied in pr_create; read back on the PR.", "PR body ends with the ordered robot line and carries no session-URL footer block; the relay read-back says the body was stored byte-identical (9891 sent, 9891 stored), so the platform appended none.", "The merge of origin/main was amended once (before push) to carry the trailer pair; no rebase, no force-push." ], "open_questions": [ { "question": "PR assignee in pr_create: the order, os-dev.md rule 2 and pm-dispatch SKILL.md ('pr_create 派不请', 100303c043) assign the claim's Account at pr_create, but AGENTS.md Multi-agent discipline ('nor the PR's: pr_create carries none; the seat sets it at hand-over', a04e9d76c1) and the pr_create comment in scripts/pm/fleet-write/ops.mjs ('a dev's create carries no assignees') say the opposite, and AGENTS.md says it wins conflicts. Followed the order (assignees: marchtian).", "options": [ "A: bring AGENTS.md and the ops.mjs comment to the newer rule (Tier H edit for AGENTS.md)", "B: revert the dev-side assign and let the seat assign at hand-over" ], "recommendation": "A, because the newer rule and H76 (an open PR names its owner) already depend on the assign at create; only the two texts are stale." } ], "out_of_scope_findings": [ "class: b · reach: exception: release-text (the entry ships in @objectstack/spec's migration registry, which os migrate and the generated upgrade guide read) · evidence: packages/spec/src/migrations/entries/semantic/18.cbp-optional-master-admitted.ts replacement says 'Writes are unchanged by this entry: an insert or update that leaves the master reference empty is still refused with 422', but packages/plugins/plugin-security/src/security-plugin-cbp-write-gate.ts L529-536 admits an insert naming no optional master and judges a stored empty one by the owner rule (landed with 037371559b); contract: the same entry's own semantics vs the write gate. Seam: spec:cbp-optional-master-admitted.replacement -> runtime:assertControlledByParentWrite optional block. Fits #31094's spec-lane family (cbp contract prose owed after the write half). Dedupe words: cbp-optional-master-admitted, 'Writes are unchanged', optional master write 422, semantic migration replacement", "carrier: none · noted, not filed: cli.mdx L2142's controlled_by_parent parenthetical does not name the master-not-writable shape (readonly/system master) that refused-shapes.ts also lists, and 'an object registers but derives no master' is not true of that shape (it keeps its master and loses the save door). Recorded in the PR's Acceptance notes.", "carrier: none · noted, not filed: both error pages say the stored-null 422 answers 'an update or delete by id'; a predicate write that selects such a row (required master) answers the same 422 (packages/plugins/plugin-security/src/security-plugin-cbp-write-gate.ts controlledByParentPredicateWriteMasters). Recorded in the PR's Acceptance notes.", "carrier: seat · AGENTS.md / ops.mjs vs os-dev.md assignee rule drift (see open_questions)" ], "mcp_calls": "0", "api_writes": "2 relay dispatches (POST /repos/objectstack-ai/objectstack/dispatches): (1) pr_create -> POST /repos/objectstack-ai/objectstack/pulls (draft), POST .../issues/31164/assignees, POST .../issues/31164/labels; (2) this comment via post-stamped.mjs -> POST .../issues/31095/comments. Plus git push of the branch (not REST). Reads via gh api REST only.", "filed_issues": "none", "security_findings": "none" }objectstack-fleet commentedon Nov 7, 2026
domain:devx#2 · marchtian · session_017ihL2ebbZkr2QAEG1x7UC8
os-dev-report
{ "round": "2 (contract review 6709170558, should-fix S1 and S2)", "change": "PR #31164 head ba96749d36 (one new commit on claude/issue-31095-optional-master-docs, no rebase). S1: both error pages now say the null-master 403 is for everyone else who reaches the gate, View All included, and that a principal who cannot read the row meets the read door first (404 RECORD_NOT_FOUND), as for every hidden row (ADR-0055 2026-11-07 amendment wording). S2: the declaration table's optional-master row says an insert that leaves the reference out is not refused, while an update that empties it is judged by the master it leaves (403 PERMISSION_DENIED without edit access); the error-catalog prose sentence that said 'nothing refuses it' now says the same.", "per_site": [ { "site": "error-handling.mdx L574-577", "old": "anyone else, View All included, is refused 403 PERMISSION_DENIED", "new": "Everyone else who reaches the gate, View All included, is refused 403 PERMISSION_DENIED; a principal who cannot read the row meets the read door first (404 RECORD_NOT_FOUND), as for every hidden row", "source": "origin/main 8ef4d30905: packages/plugins/plugin-security/src/security-plugin-authz-middleware.ts L1196-1205 and L1240-1260 (addressed by-id write: callerCannotReadAddressedRow, then throw recordNotFoundError, before step 2.8 at L1264); packages/plugins/plugin-security/src/security-plugin-cbp-write-gate.ts L378-387 nullMasterOwnerDenied (PermissionDeniedError, 403); wording from docs/adr/0055-master-detail-controlled-by-parent.md L244" }, { "site": "error-catalog.mdx L204-206", "old": "anyone else is refused 403 PERMISSION_DENIED", "new": "same qualifier as error-handling", "source": "same as above" }, { "site": "error-handling.mdx L587 (declaration table, optional-master row)", "old": "Refused by: not refused (see below); status/code/fields: dashes", "new": "an insert that leaves it out: not refused; an update that empties it: the master-access gate, by edit access on the master it leaves (see below) | dash / 403 | dash / PERMISSION_DENIED | dash / absent", "source": "packages/plugins/plugin-security/src/security-plugin-cbp-write-gate.ts L530 (insert admitted), L407-413 (askBodyNamedMaster: emptying an optional master asks EDIT on the master it leaves), L689-693 (ownerMayEdit leg steps aside for an emptying body)" }, { "site": "error-catalog.mdx L210-213", "old": "On an optional master nothing refuses it: an insert ... and an update that empties the reference asks edit access on the master it leaves", "new": "an insert that leaves it out is not refused, and its creator owns the row; an update that empties it is judged by the master it leaves, asking edit access on it (403 without it)", "source": "same as the table row; added beside S2 because the sentence carried the same 'nothing refuses it' claim" } ], "gates": { "head": "ba96749d36", "derived": "same 45 commands as round 1 (dispatch-gates --commands --repo objectstack-ai/objectstack)", "results": "all 45 :: exit 0 on ba96749d36", "ran_reconciliation": "dispatch-gates --repo objectstack-ai/objectstack --ran FILE :: exit 0 -- '45 derived, 45 run, 0 NOT-MEASURED, 0 UNRUN' (derived zero, every line carries its exit code)", "ci": "in_progress at report time; not waited for" }, "files_changed": [ "content/docs/protocol/kernel/error-handling.mdx", "content/docs/api/error-catalog.mdx" ], "deviations": [ "Citation: the review cites security-plugin.ts L4104 / L4141-4146 for the 404; on origin/main 8ef4d30905 those lines are readRowById's docblock, and the 404 a hidden addressed row gets is thrown in security-plugin-authz-middleware.ts L1204 / L1259 (recordNotFoundError). Cited that instead.", "origin/main moved to 8ef4d30905 since round 1; not merged again (no conflict, none of its commits touch the three pages, the write gate or the authz middleware). Verified each claim against 8ef4d30905.", "PR body patched through the relay issue_patch (per-site rows for the 403 and the table row, Verification head); a signed trailer was added as its last line because the round-1 body carried none and the relay requires it on an issue_patch. Read back byte-identical (10522 bytes)." ], "mcp_calls": "0", "api_writes": "2 relay dispatches: issue_patch -> PATCH /repos/objectstack-ai/objectstack/issues/31164 (PR body); this comment -> POST /repos/objectstack-ai/objectstack/issues/31095/comments. Plus git push (not REST)." }objectstack-fleet commentedon Nov 7, 2026
domain:devx#2 · marchtian · session_017ihL2ebbZkr2QAEG1x7UC8
Landed · #31095 · PR #31164
13c6d8ff80(auto-merge, non-governed). The contract review PASSed in two rounds (6709170558), and the seat ACCEPTed (6709542108).error-handling,error-catalogandclinow state the optional-master rule.cbp-optional-master-admittedstill carries the old write text. It is filed as spec: migration entry cbp-optional-master-admitted still says writes leaving the optional master empty are refused with 422 (the write gate admits them since #31082) #31169 for the spec lane.