fix(cli): the strict config refusal now carries the rule it enforces — a named export of objectstack.config.ts IS a top-level stack key

[os-support-ai]

Fixes #18171

Clause-②: no — this PR puts no new key on a published payload. It keeps the strict config parse exactly as it is and only documents the existing constraint and improves the diagnostic; no input the build refuses today becomes acceptable. Declared by the dispatching seat in claim 5694749953.

Branch B as ruled in claim 5694749953: the strict parse stays, the constraint becomes discoverable. Branch A (read only the default export) is not taken, and nothing here drifts toward it — the acceptance set is byte-for-byte what it was.

The landing point, corrected

The dispatch pointed at packages/cli/src/utils/config.ts "docblock around line 261". That docblock belongs to authoredSourcePlugin (the os migrate meta shim) and is not where the module's exports are collected. The real merge is in loadConfig() itself:

const merged: any = { ...baseConfig };
for (const key of Object.keys(mod)) {
  if (key === 'default' || key in merged) continue;
  merged[key] = (mod as any)[key];
}

The config file is therefore loaded as a module: the default export is the base, and every named export is merged onto it as a top-level stack key, under its own name. That merge is deliberate and load-bearing — onEnable and functions are declared stack keys an app authors as named exports, and unwrapping mod.default alone dropped them.

The card's finding reproduces here; its wording does not

Measured on this tree (not on the hotcrm pin the card read), through the real loadConfig() and the real ObjectStackDefinitionSchema:

the named export	merged config	strict parse
ProbeNamedExport — not a declared key	["manifest","ProbeNamedExport"]	fails, unrecognized_keys, key named
objects, default carries no objects	["manifest","objects"]	passes — the export is honoured
objects, default already has objects	["manifest","objects"], value []	passes — the export is dropped silently

So the diagnostic gap is real and the card is right to file it, but "the config file may carry no named export" / "exactly one export, the default stack" is too strict to document as the rule: rows 2 and 3 do not fail. What the code enforces is

a named export is legal only when its name is a key ObjectStackDefinitionSchema declares

and that is what this PR writes down. Documenting the card's sentence verbatim would have described a constraint the build does not have, and would have outlawed onEnable and functions.

Row 3 is a second, separate defect — a metadata-authoring trap, not a documentation gap — and it is out of scope here: closing it changes what the build accepts, which is branch-A territory and owes a pm:retriage. It is reported to the dispatching seat to file. See Acceptance notes.

Before / after

Both captured end-to-end through os validate on the same project, on this branch. The "before" leg is the same binary with namedExportRejectionHints ablated to return nothing (restore verified by blob hash).

Before — the refusal names the key, and nothing tells the author why a key they never wrote is being judged:

  ✗ Validation failed
  _root:
    ✗
      unrecognized_keys: Unrecognized key(s) on this stack definition: `ProbeNamedExport`. Until this surface was closed …
  1 validation error(s) total

After — same refusal, same exit code (1), same --json payload, with the rule and the fix added on the text face only:

  ✗ Validation failed
  _root:
    ✗
      unrecognized_keys: Unrecognized key(s) on this stack definition: `ProbeNamedExport`. Until this surface was closed …
  1 validation error(s) total
  `ProbeNamedExport` is a NAMED EXPORT of your config file, it is not a key written inside defineStack().
  The config file is loaded as a MODULE: every named export is merged onto the default-exported
  stack as a top-level key, so a named export is legal only when its name is a key the stack
  schema declares. A helper exported beside the stack is read as a stack key, and refused above.
  Fix: move it into a sibling module (e.g. objectstack.composition.ts) and import it here.

What changed

• packages/cli/src/utils/config.ts — loadConfig()'s header now states the rule where the rule is created; LoadedConfig gained a namedExports reading (the provenance the explanation needs, and nothing else); new namedExportRejectionHints() turns a root unrecognized_keys issue into the rule and the fix, for exactly the keys the merge put there.
• packages/cli/src/commands/compile.ts and validate.ts — both authoring doors print it, so os build and os validate do not disagree about what an author is told. ⛔ Text face only: the --json branches are untouched, so no field is added to a published envelope.
• packages/cli/src/commands/init.ts — all three os init templates scaffold the constraint as a comment at the head of the config they write. No ADR id, no issue number, no repo-relative path — init-template-comments-self-contained sweeps that population and is green.
• content/docs/getting-started/your-first-project.mdx and content/docs/deployment/cli.mdx — the rule on the config-authoring surface and in the CLI configuration reference, with all three rows of the table above named.
• .changeset/18171-config-module-named-export-rule.md — @objectstack/cli patch.

The pin, and that it can fail

packages/cli/src/utils/config-named-export-rule.test.ts, 5 cases. The refusal comes first, because it is the property the ruling protects: the helper export still reaches the strict parse and is still refused by name, with the unrecognized_keys code and the key echoed back. Then the hint's rule and fix; then the two things it must NOT claim (a key the author really did write inside defineStack(), and a nested unrecognised key); then the two-door parity.

Reverse verification, from the committed fix, mutation proved on disk, restored with git checkout HEAD -- THE_PATH:

mutation   `if (offenders.length === 0)` -> `if (offenders.length >= 0)`  (the hint returns nothing)
on disk    grep -c 'offenders.length === 0'  1 -> 0        blob d0043a8f -> a6911cd6
result     Tests  1 failed | 4 passed (5)   — "the hint carries the RULE and the FIX"
restore    git checkout HEAD -- …; hash back to d0043a8f; `git diff HEAD` empty
result     Tests  5 passed (5)

Direction is worth stating plainly: the two negative cases assert [] and therefore stay green under this mutation. Only the positive case is load-bearing against it — which is exactly why the file does not consist of negative assertions.

Verification

Tree measured: f6561b2b0 (working tree identical to that commit throughout; git status clean).

run	exit
93 gates derived by scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack	92 × 0
pnpm check:cross-package-test-inputs	1 — pre-existing, not this PR
pnpm lint (whole repo, re-run at f6561b2b0)	0
pnpm --filter @objectstack/cli typecheck	0
pnpm --filter @objectstack/cli exec vitest run --project unit	0 — 209 files, 2980 tests
pnpm build (whole repo)	0

check:cross-package-test-inputs names packages/cli/test/init-created-files-summary.e2e.test.ts descending packages/spec/dist/ — a file this diff does not touch. Filed as #18353 / #18348; all three sibling cards this round hit it independently.

packages/cli's integration tier is declared to CI: this diff touches no integration-tier file, no bin/ entry and no driver/kernel boot path, so only the unit project was owed locally.

Two gates were red because of this PR and are now green: check-reference-carrier-shape (exit 3) and check:comment-mask-corpus (exit 1) both refused to parse init.ts, because the first draft of the scaffold comment used backticks inside the template literal that renders it and closed the literal. Fixed in f6561b2b0.

Acceptance notes

Filed via the report on #18171 (class c — a metadata-authoring trap; dev does not open cards):

• A named export whose name the default export already carries is dropped silently and the build exits 0. if (key in merged) continue in loadConfig(). Measured above: export const objects = [{…}] beside defineStack({ manifest, objects: [] }) leaves config.objects === [], the authored row never reaches the artifact, and nothing is printed at any level. Dedupe words: config named export shadowed, loadConfig key in merged, silently dropped stack key, objectstack.config module merge.

Noted, not filed:

• os create (packages/cli/src/commands/create.ts) and create-objectstack also scaffold an objectstack.config.ts and did not get the comment. The dispatch's declared file surface names the os init template only, so widening it is the dispatching seat's call rather than this PR's. Carrier: whoever takes the follow-up — it lands in the same init-template-comments-self-contained population this PR already passes, so it needs no new verification surface.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli, touching 7 documentable anchor(s).

21 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 588475c30f98ffb5ee603382d585e41cd9a59753.

⛔ 7 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 1 anchor(s) matched too much of the corpus to be a work list: os validate (command, 49 pages)
• 2 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 100 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 24 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 588475c30f98ffb5ee603382d585e41cd9a59753 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 58f6c222f62f21cb6aed5aed19372a0e808d5c54 — the merge of head f6561b2b0e183878301311993e08de400b05a656 into base 588475c30f98ffb5ee603382d585e41cd9a59753, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 58f6c222f62f21cb6aed5aed19372a0e808d5c54 && git checkout 58f6c222f62f21cb6aed5aed19372a0e808d5c54
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 588475c30f98ffb5ee603382d585e41cd9a59753 f6561b2b0e183878301311993e08de400b05a656 && git checkout -B drift-repro 588475c30f98ffb5ee603382d585e41cd9a59753 && git merge --no-ff f6561b2b0e183878301311993e08de400b05a656

node scripts/docs-audit/affected-docs.mjs --json 588475c30f98ffb5ee603382d585e41cd9a59753

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 588475c30f98ffb5ee603382d585e41cd9a59753 → pass the list as
args.docs, on the commit named under Which tree this was computed on.