@inixiative/archive 0.2.0

package/src/config.ts

@@ -0,0 +1,80 @@
+import { randomUUID } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { z } from 'zod';
+
+const common = {
+  projectId: z.string().min(1).max(256),
+  url: z.url(),
+  tokenEnv: z.string().regex(/^[A-Z][A-Z0-9_]+$/),
+};
+export const archiveDestinationSchema = z.union([
+  z.strictObject({
+    ...common,
+    kind: z.literal('archive'),
+    keepIds: z.array(z.string()).max(0).default([]),
+  }),
+  z.strictObject({
+    ...common,
+    kind: z.literal('kingdom').optional(),
+    kastleId: z.uuid(),
+    keepIds: z.array(z.uuid()).max(50).default([]),
+  }),
+]);
+export type ArchiveDestination = z.infer<typeof archiveDestinationSchema>;
+
+export function destinationUrl(input: string) {
+  const url = new URL(input);
+  if (
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    (url.protocol !== 'https:' &&
+      !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)))
+  )
+    throw new Error('Archive destination requires HTTPS or loopback HTTP and no URL credentials');
+  if (!url.pathname.endsWith('/')) url.pathname += '/';
+  return url;
+}
+
+export function readDestinations(file: string): ArchiveDestination[] {
+  return existsSync(file)
+    ? z
+        .array(archiveDestinationSchema)
+        .max(100)
+        .parse(JSON.parse(readFileSync(file, 'utf8')))
+    : [];
+}
+export function destinationIdentity(destination: ArchiveDestination) {
+  const url = destinationUrl(destination.url);
+  // Preserve existing Foundry/Kingdom upload receipt identities.
+  return JSON.stringify([
+    url.origin,
+    new URL(destination.url).pathname,
+    destination.kind === 'archive' ? 'standalone' : destination.kastleId,
+  ]);
+}
+export function connectDestination(file: string, input: unknown) {
+  const destination = archiveDestinationSchema.parse(input);
+  destination.url = destinationUrl(destination.url).href;
+  const destinations = readDestinations(file);
+  const identity = destinationIdentity(destination);
+  const index = destinations.findIndex(
+    (item) => item.projectId === destination.projectId && destinationIdentity(item) === identity,
+  );
+  if (index < 0) destinations.push(destination);
+  else destinations[index] = destination;
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+  const temp = `${file}.${randomUUID()}.tmp`;
+  writeFileSync(temp, JSON.stringify(destinations, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
+  renameSync(temp, file);
+  chmodSync(file, 0o600);
+  return {
+    configured: true,
+    kind: destination.kind ?? 'kingdom',
+    projectId: destination.projectId,
+    url: destination.url,
+    tokenEnv: destination.tokenEnv,
+  };
+}

package/src/import-file.ts

@@ -0,0 +1,45 @@
+import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
+import { type ImportOptions, importTranscriptLines } from './import';
+
+/** Bound raw record memory while skipping unsupported payloads from long native histories. */
+export function importTranscriptFile(file: string, options: ImportOptions) {
+  function* lines() {
+    const descriptor = openSync(file, 'r');
+    try {
+      const stat = fstatSync(descriptor);
+      if (!stat.isFile() || stat.size > 1_000_000_000)
+        throw new Error('Import requires a transcript file no larger than 1 GB');
+      const buffer = Buffer.alloc(64 * 1024);
+      const decoder = new TextDecoder('utf-8', { fatal: true });
+      let pending = '',
+        bytes = 0;
+      while (true) {
+        const count = readSync(descriptor, buffer, 0, buffer.length, null);
+        bytes += count;
+        if (bytes > 1_000_000_000) throw new Error('Transcript grew beyond the 1 GB import limit');
+        pending += count
+          ? decoder.decode(buffer.subarray(0, count), { stream: true })
+          : decoder.decode();
+        let start = 0;
+        let newline = pending.indexOf('\n', start);
+        while (newline >= 0) {
+          if (newline - start > 64_000_000)
+            throw new Error('Transcript record exceeds the 64 million character limit');
+          yield pending.slice(start, newline);
+          start = newline + 1;
+          newline = pending.indexOf('\n', start);
+        }
+        pending = pending.slice(start);
+        if (pending.length > 64_000_000)
+          throw new Error('Transcript record exceeds the 64 million character limit');
+        if (!count) {
+          if (pending) yield pending;
+          break;
+        }
+      }
+    } finally {
+      closeSync(descriptor);
+    }
+  }
+  return importTranscriptLines(lines(), options);
+}

package/src/import.ts

@@ -0,0 +1,173 @@
+import { type ArchiveEntry, type ArchiveSnapshot, archiveSnapshotSchema } from './index';
+
+export interface ImportOptions {
+  source: 'codex' | 'claude-code';
+  sourceId: string;
+  sessionId?: string;
+  title?: string;
+  projectId?: string;
+}
+export function importTranscript(text: string, options: ImportOptions): ArchiveSnapshot {
+  return importTranscriptLines(text.split('\n'), options);
+}
+export function importTranscriptLines(
+  lines: Iterable<string>,
+  options: ImportOptions,
+): ArchiveSnapshot {
+  const entries: ArchiveEntry[] = [];
+  const omissions = new Set<string>();
+  let sessionId = options.sessionId;
+  let reasoning = false;
+  const seen = new Map<string, string>();
+  let index = -1;
+  let contentBytes = 0;
+  for (const rawLine of lines) {
+    index++;
+    const line = rawLine.trim();
+    if (!line) continue;
+    let row: any;
+    try {
+      row = JSON.parse(line);
+    } catch {
+      throw new Error(`Invalid transcript JSON at line ${index + 1}; no archive imported`);
+    }
+    if (!row || typeof row !== 'object' || Array.isArray(row))
+      throw new Error(`Invalid transcript record at line ${index + 1}`);
+    if (options.source === 'codex' && row.type === 'session_meta') {
+      const id = row.payload?.id;
+      if (sessionId && id && id !== sessionId)
+        throw new Error('Transcript session identity mismatch');
+      sessionId ??= id;
+    }
+    if (options.source === 'claude-code' && row.sessionId) {
+      if (sessionId && sessionId !== row.sessionId) throw new Error('Mixed transcript sessions');
+      sessionId = row.sessionId;
+    }
+    const timestamp = typeof row.timestamp === 'number' ? row.timestamp : Date.parse(row.timestamp);
+    const add = (kind: ArchiveEntry['kind'], content: unknown, suffix: string, callId?: string) => {
+      if (typeof content !== 'string' || !content.length) return;
+      const id = `${row.uuid ?? row.payload?.id ?? `line-${index + 1}`}:${suffix}`;
+      const identity = JSON.stringify([kind, content, callId]);
+      if (seen.has(id)) {
+        if (seen.get(id) !== identity)
+          throw new Error(`Conflicting transcript record at line ${index + 1}`);
+        return;
+      }
+      contentBytes += Buffer.byteLength(content);
+      if (contentBytes > 64_000_000 || entries.length >= 50_000 || content.length > 2_000_000)
+        throw new Error(
+          'Supported transcript content exceeds the archive size limit; no archive imported',
+        );
+      seen.set(id, identity);
+      entries.push({
+        id,
+        kind,
+        text: content,
+        timestamp: Number.isFinite(timestamp) ? timestamp : null,
+        sourceRef: `line:${index + 1}`,
+        ...(callId ? { callId } : {}),
+      });
+    };
+    if (options.source === 'codex') {
+      if (row.type === 'response_item') {
+        const p = row.payload ?? {};
+        if (p.type === 'message' && ['user', 'assistant'].includes(p.role)) {
+          for (const [i, block] of (p.content ?? []).entries()) {
+            if (['input_text', 'output_text', 'text'].includes(block.type))
+              add(p.role, block.text, `text-${i}`);
+            else omissions.add('Non-text message content is not included');
+          }
+        } else if (['function_call', 'custom_tool_call'].includes(p.type)) {
+          add(
+            'tool-call',
+            JSON.stringify({ name: p.name, arguments: p.arguments ?? p.input }),
+            'call',
+            p.call_id,
+          );
+        } else if (['function_call_output', 'custom_tool_call_output'].includes(p.type)) {
+          const output =
+            typeof p.output === 'string'
+              ? p.output
+              : Array.isArray(p.output)
+                ? p.output
+                    .filter((block: any) =>
+                      ['text', 'input_text', 'output_text'].includes(block.type),
+                    )
+                    .map((block: any) => block.text)
+                    .join('\n')
+                : '';
+          if (typeof p.output !== 'string')
+            omissions.add('Only text tool output blocks are included');
+          add('tool-result', output, 'result', p.call_id);
+        } else if (p.type === 'reasoning') {
+          for (const [i, block] of (p.summary ?? []).entries()) {
+            if (typeof block.text === 'string') {
+              add('reasoning-summary', block.text, `summary-${i}`);
+              reasoning = true;
+            }
+          }
+          omissions.add('Private reasoning and encrypted payloads are not included');
+        }
+      }
+    } else if (['user', 'assistant'].includes(row.type) && row.message) {
+      const blocks = row.message.content;
+      if (typeof blocks === 'string') add(row.type, blocks, 'text');
+      else if (Array.isArray(blocks))
+        for (const [i, block] of blocks.entries()) {
+          if (block.type === 'text') add(row.type, block.text, `text-${i}`);
+          else if (block.type === 'tool_use')
+            add(
+              'tool-call',
+              JSON.stringify({ name: block.name, input: block.input }),
+              `call-${i}`,
+              block.id,
+            );
+          else if (block.type === 'tool_result') {
+            const output =
+              typeof block.content === 'string'
+                ? block.content
+                : Array.isArray(block.content)
+                  ? block.content
+                      .filter((b: any) => b.type === 'text')
+                      .map((b: any) => b.text)
+                      .join('\n')
+                  : '';
+            add('tool-result', output, `result-${i}`, block.tool_use_id);
+            if (Array.isArray(block.content) && block.content.some((b: any) => b.type !== 'text'))
+              omissions.add('Non-text tool content is not included');
+          } else if (['thinking', 'redacted_thinking'].includes(block.type))
+            omissions.add('Private reasoning is not included');
+          else omissions.add('Non-text message content is not included');
+        }
+    }
+  }
+  if (!sessionId || !entries.length)
+    throw new Error('Transcript must identify a session and contain supported records');
+  const firstPrompt = entries.find(
+    (entry) =>
+      entry.kind === 'user' &&
+      !/^<(?:recommended_plugins|environment_context|user_instructions|permissions)(?:>|\s)/.test(
+        entry.text.trimStart(),
+      ),
+  );
+  const title = options.title ?? firstPrompt?.text.slice(0, 160) ?? sessionId;
+  return archiveSnapshotSchema.parse({
+    schemaVersion: 1,
+    sourceId: options.sourceId,
+    source: options.source,
+    sessionId,
+    title,
+    projectId: options.projectId,
+    tags: [],
+    capturedAt: Date.now(),
+    coverage: {
+      reasoning: reasoning ? 'summaries-only' : 'unavailable',
+      completeness: 'partial',
+      omissions: [
+        'Import contains public transcript records only; source history may be incomplete',
+        ...omissions,
+      ],
+    },
+    entries,
+  });
+}

package/src/index.ts

@@ -0,0 +1,172 @@
+import { createHash } from 'node:crypto';
+import { getEncoding } from 'js-tiktoken';
+import { z } from 'zod';
+
+const identifier = z.string().min(1).max(256);
+export const archiveEntrySchema = z.strictObject({
+  id: identifier,
+  turnId: identifier.optional(),
+  callId: identifier.optional(),
+  kind: z.enum(['user', 'assistant', 'tool-call', 'tool-result', 'reasoning-summary', 'event']),
+  text: z.string().max(2_000_000),
+  timestamp: z.number().finite().nonnegative().nullable(),
+  sourceRef: z.string().min(1).max(512),
+});
+export const archiveSnapshotSchema = z
+  .strictObject({
+    schemaVersion: z.literal(1),
+    sourceId: z.uuid(),
+    source: z.enum(['foundry', 'claude-code', 'codex']),
+    sessionId: identifier,
+    title: z.string().min(1).max(500),
+    projectId: identifier.optional(),
+    tags: z.array(z.string().min(1).max(120)).max(100),
+    goalIds: z.array(identifier).max(100).default([]),
+    runIds: z.array(identifier).max(100).default([]),
+    capturedAt: z.number().finite().nonnegative(),
+    coverage: z.strictObject({
+      reasoning: z.enum(['unavailable', 'summaries-only']),
+      completeness: z.enum(['recorded', 'partial']),
+      omissions: z.array(z.string().max(500)).max(100),
+    }),
+    entries: z.array(archiveEntrySchema).max(50_000),
+  })
+  .superRefine((value, ctx) => {
+    if (new Set(value.entries.map((entry) => entry.id)).size !== value.entries.length)
+      ctx.addIssue({ code: 'custom', message: 'Duplicate archive entry identities' });
+    if (Buffer.byteLength(JSON.stringify(value)) > 64_000_000)
+      ctx.addIssue({ code: 'custom', message: 'Archive exceeds 64 MB' });
+  });
+export type ArchiveSnapshot = z.infer<typeof archiveSnapshotSchema>;
+export type ArchiveEntry = z.infer<typeof archiveEntrySchema>;
+export interface ArchiveChunk {
+  id: string;
+  entryId: string;
+  sourceRef: string;
+  kind: ArchiveEntry['kind'];
+  start: number;
+  end: number;
+  text: string;
+  tokenCount: number;
+  encoding: 'cl100k_base';
+}
+let encoding: ReturnType<typeof getEncoding> | undefined;
+export const tokenCount = (text: string) => {
+  encoding ??= getEncoding('cl100k_base');
+  return encoding.encode(text, [], []).length;
+};
+export const digest = (text: string) => createHash('sha256').update(text).digest('hex');
+export const archiveKey = (snapshot: Pick<ArchiveSnapshot, 'sourceId' | 'source' | 'sessionId'>) =>
+  digest(JSON.stringify([snapshot.sourceId, snapshot.source, snapshot.sessionId]));
+export const snapshotDigest = (snapshot: ArchiveSnapshot) => {
+  const { capturedAt: _, ...content } = snapshot;
+  return digest(JSON.stringify(content));
+};
+
+export function chunkArchive(snapshot: ArchiveSnapshot, budget = 512): ArchiveChunk[] {
+  if (!Number.isInteger(budget) || budget < 16 || budget > 8192)
+    throw new Error('Invalid chunk token budget');
+  const chunks: ArchiveChunk[] = [];
+  for (const entry of snapshot.entries) {
+    let start = 0;
+    while (start < entry.text.length) {
+      let end = Math.min(entry.text.length, start + budget * 3);
+      if (end < entry.text.length && /[\uD800-\uDBFF]/.test(entry.text[end - 1])) end--;
+      let text = entry.text.slice(start, end);
+      while (tokenCount(text) > budget) {
+        end = start + Math.max(1, Math.floor((end - start) * 0.8));
+        if (end < entry.text.length && /[\uD800-\uDBFF]/.test(entry.text[end - 1])) end--;
+        text = entry.text.slice(start, end);
+      }
+      chunks.push({
+        id: digest(JSON.stringify([entry.id, start, end, text])),
+        entryId: entry.id,
+        sourceRef: entry.sourceRef,
+        kind: entry.kind,
+        start,
+        end,
+        text,
+        tokenCount: tokenCount(text),
+        encoding: 'cl100k_base',
+      });
+      start = end;
+    }
+  }
+  return chunks;
+}
+
+export function selectChunks(chunks: ArchiveChunk[], query: string, budget = 2048) {
+  if (!Number.isInteger(budget) || budget < 16 || budget > 32768)
+    throw new Error('Invalid context token budget');
+  const terms = [...new Set(query.toLowerCase().match(/[\p{L}\p{N}_-]+/gu) ?? [])].slice(0, 64);
+  const ranked = chunks
+    .map((chunk, index) => ({
+      chunk,
+      index,
+      score: terms.reduce(
+        (score, term) => score + Number(chunk.text.toLowerCase().includes(term)),
+        0,
+      ),
+    }))
+    .filter((item) => !terms.length || item.score > 0)
+    .sort((a, b) => b.score - a.score || a.index - b.index);
+  const selected: ArchiveChunk[] = [];
+  let used = 0;
+  for (const { chunk } of ranked) {
+    const remaining = budget - used;
+    if (remaining < 16) break;
+    if (chunk.tokenCount <= remaining) {
+      selected.push(chunk);
+      used += chunk.tokenCount;
+      continue;
+    }
+    // Return a source-addressable excerpt even when the requested context is smaller than a stored chunk.
+    const lower = chunk.text.toLowerCase();
+    const match =
+      terms
+        .map((term) => lower.indexOf(term))
+        .filter((index) => index >= 0)
+        .sort((a, b) => a - b)[0] ?? 0;
+    let offset = Math.max(0, match - Math.floor(remaining / 4));
+    if (offset > 0 && /[\uDC00-\uDFFF]/.test(chunk.text[offset])) offset--;
+    let end = Math.min(chunk.text.length, offset + remaining * 3);
+    if (end < chunk.text.length && /[\uD800-\uDBFF]/.test(chunk.text[end - 1])) end--;
+    while (tokenCount(chunk.text.slice(offset, end)) > remaining) {
+      end = offset + Math.max(1, Math.floor((end - offset) * 0.8));
+      if (end < chunk.text.length && /[\uD800-\uDBFF]/.test(chunk.text[end - 1])) end--;
+    }
+    const text = chunk.text.slice(offset, end);
+    selected.push({
+      ...chunk,
+      id: digest(JSON.stringify([chunk.entryId, chunk.start + offset, chunk.start + end, text])),
+      start: chunk.start + offset,
+      end: chunk.start + end,
+      text,
+      tokenCount: tokenCount(text),
+    });
+    used += tokenCount(text);
+  }
+  return {
+    chunks: selected,
+    tokenCount: used,
+    encoding: 'cl100k_base' as const,
+    matchingChunks: ranked.length,
+  };
+}
+
+export function categorySuggestions(snapshot: ArchiveSnapshot) {
+  const text = snapshot.entries
+    .filter((entry) => entry.kind === 'user')
+    .map((entry) => entry.text)
+    .join('\n')
+    .toLowerCase();
+  const categories = {
+    debugging: /\b(bug|error|fix|failure|regression)\b/,
+    documentation: /\b(docs|documentation|readme)\b/,
+    testing: /\b(test|tests|verification|qa)\b/,
+    design: /\b(design|architecture|diagram|proposal)\b/,
+  };
+  return Object.entries(categories)
+    .filter(([, pattern]) => pattern.test(text))
+    .map(([tag]) => ({ tag, origin: 'heuristic' as const }));
+}

package/src/local.ts

@@ -0,0 +1,150 @@
+import { Database } from 'bun:sqlite';
+import { randomUUID } from 'node:crypto';
+import { chmodSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import {
+  type ArchiveChunk,
+  type ArchiveSnapshot,
+  archiveKey,
+  archiveSnapshotSchema,
+  categorySuggestions,
+  chunkArchive,
+  selectChunks,
+  snapshotDigest,
+} from './index';
+
+export class LocalArchiveStore {
+  private readonly db: Database;
+  readonly sourceId: string;
+  constructor(path: string) {
+    if (path !== ':memory:') mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    this.db = new Database(path, { create: true });
+    if (path !== ':memory:') chmodSync(path, 0o600);
+    this.db.exec(`PRAGMA foreign_keys=ON; PRAGMA busy_timeout=1000;
+      CREATE TABLE IF NOT EXISTS settings (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS archives (id TEXT PRIMARY KEY, digest TEXT NOT NULL, revision INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS revisions (archive_id TEXT NOT NULL REFERENCES archives(id), revision INTEGER NOT NULL,
+        digest TEXT NOT NULL, snapshot TEXT NOT NULL, chunks TEXT NOT NULL, PRIMARY KEY(archive_id, revision));
+      CREATE TABLE IF NOT EXISTS receipts (archive_id TEXT NOT NULL REFERENCES archives(id), destination TEXT NOT NULL,
+        digest TEXT NOT NULL, PRIMARY KEY(archive_id, destination));
+      CREATE TABLE IF NOT EXISTS outbox (archive_id TEXT NOT NULL REFERENCES archives(id), destination TEXT NOT NULL,
+        pending TEXT NOT NULL, PRIMARY KEY(archive_id, destination));`);
+    this.db.query("INSERT OR IGNORE INTO settings VALUES ('sourceId', ?)").run(randomUUID());
+    this.sourceId = (
+      this.db.query("SELECT value FROM settings WHERE key='sourceId'").get() as { value: string }
+    ).value;
+  }
+  capture(input: unknown) {
+    const snapshot = archiveSnapshotSchema.parse(input);
+    const id = archiveKey(snapshot);
+    const hash = snapshotDigest(snapshot);
+    return this.db.transaction(() => {
+      const old = this.read(id);
+      if (old?.digest === hash) return { id, digest: hash, revision: old.revision, changed: false };
+      if (old && old.snapshot.capturedAt > snapshot.capturedAt)
+        throw new Error('Older capture cannot replace newer archive');
+      const revision = (old?.revision ?? 0) + 1;
+      const chunks = chunkArchive(snapshot);
+      this.db
+        .query(
+          'INSERT INTO archives VALUES (?, ?, ?) ON CONFLICT(id) DO UPDATE SET digest=excluded.digest, revision=excluded.revision',
+        )
+        .run(id, hash, revision);
+      this.db
+        .query('INSERT INTO revisions VALUES (?, ?, ?, ?, ?)')
+        .run(id, revision, hash, JSON.stringify(snapshot), JSON.stringify(chunks));
+      return { id, digest: hash, revision, changed: true };
+    })();
+  }
+  read(
+    id: string,
+    revision?: number,
+  ):
+    | {
+        id: string;
+        revision: number;
+        digest: string;
+        snapshot: ArchiveSnapshot;
+        chunks: ArchiveChunk[];
+      }
+    | undefined {
+    const row = this.db
+      .query(`SELECT r.* FROM revisions r JOIN archives a ON a.id=r.archive_id
+      WHERE a.id=? AND r.revision=COALESCE(?, a.revision)`)
+      .get(id, revision ?? null) as any;
+    return row
+      ? {
+          id,
+          revision: row.revision,
+          digest: row.digest,
+          snapshot: archiveSnapshotSchema.parse(JSON.parse(row.snapshot)),
+          chunks: JSON.parse(row.chunks),
+        }
+      : undefined;
+  }
+  list() {
+    return (
+      this.db.query('SELECT id FROM archives ORDER BY rowid DESC').all() as { id: string }[]
+    ).map(({ id }) => {
+      const archive = this.read(id)!;
+      const { entries, ...snapshot } = archive.snapshot;
+      return {
+        id,
+        revision: archive.revision,
+        digest: archive.digest,
+        ...snapshot,
+        entries: entries.length,
+        suggestedTags: categorySuggestions(archive.snapshot),
+      };
+    });
+  }
+  search(ids: string[], query: string, budget = 2048) {
+    return ids.map((id) => {
+      const archive = this.read(id);
+      if (!archive) throw new Error('Archive unavailable');
+      return {
+        id,
+        revision: archive.revision,
+        digest: archive.digest,
+        ...selectChunks(archive.chunks, query, budget),
+      };
+    });
+  }
+  receipt(id: string, destination: string): string | null {
+    return (
+      (
+        this.db
+          .query('SELECT digest FROM receipts WHERE archive_id=? AND destination=?')
+          .get(id, destination) as { digest: string } | null
+      )?.digest ?? null
+    );
+  }
+  acknowledge(id: string, destination: string, hash: string) {
+    this.db
+      .query(
+        'INSERT INTO receipts VALUES (?, ?, ?) ON CONFLICT(archive_id,destination) DO UPDATE SET digest=excluded.digest',
+      )
+      .run(id, destination, hash);
+  }
+  pending(id: string, destination: string): { revision: number; keepIds: string[] } | null {
+    const row = this.db
+      .query('SELECT pending FROM outbox WHERE archive_id=? AND destination=?')
+      .get(id, destination) as { pending: string } | null;
+    return row ? JSON.parse(row.pending) : null;
+  }
+  enqueue(id: string, destination: string, pending: { revision: number; keepIds: string[] }) {
+    this.db
+      .query('INSERT OR IGNORE INTO outbox VALUES (?, ?, ?)')
+      .run(id, destination, JSON.stringify(pending));
+  }
+  delivered(id: string, destination: string, hash: string, placement: string) {
+    this.db.transaction(() => {
+      this.acknowledge(id, destination, hash);
+      this.acknowledge(id, `${destination}:keeps`, placement);
+      this.db.query('DELETE FROM outbox WHERE archive_id=? AND destination=?').run(id, destination);
+    })();
+  }
+  close() {
+    this.db.close();
+  }
+}

package/src/preview.ts

@@ -0,0 +1,57 @@
+import { lstatSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { importTranscriptFile } from './import-file';
+
+/** Inspect explicit source paths without opening an archive store or publishing data. */
+export function previewImports(path: string, source: 'codex' | 'claude-code', limit = 100) {
+  if (!Number.isInteger(limit) || limit < 1 || limit > 1000)
+    throw new Error('Preview limit must be between 1 and 1000');
+  const files: string[] = [];
+  let truncated = false;
+  const visit = (candidate: string) => {
+    if (files.length > limit) {
+      truncated = true;
+      return;
+    }
+    const stat = lstatSync(candidate);
+    if (stat.isSymbolicLink()) return;
+    if (stat.isDirectory()) {
+      for (const entry of readdirSync(candidate).sort()) {
+        visit(join(candidate, entry));
+        if (files.length > limit) break;
+      }
+    } else if (stat.isFile() && candidate.endsWith('.jsonl')) files.push(candidate);
+  };
+  visit(resolve(path));
+  truncated ||= files.length > limit;
+  const sessions = files.slice(0, limit).map((file) => {
+    try {
+      const snapshot = importTranscriptFile(file, {
+        source,
+        sourceId: '00000000-0000-4000-8000-000000000000',
+      });
+      return {
+        file,
+        status: 'ready' as const,
+        source,
+        sessionId: snapshot.sessionId,
+        title: snapshot.title,
+        entries: snapshot.entries.length,
+        characters: snapshot.entries.reduce((n, entry) => n + entry.text.length, 0),
+        coverage: snapshot.coverage,
+      };
+    } catch (error) {
+      return {
+        file,
+        status: 'rejected' as const,
+        error: error instanceof Error ? error.message : 'Unable to inspect transcript',
+      };
+    }
+  });
+  return {
+    sessions,
+    truncated,
+    ready: sessions.filter((session) => session.status === 'ready').length,
+    rejected: sessions.filter((session) => session.status === 'rejected').length,
+  };
+}