@unbrained/pm-cli 2026.9.7 → 2026.9.8

package/dist/sdk/improvement-ledger-validation.js

@@ -1,63 +1,2 @@
-/**
- * @module sdk/improvement-ledger-validation
- *
- * Validates the persisted improvement-ledger envelope and observations at the
- * storage boundary so malformed workspace state never reaches analytics.
- */
-
-!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]="939d5f93-d287-5c1c-bc78-d013f76735f2")}catch(e){}}();
-import { EXIT_CODE } from "../core/shared/constants.js";
-import { PmCliError } from "../core/shared/errors.js";
-const IMPROVEMENT_LEDGER_FORMAT_VERSION = 1;
-function isValidLedgerObservation(observation) {
-    if (typeof observation !== "object" || observation === null)
-        return false;
-    const candidate = observation;
-    const hasRequiredFields = typeof candidate.id === "string" &&
-        typeof candidate.metric === "string" &&
-        typeof candidate.value === "number" &&
-        Number.isFinite(candidate.value) &&
-        ["higher", "lower", "target"].includes(String(candidate.direction)) &&
-        typeof candidate.observed_at === "string" &&
-        typeof candidate.revision === "string" &&
-        ["caller", "git", "unversioned"].includes(String(candidate.revision_source)) &&
-        typeof candidate.author === "string";
-    if (!hasRequiredFields)
-        return false;
-    return (candidate.direction !== "target" ||
-        (typeof candidate.threshold === "number" &&
-            Number.isFinite(candidate.threshold)));
-}
-/** Parse and validate a serialized improvement-ledger singleton. */
-export function parseImprovementLedgerDocument(raw) {
-    if (raw === null) {
-        return {
-            format_version: IMPROVEMENT_LEDGER_FORMAT_VERSION,
-            observations: [],
-        };
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        throw new PmCliError("Improvement ledger contains invalid JSON.", EXIT_CODE.GENERIC_FAILURE, { code: "invalid_improvement_ledger" });
-    }
-    if (typeof parsed !== "object" ||
-        parsed === null ||
-        Array.isArray(parsed) ||
-        parsed.format_version !==
-            IMPROVEMENT_LEDGER_FORMAT_VERSION ||
-        !Array.isArray(parsed.observations)) {
-        throw new PmCliError("Improvement ledger has an unsupported shape or format version.", EXIT_CODE.GENERIC_FAILURE, { code: "invalid_improvement_ledger" });
-    }
-    const observations = parsed.observations;
-    for (const observation of observations) {
-        if (!isValidLedgerObservation(observation)) {
-            throw new PmCliError("Improvement ledger contains an invalid observation.", EXIT_CODE.GENERIC_FAILURE, { code: "invalid_improvement_ledger" });
-        }
-    }
-    return parsed;
-}
+!(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]="39d2b5aa-c6f3-57ac-adb4-e775bc838828")}catch(e2){}})();import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";const IMPROVEMENT_LEDGER_FORMAT_VERSION=1;function isValidLedgerObservation(observation){if(typeof observation!=="object"||observation===null)return false;const candidate=observation;const hasRequiredFields=typeof candidate.id==="string"&&typeof candidate.metric==="string"&&typeof candidate.value==="number"&&Number.isFinite(candidate.value)&&["higher","lower","target"].includes(String(candidate.direction))&&typeof candidate.observed_at==="string"&&typeof candidate.revision==="string"&&["caller","git","unversioned"].includes(String(candidate.revision_source))&&typeof candidate.author==="string";if(!hasRequiredFields)return false;return candidate.direction!=="target"||typeof candidate.threshold==="number"&&Number.isFinite(candidate.threshold)}function parseImprovementLedgerDocument(raw){if(raw===null){return{format_version:IMPROVEMENT_LEDGER_FORMAT_VERSION,observations:[]}}let parsed;try{parsed=JSON.parse(raw)}catch{throw new PmCliError("Improvement ledger contains invalid JSON.",EXIT_CODE.GENERIC_FAILURE,{code:"invalid_improvement_ledger"})}if(typeof parsed!=="object"||parsed===null||Array.isArray(parsed)||parsed.format_version!==IMPROVEMENT_LEDGER_FORMAT_VERSION||!Array.isArray(parsed.observations)){throw new PmCliError("Improvement ledger has an unsupported shape or format version.",EXIT_CODE.GENERIC_FAILURE,{code:"invalid_improvement_ledger"})}const observations=parsed.observations;for(const observation of observations){if(!isValidLedgerObservation(observation)){throw new PmCliError("Improvement ledger contains an invalid observation.",EXIT_CODE.GENERIC_FAILURE,{code:"invalid_improvement_ledger"})}}return parsed}export{parseImprovementLedgerDocument};
 //# sourceMappingURL=improvement-ledger-validation.js.map
-//# debugId=939d5f93-d287-5c1c-bc78-d013f76735f2

package/dist/sdk/improvement-ledger.js

@@ -1,258 +1,3 @@
-/**
- * @module sdk/improvement-ledger
- *
- * Persists append-only quantitative observations in an audited workspace
- * singleton and exposes bounded trend reads for self-improvement loops.
- */
-
-!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]="c2e1edc9-c454-5cfa-85c8-e9fb0a76a296")}catch(e){}}();
-import { assertInitializedTracker } from "./environment/tracker-preflight.js";
-import { createHash } from "node:crypto";
-import { execFile } from "node:child_process";
-import path from "node:path";
-import { promisify } from "node:util";
-import { readFileIfExists } from "../core/fs/fs-utils.js";
-import { mutateWorkspaceJsonWithHistory } from "../core/history/workspace-history.js";
-import { EXIT_CODE } from "../core/shared/constants.js";
-import { resolveAuthor } from "../core/shared/author.js";
-import { PmCliError } from "../core/shared/errors.js";
-import { stableStringify } from "../core/shared/serialization.js";
-import { nowIso } from "../core/shared/time.js";
-import { resolvePmRoot, resolveWorkspaceRoot, } from "../core/store/paths.js";
-import { readSettings } from "../core/store/settings.js";
-import { parseImprovementLedgerDocument as parseLedger } from "./improvement-ledger-validation.js";
-const execFileAsync = promisify(execFile);
-const DEFAULT_OBSERVATION_LIMIT = 50;
-const MAX_OBSERVATION_LIMIT = 1_000;
-const METRIC_NAME_PATTERN = /^[a-z0-9](?:[a-z0-9._/-]{0,126}[a-z0-9])?$/u;
-function normalizeMetricName(value) {
-    const metric = value.trim().toLowerCase();
-    if (!METRIC_NAME_PATTERN.test(metric)) {
-        throw new PmCliError(`Invalid metric name "${value}"; use 1-128 lowercase letters, digits, dots, slashes, underscores, or hyphens.`, EXIT_CODE.USAGE, { code: "invalid_improvement_metric" });
-    }
-    return metric;
-}
-function normalizeDirection(value) {
-    const direction = value ?? "lower";
-    if (!["higher", "lower", "target"].includes(direction)) {
-        throw new PmCliError("Improvement direction must be higher, lower, or target.", EXIT_CODE.USAGE, { code: "invalid_improvement_observation" });
-    }
-    return direction;
-}
-function normalizeOptionalText(value, field) {
-    const normalized = value?.trim();
-    if (!normalized)
-        return undefined;
-    if (normalized.length > 256) {
-        throw new PmCliError(`${field} must not exceed 256 characters.`, EXIT_CODE.USAGE, { code: "invalid_improvement_observation" });
-    }
-    return normalized;
-}
-function parseObservationLimit(value) {
-    const limit = value ?? DEFAULT_OBSERVATION_LIMIT;
-    if (!Number.isSafeInteger(limit) ||
-        limit < 0 ||
-        limit > MAX_OBSERVATION_LIMIT) {
-        throw new PmCliError(`Improvement observation limit must be an integer from 0 to ${MAX_OBSERVATION_LIMIT}.`, EXIT_CODE.USAGE, { code: "invalid_improvement_observation_limit" });
-    }
-    return limit;
-}
-function parseIsoTimestamp(value, field) {
-    const milliseconds = Date.parse(value);
-    if (!Number.isFinite(milliseconds)) {
-        throw new PmCliError(`${field} must be an ISO timestamp.`, EXIT_CODE.USAGE, {
-            code: "invalid_improvement_observation_timestamp",
-        });
-    }
-    return new Date(milliseconds).toISOString();
-}
-async function buildImprovementObservation(pmRoot, settings, options) {
-    if (!Number.isFinite(options.value)) {
-        throw new PmCliError("Improvement observation value must be finite.", EXIT_CODE.USAGE, { code: "invalid_improvement_observation" });
-    }
-    const metric = normalizeMetricName(options.metric);
-    const direction = normalizeDirection(options.direction);
-    if ((options.threshold !== undefined && !Number.isFinite(options.threshold)) ||
-        (direction === "target" && options.threshold === undefined)) {
-        throw new PmCliError("Target-directed observations require a finite threshold.", EXIT_CODE.USAGE, { code: "invalid_improvement_observation" });
-    }
-    const revision = await resolveObservationRevision(pmRoot, options.revision);
-    const source = normalizeOptionalText(options.source, "source");
-    const itemId = normalizeOptionalText(options.itemId, "itemId");
-    const unit = normalizeOptionalText(options.unit, "unit");
-    const idempotencyKey = normalizeOptionalText(options.idempotencyKey, "idempotencyKey") ??
-        (revision.revision_source === "unversioned"
-            ? undefined
-            : [
-                revision.revision,
-                metric,
-                source ?? "manual",
-                itemId ?? "workspace",
-            ].join(":"));
-    const observationWithoutId = {
-        metric,
-        value: options.value,
-        direction,
-        ...(unit === undefined ? {} : { unit }),
-        ...(options.threshold === undefined
-            ? {}
-            : { threshold: options.threshold }),
-        observed_at: parseIsoTimestamp(options.observedAt ?? nowIso(), "observedAt"),
-        ...revision,
-        author: resolveAuthor(options.author, settings.author_default),
-        ...(itemId === undefined ? {} : { item_id: itemId }),
-        ...(source === undefined ? {} : { source }),
-        ...(idempotencyKey === undefined
-            ? {}
-            : { idempotency_key: idempotencyKey }),
-    };
-    return {
-        id: createHash("sha256")
-            .update(stableStringify(observationWithoutId))
-            .digest("hex")
-            .slice(0, 24),
-        ...observationWithoutId,
-    };
-}
-function ensureObservationCanAppend(ledger, observation) {
-    const existing = observation.idempotency_key
-        ? ledger.observations.find((row) => row.idempotency_key === observation.idempotency_key)
-        : ledger.observations.find((row) => row.id === observation.id);
-    if (existing) {
-        if (existing.metric !== observation.metric ||
-            existing.value !== observation.value ||
-            existing.direction !== observation.direction ||
-            existing.threshold !== observation.threshold ||
-            existing.unit !== observation.unit) {
-            throw new PmCliError(`Improvement observation retry key already records a different value for ${observation.metric}.`, EXIT_CODE.CONFLICT, { code: "improvement_observation_conflict" });
-        }
-        return existing;
-    }
-    const priorMetric = ledger.observations.find((row) => row.metric === observation.metric);
-    if (priorMetric &&
-        (priorMetric.direction !== observation.direction ||
-            priorMetric.unit !== observation.unit ||
-            (observation.direction === "target" &&
-                priorMetric.threshold !== observation.threshold))) {
-        throw new PmCliError(`Metric ${observation.metric} is already declared with direction ${priorMetric.direction} and unit ${priorMetric.unit ?? "<none>"}.`, EXIT_CODE.CONFLICT, { code: "improvement_metric_contract_conflict" });
-    }
-    return undefined;
-}
-async function resolveObservationRevision(pmRoot, explicit) {
-    const callerRevision = normalizeOptionalText(explicit, "revision");
-    if (callerRevision) {
-        return { revision: callerRevision, revision_source: "caller" };
-    }
-    try {
-        const result = await execFileAsync("git", ["rev-parse", "--verify", "HEAD^{commit}"], {
-            cwd: resolveWorkspaceRoot(pmRoot),
-            encoding: "utf8",
-            timeout: 5_000,
-        });
-        const revision = result.stdout.trim();
-        return { revision, revision_source: "git" };
-    }
-    catch {
-        // Git is optional for root-layout and embedded SDK workspaces.
-    }
-    return { revision: "unversioned", revision_source: "unversioned" };
-}
-function trendForMetric(observations) {
-    const baseline = observations[0];
-    const latest = observations[observations.length - 1];
-    const delta = latest.value - baseline.value;
-    const improved = latest.direction === "higher"
-        ? delta > 0
-        : latest.direction === "lower"
-            ? delta < 0
-            : Math.abs(latest.value - latest.threshold) <
-                Math.abs(baseline.value - baseline.threshold);
-    return {
-        metric: latest.metric,
-        direction: latest.direction,
-        baseline,
-        latest,
-        delta,
-        improved,
-        sample_count: observations.length,
-    };
-}
-/** Record one audited observation, returning an idempotent receipt on retry. */
-export async function recordImprovementObservation(options, global = {}) {
-    const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    await assertInitializedTracker(pmRoot);
-    const settings = await readSettings(pmRoot);
-    const observation = await buildImprovementObservation(pmRoot, settings, options);
-    const filePath = path.join(pmRoot, "improvement-ledger.json");
-    const mutation = await mutateWorkspaceJsonWithHistory({
-        pmRoot,
-        filePath,
-        op: "improvement_observe",
-        author: observation.author,
-        lockTtlSeconds: settings.locks.ttl_seconds,
-        lockWaitMs: settings.locks.wait_ms,
-        message: options.message ??
-            `Record ${observation.metric}=${String(options.value)} improvement observation`,
-        mutate: (beforeRaw) => {
-            const ledger = parseLedger(beforeRaw);
-            const existing = ensureObservationCanAppend(ledger, observation);
-            if (existing) {
-                return { raw: beforeRaw, result: existing };
-            }
-            ledger.observations.push(observation);
-            ledger.observations.sort((left, right) => left.observed_at.localeCompare(right.observed_at) ||
-                left.metric.localeCompare(right.metric) ||
-                left.id.localeCompare(right.id));
-            return {
-                raw: `${stableStringify(ledger)}\n`,
-                result: observation,
-            };
-        },
-    });
-    return {
-        changed: mutation.changed,
-        observation: mutation.result,
-        ledger_path: "improvement-ledger.json",
-    };
-}
-/** Read a bounded newest-first observation page and derive complete trends. */
-export async function readImprovementLedger(options = {}) {
-    const pmRoot = resolvePmRoot(options.cwd ?? process.cwd(), options.pmRoot);
-    await assertInitializedTracker(pmRoot);
-    const metric = options.metric === undefined
-        ? undefined
-        : normalizeMetricName(options.metric);
-    const since = options.since === undefined
-        ? undefined
-        : parseIsoTimestamp(options.since, "since");
-    const limit = parseObservationLimit(options.limit);
-    const ledger = parseLedger(await readFileIfExists(path.join(pmRoot, "improvement-ledger.json")));
-    const matching = ledger.observations.filter((row) => (metric === undefined || row.metric === metric) &&
-        (options.itemId === undefined || row.item_id === options.itemId) &&
-        (since === undefined || row.observed_at >= since));
-    const byMetric = new Map();
-    for (const observation of matching) {
-        const rows = byMetric.get(observation.metric) ?? [];
-        rows.push(observation);
-        byMetric.set(observation.metric, rows);
-    }
-    return {
-        observations: [...matching].reverse().slice(0, limit),
-        total: matching.length,
-        truncated: matching.length > limit,
-        trends: [...byMetric]
-            .map(([, observations]) => trendForMetric(observations))
-            .sort((left, right) => left.metric.localeCompare(right.metric)),
-        source: "audited_workspace_singleton",
-    };
-}
-/** Pure helpers exposed for storage and trend contract tests. */
-export const _testOnlyImprovementLedger = {
-    normalizeMetricName,
-    normalizeDirection,
-    parseLedger,
-    parseObservationLimit,
-    trendForMetric,
-};
+!(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]="c800f76b-2867-51f5-80d6-fb7b1c61f9e4")}catch(e2){}})();import{assertInitializedTracker}from"./environment/tracker-preflight.js";import{createHash}from"node:crypto";import{execFile}from"node:child_process";import path from"node:path";import{promisify}from"node:util";import{readFileIfExists}from"../core/fs/fs-utils.js";import{mutateWorkspaceJsonWithHistory}from"../core/history/workspace-history.js";import{EXIT_CODE}from"../core/shared/constants.js";import{resolveAuthor}from"../core/shared/author.js";import{PmCliError}from"../core/shared/errors.js";import{stableStringify}from"../core/shared/serialization.js";import{nowIso}from"../core/shared/time.js";import{resolvePmRoot,resolveWorkspaceRoot}from"../core/store/paths.js";import{readSettings}from"../core/store/settings.js";import{parseImprovementLedgerDocument as parseLedger}from"./improvement-ledger-validation.js";const execFileAsync=promisify(execFile);const DEFAULT_OBSERVATION_LIMIT=50;const MAX_OBSERVATION_LIMIT=1e3;const METRIC_NAME_PATTERN=/^[a-z0-9](?:[a-z0-9._/-]{0,126}[a-z0-9])?$/u;function normalizeMetricName(value){const metric=value.trim().toLowerCase();if(!METRIC_NAME_PATTERN.test(metric)){throw new PmCliError(`Invalid metric name "${value}"; use 1-128 lowercase letters, digits, dots, slashes, underscores, or hyphens.`,EXIT_CODE.USAGE,{code:"invalid_improvement_metric"})}return metric}function normalizeDirection(value){const direction=value??"lower";if(!["higher","lower","target"].includes(direction)){throw new PmCliError("Improvement direction must be higher, lower, or target.",EXIT_CODE.USAGE,{code:"invalid_improvement_observation"})}return direction}function normalizeOptionalText(value,field){const normalized=value?.trim();if(!normalized)return void 0;if(normalized.length>256){throw new PmCliError(`${field} must not exceed 256 characters.`,EXIT_CODE.USAGE,{code:"invalid_improvement_observation"})}return normalized}function parseObservationLimit(value){const limit=value??DEFAULT_OBSERVATION_LIMIT;if(!Number.isSafeInteger(limit)||limit<0||limit>MAX_OBSERVATION_LIMIT){throw new PmCliError(`Improvement observation limit must be an integer from 0 to ${MAX_OBSERVATION_LIMIT}.`,EXIT_CODE.USAGE,{code:"invalid_improvement_observation_limit"})}return limit}function parseIsoTimestamp(value,field){const milliseconds=Date.parse(value);if(!Number.isFinite(milliseconds)){throw new PmCliError(`${field} must be an ISO timestamp.`,EXIT_CODE.USAGE,{code:"invalid_improvement_observation_timestamp"})}return new Date(milliseconds).toISOString()}async function buildImprovementObservation(pmRoot,settings,options){if(!Number.isFinite(options.value)){throw new PmCliError("Improvement observation value must be finite.",EXIT_CODE.USAGE,{code:"invalid_improvement_observation"})}const metric=normalizeMetricName(options.metric);const direction=normalizeDirection(options.direction);if(options.threshold!==void 0&&!Number.isFinite(options.threshold)||direction==="target"&&options.threshold===void 0){throw new PmCliError("Target-directed observations require a finite threshold.",EXIT_CODE.USAGE,{code:"invalid_improvement_observation"})}const revision=await resolveObservationRevision(pmRoot,options.revision);const source=normalizeOptionalText(options.source,"source");const itemId=normalizeOptionalText(options.itemId,"itemId");const unit=normalizeOptionalText(options.unit,"unit");const idempotencyKey=normalizeOptionalText(options.idempotencyKey,"idempotencyKey")??(revision.revision_source==="unversioned"?void 0:[revision.revision,metric,source??"manual",itemId??"workspace"].join(":"));const observationWithoutId={metric,value:options.value,direction,...unit===void 0?{}:{unit},...options.threshold===void 0?{}:{threshold:options.threshold},observed_at:parseIsoTimestamp(options.observedAt??nowIso(),"observedAt"),...revision,author:resolveAuthor(options.author,settings.author_default),...itemId===void 0?{}:{item_id:itemId},...source===void 0?{}:{source},...idempotencyKey===void 0?{}:{idempotency_key:idempotencyKey}};return{id:createHash("sha256").update(stableStringify(observationWithoutId)).digest("hex").slice(0,24),...observationWithoutId}}function ensureObservationCanAppend(ledger,observation){const existing=observation.idempotency_key?ledger.observations.find(row=>row.idempotency_key===observation.idempotency_key):ledger.observations.find(row=>row.id===observation.id);if(existing){if(existing.metric!==observation.metric||existing.value!==observation.value||existing.direction!==observation.direction||existing.threshold!==observation.threshold||existing.unit!==observation.unit){throw new PmCliError(`Improvement observation retry key already records a different value for ${observation.metric}.`,EXIT_CODE.CONFLICT,{code:"improvement_observation_conflict"})}return existing}const priorMetric=ledger.observations.find(row=>row.metric===observation.metric);if(priorMetric&&(priorMetric.direction!==observation.direction||priorMetric.unit!==observation.unit||observation.direction==="target"&&priorMetric.threshold!==observation.threshold)){throw new PmCliError(`Metric ${observation.metric} is already declared with direction ${priorMetric.direction} and unit ${priorMetric.unit??"<none>"}.`,EXIT_CODE.CONFLICT,{code:"improvement_metric_contract_conflict"})}return void 0}async function resolveObservationRevision(pmRoot,explicit){const callerRevision=normalizeOptionalText(explicit,"revision");if(callerRevision){return{revision:callerRevision,revision_source:"caller"}}try{const result=await execFileAsync("git",["rev-parse","--verify","HEAD^{commit}"],{cwd:resolveWorkspaceRoot(pmRoot),encoding:"utf8",timeout:5e3});const revision=result.stdout.trim();return{revision,revision_source:"git"}}catch{}return{revision:"unversioned",revision_source:"unversioned"}}function trendForMetric(observations){const baseline=observations[0];const latest=observations[observations.length-1];const delta=latest.value-baseline.value;const improved=latest.direction==="higher"?delta>0:latest.direction==="lower"?delta<0:Math.abs(latest.value-latest.threshold)<Math.abs(baseline.value-baseline.threshold);return{metric:latest.metric,direction:latest.direction,baseline,latest,delta,improved,sample_count:observations.length}}async function recordImprovementObservation(options,global2={}){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot);const observation=await buildImprovementObservation(pmRoot,settings,options);const filePath=path.join(pmRoot,"improvement-ledger.json");const mutation=await mutateWorkspaceJsonWithHistory({pmRoot,filePath,op:"improvement_observe",author:observation.author,lockTtlSeconds:settings.locks.ttl_seconds,lockWaitMs:settings.locks.wait_ms,message:options.message??`Record ${observation.metric}=${String(options.value)} improvement observation`,mutate:beforeRaw=>{const ledger=parseLedger(beforeRaw);const existing=ensureObservationCanAppend(ledger,observation);if(existing){return{raw:beforeRaw,result:existing}}ledger.observations.push(observation);ledger.observations.sort((left,right)=>left.observed_at.localeCompare(right.observed_at)||left.metric.localeCompare(right.metric)||left.id.localeCompare(right.id));return{raw:`${stableStringify(ledger)}
+`,result:observation}}});return{changed:mutation.changed,observation:mutation.result,ledger_path:"improvement-ledger.json"}}async function readImprovementLedger(options={}){const pmRoot=resolvePmRoot(options.cwd??process.cwd(),options.pmRoot);await assertInitializedTracker(pmRoot);const metric=options.metric===void 0?void 0:normalizeMetricName(options.metric);const since=options.since===void 0?void 0:parseIsoTimestamp(options.since,"since");const limit=parseObservationLimit(options.limit);const ledger=parseLedger(await readFileIfExists(path.join(pmRoot,"improvement-ledger.json")));const matching=ledger.observations.filter(row=>(metric===void 0||row.metric===metric)&&(options.itemId===void 0||row.item_id===options.itemId)&&(since===void 0||row.observed_at>=since));const byMetric=new Map;for(const observation of matching){const rows=byMetric.get(observation.metric)??[];rows.push(observation);byMetric.set(observation.metric,rows)}return{observations:[...matching].reverse().slice(0,limit),total:matching.length,truncated:matching.length>limit,trends:[...byMetric].map(([,observations])=>trendForMetric(observations)).sort((left,right)=>left.metric.localeCompare(right.metric)),source:"audited_workspace_singleton"}}const _testOnlyImprovementLedger={normalizeMetricName,normalizeDirection,parseLedger,parseObservationLimit,trendForMetric};export{_testOnlyImprovementLedger,readImprovementLedger,recordImprovementObservation};
 //# sourceMappingURL=improvement-ledger.js.map
-//# debugId=c2e1edc9-c454-5cfa-85c8-e9fb0a76a296

package/dist/sdk/index.d.ts

@@ -26,6 +26,7 @@ export { PM_REPRODUCIBLE_PROCESS_ENV, createReproducibleProcessRunner, resolveRe
 export { PM_WORKSPACE_RECIPE_SCHEMA, defineWorkspaceRecipe, executeWorkspaceRecipe, runWithWorkspaceRecipe, type WorkspaceRecipe, type WorkspaceRecipeJsonValue, type WorkspaceRecipeOperation, } from "./workspace-recipe.js";
 export { SNAPSHOT_SCHEMA, WORKSPACE_SNAPSHOT_ACTIONS, createWorkspaceSnapshot, deleteWorkspaceSnapshot, inspectWorkspaceSnapshot, listWorkspaceSnapshots, planWorkspaceSnapshotRestore, restoreWorkspaceSnapshot, restoreWorkspaceSnapshotWithRecovery, type CreateWorkspaceSnapshotResult, type RestoreWorkspaceSnapshotOptions, type RestoreWorkspaceSnapshotResult, type WorkspaceSnapshotHistoryImpact, type WorkspaceSnapshotManifest, type WorkspaceSnapshotReference, type WorkspaceSnapshotRestorePlan, } from "./workspace-snapshot.js";
 export { flushTelemetryQueue } from "./telemetry-flush.js";
+export { PM_HISTORY_COMMAND_ALIASES, resolvePmHistoryOperation } from "./cli-contracts.js";
 export { EXECUTABLE_COMMAND_ALIASES, PM_COMMAND_ALIAS_CONTRACTS, renderPmCommandAliasMigrationHint, resolvePmCommandAlias, type PmCommandAliasContract, type PmCommandAliasLifecycle, type PmCommandAliasRegistration, applyBootstrapPagerPolicy, coalesceRepeatedListFlags, listAliasPluralKeys, mergeLinkedTestTwoTokenEntries, normalizeBootstrapInvocation, normalizeLegacyExtensionActionSyntax, parseBootstrapCommandName, parseBootstrapGlobalOptions, parseBootstrapHelpRequest, parseBootstrapTypeValue, stripGlobalBootstrapTokens, type BootstrapGlobalOptions, type BootstrapHelpRequest, type BootstrapInvocationNormalizationResult, type BootstrapNormalizationEvent, } from "./cli-bootstrap.js";
 export { quoteCommandArg, quoteWindowsCommandArg, renderPmCommand, } from "./command-line.js";
 export * from "./agent/command-recovery.js";
@@ -37,6 +38,7 @@ export { PM_EXACT_COVERAGE_METRICS, findCoverageDeficits, type PmCoverageDeficit
 export { _testOnlyHealthCommand, runHealth, type HealthCheck, } from "./governance/health.js";
 export { _testOnlyValidateCommand, projectValidateCounts, runValidate, type ValidateCheck, type ValidateCountsFixesSummary, type ValidateCountsResult, type ValidateFixesSummary, type ValidateMutationServices, } from "./governance/validate.js";
 export { runExtension, type ExtensionCommandAction } from "./extension.js";
+export { buildExtensionInstallPlan, planExtensionDirectoryCopy, type ExtensionCopyPlan, type ExtensionCopyPlanOptions, type ExtensionInstallPlan, } from "./extension/install-plan.js";
 export { resolveExtensionInstallSourceIdentity, type ExtensionInstallSourceCandidate, type ExtensionInstallSourceResolution, type ExtensionInstallSourceSelection, type ResolvedExtensionInstallSource, } from "./extension/source-resolution.js";
 export { applyStoredExtensionMigrationState, readExtensionMigrationState, resolveExtensionMigrationStatePath, runExtensionMigrateAction, runExtensionMigrations, type ExtensionMigrationActionContext, type ExtensionMigrationOutcomeStatus, type ExtensionMigrationReceipt, type ExtensionMigrationRunResult, type ExtensionMigrationState, type ExtensionMigrationStateEntry, type RunExtensionMigrationsOptions, } from "./extension/migrations.js";
 export { findInstalledNpmPackageCandidate, type GithubInstallSource, type InstalledNpmPackageCandidate, type InstallSource, type LocalInstallSource, type NpmInstallSource, type ResolvedInstallSource, } from "./extension/install-sources.js";
@@ -103,6 +105,8 @@ export * from "./duplicates.js";
 export * from "./lifecycle/reopen.js";
 export * from "./history-compact.js";
 export * from "./history-read.js";
+export * from "./history/maintenance.js";
+export { readHistorySnapshot, type HistoryStreamSnapshot } from "../core/history/read.js";
 export * from "./history-provenance.js";
 export * from "./mutation-events.js";
 export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, inspectWorkspaceHistoryState, mutateWorkspaceJsonWithHistory, reconcileWorkspaceJsonHistory, restoreWorkspaceJsonFromHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, type WorkspaceAuditEventOptions, type WorkspaceHistoryChange, type WorkspaceHistoryStateAgreement, type WorkspaceJsonMutation, type WorkspaceJsonMutationOptions, type WorkspaceJsonReconciliationOptions, type WorkspaceJsonRestoreOptions, type WorkspaceJsonRestoreResult, type WorkspaceJsonWriteOptions, } from "../core/history/workspace-history.js";