Merge origin/main (945ffbe) into claude/issue-11717-lead-key-allowlist

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015ahemw8RcTgqtxrj15PEZx

Author: claude

.changeset/build-json-undeclared-key-parity.md

@@ -0,0 +1,46 @@
+---
+'@objectstack/cli': patch
+---
+
+Carry the undeclared-authoring-key warnings in the `os build --json` payload,
+so its `warnings` list matches `os validate --json` on the same tree
+
+`os build --json` reported a strictly smaller `warnings` list than
+`os validate --json` did for the same stack, and the missing members were
+exactly the "your key was dropped at load" ones (#3786 / ADR-0087). A CI job
+gating on `os build --json` therefore could not see the class of warning that
+silently discards authored metadata — while the identical job gating on
+`os validate --json` did.
+
+Measured over one temp project at `origin/main` `4ceae8ab0`, three faces of one
+authored stack whose field carries an undeclared key nested in `visibleWhen`:
+
+```
+os build            ⚠ Undeclared authoring keys (1) — dropped at load (#3786)
+os validate --json  warnings: [ {rule record}, "…zzzUnknownKey…" ]
+os build   --json   warnings: [ {rule record} ]            ← the dropped list
+```
+
+`compile.ts` computed the findings and then formatted them **inside** the
+`if (… && !flags.json)` print block, which put them structurally out of reach
+of the payload: computed, then discarded, for the one audience `--json` exists
+to serve. `os validate --json` had this exact defect on its own face and fixed
+it by mapping the findings through `formatUnknownAuthoringKey` at the
+computation site; `os build` now does the same, so one list feeds both faces
+and they cannot report different sets.
+
+**No new key.** The findings land in the `warnings` key the payload already
+declared — its own comment has always said "the whole registry's advisory set,
+in the shape `os validate --json` reports" — carried as formatted strings
+beside the authoring-rule records, which is byte-for-byte the heterogeneous
+shape `os validate --json` already ships. Consumers reading `warnings` off
+either command now read one shape for one class of warning. The payload's
+top-level key set is unchanged and pinned as unchanged.
+
+This also makes an existing promise true. The truncation notice added in
+17.2.0 ends with "re-run with `--json` for the full list"; that pointer was
+honest about the authoring-rule advisories and would have been false about the
+undeclared-key list, which is why that change left the second list without a
+notice.
+
+Text output is unchanged.

.changeset/nine-parents-keep-details.md

@@ -0,0 +1,12 @@
+---
+'@objectstack/spec': minor
+'@objectstack/objectql': minor
+---
+
+`FieldSchema` now rejects an authored `deleteBehavior: 'set_null'` on a `master_detail` field at parse time (#9689). The engine has always resolved every value except `restrict` on that type to `cascade`, so the declaration asked for the child rows to be kept and got them deleted — silently, at the moment the parent went away. The rejection names the outcome and both legal re-declarations (`restrict` refuses the parent delete while children exist — no data loss; `cascade`, or omitting the key, accepts the cascade deliberately; a `lookup` is the type to use when children must survive the parent).
+
+Mechanism (the #7918 Option A shape, plus the 2026-08-24 idempotent-materialization ruling): the property-level `.default('set_null')` moved off `deleteBehavior` into a post-check `.overwrite()`, so the schema can tell an authored `set_null` from a defaulted one — and the `.overwrite()` never materializes a default the schema itself would refuse as authored. A bare `master_detail` now parses to output that OMITS `deleteBehavior` (previously the baked `set_null` was indistinguishable from an authored one by design, so parse output rejected itself on the mainline `ObjectSchema.create()` → `defineStack` re-parse — every app build with a bare `master_detail` failed). Built app artifacts stop carrying a value the schema itself refuses; the engine treats absent exactly as it treated the baked value (both cascade — measured, behavior unchanged). Every other field type keeps byte-identical output — non-reference types still carry the default at its shape position, and `set_null` on `lookup` stays legal. The inferred `Field` output type now declares `deleteBehavior` as optional (the same accepted cost as the currency `precision` relocation); at runtime a parsed field carries it on every type except `master_detail`, where absence is the honest spelling.
+
+There is deliberately no automatic conversion (`field-master-detail-set-null-refused` in the migration registry): only the author knows whether they meant `restrict` (keep-my-children, as a refusal) or `cascade`. Stored rows carrying the refused combination keep loading and serving — registry validation is a diagnostic, not a gate — and are refused on their next authoring-path save.
+
+`@objectstack/objectql`: the engine behavior is unchanged (an authored `set_null` on `master_detail` still cascades — the #9625 pin holds), but the coercion site now logs loudly (`error`, falling back to `warn`) when the combination reaches it via a raw registration or a pre-tightening stored row — the two populations parse-time rejection cannot catch.

content/docs/data-modeling/field-types.mdx

@@ -337,7 +337,7 @@ Parent-child relationship (cascading delete by default).
 |:---|:---|:---|:---|
 | `reference` | `string` | **required** | Target (master) object name |
 | `referenceFilters` | `string[]` | — | **Removed** (#2377, ADR-0049) — no longer a recognized field property. `FieldSchema` is a strict object, so an unknown key is **rejected with guidance**, not silently stripped (ADR-0078): the error echoes the offending key and prescribes the replacement. Use structured `lookupFilters` + `dependsOn` instead; see [Relationships](/docs/data-modeling/relationships) |
-| `deleteBehavior` | `'restrict' \| 'cascade' \| 'set_null'` | `'cascade'` | Behavior when parent is deleted. `restrict` is the only value that deviates: master-detail cascades on everything else, so an explicit `set_null` here is **not** honored — the child is deleted with the parent |
+| `deleteBehavior` | `'restrict' \| 'cascade'` | `'cascade'` | Behavior when parent is deleted. `restrict` refuses the parent delete while children exist; `cascade` (and omitting the key) deletes the children with the parent. An explicit `set_null` is a **parse-time rejection** on this type (#9689) — a detail row cannot outlive its master; use a `lookup` if children must survive the parent |
 | `inlineEdit` | `boolean \| 'grid' \| 'form'` | — | Edit child records inline on the parent create/edit form (`true` = auto-pick, `'grid'`, or `'form'`) |
 | `inlineColumns` | `array` | — | Optional explicit inline grid columns |
 | `inlineAmountField` | `string` | — | Numeric child field used for the inline running total |

content/docs/protocol/objectql/types.mdx

@@ -698,9 +698,13 @@ const opportunities = await engine.find('opportunity', {
 > been emptied.
 >
 > On `master_detail` the same reading applies from the other side: `restrict`
-> is the only value that deviates from `cascade`, so an explicit
-> `deleteBehavior: set_null` on a master-detail reference is *not* honored —
-> the child is cascaded away.
+> is the only value that deviates from `cascade`. An explicit
+> `deleteBehavior: set_null` on a master-detail reference is a **parse-time
+> rejection** (#9689) — a detail row cannot outlive its master, so the spec
+> refuses the declaration instead of silently cascading the children it asked
+> to keep. Metadata that bypasses the parse (a raw registration, or a row
+> stored before the tightening) still resolves to `cascade`, now with a loud
+> engine log at the coercion site.
 >
 > The refusal carries **two** messages, for two audiences. `error` is written for
 > the person who clicked delete: it is rendered in the caller's locale from the

packages/cli/src/commands/compile.ts

@@ -285,14 +285,26 @@ export default class Compile extends Command {
       //     through it; this covers the ones that skip it (a plain object
       //     default-export, `strict: false`) and would otherwise emit an
       //     artifact with the key quietly gone. Advisory, never fatal.
-      const unknownKeyFindings = [
+      //
+      //     [#11643] FORMATTED HERE, once, and consumed by BOTH faces — the
+      //     text block just below and the `--json` payload at the end of this
+      //     command. The findings used to be formatted inside that print
+      //     block, i.e. under `!flags.json`, which made them structurally
+      //     unreachable for the payload: computed, then discarded, for the one
+      //     audience `--json` exists to serve. `os validate --json` had this
+      //     exact defect and fixed it this exact way —
+      //     `.map(formatUnknownAuthoringKey)` at the computation site, beside
+      //     its own `normalized` — so hoisting the formatting rather than
+      //     restating it at the payload is what keeps the two faces from
+      //     reporting different sets. One list cannot drift from itself.
+      const unknownKeyWarnings = [
         ...lintUnknownStackKeys(normalized as Record<string, unknown>, ObjectStackDefinitionSchema),
         ...lintUnknownAuthoringKeys(normalized as Record<string, unknown>, ObjectStackDefinitionSchema),
-      ];
-      if (unknownKeyFindings.length > 0 && !flags.json) {
-        printWarning(`Undeclared authoring keys (${unknownKeyFindings.length}) — dropped at load (#3786)`);
-        for (const f of unknownKeyFindings.slice(0, 50)) {
-          console.log(`  • ${formatUnknownAuthoringKey(f)}`);
+      ].map(formatUnknownAuthoringKey);
+      if (unknownKeyWarnings.length > 0 && !flags.json) {
+        printWarning(`Undeclared authoring keys (${unknownKeyWarnings.length}) — dropped at load (#3786)`);
+        for (const w of unknownKeyWarnings.slice(0, 50)) {
+          console.log(`  • ${w}`);
         }
       }
 
@@ -464,15 +476,39 @@ export default class Compile extends Command {
           // The whole registry's advisory set, in the shape `os validate --json`
           // reports. This key used to carry the widget rule's warnings alone —
           // one gate out of the twenty-odd that raise them.
-          warnings: ruleAdvisories,
+          //
+          // [#11643] …and then, still, only the RULE advisories: the #3786
+          // undeclared-authoring-key findings were computed above and dropped,
+          // so a CI consumer reading `warnings` off this command saw a strictly
+          // smaller set than the same consumer reading it off
+          // `os validate --json` on the same tree — missing exactly the "your
+          // key was dropped at load" members. Two costs, both real: the machine
+          // faces of two commands disagreed about one class of warning, and
+          // #11529's truncation notice points the reader at `--json` "for the
+          // full list", which was true of one advisory list and false of the
+          // other.
+          //
+          // MIXED BY DESIGN, because that is what parity means here. This list
+          // now carries the rule advisories as RECORDS and the undeclared-key
+          // findings as formatted STRINGS — byte-for-byte the shape
+          // `os validate --json` has shipped since it fixed this on its own
+          // face (`warnings: [...ruleAdvisories, ...docWarnings,
+          // ...unknownKeyWarnings, …]`, likewise a heterogeneous list). The
+          // homogeneity this key used to have was not a contract; it was the
+          // symptom of the omission.
+          warnings: [...ruleAdvisories, ...unknownKeyWarnings],
           // [#10678] Body-extraction failures that made a callable fall back to
-          // the legacy .mjs bundle. A SEPARATE key on purpose: `warnings` above
-          // is author-time RULE advisories (`{where,message,rule,path,hint}`)
-          // and is the shape `os validate --json` shares — folding a different
-          // record shape (`{origin,reason}`) into it would break that contract
-          // for every consumer that reads one shape from either command. Empty
-          // array when every callable lowered cleanly, so a CI consumer can read
-          // the key unconditionally.
+          // the legacy .mjs bundle. A SEPARATE key on purpose, and the reason is
+          // parity too — the opposite way round from `unknownKeyWarnings` just
+          // above. `{origin,reason}` extraction records have NO counterpart in
+          // `os validate --json`: that command lowers no handlers, so there is
+          // no cross-command list for these to join, and folding a shape only
+          // ONE command can ever emit into the shared key would teach consumers
+          // a shape the other command never ships. The undeclared-key findings
+          // are the mirror case — validate already carries them, in `warnings`,
+          // so that is where build has to carry them too. Empty array when every
+          // callable lowered cleanly, so a CI consumer can read the key
+          // unconditionally.
           bodyExtractionWarnings: lowering.bodyExtractionWarnings,
           // Same key `os validate --json` uses, so a CI consumer reads one shape
           // from either command rather than learning two.