@indigoai-us/hq-cli 5.345.32 → 5.345.33

package/dist/hq-cloud-sync-runner/package.json

@@ -1 +1 @@
-{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.33","bundleSha256":"ac95a726e29b0c0db65da6753d3c4e249f3f8a0cf7d56fe7579ac1804a14f34f","formatVersion":1}
+{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.33","bundleSha256":"75c61dfadcd4d28795d082e0cc867b09f2b825baa3db95f662c51e9dce299412","formatVersion":1}

package/dist/lib/db/control-plane.d.ts

@@ -24,6 +24,33 @@ export interface RemoteStatusResponse {
         secretRef: string;
     } | null;
 }
+export interface RemoteUsageResponse {
+    companyUid: string;
+    dpuUsed: number;
+    dpuCap: number;
+    storageBytes: number;
+    storageCap: number;
+    pctDpu: number;
+    pctStorage: number;
+    period: string;
+    measuredAt: string | null;
+}
+/**
+ * Scoped temporary AWS credentials for one app's database role. The control
+ * plane would issue these from `POST /v1/db/apps/{appId}/session`.
+ */
+export interface RemoteAppSession {
+    endpoint: string;
+    region: string;
+    role: string;
+    schema: string;
+    credentials: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken: string;
+        expiration?: string;
+    };
+}
 export interface ControlPlaneClientOptions {
     baseUrl: string;
     /** Bearer access token */
@@ -41,5 +68,10 @@ export declare class ControlPlaneDbClient {
         region?: string;
     }): Promise<RemoteProvisionResponse>;
     status(companyUid: string): Promise<RemoteStatusResponse>;
+    usage(companyUid: string): Promise<RemoteUsageResponse>;
+    appSession(input: {
+        companyUid: string;
+        appId: string;
+    }): Promise<RemoteAppSession>;
 }
 //# sourceMappingURL=control-plane.d.ts.map

package/dist/lib/db/control-plane.js

@@ -78,5 +78,55 @@ export class ControlPlaneDbClient {
         }
         return JSON.parse(text);
     }
+    async usage(companyUid) {
+        const token = await this.getAccessToken();
+        const url = `${this.baseUrl}/v1/db/usage?companyUid=${encodeURIComponent(companyUid)}`;
+        const res = await this.fetchImpl(url, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(DB_STATUS_TIMEOUT_MS),
+        });
+        const text = await res.text();
+        assertNoPostgresUrl("usage", text);
+        if (!res.ok)
+            throw httpError("usage", res.status, text);
+        return JSON.parse(text);
+    }
+    async appSession(input) {
+        const token = await this.getAccessToken();
+        const url = `${this.baseUrl}/v1/db/apps/${encodeURIComponent(input.appId)}/session`;
+        const res = await this.fetchImpl(url, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ companyUid: input.companyUid }),
+            signal: AbortSignal.timeout(DB_STATUS_TIMEOUT_MS),
+        });
+        const text = await res.text();
+        if (!res.ok)
+            throw httpError("session", res.status, text);
+        return JSON.parse(text);
+    }
+}
+function httpError(label, status, text) {
+    let msg = `${label} failed (${status})`;
+    let code;
+    try {
+        const j = JSON.parse(text);
+        if (typeof j.error === "string")
+            msg = j.error;
+        if (typeof j.code === "string")
+            code = j.code;
+    }
+    catch {
+        /* keep */
+    }
+    const err = new Error(msg);
+    err.status = status;
+    if (code)
+        err.code = code;
+    return err;
 }
 //# sourceMappingURL=control-plane.js.map

package/dist/lib/db/redact.d.ts

@@ -0,0 +1,4 @@
+/** Strip connection strings, signed-URL parameters, and token-like strings. */
+export declare function redactSecrets(text: string): string;
+export declare function safeErrorMessage(error: unknown): string;
+//# sourceMappingURL=redact.d.ts.map

package/dist/lib/db/redact.js

@@ -0,0 +1,17 @@
+const SECRET_PATTERNS = [
+    /postgres(?:ql)?:\/\/\S*/gi,
+    /X-Amz-[A-Za-z-]+=?[^\s&"']*/gi,
+    /Security-Token=?[^\s&"']*/gi,
+    /\b[A-Za-z0-9+/_=-]{40,}\b/g,
+];
+/** Strip connection strings, signed-URL parameters, and token-like strings. */
+export function redactSecrets(text) {
+    let out = text;
+    for (const pattern of SECRET_PATTERNS)
+        out = out.replace(pattern, "[redacted]");
+    return out;
+}
+export function safeErrorMessage(error) {
+    return redactSecrets(error instanceof Error ? error.message : "Unknown error");
+}
+//# sourceMappingURL=redact.js.map

package/dist/lib/db/remote-engine.d.ts

@@ -0,0 +1,67 @@
+import type { ControlPlaneDbClient, RemoteAppSession } from "./control-plane.js";
+/**
+ * Source of short-lived, app-scoped database credentials. The control plane
+ * route behind it, `POST /v1/db/apps/{appId}/session`, does not exist yet.
+ */
+export interface DbCredentialProvider {
+    getSession(input: {
+        companyUid: string;
+        appId: string;
+    }): Promise<RemoteAppSession>;
+}
+export declare function controlPlaneCredentialProvider(client: Pick<ControlPlaneDbClient, "appSession">): DbCredentialProvider;
+export interface RemoteQueryResult {
+    rowCount: number | null;
+    fields: {
+        name: string;
+    }[];
+    rows: Record<string, unknown>[];
+}
+export interface RemoteClient {
+    connect(): Promise<void>;
+    query(sql: string, params?: unknown[]): Promise<RemoteQueryResult | RemoteQueryResult[]>;
+    end(): Promise<void>;
+}
+export interface RemoteClientConfig {
+    host: string;
+    port: number;
+    user: string;
+    password: string;
+    database: string;
+    ssl: {
+        rejectUnauthorized: boolean;
+    };
+}
+export interface RemoteEngineDeps {
+    provider: DbCredentialProvider;
+    tokenFactory?: (session: RemoteAppSession) => Promise<string>;
+    clientFactory?: (config: RemoteClientConfig) => RemoteClient;
+}
+export declare function quoteIdent(name: string): string;
+export interface RemoteAppConnection {
+    schema: string;
+    query(sql: string, params?: unknown[]): Promise<RemoteQueryResult[]>;
+    close(): Promise<void>;
+}
+/** Open a connection as the app role with `search_path` set to the app schema. */
+export declare function openRemoteAppConnection(deps: RemoteEngineDeps, input: {
+    companyUid: string;
+    appId: string;
+}): Promise<RemoteAppConnection>;
+export interface RemoteSqlOutcome {
+    results: RemoteQueryResult[];
+    readonly: boolean;
+}
+/** Run SQL in the app schema. Without `write`, the SQL runs inside BEGIN READ ONLY and is rolled back. */
+export declare function runRemoteSql(conn: RemoteAppConnection, sql: string, write: boolean): Promise<RemoteSqlOutcome>;
+export declare function formatRemoteResults(outcome: RemoteSqlOutcome): string;
+export interface DumpSummary {
+    tables: number;
+    rows: number;
+}
+/**
+ * Stream a schema dump (DDL then INSERTs) to `write`. Reads data in chunks
+ * of DUMP_CHUNK_ROWS rows ordered by primary key.
+ */
+export declare function dumpRemoteSchema(conn: RemoteAppConnection, write: (text: string) => void): Promise<DumpSummary>;
+//# sourceMappingURL=remote-engine.d.ts.map

package/dist/lib/db/remote-engine.js

@@ -0,0 +1,165 @@
+import { DsqlSigner } from "@aws-sdk/dsql-signer";
+import pg from "pg";
+const SCHEMA_PATTERN = /^app_[a-z0-9_]+$/;
+const DUMP_CHUNK_ROWS = 500;
+export function controlPlaneCredentialProvider(client) {
+    return { getSession: (input) => client.appSession(input) };
+}
+async function defaultToken(session) {
+    const signer = new DsqlSigner({
+        hostname: session.endpoint,
+        region: session.region,
+        credentials: {
+            accessKeyId: session.credentials.accessKeyId,
+            secretAccessKey: session.credentials.secretAccessKey,
+            sessionToken: session.credentials.sessionToken,
+        },
+    });
+    return signer.getDbConnectAuthToken();
+}
+function defaultClient(config) {
+    return new pg.Client(config);
+}
+export function quoteIdent(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+/** Open a connection as the app role with `search_path` set to the app schema. */
+export async function openRemoteAppConnection(deps, input) {
+    const session = await deps.provider.getSession(input);
+    if (!SCHEMA_PATTERN.test(session.schema)) {
+        throw new Error("Control plane returned an unexpected schema name");
+    }
+    const password = await (deps.tokenFactory ?? defaultToken)(session);
+    const client = (deps.clientFactory ?? defaultClient)({
+        host: session.endpoint,
+        port: 5432,
+        user: session.role,
+        password,
+        database: "postgres",
+        ssl: { rejectUnauthorized: true },
+    });
+    await client.connect();
+    try {
+        await client.query(`SET search_path TO ${quoteIdent(session.schema)}`);
+    }
+    catch (error) {
+        await client.end().catch(() => undefined);
+        throw error;
+    }
+    return {
+        schema: session.schema,
+        async query(sql, params) {
+            const res = await client.query(sql, params);
+            return Array.isArray(res) ? res : [res];
+        },
+        close: () => client.end(),
+    };
+}
+/** Run SQL in the app schema. Without `write`, the SQL runs inside BEGIN READ ONLY and is rolled back. */
+export async function runRemoteSql(conn, sql, write) {
+    await conn.query(write ? "BEGIN" : "BEGIN READ ONLY");
+    try {
+        const results = await conn.query(sql);
+        await conn.query(write ? "COMMIT" : "ROLLBACK");
+        return { results, readonly: !write };
+    }
+    catch (error) {
+        await conn.query("ROLLBACK").catch(() => undefined);
+        throw error;
+    }
+}
+export function formatRemoteResults(outcome) {
+    const blocks = outcome.results.map((r) => {
+        if (r.fields.length === 0)
+            return JSON.stringify({ rows: r.rowCount ?? 0 });
+        if (r.rows.length === 0) {
+            return JSON.stringify({ columns: r.fields.map((f) => f.name), rows: 0 });
+        }
+        return r.rows.map((row) => JSON.stringify(row)).join("\n");
+    });
+    return blocks.join("\n");
+}
+function sqlLiteral(value) {
+    if (value === null || value === undefined)
+        return "NULL";
+    if (typeof value === "number" || typeof value === "bigint")
+        return String(value);
+    if (typeof value === "boolean")
+        return value ? "TRUE" : "FALSE";
+    if (value instanceof Date)
+        return `'${value.toISOString()}'`;
+    if (Buffer.isBuffer(value))
+        return `'\\x${value.toString("hex")}'`;
+    const text = typeof value === "object" ? JSON.stringify(value) : String(value);
+    return `'${text.replace(/'/g, "''")}'`;
+}
+function columnDdl(c) {
+    const parts = [quoteIdent(c.column_name), c.data_type];
+    if (c.column_default !== null)
+        parts.push(`DEFAULT ${c.column_default}`);
+    if (c.is_nullable === "NO")
+        parts.push("NOT NULL");
+    return parts.join(" ");
+}
+/**
+ * Stream a schema dump (DDL then INSERTs) to `write`. Reads data in chunks
+ * of DUMP_CHUNK_ROWS rows ordered by primary key.
+ */
+export async function dumpRemoteSchema(conn, write) {
+    const [cols] = await conn.query(`SELECT table_name, column_name, data_type, is_nullable, column_default
+       FROM information_schema.columns
+      WHERE table_schema = $1
+      ORDER BY table_name, ordinal_position`, [conn.schema]);
+    const [pks] = await conn.query(`SELECT kcu.table_name, kcu.column_name
+       FROM information_schema.table_constraints tc
+       JOIN information_schema.key_column_usage kcu
+         ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+      WHERE tc.table_schema = $1 AND tc.constraint_type = 'PRIMARY KEY'
+      ORDER BY kcu.table_name, kcu.ordinal_position`, [conn.schema]);
+    const [indexes] = await conn.query(`SELECT tablename, indexdef FROM pg_indexes WHERE schemaname = $1 ORDER BY tablename, indexname`, [conn.schema]);
+    const byTable = new Map();
+    for (const row of cols.rows) {
+        const list = byTable.get(row.table_name) ?? [];
+        list.push(row);
+        byTable.set(row.table_name, list);
+    }
+    const pkByTable = new Map();
+    for (const row of pks.rows) {
+        const list = pkByTable.get(row.table_name) ?? [];
+        list.push(row.column_name);
+        pkByTable.set(row.table_name, list);
+    }
+    write(`-- hq db dump for schema ${conn.schema}\n\n`);
+    let totalRows = 0;
+    for (const [table, columns] of byTable) {
+        const pk = pkByTable.get(table) ?? [];
+        const defs = columns.map(columnDdl);
+        if (pk.length > 0)
+            defs.push(`PRIMARY KEY (${pk.map(quoteIdent).join(", ")})`);
+        write(`CREATE TABLE ${quoteIdent(table)} (\n  ${defs.join(",\n  ")}\n);\n\n`);
+    }
+    for (const row of indexes.rows) {
+        if (/_pkey\b/.test(row.indexdef))
+            continue;
+        write(`${row.indexdef.replace(/^CREATE (UNIQUE )?INDEX /, "CREATE $1INDEX ASYNC ")};\n`);
+    }
+    for (const [table, columns] of byTable) {
+        const pk = pkByTable.get(table) ?? [];
+        const order = (pk.length > 0 ? pk : columns.map((c) => c.column_name))
+            .map(quoteIdent)
+            .join(", ");
+        const names = columns.map((c) => quoteIdent(c.column_name)).join(", ");
+        for (let offset = 0;; offset += DUMP_CHUNK_ROWS) {
+            const [page] = await conn.query(`SELECT * FROM ${quoteIdent(table)} ORDER BY ${order} LIMIT ${DUMP_CHUNK_ROWS} OFFSET ${offset}`);
+            for (const row of page.rows) {
+                const values = columns.map((c) => sqlLiteral(row[c.column_name])).join(", ");
+                write(`INSERT INTO ${quoteIdent(table)} (${names}) VALUES (${values});\n`);
+            }
+            totalRows += page.rows.length;
+            if (page.rows.length < DUMP_CHUNK_ROWS)
+                break;
+        }
+    }
+    return { tables: byTable.size, rows: totalRows };
+}
+//# sourceMappingURL=remote-engine.js.map

package/dist/lib/db/usage-format.d.ts

@@ -0,0 +1,4 @@
+import type { RemoteUsageResponse } from "./control-plane.js";
+export declare function formatBytes(bytes: number): string;
+export declare function formatUsage(usage: RemoteUsageResponse): string;
+//# sourceMappingURL=usage-format.d.ts.map

package/dist/lib/db/usage-format.js

@@ -0,0 +1,41 @@
+const UNITS = ["bytes", "KB", "MB", "GB", "TB"];
+export function formatBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes <= 0)
+        return "0 bytes";
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < UNITS.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    const rounded = unit === 0 ? String(Math.round(value)) : value.toFixed(value >= 10 ? 0 : 1);
+    return `${rounded} ${UNITS[unit]}`;
+}
+function percent(pct) {
+    if (!Number.isFinite(pct))
+        return "0%";
+    return `${pct >= 10 ? Math.round(pct) : Math.round(pct * 10) / 10}%`;
+}
+export function formatUsage(usage) {
+    const lines = [
+        `Database usage for ${usage.period}`,
+        `Compute: ${usage.dpuUsed.toLocaleString("en-US")} of ${usage.dpuCap.toLocaleString("en-US")} units used (${percent(usage.pctDpu)})`,
+        `Storage: ${formatBytes(usage.storageBytes)} of ${formatBytes(usage.storageCap)} used (${percent(usage.pctStorage)})`,
+    ];
+    if (usage.measuredAt === null) {
+        lines.push("Not measured yet, so usage shows as 0. Check again in about 15 minutes.");
+    }
+    else {
+        lines.push(`Last measured ${usage.measuredAt}. Numbers can lag by a few minutes.`);
+    }
+    const over = [
+        usage.pctDpu >= 100 ? "compute" : null,
+        usage.pctStorage >= 100 ? "storage" : null,
+    ].filter(Boolean);
+    if (over.length > 0)
+        lines.push(`Over the cap for ${over.join(" and ")}.`);
+    else if (usage.pctDpu >= 80 || usage.pctStorage >= 80)
+        lines.push("Close to a cap (80% or more).");
+    return lines.join("\n");
+}
+//# sourceMappingURL=usage-format.js.map

package/dist/lib/lanes/keep-alive.d.ts

@@ -58,6 +58,18 @@ export declare function hasPendingKeepAliveWork(hqRoot: string, lane: Pick<LaneR
 export declare function undeliveredAnsweredQuestions(lane: Pick<LaneRecord, "lane_id" | "company">, questions: readonly QuestionRecord[]): QuestionRecord[];
 /** Missing registry means no retired lanes; every present invalid file fails closed. */
 export declare function loadRetiredLaneIds(hqRoot: string): ReadonlySet<string>;
+export interface RetiredLaneEntry {
+    lane: string;
+    index: number;
+    retired_at?: string;
+}
+/** Preserve registry metadata for diagnostics while validating the same shape as the eligibility reader. */
+export declare function loadRetiredLaneEntries(hqRoot: string): RetiredLaneEntry[];
+/** Return the matching registry row using the same bare/host-suffixed ID semantics as keepAliveExclusion. */
+export declare function findRetiredLaneEntry(hqRoot: string, laneId: string): (RetiredLaneEntry & {
+    path: string;
+}) | undefined;
+export declare function matchesRetiredLaneEntry(entry: RetiredLaneEntry, laneId: string): boolean;
 export declare function keepAliveSupersededBy<T extends KeepAliveLane>(lane: T, lanes: readonly T[], lineageAware?: boolean, companyForLane?: (lane: T) => T["company"]): T | undefined;
 export declare function keepAliveExclusion<T extends KeepAliveLane>(lane: T, lanes: readonly T[], retiredLaneIds: ReadonlySet<string>, lineageAware?: boolean, companyForLane?: (lane: T) => T["company"]): "retired" | "superseded" | undefined;
 export declare function leadLaneKeepAliveBackoffMs(attempt: number): number;

package/dist/lib/lanes/keep-alive.js

@@ -187,6 +187,10 @@ function retiredLaneRegistryPath(hqRoot) {
 }
 /** Missing registry means no retired lanes; every present invalid file fails closed. */
 export function loadRetiredLaneIds(hqRoot) {
+    return new Set(loadRetiredLaneEntries(hqRoot).map((entry) => entry.lane));
+}
+/** Preserve registry metadata for diagnostics while validating the same shape as the eligibility reader. */
+export function loadRetiredLaneEntries(hqRoot) {
     const filePath = retiredLaneRegistryPath(hqRoot);
     let text;
     try {
@@ -198,7 +202,7 @@ export function loadRetiredLaneIds(hqRoot) {
     }
     catch (err) {
         if (err.code === "ENOENT")
-            return new Set();
+            return [];
         throw new LanesError("keep_alive_retired_list_invalid", `Cannot read retired lane list ${filePath}: ${err instanceof Error ? err.message : String(err)}`, { path: filePath });
     }
     let parsed;
@@ -213,21 +217,26 @@ export function loadRetiredLaneIds(hqRoot) {
     }
     const retired = parsed.retired;
     if (retired === undefined)
-        return new Set();
+        return [];
     if (!Array.isArray(retired))
         throw invalidRetiredList(filePath, "retired must be an array");
-    const laneIds = new Set();
+    const entries = [];
     for (const [index, entry] of retired.entries()) {
         if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
             throw invalidRetiredList(filePath, `retired[${index}] must be an object with a lane id`);
         }
-        const laneId = entry.lane;
+        const row = entry;
+        const laneId = row.lane;
         if (typeof laneId !== "string" || laneId.trim() === "") {
             throw invalidRetiredList(filePath, `retired[${index}].lane must be a non-empty string`);
         }
-        laneIds.add(laneId.trim());
+        entries.push({
+            lane: laneId.trim(),
+            index,
+            ...(typeof row.retired_at === "string" ? { retired_at: row.retired_at } : {}),
+        });
     }
-    return laneIds;
+    return entries;
 }
 function invalidRetiredList(filePath, message) {
     return new LanesError("keep_alive_retired_list_invalid", `Invalid retired lane list ${filePath}: ${message}`, { path: filePath });
@@ -242,6 +251,16 @@ function isRetiredLaneId(laneId, retiredLaneIds) {
     }
     return false;
 }
+/** Return the matching registry row using the same bare/host-suffixed ID semantics as keepAliveExclusion. */
+export function findRetiredLaneEntry(hqRoot, laneId) {
+    const entry = loadRetiredLaneEntries(hqRoot).find((candidate) => matchesRetiredLaneEntry(candidate, laneId));
+    return entry === undefined ? undefined : { ...entry, path: retiredLaneRegistryPath(hqRoot) };
+}
+export function matchesRetiredLaneEntry(entry, laneId) {
+    return entry.lane === laneId ||
+        entry.lane.startsWith(`${laneId}_`) ||
+        laneId.startsWith(`${entry.lane}_`);
+}
 export function keepAliveSupersededBy(lane, lanes, lineageAware = LANE_SUPERSESSION_LINEAGE_AWARE_DEFAULT_ENABLED, companyForLane) {
     const createdAt = Date.parse(lane.created_at);
     if (!Number.isFinite(createdAt))

package/dist/lib/mesh/api.d.ts

@@ -51,6 +51,8 @@ export interface MeshProjectStoryInput {
     description?: string;
     acceptanceCriteria?: string[];
     status?: string;
+    /** Source ledger state preserved for Boards whose status enum has four columns. */
+    ledgerState?: string;
     passes?: boolean;
     priority?: number;
     assigneeUid?: string;

package/dist/lib/mesh/project-board.d.ts

@@ -4,6 +4,23 @@ export declare function mergeProjectStories(current: MeshProjectStoryInput[], pl
     resetStatus?: boolean;
 }): MeshProjectStoryInput[];
 export declare function boardStoryStatus(story: MeshProjectStoryInput): string;
+export interface ProjectStoryReconciliation {
+    storyId: string;
+    ledgerState: string | null;
+    expectedBoardStatus: string | null;
+    boardStatus: string | null;
+    boardLedgerState: string | null;
+    stateDrift: boolean;
+    missingOnBoard: boolean;
+    extraOnBoard: boolean;
+}
+export interface ProjectStoryReconciliationReport {
+    mismatches: ProjectStoryReconciliation[];
+    ledgerStateUnsupported: string[];
+    stateDriftCount: number;
+}
+/** Compare one PRD ledger with one Board snapshot without changing either. */
+export declare function reconcileProjectStories(ledger: readonly MeshProjectStoryInput[], board: readonly MeshProjectStoryInput[]): ProjectStoryReconciliationReport;
 /**
  * Keep only prd-sync task_status events whose Board status actually differs.
  * Missing Board rows stay (ensure will add them). Same-status replays of

package/dist/lib/mesh/project-board.js

@@ -36,6 +36,34 @@ export function boardStoryStatus(story) {
         return status;
     return story.passes === true ? "done" : "queued";
 }
+/** Compare one PRD ledger with one Board snapshot without changing either. */
+export function reconcileProjectStories(ledger, board) {
+    const ledgerById = new Map(ledger.map((story) => [story.id, story]));
+    const boardById = new Map(board.map((story) => [story.id, story]));
+    const ids = [...ledgerById.keys(), ...[...boardById.keys()].filter((id) => !ledgerById.has(id))];
+    const ledgerStateUnsupported = [];
+    const mismatches = ids.flatMap((storyId) => {
+        const source = ledgerById.get(storyId);
+        const current = boardById.get(storyId);
+        const expectedBoardStatus = source ? boardStoryStatus(source) : null;
+        const boardStatus = current ? boardStoryStatus(current) : null;
+        const ledgerState = source?.ledgerState ?? null;
+        const boardLedgerState = current?.ledgerState ?? null;
+        const missingOnBoard = Boolean(source && !current);
+        const extraOnBoard = Boolean(current && !source);
+        if (source && ledgerState && current && boardLedgerState === null)
+            ledgerStateUnsupported.push(storyId);
+        const stateDrift = Boolean(source && ledgerState && boardLedgerState !== null && boardLedgerState !== ledgerState);
+        if (!missingOnBoard && !extraOnBoard && boardStatus === expectedBoardStatus && !stateDrift)
+            return [];
+        return [{ storyId, ledgerState, expectedBoardStatus, boardStatus, boardLedgerState, stateDrift, missingOnBoard, extraOnBoard }];
+    });
+    return {
+        mismatches,
+        ledgerStateUnsupported,
+        stateDriftCount: mismatches.filter((mismatch) => mismatch.stateDrift).length,
+    };
+}
 /**
  * Keep only prd-sync task_status events whose Board status actually differs.
  * Missing Board rows stay (ensure will add them). Same-status replays of

package/dist/lib/mesh/story-status.d.ts

@@ -1,6 +1,21 @@
 declare const BOARD_STORY_STATUSES: readonly ["queued", "in_progress", "review", "done"];
 export type BoardStoryStatus = (typeof BOARD_STORY_STATUSES)[number];
+/**
+ * The ledger has more states than the Board. `blocked` and the review states
+ * need attention, while `dropped` is terminal; the Board has only one terminal
+ * column (`done`).
+ */
+export declare const LEDGER_STATES: readonly ["todo", "in_progress", "review", "waiting", "blocked", "done", "dropped"];
+export declare const ACCEPTED_LEDGER_STATES: readonly ["todo", "in_progress", "review", "waiting", "blocked", "done", "dropped", "in_review", "verification"];
+export declare class UnknownProjectStoryStateError extends Error {
+    readonly source: string;
+    readonly storyId: string;
+    readonly value: unknown;
+    readonly code = "PROJECT_STORY_STATE_INVALID";
+    constructor(source: string, storyId: string, value: unknown);
+}
 export declare function mapSourceStoryStatus(story: {
+    id?: unknown;
     status?: unknown;
     state?: unknown;
 }, source: string): BoardStoryStatus | undefined;
@@ -12,6 +27,7 @@ export declare function mapSourceStoryStatus(story: {
 export declare function mapReaderStoryStatus(story: {
     status?: unknown;
     state?: unknown;
+    ledgerState?: unknown;
 }): string | undefined;
 export {};
 //# sourceMappingURL=story-status.d.ts.map

package/dist/lib/mesh/story-status.js

@@ -5,27 +5,51 @@ const boardStoryStatusSet = new Set(BOARD_STORY_STATUSES);
  * need attention, while `dropped` is terminal; the Board has only one terminal
  * column (`done`).
  */
+export const LEDGER_STATES = [
+    "todo", "in_progress", "review", "waiting", "blocked", "done", "dropped",
+];
 const LEDGER_STATE_TO_BOARD_STATUS = {
     todo: "queued",
     in_progress: "in_progress",
+    review: "review",
+    // The four-column Board cannot represent waiting separately. Preserve the
+    // ledger state on each story so consumers can distinguish it from blocked.
+    waiting: "queued",
     in_review: "review",
     verification: "review",
     blocked: "review",
     done: "done",
     dropped: "done",
 };
+export const ACCEPTED_LEDGER_STATES = [
+    ...LEDGER_STATES, "in_review", "verification",
+];
+export class UnknownProjectStoryStateError extends Error {
+    source;
+    storyId;
+    value;
+    code = "PROJECT_STORY_STATE_INVALID";
+    constructor(source, storyId, value) {
+        super(`${source}.state for story ${storyId || "<missing id>"} has unsupported value ${JSON.stringify(value)}; accepted: ${ACCEPTED_LEDGER_STATES.join("|")}.`);
+        this.source = source;
+        this.storyId = storyId;
+        this.value = value;
+        this.name = "UnknownProjectStoryStateError";
+    }
+}
 export function mapSourceStoryStatus(story, source) {
+    if (Object.hasOwn(story, "state")) {
+        if (typeof story.state !== "string" || !Object.hasOwn(LEDGER_STATE_TO_BOARD_STATUS, story.state.trim())) {
+            throw new UnknownProjectStoryStateError(source, "id" in story && typeof story.id === "string" ? story.id : "", story.state);
+        }
+    }
     if (story.status !== undefined && story.status !== null) {
         if (typeof story.status !== "string" || !boardStoryStatusSet.has(story.status.trim())) {
             throw new Error(`${source}.status must be queued|in_progress|review|done.`);
         }
         return story.status.trim();
     }
-    if (Object.hasOwn(story, "state")) {
-        if (typeof story.state !== "string" ||
-            !Object.hasOwn(LEDGER_STATE_TO_BOARD_STATUS, story.state.trim())) {
-            throw new Error(`${source}.state must be todo|in_progress|in_review|verification|blocked|done|dropped.`);
-        }
+    if (typeof story.state === "string") {
         return LEDGER_STATE_TO_BOARD_STATUS[story.state.trim()];
     }
     return undefined;
@@ -39,9 +63,10 @@ export function mapReaderStoryStatus(story) {
     if (story.status !== undefined && story.status !== null) {
         return typeof story.status === "string" ? story.status : undefined;
     }
-    if (typeof story.state !== "string")
+    const stateValue = story.state ?? story.ledgerState;
+    if (typeof stateValue !== "string")
         return undefined;
-    const state = story.state.trim();
+    const state = stateValue.trim();
     return Object.hasOwn(LEDGER_STATE_TO_BOARD_STATUS, state)
         ? LEDGER_STATE_TO_BOARD_STATUS[state]
         : undefined;