@metaobjectsdev/cli 1.0.13 → 1.1.0

package/src/commands/verify.ts

@@ -30,10 +30,12 @@ import { scanForRemovedProps, type RemovedPropFinding } from "../lib/removed-pro
 import { replayRemedy } from "../lib/replay-remedy.js";
 import { FileProvider, mustacheTagLine } from "../lib/file-provider.js";
 import { derivePayloadFieldTree } from "../lib/payload-field-tree.js";
-import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenCollection, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
+import { loadMemoryOptionsFrom, loadMetaobjectsConfig, RemovedNamingConfigError, resolveGenCollection, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
 import { collectionLoadOptions } from "../lib/collection-load-options.js";
 import { computeCodegenDrift } from "../lib/codegen-drift.js";
-import { computeDocsDrift } from "../lib/docs-drift.js";
+import { hasLegacyDocsBlock, legacyDocsConfigMessage, REMOVED_VERIFY_DOCS } from "../lib/docs-removed.js";
+import { buildAgentSchemaInput } from "../lib/agent-schema.js";
+import { sourceRootsOf } from "./gen.js";
 import {
   checkRequirements, summariseRequirements, scanRequirements, type Diagnostic,
 } from "../lib/requirement-check.js";
@@ -41,8 +43,9 @@ import { lintRequirements } from "../lib/requirement-lint.js";
 import { lintOverlays } from "../lib/overlay-lint.js";
 import { lintNodeNames } from "../lib/name-lint.js";
 import { lintDeprecatedReferences } from "../lib/deprecation-lint.js";
+import { lintDuplicateFields, lintReferenceFields } from "../lib/field-lint.js";
 import { FileSource } from "@metaobjectsdev/metadata/core";
-import { resolveD1Config, resolveMigrateConfig } from "../lib/config.js";
+import { resolveD1Config, resolveMigrateConfig, type ResolvedMigrateConfig } from "../lib/config.js";
 import {
   buildWranglerExecuteArgs,
   defaultWranglerRunner,
@@ -50,7 +53,7 @@ import {
   type WranglerRunner,
 } from "../lib/wrangler.js";
 import type { MetaobjectsGenConfig } from "@metaobjectsdev/codegen-ts";
-import { buildProjectionViews, resolveDocsConfig } from "@metaobjectsdev/codegen-ts";
+import { buildProjectionViews } from "@metaobjectsdev/codegen-ts";
 import { buildKyselyFromUrl, inferDialect, type Dialect } from "../lib/kysely.js";
 import { tokensToAllowOptions, describeChange } from "../lib/allow.js";
 import {
@@ -69,6 +72,7 @@ import {
   verifyReplay,
   introspect,
   diff,
+  withoutViewRecreates,
   readSnapshot,
   snapshotPath,
   type SchemaSnapshot,
@@ -80,6 +84,8 @@ import {
   type D1Binding,
   type D1Runner,
   type DriftResult,
+  postgresViewReplaceProbe,
+  withoutFlywayHistory,
 } from "@metaobjectsdev/migrate-ts";
 import {
   DEFAULT_METAOBJECTS_DIR,
@@ -95,6 +101,7 @@ import {
   TEMPLATE_SUBTYPE_PROMPT,
   TEMPLATE_SUBTYPE_OUTPUT,
   TEMPLATE_ATTR_PAYLOAD_REF,
+  refTarget,
   TEMPLATE_ATTR_TEXT_REF,
   TEMPLATE_ATTR_REQUIRED_SLOTS,
   TEMPLATE_ATTR_REQUIRED_TAGS,
@@ -105,6 +112,7 @@ import {
   TEMPLATE_ATTR_HTML_BODY_REF,
   TEMPLATE_ATTR_TEXT_BODY_REF,
   REQUIREMENT_STATUSES,
+  physicalNamingOf,
 } from "@metaobjectsdev/metadata";
 import { verify, ERR_REQUIRED_SLOT_UNUSED, ERR_PARTIAL_UNRESOLVED } from "@metaobjectsdev/render";
 import { describeLoadError, reportLoadError } from "../lib/load-error.js";
@@ -119,9 +127,11 @@ const ERR_UNKNOWN_ATTR = "ERR_UNKNOWN_ATTR";
 
 /**
  * A no-flags MigrateFlags, so `resolveMigrateConfig` yields exactly what `meta migrate`
- * would use with nothing passed on the command line — config value, else default.
+ * would use with nothing passed on the command line — config value, else default. The one
+ * migrate flag verify also takes, `--migration-format`, is laid over it per invocation, so
+ * the format resolves flag > config > default exactly as it does for `meta migrate`.
  *
- * verify consumes `outDir` (#292) and — for the replay gate ONLY — `dialect`. The #292
+ * verify consumes `outDir` (#292), `format` and — for the replay gate ONLY — `dialect`. The #292
  * restriction that reading anything else "would be reaching into migrate's decisions"
  * was written about the DRIFT gate, whose dialect comes from the live `--db` URL. The
  * replay gate has no `--db` at all, and the dialect a committed chain was EMITTED for
@@ -172,6 +182,15 @@ export async function verifyCommand(
     emitStructured({ error: msg, hint: "run `meta verify --help` for the accepted flags" }, fmt);
     return 2;
   }
+  // ADR-0034 Amendment 9: documentation is checked by `--codegen` with everything else the
+  // generator list declares. The old flag still parses, so it can say where it went. It says
+  // so once, as plain text on stderr, like every other removed command: a structured copy on
+  // stdout printed the same sentence a second time, escaped (`error: "\`meta verify ...`).
+  if (flags.docs) {
+    log.error(REMOVED_VERIFY_DOCS);
+    return 2;
+  }
+  const migrateFlags: MigrateFlags = { ...EMPTY_MIGRATE_FLAGS, format: flags.migrationFormat };
 
   // ADR-0021 D2 — explicit verify subverbs. Each flag selects one drift mode;
   // any combination runs each and the overall exit code is the MAX (non-zero on
@@ -182,16 +201,15 @@ export async function verifyCommand(
   // The schema gate is selected by the presence of --db, or --dialect d1 (#225 —
   // D1 has no URL connection); that check lives inside runSchemaVerify.
   const runCodegen = flags.codegen;
-  const runDocs = flags.docs;
-  // Task 15 — same shape as --codegen/--docs: selected ONLY by its own flag,
+  // Task 15 — same shape as --codegen: selected ONLY by its own flag,
   // never folded into the bare-verify default (it needs the publisher
   // reachable, which CI may not have — see the VerifyFlags doc on `deps`).
   const runDeps = flags.deps;
   if (!flags.anyExplicit) {
     say(
       "meta verify — running --templates (default). Explicit subverbs: " +
-        "--templates (prompt drift), --db/--dialect d1 (schema drift), --codegen (codegen drift), " +
-        "--docs (docs drift), --deps (dependency drift), " +
+        "--templates (prompt drift), --db/--dialect d1 (schema drift), " +
+        "--codegen (drift of everything `generators` declares, documentation included), --deps (dependency drift), " +
         "--replay/--replay-snapshot (the committed migration chain replays from empty).",
     );
   }
@@ -259,7 +277,13 @@ export async function verifyCommand(
   let forgeConfig: MetaobjectsGenConfig | undefined;
   try {
     forgeConfig = await loadMetaobjectsConfig(genConfigDir);
-  } catch {
+  } catch (e) {
+    // ADR-0058: the one config problem verify cannot fall back from — the default column
+    // rule would report every column of a database built with the old value as drift.
+    if (e instanceof RemovedNamingConfigError) {
+      log.error(e.message);
+      return 2;
+    }
     forgeConfig = undefined;
   }
   // Both of the gen config's contributions to the load, together — see
@@ -360,6 +384,8 @@ export async function verifyCommand(
   // #305 — the deprecated-reference authoring lint. Its own section, same reason.
   let deprecationSection: AdvisorySection<AdvisoryDiagnosticRow> =
     skippedSection("the deprecated-reference lint did not run");
+  let fieldSection: AdvisorySection<AdvisoryDiagnosticRow> =
+    skippedSection("the field lint did not run");
   // The ledger counts `meta verify` prints on every run. Undefined for a project
   // declaring no requirement.* node at all (opt-in by declaration) — the payload
   // then omits the block rather than reporting zeroes that would read as an empty
@@ -376,9 +402,14 @@ export async function verifyCommand(
   // subverb so ANY kind of drift fails CI. Each gate only runs when its mode is
   // selected; an unselected gate contributes 0.
   const templateExit = runTemplates ? runTemplateVerify() : 0;
+  // Set when the schema gate could not reach or read the database: a failure, but not
+  // drift, and the payload must not report it as drift.
+  let schemaRunError: string | undefined;
+  // The schema gate's findings, for the structured payload: what differs, not only that
+  // something does. Left undefined when the gate did not compare anything.
+  let schemaDrift: SchemaDriftSection | undefined;
   const schemaExit = await runSchemaVerify();
   const codegenExit = runCodegen ? await runCodegenVerify() : 0;
-  const docsExit = runDocs ? await runDocsVerify() : 0;
   const depsExit = runDeps ? await runDepsVerify() : 0;
   // Requirements have no subverb: `requirement.*` nodes are metadata, so they
   // are checked on every `meta verify`. Opt-in by DECLARATION — a model with no
@@ -405,6 +436,11 @@ export async function verifyCommand(
   // warnings ONLY, never changes the exit code.
   runDeprecationLintAdvisory();
 
+  // A reference identity over a field the object lacks, and a field name declared
+  // twice in one children list — both load clean on every port. Runs on every
+  // `meta verify`; warnings ONLY, never changes the exit code.
+  await runFieldLintAdvisory();
+
   // Advisory verify-as-teacher pass: surface hand-rolled work the metadata could
   // model. Warnings ONLY — never changes the exit code (bias to under-flagging).
   // Suppressed with --no-antipatterns or META_NO_ANTIPATTERNS=1 for the rare
@@ -415,7 +451,6 @@ export async function verifyCommand(
     templateExit,
     schemaExit,
     codegenExit,
-    docsExit,
     depsExit,
     requirementExit,
     replayExit,
@@ -429,7 +464,6 @@ export async function verifyCommand(
     // failure mode this whole change exists to remove.
     { gate: "schema", ran: ranSchemaGate, ok: schemaExit === 0 },
     { gate: "codegen", ran: runCodegen, ok: codegenExit === 0 },
-    { gate: "docs", ran: runDocs, ok: docsExit === 0 },
     { gate: "deps", ran: runDeps, ok: depsExit === 0 },
     { gate: "requirements", ran: true, ok: requirementExit === 0 },
     { gate: "replay", ran: flags.replay || flags.replaySnapshot, ok: replayExit === 0 },
@@ -455,6 +489,9 @@ export async function verifyCommand(
         overlays: overlaySection,
         names: nameSection,
         deprecations: deprecationSection,
+        fields: fieldSection,
+        ...(schemaDrift !== undefined ? { schemaDrift } : {}),
+        errors: schemaRunError !== undefined ? [{ gate: "schema", error: schemaRunError }] : [],
       }),
       fmt,
     );
@@ -483,7 +520,7 @@ export async function verifyCommand(
     // Resolve the migrations directory and the chain's dialect through MIGRATE's own
     // precedence, never a second derivation — verify must not look somewhere migrate
     // does not write, nor assume a dialect the chain was not emitted for.
-    const migrateConfig = await resolveMigrateConfig(EMPTY_MIGRATE_FLAGS, projectRoot);
+    const migrateConfig = await resolveMigrateConfig(migrateFlags, projectRoot);
 
     if (migrateConfig.format === "flyway") {
       log.error(
@@ -624,11 +661,9 @@ export async function verifyCommand(
     // passes no `governed` and gets the comparison exactly as it was.
     let governed: GovernedScope | undefined;
     if (schemaScope !== undefined) {
-      const viewStrategy = forgeConfig?.columnNamingStrategy ?? "snake_case";
       const built = buildExpectedSchemaWithProvenance(root, {
         dialect,
-        columnNamingStrategy: viewStrategy,
-        views: buildProjectionViews(root, { dialect, columnNamingStrategy: viewStrategy }),
+        views: buildProjectionViews(root, { dialect }),
       });
       governed = scopeExpectedSchema(built, schemaScope, importedOption(collection));
     }
@@ -671,7 +706,14 @@ export async function verifyCommand(
     // ONE scan for all three passes. The gate and the summary each used to walk the
     // model AND resolve every @implementedBy claim for themselves — the resolution
     // being the expensive half — and the lint added a third walk on top.
-    const scan = scanRequirements(root, { coverable: collection.inScope });
+    // The strict switch (ADR-0057) is decided here, once, and travels on the scan: the
+    // flag or META_REQUIRE_IMPLEMENTERS=1 — a flag-or-variable pair, as
+    // --no-requirement-lint has below, so a CI job can turn it on without editing a
+    // command line it shares with local runs.
+    const scan = scanRequirements(root, {
+      coverable: collection.inCoverage,
+      requireImplementers: flags.requireImplementers || process.env.META_REQUIRE_IMPLEMENTERS === "1",
+    });
     const diags = [...checkRequirements(root, scan)];
 
     // Printed on EVERY run, clean or not — a gate that says nothing when it
@@ -852,6 +894,41 @@ export async function verifyCommand(
     }
   }
 
+  // -- field authoring lint (advisory) ----------------------------------------
+  // Reads the LOADED model for the reference half and the project's OWN raw files
+  // for the duplicate half (see field-lint.ts) — a dependency artifact is not the
+  // adopter's to edit. Its own section, its own cap, and a skip that carries its
+  // reason rather than looking like a clean scan.
+  async function runFieldLintAdvisory(): Promise<void> {
+    if (flags.noFieldLint) {
+      fieldSection = skippedSection("suppressed by --no-field-lint");
+      return;
+    }
+    if (process.env.META_NO_FIELD_LINT === "1") {
+      fieldSection = skippedSection("suppressed by META_NO_FIELD_LINT=1");
+      return;
+    }
+    let findings: Diagnostic[];
+    try {
+      findings = [
+        ...lintReferenceFields(root),
+        ...(await lintDuplicateFields(collection.ownFiles, (path) => new FileSource(path))),
+      ];
+    } catch (err) {
+      // Never let an advisory scan break verify — and never report it as clean.
+      fieldSection = skippedSection(`the field lint failed: ${describeError(err)}`);
+      return;
+    }
+    fieldSection = ranSection(findings.map((d) => toDiagnosticRow(d, "lint")));
+    if (findings.length > 0) {
+      log.warn(
+        `meta verify — fields: ${findings.length} authoring warning(s) ` +
+          `(advisory — does not fail the build):`,
+      );
+      warnCapped(findings.map(formatDiagnostic), flags.limit, { structured });
+    }
+  }
+
   // -- deprecated-reference authoring lint (advisory) -------------------------
   // #305 — reads the LOADED model (see deprecation-lint.ts). Its own section,
   // its own cap, and a skip that carries its reason rather than looking clean.
@@ -942,7 +1019,6 @@ export async function verifyCommand(
       if (scanDialect !== "mysql") {
         unindexedFks = scanForUnindexedForeignKeys(root, {
           dialect: scanDialect,
-          columnNamingStrategy: forgeConfig?.columnNamingStrategy ?? "snake_case",
           skip: collection.imported,
         });
       }
@@ -1059,7 +1135,7 @@ export async function verifyCommand(
 
       // @payloadRef must resolve to a loaded object.value (drives the field tree
       // every render-engine drift check runs against).
-      const fieldTree = derivePayloadFieldTree(root, payloadRef, tmpl.package ?? tmpl.fileDefaultPackage ?? "");
+      const fieldTree = derivePayloadFieldTree(refTarget(tmpl, TEMPLATE_ATTR_PAYLOAD_REF));
       if (fieldTree.length === 0) {
         log.error(
           `[${tmpl.name}] (${tmpl.subType}) ${ERR_PARTIAL_UNRESOLVED}: ` +
@@ -1180,11 +1256,9 @@ export async function verifyCommand(
     // consults it.
     const scopeMismatch = migrateScopeMismatch(collection, () => {
       const dialect: Dialect = usingD1 ? "d1" : (flags.dialect ?? inferDialect(flags.db as string));
-      const viewStrategy = forgeConfig?.columnNamingStrategy ?? "snake_case";
       return buildExpectedSchemaWithProvenance(root, {
         dialect,
-        columnNamingStrategy: viewStrategy,
-        views: buildProjectionViews(root, { dialect, columnNamingStrategy: viewStrategy }),
+        views: buildProjectionViews(root, { dialect }),
       }).provenance;
     });
     if (scopeMismatch !== undefined) {
@@ -1225,16 +1299,21 @@ export async function verifyCommand(
     try {
       kysely = await buildKyselyFromUrl(flags.db as string, flags.dialect as Dialect | undefined);
     } catch (err) {
-      log.error(`verify: ${describeError(err)}`);
+      schemaRunError = describeError(err);
+      log.error(`verify: ${schemaRunError}`);
       return 1;
     }
 
     try {
       const allow = tokensToAllowOptions(flags.allow);
+      // Resolve the migrate config once for this whole path: `tryLoadConfig` is uncached,
+      // and the flyway filter below and checkCommittedSnapshot's migrations-dir read want
+      // the same value — resolving twice would read and parse `.metaobjects/config.json`
+      // twice per `meta verify --db`.
+      const migrateConfig = await resolveMigrateConfig(migrateFlags, projectRoot);
       // Expected views from the single view-SQL source (codegen-ts), so view-body
       // drift is detected against the live DB.
-      const viewStrategy = forgeConfig?.columnNamingStrategy ?? "snake_case";
-      const expectedViews = buildProjectionViews(root, { dialect: kysely.dialect, columnNamingStrategy: viewStrategy });
+      const expectedViews = buildProjectionViews(root, { dialect: kysely.dialect });
       let driftResult;
       let actual: SchemaSnapshot;
       try {
@@ -1242,22 +1321,29 @@ export async function verifyCommand(
         // `actual` this drift comparison uses, and re-introspecting for it would both
         // cost a second round trip and open a window where the two could disagree.
         actual = await introspect(kysely.db, kysely.dialect);
+        // Flyway owns its history table; it is no drift under the flyway format, as in `meta migrate`.
+        if (migrateConfig.format === "flyway") {
+          actual = withoutFlywayHistory(actual);
+        }
         driftResult = await computeDriftFromActual(actual, kysely.dialect, root, {
           allow,
           views: expectedViews,
+          // The same question `meta migrate` asks, so the report names the change it plans.
+          ...(kysely.dialect === "postgres" ? { viewReplaceProbe: postgresViewReplaceProbe(kysely.db) } : {}),
           ...(schemaScope !== undefined ? { inScope: schemaScope } : {}),
           // The import exclusion reaches scopeExpectedSchema through this option bag —
           // there is no direct call on this path to attach it to.
           ...importedOption(collection),
         });
       } catch (err) {
-        log.error(`verify: failed to introspect ${kysely.displayUrl}: ${describeError(err)}`);
+        schemaRunError = `failed to introspect ${kysely.displayUrl}: ${describeError(err)}`;
+        log.error(`verify: ${schemaRunError}`);
         return 1;
       }
 
       const snapshotDrift =
         driftResult.changes.length === 0
-          ? await checkCommittedSnapshot(actual, kysely.dialect, kysely.displayUrl, driftResult)
+          ? await checkCommittedSnapshot(actual, kysely.dialect, kysely.displayUrl, driftResult, migrateConfig)
           : [];
 
       return reportSchemaDrift(driftResult, [...ledgerDrift, ...snapshotDrift], kysely.displayUrl);
@@ -1327,8 +1413,7 @@ export async function verifyCommand(
     }
 
     const allow = tokensToAllowOptions(flags.allow);
-    const viewStrategy = forgeConfig?.columnNamingStrategy ?? "snake_case";
-    const expectedViews = buildProjectionViews(root, { dialect: "d1", columnNamingStrategy: viewStrategy });
+    const expectedViews = buildProjectionViews(root, { dialect: "d1" });
     let driftResult;
     try {
       driftResult = await computeDriftFromActual(actual, "d1", root, {
@@ -1382,13 +1467,15 @@ export async function verifyCommand(
     dialect: Dialect,
     displayUrl: string,
     governed: GovernedScope,
+    // Resolved by the caller and threaded through — see the `verify --db` branch: the same
+    // run's flyway filter reads this config too, and `tryLoadConfig` does not cache.
+    migrateConfig: ResolvedMigrateConfig,
   ): Promise<string[]> {
     if (dialect === "d1") return []; // d1 keeps migrations Wrangler-native; no offline snapshot
-    // Resolve the migrations dir through migrate's OWN precedence (flag > config >
-    // default) rather than re-deriving it, so verify can never look somewhere migrate
-    // does not write. Only `outDir` is consumed; the rest of the resolved config is
-    // migrate's business.
-    const migrateConfig = await resolveMigrateConfig(EMPTY_MIGRATE_FLAGS, projectRoot);
+    // The migrations dir comes from migrate's OWN precedence (flag > config > default)
+    // rather than a re-derivation here, so verify can never look somewhere migrate does
+    // not write. Only `outDir` and `format` are consumed; the rest of the resolved config
+    // is migrate's business.
     const dir = resolvePath(projectRoot, migrateConfig.outDir);
     let snapshot: SchemaSnapshot | null;
     try {
@@ -1397,6 +1484,7 @@ export async function verifyCommand(
       return [];
     }
     if (snapshot === null) return [];
+    if (migrateConfig.format === "flyway") snapshot = withoutFlywayHistory(snapshot);
 
     // Out-of-scope objects leave BOTH sides of this comparison, and the schema pin
     // comes from the scope decision the DRIFT comparison already made — one door
@@ -1421,7 +1509,9 @@ export async function verifyCommand(
       // MERGED with the out-of-scope set, and a second key would silently drop that half.
       dialect,
     });
-    if (result.changes.length === 0) return [];
+    // A view recreated only around a table change matches the snapshot (D3) — not a difference.
+    const changes = withoutViewRecreates(result.changes);
+    if (changes.length === 0) return [];
 
     return [
       // `meta migrate --from-db` is NOT the repair: it writes a snapshot only when it has
@@ -1431,10 +1521,10 @@ export async function verifyCommand(
       // been told everything is in sync. `baseline --from-db` rewrites it unconditionally,
       // which is the whole point of the subcommand.
       `the committed schema snapshot disagrees with ${displayUrl} ` +
-        `(${result.changes.length} difference(s)) — the next 'meta migrate' would emit DDL from it ` +
+        `(${changes.length} difference(s)) — the next 'meta migrate' would emit DDL from it ` +
         `and fail at apply. Re-derive it with ` +
         `'meta migrate baseline --from-db --db <url> --dialect ${dialect}'.`,
-      ...summarizeDrift(result.changes),
+      ...summarizeDrift(changes),
     ];
   }
 
@@ -1458,6 +1548,7 @@ export async function verifyCommand(
     }
 
     const changes = driftResult.changes;
+    schemaDrift = { changes: changes.map(toSchemaDriftRow), findings: ledgerDrift };
     if (changes.length === 0 && ledgerDrift.length === 0) {
       say(`meta verify — schema in sync with ${displayUrl}.`);
       return 0;
@@ -1517,13 +1608,28 @@ export async function verifyCommand(
         // and the loader's own remedies. It printed a bare message plus a hand-rolled
         // suggestions read — the half-true rule this file's sibling comment warns about.
         reportLoadError(log, "verify --codegen: failed to load this package's metadata", err);
-        return 2;
+        return 1;
       }
     }
 
+    // A 1.0 `docs` block configured a command that no longer exists; regenerating without it
+    // would check no documentation and pass. Refused before anything is written, as `meta gen`
+    // refuses it.
+    if (hasLegacyDocsBlock(forgeConfig)) {
+      log.error(legacyDocsConfigMessage("meta verify"));
+      return 2;
+    }
+    const config = forgeConfig;
     let result;
     try {
-      result = await computeCodegenDrift(forgeConfig, codegenRoot, genConfigDir, genCollection.inScope);
+      result = await computeCodegenDrift(config, codegenRoot, genConfigDir, genCollection.inScope, genCollection.ownFiles, {
+        sourceRoots: sourceRootsOf(genCollection),
+        agentSchema: () => buildAgentSchemaInput(
+          codegenRoot,
+          config.dialect,
+          (m) => log.warn(`verify --codegen: [agent-docs] ${m}`),
+        ),
+      });
     } catch (err) {
       log.error(`verify --codegen: regeneration failed: ${describeError(err)}`);
       return 1;
@@ -1539,6 +1645,17 @@ export async function verifyCommand(
     // contribution is current" and nothing else. Reported on every run; fails the build
     // only under --forbid-hand-edits.
     const handEditExit = reportHandEdits(result.handEdited);
+    // Say how much documentation was NOT checked, on the pass and the fail line alike, so a
+    // gate that compared two pages of 589 cannot read as one that compared all of them.
+    if (result.docsIgnored > 0) {
+      say(`meta verify — ${result.docsIgnored} generated documentation page(s) are git-ignored and were not checked.`);
+    }
+    for (const dir of result.docsIgnoredDirs) {
+      say(`meta verify — ${dir}: the repository git-ignores every documentation page generated there, so they were not compared.`);
+    }
+    if (result.docsIgnoreUnavailable !== undefined) {
+      say(`meta verify — git could not say which documentation pages are ignored (${result.docsIgnoreUnavailable}), so every page was checked.`);
+    }
 
     if (result.clean) {
       // Says what it CHECKED, not more. Since 0.24.3 this gate asks whether each file's
@@ -1558,9 +1675,18 @@ export async function verifyCommand(
     // it MERGES the edit and exits 0 — so prescribing it there was the unbreakable loop
     // the hand-edit exemption exists to end, reintroduced for the one file the exemption
     // deliberately excludes. Both lines print when the drift set holds both kinds.
-    if (result.driftedFiles.length > result.handEditedNames.length) {
+    if (result.driftedFiles.length > result.handEditedNames.length + result.editedOrphans.length) {
       log.error("Run 'meta gen' to regenerate, then commit the result.");
     }
+    // A hand-edited orphan is the other kind `meta gen` cannot fix: it deletes an untouched
+    // file no generator emits any more, and refuses an edited one.
+    if (result.editedOrphans.length > 0) {
+      log.error(
+        "For the file(s) above that no generator emits any more and that were edited by hand, " +
+          "'meta gen' will NOT delete them. Delete each one, or move your edits into a file of " +
+          "your own first.",
+      );
+    }
     if (result.handEditedNames.length > 0) {
       log.error(
         "For the names artifact(s) above, 'meta gen' will NOT help — it preserves a hand " +
@@ -1588,90 +1714,6 @@ export async function verifyCommand(
     return 0;
   }
 
-  // -- docs drift -------------------------------------------------------------
-  // Gated on --docs. Runs `meta docs` into a temp dir and diffs the committed docs
-  // tree. See lib/docs-drift.ts for the deliberate differences from --codegen: a byte
-  // difference IS drift here; a committed file a regen would not emit is reported ONLY
-  // under `agent/` and only when it opens with the @generated marker (`docs.outDir` is
-  // otherwise full of files MetaObjects did not write); and a page the project
-  // GIT-IGNORES is exempt, because `docs.outDir` is a directory rather than a namespace
-  // MetaObjects owns.
-  //
-  // It needs a config for the same reason `--codegen` does: `docs.outDir` says which
-  // tree to compare against, and the `agent` surface will not even materialise
-  // without one.
-  async function runDocsVerify(): Promise<number> {
-    if (forgeConfig === undefined) {
-      log.error(
-        "verify --docs: no metaobjects.config.ts found (or it is invalid) — " +
-          "cannot locate the committed docs tree to diff against. " +
-          "Run 'meta init' to scaffold one, or run without --docs.",
-      );
-      return 2;
-    }
-
-    // Resolved through the SAME resolver `meta docs` uses, so a project that moved its
-    // docs elsewhere is checked where its docs actually are. `outputLayout` is the
-    // documented fallback for `docs.layout`.
-    const docsCfg = resolveDocsConfig(forgeConfig.docs, {}, forgeConfig.outputLayout ?? "flat");
-    let result;
-    try {
-      result = await computeDocsDrift({
-        projectRoot: genConfigDir,
-        docsDir: resolvePath(genConfigDir, docsCfg.outDir),
-        cwd: genConfigDir,
-      });
-    } catch (err) {
-      log.error(`verify --docs: regeneration failed: ${describeError(err)}`);
-      return 1;
-    }
-
-    if (result.error !== undefined) {
-      log.error(result.error);
-      return 2;
-    }
-
-    // What the gate did NOT check, on BOTH the passing and the failing line. A gate
-    // that quietly compared two of 589 pages and reported "no drift" would be
-    // indistinguishable from one that compared everything.
-    const notChecked =
-      result.ignoreReason !== undefined
-        ? `; .gitignore not consulted — ${result.ignoreReason} — so every page a fresh run emits was expected to be committed`
-        : result.ignored > 0
-          ? `; ${result.ignored} git-ignored page(s) not checked`
-          : "";
-
-    if (result.clean) {
-      // The denominator is what was actually COMPARED, so the passing line and the
-      // failing line below count the same set. A gate whose two halves divide by
-      // different numbers is how `verify --templates` came to report seven templates
-      // vanishing between a red run and a green one.
-      say(
-        `meta verify — ${result.checked} docs page(s) match a fresh 'meta docs' ` +
-          `(no docs drift${notChecked}).`,
-      );
-      return 0;
-    }
-
-    log.error(
-      `meta verify — docs drift (${result.driftedFiles.length} of ${result.checked} page(s) ` +
-        `differ from a fresh 'meta docs'${notChecked}):`,
-    );
-    for (const line of result.lines) log.error(`  ${line}`);
-    log.error("Run 'meta docs' to regenerate, then commit the result.");
-    // The one-command path to green, named at the point of conviction — a page reported
-    // as uncommitted is the one case where regenerating is NOT the answer.
-    if (result.lines.some((l) => l.startsWith("+ "))) {
-      log.error(
-        result.ignoreReason === undefined
-          ? "A page you deliberately do not commit is exempt once it is git-ignored."
-          : `.gitignore was not consulted (${result.ignoreReason}), so a page you ` +
-            `deliberately do not commit is reported above.`,
-      );
-    }
-    return 1;
-  }
-
   // -- dependency drift (Task 15, FR-023) --------------------------------------
   // Gated on --deps. Re-resolves each declared dependency exactly as `meta deps
   // check` does — never part of the bare-verify default (it needs the publisher
@@ -1765,6 +1807,28 @@ function summarizeDrift(changes: Change[]): string[] {
   });
 }
 
+/** One schema difference in the structured payload — the same text the stderr summary prints. */
+interface SchemaDriftRow {
+  kind: Change["kind"];
+  object: string;
+  detail: string;
+}
+
+/**
+ * The schema gate's findings in the structured payload. An adopter whose `verify --db` failed
+ * on views could not tell from `--format json` what differed (D3): the payload carried the
+ * verdict only. `changes` is the metadata↔database comparison; `findings` are the
+ * migration-ledger and committed-snapshot lines, which are text by construction.
+ */
+interface SchemaDriftSection {
+  changes: SchemaDriftRow[];
+  findings: string[];
+}
+
+function toSchemaDriftRow(c: Change): SchemaDriftRow {
+  return { kind: c.kind, object: DRIFT_PRESENTATION[c.kind].noun, detail: describeChange(c) };
+}
+
 // ---------------------------------------------------------------------------
 // structured output (--format toon|json)
 // ---------------------------------------------------------------------------
@@ -1819,7 +1883,6 @@ const GATE_SELECTOR: Record<string, string> = {
   templates: "--templates",
   schema: "--db <url>",
   codegen: "--codegen",
-  docs: "--docs",
   deps: "--deps",
   replay: "--replay",
 };
@@ -1890,14 +1953,26 @@ function buildVerifyPayload(input: {
   overlays: AdvisorySection<AdvisoryDiagnosticRow>;
   names: AdvisorySection<AdvisoryDiagnosticRow>;
   deprecations: AdvisorySection<AdvisoryDiagnosticRow>;
+  fields: AdvisorySection<AdvisoryDiagnosticRow>;
+  /** What the schema gate found, when it compared anything. */
+  schemaDrift?: SchemaDriftSection;
+  /** Gates that could not run at all (an unreachable database) — failures, not drift. */
+  errors?: readonly { gate: string; error: string }[];
 }): Record<string, unknown> {
   const ran = input.gates.filter((g) => g.ran);
   const failed = ran.filter((g) => !g.ok);
-  const parts: string[] = [
-    failed.length === 0
-      ? `${ran.length} gate(s) ran, all clean`
-      : `${failed.length} of ${ran.length} gate(s) failed (${failed.map((g) => g.gate).join(", ")})`,
-  ];
+  const errors = input.errors ?? [];
+  const drifted = failed.filter((g) => !errors.some((e) => e.gate === g.gate));
+  const parts: string[] = failed.length === 0
+    ? [`${ran.length} gate(s) ran, all clean`]
+    : [
+        ...(drifted.length > 0
+          ? [`${drifted.length} of ${ran.length} gate(s) failed (${drifted.map((g) => g.gate).join(", ")})`]
+          : []),
+        ...(errors.length > 0
+          ? [`${errors.length} gate(s) could not run (${errors.map((e) => e.gate).join(", ")})`]
+          : []),
+      ];
   if (input.antiPatterns.status === "ran" && input.antiPatterns.total > 0) {
     // "advisory", not "anti-pattern": the section also carries unindexed foreign keys, a
     // missing baseUrl and the other non-scanner rows — `help` breaks the count down by kind.
@@ -1915,9 +1990,18 @@ function buildVerifyPayload(input: {
   if (input.deprecations.status === "ran" && input.deprecations.total > 0) {
     parts.push(`${input.deprecations.total} deprecated-reference finding(s)`);
   }
+  if (input.fields.status === "ran" && input.fields.total > 0) {
+    parts.push(`${input.fields.total} field authoring finding(s)`);
+  }
 
-  const help: string[] = [];
-  if (failed.length > 0) {
+  const help: string[] = errors.map((e) =>
+    `the ${e.gate} gate could not run, which is not drift: ${e.error} — fix the connection and re-run`);
+  if (drifted.some((g) => g.gate === "schema") && input.schemaDrift !== undefined) {
+    help.push(
+      `the schema gate's differences are in schemaDrift — changes[] (metadata vs database, one row per change) and findings[] (migration ledger and committed snapshot)`,
+    );
+  }
+  if (drifted.some((g) => g.gate !== "schema")) {
     help.push(
       `the failing gate's drift DETAIL is printed as text on stderr — this payload carries the verdict only`,
     );
@@ -1940,19 +2024,26 @@ function buildVerifyPayload(input: {
       `${input.deprecations.total} reference(s) to a deprecated node — see deprecations.rows[]; each names the deprecated target and, where declared, its replacement`,
     );
   }
+  if (input.fields.total > 0) {
+    help.push(
+      `${input.fields.total} field authoring finding(s) — see fields.rows[]; each names a reference identity listing a field its object lacks, or a field name declared twice in one children list`,
+    );
+  }
   if (
     failed.length === 0 &&
     input.antiPatterns.total === 0 &&
     input.requirements.total === 0 &&
     input.overlays.total === 0 &&
     input.names.total === 0 &&
-    input.deprecations.total === 0
+    input.deprecations.total === 0 &&
+    input.fields.total === 0
   ) {
     help.push("no drift and nothing advisory to answer — nothing to do");
   }
 
   return {
     verify: input.gates,
+    ...(errors.length > 0 ? { errors } : {}),
     exitCode: input.exitCode,
     summary: parts.join("; "),
     help,
@@ -1961,12 +2052,14 @@ function buildVerifyPayload(input: {
     overlays: input.overlays,
     names: input.names,
     deprecations: input.deprecations,
+    fields: input.fields,
     ...(input.requirementCounts !== undefined ? { requirementCounts: input.requirementCounts } : {}),
+    ...(input.schemaDrift !== undefined ? { schemaDrift: input.schemaDrift } : {}),
     // The honest boundary. Everything named here is REACHABLE — it is printed as
     // text on stderr — but it is not in this document, and a reader must not have
     // to discover that by its absence.
     notRepresented: [
-      "per-gate drift detail (which template variable drifted, which schema change, which generated file differs, which migration failed to replay) — printed as text on stderr; this payload carries each gate's pass/fail verdict",
+      "per-gate drift detail for every gate but schema (which template variable drifted, which generated file differs, which migration failed to replay) — printed as text on stderr; this payload carries each gate's pass/fail verdict, and the schema gate's differences in schemaDrift",
       "the loader's own warnings and the agent-context/manifest advisories — printed as text on stderr",
     ],
   };