@ours.network/fleet 1.2.0-nightly.63 → 1.2.0-nightly.64

package/dist/session/conversation-store.js

@@ -1,6 +1,8 @@
 import { createHash } from 'node:crypto';
 import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync, writeSync, } from 'node:fs';
 import { join } from 'node:path';
+import { setImmediate as yieldTurn } from 'node:timers/promises';
+import { replayLines, ReplayCoverageError } from './conversation-replay.js';
 /**
  * Durable, append-only, single-writer conversation ledger for one role
  * The per-role runner is the only writer; readers page by seq.
@@ -24,6 +26,13 @@ export class IdempotencyConflictError extends Error {
 export class ConversationEventStore {
     dir;
     nextSeq = 1;
+    lastDurableSeq = 0;
+    segmentRanges = new Map();
+    generationFloors = new Map();
+    failedGenerations = new Set();
+    failureListeners = new Set();
+    unavailable = false;
+    rotateBeforeAppend = false;
     firstAvailableSeq;
     segments = [];
     tail = [];
@@ -47,6 +56,7 @@ export class ConversationEventStore {
             this.recover();
         }
         catch (error) {
+            this.unavailable = true;
             this.markDegraded(`store unavailable: ${error.message}`);
         }
     }
@@ -54,6 +64,10 @@ export class ConversationEventStore {
     static bodyDigest(body) {
         return createHash('sha256').update(body).digest('hex').slice(0, 24);
     }
+    /** Current delivery eligibility only; requested historical ranges still need replay verification. */
+    generationDurable(generation) {
+        return Boolean(generation) && !this.unavailable && !this.failedGenerations.has(generation);
+    }
     get degraded() { return this._degraded; }
     get degradedDetail() { return this.degradedReason; }
     /**
@@ -69,12 +83,47 @@ export class ConversationEventStore {
             at: new Date().toISOString(),
             ...draft,
         };
-        const line = JSON.stringify(event) + '\n';
-        const fd = this.segmentFd(Buffer.byteLength(line));
-        writeSync(fd, line);
-        fsyncSync(fd);
+        let line;
+        try {
+            line = JSON.stringify(event) + '\n';
+            const fd = this.segmentFd(Buffer.byteLength(line));
+            // From this point writes may have reached disk even if write/fsync throws.
+            // Never let a later generation reuse that identity; gaps are safer than collisions.
+            this.nextSeq++;
+            const bytes = Buffer.from(line);
+            let offset = 0;
+            while (offset < bytes.length) {
+                const written = writeSync(fd, bytes, offset, bytes.length - offset);
+                if (!written)
+                    throw new Error('short ledger write');
+                offset += written;
+            }
+            fsyncSync(fd);
+        }
+        catch (error) {
+            const firstFailure = !this.failedGenerations.has(draft.sessionGeneration);
+            this.failedGenerations.add(draft.sessionGeneration);
+            this.rotateBeforeAppend = true;
+            this.writeManifest();
+            this.markDegraded(`event append failed: ${error.message}`);
+            if (firstFailure)
+                for (const listener of this.failureListeners) {
+                    try {
+                        listener(draft.sessionGeneration);
+                    }
+                    catch { /* observers cannot interrupt owner failure handling */ }
+                }
+            throw error;
+        }
+        if (!this.generationFloors.has(event.sessionGeneration))
+            this.generationFloors.set(event.sessionGeneration, event.seq - 1);
+        const segment = this.segments.at(-1);
+        const range = this.segmentRanges.get(segment) ?? { damaged: false };
+        range.first ??= event.seq;
+        range.last = event.seq;
+        this.segmentRanges.set(segment, range);
         this.firstAvailableSeq ??= event.seq;
-        this.nextSeq++;
+        this.lastDurableSeq = event.seq;
         this.activeBytes += Buffer.byteLength(line);
         this.tail.push(event);
         if (this.tail.length > TAIL_EVENTS)
@@ -118,6 +167,11 @@ export class ConversationEventStore {
         this.listeners.add(listener);
         return () => this.listeners.delete(listener);
     }
+    /** A current-generation failed append invalidates even a follow already past ready. */
+    subscribeFailure(listener) {
+        this.failureListeners.add(listener);
+        return () => this.failureListeners.delete(listener);
+    }
     /** Store the receipt a repeated command must get back. */
     recordReceipt(commandId, receipt, bodyDigest) {
         this.commands.set(commandId, { receipt, bodyDigest });
@@ -143,7 +197,7 @@ export class ConversationEventStore {
         return [...this.promptStates.values()];
     }
     lastCursor() {
-        return this.nextSeq > 1 ? String(this.nextSeq - 1) : undefined;
+        return this.lastDurableSeq > 0 ? String(this.lastDurableSeq) : undefined;
     }
     close() {
         if (this.activeFd !== undefined) {
@@ -154,17 +208,27 @@ export class ConversationEventStore {
             this.activeFd = undefined;
         }
         this.listeners.clear();
+        this.failureListeners.clear();
     }
     // ── recovery ───────────────────────────────────────────────────────────────
     recover() {
         const manifest = this.readManifest();
-        this.segments = manifest?.segments.filter(name => existsSync(join(this.dir, name))) ?? this.discoverSegments();
-        if (!this.segments.length)
-            this.segments = this.discoverSegments();
+        for (const generation of manifest?.failedGenerations ?? [])
+            this.failedGenerations.add(generation);
+        // Preserve missing manifest entries: filtering them would erase proof of a gap on reopen.
+        this.segments = [...new Set([...(manifest?.segments ?? []), ...this.discoverSegments()])].sort();
         let maxSeq = 0;
         for (const segment of this.segments) {
             for (const event of this.readSegment(segment)) {
                 this.firstAvailableSeq ??= event.seq;
+                if (event.seq <= maxSeq) {
+                    // Pre-fix or corrupt ledgers may already contain colliding identities.
+                    // A cached generation floor must never certify the later duplicate.
+                    this.failedGenerations.add(event.sessionGeneration);
+                    this.markDegraded(`segment ${segment} has non-monotonic sequence ${event.seq}`);
+                }
+                if (!this.generationFloors.has(event.sessionGeneration))
+                    this.generationFloors.set(event.sessionGeneration, maxSeq);
                 maxSeq = Math.max(maxSeq, event.seq);
                 this.tail.push(event);
                 if (this.tail.length > TAIL_EVENTS)
@@ -173,10 +237,12 @@ export class ConversationEventStore {
                 this.rebuildCommandIndex(event);
             }
         }
-        this.nextSeq = maxSeq + 1;
+        this.nextSeq = Math.max(maxSeq + 1, manifest?.nextSeq ?? 1);
+        this.lastDurableSeq = maxSeq;
         if (this.segments.length) {
             const active = join(this.dir, this.segments.at(-1));
             this.activeBytes = existsSync(active) ? statSync(active).size : 0;
+            this.rotateBeforeAppend = this.segmentRanges.get(this.segments.at(-1))?.damaged ?? true;
         }
         this.writeManifest();
     }
@@ -201,25 +267,36 @@ export class ConversationEventStore {
     }
     readSegment(name) {
         const events = [];
+        const range = { damaged: false };
+        this.segmentRanges.set(name, range);
         let raw;
         try {
             raw = readFileSync(join(this.dir, name), 'utf8');
         }
         catch (error) {
+            range.damaged = true;
             this.markDegraded(`segment ${name} unreadable: ${error.message}`);
             return events;
         }
+        if (raw.length && !raw.endsWith('\n'))
+            range.damaged = true;
         for (const line of raw.split('\n')) {
             if (!line.trim())
                 continue;
             try {
                 const event = JSON.parse(line);
-                if (event.schemaVersion === 1 && typeof event.seq === 'number')
+                if (event.schemaVersion === 1 && Number.isSafeInteger(event.seq) && event.seq > 0) {
                     events.push(event);
-                else
+                    range.first ??= event.seq;
+                    range.last = event.seq;
+                }
+                else {
+                    range.damaged = true;
                     this.markDegraded(`segment ${name} holds a record of an unknown schema`);
+                }
             }
             catch {
+                range.damaged = true;
                 // A torn final line after a crash: everything before it stays readable.
                 this.markDegraded(`segment ${name} ends in a torn or corrupt line`);
             }
@@ -237,6 +314,8 @@ export class ConversationEventStore {
             bodyDigest,
             receipt: {
                 commandId: event.commandId,
+                ...(typeof event.sessionGeneration === 'string' && event.sessionGeneration
+                    ? { sessionGeneration: event.sessionGeneration } : {}),
                 promptId: event.promptId,
                 state: 'queued',
                 queuedBehind: payload.queuedBehind ?? 0,
@@ -275,7 +354,7 @@ export class ConversationEventStore {
     // ── segment management ─────────────────────────────────────────────────────
     segmentFd(incomingBytes) {
         if (this.activeFd !== undefined
-            && this.activeBytes + incomingBytes > this.segmentBytes) {
+            && (this.rotateBeforeAppend || this.activeBytes + incomingBytes > this.segmentBytes)) {
             try {
                 closeSync(this.activeFd);
             }
@@ -283,11 +362,12 @@ export class ConversationEventStore {
             this.activeFd = undefined;
         }
         if (this.activeFd === undefined) {
-            const needsNew = !this.segments.length
+            const needsNew = this.rotateBeforeAppend || !this.segments.length
                 || this.activeBytes + incomingBytes > this.segmentBytes;
             if (needsNew) {
-                const name = `events-${String(this.segments.length + 1).padStart(6, '0')}.jsonl`;
+                const name = `events-${String(Number(this.segments.at(-1)?.match(/\d+/)?.[0] ?? 0) + 1).padStart(6, '0')}.jsonl`;
                 this.segments.push(name);
+                this.rotateBeforeAppend = false;
                 this.activeBytes = 0;
                 this.writeManifest();
             }
@@ -301,6 +381,7 @@ export class ConversationEventStore {
     writeManifest() {
         const manifest = {
             schemaVersion: 1, nextSeq: this.nextSeq, segments: this.segments,
+            ...(this.failedGenerations.size ? { failedGenerations: [...this.failedGenerations] } : {}),
         };
         const tmp = join(this.dir, MANIFEST + '.tmp');
         try {
@@ -308,12 +389,115 @@ export class ConversationEventStore {
             renameSync(tmp, join(this.dir, MANIFEST));
         }
         catch (error) {
-            // The manifest is a recovery accelerator, not the source of truth;
-            // segments alone can always rebuild it.
+            // Segments reconstruct durable records, but cannot reconstruct reserved
+            // identities or failed-generation latches retained only in the manifest.
             this.log(`conversation manifest write failed: ${error.message}`);
         }
     }
     // ── reads ──────────────────────────────────────────────────────────────────
+    /** One forward iterator owns the scan; each segment is opened at most once. */
+    async *replay(request) {
+        const { expectedGeneration, after, through, signal } = request;
+        const available = Number(this.lastCursor() ?? 0);
+        if (!expectedGeneration || !Number.isSafeInteger(after) || after < 0 ||
+            !Number.isSafeInteger(through) || through < after || through > available)
+            throw new ReplayCoverageError('invalid cursor or barrier');
+        const check = () => {
+            signal?.throwIfAborted();
+            if (this.unavailable || this.failedGenerations.has(expectedGeneration))
+                throw new ReplayCoverageError('generation has non-durable events');
+        };
+        check();
+        const floor = this.generationFloors.get(expectedGeneration);
+        if (floor === undefined && through > after)
+            throw new ReplayCoverageError('generation is not retained');
+        let coveredThrough = Math.max(after, Math.min(floor ?? after, through));
+        let events = [];
+        let count = 0;
+        let bytes = 0;
+        const pageSize = Math.min(1000, Math.max(1, request.pageSize ?? 128));
+        const segments = this.segments.map(name => ({ name, ...this.segmentRanges.get(name) }));
+        const nextFirst = new Array(segments.length);
+        let following;
+        for (let i = segments.length - 1; i >= 0; i--) {
+            nextFirst[i] = following;
+            following = segments[i].first ?? following;
+        }
+        let corruptPrefix = false;
+        for (let index = 0; index < segments.length && coveredThrough < through; index++) {
+            check();
+            const segment = segments[index];
+            const followingFirst = nextFirst[index];
+            // A verified later old record localizes earlier damage outside the requested range.
+            if ((segment.last !== undefined && segment.last <= coveredThrough && !segment.damaged) ||
+                (followingFirst !== undefined && followingFirst <= coveredThrough))
+                continue;
+            try {
+                for await (const line of replayLines(join(this.dir, segment.name), signal)) {
+                    check();
+                    if (!line.trim())
+                        continue;
+                    let event;
+                    try {
+                        event = JSON.parse(line);
+                    }
+                    catch {
+                        corruptPrefix = true;
+                        continue;
+                    }
+                    if (event.schemaVersion !== 1 || !Number.isSafeInteger(event.seq) || event.seq < 1) {
+                        corruptPrefix = true;
+                        continue;
+                    }
+                    if (event.seq <= Math.max(after, floor ?? after)) {
+                        corruptPrefix = false;
+                        continue;
+                    }
+                    if (corruptPrefix)
+                        throw new ReplayCoverageError('corrupt record in requested range');
+                    if (event.seq <= coveredThrough)
+                        throw new ReplayCoverageError('non-monotonic sequence');
+                    if (event.seq !== coveredThrough + 1)
+                        throw new ReplayCoverageError('missing sequence');
+                    const visible = event.sessionGeneration === expectedGeneration && event.source !== 'agent_replay';
+                    const eventBytes = visible ? Buffer.byteLength(line) : 0;
+                    if (count && bytes + eventBytes > 256 * 1024) {
+                        yield { events, coveredThrough };
+                        events = [];
+                        count = 0;
+                        bytes = 0;
+                        await yieldTurn();
+                        check();
+                    }
+                    coveredThrough = event.seq;
+                    count++;
+                    if (visible) {
+                        events.push(event);
+                        bytes += eventBytes;
+                    }
+                    if (count >= pageSize || bytes >= 256 * 1024 || coveredThrough === through) {
+                        yield { events, coveredThrough };
+                        events = [];
+                        count = 0;
+                        bytes = 0;
+                        await yieldTurn();
+                    }
+                    if (coveredThrough === through)
+                        break;
+                }
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    throw error;
+                throw new ReplayCoverageError(error.message);
+            }
+        }
+        check();
+        if (coveredThrough !== through)
+            throw new ReplayCoverageError('barrier is not retained');
+        if (count || (through > after && floor !== undefined && floor >= through))
+            yield { events, coveredThrough };
+    }
     eventsAfter(after, limit) {
         // Serve from the in-memory tail whenever the range allows it.
         if (this.tail.length && after >= this.tail[0].seq - 1)

package/dist/session/conversation-types.d.ts

@@ -1,5 +1,5 @@
 import type { TaskCreatedNotice } from './task-notice.js';
-import type { PromptOrigin, TurnCancellationSource, TurnOutcome } from './types.js';
+import type { PromptOrigin, SessionSnapshot, TurnCancellationSource, TurnOutcome } from './types.js';
 /**
  * Durable conversation domain schema for managed-session consoles.
  *
@@ -282,6 +282,8 @@ export interface SubmitPromptCommand {
 }
 export interface PromptReceipt {
     commandId: string;
+    /** Original durable admission generation; absent when historical provenance is unknown. */
+    sessionGeneration?: string;
     promptId: string;
     state: 'queued' | 'starting';
     queuedBehind: number;
@@ -311,10 +313,36 @@ export interface ConversationSnapshot {
     queueDepth: number;
     pendingPermissionIds: string[];
     historyDegraded?: boolean;
+    /** Live observation is unavailable; REST may still serve canonical durable data. */
+    observationFailure?: 'capture_failed';
     /** Every waiting prompt, in delivery order; `pendingPromptCount` equals its length. */
     pendingPrompts?: PendingPromptSummary[];
     pendingPromptCount?: number;
 }
+/** Position captured synchronously with the owning backend's complete live state. */
+export interface ObservationPosition {
+    sessionGeneration: string;
+    stateRevision: number;
+    ledgerBarrier: number;
+}
+export interface ConversationObservationState extends ConversationSnapshot, ObservationPosition {
+    alive: boolean;
+    activePromptIds: string[];
+    pendingPrompts: PendingPromptSummary[];
+    pendingPromptCount: number;
+    /** Already presented and sanitized by the backend; never reconstructed from raw options. */
+    pendingPermissions: Array<PermissionRequestedPayload & {
+        permissionId: string;
+    }>;
+    commands: NonNullable<CapabilitiesUpdatedPayload['commands']>;
+    runtimeModel?: SessionSnapshot['runtimeModel'];
+    reasoningEffort?: SessionSnapshot['reasoningEffort'];
+    permissionMode?: SessionSnapshot['permissionMode'];
+}
+export interface ConversationObservation {
+    snapshot: ConversationObservationState;
+    unsubscribe(): void;
+}
 export interface ConversationPage {
     events: ConversationEventV1[];
     firstAvailableCursor?: string;

package/dist/session/types.d.ts

@@ -300,6 +300,12 @@ export interface AgentSession {
         limit?: number;
     }): ConversationHandlePage;
     conversationSnapshot?(): ConversationSnapshot;
+    /** Side-effect-free current-generation durability eligibility; does not certify a historical range. */
+    conversationReplayAvailable?(expectedGeneration: string): boolean;
+    replayConversation?(request: import('./conversation-replay.js').ConversationReplayRequest): AsyncIterable<import('./conversation-replay.js').ConversationReplayPage>;
+    /** Passive: registering never attaches a controller or acknowledges activity. */
+    observeConversation?(listener: (state: import('./conversation-types.js').ConversationObservationState) => void): import('./conversation-types.js').ConversationObservation;
+    subscribeConversationFailure?(listener: (generation: string) => void): () => void;
     subscribeConversation?(listener: (event: ConversationEventV1) => void): () => void;
     /** Durably admit an idempotent browser prompt; resolves on admission. */
     submitPromptBrowser?(command: SubmitPromptCommand): Promise<PromptReceipt>;

package/dist/web/auth.d.ts

@@ -65,6 +65,8 @@ export declare class WebAuth {
     anonymous(request: FastifyRequest): BrowserSession;
     resume(request: FastifyRequest): AuthResult;
     authenticate(request: FastifyRequest, mutation?: boolean): BrowserSession;
+    /** Check a transport's opening lease without refreshing cookie idle activity. */
+    sessionValid(session: Pick<BrowserSession, 'id' | 'absoluteExpiresAt'>): boolean;
     logout(request: FastifyRequest): void;
     mintTicket(request: FastifyRequest, purpose: Ticket['purpose'], roleId?: string): {
         ticket: string;

package/dist/web/auth.js

@@ -136,7 +136,7 @@ export class WebAuth {
         const id = parseCookies(request.headers.cookie ?? '').ofs_session;
         const session = id ? this.sessions.get(id) : undefined;
         const now = this.now();
-        if (!session || now > session.absoluteExpiresAt || now - session.lastSeenAt > 30 * 60_000) {
+        if (!session || !this.sessionValid(session)) {
             if (id)
                 this.removeSession(id);
             throw new FleetError('unauthorized', 'browser session is missing or expired');
@@ -150,6 +150,15 @@ export class WebAuth {
         session.lastSeenAt = now;
         return session;
     }
+    /** Check a transport's opening lease without refreshing cookie idle activity. */
+    sessionValid(session) {
+        const current = this.sessions.get(session.id), now = this.now();
+        if (!current || now >= session.absoluteExpiresAt)
+            return false;
+        if (session.id.startsWith('workspace:'))
+            return Boolean(this.workspaceDevices?.valid(session.id.slice(10)));
+        return now < current.absoluteExpiresAt && now - current.lastSeenAt < 30 * 60_000;
+    }
     logout(request) {
         const session = this.authenticate(request, true);
         const deviceId = this.sessionDevices.get(session.id);

package/dist/web/conversation-stream-codec.d.ts

@@ -0,0 +1,23 @@
+/** Public v1 wire contract. Kept free of Node APIs so browser consumers can share it. */
+export declare const MAX_FRAME_BYTES: number;
+export declare const MAX_ASSEMBLY_BYTES: number;
+export declare const MAX_PENDING_BYTES: number;
+export type ConversationRecordType = 'ready' | 'ledger' | 'state' | 'role' | 'resync' | 'keepalive';
+export interface ConversationStreamRecord {
+    version: 1;
+    type: ConversationRecordType;
+    payload: unknown;
+}
+/** A payload is the logical record; SSE/JSON envelopes do not consume its assembly budget. */
+export declare function encodeConversationRecord(type: ConversationRecordType, payload: unknown, id: string): Generator<string>;
+/** Strict incremental decoder: one assembly, no partial publication, UTF-8 split safe. */
+export declare class ConversationStreamDecoder {
+    private readonly publish;
+    private decoder;
+    private pending;
+    private assembly?;
+    constructor(publish: (record: ConversationStreamRecord) => void);
+    push(bytes: Uint8Array): void;
+    finish(): void;
+    private accept;
+}

package/dist/web/conversation-stream-codec.js

@@ -0,0 +1,110 @@
+/** Public v1 wire contract. Kept free of Node APIs so browser consumers can share it. */
+export const MAX_FRAME_BYTES = 512 * 1024;
+export const MAX_ASSEMBLY_BYTES = 16 * 1024 * 1024;
+export const MAX_PENDING_BYTES = 8 * 1024 * 1024;
+const utf8 = new TextEncoder();
+const types = new Set(['ready', 'ledger', 'state', 'role', 'resync', 'keepalive']);
+const frame = (value) => `event: conversation\ndata: ${JSON.stringify(value)}\n\n`;
+const identity = (payload) => ({ generation: payload?.sessionGeneration ?? payload?.snapshot?.sessionGeneration,
+    revision: payload?.stateRevision ?? payload?.snapshot?.stateRevision ?? payload?.roleRevision });
+/** A payload is the logical record; SSE/JSON envelopes do not consume its assembly budget. */
+export function* encodeConversationRecord(type, payload, id) {
+    const json = JSON.stringify(payload), totalBytes = utf8.encode(json).byteLength;
+    if (totalBytes > MAX_ASSEMBLY_BYTES)
+        throw new Error('conversation record exceeds assembly limit');
+    const direct = frame({ version: 1, type, payload });
+    if (utf8.encode(direct).byteLength <= MAX_FRAME_BYTES) {
+        yield direct;
+        return;
+    }
+    const position = identity(payload);
+    yield frame({ version: 1, type: 'start', id, recordType: type, totalBytes, ...position });
+    // At most 48K UTF-16 units: even worst-case JSON escapes fit a 512 KiB frame.
+    let index = 0;
+    for (let offset = 0; offset < json.length;) {
+        let end = Math.min(json.length, offset + 48 * 1024);
+        if (end < json.length && /[\uD800-\uDBFF]/.test(json[end - 1]))
+            end--;
+        yield frame({ version: 1, type: 'chunk', id, index: index++, data: json.slice(offset, end) });
+        offset = end;
+    }
+    yield frame({ version: 1, type: 'commit', id, totalBytes, ...position });
+}
+/** Strict incremental decoder: one assembly, no partial publication, UTF-8 split safe. */
+export class ConversationStreamDecoder {
+    publish;
+    decoder = new TextDecoder('utf-8', { fatal: true });
+    pending = '';
+    assembly;
+    constructor(publish) {
+        this.publish = publish;
+    }
+    push(bytes) {
+        try {
+            this.pending += this.decoder.decode(bytes, { stream: true });
+            for (;;) {
+                const end = this.pending.indexOf('\n\n');
+                if (end < 0)
+                    break;
+                const text = this.pending.slice(0, end + 2);
+                this.pending = this.pending.slice(end + 2);
+                if (utf8.encode(text).byteLength > MAX_FRAME_BYTES)
+                    throw new Error('frame limit exceeded');
+                if (!text.startsWith('event: conversation\ndata: '))
+                    throw new Error('invalid conversation frame');
+                this.accept(JSON.parse(text.slice(26, -2)));
+            }
+            if (utf8.encode(this.pending).byteLength > MAX_FRAME_BYTES)
+                throw new Error('frame limit exceeded');
+        }
+        catch (error) {
+            this.pending = '';
+            this.assembly = undefined;
+            throw error;
+        }
+    }
+    finish() {
+        const rest = this.decoder.decode();
+        if (rest || this.pending || this.assembly)
+            throw new Error('incomplete conversation stream');
+    }
+    accept(value) {
+        if (value?.version !== 1)
+            throw new Error('unsupported conversation version');
+        if (types.has(value.type)) {
+            if (this.assembly)
+                throw new Error('overlapping assembly');
+            this.publish(value);
+            return;
+        }
+        if (value.type === 'start') {
+            if (this.assembly)
+                throw new Error('overlapping assembly');
+            if (typeof value.id !== 'string' || !types.has(value.recordType) || !Number.isSafeInteger(value.totalBytes) || value.totalBytes < 1 || value.totalBytes > MAX_ASSEMBLY_BYTES)
+                throw new Error('invalid assembly length/type');
+            this.assembly = { id: value.id, type: value.recordType, total: value.totalBytes, bytes: 0, index: 0, parts: [], generation: value.generation, revision: value.revision };
+            return;
+        }
+        const assembly = this.assembly;
+        if (!assembly || value.id !== assembly.id)
+            throw new Error('assembly identity mismatch');
+        if (value.type === 'chunk') {
+            if (value.index !== assembly.index++ || typeof value.data !== 'string')
+                throw new Error('assembly chunk order');
+            if (!value.data.length)
+                throw new Error('assembly empty chunk');
+            assembly.bytes += utf8.encode(value.data).byteLength;
+            if (assembly.bytes > assembly.total)
+                throw new Error('assembly length exceeded');
+            assembly.parts.push(value.data);
+            return;
+        }
+        if (value.type !== 'commit' || value.totalBytes !== assembly.total || assembly.bytes !== assembly.total)
+            throw new Error('assembly length mismatch');
+        const payload = JSON.parse(assembly.parts.join('')), position = identity(payload);
+        if (value.generation !== assembly.generation || value.revision !== assembly.revision || position.generation !== assembly.generation || position.revision !== assembly.revision)
+            throw new Error('assembly revision mismatch');
+        this.assembly = undefined;
+        this.publish({ version: 1, type: assembly.type, payload });
+    }
+}

package/dist/web/conversation-stream.d.ts

@@ -0,0 +1,25 @@
+import type { Writable } from 'node:stream';
+import { type ConversationRecordType } from './conversation-stream-codec.js';
+/** One active logical record; only waiting encoded output consumes the pending budget. */
+export declare class ConversationStreamWriter {
+    private readonly output;
+    private readonly failed;
+    private queue;
+    private active?;
+    private waiting;
+    private ended;
+    private sequence;
+    pendingBytes: number;
+    get busy(): boolean;
+    constructor(output: Writable, failed: (reason: string) => void);
+    private error;
+    private drain;
+    send(type: ConversationRecordType, payload: unknown): boolean;
+    private flush;
+    private fail;
+    close(): void;
+}
+import type { FastifyInstance } from 'fastify';
+import type { WebServices } from './server.js';
+import type { WebAuth } from './auth.js';
+export declare function registerConversationStream(app: FastifyInstance, services: WebServices, auth: WebAuth): void;