@unbrained/pm-cli 2026.8.12 → 2026.8.13

package/dist/sdk/merge/install.js

@@ -8,7 +8,8 @@
  * mutations refresh the fenced block automatically once it is installed.
  */
 
-!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]="94d2a7a8-ce00-5689-b2f6-3d4813234b55")}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]="5e1810a5-04b8-5929-8eee-7a63f1684860")}catch(e){}}();
+import { isFileMissingError } from "../../core/fs/fs-utils.js";
 import { readFile, realpath, writeFile } from "node:fs/promises";
 import { execFile } from "node:child_process";
 import path from "node:path";
@@ -253,7 +254,7 @@ async function reconcileGitattributesBlock(workspaceRoot, patterns, dryRun) {
         current = await readFile(gitattributesPath, "utf8");
     }
     catch (error) {
-        if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
+        if (!(error instanceof Error && "code" in error && isFileMissingError(error))) {
             throw error;
         }
     }
@@ -414,7 +415,7 @@ export async function refreshMergeAttributeFenceIfInstalled(pmRoot) {
         catch (error) {
             if (error instanceof Error &&
                 "code" in error &&
-                error.code === "ENOENT") {
+                isFileMissingError(error)) {
                 return { status: "not_installed", path: gitattributesPath };
             }
             throw error;
@@ -560,4 +561,4 @@ export async function installMergeFence(options) {
     };
 }
 //# sourceMappingURL=install.js.map
-//# debugId=94d2a7a8-ce00-5689-b2f6-3d4813234b55
+//# debugId=5e1810a5-04b8-5929-8eee-7a63f1684860

package/dist/sdk/query/activity.js

@@ -4,7 +4,8 @@
  * Implements the pm activity 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]="27a71d4d-f496-5d0a-9771-caa43b81e1f7")}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]="49304d18-d722-5413-8e4d-4f2c3df4a1ca")}catch(e){}}();
+import { isFileMissingError } from "../../core/fs/fs-utils.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getActiveExtensionRegistrations, runActiveOnReadHooks, pathExists, enforceHistoryStreamPolicyForItems, resolveItemTypeRegistry, EXIT_CODE, PmCliError, compareTimestampStrings, nowIso, resolveIsoOrRelative, listAllItemMetadataLight, getSettingsPath, resolvePmRoot, readSettings, } from "../runtime-primitives.js";
@@ -107,7 +108,7 @@ async function listHistoryFiles(historyDir) {
     }
     catch (error) {
         // Activity should degrade gracefully when optional history storage is absent.
-        if (error.code === "ENOENT") {
+        if (isFileMissingError(error)) {
             return [];
         }
         throw error;
@@ -399,4 +400,4 @@ export async function runActivity(options, global) {
     };
 }
 //# sourceMappingURL=activity.js.map
-//# debugId=27a71d4d-f496-5d0a-9771-caa43b81e1f7
+//# debugId=49304d18-d722-5413-8e4d-4f2c3df4a1ca

package/dist/sdk/relationship-history.js

@@ -5,13 +5,13 @@
  * optimistic concurrency, deterministic replay, snapshots, and cursor pages.
  */
 
-!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]="c53bb1b7-12b9-5370-a85b-cdd8bef57936")}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]="bb5dfa6f-b60f-55f2-ae17-3dbcaaff1b47")}catch(e){}}();
 import { createQueryFingerprint, decodeQueryCursorState, paginateQueryRows, } from "./pagination.js";
 import { constants } from "node:fs";
 import { lstat, mkdir, open } from "node:fs/promises";
 import path from "node:path";
 import { acquireLock } from "../core/lock/lock.js";
-import { writeFileAtomic } from "../core/fs/fs-utils.js";
+import { isFileMissingError, writeFileAtomic } from "../core/fs/fs-utils.js";
 import { stableStringify } from "../core/shared/serialization.js";
 import { RelationshipGraph, createRelationshipKindRegistry, } from "./relationships.js";
 function requiredText(value, field) {
@@ -298,7 +298,7 @@ async function resolveRelationshipEventStorePath(pmRoot, relativePath = "relatio
                 throw new TypeError("Relationship event path must not contain symbolic links");
         }
         catch (error) {
-            if (error.code === "ENOENT")
+            if (isFileMissingError(error))
                 break;
             throw error;
         }
@@ -314,7 +314,7 @@ async function loadRelationshipEventLog(target, nodes, registry) {
         raw = await handle.readFile("utf8");
     }
     catch (error) {
-        if (error.code === "ENOENT")
+        if (isFileMissingError(error))
             return { log, raw: "" };
         throw error;
     }
@@ -517,4 +517,4 @@ export class RelationshipEventStore {
     }
 }
 //# sourceMappingURL=relationship-history.js.map
-//# debugId=c53bb1b7-12b9-5370-a85b-cdd8bef57936
+//# debugId=bb5dfa6f-b60f-55f2-ae17-3dbcaaff1b47

package/dist/sdk/schema-migration.js

@@ -7,11 +7,11 @@
  * guarantees.
  */
 
-!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]="7d175791-016d-59b6-a44d-a70371f36751")}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]="cd777de3-665f-5e01-ac98-8986f2a5a4c2")}catch(e){}}();
 import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { pathExists, readFileIfExists, writeFileAtomic, } from "../core/fs/fs-utils.js";
+import { isFileMissingError, pathExists, readFileIfExists, writeFileAtomic, } from "../core/fs/fs-utils.js";
 import { appendWorkspaceHistoryChange } from "../core/history/workspace-history.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
 import { parseFieldsFile, serializeFieldsFile, } from "../core/schema/fields-file.js";
@@ -681,7 +681,7 @@ async function collectSchemaReferenceState(params) {
         if (typeof error !== "object" ||
             error === null ||
             !("code" in error) ||
-            error.code !== "ENOENT") {
+            !isFileMissingError(error)) {
             throw error;
         }
     }
@@ -855,4 +855,4 @@ export const schemaMigrationTestOnly = {
     validateAndStoreMigrationPlan,
 };
 //# sourceMappingURL=schema-migration.js.map
-//# debugId=7d175791-016d-59b6-a44d-a70371f36751
+//# debugId=cd777de3-665f-5e01-ac98-8986f2a5a4c2

package/dist/sdk/test/execution.js

@@ -4,13 +4,13 @@
  * Implements the pm test 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]="b40f54be-2d3e-5b98-9d49-cb8608a782f5")}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]="76053150-cc55-57e0-80d6-369196284cd0")}catch(e){}}();
 import { spawn } from "node:child_process";
 import { cp, mkdir, mkdtemp, open, readdir, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
-import { pathExists } from "../../core/fs/fs-utils.js";
+import { isFileMissingError, pathExists } from "../../core/fs/fs-utils.js";
 import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
 import { createStdinTokenResolver, parseCsvKv, parseOptionalNumber, } from "../../core/item/parse.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
@@ -989,7 +989,7 @@ async function copyIntoSandboxIfPresent(sourcePath, targetPath, recursive = fals
         if (typeof error === "object" &&
             error !== null &&
             "code" in error &&
-            error.code === "ENOENT") {
+            isFileMissingError(error)) {
             return;
         }
         throw error;
@@ -1939,4 +1939,4 @@ export const _testOnlyTestCommand = {
     summarizeRunResultStatuses,
 };
 //# sourceMappingURL=execution.js.map
-//# debugId=b40f54be-2d3e-5b98-9d49-cb8608a782f5
+//# debugId=76053150-cc55-57e0-80d6-369196284cd0

package/dist/sdk/workspace-memory.js

@@ -4,10 +4,10 @@
  * Builds compact, cursor-bound historical rollups for large workspaces.
  */
 
-!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]="2e225010-1b53-59e9-8188-dcbe4a4f7eb7")}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]="ad77a79d-54da-55f1-8ac8-935366880d90")}catch(e){}}();
 import path from "node:path";
 import { createHash } from "node:crypto";
-import { writeFileAtomic } from "../core/fs/fs-utils.js";
+import { isFileAbsentError, writeFileAtomic } from "../core/fs/fs-utils.js";
 import { normalizeStatusForRegistry } from "../core/item/status.js";
 import { stableStringify } from "../core/shared/serialization.js";
 import { readItemMetadataDerivedIndexState } from "../core/store/item-metadata-cache.js";
@@ -194,7 +194,7 @@ async function readPersistedWorkspaceMemory(filePath) {
         const missing = typeof error === "object" &&
             error !== null &&
             "code" in error &&
-            error.code === "ENOENT";
+            isFileAbsentError(error);
         return { snapshot: null, invalid: !missing };
     }
 }
@@ -316,4 +316,4 @@ export function searchWorkspaceMemoryReadResult(memory, query, limit = 5) {
     };
 }
 //# sourceMappingURL=workspace-memory.js.map
-//# debugId=2e225010-1b53-59e9-8188-dcbe4a4f7eb7
+//# debugId=ad77a79d-54da-55f1-8ac8-935366880d90

package/dist/sdk/workspace-snapshot.js

@@ -5,11 +5,11 @@
  * state while excluding clone-local caches, locks, and recovery journals.
  */
 
-!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]="470bb466-4619-5c54-a154-186b7ef4a049")}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]="36aacc71-c5f5-56f1-85f4-28b2be5b02e2")}catch(e){}}();
 import crypto from "node:crypto";
 import { cp, lstat, mkdir, readFile, readdir, rename, rm, writeFile, } from "node:fs/promises";
 import path from "node:path";
-import { writeFileAtomic } from "../core/fs/fs-utils.js";
+import { isFileMissingError, writeFileAtomic } from "../core/fs/fs-utils.js";
 import { appendWorkspaceAuditEvent } from "../core/history/workspace-history.js";
 import { acquireLock } from "../core/lock/lock.js";
 import { getLockPath } from "../core/store/paths.js";
@@ -205,12 +205,6 @@ function validateSnapshotTarget(target) {
         });
     }
 }
-function isErrno(error, code) {
-    return (typeof error === "object" &&
-        error !== null &&
-        "code" in error &&
-        error.code === code);
-}
 /**
  * Runs a bounded snapshot filesystem stage, converting host environment faults
  * into declared refusals.
@@ -250,7 +244,7 @@ async function readSnapshotJson(file, target) {
         return JSON.parse(await readFile(file, "utf8"));
     }
     catch (error) {
-        if (isErrno(error, "ENOENT")) {
+        if (isFileMissingError(error)) {
             throw workspaceSnapshotNotFound(target);
         }
         throw error;
@@ -261,7 +255,7 @@ async function removeSnapshotEntry(entry, target, recursive) {
         await rm(entry, { recursive });
     }
     catch (error) {
-        if (isErrno(error, "ENOENT")) {
+        if (isFileMissingError(error)) {
             throw workspaceSnapshotNotFound(target);
         }
         throw error;
@@ -335,7 +329,7 @@ export async function createWorkspaceSnapshot(pmRoot, options = {}) {
         deduplicated = objectStat.isDirectory();
     }
     catch (error) {
-        if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
+        if (!(error instanceof Error && "code" in error && isFileMissingError(error))) {
             throw error;
         }
     }
@@ -392,7 +386,7 @@ export async function listWorkspaceSnapshots(pmRoot) {
     const objectNames = await readdir(path.join(store, "objects")).catch((error) => {
         if (error instanceof Error &&
             "code" in error &&
-            error.code === "ENOENT") {
+            isFileMissingError(error)) {
             return [];
         }
         throw error;
@@ -400,7 +394,7 @@ export async function listWorkspaceSnapshots(pmRoot) {
     const referenceNames = await readdir(path.join(store, "refs")).catch((error) => {
         if (error instanceof Error &&
             "code" in error &&
-            error.code === "ENOENT") {
+            isFileMissingError(error)) {
             return [];
         }
         throw error;
@@ -609,4 +603,4 @@ export async function deleteWorkspaceSnapshot(pmRoot, target) {
     return { deleted: "object", target };
 }
 //# sourceMappingURL=workspace-snapshot.js.map
-//# debugId=470bb466-4619-5c54-a154-186b7ef4a049
+//# debugId=36aacc71-c5f5-56f1-85f4-28b2be5b02e2

package/dist/sdk/workspace-transaction-gc.js

@@ -13,17 +13,12 @@
  * never breaks correctness.
  */
 
-!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]="a6c0aa24-501a-5e76-a669-91d125634cf1")}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]="7df80849-51e1-5efa-b40a-b44088f941a9")}catch(e){}}();
+import { isFileMissingError } from "../core/fs/fs-utils.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 const MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000;
 const TERMINAL_JOURNAL_STATUSES = new Set(["committed", "compensated"]);
-function isErrno(error, code) {
-    return (typeof error === "object" &&
-        error !== null &&
-        "code" in error &&
-        error.code === code);
-}
 function readJournalStatusAndTimestamp(raw) {
     let parsed;
     try {
@@ -129,7 +124,7 @@ export async function runWorkspaceTransactionGc(pmRoot, options) {
             .sort((left, right) => left.localeCompare(right));
     }
     catch (error) {
-        if (isErrno(error, "ENOENT")) {
+        if (isFileMissingError(error)) {
             return result;
         }
         throw error;
@@ -152,4 +147,4 @@ export async function runWorkspaceTransactionGc(pmRoot, options) {
     return result;
 }
 //# sourceMappingURL=workspace-transaction-gc.js.map
-//# debugId=a6c0aa24-501a-5e76-a669-91d125634cf1
+//# debugId=7df80849-51e1-5efa-b40a-b44088f941a9

package/dist/sdk/workspace-transaction.js

@@ -5,11 +5,11 @@
  * mutation primitives without rewriting immutable item or relationship history.
  */
 
-!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]="d49ec604-c10c-5706-9d87-510845e55e1a")}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]="6ed4a26f-2ae2-556a-87db-56844108757f")}catch(e){}}();
 import { mkdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { acquireLock } from "../core/lock/lock.js";
-import { writeFileAtomic } from "../core/fs/fs-utils.js";
+import { isFileMissingError, writeFileAtomic } from "../core/fs/fs-utils.js";
 import { nowIso } from "../core/shared/time.js";
 /**
  * Deliberate process-boundary interruption used by deterministic crash tests.
@@ -244,7 +244,7 @@ async function loadJournal(pmRoot, transactionId, stepIds) {
         if (error !== null &&
             typeof error === "object" &&
             "code" in error &&
-            error.code === "ENOENT")
+            isFileMissingError(error))
             return undefined;
         throw error;
     }
@@ -361,4 +361,4 @@ export async function commitWorkspaceTransaction(options) {
     }
 }
 //# sourceMappingURL=workspace-transaction.js.map
-//# debugId=d49ec604-c10c-5706-9d87-510845e55e1a
+//# debugId=6ed4a26f-2ae2-556a-87db-56844108757f

package/dist/sdk/workspace.js

@@ -4,7 +4,8 @@
  * Maintains repository-scaffold contracts shared by the public SDK and CLI.
  */
 
-!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]="bbfa5b19-d801-582a-98e8-0c4925dd57c0")}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]="89261a49-97e5-5ffc-a81c-2409f0b529cf")}catch(e){}}();
+import { isFileMissingError } from "../core/fs/fs-utils.js";
 import { readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { EXIT_CODE } from "../core/shared/constants.js";
@@ -107,7 +108,7 @@ export async function ensurePmGitignore(workspaceRoot, options = {}) {
         current = await withGitignorePermissionRecovery(() => readFile(gitignorePath, "utf8"));
     }
     catch (error) {
-        if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
+        if (!(error instanceof Error && "code" in error && isFileMissingError(error))) {
             throw error;
         }
     }
@@ -125,4 +126,4 @@ export async function ensurePmGitignore(workspaceRoot, options = {}) {
     return { path: gitignorePath, changed: true };
 }
 //# sourceMappingURL=workspace.js.map
-//# debugId=bbfa5b19-d801-582a-98e8-0c4925dd57c0
+//# debugId=89261a49-97e5-5ffc-a81c-2409f0b529cf

package/docs/ASSURANCE.md

@@ -1,6 +1,6 @@
 # Project Assurance Primitives
 
-Tracker: [pm-2lex4r](../.agents/pm/features/pm-2lex4r.toon), [pm-lyfu7b](../.agents/pm/features/pm-lyfu7b.toon), [pm-wn6wot](../.agents/pm/features/pm-wn6wot.toon), [pm-91xeam](../.agents/pm/features/pm-91xeam.toon), [pm-py7qv2](../.agents/pm/issues/pm-py7qv2.toon), [pm-33mjrw](../.agents/pm/issues/pm-33mjrw.toon), [pm-q6n8sj](../.agents/pm/issues/pm-q6n8sj.toon)
+Tracker: [pm-2lex4r](../.agents/pm/features/pm-2lex4r.toon), [pm-lyfu7b](../.agents/pm/features/pm-lyfu7b.toon), [pm-wn6wot](../.agents/pm/features/pm-wn6wot.toon), [pm-91xeam](../.agents/pm/features/pm-91xeam.toon), [pm-uhv1m5](../.agents/pm/features/pm-uhv1m5.toon), [pm-m7bb7r](../.agents/pm/features/pm-m7bb7r.toon), [pm-py7qv2](../.agents/pm/issues/pm-py7qv2.toon), [pm-33mjrw](../.agents/pm/issues/pm-33mjrw.toon), [pm-q6n8sj](../.agents/pm/issues/pm-q6n8sj.toon)
 
 ## Agent Quick Context
 
@@ -36,6 +36,11 @@ Measurements support these built-in sources:
 
 Each measurement may declare `max_cost`. Evaluation fails closed when the total abstract compute units exceed that ceiling. Every result reports units, scanned items, scanned history rows, provider calls, duration, population size, and contributors.
 
+One workspace context memoizes identical graph operations and the shared
+validate and health reports for its lifetime. A gate may therefore project many
+fields from one authoritative audit snapshot without multiplying full-workspace
+I/O or allowing concurrent assertions to observe different tracker states.
+
 An `items` source with `field` must declare exactly one predicate: `equals` (including an explicit `null`) or `state`. `state: missing` treats an absent property, `null`, an empty string, or an empty array as missing; `state: present` selects the complement. Workspace evaluation loads full item metadata, so `files`, `tests`, and `docs` selectors measure stored evidence rather than a light projection that omitted those collections.
 
 Assertions require exactly one polarity:
@@ -86,6 +91,152 @@ pm assurance remove gate release-readiness
 
 Referenced measurements and assertions cannot be removed. Remove the consuming gate or assertion first.
 
+### Presets, derivation, and promotion
+
+List the four built-in project shapes, preview one as ordinary declarations, or apply it atomically:
+
+```bash
+pm assurance presets
+pm assurance presets software-delivery --owner pm-example
+pm assurance apply software-delivery --owner pm-example \
+  --message "Adopt the initial delivery evidence contract"
+```
+
+The preset creates measurements, assertions, and a gate in one audited transaction. Reapplying the same bundle is idempotent; an existing divergent id is refused rather than overwritten. The available shapes are `software-delivery`, `research`, `agent-evaluation`, and `operations`.
+
+Self-derivation observes active items without writing anything. Each proposal reports its active scope, population size, and observed missing-evidence ceiling. Persistence requires the explicit `--apply` flag:
+
+```bash
+pm assurance derive --owner pm-example
+pm assurance derive --owner pm-example --apply \
+  --message "Accept the observed evidence baseline"
+pm assurance promote derived-active-missing-tests-ceiling --enforcement warn
+pm assurance promote derived-active-missing-tests-ceiling --enforcement block
+```
+
+Derived assertions start at `observe`. Promotion is exactly one step (`observe` to `warn`, then `warn` to `block`) and each transition is an ordinary audited declaration mutation. There is no automatic promotion and no privileged preset execution path.
+
+## Extension Measurement Providers
+
+An extension opens the measurement vocabulary through `api.registerAssuranceMeasurementProvider`. The registration declares stable keys, parameter types, a coarse `low`/`medium`/`high` cost class, network use, a host timeout, and a resolver. It requires the `services` capability; a network provider must also declare `permissions.network: true` in `manifest.json`.
+
+This code-quality provider measures a local report without changing assertion or gate semantics:
+
+```ts
+import { readFile } from "node:fs/promises";
+import { defineExtension } from "@unbrained/pm-cli/sdk";
+
+export default defineExtension({
+  activate(api) {
+    api.registerAssuranceMeasurementProvider({
+      id: "coverage",
+      keys: {
+        lines: {
+          value_type: "number",
+          parameters: { report: { type: "string", required: true } },
+        },
+      },
+      cost_class: "low",
+      network: false,
+      timeout_ms: 2_000,
+      async resolve({ parameters }) {
+        const report = JSON.parse(
+          await readFile(String(parameters.report), "utf8"),
+        ) as {
+          total: { lines: { pct: number } };
+        };
+        return { value: report.total.lines.pct, population_size: 1, cost: 1 };
+      },
+    });
+  },
+});
+```
+
+An evaluation package can expose episode reward on the same surface:
+
+```ts
+api.registerAssuranceMeasurementProvider({
+  id: "agent-eval",
+  keys: {
+    "mean-reward": {
+      value_type: "number",
+      parameters: { suite: { type: "string", required: true } },
+    },
+  },
+  cost_class: "high",
+  network: false,
+  timeout_ms: 120_000,
+  async resolve({ parameters }) {
+    const result = await runFrozenEvaluation(String(parameters.suite));
+    return {
+      value: result.meanReward,
+      population_size: result.episodes,
+      cost: result.steps,
+      contributors: result.regressedScenarioIds,
+    };
+  },
+});
+```
+
+An external registry provider declares its network dependency explicitly:
+
+```ts
+api.registerAssuranceMeasurementProvider({
+  id: "npm-registry",
+  keys: {
+    "dist-tag-count": {
+      value_type: "number",
+      parameters: { package: { type: "string", required: true } },
+    },
+  },
+  cost_class: "medium",
+  network: true,
+  timeout_ms: 5_000,
+  async resolve({ parameters }) {
+    const name = encodeURIComponent(String(parameters.package));
+    const response = await fetch(
+      `https://registry.npmjs.org/-/package/${name}/dist-tags`,
+    );
+    if (!response.ok) throw new Error(`registry returned ${response.status}`);
+    const tags = (await response.json()) as Record<string, string>;
+    return { value: Object.keys(tags).length, population_size: 1, cost: 10 };
+  },
+});
+```
+
+The corresponding measurement is ordinary registry data:
+
+```json
+{
+  "id": "published-tag-count",
+  "source": {
+    "kind": "provider",
+    "provider": "npm-registry",
+    "key": "dist-tag-count",
+    "parameters": { "package": "@example/tool" }
+  }
+}
+```
+
+A provider-backed gate must opt into every provider and each trigger's execution envelope. Omission refuses provider execution:
+
+```json
+{
+  "id": "release-readiness",
+  "assertion_ids": ["published-tag-count-ceiling"],
+  "triggers": ["ci", "scheduled"],
+  "provider_policy": {
+    "allowed_providers": ["npm-registry"],
+    "triggers": {
+      "ci": { "max_cost_class": "low", "allow_network": false },
+      "scheduled": { "max_cost_class": "medium", "allow_network": true }
+    }
+  }
+}
+```
+
+Before invocation the host verifies the provider allow-list, declared cost class, and network capability for the active trigger. It then validates key parameters and result shape, enforces the registered timeout, and charges the returned cost through the existing measurement ceiling. Extension tests must bind `PM_PATH` and `PM_GLOBAL_PATH` to temporary roots; never point provider fixtures at the repository tracker or a live service.
+
 ## SDK and MCP
 
 The reusable client exposes the same action grammar:
@@ -103,9 +254,9 @@ await pm.assurance({
 });
 ```
 
-For direct host composition, use `evaluateMeasurement`, `evaluateAssuranceGate`, `createAssuranceWorkspaceContext`, and the audited declaration/verdict helpers exported from `@unbrained/pm-cli/sdk`. A host contributes provider measurements by passing stable resolver ids to `createAssuranceWorkspaceContext`; an absent resolver fails loudly. External adapters must enforce an appropriate timeout. The core evaluator bounds concurrent assertions and expression operands, and workspace history loading uses bounded concurrency; item-only callers can explicitly skip history and Git identity resolution.
+For direct host composition, use `evaluateMeasurement`, `evaluateAssuranceGate`, `createAssuranceWorkspaceContext`, the preset/derivation helpers, and the audited declaration/verdict helpers exported from `@unbrained/pm-cli/sdk`. Active extension registrations are discovered automatically. Embedding hosts may additionally pass stable resolver ids and matching `provider_capabilities` to `createAssuranceWorkspaceContext`; an absent resolver or capability fails loudly. The core evaluator bounds concurrent assertions and expression operands, and workspace history loading uses bounded concurrency; item-only callers can explicitly skip history and Git identity resolution.
 
-Generic SDK and MCP dispatch use `action: "assurance"` with `subcommand` set to `list`, `show`, `put`, `remove`, `run`, or `verdicts`. Discover the current machine contract instead of copying parameter lists:
+Generic SDK and MCP dispatch use `action: "assurance"` with `subcommand` set to `list`, `show`, `put`, `remove`, `run`, `verdicts`, `presets`, `apply`, `derive`, or `promote`. Discover the current machine contract instead of copying parameter lists:
 
 ```bash
 pm contracts --action assurance --schema-only --json

package/docs/CONFIGURATION.md

@@ -156,6 +156,7 @@ Telemetry is opt-in via `pm config set telemetry-tracking on` (see [Common Setti
 | `PM_TELEMETRY_OTEL_DISABLED`         | boolean                                       | Disable only OTLP trace-span export; the event queue still flushes.                                                                             |
 | `PM_TELEMETRY_INLINE_FLUSH`          | boolean                                       | Flush the queue and OTLP spans inline instead of dispatching the detached worker. Mainly for tests; normal use relies on the background worker. |
 | `PM_TELEMETRY_SOURCE_CONTEXT`        | `user` \| `automation` \| `test` \| `dogfood` | Override the inferred source context recorded on each event. Any other value is ignored and the context is inferred.                            |
+| `PM_TELEMETRY_HTTP_TIMEOUT_MS`        | integer milliseconds                          | Bound each background event or OTLP request (default `20000`, clamped to `1000`–`25000` to stay below the worker lock TTL).                     |
 | `PM_TELEMETRY_INGEST_KEY`            | string                                        | Sent as the `x-pm-telemetry-key` header on queue flushes; never logged.                                                                         |
 | `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | URL                                           | OTLP/HTTP traces endpoint for command spans. Takes precedence over the base endpoint.                                                           |
 | `OTEL_EXPORTER_OTLP_ENDPOINT`        | URL                                           | Base OTLP endpoint; the traces endpoint is derived by appending `/v1/traces`.                                                                   |
@@ -164,6 +165,7 @@ Telemetry is opt-in via `pm config set telemetry-tracking on` (see [Common Setti
 Interaction rules:
 
 - `PM_TELEMETRY_DISABLED` / `PM_NO_TELEMETRY` short-circuit everything, including OTLP export, regardless of the other knobs.
+- `PM_TELEMETRY_HTTP_TIMEOUT_MS` applies only to the detached flush worker in normal use. It covers DNS, each IPv4/IPv6 connection attempt, TLS, and response completion. The upper bound preserves the 60-second worker-lock safety margin across the sequential event and OTLP phases; it does not make foreground commands wait for the network.
 - OTLP span export only happens when telemetry is enabled, `PM_TELEMETRY_OTEL_DISABLED` is off, and a traces endpoint is configured. By default spans are persisted to a bounded queue and exported by the detached, unref'd flush worker so commands exit promptly even when the traces endpoint is unreachable. `PM_TELEMETRY_INLINE_FLUSH=1` is the explicit test-oriented exception that performs the flush inline.
 - `pm health --check-telemetry --json` surfaces flush and OTLP export diagnostics (`pending_otel_spans`, `last_otel_attempt_at`, `last_otel_success_at`, `last_otel_failure_at`, `last_otel_failure_error`) and the active `env_overrides` (including `telemetry_inline_flush` and `telemetry_source_context`) so agents can self-diagnose a stalled endpoint.
 - An explicit `PM_AUTHOR` override adds a privacy-preserving agent-identity dimension to `command_start`/`command_finish` events so overridden invocations can be segmented in dashboards without leaking the raw author string. At `redacted`/`max` capture the events carry `author_context_hash` — the same installation-id-keyed one-way SHA-256 used for `pm_root_hash`/`cwd_hash`, so the same author hashes consistently within an installation but differently across installations. At `minimal` capture only a boolean `has_author_context` is emitted. The raw `PM_AUTHOR` value is never exported.