@playola-radio/slipstream 0.1.0 → 0.3.0

package/dist/questions.js

@@ -154,12 +154,111 @@ export function questionResult(event) {
 }
 /** Answer text is stored verbatim, so it is checked but never trimmed. Unpaired
  * surrogates are refused for the same reason as in question text. */
-export function assertAnswerText(text) {
+export function assertAnswerText(text, maxBytes = MAX_ANSWER_BYTES) {
     if (typeof text !== 'string' || !/\S/u.test(text) || /[\uD800-\uDFFF]/u.test(text)
-        || Buffer.byteLength(text, 'utf8') > MAX_ANSWER_BYTES) {
-        throw new QuestionError('INVALID_ANSWER', `answer text must contain a non-whitespace character and be at most ${MAX_ANSWER_BYTES} UTF-8 bytes`);
+        || Buffer.byteLength(text, 'utf8') > maxBytes) {
+        const limit = Number.isFinite(maxBytes) ? ` and be at most ${maxBytes} UTF-8 bytes` : '';
+        throw new QuestionError('INVALID_ANSWER', `answer text must contain a non-whitespace character${limit}`);
     }
 }
+const HARNESSES = ['claude-code', 'codex'];
+const CONTROL_CHARS = /[\u0000-\u001F\u007F-\u009F]/;
+function conversationId(value, name) {
+    if (typeof value !== 'string' || value.length < 1 || value.length > 256 || CONTROL_CHARS.test(value)
+        || /[\uD800-\uDFFF]/u.test(value)) {
+        throw new QuestionError('PROTOCOL', `${name} must be 1–256 characters with no control characters or unpaired surrogates`);
+    }
+    return value;
+}
+/** Client-reported conversation ids are unverified: only their shape is checked. The answer is never trimmed or capped. */
+export function normalizeExchange(value) {
+    const ask = normalizeAsk(value);
+    const req = record(value);
+    assertAnswerText(req.answer_text, Infinity);
+    const conv = req.conversation;
+    if (typeof conv !== 'object' || conv === null || Array.isArray(conv)) {
+        throw new QuestionError('PROTOCOL', 'exchange requires a conversation object');
+    }
+    const c = conv;
+    if (!HARNESSES.includes(c.harness)) {
+        throw new QuestionError('PROTOCOL', `conversation.harness must be one of ${HARNESSES.join(', ')}`);
+    }
+    const parent = conversationId(c.parent_session_id, 'conversation.parent_session_id');
+    const fork = conversationId(c.fork_session_id, 'conversation.fork_session_id');
+    if (parent === fork)
+        throw new QuestionError('PROTOCOL', 'conversation parent and fork ids must differ');
+    return { ...ask, answer_text: req.answer_text, conversation: {
+            harness: c.harness, parent_session_id: parent, fork_session_id: fork,
+        }, ...(req.relay !== undefined ? { relay: normalizeRelay(req.relay) } : {}) };
+}
+function normalizeRelay(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new QuestionError('PROTOCOL', 'relay must be an object');
+    const r = value;
+    if (typeof r.relay_id !== 'string' || !UUID.test(r.relay_id))
+        throw new QuestionError('PROTOCOL', 'relay.relay_id must be a canonical lowercase UUID');
+    return { relay_id: r.relay_id, chat_session_id: conversationId(r.chat_session_id, 'relay.chat_session_id') };
+}
+/**
+ * Idempotency fingerprint: the sha256 hex digest of the JSON of the ask body plus the answer, the
+ * reported conversation and the relay when present (an exchange without one keeps its original digest).
+ * A digest, not the JSON itself, so the capture does not retain every answer (up to ~1 MiB each) for
+ * its lifetime.
+ */
+export function exchangeBody(req) {
+    const c = req.conversation;
+    const relay = req.relay ? [req.relay.relay_id, req.relay.chat_session_id] : [];
+    const json = JSON.stringify([questionBody(req), req.answer_text, c.harness, c.parent_session_id, c.fork_session_id, ...relay]);
+    return createHash('sha256').update(json).digest('hex');
+}
+export function exchangeResult(event) {
+    const d = event.data;
+    return Object.freeze({ session_id: d.session_id, request_id: d.request_id, question_id: d.question_id,
+        seq: event.seq, duplicate: false });
+}
+function normalizeUpdate(value) {
+    const u = record(value);
+    switch (u.kind) {
+        case 'sent': return { kind: 'sent', chat_session_id: conversationId(u.chat_session_id, 'update.chat_session_id') };
+        case 'picked_up': return { kind: 'picked_up' };
+        case 'not_delivered': return { kind: 'not_delivered' };
+        case 'reported':
+            if (u.outcome !== 'done' && u.outcome !== 'not_done_yet')
+                throw new QuestionError('PROTOCOL', 'update.outcome must be done or not_done_yet');
+            // Stored verbatim, like answer text.
+            if (typeof u.text !== 'string' || !/\S/u.test(u.text) || /[\uD800-\uDFFF]/u.test(u.text)) {
+                throw new QuestionError('PROTOCOL', 'update.text must contain a non-whitespace character and no unpaired surrogates');
+            }
+            return { kind: 'reported', outcome: u.outcome, text: u.text };
+        default: throw new QuestionError('PROTOCOL', 'update.kind must be sent, picked_up, not_delivered or reported');
+    }
+}
+/** Copy only contract fields, as normalizeAsk does. */
+export function normalizeRelayUpdate(value) {
+    const req = record(value);
+    for (const name of ['session_id', 'request_id', 'question_id', 'relay_id']) {
+        if (typeof req[name] !== 'string' || !UUID.test(req[name]))
+            throw new QuestionError('PROTOCOL', `${name} must be a canonical lowercase UUID`);
+    }
+    return { session_id: req.session_id, request_id: req.request_id, question_id: req.question_id,
+        relay_id: req.relay_id, update: normalizeUpdate(req.update) };
+}
+/** Idempotency fingerprint: a digest, as for exchanges, because a report's text is unbounded. */
+export function relayUpdateBody(req) {
+    const u = req.update;
+    const fields = u.kind === 'sent' ? [u.chat_session_id] : u.kind === 'reported' ? [u.outcome, u.text] : [];
+    return createHash('sha256').update(JSON.stringify([req.question_id, req.relay_id, u.kind, ...fields])).digest('hex');
+}
+export function relayUpdateResult(event) {
+    const d = event.data;
+    return Object.freeze({ session_id: d.session_id, request_id: d.request_id, question_id: d.question_id,
+        relay_id: d.relay_id, seq: event.seq, duplicate: false });
+}
+/** A follow-up must restate its parent's exact source context. */
+export function sameSourceContext(parent, c) {
+    return parent !== undefined && parent.change_seq === c.change_seq && parent.path === c.path && parent.snapshot_sha256 === c.snapshot_sha256
+        && parent.line_start === c.line_start && parent.line_end === c.line_end;
+}
 export function answerResult(event) {
     const d = event.data;
     return Object.freeze({ session_id: d.session_id, question_id: d.question_id, event_id: event.seq, seq: event.seq,

package/dist/recovery.js

@@ -81,16 +81,23 @@ export async function recoverSession(logPath, expectedSessionId, cas) {
     const questions = [];
     const questionAttempts = [];
     const questionAnswers = [];
+    const questionExchanges = [];
+    const questionRelayUpdates = [];
+    const relayQuestions = new Map();
+    const exchangeQuestionIds = new Set();
     // Keep the ordered event arrays for callers, while replay validation uses
     // indexes so a long-lived session is replayed in one pass.
     const queuedSeqsByQuestion = new Map();
-    const attemptSeqByQuestion = new Map();
+    const attemptSeqsByQuestion = new Map();
     const answeredQuestionIds = new Set();
     const verifiedBlobs = new Map(); // sha256 -> verified byte length
     let root;
     let maxBytes;
     let baselineCompleted = false;
     let currentTaskId;
+    let resumeSeq = 0n;
+    let unlinkSeq = 0n;
+    const bindingGenerations = new Set();
     let seq = 0n;
     const verifyBlob = async (snap, where) => {
         if (snap.kind !== 'content')
@@ -106,8 +113,14 @@ export async function recoverSession(logPath, expectedSessionId, cas) {
         try {
             bytes = await cas.read(snap.sha256);
         }
-        catch {
-            throw new CorruptLogError(`${where}: referenced blob ${snap.sha256} is missing`);
+        catch (err) {
+            // A missing content-addressed path proves this history cannot be replayed.
+            // Other read errors (EACCES, EIO, EMFILE) only describe the store's current
+            // availability, so keep them retryable rather than recommending deletion.
+            if (err.code === 'ENOENT') {
+                throw new CorruptLogError(`${where}: referenced blob ${snap.sha256} is missing`);
+            }
+            throw err;
         }
         if (bytes.length !== snap.size) {
             throw new CorruptLogError(`${where}: blob ${snap.sha256} size ${bytes.length} != ${snap.size}`);
@@ -224,18 +237,22 @@ export async function recoverSession(logPath, expectedSessionId, cas) {
                 break;
             }
             case 'slipstream.question.dispatch_attempted.v1': {
+                // Only an unlink offers an attempted question again.
+                const attemptSeqs = attemptSeqsByQuestion.get(event.data.question_id) ?? [];
+                const lastAttempt = attemptSeqs.at(-1);
                 if (event.subject !== `question/${event.data.question_id}`
                     || !queuedSeqsByQuestion.get(event.data.question_id)?.has(event.data.queued_seq)
-                    || attemptSeqByQuestion.has(event.data.question_id)) {
+                    || (lastAttempt !== undefined && BigInt(lastAttempt) > unlinkSeq)) {
                     throw new CorruptLogError(`${at}: dispatch attempt has no unique queued question`);
                 }
                 questionAttempts.push(event);
-                attemptSeqByQuestion.set(event.data.question_id, event.seq);
+                attemptSeqs.push(event.seq);
+                attemptSeqsByQuestion.set(event.data.question_id, attemptSeqs);
                 break;
             }
             case 'slipstream.question.answered.v1': {
                 if (event.subject !== `question/${event.data.question_id}`
-                    || attemptSeqByQuestion.get(event.data.question_id) !== event.data.attempt_seq
+                    || !attemptSeqsByQuestion.get(event.data.question_id)?.includes(event.data.attempt_seq)
                     || answeredQuestionIds.has(event.data.question_id)) {
                     throw new CorruptLogError(`${at}: answer has no unique attempted question`);
                 }
@@ -243,6 +260,30 @@ export async function recoverSession(logPath, expectedSessionId, cas) {
                 answeredQuestionIds.add(event.data.question_id);
                 break;
             }
+            case 'slipstream.question.exchange_recorded.v1': {
+                if (event.subject !== `question/${event.data.question_id}`)
+                    throw new CorruptLogError(`${at}: question subject disagrees with id`);
+                if (event.data.relay && relayQuestions.has(event.data.relay.relay_id))
+                    throw new CorruptLogError(`${at}: relay_id was already sent`);
+                questionExchanges.push(event);
+                exchangeQuestionIds.add(event.data.question_id);
+                if (event.data.relay)
+                    relayQuestions.set(event.data.relay.relay_id, event.data.question_id);
+                break;
+            }
+            case 'slipstream.question.relay_updated.v1': {
+                // The live checks in recordQuestionRelayUpdate, replayed.
+                const owner = relayQuestions.get(event.data.relay_id);
+                if (event.subject !== `question/${event.data.question_id}`
+                    || !exchangeQuestionIds.has(event.data.question_id)
+                    || (event.data.update.kind === 'sent' ? owner !== undefined : owner !== event.data.question_id)) {
+                    throw new CorruptLogError(`${at}: relay update has no matching sent relay`);
+                }
+                questionRelayUpdates.push(event);
+                if (event.data.update.kind === 'sent')
+                    relayQuestions.set(event.data.relay_id, event.data.question_id);
+                break;
+            }
             case 'slipstream.task.started.v1': {
                 // Replayed in order: the last committed declaration is the current task,
                 // and its request_id indexes the committed result so a replayed duplicate
@@ -255,7 +296,16 @@ export async function recoverSession(logPath, expectedSessionId, cas) {
                 });
                 break;
             }
+            case 'slipstream.agent.binding.v1':
+                bindingGenerations.add(event.data.binding_generation);
+                break;
             case 'slipstream.session.resumed.v1':
+                currentTaskId = undefined;
+                resumeSeq = BigInt(event.seq);
+                break;
+            case 'slipstream.agent.unlinked.v1':
+                currentTaskId = undefined;
+                unlinkSeq = BigInt(event.seq);
                 break;
         }
     }
@@ -294,10 +344,16 @@ export async function recoverSession(logPath, expectedSessionId, cas) {
         baselineUnknownDirs,
         storageGapSeqByEpisode,
         currentTaskId,
+        resumeSeq,
+        unlinkSeq,
         taskDeclarations,
         attributionEvents,
         questions,
         questionAttempts,
         questionAnswers,
+        questionExchanges,
+        questionRelayUpdates,
+        relayQuestions,
+        bindingGenerations,
     };
 }