feat(cli,docs): the build path reports undeclared keys too, and the gate table says so (#3786)

Follow-up to the lint's first commit, closing a gap the docs-drift check made
visible: `validating-metadata.mdx` is a catalog of what `os validate`/`os build`
report, and the new check was not in it. Writing the row surfaced the real
omission underneath — the check ran in `validate.ts` only.

`defineStack` already covers any config authored through it, whichever command
loads it. What it does not cover is a config that SKIPS it — a plain object
default-export, or `strict: false` — and on that path `os build` would emit an
artifact with the key silently gone. `compile.ts` now runs the same pre-parse
report, at the same seam as the ADR-0089 visibility rule beside it. Verified:
a plain-object config with `pii` + `indexed` now warns on the build path.

Not a parity-test violation either way — `validate-build-gate-parity.test.ts`
enforces compile ⊆ validate, and validate already had it. This makes the two
agree in the direction the test cannot see.

Docs: a row in the two-entry-point table, and a §9 section showing what the
finding looks like and why a retired key deliberately gets no "did you mean".

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

Author: claude

.changeset/unknown-authoring-key-lint.md

@@ -42,13 +42,17 @@ in the protocol, so flipping them rejects metadata that parses today: a migratio
 event for every consumer, and one that deserves to be scheduled on evidence
 rather than guessed at. This produces that evidence and costs nobody a migration.
 
-Wired into the two layers that perform the discard, both **pre-parse** (the parse
-is what eats the key, so after it there is nothing left to report):
+Wired into every layer that performs the discard, all **pre-parse** (the parse is
+what eats the key, so after it there is nothing left to report):
 
 - **`defineStack`** — warns on the console, once per distinct path, in strict
   *and* non-strict mode, since the key is dropped either way.
 - **`os validate`** — a non-blocking warning, and included in `--json` output
   rather than computed and discarded.
+- **`os build` / `os compile`** — the same non-blocking warning. `defineStack`
+  already covers configs authored through it; this catches the ones that skip it
+  (a plain object default-export, `strict: false`), which would otherwise emit an
+  artifact with the key quietly gone.
 
 Verified against the three first-party example apps (`app-todo`, `app-crm`,
 `app-showcase`): all clean, no false positives.

content/docs/deployment/validating-metadata.mdx

@@ -209,6 +209,41 @@ literal (it comes from React state or a variable), a usage carrying a `{...sprea
 a chart given static `data` (its columns are the author's own), and objects
 another package defines.
 
+### 9. Object and field keys the schema never declared
+
+`ObjectSchema` and `FieldSchema` are deliberately not strict, so a key they do
+not declare **parses clean and is dropped** on the way to storage. Nothing fails;
+the setting simply is not there.
+
+```ts
+fields: {
+  ssn: { label: 'SSN', type: 'text', pii: true, indexed: true },
+  //                                  ↑ neither is a FieldSchema key → both dropped
+}
+```
+
+Each one is reported with what to do about it — a rename where the concept
+survives under another key, or the reason it was retired where it does not:
+
+```
+objects.employee.fields.ssn.pii: 'pii' is not a declared field key, so its value
+  is dropped at load — the `dataQuality` governance family was pruned in 2026-06
+  as dead in both layers — it enforced nothing.
+objects.employee.fields.ssn.indexed: 'indexed' is not a declared field key, so its
+  value is dropped at load — never a FieldSchema key; a field-level index flag
+  built no index (#2377). Declare the index in the object's `indexes[]`.
+```
+
+Plain typos get a "did you mean" (`requred` → `required`); a retired key does
+not, because the nearest declared key by spelling would be noise rather than
+advice.
+
+This is **advisory** — the stack still loads. Strict rejection is where these
+schemas are headed (ADR-0049 enforce-or-remove), but they are the two
+most-authored surfaces in the protocol, so the tightening is scheduled on what
+this check finds rather than assumed. `defineStack` reports the same findings at
+config-load time, so an author sees them without running the CLI at all.
+
 ## The one gate, two entry points
 
 `os validate` and `os build` (alias of `os compile`) run the **same** validator:
@@ -228,6 +263,7 @@ another package defines.
 | View references — form targets, view-key collisions (#2554) | ✓ | ✓ |
 | Flow authoring anti-patterns (#1874) | ✓ | ✓ |
 | Liveness author-warnings | ✓ | ✓ |
+| Undeclared object/field keys (#3786) | ✓ | ✓ |
 | Emits `dist/objectstack.json` | — | ✓ |
 
 So `os validate` is the fast inner-loop check (no artifact); `os build` is what

packages/cli/src/commands/compile.ts

@@ -5,7 +5,13 @@ import path from 'path';
 import fs from 'fs';
 import chalk from 'chalk';
 import { ZodError } from 'zod';
-import { ObjectStackDefinitionSchema, normalizeStackInput, type ConversionNotice } from '@objectstack/spec';
+import {
+  ObjectStackDefinitionSchema,
+  normalizeStackInput,
+  lintUnknownAuthoringKeys,
+  formatUnknownAuthoringKey,
+  type ConversionNotice,
+} from '@objectstack/spec';
 import { loadConfig } from '../utils/config.js';
 import { lowerCallables } from '../utils/lower-callables.js';
 import { validateStackExpressions } from '@objectstack/lint';
@@ -251,6 +257,20 @@ export default class Compile extends Command {
         }
       }
 
+      // 3b-ter. [#3786] Keys `ObjectSchema` / `FieldSchema` do not declare, and
+      //     so drop silently on the way to storage. PRE-parse for the same
+      //     reason as the rule above. `defineStack` already warns for configs
+      //     authored 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 = lintUnknownAuthoringKeys(normalized as Record<string, unknown>);
+      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)}`);
+        }
+      }
+
       // 3c. Widget-binding diagnostics (issues #1719/#1721) — semantic checks
       //     that need the widget's `dataset` reference resolved to its dataset
       //     and `dimensions`/`values` resolved to declared names. Errors are