pm-context 2026.10.21 → 2026.10.24

package/dist/index.js

@@ -1,8 +1,16 @@
+import { packCriterionEvidence, encodeEvidencePack, readEvidencePacket, EvidencePackingError } from "./evidence-packing.js";
+export { packCriterionEvidence, encodeEvidencePack, parseEvidencePacket, readEvidencePacket, EvidencePackingError } from "./evidence-packing.js";
+import { createFreshnessReader, encodeFreshness, FreshnessError, parseFreshnessPacket, readFreshnessJson, recordFreshness, resumeFreshness } from "./freshness.js";
+import { checkContextWitnesses, encodeWitnessReport, readWitnessPacket, WitnessError } from "./witnesses.js";
+export { checkContextWitnesses, encodeWitnessReport, parseWitnessPacket, readWitnessPacket, WitnessError } from "./witnesses.js";
+export { createFreshnessReader, encodeFreshness, FRESHNESS_LIMITS, FreshnessError, parseFreshnessPacket, readFreshnessFile, readFreshnessJson, recordFreshness, resumeFreshness } from "./freshness.js";
+import { buildSincePack, encodeSincePack } from "./since.js";
 import { writeFileSync } from "node:fs";
+import { isDeepStrictEqual } from "node:util";
 import { resolveFileFocus, matchFileFocus, rankFileFocus, renderFileFocus, readFileFocusItems } from "./file-focus.js";
 import { createRelationshipKindRegistry, readSettings, resolveRuntimeStatusRegistry, resolveWorkspaceRelationshipKindRegistry, } from "@unbrained/pm-cli/sdk";
-import { list as pmList } from "@unbrained/pm-cli/sdk/core";
-import { buildItemContextRelevanceCandidates, defaultScoreContextCandidates, packContextCandidates, recordContextUsageServing, } from "@unbrained/pm-cli/sdk/query";
+import { listAllComplete } from "@unbrained/pm-cli/sdk/core";
+import { buildItemContextRelevanceCandidates, certifyCompleteListResult, PmCompleteListValidationError, defaultScoreContextCandidates, packContextCandidates, recordContextUsageServing, } from "@unbrained/pm-cli/sdk/query";
 import { DEFAULT_REPORT_LIMIT, renderUsageReport, reportContextUsage, resolveSince } from "./context-usage.js";
 import { readContextUsageAffinity } from "@unbrained/pm-cli/sdk/query";
 import { recordReceiptUsage, reportContextReceipts, renderReceiptReport, serveContextReceipt } from "./context-receipts.js";
@@ -730,97 +738,23 @@ export function renderAgentHandoff(pack, options = {}) {
     return output;
 }
 /**
- * Refuse an incomplete SDK `list-all` result instead of consuming it.
- *
- * Reading `.items` without consulting the result's completeness receipt is how
- * this package once built a context pack from 10 of 682 workspace items and
- * reported success: pm 2026.8.14 defaulted the list to a truncated answer and
- * nothing here checked. Any one of four independent signals means the rows in
- * `items` are NOT the whole workspace, so this throws (never returns a partial
- * list, never logs and continues) naming the signal that tripped plus the
- * `count`/`total` figures:
- *
- * - `truncated === true` — the row list was cut short (output budget, limit);
- * - `has_more === true` — rows exist past the returned cursor boundary;
- * - `completeness.status !== "complete"` — items/directories were unreadable
- *   ("partial") or the corpus was never scanned ("unchecked"); either way the
- *   answer is not attested complete;
- * - `omission_receipt.has_omissions === true` — field groups were dropped from
- *   the projection, so rows are present but degraded.
- *
- * Thrown errors are {@link CommandError} so the command runtime turns them into
- * a clean nonzero exit. Paging is deliberately NOT attempted: a context pack
- * silently built from a partial page is the failure mode this guard exists to
- * prevent, so refusing loudly is simpler and safer.
- *
- * @param result - SDK list result (a result missing its receipt trips the
- *                 completeness signal: an unverifiable answer is not complete).
- * @throws {@link CommandError} naming the first tripped signal and the counts.
+ * Re-certify the full SDK envelope and require its producer's certificate.
+ * The SDK owns corpus and output invariants; this consumer also refuses a
+ * missing or inconsistent producer certificate before constructing a pack.
  */
 export function assertListResultComplete(result) {
-    const count = typeof result.count === "number" ? result.count : result.items.length;
-    const total = typeof result.total === "number" ? result.total : count;
-    const counts = `count ${count} of total ${total}`;
-    if (result.truncated === true) {
-        throw new CommandError(`Refusing incomplete pm list-all result: truncated=true (${counts}). `
-            + "The item list was cut short (output budget or limit); a context pack "
-            + "built from it would silently miss items. Narrow the operation or "
-            + "raise the output budget, then retry.");
-    }
-    if (result.has_more === true) {
-        throw new CommandError(`Refusing incomplete pm list-all result: has_more=true (${counts}). `
-            + "Rows exist beyond the returned page; packing the page as the whole "
-            + "workspace would silently drop them.");
-    }
-    if (result.completeness?.status !== "complete") {
-        const status = result.completeness?.status === undefined
-            ? "(missing)"
-            : JSON.stringify(result.completeness.status);
-        const unreadable = `unreadable_item_count=${result.completeness?.unreadable_item_count ?? 0}`
-            + `, unreadable_directory_count=${result.completeness?.unreadable_directory_count ?? 0}`;
-        throw new CommandError(`Refusing incomplete pm list-all result: completeness.status=${status} `
-            + `(${unreadable}; ${counts}). The workspace corpus behind this list was `
-            + "not attested completely read, so the rows are not the whole workspace.");
-    }
-    const omission = result.omission_receipt;
-    if (omission?.has_omissions === true) {
-        const groups = omission.omitted_field_groups ?? [];
-        throw new CommandError(`Refusing incomplete pm list-all result: omission_receipt.has_omissions=true `
-            + `(omitted_field_groups: ${groups.length ? groups.join(", ") : "(none listed)"}; ${counts}). `
-            + "Field groups were dropped from the projection, so the rows are present "
-            + "but degraded; re-read without the field-omitting options.");
+    const certified = certifyCompleteListResult(result);
+    if (!isDeepStrictEqual(result.complete_list, certified.complete_list)) {
+        throw new PmCompleteListValidationError([{
+                code: "invalid_envelope", message: "Context input requires a matching complete_list certificate from listAllComplete.",
+            }]);
     }
 }
-/**
- * Read every pm item (full metadata + body) in-process through the SDK.
- *
- * Replaces the previous `spawnSync("pm", ["list-all", "--json", "--include-body"])`
- * shell-out with the typed {@link list} action from `@unbrained/pm-cli/sdk/core`.
- * `list-all` is the SDK alias for `list` with `excludeTerminal: false`; passing
- * `full: true` + `includeBody: true` reproduces the full-metadata-with-body
- * projection the shell-out parsed. `noTruncate: true` deliberately overrides any
- * truncating limit and `strictRead: true` makes unreadable corpus entries a hard
- * SDK error, and the returned receipt is STILL verified by
- * {@link assertListResultComplete} — the 2026.8.14 truncated-default regression
- * is exactly the silently-partial read this package refuses to reintroduce, so
- * the guard does not trust the request options alone. Being an in-process SDK
- * action (no child process), there is no spawn stdout buffer to size here; the
- * completeness receipt is the over-run guard.
- *
- * @param pmRoot - Tracker storage root to read.
- * @param list - Injectable SDK list action (tests substitute a canned real
- *               result); defaults to the real {@link pmList}.
- */
-export async function readPmItems(pmRoot, list = pmList) {
-    let result;
-    try {
-        result = await list({ full: true, includeBody: true, excludeTerminal: false, noTruncate: true, strictRead: true }, { pmRoot });
-    }
-    catch (err) {
-        throw new CommandError(`Could not read pm items via SDK list: ${err instanceof Error ? err.message : String(err)}`);
-    }
+/** Read all types and lifecycle states without extension side effects, preserving SDK refusals. */
+export async function readPmItems(pmRoot, list = listAllComplete) {
+    const result = await list({ includeBody: true }, { pmRoot, noExtensions: true });
     assertListResultComplete(result);
-    return result.items.filter((item) => typeof item.id === "string");
+    return result.items;
 }
 /** Per-item token estimate for one character of text (rough 4 chars/token). */
 const TOKENS_PER_CHAR = 0.25;
@@ -936,21 +870,22 @@ function estimateProjectionCosts(item) {
  * focus items are required anchors, neighbors compete by relevance rank for the
  * remaining budget. The packer first selects under that token budget with pm's
  * projection-degradation optimizer, then enforces the command's explicit item
- * ceiling while preserving the SDK-selected focus-first order.
+ * ceiling. The incoming focus order is authoritative (including file-overlap
+ * ranking); corpus ranks apply only to neighbors, so equal-cost focus ties keep
+ * the selection order established by buildContextPack.
  */
 export function createSdkPacker(rankedFocus, rankedNeighbors) {
-    const focusRank = new Map(rankedFocus.map((item, index) => [item.id, index + 1]));
     const neighborRank = new Map(rankedNeighbors.map((item, index) => [item.id, rankedFocus.length + index + 1]));
     return (focus, neighbors, maxItems) => {
         if (!(maxItems > 0))
             return { focus, neighbors };
         const tokenBudget = maxItems * TOKENS_PER_ITEM_SLOT;
         const candidates = [
-            ...focus.map((item) => ({
+            ...focus.map((item, index) => ({
                 id: item.id,
                 item,
-                rank: focusRank.get(item.id) ?? 1,
-                score: 1 / (focusRank.get(item.id) ?? 1),
+                rank: index + 1,
+                score: 1 / (index + 1),
                 token_costs: estimateProjectionCosts(item),
                 required: true,
             })),
@@ -1108,7 +1043,7 @@ async function recordPackServing(ctx, focus, neighbors) {
  */
 async function measureContextOutput(ctx, pack, output, format, command, compress, outputPath) {
     try {
-        const measured = serveContextReceipt(ctx.pm_root, output, format === "json" ? "json" : "text", {
+        const measured = await serveContextReceipt(ctx.pm_root, output, format === "json" ? "json" : "text", {
             item_ids: [...pack.items, ...pack.neighbors].map((item) => item.id),
             files: pack.links.filter((link) => link.kind === "file"),
         }, {
@@ -1188,7 +1123,7 @@ function setupCommands(api) {
                 throw new CommandError("--format must be markdown, json, agent, or compact", EXIT_CODE.USAGE);
             }
             const selection = resolveSelectionOptions(options);
-            const fileFocus = resolveFileFocus(options, ctx.args, ctx.repo_root ?? ctx.source_workspace_root ?? process.cwd(), ctx.pm_root);
+            const fileFocus = resolveFileFocus(options, ctx.args, ctx.repo_root ?? ctx.source_workspace_root ?? process.cwd(), ctx.pm_root, process.cwd());
             const limit = intOption(options, "limit", contextPackDefaultLimit);
             const includeBody = boolOption(options, "include-body", "includeBody");
             const includeClosed = boolOption(options, "include-closed", "includeClosed");
@@ -1203,8 +1138,8 @@ function setupCommands(api) {
             const items = fileFocus ? await readFileFocusItems(ctx.pm_root) : await readPmItems(ctx.pm_root);
             const rankOptions = await resolveSdkRankOptions(ctx);
             const ranker = createSdkRanker(items, rankOptions);
-            // Pre-rank the full corpus so the token-budgeted packer has relevance ranks
-            // for both focus and neighbor candidates before buildContextPack trims.
+            // Pre-rank the corpus for neighbor relevance. Focus arrives in the final
+            // selection order, including file overlap, after buildContextPack trims.
             let packer;
             if (maxItems) {
                 const rankedAll = rankContextItems(items, rankOptions);
@@ -1299,6 +1234,96 @@ function setupCommands(api) {
             return renderedCommandResult(output);
         },
     });
+    api.registerCommand({
+        name: "context-evidence",
+        description: "Pack explicit criterion evidence with exact coverage lost at a byte budget.",
+        flags: [
+            { long: "--packet", value_name: "file", description: "JSON acceptance criteria and tracker field bindings", type: "string" },
+            { long: "--format", value_name: "format", description: "toon (default) or json", type: "string" },
+            { long: "--byte-budget", value_name: "n", description: "Complete-output UTF-8 byte ceiling (default 4000)", type: "string" },
+        ],
+        async run(ctx) {
+            const path = stringOption(ctx.options, "packet");
+            const format = stringOption(ctx.options, "format") ?? (ctx.global.json ? "json" : "toon");
+            if (!path || (format !== "json" && format !== "toon") || ctx.args.length)
+                throw new EvidencePackingError("INVALID_ARGUMENT", "Supply --packet JSON with --format json or toon; no positional arguments are accepted.");
+            const pack = await packCriterionEvidence(readEvidencePacket(path), createFreshnessReader(ctx.pm_root, "."), {
+                format, byteBudget: Number(stringOption(ctx.options, "byte-budget", "byteBudget") ?? "4000"),
+            });
+            return renderedCommandResult(encodeEvidencePack(pack, format));
+        },
+    });
+    api.registerCommand({
+        name: "context-witnesses",
+        description: "Find the smallest cited contradiction among declared packet assertions without editing sources.",
+        flags: [
+            { long: "--packet", value_name: "file", description: "JSON packet of cited co-current claims", type: "string" },
+            { long: "--format", value_name: "format", description: "toon (default) or json", type: "string" },
+            { long: "--byte-budget", value_name: "n", description: "Complete-output UTF-8 byte ceiling (default 4000)", type: "string" },
+        ],
+        async run(ctx) {
+            const path = stringOption(ctx.options, "packet");
+            const format = stringOption(ctx.options, "format") ?? (ctx.global.json ? "json" : "toon");
+            if (!path || (format !== "json" && format !== "toon") || ctx.args.length)
+                throw new WitnessError("INVALID_ARGUMENT", "Supply --packet JSON with --format json or toon; no positional arguments are accepted.");
+            const budget = Number(stringOption(ctx.options, "byte-budget", "byteBudget") ?? "4000");
+            const report = checkContextWitnesses(readWitnessPacket(path));
+            return renderedCommandResult(encodeWitnessReport(report, format, budget));
+        },
+    });
+    for (const action of ["record", "resume"]) {
+        api.registerCommand({
+            name: `context-freshness ${action}`,
+            description: action === "record" ? "Record source digests behind declared packet assumptions." : "Return only assumptions invalidated by later source changes.",
+            flags: [
+                { long: "--packet", value_name: "file", description: "JSON packet with section content and source dependencies", type: "string" },
+                { long: "--manifest", value_name: "file", description: "Original JSON digest manifest (resume only)", type: "string" },
+                { long: "--evidence-root", value_name: "directory", description: "Root for relative evidence files (default: source workspace)", type: "string" },
+                { long: "--format", value_name: "format", description: "Record: json; resume: toon (default) or json", type: "string" },
+                { long: "--byte-budget", value_name: "n", description: "Output UTF-8 byte ceiling (default: record 262144; resume 4000)", type: "string" },
+            ],
+            async run(ctx) {
+                const path = stringOption(ctx.options, "packet");
+                const manifestPath = stringOption(ctx.options, "manifest");
+                const format = stringOption(ctx.options, "format") ?? (ctx.global.json || action === "record" ? "json" : "toon");
+                if (!path || (action === "resume" ? !manifestPath : Boolean(manifestPath)) || (format !== "json" && format !== "toon") || (action === "record" && format !== "json")) {
+                    throw new FreshnessError("INVALID_ARGUMENT", "Supply --packet JSON; resume also requires --manifest JSON. Record uses json; resume accepts --format json or toon.");
+                }
+                const budget = Number(stringOption(ctx.options, "byte-budget", "byteBudget") ?? (action === "record" ? "262144" : "4000"));
+                if (!Number.isSafeInteger(budget) || budget < 512)
+                    throw new FreshnessError("INVALID_ARGUMENT", "Use an integer --byte-budget of at least 512.");
+                const packet = parseFreshnessPacket(readFreshnessJson(path));
+                const read = createFreshnessReader(ctx.pm_root, stringOption(ctx.options, "evidence-root", "evidenceRoot") ?? ctx.source_workspace_root ?? ctx.repo_root ?? process.cwd());
+                if (action === "record")
+                    return renderedCommandResult(encodeFreshness(await recordFreshness(packet, read), "json", Math.min(budget, 262144)));
+                const report = await resumeFreshness(packet, readFreshnessJson(manifestPath), read);
+                const output = encodeFreshness(report, format, budget);
+                if (report.code === "SOURCE_UNAVAILABLE")
+                    process.exitCode = EXIT_CODE.USAGE;
+                return renderedCommandResult(output);
+            },
+        });
+    }
+    api.registerCommand({
+        name: "context-pack since",
+        description: "Resume with ranked changes, substantive excerpts, claims and an opaque cursor.",
+        flags: [
+            { long: "--cursor", value_name: "token", description: "Resume a retained delta checkpoint", type: "string" },
+            { long: "--from", value_name: "timestamp", description: "Start from an inclusive ISO timestamp", type: "string" },
+            { long: "--token-budget", value_name: "n", description: "Complete JSON byte-token upper bound (default: 4000)", type: "string" },
+        ],
+        async run(ctx) {
+            const settings = await readSettings(ctx.pm_root);
+            const registry = resolveRuntimeStatusRegistry(settings.schema);
+            const pack = await buildSincePack(ctx.pm_root, await readPmItems(ctx.pm_root), new Set(registry.terminal_statuses), {
+                cursor: stringOption(ctx.options, "cursor"),
+                from: stringOption(ctx.options, "from"),
+                author: ctx.global.author ?? process.env.PM_AUTHOR ?? settings.author_default,
+                tokenBudget: Number(stringOption(ctx.options, "token-budget", "tokenBudget") ?? "4000"),
+            });
+            return renderedCommandResult(encodeSincePack(pack));
+        },
+    });
     api.registerCommand({
         name: "context-handoff",
         description: "Generate an agent-ready handoff with concise defaults.",
@@ -1460,7 +1485,7 @@ function setupCommands(api) {
                 if (!receiptId)
                     throw new CommandError("Usage evidence requires --receipt", EXIT_CODE.USAGE);
                 try {
-                    recordReceiptUsage(ctx.pm_root, { receipt_id: receiptId, session, citations, touched_items: touchedItems, edited_files: editedFiles });
+                    await recordReceiptUsage(ctx.pm_root, { receipt_id: receiptId, session, citations, touched_items: touchedItems, edited_files: editedFiles });
                 }
                 catch (error) {
                     throw new CommandError(error instanceof Error ? error.message : String(error), EXIT_CODE.USAGE);
@@ -1501,13 +1526,13 @@ function setupCommands(api) {
 /** Register context commands and renderers with checked host behavior and package metadata. */
 export default {
     name: "pm-context",
-    version: "2026.10.21",
+    version: "2026.10.24",
     description: "Generate deterministic pm context packs for agent handoffs, reviews, and status briefs",
     activate(api) {
         setupCommands(api);
         if (typeof api.registerRenderer === "function") {
             const rendererOwnership = {
-                commands: ["context-pack", "context-handoff", "context-usage"],
+                commands: ["context-pack", "context-pack since", "context-handoff", "context-usage", "context-freshness record", "context-freshness resume", "context-witnesses", "context-evidence"],
                 resultDiscriminator: isRenderedCommandResult,
             };
             api.registerRenderer("toon", renderCommandResult, rendererOwnership);