@naswerks/periscope 1.0.0

package/dist/persistence/mirror.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The mirror's own rules — deduplication on the way in, and what a dropped batch means.
+ *
+ * Two mirrors exist and they are not the same thing. The SDK dual-writes: the subprocess writes
+ * locally first, then hands a batch to the adapter. Its retry and its drop are the SDK's behaviour —
+ * this host cannot change them and must not pretend to. What belongs here is what an adapter does
+ * with a batch it receives, and what the host does when the SDK tells it a batch was lost.
+ *
+ * A dropped batch is the one failure that looks exactly like nothing happening. The store simply
+ * has fewer entries than local disk, with no error at the read and no gap anything can compute — the
+ * durable copy is silently behind local truth. So the host surfaces the SDK's own report as a named
+ * degrade rather than logging it and moving on. Silence here is indistinguishable from health.
+ */
+import type { TranscriptEntry } from './entry.js';
+import type { TranscriptKey } from './key.js';
+/**
+ * How a mirror write failed, as the SDK distinguishes them.
+ *
+ * The two are not one failure with two names, and a test that covers only the first measures the
+ * retry loop rather than the drop. A rejection is retried — three attempts in total, with short
+ * backoff. A timeout is not retried at all, because the in-flight call may still land, so a timeout
+ * drops on its first failure. An operator reasoning from "it retries three times" will therefore
+ * mis-predict every timeout-shaped outage, and a slow store is the likeliest way to lose data here.
+ */
+export type MirrorFailureKind = 'rejected' | 'timed-out';
+/**
+ * Attempts each failure kind receives before the batch is dropped. Data, so the asymmetry above is
+ * checkable rather than remembered.
+ */
+export declare const MIRROR_ATTEMPTS: Readonly<Record<MirrorFailureKind, number>>;
+/** What was lost, and enough to say which session lost it. */
+export interface MirrorDrop {
+    readonly key: TranscriptKey;
+    readonly kind: MirrorFailureKind;
+    readonly attempts: number;
+    /** The store's own error text. Never parsed — carried so a human can read it. */
+    readonly error: string;
+    /**
+     * The uuids in the lost batch, where the entries carried them.
+     *
+     * This is what makes a drop recoverable rather than merely reported. With the ids, a consumer
+     * can re-drive those entries from local disk, which is still authoritative. Without them a drop is
+     * only an alarm.
+     */
+    readonly entryUuids: readonly string[];
+}
+/** A dropped batch as one line a human reads. Never parsed back. */
+export declare function describeMirrorDrop(drop: MirrorDrop): string;
+/** What a batch splits into once the store's existing ids are known. */
+export interface DedupedBatch {
+    /** Entries to write. */
+    readonly append: readonly TranscriptEntry[];
+    /** Entries already present, identified by uuid. */
+    readonly skipped: readonly TranscriptEntry[];
+}
+/**
+ * Split a batch into what to write and what is already there.
+ *
+ * An entry with no `uuid` is always appended, never deduplicated. The adapter contract is explicit
+ * that most entries carry a stable uuid and that the ones that do not — titles, tags, mode markers —
+ * should be appended without dedup. Treating "no uuid" as a duplicate would silently drop every one
+ * of them; treating them as distinct is the contract, and the cost is at worst a repeated marker.
+ *
+ * Why dedup at all: the contract says retries and transcript imports replay batches, and asks
+ * adapters to treat the uuid as an idempotency key so a replay does not create duplicate rows. A
+ * store without this grows a second copy of a session every time a batch is retried.
+ */
+export declare function dedupeBatch(knownUuids: ReadonlySet<string>, batch: readonly TranscriptEntry[]): DedupedBatch;
+/** Every uuid in a stored transcript, for the dedup above. */
+export declare function uuidsIn(entries: readonly TranscriptEntry[]): Set<string>;
+//# sourceMappingURL=mirror.d.ts.map

package/dist/persistence/mirror.js

@@ -0,0 +1,57 @@
+/**
+ * Attempts each failure kind receives before the batch is dropped. Data, so the asymmetry above is
+ * checkable rather than remembered.
+ */
+export const MIRROR_ATTEMPTS = {
+    rejected: 3,
+    'timed-out': 1,
+};
+/** A dropped batch as one line a human reads. Never parsed back. */
+export function describeMirrorDrop(drop) {
+    const attemptWord = drop.attempts === 1 ? 'attempt' : 'attempts';
+    const scope = drop.key.subpath === undefined ? drop.key.sessionId : `${drop.key.sessionId}/${drop.key.subpath}`;
+    return (`mirror batch DROPPED for ${scope} after ${drop.attempts} ${attemptWord} (${drop.kind}): ${drop.error} — ` +
+        `${drop.entryUuids.length} entr${drop.entryUuids.length === 1 ? 'y is' : 'ies are'} in the store's ` +
+        'copy no longer, though local disk still holds them');
+}
+/**
+ * Split a batch into what to write and what is already there.
+ *
+ * An entry with no `uuid` is always appended, never deduplicated. The adapter contract is explicit
+ * that most entries carry a stable uuid and that the ones that do not — titles, tags, mode markers —
+ * should be appended without dedup. Treating "no uuid" as a duplicate would silently drop every one
+ * of them; treating them as distinct is the contract, and the cost is at worst a repeated marker.
+ *
+ * Why dedup at all: the contract says retries and transcript imports replay batches, and asks
+ * adapters to treat the uuid as an idempotency key so a replay does not create duplicate rows. A
+ * store without this grows a second copy of a session every time a batch is retried.
+ */
+export function dedupeBatch(knownUuids, batch) {
+    const append = [];
+    const skipped = [];
+    const seenInBatch = new Set();
+    for (const entry of batch) {
+        const uuid = entry.uuid;
+        if (typeof uuid !== 'string' || uuid.length === 0) {
+            append.push(entry);
+            continue;
+        }
+        if (knownUuids.has(uuid) || seenInBatch.has(uuid)) {
+            skipped.push(entry);
+            continue;
+        }
+        seenInBatch.add(uuid);
+        append.push(entry);
+    }
+    return { append, skipped };
+}
+/** Every uuid in a stored transcript, for the dedup above. */
+export function uuidsIn(entries) {
+    const uuids = new Set();
+    for (const entry of entries) {
+        if (typeof entry.uuid === 'string' && entry.uuid.length > 0)
+            uuids.add(entry.uuid);
+    }
+    return uuids;
+}
+//# sourceMappingURL=mirror.js.map

package/dist/persistence/receipt.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The delivery receipt — did the text a controller injected actually land in the session?
+ *
+ * Getting this wrong is silent. Read the three defences below before changing anything here.
+ *
+ * What it is read from, and why that is the whole point. A receipt is answered from raw stored
+ * entries — the adapter's `load`, or the local JSONL — and never from the SDK's conversation reader.
+ * That reader reconstructs the conversation by following `parentUuid` links, and compaction relinks
+ * those links: the shipped types say a loader splices the preserved segment at an anchor uuid and
+ * relinks each preserved uuid to its predecessor rather than walking `parentUuid` at all, and that
+ * both the preserved-segment and preserved-messages blocks are "unset when compaction summarizes
+ * everything". So after a compaction a `parentUuid` walk structurally cannot reach pre-compaction
+ * turns. Raw entries are append-only and lose nothing, which is why the receipt reads those.
+ *
+ * The reader is not banned — it is for a different question. "What would the agent see?" is
+ * exactly the post-compaction conversation, and the SDK's reader answers it correctly. "What
+ * actually happened?" is this file. Two questions, two reads; using one for the other is the defect.
+ *
+ * The three defences, each with a different failure direction. They are named because an
+ * invariant defended in depth cannot be proven by removing one guard — the test then measures
+ * the redundancy instead of the invariant.
+ *
+ *   Defence 1  Raw entries, never a `parentUuid` walk.   Removing it means a false negative after
+ *                                                        a compaction.
+ *   Defence 2  A uuid anchor, never a numeric offset.    Removing it means a false negative, or a
+ *                                                        mis-anchored scan, the moment the entry
+ *                                                        count shrinks.
+ *   Defence 3  Compaction-produced entries are not       Removing it means a false positive — the
+ *              candidates.                               summary a compaction writes is matched as
+ *                                                        if it were the injected turn, so the
+ *                                                        controller is told text landed that the
+ *                                                        agent never saw.
+ *
+ * Defences 1 and 2 fail toward "it did not land", which makes a controller paste the text a second
+ * time. Defence 3 fails toward "it landed", which makes a controller move on from an inject that
+ * never arrived. Both are silent; they are opposite, and no single test can see both.
+ */
+import type { Result } from '../core/result.js';
+import type { TranscriptEntry } from './entry.js';
+/**
+ * What to look for.
+ *
+ * There is no offset field, and its absence is Defence 2. A count is meaningless across a
+ * compaction: the conversation the agent sees can shrink from hundreds of entries to a handful, so
+ * "past entry 412" stops addressing anything. A uuid addresses one entry for as long as that entry
+ * exists, and in an append-only log it exists forever. If this interface ever grows a numeric
+ * baseline, the receipt has been reopened to the exact defect it was written to close.
+ */
+export interface ReceiptQuery {
+    /**
+     * The uuid of the last entry seen before the inject. `null` scans the whole transcript.
+     *
+     * A controller takes this from its own pre-inject read. `null` is for the first inject into a
+     * session that had no entries yet — not a fallback for an anchor that could not be found.
+     */
+    readonly anchorUuid: string | null;
+    /**
+     * Text the delivered entry must carry.
+     *
+     * Optional, and stronger than the position alone. Without it the receipt answers "a user turn
+     * arrived after my anchor", which is true of any user turn — including one a different writer
+     * queued. With it the receipt answers "my text arrived". A controller driving one session at a
+     * time can omit it; anything with two writers should not.
+     */
+    readonly expectText?: string;
+}
+/** What the transcript says happened. */
+export interface ReceiptOutcome {
+    /** Whether a qualifying user entry arrived after the anchor. */
+    readonly delivered: boolean;
+    /** The uuid of the entry that satisfied it, when one did. */
+    readonly entryUuid: string | null;
+    /** That entry's own timestamp, when it carries one. */
+    readonly at: string | null;
+    /**
+     * Whether a compaction sits between the anchor and now.
+     *
+     * Reported rather than hidden because it is the fact that makes this receipt trustworthy: a
+     * `true` here on a `delivered: true` receipt is the observation that the read survived the
+     * boundary. It is also what lets a reader tell a genuinely quiet session apart from one whose
+     * history was just rewritten underneath it.
+     */
+    readonly crossedCompaction: boolean;
+    /** How many entries were examined after the anchor. Diagnostic; never a receipt on its own. */
+    readonly scannedAfterAnchor: number;
+}
+/**
+ * Resolve a delivery receipt against raw stored entries.
+ *
+ * An unfindable anchor is a refusal, not a negative receipt — and this is the single most
+ * important line in the file. Three situations exist: the text landed, the text did not land, and
+ * the question cannot be evaluated. Collapsing the third into the second is what makes the failure
+ * invisible: a controller reading a false "no" pastes the text again, and a double-paste is the
+ * exact production symptom this read path exists to prevent. So it refuses by name and the caller
+ * has to decide what to do about not knowing.
+ *
+ * @param entries Raw entries in append order — `store.load(key)` or the local JSONL. Not a
+ *                reconstructed conversation: see Defence 1 in this file's header.
+ */
+export declare function resolveReceipt(entries: readonly TranscriptEntry[], query: ReceiptQuery): Result<ReceiptOutcome>;
+/**
+ * The uuid a controller should hold as its next baseline — the last entry currently stored.
+ *
+ * Null for an empty transcript, which is the one case where a query may honestly carry a null
+ * anchor. Entries without a uuid are skipped: an anchor has to be addressable, and the contract
+ * says some entry kinds legitimately carry none.
+ */
+export declare function baselineAnchor(entries: readonly TranscriptEntry[]): string | null;
+/** How many compactions this transcript records. For observability, not for the receipt. */
+export declare function compactionCount(entries: readonly TranscriptEntry[]): number;
+//# sourceMappingURL=receipt.d.ts.map

package/dist/persistence/receipt.js

@@ -0,0 +1,85 @@
+import { ok, refuse } from '../core/result.js';
+import { isCompactBoundary, isCompactionProduced, isUserEntry } from './entry.js';
+/**
+ * Resolve a delivery receipt against raw stored entries.
+ *
+ * An unfindable anchor is a refusal, not a negative receipt — and this is the single most
+ * important line in the file. Three situations exist: the text landed, the text did not land, and
+ * the question cannot be evaluated. Collapsing the third into the second is what makes the failure
+ * invisible: a controller reading a false "no" pastes the text again, and a double-paste is the
+ * exact production symptom this read path exists to prevent. So it refuses by name and the caller
+ * has to decide what to do about not knowing.
+ *
+ * @param entries Raw entries in append order — `store.load(key)` or the local JSONL. Not a
+ *                reconstructed conversation: see Defence 1 in this file's header.
+ */
+export function resolveReceipt(entries, query) {
+    // Defence 2: the anchor is located by identity. Nothing here counts.
+    const anchorIndex = query.anchorUuid === null ? -1 : entries.findIndex((entry) => entry.uuid === query.anchorUuid);
+    if (query.anchorUuid !== null && anchorIndex === -1) {
+        return refuse('receipt-anchor-unknown', `no entry carries the baseline uuid ${query.anchorUuid} in ${entries.length} stored entries — ` +
+            'the receipt cannot be evaluated, which is not the same as the text not arriving');
+    }
+    const after = entries.slice(anchorIndex + 1);
+    const crossedCompaction = after.some(isCompactBoundary);
+    for (const entry of after) {
+        // Defence 3: a compaction's own output is never a candidate, however much it looks like a turn.
+        if (isCompactionProduced(entry))
+            continue;
+        if (!isUserEntry(entry))
+            continue;
+        if (query.expectText !== undefined && !entryCarriesText(entry, query.expectText))
+            continue;
+        return ok({
+            delivered: true,
+            entryUuid: entry.uuid ?? null,
+            at: entry.timestamp ?? null,
+            crossedCompaction,
+            scannedAfterAnchor: after.length,
+        });
+    }
+    return ok({
+        delivered: false,
+        entryUuid: null,
+        at: null,
+        crossedCompaction,
+        scannedAfterAnchor: after.length,
+    });
+}
+/**
+ * The uuid a controller should hold as its next baseline — the last entry currently stored.
+ *
+ * Null for an empty transcript, which is the one case where a query may honestly carry a null
+ * anchor. Entries without a uuid are skipped: an anchor has to be addressable, and the contract
+ * says some entry kinds legitimately carry none.
+ */
+export function baselineAnchor(entries) {
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const uuid = entries[index]?.uuid;
+        if (typeof uuid === 'string' && uuid.length > 0)
+            return uuid;
+    }
+    return null;
+}
+/** How many compactions this transcript records. For observability, not for the receipt. */
+export function compactionCount(entries) {
+    return entries.filter(isCompactBoundary).length;
+}
+/**
+ * Whether an entry's payload carries this text anywhere in it.
+ *
+ * A structural search, not a content model. A user entry's `message` is the CLI's own shape and
+ * this package does not model it, so the text is looked for across the serialised payload rather
+ * than at a path this file would have to keep in step with a format it does not own.
+ */
+function entryCarriesText(entry, text) {
+    if (text.length === 0)
+        return true;
+    try {
+        return JSON.stringify(entry).includes(text);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=receipt.js.map

package/dist/persistence/retention.d.ts

@@ -0,0 +1,68 @@
+/**
+ * How long stored entries are kept — and why this file exists at all.
+ *
+ * The SDK never deletes from your store. Its adapter contract says so in as many words and hands
+ * retention to the adapter, naming TTLs and lifecycle policies as the adapter's job. So a compliance
+ * window is not something this host inherits — it is something it must implement, and a package that
+ * shipped without one would quietly keep every transcript forever.
+ *
+ * This is a plan, not a deletion. It returns what would go and what would stay; something in
+ * `host/` performs it. That is what makes "retention removes what it claims to" measurable before
+ * and after by a plain unit test instead of by deleting real files and hoping.
+ *
+ * It does not contradict the append-only log, and the distinction is exact. Append-only forbids
+ * editing or selectively erasing a record — rewriting an abandoned entry to look closed, dropping
+ * an inconvenient refusal. Retention drops whole entries once they age out of a stated window,
+ * uniformly and by a rule announced in advance. The first destroys a signal while keeping its
+ * neighbours, which makes the remaining record misleading; the second removes the record and
+ * says so.
+ */
+import type { Result } from '../core/result.js';
+import type { TranscriptEntry } from './entry.js';
+export interface RetentionPolicy {
+    /** Entries older than this go. Must be a finite, non-negative number of milliseconds. */
+    readonly maxAgeMs: number;
+}
+export interface RetentionPlan {
+    readonly keep: readonly TranscriptEntry[];
+    readonly remove: readonly TranscriptEntry[];
+    /**
+     * Entries kept only because they carry no readable timestamp.
+     *
+     * Surfaced rather than folded into `keep`, because it is the number that says whether this
+     * policy is actually doing what its window claims. A store full of undated entries is one where
+     * retention is silently a no-op, and that is a thing an operator must be able to see.
+     */
+    readonly undatedKept: number;
+}
+/**
+ * What this policy would remove, given the time now.
+ *
+ * An entry that cannot be dated is kept. Deleting on a guess is worse than keeping too much: an
+ * unparseable or absent timestamp means the age is unknown, and treating unknown as old would delete
+ * exactly the malformed records somebody needs to look at. It errs toward keeping, and reports how
+ * often it did.
+ */
+export declare function planRetention(entries: readonly TranscriptEntry[], policy: RetentionPolicy, nowMs: number): Result<RetentionPlan>;
+/**
+ * One entry's time, in epoch milliseconds, or null when it has none this can read.
+ *
+ * Exported because the retention plan's honesty depends on it: a caller that wants to know whether a
+ * store is datable at all asks this rather than inferring it from a plan that kept everything.
+ */
+export declare function entryTimeMs(entry: TranscriptEntry): number | null;
+/**
+ * Why an abandonment mark can never be orphaned by this policy, stated because the pairing is the
+ * one thing retention could destroy while looking correct.
+ *
+ * A mark is written strictly after the entry it refers to — it records that an already-open entry
+ * was later found abandoned. An age window removes oldest-first, so the only orderings it can
+ * produce are "both kept", "both removed", or "the older subject removed while the newer mark
+ * stays". The dangerous fourth — the mark removed while the subject stays, leaving an abandoned
+ * entry reading as merely still-open — is unreachable, because that requires the mark to be older
+ * than its subject.
+ *
+ * This function is the assertion of that, so the property is checked rather than reasoned about.
+ */
+export declare function markOutlivesSubject(subjectAtMs: number, markAtMs: number, cutoffMs: number): boolean;
+//# sourceMappingURL=retention.d.ts.map

package/dist/persistence/retention.js

@@ -0,0 +1,68 @@
+import { ok, refuse } from '../core/result.js';
+/**
+ * What this policy would remove, given the time now.
+ *
+ * An entry that cannot be dated is kept. Deleting on a guess is worse than keeping too much: an
+ * unparseable or absent timestamp means the age is unknown, and treating unknown as old would delete
+ * exactly the malformed records somebody needs to look at. It errs toward keeping, and reports how
+ * often it did.
+ */
+export function planRetention(entries, policy, nowMs) {
+    if (!Number.isFinite(policy.maxAgeMs) || policy.maxAgeMs < 0) {
+        return refuse('retention-window-invalid', `maxAgeMs must be a finite, non-negative number of milliseconds, got ${String(policy.maxAgeMs)}`);
+    }
+    if (!Number.isFinite(nowMs)) {
+        return refuse('retention-window-invalid', `now must be a finite epoch value, got ${String(nowMs)}`);
+    }
+    const cutoff = nowMs - policy.maxAgeMs;
+    const keep = [];
+    const remove = [];
+    let undatedKept = 0;
+    for (const entry of entries) {
+        const at = entryTimeMs(entry);
+        if (at === null) {
+            keep.push(entry);
+            undatedKept += 1;
+            continue;
+        }
+        if (at < cutoff)
+            remove.push(entry);
+        else
+            keep.push(entry);
+    }
+    return ok({ keep, remove, undatedKept });
+}
+/**
+ * One entry's time, in epoch milliseconds, or null when it has none this can read.
+ *
+ * Exported because the retention plan's honesty depends on it: a caller that wants to know whether a
+ * store is datable at all asks this rather than inferring it from a plan that kept everything.
+ */
+export function entryTimeMs(entry) {
+    const timestamp = entry.timestamp;
+    if (typeof timestamp !== 'string' || timestamp.length === 0)
+        return null;
+    const parsed = Date.parse(timestamp);
+    return Number.isNaN(parsed) ? null : parsed;
+}
+/**
+ * Why an abandonment mark can never be orphaned by this policy, stated because the pairing is the
+ * one thing retention could destroy while looking correct.
+ *
+ * A mark is written strictly after the entry it refers to — it records that an already-open entry
+ * was later found abandoned. An age window removes oldest-first, so the only orderings it can
+ * produce are "both kept", "both removed", or "the older subject removed while the newer mark
+ * stays". The dangerous fourth — the mark removed while the subject stays, leaving an abandoned
+ * entry reading as merely still-open — is unreachable, because that requires the mark to be older
+ * than its subject.
+ *
+ * This function is the assertion of that, so the property is checked rather than reasoned about.
+ */
+export function markOutlivesSubject(subjectAtMs, markAtMs, cutoffMs) {
+    if (markAtMs < subjectAtMs)
+        return false;
+    const subjectKept = subjectAtMs >= cutoffMs;
+    const markKept = markAtMs >= cutoffMs;
+    return !(subjectKept && !markKept);
+}
+//# sourceMappingURL=retention.js.map

package/dist/persistence/store.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Where transcripts are kept — the seam, and the JSONL implementation that ships.
+ *
+ * The store is the embedder's, the same way the workspace provider is. One implementation ships
+ * because everyone needs a local one; the interesting ones — S3, Postgres, a blob container behind
+ * a tenant boundary — are the embedder's and are written against this interface without ever
+ * learning what a session means. The effects are injected for the same reason they are there: the
+ * rules worth testing are which key becomes which record and what a missing transcript returns, and
+ * none of that needs a disk.
+ *
+ * This is not the sole record, by the SDK's design and not by this package's. The subprocess
+ * writes to local disk first and the mirror runs after that write succeeds, so local disk is
+ * authoritative and a store can legitimately lag it. The adapter contract also forbids turning
+ * local persistence off while a store is set. Anything reasoning about "what the store has" must
+ * hold that the local copy may be ahead — see `mirror.ts` on dropped batches, which is how it gets
+ * ahead and stays there.
+ *
+ * `listSessionSummaries` is deliberately not part of this interface — a decision, not an omission.
+ * The SDK offers a summary side-file a store can maintain inside `append()`, and it is declined
+ * here for three reasons. Its payload is documented as opaque SDK-owned state a store must persist
+ * verbatim and must not interpret, so it yields nothing this host could put on the wire;
+ * maintaining it requires serialising side-file writes behind a per-session lock on a path that
+ * receives batches at roughly ten a second; and it optimises a read path this host does not use.
+ * The underlying requirement — parse at the edge, ship summaries rather than transcripts — is met
+ * instead by `receipt.ts` and `transition-log.ts`, which answer the questions a controller actually
+ * asks without sending it a transcript. The adapter contract marks the method optional, so
+ * declining it is a supported posture rather than a gap.
+ */
+import type { Result } from '../core/result.js';
+import type { TranscriptEntry } from './entry.js';
+import type { TranscriptKey } from './key.js';
+/** One stored session, as a listing reports it. */
+export interface StoredSession {
+    readonly sessionId: string;
+    /** Storage write time, epoch milliseconds. The store's own clock, never an entry's timestamp. */
+    readonly mtime: number;
+}
+/**
+ * Where transcripts go.
+ *
+ * `load` returns `null` for a transcript that was never written, and that is distinct from an
+ * empty list. "Never written" and "written and then emptied" are different facts, and a store that
+ * cannot tell them apart is allowed to say `null` for both — but it may not report either as an
+ * empty transcript, because a resume reading an empty list would start a session claiming it had
+ * checked and found no history.
+ */
+export interface TranscriptStore {
+    /** Mirror a batch. Idempotent on `uuid` — see mirror.ts. */
+    append(key: TranscriptKey, entries: readonly TranscriptEntry[]): Promise<Result<void>>;
+    /** Everything stored for this key, or null when nothing ever was. */
+    load(key: TranscriptKey): Promise<Result<TranscriptEntry[] | null>>;
+    /** Sessions under one project scope. Optional — a store may not be able to enumerate. */
+    listSessions?(projectKey: string): Promise<Result<StoredSession[]>>;
+    /**
+     * Remove a transcript.
+     *
+     * Optional, and absent means "deletion is a no-op" rather than "deletion fails". That is the
+     * adapter contract's own shape and it is the right one for append-only backends: a write-once
+     * bucket cannot delete, and pretending otherwise would make retention look like it ran.
+     */
+    delete?(key: TranscriptKey): Promise<Result<void>>;
+    /** Subagent transcripts under one session, so a resume can materialise them too. */
+    listSubkeys?(key: TranscriptKey): Promise<Result<string[]>>;
+}
+/**
+ * The storage effects a JSONL store needs, injected.
+ *
+ * Same rule as everywhere else: `src/host/` is the only directory that may touch a filesystem, so
+ * the logic lives here and the real implementation is host-side.
+ */
+export interface StoreEffects {
+    /** Append text to a record, creating it and any container it needs. */
+    appendTo(token: string, text: string): Promise<void>;
+    /** The whole record's text, or null when it does not exist. */
+    readAll(token: string): Promise<string | null>;
+    /** Tokens under one project scope, with their storage write times. */
+    list(projectKey: string): Promise<readonly {
+        token: string;
+        sessionId: string;
+        mtime: number;
+    }[]>;
+    /** Remove one record. Succeeds when it is already gone. */
+    remove(token: string): Promise<void>;
+    /** Subpath tokens under one session. */
+    subkeys(projectKey: string, sessionId: string): Promise<readonly string[]>;
+}
+/**
+ * A store that keeps each transcript as JSONL, one line per entry.
+ *
+ * Append is a real append, not a read-modify-write of the whole file. A transcript reaches
+ * megabytes and batches arrive throughout a turn, so rewriting it per batch would make cost grow
+ * with the square of the session's length. The one place that does read first is deduplication,
+ * which is why `dedupeOnAppend` can be turned off for a caller that knows its batches are unique.
+ */
+export declare function createJsonlStore(effects: StoreEffects, options?: JsonlStoreOptions): TranscriptStore;
+export interface JsonlStoreOptions {
+    /**
+     * Read before appending so a replayed batch does not duplicate. Defaults to true.
+     *
+     * Turning it off is a real choice with a named cost. It removes a full read per batch, which
+     * matters on a long transcript; what it costs is that a retried or re-imported batch lands twice,
+     * and nothing downstream can tell a duplicated entry from a repeated one.
+     */
+    readonly dedupeOnAppend?: boolean;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/persistence/store.js

@@ -0,0 +1,86 @@
+import { ok, refuse } from '../core/result.js';
+import { decodeTranscript, encodeTranscript } from './entry.js';
+import { transcriptToken } from './key.js';
+import { dedupeBatch, uuidsIn } from './mirror.js';
+/**
+ * A store that keeps each transcript as JSONL, one line per entry.
+ *
+ * Append is a real append, not a read-modify-write of the whole file. A transcript reaches
+ * megabytes and batches arrive throughout a turn, so rewriting it per batch would make cost grow
+ * with the square of the session's length. The one place that does read first is deduplication,
+ * which is why `dedupeOnAppend` can be turned off for a caller that knows its batches are unique.
+ */
+export function createJsonlStore(effects, options = {}) {
+    const dedupe = options.dedupeOnAppend ?? true;
+    return {
+        async append(key, entries) {
+            if (entries.length === 0)
+                return ok(undefined);
+            const token = transcriptToken(key);
+            let toWrite = entries;
+            if (dedupe) {
+                const existing = await readEntries(effects, token);
+                if (!existing.ok)
+                    return refuse(existing.refusal.reason, existing.refusal.detail);
+                toWrite = dedupeBatch(uuidsIn(existing.value ?? []), entries).append;
+                if (toWrite.length === 0)
+                    return ok(undefined);
+            }
+            try {
+                await effects.appendTo(token, `${encodeTranscript(toWrite)}\n`);
+                return ok(undefined);
+            }
+            catch (error) {
+                return refuse('transcript-write-failed', `${token}: ${messageOf(error)}`);
+            }
+        },
+        async load(key) {
+            return readEntries(effects, transcriptToken(key));
+        },
+        async listSessions(projectKey) {
+            try {
+                const found = await effects.list(projectKey);
+                return ok(found.map((one) => ({ sessionId: one.sessionId, mtime: one.mtime })));
+            }
+            catch (error) {
+                return refuse('transcript-read-failed', `${projectKey}: ${messageOf(error)}`);
+            }
+        },
+        async delete(key) {
+            try {
+                await effects.remove(transcriptToken(key));
+                return ok(undefined);
+            }
+            catch (error) {
+                return refuse('transcript-write-failed', `${transcriptToken(key)}: ${messageOf(error)}`);
+            }
+        },
+        async listSubkeys(key) {
+            try {
+                return ok([...(await effects.subkeys(key.projectKey, key.sessionId))]);
+            }
+            catch (error) {
+                return refuse('transcript-read-failed', `${transcriptToken(key)}: ${messageOf(error)}`);
+            }
+        },
+    };
+}
+async function readEntries(effects, token) {
+    let text;
+    try {
+        text = await effects.readAll(token);
+    }
+    catch (error) {
+        return refuse('transcript-read-failed', `${token}: ${messageOf(error)}`);
+    }
+    if (text === null)
+        return ok(null);
+    const decoded = decodeTranscript(text);
+    if (!decoded.ok)
+        return refuse(decoded.refusal.reason, `${token}: ${decoded.refusal.detail}`);
+    return ok(decoded.value);
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=store.js.map