@ai-agent-forge/agent-forge 0.85.0

package/dist/profile/root-facade.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Root-agent-controller facade adapter (2.1a).
+ *
+ * Proves the default root can be created and run through the public facade:
+ * the adapter defines (or reuses) a `root-agent-controller` definition on the
+ * composition and runs each turn on a fresh instance with the controller
+ * lease acquired and released through the public API — no private main-loop
+ * access. The TUI keeps its transitional path until 2.1c.
+ */
+import type { AgentCompositionAPI } from "../core/extensions/public-api.ts";
+export interface RootAgentFacadeTurnResultV1<TResult> {
+    readonly status: "succeeded" | "failed" | "cancelled" | "disposed";
+    readonly output?: TResult;
+    readonly revision: number;
+    readonly error?: Error;
+    readonly instanceId: string;
+    readonly leaseId: string;
+}
+export interface RootAgentFacadeV1<TInput = unknown, TResult = unknown> {
+    readonly definitionId: string;
+    /** Runs one minimal turn: create instance → acquire controller lease → run → release. */
+    runTurn(input: TInput, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<RootAgentFacadeTurnResultV1<TResult>>;
+}
+export declare function createRootAgentFacade<TInput, TResult = unknown>(options: {
+    readonly composition: AgentCompositionAPI;
+    readonly rootDefinitionId?: string;
+    readonly rootVersion?: number;
+    readonly owner?: string;
+    /** The root turn implementation (deterministic in tests). */
+    readonly run: (input: TInput, context: {
+        readonly signal?: AbortSignal;
+    }) => Promise<TResult> | TResult;
+}): RootAgentFacadeV1<TInput, TResult>;
+//# sourceMappingURL=root-facade.d.ts.map

package/dist/profile/root-facade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-facade.d.ts","sourceRoot":"","sources":["../../src/profile/root-facade.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAE5E,MAAM,WAAW,2BAA2B,CAAC,OAAO;IACnD,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,CAAC;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IACrE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,+FAAyF;IACzF,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,2BAA2B,CAAC,OAAO,CAAC,CAAC,CAAC;CACnH;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,EAAE,OAAO,EAAE;IACzE,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;IAC1C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CACxG,GAAG,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,CA4CrC","sourcesContent":["/**\n * Root-agent-controller facade adapter (2.1a).\n *\n * Proves the default root can be created and run through the public facade:\n * the adapter defines (or reuses) a `root-agent-controller` definition on the\n * composition and runs each turn on a fresh instance with the controller\n * lease acquired and released through the public API — no private main-loop\n * access. The TUI keeps its transitional path until 2.1c.\n */\nimport type { AgentCompositionAPI } from \"../core/extensions/public-api.ts\";\n\nexport interface RootAgentFacadeTurnResultV1<TResult> {\n\treadonly status: \"succeeded\" | \"failed\" | \"cancelled\" | \"disposed\";\n\treadonly output?: TResult;\n\treadonly revision: number;\n\treadonly error?: Error;\n\treadonly instanceId: string;\n\treadonly leaseId: string;\n}\n\nexport interface RootAgentFacadeV1<TInput = unknown, TResult = unknown> {\n\treadonly definitionId: string;\n\t/** Runs one minimal turn: create instance → acquire controller lease → run → release. */\n\trunTurn(input: TInput, options?: { readonly signal?: AbortSignal }): Promise<RootAgentFacadeTurnResultV1<TResult>>;\n}\n\nexport function createRootAgentFacade<TInput, TResult = unknown>(options: {\n\treadonly composition: AgentCompositionAPI;\n\treadonly rootDefinitionId?: string;\n\treadonly rootVersion?: number;\n\treadonly owner?: string;\n\t/** The root turn implementation (deterministic in tests). */\n\treadonly run: (input: TInput, context: { readonly signal?: AbortSignal }) => Promise<TResult> | TResult;\n}): RootAgentFacadeV1<TInput, TResult> {\n\tconst definitionId = options.rootDefinitionId ?? \"root-agent-controller\";\n\tconst owner = options.owner ?? \"root-facade\";\n\tconst definition = options.composition.define({\n\t\tid: definitionId,\n\t\tversion: options.rootVersion ?? 1,\n\t\trole: \"root-agent-controller\",\n\t\trun: (input: TInput, context: { readonly signal?: AbortSignal }) => options.run(input, context),\n\t});\n\tlet turnInFlight = false;\n\n\treturn {\n\t\tdefinitionId,\n\t\tasync runTurn(input, runOptions) {\n\t\t\t// Single-controller rule: one turn at a time per root facade.\n\t\t\tif (turnInFlight) {\n\t\t\t\tthrow new Error(\"Root facade is already running a turn\");\n\t\t\t}\n\t\t\tturnInFlight = true;\n\t\t\ttry {\n\t\t\t\t// A composition instance is single-run; every turn gets a fresh one.\n\t\t\t\tconst instance = options.composition.create<TInput, TResult>(definition);\n\t\t\t\tconst lease = await instance.acquireControllerLease(owner);\n\t\t\t\tconst leaseId = lease.id;\n\t\t\t\ttry {\n\t\t\t\t\tconst operation = instance.run(input, { lease, signal: runOptions?.signal });\n\t\t\t\t\tawait operation.result;\n\t\t\t\t\tconst instanceResult = await instance.wait();\n\t\t\t\t\treturn {\n\t\t\t\t\t\tstatus: instanceResult.status,\n\t\t\t\t\t\t...(instanceResult.output !== undefined ? { output: instanceResult.output } : {}),\n\t\t\t\t\t\t...(instanceResult.error instanceof Error ? { error: instanceResult.error } : {}),\n\t\t\t\t\t\trevision: instanceResult.revision,\n\t\t\t\t\t\tinstanceId: instance.id,\n\t\t\t\t\t\tleaseId,\n\t\t\t\t\t};\n\t\t\t\t} finally {\n\t\t\t\t\tif (lease.isActive()) await lease.release();\n\t\t\t\t}\n\t\t\t} finally {\n\t\t\t\tturnInFlight = false;\n\t\t\t}\n\t\t},\n\t};\n}\n"]}

package/dist/profile/root-facade.js

@@ -0,0 +1,48 @@
+export function createRootAgentFacade(options) {
+    const definitionId = options.rootDefinitionId ?? "root-agent-controller";
+    const owner = options.owner ?? "root-facade";
+    const definition = options.composition.define({
+        id: definitionId,
+        version: options.rootVersion ?? 1,
+        role: "root-agent-controller",
+        run: (input, context) => options.run(input, context),
+    });
+    let turnInFlight = false;
+    return {
+        definitionId,
+        async runTurn(input, runOptions) {
+            // Single-controller rule: one turn at a time per root facade.
+            if (turnInFlight) {
+                throw new Error("Root facade is already running a turn");
+            }
+            turnInFlight = true;
+            try {
+                // A composition instance is single-run; every turn gets a fresh one.
+                const instance = options.composition.create(definition);
+                const lease = await instance.acquireControllerLease(owner);
+                const leaseId = lease.id;
+                try {
+                    const operation = instance.run(input, { lease, signal: runOptions?.signal });
+                    await operation.result;
+                    const instanceResult = await instance.wait();
+                    return {
+                        status: instanceResult.status,
+                        ...(instanceResult.output !== undefined ? { output: instanceResult.output } : {}),
+                        ...(instanceResult.error instanceof Error ? { error: instanceResult.error } : {}),
+                        revision: instanceResult.revision,
+                        instanceId: instance.id,
+                        leaseId,
+                    };
+                }
+                finally {
+                    if (lease.isActive())
+                        await lease.release();
+                }
+            }
+            finally {
+                turnInFlight = false;
+            }
+        },
+    };
+}
+//# sourceMappingURL=root-facade.js.map

package/dist/profile/root-facade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-facade.js","sourceRoot":"","sources":["../../src/profile/root-facade.ts"],"names":[],"mappings":"AA0BA,MAAM,UAAU,qBAAqB,CAA4B,OAOhE,EAAsC;IACtC,MAAM,YAAY,GAAG,OAAO,CAAC,gBAAgB,IAAI,uBAAuB,CAAC;IACzE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,aAAa,CAAC;IAC7C,MAAM,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC;QAC7C,EAAE,EAAE,YAAY;QAChB,OAAO,EAAE,OAAO,CAAC,WAAW,IAAI,CAAC;QACjC,IAAI,EAAE,uBAAuB;QAC7B,GAAG,EAAE,CAAC,KAAa,EAAE,OAA0C,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC;KAC/F,CAAC,CAAC;IACH,IAAI,YAAY,GAAG,KAAK,CAAC;IAEzB,OAAO;QACN,YAAY;QACZ,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE;YAChC,8DAA8D;YAC9D,IAAI,YAAY,EAAE,CAAC;gBAClB,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;YAC1D,CAAC;YACD,YAAY,GAAG,IAAI,CAAC;YACpB,IAAI,CAAC;gBACJ,qEAAqE;gBACrE,MAAM,QAAQ,GAAG,OAAO,CAAC,WAAW,CAAC,MAAM,CAAkB,UAAU,CAAC,CAAC;gBACzE,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,sBAAsB,CAAC,KAAK,CAAC,CAAC;gBAC3D,MAAM,OAAO,GAAG,KAAK,CAAC,EAAE,CAAC;gBACzB,IAAI,CAAC;oBACJ,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;oBAC7E,MAAM,SAAS,CAAC,MAAM,CAAC;oBACvB,MAAM,cAAc,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;oBAC7C,OAAO;wBACN,MAAM,EAAE,cAAc,CAAC,MAAM;wBAC7B,GAAG,CAAC,cAAc,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBACjF,GAAG,CAAC,cAAc,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBACjF,QAAQ,EAAE,cAAc,CAAC,QAAQ;wBACjC,UAAU,EAAE,QAAQ,CAAC,EAAE;wBACvB,OAAO;qBACP,CAAC;gBACH,CAAC;wBAAS,CAAC;oBACV,IAAI,KAAK,CAAC,QAAQ,EAAE;wBAAE,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC;gBAC7C,CAAC;YACF,CAAC;oBAAS,CAAC;gBACV,YAAY,GAAG,KAAK,CAAC;YACtB,CAAC;QAAA,CACD;KACD,CAAC;AAAA,CACF","sourcesContent":["/**\n * Root-agent-controller facade adapter (2.1a).\n *\n * Proves the default root can be created and run through the public facade:\n * the adapter defines (or reuses) a `root-agent-controller` definition on the\n * composition and runs each turn on a fresh instance with the controller\n * lease acquired and released through the public API — no private main-loop\n * access. The TUI keeps its transitional path until 2.1c.\n */\nimport type { AgentCompositionAPI } from \"../core/extensions/public-api.ts\";\n\nexport interface RootAgentFacadeTurnResultV1<TResult> {\n\treadonly status: \"succeeded\" | \"failed\" | \"cancelled\" | \"disposed\";\n\treadonly output?: TResult;\n\treadonly revision: number;\n\treadonly error?: Error;\n\treadonly instanceId: string;\n\treadonly leaseId: string;\n}\n\nexport interface RootAgentFacadeV1<TInput = unknown, TResult = unknown> {\n\treadonly definitionId: string;\n\t/** Runs one minimal turn: create instance → acquire controller lease → run → release. */\n\trunTurn(input: TInput, options?: { readonly signal?: AbortSignal }): Promise<RootAgentFacadeTurnResultV1<TResult>>;\n}\n\nexport function createRootAgentFacade<TInput, TResult = unknown>(options: {\n\treadonly composition: AgentCompositionAPI;\n\treadonly rootDefinitionId?: string;\n\treadonly rootVersion?: number;\n\treadonly owner?: string;\n\t/** The root turn implementation (deterministic in tests). */\n\treadonly run: (input: TInput, context: { readonly signal?: AbortSignal }) => Promise<TResult> | TResult;\n}): RootAgentFacadeV1<TInput, TResult> {\n\tconst definitionId = options.rootDefinitionId ?? \"root-agent-controller\";\n\tconst owner = options.owner ?? \"root-facade\";\n\tconst definition = options.composition.define({\n\t\tid: definitionId,\n\t\tversion: options.rootVersion ?? 1,\n\t\trole: \"root-agent-controller\",\n\t\trun: (input: TInput, context: { readonly signal?: AbortSignal }) => options.run(input, context),\n\t});\n\tlet turnInFlight = false;\n\n\treturn {\n\t\tdefinitionId,\n\t\tasync runTurn(input, runOptions) {\n\t\t\t// Single-controller rule: one turn at a time per root facade.\n\t\t\tif (turnInFlight) {\n\t\t\t\tthrow new Error(\"Root facade is already running a turn\");\n\t\t\t}\n\t\t\tturnInFlight = true;\n\t\t\ttry {\n\t\t\t\t// A composition instance is single-run; every turn gets a fresh one.\n\t\t\t\tconst instance = options.composition.create<TInput, TResult>(definition);\n\t\t\t\tconst lease = await instance.acquireControllerLease(owner);\n\t\t\t\tconst leaseId = lease.id;\n\t\t\t\ttry {\n\t\t\t\t\tconst operation = instance.run(input, { lease, signal: runOptions?.signal });\n\t\t\t\t\tawait operation.result;\n\t\t\t\t\tconst instanceResult = await instance.wait();\n\t\t\t\t\treturn {\n\t\t\t\t\t\tstatus: instanceResult.status,\n\t\t\t\t\t\t...(instanceResult.output !== undefined ? { output: instanceResult.output } : {}),\n\t\t\t\t\t\t...(instanceResult.error instanceof Error ? { error: instanceResult.error } : {}),\n\t\t\t\t\t\trevision: instanceResult.revision,\n\t\t\t\t\t\tinstanceId: instance.id,\n\t\t\t\t\t\tleaseId,\n\t\t\t\t\t};\n\t\t\t\t} finally {\n\t\t\t\t\tif (lease.isActive()) await lease.release();\n\t\t\t\t}\n\t\t\t} finally {\n\t\t\t\tturnInFlight = false;\n\t\t\t}\n\t\t},\n\t};\n}\n"]}

package/dist/profile/skill-discovery-wiring.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Skill/MCP discovery wiring (4.4) — turns discovered Skill and MCP tool
+ * capabilities into profile-assembly inputs, with all four failure modes
+ * explicit BEFORE a session exists: missing dependencies, version conflicts
+ * between sources, disabled items, and replacements.
+ *
+ * Each registered item (a Skill or an MCP server) contributes capability
+ * declarations; MCP tools derive capability ids `mcp:<serverId>:<toolName>`.
+ * Two enabled items declaring the SAME capability id with DIFFERENT
+ * versions is a structured version conflict; identical versions dedupe.
+ * Disabled items contribute nothing (replacement = disable + register).
+ * Resolution reuses the 2.5a exact-version wiring — no kernel special
+ * cases. Implementation lives entirely in profile/assembly land.
+ */
+import type { ProfileDependencyWiringV1 } from "./dependency-wiring.ts";
+export type DiscoverySourceKindV1 = "skill" | "mcp";
+export interface DiscoveredItemV1 {
+    readonly sourceKind: DiscoverySourceKindV1;
+    readonly itemId: string;
+    readonly version: string;
+    readonly capabilities: readonly {
+        readonly id: string;
+        readonly version: number;
+    }[];
+    readonly enabled: boolean;
+}
+export interface DiscoveryVersionConflictV1 {
+    readonly capabilityId: string;
+    readonly declarations: readonly {
+        readonly sourceKind: DiscoverySourceKindV1;
+        readonly itemId: string;
+        readonly version: number;
+    }[];
+}
+export interface DiscoveryWiringV1 {
+    register(item: DiscoveredItemV1): void;
+    deriveMcpItem(input: {
+        readonly serverId: string;
+        readonly version: string;
+        readonly tools: readonly {
+            readonly name: string;
+            readonly description?: string;
+        }[];
+        readonly enabled?: boolean;
+    }): DiscoveredItemV1;
+    wireDiscoveredDependencies(input: {
+        readonly availableCapabilities: readonly {
+            readonly id: string;
+            readonly version: number;
+        }[];
+        readonly disabledItemIds?: readonly string[];
+    }): {
+        readonly conflicts: readonly DiscoveryVersionConflictV1[];
+        readonly wiring: ProfileDependencyWiringV1;
+    };
+}
+export declare function createSkillDiscoveryWiring(): DiscoveryWiringV1;
+//# sourceMappingURL=skill-discovery-wiring.d.ts.map

package/dist/profile/skill-discovery-wiring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-discovery-wiring.d.ts","sourceRoot":"","sources":["../../src/profile/skill-discovery-wiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AAIxE,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,KAAK,CAAC;AAEpD,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,SAAS;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACpF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,0BAA0B;IAC1C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,SAAS;QAC/B,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;QAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KACzB,EAAE,CAAC;CACJ;AAED,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACvC,aAAa,CAAC,KAAK,EAAE;QACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,KAAK,EAAE,SAAS;YAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QACpF,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;KAC3B,GAAG,gBAAgB,CAAC;IACrB,0BAA0B,CAAC,KAAK,EAAE;QACjC,QAAQ,CAAC,qBAAqB,EAAE,SAAS;YAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QAC7F,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KAC7C,GAAG;QAAE,QAAQ,CAAC,SAAS,EAAE,SAAS,0BAA0B,EAAE,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,yBAAyB,CAAA;KAAE,CAAC;CAC9G;AAED,wBAAgB,0BAA0B,IAAI,iBAAiB,CAgE9D","sourcesContent":["/**\n * Skill/MCP discovery wiring (4.4) — turns discovered Skill and MCP tool\n * capabilities into profile-assembly inputs, with all four failure modes\n * explicit BEFORE a session exists: missing dependencies, version conflicts\n * between sources, disabled items, and replacements.\n *\n * Each registered item (a Skill or an MCP server) contributes capability\n * declarations; MCP tools derive capability ids `mcp:<serverId>:<toolName>`.\n * Two enabled items declaring the SAME capability id with DIFFERENT\n * versions is a structured version conflict; identical versions dedupe.\n * Disabled items contribute nothing (replacement = disable + register).\n * Resolution reuses the 2.5a exact-version wiring — no kernel special\n * cases. Implementation lives entirely in profile/assembly land.\n */\n\nimport type { ProfileDependencyWiringV1 } from \"./dependency-wiring.ts\";\nimport { wireProfileDependencies } from \"./dependency-wiring.ts\";\nimport type { ResolvedPluginManifestV1 } from \"./identity.ts\";\n\nexport type DiscoverySourceKindV1 = \"skill\" | \"mcp\";\n\nexport interface DiscoveredItemV1 {\n\treadonly sourceKind: DiscoverySourceKindV1;\n\treadonly itemId: string;\n\treadonly version: string;\n\treadonly capabilities: readonly { readonly id: string; readonly version: number }[];\n\treadonly enabled: boolean;\n}\n\nexport interface DiscoveryVersionConflictV1 {\n\treadonly capabilityId: string;\n\treadonly declarations: readonly {\n\t\treadonly sourceKind: DiscoverySourceKindV1;\n\t\treadonly itemId: string;\n\t\treadonly version: number;\n\t}[];\n}\n\nexport interface DiscoveryWiringV1 {\n\tregister(item: DiscoveredItemV1): void;\n\tderiveMcpItem(input: {\n\t\treadonly serverId: string;\n\t\treadonly version: string;\n\t\treadonly tools: readonly { readonly name: string; readonly description?: string }[];\n\t\treadonly enabled?: boolean;\n\t}): DiscoveredItemV1;\n\twireDiscoveredDependencies(input: {\n\t\treadonly availableCapabilities: readonly { readonly id: string; readonly version: number }[];\n\t\treadonly disabledItemIds?: readonly string[];\n\t}): { readonly conflicts: readonly DiscoveryVersionConflictV1[]; readonly wiring: ProfileDependencyWiringV1 };\n}\n\nexport function createSkillDiscoveryWiring(): DiscoveryWiringV1 {\n\tconst items = new Map<string, DiscoveredItemV1>();\n\tconst keyOf = (item: DiscoveredItemV1): string => `${item.sourceKind}:${item.itemId}`;\n\n\treturn {\n\t\tregister(item) {\n\t\t\tif (item.itemId.trim().length === 0) throw new Error(\"Discovered item id must be a non-empty string\");\n\t\t\tconst existing = items.get(keyOf(item));\n\t\t\tif (existing && existing.version !== item.version) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Item ${keyOf(item)} re-registered with a different version (${existing.version} -> ${item.version})`,\n\t\t\t\t);\n\t\t\t}\n\t\t\titems.set(keyOf(item), { ...item, capabilities: [...item.capabilities] });\n\t\t},\n\t\tderiveMcpItem({ serverId, version, tools, enabled = true }) {\n\t\t\treturn {\n\t\t\t\tsourceKind: \"mcp\",\n\t\t\t\titemId: serverId,\n\t\t\t\tversion,\n\t\t\t\tcapabilities: tools.map((tool) => ({ id: `mcp:${serverId}:${tool.name}`, version: 1 })),\n\t\t\t\tenabled,\n\t\t\t};\n\t\t},\n\t\twireDiscoveredDependencies({ availableCapabilities, disabledItemIds }) {\n\t\t\tconst disabled = new Set(disabledItemIds ?? []);\n\t\t\tconst enabledItems = [...items.values()].filter((item) => item.enabled && !disabled.has(keyOf(item)));\n\n\t\t\t// Version conflicts: same capability id, different declared versions,\n\t\t\t// across different enabled items.\n\t\t\tconst byCapability = new Map<\n\t\t\t\tstring,\n\t\t\t\tArray<{ sourceKind: DiscoverySourceKindV1; itemId: string; version: number }>\n\t\t\t>();\n\t\t\tfor (const item of enabledItems) {\n\t\t\t\tfor (const capability of item.capabilities) {\n\t\t\t\t\tconst list = byCapability.get(capability.id) ?? [];\n\t\t\t\t\tif (!list.some((entry) => entry.itemId === item.itemId)) {\n\t\t\t\t\t\tlist.push({ sourceKind: item.sourceKind, itemId: item.itemId, version: capability.version });\n\t\t\t\t\t}\n\t\t\t\t\tbyCapability.set(capability.id, list);\n\t\t\t\t}\n\t\t\t}\n\t\t\tconst conflicts: DiscoveryVersionConflictV1[] = [];\n\t\t\tfor (const [capabilityId, declarations] of byCapability) {\n\t\t\t\tconst versions = new Set(declarations.map((entry) => entry.version));\n\t\t\t\tif (versions.size > 1) conflicts.push({ capabilityId, declarations });\n\t\t\t}\n\n\t\t\t// Disabled items stay in the manifests so the wiring result shows an\n\t\t\t// explicit skipped_disabled entry (visible audit, not silent removal).\n\t\t\tconst manifests: ResolvedPluginManifestV1[] = [...items.values()].map((item) => ({\n\t\t\t\tpluginId: keyOf(item),\n\t\t\t\tpluginVersion: item.version,\n\t\t\t\tcapabilityRefs: [...item.capabilities],\n\t\t\t}));\n\t\t\tconst wiring = wireProfileDependencies({\n\t\t\t\tresolvedPlugins: manifests,\n\t\t\t\tavailableCapabilities,\n\t\t\t\tdisabledPluginIds: disabledItemIds,\n\t\t\t});\n\t\t\treturn { conflicts: Object.freeze(conflicts), wiring };\n\t\t},\n\t};\n}\n"]}

package/dist/profile/skill-discovery-wiring.js

@@ -0,0 +1,75 @@
+/**
+ * Skill/MCP discovery wiring (4.4) — turns discovered Skill and MCP tool
+ * capabilities into profile-assembly inputs, with all four failure modes
+ * explicit BEFORE a session exists: missing dependencies, version conflicts
+ * between sources, disabled items, and replacements.
+ *
+ * Each registered item (a Skill or an MCP server) contributes capability
+ * declarations; MCP tools derive capability ids `mcp:<serverId>:<toolName>`.
+ * Two enabled items declaring the SAME capability id with DIFFERENT
+ * versions is a structured version conflict; identical versions dedupe.
+ * Disabled items contribute nothing (replacement = disable + register).
+ * Resolution reuses the 2.5a exact-version wiring — no kernel special
+ * cases. Implementation lives entirely in profile/assembly land.
+ */
+import { wireProfileDependencies } from "./dependency-wiring.js";
+export function createSkillDiscoveryWiring() {
+    const items = new Map();
+    const keyOf = (item) => `${item.sourceKind}:${item.itemId}`;
+    return {
+        register(item) {
+            if (item.itemId.trim().length === 0)
+                throw new Error("Discovered item id must be a non-empty string");
+            const existing = items.get(keyOf(item));
+            if (existing && existing.version !== item.version) {
+                throw new Error(`Item ${keyOf(item)} re-registered with a different version (${existing.version} -> ${item.version})`);
+            }
+            items.set(keyOf(item), { ...item, capabilities: [...item.capabilities] });
+        },
+        deriveMcpItem({ serverId, version, tools, enabled = true }) {
+            return {
+                sourceKind: "mcp",
+                itemId: serverId,
+                version,
+                capabilities: tools.map((tool) => ({ id: `mcp:${serverId}:${tool.name}`, version: 1 })),
+                enabled,
+            };
+        },
+        wireDiscoveredDependencies({ availableCapabilities, disabledItemIds }) {
+            const disabled = new Set(disabledItemIds ?? []);
+            const enabledItems = [...items.values()].filter((item) => item.enabled && !disabled.has(keyOf(item)));
+            // Version conflicts: same capability id, different declared versions,
+            // across different enabled items.
+            const byCapability = new Map();
+            for (const item of enabledItems) {
+                for (const capability of item.capabilities) {
+                    const list = byCapability.get(capability.id) ?? [];
+                    if (!list.some((entry) => entry.itemId === item.itemId)) {
+                        list.push({ sourceKind: item.sourceKind, itemId: item.itemId, version: capability.version });
+                    }
+                    byCapability.set(capability.id, list);
+                }
+            }
+            const conflicts = [];
+            for (const [capabilityId, declarations] of byCapability) {
+                const versions = new Set(declarations.map((entry) => entry.version));
+                if (versions.size > 1)
+                    conflicts.push({ capabilityId, declarations });
+            }
+            // Disabled items stay in the manifests so the wiring result shows an
+            // explicit skipped_disabled entry (visible audit, not silent removal).
+            const manifests = [...items.values()].map((item) => ({
+                pluginId: keyOf(item),
+                pluginVersion: item.version,
+                capabilityRefs: [...item.capabilities],
+            }));
+            const wiring = wireProfileDependencies({
+                resolvedPlugins: manifests,
+                availableCapabilities,
+                disabledPluginIds: disabledItemIds,
+            });
+            return { conflicts: Object.freeze(conflicts), wiring };
+        },
+    };
+}
+//# sourceMappingURL=skill-discovery-wiring.js.map

package/dist/profile/skill-discovery-wiring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-discovery-wiring.js","sourceRoot":"","sources":["../../src/profile/skill-discovery-wiring.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Skill/MCP discovery wiring (4.4) — turns discovered Skill and MCP tool\n * capabilities into profile-assembly inputs, with all four failure modes\n * explicit BEFORE a session exists: missing dependencies, version conflicts\n * between sources, disabled items, and replacements.\n *\n * Each registered item (a Skill or an MCP server) contributes capability\n * declarations; MCP tools derive capability ids `mcp:<serverId>:<toolName>`.\n * Two enabled items declaring the SAME capability id with DIFFERENT\n * versions is a structured version conflict; identical versions dedupe.\n * Disabled items contribute nothing (replacement = disable + register).\n * Resolution reuses the 2.5a exact-version wiring — no kernel special\n * cases. Implementation lives entirely in profile/assembly land.\n */\n\nimport type { ProfileDependencyWiringV1 } from \"./dependency-wiring.ts\";\nimport { wireProfileDependencies } from \"./dependency-wiring.ts\";\nimport type { ResolvedPluginManifestV1 } from \"./identity.ts\";\n\nexport type DiscoverySourceKindV1 = \"skill\" | \"mcp\";\n\nexport interface DiscoveredItemV1 {\n\treadonly sourceKind: DiscoverySourceKindV1;\n\treadonly itemId: string;\n\treadonly version: string;\n\treadonly capabilities: readonly { readonly id: string; readonly version: number }[];\n\treadonly enabled: boolean;\n}\n\nexport interface DiscoveryVersionConflictV1 {\n\treadonly capabilityId: string;\n\treadonly declarations: readonly {\n\t\treadonly sourceKind: DiscoverySourceKindV1;\n\t\treadonly itemId: string;\n\t\treadonly version: number;\n\t}[];\n}\n\nexport interface DiscoveryWiringV1 {\n\tregister(item: DiscoveredItemV1): void;\n\tderiveMcpItem(input: {\n\t\treadonly serverId: string;\n\t\treadonly version: string;\n\t\treadonly tools: readonly { readonly name: string; readonly description?: string }[];\n\t\treadonly enabled?: boolean;\n\t}): DiscoveredItemV1;\n\twireDiscoveredDependencies(input: {\n\t\treadonly availableCapabilities: readonly { readonly id: string; readonly version: number }[];\n\t\treadonly disabledItemIds?: readonly string[];\n\t}): { readonly conflicts: readonly DiscoveryVersionConflictV1[]; readonly wiring: ProfileDependencyWiringV1 };\n}\n\nexport function createSkillDiscoveryWiring(): DiscoveryWiringV1 {\n\tconst items = new Map<string, DiscoveredItemV1>();\n\tconst keyOf = (item: DiscoveredItemV1): string => `${item.sourceKind}:${item.itemId}`;\n\n\treturn {\n\t\tregister(item) {\n\t\t\tif (item.itemId.trim().length === 0) throw new Error(\"Discovered item id must be a non-empty string\");\n\t\t\tconst existing = items.get(keyOf(item));\n\t\t\tif (existing && existing.version !== item.version) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Item ${keyOf(item)} re-registered with a different version (${existing.version} -> ${item.version})`,\n\t\t\t\t);\n\t\t\t}\n\t\t\titems.set(keyOf(item), { ...item, capabilities: [...item.capabilities] });\n\t\t},\n\t\tderiveMcpItem({ serverId, version, tools, enabled = true }) {\n\t\t\treturn {\n\t\t\t\tsourceKind: \"mcp\",\n\t\t\t\titemId: serverId,\n\t\t\t\tversion,\n\t\t\t\tcapabilities: tools.map((tool) => ({ id: `mcp:${serverId}:${tool.name}`, version: 1 })),\n\t\t\t\tenabled,\n\t\t\t};\n\t\t},\n\t\twireDiscoveredDependencies({ availableCapabilities, disabledItemIds }) {\n\t\t\tconst disabled = new Set(disabledItemIds ?? []);\n\t\t\tconst enabledItems = [...items.values()].filter((item) => item.enabled && !disabled.has(keyOf(item)));\n\n\t\t\t// Version conflicts: same capability id, different declared versions,\n\t\t\t// across different enabled items.\n\t\t\tconst byCapability = new Map<\n\t\t\t\tstring,\n\t\t\t\tArray<{ sourceKind: DiscoverySourceKindV1; itemId: string; version: number }>\n\t\t\t>();\n\t\t\tfor (const item of enabledItems) {\n\t\t\t\tfor (const capability of item.capabilities) {\n\t\t\t\t\tconst list = byCapability.get(capability.id) ?? [];\n\t\t\t\t\tif (!list.some((entry) => entry.itemId === item.itemId)) {\n\t\t\t\t\t\tlist.push({ sourceKind: item.sourceKind, itemId: item.itemId, version: capability.version });\n\t\t\t\t\t}\n\t\t\t\t\tbyCapability.set(capability.id, list);\n\t\t\t\t}\n\t\t\t}\n\t\t\tconst conflicts: DiscoveryVersionConflictV1[] = [];\n\t\t\tfor (const [capabilityId, declarations] of byCapability) {\n\t\t\t\tconst versions = new Set(declarations.map((entry) => entry.version));\n\t\t\t\tif (versions.size > 1) conflicts.push({ capabilityId, declarations });\n\t\t\t}\n\n\t\t\t// Disabled items stay in the manifests so the wiring result shows an\n\t\t\t// explicit skipped_disabled entry (visible audit, not silent removal).\n\t\t\tconst manifests: ResolvedPluginManifestV1[] = [...items.values()].map((item) => ({\n\t\t\t\tpluginId: keyOf(item),\n\t\t\t\tpluginVersion: item.version,\n\t\t\t\tcapabilityRefs: [...item.capabilities],\n\t\t\t}));\n\t\t\tconst wiring = wireProfileDependencies({\n\t\t\t\tresolvedPlugins: manifests,\n\t\t\t\tavailableCapabilities,\n\t\t\t\tdisabledPluginIds: disabledItemIds,\n\t\t\t});\n\t\t\treturn { conflicts: Object.freeze(conflicts), wiring };\n\t\t},\n\t};\n}\n"]}

package/dist/profile/state-store.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Generic transition/evidence/revision store (2.3a) — the domain-agnostic
+ * contract base for Goal/Plan/Todo plugins.
+ *
+ * The store knows NOTHING about goal/plan/todo semantics. It only enforces:
+ * - causality: a transition's `fromStatus` must equal the entity's current
+ *   status (null = initial transition), otherwise an explicit conflict;
+ * - idempotency: replaying the same (domain, entityId, operationId, toStatus)
+ *   returns the existing record and never advances the revision;
+ * - evidence: every transition carries structured evidence references;
+ * - payload: transitions may carry an optional domain payload (e.g. a goal
+ *   title) that is validated JSON and part of the replayable record;
+ * - replay: the full history rebuilds the identical current state.
+ */
+import type { JsonValue } from "@agent-forge/ai";
+export interface TransitionEvidenceRefV1 {
+    readonly kind: string;
+    readonly ref: string;
+    readonly digest?: string;
+}
+export interface TransitionRecordV1 {
+    readonly domain: string;
+    readonly entityId: string;
+    readonly owner: string;
+    readonly fromStatus: string | null;
+    readonly toStatus: string;
+    readonly operationId: string;
+    readonly evidence: readonly TransitionEvidenceRefV1[];
+    readonly payload?: JsonValue;
+    readonly revision: number;
+    readonly at: number;
+}
+export interface TransitionInputV1 {
+    readonly domain: string;
+    readonly entityId: string;
+    readonly owner: string;
+    readonly fromStatus: string | null;
+    readonly toStatus: string;
+    readonly operationId: string;
+    readonly evidence?: readonly TransitionEvidenceRefV1[];
+    readonly payload?: JsonValue;
+    readonly at?: number;
+}
+export interface TransitionResultV1 {
+    readonly record: TransitionRecordV1;
+    readonly deduped: boolean;
+}
+export interface TransitionStoreV1 {
+    transition(input: TransitionInputV1): TransitionResultV1;
+    currentStatus(domain: string, entityId: string): {
+        readonly status: string;
+        readonly revision: number;
+    } | undefined;
+    history(entityId: string): readonly TransitionRecordV1[];
+    /** Replays a history into a fresh store; the rebuilt state must be identical. */
+    replay(history: readonly TransitionRecordV1[]): void;
+    entities(): readonly string[];
+}
+export declare function createTransitionStore(options?: {
+    readonly now?: () => number;
+}): TransitionStoreV1;
+//# sourceMappingURL=state-store.d.ts.map

package/dist/profile/state-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-store.d.ts","sourceRoot":"","sources":["../../src/profile/state-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACtD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACvD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC;IAC7B,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC1B;AAyDD,MAAM,WAAW,iBAAiB;IACjC,UAAU,CAAC,KAAK,EAAE,iBAAiB,GAAG,kBAAkB,CAAC;IACzD,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IACpH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,kBAAkB,EAAE,CAAC;IACzD,iFAAiF;IACjF,MAAM,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,GAAG,IAAI,CAAC;IACrD,QAAQ,IAAI,SAAS,MAAM,EAAE,CAAC;CAC9B;AAED,wBAAgB,qBAAqB,CAAC,OAAO,GAAE;IAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAAO,GAAG,iBAAiB,CAiFtG","sourcesContent":["/**\n * Generic transition/evidence/revision store (2.3a) — the domain-agnostic\n * contract base for Goal/Plan/Todo plugins.\n *\n * The store knows NOTHING about goal/plan/todo semantics. It only enforces:\n * - causality: a transition's `fromStatus` must equal the entity's current\n *   status (null = initial transition), otherwise an explicit conflict;\n * - idempotency: replaying the same (domain, entityId, operationId, toStatus)\n *   returns the existing record and never advances the revision;\n * - evidence: every transition carries structured evidence references;\n * - payload: transitions may carry an optional domain payload (e.g. a goal\n *   title) that is validated JSON and part of the replayable record;\n * - replay: the full history rebuilds the identical current state.\n */\nimport type { JsonValue } from \"@agent-forge/ai\";\n\nexport interface TransitionEvidenceRefV1 {\n\treadonly kind: string;\n\treadonly ref: string;\n\treadonly digest?: string;\n}\n\nexport interface TransitionRecordV1 {\n\treadonly domain: string;\n\treadonly entityId: string;\n\treadonly owner: string;\n\treadonly fromStatus: string | null;\n\treadonly toStatus: string;\n\treadonly operationId: string;\n\treadonly evidence: readonly TransitionEvidenceRefV1[];\n\treadonly payload?: JsonValue;\n\treadonly revision: number;\n\treadonly at: number;\n}\n\nexport interface TransitionInputV1 {\n\treadonly domain: string;\n\treadonly entityId: string;\n\treadonly owner: string;\n\treadonly fromStatus: string | null;\n\treadonly toStatus: string;\n\treadonly operationId: string;\n\treadonly evidence?: readonly TransitionEvidenceRefV1[];\n\treadonly payload?: JsonValue;\n\treadonly at?: number;\n}\n\nexport interface TransitionResultV1 {\n\treadonly record: TransitionRecordV1;\n\treadonly deduped: boolean;\n}\n\nfunction assertNonEmptyString(value: unknown, label: string): asserts value is string {\n\tif (typeof value !== \"string\" || value.trim().length === 0) throw new Error(`${label} must be a non-empty string`);\n}\n\nfunction validateEvidence(value: unknown, label: string): TransitionEvidenceRefV1[] {\n\tif (value === undefined) return [];\n\tif (!Array.isArray(value)) throw new Error(`${label} must be an array`);\n\treturn value.map((item, index) => {\n\t\tconst depLabel = `${label}[${index}]`;\n\t\tif (item === null || typeof item !== \"object\" || Array.isArray(item)) {\n\t\t\tthrow new Error(`${depLabel} must be a plain object`);\n\t\t}\n\t\tconst record = item as Record<string, unknown>;\n\t\tassertNonEmptyString(record.kind, `${depLabel}.kind`);\n\t\tassertNonEmptyString(record.ref, `${depLabel}.ref`);\n\t\tif (record.digest !== undefined) assertNonEmptyString(record.digest, `${depLabel}.digest`);\n\t\treturn Object.freeze({\n\t\t\tkind: record.kind,\n\t\t\tref: record.ref,\n\t\t\t...(record.digest === undefined ? {} : { digest: record.digest }),\n\t\t});\n\t});\n}\n\nfunction validatePayload(value: unknown, label: string): JsonValue | undefined {\n\tif (value === undefined) return undefined;\n\tconst seen = new Set<object>();\n\tconst check = (node: unknown): void => {\n\t\tif (node === null || typeof node === \"string\" || typeof node === \"boolean\") return;\n\t\tif (typeof node === \"number\") {\n\t\t\tif (!Number.isFinite(node)) throw new Error(`${label} must be JSON-safe: ${node} is not a finite number`);\n\t\t\treturn;\n\t\t}\n\t\tif (typeof node === \"object\") {\n\t\t\tif (seen.has(node)) throw new Error(`${label} must be JSON-safe: circular reference`);\n\t\t\tseen.add(node);\n\t\t\tif (Array.isArray(node)) {\n\t\t\t\tfor (const item of node) check(item);\n\t\t\t} else {\n\t\t\t\tconst proto = Object.getPrototypeOf(node) as unknown;\n\t\t\t\tif (proto !== Object.prototype && proto !== null) throw new Error(`${label} must be a plain object`);\n\t\t\t\tfor (const entry of Object.entries(node)) {\n\t\t\t\t\tif (entry[1] === undefined) throw new Error(`${label} must be JSON-safe: ${entry[0]} is undefined`);\n\t\t\t\t\tcheck(entry[1]);\n\t\t\t\t}\n\t\t\t}\n\t\t\tseen.delete(node);\n\t\t\treturn;\n\t\t}\n\t\tthrow new Error(`${label} must be JSON-safe: unsupported value of type ${typeof node}`);\n\t};\n\tcheck(value);\n\treturn JSON.parse(JSON.stringify(value)) as JsonValue;\n}\n\nexport interface TransitionStoreV1 {\n\ttransition(input: TransitionInputV1): TransitionResultV1;\n\tcurrentStatus(domain: string, entityId: string): { readonly status: string; readonly revision: number } | undefined;\n\thistory(entityId: string): readonly TransitionRecordV1[];\n\t/** Replays a history into a fresh store; the rebuilt state must be identical. */\n\treplay(history: readonly TransitionRecordV1[]): void;\n\tentities(): readonly string[];\n}\n\nexport function createTransitionStore(options: { readonly now?: () => number } = {}): TransitionStoreV1 {\n\tconst now = options.now ?? (() => Date.now());\n\tconst recordsByEntity = new Map<string, TransitionRecordV1[]>();\n\tconst idempotency = new Map<string, TransitionRecordV1>();\n\tconst currentStatus = new Map<string, { status: string; revision: number }>();\n\tconst revisions = new Map<string, number>();\n\n\tconst entityKey = (domain: string, entityId: string): string => `${domain}\\u0000${entityId}`;\n\n\treturn {\n\t\ttransition(input) {\n\t\t\tassertNonEmptyString(input.domain, \"Transition domain\");\n\t\t\tassertNonEmptyString(input.entityId, \"Transition entityId\");\n\t\t\tassertNonEmptyString(input.owner, \"Transition owner\");\n\t\t\tassertNonEmptyString(input.operationId, \"Transition operationId\");\n\t\t\tassertNonEmptyString(input.toStatus, \"Transition toStatus\");\n\t\t\tconst evidence = validateEvidence(input.evidence, \"Transition evidence\");\n\t\t\tconst payload = validatePayload(input.payload, \"Transition payload\");\n\t\t\tconst key = `${entityKey(input.domain, input.entityId)}\\u0000${input.operationId}\\u0000${input.toStatus}`;\n\n\t\t\tconst existing = idempotency.get(key);\n\t\t\tif (existing) return { record: existing, deduped: true };\n\n\t\t\tconst entityKeyId = entityKey(input.domain, input.entityId);\n\t\t\tconst current = currentStatus.get(entityKeyId);\n\t\t\tconst fromStatus = input.fromStatus;\n\t\t\tif ((current?.status ?? null) !== fromStatus) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Transition conflict: expected fromStatus ${JSON.stringify(current?.status ?? null)}, got ${JSON.stringify(fromStatus)}`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst revision = (revisions.get(entityKeyId) ?? 0) + 1;\n\t\t\trevisions.set(entityKeyId, revision);\n\t\t\tconst record: TransitionRecordV1 = Object.freeze({\n\t\t\t\tdomain: input.domain,\n\t\t\t\tentityId: input.entityId,\n\t\t\t\towner: input.owner,\n\t\t\t\tfromStatus,\n\t\t\t\ttoStatus: input.toStatus,\n\t\t\t\toperationId: input.operationId,\n\t\t\t\tevidence: Object.freeze(evidence),\n\t\t\t\t...(payload === undefined ? {} : { payload }),\n\t\t\t\trevision,\n\t\t\t\tat: input.at ?? now(),\n\t\t\t});\n\t\t\tconst log = recordsByEntity.get(entityKeyId) ?? [];\n\t\t\tlog.push(record);\n\t\t\trecordsByEntity.set(entityKeyId, log);\n\t\t\tcurrentStatus.set(entityKeyId, { status: input.toStatus, revision });\n\t\t\tidempotency.set(key, record);\n\t\t\treturn { record, deduped: false };\n\t\t},\n\t\tcurrentStatus(domain: string, entityId: string) {\n\t\t\treturn currentStatus.get(entityKey(domain, entityId));\n\t\t},\n\t\thistory(entityId: string) {\n\t\t\treturn Object.freeze(\n\t\t\t\t[...recordsByEntity.entries()]\n\t\t\t\t\t.filter(([entityKeyId]) => entityKeyId.endsWith(`\\u0000${entityId}`))\n\t\t\t\t\t.flatMap(([, log]) => log),\n\t\t\t);\n\t\t},\n\t\treplay(history) {\n\t\t\tfor (const record of history) {\n\t\t\t\tthis.transition({\n\t\t\t\t\tdomain: record.domain,\n\t\t\t\t\tentityId: record.entityId,\n\t\t\t\t\towner: record.owner,\n\t\t\t\t\tfromStatus: record.fromStatus,\n\t\t\t\t\ttoStatus: record.toStatus,\n\t\t\t\t\toperationId: record.operationId,\n\t\t\t\t\tevidence: record.evidence,\n\t\t\t\t\tpayload: record.payload,\n\t\t\t\t\tat: record.at,\n\t\t\t\t});\n\t\t\t}\n\t\t},\n\t\tentities() {\n\t\t\treturn Object.freeze([...new Set([...currentStatus.keys()].map((key) => key.split(\"\\u0000\")[1]!))]);\n\t\t},\n\t};\n}\n"]}

package/dist/profile/state-store.js

@@ -0,0 +1,140 @@
+function assertNonEmptyString(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        throw new Error(`${label} must be a non-empty string`);
+}
+function validateEvidence(value, label) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error(`${label} must be an array`);
+    return value.map((item, index) => {
+        const depLabel = `${label}[${index}]`;
+        if (item === null || typeof item !== "object" || Array.isArray(item)) {
+            throw new Error(`${depLabel} must be a plain object`);
+        }
+        const record = item;
+        assertNonEmptyString(record.kind, `${depLabel}.kind`);
+        assertNonEmptyString(record.ref, `${depLabel}.ref`);
+        if (record.digest !== undefined)
+            assertNonEmptyString(record.digest, `${depLabel}.digest`);
+        return Object.freeze({
+            kind: record.kind,
+            ref: record.ref,
+            ...(record.digest === undefined ? {} : { digest: record.digest }),
+        });
+    });
+}
+function validatePayload(value, label) {
+    if (value === undefined)
+        return undefined;
+    const seen = new Set();
+    const check = (node) => {
+        if (node === null || typeof node === "string" || typeof node === "boolean")
+            return;
+        if (typeof node === "number") {
+            if (!Number.isFinite(node))
+                throw new Error(`${label} must be JSON-safe: ${node} is not a finite number`);
+            return;
+        }
+        if (typeof node === "object") {
+            if (seen.has(node))
+                throw new Error(`${label} must be JSON-safe: circular reference`);
+            seen.add(node);
+            if (Array.isArray(node)) {
+                for (const item of node)
+                    check(item);
+            }
+            else {
+                const proto = Object.getPrototypeOf(node);
+                if (proto !== Object.prototype && proto !== null)
+                    throw new Error(`${label} must be a plain object`);
+                for (const entry of Object.entries(node)) {
+                    if (entry[1] === undefined)
+                        throw new Error(`${label} must be JSON-safe: ${entry[0]} is undefined`);
+                    check(entry[1]);
+                }
+            }
+            seen.delete(node);
+            return;
+        }
+        throw new Error(`${label} must be JSON-safe: unsupported value of type ${typeof node}`);
+    };
+    check(value);
+    return JSON.parse(JSON.stringify(value));
+}
+export function createTransitionStore(options = {}) {
+    const now = options.now ?? (() => Date.now());
+    const recordsByEntity = new Map();
+    const idempotency = new Map();
+    const currentStatus = new Map();
+    const revisions = new Map();
+    const entityKey = (domain, entityId) => `${domain}\u0000${entityId}`;
+    return {
+        transition(input) {
+            assertNonEmptyString(input.domain, "Transition domain");
+            assertNonEmptyString(input.entityId, "Transition entityId");
+            assertNonEmptyString(input.owner, "Transition owner");
+            assertNonEmptyString(input.operationId, "Transition operationId");
+            assertNonEmptyString(input.toStatus, "Transition toStatus");
+            const evidence = validateEvidence(input.evidence, "Transition evidence");
+            const payload = validatePayload(input.payload, "Transition payload");
+            const key = `${entityKey(input.domain, input.entityId)}\u0000${input.operationId}\u0000${input.toStatus}`;
+            const existing = idempotency.get(key);
+            if (existing)
+                return { record: existing, deduped: true };
+            const entityKeyId = entityKey(input.domain, input.entityId);
+            const current = currentStatus.get(entityKeyId);
+            const fromStatus = input.fromStatus;
+            if ((current?.status ?? null) !== fromStatus) {
+                throw new Error(`Transition conflict: expected fromStatus ${JSON.stringify(current?.status ?? null)}, got ${JSON.stringify(fromStatus)}`);
+            }
+            const revision = (revisions.get(entityKeyId) ?? 0) + 1;
+            revisions.set(entityKeyId, revision);
+            const record = Object.freeze({
+                domain: input.domain,
+                entityId: input.entityId,
+                owner: input.owner,
+                fromStatus,
+                toStatus: input.toStatus,
+                operationId: input.operationId,
+                evidence: Object.freeze(evidence),
+                ...(payload === undefined ? {} : { payload }),
+                revision,
+                at: input.at ?? now(),
+            });
+            const log = recordsByEntity.get(entityKeyId) ?? [];
+            log.push(record);
+            recordsByEntity.set(entityKeyId, log);
+            currentStatus.set(entityKeyId, { status: input.toStatus, revision });
+            idempotency.set(key, record);
+            return { record, deduped: false };
+        },
+        currentStatus(domain, entityId) {
+            return currentStatus.get(entityKey(domain, entityId));
+        },
+        history(entityId) {
+            return Object.freeze([...recordsByEntity.entries()]
+                .filter(([entityKeyId]) => entityKeyId.endsWith(`\u0000${entityId}`))
+                .flatMap(([, log]) => log));
+        },
+        replay(history) {
+            for (const record of history) {
+                this.transition({
+                    domain: record.domain,
+                    entityId: record.entityId,
+                    owner: record.owner,
+                    fromStatus: record.fromStatus,
+                    toStatus: record.toStatus,
+                    operationId: record.operationId,
+                    evidence: record.evidence,
+                    payload: record.payload,
+                    at: record.at,
+                });
+            }
+        },
+        entities() {
+            return Object.freeze([...new Set([...currentStatus.keys()].map((key) => key.split("\u0000")[1]))]);
+        },
+    };
+}
+//# sourceMappingURL=state-store.js.map

package/dist/profile/state-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-store.js","sourceRoot":"","sources":["../../src/profile/state-store.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Generic transition/evidence/revision store (2.3a) — the domain-agnostic\n * contract base for Goal/Plan/Todo plugins.\n *\n * The store knows NOTHING about goal/plan/todo semantics. It only enforces:\n * - causality: a transition's `fromStatus` must equal the entity's current\n *   status (null = initial transition), otherwise an explicit conflict;\n * - idempotency: replaying the same (domain, entityId, operationId, toStatus)\n *   returns the existing record and never advances the revision;\n * - evidence: every transition carries structured evidence references;\n * - payload: transitions may carry an optional domain payload (e.g. a goal\n *   title) that is validated JSON and part of the replayable record;\n * - replay: the full history rebuilds the identical current state.\n */\nimport type { JsonValue } from \"@agent-forge/ai\";\n\nexport interface TransitionEvidenceRefV1 {\n\treadonly kind: string;\n\treadonly ref: string;\n\treadonly digest?: string;\n}\n\nexport interface TransitionRecordV1 {\n\treadonly domain: string;\n\treadonly entityId: string;\n\treadonly owner: string;\n\treadonly fromStatus: string | null;\n\treadonly toStatus: string;\n\treadonly operationId: string;\n\treadonly evidence: readonly TransitionEvidenceRefV1[];\n\treadonly payload?: JsonValue;\n\treadonly revision: number;\n\treadonly at: number;\n}\n\nexport interface TransitionInputV1 {\n\treadonly domain: string;\n\treadonly entityId: string;\n\treadonly owner: string;\n\treadonly fromStatus: string | null;\n\treadonly toStatus: string;\n\treadonly operationId: string;\n\treadonly evidence?: readonly TransitionEvidenceRefV1[];\n\treadonly payload?: JsonValue;\n\treadonly at?: number;\n}\n\nexport interface TransitionResultV1 {\n\treadonly record: TransitionRecordV1;\n\treadonly deduped: boolean;\n}\n\nfunction assertNonEmptyString(value: unknown, label: string): asserts value is string {\n\tif (typeof value !== \"string\" || value.trim().length === 0) throw new Error(`${label} must be a non-empty string`);\n}\n\nfunction validateEvidence(value: unknown, label: string): TransitionEvidenceRefV1[] {\n\tif (value === undefined) return [];\n\tif (!Array.isArray(value)) throw new Error(`${label} must be an array`);\n\treturn value.map((item, index) => {\n\t\tconst depLabel = `${label}[${index}]`;\n\t\tif (item === null || typeof item !== \"object\" || Array.isArray(item)) {\n\t\t\tthrow new Error(`${depLabel} must be a plain object`);\n\t\t}\n\t\tconst record = item as Record<string, unknown>;\n\t\tassertNonEmptyString(record.kind, `${depLabel}.kind`);\n\t\tassertNonEmptyString(record.ref, `${depLabel}.ref`);\n\t\tif (record.digest !== undefined) assertNonEmptyString(record.digest, `${depLabel}.digest`);\n\t\treturn Object.freeze({\n\t\t\tkind: record.kind,\n\t\t\tref: record.ref,\n\t\t\t...(record.digest === undefined ? {} : { digest: record.digest }),\n\t\t});\n\t});\n}\n\nfunction validatePayload(value: unknown, label: string): JsonValue | undefined {\n\tif (value === undefined) return undefined;\n\tconst seen = new Set<object>();\n\tconst check = (node: unknown): void => {\n\t\tif (node === null || typeof node === \"string\" || typeof node === \"boolean\") return;\n\t\tif (typeof node === \"number\") {\n\t\t\tif (!Number.isFinite(node)) throw new Error(`${label} must be JSON-safe: ${node} is not a finite number`);\n\t\t\treturn;\n\t\t}\n\t\tif (typeof node === \"object\") {\n\t\t\tif (seen.has(node)) throw new Error(`${label} must be JSON-safe: circular reference`);\n\t\t\tseen.add(node);\n\t\t\tif (Array.isArray(node)) {\n\t\t\t\tfor (const item of node) check(item);\n\t\t\t} else {\n\t\t\t\tconst proto = Object.getPrototypeOf(node) as unknown;\n\t\t\t\tif (proto !== Object.prototype && proto !== null) throw new Error(`${label} must be a plain object`);\n\t\t\t\tfor (const entry of Object.entries(node)) {\n\t\t\t\t\tif (entry[1] === undefined) throw new Error(`${label} must be JSON-safe: ${entry[0]} is undefined`);\n\t\t\t\t\tcheck(entry[1]);\n\t\t\t\t}\n\t\t\t}\n\t\t\tseen.delete(node);\n\t\t\treturn;\n\t\t}\n\t\tthrow new Error(`${label} must be JSON-safe: unsupported value of type ${typeof node}`);\n\t};\n\tcheck(value);\n\treturn JSON.parse(JSON.stringify(value)) as JsonValue;\n}\n\nexport interface TransitionStoreV1 {\n\ttransition(input: TransitionInputV1): TransitionResultV1;\n\tcurrentStatus(domain: string, entityId: string): { readonly status: string; readonly revision: number } | undefined;\n\thistory(entityId: string): readonly TransitionRecordV1[];\n\t/** Replays a history into a fresh store; the rebuilt state must be identical. */\n\treplay(history: readonly TransitionRecordV1[]): void;\n\tentities(): readonly string[];\n}\n\nexport function createTransitionStore(options: { readonly now?: () => number } = {}): TransitionStoreV1 {\n\tconst now = options.now ?? (() => Date.now());\n\tconst recordsByEntity = new Map<string, TransitionRecordV1[]>();\n\tconst idempotency = new Map<string, TransitionRecordV1>();\n\tconst currentStatus = new Map<string, { status: string; revision: number }>();\n\tconst revisions = new Map<string, number>();\n\n\tconst entityKey = (domain: string, entityId: string): string => `${domain}\\u0000${entityId}`;\n\n\treturn {\n\t\ttransition(input) {\n\t\t\tassertNonEmptyString(input.domain, \"Transition domain\");\n\t\t\tassertNonEmptyString(input.entityId, \"Transition entityId\");\n\t\t\tassertNonEmptyString(input.owner, \"Transition owner\");\n\t\t\tassertNonEmptyString(input.operationId, \"Transition operationId\");\n\t\t\tassertNonEmptyString(input.toStatus, \"Transition toStatus\");\n\t\t\tconst evidence = validateEvidence(input.evidence, \"Transition evidence\");\n\t\t\tconst payload = validatePayload(input.payload, \"Transition payload\");\n\t\t\tconst key = `${entityKey(input.domain, input.entityId)}\\u0000${input.operationId}\\u0000${input.toStatus}`;\n\n\t\t\tconst existing = idempotency.get(key);\n\t\t\tif (existing) return { record: existing, deduped: true };\n\n\t\t\tconst entityKeyId = entityKey(input.domain, input.entityId);\n\t\t\tconst current = currentStatus.get(entityKeyId);\n\t\t\tconst fromStatus = input.fromStatus;\n\t\t\tif ((current?.status ?? null) !== fromStatus) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Transition conflict: expected fromStatus ${JSON.stringify(current?.status ?? null)}, got ${JSON.stringify(fromStatus)}`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst revision = (revisions.get(entityKeyId) ?? 0) + 1;\n\t\t\trevisions.set(entityKeyId, revision);\n\t\t\tconst record: TransitionRecordV1 = Object.freeze({\n\t\t\t\tdomain: input.domain,\n\t\t\t\tentityId: input.entityId,\n\t\t\t\towner: input.owner,\n\t\t\t\tfromStatus,\n\t\t\t\ttoStatus: input.toStatus,\n\t\t\t\toperationId: input.operationId,\n\t\t\t\tevidence: Object.freeze(evidence),\n\t\t\t\t...(payload === undefined ? {} : { payload }),\n\t\t\t\trevision,\n\t\t\t\tat: input.at ?? now(),\n\t\t\t});\n\t\t\tconst log = recordsByEntity.get(entityKeyId) ?? [];\n\t\t\tlog.push(record);\n\t\t\trecordsByEntity.set(entityKeyId, log);\n\t\t\tcurrentStatus.set(entityKeyId, { status: input.toStatus, revision });\n\t\t\tidempotency.set(key, record);\n\t\t\treturn { record, deduped: false };\n\t\t},\n\t\tcurrentStatus(domain: string, entityId: string) {\n\t\t\treturn currentStatus.get(entityKey(domain, entityId));\n\t\t},\n\t\thistory(entityId: string) {\n\t\t\treturn Object.freeze(\n\t\t\t\t[...recordsByEntity.entries()]\n\t\t\t\t\t.filter(([entityKeyId]) => entityKeyId.endsWith(`\\u0000${entityId}`))\n\t\t\t\t\t.flatMap(([, log]) => log),\n\t\t\t);\n\t\t},\n\t\treplay(history) {\n\t\t\tfor (const record of history) {\n\t\t\t\tthis.transition({\n\t\t\t\t\tdomain: record.domain,\n\t\t\t\t\tentityId: record.entityId,\n\t\t\t\t\towner: record.owner,\n\t\t\t\t\tfromStatus: record.fromStatus,\n\t\t\t\t\ttoStatus: record.toStatus,\n\t\t\t\t\toperationId: record.operationId,\n\t\t\t\t\tevidence: record.evidence,\n\t\t\t\t\tpayload: record.payload,\n\t\t\t\t\tat: record.at,\n\t\t\t\t});\n\t\t\t}\n\t\t},\n\t\tentities() {\n\t\t\treturn Object.freeze([...new Set([...currentStatus.keys()].map((key) => key.split(\"\\u0000\")[1]!))]);\n\t\t},\n\t};\n}\n"]}

package/dist/profile/todo-plugin.d.ts

@@ -0,0 +1,37 @@
+import type { TransitionEvidenceRefV1, TransitionStoreV1 } from "./state-store.ts";
+export type TodoStatusV1 = "open" | "in_progress" | "completed" | "cancelled";
+export interface TodoV1 {
+    readonly todoId: string;
+    readonly owner: string;
+    readonly content: string;
+    readonly status: TodoStatusV1;
+    readonly evidence: readonly TransitionEvidenceRefV1[];
+    readonly revision: number;
+}
+export interface TodoPluginV1 {
+    createTodo(input: {
+        readonly todoId: string;
+        readonly owner: string;
+        readonly content: string;
+    }): TodoV1;
+    start(todoId: string, owner: string, options?: {
+        readonly operationId?: string;
+    }): TodoV1;
+    /** Rewrites the content while open/in_progress; the ledger keeps every version replayable. */
+    update(todoId: string, owner: string, content: string, options?: {
+        readonly operationId?: string;
+    }): TodoV1;
+    complete(todoId: string, owner: string, evidence?: readonly TransitionEvidenceRefV1[], options?: {
+        readonly operationId?: string;
+    }): TodoV1;
+    cancel(todoId: string, owner: string, reason?: string): TodoV1;
+    /** Restarts a cancelled todo back into open. */
+    reopen(todoId: string, owner: string, options?: {
+        readonly operationId?: string;
+    }): TodoV1;
+    get(todoId: string, owner: string): TodoV1 | undefined;
+}
+export declare function createTodoPlugin(options: {
+    readonly transitions: TransitionStoreV1;
+}): TodoPluginV1;
+//# sourceMappingURL=todo-plugin.d.ts.map

package/dist/profile/todo-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"todo-plugin.d.ts","sourceRoot":"","sources":["../../src/profile/todo-plugin.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEnF,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,aAAa,GAAG,WAAW,GAAG,WAAW,CAAC;AAE9E,MAAM,WAAW,MAAM;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC5B,UAAU,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC;IACzG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC;IAC1F,8FAA8F;IAC9F,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC;IAC5G,QAAQ,CACP,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,SAAS,uBAAuB,EAAE,EAC7C,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GACzC,MAAM,CAAC;IACV,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/D,gDAAgD;IAChD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC;IAC3F,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACvD;AAyBD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE;IAAE,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAA;CAAE,GAAG,YAAY,CAuInG","sourcesContent":["/**\n * Todo plugin (2.3d) — Todo content lifecycle with cancellation and restart\n * over the 2.3a transition store.\n *\n * Status graph: null → open → in_progress → completed; open/in_progress →\n * cancelled; cancelled → open (restart). Content updates rewrite the payload\n * in place while the todo is open/in_progress, and every terminal transition\n * stays replayable from the ledger. The plugin holds NO shadow state —\n * content and status are always derived from the transition history.\n */\nimport type { JsonValue } from \"@agent-forge/ai\";\nimport type { TransitionEvidenceRefV1, TransitionStoreV1 } from \"./state-store.ts\";\n\nexport type TodoStatusV1 = \"open\" | \"in_progress\" | \"completed\" | \"cancelled\";\n\nexport interface TodoV1 {\n\treadonly todoId: string;\n\treadonly owner: string;\n\treadonly content: string;\n\treadonly status: TodoStatusV1;\n\treadonly evidence: readonly TransitionEvidenceRefV1[];\n\treadonly revision: number;\n}\n\nexport interface TodoPluginV1 {\n\tcreateTodo(input: { readonly todoId: string; readonly owner: string; readonly content: string }): TodoV1;\n\tstart(todoId: string, owner: string, options?: { readonly operationId?: string }): TodoV1;\n\t/** Rewrites the content while open/in_progress; the ledger keeps every version replayable. */\n\tupdate(todoId: string, owner: string, content: string, options?: { readonly operationId?: string }): TodoV1;\n\tcomplete(\n\t\ttodoId: string,\n\t\towner: string,\n\t\tevidence?: readonly TransitionEvidenceRefV1[],\n\t\toptions?: { readonly operationId?: string },\n\t): TodoV1;\n\tcancel(todoId: string, owner: string, reason?: string): TodoV1;\n\t/** Restarts a cancelled todo back into open. */\n\treopen(todoId: string, owner: string, options?: { readonly operationId?: string }): TodoV1;\n\tget(todoId: string, owner: string): TodoV1 | undefined;\n}\n\ninterface TodoPayloadV1 {\n\treadonly content: string;\n\treadonly cancelReason?: string;\n}\n\n/** FNV-1a 32-bit — a short deterministic operationId suffix for content updates. */\nfunction contentHash(content: string): string {\n\tlet hash = 0x811c9dc5;\n\tfor (let index = 0; index < content.length; index += 1) {\n\t\thash ^= content.charCodeAt(index);\n\t\thash = Math.imul(hash, 0x01000193);\n\t}\n\treturn (hash >>> 0).toString(36);\n}\n\nfunction todoPayloadOf(record: { readonly payload?: unknown }): Partial<TodoPayloadV1> | undefined {\n\tconst payload = record.payload;\n\tif (payload !== null && typeof payload === \"object\" && !Array.isArray(payload)) {\n\t\treturn payload as Partial<TodoPayloadV1>;\n\t}\n\treturn undefined;\n}\n\nexport function createTodoPlugin(options: { readonly transitions: TransitionStoreV1 }): TodoPluginV1 {\n\tconst transitions = options.transitions;\n\n\tconst todoHistory = (todoId: string, owner: string) =>\n\t\ttransitions.history(todoId).filter((record) => record.domain === \"todo\" && record.owner === owner);\n\n\tconst current = (todoId: string, owner: string): { status: TodoStatusV1; revision: number } | undefined => {\n\t\tconst state = transitions.currentStatus(\"todo\", todoId);\n\t\tif (state === undefined || todoHistory(todoId, owner).length === 0) return undefined;\n\t\treturn { status: state.status as TodoStatusV1, revision: state.revision };\n\t};\n\n\tconst todoGet = (todoId: string, owner: string): TodoV1 | undefined => {\n\t\tconst state = current(todoId, owner);\n\t\tif (!state) return undefined;\n\t\tconst history = todoHistory(todoId, owner);\n\t\tconst content = [...history]\n\t\t\t.reverse()\n\t\t\t.map((record) => todoPayloadOf(record)?.content)\n\t\t\t.find((value): value is string => typeof value === \"string\");\n\t\tconst lastEvidence = [...history].reverse().find((record) => record.evidence.length > 0)?.evidence ?? [];\n\t\treturn {\n\t\t\ttodoId,\n\t\t\towner,\n\t\t\t// v8 ignore next -- createTodo 恒写入 content payload，标题扫描必命中\n\t\t\tcontent: content ?? \"\",\n\t\t\tstatus: state.status,\n\t\t\tevidence: lastEvidence,\n\t\t\trevision: state.revision,\n\t\t};\n\t};\n\n\t/** A retried transition with an already-applied operationId returns the existing state instead of conflicting. */\n\tconst replayedTodo = (\n\t\ttodoId: string,\n\t\towner: string,\n\t\ttoStatus: TodoStatusV1,\n\t\toperationId?: string,\n\t): TodoV1 | undefined => {\n\t\tif (!operationId) return undefined;\n\t\tconst applied = todoHistory(todoId, owner).some(\n\t\t\t(record) => record.toStatus === toStatus && record.operationId === operationId,\n\t\t);\n\t\treturn applied ? todoGet(todoId, owner) : undefined;\n\t};\n\n\tconst transitionTodo = (\n\t\ttodoId: string,\n\t\towner: string,\n\t\tfromStatus: TodoStatusV1 | null,\n\t\ttoStatus: TodoStatusV1,\n\t\ttodoOptions: {\n\t\t\treadonly evidence?: readonly TransitionEvidenceRefV1[];\n\t\t\treadonly payload?: TodoPayloadV1;\n\t\t\treadonly operationId?: string;\n\t\t},\n\t): TodoV1 => {\n\t\ttransitions.transition({\n\t\t\tdomain: \"todo\",\n\t\t\tentityId: todoId,\n\t\t\towner,\n\t\t\tfromStatus,\n\t\t\ttoStatus,\n\t\t\toperationId: todoOptions.operationId ?? `${toStatus}:${todoId}`,\n\t\t\tevidence: todoOptions.evidence,\n\t\t\tpayload: todoOptions.payload as JsonValue | undefined,\n\t\t});\n\t\treturn todoGet(todoId, owner)!;\n\t};\n\n\tconst requireStatus = (todoId: string, owner: string, allowed: readonly TodoStatusV1[]): TodoV1 => {\n\t\tconst todo = todoGet(todoId, owner);\n\t\tif (!todo || !allowed.includes(todo.status)) {\n\t\t\tthrow new Error(`Todo ${todoId} must be ${allowed.join(\"/\")} (current: ${todo?.status ?? \"missing\"})`);\n\t\t}\n\t\treturn todo;\n\t};\n\n\treturn {\n\t\tcreateTodo({ todoId, owner, content }) {\n\t\t\tif (content.trim().length === 0) throw new Error(\"Todo content must be a non-empty string\");\n\t\t\treturn transitionTodo(todoId, owner, null, \"open\", {\n\t\t\t\tpayload: { content },\n\t\t\t\toperationId: `create:${todoId}`,\n\t\t\t});\n\t\t},\n\t\tstart(todoId, owner, startOptions) {\n\t\t\tconst replayed = replayedTodo(todoId, owner, \"in_progress\", startOptions?.operationId);\n\t\t\tif (replayed) return replayed;\n\t\t\trequireStatus(todoId, owner, [\"open\"]);\n\t\t\treturn transitionTodo(todoId, owner, \"open\", \"in_progress\", { operationId: startOptions?.operationId });\n\t\t},\n\t\tupdate(todoId, owner, content, updateOptions) {\n\t\t\tif (content.trim().length === 0) throw new Error(\"Todo content must be a non-empty string\");\n\t\t\tconst replayed = replayedTodo(\n\t\t\t\ttodoId,\n\t\t\t\towner,\n\t\t\t\ttodoGet(todoId, owner)?.status ?? \"open\",\n\t\t\t\tupdateOptions?.operationId,\n\t\t\t);\n\t\t\tif (replayed) return replayed;\n\t\t\tconst todo = requireStatus(todoId, owner, [\"open\", \"in_progress\"]);\n\t\t\treturn transitionTodo(todoId, owner, todo.status, todo.status, {\n\t\t\t\tpayload: { content },\n\t\t\t\toperationId: updateOptions?.operationId ?? `update:${todoId}:${contentHash(content)}`,\n\t\t\t});\n\t\t},\n\t\tcomplete(todoId, owner, evidence, completeOptions) {\n\t\t\tconst replayed = replayedTodo(todoId, owner, \"completed\", completeOptions?.operationId);\n\t\t\tif (replayed) return replayed;\n\t\t\trequireStatus(todoId, owner, [\"in_progress\"]);\n\t\t\treturn transitionTodo(todoId, owner, \"in_progress\", \"completed\", {\n\t\t\t\tevidence: evidence ?? [],\n\t\t\t\toperationId: completeOptions?.operationId,\n\t\t\t});\n\t\t},\n\t\tcancel(todoId, owner, reason) {\n\t\t\tconst todo = requireStatus(todoId, owner, [\"open\", \"in_progress\"]);\n\t\t\tif (reason !== undefined && reason.trim().length === 0) {\n\t\t\t\tthrow new Error(\"Todo cancel reason must be a non-empty string when provided\");\n\t\t\t}\n\t\t\treturn transitionTodo(todoId, owner, todo.status, \"cancelled\", {\n\t\t\t\t...(reason === undefined ? {} : { payload: { content: todo.content, cancelReason: reason } }),\n\t\t\t});\n\t\t},\n\t\treopen(todoId, owner, reopenOptions) {\n\t\t\tconst replayed = replayedTodo(todoId, owner, \"open\", reopenOptions?.operationId);\n\t\t\tif (replayed) return replayed;\n\t\t\trequireStatus(todoId, owner, [\"cancelled\"]);\n\t\t\treturn transitionTodo(todoId, owner, \"cancelled\", \"open\", { operationId: reopenOptions?.operationId });\n\t\t},\n\t\tget(todoId, owner) {\n\t\t\treturn todoGet(todoId, owner);\n\t\t},\n\t};\n}\n"]}