@feltdb/core 0.12.0 → 0.12.1

package/dist/agent-state.js

@@ -0,0 +1,993 @@
+/**
+ * Durable agent state: tasks, checkpoints, scoped memory, and handoffs.
+ *
+ * Everything here is ordinary FeltDB state in four `_feltdb.Agent*`
+ * collections. No new storage, cache, or authority is introduced:
+ *
+ * - every write is one `db.transaction`, fenced by the authority's own
+ *   `ifVersion` / `requireAbsent` / `expectedLeaseId` predicates, so a stale
+ *   or concurrent write is refused by the authority rather than by this module;
+ * - every read is `collection.get` by id or a bounded `db.query` on a declared
+ *   compound index; nothing reads a whole collection;
+ * - nothing is held in process memory between calls, so a fresh process (or a
+ *   different agent, framework, or model provider) resumes from exactly what
+ *   was committed.
+ *
+ *   createTask ──▶ _feltdb.AgentTask  (head: status, owner, checkpoint_version)
+ *                  _feltdb.AgentCheckpoint  (immutable, one per version)
+ *   checkpoint ──▶ task@N → N+1 + checkpoint vN+1 + evidence fences, one commit
+ *   remember   ──▶ _feltdb.AgentMemory  (scoped; superseded, never rewritten)
+ *   handoff    ──▶ _feltdb.AgentHandoff (a reference to task@checkpoint)
+ *   claim      ──▶ handoff open → claimed (leased) + task owner, one commit
+ *
+ * Provider identifiers, token counts, and transcript references are optional
+ * `execution` metadata on a checkpoint. They never decide status, ownership,
+ * or what a resume returns.
+ *
+ * Contract and guarantees: docs/reference/agent-state.md.
+ */
+import { ConditionalConflictError, } from './transaction.js';
+export const FELTDB_AGENT_TASK_COLLECTION = '_feltdb.AgentTask';
+export const FELTDB_AGENT_CHECKPOINT_COLLECTION = '_feltdb.AgentCheckpoint';
+export const FELTDB_AGENT_MEMORY_COLLECTION = '_feltdb.AgentMemory';
+export const FELTDB_AGENT_HANDOFF_COLLECTION = '_feltdb.AgentHandoff';
+export const AGENT_CONTEXT_FORMAT = 'feltdb.agent-context@1';
+/** Compound indexes every agent-state query is planned against. */
+export const AGENT_STATE_INDEXES = [
+    {
+        collection: FELTDB_AGENT_CHECKPOINT_COLLECTION,
+        index: {
+            name: 'agent_checkpoints_by_task_version',
+            type: 'compound',
+            fields: ['task_id', 'version', 'id'],
+            directions: ['asc', 'desc', 'asc'],
+            persistent: true,
+        },
+    },
+    {
+        collection: FELTDB_AGENT_MEMORY_COLLECTION,
+        index: {
+            name: 'agent_memory_by_scope_status_created',
+            type: 'compound',
+            fields: ['scope_key', 'status', 'created_at', 'id'],
+            directions: ['asc', 'asc', 'desc', 'asc'],
+            persistent: true,
+        },
+    },
+];
+const TASK_STATUSES = ['ready', 'running', 'blocked', 'completed', 'cancelled'];
+const TERMINAL = ['completed', 'cancelled'];
+/** Every refusal. A refused write committed nothing. */
+export class AgentStateError extends Error {
+    code;
+    detail;
+    constructor(code, message, detail = {}) {
+        super(message);
+        this.code = code;
+        this.detail = detail;
+        this.name = 'AgentStateError';
+    }
+}
+const SEGMENT = /^[A-Za-z0-9._-]+$/;
+const LIST_LIMIT = 200;
+const CUMULATIVE_LIMIT = 10_000;
+const TEXT_LIMIT = 4_000;
+const CONTENT_LIMIT = 32 * 1024;
+const DEFAULT_LEASE_MS = 5 * 60_000;
+function fail(code, message, detail) {
+    return new AgentStateError(code, message, detail);
+}
+function identifier(value, label, max = 96) {
+    if (typeof value !== 'string' || !value || value.length > max || !SEGMENT.test(value)) {
+        throw fail('INVALID_REQUEST', `${label} must be 1-${max} characters of [A-Za-z0-9._-]`);
+    }
+    return value;
+}
+function name(value, label) {
+    if (typeof value !== 'string' || !value.trim() || value.length > 128) {
+        throw fail('INVALID_REQUEST', `${label} must be a non-empty string of at most 128 characters`);
+    }
+    return value;
+}
+function text(value, label, max = TEXT_LIMIT) {
+    if (typeof value !== 'string' || !value.trim() || value.length > max) {
+        throw fail('INVALID_REQUEST', `${label} must be a non-empty string of at most ${max} characters`);
+    }
+    return value;
+}
+function list(value, label) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > LIST_LIMIT) {
+        throw fail('INVALID_REQUEST', `${label} must be an array of at most ${LIST_LIMIT} strings`);
+    }
+    return value.map((entry, index) => text(entry, `${label}[${index}]`));
+}
+function taskScope(value) {
+    if (value === undefined)
+        return {};
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw fail('INVALID_REQUEST', 'scope must be an object');
+    const { project, workspace, ...rest } = value;
+    if (Object.keys(rest).length)
+        throw fail('INVALID_REQUEST', `scope has unknown fields: ${Object.keys(rest).join(', ')}`);
+    return {
+        ...(project === undefined ? {} : { project: name(project, 'scope.project') }),
+        ...(workspace === undefined ? {} : { workspace: name(workspace, 'scope.workspace') }),
+    };
+}
+const EXECUTION_TEXT = ['adapter', 'provider', 'model', 'conversation_id', 'transcript_ref'];
+const EXECUTION_COUNT = ['input_tokens', 'output_tokens'];
+function execution(value) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw fail('INVALID_REQUEST', 'execution must be an object');
+    const result = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (EXECUTION_TEXT.includes(key)) {
+            result[key] = text(entry, `execution.${key}`, 512);
+        }
+        else if (EXECUTION_COUNT.includes(key)) {
+            if (!Number.isInteger(entry) || entry < 0)
+                throw fail('INVALID_REQUEST', `execution.${key} must be a non-negative integer`);
+            result[key] = entry;
+        }
+        else {
+            throw fail('INVALID_REQUEST', `execution.${key} is not recorded; execution metadata is ${[...EXECUTION_TEXT, ...EXECUTION_COUNT].join(', ')}`);
+        }
+    }
+    return result;
+}
+function cumulative(previous, next, label) {
+    const combined = [...previous, ...next];
+    if (combined.length > CUMULATIVE_LIMIT) {
+        throw fail('INVALID_REQUEST', `${label} would exceed ${CUMULATIVE_LIMIT} entries`);
+    }
+    return combined;
+}
+function strip(row) {
+    const { id: _id, __version, ...rest } = row;
+    return { ...rest, revision: typeof __version === 'number' ? __version : 1 };
+}
+function version(row) {
+    return typeof row.__version === 'number' ? row.__version : 1;
+}
+function newId(prefix) {
+    const random = globalThis.crypto?.randomUUID?.()
+        ?? `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;
+    return `${prefix}-${random}`;
+}
+function checkpointId(taskId, checkpointVersion) {
+    return `${taskId}.v${checkpointVersion}`;
+}
+function memoryScopeKey(scope) {
+    if (scope.kind === 'task')
+        return `task:${identifier(scope.taskId, 'scope.taskId')}`;
+    if (scope.kind === 'project')
+        return `project:${name(scope.project, 'scope.project')}`;
+    if (scope.kind === 'workspace')
+        return `workspace:${name(scope.workspace, 'scope.workspace')}`;
+    throw fail('INVALID_REQUEST', 'scope.kind must be task, project, or workspace');
+}
+function memoryContent(value) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(value);
+    }
+    catch {
+        serialized = undefined;
+    }
+    if (serialized === undefined || value === null || value === '') {
+        throw fail('INVALID_REQUEST', 'content must be a non-empty JSON value');
+    }
+    if (bytes(serialized) > CONTENT_LIMIT)
+        throw fail('INVALID_REQUEST', `content must serialize to at most ${CONTENT_LIMIT} bytes`);
+    return JSON.parse(serialized);
+}
+const encoder = new TextEncoder();
+function bytes(value) {
+    return encoder.encode(value).length;
+}
+function now() {
+    return new Date().toISOString();
+}
+/**
+ * Open the agent-state contract over a FeltDB database.
+ *
+ * Refuses a runtime without atomic transactions instead of emulating one.
+ */
+export async function openAgentState(db, options = {}) {
+    const capabilities = db.capabilities?.();
+    if (capabilities && !capabilities.transactions) {
+        throw fail('CONTRACT_UNSUPPORTED', 'agent state requires a FeltDB runtime with atomic transactions');
+    }
+    if ((options.declareIndexes ?? true) && !capabilities?.remoteAuthority) {
+        for (const { collection, index } of AGENT_STATE_INDEXES) {
+            const handle = db.collection(collection);
+            if (handle.listIndexes().some(existing => existing.name === index.name))
+                continue;
+            // An index declared in an earlier process is already a durable
+            // definition; declaring it again would only rewrite it.
+            const planned = await db.explain?.({
+                collection,
+                where: [{ field: index.fields[0], eq: '' }],
+                limit: 1,
+            }).catch(() => undefined);
+            if (planned?.index === index.name)
+                continue;
+            handle.createIndex(index);
+        }
+    }
+    return new AgentStateStore(db);
+}
+/** The agent-state contract. Holds no state of its own between calls. */
+export class AgentStateStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    // ---------------------------------------------------------------- tasks
+    async createTask(input) {
+        const taskId = input.taskId === undefined ? newId('task') : identifier(input.taskId, 'taskId');
+        const actor = name(input.actor, 'actor');
+        const status = input.status ?? 'ready';
+        if (!['ready', 'running', 'blocked'].includes(status)) {
+            throw fail('INVALID_REQUEST', 'a task is created ready, running, or blocked');
+        }
+        const at = now();
+        const pending = list(input.pendingWork, 'pendingWork');
+        const constraints = list(input.constraints, 'constraints');
+        const task = {
+            task_id: taskId,
+            objective: text(input.objective, 'objective'),
+            scope: taskScope(input.scope),
+            status,
+            owner: actor,
+            checkpoint_version: 1,
+            pending_work: pending,
+            constraints,
+            created_at: at,
+            created_by: actor,
+            updated_at: at,
+            updated_by: actor,
+        };
+        const checkpoint = {
+            checkpoint_id: checkpointId(taskId, 1),
+            task_id: taskId,
+            version: 1,
+            status,
+            summary: input.summary === undefined ? 'Task created.' : text(input.summary, 'summary'),
+            completed: [],
+            completed_work: [],
+            pending_work: pending,
+            constraints,
+            decisions: [],
+            evidence: [],
+            actor,
+            ...(input.execution ? { execution: execution(input.execution) } : {}),
+            created_at: at,
+        };
+        try {
+            await this.db.transaction(tx => {
+                tx.collection(FELTDB_AGENT_TASK_COLLECTION).set(taskId, task, { requireAbsent: true });
+                tx.collection(FELTDB_AGENT_CHECKPOINT_COLLECTION).set(checkpoint.checkpoint_id, checkpoint, { requireAbsent: true });
+            });
+        }
+        catch (error) {
+            if (error instanceof ConditionalConflictError)
+                throw fail('VERSION_CONFLICT', `task ${taskId} already exists`, { taskId });
+            throw error;
+        }
+        return { task: { ...task, revision: 1 }, checkpoint };
+    }
+    /** The task head and its latest committed checkpoint, from durable state. */
+    async getTask(taskId) {
+        const row = await this.taskRow(identifier(taskId, 'taskId'));
+        if (!row)
+            return null;
+        const task = strip(row);
+        const checkpoint = await this.getCheckpoint(task.task_id, task.checkpoint_version);
+        if (!checkpoint) {
+            throw fail('NOT_FOUND', `task ${taskId} names checkpoint ${task.checkpoint_version}, which is not committed`);
+        }
+        return { task, checkpoint };
+    }
+    async getCheckpoint(taskId, checkpointVersion) {
+        const row = await this.db.collection(FELTDB_AGENT_CHECKPOINT_COLLECTION).get(checkpointId(identifier(taskId, 'taskId'), checkpointVersion));
+        if (!row)
+            return null;
+        const { revision: _revision, ...checkpoint } = strip(row);
+        return checkpoint;
+    }
+    /**
+     * Commit checkpoint N+1 atomically with the task head.
+     *
+     * Refused, with nothing written, when `expectedVersion` is not the committed
+     * version, when another writer commits first, when `actor` does not own the
+     * task, when the task is terminal, or when cited record evidence is absent.
+     */
+    async checkpoint(taskId, input) {
+        const id = identifier(taskId, 'taskId');
+        const actor = name(input.actor, 'actor');
+        const summary = text(input.summary, 'summary');
+        if (input.status !== undefined && !TASK_STATUSES.includes(input.status)) {
+            throw fail('INVALID_REQUEST', `status must be one of ${TASK_STATUSES.join(', ')}`);
+        }
+        const completed = list(input.completed, 'completed');
+        const decisions = list(input.decisions, 'decisions');
+        const pending = input.pendingWork === undefined ? undefined : list(input.pendingWork, 'pendingWork');
+        const constraints = input.constraints === undefined ? undefined : list(input.constraints, 'constraints');
+        const metadata = execution(input.execution);
+        if (input.evidence !== undefined && (!Array.isArray(input.evidence) || input.evidence.length > LIST_LIMIT)) {
+            throw fail('INVALID_REQUEST', `evidence must be an array of at most ${LIST_LIMIT} references`);
+        }
+        const row = await this.requireTask(id);
+        const task = strip(row);
+        if (input.expectedVersion !== undefined && input.expectedVersion !== task.checkpoint_version) {
+            throw fail('VERSION_CONFLICT', `task ${id} is at checkpoint ${task.checkpoint_version}, not ${input.expectedVersion}`, {
+                expected: input.expectedVersion, current: task.checkpoint_version,
+            });
+        }
+        this.assertOwner(task, actor);
+        if (TERMINAL.includes(task.status)) {
+            throw fail('INVALID_TRANSITION', `task ${id} is ${task.status}; a terminal task takes no further checkpoints`);
+        }
+        const previous = await this.getCheckpoint(id, task.checkpoint_version);
+        if (!previous)
+            throw fail('NOT_FOUND', `checkpoint ${task.checkpoint_version} of task ${id} is not committed`);
+        const nextVersion = task.checkpoint_version + 1;
+        const cited = await this.resolveEvidence(input.evidence ?? [], nextVersion);
+        const at = now();
+        const status = input.status ?? task.status;
+        const next = {
+            checkpoint_id: checkpointId(id, nextVersion),
+            task_id: id,
+            version: nextVersion,
+            status,
+            summary,
+            completed,
+            completed_work: cumulative(previous.completed_work, completed, 'completed_work'),
+            pending_work: pending ?? previous.pending_work,
+            constraints: constraints ?? previous.constraints,
+            decisions: cumulative(previous.decisions, decisions, 'decisions'),
+            evidence: [...previous.evidence, ...cited.map(entry => entry.evidence)],
+            actor,
+            ...(metadata ? { execution: metadata } : {}),
+            created_at: at,
+        };
+        if (next.evidence.length > CUMULATIVE_LIMIT)
+            throw fail('INVALID_REQUEST', `evidence would exceed ${CUMULATIVE_LIMIT} entries`);
+        const head = {
+            ...withoutRevision(task),
+            status,
+            checkpoint_version: nextVersion,
+            pending_work: next.pending_work,
+            constraints: next.constraints,
+            updated_at: at,
+            updated_by: actor,
+        };
+        try {
+            await this.db.transaction(tx => {
+                tx.collection(FELTDB_AGENT_TASK_COLLECTION).set(id, head, { ifVersion: version(row) });
+                tx.collection(FELTDB_AGENT_CHECKPOINT_COLLECTION).set(next.checkpoint_id, next, { requireAbsent: true });
+                for (const entry of cited) {
+                    if (entry.evidence.kind === 'record') {
+                        tx.require({ collection: entry.evidence.collection, id: entry.evidence.id, ifVersion: entry.evidence.version });
+                    }
+                }
+            });
+        }
+        catch (error) {
+            if (error instanceof ConditionalConflictError) {
+                const current = await this.taskRow(id);
+                const failure = error.failure;
+                if (failure && failure.collection !== FELTDB_AGENT_TASK_COLLECTION && failure.collection !== FELTDB_AGENT_CHECKPOINT_COLLECTION) {
+                    throw fail('VERSION_CONFLICT', `cited evidence ${failure.key} changed before the checkpoint committed`, { evidence: failure.key });
+                }
+                throw fail('VERSION_CONFLICT', `task ${id} moved to checkpoint ${current ? current.checkpoint_version : 'unknown'} before this write committed`, {
+                    expected: task.checkpoint_version, current: current?.checkpoint_version,
+                });
+            }
+            throw error;
+        }
+        return { task: { ...head, revision: version(row) + 1 }, checkpoint: next };
+    }
+    /**
+     * Resume a task from durable state alone: verify that `actor` owns it, then
+     * assemble its context. Writes nothing; the next `checkpoint` should pass
+     * `expectedVersion: bundle.checkpoint.version`.
+     */
+    async resume(taskId, input) {
+        const row = await this.requireTask(identifier(taskId, 'taskId'));
+        this.assertOwner(strip(row), name(input.actor, 'actor'));
+        return this.assembleContext(taskId, input);
+    }
+    // --------------------------------------------------------------- memory
+    async remember(input) {
+        const actor = name(input.source?.actor, 'source.actor');
+        const taskId = input.taskId === undefined ? undefined : identifier(input.taskId, 'taskId');
+        if (!input.scope && !taskId) {
+            throw fail('SCOPE_REQUIRED', 'memory requires a scope, or a taskId whose task scope it defaults to; there is no global memory');
+        }
+        const scope = input.scope ?? { kind: 'task', taskId: taskId };
+        const scopeKey = memoryScopeKey(scope);
+        if (taskId || scope.kind === 'task') {
+            const owningTask = taskId ?? scope.taskId;
+            const task = strip(await this.requireTask(owningTask));
+            if (scope.kind === 'task' && scope.taskId !== task.task_id) {
+                throw fail('INVALID_REQUEST', `memory for task ${task.task_id} cannot be written to task scope ${scope.taskId}`);
+            }
+            if (scope.kind === 'project' && task.scope.project !== scope.project) {
+                throw fail('INVALID_REQUEST', `task ${task.task_id} is not in project ${scope.project}`);
+            }
+            if (scope.kind === 'workspace' && task.scope.workspace !== scope.workspace) {
+                throw fail('INVALID_REQUEST', `task ${task.task_id} is not in workspace ${scope.workspace}`);
+            }
+        }
+        const memoryId = input.memoryId === undefined ? newId('mem') : identifier(input.memoryId, 'memoryId', 128);
+        const at = now();
+        const memory = {
+            memory_id: memoryId,
+            scope: scope.kind === 'task' ? { kind: 'task', taskId: scope.taskId } : scope,
+            scope_key: scopeKey,
+            kind: input.kind === undefined ? 'note' : name(input.kind, 'kind'),
+            content: memoryContent(input.content),
+            source: memorySource(input.source, actor, taskId ?? (scope.kind === 'task' ? scope.taskId : undefined)),
+            status: 'active',
+            created_at: at,
+            updated_at: at,
+        };
+        try {
+            await this.db.transaction(tx => {
+                tx.collection(FELTDB_AGENT_MEMORY_COLLECTION).set(memoryId, memory, { requireAbsent: true });
+            });
+        }
+        catch (error) {
+            if (error instanceof ConditionalConflictError)
+                throw fail('VERSION_CONFLICT', `memory ${memoryId} already exists`);
+            throw error;
+        }
+        return { ...memory, revision: 1 };
+    }
+    async getMemory(memoryId) {
+        const row = await this.db.collection(FELTDB_AGENT_MEMORY_COLLECTION).get(identifier(memoryId, 'memoryId', 128));
+        return row ? strip(row) : null;
+    }
+    /**
+     * One bounded page of a single scope, newest first (ties by id).
+     * There is no unscoped recall.
+     */
+    async recall(input) {
+        if (!input?.scope)
+            throw fail('SCOPE_REQUIRED', 'recall requires a scope; there is no global memory');
+        const status = input.status ?? 'active';
+        if (!['active', 'superseded', 'invalidated'].includes(status))
+            throw fail('INVALID_REQUEST', 'status must be active, superseded, or invalidated');
+        const page = await this.db.query({
+            collection: FELTDB_AGENT_MEMORY_COLLECTION,
+            where: [{ field: 'scope_key', eq: memoryScopeKey(input.scope) }, { field: 'status', eq: status }],
+            orderBy: [{ field: 'created_at', direction: 'desc' }],
+            limit: boundedLimit(input.limit, 50, 1_000),
+            ...(input.cursor ? { cursor: input.cursor } : {}),
+        });
+        return {
+            memories: page.records.map(row => strip(row)),
+            ...(page.nextCursor && !page.exhausted ? { nextCursor: page.nextCursor } : {}),
+        };
+    }
+    /**
+     * Active memories visible to a task: its own scope, then its project, then
+     * its workspace. A memory scoped to another task is never returned.
+     */
+    async recallForTask(taskId, input = {}) {
+        const task = strip(await this.requireTask(identifier(taskId, 'taskId')));
+        const limit = boundedLimit(input.limit, 20, 100);
+        const scopes = [
+            { kind: 'task', taskId: task.task_id },
+            ...(task.scope.project ? [{ kind: 'project', project: task.scope.project }] : []),
+            ...(task.scope.workspace ? [{ kind: 'workspace', workspace: task.scope.workspace }] : []),
+        ];
+        const pages = await Promise.all(scopes.map(scope => this.recall({ scope, limit })));
+        return pages.flatMap(page => page.memories);
+    }
+    /** Replace a memory with a new one, atomically. The old record stays, marked superseded. */
+    async supersede(memoryId, input) {
+        const id = identifier(memoryId, 'memoryId', 128);
+        const actor = name(input.source?.actor, 'source.actor');
+        const row = await this.db.collection(FELTDB_AGENT_MEMORY_COLLECTION).get(id);
+        if (!row)
+            throw fail('NOT_FOUND', `memory ${id} does not exist`);
+        const old = strip(row);
+        if (input.expectedRevision !== undefined && input.expectedRevision !== old.revision) {
+            throw fail('VERSION_CONFLICT', `memory ${id} is at revision ${old.revision}, not ${input.expectedRevision}`);
+        }
+        if (old.status !== 'active') {
+            throw fail('INVALID_TRANSITION', `memory ${id} is ${old.status}${old.superseded_by ? ` by ${old.superseded_by}` : ''}`);
+        }
+        const nextId = input.memoryId === undefined ? newId('mem') : identifier(input.memoryId, 'memoryId', 128);
+        const at = now();
+        const replaced = { ...withoutRevision(old), status: 'superseded', superseded_by: nextId, updated_at: at };
+        const memory = {
+            memory_id: nextId,
+            scope: old.scope,
+            scope_key: old.scope_key,
+            kind: input.kind === undefined ? old.kind : name(input.kind, 'kind'),
+            content: memoryContent(input.content),
+            source: memorySource(input.source, actor, old.source.task_id),
+            status: 'active',
+            supersedes: id,
+            created_at: at,
+            updated_at: at,
+        };
+        try {
+            await this.db.transaction(tx => {
+                tx.collection(FELTDB_AGENT_MEMORY_COLLECTION).set(id, replaced, { ifVersion: old.revision });
+                tx.collection(FELTDB_AGENT_MEMORY_COLLECTION).set(nextId, memory, { requireAbsent: true });
+            });
+        }
+        catch (error) {
+            if (error instanceof ConditionalConflictError) {
+                throw fail('VERSION_CONFLICT', `memory ${id} changed before the supersession committed`);
+            }
+            throw error;
+        }
+        return { superseded: { ...replaced, revision: old.revision + 1 }, memory: { ...memory, revision: 1 } };
+    }
+    /** Withdraw a memory without replacing it. */
+    async invalidate(memoryId, input) {
+        const id = identifier(memoryId, 'memoryId', 128);
+        name(input.actor, 'actor');
+        const reason = text(input.reason, 'reason');
+        const row = await this.db.collection(FELTDB_AGENT_MEMORY_COLLECTION).get(id);
+        if (!row)
+            throw fail('NOT_FOUND', `memory ${id} does not exist`);
+        const old = strip(row);
+        if (input.expectedRevision !== undefined && input.expectedRevision !== old.revision) {
+            throw fail('VERSION_CONFLICT', `memory ${id} is at revision ${old.revision}, not ${input.expectedRevision}`);
+        }
+        if (old.status !== 'active')
+            throw fail('INVALID_TRANSITION', `memory ${id} is already ${old.status}`);
+        const next = { ...withoutRevision(old), status: 'invalidated', invalidated_reason: reason, updated_at: now() };
+        try {
+            await this.db.transaction(tx => {
+                tx.collection(FELTDB_AGENT_MEMORY_COLLECTION).set(id, next, { ifVersion: old.revision });
+            });
+        }
+        catch (error) {
+            if (error instanceof ConditionalConflictError)
+                throw fail('VERSION_CONFLICT', `memory ${id} changed before the invalidation committed`);
+            throw error;
+        }
+        return { ...next, revision: old.revision + 1 };
+    }
+    // ------------------------------------------------------------- handoffs
+    /**
+     * Record that the task's owner offers it, at its committed checkpoint, to
+     * another agent. The handoff is fenced on the task head, so it can only
+     * reference the checkpoint that is committed when it commits.
+     */
+    async createHandoff(taskId, input) {
+        const id = identifier(taskId, 'taskId');
+        const actor = name(input.actor, 'actor');
+        const to = input.to === undefined ? undefined : name(input.to, 'to');
+        const row = await this.requireTask(id);
+        const task = strip(row);
+        this.assertOwner(task, actor);
+        if (TERMINAL.includes(task.status))
+            throw fail('INVALID_TRANSITION', `task ${id} is ${task.status}; it cannot be handed off`);
+        if (input.expectedVersion !== undefined && input.expectedVersion !== task.checkpoint_version) {
+            throw fail('VERSION_CONFLICT', `task ${id} is at checkpoint ${task.checkpoint_version}, not ${input.expectedVersion}`, {
+                expected: input.expectedVersion, current: task.checkpoint_version,
+            });
+        }
+        const checkpoint = await this.getCheckpoint(id, task.checkpoint_version);
+        if (!checkpoint)
+            throw fail('NOT_FOUND', `checkpoint ${task.checkpoint_version} of task ${id} is not committed`);
+        const memoryRefs = [...new Set(list(input.memoryRefs, 'memoryRefs'))];
+        const visible = new Set([`task:${id}`, ...(task.scope.project ? [`project:${task.scope.project}`] : []), ...(task.scope.workspace ? [`workspace:${task.scope.workspace}`] : [])]);
+        for (const memoryId of memoryRefs) {
+            const memory = await this.getMemory(memoryId);
+            if (!memory)
+                throw fail('INVALID_REQUEST', `memoryRefs names ${memoryId}, which does not exist`);
+            if (!visible.has(memory.scope_key))
+                throw fail('INVALID_REQUEST', `memory ${memoryId} (${memory.scope_key}) is not visible to task ${id}`);
+        }
+        const evidence = input.evidenceRefs ?? checkpoint.evidence;
+        if (!Array.isArray(evidence) || evidence.length > CUMULATIVE_LIMIT)
+            throw fail('INVALID_REQUEST', 'evidenceRefs must be an array');
+        const known = new Set(checkpoint.evidence.map(evidenceKey));
+        for (const entry of evidence) {
+            if (!known.has(evidenceKey(entry))) {
+                throw fail('INVALID_REQUEST', `evidenceRefs must be evidence cited by checkpoint ${checkpoint.version}`);
+            }
+        }
+        const handoffId = input.handoffId === undefined ? newId('handoff') : identifier(input.handoffId, 'handoffId', 128);
+        const at = now();
+        const record = {
+            handoff_id: handoffId,
+            task_id: id,
+            checkpoint_version: task.checkpoint_version,
+            from: actor,
+            ...(to ? { to } : {}),
+            ...(input.note === undefined ? {} : { note: text(input.note, 'note') }),
+            memory_refs: memoryRefs,
+            evidence_refs: evidence,
+            artifact_refs: list(input.artifactRefs, 'artifactRefs'),
+            status: 'open',
+            lease: null,
+            created_at: at,
+            updated_at: at,
+        };
+        try {
+            await this.db.transaction(tx => {
+                tx.collection(FELTDB_AGENT_HANDOFF_COLLECTION).set(handoffId, record, { requireAbsent: true });
+                tx.require({ collection: FELTDB_AGENT_TASK_COLLECTION, id, ifVersion: version(row) });
+            });
+        }
+        catch (error) {
+            if (error instanceof ConditionalConflictError) {
+                throw fail('VERSION_CONFLICT', `task ${id} changed, or handoff ${handoffId} exists, before the handoff committed`);
+            }
+            throw error;
+        }
+        return resolveHandoff({ ...record, revision: 1 }, task, checkpoint);
+    }
+    async getHandoff(handoffId) {
+        const row = await this.db.collection(FELTDB_AGENT_HANDOFF_COLLECTION).get(identifier(handoffId, 'handoffId', 128));
+        if (!row)
+            return null;
+        const record = strip(row);
+        const task = strip(await this.requireTask(record.task_id));
+        const checkpoint = await this.getCheckpoint(record.task_id, record.checkpoint_version);
+        if (!checkpoint)
+            throw fail('NOT_FOUND', `handoff ${handoffId} references checkpoint ${record.checkpoint_version}, which is not committed`);
+        return resolveHandoff(record, task, checkpoint);
+    }
+    /**
+     * Take exclusive, leased ownership of a handoff and its task.
+     *
+     * One commit moves the handoff to `claimed` and the task's owner to the
+     * claimant, fenced on both records' versions: of concurrent claimants
+     * exactly one succeeds. A claim that is not accepted before its lease
+     * expires may be taken by another claimant (see the reference for the
+     * clock this uses).
+     */
+    async claimHandoff(handoffId, input) {
+        const id = identifier(handoffId, 'handoffId', 128);
+        const claimant = name(input.claimant, 'claimant');
+        const leaseMs = input.leaseMs ?? DEFAULT_LEASE_MS;
+        if (!Number.isInteger(leaseMs) || leaseMs < 1 || leaseMs > 24 * 60 * 60_000) {
+            throw fail('INVALID_REQUEST', 'leaseMs must be an integer between 1 and 86400000');
+        }
+        const handoffs = this.db.collection(FELTDB_AGENT_HANDOFF_COLLECTION);
+        const first = await handoffs.get(id);
+        if (!first)
+            throw fail('NOT_FOUND', `handoff ${id} does not exist`);
+        const task = strip(await this.requireTask(strip(first).task_id));
+        // Decide on a handoff read taken after the task read. A claim commits both
+        // records together, so this pair can never show a claimed task beside an
+        // open handoff, which would misreport a lost race as a stale handoff.
+        const handoff = strip((await handoffs.get(id)));
+        if (handoff.to && handoff.to !== claimant) {
+            throw fail('OWNERSHIP_CONFLICT', `handoff ${id} is addressed to ${handoff.to}`);
+        }
+        const clock = Date.now();
+        const leaseHeld = Boolean(handoff.lease && handoff.lease.expiresAt > clock);
+        if (handoff.status === 'accepted') {
+            throw fail('HANDOFF_CLAIMED', `handoff ${id} was accepted by ${handoff.accepted_by}`, { claimant: handoff.accepted_by });
+        }
+        if (handoff.status === 'claimed' && leaseHeld) {
+            if (handoff.claim?.claimant === claimant && task.owner === claimant) {
+                // A retry by the holder after an uncertain outcome: the claim stands.
+                return { handoff: await this.resolveRecord(handoff, task), leaseId: handoff.lease.leaseId, expiresAt: handoff.lease.expiresAt };
+            }
+            throw fail('HANDOFF_CLAIMED', `handoff ${id} is claimed by ${handoff.claim?.claimant}`, { claimant: handoff.claim?.claimant });
+        }
+        if (handoff.status === 'open') {
+            if (task.owner !== handoff.from || task.checkpoint_version !== handoff.checkpoint_version) {
+                throw fail('HANDOFF_STALE', `task ${task.task_id} moved past handoff ${id} (checkpoint ${task.checkpoint_version}, owner ${task.owner})`, {
+                    handoffCheckpoint: handoff.checkpoint_version, currentCheckpoint: task.checkpoint_version,
+                });
+            }
+        }
+        else if (task.owner !== handoff.claim?.claimant) {
+            // An expired claim: only recoverable while the task is still with the
+            // claimant that abandoned it.
+            throw fail('HANDOFF_STALE', `task ${task.task_id} is owned by ${task.owner}, not the expired claimant`);
+        }
+        const leaseId = newId('lease');
+        const expiresAt = clock + leaseMs;
+        const at = now();
+        const claimed = {
+            ...withoutRevision(handoff),
+            status: 'claimed',
+            claim: { claimant, claimed_at: at, attempt: (handoff.claim?.attempt ?? 0) + 1 },
+            lease: { leaseId, expiresAt },
+            updated_at: at,
+        };
+        const head = { ...withoutRevision(task), owner: claimant, updated_at: at, updated_by: claimant };
+        try {
+            await this.db.transaction(tx => {
+                tx.collection(FELTDB_AGENT_HANDOFF_COLLECTION).set(id, claimed, { ifVersion: handoff.revision });
+                tx.collection(FELTDB_AGENT_TASK_COLLECTION).set(task.task_id, head, { ifVersion: task.revision });
+            });
+        }
+        catch (error) {
+            if (error instanceof ConditionalConflictError) {
+                const current = await this.db.collection(FELTDB_AGENT_HANDOFF_COLLECTION).get(id);
+                const winner = current ? strip(current) : undefined;
+                if (winner && winner.status !== 'open' && winner.claim?.claimant !== claimant) {
+                    throw fail('HANDOFF_CLAIMED', `handoff ${id} was claimed by ${winner.claim?.claimant}`, { claimant: winner.claim?.claimant });
+                }
+                throw fail('VERSION_CONFLICT', `handoff ${id} or task ${task.task_id} changed before the claim committed`);
+            }
+            throw error;
+        }
+        return {
+            handoff: await this.resolveRecord({ ...claimed, revision: handoff.revision + 1 }, { ...head, revision: task.revision + 1 }),
+            leaseId,
+            expiresAt,
+        };
+    }
+    /**
+     * Make a claim final. The authority checks, inside the commit, that the
+     * caller's lease is the one recorded and has not expired.
+     */
+    async acceptHandoff(handoffId, input) {
+        const id = identifier(handoffId, 'handoffId', 128);
+        const claimant = name(input.claimant, 'claimant');
+        const leaseId = name(input.leaseId, 'leaseId');
+        const row = await this.db.collection(FELTDB_AGENT_HANDOFF_COLLECTION).get(id);
+        if (!row)
+            throw fail('NOT_FOUND', `handoff ${id} does not exist`);
+        const handoff = strip(row);
+        if (handoff.status !== 'claimed' || handoff.claim?.claimant !== claimant) {
+            throw fail('INVALID_TRANSITION', `handoff ${id} is ${handoff.status}${handoff.claim ? ` by ${handoff.claim.claimant}` : ''}; only its claimant can accept it`);
+        }
+        const at = now();
+        const accepted = {
+            ...withoutRevision(handoff), status: 'accepted', accepted_by: claimant, accepted_at: at, lease: null, updated_at: at,
+        };
+        try {
+            await this.db.transaction(tx => {
+                tx.collection(FELTDB_AGENT_HANDOFF_COLLECTION).set(id, accepted, { ifVersion: handoff.revision, expectedLeaseId: leaseId });
+            });
+        }
+        catch (error) {
+            if (error instanceof ConditionalConflictError) {
+                throw fail('HANDOFF_STALE', `the claim on handoff ${id} expired or was taken over before it was accepted`);
+            }
+            throw error;
+        }
+        const task = strip(await this.requireTask(handoff.task_id));
+        return this.resolveRecord({ ...accepted, revision: handoff.revision + 1 }, task);
+    }
+    // -------------------------------------------------------------- context
+    /**
+     * A provider-neutral, bounded context bundle assembled from committed
+     * state only.
+     *
+     * Required content — the task, the latest checkpoint's status, summary,
+     * pending work and constraints, every evidence reference, and the handoff —
+     * is never truncated: if it does not fit `maxBytes` the call fails with
+     * BUDGET_EXCEEDED. Decisions, memories, completed work and recent
+     * checkpoints fill the remainder newest first, and what did not fit is
+     * counted in `budget.omitted`.
+     */
+    async assembleContext(taskId, options) {
+        if (!Number.isInteger(options?.maxBytes) || options.maxBytes < 1) {
+            throw fail('INVALID_REQUEST', 'maxBytes must be a positive integer');
+        }
+        const loaded = await this.getTask(taskId);
+        if (!loaded)
+            throw fail('NOT_FOUND', `task ${taskId} does not exist`);
+        const { task, checkpoint } = loaded;
+        let handoff;
+        if (options.handoffId !== undefined) {
+            const resolved = await this.getHandoff(options.handoffId);
+            if (!resolved || resolved.task_id !== task.task_id)
+                throw fail('NOT_FOUND', `handoff ${options.handoffId} does not belong to task ${task.task_id}`);
+            handoff = {
+                handoff_id: resolved.handoff_id,
+                checkpoint_version: resolved.checkpoint_version,
+                status: resolved.status,
+                from: resolved.from,
+                ...(resolved.to ? { to: resolved.to } : {}),
+                ...(resolved.note ? { note: resolved.note } : {}),
+                memory_refs: resolved.memory_refs,
+                artifact_refs: resolved.artifact_refs,
+                evidence_refs: resolved.evidence_refs,
+            };
+        }
+        const memories = await this.recallForTask(task.task_id, { limit: options.memoryLimit });
+        const referenced = handoff ? new Set(handoff.memory_refs) : new Set();
+        // Memories the handoff names come first: the sender chose them.
+        memories.sort((left, right) => Number(referenced.has(right.memory_id)) - Number(referenced.has(left.memory_id)));
+        const recentPage = await this.db.query({
+            collection: FELTDB_AGENT_CHECKPOINT_COLLECTION,
+            where: [{ field: 'task_id', eq: task.task_id }],
+            orderBy: [{ field: 'version', direction: 'desc' }],
+            limit: boundedLimit(options.recentLimit, 5, 50),
+        });
+        const bundle = {
+            format: AGENT_CONTEXT_FORMAT,
+            task: {
+                task_id: task.task_id,
+                objective: task.objective,
+                scope: task.scope,
+                status: task.status,
+                owner: task.owner,
+                task_revision: task.revision,
+                checkpoint_version: task.checkpoint_version,
+            },
+            checkpoint: {
+                version: checkpoint.version,
+                status: checkpoint.status,
+                summary: checkpoint.summary,
+                actor: checkpoint.actor,
+                created_at: checkpoint.created_at,
+                pending_work: checkpoint.pending_work,
+                constraints: checkpoint.constraints,
+                completed_work: [],
+                decisions: [],
+            },
+            evidence: checkpoint.evidence,
+            ...(handoff ? { handoff } : {}),
+            memories: [],
+            recent: [],
+            budget: {
+                maxBytes: options.maxBytes,
+                usedBytes: 0,
+                unit: 'utf8-bytes',
+                omitted: { completed_work: 0, decisions: 0, memories: 0, recent: 0 },
+            },
+        };
+        // Measured with the widest possible counters so that filling them in
+        // later can never push a fitted bundle over the budget.
+        const widest = { completed_work: CUMULATIVE_LIMIT, decisions: CUMULATIVE_LIMIT, memories: CUMULATIVE_LIMIT, recent: CUMULATIVE_LIMIT };
+        const sizeOf = () => bytes(JSON.stringify({ ...bundle, budget: { ...bundle.budget, usedBytes: options.maxBytes, omitted: widest } }));
+        let used = sizeOf();
+        if (used > options.maxBytes) {
+            throw fail('BUDGET_EXCEEDED', `the required context for task ${task.task_id} is ${used} bytes, more than the ${options.maxBytes}-byte budget`, {
+                requiredBytes: used, maxBytes: options.maxBytes,
+            });
+        }
+        // Adding an element to a compact JSON array adds exactly its own
+        // serialization, plus one comma when the array is not empty.
+        const fill = (target, candidates, prepend) => {
+            let taken = 0;
+            for (const candidate of candidates) {
+                const cost = bytes(JSON.stringify(candidate)) + (target.length ? 1 : 0);
+                if (used + cost > options.maxBytes)
+                    break;
+                if (prepend)
+                    target.unshift(candidate);
+                else
+                    target.push(candidate);
+                used += cost;
+                taken += 1;
+            }
+            return candidates.length - taken;
+        };
+        bundle.budget.omitted.decisions = fill(bundle.checkpoint.decisions, [...checkpoint.decisions].reverse(), true);
+        bundle.budget.omitted.memories = fill(bundle.memories, memories.map(memory => ({
+            memory_id: memory.memory_id,
+            scope_key: memory.scope_key,
+            kind: memory.kind,
+            content: memory.content,
+            source: memory.source,
+            created_at: memory.created_at,
+        })), false);
+        bundle.budget.omitted.completed_work = fill(bundle.checkpoint.completed_work, [...checkpoint.completed_work].reverse(), true);
+        bundle.budget.omitted.recent = fill(bundle.recent, recentPage.records.map(row => ({
+            version: row.version,
+            status: row.status,
+            summary: row.summary,
+            actor: row.actor,
+            created_at: row.created_at,
+        })), false);
+        bundle.budget.usedBytes = 0;
+        bundle.budget.usedBytes = bytes(JSON.stringify(bundle));
+        // usedBytes counts its own digits; one pass settles it.
+        bundle.budget.usedBytes = bytes(JSON.stringify(bundle));
+        return bundle;
+    }
+    // ------------------------------------------------------------- internal
+    async taskRow(taskId) {
+        return this.db.collection(FELTDB_AGENT_TASK_COLLECTION).get(taskId);
+    }
+    async requireTask(taskId) {
+        const row = await this.taskRow(taskId);
+        if (!row)
+            throw fail('NOT_FOUND', `task ${taskId} does not exist`);
+        return row;
+    }
+    assertOwner(task, actor) {
+        if (task.owner !== actor) {
+            throw fail('OWNERSHIP_CONFLICT', `task ${task.task_id} is owned by ${task.owner}, not ${actor}`, { owner: task.owner });
+        }
+    }
+    async resolveEvidence(inputs, checkpointVersion) {
+        const resolved = [];
+        for (const [index, input] of inputs.entries()) {
+            const label = `evidence[${index}]`;
+            const description = input?.description === undefined ? {} : { description: text(input.description, `${label}.description`, 1_000) };
+            if (input?.kind === 'record') {
+                const collection = identifier(input.collection, `${label}.collection`, 128);
+                const id = identifier(input.id, `${label}.id`, 128);
+                const row = await this.db.collection(collection).get(id);
+                if (!row)
+                    throw fail('INVALID_REQUEST', `${label} cites ${collection}/${id}, which is not committed state`);
+                const actual = version(row);
+                if (input.version !== undefined && input.version !== actual) {
+                    throw fail('VERSION_CONFLICT', `${label} cites ${collection}/${id} at version ${input.version}; it is at ${actual}`);
+                }
+                resolved.push({ evidence: { kind: 'record', collection, id, version: actual, verified: true, ...description, checkpoint_version: checkpointVersion } });
+            }
+            else if (input?.kind === 'external') {
+                resolved.push({
+                    evidence: {
+                        kind: 'external',
+                        uri: text(input.uri, `${label}.uri`, 2_000),
+                        ...(input.digest === undefined ? {} : { digest: text(input.digest, `${label}.digest`, 256) }),
+                        verified: false,
+                        ...description,
+                        checkpoint_version: checkpointVersion,
+                    },
+                });
+            }
+            else {
+                throw fail('INVALID_REQUEST', `${label}.kind must be record or external`);
+            }
+        }
+        return resolved;
+    }
+    async resolveRecord(record, task) {
+        const checkpoint = await this.getCheckpoint(record.task_id, record.checkpoint_version);
+        if (!checkpoint)
+            throw fail('NOT_FOUND', `handoff ${record.handoff_id} references checkpoint ${record.checkpoint_version}, which is not committed`);
+        return resolveHandoff(record, task, checkpoint);
+    }
+}
+function resolveHandoff(record, task, checkpoint) {
+    return {
+        ...record,
+        objective: task.objective,
+        scope: task.scope,
+        constraints: checkpoint.constraints,
+        pending_work: checkpoint.pending_work,
+        completed_work: checkpoint.completed_work,
+        summary: checkpoint.summary,
+        current_checkpoint_version: task.checkpoint_version,
+        current_owner: task.owner,
+    };
+}
+function memorySource(source, actor, taskId) {
+    if (source.checkpointVersion !== undefined && (!Number.isInteger(source.checkpointVersion) || source.checkpointVersion < 1)) {
+        throw fail('INVALID_REQUEST', 'source.checkpointVersion must be a positive integer');
+    }
+    return {
+        actor,
+        ...(taskId ? { task_id: taskId } : {}),
+        ...(source.checkpointVersion === undefined ? {} : { checkpoint_version: source.checkpointVersion }),
+        ...(source.adapter === undefined ? {} : { adapter: name(source.adapter, 'source.adapter') }),
+        ...(source.evidence === undefined ? {} : { evidence: list(source.evidence, 'source.evidence') }),
+    };
+}
+function evidenceKey(entry) {
+    return entry.kind === 'record'
+        ? `record:${entry.collection}/${entry.id}@${entry.version}`
+        : `external:${entry.uri}#${entry.digest ?? ''}`;
+}
+function withoutRevision(value) {
+    const { revision: _revision, ...rest } = value;
+    return rest;
+}
+function boundedLimit(value, fallback, max) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isInteger(value) || value < 1 || value > max)
+        throw fail('INVALID_REQUEST', `limit must be an integer between 1 and ${max}`);
+    return value;
+}