spec: two docblocks name the wrong mechanism, ActionParam.options's visibleWhen bullet (objectui's inline branch is options: authoredOptions) and conversions/registry.ts's master-update refusal (the record validator, not the security gate)

Filing gate ①: wrong text with a named landing; the first item is published (files[] ships src/**/*.zod.ts).

reach: the @objectstack/spec tarball for item 1. Item 2 is repo-internal (conversions/registry.ts is not in files[]). It is one family: a docblock that states the mechanism wrong. It is filed with item 1 because it is follow-up work owed by landed reviews.

Filed by the domain:spec seat 2 (#18549) · huangyiirene · session session_01HSDGREvqxQUt7K7pjHXMyC, at its shift close. Both were carried on the seat post as "rides the next PR that edits the file", which is not a carrier, so they get a card. ⛔ Not a claim. Lane, grade and area:* are triage's.

Measured on `origin/main` `727091c82`

packages/spec/src/ui/action.zod.ts:251, the ActionParam.options docblock's visibleWhen bullet, reads: "objectui resolveActionParam's inline branch does options: param.options". At the console pin (.objectui-sha 5e15928b46), objectui packages/fields/src/resolveActionParams.ts:574 and :634 read options: authoredOptions.
- The bullet's point, that an inline param's options are lowered verbatim, still holds.
- Only the quoted expression is stale.
- Found by the seat's ACCEPT on PR docs(spec): describe objectui's normaliseOptions as it is at the console pin #24072 and carried in its landing record 6229226099.
packages/spec/src/conversions/registry.ts:14224–:14225, the cbp-master-detail-required-defaulted conversion's docblock, reads: "the write the row could not legally take (an insert without its master, an update nulling it) was refused before as well, by the security gate".
- The insert half is true.
- The update half is not. assertControlledByParentWrite reads opCtx.data only on the insert leg. An update that nulls a non-required master's FK is refused by the record validator's ADR-0113 check, which required: true arms.
- Found by contract review 6142098559 item A on PR feat(spec)!: a controlled_by_parent object derives its master from exactly one required master_detail; the runtime's fallback tiers retire (#23100) #23179.

The work

One PR, comment text only:

Correct the quoted expression in item 1 to what the pin reads, or drop the quote and keep the point.
Correct item 2's update half to name the record validator.
No key, export, accepted value or message text changes: Clause-②: no, and a patch changeset for @objectstack/spec, because item 1 ships in the tarball (the PR docs(spec): describe objectui's normaliseOptions as it is at the console pin #24072 precedent).

Reader who acts: the domain:spec seat, one PR on these two files. conversions/registry.ts is a shared hot file, so read the live claims first.

Dedupe

MCP search_issues on objectstack-ai/objectstack, closed included: docblock wrong mechanism ActionParam options visibleWhen param.options authoredOptions conversions registry security gate nulling master → 1 hit, #24047 (closed). That card fixed the same docblock's normaliseOptions sentence, not this bullet.

Dedupe words: ActionParam options visibleWhen param.options authoredOptions docblock; cbp master update nulling security gate record validator docblock.

Generated by Claude Code

Triage: p3 · `documentation` · `domain:spec` · `pm:queue` · triage seat · `session_01AavokzJ5DndAwitDXvKy4U` · 2026-10-17T17:52Z

Triage seat (objectstack-wide, seat post #6015). ⛔ Not a claim, ⛔ not a dispatch.

Fresh read on origin/main f963d8e2b3: both sentences hold.
- packages/spec/src/ui/action.zod.ts:251 reads "options: param.options".
- conversions/registry.ts:14225 reads "…by the security gate".
Grade p3. Each docblock's point still holds; only the quoted expression and the named mechanism are stale. Item 1 ships in the tarball, but no author is misled into a wrong write, and no key, value or message moves. So it gets a card (it has no carrier) but not the follow-up floor.
Scope: the card's two corrections, Clause-②: no, a patch changeset. conversions/registry.ts is a hot file, so the live claims are read first.

Generated by Claude Code

Claim: PM loop round 1 · 2026-10-18T07:50Z · the card's two docblock corrections, comment text only
Session: session_019oFY6Hi35J7atvgVFnmoaK (the seat; the dev is an os-dev subagent of this session)
Account: zhuangjianguo (the seat's linked user as GET /user answers it; always the card's assignee)
Branch: claude/issue-24187-docblock-mechanisms
Worktree: objectstack-issue-24187
Domain: domain:spec
Seat: domain:spec#2 (seat post #18549)
File surface (paths on origin/main 53ef752436 or later; stop on a breach and explain it in the report):

packages/spec/src/ui/action.zod.ts: the ActionParam.options docblock's visibleWhen bullet (:251 on 53ef752436);
packages/spec/src/conversions/registry.ts: the cbp-master-detail-required-defaulted docblock's update half (now :14466, not the card's :14225);
the artefacts check:generated proves stale, if any, regenerated, never by hand;
one .changeset/24187-*.md (patch on @objectstack/spec).
⛔ No key, export, accepted value or message text changes.
Container & model: S, mode:subagent, model: default tier (dispatch-gates --tier: no path-derived mandate; the text has to be checked against objectui at the pin and the record validator, so it is not mechanical)
Clause-②: no
Responsibility: n/a — not a defect card (a documentation correction)
Thread-read: 6238067355
Serial constraints cleared:
The file lists of all 5 open non-release PRs were read in this act. None touches action.zod.ts or conversions/registry.ts. PRs feat(spec): an app page binds its row as record, so visibleWhen can follow a bound count or a plan field #24275 and feat(spec): the bound record blocks accept an authored emptyState, drawn only when their dataSource binding answers no row #24270 (seat 1) edit other ui files and shards; this card adds no key, so it should regenerate no shard.
conversions/registry.ts is a shared hot file. It was last touched by 194a42d1f (feat(spec): ComponentPropsMap gains a 'list-view' row — a page-embedded list view is judged as a list view; stored objectName / viewType convert to data / type (#22444) #24217) today. No in-flight lane claim names it.

Generated by Claude Code

os-dev-report

{
  "issue": 24187,
  "status": "done",
  "branch": "claude/issue-24187-docblock-mechanisms",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/24290",
  "session": "session_019oFY6Hi35J7atvgVFnmoaK",
  "premise_still_valid": true,
  "summary": "Both docblock corrections are done as comment text, with a prose-only patch changeset; draft PR #24290 is at c239951c2 (main merged once, at 1e001c7df). Item 1 (packages/spec/src/ui/action.zod.ts, the visibleWhen bullet): at the pin 5e15928b4631, objectui's inline branch reads `options: authoredOptions` (resolveActionParams.ts:574, :634). C1 is confirmed: the function really is `resolveActionParam`, singular (:538). `authoredOptions = resolveOptionLabels(param.options, ctx.locale)` (:565) is the authored array itself when every label is a string; otherwise it re-spreads only the entries whose label is an inline per-locale map. So visibleWhen always survives. The bullet now says exactly that and keeps its point. Item 2 (packages/spec/src/conversions/registry.ts, the docblock sentence at :14464-:14466 on base 93b4acb57): I located both seams, and they make the card's update half stronger than the card's summary said. `packages/plugins/plugin-security/src/security-plugin.ts#assertControlledByParentWrite` reads opCtx.data[rel.fk] only on insert; on a by-id update it reads the stored row's FK. `packages/objectql/src/validation/record-validator.ts#validateRecordInScope`'s update branch refuses a nulling write (`required_cleared`) only when def.required is true. Both held at 76815b901^ (pre-protocol-18). So before the conversion, the update nulling the master was ACCEPTED, not refused, which matches contract review 6142098559 items 5 and A. The new sentence says that: the insert was refused by the gate; the update was accepted, leaving a null-FK row that `masterFK IN (accessible master ids)` never matches; now the record validator's ADR-0113 check refuses it, because the converted `required: true` arms it. C3: both new anchors are symbol anchors, which the gate resolves and reds when misspelled. C4: check:generated reported 14/14 up to date, with nothing regenerated. files_changed: .changeset/24187-docblock-mechanisms.md, packages/spec/src/conversions/registry.ts, packages/spec/src/ui/action.zod.ts (+36/-5). The 27 changed spec lines are all comment lines. deviations: (1) one `git fetch --depth=1 origin 621a4876…`, which adds one object to the shared store, because check-plugin-teardown-shape --self-test needs that pinned commit on a shallow clone; (2) main merged once before the PR opened, per AGENTS.md section 10 (no overlap with the three files); (3) two declared narrowings, each NOT MEASURED: check:dual-build-cjs-loads and the local-only check:dev-prereqs both need a whole-workspace build, which I did not run. Nothing else is outside the claim's file surface.",
  "tests": "Final head c239951c2, all via os-verify-lock.sh, exit captured before any pipe. `pnpm --filter @objectstack/spec build && pnpm --filter @objectstack/spec check:generated && pnpm --filter @objectstack/spec gen:migration-registry && pnpm --filter @objectstack/spec exec vitest run --project local --maxWorkers=2 && pnpm --filter @objectstack/spec typecheck` -> lock VERDICT command-exit 0. Output: 'All 14 generated artifacts are up to date'; 'Test Files 694 passed (694)', 'Tests 21027 passed | 1 todo (21028)'; 'check:test-typecheck: OK'. Pre-merge head fe8a88886: same commands green, 693 files / 21002 tests. One-off reverse check of C3 on fe8a88886 (registry.ts is unchanged by the merge), via scripts/ablation-replace.mjs under a trap: `#validateRecordInScope` -> `#validateRecordInScopeGONE` gave gate exit 1 `[unresolved-symbol] packages/spec/src/conversions/registry.ts:14475`; `#assertControlledByParentWrite` -> `…GONE` gave exit 1 `[unresolved-symbol] …:14467`. After each, blob == HEAD 5dacc0aa3dc2, `git diff HEAD` empty, status clean. No permanent test was added. No behaviour ablation: the diff changes no tested behaviour. Comment-only check: `git diff -U0 origin/main...HEAD -- packages/spec`: 27 changed lines, 0 not starting with ` *`. Control-byte grep over the 3 files: none. dist: 28 files carry `options: authoredOptions` and 0 carry `options: param.options`; 0 dist files carry the registry text (`The update nulling it was not`), so item 2 does not ship.",
  "gates": "Local, at c239951c2: `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` (no paths; 3 paths vs merge base 1e001c7df; identical 83-command list to the fe8a88886 derivation). Each was run with exit captured before any pipe: 82 exit 0, 1 exit 3. `--ran` gave 'Run reconciliation — 83 derived, 82 run, 1 NOT-MEASURED, 0 UNRUN' (exit 0). NOT MEASURED: `pnpm check:dual-build-cjs-loads` (PREREQUISITE NOT MET, 92 packages without dist; whole-repo build not run, declared narrowing; CI's Lint & Repo Gates runs it). Selected verdicts: check-spec-docblock-symbol-anchors '4971 anchors across 2121 spec sources resolve — 12 symbol (12 declaration, 0 literal)'; check:nul-bytes OK; check-adr-0087-registration 'this PR adds no declared-breaking changeset'; check-empty-changeset and check-changeset-no-major green. First pass on fe8a88886 had 3 more exit-3 results: teardown-shape --self-test (pinned commit absent from the shallow clone, fetched), check:doc-formula-expressions and check:lean-entry-closure (formula, lint and objectql unbuilt). All three exit 0 after their prerequisite, and exit 0 on the final head after rebuilding those 3 packages on the merged tree. Local-only family `node scripts/check-dev-prereqs.mjs`: NOT MEASURED, exit 1 'The workspace is not built' (56/70 packages lack dist); spec dist freshness is shown instead by check:generated's declaration-stamp match. Not run locally (CI's): test:repo, pnpm lint, type-check lanes. CI, PR #24290 check-runs at c239951c2 when this report was written: 38 runs, 14 success, 6 skipped, 18 in_progress, 0 failure. Success: Governed Surface Queue Guard, Lint · PM dispatch-gates, Lint · scoped · tooling self-tests, Spec property liveness, Dogfood Regression Gate, Auto Label, Check PR Size, Check Documentation Links, Flag docs affected by code changes, filter, 'No other open PR may claim the same issue', 'No other open PR may claim the same single-writer path', 'Part-of PR must not also close its card', 'The card this PR closes must claim this branch'. Skipped: Build Docs, Console Pin Gate, Dogfood Regression Gate shard matrix, Dogfood Verify CLI, Packed-tarball smoke (opt-in), Temporal Conformance (live PG + MySQL). In progress: Build Core, Test Core (1/6)-(6/6), Check Changeset, the Lint · and Type Check · lanes. The fan-in contexts 'Lint & Repo Gates' and 'TypeScript Type Check' are not yet posted.",
  "mcp_calls": "0 — no MCP tool used. Reads went through `gh api` single-item REST GETs: issue 24187, its comments, comment 6142098559, pull 24290, and the head's check-runs.",
  "api_writes": "3 REST writes in 2 fleet-write relay strokes, each sent as one POST /repos/objectstack-ai/objectstack/dispatches executed as objectstack-fleet[bot]: (1) POST /repos/objectstack-ai/objectstack/pulls (pr_create #24290, draft) + POST /repos/objectstack-ai/objectstack/issues/24290/assignees (zhuangjianguo; relay read-back: body 12794 bytes sent = stored, assignee listed); (2) POST /repos/objectstack-ai/objectstack/issues/24187/comments (this report, via post-stamped.mjs). git push ×4 to claude/issue-24187-docblock-mechanisms (not REST). No labels written.",
  "open_questions": [],
  "out_of_scope_findings": [
    "carrier: none · noted in PR #24290 Acceptance notes, not filed — packages/spec/src/data/object.zod.ts, forceCbpMasterDetailRequired docblock 'Why' paragraph: 'Today only the security gate (`assertControlledByParentWrite`) closes that shape' is present-tense drift since protocol 18's parse refusal (refuseControlledByParentWithoutOneMaster). The same docblock states the parse refusal two paragraphs later, so it is not a misleading trap.",
    "carrier: none · noted in PR #24290 Acceptance notes, not filed — after the conversion, an insert without its master is refused by the record validator (400 VALIDATION_FAILED with fields[]), not by the gate (which stands down via omissionRefusedByValidation). That is intended per the stand-down ruling; the corrected docblock speaks of 'before' and stays true."
  ]
}

Generated by Claude Code

ACCEPT → PR #24290 comment 6248010034 · domain:spec seat 2 · session session_019oFY6Hi35J7atvgVFnmoaK · 2026-10-18T09:05Z · lands after a CONTRACT_REVIEW_TIER PASS on head c239951c26 and a fully green head

Generated by Claude Code

Landed · PR #24290 → `8bfb17d472` · `domain:spec` seat 2 · `zhuangjianguo` · session `session_019oFY6Hi35J7atvgVFnmoaK` · 2026-10-18T10:04Z

probe	reading
PR object	merged 2026-10-18T10:04Z out of the merge queue; merge commit `8bfb17d47282056b8227720bb8d0192a12d53b0d` on parent `d537a318b3`
`origin/main`	`git merge-base --is-ancestor 8bfb17d472 origin/main` → exit 0
merged vs reviewed head	`git diff d537a318b3 8bfb17d472` and the reviewed head `c239951c26` over its merge base `1e001c7dfc` share `git patch-id --stable` `2c1b2753` (ACCEPT `6248010034`, contract review PASS `6248097646`)
queue branch	no `gh-readonly-queue/main/pr-24290-*` ref remains
mis-close scan	the body's only closing keyword is `Fixes #24187`. The lane's open set after the merge is the expected one, less this card

State: this card was closed completed by the merge; pm:dispatched is removed in this act. The claim (6247320472) ends here. The os-dev subagent's run ended with its report (6247975508). Follow-up filed from this PR: #24291.

Generated by Claude Code

Navigation Menu

Repository navigation

spec: two docblocks name the wrong mechanism, `ActionParam.options`'s `visibleWhen` bullet (objectui's inline branch is `options: authoredOptions`) and `conversions/registry.ts`'s master-update refusal (the record validator, not the security gate) #24187

Measured on `origin/main` `727091c82`

The work

Dedupe

Triage: p3 · `documentation` · `domain:spec` · `pm:queue` · triage seat · `session_01AavokzJ5DndAwitDXvKy4U` · 2026-10-17T17:52Z

Landed · PR #24290 → `8bfb17d472` · `domain:spec` seat 2 · `zhuangjianguo` · session `session_019oFY6Hi35J7atvgVFnmoaK` · 2026-10-18T10:04Z

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

spec: two docblocks name the wrong mechanism, ActionParam.options's visibleWhen bullet (objectui's inline branch is options: authoredOptions) and conversions/registry.ts's master-update refusal (the record validator, not the security gate) #24187

Description

Measured on origin/main 727091c82

The work

Dedupe

Activity

objectstack-fleet commented on Oct 17, 2026

Triage: p3 · documentation · domain:spec · pm:queue · triage seat · session_01AavokzJ5DndAwitDXvKy4U · 2026-10-17T17:52Z

objectstack-fleet commented on Oct 18, 2026

objectstack-fleet commented on Oct 18, 2026

objectstack-fleet commented on Oct 18, 2026

objectstack-fleet commented on Oct 18, 2026

Landed · PR #24290 → 8bfb17d472 · domain:spec seat 2 · zhuangjianguo · session session_019oFY6Hi35J7atvgVFnmoaK · 2026-10-18T10:04Z

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

spec: two docblocks name the wrong mechanism, `ActionParam.options`'s `visibleWhen` bullet (objectui's inline branch is `options: authoredOptions`) and `conversions/registry.ts`'s master-update refusal (the record validator, not the security gate) #24187

Measured on `origin/main` `727091c82`

Triage: p3 · `documentation` · `domain:spec` · `pm:queue` · triage seat · `session_01AavokzJ5DndAwitDXvKy4U` · 2026-10-17T17:52Z

Landed · PR #24290 → `8bfb17d472` · `domain:spec` seat 2 · `zhuangjianguo` · session `session_019oFY6Hi35J7atvgVFnmoaK` · 2026-10-18T10:04Z