@nanobpm/agentic 0.1.0 → 0.4.0

package/dist/session/acp/transport.js

@@ -0,0 +1,126 @@
+/**
+ * The ACP transport seam — ADR 0062, slice 2.
+ *
+ * ACP frames JSON-RPC 2.0 as **newline-delimited JSON over stdio** (one complete
+ * message per line, UTF-8, no `Content-Length` headers — that is LSP/MCP framing,
+ * not ACP). {@link AcpConnection} speaks only to this narrow {@link AcpTransport}
+ * port, so the JSON-RPC peer never knows whether it is wired to a spawned
+ * `opencode acp` subprocess ({@link ./spawn.ts}) or, in a test, to an in-memory
+ * fake agent ({@link inMemoryTransportPair}). Transport is a seam, never
+ * re-implemented per backend (AGENTS.md: no drift surfaces).
+ */
+/**
+ * Split a byte stream into complete newline-delimited JSON messages. Handles
+ * chunk boundaries that fall mid-line (buffering the remainder) and ignores
+ * blank lines. Each decoded value is handed to `onMessage`; a line that fails to
+ * parse goes to `onError` and does not abort the stream.
+ */
+export class NewlineJsonDecoder {
+    #buffer = "";
+    #onMessage;
+    #onError;
+    constructor(onMessage, onError) {
+        this.#onMessage = onMessage;
+        this.#onError = onError;
+    }
+    /** Feed a decoded string chunk; emits every complete line it now contains. */
+    push(chunk) {
+        this.#buffer += chunk;
+        let newlineIndex = this.#buffer.indexOf("\n");
+        while (newlineIndex !== -1) {
+            const line = this.#buffer.slice(0, newlineIndex).trim();
+            this.#buffer = this.#buffer.slice(newlineIndex + 1);
+            if (line.length > 0)
+                this.#deliver(line);
+            newlineIndex = this.#buffer.indexOf("\n");
+        }
+    }
+    /**
+     * Deliver any final buffered line at stream end (EOF without a trailing
+     * newline). A compliant peer newline-terminates every message, but on abrupt
+     * process/pipe EOF a complete final message can sit unterminated in the buffer;
+     * flushing it surfaces the message (or a parse error) instead of silently
+     * dropping it. Idempotent: it clears the buffer, so a second call is a no-op.
+     */
+    flush() {
+        const line = this.#buffer.trim();
+        this.#buffer = "";
+        if (line.length > 0)
+            this.#deliver(line);
+    }
+    #deliver(line) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch (cause) {
+            this.#onError(new Error(`ACP transport received a non-JSON line: ${line.slice(0, 200)}`, { cause }));
+            return;
+        }
+        this.#onMessage(parsed);
+    }
+}
+/** Serialise a JSON-RPC message as a single ACP wire line (JSON + `\n`). */
+export function encodeMessageLine(message) {
+    const json = JSON.stringify(message);
+    // `JSON.stringify(undefined)` (and other non-serialisable inputs) returns
+    // `undefined`, which would emit the literal line "undefined\n" and always fail
+    // `JSON.parse` on the peer. Fail loudly at the sender instead of on the wire.
+    if (json === undefined) {
+        throw new Error("ACP transport cannot encode a non-JSON-serialisable message");
+    }
+    return `${json}\n`;
+}
+/**
+ * A pair of transports wired directly to each other in memory: what one `send`s
+ * the other receives (after a `queueMicrotask` hop, so delivery is asynchronous
+ * like a real pipe and never re-enters the sender synchronously). The reference
+ * substrate for driving a fake agent in tests without spawning a process.
+ */
+export function inMemoryTransportPair() {
+    const client = new InMemoryTransport();
+    const agent = new InMemoryTransport();
+    client.connect(agent);
+    agent.connect(client);
+    return { client, agent };
+}
+class InMemoryTransport {
+    #peer;
+    #onMessage;
+    #onError;
+    #closed = false;
+    connect(peer) {
+        this.#peer = peer;
+    }
+    send(message) {
+        if (this.#closed)
+            return;
+        // Round-trip through the wire encoding so an in-memory test exercises the same
+        // JSON serialisation a real pipe would.
+        const line = encodeMessageLine(message);
+        const peer = this.#peer;
+        queueMicrotask(() => peer?.receive(line));
+    }
+    receive(line) {
+        if (this.#closed)
+            return;
+        const handler = this.#onMessage;
+        if (handler === undefined)
+            return;
+        const onError = this.#onError ??
+            ((error) => {
+                throw error;
+            });
+        const decoder = new NewlineJsonDecoder(handler, onError);
+        decoder.push(line);
+    }
+    onMessage(handler) {
+        this.#onMessage = handler;
+    }
+    onError(handler) {
+        this.#onError = handler;
+    }
+    close() {
+        this.#closed = true;
+    }
+}

package/dist/session/adapter.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The `@nanobpm/agentic/session` adapter contract — ADR 0062, slice 1.
+ *
+ * The three-method interface every session backend implements. It is the *mind*
+ * side of a durable agent activation: the authoritative log of what the agent
+ * thought/did ({@link SessionAdapter.emit}, the "mind tap"), the mind/world join
+ * points at a push boundary ({@link SessionAdapter.checkpoint}), and the seed a
+ * re-leased incarnation replays to resume ({@link SessionAdapter.restore}).
+ *
+ * Publishing this interface + the {@link SessionEvent} types first is the whole
+ * point of slice 1: the ACP client (slice 2), the stream-json/native normalisers
+ * (slice 3) and the nano-workforce world-restore (slice 4) all code against this
+ * stable contract in parallel. Keep it small and additive.
+ */
+import type { AppendedSessionEvent, SessionEvent } from "./events.ts";
+/**
+ * Identifies one **activation** — a single leased run of a BPMN element. This is
+ * the log's identity for fencing and replay: every incarnation of the same
+ * `(processInstanceKey, elementId)` shares one causal log and one fence, so a
+ * re-lease resumes the same session rather than starting a new one.
+ *
+ * The authoritative log is keyed `(processInstanceKey, elementId)` (ADR 0062):
+ * this pair identifies the activation and shares one fence. The current
+ * `incarnation` is stored as the fence token, and each appended event carries an
+ * `incarnation` stamp recording which generation wrote that row.
+ */
+export interface ActivationKey {
+    readonly processInstanceKey: string;
+    readonly elementId: string;
+}
+/** Render an {@link ActivationKey} as an opaque, collision-free string key. */
+export declare function activationKeyString(key: ActivationKey): string;
+/**
+ * One recorded side effect at a checkpoint's push boundary. The *shape* of an
+ * effect (its `kind` vocabulary, how it is replayed/fenced) is owned by slice 4
+ * (nano-workforce world-restore); slice 1 stores the ledger opaquely so the
+ * contract is stable before that lands. `detail` is an opaque JSON value.
+ */
+export interface EffectEntry {
+    readonly id: string;
+    readonly kind: string;
+    readonly detail?: unknown;
+}
+/**
+ * The world-side effects committed at a checkpoint. Stored verbatim (JSON) and
+ * handed back unchanged at {@link SessionAdapter.restore}; slice 1 never
+ * interprets it.
+ */
+export type EffectLedger = readonly EffectEntry[];
+/**
+ * A mind/world join recorded at a push boundary: the agent's mind is at log
+ * `offset`, the world is at git `commitSha`, and `effectLedger` lists the effects
+ * that boundary committed. On re-lease the newest checkpoint's seed is replayed.
+ */
+export interface SessionCheckpoint {
+    /** Unique checkpoint id (producer- or backend-assigned). */
+    readonly id: string;
+    /**
+     * The log offset the checkpoint pins: exactly the log's `nextOffset` at the
+     * moment it was taken, so the seed is events `[0, offset)`.
+     */
+    readonly offset: number;
+    /** The world (git) commit the mind is joined to at this boundary. */
+    readonly commitSha: string;
+    /** The effects committed at this boundary (opaque to slice 1). */
+    readonly effectLedger: EffectLedger;
+    /** The incarnation that took the checkpoint. */
+    readonly incarnation: number;
+    /** When the checkpoint was taken, ISO-8601. */
+    readonly at: string;
+}
+/**
+ * The mind seed handed back on re-lease: everything a resumed incarnation needs
+ * to reconstruct the agent's mind up to a checkpoint and continue from there.
+ */
+export interface SessionSeed {
+    /**
+     * The checkpoint the seed restores from, or `null` when the session has no
+     * checkpoint yet (a fresh start — `events` is empty and `nextOffset` is 0).
+     */
+    readonly checkpoint: SessionCheckpoint | null;
+    /**
+     * The authoritative log replayed up to (and excluding) the checkpoint offset,
+     * in offset order — the events the resumed agent replays to rebuild its mind.
+     */
+    readonly events: readonly AppendedSessionEvent[];
+    /**
+     * The offset the resumed incarnation continues appending at — the checkpoint
+     * offset (0 when there is no checkpoint). Any events a dead incarnation wrote
+     * *past* the checkpoint are uncommitted and are not part of the seed.
+     */
+    readonly nextOffset: number;
+}
+/**
+ * The three-method session adapter. An instance is bound to one
+ * {@link ActivationKey} and one `incarnation`; a re-lease constructs a new
+ * adapter at a higher incarnation over the same authoritative log.
+ */
+export interface SessionAdapter {
+    /** The activation this adapter writes to. */
+    readonly key: ActivationKey;
+    /** The generation of this writer (the fencing token). */
+    readonly incarnation: number;
+    /**
+     * The **mind tap**: append `event` to the authoritative session log at the
+     * current offset, returning it stamped with its assigned `offset` and this
+     * writer's `incarnation`. Fenced — a call from an incarnation that a newer one
+     * has superseded throws {@link StaleIncarnationError} and writes nothing.
+     */
+    emit(event: SessionEvent): AppendedSessionEvent;
+    /**
+     * Mark a mind/world join at a push boundary: record a checkpoint pinning the
+     * current log offset to `commitSha` and `effectLedger`. Fenced like
+     * {@link emit}. Returns the recorded checkpoint.
+     */
+    checkpoint(commitSha: string, effectLedger: EffectLedger): SessionCheckpoint;
+    /**
+     * Hand back the mind seed to resume from. With no argument (or an unknown id)
+     * it resolves the **latest** checkpoint; given a checkpoint id it restores that
+     * specific one. Returns a {@link SessionSeed} of the log up to the checkpoint
+     * offset. Read-only — it does not mutate the log or the fence.
+     */
+    restore(fromCheckpoint?: string): SessionSeed;
+}
+/**
+ * Raised when a write (emit/checkpoint) is attempted by an incarnation that a
+ * newer one has already superseded — the fence rejected it. The stale writer's
+ * call has no effect; the log stays owned by the current incarnation.
+ */
+export declare class StaleIncarnationError extends Error {
+    readonly key: ActivationKey;
+    readonly incarnation: number;
+    readonly current: number;
+    constructor(key: ActivationKey, incarnation: number, current: number);
+}

package/dist/session/adapter.js

@@ -0,0 +1,24 @@
+/** Render an {@link ActivationKey} as an opaque, collision-free string key. */
+export function activationKeyString(key) {
+    // NUL separates the two components so no pair of distinct (pik, elementId)
+    // values can collide by concatenation (NUL cannot appear in either).
+    return `${key.processInstanceKey}\u0000${key.elementId}`;
+}
+/**
+ * Raised when a write (emit/checkpoint) is attempted by an incarnation that a
+ * newer one has already superseded — the fence rejected it. The stale writer's
+ * call has no effect; the log stays owned by the current incarnation.
+ */
+export class StaleIncarnationError extends Error {
+    key;
+    incarnation;
+    current;
+    constructor(key, incarnation, current) {
+        super(`incarnation ${incarnation} is fenced for activation ` +
+            `${key.processInstanceKey}/${key.elementId}: a newer incarnation ${current} has taken over`);
+        this.name = "StaleIncarnationError";
+        this.key = key;
+        this.incarnation = incarnation;
+        this.current = current;
+    }
+}

package/dist/session/backend.d.ts

@@ -0,0 +1,43 @@
+import { type ActivationKey, type EffectLedger, type SessionAdapter, type SessionCheckpoint, type SessionSeed } from "./adapter.ts";
+import type { AppendedSessionEvent, SessionEvent } from "./events.ts";
+import { type Clock, InMemorySessionLog, type SessionLog, type SqliteDb, SqliteSessionLog } from "./log.ts";
+export interface SessionBackendOptions {
+    /** Injectable clock for deterministic checkpoint timestamps. Default {@link systemClock}. */
+    clock?: Clock;
+    /** Injectable checkpoint-id generator (deterministic tests). Default `crypto.randomUUID`. */
+    newCheckpointId?: () => string;
+}
+/**
+ * A session adapter bound to one activation and one incarnation. Constructing it
+ * takes the lease at `incarnation` (advancing the fence), so a re-lease at a
+ * higher incarnation immediately fences every prior one — a subsequent `emit`
+ * from an older adapter throws {@link StaleIncarnationError}.
+ */
+export declare class SessionBackend implements SessionAdapter {
+    #private;
+    readonly key: ActivationKey;
+    readonly incarnation: number;
+    constructor(log: SessionLog, key: ActivationKey, incarnation: number, options?: SessionBackendOptions);
+    /** The offset the next `emit` will assign. */
+    get nextOffset(): number;
+    emit(event: SessionEvent): AppendedSessionEvent;
+    checkpoint(commitSha: string, effectLedger: EffectLedger): SessionCheckpoint;
+    restore(fromCheckpoint?: string): SessionSeed;
+}
+/**
+ * Open a session adapter over an in-memory reference log. Pass a shared
+ * {@link InMemorySessionLog} across incarnations of the same activation so the
+ * fence and events persist across a re-lease (the reference resume scenario);
+ * omit it for a throwaway single-incarnation log.
+ */
+export declare function openInMemorySession(key: ActivationKey, incarnation: number, options?: SessionBackendOptions & {
+    log?: InMemorySessionLog;
+}): {
+    backend: SessionBackend;
+    log: InMemorySessionLog;
+};
+/** Open a session adapter over the durable SQLite log. Applies the schema idempotently. */
+export declare function openSqliteSession(db: SqliteDb, key: ActivationKey, incarnation: number, options?: SessionBackendOptions): {
+    backend: SessionBackend;
+    log: SqliteSessionLog;
+};

package/dist/session/backend.js

@@ -0,0 +1,95 @@
+/**
+ * {@link SessionBackend} — the canonical {@link SessionAdapter} implementation,
+ * ADR 0062 slice 1.
+ *
+ * There is exactly **one** adapter implementation (derivation over duplication):
+ * it is bound to a {@link SessionLog} port, so the *same* emit/checkpoint/restore
+ * semantics run over either the in-memory reference log ({@link InMemorySessionLog}
+ * — the stub slices 2–5 code against) or the durable SQLite log
+ * ({@link SqliteSessionLog}). The backend owns the append cursor and the fencing
+ * token; the log owns storage and the fence high-water.
+ */
+import { randomUUID } from "node:crypto";
+import { InMemorySessionLog, SqliteSessionLog, systemClock } from "./log.js";
+/**
+ * A session adapter bound to one activation and one incarnation. Constructing it
+ * takes the lease at `incarnation` (advancing the fence), so a re-lease at a
+ * higher incarnation immediately fences every prior one — a subsequent `emit`
+ * from an older adapter throws {@link StaleIncarnationError}.
+ */
+export class SessionBackend {
+    key;
+    incarnation;
+    #log;
+    #clock;
+    #newCheckpointId;
+    /** The offset the next `emit` writes at. Advanced by `emit`, repositioned by `restore`. */
+    #cursor;
+    constructor(log, key, incarnation, options = {}) {
+        log.lease(key, incarnation);
+        this.#log = log;
+        this.key = key;
+        this.incarnation = incarnation;
+        this.#clock = options.clock ?? systemClock;
+        this.#newCheckpointId = options.newCheckpointId ?? randomUUID;
+        // Default to appending after whatever is already committed; `restore`
+        // repositions the cursor to a checkpoint boundary when resuming.
+        this.#cursor = log.nextOffset(key);
+    }
+    /** The offset the next `emit` will assign. */
+    get nextOffset() {
+        return this.#cursor;
+    }
+    emit(event) {
+        const appended = this.#log.append(this.key, this.incarnation, this.#cursor, event);
+        this.#cursor = appended.offset + 1;
+        return appended;
+    }
+    checkpoint(commitSha, effectLedger) {
+        const checkpoint = {
+            id: this.#newCheckpointId(),
+            offset: this.#cursor,
+            commitSha,
+            effectLedger,
+            incarnation: this.incarnation,
+            at: new Date(this.#clock.now()).toISOString(),
+        };
+        return this.#log.putCheckpoint(this.key, this.incarnation, checkpoint);
+    }
+    restore(fromCheckpoint) {
+        // Contract: no argument OR an unknown id resolves the latest checkpoint; a
+        // known id restores exactly that checkpoint.
+        const checkpoint = fromCheckpoint === undefined
+            ? this.#log.latestCheckpoint(this.key)
+            : (this.#log.getCheckpoint(this.key, fromCheckpoint) ?? this.#log.latestCheckpoint(this.key));
+        if (checkpoint === undefined) {
+            // No checkpoint to resume from: start the mind fresh at offset 0. The next
+            // emit at offset 0 discards any uncommitted events a dead incarnation left.
+            this.#cursor = 0;
+            return { checkpoint: null, events: [], nextOffset: 0 };
+        }
+        const events = this.#log.replay(this.key, 0, checkpoint.offset);
+        // Reposition the write cursor to the checkpoint boundary: the resumed
+        // incarnation continues from there, overwriting any uncommitted tail.
+        this.#cursor = checkpoint.offset;
+        return { checkpoint, events, nextOffset: checkpoint.offset };
+    }
+}
+/**
+ * Open a session adapter over an in-memory reference log. Pass a shared
+ * {@link InMemorySessionLog} across incarnations of the same activation so the
+ * fence and events persist across a re-lease (the reference resume scenario);
+ * omit it for a throwaway single-incarnation log.
+ */
+export function openInMemorySession(key, incarnation, options = {}) {
+    const log = options.log ?? new InMemorySessionLog();
+    const backend = new SessionBackend(log, key, incarnation, options);
+    return { backend, log };
+}
+/** Open a session adapter over the durable SQLite log. Applies the schema idempotently. */
+export function openSqliteSession(db, key, incarnation, options = {}) {
+    const log = new SqliteSessionLog(db, { clock: options.clock });
+    log.ensureSchema();
+    const backend = new SessionBackend(log, key, incarnation, options);
+    return { backend, log };
+}

package/dist/session/events.d.ts

@@ -0,0 +1,152 @@
+/**
+ * The canonical `SessionEvent` model — ADR 0062, slice 1 (the shared contract).
+ *
+ * This is **Nano's own** agent-session event model: the single schema every
+ * harness dialect (ACP, stream-json, a native normalizer, …) normalizes *into*.
+ * We never adopt an external harness schema as ours — those are ingestion
+ * details owned by the later slices; this union is the stable interface they all
+ * target.
+ *
+ * ## The causal chain
+ *
+ * A session is an append-only log of events. Two orthogonal orderings make the
+ * log both replayable and mergeable:
+ *
+ *  - a **monotonic, gap-free `offset`** assigned by the authoritative log on
+ *    append (see {@link AppendedSessionEvent}); it is the resume coordinate —
+ *    `restore` hands back everything up to a checkpoint offset.
+ *  - a **causal `parentId`** the producer stamps: the id of the event this one
+ *    logically follows (`null` for the first event of a session). Offset gives a
+ *    total order for replay; `parentId` records the *causal* edge, which survives
+ *    a compaction that rewrites offsets.
+ *
+ * The producer owns identity (`id`) and causality (`parentId`); the log owns
+ * ordering (`offset`) and fencing (`incarnation`). Keeping those responsibilities
+ * split is what lets a resumed incarnation continue the same causal chain at a
+ * fresh offset without the producer knowing the log's internal cursor.
+ */
+/** Discriminates a {@link SessionEvent}. One member per row in the union below. */
+export type SessionEventType = "system" | "user" | "assistant" | "reasoning" | "tool-call" | "tool-result" | "compaction" | "usage" | "turn-start" | "turn-end";
+/** The set of valid event types, for a runtime membership check at the DB boundary. */
+export declare const SESSION_EVENT_TYPES: readonly SessionEventType[];
+/**
+ * The fields every event carries regardless of type. `offset` is deliberately
+ * absent — the producer does not assign it; the authoritative log does, yielding
+ * an {@link AppendedSessionEvent}.
+ */
+export interface SessionEventEnvelope {
+    /** Producer-assigned unique id for this event (the causal-chain node id). */
+    readonly id: string;
+    /** The id of the causal predecessor, or `null` for the first event of a session. */
+    readonly parentId: string | null;
+}
+/** A system/instruction message (the harness/system prompt turn). */
+export interface SystemMessageEvent extends SessionEventEnvelope {
+    readonly type: "system";
+    readonly text: string;
+}
+/** A user message. */
+export interface UserMessageEvent extends SessionEventEnvelope {
+    readonly type: "user";
+    readonly text: string;
+}
+/** An assistant (model) message — the visible answer text. */
+export interface AssistantMessageEvent extends SessionEventEnvelope {
+    readonly type: "assistant";
+    readonly text: string;
+}
+/**
+ * Assistant reasoning (chain-of-thought / thinking) for a turn.
+ *
+ * `text` is the human-readable reasoning summary when the provider exposes one.
+ * `providerContinuation` is an **opaque provider reasoning-continuation blob**:
+ * some providers (e.g. encrypted reasoning tokens) return a handle that must be
+ * fed back verbatim to continue reasoning across a resume. Nano never parses,
+ * validates, or transforms it — it stores and replays it as an opaque string so
+ * a re-leased incarnation can resume the model's reasoning exactly.
+ */
+export interface ReasoningEvent extends SessionEventEnvelope {
+    readonly type: "reasoning";
+    readonly text?: string;
+    readonly providerContinuation?: string;
+}
+/** A tool/function call the assistant requested. */
+export interface ToolCallEvent extends SessionEventEnvelope {
+    readonly type: "tool-call";
+    /** Correlates this call with its {@link ToolResultEvent}. */
+    readonly callId: string;
+    readonly name: string;
+    /** The call arguments, as an opaque JSON-serialisable value. */
+    readonly args: unknown;
+}
+/** The result of a previously-emitted {@link ToolCallEvent}. */
+export interface ToolResultEvent extends SessionEventEnvelope {
+    readonly type: "tool-result";
+    /** Matches the originating {@link ToolCallEvent.callId}. */
+    readonly callId: string;
+    /** `false` when the tool failed; the failure detail lives in `result`. */
+    readonly ok: boolean;
+    /** The tool output, as an opaque JSON-serialisable value. */
+    readonly result: unknown;
+}
+/**
+ * A compaction or truncation boundary: the events in the (inclusive-exclusive)
+ * offset range `[replacesFrom, replacesTo)` were summarised/dropped to bound
+ * context growth. `summary` is the replacement text (present for compaction,
+ * typically absent for a hard truncation). The original events keep their
+ * offsets in the authoritative log; this marker records that a *replay* should
+ * fold that range into the summary rather than replaying it verbatim.
+ */
+export interface CompactionEvent extends SessionEventEnvelope {
+    readonly type: "compaction";
+    readonly reason: "compaction" | "truncation";
+    readonly replacesFrom: number;
+    readonly replacesTo: number;
+    readonly summary?: string;
+}
+/** A usage/accounting record for a turn (token counts, etc.). */
+export interface UsageEvent extends SessionEventEnvelope {
+    readonly type: "usage";
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    /** Optional provider model identifier the usage is attributed to. */
+    readonly model?: string;
+}
+/** The start of a turn (a request/response cycle). `turn` is a monotonic index. */
+export interface TurnStartEvent extends SessionEventEnvelope {
+    readonly type: "turn-start";
+    readonly turn: number;
+}
+/** The end of a turn matching a prior {@link TurnStartEvent}. */
+export interface TurnEndEvent extends SessionEventEnvelope {
+    readonly type: "turn-end";
+    readonly turn: number;
+}
+/**
+ * The canonical session event — a discriminated union over {@link SessionEventType}.
+ * Every harness dialect normalises into exactly this shape.
+ */
+export type SessionEvent = SystemMessageEvent | UserMessageEvent | AssistantMessageEvent | ReasoningEvent | ToolCallEvent | ToolResultEvent | CompactionEvent | UsageEvent | TurnStartEvent | TurnEndEvent;
+/**
+ * A {@link SessionEvent} after the authoritative log has appended it: the same
+ * event plus the log-assigned `offset` (its monotonic resume coordinate) and the
+ * `incarnation` (the generation of the writer that produced it — the fencing
+ * stamp). This is what {@link restore} replays as the mind seed.
+ */
+export type AppendedSessionEvent = SessionEvent & {
+    readonly offset: number;
+    readonly incarnation: number;
+};
+/** Raised when a value read back from storage is not a well-formed session event. */
+export declare class SessionEventShapeError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse and validate an untyped value (e.g. `JSON.parse` of a stored row) into a
+ * {@link SessionEvent}, reconstructing the exact union member for its `type`.
+ * Throws {@link SessionEventShapeError} on any malformed field. This is the
+ * single trusted boundary between untyped storage and the typed union — it never
+ * uses an `as`-cast to fabricate a shape (see AGENTS.md), it *builds* one field
+ * by field, so a corrupt row fails loudly instead of masquerading as valid.
+ */
+export declare function parseSessionEvent(value: unknown): SessionEvent;