limen-ai 1.0.0

package/dist/orchestration/tasks/task_graph.js

@@ -0,0 +1,204 @@
+/**
+ * Task Graph Engine -- DAG validation with Kahn's algorithm.
+ * S ref: S16 (propose_task_graph), S7 (Task lifecycle), I-20 (task limits),
+ *        I-24 (goal anchoring -- objectiveAlignment required)
+ *
+ * Phase: 3 (Orchestration)
+ * Implements: Graph validation (acyclicity via Kahn's), task creation,
+ *             plan versioning, capability validation.
+ *
+ * SD-14: Kahn's algorithm chosen for O(V+E) acyclicity proof + topological
+ *        ordering as byproduct. Both Alpha and Bravo converged on this.
+ */
+import { MISSION_TREE_DEFAULTS, generateId } from '../interfaces/orchestration.js';
+import { getTask, getActiveTasks, transitionTask, areDependenciesMet } from './task_store.js';
+/**
+ * SD-14: Kahn's algorithm for DAG acyclicity verification.
+ * Returns topological order if DAG, null if cycle detected.
+ * O(V+E) time complexity.
+ */
+export function kahnsAlgorithm(tasks, dependencies) {
+    const taskIds = new Set(tasks.map(t => t.id));
+    const inDegree = new Map();
+    const adjacency = new Map();
+    // Initialize
+    for (const id of taskIds) {
+        inDegree.set(id, 0);
+        adjacency.set(id, []);
+    }
+    // Build graph: from -> to means "to depends on from"
+    for (const dep of dependencies) {
+        const fromStr = dep.from;
+        const toStr = dep.to;
+        const adj = adjacency.get(fromStr);
+        if (adj) {
+            adj.push(toStr);
+        }
+        inDegree.set(toStr, (inDegree.get(toStr) ?? 0) + 1);
+    }
+    // Collect nodes with in-degree 0
+    const queue = [];
+    for (const [id, degree] of inDegree.entries()) {
+        if (degree === 0) {
+            queue.push(id);
+        }
+    }
+    const sorted = [];
+    while (queue.length > 0) {
+        const node = queue.shift();
+        sorted.push(node);
+        const neighbors = adjacency.get(node) ?? [];
+        for (const neighbor of neighbors) {
+            const newDegree = (inDegree.get(neighbor) ?? 1) - 1;
+            inDegree.set(neighbor, newDegree);
+            if (newDegree === 0) {
+                queue.push(neighbor);
+            }
+        }
+    }
+    // If we didn't process all nodes, there's a cycle
+    if (sorted.length !== taskIds.size) {
+        return null;
+    }
+    return sorted;
+}
+/**
+ * S16: Create the task graph engine module.
+ * Factory function returns frozen object per C-07.
+ */
+export function createTaskGraphEngine() {
+    /** S16: Validate and install a new task graph */
+    function proposeGraph(deps, _ctx, input) {
+        // I-24: objectiveAlignment required and non-empty
+        if (!input.objectiveAlignment || input.objectiveAlignment.trim().length === 0) {
+            return { ok: false, error: { code: 'MISSION_NOT_ACTIVE', message: 'objectiveAlignment is required and must be non-empty (I-24)', spec: 'I-24' } };
+        }
+        // Verify mission exists and is in valid state
+        const mission = deps.conn.get('SELECT state, plan_version, capabilities, constraints_json FROM core_missions WHERE id = ?', [input.missionId]);
+        if (!mission) {
+            return { ok: false, error: { code: 'MISSION_NOT_ACTIVE', message: `Mission ${input.missionId} not found`, spec: 'S16' } };
+        }
+        // Must be in a state that allows planning
+        const validStates = ['CREATED', 'PLANNING', 'EXECUTING'];
+        if (!validStates.includes(mission.state)) {
+            return { ok: false, error: { code: 'MISSION_NOT_ACTIVE', message: `Mission in state ${mission.state}, must be CREATED/PLANNING/EXECUTING`, spec: 'S16' } };
+        }
+        const constraints = JSON.parse(mission.constraints_json);
+        const maxTasks = constraints.maxTasks ?? MISSION_TREE_DEFAULTS.maxTasks;
+        const maxPlanRevisions = MISSION_TREE_DEFAULTS.maxPlanRevisions;
+        // FM-17: Task limit
+        if (input.tasks.length > maxTasks) {
+            return { ok: false, error: { code: 'TASK_LIMIT_EXCEEDED', message: `${input.tasks.length} tasks exceeds maxTasks ${maxTasks}`, spec: 'FM-17' } };
+        }
+        // FM-17: Plan revision limit
+        if (mission.plan_version >= maxPlanRevisions) {
+            return { ok: false, error: { code: 'PLAN_REVISION_LIMIT', message: `Plan version ${mission.plan_version} >= max ${maxPlanRevisions}`, spec: 'FM-17' } };
+        }
+        // Validate task IDs are unique
+        const taskIds = new Set(input.tasks.map(t => t.id));
+        if (taskIds.size !== input.tasks.length) {
+            return { ok: false, error: { code: 'INVALID_DEPENDENCY', message: 'Duplicate task IDs in graph', spec: 'S16' } };
+        }
+        // Validate dependency references exist in this graph
+        for (const dep of input.dependencies) {
+            if (!taskIds.has(dep.from)) {
+                return { ok: false, error: { code: 'INVALID_DEPENDENCY', message: `Dependency from ${dep.from} references non-existent task`, spec: 'S16' } };
+            }
+            if (!taskIds.has(dep.to)) {
+                return { ok: false, error: { code: 'INVALID_DEPENDENCY', message: `Dependency to ${dep.to} references non-existent task`, spec: 'S16' } };
+            }
+            // Self-dependency (also caught by SQL CHECK but validate here too)
+            if (dep.from === dep.to) {
+                return { ok: false, error: { code: 'CYCLE_DETECTED', message: `Self-dependency: ${dep.from} -> ${dep.to}`, spec: 'S16' } };
+            }
+        }
+        // SD-14: Kahn's algorithm -- acyclicity proof
+        const topologicalOrder = kahnsAlgorithm(input.tasks, input.dependencies);
+        if (topologicalOrder === null) {
+            return { ok: false, error: { code: 'CYCLE_DETECTED', message: 'Task graph contains a cycle', spec: 'S16' } };
+        }
+        // I-22: Capability check -- all task capabilities must be in mission capabilities
+        const missionCaps = new Set(JSON.parse(mission.capabilities));
+        for (const task of input.tasks) {
+            for (const cap of task.capabilitiesRequired) {
+                if (!missionCaps.has(cap)) {
+                    return { ok: false, error: { code: 'CAPABILITY_VIOLATION', message: `Task ${task.id} requires capability '${cap}' not in mission`, spec: 'I-22' } };
+                }
+            }
+        }
+        // Budget check -- sum of estimated tokens must not exceed remaining
+        const totalEstimated = input.tasks.reduce((sum, t) => sum + t.estimatedTokens, 0);
+        const resource = deps.conn.get('SELECT token_remaining FROM core_resources WHERE mission_id = ?', [input.missionId]);
+        if (resource && totalEstimated > resource.token_remaining) {
+            return { ok: false, error: { code: 'BUDGET_EXCEEDED', message: `Estimated ${totalEstimated} tokens exceeds remaining ${resource.token_remaining}`, spec: 'S11' } };
+        }
+        // F-02 fix: Inherit tenant_id from mission (T-4 cross-tenant isolation)
+        const missionTenantId = (deps.conn.get('SELECT tenant_id FROM core_missions WHERE id = ?', [input.missionId])?.tenant_id ?? null);
+        const graphId = generateId();
+        const newPlanVersion = mission.plan_version + 1;
+        const now = deps.time.nowISO();
+        deps.conn.transaction(() => {
+            // Deactivate previous active graph and cancel its PENDING tasks
+            const prevGraph = deps.conn.get('SELECT id FROM core_task_graphs WHERE mission_id = ? AND is_active = 1', [input.missionId]);
+            if (prevGraph) {
+                deps.conn.run('UPDATE core_task_graphs SET is_active = 0 WHERE id = ?', [prevGraph.id]);
+                deps.conn.run(`UPDATE core_tasks SET state = 'CANCELLED', updated_at = ?, completed_at = ? WHERE graph_id = ? AND state = 'PENDING'`, [now, now, prevGraph.id]);
+            }
+            // Insert new graph metadata
+            // FM-10: tenant_id inherited from mission (T-4 cross-tenant isolation)
+            deps.conn.run('INSERT INTO core_task_graphs (id, mission_id, tenant_id, version, objective_alignment, is_active, created_at) VALUES (?, ?, ?, ?, ?, 1, ?)', [graphId, input.missionId, missionTenantId, newPlanVersion, input.objectiveAlignment, now]);
+            // Insert tasks
+            for (const task of input.tasks) {
+                deps.conn.run(`INSERT INTO core_tasks (id, mission_id, tenant_id, graph_id, description,
+           execution_mode, estimated_tokens, capabilities_required, state,
+           created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'PENDING', ?, ?)`, [
+                    task.id,
+                    input.missionId,
+                    missionTenantId, // F-02: tenant_id inherited from mission (T-4)
+                    graphId,
+                    task.description,
+                    task.executionMode,
+                    task.estimatedTokens,
+                    JSON.stringify(task.capabilitiesRequired),
+                    now,
+                    now,
+                ]);
+            }
+            // Insert dependencies
+            // FM-10: tenant_id inherited from mission (T-4 cross-tenant isolation)
+            for (const dep of input.dependencies) {
+                deps.conn.run('INSERT INTO core_task_dependencies (graph_id, from_task, to_task, tenant_id) VALUES (?, ?, ?, ?)', [graphId, dep.from, dep.to, missionTenantId]);
+            }
+            // Update mission plan version and state
+            deps.conn.run(`UPDATE core_missions SET plan_version = ?, state = CASE WHEN state = 'CREATED' THEN 'PLANNING' ELSE state END, updated_at = ? WHERE id = ?`, [newPlanVersion, now, input.missionId]);
+            // I-03: Audit entry
+            deps.audit.append(deps.conn, {
+                tenantId: missionTenantId,
+                actorType: 'system',
+                actorId: 'orchestrator',
+                operation: 'propose_task_graph',
+                resourceType: 'task_graph',
+                resourceId: graphId,
+                detail: { missionId: input.missionId, taskCount: input.tasks.length, planVersion: newPlanVersion },
+            });
+        });
+        return {
+            ok: true,
+            value: {
+                graphId,
+                planVersion: newPlanVersion,
+                taskCount: input.tasks.length,
+                validationWarnings: [], // CQ-09 fix: S16 spec output includes validationWarnings
+            },
+        };
+    }
+    return Object.freeze({
+        proposeGraph,
+        getTask,
+        getActiveTasks,
+        transitionTask,
+        areDependenciesMet,
+    });
+}
+//# sourceMappingURL=task_graph.js.map

package/dist/orchestration/tasks/task_graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task_graph.js","sourceRoot":"","sources":["../../../src/orchestration/tasks/task_graph.ts"],"names":[],"mappings":"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"}

package/dist/orchestration/tasks/task_store.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Task Store -- Task lifecycle and state machine.
+ * S ref: S7 (Task lifecycle), I-20 (task limits)
+ *
+ * Phase: 3 (Orchestration)
+ * Implements: Task CRUD, state transitions with validation.
+ */
+import type { Result, MissionId, TaskId } from '../../kernel/interfaces/index.js';
+import type { OrchestrationDeps, Task, TaskState } from '../interfaces/orchestration.js';
+/** S7: Get task by id */
+export declare function getTask(deps: OrchestrationDeps, taskId: TaskId): Result<Task>;
+/** S7: Get tasks for a mission's active graph */
+export declare function getActiveTasks(deps: OrchestrationDeps, missionId: MissionId): Result<Task[]>;
+/** S7: Transition task state with validation */
+export declare function transitionTask(deps: OrchestrationDeps, taskId: TaskId, from: TaskState, to: TaskState): Result<void>;
+/** S16: Check if all dependencies for a task are satisfied */
+export declare function areDependenciesMet(deps: OrchestrationDeps, taskId: TaskId): Result<boolean>;
+//# sourceMappingURL=task_store.d.ts.map

package/dist/orchestration/tasks/task_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task_store.d.ts","sourceRoot":"","sources":["../../../src/orchestration/tasks/task_store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAY,MAAM,kCAAkC,CAAC;AAC5F,OAAO,KAAK,EAAE,iBAAiB,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAwBzF,yBAAyB;AACzB,wBAAgB,OAAO,CAAC,IAAI,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,CAS7E;AAED,iDAAiD;AACjD,wBAAgB,cAAc,CAAC,IAAI,EAAE,iBAAiB,EAAE,SAAS,EAAE,SAAS,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,CAe5F;AAED,gDAAgD;AAChD,wBAAgB,cAAc,CAC5B,IAAI,EAAE,iBAAiB,EACvB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,SAAS,EACf,EAAE,EAAE,SAAS,GACZ,MAAM,CAAC,IAAI,CAAC,CAsCd;AAED,8DAA8D;AAC9D,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,CAgC3F"}

package/dist/orchestration/tasks/task_store.js

@@ -0,0 +1,99 @@
+/**
+ * Task Store -- Task lifecycle and state machine.
+ * S ref: S7 (Task lifecycle), I-20 (task limits)
+ *
+ * Phase: 3 (Orchestration)
+ * Implements: Task CRUD, state transitions with validation.
+ */
+import { TASK_TRANSITIONS } from '../interfaces/orchestration.js';
+/** S7: Parse task row to domain object */
+function rowToTask(row) {
+    return {
+        id: row['id'],
+        missionId: row['mission_id'],
+        tenantId: (row['tenant_id'] ?? null),
+        graphId: row['graph_id'],
+        description: row['description'],
+        executionMode: row['execution_mode'],
+        estimatedTokens: row['estimated_tokens'],
+        capabilitiesRequired: JSON.parse(row['capabilities_required']),
+        state: row['state'],
+        assignedAgent: (row['assigned_agent'] ?? null),
+        retryCount: row['retry_count'],
+        maxRetries: row['max_retries'],
+        createdAt: row['created_at'],
+        updatedAt: row['updated_at'],
+        completedAt: (row['completed_at'] ?? null),
+    };
+}
+/** S7: Get task by id */
+export function getTask(deps, taskId) {
+    const row = deps.conn.get('SELECT * FROM core_tasks WHERE id = ?', [taskId]);
+    if (!row) {
+        return { ok: false, error: { code: 'NOT_FOUND', message: `Task ${taskId} not found`, spec: 'S7' } };
+    }
+    return { ok: true, value: rowToTask(row) };
+}
+/** S7: Get tasks for a mission's active graph */
+export function getActiveTasks(deps, missionId) {
+    // Find active graph
+    const graph = deps.conn.get('SELECT id FROM core_task_graphs WHERE mission_id = ? AND is_active = 1', [missionId]);
+    if (!graph) {
+        return { ok: true, value: [] };
+    }
+    const rows = deps.conn.query('SELECT * FROM core_tasks WHERE graph_id = ?', [graph.id]);
+    return { ok: true, value: rows.map(rowToTask) };
+}
+/** S7: Transition task state with validation */
+export function transitionTask(deps, taskId, from, to) {
+    const validTargets = TASK_TRANSITIONS[from];
+    if (!validTargets.includes(to)) {
+        return { ok: false, error: { code: 'INVALID_TRANSITION', message: `Cannot transition task from ${from} to ${to}`, spec: 'S7' } };
+    }
+    const now = deps.time.nowISO();
+    const isTerminal = to === 'COMPLETED' || to === 'FAILED' || to === 'CANCELLED';
+    // Debt 3: Derive tenant_id from task for audit trail
+    const taskRow = deps.conn.get('SELECT tenant_id FROM core_tasks WHERE id = ?', [taskId]);
+    const taskTenantId = (taskRow?.tenant_id ?? null);
+    deps.conn.transaction(() => {
+        const result = deps.conn.run(`UPDATE core_tasks SET state = ?, updated_at = ?${isTerminal ? ', completed_at = ?' : ''} WHERE id = ? AND state = ?`, isTerminal ? [to, now, now, taskId, from] : [to, now, taskId, from]);
+        if (result.changes === 0) {
+            throw new Error(`Task ${taskId} not in state ${from}`);
+        }
+        deps.audit.append(deps.conn, {
+            tenantId: taskTenantId,
+            actorType: 'system',
+            actorId: 'orchestrator',
+            operation: 'task_transition',
+            resourceType: 'task',
+            resourceId: taskId,
+            detail: { from, to },
+        });
+    });
+    return { ok: true, value: undefined };
+}
+/** S16: Check if all dependencies for a task are satisfied */
+export function areDependenciesMet(deps, taskId) {
+    const task = deps.conn.get('SELECT graph_id FROM core_tasks WHERE id = ?', [taskId]);
+    if (!task) {
+        return { ok: false, error: { code: 'NOT_FOUND', message: `Task ${taskId} not found`, spec: 'S16' } };
+    }
+    // Find all tasks that this task depends on (from_task -> to_task means to_task depends on from_task)
+    const depRows = deps.conn.query('SELECT from_task FROM core_task_dependencies WHERE graph_id = ? AND to_task = ?', [task.graph_id, taskId]);
+    if (depRows.length === 0) {
+        return { ok: true, value: true };
+    }
+    // Check all dependencies are COMPLETED
+    for (const dep of depRows) {
+        const depTask = deps.conn.get('SELECT state FROM core_tasks WHERE id = ?', [dep.from_task]);
+        if (!depTask) {
+            // Debt 2: Missing dependency task is data corruption — do not silently treat as "not met"
+            return { ok: false, error: { code: 'NOT_FOUND', message: `Dependency task ${dep.from_task} not found — graph references phantom task`, spec: 'S16' } };
+        }
+        if (depTask.state !== 'COMPLETED') {
+            return { ok: true, value: false };
+        }
+    }
+    return { ok: true, value: true };
+}
+//# sourceMappingURL=task_store.js.map

package/dist/orchestration/tasks/task_store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task_store.js","sourceRoot":"","sources":["../../../src/orchestration/tasks/task_store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAElE,0CAA0C;AAC1C,SAAS,SAAS,CAAC,GAA4B;IAC7C,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,IAAI,CAAW;QACvB,SAAS,EAAE,GAAG,CAAC,YAAY,CAAc;QACzC,QAAQ,EAAE,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,IAAI,CAAqB;QACxD,OAAO,EAAE,GAAG,CAAC,UAAU,CAAW;QAClC,WAAW,EAAE,GAAG,CAAC,aAAa,CAAW;QACzC,aAAa,EAAE,GAAG,CAAC,gBAAgB,CAA0B;QAC7D,eAAe,EAAE,GAAG,CAAC,kBAAkB,CAAW;QAClD,oBAAoB,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,uBAAuB,CAAW,CAAa;QACpF,KAAK,EAAE,GAAG,CAAC,OAAO,CAAc;QAChC,aAAa,EAAE,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,IAAI,CAA0B;QACvE,UAAU,EAAE,GAAG,CAAC,aAAa,CAAW;QACxC,UAAU,EAAE,GAAG,CAAC,aAAa,CAAW;QACxC,SAAS,EAAE,GAAG,CAAC,YAAY,CAAW;QACtC,SAAS,EAAE,GAAG,CAAC,YAAY,CAAW;QACtC,WAAW,EAAE,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,IAAI,CAAkB;KAC5D,CAAC;AACJ,CAAC;AAED,yBAAyB;AACzB,MAAM,UAAU,OAAO,CAAC,IAAuB,EAAE,MAAc;IAC7D,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CACvB,uCAAuC,EACvC,CAAC,MAAM,CAAC,CACT,CAAC;IACF,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,MAAM,YAAY,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC;IACtG,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;AAC7C,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,cAAc,CAAC,IAAuB,EAAE,SAAoB;IAC1E,oBAAoB;IACpB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CACzB,wEAAwE,EACxE,CAAC,SAAS,CAAC,CACZ,CAAC;IACF,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IACjC,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAC1B,6CAA6C,EAC7C,CAAC,KAAK,CAAC,EAAE,CAAC,CACX,CAAC;IACF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;AAClD,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,cAAc,CAC5B,IAAuB,EACvB,MAAc,EACd,IAAe,EACf,EAAa;IAEb,MAAM,YAAY,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;QAC/B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,oBAAoB,EAAE,OAAO,EAAE,+BAA+B,IAAI,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC;IACnI,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IAC/B,MAAM,UAAU,GAAG,EAAE,KAAK,WAAW,IAAI,EAAE,KAAK,QAAQ,IAAI,EAAE,KAAK,WAAW,CAAC;IAE/E,qDAAqD;IACrD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAC3B,+CAA+C,EAC/C,CAAC,MAAM,CAAC,CACT,CAAC;IACF,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,SAAS,IAAI,IAAI,CAAoB,CAAC;IAErE,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE;QACzB,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAC1B,kDAAkD,UAAU,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,6BAA6B,EACrH,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,CACpE,CAAC;QAEF,IAAI,MAAM,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,QAAQ,MAAM,iBAAiB,IAAI,EAAE,CAAC,CAAC;QACzD,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE;YAC3B,QAAQ,EAAE,YAAY;YACtB,SAAS,EAAE,QAAQ;YACnB,OAAO,EAAE,cAAc;YACvB,SAAS,EAAE,iBAAiB;YAC5B,YAAY,EAAE,MAAM;YACpB,UAAU,EAAE,MAAM;YAClB,MAAM,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;SACrB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AACxC,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,kBAAkB,CAAC,IAAuB,EAAE,MAAc;IACxE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAuB,8CAA8C,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3G,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,MAAM,YAAY,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;IACvG,CAAC;IAED,qGAAqG;IACrG,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAC7B,iFAAiF,EACjF,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CACxB,CAAC;IAEF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACnC,CAAC;IAED,uCAAuC;IACvC,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAC3B,2CAA2C,EAC3C,CAAC,GAAG,CAAC,SAAS,CAAC,CAChB,CAAC;QACF,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,0FAA0F;YAC1F,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,mBAAmB,GAAG,CAAC,SAAS,4CAA4C,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACzJ,CAAC;QACD,IAAI,OAAO,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;YAClC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QACpC,CAAC;IACH,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACnC,CAAC"}

package/dist/reference-agent/artifact_manager.d.ts

@@ -0,0 +1,119 @@
+/**
+ * ArtifactManager -- workspace management for artifacts.
+ * S ref: S18 (create_artifact), S19 (read_artifact),
+ *        SD-01 (lifecycle-phase grouping)
+ *
+ * Phase: 5 (Reference Agent)
+ * Implements: SDD §10 Build Order Step 3 (ArtifactManager)
+ *
+ * The ArtifactManager is responsible for:
+ *   1. Creating artifacts via SC-4 (create_artifact)
+ *   2. Reading artifacts via SC-5 (read_artifact)
+ *   3. Tracking artifact IDs for result submission
+ *   4. Managing artifact versioning (parentArtifactId for revisions)
+ *
+ * I-19: The manager never mutates artifacts after creation. Revisions
+ * create new versions via parentArtifactId, not by modifying existing ones.
+ *
+ * I-23: All reads go through read_artifact, creating proper dependency edges.
+ * The manager never caches content to bypass dependency tracking.
+ *
+ * Invariants enforced: I-19 (artifact immutability),
+ *                      I-21 (reads only ACTIVE artifacts),
+ *                      I-23 (dependency tracking via read_artifact)
+ * Failure modes defended: FM-15 (artifact entropy -- purposeful creation)
+ */
+import type { MissionId, ArtifactId, ArtifactCreateOutput, ArtifactReadOutput, AgentExecutionState } from './reference_agent.types.js';
+import { SystemCallClient } from './system_call_client.js';
+/**
+ * SD-01: ArtifactManager groups create_artifact + read_artifact.
+ * These are the "workspace" calls that manage OUTPUT during execution.
+ *
+ * FM-15 defense: The manager creates artifacts purposefully:
+ *   - One artifact per task output (not duplicates)
+ *   - Uses parentArtifactId for revisions (not new entries)
+ *   - Reads only ACTIVE artifacts (I-21)
+ */
+export declare class ArtifactManager {
+    private readonly client;
+    constructor(client: SystemCallClient);
+    /**
+     * §18, SC-4: Create an artifact from task output.
+     *
+     * I-19: Once created, the artifact is immutable. Revisions create
+     * new versions via parentArtifactId.
+     *
+     * FM-15: Creates one artifact per task output. Does not create
+     * duplicates or unnecessary artifacts.
+     *
+     * @param missionId - The mission this artifact belongs to
+     * @param name - Descriptive name for the artifact
+     * @param type - Artifact type (report, data, code, analysis, image, raw)
+     * @param format - Content format (markdown, json, csv, python, sql, html)
+     * @param content - The artifact content
+     * @param sourceTaskId - The task that produced this artifact
+     * @param parentArtifactId - Parent artifact for revisions (null for new)
+     * @param metadata - Additional metadata
+     * @param state - Agent execution state (for tracking)
+     * @returns ArtifactCreateOutput with artifactId and version
+     */
+    createArtifact(missionId: MissionId, name: string, type: 'report' | 'data' | 'code' | 'analysis' | 'image' | 'raw', format: 'markdown' | 'json' | 'csv' | 'python' | 'sql' | 'html', content: string | Buffer, sourceTaskId: string, parentArtifactId: ArtifactId | undefined, metadata: Record<string, unknown>, state: AgentExecutionState): Promise<ArtifactCreateOutput>;
+    /**
+     * §19, SC-5: Read an artifact.
+     *
+     * I-23: This call creates a dependency edge from the reading mission
+     * to the artifact. The system uses these edges for invalidation cascading.
+     * The agent NEVER caches artifact content to bypass this tracking.
+     *
+     * I-21: The agent reads only ACTIVE artifacts. SUMMARIZED and ARCHIVED
+     * artifacts are excluded from the working set.
+     *
+     * @param artifactId - The artifact to read
+     * @param version - Specific version or 'latest'
+     * @returns ArtifactReadOutput with full artifact content
+     */
+    readArtifact(artifactId: ArtifactId, version?: number | 'latest'): Promise<ArtifactReadOutput>;
+    /**
+     * §18: Create a task output artifact with standard metadata.
+     *
+     * Convenience method that creates an artifact with task execution metadata
+     * automatically attached. One artifact per task output (FM-15).
+     *
+     * @param missionId - Mission context
+     * @param taskId - Task that produced this output
+     * @param taskDescription - Description of what the task did
+     * @param content - The output content
+     * @param state - Agent execution state
+     * @returns ArtifactCreateOutput
+     */
+    createTaskOutput(missionId: MissionId, taskId: string, taskDescription: string, content: string, state: AgentExecutionState): Promise<ArtifactCreateOutput>;
+    /**
+     * §18: Create a final report artifact.
+     *
+     * @param missionId - Mission context
+     * @param taskId - The delivery task that produced the report
+     * @param title - Report title
+     * @param content - Report content
+     * @param state - Agent execution state
+     * @returns ArtifactCreateOutput
+     */
+    createReport(missionId: MissionId, taskId: string, title: string, content: string, state: AgentExecutionState): Promise<ArtifactCreateOutput>;
+    /**
+     * §18, I-19: Revise an existing artifact by creating a new version.
+     *
+     * Does NOT modify the original. Creates a new version linked via
+     * parentArtifactId (I-19: immutability).
+     *
+     * @param missionId - Mission context
+     * @param parentArtifactId - The artifact being revised
+     * @param name - Updated name
+     * @param type - Artifact type
+     * @param format - Content format
+     * @param content - Updated content
+     * @param sourceTaskId - Task producing the revision
+     * @param state - Agent execution state
+     * @returns ArtifactCreateOutput for the new version
+     */
+    reviseArtifact(missionId: MissionId, parentArtifactId: ArtifactId, name: string, type: 'report' | 'data' | 'code' | 'analysis' | 'image' | 'raw', format: 'markdown' | 'json' | 'csv' | 'python' | 'sql' | 'html', content: string | Buffer, sourceTaskId: string, state: AgentExecutionState): Promise<ArtifactCreateOutput>;
+}
+//# sourceMappingURL=artifact_manager.d.ts.map

package/dist/reference-agent/artifact_manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact_manager.d.ts","sourceRoot":"","sources":["../../src/reference-agent/artifact_manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EACV,SAAS,EAAU,UAAU,EACR,oBAAoB,EACtB,kBAAkB,EACrC,mBAAmB,EACpB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAM3D;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;gBAE9B,MAAM,EAAE,gBAAgB;IAIpC;;;;;;;;;;;;;;;;;;;OAmBG;IACG,cAAc,CAClB,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,KAAK,EAC/D,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,EAC/D,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,UAAU,GAAG,SAAS,EACxC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,oBAAoB,CAAC;IAoBhC;;;;;;;;;;;;;OAaG;IACG,YAAY,CAChB,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,MAAM,GAAG,QAAmB,GACpC,OAAO,CAAC,kBAAkB,CAAC;IAS9B;;;;;;;;;;;;OAYG;IACG,gBAAgB,CACpB,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,oBAAoB,CAAC;IAchC;;;;;;;;;OASG;IACG,YAAY,CAChB,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,oBAAoB,CAAC;IAchC;;;;;;;;;;;;;;;OAeG;IACG,cAAc,CAClB,SAAS,EAAE,SAAS,EACpB,gBAAgB,EAAE,UAAU,EAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,KAAK,EAC/D,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,EAC/D,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,oBAAoB,CAAC;CAajC"}

package/dist/reference-agent/artifact_manager.js

@@ -0,0 +1,149 @@
+/**
+ * ArtifactManager -- workspace management for artifacts.
+ * S ref: S18 (create_artifact), S19 (read_artifact),
+ *        SD-01 (lifecycle-phase grouping)
+ *
+ * Phase: 5 (Reference Agent)
+ * Implements: SDD §10 Build Order Step 3 (ArtifactManager)
+ *
+ * The ArtifactManager is responsible for:
+ *   1. Creating artifacts via SC-4 (create_artifact)
+ *   2. Reading artifacts via SC-5 (read_artifact)
+ *   3. Tracking artifact IDs for result submission
+ *   4. Managing artifact versioning (parentArtifactId for revisions)
+ *
+ * I-19: The manager never mutates artifacts after creation. Revisions
+ * create new versions via parentArtifactId, not by modifying existing ones.
+ *
+ * I-23: All reads go through read_artifact, creating proper dependency edges.
+ * The manager never caches content to bypass dependency tracking.
+ *
+ * Invariants enforced: I-19 (artifact immutability),
+ *                      I-21 (reads only ACTIVE artifacts),
+ *                      I-23 (dependency tracking via read_artifact)
+ * Failure modes defended: FM-15 (artifact entropy -- purposeful creation)
+ */
+// ============================================================================
+// ArtifactManager Class
+// ============================================================================
+/**
+ * SD-01: ArtifactManager groups create_artifact + read_artifact.
+ * These are the "workspace" calls that manage OUTPUT during execution.
+ *
+ * FM-15 defense: The manager creates artifacts purposefully:
+ *   - One artifact per task output (not duplicates)
+ *   - Uses parentArtifactId for revisions (not new entries)
+ *   - Reads only ACTIVE artifacts (I-21)
+ */
+export class ArtifactManager {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * §18, SC-4: Create an artifact from task output.
+     *
+     * I-19: Once created, the artifact is immutable. Revisions create
+     * new versions via parentArtifactId.
+     *
+     * FM-15: Creates one artifact per task output. Does not create
+     * duplicates or unnecessary artifacts.
+     *
+     * @param missionId - The mission this artifact belongs to
+     * @param name - Descriptive name for the artifact
+     * @param type - Artifact type (report, data, code, analysis, image, raw)
+     * @param format - Content format (markdown, json, csv, python, sql, html)
+     * @param content - The artifact content
+     * @param sourceTaskId - The task that produced this artifact
+     * @param parentArtifactId - Parent artifact for revisions (null for new)
+     * @param metadata - Additional metadata
+     * @param state - Agent execution state (for tracking)
+     * @returns ArtifactCreateOutput with artifactId and version
+     */
+    async createArtifact(missionId, name, type, format, content, sourceTaskId, parentArtifactId, metadata, state) {
+        const input = {
+            missionId,
+            name,
+            type,
+            format,
+            content,
+            sourceTaskId: sourceTaskId,
+            ...(parentArtifactId != null ? { parentArtifactId } : {}),
+            metadata,
+        };
+        const result = await this.client.createArtifact(input);
+        // Track artifact for result submission
+        state.completedArtifactIds.push(result.artifactId);
+        return result;
+    }
+    /**
+     * §19, SC-5: Read an artifact.
+     *
+     * I-23: This call creates a dependency edge from the reading mission
+     * to the artifact. The system uses these edges for invalidation cascading.
+     * The agent NEVER caches artifact content to bypass this tracking.
+     *
+     * I-21: The agent reads only ACTIVE artifacts. SUMMARIZED and ARCHIVED
+     * artifacts are excluded from the working set.
+     *
+     * @param artifactId - The artifact to read
+     * @param version - Specific version or 'latest'
+     * @returns ArtifactReadOutput with full artifact content
+     */
+    async readArtifact(artifactId, version = 'latest') {
+        const input = {
+            artifactId,
+            version,
+        };
+        return this.client.readArtifact(input);
+    }
+    /**
+     * §18: Create a task output artifact with standard metadata.
+     *
+     * Convenience method that creates an artifact with task execution metadata
+     * automatically attached. One artifact per task output (FM-15).
+     *
+     * @param missionId - Mission context
+     * @param taskId - Task that produced this output
+     * @param taskDescription - Description of what the task did
+     * @param content - The output content
+     * @param state - Agent execution state
+     * @returns ArtifactCreateOutput
+     */
+    async createTaskOutput(missionId, taskId, taskDescription, content, state) {
+        return this.createArtifact(missionId, `Output: ${taskDescription}`, 'analysis', 'markdown', content, taskId, undefined, { producedBy: 'reference-agent', taskDescription }, state);
+    }
+    /**
+     * §18: Create a final report artifact.
+     *
+     * @param missionId - Mission context
+     * @param taskId - The delivery task that produced the report
+     * @param title - Report title
+     * @param content - Report content
+     * @param state - Agent execution state
+     * @returns ArtifactCreateOutput
+     */
+    async createReport(missionId, taskId, title, content, state) {
+        return this.createArtifact(missionId, title, 'report', 'markdown', content, taskId, undefined, { producedBy: 'reference-agent', isDeliverable: true }, state);
+    }
+    /**
+     * §18, I-19: Revise an existing artifact by creating a new version.
+     *
+     * Does NOT modify the original. Creates a new version linked via
+     * parentArtifactId (I-19: immutability).
+     *
+     * @param missionId - Mission context
+     * @param parentArtifactId - The artifact being revised
+     * @param name - Updated name
+     * @param type - Artifact type
+     * @param format - Content format
+     * @param content - Updated content
+     * @param sourceTaskId - Task producing the revision
+     * @param state - Agent execution state
+     * @returns ArtifactCreateOutput for the new version
+     */
+    async reviseArtifact(missionId, parentArtifactId, name, type, format, content, sourceTaskId, state) {
+        return this.createArtifact(missionId, name, type, format, content, sourceTaskId, parentArtifactId, { producedBy: 'reference-agent', isRevision: true }, state);
+    }
+}
+//# sourceMappingURL=artifact_manager.js.map

package/dist/reference-agent/artifact_manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact_manager.js","sourceRoot":"","sources":["../../src/reference-agent/artifact_manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAWH,+EAA+E;AAC/E,wBAAwB;AACxB,+EAA+E;AAE/E;;;;;;;;GAQG;AACH,MAAM,OAAO,eAAe;IACT,MAAM,CAAmB;IAE1C,YAAY,MAAwB;QAClC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,KAAK,CAAC,cAAc,CAClB,SAAoB,EACpB,IAAY,EACZ,IAA+D,EAC/D,MAA+D,EAC/D,OAAwB,EACxB,YAAoB,EACpB,gBAAwC,EACxC,QAAiC,EACjC,KAA0B;QAE1B,MAAM,KAAK,GAAwB;YACjC,SAAS;YACT,IAAI;YACJ,IAAI;YACJ,MAAM;YACN,OAAO;YACP,YAAY,EAAE,YAAsB;YACpC,GAAG,CAAC,gBAAgB,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzD,QAAQ;SACT,CAAC;QAEF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QAEvD,uCAAuC;QACvC,KAAK,CAAC,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAEnD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,YAAY,CAChB,UAAsB,EACtB,UAA6B,QAAQ;QAErC,MAAM,KAAK,GAAsB;YAC/B,UAAU;YACV,OAAO;SACR,CAAC;QAEF,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,gBAAgB,CACpB,SAAoB,EACpB,MAAc,EACd,eAAuB,EACvB,OAAe,EACf,KAA0B;QAE1B,OAAO,IAAI,CAAC,cAAc,CACxB,SAAS,EACT,WAAW,eAAe,EAAE,EAC5B,UAAU,EACV,UAAU,EACV,OAAO,EACP,MAAM,EACN,SAAS,EACT,EAAE,UAAU,EAAE,iBAAiB,EAAE,eAAe,EAAE,EAClD,KAAK,CACN,CAAC;IACJ,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,YAAY,CAChB,SAAoB,EACpB,MAAc,EACd,KAAa,EACb,OAAe,EACf,KAA0B;QAE1B,OAAO,IAAI,CAAC,cAAc,CACxB,SAAS,EACT,KAAK,EACL,QAAQ,EACR,UAAU,EACV,OAAO,EACP,MAAM,EACN,SAAS,EACT,EAAE,UAAU,EAAE,iBAAiB,EAAE,aAAa,EAAE,IAAI,EAAE,EACtD,KAAK,CACN,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,cAAc,CAClB,SAAoB,EACpB,gBAA4B,EAC5B,IAAY,EACZ,IAA+D,EAC/D,MAA+D,EAC/D,OAAwB,EACxB,YAAoB,EACpB,KAA0B;QAE1B,OAAO,IAAI,CAAC,cAAc,CACxB,SAAS,EACT,IAAI,EACJ,IAAI,EACJ,MAAM,EACN,OAAO,EACP,YAAY,EACZ,gBAAgB,EAChB,EAAE,UAAU,EAAE,iBAAiB,EAAE,UAAU,EAAE,IAAI,EAAE,EACnD,KAAK,CACN,CAAC;IACJ,CAAC;CACF"}