@unbrained/pm-cli 2026.8.11 → 2026.8.13

package/dist/core/extensions/registration-values.js

@@ -0,0 +1,210 @@
+/**
+ * @module core/extensions/registration-values
+ *
+ * Preserves executable extension registrations while producing deterministic,
+ * serializable public inventory snapshots and validates assurance providers.
+ */
+
+!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]="7316b9ef-38e1-5ee0-9107-da15ec7804d4")}catch(e){}}();
+import { KNOWN_EXTENSION_SERVICE_NAMES, } from "./extension-types.js";
+import { asRegistrationRecord, assertOptionalBooleanField, assertOptionalStringField, } from "./registration-validation.js";
+import { normalizeCommandName } from "./extension-runtime-helpers.js";
+/** Narrow a string to a renderer format accepted by the extension host. */
+export function isOutputRendererFormat(value) {
+    return value === "toon" || value === "json";
+}
+/** Narrow a string to a service name accepted by the extension host. */
+export function isExtensionServiceName(value) {
+    return KNOWN_EXTENSION_SERVICE_NAMES.includes(value);
+}
+/** Require a callable lifecycle hook before registry mutation. */
+export function assertHookHandler(hookName, hook) {
+    if (typeof hook !== "function") {
+        throw new TypeError(`api.hooks.${hookName} requires a function handler`);
+    }
+}
+const EXTENSION_REGISTRATION_TRACE_SYMBOL = Symbol("extension_registration_trace");
+/** Create a validation error carrying a hidden structured activation trace. */
+export function createRegistrationValidationError(message, trace) {
+    const error = new TypeError(message);
+    Object.defineProperty(error, EXTENSION_REGISTRATION_TRACE_SYMBOL, {
+        value: trace,
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
+    return error;
+}
+/** Recover a hidden structured activation trace from a validation error. */
+export function extractRegistrationValidationTrace(error) {
+    return error instanceof Error
+        ? error[EXTENSION_REGISTRATION_TRACE_SYMBOL]
+        : undefined;
+}
+/** Recursively project an arbitrary registration value into serializable data. */
+export function sanitizeRegistrationValue(value) {
+    if (value === null)
+        return null;
+    if (Array.isArray(value)) {
+        return value.map((entry) => sanitizeRegistrationValue(entry));
+    }
+    if (typeof value === "function")
+        return "[Function]";
+    if (typeof value === "bigint" || typeof value === "symbol") {
+        return value.toString();
+    }
+    if (typeof value === "object") {
+        const record = value;
+        const normalized = {};
+        for (const key of Object.keys(record).sort((left, right) => left.localeCompare(right))) {
+            normalized[key] = sanitizeRegistrationValue(record[key]);
+        }
+        return normalized;
+    }
+    return value;
+}
+/** Recursively clone registration containers while preserving function identities. */
+export function cloneRuntimeRegistrationValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => cloneRuntimeRegistrationValue(entry));
+    }
+    if (typeof value === "object" && value !== null) {
+        const record = value;
+        const cloned = {};
+        for (const key of Object.keys(record).sort((left, right) => left.localeCompare(right))) {
+            cloned[key] = cloneRuntimeRegistrationValue(record[key]);
+        }
+        return cloned;
+    }
+    return value;
+}
+/** Create a deterministic serializable registration snapshot with functions redacted. */
+export function normalizeRegistrationRecord(name, value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new TypeError(`${name} requires an object definition`);
+    }
+    return sanitizeRegistrationValue(value);
+}
+/** Clone a registration record without stripping executable function values. */
+export function normalizeRuntimeRegistrationRecord(name, value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new TypeError(`${name} requires an object definition`);
+    }
+    return cloneRuntimeRegistrationValue(value);
+}
+/** Implement the typed and untyped registration-array normalization overloads. */
+export function normalizeRegistrationRecordList(name, value) {
+    if (!Array.isArray(value)) {
+        throw new TypeError(`${name} requires an array of object definitions`);
+    }
+    return value.map((entry) => normalizeRegistrationRecord(name, entry));
+}
+/** Require a trimmed non-empty string at an extension authoring boundary. */
+export function assertNonEmptyRegistrationString(name, value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new TypeError(`${name} requires a non-empty string`);
+    }
+    return value.trim();
+}
+/** Require an executable handler at an extension authoring boundary. */
+export function assertRegistrationFunction(name, value) {
+    if (typeof value !== "function") {
+        throw new TypeError(`${name} requires a function handler`);
+    }
+}
+/** Canonicalize a user-facing registration name for stable routing. */
+export function normalizeRegistrationName(name) {
+    return name
+        .trim()
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((part) => part.length > 0)
+        .join(" ");
+}
+/** Build the canonical command path synthesized for an importer or exporter. */
+export function toRegistrationCommandPath(name, action) {
+    return normalizeCommandName(`${name} ${action}`);
+}
+/** Attach an executable definition as hidden immutable runtime-only state. */
+export function attachRuntimeDefinition(entry, runtimeDefinition) {
+    Object.defineProperty(entry, "runtime_definition", {
+        value: runtimeDefinition,
+        enumerable: false,
+        writable: false,
+        configurable: false,
+    });
+    return entry;
+}
+const ASSURANCE_PROVIDER_COST_CLASSES = new Set(["low", "medium", "high"]);
+const ASSURANCE_PROVIDER_VALUE_TYPES = new Set(["number", "string_set"]);
+const ASSURANCE_PROVIDER_PARAMETER_TYPES = new Set([
+    "string",
+    "number",
+    "boolean",
+]);
+function nonEmptyString(label, value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new TypeError(`${label} requires a non-empty string`);
+    }
+    return value.trim();
+}
+function validateAssuranceProviderKey(providerId, key, definition) {
+    const label = `registerAssuranceMeasurementProvider provider.keys.${key}`;
+    const record = asRegistrationRecord(label, definition);
+    if (!ASSURANCE_PROVIDER_VALUE_TYPES.has(String(record.value_type))) {
+        throw new TypeError(`${label}.value_type must be number or string_set`);
+    }
+    assertOptionalStringField(`${label}.description`, record.description);
+    if (record.parameters === undefined)
+        return;
+    const parameters = asRegistrationRecord(`${label}.parameters`, record.parameters);
+    for (const [parameter, rawDefinition] of Object.entries(parameters)) {
+        const parameterLabel = `${label}.parameters.${parameter}`;
+        nonEmptyString(`${parameterLabel}.name`, parameter);
+        const parameterDefinition = asRegistrationRecord(parameterLabel, rawDefinition);
+        if (!ASSURANCE_PROVIDER_PARAMETER_TYPES.has(String(parameterDefinition.type))) {
+            throw new TypeError(`${parameterLabel}.type must be string, number, or boolean`);
+        }
+        assertOptionalBooleanField(`${parameterLabel}.required`, parameterDefinition.required);
+        assertOptionalStringField(`${parameterLabel}.description`, parameterDefinition.description);
+    }
+    if (Object.keys(parameters).length > 50) {
+        throw new TypeError(`assurance provider ${providerId} key ${key} exceeds 50 parameters`);
+    }
+}
+/** Validate the closed provider schema before any activation registry mutation. */
+export function validateAssuranceMeasurementProviderDefinition(provider) {
+    const record = asRegistrationRecord("registerAssuranceMeasurementProvider provider", provider);
+    const id = nonEmptyString("registerAssuranceMeasurementProvider provider.id", record.id);
+    if (!/^[a-z0-9][a-z0-9-]*$/u.test(id)) {
+        throw new TypeError("registerAssuranceMeasurementProvider provider.id must be a stable lowercase id");
+    }
+    if (!ASSURANCE_PROVIDER_COST_CLASSES.has(String(record.cost_class))) {
+        throw new TypeError("registerAssuranceMeasurementProvider provider.cost_class must be low, medium, or high");
+    }
+    if (typeof record.network !== "boolean") {
+        throw new TypeError("registerAssuranceMeasurementProvider provider.network must be boolean");
+    }
+    const keys = asRegistrationRecord("registerAssuranceMeasurementProvider provider.keys", record.keys);
+    if (Object.keys(keys).length === 0) {
+        throw new TypeError("registerAssuranceMeasurementProvider provider.keys requires at least one key");
+    }
+    for (const [key, definition] of Object.entries(keys)) {
+        if (!/^[a-z0-9][a-z0-9-]*$/u.test(key)) {
+            throw new TypeError(`registerAssuranceMeasurementProvider provider key ${key} must be a stable lowercase id`);
+        }
+        validateAssuranceProviderKey(id, key, definition);
+    }
+    if (record.timeout_ms !== undefined &&
+        (typeof record.timeout_ms !== "number" ||
+            !Number.isInteger(record.timeout_ms) ||
+            record.timeout_ms < 1 ||
+            record.timeout_ms > 300_000)) {
+        throw new TypeError("registerAssuranceMeasurementProvider provider.timeout_ms must be an integer from 1 through 300000");
+    }
+    if (typeof record.resolve !== "function") {
+        throw new TypeError("registerAssuranceMeasurementProvider provider.resolve requires a function handler");
+    }
+}
+//# sourceMappingURL=registration-values.js.map
+//# debugId=7316b9ef-38e1-5ee0-9107-da15ec7804d4

package/dist/core/extensions/reserved-host-flags.js

@@ -5,7 +5,7 @@
  */
 /** Host-owned flags inherited by every subcommand, including extension commands. */
 
-!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]="47bfb287-bdd9-5984-9db4-cb996845d98c")}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]="d4493313-8f07-585b-84c7-4141e1d0cba4")}catch(e){}}();
 export const RESERVED_EXTENSION_HOST_FLAGS = Object.freeze([
     { flag: "--json" },
     { flag: "--lean" },
@@ -15,6 +15,7 @@ export const RESERVED_EXTENSION_HOST_FLAGS = Object.freeze([
     { flag: "--output-budget", value_name: "tokens" },
     { flag: "--output-format", value_name: "toon|json" },
     { flag: "--output-session", value_name: "state" },
+    { flag: "--output-row-contract" },
     { flag: "--quiet" },
     { flag: "--no-changed-fields" },
     { flag: "--full-changed-fields" },
@@ -32,4 +33,4 @@ export const RESERVED_EXTENSION_HOST_FLAG_NAMES = new Set(RESERVED_EXTENSION_HOS
     ...(definition.aliases ?? []),
 ]));
 //# sourceMappingURL=reserved-host-flags.js.map
-//# debugId=47bfb287-bdd9-5984-9db4-cb996845d98c
+//# debugId=d4493313-8f07-585b-84c7-4141e1d0cba4

package/dist/core/extensions/runtime-registrations.d.ts

@@ -3,7 +3,9 @@
  *
  * Implements extension runtime contracts and governance for Runtime Registrations.
  */
-import type { ExtensionRegistrationRegistry, RegisteredExtensionSchemaMigrationDefinition, RegisteredExtensionSearchProvider, RegisteredExtensionVectorStoreAdapter, SchemaFieldDefinition } from "./loader.js";
+import type { ExtensionRegistrationRegistry, RegisteredExtensionSchemaMigrationDefinition, RegisteredExtensionSearchProvider, RegisteredExtensionVectorStoreAdapter, RegisteredExtensionAssuranceMeasurementProvider, SchemaFieldDefinition } from "./loader.js";
+/** Resolve the last-activated assurance provider with the requested stable id. */
+export declare function resolveRegisteredAssuranceMeasurementProvider(registrations: ExtensionRegistrationRegistry | null, providerId: string | undefined): RegisteredExtensionAssuranceMeasurementProvider | null;
 /** Implements collect registered item fields for the public runtime surface of this module. */
 export declare function collectRegisteredItemFields(registrations: ExtensionRegistrationRegistry | null): SchemaFieldDefinition[];
 /** Implements resolve registered search provider for the public runtime surface of this module. */

package/dist/core/extensions/runtime-registrations.js

@@ -1,5 +1,5 @@
 
-!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]="4507a449-1c20-5684-9ed8-e72c9bc694c1")}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]="ab276268-7a98-5f97-b3f5-300dfd1b5ed5")}catch(e){}}();
 function normalizeRegistrationName(value) {
     if (typeof value !== "string") {
         return null;
@@ -7,6 +7,16 @@ function normalizeRegistrationName(value) {
     const normalized = value.trim().toLowerCase();
     return normalized.length > 0 ? normalized : null;
 }
+/** Resolve the last-activated assurance provider with the requested stable id. */
+export function resolveRegisteredAssuranceMeasurementProvider(registrations, providerId) {
+    const normalizedId = normalizeRegistrationName(providerId);
+    if (!registrations || !normalizedId)
+        return null;
+    return ([...(registrations.assurance_providers ?? [])]
+        .reverse()
+        .find((registration) => normalizeRegistrationName(registration.definition.id) ===
+        normalizedId) ?? null);
+}
 /** Implements collect registered item fields for the public runtime surface of this module. */
 export function collectRegisteredItemFields(registrations) {
     if (!registrations) {
@@ -55,4 +65,4 @@ export function getMigrationRuntimeDefinition(migration) {
     return migration.runtime_definition ?? migration.definition;
 }
 //# sourceMappingURL=runtime-registrations.js.map
-//# debugId=4507a449-1c20-5684-9ed8-e72c9bc694c1
+//# debugId=ab276268-7a98-5f97-b3f5-300dfd1b5ed5

package/dist/core/fs/fs-utils.d.ts

@@ -12,6 +12,8 @@ export declare function pathExists(targetPath: string): Promise<boolean>;
  * runtime fault instead of reaching the caller's own root validation.
  */
 export declare function isFileAbsentError(error: unknown): boolean;
+/** Report an exact missing-entry race while preserving ENOTDIR as structural corruption. */
+export declare function isFileMissingError(error: unknown): boolean;
 /** Implements read file if exists for the public runtime surface of this module. */
 export declare function readFileIfExists(targetPath: string): Promise<string | null>;
 /** Implements write file atomic for the public runtime surface of this module. */

package/dist/core/fs/fs-utils.js

@@ -4,7 +4,7 @@
  * Provides filesystem helpers for Fs Utils.
  */
 
-!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]="5aef9dc6-948a-5c82-9e3c-2f85fef46beb")}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]="23fc5fcb-5c80-57ab-8d91-8d15ee35ab53")}catch(e){}}();
 import * as fs from "node:fs/promises";
 import path from "node:path";
 import crypto from "node:crypto";
@@ -33,7 +33,11 @@ export async function pathExists(targetPath) {
  * runtime fault instead of reaching the caller's own root validation.
  */
 export function isFileAbsentError(error) {
-    return isErrno(error, "ENOENT") || isErrno(error, "ENOTDIR");
+    return isFileMissingError(error) || isErrno(error, "ENOTDIR");
+}
+/** Report an exact missing-entry race while preserving ENOTDIR as structural corruption. */
+export function isFileMissingError(error) {
+    return isErrno(error, "ENOENT");
 }
 /** Implements read file if exists for the public runtime surface of this module. */
 export async function readFileIfExists(targetPath) {
@@ -152,4 +156,4 @@ function isErrno(error, code) {
         error.code === code);
 }
 //# sourceMappingURL=fs-utils.js.map
-//# debugId=5aef9dc6-948a-5c82-9e3c-2f85fef46beb
+//# debugId=23fc5fcb-5c80-57ab-8d91-8d15ee35ab53

package/dist/core/history/drift-cache.js

@@ -4,7 +4,8 @@
  * Invalidates derived history-chain verification state after committed writes.
  */
 
-!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]="4db09d54-90c6-548b-baa8-c7ce419f70a2")}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]="5121b339-6594-58ec-b479-11cbf7dafd27")}catch(e){}}();
+import { isFileMissingError } from "../fs/fs-utils.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { writeStderr } from "../output/output.js";
@@ -49,7 +50,7 @@ export async function invalidateHistoryDriftCache(pmRoot) {
     }
     catch (error) {
         const errorCode = getFilesystemErrorCode(error);
-        if (errorCode === "ENOENT") {
+        if (isFileMissingError(error)) {
             return;
         }
         const code = errorCode === undefined
@@ -69,4 +70,4 @@ export async function invalidateHistoryDriftCacheForPath(historyPath) {
     await invalidateHistoryDriftCache(path.dirname(historyDirectory));
 }
 //# sourceMappingURL=drift-cache.js.map
-//# debugId=4db09d54-90c6-548b-baa8-c7ce419f70a2
+//# debugId=5121b339-6594-58ec-b479-11cbf7dafd27

package/dist/core/history/drift-scan.js

@@ -1,14 +1,14 @@
 
-!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]="90364096-b94c-591c-9024-e697fa9322a5")}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]="a6714da6-6e2b-5647-bfde-607a54d7e4cd")}catch(e){}}();
 import fs from "node:fs/promises";
 import { createHash } from "node:crypto";
 import path from "node:path";
 import { getHistoryPath } from "../store/paths.js";
-import { writeFileAtomic } from "../fs/fs-utils.js";
-import { hashDocument } from "./history.js";
-import { verifyHistoryChain } from "./replay.js";
+import { isFileMissingError, writeFileAtomic } from "../fs/fs-utils.js";
+import { CURRENT_HISTORY_ITEM_HASH_VERSION, hashDocumentForVersion, } from "./history.js";
+import { verifyHistoryChainWithVersion } from "./replay.js";
 import { getWorkspaceHistoryPath, WORKSPACE_HISTORY_ID, } from "./workspace-history.js";
-const DRIFT_CACHE_VERSION = 3;
+const DRIFT_CACHE_VERSION = 4;
 const DRIFT_CACHE_FILENAME = "history-drift-cache.json";
 function getDriftCachePath(pmRoot) {
     return path.join(pmRoot, "runtime", DRIFT_CACHE_FILENAME);
@@ -28,12 +28,6 @@ async function loadDriftCache(pmRoot) {
         return null;
     }
 }
-function isErrno(error, code) {
-    return (typeof error === "object" &&
-        error !== null &&
-        "code" in error &&
-        error.code === code);
-}
 async function scanWorkspaceHistory(pmRoot, previousEntries, nextEntries, verifyCacheHitByContent, accumulator) {
     const historyPath = getWorkspaceHistoryPath(pmRoot);
     let stat;
@@ -41,7 +35,7 @@ async function scanWorkspaceHistory(pmRoot, previousEntries, nextEntries, verify
         stat = await fs.stat(historyPath);
     }
     catch (error) {
-        if (isErrno(error, "ENOENT"))
+        if (isFileMissingError(error))
             return false;
         accumulator.unreadableStreams.push(WORKSPACE_HISTORY_ID);
         return false;
@@ -69,6 +63,7 @@ async function scanWorkspaceHistory(pmRoot, previousEntries, nextEntries, verify
         content_hash: resolved.verification.contentHash,
         latest_after_hash: resolved.verification.latestAfterHash,
         chain_ok: resolved.verification.chainOk,
+        item_hash_version: resolved.verification.itemHashVersion,
     };
     return resolved.cacheDirty;
 }
@@ -106,10 +101,12 @@ async function verifyHistoryStream(historyPath) {
         return null;
     }
     /* c8 ignore stop */
+    const verification = verifyHistoryChainWithVersion(entries);
     return {
         latestAfterHash,
-        chainOk: verifyHistoryChain(entries).ok,
+        chainOk: verification.ok,
         contentHash,
+        itemHashVersion: verification.item_hash_version ?? CURRENT_HISTORY_ITEM_HASH_VERSION,
     };
 }
 function cacheMetadataMatches(cached, stat) {
@@ -166,6 +163,7 @@ async function resolveStreamVerification(params) {
                 latestAfterHash: params.cached.latest_after_hash,
                 chainOk: params.cached.chain_ok,
                 contentHash: currentContentHash,
+                itemHashVersion: params.cached.item_hash_version ?? CURRENT_HISTORY_ITEM_HASH_VERSION,
             },
             cacheDirty: false,
         };
@@ -206,7 +204,7 @@ export async function scanHistoryDrift(pmRoot, items, options = {}) {
             stat = await fs.stat(historyPath);
         }
         catch (error) {
-            if (isErrno(error, "ENOENT")) {
+            if (isFileMissingError(error)) {
                 accumulator.missingStreams.push(item.id);
             }
             else {
@@ -237,12 +235,13 @@ export async function scanHistoryDrift(pmRoot, items, options = {}) {
             content_hash: resolved.verification.contentHash,
             latest_after_hash: resolved.verification.latestAfterHash,
             chain_ok: resolved.verification.chainOk,
+            item_hash_version: resolved.verification.itemHashVersion,
         };
         const { body, ...itemMetadata } = item;
-        const currentHash = hashDocument({
+        const currentHash = hashDocumentForVersion({
             metadata: itemMetadata,
             body,
-        });
+        }, resolved.verification.itemHashVersion);
         if (currentHash !== resolved.verification.latestAfterHash) {
             accumulator.hashMismatches.push(item.id);
         }
@@ -271,4 +270,4 @@ export async function scanHistoryDrift(pmRoot, items, options = {}) {
     return { ...accumulator, driftedItems };
 }
 //# sourceMappingURL=drift-scan.js.map
-//# debugId=90364096-b94c-591c-9024-e697fa9322a5
+//# debugId=a6714da6-6e2b-5647-bfde-607a54d7e4cd

package/dist/core/history/history.d.ts

@@ -1,9 +1,17 @@
 import { type AuthorSource } from "../shared/author.js";
 import type { HistoryEntry, ItemDocument } from "../../types/index.js";
+/** Hash epoch that preserves linked-test insertion order in immutable history. */
+export declare const CURRENT_HISTORY_ITEM_HASH_VERSION: 2;
+/** Hash epochs understood by this runtime. */
+export declare const SUPPORTED_HISTORY_ITEM_HASH_VERSIONS: readonly [1, 2];
+/** Restricts item hash versions accepted by history replay. */
+export type HistoryItemHashVersion = (typeof SUPPORTED_HISTORY_ITEM_HASH_VERSIONS)[number];
 declare function decodeJsonPointer(path: string): string[];
 declare function isDefinedPointerPath(document: unknown, path: string): boolean;
 /** Implements hash document for the public runtime surface of this module. */
 export declare function hashDocument(document: ItemDocument): string;
+/** Hash an item with an explicit canonicalization epoch for replay compatibility. */
+export declare function hashDocumentForVersion(document: ItemDocument, version: HistoryItemHashVersion): string;
 /** Implements hash empty document for the public runtime surface of this module. */
 export declare function hashEmptyDocument(): string;
 /** Implements create history entry for the public runtime surface of this module. */

package/dist/core/history/history.js

@@ -4,7 +4,7 @@
  * Implements append-only history and replay behavior for 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]="ce2dace3-7c86-5edf-8bda-083a0b3e7f2b")}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]="2fc7f675-3500-5abb-8d5c-9ca9caa803b6")}catch(e){}}();
 import jsonPatch from "fast-json-patch";
 import { ITEM_METADATA_KEY_ORDER } from "../shared/constants.js";
 import { runActiveServiceOverride } from "../extensions/index.js";
@@ -20,6 +20,42 @@ const EMPTY_LEGACY_HASH_DOCUMENT = {
     front_matter: {},
     body: "",
 };
+/** Hash epoch that preserves linked-test insertion order in immutable history. */
+export const CURRENT_HISTORY_ITEM_HASH_VERSION = 2;
+/** Hash epochs understood by this runtime. */
+export const SUPPORTED_HISTORY_ITEM_HASH_VERSIONS = [1, 2];
+function compareOptionalStrings(left, right) {
+    return (left ?? "").localeCompare(right ?? "");
+}
+function compareOptionalNumbers(left, right) {
+    return (left ?? 0) - (right ?? 0);
+}
+function compareJsonValues(left, right, fallback) {
+    // Preserve the original v1 comparator byte-for-byte: replacing JSON.stringify
+    // with stableStringify would invalidate immutable hashes from legacy streams.
+    return JSON.stringify(left ?? fallback).localeCompare(JSON.stringify(right ?? fallback));
+}
+function compareLegacyLinkedTests(left, right) {
+    const comparisons = [
+        left.scope.localeCompare(right.scope),
+        compareOptionalStrings(left.path, right.path),
+        compareOptionalStrings(left.command, right.command),
+        compareOptionalNumbers(left.timeout_seconds, right.timeout_seconds),
+        compareOptionalStrings(left.pm_context_mode, right.pm_context_mode),
+        Number(Boolean(left.shared_host_safe)) - Number(Boolean(right.shared_host_safe)),
+        compareJsonValues(left.env_clear, right.env_clear, []),
+        compareJsonValues(left.env_set, right.env_set, {}),
+        compareJsonValues(left.assert_stdout_contains, right.assert_stdout_contains, []),
+        compareJsonValues(left.assert_stdout_regex, right.assert_stdout_regex, []),
+        compareJsonValues(left.assert_stderr_contains, right.assert_stderr_contains, []),
+        compareJsonValues(left.assert_stderr_regex, right.assert_stderr_regex, []),
+        compareOptionalNumbers(left.assert_stdout_min_lines, right.assert_stdout_min_lines),
+        compareJsonValues(left.assert_json_field_equals, right.assert_json_field_equals, {}),
+        compareJsonValues(left.assert_json_field_gte, right.assert_json_field_gte, {}),
+        compareOptionalStrings(left.note, right.note),
+    ];
+    return comparisons.find((comparison) => comparison !== 0) ?? 0;
+}
 function decodeJsonPointer(path) {
     if (!path || path === "/") {
         return [];
@@ -81,7 +117,7 @@ function normalizeHistoryPatchOps(beforeDocument, patch) {
     }
     return normalized;
 }
-function canonicalHashDocument(document) {
+function canonicalHashDocument(document, version) {
     const hasMetadata = document.metadata && Object.keys(document.metadata).length > 0;
     if (!hasMetadata) {
         return {
@@ -90,7 +126,13 @@ function canonicalHashDocument(document) {
         };
     }
     const canonical = canonicalDocument(document);
-    const orderedMetadata = orderObject(toItemRecord(canonical.metadata), ITEM_METADATA_KEY_ORDER);
+    const metadata = version === 1 && canonical.metadata.tests
+        ? {
+            ...canonical.metadata,
+            tests: [...canonical.metadata.tests].sort(compareLegacyLinkedTests),
+        }
+        : canonical.metadata;
+    const orderedMetadata = orderObject(toItemRecord(metadata), ITEM_METADATA_KEY_ORDER);
     return {
         front_matter: orderedMetadata,
         body: canonical.body,
@@ -113,7 +155,14 @@ function canonicalPatchDocument(document) {
 }
 /** Implements hash document for the public runtime surface of this module. */
 export function hashDocument(document) {
-    return sha256Hex(stableStringify(canonicalHashDocument(document)));
+    return hashDocumentForVersion(document, CURRENT_HISTORY_ITEM_HASH_VERSION);
+}
+/** Hash an item with an explicit canonicalization epoch for replay compatibility. */
+export function hashDocumentForVersion(document, version) {
+    if (!SUPPORTED_HISTORY_ITEM_HASH_VERSIONS.some((supportedVersion) => supportedVersion === version)) {
+        throw new TypeError(`unsupported_item_hash_version:${String(version)}`);
+    }
+    return sha256Hex(stableStringify(canonicalHashDocument(document, version)));
 }
 /** Implements hash empty document for the public runtime surface of this module. */
 export function hashEmptyDocument() {
@@ -121,8 +170,8 @@ export function hashEmptyDocument() {
 }
 /** Implements create history entry for the public runtime surface of this module. */
 export function createHistoryEntry(params) {
-    const beforeHashCanonical = canonicalHashDocument(params.before);
-    const afterHashCanonical = canonicalHashDocument(params.after);
+    const beforeHashCanonical = canonicalHashDocument(params.before, CURRENT_HISTORY_ITEM_HASH_VERSION);
+    const afterHashCanonical = canonicalHashDocument(params.after, CURRENT_HISTORY_ITEM_HASH_VERSION);
     const beforePatchCanonical = canonicalPatchDocument(params.before);
     const afterPatchCanonical = canonicalPatchDocument(params.after);
     const rawPatch = jsonPatch.compare(beforePatchCanonical, afterPatchCanonical);
@@ -159,6 +208,7 @@ export function createHistoryEntry(params) {
         patch,
         before_hash: sha256Hex(stableStringify(beforeHashCanonical)),
         after_hash: sha256Hex(stableStringify(afterHashCanonical)),
+        item_hash_version: CURRENT_HISTORY_ITEM_HASH_VERSION,
         message: params.message === undefined ? undefined : params.message,
         ...(context === undefined ? {} : { context }),
     };
@@ -242,4 +292,4 @@ export const _testOnly = {
     isDefinedPointerPath,
 };
 //# sourceMappingURL=history.js.map
-//# debugId=ce2dace3-7c86-5edf-8bda-083a0b3e7f2b
+//# debugId=2fc7f675-3500-5abb-8d5c-9ca9caa803b6

package/dist/core/history/replay.d.ts

@@ -1,4 +1,5 @@
 import { canonicalDocument } from "../item/item-format.js";
+import { type HistoryItemHashVersion } from "./history.js";
 import type { HistoryEntry, HistoryPatchOp, ItemDocument } from "../../types/index.js";
 /**
  * Shared history replay/patch mechanics single-sourced for the history, restore,
@@ -19,7 +20,7 @@ export declare const EMPTY_REPLAY_DOCUMENT: ReplayDocument;
 /** Implements clone empty replay document for the public runtime surface of this module. */
 export declare function cloneEmptyReplayDocument(): ReplayDocument;
 /** Implements replay hash for the public runtime surface of this module. */
-export declare function replayHash(document: ReplayDocument): string;
+export declare function replayHash(document: ReplayDocument, version?: HistoryItemHashVersion): string;
 /** Implements replay to item document for the public runtime surface of this module. */
 export declare function replayToItemDocument(document: ReplayDocument): ItemDocument;
 /** Converts a materialized replay document into a canonical item document. Use this when callers have already rejected the empty/deleted replay state and need restored metadata validated through the normal item-metadata rules. */
@@ -41,6 +42,13 @@ export type ReplayApplyResult = {
 /** Strictly apply a history patch (front_matter->metadata normalized) to a replay document. Returns a result envelope rather than throwing so each caller can format its own error contract. */
 export declare function tryApplyReplayPatch(current: ReplayDocument, patch: HistoryPatchOp[]): ReplayApplyResult;
 /** Deterministically verify a history chain: each entry's before_hash must equal the prior replayed after_hash, the patch must strictly apply, and the recorded after_hash must equal the replayed result. */
+/** Verify a chain and report the explicit or auto-detected item hash epoch. */
+export declare function verifyHistoryChainWithVersion(entries: HistoryEntry[]): {
+    ok: boolean;
+    errors: string[];
+    item_hash_version?: HistoryItemHashVersion;
+};
+/** Deterministically verify a history chain while preserving the legacy result shape. */
 export declare function verifyHistoryChain(entries: HistoryEntry[]): {
     ok: boolean;
     errors: string[];