@hunterzhu/pulse-runtime 0.1.0

package/dist/context/builder.d.ts

@@ -0,0 +1,68 @@
+import type { AgentRecord, ArtifactRef, LaneRecord, LLMRequestProjection, PrivacyLabel, PrivacyTaint, ResultRef, RuntimeState, JsonValue, ContextDelta } from '../core/types.js';
+export interface ContextBuildInput {
+    agent: AgentRecord;
+    lane: LaneRecord;
+    resultRefs?: ResultRef[];
+    artifactRefs?: ArtifactRef[];
+    eventIds?: string[];
+    instruction: string;
+    system?: string;
+    policy?: JsonValue;
+    tools?: JsonValue;
+    toolSetId: string;
+}
+export declare class ContextBuilder {
+    private readonly state;
+    readonly version = "1";
+    constructor(state: RuntimeState);
+    build(input: ContextBuildInput): LLMRequestProjection;
+}
+export declare function appendHistory(lane: LaneRecord, record: {
+    effectId?: string;
+    instruction: string;
+    resultRefs: string[];
+    resultSelection?: Array<{
+        ref: string;
+        rule: string;
+        hash: string;
+    }>;
+    result?: string;
+    findings?: string[];
+    output: JsonValue;
+    privacy: PrivacyLabel;
+    privacyTaints?: PrivacyTaint[];
+}): LaneRecord;
+/** A deterministic, conservative estimate used for admission rather than billing. */
+export declare function estimateHistoryTokens(history: ReadonlyArray<{
+    seq: number;
+    instruction: string;
+    resultRefs: string[];
+    output: JsonValue;
+    privacy: PrivacyLabel;
+}>): number;
+export declare function historyPressure(history: ReadonlyArray<{
+    seq: number;
+    instruction: string;
+    resultRefs: string[];
+    output: JsonValue;
+    privacy: PrivacyLabel;
+}>, softTokens: number, hardTokens: number): {
+    historyTokens: number;
+    softTokens: number;
+    hardTokens: number;
+} | undefined;
+export declare function stableSerialize(value: unknown): string;
+export declare function contentHash(value: unknown): string;
+export declare function isUnsafePathSegment(segment: string): boolean;
+export declare function hasUnsafePathSegment(path: readonly string[]): boolean;
+/** Own-property lookup that never walks the prototype chain. */
+export declare function ownChild(container: Record<string, JsonValue>, key: string): JsonValue | undefined;
+export interface RebaseConflict {
+    path: string[];
+    reason: 'changed_since_base' | 'append_target_changed' | 'history_compaction_requires_review';
+}
+export interface RebaseResult {
+    delta?: ContextDelta;
+    conflicts: RebaseConflict[];
+}
+export declare function rebaseContextDelta(delta: ContextDelta, baseState: JsonValue, currentState: JsonValue, currentVersion: number): RebaseResult;

package/dist/context/builder.js

@@ -0,0 +1,127 @@
+import { createHash } from 'node:crypto';
+import { effectivePrivacy, privacyRank, strictestPrivacy } from '../core/types.js';
+function stable(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stable).join(',')}]`;
+    return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${stable(item)}`).join(',')}}`;
+}
+function hash(value) { return createHash('sha256').update(stable(value)).digest('hex'); }
+export class ContextBuilder {
+    state;
+    version = '1';
+    constructor(state) {
+        this.state = state;
+    }
+    build(input) {
+        if (input.instruction.length > 2048)
+            throw new Error('INSTRUCTION_TOO_LARGE');
+        const global = input.agent.globalVersions.get(input.lane.contextSnapshotVersion);
+        if (global === undefined)
+            throw new Error('UNKNOWN_CONTEXT_VERSION');
+        const resultRefs = input.resultRefs ?? [];
+        const results = resultRefs.map((ref) => {
+            const result = this.state.results.get(ref);
+            if (!result)
+                throw new Error(`UNKNOWN_RESULT_REF:${ref}`);
+            if (input.lane.visibleResultRefs !== undefined && !input.lane.visibleResultRefs.has(ref))
+                throw new Error(`RESULT_NOT_VISIBLE:${ref}`);
+            return result;
+        });
+        const artifactRefs = input.artifactRefs ?? [];
+        const artifacts = artifactRefs.map((ref) => {
+            const artifact = this.state.artifacts.get(ref);
+            if (!artifact)
+                throw new Error(`UNKNOWN_ARTIFACT_REF:${ref}`);
+            if (artifact.agentId !== undefined && artifact.agentId !== input.agent.id)
+                throw new Error(`ARTIFACT_NOT_VISIBLE:${ref}`);
+            return artifact;
+        });
+        const globalMetadata = input.agent.globalPrivacy?.get(input.lane.contextSnapshotVersion) ?? { privacy: 'public' };
+        const laneMetadata = { privacy: input.lane.context.privacy ?? 'public', privacyTaints: input.lane.context.privacyTaints };
+        const effectiveResults = results.map((result) => ({ result, privacy: effectivePrivacy(result.privacy, result.privacyTaints) }));
+        const effectiveArtifacts = artifacts.map((artifact) => ({ artifact, privacy: effectivePrivacy(artifact.privacy, artifact.privacyTaints) }));
+        const privacy = strictestPrivacy([globalMetadata.privacy, laneMetadata.privacy, ...effectiveResults.map((item) => item.privacy), ...effectiveArtifacts.map((item) => item.privacy)]);
+        const privacyRefs = [
+            ...(privacyRank(globalMetadata.privacy) > 0 ? [`global:${input.lane.contextSnapshotVersion}`] : []),
+            ...(privacyRank(laneMetadata.privacy) > 0 ? [`lane:${input.lane.context.version}`] : []),
+            ...effectiveResults.filter((item) => privacyRank(item.privacy) > 0).map((item) => ({ kind: 'result', ref: item.result.id })),
+            ...effectiveArtifacts.filter((item) => privacyRank(item.privacy) > 0).map((item) => ({ kind: 'artifact', ref: item.artifact.ref })),
+        ];
+        const privacyTaints = [
+            ...(globalMetadata.privacyTaints ?? []).map((taint) => ({ path: ['global', ...taint.path], privacy: taint.privacy })),
+            ...(laneMetadata.privacyTaints ?? []).map((taint) => ({ path: ['lane', ...taint.path], privacy: taint.privacy })),
+            ...effectiveResults.flatMap((item) => (item.result.privacyTaints ?? []).map((taint) => ({ path: [item.result.id, ...taint.path], privacy: taint.privacy }))),
+            ...effectiveArtifacts.flatMap((item) => (item.artifact.privacyTaints ?? []).map((taint) => ({ path: [item.artifact.ref, ...taint.path], privacy: taint.privacy }))),
+        ];
+        const contextSpec = { globalSnapshotVersion: input.lane.contextSnapshotVersion, laneSnapshotVersion: input.lane.context.version, resultRefs, ...(artifactRefs.length ? { artifactRefs } : {}), eventIds: input.eventIds ?? [], toolSetId: input.toolSetId, instruction: input.instruction, privacy, privacyRefs, ...(privacyTaints.length ? { privacyTaints } : {}) };
+        const prefixBlocks = [
+            { kind: 'system', content: input.system ?? '' },
+            { kind: 'policy', content: input.policy ?? {} },
+            { kind: 'tools', content: input.tools ?? {} },
+            { kind: 'global', content: global },
+            { kind: 'history', content: input.lane.context.history.map((record) => ({ seq: record.seq, ...(record.effectId === undefined ? {} : { effectId: record.effectId }), instruction: record.instruction, resultRefs: record.resultRefs, ...(record.resultSelection === undefined ? {} : { resultSelection: record.resultSelection }), ...(record.result === undefined ? {} : { result: record.result }), ...(record.findings === undefined ? {} : { findings: record.findings }), output: record.output, privacy: record.privacy, ...(record.privacyTaints === undefined ? {} : { privacyTaints: record.privacyTaints }) })) },
+        ];
+        const blocks = [...prefixBlocks, { kind: 'lane', content: input.lane.context.state }, { kind: 'events', content: input.eventIds ?? [] }, { kind: 'results', content: results.map((result) => ({ id: result.id, value: result.value ?? null, ...(result.privacyTaints === undefined ? {} : { privacyTaints: result.privacyTaints.map((taint) => ({ path: [...taint.path], privacy: taint.privacy })) }) })) }, { kind: 'artifacts', content: artifacts.map((artifact) => ({ ref: artifact.ref, mediaType: artifact.mediaType, sizeBytes: artifact.sizeBytes, contentHash: artifact.contentHash })) }, { kind: 'instruction', content: input.instruction }];
+        return { contextSpec, blocks, prefixHash: hash(prefixBlocks), projectionHash: hash(blocks), builderVersion: this.version, policyVersion: '1', toolSetVersion: input.toolSetId, privacy, privacyRefs, ...(privacyTaints.length ? { privacyTaints } : {}) };
+    }
+}
+export function appendHistory(lane, record) {
+    const next = structuredClone(lane);
+    const seq = next.context.history.length ? next.context.history[next.context.history.length - 1].seq + 1 : 1;
+    next.context.history.push({ seq, ...record });
+    next.context.version += 1;
+    return next;
+}
+/** A deterministic, conservative estimate used for admission rather than billing. */
+export function estimateHistoryTokens(history) {
+    return Math.ceil(Buffer.byteLength(stableSerialize(history), 'utf8') / 4);
+}
+export function historyPressure(history, softTokens, hardTokens) {
+    const historyTokens = estimateHistoryTokens(history);
+    return historyTokens > softTokens ? { historyTokens, softTokens, hardTokens } : undefined;
+}
+export function stableSerialize(value) { return stable(value); }
+export function contentHash(value) { return hash(value); }
+/**
+ * Path segments that would reach the prototype chain instead of own data. Any
+ * ContextDelta, MergeProposal or draft-proxy path containing one of these is
+ * rejected before it can touch `Object.prototype`.
+ */
+const UNSAFE_PATH_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
+export function isUnsafePathSegment(segment) { return UNSAFE_PATH_SEGMENTS.has(segment); }
+export function hasUnsafePathSegment(path) { return path.some(isUnsafePathSegment); }
+/** Own-property lookup that never walks the prototype chain. */
+export function ownChild(container, key) { return Object.hasOwn(container, key) ? container[key] : undefined; }
+function atPath(value, path) {
+    let current = value;
+    for (const part of path) {
+        if (!current || typeof current !== 'object' || Array.isArray(current) || isUnsafePathSegment(part))
+            return undefined;
+        current = ownChild(current, part);
+    }
+    return current;
+}
+function equal(a, b) { return stableSerialize(a) === stableSerialize(b); }
+export function rebaseContextDelta(delta, baseState, currentState, currentVersion) {
+    const conflicts = [];
+    for (const op of delta.ops) {
+        if (op.op === 'compact_history') {
+            conflicts.push({ path: ['history'], reason: 'history_compaction_requires_review' });
+            continue;
+        }
+        const path = op.path ?? [];
+        const baseValue = atPath(baseState, path);
+        const currentValue = atPath(currentState, path);
+        if (op.op === 'append') {
+            if (!Array.isArray(baseValue) || !Array.isArray(currentValue) || currentValue.length < baseValue.length || !baseValue.every((item, index) => equal(item, currentValue[index])))
+                conflicts.push({ path, reason: 'append_target_changed' });
+        }
+        else if (!equal(baseValue, currentValue))
+            conflicts.push({ path, reason: 'changed_since_base' });
+    }
+    if (conflicts.length)
+        return { conflicts };
+    return { conflicts: [], delta: { ...delta, baseVersion: currentVersion } };
+}

package/dist/context/index.d.ts

@@ -0,0 +1,2 @@
+export * from './builder.js';
+export * from './merger.js';

package/dist/context/index.js

@@ -0,0 +1,2 @@
+export * from './builder.js';
+export * from './merger.js';

package/dist/context/merger.d.ts

@@ -0,0 +1,25 @@
+import { type RebaseConflict } from './builder.js';
+import type { Mutation } from '../core/mutations.js';
+import type { AgentRecord, JsonValue, RuntimeState } from '../core/types.js';
+export interface MergeConflict {
+    proposalId: string;
+    sourceLaneId: string;
+    baseGlobalVersion: number;
+    conflicts: RebaseConflict[];
+}
+export interface MergePlan {
+    agentId: string;
+    version?: number;
+    value?: JsonValue;
+    appliedProposalIds: string[];
+    conflicts: MergeConflict[];
+    mutations: Mutation[];
+}
+export declare class ContextMerger {
+    private readonly state;
+    constructor(state: RuntimeState);
+    plan(agentId: string, proposalIds?: string[]): MergePlan;
+    commit(agentId: string, proposalIds?: string[]): MergePlan;
+}
+export declare function mergeProposals(state: RuntimeState, agentId: string, proposalIds?: string[]): MergePlan;
+export type { AgentRecord };

package/dist/context/merger.js

@@ -0,0 +1,125 @@
+import { hasUnsafePathSegment, ownChild, rebaseContextDelta, stableSerialize } from './builder.js';
+import { apply } from '../core/mutations.js';
+import { privacyTaintPrivacy, strictestPrivacy } from '../core/types.js';
+function clone(value) { return structuredClone(value); }
+function setPath(root, path, value) {
+    let cursor = root;
+    for (const part of path.slice(0, -1)) {
+        const child = ownChild(cursor, part);
+        if (!child || typeof child !== 'object' || Array.isArray(child))
+            cursor[part] = {};
+        cursor = cursor[part];
+    }
+    cursor[path[path.length - 1]] = clone(value);
+}
+function removePath(root, path) {
+    let cursor = root;
+    for (const part of path.slice(0, -1)) {
+        if (!cursor || typeof cursor !== 'object' || Array.isArray(cursor))
+            return;
+        const next = ownChild(cursor, part);
+        if (next === undefined)
+            return;
+        cursor = next;
+    }
+    if (cursor && typeof cursor === 'object' && !Array.isArray(cursor))
+        delete cursor[path[path.length - 1]];
+}
+function applyDelta(root, delta) {
+    const result = clone(root);
+    for (const op of delta.ops) {
+        if (op.op === 'compact_history')
+            throw new Error('GLOBAL_HISTORY_COMPACTION_NOT_ALLOWED');
+        const path = op.path ?? [];
+        if (path.length === 0 || hasUnsafePathSegment(path))
+            throw new Error('INVALID_CONTEXT_PATH');
+        if (op.op === 'set')
+            setPath(result, path, op.value ?? null);
+        else if (op.op === 'remove')
+            removePath(result, path);
+        else {
+            let cursor = result;
+            for (const part of path) {
+                if (!cursor || typeof cursor !== 'object' || Array.isArray(cursor))
+                    throw new Error('APPEND_TARGET_NOT_ARRAY');
+                const next = ownChild(cursor, part);
+                if (next === undefined)
+                    throw new Error('APPEND_TARGET_NOT_ARRAY');
+                cursor = next;
+            }
+            if (!Array.isArray(cursor))
+                throw new Error('APPEND_TARGET_NOT_ARRAY');
+            cursor.push(clone(op.value ?? null));
+        }
+    }
+    return result;
+}
+function proposalOrder(proposals) {
+    return [...proposals].sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id));
+}
+export class ContextMerger {
+    state;
+    constructor(state) {
+        this.state = state;
+    }
+    plan(agentId, proposalIds) {
+        const agent = this.state.agents.get(agentId);
+        if (!agent)
+            throw new Error(`UNKNOWN_AGENT:${agentId}`);
+        const wanted = proposalIds === undefined ? undefined : new Set(proposalIds);
+        const proposals = proposalOrder([...this.state.mergeProposals.values()].filter((proposal) => proposal.agentId === agentId && (wanted === undefined || wanted.has(proposal.id))));
+        let version = agent.latestGlobalVersion;
+        let value = clone(agent.globalVersions.get(version) ?? {});
+        let metadata = clone(agent.globalPrivacy?.get(version) ?? { privacy: 'public' });
+        const appliedProposalIds = [];
+        const conflicts = [];
+        const mutations = [];
+        const versionMutations = [];
+        for (const proposal of proposals) {
+            const base = agent.globalVersions.get(proposal.baseGlobalVersion);
+            if (base === undefined) {
+                conflicts.push({ proposalId: proposal.id, sourceLaneId: proposal.sourceLaneId, baseGlobalVersion: proposal.baseGlobalVersion, conflicts: [{ path: [], reason: 'changed_since_base' }] });
+                continue;
+            }
+            const rebased = rebaseContextDelta(proposal.delta, base, value, version);
+            if (!rebased.delta || rebased.conflicts.length) {
+                conflicts.push({ proposalId: proposal.id, sourceLaneId: proposal.sourceLaneId, baseGlobalVersion: proposal.baseGlobalVersion, conflicts: rebased.conflicts });
+                continue;
+            }
+            try {
+                const next = applyDelta(value, rebased.delta);
+                const nextMetadata = {
+                    privacy: strictestPrivacy([metadata.privacy, proposal.delta.privacy ?? 'public', privacyTaintPrivacy(proposal.delta.privacyTaints)]),
+                    ...(metadata.privacyTaints?.length || proposal.delta.privacyTaints?.length ? { privacyTaints: [...(metadata.privacyTaints ?? []), ...(proposal.delta.privacyTaints ?? [])] } : {}),
+                };
+                if (stableSerialize(next) !== stableSerialize(value) || stableSerialize(nextMetadata) !== stableSerialize(metadata)) {
+                    value = next;
+                    version++;
+                    // Every version number that is handed out must exist in `globalVersions`;
+                    // otherwise `adopt_context(version)` for an intermediate version fails.
+                    versionMutations.push({ op: 'setGlobal', agentId, version, value: clone(value), metadata: clone(nextMetadata) });
+                }
+                metadata = nextMetadata;
+                appliedProposalIds.push(proposal.id);
+                mutations.push({ op: 'removeMergeProposal', proposalId: proposal.id });
+            }
+            catch (cause) {
+                conflicts.push({ proposalId: proposal.id, sourceLaneId: proposal.sourceLaneId, baseGlobalVersion: proposal.baseGlobalVersion, conflicts: [{ path: [], reason: 'changed_since_base' }] });
+            }
+        }
+        if (appliedProposalIds.length) {
+            mutations.unshift(...versionMutations);
+            mutations.push({ op: 'appendEvent', event: { type: 'context.merge_committed', agentId, data: { version, proposalIds: appliedProposalIds } } });
+        }
+        return { agentId, ...(appliedProposalIds.length ? { version, value: clone(value) } : {}), appliedProposalIds, conflicts, mutations };
+    }
+    commit(agentId, proposalIds) {
+        const plan = this.plan(agentId, proposalIds);
+        if (plan.conflicts.length)
+            return plan;
+        if (plan.mutations.length)
+            apply(this.state, plan.mutations);
+        return plan;
+    }
+}
+export function mergeProposals(state, agentId, proposalIds) { return new ContextMerger(state).commit(agentId, proposalIds); }

package/dist/core/actions.d.ts

@@ -0,0 +1 @@
+export type { RuntimeAction, SubmitEffectsAction, WaitAction, ForkAction, CancelLaneAction, ProposeCancelAction, CompleteAction, FailAction, AdoptContextAction, EffectSubmission, ForkLaneSpec, SeriesLaneSpec } from './types.js';

package/dist/core/actions.js

@@ -0,0 +1 @@
+export {};

package/dist/core/errors.d.ts

@@ -0,0 +1,8 @@
+import type { RuntimeError } from './types.js';
+export declare class ControlError extends Error {
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(error: RuntimeError);
+}
+export declare function error(code: string, message: string, details?: unknown): RuntimeError;
+export declare function runtimeErrorFromCause(cause: unknown, fallbackCode?: string): RuntimeError;

package/dist/core/errors.js

@@ -0,0 +1,36 @@
+export class ControlError extends Error {
+    code;
+    details;
+    constructor(error) {
+        super(error.message);
+        this.name = 'ControlError';
+        this.code = error.code;
+        this.details = error.details;
+    }
+}
+export function error(code, message, details) {
+    return { code, message, ...(details === undefined ? {} : { details: details }) };
+}
+export function runtimeErrorFromCause(cause, fallbackCode = 'EFFECT_FAILED') {
+    if (typeof cause === 'object' && cause !== null) {
+        const candidate = cause;
+        const code = typeof candidate.code === 'string' ? candidate.code : fallbackCode;
+        const message = typeof candidate.message === 'string' ? candidate.message : cause instanceof Error ? cause.message : String(cause);
+        return {
+            code,
+            message,
+            ...(typeof candidate.retryable === 'boolean' ? { retryable: candidate.retryable } : {}),
+            ...(isJsonValue(candidate.details) ? { details: candidate.details } : {}),
+        };
+    }
+    return { code: fallbackCode, message: cause instanceof Error ? cause.message : String(cause) };
+}
+function isJsonValue(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean' || typeof value === 'number')
+        return true;
+    if (Array.isArray(value))
+        return value.every(isJsonValue);
+    if (typeof value !== 'object')
+        return false;
+    return Object.values(value).every(isJsonValue);
+}

package/dist/core/events.d.ts

@@ -0,0 +1,10 @@
+import type { RuntimeEvent, RuntimeEventInput, RuntimeState } from './types.js';
+export type { RuntimeEvent, RuntimeEventInput, ResumeInput, WaitResolution, Outcome } from './types.js';
+export declare function normalizeRuntimeEvent(input: RuntimeEventInput, seq: number, defaults?: {
+    sessionId?: string;
+    timestamp?: number;
+}): RuntimeEvent;
+export declare function appendRuntimeEvent(state: RuntimeState, input: RuntimeEventInput, defaults?: {
+    sessionId?: string;
+    timestamp?: number;
+}): RuntimeEvent;

package/dist/core/events.js

@@ -0,0 +1,24 @@
+export function normalizeRuntimeEvent(input, seq, defaults = {}) {
+    const payload = input.payload ?? input.data ?? null;
+    return {
+        id: input.id ?? `event-${seq}`,
+        schemaVersion: input.schemaVersion ?? 1,
+        sessionId: input.sessionId ?? defaults.sessionId ?? 'session-unknown',
+        seq,
+        timestamp: input.timestamp ?? defaults.timestamp ?? 0,
+        type: input.type,
+        ...(input.txId === undefined ? {} : { txId: input.txId }),
+        ...(input.agentId === undefined ? {} : { agentId: input.agentId }),
+        ...(input.laneId === undefined ? {} : { laneId: input.laneId }),
+        ...(input.effectId === undefined ? {} : { effectId: input.effectId }),
+        ...(input.attemptId === undefined ? {} : { attemptId: input.attemptId }),
+        ...(input.causationId === undefined ? {} : { causationId: input.causationId }),
+        payload,
+        ...(input.data === undefined ? { data: payload } : { data: input.data }),
+    };
+}
+export function appendRuntimeEvent(state, input, defaults = {}) {
+    const event = normalizeRuntimeEvent(input, state.nextIds.event++, { ...(defaults.sessionId === undefined ? {} : { sessionId: defaults.sessionId }), timestamp: defaults.timestamp ?? state.now });
+    state.events.push(event);
+    return event;
+}

package/dist/core/factory.d.ts

@@ -0,0 +1,35 @@
+import type { AgentRecord, LaneRecord, ResumePoint, RuntimeState, JsonValue } from './types.js';
+export interface AgentBuildResult {
+    agent: AgentRecord;
+    root: LaneRecord;
+    nextIds: RuntimeState['nextIds'];
+}
+export declare function buildAgent(state: RuntimeState, goal: string, resume: ResumePoint, options?: {
+    agentId?: string;
+    maxActiveLanes?: number;
+    priority?: number;
+    initialGlobal?: JsonValue;
+    initialGlobalPrivacy?: import('./types.js').PrivacyMetadata;
+    parentAgentId?: string;
+    depth?: number;
+    inheritedFloor?: number;
+    policyId?: string;
+    limitsId?: string;
+    deadlineAt?: number;
+}): AgentBuildResult;
+export declare function createAgent(state: RuntimeState, goal: string, resume: ResumePoint, options?: {
+    agentId?: string;
+    maxActiveLanes?: number;
+    priority?: number;
+    initialGlobal?: JsonValue;
+    initialGlobalPrivacy?: import('./types.js').PrivacyMetadata;
+    parentAgentId?: string;
+    depth?: number;
+    inheritedFloor?: number;
+    policyId?: string;
+    limitsId?: string;
+    deadlineAt?: number;
+}): {
+    agent: AgentRecord;
+    root: LaneRecord;
+};

package/dist/core/factory.js

@@ -0,0 +1,27 @@
+export function buildAgent(state, goal, resume, options = {}) {
+    let agentSequence = state.nextIds.agent;
+    let agentId = options.agentId ?? `agent-${agentSequence}`;
+    if (options.agentId === undefined)
+        while (state.agents.has(agentId)) {
+            agentSequence++;
+            agentId = `agent-${agentSequence}`;
+        }
+    let laneSequence = state.nextIds.lane;
+    let rootId = `lane-${laneSequence}`;
+    while (state.lanes.has(rootId)) {
+        laneSequence++;
+        rootId = `lane-${laneSequence}`;
+    }
+    const initialPrivacy = structuredClone(options.initialGlobalPrivacy ?? { privacy: 'public' });
+    const agent = { id: agentId, rootLaneId: rootId, goal, state: 'created', globalVersions: new Map([[0, structuredClone(options.initialGlobal ?? {})]]), globalPrivacy: new Map([[0, initialPrivacy]]), latestGlobalVersion: 0, maxActiveLanes: options.maxActiveLanes ?? 64, ...(options.policyId === undefined ? {} : { policyId: options.policyId }), ...(options.limitsId === undefined ? {} : { limitsId: options.limitsId }), ...(options.deadlineAt === undefined ? {} : { deadlineAt: options.deadlineAt }), ...(options.parentAgentId === undefined ? {} : { parentAgentId: options.parentAgentId }), ...(options.depth === undefined ? {} : { depth: options.depth }) };
+    const root = { id: rootId, agentId, status: 'ready', version: 0, goal, resume, contextSnapshotVersion: 0, context: { version: 0, history: [], state: {}, privacy: 'public' }, visibleResultRefs: new Set(), children: new Set(), priority: options.priority ?? 0, ...(options.inheritedFloor === undefined ? {} : { inheritedFloor: options.inheritedFloor }), enqueueSeq: 0, readySince: state.now, ownedEffectIds: new Set() };
+    return { agent, root, nextIds: { ...state.nextIds, agent: Math.max(state.nextIds.agent + 1, agentSequence + 1), lane: laneSequence + 1 } };
+}
+export function createAgent(state, goal, resume, options = {}) {
+    const built = buildAgent(state, goal, resume, options);
+    state.nextIds = built.nextIds;
+    const { agent, root } = built;
+    state.agents.set(agent.id, agent);
+    state.lanes.set(root.id, root);
+    return { agent, root };
+}

package/dist/core/inbox.d.ts

@@ -0,0 +1,119 @@
+import type { JsonValue } from './types.js';
+export interface FactEnvelope<T extends JsonValue = JsonValue> {
+    eventId: string;
+    receivedSeq: number;
+    fact: T;
+}
+export interface FactInboxDedupeEntry {
+    eventId: string;
+    receivedSeq: number;
+}
+/**
+ * A durable, exact membership view for event ids already archived by a
+ * checkpoint. `contains(eventId)` is used on the hot enqueue path, while the
+ * sequence argument lets compaction verify that the archive contains the
+ * exact ledger entry rather than only an unrelated event with the same shape.
+ *
+ * Implementations must make the view durable before acknowledging an archive
+ * batch to FactInbox. The interface is synchronous on purpose: enqueue() is a
+ * synchronous single-writer boundary and cannot safely await a storage query.
+ */
+export interface FactInboxDedupeArchive {
+    readonly archiveId: string;
+    /** Highest contiguous receivedSeq durably present in this archive. */
+    readonly watermark: number;
+    contains(eventId: string, receivedSeq?: number): boolean;
+    /** Digest of the exact archived ledger prefix through `watermark`. */
+    digestThrough(through: number): string;
+}
+/**
+ * A durable archive writer used by checkpoint implementations. Membership
+ * reads stay synchronous for the FactInbox hot path; checkpoint writes are
+ * explicitly asynchronous and must be durable before compaction is acked.
+ */
+export interface FactInboxDedupeArchiveWriter extends FactInboxDedupeArchive {
+    append(batch: FactInboxDedupeArchiveBatch): Promise<void>;
+}
+export interface FactInboxDedupeArchiveBatch {
+    schemaVersion: 1;
+    archiveId: string;
+    through: number;
+    ledgerDigest: string;
+    entries: FactInboxDedupeEntry[];
+}
+export interface FactInboxDedupeLedgerSnapshot {
+    schemaVersion: 1;
+    archivedThrough: number;
+    entries: FactInboxDedupeEntry[];
+    /** Event ids restored from the pre-ledger v1 snapshot format. */
+    legacyEventIds?: string[];
+    archiveId?: string;
+    archiveDigest?: string;
+}
+export declare function factInboxDedupeDigestFrom(previousDigest: string, entries: readonly FactInboxDedupeEntry[]): string;
+export declare function factInboxDedupeDigest(entries: readonly FactInboxDedupeEntry[]): string;
+export interface FactInboxSnapshot<T extends JsonValue = JsonValue> {
+    schemaVersion: 1 | 2;
+    nextSeq: number;
+    seen: string[];
+    queue: FactEnvelope<T>[];
+    dedupeLedger?: FactInboxDedupeLedgerSnapshot;
+}
+export declare class FactInbox<T extends JsonValue = JsonValue> {
+    private readonly queue;
+    private readonly seen;
+    private nextSeq;
+    private archivedThrough;
+    private dedupeArchive;
+    constructor(options?: {
+        dedupeArchive?: FactInboxDedupeArchive;
+    });
+    /** Attach a backend-provided archive before the first compaction. */
+    attachDedupeArchive(archive: FactInboxDedupeArchive): void;
+    enqueue(fact: T, eventId: string): FactEnvelope<T> | undefined;
+    drain(limit?: number): FactEnvelope<T>[];
+    get size(): number;
+    get dedupeWatermark(): number;
+    has(eventId: string): boolean;
+    snapshot(): FactInboxSnapshot<T>;
+    /**
+     * Build the exact ledger batch that a durable checkpoint/archive must
+     * acknowledge before local dedupe entries can be compacted.
+     */
+    createDedupeArchiveBatch(through?: number): FactInboxDedupeArchiveBatch;
+    /**
+     * Acknowledge a batch only after its exact entries are durably archived.
+     * This is the sole operation that advances the watermark or removes local
+     * dedupe entries; clear() intentionally does not affect deduplication.
+     */
+    compactDedupeThrough(batch: FactInboxDedupeArchiveBatch): number;
+    restore(snapshot: FactInboxSnapshot<T> | JsonValue): void;
+    static fromSnapshot<T extends JsonValue = JsonValue>(snapshot: FactInboxSnapshot<T> | JsonValue, options?: {
+        dedupeArchive?: FactInboxDedupeArchive;
+    }): FactInbox<T>;
+    clear(): void;
+}
+export interface ObservationEnvelope {
+    seq: number;
+    agentId: string;
+    laneId?: string;
+    type: 'progress' | 'chunk' | 'trace' | 'warning' | 'diagnostic';
+    data: JsonValue;
+    timestamp: number;
+}
+export declare class ObservationInbox {
+    readonly maxEntries: number;
+    readonly maxBytes: number;
+    private readonly queue;
+    private readonly droppedThroughByAgent;
+    private bytes;
+    private nextSeq;
+    constructor(maxEntries?: number, maxBytes?: number);
+    enqueue(input: Omit<ObservationEnvelope, 'seq'>): ObservationEnvelope;
+    drain(agentId?: string): ObservationEnvelope[];
+    get size(): number;
+    get sizeBytes(): number;
+    droppedThrough(agentId: string): number;
+    snapshot(): ObservationEnvelope[];
+    private eventBytes;
+}