@unbrained/pm-cli 2026.8.16 → 2026.8.18

package/dist/sdk/linked-artifacts.js

@@ -4,7 +4,7 @@
  * Implements the pm linked artifacts command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="256b39b7-882e-553c-9dea-813bfd363dd7")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="72f57c4d-65c5-57f1-a16a-f6c970aca680")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import fg from "fast-glob";
@@ -83,24 +83,73 @@ function expandBareCommaSeparatedAddEntries(raw) {
         return splitCommaList(trimmed);
     });
 }
+/** Whether a Markdown destination contains only balanced parentheses. */
+function hasBalancedParentheses(value) {
+    let depth = 0;
+    for (const character of value) {
+        if (character === "(")
+            depth += 1;
+        if (character === ")")
+            depth -= 1;
+        if (depth < 0)
+            return false;
+    }
+    return depth === 0;
+}
+/** Parse one lossless bare, Markdown, or CSV-label remote documentation reference. */
+function parseDocumentationReference(trimmed) {
+    if (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//u.test(trimmed) &&
+        !looksLikeStructuredPathEntry(trimmed)) {
+        return { path: trimmed, scope: "project", note: undefined };
+    }
+    const labelEnd = trimmed.indexOf("](");
+    if (trimmed.startsWith("[") && labelEnd > 0 && trimmed.endsWith(")")) {
+        const destination = trimmed.slice(labelEnd + 2, -1).trim();
+        if (destination.length > 0 && hasBalancedParentheses(destination)) {
+            return {
+                path: destination,
+                scope: "project",
+                note: trimmed.slice(1, labelEnd).trim() || undefined,
+            };
+        }
+    }
+    const delimiterIndex = trimmed.indexOf(",");
+    if (delimiterIndex < 0)
+        return undefined;
+    const label = trimmed.slice(0, delimiterIndex).trim();
+    const destination = trimmed.slice(delimiterIndex + 1).trim();
+    if (label.length === 0 ||
+        !/^[A-Za-z][A-Za-z0-9+.-]*:\/\//u.test(destination)) {
+        return undefined;
+    }
+    return { path: destination, scope: "project", note: label };
+}
 /** Implements parse add entries for the public runtime surface of this module. */
 export function parseAddEntries(raw, bareNoun) {
     if (!raw)
         return [];
-    return expandBareCommaSeparatedAddEntries(raw).map((entry) => {
+    return raw.flatMap((entry) => {
         const trimmed = entry.trim();
-        const kv = looksLikeStructuredPathEntry(trimmed)
-            ? parseCsvKv(entry, "--add")
-            : { path: trimmed };
-        assertNoUnknownCsvKeys(kv, "--add", LINKED_ARTIFACT_ADD_KEYS);
-        if (!kv.path) {
-            throw new PmCliError(`--add requires path=<value> or a bare ${bareNoun} path`, EXIT_CODE.USAGE);
+        if (bareNoun === "doc") {
+            const reference = parseDocumentationReference(trimmed);
+            if (reference !== undefined)
+                return [reference];
         }
-        return {
-            path: kv.path,
-            scope: ensureScope(kv.scope),
-            note: kv.note?.trim() || undefined,
-        };
+        return expandBareCommaSeparatedAddEntries([entry]).map((expanded) => {
+            const expandedTrimmed = expanded.trim();
+            const kv = looksLikeStructuredPathEntry(expandedTrimmed)
+                ? parseCsvKv(expanded, "--add")
+                : { path: expandedTrimmed };
+            assertNoUnknownCsvKeys(kv, "--add", LINKED_ARTIFACT_ADD_KEYS);
+            if (!kv.path) {
+                throw new PmCliError(`--add requires path=<value> or a bare ${bareNoun} path`, EXIT_CODE.USAGE);
+            }
+            return {
+                path: kv.path,
+                scope: ensureScope(kv.scope),
+                note: kv.note?.trim() || undefined,
+            };
+        });
     });
 }
 /** Implements parse add glob entries for the public runtime surface of this module. */
@@ -490,4 +539,4 @@ export function renameArtifactsResultKey(result, key) {
     return out;
 }
 //# sourceMappingURL=linked-artifacts.js.map
-//# debugId=256b39b7-882e-553c-9dea-813bfd363dd7
+//# debugId=72f57c4d-65c5-57f1-a16a-f6c970aca680

package/dist/sdk/mutation-events.d.ts

@@ -1,6 +1,13 @@
 import { type IndexedHistoryEvent } from "../core/history/event-index.js";
 import type { HistoryEntry } from "../types/index.js";
 import { type HistoryProvenanceRow, type HistoryProvenanceSummary } from "./history-provenance.js";
+/** Regression budgets for the canonical 200-event wire-cost fixture. */
+export declare const MUTATION_EVENT_WIRE_BUDGET: Readonly<{
+    /** Maximum default batch bytes divided by legacy row-cursor bytes. */
+    batch_to_row_ratio: 0.6;
+    /** Fixture size used to keep the ratio representative of fleet catch-up. */
+    fixture_events: 200;
+}>;
 interface MutationEventCursorEnvelope {
     version: number;
     fingerprint: string;
@@ -36,11 +43,13 @@ export interface ListMutationEventsOptions {
     agentInstance?: string | readonly string[];
     /** Exact provenance dimension predicates (`dimension=value`). */
     provenanceFilter?: string | readonly string[];
+    /** Cursor framing mode; batch is the token-efficient default. */
+    cursorMode?: "batch" | "row";
 }
 /** One ordered cross-item mutation event. */
 export interface MutationEvent {
     /** Cursor that resumes strictly after this event. */
-    cursor: string;
+    cursor?: string;
     /** Item id or `_workspace` stream subject. */
     item_id: string;
     /** One-based version within the subject's stream. */
@@ -68,10 +77,12 @@ export interface MutationEventPage {
     count: number;
     /** Whether another matching event is immediately available. */
     has_more: boolean;
+    /** Cursor framing used by this page. */
+    cursor_mode: "batch" | "row";
     /** Cursor that resumes after the final returned event. */
     next_cursor?: string;
     /** Persistent derived projection used for the read. */
-    source: "derived_index";
+    source: "derived_index" | "authoritative_history";
     /** Constant-size provenance completeness metrics for the returned page. */
     provenance_summary?: HistoryProvenanceSummary;
 }
@@ -94,6 +105,11 @@ declare function resolveMutationEventStart(sinceValue: string | undefined, finge
 };
 /** Read one bounded page of mutation events from the persistent projection. */
 export declare function listMutationEvents(options?: ListMutationEventsOptions): Promise<MutationEventPage>;
+/**
+ * Subscribe to complete event batches. Every yield is a recoverable boundary;
+ * an empty batch is an idle heartbeat carrying the last known cursor.
+ */
+export declare function subscribeMutationEventBatches(options?: SubscribeMutationEventsOptions): AsyncGenerator<MutationEventPage, void, void>;
 /**
  * Subscribe to committed mutation facts as an async iterable. The iterator
  * performs cursor catch-up reads and waits only when no new event is available.

package/dist/sdk/mutation-events.js

@@ -5,10 +5,10 @@
  * history store without requiring a daemon or shell subprocess.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="3f9853cc-0719-544f-8726-3cfd6063b59e")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e8cd5790-eacf-5ef7-bc0a-11ea3fe17d2d")}catch(e){}}();
 import { createHash } from "node:crypto";
 import { setTimeout as delay } from "node:timers/promises";
-import { queryHistoryEventIndex, rebuildHistoryEventIndex, } from "../core/history/event-index.js";
+import { queryHistoryEventIndex, queryHistoryEventStreams, rebuildHistoryEventIndex, } from "../core/history/event-index.js";
 import { pathExists } from "../core/fs/fs-utils.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
@@ -21,6 +21,13 @@ const MUTATION_EVENT_CURSOR_PATTERN = /^[A-Za-z0-9_-]+$/;
 const DEFAULT_EVENT_LIMIT = 100;
 const MAX_EVENT_LIMIT = 1_000;
 const DEFAULT_FOLLOW_INTERVAL_MS = 250;
+/** Regression budgets for the canonical 200-event wire-cost fixture. */
+export const MUTATION_EVENT_WIRE_BUDGET = Object.freeze({
+    /** Maximum default batch bytes divided by legacy row-cursor bytes. */
+    batch_to_row_ratio: 0.6,
+    /** Fixture size used to keep the ratio representative of fleet catch-up. */
+    fixture_events: 200,
+});
 function normalizeFilter(value) {
     if (value === undefined)
         return undefined;
@@ -120,14 +127,25 @@ async function resolveIndexedMutationEvents(pmRoot, query) {
     let indexed = await queryHistoryEventIndex(pmRoot, query);
     if (indexed === null) {
         if (!(await rebuildHistoryEventIndex(pmRoot))) {
-            throw new PmCliError("Mutation events require a runtime with node:sqlite DatabaseSync support.", EXIT_CODE.GENERIC_FAILURE, { code: "event_index_unavailable" });
+            return {
+                ...(await queryHistoryEventStreams(pmRoot, query)),
+                source: "authoritative_history",
+            };
         }
         indexed = await queryHistoryEventIndex(pmRoot, query);
     }
     if (indexed === null) {
         throw new PmCliError("Mutation event index could not be opened after rebuild.", EXIT_CODE.GENERIC_FAILURE, { code: "event_index_unavailable" });
     }
-    return indexed;
+    return { ...indexed, source: "derived_index" };
+}
+/** Resolves the event cursor emission mode and rejects unsupported transport spellings. */
+function resolveMutationEventCursorMode(value) {
+    const cursorMode = value ?? "batch";
+    if (cursorMode !== "batch" && cursorMode !== "row") {
+        throw new PmCliError("Mutation event cursor mode must be batch or row.", EXIT_CODE.USAGE, { code: "invalid_event_cursor_mode" });
+    }
+    return cursorMode;
 }
 /** Read one bounded page of mutation events from the persistent projection. */
 export async function listMutationEvents(options = {}) {
@@ -136,6 +154,7 @@ export async function listMutationEvents(options = {}) {
         throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
     }
     const requestedLimit = parseMutationEventLimit(options.limit);
+    const cursorMode = resolveMutationEventCursorMode(options.cursorMode);
     if (options.full === true && options.provenance === true) {
         throw new PmCliError("Mutation event projections are mutually exclusive. Use --provenance or --full.", EXIT_CODE.USAGE);
     }
@@ -174,7 +193,9 @@ export async function listMutationEvents(options = {}) {
     };
     const indexed = await resolveIndexedMutationEvents(pmRoot, query);
     const events = indexed.events.map((event) => ({
-        cursor: encodeMutationEventCursor(event, fingerprint),
+        ...(cursorMode === "row"
+            ? { cursor: encodeMutationEventCursor(event, fingerprint) }
+            : {}),
         item_id: event.stream_id,
         version: event.stream_offset + 1,
         ts: event.entry.ts,
@@ -198,10 +219,13 @@ export async function listMutationEvents(options = {}) {
         events,
         count: events.length,
         has_more: indexed.has_more,
-        ...(events.length === 0
+        cursor_mode: cursorMode,
+        ...(indexed.events.length === 0
             ? {}
-            : { next_cursor: events[events.length - 1].cursor }),
-        source: "derived_index",
+            : {
+                next_cursor: encodeMutationEventCursor(indexed.events[indexed.events.length - 1], fingerprint),
+            }),
+        source: indexed.source,
         ...(options.provenanceSummary === true
             ? {
                 provenance_summary: summarizeHistoryProvenance(indexed.events.map((event) => event.entry), vocabulary, dimensions),
@@ -210,21 +234,26 @@ export async function listMutationEvents(options = {}) {
     };
 }
 /**
- * Subscribe to committed mutation facts as an async iterable. The iterator
- * performs cursor catch-up reads and waits only when no new event is available.
+ * Subscribe to complete event batches. Every yield is a recoverable boundary;
+ * an empty batch is an idle heartbeat carrying the last known cursor.
  */
-export async function* subscribeMutationEvents(options = {}) {
+export async function* subscribeMutationEventBatches(options = {}) {
     const intervalMs = options.intervalMs ?? DEFAULT_FOLLOW_INTERVAL_MS;
     if (!Number.isSafeInteger(intervalMs) || intervalMs < 10) {
         throw new PmCliError("Mutation event follow interval must be an integer of at least 10ms.", EXIT_CODE.USAGE, { code: "invalid_event_follow_interval" });
     }
     let cursor = options.since;
     while (options.signal?.aborted !== true) {
-        const page = await listMutationEvents({ ...options, since: cursor });
+        const page = await listMutationEvents({
+            ...options,
+            cursorMode: options.cursorMode ?? "batch",
+            since: cursor,
+        });
+        const boundary = page.next_cursor === undefined && cursor !== undefined
+            ? { ...page, next_cursor: cursor }
+            : page;
+        yield boundary;
         if (page.events.length > 0) {
-            for (const event of page.events) {
-                yield event;
-            }
             cursor = page.next_cursor;
             continue;
         }
@@ -238,6 +267,20 @@ export async function* subscribeMutationEvents(options = {}) {
         }
     }
 }
+/**
+ * Subscribe to committed mutation facts as an async iterable. The iterator
+ * performs cursor catch-up reads and waits only when no new event is available.
+ */
+export async function* subscribeMutationEvents(options = {}) {
+    for await (const page of subscribeMutationEventBatches({
+        ...options,
+        cursorMode: "row",
+    })) {
+        for (const event of page.events) {
+            yield event;
+        }
+    }
+}
 /** Public test seams for cursor contract verification. */
 export const _testOnlyMutationEvents = {
     decodeMutationEventCursor,
@@ -249,4 +292,4 @@ export const _testOnlyMutationEvents = {
     resolveMutationEventStart,
 };
 //# sourceMappingURL=mutation-events.js.map
-//# debugId=3f9853cc-0719-544f-8726-3cfd6063b59e
+//# debugId=e8cd5790-eacf-5ef7-bc0a-11ea3fe17d2d

package/dist/sdk/output.d.ts

@@ -14,3 +14,47 @@ export { SUPPRESS_HOST_OUTPUT_MARKER, isHostOutputSuppressed, suppressHostOutput
  * non-array object.
  */
 export declare function serializeNdjsonRows(rows: readonly unknown[]): string;
+/** Terminal metadata that makes an NDJSON batch independently resumable. */
+export interface PmNdjsonStreamTrailer {
+    /** Producer-owned constant-size fields may extend the shared trailer. */
+    readonly [key: string]: unknown;
+    /** Stable discriminator that cannot be confused with a domain row. */
+    record_type: "pm.stream.trailer";
+    /** Number of domain rows preceding this trailer in the batch. */
+    count: number;
+    /** Whether another row was available when the batch was read. */
+    has_more: boolean;
+    /** Opaque cursor that resumes strictly after this batch. */
+    next_cursor: string | null;
+    /** Name of the authoritative or derived source that produced the batch. */
+    source: string;
+    /** Optional constant-size metadata owned by the stream producer. */
+    metadata?: Readonly<Record<string, unknown>>;
+}
+/** Metadata accepted by {@link serializeNdjsonStream}. */
+export interface PmNdjsonStreamTrailerInput {
+    /** Producer-owned constant-size fields may extend the shared trailer. */
+    readonly [key: string]: unknown;
+    /** The serializer owns the discriminator and callers cannot override it. */
+    readonly record_type?: never;
+    /** Number of domain rows preceding the terminal trailer. */
+    count: number;
+    /** Whether another row was available when the batch was read. */
+    has_more: boolean;
+    /** Opaque cursor that resumes strictly after this batch. */
+    next_cursor: string | null;
+    /** Name of the authoritative or derived source that produced the batch. */
+    source: string;
+    /** Optional constant-size metadata owned by the stream producer. */
+    metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Serialize a bounded NDJSON batch followed by exactly one typed terminal
+ * trailer. The result has no trailing newline so callers retain framing
+ * control while consumers always receive count and recovery metadata, even
+ * for an empty batch.
+ *
+ * @throws {TypeError} When the trailer count differs from the number of domain
+ * rows or a domain row uses the reserved terminal discriminator.
+ */
+export declare function serializeNdjsonStream(rows: readonly unknown[], trailer: PmNdjsonStreamTrailerInput): string;

package/dist/sdk/output.js

@@ -5,7 +5,7 @@
  * renderers, and custom SDK-built hosts.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f3cc2b57-d6e1-5df0-bdde-756af08a3552")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="38facf38-c1e1-5574-9e70-98977494d939")}catch(e){}}();
 export { SUPPRESS_HOST_OUTPUT_MARKER, isHostOutputSuppressed, suppressHostOutput, } from "../core/output/output-control.js";
 /**
  * Serialize object rows as newline-delimited JSON without adding a trailing
@@ -35,5 +35,31 @@ export function serializeNdjsonRows(rows) {
     })
         .join("\n");
 }
+/**
+ * Serialize a bounded NDJSON batch followed by exactly one typed terminal
+ * trailer. The result has no trailing newline so callers retain framing
+ * control while consumers always receive count and recovery metadata, even
+ * for an empty batch.
+ *
+ * @throws {TypeError} When the trailer count differs from the number of domain
+ * rows or a domain row uses the reserved terminal discriminator.
+ */
+export function serializeNdjsonStream(rows, trailer) {
+    if (trailer.count !== rows.length) {
+        throw new TypeError(`NDJSON trailer count ${trailer.count} does not match ${rows.length} ${rows.length === 1 ? "row" : "rows"}.`);
+    }
+    for (const [index, row] of rows.entries()) {
+        if (typeof row === "object" &&
+            row !== null &&
+            !Array.isArray(row) &&
+            Reflect.get(row, "record_type") === "pm.stream.trailer") {
+            throw new TypeError(`NDJSON row ${index} uses reserved record_type pm.stream.trailer`);
+        }
+    }
+    return serializeNdjsonRows([
+        ...rows,
+        { ...trailer, record_type: "pm.stream.trailer" },
+    ]);
+}
 //# sourceMappingURL=output.js.map
-//# debugId=f3cc2b57-d6e1-5df0-bdde-756af08a3552
+//# debugId=38facf38-c1e1-5574-9e70-98977494d939

package/dist/sdk/query/complete-list.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @module sdk/query/complete-list
+ *
+ * Certifies that a list result represents the complete, unfiltered workspace.
+ */
+import type { PmReadOutputReceipt } from "../read-output-contracts.js";
+import type { ListFullResult, ListOptions } from "./list.js";
+/** Stable reasons a purported whole-workspace list cannot be trusted. */
+export declare const PM_COMPLETE_LIST_FINDING_CODES: readonly ["invalid_envelope", "source_incomplete", "source_unchecked", "filtered_corpus", "terminal_items_excluded", "strict_read_unproven", "page_incomplete", "count_mismatch", "projection_incomplete", "field_omission", "budget_compaction", "budget_omission", "session_projection", "invalid_item_id", "duplicate_item_id"];
+/** Machine-readable reason a complete-list candidate failed certification. */
+export type PmCompleteListFindingCode = (typeof PM_COMPLETE_LIST_FINDING_CODES)[number];
+/** One independently actionable complete-list contract violation. */
+export interface PmCompleteListFinding {
+    /** Stable finding identifier suitable for automation. */
+    code: PmCompleteListFindingCode;
+    /** Concise explanation of the evidence that failed. */
+    message: string;
+}
+/** Proof attached only after every whole-corpus invariant passes. */
+export interface PmCompleteListCertificate {
+    /** Certificate schema version. */
+    contract_version: 1;
+    /** Number of full item rows certified. */
+    item_count: number;
+    /** Number of distinct non-empty item identifiers certified. */
+    unique_item_id_count: number;
+    /** Confirms the request did not exclude closed or canceled work. */
+    terminal_items_included: true;
+    /** Confirms the underlying tracker scan reported complete. */
+    source_complete: true;
+    /** Confirms every row used the full metadata projection. */
+    full_projection: true;
+    /** Confirms neither field nor whole-result omission occurred. */
+    no_omissions: true;
+    /** Confirms no page, row, or token ceiling reduced the corpus. */
+    unbounded: true;
+}
+/** Full list result augmented with a fail-closed whole-corpus certificate. */
+export interface PmCompleteListResult extends ListFullResult {
+    /** Exact proof that the returned rows represent the full tracker corpus. */
+    complete_list: PmCompleteListCertificate;
+    /** Universal read receipt when the runtime attached one. */
+    read_output?: PmReadOutputReceipt;
+}
+/** Inspection report returned without throwing for policy and UI consumers. */
+export interface PmCompleteListInspection {
+    /** Whether the candidate is safe to certify as the whole tracker corpus. */
+    ok: boolean;
+    /** Every independently detected contract violation. */
+    findings: PmCompleteListFinding[];
+}
+/** Failure receipt with both CLI and SDK recovery paths. */
+export interface PmCompleteListFailureReceipt {
+    /** Stable receipt schema version. */
+    contract_version: 1;
+    /** Failed contract name. */
+    contract: "complete_list";
+    /** Every independently detected contract violation. */
+    findings: PmCompleteListFinding[];
+    /** Executable recovery instructions for both public transports. */
+    recovery: {
+        /** Exact CLI command that requests the canonical whole corpus. */
+        suggested_retry: string;
+        /** Equivalent SDK operation. */
+        sdk: string;
+    };
+}
+/** Typed fail-closed error raised when whole-corpus proof is absent. */
+export declare class PmCompleteListValidationError extends Error {
+    /** Structured failure and executable recovery evidence. */
+    readonly receipt: PmCompleteListFailureReceipt;
+    /** Construct an immutable complete-list validation failure. */
+    constructor(findings: PmCompleteListFinding[]);
+}
+/** Options accepted by the whole-corpus list helper. */
+export interface PmCompleteListOptions {
+    /** Include item bodies in addition to complete metadata. */
+    includeBody?: boolean;
+}
+/** Build the canonical all-status, full, strict, and unbounded list request. */
+export declare function createCompleteListOptions(options?: PmCompleteListOptions): ListOptions & {
+    excludeTerminal: false;
+    full: true;
+    noTruncate: true;
+    outputBudget: "unbounded";
+    outputLimit: "unbounded";
+    strictRead: true;
+};
+/** Inspect an unknown result and report every missing whole-corpus invariant. */
+export declare function inspectCompleteListResult(candidate: unknown): PmCompleteListInspection;
+/** Certify a result as the whole tracker corpus or throw a typed recovery error. */
+export declare function certifyCompleteListResult(candidate: unknown): PmCompleteListResult;
+/** Assert whole-corpus completeness while narrowing the candidate type in place. */
+export declare function assertCompleteListResult(candidate: unknown): asserts candidate is ListFullResult;

package/dist/sdk/query/complete-list.js

@@ -0,0 +1,173 @@
+/** Stable reasons a purported whole-workspace list cannot be trusted. */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="cc342d27-aa2d-5e84-8441-46a35c42dc00")}catch(e){}}();
+export const PM_COMPLETE_LIST_FINDING_CODES = [
+    "invalid_envelope",
+    "source_incomplete",
+    "source_unchecked",
+    "filtered_corpus",
+    "terminal_items_excluded",
+    "strict_read_unproven",
+    "page_incomplete",
+    "count_mismatch",
+    "projection_incomplete",
+    "field_omission",
+    "budget_compaction",
+    "budget_omission",
+    "session_projection",
+    "invalid_item_id",
+    "duplicate_item_id",
+];
+/** Typed fail-closed error raised when whole-corpus proof is absent. */
+export class PmCompleteListValidationError extends Error {
+    /** Structured failure and executable recovery evidence. */
+    receipt;
+    /** Construct an immutable complete-list validation failure. */
+    constructor(findings) {
+        super(`Complete-list certification failed: ${findings.map((finding) => finding.code).join(", ")}.`);
+        this.name = "PmCompleteListValidationError";
+        this.receipt = {
+            contract_version: 1,
+            contract: "complete_list",
+            findings,
+            recovery: {
+                suggested_retry: "pm list-all --full --strict-read --no-truncate --output-budget unbounded --json",
+                sdk: "await client.listAllComplete()",
+            },
+        };
+    }
+}
+/** Build the canonical all-status, full, strict, and unbounded list request. */
+export function createCompleteListOptions(options = {}) {
+    return {
+        excludeTerminal: false,
+        full: true,
+        ...(options.includeBody === undefined
+            ? {}
+            : { includeBody: options.includeBody }),
+        noTruncate: true,
+        outputBudget: "unbounded",
+        outputLimit: "unbounded",
+        strictRead: true,
+    };
+}
+/** Narrow an unknown envelope fragment to a non-array object. */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Append one finding only when its invariant failed. */
+function addFinding(findings, condition, code, message) {
+    if (condition)
+        findings.push({ code, message });
+}
+/** Append source-scan and filter-scope findings for a list envelope. */
+function inspectSourceScope(candidate, findings) {
+    const completeness = isRecord(candidate.completeness)
+        ? candidate.completeness
+        : {};
+    addFinding(findings, completeness.status === "partial", "source_incomplete", "The source scan reported unreadable tracker artifacts.");
+    addFinding(findings, completeness.status !== "complete" && completeness.status !== "partial", "source_unchecked", "The source scan did not prove completeness.");
+    const filters = isRecord(candidate.filters) ? candidate.filters : {};
+    const runtimeFilters = isRecord(filters.runtime_filters)
+        ? filters.runtime_filters
+        : {};
+    const filterEchoKeys = new Set([
+        "exclude_terminal",
+        "include_body",
+        "no_truncate",
+        "runtime_filters",
+        "status",
+        "strict_read",
+    ]);
+    addFinding(findings, filters.status !== "all" ||
+        Object.keys(runtimeFilters).length > 0 ||
+        Object.keys(filters).some((key) => !filterEchoKeys.has(key)), "filtered_corpus", "The list did not explicitly select every lifecycle status.");
+    addFinding(findings, filters.exclude_terminal === true, "terminal_items_excluded", "Terminal lifecycle states were explicitly excluded.");
+    addFinding(findings, filters.strict_read !== true, "strict_read_unproven", "The result does not echo strict source-read enforcement.");
+    return filters;
+}
+/** Append pagination, count, projection, and field-omission findings. */
+function inspectEnvelopeShape(candidate, filters, findings) {
+    addFinding(findings, candidate.has_more !== false ||
+        candidate.next_cursor !== null ||
+        candidate.truncated !== false ||
+        candidate.applied_limit !== undefined ||
+        filters.no_truncate !== true, "page_incomplete", "Pagination or a row ceiling may have withheld items.");
+    addFinding(findings, candidate.count !== candidate.items.length ||
+        candidate.total !== candidate.items.length, "count_mismatch", "Envelope counts do not equal the returned item count.");
+    const projection = isRecord(candidate.projection) ? candidate.projection : {};
+    addFinding(findings, projection.mode !== "full" || projection.fields !== null, "projection_incomplete", "The result is not the full metadata projection.");
+    const omissionReceipt = isRecord(candidate.omission_receipt)
+        ? candidate.omission_receipt
+        : undefined;
+    addFinding(findings, omissionReceipt?.has_omissions === true, "field_omission", "The omission receipt reports withheld field groups.");
+}
+/** Append universal-output and cross-call-session findings. */
+function inspectOutputScope(candidate, findings) {
+    const readOutput = isRecord(candidate.read_output)
+        ? candidate.read_output
+        : undefined;
+    addFinding(findings, readOutput?.strings_compacted === true ||
+        readOutput?.rows_compacted === true ||
+        candidate.output_budget_truncation !== undefined, "budget_compaction", "Universal output shaping compacted the result.");
+    const budgetExceeded = isRecord(candidate.output_budget_exceeded)
+        ? candidate.output_budget_exceeded
+        : undefined;
+    addFinding(findings, readOutput?.result_omitted === true ||
+        budgetExceeded?.omitted_result === true, "budget_omission", "Universal output shaping omitted the useful result.");
+    addFinding(findings, candidate.read_session !== undefined, "session_projection", "A cross-call read session can suppress previously served facts.");
+}
+/** Append row-identity findings that prevent exact set reasoning. */
+function inspectItemIds(items, findings) {
+    const ids = items.map((item) => isRecord(item) && typeof item.id === "string" ? item.id.trim() : "");
+    addFinding(findings, ids.some((id) => id.length === 0), "invalid_item_id", "Every full item row must carry a non-empty string id.");
+    addFinding(findings, new Set(ids).size !== ids.length, "duplicate_item_id", "Every item id must occur exactly once.");
+}
+/** Inspect an unknown result and report every missing whole-corpus invariant. */
+export function inspectCompleteListResult(candidate) {
+    if (!isRecord(candidate) || !Array.isArray(candidate.items)) {
+        return {
+            ok: false,
+            findings: [
+                {
+                    code: PM_COMPLETE_LIST_FINDING_CODES[0],
+                    message: "The result must be an object with an items array.",
+                },
+            ],
+        };
+    }
+    const envelope = candidate;
+    const findings = [];
+    const filters = inspectSourceScope(envelope, findings);
+    inspectEnvelopeShape(envelope, filters, findings);
+    inspectOutputScope(envelope, findings);
+    inspectItemIds(envelope.items, findings);
+    return { ok: findings.length === 0, findings };
+}
+/** Certify a result as the whole tracker corpus or throw a typed recovery error. */
+export function certifyCompleteListResult(candidate) {
+    const inspection = inspectCompleteListResult(candidate);
+    if (!inspection.ok) {
+        throw new PmCompleteListValidationError(inspection.findings);
+    }
+    const result = candidate;
+    return {
+        ...result,
+        complete_list: {
+            contract_version: 1,
+            item_count: result.items.length,
+            unique_item_id_count: new Set(result.items.map((item) => item.id)).size,
+            terminal_items_included: true,
+            source_complete: true,
+            full_projection: true,
+            no_omissions: true,
+            unbounded: true,
+        },
+    };
+}
+/** Assert whole-corpus completeness while narrowing the candidate type in place. */
+export function assertCompleteListResult(candidate) {
+    certifyCompleteListResult(candidate);
+}
+//# sourceMappingURL=complete-list.js.map
+//# debugId=cc342d27-aa2d-5e84-8441-46a35c42dc00