@hunterzhu/pulse-runtime 0.1.0

package/dist/core/inbox.js

@@ -0,0 +1,217 @@
+import { createHash } from 'node:crypto';
+const EMPTY_FACT_INBOX_DEDUPE_DIGEST = createHash('sha256').update('pulse.fact-inbox.dedupe.v1').digest('hex');
+export function factInboxDedupeDigestFrom(previousDigest, entries) {
+    let digest = previousDigest;
+    for (const entry of entries)
+        digest = createHash('sha256').update(`${digest}\u0000${entry.eventId}\u0000${entry.receivedSeq}`).digest('hex');
+    return digest;
+}
+export function factInboxDedupeDigest(entries) {
+    return factInboxDedupeDigestFrom(EMPTY_FACT_INBOX_DEDUPE_DIGEST, entries);
+}
+export class FactInbox {
+    queue = [];
+    seen = new Map();
+    nextSeq = 1;
+    archivedThrough = 0;
+    dedupeArchive;
+    constructor(options = {}) {
+        this.dedupeArchive = options.dedupeArchive;
+    }
+    /** Attach a backend-provided archive before the first compaction. */
+    attachDedupeArchive(archive) {
+        if (this.dedupeArchive !== undefined && this.dedupeArchive !== archive)
+            throw new Error('FACT_INBOX_DEDUPE_ARCHIVE_MISMATCH');
+        if (this.archivedThrough > 0)
+            throw new Error('FACT_INBOX_DEDUPE_ARCHIVE_ALREADY_COMPACTED');
+        this.dedupeArchive = archive;
+    }
+    enqueue(fact, eventId) {
+        if (!eventId || this.seen.has(eventId) || this.dedupeArchive?.contains(eventId))
+            return undefined;
+        const envelope = { eventId, receivedSeq: this.nextSeq++, fact: structuredClone(fact) };
+        this.seen.set(eventId, envelope.receivedSeq);
+        this.queue.push(envelope);
+        return structuredClone(envelope);
+    }
+    drain(limit = Number.POSITIVE_INFINITY) {
+        if (limit !== Number.POSITIVE_INFINITY && (!Number.isInteger(limit) || limit < 0))
+            throw new Error('INVALID_FACT_DRAIN_LIMIT');
+        return this.queue.splice(0, limit).map((envelope) => structuredClone(envelope));
+    }
+    get size() { return this.queue.length; }
+    get dedupeWatermark() { return this.archivedThrough; }
+    has(eventId) { return this.seen.has(eventId) || Boolean(this.dedupeArchive?.contains(eventId)); }
+    snapshot() {
+        const entries = [...this.seen.entries()].filter((entry) => entry[1] !== undefined).map(([eventId, receivedSeq]) => ({ eventId, receivedSeq }));
+        const legacyEventIds = [...this.seen.entries()].filter((entry) => entry[1] === undefined).map(([eventId]) => eventId);
+        return {
+            schemaVersion: 2,
+            nextSeq: this.nextSeq,
+            seen: [...this.seen.keys()],
+            queue: this.queue.map((envelope) => structuredClone(envelope)),
+            dedupeLedger: {
+                schemaVersion: 1,
+                archivedThrough: this.archivedThrough,
+                entries,
+                ...(legacyEventIds.length === 0 ? {} : { legacyEventIds }),
+                ...(this.archivedThrough === 0 || this.dedupeArchive === undefined ? {} : { archiveId: this.dedupeArchive.archiveId, archiveDigest: this.dedupeArchive.digestThrough(this.archivedThrough) }),
+            },
+        };
+    }
+    /**
+     * Build the exact ledger batch that a durable checkpoint/archive must
+     * acknowledge before local dedupe entries can be compacted.
+     */
+    createDedupeArchiveBatch(through = this.nextSeq - 1) {
+        if (!Number.isInteger(through) || through < this.archivedThrough || through >= this.nextSeq)
+            throw new Error('INVALID_FACT_INBOX_DEDUPE_WATERMARK');
+        const bySeq = new Map();
+        for (const [eventId, receivedSeq] of this.seen) {
+            if (receivedSeq !== undefined && receivedSeq > this.archivedThrough && receivedSeq <= through)
+                bySeq.set(receivedSeq, { eventId, receivedSeq });
+        }
+        const entries = [];
+        for (let receivedSeq = this.archivedThrough + 1; receivedSeq <= through; receivedSeq++) {
+            const entry = bySeq.get(receivedSeq);
+            if (!entry)
+                throw new Error('FACT_INBOX_DEDUPE_LEDGER_INCOMPLETE');
+            entries.push({ ...entry });
+        }
+        if (!this.dedupeArchive || this.dedupeArchive.watermark < this.archivedThrough)
+            throw new Error('FACT_INBOX_DEDUPE_ARCHIVE_REQUIRED');
+        return { schemaVersion: 1, archiveId: this.dedupeArchive.archiveId, through, ledgerDigest: factInboxDedupeDigestFrom(this.dedupeArchive.digestThrough(this.archivedThrough), entries), entries };
+    }
+    /**
+     * 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) {
+        if (!batch || batch.schemaVersion !== 1 || !Number.isInteger(batch.through) || batch.through < 1 || batch.archiveId !== this.dedupeArchive?.archiveId)
+            throw new Error('INVALID_FACT_INBOX_DEDUPE_ARCHIVE_BATCH');
+        if (batch.through <= this.archivedThrough)
+            return 0;
+        const expected = this.createDedupeArchiveBatch(batch.through);
+        if (expected.ledgerDigest !== batch.ledgerDigest || expected.entries.length !== batch.entries.length || expected.entries.some((entry, index) => entry.eventId !== batch.entries[index]?.eventId || entry.receivedSeq !== batch.entries[index]?.receivedSeq))
+            throw new Error('INVALID_FACT_INBOX_DEDUPE_ARCHIVE_BATCH');
+        if (this.queue.some((envelope) => envelope.receivedSeq <= batch.through))
+            throw new Error('FACT_INBOX_DEDUPE_PENDING_FACTS');
+        if (this.dedupeArchive.watermark < batch.through)
+            throw new Error('FACT_INBOX_DEDUPE_ARCHIVE_NOT_DURABLE');
+        for (const entry of expected.entries)
+            if (!this.dedupeArchive.contains(entry.eventId, entry.receivedSeq))
+                throw new Error('FACT_INBOX_DEDUPE_ARCHIVE_NOT_DURABLE');
+        if (this.dedupeArchive.digestThrough(batch.through) !== batch.ledgerDigest)
+            throw new Error('FACT_INBOX_DEDUPE_ARCHIVE_NOT_DURABLE');
+        for (const entry of expected.entries)
+            this.seen.delete(entry.eventId);
+        this.archivedThrough = batch.through;
+        return expected.entries.length;
+    }
+    restore(snapshot) {
+        const restored = FactInbox.fromSnapshot(snapshot, this.dedupeArchive === undefined ? {} : { dedupeArchive: this.dedupeArchive });
+        this.queue.splice(0, this.queue.length, ...restored.queue.map((envelope) => structuredClone(envelope)));
+        this.seen.clear();
+        for (const [eventId, receivedSeq] of restored.seen)
+            this.seen.set(eventId, receivedSeq);
+        this.nextSeq = restored.nextSeq;
+        this.archivedThrough = restored.archivedThrough;
+    }
+    static fromSnapshot(snapshot, options = {}) {
+        const value = snapshot;
+        if (!value || (value.schemaVersion !== 1 && value.schemaVersion !== 2) || !Number.isInteger(value.nextSeq) || value.nextSeq < 1 || !Array.isArray(value.seen) || value.seen.some((eventId) => typeof eventId !== 'string' || eventId.length === 0) || !Array.isArray(value.queue))
+            throw new Error('INVALID_FACT_INBOX_SNAPSHOT');
+        if (new Set(value.seen).size !== value.seen.length)
+            throw new Error('INVALID_FACT_INBOX_SNAPSHOT');
+        const ledger = value.dedupeLedger;
+        if (ledger !== undefined && (ledger.schemaVersion !== 1 || !Number.isInteger(ledger.archivedThrough) || ledger.archivedThrough < 0 || ledger.archivedThrough >= value.nextSeq || !Array.isArray(ledger.entries) || !Array.isArray(ledger.legacyEventIds ?? []) || ledger.entries.some((entry) => !entry || typeof entry.eventId !== 'string' || entry.eventId.length === 0 || !Number.isInteger(entry.receivedSeq) || entry.receivedSeq < 1 || entry.receivedSeq <= ledger.archivedThrough || entry.receivedSeq >= value.nextSeq) || ledger.legacyEventIds?.some((eventId) => typeof eventId !== 'string' || eventId.length === 0) || (ledger.archivedThrough > 0 && ((ledger.legacyEventIds ?? []).length > 0 || !ledger.archiveId || !ledger.archiveDigest || !/^[a-f0-9]{64}$/.test(ledger.archiveDigest))) || (ledger.archivedThrough === 0 && ledger.archiveDigest !== undefined) || new Set(ledger.entries.map((entry) => entry.eventId)).size !== ledger.entries.length || new Set(ledger.entries.map((entry) => entry.receivedSeq)).size !== ledger.entries.length || new Set(ledger.legacyEventIds ?? []).size !== (ledger.legacyEventIds ?? []).length || ledger.entries.some((entry) => (ledger.legacyEventIds ?? []).includes(entry.eventId))))
+            throw new Error('INVALID_FACT_INBOX_SNAPSHOT');
+        if (ledger?.archivedThrough && (!options.dedupeArchive || ledger.archiveId !== options.dedupeArchive.archiveId || options.dedupeArchive.watermark < ledger.archivedThrough || options.dedupeArchive.digestThrough(ledger.archivedThrough) !== ledger.archiveDigest))
+            throw new Error('FACT_INBOX_DEDUPE_ARCHIVE_REQUIRED');
+        const inbox = new FactInbox(options);
+        const seen = new Map();
+        if (ledger) {
+            for (const entry of ledger.entries)
+                seen.set(entry.eventId, entry.receivedSeq);
+            for (const eventId of ledger.legacyEventIds ?? [])
+                seen.set(eventId, undefined);
+            if (new Set(seen.keys()).size !== value.seen.length || value.seen.some((eventId) => !seen.has(eventId)))
+                throw new Error('INVALID_FACT_INBOX_SNAPSHOT');
+            inbox.archivedThrough = ledger.archivedThrough;
+        }
+        else {
+            const queued = new Map(value.queue.map((envelope) => [envelope.eventId, envelope.receivedSeq]));
+            for (const eventId of value.seen)
+                seen.set(eventId, queued.get(eventId));
+        }
+        let maxReceivedSeq = 0;
+        for (const envelope of value.queue) {
+            if (!envelope || typeof envelope.eventId !== 'string' || (!seen.has(envelope.eventId) && !options.dedupeArchive?.contains(envelope.eventId, envelope.receivedSeq)) || !Number.isInteger(envelope.receivedSeq) || envelope.receivedSeq < 1 || envelope.fact === undefined)
+                throw new Error('INVALID_FACT_INBOX_SNAPSHOT');
+            if (inbox.queue.some((candidate) => candidate.eventId === envelope.eventId || candidate.receivedSeq === envelope.receivedSeq))
+                throw new Error('INVALID_FACT_INBOX_SNAPSHOT');
+            if (envelope.receivedSeq <= maxReceivedSeq)
+                throw new Error('INVALID_FACT_INBOX_SNAPSHOT');
+            const knownSeq = seen.get(envelope.eventId);
+            if (knownSeq !== undefined && knownSeq !== envelope.receivedSeq)
+                throw new Error('INVALID_FACT_INBOX_SNAPSHOT');
+            if ([...seen.entries()].some(([eventId, receivedSeq]) => eventId !== envelope.eventId && receivedSeq === envelope.receivedSeq))
+                throw new Error('INVALID_FACT_INBOX_SNAPSHOT');
+            inbox.queue.push({ eventId: envelope.eventId, receivedSeq: envelope.receivedSeq, fact: structuredClone(envelope.fact) });
+            maxReceivedSeq = Math.max(maxReceivedSeq, envelope.receivedSeq);
+        }
+        if (value.nextSeq <= maxReceivedSeq)
+            throw new Error('INVALID_FACT_INBOX_SNAPSHOT');
+        for (const [eventId, receivedSeq] of seen)
+            inbox.seen.set(eventId, receivedSeq);
+        inbox.nextSeq = value.nextSeq;
+        return inbox;
+    }
+    clear() { this.queue.length = 0; }
+}
+export class ObservationInbox {
+    maxEntries;
+    maxBytes;
+    queue = [];
+    droppedThroughByAgent = new Map();
+    bytes = 0;
+    nextSeq = 1;
+    constructor(maxEntries = 4096, maxBytes = 1_000_000) {
+        this.maxEntries = maxEntries;
+        this.maxBytes = maxBytes;
+    }
+    enqueue(input) {
+        const event = structuredClone({ ...input, seq: this.nextSeq++ });
+        this.queue.push(event);
+        this.bytes += this.eventBytes(event);
+        while (this.queue.length > this.maxEntries || this.bytes > this.maxBytes) {
+            const dropped = this.queue.shift();
+            this.bytes -= this.eventBytes(dropped);
+            this.droppedThroughByAgent.set(dropped.agentId, Math.max(this.droppedThroughByAgent.get(dropped.agentId) ?? 0, dropped.seq));
+        }
+        return structuredClone(event);
+    }
+    drain(agentId) {
+        if (agentId === undefined) {
+            const selected = this.queue.splice(0);
+            this.bytes = 0;
+            return selected.map((event) => structuredClone(event));
+        }
+        const selected = this.queue.filter((event) => event.agentId === agentId);
+        if (selected.length) {
+            const ids = new Set(selected.map((event) => event.seq));
+            for (let index = this.queue.length - 1; index >= 0; index--)
+                if (ids.has(this.queue[index].seq)) {
+                    this.bytes -= this.eventBytes(this.queue[index]);
+                    this.queue.splice(index, 1);
+                }
+        }
+        return selected.map((event) => structuredClone(event));
+    }
+    get size() { return this.queue.length; }
+    get sizeBytes() { return this.bytes; }
+    droppedThrough(agentId) { return this.droppedThroughByAgent.get(agentId) ?? 0; }
+    snapshot() { return this.queue.map((event) => structuredClone(event)); }
+    eventBytes(event) { return Buffer.byteLength(JSON.stringify(event), 'utf8'); }
+}

package/dist/core/mutations.d.ts

@@ -0,0 +1,80 @@
+import type { RuntimeEventInput, RuntimeState, RuntimeError, ContextVersion, JsonValue, AgentRecord, LaneRecord, EffectRecord, WaitRecord, ResultRecord, FindingRecord, ArtifactRecord, LaneId, WaitId, EffectId, HistoryRecord, MergeProposal, ToolCallCorrelation, PrivacyMetadata } from './types.js';
+export type Mutation = {
+    op: 'setAgent';
+    agentId: string;
+    record: AgentRecord;
+} | {
+    op: 'setLane';
+    laneId: LaneId;
+    record: LaneRecord;
+} | {
+    op: 'setEffect';
+    effectId: EffectId;
+    record: EffectRecord;
+} | {
+    op: 'setWait';
+    waitId: WaitId;
+    record: WaitRecord;
+} | {
+    op: 'insertLane';
+    record: LaneRecord;
+} | {
+    op: 'insertEffect';
+    record: EffectRecord;
+} | {
+    op: 'insertWait';
+    record: WaitRecord;
+} | {
+    op: 'publishResult';
+    record: ResultRecord;
+} | {
+    op: 'publishFinding';
+    record: FindingRecord;
+} | {
+    op: 'publishArtifact';
+    record: ArtifactRecord;
+} | {
+    op: 'setToolCallCorrelation';
+    record: ToolCallCorrelation;
+} | {
+    op: 'insertMergeProposal';
+    proposal: MergeProposal;
+} | {
+    op: 'removeMergeProposal';
+    proposalId: string;
+} | {
+    op: 'setGlobal';
+    agentId: string;
+    version: ContextVersion;
+    value: JsonValue;
+    metadata?: PrivacyMetadata;
+} | {
+    op: 'setLaneContext';
+    laneId: LaneId;
+    value: JsonValue;
+    version: ContextVersion;
+    history?: HistoryRecord[];
+    metadata?: PrivacyMetadata;
+} | {
+    op: 'setNextIds';
+    nextIds: RuntimeState['nextIds'];
+} | {
+    op: 'appendEvent';
+    event: RuntimeEventInput;
+} | {
+    op: 'setNow';
+    now: number;
+};
+export interface ValidationSuccess {
+    mutations: Mutation[];
+}
+export interface ValidationFailure {
+    rejection: RuntimeError;
+}
+export type ValidationResult = ValidationSuccess | ValidationFailure;
+/** Shallow-fork maps and clone only records `apply()` mutates in place. */
+export declare function forkRuntimeStateForAdmission(state: RuntimeState, mutations: Mutation[]): RuntimeState;
+export declare function apply(state: RuntimeState, mutations: Mutation[], defaults?: {
+    sessionId?: string;
+    timestamp?: number;
+}): void;

package/dist/core/mutations.js

@@ -0,0 +1,127 @@
+import { appendRuntimeEvent } from './events.js';
+/** Shallow-fork maps and clone only records `apply()` mutates in place. */
+export function forkRuntimeStateForAdmission(state, mutations) {
+    const dirtyAgents = new Set();
+    const dirtyLanes = new Set();
+    for (const mutation of mutations) {
+        if (mutation.op === 'setGlobal')
+            dirtyAgents.add(mutation.agentId);
+        else if (mutation.op === 'setLaneContext')
+            dirtyLanes.add(mutation.laneId);
+        else if (mutation.op === 'publishFinding')
+            dirtyLanes.add(mutation.record.laneId);
+    }
+    const agents = new Map(state.agents);
+    const lanes = new Map(state.lanes);
+    for (const id of dirtyAgents) {
+        const agent = agents.get(id);
+        if (agent)
+            agents.set(id, { ...agent, globalVersions: new Map(agent.globalVersions), ...(agent.globalPrivacy === undefined ? {} : { globalPrivacy: new Map(agent.globalPrivacy) }) });
+    }
+    for (const id of dirtyLanes) {
+        const lane = lanes.get(id);
+        if (lane)
+            lanes.set(id, { ...lane, ...(lane.visibleResultRefs === undefined ? {} : { visibleResultRefs: new Set(lane.visibleResultRefs) }) });
+    }
+    return {
+        ...state,
+        agents,
+        lanes,
+        effects: new Map(state.effects),
+        waits: new Map(state.waits),
+        results: new Map(state.results),
+        artifacts: new Map(state.artifacts),
+        toolCallCorrelations: new Map(state.toolCallCorrelations),
+        mergeProposals: new Map(state.mergeProposals),
+        events: state.events.slice(),
+        nextIds: { ...state.nextIds },
+        trustedSanitizerIds: new Set(state.trustedSanitizerIds),
+    };
+}
+export function apply(state, mutations, defaults = {}) {
+    for (const mutation of mutations) {
+        switch (mutation.op) {
+            case 'setAgent':
+                state.agents.set(mutation.agentId, mutation.record);
+                break;
+            case 'setLane':
+                state.lanes.set(mutation.laneId, mutation.record);
+                break;
+            case 'setEffect':
+                state.effects.set(mutation.effectId, mutation.record);
+                break;
+            case 'setWait':
+                state.waits.set(mutation.waitId, mutation.record);
+                break;
+            case 'insertLane':
+                state.lanes.set(mutation.record.id, mutation.record);
+                break;
+            case 'insertEffect':
+                state.effects.set(mutation.record.id, mutation.record);
+                break;
+            case 'insertWait':
+                state.waits.set(mutation.record.id, mutation.record);
+                break;
+            case 'publishResult': {
+                state.results.set(mutation.record.id, mutation.record);
+                const match = /^result-(\d+)$/.exec(mutation.record.id);
+                if (match)
+                    state.nextIds.result = Math.max(state.nextIds.result, Number(match[1]) + 1);
+                break;
+            }
+            case 'publishFinding': {
+                state.results.set(mutation.record.id, mutation.record);
+                const lane = state.lanes.get(mutation.record.laneId);
+                if (lane?.visibleResultRefs)
+                    lane.visibleResultRefs.add(mutation.record.id);
+                else if (lane)
+                    lane.visibleResultRefs = new Set([mutation.record.id]);
+                const match = /^finding-(\d+)$/.exec(mutation.record.id);
+                if (match)
+                    state.nextIds.result = Math.max(state.nextIds.result, Number(match[1]) + 1);
+                break;
+            }
+            case 'publishArtifact': {
+                state.artifacts.set(mutation.record.ref, mutation.record);
+                const match = /^artifact-(\d+)$/.exec(mutation.record.ref);
+                if (match)
+                    state.nextIds.artifact = Math.max(state.nextIds.artifact, Number(match[1]) + 1);
+                break;
+            }
+            case 'setToolCallCorrelation':
+                state.toolCallCorrelations.set(mutation.record.toolCallId, mutation.record);
+                break;
+            case 'insertMergeProposal':
+                state.mergeProposals.set(mutation.proposal.id, mutation.proposal);
+                break;
+            case 'removeMergeProposal':
+                state.mergeProposals.delete(mutation.proposalId);
+                break;
+            case 'setGlobal': {
+                const agent = state.agents.get(mutation.agentId);
+                agent.globalVersions.set(mutation.version, mutation.value);
+                if (mutation.metadata) {
+                    if (!agent.globalPrivacy)
+                        agent.globalPrivacy = new Map();
+                    agent.globalPrivacy.set(mutation.version, structuredClone(mutation.metadata));
+                }
+                agent.latestGlobalVersion = mutation.version;
+                break;
+            }
+            case 'setLaneContext': {
+                const lane = state.lanes.get(mutation.laneId);
+                lane.context = { ...lane.context, state: mutation.value, version: mutation.version, ...(mutation.history === undefined ? {} : { history: structuredClone(mutation.history) }), ...(mutation.metadata === undefined ? {} : structuredClone(mutation.metadata)) };
+                break;
+            }
+            case 'setNextIds':
+                state.nextIds = { ...mutation.nextIds };
+                break;
+            case 'appendEvent':
+                appendRuntimeEvent(state, mutation.event, defaults);
+                break;
+            case 'setNow':
+                state.now = mutation.now;
+                break;
+        }
+    }
+}

package/dist/core/records.d.ts

@@ -0,0 +1 @@
+export type { AgentRecord, LaneRecord, EffectRecord, WaitRecord, ResultRecord, FindingRecord, RuntimeState, LaneContext, HistoryRecord, ProgressWatchdogState, MergeProposal, ArtifactRecord } from './types.js';

package/dist/core/records.js

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