vouchington-tooling 0.38.0 → 0.39.0

package/README.md

@@ -698,14 +698,17 @@ lifecycle decisions.
 
 ## SQL index shapes
 
-`vouchington-tooling/sql-ast` exports `extractIndexShapes(sql)`. Await `initSqlAst()` before
-calling it. It returns `{ idxname, table, shapeKey }` for each named top-level `CREATE INDEX`.
-Consumers can group identical `shapeKey` values to find differently named index definitions
-with the same projected physical shape. The key normalizes effective sort and null ordering and
-removes parser locations from expressions and predicates. Invalid SQL throws. Anonymous indexes
-and indexes inside `DO` blocks are omitted. The projection does not model operator classes,
-collations, or `INCLUDE` columns, so callers using those features must extend it before relying
-on shape collisions.
+`vouchington-tooling/sql-ast` exports asynchronous `extractIndexShapes(sql)`. Await its result;
+it lazily loads the optional `no-mistakes` peer and requires version 0.81.0 or newer when
+called with nonblank SQL. Other SQL exports do not require this peer. It does not need
+`initSqlAst()`. It returns
+`{ idxname, table, shapeKey }` for each named top-level `CREATE INDEX`. Consumers can group
+identical keys to detect collisions. Keys use upstream structural identity, including effective
+sort/null ordering, quoted relation identity, expressions, predicates, operator classes, and
+`INCLUDE` columns. Key serialization is opaque and must not be persisted across versions.
+Any parse diagnostic rejects the whole input. Anonymous indexes and indexes inside `DO` blocks
+are omitted. Consumer call sites must change from synchronous calls to `await` when adopting
+this release.
 
 ## Publication writer inventory facts
 

package/dist/index.d.mts

@@ -12,8 +12,8 @@ export { buildSessionFrictionReport, classifyFrictionObservation, FRICTION_LOG_M
 export type { FrictionEvent, FrictionEventKind, FrictionLogOptions, FrictionLogReadResult, FrictionObservation, JournalEntry, JournalLoader, JournalLoadResult, PermissionRequestObservation, SessionFrictionReport, SessionFrictionReportOptions, ToolResultObservation, } from './session-friction/index.mts';
 export { EphemeralListenerAttemptsExhaustedError, isRunnerReservedPort, listenOnRunnerUnreservedEphemeralPort, loadRunnerPortPolicy, runnerPortPolicy, validateRunnerPortPolicy, } from './runner-port-policy/index.mts';
 export type { EphemeralListenerOptions, RunnerPortPolicy } from './runner-port-policy/index.mts';
-export { extractCreateIndexMetadata, extractCreateTableMetadata, extractDefaultFunction, extractFuncCallArgColumnNames, extractMigrationConstraintMetadata, initSqlAst, lineOfUtf8ByteOffset, MissingSqlAstParserError, parseSql, } from './sql-ast/index.mts';
-export type { ForeignKey, SqlCreateIndexMetadata, SqlCreateTableColumn, SqlCreateTableMetadata, SqlIndexParam, SqlMigrationConstraintMetadata, } from './sql-ast/index.mts';
+export { extractCreateTableMetadata, extractDefaultFunction, extractFuncCallArgColumnNames, initSqlAst, lineOfUtf8ByteOffset, MissingSqlAstParserError, parseSql, } from './sql-ast/index.mts';
+export type { SqlCreateTableColumn, SqlCreateTableMetadata } from './sql-ast/index.mts';
 export { dollarQuoteEnd, lineOf, maskSqlQuotedText, readDollarQuoteDelimiter, readStringLiteral, splitSqlStatements, sqlFragments, stripSqlComments, } from './sql-scanner/index.mts';
 export { auditCiJobRuntime, parseWorkflowNameMatch } from './gha-runtime-audit/index.mts';
 export type { GhApiExecutor, RuntimeAuditOptions, RuntimeAuditResult, RuntimeAuditWorkflowFilter, RuntimeJobResult, RuntimeSample, } from './gha-runtime-audit/index.mts';

package/dist/index.mjs

@@ -6,7 +6,7 @@ export { runRetrospectiveFacts } from "./retrospective-facts/index.mjs";
 export { appendJournal, assertSessionId, cleanupSnapshotPartitions, partitionSnapshot, probeBlackboard, readJournal, resolveBlackboardConnection, } from "./agent-blackboard/index.mjs";
 export { buildSessionFrictionReport, classifyFrictionObservation, FRICTION_LOG_MAX_EVENTS, isConformingCiFailureBlock, normalizeCommandPrefix, readFrictionLog, recordFriction, } from "./session-friction/index.mjs";
 export { EphemeralListenerAttemptsExhaustedError, isRunnerReservedPort, listenOnRunnerUnreservedEphemeralPort, loadRunnerPortPolicy, runnerPortPolicy, validateRunnerPortPolicy, } from "./runner-port-policy/index.mjs";
-export { extractCreateIndexMetadata, extractCreateTableMetadata, extractDefaultFunction, extractFuncCallArgColumnNames, extractMigrationConstraintMetadata, initSqlAst, lineOfUtf8ByteOffset, MissingSqlAstParserError, parseSql, } from "./sql-ast/index.mjs";
+export { extractCreateTableMetadata, extractDefaultFunction, extractFuncCallArgColumnNames, initSqlAst, lineOfUtf8ByteOffset, MissingSqlAstParserError, parseSql, } from "./sql-ast/index.mjs";
 export { dollarQuoteEnd, lineOf, maskSqlQuotedText, readDollarQuoteDelimiter, readStringLiteral, splitSqlStatements, sqlFragments, stripSqlComments, } from "./sql-scanner/index.mjs";
 export { auditCiJobRuntime, parseWorkflowNameMatch } from "./gha-runtime-audit/index.mjs";
 export { checkGhaWorkspacePolicy } from "./gha-workspace-policy/index.mjs";

package/dist/pg-schema-snapshot/index.d.mts

@@ -4,7 +4,7 @@ export type { CatalogColumnRow, CatalogConstraintRow, CatalogEnumValueRow, Catal
 export { generateSchemaSnapshot, stableStringify, writeSchemaSnapshot } from './generate.mts';
 export { detectRenamedIndexes, indexShapeKey } from './index-rename-detect.mts';
 export type { RenamedIndex, SchemaIndexRenameSnapshot } from './index-rename-detect.mts';
-export { createPostgresReplayContext } from './replay-context.mts';
+export { createPostgresReplayContext, createPostgresReplayContextFromSchema, } from './replay-context.mts';
 export type { GeneratedColumnReferences, PostgresReplayContext } from './replay-context.mts';
 export { renderSchemaMarkdown } from './render-markdown.mts';
 export type { SchemaMarkdownFiles } from './render-markdown.mts';

package/dist/pg-schema-snapshot/index.mjs

@@ -2,6 +2,6 @@ export { buildSchemaSnapshot, buildTableSnapshots } from "./build-snapshot.mjs";
 export { readColumns, readConstraints, readEnums, readExtensions, readFunctions, readIndexes, readPolicies, readSchemaCatalog, readTables, readTriggers, readViews, } from "./catalog-queries.mjs";
 export { generateSchemaSnapshot, stableStringify, writeSchemaSnapshot } from "./generate.mjs";
 export { detectRenamedIndexes, indexShapeKey } from "./index-rename-detect.mjs";
-export { createPostgresReplayContext } from "./replay-context.mjs";
+export { createPostgresReplayContext, createPostgresReplayContextFromSchema, } from "./replay-context.mjs";
 export { renderSchemaMarkdown } from "./render-markdown.mjs";
 export { renderTableDocument } from "./render-tables.mjs";

package/dist/pg-schema-snapshot/replay-context.d.mts

@@ -11,6 +11,8 @@ export type PostgresReplayContext = {
     /** Memoized per table; unknown tables return undefined and empty dependency sets return an empty map. */
     generatedDependenciesForTable(table: string): ReadonlyMap<string, ReadonlySet<string>> | undefined;
 };
+/** Collects generated-expression facts with the optional SQL peer, once per snapshot. */
+export declare function createPostgresReplayContextFromSchema(schema: SchemaSnapshot): Promise<PostgresReplayContext>;
 /**
  * Projects injected schema snapshot data and parser-derived generated-expression references for
  * replay checks. The caller owns snapshot loading and SQL parsing. Every STORED generated column

package/dist/pg-schema-snapshot/replay-context.mjs

@@ -1,3 +1,38 @@
+import { loadPostgresParser } from "../sql-ast/no-mistakes-peer.mjs";
+/** Collects generated-expression facts with the optional SQL peer, once per snapshot. */
+export async function createPostgresReplayContextFromSchema(schema) {
+    const definitions = Object.entries(schema.tables).flatMap(([table, snapshotTable]) => Object.entries(snapshotTable.columns).flatMap(([column, definition]) => definition.generated === 'stored' && definition.generatedExpression !== null
+        ? [{ table, column, expression: definition.generatedExpression }]
+        : []));
+    if (definitions.length === 0) {
+        return createPostgresReplayContext({ schema, generatedColumnReferences: [] });
+    }
+    const { parsePostgresSql } = await loadPostgresParser('createPostgresReplayContextFromSchema');
+    const parsed = await parsePostgresSql(definitions.map(({ table, column, expression }) => ({
+        sql: `SELECT (${expression})`,
+        fileName: `schema-snapshot:${table}.${column}`,
+    })));
+    const generatedColumnReferences = definitions.map(({ table, column }, index) => {
+        const facts = parsed[index];
+        const statement = facts?.statements[0];
+        if (!facts ||
+            facts.diagnostics.length > 0 ||
+            facts.statements.length !== 1 ||
+            statement?.kind !== 'select' ||
+            !statement.query.complete ||
+            statement.query.unsupported.length > 0) {
+            throw new Error(`Unable to collect generated-column references for ${table}.${column}`);
+        }
+        return {
+            table,
+            column,
+            sourceColumns: [
+                ...new Set(statement.query.columns.map((reference) => reference.name.parts.at(-1).identity)),
+            ],
+        };
+    });
+    return createPostgresReplayContext({ schema, generatedColumnReferences });
+}
 /**
  * Projects injected schema snapshot data and parser-derived generated-expression references for
  * replay checks. The caller owns snapshot loading and SQL parsing. Every STORED generated column

package/dist/sql-ast/index-shapes.d.mts

@@ -1,34 +1,11 @@
 /**
- * Extracts a canonical "shape key" for every top-level CREATE INDEX statement in the given SQL,
- * for detecting index definitions that build the same physical index under different names.
- *
- * The key is built from normalized `IndexStmt` AST fields (table, uniqueness, access method, each
- * indexed column/expression with its *effective* sort order and null ordering, and the predicate
- * with position-dependent `location` fields stripped) rather than from raw source text. This
- * canonicalizes cosmetic syntax variance that leaves the physical index unchanged:
- * - implicit vs. explicit `ASC` (`SORTBY_DEFAULT` is normalized to `SORTBY_ASC`, PostgreSQL's
- *   actual default for btree ordering);
- * - implicit vs. explicit `NULLS FIRST`/`NULLS LAST` (PostgreSQL's real default depends on sort
- *   direction — `NULLS LAST` for ascending, `NULLS FIRST` for descending — so
- *   `SORTBY_NULLS_DEFAULT` is resolved against the effective ordering rather than compared as-is);
- * - redundant parentheses in a predicate or expression (parentheses are pure grouping and leave no
- *   trace in the parsed AST once `location` offsets — which shift under added parens even though
- *   the tree shape is unchanged — are stripped before comparison).
- *
- * Operator classes, collations, and INCLUDE columns are intentionally NOT modeled; callers whose
- * generators use them must extend the projection before using this collision policy for those SQL.
- *
- * @libpg-query/parser has no deparse/SQL-regeneration function, so this hashes a normalized JSON
- * projection of the relevant AST subtrees instead of reconstructing SQL text.
- *
- * DO $$ ... END $$; blocks are opaque to the top-level parser — they appear as a single DoStmt,
- * not individual IndexStmt nodes — so nested CREATE INDEX statements are not covered.
- *
- * Unparseable SQL throws rather than returning an empty shape list.
- * Requires initSqlAst() to have resolved before the first call.
+ * Returns collision keys for named top-level CREATE INDEX statements using released SQL facts.
+ * Effective ordering, expressions, predicates, operator classes, and INCLUDE columns participate
+ * in the upstream structural identity. DO blocks remain opaque to this top-level projection.
+ * Any parse diagnostic rejects the complete input instead of returning partial collision facts.
  */
-export declare function extractIndexShapes(sql: string): {
+export declare function extractIndexShapes(sql: string): Promise<{
     idxname: string;
     table: string;
     shapeKey: string;
-}[];
+}[]>;

package/dist/sql-ast/index-shapes.mjs

@@ -1,85 +1,28 @@
-import { parseSql } from "./parser.mjs";
+import { loadPostgresParser } from "./no-mistakes-peer.mjs";
 /**
- * Extracts a canonical "shape key" for every top-level CREATE INDEX statement in the given SQL,
- * for detecting index definitions that build the same physical index under different names.
- *
- * The key is built from normalized `IndexStmt` AST fields (table, uniqueness, access method, each
- * indexed column/expression with its *effective* sort order and null ordering, and the predicate
- * with position-dependent `location` fields stripped) rather than from raw source text. This
- * canonicalizes cosmetic syntax variance that leaves the physical index unchanged:
- * - implicit vs. explicit `ASC` (`SORTBY_DEFAULT` is normalized to `SORTBY_ASC`, PostgreSQL's
- *   actual default for btree ordering);
- * - implicit vs. explicit `NULLS FIRST`/`NULLS LAST` (PostgreSQL's real default depends on sort
- *   direction — `NULLS LAST` for ascending, `NULLS FIRST` for descending — so
- *   `SORTBY_NULLS_DEFAULT` is resolved against the effective ordering rather than compared as-is);
- * - redundant parentheses in a predicate or expression (parentheses are pure grouping and leave no
- *   trace in the parsed AST once `location` offsets — which shift under added parens even though
- *   the tree shape is unchanged — are stripped before comparison).
- *
- * Operator classes, collations, and INCLUDE columns are intentionally NOT modeled; callers whose
- * generators use them must extend the projection before using this collision policy for those SQL.
- *
- * @libpg-query/parser has no deparse/SQL-regeneration function, so this hashes a normalized JSON
- * projection of the relevant AST subtrees instead of reconstructing SQL text.
- *
- * DO $$ ... END $$; blocks are opaque to the top-level parser — they appear as a single DoStmt,
- * not individual IndexStmt nodes — so nested CREATE INDEX statements are not covered.
- *
- * Unparseable SQL throws rather than returning an empty shape list.
- * Requires initSqlAst() to have resolved before the first call.
+ * Returns collision keys for named top-level CREATE INDEX statements using released SQL facts.
+ * Effective ordering, expressions, predicates, operator classes, and INCLUDE columns participate
+ * in the upstream structural identity. DO blocks remain opaque to this top-level projection.
+ * Any parse diagnostic rejects the complete input instead of returning partial collision facts.
  */
-export function extractIndexShapes(sql) {
+export async function extractIndexShapes(sql) {
     if (!sql.trim())
         return [];
-    const result = parseSql(sql);
-    const shapes = [];
-    for (const stmt of result.stmts ?? []) {
-        const node = stmt.stmt;
-        if (!node || !('IndexStmt' in node))
-            continue;
-        const indexStmt = node.IndexStmt;
-        const idxname = indexStmt.idxname;
-        if (!idxname)
-            continue;
-        const table = indexStmt.relation?.relname ?? '';
-        const canonical = {
-            table,
-            unique: Boolean(indexStmt.unique),
-            accessMethod: indexStmt.accessMethod ?? 'btree',
-            indexParams: (indexStmt.indexParams ?? []).map(normalizeIndexParam),
-            whereClause: indexStmt.whereClause ? stripLocations(indexStmt.whereClause) : null,
-        };
-        shapes.push({ idxname, table, shapeKey: JSON.stringify(canonical) });
+    const { parsePostgresSql } = await loadPostgresParser('extractIndexShapes');
+    const facts = await parsePostgresSql({ sql });
+    if (facts.diagnostics.length > 0) {
+        throw new Error(`SQL syntax error: ${facts.diagnostics.map(({ message }) => message).join('; ')}`);
     }
-    return shapes;
-}
-function normalizeIndexParam(param) {
-    if (!('IndexElem' in param))
-        return stripLocations(param);
-    const elem = param.IndexElem;
-    const ordering = elem.ordering === undefined || elem.ordering === 'SORTBY_DEFAULT' ? 'SORTBY_ASC' : elem.ordering;
-    const nullsOrdering = elem.nulls_ordering === undefined || elem.nulls_ordering === 'SORTBY_NULLS_DEFAULT'
-        ? ordering === 'SORTBY_DESC'
-            ? 'SORTBY_NULLS_FIRST'
-            : 'SORTBY_NULLS_LAST'
-        : elem.nulls_ordering;
-    return {
-        key: elem.name ?? stripLocations(elem.expr),
-        ordering,
-        nullsOrdering,
-    };
-}
-function stripLocations(value) {
-    if (Array.isArray(value))
-        return value.map(stripLocations);
-    if (value && typeof value === 'object') {
-        const out = {};
-        for (const [key, val] of Object.entries(value)) {
-            if (key === 'location')
-                continue;
-            out[key] = stripLocations(val);
-        }
-        return out;
-    }
-    return value;
+    return facts.statements.flatMap((statement) => {
+        if (statement.kind !== 'createIndex' || !statement.index.name)
+            return [];
+        const { index } = statement;
+        return [
+            {
+                idxname: index.name.parts.at(-1).value,
+                table: index.table.parts.at(-1).value,
+                shapeKey: index.structuralIdentity,
+            },
+        ];
+    });
 }

package/dist/sql-ast/index.d.mts

@@ -1,11 +1,7 @@
-export { extractMigrationConstraintMetadata } from './constraint.mts';
-export type { ForeignKey, SqlMigrationConstraintMetadata } from './constraint-shared.mts';
 export { extractCreateTableMetadata } from './create-table.mts';
 export type { SqlCreateTableColumn, SqlCreateTableColumnConstraint, SqlCreateTableMetadata, } from './create-table.mts';
 export { extractDefaultFunction, extractFuncCallArgColumnNames } from './default-function.mts';
-export { extractCreateIndexMetadata } from './index-metadata.mts';
 export { extractIndexShapes } from './index-shapes.mts';
-export type { SqlCreateIndexMetadata, SqlIndexParam } from './index-metadata.mts';
 export { lineOfUtf8ByteOffset } from './line-of-offset.mts';
 export { initSqlAst, MissingSqlAstParserError, parseSql } from './parser.mts';
 export { extractViewDeclarations } from './view-declarations.mts';

package/dist/sql-ast/index.mjs

@@ -1,7 +1,5 @@
-export { extractMigrationConstraintMetadata } from "./constraint.mjs";
 export { extractCreateTableMetadata } from "./create-table.mjs";
 export { extractDefaultFunction, extractFuncCallArgColumnNames } from "./default-function.mjs";
-export { extractCreateIndexMetadata } from "./index-metadata.mjs";
 export { extractIndexShapes } from "./index-shapes.mjs";
 export { lineOfUtf8ByteOffset } from "./line-of-offset.mjs";
 export { initSqlAst, MissingSqlAstParserError, parseSql } from "./parser.mjs";

package/dist/sql-ast/no-mistakes-peer.d.mts

@@ -0,0 +1,86 @@
+export declare function loadPostgresParser(caller: string): Promise<{
+    default: typeof import("no-mistakes");
+    analyzeTypeScriptModules(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").TypeScriptModulesOptions>): Promise<import("no-mistakes").TypeScriptModulesReport>;
+    parsePostgresSql(source: import("no-mistakes").PostgresSqlSource): Promise<import("no-mistakes").PostgresSqlFacts>;
+    parsePostgresSql(sources: import("no-mistakes").PostgresSqlSource[]): Promise<import("no-mistakes").PostgresSqlFacts[]>;
+    dependencies(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").TraversePathsOptions>): Promise<import("no-mistakes").ImportClosureResult>;
+    dependencies(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").TraverseGraphOptions>): Promise<import("no-mistakes").DependencyResult>;
+    dependents(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").TraverseOptions>): Promise<import("no-mistakes").DependencyResult>;
+    related(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").TraverseOptions>): Promise<import("no-mistakes").DependencyResult>;
+    analyzeProject(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").AnalyzeProjectOptions>): Promise<import("no-mistakes").AnalyzeProjectResult>;
+    writePlanningImpactArtifacts(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").WritePlanningImpactArtifactsOptions>): Promise<import("no-mistakes").PlanningImpactArtifacts>;
+    symbols(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").SymbolsSignatureImpactOptions>): Promise<import("no-mistakes").SignatureImpactResult>;
+    symbols(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").SymbolsListOptions>): Promise<import("no-mistakes").SymbolsResult>;
+    symbols(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").SymbolsOptions>): Promise<import("no-mistakes").SymbolsResult | import("no-mistakes").SignatureImpactResult>;
+    importUsages(options?: import("no-mistakes").WithInvocationOptions<import("no-mistakes").ImportUsagesOptions>): Promise<import("no-mistakes").ImportUsagesResult>;
+    importers(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").ImportersOptions>): Promise<import("no-mistakes").ImportersResult>;
+    exportsOf(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").ExportsOfOptions>): Promise<import("no-mistakes").ExportsOfResult>;
+    deadExports(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").DeadExportsOptions>): Promise<import("no-mistakes").DeadExportsResult>;
+    callSites(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").CallSitesOptions>): Promise<import("no-mistakes").CallSitesResult>;
+    resolveCheck(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").ResolveCheckOptions>): Promise<import("no-mistakes").ResolveCheckResult>;
+    resolveCheck(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").ResolveCheckFilesOptions>): Promise<import("no-mistakes").ResolveCheckBatchResult>;
+    fetches(options?: import("no-mistakes").WithInvocationOptions<import("no-mistakes").FetchesOptions>): Promise<import("no-mistakes").FetchReport>;
+    flow(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").FlowOptions>): Promise<import("no-mistakes").FlowReport>;
+    check(options?: import("no-mistakes").WithInvocationOptions<import("no-mistakes").CheckOptions>): Promise<import("no-mistakes").CheckReport>;
+    resolveConfig(options?: import("no-mistakes").WithInvocationOptions<import("no-mistakes").ProjectOptions>): Promise<import("no-mistakes").ResolvedConfig>;
+    validateMermaidMarkdown(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").MermaidValidationOptions>): Promise<import("no-mistakes").MermaidValidationResult>;
+    testsPlan(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").TestsPlanOptions>): Promise<import("no-mistakes").TestPlan>;
+    testsImpact(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").TestsImpactOptions>): Promise<import("no-mistakes").TestPlan>;
+    testsTargets(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").TestsTargetsOptions>): Promise<import("no-mistakes").TestsTargetsReport>;
+    testsWhy(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").TestsWhyOptions>): Promise<Record<string, import("no-mistakes").WhyStep[]>>;
+    testsComment(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").TestsPlanDocumentOptions>): Promise<string>;
+    testsGraph(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").TestsPlanDocumentOptions>): Promise<import("no-mistakes").TestGraph>;
+    testsGraphMermaid(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").TestsPlanDocumentOptions>): Promise<string>;
+    playwrightCheck(options?: import("no-mistakes").WithInvocationOptions<import("no-mistakes").PlaywrightOptions>): Promise<unknown>;
+    playwrightEdges(options?: import("no-mistakes").WithInvocationOptions<import("no-mistakes").PlaywrightOptions>): Promise<unknown>;
+    playwrightRelated(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").PlaywrightRelatedOptions>): Promise<unknown>;
+    playwrightTests(options?: import("no-mistakes").WithInvocationOptions<import("no-mistakes").PlaywrightOptions>): Promise<unknown>;
+    queues(options?: import("no-mistakes").WithInvocationOptions<import("no-mistakes").ProjectOptions>): Promise<import("no-mistakes").QueueReport>;
+    queueEdges(options?: import("no-mistakes").WithInvocationOptions<import("no-mistakes").ProjectOptions>): Promise<import("no-mistakes").QueueEdge[]>;
+    queueRelated(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").ProjectOptions>): Promise<import("no-mistakes").QueueEdge[]>;
+    queueCheck(options?: import("no-mistakes").WithInvocationOptions<import("no-mistakes").ProjectOptions>): Promise<import("no-mistakes").QueueCheckFinding[]>;
+    serverRoutes(options?: import("no-mistakes").WithInvocationOptions<import("no-mistakes").ProjectOptions>): Promise<import("no-mistakes").ServerRoutesReport>;
+    serverRouteList(options?: import("no-mistakes").WithInvocationOptions<import("no-mistakes").ProjectOptions>): Promise<unknown[]>;
+    serverRouteEdges(options?: import("no-mistakes").WithInvocationOptions<import("no-mistakes").ProjectOptions>): Promise<import("no-mistakes").GraphEdge[]>;
+    serverRouteRelated(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").ProjectOptions>): Promise<import("no-mistakes").GraphEdge[]>;
+    serverContracts(options?: import("no-mistakes").WithInvocationOptions<import("no-mistakes").ProjectOptions>): Promise<import("no-mistakes").ServerContractsReport>;
+    reactAnalyze(options?: import("no-mistakes").WithInvocationOptions<import("no-mistakes").ProjectOptions>): Promise<import("no-mistakes").ReactComponentFacts[]>;
+    reactCheck(options?: import("no-mistakes").WithInvocationOptions<import("no-mistakes").ProjectOptions>): Promise<import("no-mistakes").ReactViolation[]>;
+    reactUsages(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").ProjectOptions & {
+        target: string;
+    }>): Promise<import("no-mistakes").ReactUsagesReport>;
+    generatePostgresCatalog(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").PostgresCatalogOptions & {
+        coverage: "ordering";
+    }>): Promise<import("no-mistakes").PostgresOrderingCatalog>;
+    generatePostgresCatalog(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").PostgresCatalogOptions & {
+        coverage?: "complete";
+    }>): Promise<import("no-mistakes").PostgresCompleteCatalog>;
+    generatePostgresCatalog(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").PostgresCatalogOptions>): Promise<import("no-mistakes").PostgresCatalog>;
+    lockfileDiff(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").LockfileDiffOptions>): Promise<import("no-mistakes").LockfileDiffEntry[]>;
+    ciImpact(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").CiImpactOptions>): Promise<import("no-mistakes").CiImpactReport>;
+    ciEnv(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").CiEnvOptions>): Promise<import("no-mistakes").CiEnvReport>;
+    ciTopology(options?: import("no-mistakes").WithInvocationOptions<import("no-mistakes").CiTopologyOptions>): Promise<import("no-mistakes").WorkflowTopology>;
+    ciTopologyImpact(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").CiTopologyImpactOptions>): Promise<import("no-mistakes").CiTopologyImpactReport>;
+    createWorkflowTopologyIndex(topology: import("no-mistakes").WorkflowTopology): import("no-mistakes").WorkflowTopologyIndex;
+    impactedChecks(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").ImpactedChecksOptions>): Promise<import("no-mistakes").ImpactedChecksReport>;
+    dataPw(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").DataPwOptions>): Promise<import("no-mistakes").DataPwReport>;
+    effects(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").EffectsOptions>): Promise<import("no-mistakes").EffectsReport>;
+    rscCallers(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").RscCallersOptions>): Promise<import("no-mistakes").RscCallersReport>;
+    registryExtension(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").RegistryExtensionOptions>): Promise<import("no-mistakes").RegistryExtensionReport>;
+    infraResourceRefs(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").InfraOptions & {
+        address: string;
+    }>): Promise<import("no-mistakes").ResourceRefRow[]>;
+    infraOutputs(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").InfraOptions & {
+        moduleDir: string;
+    }>): Promise<import("no-mistakes").ModuleOutputsResult>;
+    infraTestFor(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").InfraOptions & {
+        tfFile: string;
+    }>): Promise<import("no-mistakes").TestForRow[]>;
+    swiftImporters(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").SwiftOptions & {
+        file: string;
+    }>): Promise<import("no-mistakes").SwiftImporterRow[]>;
+    swiftTestTargets(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").SwiftOptions & {
+        file: string;
+    }>): Promise<import("no-mistakes").SwiftTestTargetRow[]>;
+    version(): Promise<string>;
+}>;

package/dist/sql-ast/no-mistakes-peer.mjs

@@ -0,0 +1,13 @@
+import { readFile } from 'node:fs/promises';
+export async function loadPostgresParser(caller) {
+    const entry = import.meta.resolve('no-mistakes');
+    const metadata = JSON.parse(await readFile(new URL('package.json', entry), 'utf8'));
+    const version = /^(\d+)\.(\d+)\.(\d+)(-[\w.-]+)?(?:\+[\w.-]+)?$/.exec(metadata.version);
+    const major = Number(version?.[1]);
+    const minor = Number(version?.[2]);
+    const patch = Number(version?.[3]);
+    if (!version || (major === 0 && (minor < 81 || (minor === 81 && patch === 0 && version[4])))) {
+        throw new Error(`${caller} requires no-mistakes >=0.81.0`);
+    }
+    return import('no-mistakes');
+}

package/docs/postgres-replay-context.md

@@ -1,5 +1,11 @@
 # PostgreSQL replay context
 
+`await createPostgresReplayContextFromSchema(schema)` collects STORED generated-expression
+references using the optional `no-mistakes >=0.81.0` SQL peer, then returns the memoized replay context.
+It rejects malformed expressions, additional statements, and unsupported queries instead of
+treating missing facts as an empty dependency set. Snapshots without STORED expressions do not
+load the peer. An incompatible peer is rejected before loading its parser. Snapshot loading and INSERT policy remain the caller's responsibility.
+
 `createPostgresReplayContext` projects a caller-owned schema snapshot and generated-column
 reference facts into the two lookups used by replay checks. It does not load snapshots, parse SQL,
 or decide INSERT policy.
@@ -7,7 +13,7 @@ or decide INSERT policy.
 The caller supplies one `{ table, column, sourceColumns }` fact for each snapshot column whose
 `generated` value is `stored` and whose `generatedExpression` is present. Build `sourceColumns` from
 the parser's typed expression column references, retaining each reference's final identifier
-component. Supply an empty array for a valid expression with no column references. Missing facts
+identity (unquoted names fold to lowercase; quoted names preserve case). Supply an empty array for a valid expression with no column references. Missing facts
 throw when that table's dependencies are requested, so parser failures cannot silently become an
 empty dependency set.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -380,14 +380,14 @@
     "@modelcontextprotocol/sdk": "1.31.0",
     "@types/picomatch": "^4.0.3",
     "@types/spdx-expression-parse": "4.0.0",
-    "agent-blackboard": "^0.6.0",
-    "no-mistakes": "0.78.0",
+    "agent-blackboard": "^0.6.1",
+    "no-mistakes": "0.81.0",
     "smol-toml": "1.9.0",
     "typescript5": "npm:typescript@5.9.3"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.31.0",
-    "agent-blackboard": "^0.6.0",
+    "agent-blackboard": "^0.6.1",
     "no-mistakes": "*",
     "typescript": ">=5",
     "vitest": ">=5"

package/skills/bounded-iteration/SKILL.md

@@ -15,6 +15,10 @@ A run's cost is the rows it reads and the work it starts, not the memory it hold
    serves: a work-item or dirty-marker row, a parent id, a due timestamp with a partial index, or
    a time or UUIDv7 window past a high-water mark. Column-to-column comparisons, `OR` of unrelated
    conditions, and `EXISTS` as the only condition are not filters. (`postgres-required-predicates`)
+   A per-row threshold becomes one bucket per distinct value, comparing the stored fact with a
+   bound, never with another column; `timestamptz + interval` is not immutable, so it cannot be
+   indexed. See [per-row interval](references/sweep-patterns.md#per-row-interval-one-bucket-per-threshold)
+   and [age milestones](references/sweep-patterns.md#age-milestones-from-the-uuidv7-key).
 2. **Cap every run.** Every loop has a per-run cap (batches, rows, or a deadline), reports whether
    work remains, and resumes from a persisted position. Never loop until empty, and never default
    a cap to infinity.
@@ -36,12 +40,31 @@ A run's cost is the rows it reads and the work it starts, not the memory it hold
 8. **Tunables are runtime configuration.** Batch sizes, page sizes, caps, and windows come from
    the consumer's runtime configuration with a validated default and a hard maximum, and are bound
    as SQL parameters. `LIMIT 1` and an external API's page maximum are contracts, not tunables.
-9. **Work that needs every key** (rebuilding a membership filter, a reindex) keeps derived state
-   current on write. A full pass is an explicit, capped, resumable backfill, not a scheduled pass
-   over everything.
-10. **Verify with a plan.** EXPLAIN at representative cardinality shows no Seq Scan on an
+9. **One dispatcher per signal.** Split an `OR` of unrelated reasons into one dispatcher per
+   reason, each with its own index-served predicate, position, and schedule, all enqueuing the same
+   idempotent job. Writes that cause a signal enqueue directly; the sweep is the backstop. See
+   [one dispatcher per signal](references/sweep-patterns.md#one-dispatcher-per-signal).
+10. **Deduplicate jobs by entity and triggering event.** A job id keyed only by the entity drops a
+    new trigger while the last job runs or is retained. Key it by entity and event; dedup lasts
+    only while the record is retained, and a failed retained job still claims its id. See
+    [queue job ids](references/sweep-patterns.md#queue-job-ids-for-deduplication).
+11. **Repair through an existing reconciler.** Repeat a fire-and-forget side effect (cache fill,
+    filter add, enqueue) idempotently from the reconciler that already sweeps recently changed
+    rows. Do not add a sweeper. See
+    [repair](references/sweep-patterns.md#repair-through-an-existing-reconciler).
+12. **Membership filters are never rebuilt on a schedule.** Add on write, rebuild in full only on
+    an operator action or a detected failure, and stop trusting the filter after a failed add.
+    Deleted keys and growth only cost false positives. See
+    [membership filters](references/sweep-patterns.md#membership-filters).
+13. **Global rankings stay one periodic aggregate.** A result over every row needs every score;
+    incremental per-row inputs move the cost to every write without freshening the ranking. Give
+    the pass an EXPLAIN budget. See [global ranking](references/sweep-patterns.md#global-ranking).
+14. **External listings carry the provider's continuation token.** Cap pages per run and enqueue a
+    continuation with the token; restarting at page one lets failing front items starve the rest.
+    See [external listing](references/sweep-patterns.md#external-listing-with-a-continuation-token).
+15. **Verify with a plan.** EXPLAIN at representative cardinality shows no Seq Scan on an
     unbounded table, and an index that supplies the `ORDER BY`, so the scan stops at the
-    `LIMIT` instead of reading and sorting every match.
+    `LIMIT` instead of reading and sorting every match. Compare rows read with rows returned.
 
 For work-item, lease, and cursor tables, read [postgres-schema-design](../postgres-schema-design/SKILL.md).
 For query shape and streaming, read [performance patterns](../postgres-node-performance-tuning/references/performance-patterns.md).