Repository navigation
Commit 8bfb17d
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
- .changeset
- packages/spec/src
- conversions
- ui
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
14461 | 14461 | | |
14462 | 14462 | | |
14463 | 14463 | | |
14464 | | - | |
14465 | | - | |
14466 | | - | |
| 14464 | + | |
| 14465 | + | |
| 14466 | + | |
| 14467 | + | |
| 14468 | + | |
| 14469 | + | |
| 14470 | + | |
| 14471 | + | |
| 14472 | + | |
| 14473 | + | |
| 14474 | + | |
| 14475 | + | |
| 14476 | + | |
| 14477 | + | |
| 14478 | + | |
14467 | 14479 | | |
14468 | 14480 | | |
14469 | 14481 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
247 | 247 | | |
248 | 248 | | |
249 | 249 | | |
250 | | - | |
251 | | - | |
| 250 | + | |
| 251 | + | |
| 252 | + | |
| 253 | + | |
| 254 | + | |
| 255 | + | |
| 256 | + | |
252 | 257 | | |
253 | 258 | | |
254 | 259 | | |
| |||
0 commit comments