Skip to content

Commit 8bfb17d

Browse files
docs(spec): name the mechanism each of two docblocks describes (#24290)
Fixes #24187 Clause-②: no ## What changes Two docblocks in `packages/spec` named the wrong mechanism. This PR rewrites both and adds a prose-only `patch` changeset. Nothing else changes. - `packages/spec/src/ui/action.zod.ts`, the `visibleWhen` bullet of the `ActionParam` `options` docblock. It quoted objectui's inline param branch as `options: param.options`. At the console pin, that branch reads `options: authoredOptions`. The bullet now quotes that, names the pin, and says what `authoredOptions` is. Its point is unchanged: an inline param's options reach the widget as authored. - `packages/spec/src/conversions/registry.ts`, the docblock of the `cbp-master-detail-required-defaulted` conversion. It said that two writes the row could not legally take ("an insert without its master, an update nulling it") were "refused before as well, by the security gate". The insert half is true and stays. The update half was wrong in two ways. The security gate never reads the incoming FK on an update. So before the conversion, that update was not refused at all. The sentence now names both seams by symbol anchor. It says the update was accepted before, and that its refusal now comes from the record validator's ADR-0113 check, which only `required: true` arms. - `.changeset/24187-docblock-mechanisms.md`: `'@objectstack/spec': patch`, prose only, with `Clause-②: no`. No key, schema, export, accepted value, `guidance` string or message text changes. All 27 changed lines in `packages/spec` are ` *` comment lines (see the mechanical check under Verification). ## Item 1: what the pin reads `.objectui-sha` = `5e15928b4631a9dfd0d9bdd7282d1b746cdbaa68`. I read every file below with `git show PIN:PATH` from the local objectui object store. The objectui tree was not checked out or edited. `packages/fields/src/resolveActionParams.ts` at the pin: - `:538` declares `export function resolveActionParam(`, singular, so the docblock's name is right. `resolveActionParams` (plural, `:873`) is the list wrapper. - `:565` is `const authoredOptions = resolveOptionLabels(param.options, ctx.locale);`. - `:574` (the inline branch, no `param.field`) and `:634` (field-backed, but the field is not in the metadata) both read `options: authoredOptions,`. - `resolveOptionLabels` (`:246`) returns the authored array itself when `everyLabelResolved(options)` holds, that is, when every `label` is already a string. This is an identity fast path. Its comment says objectui `fbc23e094`'s `toBe` pin depends on it. Otherwise it maps the list. An entry with a string `label` comes back as it is. An entry whose `label` is an inline per-locale map is re-spread as `{ ...option, label: resolveInlineI18nLabel(option.label, locale) ?? option.value }`. So `visibleWhen`, and every other key, survives on both paths. Only a `label` written as a map is resolved. That is the bullet's point, so the bullet keeps the word VERBATIM, and its parenthesis now says exactly what happens to `label`. The map path can be reached from spec-valid metadata, because the spec's option `label` is `I18nLabelSchema` (the option `strictObject` in `action.zod.ts`). I re-read the bullet's other links at the same pin: - `packages/app-shell/src/views/ActionParamDialog.tsx:536` re-spreads each option to localise `label`. - `packages/app-shell/src/utils/paramToField.ts:102` passes `options: param.options` on. - `SelectField`, `MultiSelectField`, `RadioField` and `CheckboxesField` each reference `useCascadingOptions`. - `resolveCascadingOptions` is exported from `packages/core/src/evaluator/optionRules.ts:217`. `resolveActionParams.ts`, `ActionParamDialog.tsx` and `paramToField.ts` are byte-identical between this pin and the previous pin `f8267df93aba`, which the docblock's next paragraph names. `git diff --stat` between the two pins over those three paths prints nothing. So that paragraph's `:650`-`:651` and `:515` readings still hold. ## Item 2: the two seams, read on this branch's base `93b4acb57` - **The security gate:** `packages/plugins/plugin-security/src/security-plugin.ts#assertControlledByParentWrite`. - On `operation === 'insert'` it takes the master id from the incoming body, `opCtx.data[rel.fk]`. - On any other single-id write it reads the stored row as system (`readRowById(object, targetId, { isSystem: true })`) and takes `row[rel.fk]`. It never reads the incoming body's FK there. - A null master id throws `MasterReferenceMissingError` (422). The one exception is an insert where `rel.omissionRefusedByValidation` holds (`master_detail` + `required`, and neither `readonly` nor `system`). There the gate stands down and leaves the refusal to the validator. - **The record validator:** `packages/objectql/src/validation/record-validator.ts#validateRecordInScope`, which the exported `validateRecord` calls. - Its update branch walks only the keys the caller supplied. - Its check commented "ADR-0113 non-regression: a PATCH may not null OUT a required field" is `def.required && isEmptyForRequired(def, value) && def.type !== 'autonumber'`. It pushes a `required` error with message key `required_cleared`. - On a field without `required`, the check does not fire. "Before" in the docblock means the runtime before protocol 18. Then, a row with `required` omitted derived its master through the second tier. I re-read both seams at `76815b901^`, the parent of the #23179 merge that retired that tier. All four readings are the same there: - `masterId = data … [rel.fk]` on the insert leg; - `masterId = row[rel.fk]` otherwise; - the stand-down predicate `def?.type === 'master_detail' && !!def?.required && !def?.readonly && !def?.system`; - the same `def.required && isEmptyForRequired(…)` update check. So before the conversion: - **An insert without the master:** the stand-down predicate is false for a non-required master, so the gate threw. The security gate refused it, as the docblock says. - **An update nulling the master:** the gate read the stored FK, which was not null, and passed. The validator's check was not armed. The write was accepted. This matches contract review `6142098559` on PR #23179 (items 5 and A). I read the card's summary, "refused by the record validator's ADR-0113 check, which `required: true` arms", in the same sense: the refusal exists only once the conversion writes `required: true`. So the new sentence does not say the update "was refused before". It says: - the update was accepted before; - it left a detail row with a null FK, which the read filter `masterFK IN (accessible master ids)` never matches; - it is now refused by the validator, because `required: true` arms that check. That is the same refusal the builder's force gives an authored object. So the paragraph's "Lossless" claim still holds, as the contract review judged. The filter is spelled the way `src/migrations/registry.ts` and the lint rule already spell it. ## Changeset `@objectstack/spec`'s `files` array ships `src/**/*.zod.ts`, so `src/ui/action.zod.ts` goes into the tarball as written. After the build, the new bullet is also in the `dist` bundles: 28 `dist` files carry `options: authoredOptions`, and 0 carry `options: param.options`. `src/conversions/registry.ts` is not in `files`, and its new text reaches no `dist` file: 0 files carry `The update nulling it was not`. So the changeset describes item 1 only. It is a `patch` with `Clause-②: no`, following PR #24072. ## Verification All readings below are on the final head `c239951c2` (the merge of `main` at `1e001c7df`) unless marked otherwise. Build and test ran through `scripts/pm/os-verify-lock.sh`, and every exit code was captured before any pipe. - `pnpm --filter @objectstack/spec build && pnpm --filter @objectstack/spec check:generated`: lock verdict `command-exit 0`. The output was `All 14 generated artifacts are up to date`. The comment-only edit regenerates nothing, and no artefact was touched. - `pnpm --filter @objectstack/spec exec vitest run --project local --maxWorkers=2`: `Test Files 694 passed (694)`, `Tests 21027 passed | 1 todo (21028)`. On the pre-merge head `fe8a88886` it was 693 files and 21002 tests, all passing. - `pnpm --filter @objectstack/spec typecheck`: exit 0, ending `check:test-typecheck: OK`. - `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` derived 83 commands from the 3 changed paths, against merge base `1e001c7df`. 82 exit 0. `--ran` reconciliation: `83 derived, 82 run, 1 NOT-MEASURED, 0 UNRUN`. - `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` are green. - **NOT MEASURED: `check:dual-build-cjs-loads`** (exit 3, `PREREQUISITE NOT MET`). It reads the built output of every workspace package, and 92 had no `dist`. I did not run a whole-repo build locally; that is a declared narrowing. CI's `Lint & Repo Gates` runs this gate. - On the pre-merge head, three more commands exited 3 at first. Each was re-run after its prerequisite was met: - `check-plugin-teardown-shape.mjs --self-test` needed a pinned commit missing from the shallow clone (see Deviations); - `check:doc-formula-expressions` and `check:lean-entry-closure` needed `@objectstack/formula`, `@objectstack/lint` and `@objectstack/objectql` built. On the final head, all three exit 0 in the first pass, after those three packages were rebuilt on the merged tree. - **The symbol-anchor gate judges both new anchors** (a one-off reverse check on `fe8a88886`; the merge did not touch `registry.ts`). - I misspelled each anchor's symbol in turn, through `scripts/ablation-replace.mjs`. Each time the gate went red with exit 1: `[unresolved-symbol] packages/spec/src/conversions/registry.ts:14475` for `#validateRecordInScope`, and `:14467` for `#assertControlledByParentWrite`. - Both restores are proven: the blob equals HEAD's (`5dacc0aa3dc2`), `git diff HEAD` is empty, and `git status` is clean. - No test file was added or kept. - Comment-only check: `git diff -U0 origin/main...HEAD -- packages/spec` has 27 changed lines. None starts with anything other than ` *`. A control-byte scan of the three changed files finds nothing. - Local-only family `node scripts/check-dev-prereqs.mjs`: NOT MEASURED. It exits 1 with "The workspace is not built" (56 of 70 packages have no `dist`), so it never reached the spec-dist freshness check. Spec's own `dist` freshness is covered by `check:generated`'s declaration stamp match on this head. - No ablation: the diff changes no tested behaviour. - Not run locally, left to CI: `test:repo` (`Test Core`), `pnpm lint`, the type-check lanes, and the families `dispatch-gates` lists outside its runnable set. ## Acceptance notes - `packages/spec/src/data/object.zod.ts`, in the `forceCbpMasterDetailRequired` docblock: the "Why" paragraph says "Today only the security gate (`assertControlledByParentWrite`) closes that shape". Since protocol 18, the parse also refuses that shape (`refuseControlledByParentWithoutOneMaster`). The same docblock says so two paragraphs later, so a reader is not misled. It is present-tense drift, and outside this card's file surface. Carrier: none. - After the conversion, an insert without the master is also refused by the record validator, not the gate. The gate stands down for a `required: true` master, which is the 2026-08-15 ruling behind `omissionRefusedByValidation`. The envelope is then `400 VALIDATION_FAILED` with `fields[]`, where it was the gate's `422 MISSING_REQUIRED_FIELD`. The docblock's sentence is about "before", so it stays true, and I did not widen it to describe the insert's current envelope. This is an observation, not a defect. Carrier: none. - Three other prose sites name `assertControlledByParentWrite`: `packages/lint/src/data-model-rules.ts`, `packages/lint/src/rule-explanations.ts` and that same `object.zod.ts` docblock. Each speaks of the insert leg only. None repeats the wrong update-half claim. ## Deviations - One `git fetch --depth=1 origin 621a487`. This adds one object to the shared store. `check-plugin-teardown-shape.mjs --self-test` refused with exit 3 because its pinned positive-control commit was missing from the shallow clone. After the fetch it exits 0. - `main` was merged once before this PR opened (`c239951c2`), as AGENTS.md section 10 asks. The two incoming commits (#24269, #24270) touch none of the three files here. Spec was rebuilt and re-verified on the merged head. - Labels: none written. --- _Generated by [Claude Code](https://claude.ai/code/session_019oFY6Hi35J7atvgVFnmoaK)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent d537a31 commit 8bfb17d

3 files changed

Lines changed: 36 additions & 5 deletions

File tree

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
'@objectstack/spec': patch
3+
---
4+
5+
Clause-②: no
6+
7+
The `ActionParam` `options` docblock in `src/ui/action.zod.ts` no longer quotes objectui's inline
8+
param branch as `options: param.options`. At the console pin (`.objectui-sha` `5e15928b4631`) that
9+
branch of `resolveActionParam` reads `options: authoredOptions`, where `authoredOptions` is
10+
`resolveOptionLabels(param.options, ctx.locale)`: the authored array itself when every `label` is
11+
already a string, and otherwise only the entries with an inline per-locale `label` re-spread with
12+
that label resolved. The docblock's point is unchanged: an inline param's options, `visibleWhen`
13+
included, reach the widget as authored. No key, schema, export, accepted value or message text
14+
changes.

‎packages/spec/src/conversions/registry.ts‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14461,9 +14461,21 @@ const pageAssignedProfilesRemoved: MetadataConversion = {
1446114461
* `master_detail` under this sharing model into `required: true`
1446214462
* (`forceCbpMasterDetailRequired`, `data/object.zod.ts`), so the converted row
1446314463
* is exactly the object the builder would have produced from the same source.
14464-
* The relation it resolves is the one the second tier resolved, and the write
14465-
* the row could not legally take (an insert without its master, an update
14466-
* nulling it) was refused before as well, by the security gate.
14464+
* The relation it resolves is the one the second tier resolved. Of the two
14465+
* writes the row could not legally take, the insert without its master was
14466+
* refused before as well, by the security gate: on an insert
14467+
* `packages/plugins/plugin-security/src/security-plugin.ts#assertControlledByParentWrite`
14468+
* reads the master FK from the incoming body. The update nulling it was not.
14469+
* On a by-id update that gate reads the STORED row's FK, never the incoming
14470+
* value, so the write was accepted and left a detail row with a null master
14471+
* FK, which the `controlled_by_parent` read filter
14472+
* (`masterFK IN (accessible master ids)`) never matches. The refusal for that
14473+
* update is the record validator's ADR-0113 check, a PATCH may not null out a
14474+
* required field (the update branch of
14475+
* `packages/objectql/src/validation/record-validator.ts#validateRecordInScope`),
14476+
* and only `required: true` arms it. So the converted row loses no write the
14477+
* contract allows: it gains the refusal the builder's force already gives an
14478+
* authored object.
1446714479
*
1446814480
* **Deliberately narrow — exactly one shape, nothing else.**
1446914481
* - An explicit `required: false` is NOT converted. The builder refuses it

‎packages/spec/src/ui/action.zod.ts‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -247,8 +247,13 @@ export const ActionParamSchema = lazySchema(() => strictObject(
247247
* guessed at here, and #5016 answered it **per key, on measurement**:
248248
*
249249
* - **`visibleWhen` — opened.** The reader is on this exact path and it works
250-
* today. An inline param's `options` are lowered VERBATIM (objectui
251-
* `resolveActionParam`'s inline branch does `options: param.options`;
250+
* today. An inline param's `options` are lowered VERBATIM (at the console
251+
* pin, `.objectui-sha` `5e15928b4631`, objectui `resolveActionParam`'s
252+
* inline branch does `options: authoredOptions`, and `authoredOptions` is
253+
* `resolveOptionLabels(param.options, ctx.locale)`, which returns the
254+
* authored array itself when every `label` is already a string and
255+
* otherwise re-spreads only the entries whose `label` is an inline
256+
* per-locale map, resolving that `label`;
252257
* `ActionParamDialog` re-spreads each entry to localise `label`;
253258
* `paramToField` passes the array straight into the widget's field
254259
* metadata), and `SelectField` / `MultiSelectField` / `RadioField` /

0 commit comments

Comments
 (0)