@miller-tech/uap 1.210.8 → 1.211.0

package/dist/cli/schema-diff.js

@@ -48,15 +48,87 @@ function extractTypeScriptFields(content) {
     }
     return fields;
 }
+/**
+ * Blank out SQL comments, preserving offsets and line structure.
+ *
+ * Everything below counts parentheses and splits on commas, and a comment is
+ * allowed to contain both. `-- natural key (see ADR-14` raised the paren depth
+ * and swallowed the rest of the file, so the table it belonged to contributed
+ * NO columns; if that happened on one side of the diff only, every column read
+ * as removed and an added comment became a BREAKING verdict. Replacing with
+ * spaces rather than deleting keeps every offset valid for the callers that
+ * index back into the string.
+ */
+function stripSqlComments(content) {
+    let out = '';
+    let i = 0;
+    while (i < content.length) {
+        const two = content.slice(i, i + 2);
+        if (two === '--') {
+            while (i < content.length && content[i] !== '\n') {
+                out += ' ';
+                i++;
+            }
+            continue;
+        }
+        if (two === '/*') {
+            while (i < content.length && content.slice(i, i + 2) !== '*/') {
+                out += content[i] === '\n' ? '\n' : ' ';
+                i++;
+            }
+            out += '  ';
+            i += 2;
+            continue;
+        }
+        // A quoted literal may legitimately contain -- or parens; copy it whole.
+        if (content[i] === "'" || content[i] === '"') {
+            const quote = content[i];
+            out += content[i];
+            i++;
+            while (i < content.length) {
+                out += content[i];
+                if (content[i] === quote) {
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            continue;
+        }
+        out += content[i];
+        i++;
+    }
+    return out;
+}
+/** Contents between `content[open]` ('(') and its matching ')', or null. */
+function tableBody(content, open) {
+    let depth = 0;
+    for (let i = open; i < content.length; i++) {
+        if (content[i] === '(')
+            depth++;
+        else if (content[i] === ')') {
+            depth--;
+            if (depth === 0)
+                return content.slice(open + 1, i);
+        }
+    }
+    return null;
+}
 /**
  * Extract SQLite CREATE TABLE columns from SQL or source code.
  */
-function extractSQLiteColumns(content) {
+function extractSQLiteColumns(raw) {
     const columns = new Map();
-    const createTables = content.matchAll(/CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?(\w+)\s*\(([\s\S]*?)\)/gi);
+    const content = stripSqlComments(raw);
+    const createTables = content.matchAll(/CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?(\w+)\s*\(/gi);
     for (const table of createTables) {
         const tableName = table[1];
-        const body = table[2];
+        // Paren-matched, not `\(([\s\S]*?)\)`: the non-greedy form stopped at the
+        // FIRST `)`, so one `amt DECIMAL(10,2)` hid every column declared after it
+        // — including a later NOT NULL addition, which a blocking gate must see.
+        const body = tableBody(content, (table.index ?? 0) + table[0].length - 1);
+        if (body === null)
+            continue;
         const colMatches = body.matchAll(/(\w+)\s+(INTEGER|TEXT|REAL|BLOB|DATETIME|BOOLEAN|VARCHAR[^,]*)/gi);
         for (const col of colMatches) {
             columns.set(`${tableName}.${col[1]}`, col[2].trim());
@@ -64,6 +136,135 @@ function extractSQLiteColumns(content) {
     }
     return columns;
 }
+/** Top-level comma split: `DECIMAL(10,2)` is one part, not two. */
+function splitTopLevel(body) {
+    const parts = [];
+    let depth = 0;
+    let cur = '';
+    for (const ch of body) {
+        if (ch === '(')
+            depth++;
+        else if (ch === ')')
+            depth--;
+        if (ch === ',' && depth === 0) {
+            parts.push(cur);
+            cur = '';
+            continue;
+        }
+        cur += ch;
+    }
+    if (cur.trim())
+        parts.push(cur);
+    return parts;
+}
+/** Clauses that describe the TABLE, not a column. */
+const TABLE_CONSTRAINT = /^\s*(PRIMARY|FOREIGN|UNIQUE|CHECK|CONSTRAINT|KEY|INDEX|EXCLUDE|LIKE|INHERITS)\b/i;
+/**
+ * Columns the schema makes MANDATORY: NOT NULL with nothing to fill them.
+ *
+ * Needed because the generic added-field rule ("breaking unless the type says
+ * optional or ?") is Zod/TypeScript-shaped and reads every SQL type as
+ * required — so a plain `ADD COLUMN note TEXT`, the most common and most
+ * harmless migration there is, was reported BREAKING. Harmless while the
+ * checker only printed advice; not harmless now that a gate blocks on the
+ * verdict, where it would refuse ordinary additive migrations and teach people
+ * to reach for the waiver.
+ *
+ * A column is only genuinely breaking to add when existing rows and existing
+ * INSERTs cannot satisfy it: NOT NULL, no DEFAULT, and not self-filling
+ * (SERIAL/IDENTITY/AUTOINCREMENT/GENERATED).
+ *
+ * The table body is matched by counting parens rather than with the
+ * non-greedy `\(([\s\S]*?)\)` used elsewhere here, which stops at the first
+ * `)` and so loses every column after a `DECIMAL(10,2)`. Over-collecting is
+ * safe: this set only ever classifies names the diff already produced.
+ */
+function sqlRequiredColumns(raw) {
+    const required = new Set();
+    const content = stripSqlComments(raw);
+    const heads = content.matchAll(/CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?([\w."`\[\]]+)\s*\(/gi);
+    for (const head of heads) {
+        const table = (head[1] ?? '').replace(/["`[\]]/g, '').split('.').pop() ?? '';
+        const body = tableBody(content, (head.index ?? 0) + head[0].length - 1);
+        if (body === null)
+            continue;
+        for (const part of splitTopLevel(body)) {
+            if (TABLE_CONSTRAINT.test(part))
+                continue;
+            const name = part.trim().match(/^["`[]?(\w+)/)?.[1];
+            if (!name)
+                continue;
+            const notNull = /\bNOT\s+NULL\b/i.test(part);
+            const filled = /\b(DEFAULT|SERIAL|BIGSERIAL|SMALLSERIAL|AUTOINCREMENT|IDENTITY|GENERATED)\b/i.test(part);
+            if (notNull && !filled)
+                required.add(`${table}.${name}`);
+        }
+    }
+    return required;
+}
+/**
+ * Apply the SQL rule to `added` verdicts produced by the generic differ.
+ *
+ * Only additions are re-scored: removals and type changes keep the generic
+ * judgement, which is right for SQL too.
+ */
+function rescoreSqlAdditions(changes, afterContent, context) {
+    const required = sqlRequiredColumns(afterContent);
+    return changes.map((c) => {
+        if (c.type !== 'added')
+            return c;
+        const column = c.path.startsWith(`${context}.`) ? c.path.slice(context.length + 1) : c.path;
+        const breaking = required.has(column);
+        if (breaking === c.breaking)
+            return c;
+        return {
+            ...c,
+            breaking,
+            description: breaking
+                ? `${c.description.replace(/ \(required — breaking\)$/, '')} (NOT NULL with no default — breaking)`
+                : c.description.replace(/ \(required — breaking\)$/, ''),
+        };
+    });
+}
+/**
+ * Destructive DDL statements, as human-readable descriptions.
+ *
+ * The CREATE TABLE differ can only speak about a file that HAS a previous
+ * version to compare against, which excludes the single most common breaking
+ * change there is: a brand-new migration whose whole content is `DROP TABLE
+ * users;`. Nothing was removed relative to the old file, because there is no
+ * old file -- so the differ said "no changes" and the gate cleared it.
+ *
+ * These statements are breaking on sight, no baseline required.
+ */
+function destructiveDdl(raw) {
+    const sql = stripSqlComments(raw);
+    const found = [];
+    const scan = (re, describe) => {
+        for (const m of sql.matchAll(re))
+            found.push(describe(m));
+    };
+    scan(/\bDROP\s+TABLE\s+(?:IF\s+EXISTS\s+)?([\w."`[\]]+)/gi, (m) => `DROP TABLE ${m[1]}`);
+    scan(/\bDROP\s+(?:MATERIALIZED\s+)?VIEW\s+(?:IF\s+EXISTS\s+)?([\w."`[\]]+)/gi, (m) => `DROP VIEW ${m[1]}`);
+    scan(/\bDROP\s+INDEX\s+(?:IF\s+EXISTS\s+)?([\w."`[\]]+)/gi, (m) => `DROP INDEX ${m[1]}`);
+    scan(/\bTRUNCATE\s+(?:TABLE\s+)?([\w."`[\]]+)/gi, (m) => `TRUNCATE ${m[1]}`);
+    scan(/\bALTER\s+TABLE\s+([\w."`[\]]+)\s+DROP\s+(?:COLUMN\s+)?(?:IF\s+EXISTS\s+)?([\w."`[\]]+)/gi, (m) => `ALTER TABLE ${m[1]} DROP COLUMN ${m[2]}`);
+    scan(/\bALTER\s+TABLE\s+([\w."`[\]]+)\s+RENAME\s+(?:COLUMN\s+)?([\w."`[\]]+)\s+TO\s+([\w."`[\]]+)/gi, (m) => `ALTER TABLE ${m[1]} RENAME ${m[2]} TO ${m[3]}`);
+    scan(/\bALTER\s+TABLE\s+([\w."`[\]]+)\s+RENAME\s+TO\s+([\w."`[\]]+)/gi, (m) => `ALTER TABLE ${m[1]} RENAME TO ${m[2]}`);
+    scan(/\bALTER\s+TABLE\s+([\w."`[\]]+)\s+ALTER\s+(?:COLUMN\s+)?([\w."`[\]]+)\s+(?:SET\s+DATA\s+)?TYPE\b/gi, (m) => `ALTER TABLE ${m[1]} ALTER COLUMN ${m[2]} TYPE`);
+    scan(/\bALTER\s+TABLE\s+([\w."`[\]]+)\s+ALTER\s+(?:COLUMN\s+)?([\w."`[\]]+)\s+SET\s+NOT\s+NULL/gi, (m) => `ALTER TABLE ${m[1]} SET NOT NULL on ${m[2]}`);
+    // ADD COLUMN is breaking only when existing rows cannot satisfy it, the same
+    // rule sqlRequiredColumns applies inside CREATE TABLE.
+    for (const m of sql.matchAll(/\bALTER\s+TABLE\s+([\w."`[\]]+)\s+ADD\s+(?:COLUMN\s+)?(?:IF\s+NOT\s+EXISTS\s+)?([\w."`[\]]+)([^;]*)/gi)) {
+        const tail = m[3] ?? '';
+        const notNull = /\bNOT\s+NULL\b/i.test(tail);
+        const filled = /\b(DEFAULT|SERIAL|BIGSERIAL|SMALLSERIAL|AUTOINCREMENT|IDENTITY|GENERATED)\b/i.test(tail);
+        if (notNull && !filled) {
+            found.push(`ALTER TABLE ${m[1]} ADD COLUMN ${m[2]} NOT NULL with no default`);
+        }
+    }
+    return found;
+}
 /**
  * Compare two field maps and produce a list of changes.
  */
@@ -125,11 +326,114 @@ function gitEnv() {
     }
     return env;
 }
-export async function diffFileSchema(filePath, baseBranch = 'HEAD~1', cwd = process.cwd()) {
+/**
+ * Both versions of a path, because a commit may take either.
+ *
+ * `git commit` stores the INDEX; `git commit -a` stores the WORKTREE. Callers
+ * need to know both to decide which one a given commit will take — but only
+ * the analysed one is ever RECORDED (see committedVersion), because a marker
+ * that names bytes nothing inspected is the bug this whole change exists to
+ * remove.
+ */
+async function fileVersions(path, cwd) {
+    const { execFileSync } = await import('child_process');
+    const opts = { cwd, env: gitEnv(), encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] };
+    const hex = (s) => (/^[0-9a-f]{40}$|^[0-9a-f]{64}$/.test(s) ? s : '');
+    let index = '';
+    let worktree = '';
+    try {
+        index = hex(execFileSync('git', ['rev-parse', `:${path}`], opts).trim());
+    }
+    catch {
+        /* not staged */
+    }
+    try {
+        worktree = hex(execFileSync('git', ['hash-object', '--', path], opts).trim());
+    }
+    catch {
+        /* deleted, unreadable, sparse */
+    }
+    return { index, worktree };
+}
+/**
+ * The version that will be committed, and the bytes to analyse.
+ *
+ * INDEX-preferred, because `git commit` stores the index. Recording the
+ * worktree instead is what let a staged-malicious / benign-worktree pair clear
+ * a gate claiming to cover "staged content"; and recording BOTH without
+ * analysing both would re-open exactly that, since the marker would vouch for
+ * bytes nothing inspected. So the analysed bytes and the recorded sha are the
+ * same object, always.
+ *
+ * When the worktree has since diverged, only the index version is vouched for.
+ * A subsequent `git commit -a` would take the worktree, which the enforcer then
+ * finds uncovered and blocks — clearable with `git add` and a re-run.
+ */
+async function committedVersion(path, cwd, source = 'index') {
+    const { execFileSync } = await import('child_process');
+    const opts = {
+        cwd,
+        env: gitEnv(),
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+    };
+    const v = await fileVersions(path, cwd);
+    // `commit -a` / `--all` stores the worktree; everything else the index. The
+    // GATE decides which and tells us, so the bytes examined here are the bytes
+    // that command will store — no inference, no drift.
+    const preferWorktree = source === 'worktree';
+    if (!preferWorktree && v.index) {
+        try {
+            const content = execFileSync('git', ['cat-file', 'blob', v.index], {
+                ...opts,
+                maxBuffer: 32 * 1024 * 1024,
+            });
+            return { sha: v.index, content };
+        }
+        catch {
+            return { sha: v.index, content: null };
+        }
+    }
+    if (v.worktree) {
+        const abs = isAbsolute(path) ? path : join(cwd, path);
+        try {
+            return { sha: v.worktree, content: readFileSync(abs, 'utf-8') };
+        }
+        catch {
+            return { sha: v.worktree, content: null };
+        }
+    }
+    return { sha: '', content: null };
+}
+async function hashFiles(paths, cwd, source = 'index') {
+    if (paths.length === 0)
+        return [];
+    const out = [];
+    for (const path of paths) {
+        // The source's OWN blob, with no cross-source fallback.
+        // committedVersion falls back to the worktree when the index has no entry,
+        // which is right for choosing bytes to analyse but wrong as an identity
+        // claim: for `git rm --cached x` it reported the worktree sha for a path
+        // the index no longer holds, so the gate's sha comparison disagreed and a
+        // precisely-detected staged deletion decayed into "could not answer".
+        // Empty means "this source holds nothing here" — itself a fact the gate
+        // needs, since that is exactly what a deletion looks like.
+        const v = await fileVersions(path, cwd);
+        out.push({ path, sha: source === 'worktree' ? v.worktree : v.index });
+    }
+    return out;
+}
+export async function diffFileSchema(filePath, baseBranch = 'HEAD~1', cwd = process.cwd(), source = 'index') {
     const changes = [];
+    const isSql = filePath.endsWith('.sql');
+    // False until an analyser proves otherwise. Every early exit and the outer
+    // catch therefore report "not analysed", which the gate treats as uncovered
+    // rather than as clean.
+    let analysed = false;
     try {
         // Get the "before" version from git
         let beforeContent;
+        let hasBaseline = true;
         try {
             // execFileSync with an argv array: the old template string ran through a
             // shell, and `filePath` comes straight from `git diff --name-only`, which
@@ -144,8 +448,13 @@ export async function diffFileSchema(filePath, baseBranch = 'HEAD~1', cwd = proc
             });
         }
         catch {
-            // File didn't exist before — all fields are new (non-breaking)
-            return { file: filePath, changes: [], breaking: false };
+            // No previous version. Adding fields to something that did not exist
+            // cannot break a reader of the OLD schema -- but the file's own
+            // statements still can, and a new migration is where they usually live.
+            // Returning "no changes" here is what cleared a brand-new
+            // migrations/002.sql whose entire content was DROP TABLE users;.
+            beforeContent = '';
+            hasBaseline = false;
         }
         // Get the "after" version from working tree
         // Resolved against the run's cwd: `git diff --name-only` emits
@@ -153,8 +462,33 @@ export async function diffFileSchema(filePath, baseBranch = 'HEAD~1', cwd = proc
         // every file look DELETED when run from a subdirectory — reporting
         // breaking:true for each and blocking the very commit it was asked to
         // clear. (join() leaves an absolute path untouched.)
+        // Analyse the version that will be COMMITTED (index-preferred), so the
+        // bytes inspected here are the same object whose sha the marker records.
+        // Reading the worktree while recording the index — or the reverse — is how
+        // a marker ends up vouching for bytes nothing looked at.
+        const committed = await committedVersion(filePath, cwd, source);
         const absPath = isAbsolute(filePath) ? filePath : join(cwd, filePath);
-        if (!existsSync(absPath)) {
+        // A path removed from the INDEX is a staged deletion even though the
+        // worktree copy is still sitting there. committedVersion falls back to the
+        // worktree when the index has no entry, so `git rm --cached x` was
+        // analysed as "worktree vs HEAD: unchanged" -- clean -- while the commit
+        // removed the file. Verified.
+        if (hasBaseline && source === 'index' && !(await fileVersions(filePath, cwd)).index) {
+            return {
+                file: filePath,
+                changes: [
+                    {
+                        type: 'removed',
+                        path: filePath,
+                        description: `File "${filePath}" was removed from the index (staged deletion)`,
+                        breaking: true,
+                    },
+                ],
+                breaking: true,
+                analysed: true,
+            };
+        }
+        if (committed.content === null && !existsSync(absPath)) {
             // File was deleted — all fields removed (breaking)
             return {
                 file: filePath,
@@ -167,11 +501,28 @@ export async function diffFileSchema(filePath, baseBranch = 'HEAD~1', cwd = proc
                     },
                 ],
                 breaking: true,
+                analysed: true,
             };
         }
-        const afterContent = readFileSync(absPath, 'utf-8');
+        const afterContent = committed.content ?? readFileSync(absPath, 'utf-8');
+        // Statements that are breaking on their own terms, baseline or not.
+        const before = new Set(hasBaseline ? destructiveDdl(beforeContent) : []);
+        for (const stmt of destructiveDdl(afterContent)) {
+            if (before.has(stmt))
+                continue; // already in the base; not new here
+            changes.push({
+                type: 'removed',
+                path: filePath,
+                description: `Destructive statement: ${stmt}`,
+                breaking: true,
+            });
+        }
         // Detect schema type and extract fields
+        let understood = isSql; // .sql is covered: CREATE TABLE diff + DDL scan
         if (filePath.endsWith('.ts') || filePath.endsWith('.js')) {
+            // Only meaningful against a baseline -- there is no TS analogue of the
+            // DDL scan, so a new file tells us nothing about what it breaks.
+            understood = hasBaseline;
             // Check for Zod schemas
             if (beforeContent.includes('z.object') || afterContent.includes('z.object')) {
                 const beforeFields = extractZodFields(beforeContent);
@@ -188,14 +539,14 @@ export async function diffFileSchema(filePath, baseBranch = 'HEAD~1', cwd = proc
             if (beforeContent.includes('CREATE TABLE') || afterContent.includes('CREATE TABLE')) {
                 const beforeCols = extractSQLiteColumns(beforeContent);
                 const afterCols = extractSQLiteColumns(afterContent);
-                changes.push(...diffFields(beforeCols, afterCols, 'sqlite'));
+                changes.push(...rescoreSqlAdditions(diffFields(beforeCols, afterCols, 'sqlite'), afterContent, 'sqlite'));
             }
         }
         // SQL files
         if (filePath.endsWith('.sql')) {
             const beforeCols = extractSQLiteColumns(beforeContent);
             const afterCols = extractSQLiteColumns(afterContent);
-            changes.push(...diffFields(beforeCols, afterCols, 'sql'));
+            changes.push(...rescoreSqlAdditions(diffFields(beforeCols, afterCols, 'sql'), afterContent, 'sql'));
         }
         // JSON schema files
         if (filePath.endsWith('.json') &&
@@ -203,6 +554,7 @@ export async function diffFileSchema(filePath, baseBranch = 'HEAD~1', cwd = proc
             try {
                 const beforeObj = JSON.parse(beforeContent);
                 const afterObj = JSON.parse(afterContent);
+                understood = hasBaseline;
                 const flatBefore = flattenObject(beforeObj);
                 const flatAfter = flattenObject(afterObj);
                 const beforeKeys = new Map(Object.keys(flatBefore).map((k) => [k, typeof flatBefore[k]]));
@@ -210,17 +562,21 @@ export async function diffFileSchema(filePath, baseBranch = 'HEAD~1', cwd = proc
                 changes.push(...diffFields(beforeKeys, afterKeys, 'json'));
             }
             catch {
-                // Not valid JSON
+                // Not valid JSON — say so rather than reporting a clean parse.
+                understood = false;
             }
         }
+        analysed = understood;
     }
     catch {
-        // Git or file read error
+        // Git or file read error. `analysed` stays false: the gate must not read a
+        // failed read as an all-clear.
     }
     return {
         file: filePath,
         changes,
         breaking: changes.some((c) => c.breaking),
+        analysed,
     };
 }
 /**
@@ -266,8 +622,37 @@ async function baseResolves(base, cwd) {
         return false;
     }
 }
+/**
+ * What the GATE watches — kept identical to WATCHED_RE in
+ * src/policies/enforcers/schema_diff_gate.py.
+ *
+ * The two sets must agree, because the gate now demands that every watched path
+ * be covered by the marker, and only paths this CLI EXAMINES get into the
+ * marker. When the gate watched a superset, the difference was a permanent
+ * deadlock: `infra/helm_charts/pgdog/values.yaml` matched none of the filters
+ * below, so it could never be recorded, and the refusal told the operator to
+ * re-run a command that produced the identical marker. Verified before the fix.
+ *
+ * These files are hashed and recorded even though diffFileSchema cannot parse
+ * YAML — coverage is about "these bytes were seen", which is exactly the claim
+ * the marker needs to support. Any change to the enforcer's WATCHED_RE must be
+ * mirrored here; test/cli/gate-watched-mirror.test.ts pins that.
+ */
+export // `s` (dotAll) so `.` spans a newline: a path may legally contain one, and
+ 
+// without the flag `migrations/a\nb.sql` matched nothing — the gate did not
+// consider it watched at all, and a column drop in it was never examined.
+const GATE_WATCHED_RE = /(migrations\/.*\.sql|infra\/postgres-spock\/|infra\/helm_charts\/[^/]*pgdog|infra\/helm_charts\/[^/]*cnpg|infra\/helm_charts\/[^/]*redis|infra\/helm_charts\/[^/]*envoy|infra\/helm_charts\/[^/]*sentinel)/is;
 /** git's empty tree — diffing against it means "every tracked file is new". */
 const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+/**
+ * Version of the --json verdict shape.
+ *
+ * Bump on any change to the fields the gate reads. The gate refuses a contract
+ * it does not recognise and falls back rather than guessing, so an old gate
+ * paired with a new CLI degrades instead of misreading.
+ */
+export const SCHEMA_DIFF_CONTRACT = 1;
 export async function runSchemaDiff(baseBranch = 'HEAD~1', cwd = process.cwd(), 
 /**
  * True when the caller did not pass -b, i.e. `HEAD~1` is our default rather
@@ -280,7 +665,8 @@ export async function runSchemaDiff(baseBranch = 'HEAD~1', cwd = process.cwd(),
  * commit with no waiver and no override — verified. Falling back
  * unconditionally would instead resurrect the stamp for `-b typo`.
  */
-baseIsDefault = false) {
+baseIsDefault = false, opts = {}) {
+    const { only, source = 'index', quiet = false } = opts;
     const results = [];
     let examined = [];
     let ran = false;
@@ -323,7 +709,8 @@ baseIsDefault = false) {
             return { ran, examined, effectiveBase, results };
         }
         // Filter to schema-relevant files
-        const schemaFiles = changedFiles.filter((f) => f.includes('schema') ||
+        const schemaFiles = changedFiles.filter((f) => GATE_WATCHED_RE.test(f) ||
+            f.includes('schema') ||
             f.includes('types') ||
             f.includes('config') ||
             f.includes('database') ||
@@ -335,26 +722,46 @@ baseIsDefault = false) {
                     f.includes('memory/short-term/schema') ||
                     f.includes('tasks/database') ||
                     f.includes('tasks/types'))));
+        // `only` REPLACES this enumeration rather than intersecting it. The list
+        // above comes from `git diff --name-only <base>`, which compares the
+        // WORKTREE — so a staged-only change whose worktree copy still matches the
+        // base does not appear in it at all. Intersecting would have dropped
+        // exactly those paths, handed the gate an empty `examined`, and let the
+        // staged change through as "covered": the same class of hole as verifying
+        // the index while `-a` commits the worktree. The gate derives its watched
+        // set from the source it is about to commit, and it is authoritative.
+        const scopedFiles = only ? [...new Set(only)] : schemaFiles;
         // Past this point git has produced a real file list, so the run is genuine
         // even if nothing schema-relevant changed.
         ran = true;
-        examined = schemaFiles;
-        for (const file of schemaFiles) {
-            const result = await diffFileSchema(file, effectiveBase, cwd);
-            if (result.changes.length > 0) {
-                results.push(result);
-            }
+        // Hash what we are about to read, so the marker binds to content. Batched
+        // in one process rather than one per file: this runs inside a gate remedy.
+        examined = await hashFiles(scopedFiles, cwd, source);
+        for (const file of scopedFiles) {
+            const result = await diffFileSchema(file, effectiveBase, cwd, source);
+            // Every examined path gets a result, not just the ones with changes: the
+            // gate needs `analysed` for the quiet ones too, and "absent from the
+            // list" is precisely the ambiguity between "clean" and "never looked at"
+            // that this change exists to remove. The human report still prints only
+            // files with changes.
+            results.push(result);
+        }
+        // Print results. In --json mode the verdict IS the output: a stray human
+        // line here would break the gate's JSON parse, and a gate that cannot read
+        // its checker falls back to allow-with-warning — silently unarmed.
+        const changed = results.filter((r) => r.changes.length > 0);
+        if (quiet) {
+            // caller renders the verdict
         }
-        // Print results
-        if (results.length === 0) {
+        else if (changed.length === 0) {
             console.log('No schema changes detected.');
         }
         else {
-            const hasBreaking = results.some((r) => r.breaking);
-            console.log(`\nSchema Diff Results (${results.length} files with changes):`);
+            const hasBreaking = changed.some((r) => r.breaking);
+            console.log(`\nSchema Diff Results (${changed.length} files with changes):`);
             console.log(hasBreaking ? '  BREAKING CHANGES DETECTED' : '  No breaking changes');
             console.log('');
-            for (const result of results) {
+            for (const result of changed) {
                 console.log(`  ${result.breaking ? 'BREAKING' : 'OK'} ${result.file}`);
                 for (const change of result.changes) {
                     const icon = change.breaking ? '  !!!' : '     ';
@@ -387,11 +794,36 @@ baseIsDefault = false) {
 /** Bounded rendering: one branch touching hundreds of schema files otherwise
  *  writes a multi-kilobyte row into the shared short-term store, at high
  *  importance, where it crowds out real context and survives pruning. */
+/**
+ * How many `path@sha` entries a marker may carry before it degrades to a
+ * legacy (time-only) marker.
+ *
+ * Content scoping needs EVERY examined path in the marker — a truncated list
+ * would leave the omitted paths uncovered and block them with no way for the
+ * operator to produce a covering marker. Rather than deadlock, an oversized
+ * change records `(truncated)` and the gate falls back to time-only. 100
+ * entries is roughly 5KB, above any realistic schema change and well under the
+ * size where one memory row starts crowding recall.
+ */
+const MAX_MARKER_ENTRIES = 100;
+/** Marker rendering. `path@sha7` is what makes a pass content-scoped. */
 function fileList(examined) {
     if (examined.length === 0)
         return '(none changed)';
-    const head = examined.slice(0, 20).join(',');
-    return examined.length > 20 ? `${head} (+${examined.length - 20} more)` : head;
+    if (examined.length > MAX_MARKER_ENTRIES) {
+        return `(truncated: ${examined.length} files)`;
+    }
+    return examined
+        .map((f) => {
+        // A path containing the delimiters can forge a second, parsable entry:
+        // a file named `xschema@<40hex>,migrations/002.sql@<benign sha>` parses
+        // into a bogus coverage claim for 002.sql that overwrites the real one.
+        // Such a path is recorded WITHOUT identity, so the enforcer treats that
+        // one path as uncovered instead of trusting an attacker-built entry.
+        const safe = !f.path.includes(',') && !f.path.includes('@');
+        return f.sha && safe ? `${f.path}@${f.sha}` : f.path;
+    })
+        .join(',');
 }
 export async function recordSchemaDiffPass(baseBranch, examined, cwd = process.cwd()) {
     try {
@@ -457,11 +889,74 @@ export function registerSchemaDiffCommand(program) {
         // No commander default: an omitted -b must be distinguishable from an
         // explicit one, because only the default may fall back to the empty tree.
         .option('-b, --base <branch>', 'Base branch/commit to compare against (default: HEAD~1)')
+        // --- the inline-gate contract -------------------------------------------
+        // The enforcer calls this directly instead of hunting for a marker written
+        // by some earlier run. That deletes an entire class of defect: a stored
+        // verdict can be stale, forged, truncated, format-drifted, scoped to a
+        // different file set, or written by another worktree — and every one of
+        // those actually happened here. A verdict computed now, over the exact
+        // paths the gate is about to allow, can be none of them.
+        .option('--json', 'Emit a machine-readable verdict for the gate (implies no marker write)')
+        .option('--paths-from <file>', 'Read NUL-separated paths from a file. Preferred over --paths: a comma or ' +
+        'newline in a filename cannot corrupt the list, and git C-quotes such ' +
+        'names in --name-only output, which made the checker examine a path ' +
+        'that does not exist and report it clean.')
+        .option('--paths <csv>', 'Restrict the check to these paths. The GATE passes its own watched set, ' +
+        'so the checker and the gate can never disagree about what was examined.')
+        .option('--source <which>', 'Which bytes to examine: "index" (what `git commit` stores) or "worktree" (what `commit -a` stores)')
         .action(async (options) => {
         const baseIsDefault = options.base === undefined;
         const base = options.base ?? 'HEAD~1';
-        const run = await runSchemaDiff(base, process.cwd(), baseIsDefault);
+        // No trimming on this path: a leading or trailing space is part of the
+        // filename, and silently trimming it produced a path the checker could
+        // not open while the gate still counted it as covered.
+        const only = options.pathsFrom
+            ? readFileSync(options.pathsFrom, 'utf-8').split('\0').filter(Boolean)
+            : options.paths
+                ? options.paths.split(',').map((p) => p.trim()).filter(Boolean)
+                : undefined;
+        const run = await runSchemaDiff(base, process.cwd(), baseIsDefault, {
+            only,
+            source: options.source === 'worktree' ? 'worktree' : 'index',
+            quiet: Boolean(options.json),
+        });
         const hasBreaking = run.results.some((r) => r.breaking);
+        if (options.json) {
+            // The gate reads THIS, not an exit code: exit 1 conflates "breaking
+            // change found" with "the run never happened", and those must lead to
+            // opposite decisions (block vs fall back).
+            //
+            // One entry per requested path, each carrying the evidence the gate
+            // needs to decide whether to believe it:
+            //   sha       the blob actually read. The gate re-derives it and
+            //             compares. Without it the old `examined` was a list of
+            //             the gate's own argument echoed back -- it could only
+            //             fail on a whitespace artefact, never on "nothing was
+            //             read", which is exactly the case it existed to catch.
+            //   analysed  whether any analyser understood the file at all. An
+            //             empty `breaking` from a helm chart is not an all-clear.
+            // `contract` lets a future gate refuse a shape it does not know
+            // instead of misreading it.
+            const byPath = new Map(run.results.map((r) => [r.file, r]));
+            console.log(JSON.stringify({
+                contract: SCHEMA_DIFF_CONTRACT,
+                ran: run.ran,
+                base: run.effectiveBase,
+                files: run.examined.map((f) => {
+                    const r = byPath.get(f.path);
+                    return {
+                        path: f.path,
+                        sha: f.sha,
+                        analysed: r ? r.analysed : false,
+                        breaking: r
+                            ? r.changes.filter((c) => c.breaking).map((c) => c.description)
+                            : [],
+                    };
+                }),
+            }));
+            process.exitCode = hasBreaking ? 1 : 0;
+            return;
+        }
         if (hasBreaking) {
             console.log('\nBreaking changes require explicit approval before proceeding.');
             process.exitCode = 1;