@metaobjectsdev/cli 1.0.12 → 1.1.0

package/dist/src/commands/verify.js

@@ -22,26 +22,29 @@ import { scanForRemovedProps } from "../lib/removed-prop-advisory.js";
 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, } from "../lib/requirement-check.js";
 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 { buildWranglerExecuteArgs, defaultWranglerRunner, isWranglerLocalD1StatePath, } from "../lib/wrangler.js";
-import { buildProjectionViews, resolveDocsConfig } from "@metaobjectsdev/codegen-ts";
+import { buildProjectionViews } from "@metaobjectsdev/codegen-ts";
 import { buildKyselyFromUrl, inferDialect } from "../lib/kysely.js";
 import { tokensToAllowOptions, describeChange } from "../lib/allow.js";
-import { computeDrift, computeDriftFromActual, collectUnmanagedNames, excludeFromSnapshot, scopedDiffInputs, scopeExpectedSchema, buildExpectedSchemaWithProvenance, applyPending, openReplayEngine, verifyReplay, introspect, diff, readSnapshot, snapshotPath, introspectD1, findWranglerConfig, parseWranglerConfig, resolveD1Binding, } from "@metaobjectsdev/migrate-ts";
+import { computeDrift, computeDriftFromActual, collectUnmanagedNames, excludeFromSnapshot, scopedDiffInputs, scopeExpectedSchema, buildExpectedSchemaWithProvenance, applyPending, openReplayEngine, verifyReplay, introspect, diff, withoutViewRecreates, readSnapshot, snapshotPath, introspectD1, findWranglerConfig, parseWranglerConfig, resolveD1Binding, postgresViewReplaceProbe, withoutFlywayHistory, } from "@metaobjectsdev/migrate-ts";
 import { DEFAULT_METAOBJECTS_DIR, loadConfig, loadMemory, resolveCollection, } from "@metaobjectsdev/sdk";
 import { checkDependencies, ERR_DEPENDENCY_UPSTREAM_DRIFT, formatCheckLine, readLockOrThrow } from "../lib/dependency-sync.js";
 import { exclusionNotes, importedOption, migrateScopeMismatch } from "../lib/migrate-scope.js";
-import { TYPE_TEMPLATE, TEMPLATE_SUBTYPE_PROMPT, TEMPLATE_SUBTYPE_OUTPUT, TEMPLATE_ATTR_PAYLOAD_REF, TEMPLATE_ATTR_TEXT_REF, TEMPLATE_ATTR_REQUIRED_SLOTS, TEMPLATE_ATTR_REQUIRED_TAGS, TEMPLATE_ATTR_KIND, TEMPLATE_KIND_EMAIL, TEMPLATE_KIND_DEFAULT, TEMPLATE_ATTR_SUBJECT_REF, TEMPLATE_ATTR_HTML_BODY_REF, TEMPLATE_ATTR_TEXT_BODY_REF, REQUIREMENT_STATUSES, } from "@metaobjectsdev/metadata";
+import { TYPE_TEMPLATE, TEMPLATE_SUBTYPE_PROMPT, TEMPLATE_SUBTYPE_OUTPUT, TEMPLATE_ATTR_PAYLOAD_REF, refTarget, TEMPLATE_ATTR_TEXT_REF, TEMPLATE_ATTR_REQUIRED_SLOTS, TEMPLATE_ATTR_REQUIRED_TAGS, TEMPLATE_ATTR_KIND, TEMPLATE_KIND_EMAIL, TEMPLATE_KIND_DEFAULT, TEMPLATE_ATTR_SUBJECT_REF, 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";
 import { describeError } from "../lib/error-text.js";
@@ -52,9 +55,11 @@ const DEFAULT_PROMPTS_DIR = "prompts";
 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
@@ -106,6 +111,15 @@ fmt = "text") {
         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 = { ...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
     // any drift). A bare `verify` (no explicit subverb) keeps its documented
@@ -115,15 +129,14 @@ fmt = "text") {
     // 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).");
     }
     // Where the metadata lives is `resolveCollection`'s decision, not a hardcoded
@@ -187,7 +200,13 @@ fmt = "text") {
     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
@@ -281,6 +300,7 @@ fmt = "text") {
     let nameSection = skippedSection("the name lint did not run");
     // #305 — the deprecated-reference authoring lint. Its own section, same reason.
     let deprecationSection = skippedSection("the deprecated-reference lint did not run");
+    let fieldSection = 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
@@ -295,9 +315,14 @@ fmt = "text") {
     // 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;
+    // 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;
     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
@@ -320,12 +345,16 @@ fmt = "text") {
     // @from/@of/@via) on a `deprecated` node. Runs on every `meta verify`;
     // 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
     // noisy project (both opt-outs work on `meta verify` and `meta gen`).
     await runAntiPatternAdvisory();
-    const exitCode = Math.max(templateExit, schemaExit, codegenExit, docsExit, depsExit, requirementExit, replayExit);
+    const exitCode = Math.max(templateExit, schemaExit, codegenExit, depsExit, requirementExit, replayExit);
     const gates = [
         { gate: "templates", ran: runTemplates, ok: templateExit === 0 },
         // The schema gate decides internally whether it is selected (--db, or
@@ -334,7 +363,6 @@ fmt = "text") {
         // 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 },
@@ -358,6 +386,9 @@ fmt = "text") {
             overlays: overlaySection,
             names: nameSection,
             deprecations: deprecationSection,
+            fields: fieldSection,
+            ...(schemaDrift !== undefined ? { schemaDrift } : {}),
+            errors: schemaRunError !== undefined ? [{ gate: "schema", error: schemaRunError }] : [],
         }), fmt);
     }
     return exitCode;
@@ -382,7 +413,7 @@ fmt = "text") {
         // 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(`meta verify --replay is not supported with --migration-format flyway — run 'flyway migrate' against a scratch database to replay`);
             return 2;
@@ -507,11 +538,9 @@ fmt = "text") {
         // passes no `governed` and gets the comparison exactly as it was.
         let governed;
         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));
         }
@@ -550,7 +579,14 @@ fmt = "text") {
         // 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
         // passes cannot be told apart from a gate that checked nothing, and the
@@ -715,6 +751,39 @@ fmt = "text") {
             warnCapped(findings.map(formatDiagnostic), flags.limit, { structured });
         }
     }
+    // -- 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() {
+        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;
+        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.
@@ -802,7 +871,6 @@ fmt = "text") {
             if (scanDialect !== "mysql") {
                 unindexedFks = scanForUnindexedForeignKeys(root, {
                     dialect: scanDialect,
-                    columnNamingStrategy: forgeConfig?.columnNamingStrategy ?? "snake_case",
                     skip: collection.imported,
                 });
             }
@@ -904,7 +972,7 @@ fmt = "text") {
                 continue;
             // @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}: ` +
                     `@payloadRef "${payloadRef}" did not resolve to a loaded object.value`);
@@ -1023,11 +1091,9 @@ fmt = "text") {
         // consults it.
         const scopeMismatch = migrateScopeMismatch(collection, () => {
             const dialect = usingD1 ? "d1" : (flags.dialect ?? inferDialect(flags.db));
-            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) {
@@ -1063,15 +1129,20 @@ fmt = "text") {
             kysely = await buildKyselyFromUrl(flags.db, flags.dialect);
         }
         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;
             try {
@@ -1079,9 +1150,15 @@ fmt = "text") {
                 // `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.
@@ -1089,11 +1166,12 @@ fmt = "text") {
                 });
             }
             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);
         }
@@ -1160,8 +1238,7 @@ fmt = "text") {
             return 1;
         }
         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, {
@@ -1209,14 +1286,16 @@ fmt = "text") {
     // Fails OPEN when there is no snapshot on disk (a project that has never generated one
     // offline is not in an error state) and when the file cannot be read or parsed (that is
     // migrate's error to raise, with its own message, not a drift verdict).
-    async function checkCommittedSnapshot(actual, dialect, displayUrl, governed) {
+    async function checkCommittedSnapshot(actual, dialect, displayUrl, governed, 
+    // 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) {
         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;
         try {
@@ -1227,6 +1306,8 @@ fmt = "text") {
         }
         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
         // (migrate-ts's `excludeFromSnapshot` + `scopedDiffInputs`), not a fifth
@@ -1250,7 +1331,9 @@ fmt = "text") {
             // MERGED with the out-of-scope set, and a second key would silently drop that half.
             dialect,
         });
-        if (result.changes.length === 0)
+        // 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
@@ -1260,10 +1343,10 @@ fmt = "text") {
             // 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),
         ];
     }
     function reportSchemaDrift(driftResult, ledgerDrift, displayUrl) {
@@ -1282,6 +1365,7 @@ fmt = "text") {
             say(note);
         }
         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;
@@ -1339,12 +1423,23 @@ fmt = "text") {
                 // 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)}`);
@@ -1359,6 +1454,17 @@ fmt = "text") {
         // 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
             // GENERATED contribution is current — a hand edit `meta gen` preserves is exempt —
@@ -1375,9 +1481,16 @@ fmt = "text") {
         // 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 " +
                 "edit by design. Revert the edit (or delete the file and re-run 'meta gen' to " +
@@ -1404,77 +1517,6 @@ fmt = "text") {
             log.warn(line);
         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() {
-        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
@@ -1561,6 +1603,9 @@ function summarizeDrift(changes) {
         return `${p.glyph} ${p.noun} ${describeChange(c)}`;
     });
 }
+function toSchemaDriftRow(c) {
+    return { kind: c.kind, object: DRIFT_PRESENTATION[c.kind].noun, detail: describeChange(c) };
+}
 /**
  * The hand-edit report for `verify --codegen`: a header with the count, one indented line
  * per path, then how to see an edit. Exported for its test.
@@ -1589,7 +1634,6 @@ const GATE_SELECTOR = {
     templates: "--templates",
     schema: "--db <url>",
     codegen: "--codegen",
-    docs: "--docs",
     deps: "--deps",
     replay: "--replay",
 };
@@ -1648,11 +1692,18 @@ function toDiagnosticRow(d, source) {
 function buildVerifyPayload(input) {
     const ran = input.gates.filter((g) => g.ran);
     const failed = ran.filter((g) => !g.ok);
-    const parts = [
-        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 = 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.
@@ -1670,8 +1721,14 @@ function buildVerifyPayload(input) {
     if (input.deprecations.status === "ran" && input.deprecations.total > 0) {
         parts.push(`${input.deprecations.total} deprecated-reference finding(s)`);
     }
-    const help = [];
-    if (failed.length > 0) {
+    if (input.fields.status === "ran" && input.fields.total > 0) {
+        parts.push(`${input.fields.total} field authoring finding(s)`);
+    }
+    const help = 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`);
     }
     if (input.antiPatterns.total > 0) {
@@ -1686,16 +1743,21 @@ function buildVerifyPayload(input) {
     if (input.deprecations.total > 0) {
         help.push(`${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,
@@ -1704,12 +1766,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",
         ],
     };