@ai-agent-forge/agent-forge 0.85.0

package/dist/host/auto-compaction.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Auto compaction executor (2A.3a) — threshold-triggered compaction with
+ * explicit cancellation and re-entrancy semantics, still built on the 2A.1
+ * checkpoint primitives.
+ *
+ * The trigger is a declared policy (enabled flag + token threshold); a
+ * disabled policy answers `disabled` explicitly. When the threshold is met
+ * the executor stages a checkpoint, hands an AbortSignal to the plugin's
+ * summarize callback, and commits — unless the signal fired first
+ * (`cancelled`, staged entry dropped, no half commit). Re-entrant triggers
+ * while a compaction is in flight are rejected as `busy`. Overflow recovery
+ * and retry belong to 2A.3b/2A.4.
+ */
+import type { JsonValue } from "@agent-forge/ai";
+import type { HostCheckpointCoordinatorV1 } from "./checkpoint-commit.ts";
+export interface AutoCompactionPolicyV1 {
+    readonly policyId: string;
+    /** Compaction triggers only when currentTokens >= tokenThreshold. */
+    readonly tokenThreshold: number;
+    readonly enabled: boolean;
+}
+export type AutoCompactionOutcomeV1 = {
+    readonly status: "completed";
+    readonly revision: number;
+    readonly summary: JsonValue;
+} | {
+    readonly status: "below_threshold";
+    readonly currentTokens: number;
+    readonly threshold: number;
+} | {
+    readonly status: "cancelled";
+} | {
+    readonly status: "summary_failed";
+    readonly reason: string;
+} | {
+    readonly status: "stale";
+    readonly currentRevision: number;
+} | {
+    readonly status: "busy";
+} | {
+    readonly status: "disabled";
+};
+export interface AutoCompactionExecutorV1 {
+    maybeCompact(input: {
+        readonly operationId: string;
+        readonly currentTokens: number;
+        readonly summarize: (signal: AbortSignal | undefined) => JsonValue;
+        readonly signal?: AbortSignal;
+    }): AutoCompactionOutcomeV1;
+    readonly inProgress: boolean;
+}
+export declare function createAutoCompactionExecutor(options: {
+    readonly coordinator: HostCheckpointCoordinatorV1;
+    readonly policy: AutoCompactionPolicyV1;
+}): AutoCompactionExecutorV1;
+//# sourceMappingURL=auto-compaction.d.ts.map

package/dist/host/auto-compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-compaction.d.ts","sourceRoot":"","sources":["../../src/host/auto-compaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAE1E,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,MAAM,uBAAuB,GAChC;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAA;CAAE,GACxF;IAAE,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAClG;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAChC;IAAE,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC9D;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CAAE,GAC9D;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC;AAEnC,MAAM,WAAW,wBAAwB;IACxC,YAAY,CAAC,KAAK,EAAE;QACnB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;QAC/B,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,KAAK,SAAS,CAAC;QACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;KAC9B,GAAG,uBAAuB,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC7B;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE;IACrD,QAAQ,CAAC,WAAW,EAAE,2BAA2B,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;CACxC,GAAG,wBAAwB,CAsD3B","sourcesContent":["/**\n * Auto compaction executor (2A.3a) — threshold-triggered compaction with\n * explicit cancellation and re-entrancy semantics, still built on the 2A.1\n * checkpoint primitives.\n *\n * The trigger is a declared policy (enabled flag + token threshold); a\n * disabled policy answers `disabled` explicitly. When the threshold is met\n * the executor stages a checkpoint, hands an AbortSignal to the plugin's\n * summarize callback, and commits — unless the signal fired first\n * (`cancelled`, staged entry dropped, no half commit). Re-entrant triggers\n * while a compaction is in flight are rejected as `busy`. Overflow recovery\n * and retry belong to 2A.3b/2A.4.\n */\nimport type { JsonValue } from \"@agent-forge/ai\";\nimport type { HostCheckpointCoordinatorV1 } from \"./checkpoint-commit.ts\";\n\nexport interface AutoCompactionPolicyV1 {\n\treadonly policyId: string;\n\t/** Compaction triggers only when currentTokens >= tokenThreshold. */\n\treadonly tokenThreshold: number;\n\treadonly enabled: boolean;\n}\n\nexport type AutoCompactionOutcomeV1 =\n\t| { readonly status: \"completed\"; readonly revision: number; readonly summary: JsonValue }\n\t| { readonly status: \"below_threshold\"; readonly currentTokens: number; readonly threshold: number }\n\t| { readonly status: \"cancelled\" }\n\t| { readonly status: \"summary_failed\"; readonly reason: string }\n\t| { readonly status: \"stale\"; readonly currentRevision: number }\n\t| { readonly status: \"busy\" }\n\t| { readonly status: \"disabled\" };\n\nexport interface AutoCompactionExecutorV1 {\n\tmaybeCompact(input: {\n\t\treadonly operationId: string;\n\t\treadonly currentTokens: number;\n\t\treadonly summarize: (signal: AbortSignal | undefined) => JsonValue;\n\t\treadonly signal?: AbortSignal;\n\t}): AutoCompactionOutcomeV1;\n\treadonly inProgress: boolean;\n}\n\nexport function createAutoCompactionExecutor(options: {\n\treadonly coordinator: HostCheckpointCoordinatorV1;\n\treadonly policy: AutoCompactionPolicyV1;\n}): AutoCompactionExecutorV1 {\n\tconst coordinator = options.coordinator;\n\tconst policy = options.policy;\n\tlet inProgress = false;\n\n\treturn {\n\t\tget inProgress() {\n\t\t\treturn inProgress;\n\t\t},\n\t\tmaybeCompact(input) {\n\t\t\tif (!policy.enabled) return { status: \"disabled\" };\n\t\t\tif (inProgress) return { status: \"busy\" };\n\t\t\tif (input.currentTokens < policy.tokenThreshold) {\n\t\t\t\treturn { status: \"below_threshold\", currentTokens: input.currentTokens, threshold: policy.tokenThreshold };\n\t\t\t}\n\t\t\tinProgress = true;\n\t\t\ttry {\n\t\t\t\tconst staged = coordinator.stage({\n\t\t\t\t\toperationId: input.operationId,\n\t\t\t\t\texpectedRevision: coordinator.currentRevision,\n\t\t\t\t\tpayload: null,\n\t\t\t\t});\n\t\t\t\tif (staged.status === \"stale\") return { status: \"stale\", currentRevision: staged.currentRevision };\n\t\t\t\tif (staged.status === \"duplicate\") return { status: \"cancelled\" };\n\t\t\t\tif (input.signal?.aborted) {\n\t\t\t\t\tcoordinator.cancelStage(staged.staged.token);\n\t\t\t\t\treturn { status: \"cancelled\" };\n\t\t\t\t}\n\t\t\t\tlet summary: JsonValue;\n\t\t\t\ttry {\n\t\t\t\t\tsummary = input.summarize(input.signal);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tcoordinator.cancelStage(staged.staged.token);\n\t\t\t\t\treturn { status: \"summary_failed\", reason: error instanceof Error ? error.message : String(error) };\n\t\t\t\t}\n\t\t\t\tif (input.signal?.aborted) {\n\t\t\t\t\tcoordinator.cancelStage(staged.staged.token);\n\t\t\t\t\treturn { status: \"cancelled\" };\n\t\t\t\t}\n\t\t\t\tconst outcome = coordinator.commitStage({\n\t\t\t\t\ttoken: staged.staged.token,\n\t\t\t\t\tapply: () => undefined,\n\t\t\t\t});\n\t\t\t\tif (outcome.status === \"stale\") return { status: \"stale\", currentRevision: outcome.currentRevision };\n\t\t\t\tif (outcome.status === \"committed\") {\n\t\t\t\t\treturn { status: \"completed\", revision: outcome.revision, summary };\n\t\t\t\t}\n\t\t\t\tcoordinator.cancelStage(staged.staged.token);\n\t\t\t\treturn { status: \"cancelled\" };\n\t\t\t} finally {\n\t\t\t\tinProgress = false;\n\t\t\t}\n\t\t},\n\t};\n}\n"]}

package/dist/host/auto-compaction.js

@@ -0,0 +1,62 @@
+export function createAutoCompactionExecutor(options) {
+    const coordinator = options.coordinator;
+    const policy = options.policy;
+    let inProgress = false;
+    return {
+        get inProgress() {
+            return inProgress;
+        },
+        maybeCompact(input) {
+            if (!policy.enabled)
+                return { status: "disabled" };
+            if (inProgress)
+                return { status: "busy" };
+            if (input.currentTokens < policy.tokenThreshold) {
+                return { status: "below_threshold", currentTokens: input.currentTokens, threshold: policy.tokenThreshold };
+            }
+            inProgress = true;
+            try {
+                const staged = coordinator.stage({
+                    operationId: input.operationId,
+                    expectedRevision: coordinator.currentRevision,
+                    payload: null,
+                });
+                if (staged.status === "stale")
+                    return { status: "stale", currentRevision: staged.currentRevision };
+                if (staged.status === "duplicate")
+                    return { status: "cancelled" };
+                if (input.signal?.aborted) {
+                    coordinator.cancelStage(staged.staged.token);
+                    return { status: "cancelled" };
+                }
+                let summary;
+                try {
+                    summary = input.summarize(input.signal);
+                }
+                catch (error) {
+                    coordinator.cancelStage(staged.staged.token);
+                    return { status: "summary_failed", reason: error instanceof Error ? error.message : String(error) };
+                }
+                if (input.signal?.aborted) {
+                    coordinator.cancelStage(staged.staged.token);
+                    return { status: "cancelled" };
+                }
+                const outcome = coordinator.commitStage({
+                    token: staged.staged.token,
+                    apply: () => undefined,
+                });
+                if (outcome.status === "stale")
+                    return { status: "stale", currentRevision: outcome.currentRevision };
+                if (outcome.status === "committed") {
+                    return { status: "completed", revision: outcome.revision, summary };
+                }
+                coordinator.cancelStage(staged.staged.token);
+                return { status: "cancelled" };
+            }
+            finally {
+                inProgress = false;
+            }
+        },
+    };
+}
+//# sourceMappingURL=auto-compaction.js.map

package/dist/host/auto-compaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-compaction.js","sourceRoot":"","sources":["../../src/host/auto-compaction.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Auto compaction executor (2A.3a) — threshold-triggered compaction with\n * explicit cancellation and re-entrancy semantics, still built on the 2A.1\n * checkpoint primitives.\n *\n * The trigger is a declared policy (enabled flag + token threshold); a\n * disabled policy answers `disabled` explicitly. When the threshold is met\n * the executor stages a checkpoint, hands an AbortSignal to the plugin's\n * summarize callback, and commits — unless the signal fired first\n * (`cancelled`, staged entry dropped, no half commit). Re-entrant triggers\n * while a compaction is in flight are rejected as `busy`. Overflow recovery\n * and retry belong to 2A.3b/2A.4.\n */\nimport type { JsonValue } from \"@agent-forge/ai\";\nimport type { HostCheckpointCoordinatorV1 } from \"./checkpoint-commit.ts\";\n\nexport interface AutoCompactionPolicyV1 {\n\treadonly policyId: string;\n\t/** Compaction triggers only when currentTokens >= tokenThreshold. */\n\treadonly tokenThreshold: number;\n\treadonly enabled: boolean;\n}\n\nexport type AutoCompactionOutcomeV1 =\n\t| { readonly status: \"completed\"; readonly revision: number; readonly summary: JsonValue }\n\t| { readonly status: \"below_threshold\"; readonly currentTokens: number; readonly threshold: number }\n\t| { readonly status: \"cancelled\" }\n\t| { readonly status: \"summary_failed\"; readonly reason: string }\n\t| { readonly status: \"stale\"; readonly currentRevision: number }\n\t| { readonly status: \"busy\" }\n\t| { readonly status: \"disabled\" };\n\nexport interface AutoCompactionExecutorV1 {\n\tmaybeCompact(input: {\n\t\treadonly operationId: string;\n\t\treadonly currentTokens: number;\n\t\treadonly summarize: (signal: AbortSignal | undefined) => JsonValue;\n\t\treadonly signal?: AbortSignal;\n\t}): AutoCompactionOutcomeV1;\n\treadonly inProgress: boolean;\n}\n\nexport function createAutoCompactionExecutor(options: {\n\treadonly coordinator: HostCheckpointCoordinatorV1;\n\treadonly policy: AutoCompactionPolicyV1;\n}): AutoCompactionExecutorV1 {\n\tconst coordinator = options.coordinator;\n\tconst policy = options.policy;\n\tlet inProgress = false;\n\n\treturn {\n\t\tget inProgress() {\n\t\t\treturn inProgress;\n\t\t},\n\t\tmaybeCompact(input) {\n\t\t\tif (!policy.enabled) return { status: \"disabled\" };\n\t\t\tif (inProgress) return { status: \"busy\" };\n\t\t\tif (input.currentTokens < policy.tokenThreshold) {\n\t\t\t\treturn { status: \"below_threshold\", currentTokens: input.currentTokens, threshold: policy.tokenThreshold };\n\t\t\t}\n\t\t\tinProgress = true;\n\t\t\ttry {\n\t\t\t\tconst staged = coordinator.stage({\n\t\t\t\t\toperationId: input.operationId,\n\t\t\t\t\texpectedRevision: coordinator.currentRevision,\n\t\t\t\t\tpayload: null,\n\t\t\t\t});\n\t\t\t\tif (staged.status === \"stale\") return { status: \"stale\", currentRevision: staged.currentRevision };\n\t\t\t\tif (staged.status === \"duplicate\") return { status: \"cancelled\" };\n\t\t\t\tif (input.signal?.aborted) {\n\t\t\t\t\tcoordinator.cancelStage(staged.staged.token);\n\t\t\t\t\treturn { status: \"cancelled\" };\n\t\t\t\t}\n\t\t\t\tlet summary: JsonValue;\n\t\t\t\ttry {\n\t\t\t\t\tsummary = input.summarize(input.signal);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tcoordinator.cancelStage(staged.staged.token);\n\t\t\t\t\treturn { status: \"summary_failed\", reason: error instanceof Error ? error.message : String(error) };\n\t\t\t\t}\n\t\t\t\tif (input.signal?.aborted) {\n\t\t\t\t\tcoordinator.cancelStage(staged.staged.token);\n\t\t\t\t\treturn { status: \"cancelled\" };\n\t\t\t\t}\n\t\t\t\tconst outcome = coordinator.commitStage({\n\t\t\t\t\ttoken: staged.staged.token,\n\t\t\t\t\tapply: () => undefined,\n\t\t\t\t});\n\t\t\t\tif (outcome.status === \"stale\") return { status: \"stale\", currentRevision: outcome.currentRevision };\n\t\t\t\tif (outcome.status === \"committed\") {\n\t\t\t\t\treturn { status: \"completed\", revision: outcome.revision, summary };\n\t\t\t\t}\n\t\t\t\tcoordinator.cancelStage(staged.staged.token);\n\t\t\t\treturn { status: \"cancelled\" };\n\t\t\t} finally {\n\t\t\t\tinProgress = false;\n\t\t\t}\n\t\t},\n\t};\n}\n"]}

package/dist/host/branch-reload.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Branch state migration (2A.5a) and reload transaction (2A.5b).
+ *
+ * Branch migration copies state entries from one branch to another: the
+ * source entries stay in place (a migrated copy never overwrites or erases
+ * the old branch), and scanning a branch only ever sees that branch's own
+ * entries. The reload transaction is all-or-nothing: every item is
+ * validated FIRST — one validation failure rolls back the whole batch with
+ * structured failure evidence, and no commit callback ever runs. Empty
+ * migration sources are an explicit outcome, never a silent no-op success.
+ */
+export interface BranchStateEntryV1 {
+    readonly key: string;
+    readonly value: string;
+    readonly branch: string;
+}
+export type BranchMigrationOutcomeV1 = {
+    readonly status: "migrated";
+    readonly fromBranch: string;
+    readonly toBranch: string;
+    readonly migrated: readonly {
+        readonly key: string;
+        readonly value: string;
+    }[];
+} | {
+    readonly status: "empty_source";
+    readonly fromBranch: string;
+};
+export interface BranchStateMigrationV1 {
+    migrate(input: {
+        readonly entries: readonly BranchStateEntryV1[];
+        readonly fromBranch: string;
+        readonly toBranch: string;
+    }): BranchMigrationOutcomeV1;
+    scan(entries: readonly BranchStateEntryV1[], branch: string): readonly BranchStateEntryV1[];
+}
+export declare function createBranchStateMigration(): BranchStateMigrationV1;
+export interface ReloadTransactionItemV1 {
+    /** Returns null when valid, otherwise the raw validation failure. */
+    validate(): string | null;
+    commit(): void;
+}
+export interface ReloadTransactionV1 {
+    reload(items: readonly ReloadTransactionItemV1[]): {
+        readonly status: "committed";
+        readonly count: number;
+    } | {
+        readonly status: "rolled_back";
+        readonly failures: readonly {
+            readonly index: number;
+            readonly reason: string;
+        }[];
+    };
+}
+export declare function createReloadTransaction(): ReloadTransactionV1;
+//# sourceMappingURL=branch-reload.d.ts.map

package/dist/host/branch-reload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-reload.d.ts","sourceRoot":"","sources":["../../src/host/branch-reload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,wBAAwB,GACjC;IACA,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,SAAS;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC9E,GACD;IAAE,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE,MAAM,WAAW,sBAAsB;IACtC,OAAO,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;QAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;KAC1B,GAAG,wBAAwB,CAAC;IAC7B,IAAI,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,kBAAkB,EAAE,CAAC;CAC5F;AAED,wBAAgB,0BAA0B,IAAI,sBAAsB,CAkBnE;AAED,MAAM,WAAW,uBAAuB;IACvC,qEAAqE;IACrE,QAAQ,IAAI,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IACnC,MAAM,CAAC,KAAK,EAAE,SAAS,uBAAuB,EAAE,GAC7C;QAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GACxD;QACA,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;QAC/B,QAAQ,CAAC,QAAQ,EAAE,SAAS;YAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;KACjF,CAAC;CACL;AAED,wBAAgB,uBAAuB,IAAI,mBAAmB,CAgB7D","sourcesContent":["/**\n * Branch state migration (2A.5a) and reload transaction (2A.5b).\n *\n * Branch migration copies state entries from one branch to another: the\n * source entries stay in place (a migrated copy never overwrites or erases\n * the old branch), and scanning a branch only ever sees that branch's own\n * entries. The reload transaction is all-or-nothing: every item is\n * validated FIRST — one validation failure rolls back the whole batch with\n * structured failure evidence, and no commit callback ever runs. Empty\n * migration sources are an explicit outcome, never a silent no-op success.\n */\nexport interface BranchStateEntryV1 {\n\treadonly key: string;\n\treadonly value: string;\n\treadonly branch: string;\n}\n\nexport type BranchMigrationOutcomeV1 =\n\t| {\n\t\t\treadonly status: \"migrated\";\n\t\t\treadonly fromBranch: string;\n\t\t\treadonly toBranch: string;\n\t\t\treadonly migrated: readonly { readonly key: string; readonly value: string }[];\n\t  }\n\t| { readonly status: \"empty_source\"; readonly fromBranch: string };\n\nexport interface BranchStateMigrationV1 {\n\tmigrate(input: {\n\t\treadonly entries: readonly BranchStateEntryV1[];\n\t\treadonly fromBranch: string;\n\t\treadonly toBranch: string;\n\t}): BranchMigrationOutcomeV1;\n\tscan(entries: readonly BranchStateEntryV1[], branch: string): readonly BranchStateEntryV1[];\n}\n\nexport function createBranchStateMigration(): BranchStateMigrationV1 {\n\treturn {\n\t\tmigrate({ entries, fromBranch, toBranch }) {\n\t\t\tconst source = entries.filter((entry) => entry.branch === fromBranch);\n\t\t\tif (source.length === 0) {\n\t\t\t\treturn { status: \"empty_source\", fromBranch };\n\t\t\t}\n\t\t\treturn {\n\t\t\t\tstatus: \"migrated\",\n\t\t\t\tfromBranch,\n\t\t\t\ttoBranch,\n\t\t\t\tmigrated: Object.freeze(source.map((entry) => ({ key: entry.key, value: entry.value }))),\n\t\t\t};\n\t\t},\n\t\tscan(entries, branch) {\n\t\t\treturn Object.freeze(entries.filter((entry) => entry.branch === branch));\n\t\t},\n\t};\n}\n\nexport interface ReloadTransactionItemV1 {\n\t/** Returns null when valid, otherwise the raw validation failure. */\n\tvalidate(): string | null;\n\tcommit(): void;\n}\n\nexport interface ReloadTransactionV1 {\n\treload(items: readonly ReloadTransactionItemV1[]):\n\t\t| { readonly status: \"committed\"; readonly count: number }\n\t\t| {\n\t\t\t\treadonly status: \"rolled_back\";\n\t\t\t\treadonly failures: readonly { readonly index: number; readonly reason: string }[];\n\t\t  };\n}\n\nexport function createReloadTransaction(): ReloadTransactionV1 {\n\treturn {\n\t\treload(items) {\n\t\t\t// Validate EVERY item before committing ANY item.\n\t\t\tconst failures: Array<{ index: number; reason: string }> = [];\n\t\t\tfor (const [index, item] of items.entries()) {\n\t\t\t\tconst failure = item.validate();\n\t\t\t\tif (failure !== null) failures.push({ index, reason: failure });\n\t\t\t}\n\t\t\tif (failures.length > 0) {\n\t\t\t\treturn { status: \"rolled_back\", failures: Object.freeze(failures) };\n\t\t\t}\n\t\t\tfor (const item of items) item.commit();\n\t\t\treturn { status: \"committed\", count: items.length };\n\t\t},\n\t};\n}\n"]}

package/dist/host/branch-reload.js

@@ -0,0 +1,39 @@
+export function createBranchStateMigration() {
+    return {
+        migrate({ entries, fromBranch, toBranch }) {
+            const source = entries.filter((entry) => entry.branch === fromBranch);
+            if (source.length === 0) {
+                return { status: "empty_source", fromBranch };
+            }
+            return {
+                status: "migrated",
+                fromBranch,
+                toBranch,
+                migrated: Object.freeze(source.map((entry) => ({ key: entry.key, value: entry.value }))),
+            };
+        },
+        scan(entries, branch) {
+            return Object.freeze(entries.filter((entry) => entry.branch === branch));
+        },
+    };
+}
+export function createReloadTransaction() {
+    return {
+        reload(items) {
+            // Validate EVERY item before committing ANY item.
+            const failures = [];
+            for (const [index, item] of items.entries()) {
+                const failure = item.validate();
+                if (failure !== null)
+                    failures.push({ index, reason: failure });
+            }
+            if (failures.length > 0) {
+                return { status: "rolled_back", failures: Object.freeze(failures) };
+            }
+            for (const item of items)
+                item.commit();
+            return { status: "committed", count: items.length };
+        },
+    };
+}
+//# sourceMappingURL=branch-reload.js.map

package/dist/host/branch-reload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-reload.js","sourceRoot":"","sources":["../../src/host/branch-reload.ts"],"names":[],"mappings":"AAmCA,MAAM,UAAU,0BAA0B,GAA2B;IACpE,OAAO;QACN,OAAO,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,EAAE;YAC1C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC;YACtE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACzB,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,CAAC;YAC/C,CAAC;YACD,OAAO;gBACN,MAAM,EAAE,UAAU;gBAClB,UAAU;gBACV,QAAQ;gBACR,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;aACxF,CAAC;QAAA,CACF;QACD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE;YACrB,OAAO,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC;QAAA,CACzE;KACD,CAAC;AAAA,CACF;AAiBD,MAAM,UAAU,uBAAuB,GAAwB;IAC9D,OAAO;QACN,MAAM,CAAC,KAAK,EAAE;YACb,kDAAkD;YAClD,MAAM,QAAQ,GAA6C,EAAE,CAAC;YAC9D,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;gBAC7C,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAChC,IAAI,OAAO,KAAK,IAAI;oBAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;YACjE,CAAC;YACD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACzB,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;YACrE,CAAC;YACD,KAAK,MAAM,IAAI,IAAI,KAAK;gBAAE,IAAI,CAAC,MAAM,EAAE,CAAC;YACxC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;QAAA,CACpD;KACD,CAAC;AAAA,CACF","sourcesContent":["/**\n * Branch state migration (2A.5a) and reload transaction (2A.5b).\n *\n * Branch migration copies state entries from one branch to another: the\n * source entries stay in place (a migrated copy never overwrites or erases\n * the old branch), and scanning a branch only ever sees that branch's own\n * entries. The reload transaction is all-or-nothing: every item is\n * validated FIRST — one validation failure rolls back the whole batch with\n * structured failure evidence, and no commit callback ever runs. Empty\n * migration sources are an explicit outcome, never a silent no-op success.\n */\nexport interface BranchStateEntryV1 {\n\treadonly key: string;\n\treadonly value: string;\n\treadonly branch: string;\n}\n\nexport type BranchMigrationOutcomeV1 =\n\t| {\n\t\t\treadonly status: \"migrated\";\n\t\t\treadonly fromBranch: string;\n\t\t\treadonly toBranch: string;\n\t\t\treadonly migrated: readonly { readonly key: string; readonly value: string }[];\n\t  }\n\t| { readonly status: \"empty_source\"; readonly fromBranch: string };\n\nexport interface BranchStateMigrationV1 {\n\tmigrate(input: {\n\t\treadonly entries: readonly BranchStateEntryV1[];\n\t\treadonly fromBranch: string;\n\t\treadonly toBranch: string;\n\t}): BranchMigrationOutcomeV1;\n\tscan(entries: readonly BranchStateEntryV1[], branch: string): readonly BranchStateEntryV1[];\n}\n\nexport function createBranchStateMigration(): BranchStateMigrationV1 {\n\treturn {\n\t\tmigrate({ entries, fromBranch, toBranch }) {\n\t\t\tconst source = entries.filter((entry) => entry.branch === fromBranch);\n\t\t\tif (source.length === 0) {\n\t\t\t\treturn { status: \"empty_source\", fromBranch };\n\t\t\t}\n\t\t\treturn {\n\t\t\t\tstatus: \"migrated\",\n\t\t\t\tfromBranch,\n\t\t\t\ttoBranch,\n\t\t\t\tmigrated: Object.freeze(source.map((entry) => ({ key: entry.key, value: entry.value }))),\n\t\t\t};\n\t\t},\n\t\tscan(entries, branch) {\n\t\t\treturn Object.freeze(entries.filter((entry) => entry.branch === branch));\n\t\t},\n\t};\n}\n\nexport interface ReloadTransactionItemV1 {\n\t/** Returns null when valid, otherwise the raw validation failure. */\n\tvalidate(): string | null;\n\tcommit(): void;\n}\n\nexport interface ReloadTransactionV1 {\n\treload(items: readonly ReloadTransactionItemV1[]):\n\t\t| { readonly status: \"committed\"; readonly count: number }\n\t\t| {\n\t\t\t\treadonly status: \"rolled_back\";\n\t\t\t\treadonly failures: readonly { readonly index: number; readonly reason: string }[];\n\t\t  };\n}\n\nexport function createReloadTransaction(): ReloadTransactionV1 {\n\treturn {\n\t\treload(items) {\n\t\t\t// Validate EVERY item before committing ANY item.\n\t\t\tconst failures: Array<{ index: number; reason: string }> = [];\n\t\t\tfor (const [index, item] of items.entries()) {\n\t\t\t\tconst failure = item.validate();\n\t\t\t\tif (failure !== null) failures.push({ index, reason: failure });\n\t\t\t}\n\t\t\tif (failures.length > 0) {\n\t\t\t\treturn { status: \"rolled_back\", failures: Object.freeze(failures) };\n\t\t\t}\n\t\t\tfor (const item of items) item.commit();\n\t\t\treturn { status: \"committed\", count: items.length };\n\t\t},\n\t};\n}\n"]}

package/dist/host/channel-adapter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * stdio/stderr channel adapter (3.5b) — routes projected host output records
+ * (2.6b) into print and JSON channel semantics.
+ *
+ * print mode: stdout carries ONLY the model's answer text (message records);
+ * tool activity, diagnostics, and lifecycle phases go to stderr. JSON mode:
+ * stdout carries every record as one stable JSON line per record (machine
+ * and RPC consumers — identical input yields identical bytes, with traceId
+ * and correlationId preserved), while stderr still mirrors diagnostics for
+ * humans. No web viewer here.
+ */
+import type { HostOutputRecordV1 } from "./output-projection.ts";
+export type ChannelFormatV1 = "print" | "json";
+export interface ChannelAdapterV1 {
+    ingest(records: readonly HostOutputRecordV1[]): {
+        readonly stdoutLines: number;
+        readonly stderrLines: number;
+    };
+}
+export declare function createStdioChannelAdapter(options: {
+    readonly format: ChannelFormatV1;
+    readonly writeStdout: (text: string) => void;
+    readonly writeStderr: (text: string) => void;
+}): ChannelAdapterV1;
+//# sourceMappingURL=channel-adapter.d.ts.map

package/dist/host/channel-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-adapter.d.ts","sourceRoot":"","sources":["../../src/host/channel-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,MAAM,CAAC;AAE/C,MAAM,WAAW,gBAAgB;IAChC,MAAM,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,GAAG;QAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/G;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE;IAClD,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7C,GAAG,gBAAgB,CA6BnB","sourcesContent":["/**\n * stdio/stderr channel adapter (3.5b) — routes projected host output records\n * (2.6b) into print and JSON channel semantics.\n *\n * print mode: stdout carries ONLY the model's answer text (message records);\n * tool activity, diagnostics, and lifecycle phases go to stderr. JSON mode:\n * stdout carries every record as one stable JSON line per record (machine\n * and RPC consumers — identical input yields identical bytes, with traceId\n * and correlationId preserved), while stderr still mirrors diagnostics for\n * humans. No web viewer here.\n */\nimport type { HostOutputRecordV1 } from \"./output-projection.ts\";\n\nexport type ChannelFormatV1 = \"print\" | \"json\";\n\nexport interface ChannelAdapterV1 {\n\tingest(records: readonly HostOutputRecordV1[]): { readonly stdoutLines: number; readonly stderrLines: number };\n}\n\nexport function createStdioChannelAdapter(options: {\n\treadonly format: ChannelFormatV1;\n\treadonly writeStdout: (text: string) => void;\n\treadonly writeStderr: (text: string) => void;\n}): ChannelAdapterV1 {\n\tconst { format, writeStdout, writeStderr } = options;\n\n\treturn {\n\t\tingest(records) {\n\t\t\tlet stdoutLines = 0;\n\t\t\tlet stderrLines = 0;\n\t\t\tfor (const record of records) {\n\t\t\t\tif (format === \"print\") {\n\t\t\t\t\tif (record.channel === \"message\") {\n\t\t\t\t\t\twriteStdout(record.summary);\n\t\t\t\t\t\tstdoutLines += 1;\n\t\t\t\t\t\tcontinue;\n\t\t\t\t\t}\n\t\t\t\t\twriteStderr(formatStderrLine(record));\n\t\t\t\t\tstderrLines += 1;\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\t// JSON mode: stable serialization on stdout for machine/RPC consumers.\n\t\t\t\twriteStdout(JSON.stringify(record));\n\t\t\t\tstdoutLines += 1;\n\t\t\t\tif (record.channel === \"diagnostic\") {\n\t\t\t\t\twriteStderr(formatStderrLine(record));\n\t\t\t\t\tstderrLines += 1;\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn { stdoutLines, stderrLines };\n\t\t},\n\t};\n}\n\nfunction formatStderrLine(record: HostOutputRecordV1): string {\n\tconst parts = [`[${record.channel}/${record.severity}]`];\n\tif (record.traceId) parts.push(`trace=${record.traceId}`);\n\tif (record.correlationId !== undefined) parts.push(`call=${record.correlationId}`);\n\tif (record.code !== undefined) {\n\t\tconst label = record.channel === \"tool\" ? \"tool\" : \"code\";\n\t\tparts.push(`${label}=${record.code}: ${record.summary}`);\n\t} else {\n\t\tparts.push(record.summary);\n\t}\n\treturn parts.join(\" \");\n}\n"]}

package/dist/host/channel-adapter.js

@@ -0,0 +1,45 @@
+export function createStdioChannelAdapter(options) {
+    const { format, writeStdout, writeStderr } = options;
+    return {
+        ingest(records) {
+            let stdoutLines = 0;
+            let stderrLines = 0;
+            for (const record of records) {
+                if (format === "print") {
+                    if (record.channel === "message") {
+                        writeStdout(record.summary);
+                        stdoutLines += 1;
+                        continue;
+                    }
+                    writeStderr(formatStderrLine(record));
+                    stderrLines += 1;
+                    continue;
+                }
+                // JSON mode: stable serialization on stdout for machine/RPC consumers.
+                writeStdout(JSON.stringify(record));
+                stdoutLines += 1;
+                if (record.channel === "diagnostic") {
+                    writeStderr(formatStderrLine(record));
+                    stderrLines += 1;
+                }
+            }
+            return { stdoutLines, stderrLines };
+        },
+    };
+}
+function formatStderrLine(record) {
+    const parts = [`[${record.channel}/${record.severity}]`];
+    if (record.traceId)
+        parts.push(`trace=${record.traceId}`);
+    if (record.correlationId !== undefined)
+        parts.push(`call=${record.correlationId}`);
+    if (record.code !== undefined) {
+        const label = record.channel === "tool" ? "tool" : "code";
+        parts.push(`${label}=${record.code}: ${record.summary}`);
+    }
+    else {
+        parts.push(record.summary);
+    }
+    return parts.join(" ");
+}
+//# sourceMappingURL=channel-adapter.js.map

package/dist/host/channel-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-adapter.js","sourceRoot":"","sources":["../../src/host/channel-adapter.ts"],"names":[],"mappings":"AAmBA,MAAM,UAAU,yBAAyB,CAAC,OAIzC,EAAoB;IACpB,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC;IAErD,OAAO;QACN,MAAM,CAAC,OAAO,EAAE;YACf,IAAI,WAAW,GAAG,CAAC,CAAC;YACpB,IAAI,WAAW,GAAG,CAAC,CAAC;YACpB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC9B,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;oBACxB,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;wBAClC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;wBAC5B,WAAW,IAAI,CAAC,CAAC;wBACjB,SAAS;oBACV,CAAC;oBACD,WAAW,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC;oBACtC,WAAW,IAAI,CAAC,CAAC;oBACjB,SAAS;gBACV,CAAC;gBACD,uEAAuE;gBACvE,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;gBACpC,WAAW,IAAI,CAAC,CAAC;gBACjB,IAAI,MAAM,CAAC,OAAO,KAAK,YAAY,EAAE,CAAC;oBACrC,WAAW,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC;oBACtC,WAAW,IAAI,CAAC,CAAC;gBAClB,CAAC;YACF,CAAC;YACD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC;QAAA,CACpC;KACD,CAAC;AAAA,CACF;AAED,SAAS,gBAAgB,CAAC,MAA0B,EAAU;IAC7D,MAAM,KAAK,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,QAAQ,GAAG,CAAC,CAAC;IACzD,IAAI,MAAM,CAAC,OAAO;QAAE,KAAK,CAAC,IAAI,CAAC,SAAS,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IAC1D,IAAI,MAAM,CAAC,aAAa,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,MAAM,CAAC,aAAa,EAAE,CAAC,CAAC;IACnF,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;QAC1D,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IAC1D,CAAC;SAAM,CAAC;QACP,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAAA,CACvB","sourcesContent":["/**\n * stdio/stderr channel adapter (3.5b) — routes projected host output records\n * (2.6b) into print and JSON channel semantics.\n *\n * print mode: stdout carries ONLY the model's answer text (message records);\n * tool activity, diagnostics, and lifecycle phases go to stderr. JSON mode:\n * stdout carries every record as one stable JSON line per record (machine\n * and RPC consumers — identical input yields identical bytes, with traceId\n * and correlationId preserved), while stderr still mirrors diagnostics for\n * humans. No web viewer here.\n */\nimport type { HostOutputRecordV1 } from \"./output-projection.ts\";\n\nexport type ChannelFormatV1 = \"print\" | \"json\";\n\nexport interface ChannelAdapterV1 {\n\tingest(records: readonly HostOutputRecordV1[]): { readonly stdoutLines: number; readonly stderrLines: number };\n}\n\nexport function createStdioChannelAdapter(options: {\n\treadonly format: ChannelFormatV1;\n\treadonly writeStdout: (text: string) => void;\n\treadonly writeStderr: (text: string) => void;\n}): ChannelAdapterV1 {\n\tconst { format, writeStdout, writeStderr } = options;\n\n\treturn {\n\t\tingest(records) {\n\t\t\tlet stdoutLines = 0;\n\t\t\tlet stderrLines = 0;\n\t\t\tfor (const record of records) {\n\t\t\t\tif (format === \"print\") {\n\t\t\t\t\tif (record.channel === \"message\") {\n\t\t\t\t\t\twriteStdout(record.summary);\n\t\t\t\t\t\tstdoutLines += 1;\n\t\t\t\t\t\tcontinue;\n\t\t\t\t\t}\n\t\t\t\t\twriteStderr(formatStderrLine(record));\n\t\t\t\t\tstderrLines += 1;\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\t// JSON mode: stable serialization on stdout for machine/RPC consumers.\n\t\t\t\twriteStdout(JSON.stringify(record));\n\t\t\t\tstdoutLines += 1;\n\t\t\t\tif (record.channel === \"diagnostic\") {\n\t\t\t\t\twriteStderr(formatStderrLine(record));\n\t\t\t\t\tstderrLines += 1;\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn { stdoutLines, stderrLines };\n\t\t},\n\t};\n}\n\nfunction formatStderrLine(record: HostOutputRecordV1): string {\n\tconst parts = [`[${record.channel}/${record.severity}]`];\n\tif (record.traceId) parts.push(`trace=${record.traceId}`);\n\tif (record.correlationId !== undefined) parts.push(`call=${record.correlationId}`);\n\tif (record.code !== undefined) {\n\t\tconst label = record.channel === \"tool\" ? \"tool\" : \"code\";\n\t\tparts.push(`${label}=${record.code}: ${record.summary}`);\n\t} else {\n\t\tparts.push(record.summary);\n\t}\n\treturn parts.join(\" \");\n}\n"]}

package/dist/host/checkpoint-commit.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Host checkpoint/commit (2A.1) — the revision-guarded, idempotent,
+ * two-phase write primitive the execution loop uses to persist session
+ * context.
+ *
+ * Phase 1 (`stage`): the writer declares an operation against an expected
+ * revision. Stale expectations are rejected with the current revision.
+ * Phase 2 (`commitStage`): the payload is applied exactly once through the
+ * caller's apply callback ONLY if the revision still matches; the revision
+ * advances strictly after a successful apply.
+ *
+ * No path ever leaves a half commit: stale → revision untouched; duplicate
+ * operationId → the first committed result is returned verbatim (never
+ * re-applied); write failure → staged entry dropped, revision untouched;
+ * cancellation → the staged entry is cancelled and can never commit.
+ * Everything is deterministic and replayable. Summary policies, auto
+ * compaction, retry, and branch migration are later 2A slices.
+ */
+import type { JsonValue } from "@agent-forge/ai";
+export interface HostStagedWriteV1 {
+    readonly token: string;
+    readonly operationId: string;
+    readonly expectedRevision: number;
+    readonly currentRevision: number;
+}
+export type HostStageResultV1 = {
+    readonly status: "staged";
+    readonly staged: HostStagedWriteV1;
+} | {
+    readonly status: "stale";
+    readonly currentRevision: number;
+}
+/** The operationId already committed; the first result is echoed, never re-applied. */
+ | {
+    readonly status: "duplicate";
+    readonly revision: number;
+};
+export type HostCommitOutcomeV1 = {
+    readonly status: "committed";
+    readonly revision: number;
+} | {
+    readonly status: "stale";
+    readonly currentRevision: number;
+} | {
+    readonly status: "write_failed";
+    readonly reason: string;
+} | {
+    readonly status: "cancelled";
+} | {
+    readonly status: "unknown_token";
+} | {
+    readonly status: "duplicate";
+    readonly revision: number;
+};
+export interface HostCheckpointCoordinatorV1 {
+    stage(input: {
+        readonly operationId: string;
+        readonly expectedRevision: number;
+        readonly payload: JsonValue;
+    }): HostStageResultV1;
+    commitStage(input: {
+        readonly token: string;
+        readonly apply: (payload: JsonValue, revision: number) => void;
+    }): HostCommitOutcomeV1;
+    cancelStage(token: string): {
+        readonly status: "cancelled" | "unknown_token" | "already_committed";
+    };
+    readonly currentRevision: number;
+    committedOperationIds(): readonly string[];
+}
+export declare function createHostCheckpointCoordinator(options?: {
+    readonly startRevision?: number;
+}): HostCheckpointCoordinatorV1;
+//# sourceMappingURL=checkpoint-commit.d.ts.map

package/dist/host/checkpoint-commit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-commit.d.ts","sourceRoot":"","sources":["../../src/host/checkpoint-commit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,iBAAiB,GAC1B;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;CAAE,GACjE;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CAAE;AAChE,uFAAuF;GACrF;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D,MAAM,MAAM,mBAAmB,GAC5B;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CAAE,GAC9D;IAAE,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAChC;IAAE,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GACpC;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D,MAAM,WAAW,2BAA2B;IAC3C,KAAK,CAAC,KAAK,EAAE;QACZ,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;QAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;KAC5B,GAAG,iBAAiB,CAAC;IACtB,WAAW,CAAC,KAAK,EAAE;QAClB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;KAC/D,GAAG,mBAAmB,CAAC;IACxB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG;QAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,eAAe,GAAG,mBAAmB,CAAA;KAAE,CAAC;IACrG,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,qBAAqB,IAAI,SAAS,MAAM,EAAE,CAAC;CAC3C;AASD,wBAAgB,+BAA+B,CAC9C,OAAO,GAAE;IAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/C,2BAA2B,CAsE7B","sourcesContent":["/**\n * Host checkpoint/commit (2A.1) — the revision-guarded, idempotent,\n * two-phase write primitive the execution loop uses to persist session\n * context.\n *\n * Phase 1 (`stage`): the writer declares an operation against an expected\n * revision. Stale expectations are rejected with the current revision.\n * Phase 2 (`commitStage`): the payload is applied exactly once through the\n * caller's apply callback ONLY if the revision still matches; the revision\n * advances strictly after a successful apply.\n *\n * No path ever leaves a half commit: stale → revision untouched; duplicate\n * operationId → the first committed result is returned verbatim (never\n * re-applied); write failure → staged entry dropped, revision untouched;\n * cancellation → the staged entry is cancelled and can never commit.\n * Everything is deterministic and replayable. Summary policies, auto\n * compaction, retry, and branch migration are later 2A slices.\n */\nimport type { JsonValue } from \"@agent-forge/ai\";\n\nexport interface HostStagedWriteV1 {\n\treadonly token: string;\n\treadonly operationId: string;\n\treadonly expectedRevision: number;\n\treadonly currentRevision: number;\n}\n\nexport type HostStageResultV1 =\n\t| { readonly status: \"staged\"; readonly staged: HostStagedWriteV1 }\n\t| { readonly status: \"stale\"; readonly currentRevision: number }\n\t/** The operationId already committed; the first result is echoed, never re-applied. */\n\t| { readonly status: \"duplicate\"; readonly revision: number };\n\nexport type HostCommitOutcomeV1 =\n\t| { readonly status: \"committed\"; readonly revision: number }\n\t| { readonly status: \"stale\"; readonly currentRevision: number }\n\t| { readonly status: \"write_failed\"; readonly reason: string }\n\t| { readonly status: \"cancelled\" }\n\t| { readonly status: \"unknown_token\" }\n\t| { readonly status: \"duplicate\"; readonly revision: number };\n\nexport interface HostCheckpointCoordinatorV1 {\n\tstage(input: {\n\t\treadonly operationId: string;\n\t\treadonly expectedRevision: number;\n\t\treadonly payload: JsonValue;\n\t}): HostStageResultV1;\n\tcommitStage(input: {\n\t\treadonly token: string;\n\t\treadonly apply: (payload: JsonValue, revision: number) => void;\n\t}): HostCommitOutcomeV1;\n\tcancelStage(token: string): { readonly status: \"cancelled\" | \"unknown_token\" | \"already_committed\" };\n\treadonly currentRevision: number;\n\tcommittedOperationIds(): readonly string[];\n}\n\ninterface StagedEntry {\n\toperationId: string;\n\texpectedRevision: number;\n\tpayload: JsonValue;\n\tstate: \"staged\" | \"cancelled\";\n}\n\nexport function createHostCheckpointCoordinator(\n\toptions: { readonly startRevision?: number } = {},\n): HostCheckpointCoordinatorV1 {\n\tlet revision = options.startRevision ?? 0;\n\tconst staged = new Map<string, StagedEntry>();\n\tconst committed = new Map<string, number>();\n\tlet tokenSequence = 0;\n\n\treturn {\n\t\tget currentRevision() {\n\t\t\treturn revision;\n\t\t},\n\t\tstage(input) {\n\t\t\tif (typeof input.operationId !== \"string\" || input.operationId.trim().length === 0) {\n\t\t\t\tthrow new Error(\"Checkpoint operationId must be a non-empty string\");\n\t\t\t}\n\t\t\tconst appliedRevision = committed.get(input.operationId);\n\t\t\tif (appliedRevision !== undefined) {\n\t\t\t\treturn { status: \"duplicate\", revision: appliedRevision };\n\t\t\t}\n\t\t\tif (input.expectedRevision !== revision) {\n\t\t\t\treturn { status: \"stale\", currentRevision: revision };\n\t\t\t}\n\t\t\ttokenSequence += 1;\n\t\t\tconst token = `ckpt-${tokenSequence}`;\n\t\t\tconst entry: StagedEntry = {\n\t\t\t\toperationId: input.operationId,\n\t\t\t\texpectedRevision: input.expectedRevision,\n\t\t\t\tpayload: input.payload,\n\t\t\t\tstate: \"staged\",\n\t\t\t};\n\t\t\tstaged.set(token, entry);\n\t\t\treturn {\n\t\t\t\tstatus: \"staged\",\n\t\t\t\tstaged: {\n\t\t\t\t\ttoken,\n\t\t\t\t\toperationId: input.operationId,\n\t\t\t\t\texpectedRevision: input.expectedRevision,\n\t\t\t\t\tcurrentRevision: revision,\n\t\t\t\t},\n\t\t\t};\n\t\t},\n\t\tcommitStage({ token, apply }) {\n\t\t\tconst entry = staged.get(token);\n\t\t\tif (!entry) return { status: \"unknown_token\" };\n\t\t\tif (entry.state === \"cancelled\") return { status: \"cancelled\" };\n\t\t\tif (entry.expectedRevision !== revision) {\n\t\t\t\tstaged.delete(token);\n\t\t\t\treturn { status: \"stale\", currentRevision: revision };\n\t\t\t}\n\t\t\ttry {\n\t\t\t\tapply(entry.payload, revision + 1);\n\t\t\t} catch (error) {\n\t\t\t\tstaged.delete(token);\n\t\t\t\treturn { status: \"write_failed\", reason: error instanceof Error ? error.message : String(error) };\n\t\t\t}\n\t\t\trevision += 1;\n\t\t\tcommitted.set(entry.operationId, revision);\n\t\t\tstaged.delete(token);\n\t\t\treturn { status: \"committed\", revision };\n\t\t},\n\t\tcancelStage(token) {\n\t\t\tconst entry = staged.get(token);\n\t\t\tif (!entry) return { status: \"unknown_token\" };\n\t\t\tif (committed.has(entry.operationId)) return { status: \"already_committed\" };\n\t\t\tentry.state = \"cancelled\";\n\t\t\treturn { status: \"cancelled\" };\n\t\t},\n\t\tcommittedOperationIds() {\n\t\t\treturn Object.freeze([...committed.keys()].sort());\n\t\t},\n\t};\n}\n"]}

package/dist/host/checkpoint-commit.js

@@ -0,0 +1,76 @@
+export function createHostCheckpointCoordinator(options = {}) {
+    let revision = options.startRevision ?? 0;
+    const staged = new Map();
+    const committed = new Map();
+    let tokenSequence = 0;
+    return {
+        get currentRevision() {
+            return revision;
+        },
+        stage(input) {
+            if (typeof input.operationId !== "string" || input.operationId.trim().length === 0) {
+                throw new Error("Checkpoint operationId must be a non-empty string");
+            }
+            const appliedRevision = committed.get(input.operationId);
+            if (appliedRevision !== undefined) {
+                return { status: "duplicate", revision: appliedRevision };
+            }
+            if (input.expectedRevision !== revision) {
+                return { status: "stale", currentRevision: revision };
+            }
+            tokenSequence += 1;
+            const token = `ckpt-${tokenSequence}`;
+            const entry = {
+                operationId: input.operationId,
+                expectedRevision: input.expectedRevision,
+                payload: input.payload,
+                state: "staged",
+            };
+            staged.set(token, entry);
+            return {
+                status: "staged",
+                staged: {
+                    token,
+                    operationId: input.operationId,
+                    expectedRevision: input.expectedRevision,
+                    currentRevision: revision,
+                },
+            };
+        },
+        commitStage({ token, apply }) {
+            const entry = staged.get(token);
+            if (!entry)
+                return { status: "unknown_token" };
+            if (entry.state === "cancelled")
+                return { status: "cancelled" };
+            if (entry.expectedRevision !== revision) {
+                staged.delete(token);
+                return { status: "stale", currentRevision: revision };
+            }
+            try {
+                apply(entry.payload, revision + 1);
+            }
+            catch (error) {
+                staged.delete(token);
+                return { status: "write_failed", reason: error instanceof Error ? error.message : String(error) };
+            }
+            revision += 1;
+            committed.set(entry.operationId, revision);
+            staged.delete(token);
+            return { status: "committed", revision };
+        },
+        cancelStage(token) {
+            const entry = staged.get(token);
+            if (!entry)
+                return { status: "unknown_token" };
+            if (committed.has(entry.operationId))
+                return { status: "already_committed" };
+            entry.state = "cancelled";
+            return { status: "cancelled" };
+        },
+        committedOperationIds() {
+            return Object.freeze([...committed.keys()].sort());
+        },
+    };
+}
+//# sourceMappingURL=checkpoint-commit.js.map

package/dist/host/checkpoint-commit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-commit.js","sourceRoot":"","sources":["../../src/host/checkpoint-commit.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Host checkpoint/commit (2A.1) — the revision-guarded, idempotent,\n * two-phase write primitive the execution loop uses to persist session\n * context.\n *\n * Phase 1 (`stage`): the writer declares an operation against an expected\n * revision. Stale expectations are rejected with the current revision.\n * Phase 2 (`commitStage`): the payload is applied exactly once through the\n * caller's apply callback ONLY if the revision still matches; the revision\n * advances strictly after a successful apply.\n *\n * No path ever leaves a half commit: stale → revision untouched; duplicate\n * operationId → the first committed result is returned verbatim (never\n * re-applied); write failure → staged entry dropped, revision untouched;\n * cancellation → the staged entry is cancelled and can never commit.\n * Everything is deterministic and replayable. Summary policies, auto\n * compaction, retry, and branch migration are later 2A slices.\n */\nimport type { JsonValue } from \"@agent-forge/ai\";\n\nexport interface HostStagedWriteV1 {\n\treadonly token: string;\n\treadonly operationId: string;\n\treadonly expectedRevision: number;\n\treadonly currentRevision: number;\n}\n\nexport type HostStageResultV1 =\n\t| { readonly status: \"staged\"; readonly staged: HostStagedWriteV1 }\n\t| { readonly status: \"stale\"; readonly currentRevision: number }\n\t/** The operationId already committed; the first result is echoed, never re-applied. */\n\t| { readonly status: \"duplicate\"; readonly revision: number };\n\nexport type HostCommitOutcomeV1 =\n\t| { readonly status: \"committed\"; readonly revision: number }\n\t| { readonly status: \"stale\"; readonly currentRevision: number }\n\t| { readonly status: \"write_failed\"; readonly reason: string }\n\t| { readonly status: \"cancelled\" }\n\t| { readonly status: \"unknown_token\" }\n\t| { readonly status: \"duplicate\"; readonly revision: number };\n\nexport interface HostCheckpointCoordinatorV1 {\n\tstage(input: {\n\t\treadonly operationId: string;\n\t\treadonly expectedRevision: number;\n\t\treadonly payload: JsonValue;\n\t}): HostStageResultV1;\n\tcommitStage(input: {\n\t\treadonly token: string;\n\t\treadonly apply: (payload: JsonValue, revision: number) => void;\n\t}): HostCommitOutcomeV1;\n\tcancelStage(token: string): { readonly status: \"cancelled\" | \"unknown_token\" | \"already_committed\" };\n\treadonly currentRevision: number;\n\tcommittedOperationIds(): readonly string[];\n}\n\ninterface StagedEntry {\n\toperationId: string;\n\texpectedRevision: number;\n\tpayload: JsonValue;\n\tstate: \"staged\" | \"cancelled\";\n}\n\nexport function createHostCheckpointCoordinator(\n\toptions: { readonly startRevision?: number } = {},\n): HostCheckpointCoordinatorV1 {\n\tlet revision = options.startRevision ?? 0;\n\tconst staged = new Map<string, StagedEntry>();\n\tconst committed = new Map<string, number>();\n\tlet tokenSequence = 0;\n\n\treturn {\n\t\tget currentRevision() {\n\t\t\treturn revision;\n\t\t},\n\t\tstage(input) {\n\t\t\tif (typeof input.operationId !== \"string\" || input.operationId.trim().length === 0) {\n\t\t\t\tthrow new Error(\"Checkpoint operationId must be a non-empty string\");\n\t\t\t}\n\t\t\tconst appliedRevision = committed.get(input.operationId);\n\t\t\tif (appliedRevision !== undefined) {\n\t\t\t\treturn { status: \"duplicate\", revision: appliedRevision };\n\t\t\t}\n\t\t\tif (input.expectedRevision !== revision) {\n\t\t\t\treturn { status: \"stale\", currentRevision: revision };\n\t\t\t}\n\t\t\ttokenSequence += 1;\n\t\t\tconst token = `ckpt-${tokenSequence}`;\n\t\t\tconst entry: StagedEntry = {\n\t\t\t\toperationId: input.operationId,\n\t\t\t\texpectedRevision: input.expectedRevision,\n\t\t\t\tpayload: input.payload,\n\t\t\t\tstate: \"staged\",\n\t\t\t};\n\t\t\tstaged.set(token, entry);\n\t\t\treturn {\n\t\t\t\tstatus: \"staged\",\n\t\t\t\tstaged: {\n\t\t\t\t\ttoken,\n\t\t\t\t\toperationId: input.operationId,\n\t\t\t\t\texpectedRevision: input.expectedRevision,\n\t\t\t\t\tcurrentRevision: revision,\n\t\t\t\t},\n\t\t\t};\n\t\t},\n\t\tcommitStage({ token, apply }) {\n\t\t\tconst entry = staged.get(token);\n\t\t\tif (!entry) return { status: \"unknown_token\" };\n\t\t\tif (entry.state === \"cancelled\") return { status: \"cancelled\" };\n\t\t\tif (entry.expectedRevision !== revision) {\n\t\t\t\tstaged.delete(token);\n\t\t\t\treturn { status: \"stale\", currentRevision: revision };\n\t\t\t}\n\t\t\ttry {\n\t\t\t\tapply(entry.payload, revision + 1);\n\t\t\t} catch (error) {\n\t\t\t\tstaged.delete(token);\n\t\t\t\treturn { status: \"write_failed\", reason: error instanceof Error ? error.message : String(error) };\n\t\t\t}\n\t\t\trevision += 1;\n\t\t\tcommitted.set(entry.operationId, revision);\n\t\t\tstaged.delete(token);\n\t\t\treturn { status: \"committed\", revision };\n\t\t},\n\t\tcancelStage(token) {\n\t\t\tconst entry = staged.get(token);\n\t\t\tif (!entry) return { status: \"unknown_token\" };\n\t\t\tif (committed.has(entry.operationId)) return { status: \"already_committed\" };\n\t\t\tentry.state = \"cancelled\";\n\t\t\treturn { status: \"cancelled\" };\n\t\t},\n\t\tcommittedOperationIds() {\n\t\t\treturn Object.freeze([...committed.keys()].sort());\n\t\t},\n\t};\n}\n"]}

package/dist/host/manual-compaction.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Manual compaction executor (2A.2) — the host primitive that lets a PLUGIN
+ * decide when compaction happens and what the summary contains, while the
+ * kernel side only provides the model/session/commit primitives (here: the
+ * 2A.1 checkpoint coordinator).
+ *
+ * The executor owns no summarization policy: the requesting plugin supplies
+ * the deterministic `summarize` callback. The executor sequences the
+ * operation through the checkpoint coordinator (stage → summarize → commit),
+ * so a stale revision, a failing summary, or a concurrent compaction can
+ * never produce a half commit. Auto compaction, overflow recovery, retry,
+ * and tree/branch migration are later 2A slices.
+ */
+import type { JsonValue } from "@agent-forge/ai";
+import type { HostCheckpointCoordinatorV1 } from "./checkpoint-commit.ts";
+export type ManualCompactionStateV1 = "idle" | "in_progress";
+export type ManualCompactionOutcomeV1 = {
+    readonly status: "completed";
+    readonly revision: number;
+    readonly summary: JsonValue;
+} | {
+    readonly status: "stale";
+    readonly currentRevision: number;
+} | {
+    readonly status: "summary_failed";
+    readonly reason: string;
+} | {
+    readonly status: "busy";
+    readonly currentOperationId: string;
+};
+export interface ManualCompactionExecutorV1 {
+    /** Plugin-driven entry point: the plugin decides timing AND the summary. */
+    requestCompaction(input: {
+        readonly pluginId: string;
+        readonly operationId: string;
+        readonly summarize: () => JsonValue;
+    }): ManualCompactionOutcomeV1;
+    readonly state: ManualCompactionStateV1;
+}
+export declare function createManualCompactionExecutor(options: {
+    readonly coordinator: HostCheckpointCoordinatorV1;
+}): ManualCompactionExecutorV1;
+//# sourceMappingURL=manual-compaction.d.ts.map

package/dist/host/manual-compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manual-compaction.d.ts","sourceRoot":"","sources":["../../src/host/manual-compaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAE1E,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,aAAa,CAAC;AAE7D,MAAM,MAAM,yBAAyB,GAClC;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAA;CAAE,GACxF;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CAAE,GAC9D;IAAE,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC9D;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE,MAAM,WAAW,0BAA0B;IAC1C,4EAA4E;IAC5E,iBAAiB,CAAC,KAAK,EAAE;QACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,SAAS,CAAC;KACpC,GAAG,yBAAyB,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,uBAAuB,CAAC;CACxC;AAED,wBAAgB,8BAA8B,CAAC,OAAO,EAAE;IACvD,QAAQ,CAAC,WAAW,EAAE,2BAA2B,CAAC;CAClD,GAAG,0BAA0B,CA4D7B","sourcesContent":["/**\n * Manual compaction executor (2A.2) — the host primitive that lets a PLUGIN\n * decide when compaction happens and what the summary contains, while the\n * kernel side only provides the model/session/commit primitives (here: the\n * 2A.1 checkpoint coordinator).\n *\n * The executor owns no summarization policy: the requesting plugin supplies\n * the deterministic `summarize` callback. The executor sequences the\n * operation through the checkpoint coordinator (stage → summarize → commit),\n * so a stale revision, a failing summary, or a concurrent compaction can\n * never produce a half commit. Auto compaction, overflow recovery, retry,\n * and tree/branch migration are later 2A slices.\n */\nimport type { JsonValue } from \"@agent-forge/ai\";\nimport type { HostCheckpointCoordinatorV1 } from \"./checkpoint-commit.ts\";\n\nexport type ManualCompactionStateV1 = \"idle\" | \"in_progress\";\n\nexport type ManualCompactionOutcomeV1 =\n\t| { readonly status: \"completed\"; readonly revision: number; readonly summary: JsonValue }\n\t| { readonly status: \"stale\"; readonly currentRevision: number }\n\t| { readonly status: \"summary_failed\"; readonly reason: string }\n\t| { readonly status: \"busy\"; readonly currentOperationId: string };\n\nexport interface ManualCompactionExecutorV1 {\n\t/** Plugin-driven entry point: the plugin decides timing AND the summary. */\n\trequestCompaction(input: {\n\t\treadonly pluginId: string;\n\t\treadonly operationId: string;\n\t\treadonly summarize: () => JsonValue;\n\t}): ManualCompactionOutcomeV1;\n\treadonly state: ManualCompactionStateV1;\n}\n\nexport function createManualCompactionExecutor(options: {\n\treadonly coordinator: HostCheckpointCoordinatorV1;\n}): ManualCompactionExecutorV1 {\n\tconst coordinator = options.coordinator;\n\tlet state: ManualCompactionStateV1 = \"idle\";\n\tlet currentOperationId: string | undefined;\n\n\treturn {\n\t\tget state() {\n\t\t\treturn state;\n\t\t},\n\t\trequestCompaction(input) {\n\t\t\tif (state === \"in_progress\") {\n\t\t\t\t// v8 ignore next -- state 与 currentOperationId 同步赋值，busy 时必有 operationId\n\t\t\t\treturn { status: \"busy\", currentOperationId: currentOperationId ?? \"unknown\" };\n\t\t\t}\n\t\t\tif (input.pluginId.trim().length === 0) {\n\t\t\t\tthrow new Error(\"Compaction pluginId must be a non-empty string\");\n\t\t\t}\n\t\t\tstate = \"in_progress\";\n\t\t\tcurrentOperationId = input.operationId;\n\t\t\ttry {\n\t\t\t\t// Stage against the current revision; a concurrent commit makes this stale.\n\t\t\t\tconst staged = coordinator.stage({\n\t\t\t\t\toperationId: input.operationId,\n\t\t\t\t\texpectedRevision: coordinator.currentRevision,\n\t\t\t\t\tpayload: null,\n\t\t\t\t});\n\t\t\t\tif (staged.status === \"stale\") {\n\t\t\t\t\treturn { status: \"stale\", currentRevision: staged.currentRevision };\n\t\t\t\t}\n\t\t\t\tif (staged.status === \"duplicate\") {\n\t\t\t\t\treturn { status: \"completed\", revision: staged.revision, summary: { duplicate: true } };\n\t\t\t\t}\n\t\t\t\t// Plugin-owned summarization; the executor knows nothing of the content.\n\t\t\t\tlet summary: JsonValue;\n\t\t\t\ttry {\n\t\t\t\t\tsummary = input.summarize();\n\t\t\t\t} catch (error) {\n\t\t\t\t\tcoordinator.cancelStage(staged.staged.token);\n\t\t\t\t\treturn { status: \"summary_failed\", reason: error instanceof Error ? error.message : String(error) };\n\t\t\t\t}\n\t\t\t\tconst outcome = coordinator.commitStage({\n\t\t\t\t\ttoken: staged.staged.token,\n\t\t\t\t\tapply: (payload, revision) => {\n\t\t\t\t\t\tvoid payload;\n\t\t\t\t\t\tvoid revision;\n\t\t\t\t\t},\n\t\t\t\t});\n\t\t\t\tif (outcome.status === \"stale\") {\n\t\t\t\t\treturn { status: \"stale\", currentRevision: outcome.currentRevision };\n\t\t\t\t}\n\t\t\t\tif (outcome.status === \"committed\") {\n\t\t\t\t\treturn { status: \"completed\", revision: outcome.revision, summary };\n\t\t\t\t}\n\t\t\t\treturn { status: \"summary_failed\", reason: `Unexpected checkpoint outcome: ${outcome.status}` };\n\t\t\t} finally {\n\t\t\t\tstate = \"idle\";\n\t\t\t\tcurrentOperationId = undefined;\n\t\t\t}\n\t\t},\n\t};\n}\n"]}