@unbrained/pm-cli 2026.8.6 → 2026.8.8

package/dist/sdk/improvement-ledger.d.ts

@@ -0,0 +1,139 @@
+import { parseImprovementLedgerDocument as parseLedger } from "./improvement-ledger-validation.js";
+/** Direction in which a metric represents improvement. */
+export type ImprovementDirection = "higher" | "lower" | "target";
+/** One immutable quantitative observation retained by the workspace ledger. */
+export interface ImprovementObservation {
+    /** Content-derived observation identity. */
+    id: string;
+    /** Stable, agent-readable metric name. */
+    metric: string;
+    /** Finite observed numeric value. */
+    value: number;
+    /** Direction in which later values improve. */
+    direction: ImprovementDirection;
+    /** Optional domain unit such as count, ms, bytes, or percent. */
+    unit?: string;
+    /** Required target when direction is target; optional gate threshold otherwise. */
+    threshold?: number;
+    /** ISO timestamp at which the value was observed. */
+    observed_at: string;
+    /** Git commit, caller revision, or explicit unversioned marker. */
+    revision: string;
+    /** How the revision value was obtained. */
+    revision_source: "caller" | "git" | "unversioned";
+    /** Attributed actor that recorded the observation. */
+    author: string;
+    /** Optional tracked item owning the measurement. */
+    item_id?: string;
+    /** Optional producing instrument or gate name. */
+    source?: string;
+    /** Stable retry key when supplied or derivable from a revision. */
+    idempotency_key?: string;
+}
+/** Versioned workspace singleton containing every retained observation. */
+export interface ImprovementLedgerDocument {
+    /** Storage contract revision. */
+    format_version: 1;
+    /** Append-only observations in deterministic chronological order. */
+    observations: ImprovementObservation[];
+}
+/** Mutation controls accepted by {@link recordImprovementObservation}. */
+export interface RecordImprovementObservationOptions {
+    /** Stable metric name. */
+    metric: string;
+    /** Finite observed numeric value. */
+    value: number;
+    /** Direction in which later values improve. */
+    direction?: ImprovementDirection;
+    /** Optional domain unit. */
+    unit?: string;
+    /** Target or gate threshold associated with this observation. */
+    threshold?: number;
+    /** Optional producing instrument or gate name. */
+    source?: string;
+    /** Optional tracked item owning the observation. */
+    itemId?: string;
+    /** Explicit source revision; otherwise git HEAD is resolved when available. */
+    revision?: string;
+    /** Explicit observation time, primarily for reproducible importers. */
+    observedAt?: string;
+    /** Explicit retry identity. */
+    idempotencyKey?: string;
+    /** Intentional author override. */
+    author?: string;
+    /** Human-readable audit rationale. */
+    message?: string;
+}
+/** Receipt returned after recording or replaying one observation. */
+export interface RecordImprovementObservationResult {
+    /** Whether a new observation was appended. */
+    changed: boolean;
+    /** Recorded or idempotently replayed observation. */
+    observation: ImprovementObservation;
+    /** Workspace-relative singleton path. */
+    ledger_path: "improvement-ledger.json";
+}
+/** Bounded read controls for {@link readImprovementLedger}. */
+export interface ReadImprovementLedgerOptions {
+    /** Explicit tracker root, equivalent to global --pm-path. */
+    pmRoot?: string;
+    /** Working directory used for implicit tracker discovery. */
+    cwd?: string;
+    /** Optional exact metric filter. */
+    metric?: string;
+    /** Optional tracked owner filter. */
+    itemId?: string;
+    /** Inclusive ISO timestamp lower bound. */
+    since?: string;
+    /** Maximum newest observations returned. */
+    limit?: number;
+}
+/** One baseline-to-latest trend computed without rewriting observations. */
+export interface ImprovementTrend {
+    /** Stable metric name. */
+    metric: string;
+    /** Direction used to interpret the delta. */
+    direction: ImprovementDirection;
+    /** Oldest matching observation. */
+    baseline: ImprovementObservation;
+    /** Newest matching observation. */
+    latest: ImprovementObservation;
+    /** Latest value minus baseline value. */
+    delta: number;
+    /** Whether the latest value improved over the baseline. */
+    improved: boolean;
+    /** Number of observations contributing to the trend. */
+    sample_count: number;
+}
+/** Bounded ledger page plus complete aggregate trend metadata. */
+export interface ImprovementLedgerResult {
+    /** Newest-first observation page. */
+    observations: ImprovementObservation[];
+    /** Matching observation count before the page limit. */
+    total: number;
+    /** Whether older matching rows were omitted. */
+    truncated: boolean;
+    /** Trends for every matching metric, sorted by metric name. */
+    trends: ImprovementTrend[];
+    /** Read provenance for deterministic consumers. */
+    source: "audited_workspace_singleton";
+}
+declare function normalizeMetricName(value: string): string;
+declare function normalizeDirection(value: ImprovementDirection | undefined): ImprovementDirection;
+declare function parseObservationLimit(value: number | undefined): number;
+declare function trendForMetric(observations: ImprovementObservation[]): ImprovementTrend;
+/** Record one audited observation, returning an idempotent receipt on retry. */
+export declare function recordImprovementObservation(options: RecordImprovementObservationOptions, global?: {
+    path?: string;
+}): Promise<RecordImprovementObservationResult>;
+/** Read a bounded newest-first observation page and derive complete trends. */
+export declare function readImprovementLedger(options?: ReadImprovementLedgerOptions): Promise<ImprovementLedgerResult>;
+/** Pure helpers exposed for storage and trend contract tests. */
+export declare const _testOnlyImprovementLedger: {
+    normalizeMetricName: typeof normalizeMetricName;
+    normalizeDirection: typeof normalizeDirection;
+    parseLedger: typeof parseLedger;
+    parseObservationLimit: typeof parseObservationLimit;
+    trendForMetric: typeof trendForMetric;
+};
+export {};

package/dist/sdk/improvement-ledger.js

@@ -0,0 +1,261 @@
+/**
+ * @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]="aaa927b3-4bc4-561f-aff1-85dc95c12ea1")}catch(e){}}();
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+import { pathExists, 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 { getSettingsPath, 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);
+    if (!(await pathExists(getSettingsPath(pmRoot)))) {
+        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
+    }
+    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);
+    if (!(await pathExists(getSettingsPath(pmRoot)))) {
+        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
+    }
+    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,
+};
+//# sourceMappingURL=improvement-ledger.js.map
+//# debugId=aaa927b3-4bc4-561f-aff1-85dc95c12ea1

package/dist/sdk/index.d.ts

@@ -6,8 +6,8 @@
 export { PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, PM_MCP_TOOL_COMMAND_CONTRACTS, listPmCommandsForTier, listPmMcpToolsForProfile, renderPmCommandVisibilityMarkdown, resolvePmCommandVisibilityTier, } from "./agent-capability-contracts.js";
 export * from "./agent-session-context.js";
 export type { PmCommandVisibilityContract, PmCommandVisibilityTier, PmMcpPromptArgumentContract, PmMcpPromptContract, PmMcpResourceContract, PmMcpToolProfile, } from "./agent-capability-contracts.js";
-export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, type AnnotationCommandConfig, type AnnotationCommandOptions, type AnnotationCommandResult, type AnnotationEntry, type AnnotationInput, type AnnotationSourceOptions, type OwnershipConflictGuidance, } from "./annotations.js";
-export { acknowledgeUnknownAuthorHistoryEvents, inspectHistoryAuthorStream, scanHistoryAuthorAttribution, type AcknowledgeUnknownAuthorEventsOptions, type HistoryAuthorAttributionScan, type UnknownAuthorHistoryEvent, } from "./author-attribution.js";
+export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, normalizeAnnotationTransportOptions, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, type AnnotationCommandConfig, type AnnotationCommandOptions, type AnnotationCommandResult, type AnnotationEntry, type AnnotationInput, type AnnotationHistoryRestoration, type AnnotationMutationReceipt, type AnnotationOmissionReceipt, type AnnotationSourceOptions, type OwnershipConflictGuidance, } from "./annotations.js";
+export { acknowledgeUnknownAuthorHistoryEvents, acknowledgeUnknownAuthorHistoryEventsFromTransport, inspectHistoryAuthorStream, parseUnknownAuthorHistoryEventCoordinates, resolveUnknownAuthorAcknowledgmentSelector, scanHistoryAuthorAttribution, type AcknowledgeUnknownAuthorEventsOptions, type HistoryAuthorAttributionScan, type UnknownAuthorHistoryEvent, } from "./author-attribution.js";
 export { BUILTIN_CORPUS_SHAPES, PM_CORPUS_SHAPE_SCHEMA, buildCorpusShapeItemPlan, createCorpusShapeMeasurement, defineCorpusShape, listBuiltinCorpusShapes, measureCorpusShapePlan, resolveBuiltinCorpusShape, type BuiltinCorpusShapeName, type CorpusShape, type CorpusShapeEdgeWeight, type CorpusShapeItemPlan, type CorpusShapeMeasurement, type CorpusShapeProfile, } from "./corpus-shape.js";
 export * from "./core-governance.js";
 export { createPmCliProgram } from "./cli-program.js";
@@ -20,7 +20,7 @@ export { quoteCommandArg, quoteWindowsCommandArg, renderPmCommand, } from "./com
 export { runGc, type GcCheckpointsSummary, type GcLocksSummary, } from "./governance/gc.js";
 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 { runExtension, type ExtensionCommandAction } from "./extension.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";
@@ -29,7 +29,7 @@ export { runEvent, runMeet, runRemind, type MeetingEventShortcutOptions, type Re
 export { createExtensionCommandSdk } from "./extension-command-context.js";
 export { isRuntimeRecord } from "./runtime-input.js";
 export { resolveStartTaskInProgressStatus } from "./start-task-status.js";
-export { auditMergeAttributeFence, buildMergeAttributePatterns, findGitWorkspaceRoot, installMergeFence, refreshMergeAttributeFenceIfInstalled, resolveProjectMergeTypeFolders, runMergeInstall, type MergeFenceAuditResult, type MergeFenceRefreshOutcome, type MergeInstallOptions, type MergeInstallResult, } from "./merge/install.js";
+export { auditMergeAttributeFence, buildMergeAttributePatterns, findGitWorkspaceRoot, installMergeFence, refreshMergeAttributeFenceIfInstalled, resolveMergeInstallContext, resolveProjectMergeTypeFolders, runMergeInstall, type MergeFenceAuditResult, type MergeFenceRefreshOutcome, type MergeInstallOptions, type MergeInstallContextResolution, type MergeInstallResult, } from "./merge/install.js";
 export { deriveSchemaEvolutionMigrationId, formatSchemaEvolutionMigrationHuman, planSchemaEvolutionMigration, runSchemaEvolutionMigration, type PlanSchemaEvolutionMigrationOptions, type SchemaEvolutionFieldChange, type SchemaEvolutionItemPlan, type SchemaEvolutionMigrationPlan, } from "./schema-migration.js";
 export { runWithActiveExtensions, type ActiveExtensionScopeOptions, } from "./runtime.js";
 export { applyInvocationAuthorOverride } from "./invocation-author.js";
@@ -52,6 +52,10 @@ export { ACTIVITY_FLAG_CONTRACTS, ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, AG
 export type { CliFlagContract, OptionsFromContracts, PmActionSchemaContract, PmActionToolInputSchemaOptions, PmToolCustomFieldCollision, PmBulkMutationControlOptions, PmBulkMutationFilterOptions, PmCloseActionOptions, PmCloseManyActionOptions, PmCreateActionOptions, PmMutationAttributionOptions, PmOptionScalar, PmCommandOutputBudgetContract, PmOutputBudgetClass, PmOutputDegradationStep, PmUpdateActionOptions, PmUpdateManyActionOptions, PmExtensionCapabilityContract, PmExtensionPolicyModeContract, PmExtensionPolicySurfaceContract, PmExtensionSandboxProfileContract, PmExtensionServiceNameContract, PmExtensionTrustModeContract, PmToolAction, SdkCliActionParameterCoverage, SdkCliCompletenessContractSource, SdkCliParameterCoverageEntry, SdkCliParameterDisposition, ToolOptionFlagContract, } from "./cli-contracts.js";
 export * from "./compose.js";
 export * from "./compile-cache.js";
+export * from "./environment/project-runtime-compatibility.js";
+export * from "./environment/source-context.js";
+export * from "./environment/host-environment-errors.js";
+export * from "./cli-contracts/command-exit-contracts.js";
 export * from "./context-relevance.js";
 export * from "./context-intent-contracts.js";
 export * from "./context-intent-runtime.js";
@@ -61,6 +65,8 @@ export * from "./lifecycle-completion.js";
 export * from "./lifecycle-policy.js";
 export * from "./output-projection.js";
 export * from "./read-output-contracts.js";
+export * from "./read-output-rows.js";
+export * from "./read-output-session.js";
 export * from "./output-token-accounting.js";
 export * from "./context-packing.js";
 export * from "./context-usage.js";
@@ -70,7 +76,7 @@ export * from "./history-compact.js";
 export * from "./history-read.js";
 export * from "./history-provenance.js";
 export * from "./mutation-events.js";
-export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, type WorkspaceAuditEventOptions, type WorkspaceHistoryChange, type WorkspaceJsonWriteOptions, } from "../core/history/workspace-history.js";
+export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, mutateWorkspaceJsonWithHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, type WorkspaceAuditEventOptions, type WorkspaceHistoryChange, type WorkspaceJsonMutation, type WorkspaceJsonMutationOptions, type WorkspaceJsonWriteOptions, } from "../core/history/workspace-history.js";
 export * from "./history-redact.js";
 export { _testOnly } from "./history-redact.js";
 export * from "./history-repair.js";
@@ -125,6 +131,8 @@ export { BASELINE_ITEM_FORMAT_VERSION, BUILTIN_ITEM_TYPE_VALUES, CONFIDENCE_TEXT
 export { extensionMigrate, packageMigrate } from "./package-migrations.js";
 export { CONTEXT_OUTPUT_VALUES, NEXT_OUTPUT_VALUES, PM_GITIGNORE_END, PM_GITIGNORE_START, analyzeSdkActionCoverage, ensurePmGitignore, getPmGitignoreBlock, closeItem, runAggregate, runClose, runCopy, runContext, runDelete, runFocus, runGet, runNext, runRestore, runUpdate, type CloseCommandOptions, type CopyOptions, type DeleteCommandOptions, type EnsurePmGitignoreResult, type HierarchyChild, type HierarchyNode, type HotFile, type FocusOptions, type ImportPriorityValue, type ProgressEntry, type RecentContextItem, type RestoreCommandOptions, type SdkActionCoverageRow, type StaleEntry, type TestHealthSummary, type UpdateCommandOptions, type WorkloadEntry, } from "./runtime.js";
 export { runStats } from "./stats.js";
+export { readImprovementLedger, recordImprovementObservation, type ImprovementDirection, type ImprovementLedgerDocument, type ImprovementLedgerResult, type ImprovementObservation, type ImprovementTrend, type ReadImprovementLedgerOptions, type RecordImprovementObservationOptions, type RecordImprovementObservationResult, } from "./improvement-ledger.js";
+export { evaluateProvenanceCoverage, projectFleetAttributionAnalytics, projectProvenanceCoverageAnalytics, readHistoryAnalyticsWindow, runFleetAttributionAnalytics, runProvenanceCoverageAnalytics, type FleetAttributionAnalytics, type FleetAttributionDimension, type FleetAttributionRow, type HistoryAnalyticsWindowOptions, type HistoryAnalyticsWindowReceipt, type HistoryAnalyticsEvent, type HistoryAnalyticsWindow, type ProvenanceCoverageAnalytics, } from "./history-analytics.js";
 export { DEFAULT_EVAL_QUERIES_RELATIVE_PATH, EVAL_QUERY_SET_CONTRACT, EVAL_QUERY_SET_EXAMPLE, EVAL_QUERY_SET_SCHEMA_ID, parseEvalQuerySet, runEval, type EvalOptions, type EvalQueryReport, type EvalResult, } from "./eval.js";
 export { runTelemetry, TELEMETRY_SUBCOMMANDS, type TelemetryCommandOptions, type TelemetryFlushResult, type TelemetryStatusSummary, type TelemetrySubcommand, } from "./telemetry.js";
 export { classifyLinkedTestFailure, countFailureCategories, extractReferencedPmItemIdsFromCommand, resolveLinkedTestFailureExitCode, runLinkedTests, runTest, summarizeContextPreflight, type LinkedTestFailureCategory, type TestCommandOptions, type TestResult, type TestRunResult, } from "./test/execution.js";

package/dist/sdk/index.js

@@ -4,11 +4,11 @@
  * Defines public SDK APIs and package-author helpers for Index.
  */
 
-!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]="4e336574-f00e-5296-a55f-7f27a264188c")}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]="ae84c7af-bfa7-577d-b9f3-2bd9450d5755")}catch(e){}}();
 export { PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, PM_MCP_TOOL_COMMAND_CONTRACTS, listPmCommandsForTier, listPmMcpToolsForProfile, renderPmCommandVisibilityMarkdown, resolvePmCommandVisibilityTier, } from "./agent-capability-contracts.js";
 export * from "./agent-session-context.js";
-export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, } from "./annotations.js";
-export { acknowledgeUnknownAuthorHistoryEvents, inspectHistoryAuthorStream, scanHistoryAuthorAttribution, } from "./author-attribution.js";
+export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, normalizeAnnotationTransportOptions, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, } from "./annotations.js";
+export { acknowledgeUnknownAuthorHistoryEvents, acknowledgeUnknownAuthorHistoryEventsFromTransport, inspectHistoryAuthorStream, parseUnknownAuthorHistoryEventCoordinates, resolveUnknownAuthorAcknowledgmentSelector, scanHistoryAuthorAttribution, } from "./author-attribution.js";
 export { BUILTIN_CORPUS_SHAPES, PM_CORPUS_SHAPE_SCHEMA, buildCorpusShapeItemPlan, createCorpusShapeMeasurement, defineCorpusShape, listBuiltinCorpusShapes, measureCorpusShapePlan, resolveBuiltinCorpusShape, } from "./corpus-shape.js";
 export * from "./core-governance.js";
 export { createPmCliProgram } from "./cli-program.js";
@@ -21,7 +21,7 @@ export { quoteCommandArg, quoteWindowsCommandArg, renderPmCommand, } from "./com
 export { runGc, } from "./governance/gc.js";
 export { _testOnlyHealthCommand, runHealth, } from "./governance/health.js";
 export { _testOnlyValidateCommand, projectValidateCounts, runValidate, } from "./governance/validate.js";
-export { runExtension, } from "./extension.js";
+export { runExtension } from "./extension.js";
 export { resolveExtensionInstallSourceIdentity, } from "./extension/source-resolution.js";
 export { applyStoredExtensionMigrationState, readExtensionMigrationState, resolveExtensionMigrationStatePath, runExtensionMigrateAction, runExtensionMigrations, } from "./extension/migrations.js";
 export { findInstalledNpmPackageCandidate, } from "./extension/install-sources.js";
@@ -30,7 +30,7 @@ export { runEvent, runMeet, runRemind, } from "./scheduling-shortcuts.js";
 export { createExtensionCommandSdk } from "./extension-command-context.js";
 export { isRuntimeRecord } from "./runtime-input.js";
 export { resolveStartTaskInProgressStatus } from "./start-task-status.js";
-export { auditMergeAttributeFence, buildMergeAttributePatterns, findGitWorkspaceRoot, installMergeFence, refreshMergeAttributeFenceIfInstalled, resolveProjectMergeTypeFolders, runMergeInstall, } from "./merge/install.js";
+export { auditMergeAttributeFence, buildMergeAttributePatterns, findGitWorkspaceRoot, installMergeFence, refreshMergeAttributeFenceIfInstalled, resolveMergeInstallContext, resolveProjectMergeTypeFolders, runMergeInstall, } from "./merge/install.js";
 export { deriveSchemaEvolutionMigrationId, formatSchemaEvolutionMigrationHuman, planSchemaEvolutionMigration, runSchemaEvolutionMigration, } from "./schema-migration.js";
 export { runWithActiveExtensions, } from "./runtime.js";
 export { applyInvocationAuthorOverride } from "./invocation-author.js";
@@ -50,6 +50,10 @@ export { PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS, PM_PACKAGE_RESOURCE_KINDS, coll
 export { ACTIVITY_FLAG_CONTRACTS, ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_ACTION_OPTION_KEYS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EVAL_FLAG_CONTRACTS, EVENT_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_SCOPE_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, PLAN_CREATE_METADATA_PARAMETER_KEYS, PLAN_FLAG_CONTRACTS, PM_COMMAND_OUTPUT_BUDGET_CONTRACTS, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_CORE_COMMAND_NAMES, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION, PM_TOOL_ACTIONS, analyzePmToolActionParity, PM_TOOL_ACTION_PARAMETER_CONTRACTS, PM_TOOL_PARAMETERS_SCHEMA, PM_TOOL_PARAMETERS_SCHEMA_MAJOR, PM_TOOL_PARAMETERS_SCHEMA_VERSION, PM_OUTPUT_BUDGET_CLASSES, PM_OUTPUT_DEGRADATION_STEPS, PROFILE_FLAG_CONTRACTS, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACT_SOURCE, TOOL_CALENDAR_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACT_SOURCE, TOOL_DEPS_OPTION_CONTRACTS, TOOL_GRAPH_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACT_SOURCE, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACT_SOURCE, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, buildPmActionToolInputSchema, PM_TOOL_RESERVED_CUSTOM_FIELD_PROPERTIES, compactFlagAliasContracts, createPmCommandOutputBudget, definePmCommandOutputBudget, estimatePmOutputTokens, inferPmOutputBudgetClass, analyzeSdkCliParameterCompleteness, isPmExtensionCapabilityContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, isPmExtensionServiceNameContract, isPmToolAction, hasSubcommandFlagContractsForCommand, readFirstStringFromCommanderOptions, readFirstValueFromCommanderOptions, readStringArrayFromCommanderOptions, resolveSubcommandFlagContractsForCommand, resolvePmCommandOutputBudget, resolvePmToolCustomFieldCollision, toCompletionFlagString, withFlagAliasMetadata, } from "./cli-contracts.js";
 export * from "./compose.js";
 export * from "./compile-cache.js";
+export * from "./environment/project-runtime-compatibility.js";
+export * from "./environment/source-context.js";
+export * from "./environment/host-environment-errors.js";
+export * from "./cli-contracts/command-exit-contracts.js";
 export * from "./context-relevance.js";
 export * from "./context-intent-contracts.js";
 export * from "./context-intent-runtime.js";
@@ -59,6 +63,8 @@ export * from "./lifecycle-completion.js";
 export * from "./lifecycle-policy.js";
 export * from "./output-projection.js";
 export * from "./read-output-contracts.js";
+export * from "./read-output-rows.js";
+export * from "./read-output-session.js";
 export * from "./output-token-accounting.js";
 export * from "./context-packing.js";
 export * from "./context-usage.js";
@@ -68,7 +74,7 @@ export * from "./history-compact.js";
 export * from "./history-read.js";
 export * from "./history-provenance.js";
 export * from "./mutation-events.js";
-export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, } from "../core/history/workspace-history.js";
+export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, mutateWorkspaceJsonWithHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, } from "../core/history/workspace-history.js";
 export * from "./history-redact.js";
 export { _testOnly } from "./history-redact.js";
 export * from "./history-repair.js";
@@ -117,6 +123,8 @@ export { BASELINE_ITEM_FORMAT_VERSION, BUILTIN_ITEM_TYPE_VALUES, CONFIDENCE_TEXT
 export { extensionMigrate, packageMigrate } from "./package-migrations.js";
 export { CONTEXT_OUTPUT_VALUES, NEXT_OUTPUT_VALUES, PM_GITIGNORE_END, PM_GITIGNORE_START, analyzeSdkActionCoverage, ensurePmGitignore, getPmGitignoreBlock, closeItem, runAggregate, runClose, runCopy, runContext, runDelete, runFocus, runGet, runNext, runRestore, runUpdate, } from "./runtime.js";
 export { runStats } from "./stats.js";
+export { readImprovementLedger, recordImprovementObservation, } from "./improvement-ledger.js";
+export { evaluateProvenanceCoverage, projectFleetAttributionAnalytics, projectProvenanceCoverageAnalytics, readHistoryAnalyticsWindow, runFleetAttributionAnalytics, runProvenanceCoverageAnalytics, } from "./history-analytics.js";
 export { DEFAULT_EVAL_QUERIES_RELATIVE_PATH, EVAL_QUERY_SET_CONTRACT, EVAL_QUERY_SET_EXAMPLE, EVAL_QUERY_SET_SCHEMA_ID, parseEvalQuerySet, runEval, } from "./eval.js";
 export { runTelemetry, TELEMETRY_SUBCOMMANDS, } from "./telemetry.js";
 export { classifyLinkedTestFailure, countFailureCategories, extractReferencedPmItemIdsFromCommand, resolveLinkedTestFailureExitCode, runLinkedTests, runTest, summarizeContextPreflight, } from "./test/execution.js";
@@ -133,4 +141,4 @@ export * from "./governance.js";
 export * from "./query.js";
 export * from "./testing.js";
 //# sourceMappingURL=index.js.map
-//# debugId=4e336574-f00e-5296-a55f-7f27a264188c
+//# debugId=ae84c7af-bfa7-577d-b9f3-2bd9450d5755

package/dist/sdk/learnings.d.ts

@@ -5,6 +5,7 @@
  */
 import { type GlobalOptions } from "./runtime-primitives.js";
 import type { LogNote } from "../types/index.js";
+import { type AnnotationMutationReceipt, type AnnotationOmissionReceipt } from "./annotations.js";
 /** Documents the learnings command options payload exchanged by command, SDK, and package integrations. */
 export interface LearningsCommandOptions {
     /** Value that configures or reports add for this contract. */
@@ -19,6 +20,8 @@ export interface LearningsCommandOptions {
     delete?: number;
     /** Value that configures or reports limit for this contract. */
     limit?: string;
+    /** Return complete learning history after a mutation instead of a bounded receipt. */
+    fullHistory?: boolean;
     /** Value that configures or reports author for this contract. */
     author?: string;
     /** Human-readable explanation suitable for logs and agent-facing output. */
@@ -34,6 +37,18 @@ export interface LearningsResult {
     learnings: LogNote[];
     /** Value that configures or reports count for this contract. */
     count: number;
+    /** Total learning count after the mutation. */
+    total_count?: number;
+    /** Number of learning entries returned in this projection. */
+    returned_count?: number;
+    /** Whether additional stored learning entries were withheld. */
+    has_more?: boolean;
+    /** Applied read limit when one was requested. */
+    limit?: number;
+    /** Mutation identity when this result changed the collection. */
+    mutation_receipt?: AnnotationMutationReceipt;
+    /** Declares whether older learnings were withheld from a mutation response. */
+    omission_receipt?: AnnotationOmissionReceipt;
 }
 /** Implements run learnings for the public runtime surface of this module. */
 export declare function runLearnings(id: string, options: LearningsCommandOptions, global: GlobalOptions): Promise<LearningsResult>;

package/dist/sdk/learnings.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]="26e30c82-7d6d-51b9-909f-b779213846b1")}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]="93184f29-f215-5413-9628-fb5b34523995")}catch(e){}}();
 import { parseAnnotationTextInput, resolveAnnotationInput, runAnnotationCommand, } from "./annotations.js";
 /** Implements run learnings for the public runtime surface of this module. */
 export async function runLearnings(id, options, global) {
@@ -24,4 +24,4 @@ export async function runLearnings(id, options, global) {
     });
 }
 //# sourceMappingURL=learnings.js.map
-//# debugId=26e30c82-7d6d-51b9-909f-b779213846b1
+//# debugId=93184f29-f215-5413-9628-fb5b34523995

package/dist/sdk/lifecycle/close-many.d.ts

@@ -5,6 +5,7 @@
  */
 import { type GlobalOptions, readSettings } from "../runtime-primitives.js";
 import { type ListOptions } from "../query/list.js";
+import { type PmCommandEffectReceipt } from "../cli-contracts/command-exit-contracts.js";
 /** Documents the close many command options payload exchanged by command, SDK, and package integrations. */
 export interface CloseManyCommandOptions {
     /** Lifecycle state reported for status. */
@@ -55,7 +56,7 @@ interface CloseManyApplyRow {
     error?: string;
 }
 /** Documents the close many result payload exchanged by command, SDK, and package integrations. */
-export interface CloseManyResult {
+export interface CloseManyResult extends PmCommandEffectReceipt {
     /** Value that configures or reports mode for this contract. */
     mode: "dry_run" | "apply" | "rollback";
     /** Number of matched entries represented by this result. */
@@ -97,6 +98,10 @@ export interface CloseManyResult {
     }>;
     /** Value that configures or reports ids for this contract. */
     ids: string[];
+    /** Explicitly requested --ids values that matched no selected item. */
+    unmatched_ids?: string[];
+    /** Number of explicitly requested --ids values that matched no selected item. */
+    unmatched_count?: number;
 }
 declare function hasCloseManyFilters(list: ListOptions | undefined, status: string | undefined): boolean;
 declare function hasCloseManyRollbackConflicts(list: ListOptions | undefined, status: string | undefined): boolean;