Merge remote-tracking branch 'origin/main' into claude/issue-12016-cli-command-id-coupling

Author: claude

.changeset/docs-root-meta-declared-pages.md

@@ -0,0 +1,35 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): the generated docs root sidebar lists categories from the same declared page list `meta.json` and the category index already agree on (#11482)
+
+`build-docs.ts` writes the docs tree from what should be one answer to "which
+categories/pages exist", but the ROOT `content/docs/references/meta.json` (§3
+— the sidebar's top-level category list) was still answering it a third way:
+
+- a category's own `meta.json` (§2) is built from the pages the run
+  **emitted**;
+- that category's `index.mdx` card grid (§2.5) reads the SAME declared list
+  (#11260) — no longer a second, independently-derived enumeration;
+- the root `meta.json` (§3), until now, filtered on `categoryZodFiles` — the
+  `.zod.ts` files found **on disk** — a third, independent enumeration.
+
+A category whose published pages all come from plain `.ts` files rather than
+`.zod.ts` ones (the `misc` catch-all class `security/misc` proves is real) has
+zero `.zod.ts` files while still publishing a page, a `meta.json` and an
+`index.mdx`. The old filter would drop such a category from the sidebar even
+though it is fully generated and routed everywhere else — a folder complete on
+disk and unreachable from the nav.
+
+**No category is in that state today** — all 14 have at least one `.zod.ts`
+file — so this was a latent defect with no live instance, and the regenerated
+root `meta.json` is byte-identical. The filter now reads `categoryMetaPages`,
+the same map §2.5 already reads, so all three files answer from one list
+instead of three that happen to agree today. The rule moved into
+`scripts/lib/root-meta.ts` (`rootCategoryDirs`), pinned directly with the
+all-`misc`-category shape that has no instance in the repo — the same move
+#11260 made for the category card grid, for the same reason: the defect's
+output is an ABSENT sidebar entry, which `check:docs` cannot see any more than
+it could see an absent card, and the edge that has no live instance cannot be
+pinned from emitted output at all.

.changeset/liveness-citation-key-mention.md

@@ -0,0 +1,50 @@
+---
+'@objectstack/spec': patch
+---
+
+liveness gate: a citation must name the property it is evidence for
+
+Two checks already bounded a `live` entry's citation, and both bounded it from the
+outside — the cited file must exist (#5623), and a cited line must be inside it
+(#11210). Between them sat a gap neither could see: a consumer that moves *within*
+the file it is cited to, or a citation written with no line at all, leaves the file
+present and every named line in range. The pointer is wrong and the gate is green.
+
+Measured over the whole ledger before anything was switched on: 403 (entry, cited
+local file) pairs, **11** where the cited file never mentions the property's own key,
+and **7 of those 11 were real rot** — repaired here:
+
+- `permission.objects.allowExport` — `annotateEffectiveApiOperations` moved to
+  `current-user-endpoints.ts`; the same repos-internal movement that had already
+  rotted `permission.systemPermissions` and `permission.tabPermissions`.
+- `object.tenancy.organizationField` — the resolver was promoted into
+  `@objectstack/metadata-core`; the cited `audit-writers.ts` says so itself, in the
+  re-export comment left behind.
+- `action.target` / `action.requiredPermissions` — the actions domain was extracted
+  out of `http-dispatcher.ts`, which retains 0 occurrences of either key.
+- `action.bodyShape` / `action.bodyExtra` — client-dispatched keys whose only
+  consumer has always been the renderer; the in-repo citation could not have been
+  right at any point. Now attributed to `objectui` with the commit pinned.
+- `field.requiredWhen` — cited its *sibling* `record-validator.ts`, which enforces the
+  static `required` contract; the CEL predicate is evaluated one file over in
+  `rule-validator.ts`. Both files exist, so nothing could see it.
+
+The remaining 4 are the `camelCase` → `snake_case` convention this platform mandates
+(Prime Directive #3): a property persisted as a column is read as `body_html`,
+`managed_by`, never as the authoring key. Three are handled **structurally** — the
+matcher folds the key across the naming convention rather than exempting them — and
+the match is word-bounded so a prefix cannot satisfy the key (`required` is not
+`requiredWhen`, which is precisely how that rot stayed hidden). The one residual is a
+compound *child*-key remap (`fromOverride.address` → `from_address`) that no fold of
+the parent key reaches, and it is a single explicit row in the shrink-only
+`scripts/liveness/key-mention.baseline.json`, which fails in **both** directions: a
+row whose pair later anchors must be deleted.
+
+So the check ships red-capable at zero unexplained hits, which is the whole reason the
+census came first — `evidence.mts`'s header records what the alternative costs, when
+48 of 227 entries were flagged, every one was a false positive, and the single genuine
+rot inside that list sat unread.
+
+The check asks `evidence` only, never `producer`: a producer cites *who supplies a
+second input* (#4837), which is by definition a call site and need not name the key at
+all.

.changeset/maxlength-adr0087-ledger-entry.md

@@ -0,0 +1,7 @@
+---
+'@objectstack/spec': minor
+---
+
+The #11566 `maxLength` narrowing (shipped in 17.x: `z.number().int().min(1)`, refused outside `BOUNDED_STRING_FIELD_TYPES`) is now registered in the ADR-0087 migration ledger (#11950) — the enforcement PR deliberately deferred the entry because the registry file was serialized behind an in-flight change. Following the #8321 `scale`/`precision` template, the major-18 semantic entry carries both halves: the mechanical one (delete the key where it was misplaced — inert by construction outside the write-time validator's bounded-string branch) and the judgment one (a malformed value on a bounded-string type WAS consumed by the validator's raw comparison — `maxLength: 0` accepted only empty strings, a negative value refused every write — so only the author knows the bound they meant; the entry tells them to re-declare it). `objectstack migrate meta`, `spec-changes.json` and the upgrade guide surface the entry at the major boundary; no accept/reject behaviour changes in this release.
+
+<!-- adr-0087: registered field-max-length-malformed-or-misplaced-refused -->

.changeset/minlength-bounded-string-only.md

@@ -0,0 +1,9 @@
+---
+'@objectstack/spec': minor
+---
+
+`FieldSchema.minLength` tightens on both axes (#11949, maintainer ruling 2026-08-25) — `maxLength`'s twin defect pair (#11566), closed with the same template. Shape: the key is now `z.number().int().min(1)`, so `minLength: 0`, negative and non-integer declarations are refused at parse. The lower bound is 1 by ruling: "no minimum" is expressed by omitting the key, not by declaring a vacuous truth — `minLength: 0` can never fail, and a permanently-true declaration is exactly the noise an AI metadata author mass-produces, so it is refused loudly at authoring time. Applicability: the key sat on the base schema and was authorable on every field type; it is now refused on any type that does not store a bounded string, and accepted on exactly the `BOUNDED_STRING_FIELD_TYPES` set — `text`, `textarea`, `email`, `url`, `phone`, `password`, `markdown`, `html`, `richtext`, `code`, `signature`, `qrcode` (twelve members since #11875) — the same set `maxLength` converged on.
+
+What newly gets rejected: `minLength: 0` / negative / non-integer on any type, and `minLength` with any value on every non-bounded-string type (`boolean`, `number`, `date`, `select`, `lookup`, `autonumber`, `formula`, `json`, `secret`, …). Both rejections are prescriptive — the message names the legal shape, the legal type set, and the fix. The two authoring forms converge on the same set (`field.form.ts` previously showed the key for three types; `object.form.ts` for nine). Already-legal declarations (a positive-integer `minLength` on a bounded-string type) round-trip byte-identically, and absence stays absence — no default materializes.
+
+<!-- adr-0087: registered field-min-length-malformed-or-misplaced-refused -->

.changeset/object-editmode-declared.md

@@ -0,0 +1,27 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): declare `editMode?: 'modal' | 'page'` on the object document (#11408)
+
+Accept-set **widening** — no existing document changes meaning and nothing is
+removed. Maintainer ruling 2026-08-24 (declare, the #10144 declare-or-rule-out
+family): objectui's shipped runtime reads `objectDef.editMode` (record-edit
+routing: modal form vs a dedicated `/record/:id/edit` route) and its CHANGELOG
+announces the key to authors, while the spec's strict parse rejected it with
+`unrecognized_keys` — so an author following objectui's documentation was
+refused by every spec-validating path and the key only worked through data
+sources that skip validation.
+
+The object document now declares it beside the other display hints
+(`nameField`, `highlightFields`, `stageField`): an optional cross-renderer
+edit-interaction intent — `'modal'` opens the edit form as a dialog over the
+current view, `'page'` navigates to a dedicated full-page edit route, absent
+lets the renderer pick its own default (objectui defaults to modal). Values
+outside the enum are rejected as a located value error at `editMode`.
+
+Consumer-side follow-up (not in this change): objectui retires its
+`ObjectSchemaClientExtensions.editMode` client-extension member and lets the
+spec derivation carry the key — its pinned rejection tests flip by design.
+That retirement is **release-gated** on the `@objectstack/spec` release
+containing this change (per the recorded ruling), not merely on this merge.

.github/workflows/ci.yml

@@ -556,6 +556,13 @@ jobs:
             echo "No packages on this shard — nothing to test."
             exit 0
           fi
+          # Bound vitest's INNER worker pool (#11958). A no-op on a runner with
+          # <= 5 cores (it only ever LOWERS vitest's own `cores - 1` default);
+          # it exists so a larger runner cannot multiply turbo's outer
+          # --concurrency by a host-sized inner pool. Empty on failure, which is
+          # vitest's own "use the default" signal. Needs turbo.json's
+          # globalPassThroughEnv entry or turbo strips it — see the script header.
+          export VITEST_MAX_WORKERS="$(node scripts/vitest-worker-cap.mjs)"
           FILTERS=$(sed 's/^/--filter=/' "$RUNNER_TEMP/shard-packages.txt" | tr '\n' ' ')
           mkdir -p "$RUNNER_TEMP/stall-reports"
           node scripts/run-with-stall-guard.mjs --log "$RUNNER_TEMP/test-core.log" --stall-minutes 10 \
@@ -1129,6 +1136,13 @@ jobs:
         env:
           NODE_OPTIONS: --report-on-signal --report-signal=SIGUSR2 --report-directory=${{ runner.temp }}/stall-reports
         run: |
+          # Bound vitest's INNER worker pool (#11958). A no-op on a runner with
+          # <= 5 cores (it only ever LOWERS vitest's own `cores - 1` default);
+          # it exists so a larger runner cannot multiply turbo's outer
+          # --concurrency by a host-sized inner pool. Empty on failure, which is
+          # vitest's own "use the default" signal. Needs turbo.json's
+          # globalPassThroughEnv entry or turbo strips it — see the script header.
+          export VITEST_MAX_WORKERS="$(node scripts/vitest-worker-cap.mjs)"
           mkdir -p "$RUNNER_TEMP/stall-reports"
           node scripts/run-with-stall-guard.mjs --log "$RUNNER_TEMP/dogfood.log" --stall-minutes 10 \
             --report-dir "$RUNNER_TEMP/stall-reports" -- \

.github/workflows/docs-drift-check.yml

@@ -259,7 +259,47 @@ jobs:
             if (crossCutting.length) limits.push(`**${crossCutting.length}** cross-cutting symbol(s) contributed no route anchor: \`${crossCutting.join('`, `')}\``);
             if (overbroad.length) limits.push(`**${overbroad.length}** anchor(s) matched too much of the corpus to be a work list: \`${overbroad.join('`, `')}\``);
             if (weak.length) limits.push(`**${weak.length}** name(s) were too generic to anchor anything (single lowercase words)`);
-            if (bridge && bridge.measured && bridge.unreachable > 0) limits.push(`the SDK route bridge reached **${bridge.reachable}** of **${bridge.clientRows}** client-bound route-ledger rows — the other **${bridge.unreachable}** have no registrar \`path:\` tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run: \`node scripts/docs-audit/affected-docs.mjs --bridge-coverage\``);
+            // ── WHY THOSE ROWS ARE UNREACHABLE, NOT JUST HOW MANY (#11867) ────────
+            //
+            // The line above used to end at the count, and a count is one population.
+            // The census says there are three, and the difference is the whole reason
+            // the split exists: the auth ledger's `56 of 56` and the rest ledger's
+            // `46 of 87` print identically and are NOT the same finding — the first has
+            // no in-repo registration site at all, so the discovery widening the second
+            // one wants moves it by zero rows. That conflation already aimed one card
+            // (#11178) at widening a recognizer that was never the constraint, and this
+            // comment is the surface where a human meets the number.
+            //
+            // ⛔ SAME NAMES, ONE DERIVATION — the rule stated three lines up for the
+            // `anchorless` pair, and it binds here for the same reason. `bridge.causes`
+            // is a PARTITION of `bridge.unreachable`, computed ONCE inside
+            // `bridgeCoverageFrom` and published whole; the parts are READ off the same
+            // object as the total and never recomputed here. Re-deriving them from
+            // `bridge.ledgers` would be a second derivation that agrees today, drifts
+            // silently tomorrow, and renders a breakdown that sums to something the
+            // headline beside it denies.
+            //
+            // And on numbers that do NOT partition that total, the split is WITHHELD and
+            // the run says the census is broken, rather than printing three figures
+            // beside a fourth they contradict. That state cannot arise from
+            // `bridgeCoverageFrom` — `affected-docs.mjs --self-test` pins the partition
+            // — which is what makes it a verdict here and not a fallback.
+            //
+            // `measured: false` keeps its honest arm: a run that supplied no ceiling
+            // reports that WHY was not measured. It says so in words rather than
+            // rendering three nulls or, worse, three zeroes — "nobody looked" is not
+            // "none found", the same distinction `computedOn.dirty`'s null arm draws.
+            const causes = (bridge && bridge.causes) || null;
+            let bridgeCauses = '';
+            if (causes && causes.measured === true) {
+              const parts = causes.remediable + causes.structural + causes.undecided;
+              bridgeCauses = parts === bridge.unreachable
+                ? ` Of those **${bridge.unreachable}**: **${causes.remediable}** are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); **${causes.structural}** are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; **${causes.undecided}** are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here).`
+                : ` ⛔ Its cause census is BROKEN — **${causes.remediable}** + **${causes.structural}** + **${causes.undecided}** is not the **${bridge.unreachable}** it claims to break down, so the split is withheld.`;
+            } else if (causes && causes.measured === false) {
+              bridgeCauses = ` ⚠️ Cause NOT measured on this run: ${causes.reason}. No cause may be read into the count above — "nobody looked" is not "none found".`;
+            }
+            if (bridge && bridge.measured && bridge.unreachable > 0) limits.push(`the SDK route bridge reached **${bridge.reachable}** of **${bridge.clientRows}** client-bound route-ledger rows — the other **${bridge.unreachable}** have no registrar \`path:\` tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run.${bridgeCauses} The rows themselves: \`node scripts/docs-audit/affected-docs.mjs --bridge-coverage\``);
             // ── THE RULE-CARRYING PAGE AN EMITTER DIFF CANNOT REACH (#11434) ──────
             //
             // Every line above is a REPORT about this run: a count this run produced, a

.github/workflows/rerun-safety-nightly.yml

@@ -89,6 +89,13 @@ jobs:
       # frozen while healthy. The guard refuses a turbo run without it.
       - name: Test suite — pass 1
         run: |
+          # Bound vitest's INNER worker pool (#11958). A no-op on a runner with
+          # <= 5 cores (it only ever LOWERS vitest's own `cores - 1` default);
+          # it exists so a larger runner cannot multiply turbo's outer
+          # --concurrency by a host-sized inner pool. Empty on failure, which is
+          # vitest's own "use the default" signal. Needs turbo.json's
+          # globalPassThroughEnv entry or turbo strips it — see the script header.
+          export VITEST_MAX_WORKERS="$(node scripts/vitest-worker-cap.mjs)"
           node scripts/run-with-stall-guard.mjs --log "$RUNNER_TEMP/rerun-pass1.log" --stall-minutes 15 -- \
             pnpm turbo run test --concurrency=4 --force --log-order=stream
 
@@ -112,6 +119,13 @@ jobs:
       # there. Keep the two verdicts apart.
       - name: Test suite — pass 2 (same working tree)
         run: |
+          # Bound vitest's INNER worker pool (#11958). A no-op on a runner with
+          # <= 5 cores (it only ever LOWERS vitest's own `cores - 1` default);
+          # it exists so a larger runner cannot multiply turbo's outer
+          # --concurrency by a host-sized inner pool. Empty on failure, which is
+          # vitest's own "use the default" signal. Needs turbo.json's
+          # globalPassThroughEnv entry or turbo strips it — see the script header.
+          export VITEST_MAX_WORKERS="$(node scripts/vitest-worker-cap.mjs)"
           status=0
           node scripts/run-with-stall-guard.mjs --log "$RUNNER_TEMP/rerun-pass2.log" --stall-minutes 15 -- \
             pnpm turbo run test --concurrency=4 --force --log-order=stream || status=$?