fuli-context 0.2.0

package/src/storage/legacy-snapshot-validation.js

@@ -0,0 +1,32 @@
+import { validateLegacyRecords } from './legacy-record-validation.js';
+
+const REQUIRED_COLLECTIONS = ['spaces', 'subscriptions', 'episodes', 'facts', 'candidates'];
+const OPTIONAL_COLLECTIONS = ['outbox', 'imports'];
+
+export function validateLegacySnapshot(snapshot) {
+  if (!isRecord(snapshot)) throw new TypeError('Snapshot must be a JSON object');
+  const collections = requireCollections(snapshot);
+  validateLegacyRecords(collections);
+  return collections;
+}
+
+function requireCollections(snapshot) {
+  const collections = {};
+  for (const name of REQUIRED_COLLECTIONS) collections[name] = requireArray(snapshot, name);
+  for (const name of OPTIONAL_COLLECTIONS) {
+    if (Object.hasOwn(snapshot, name)) collections[name] = requireArray(snapshot, name);
+  }
+  return collections;
+}
+
+function requireArray(snapshot, name) {
+  if (!Array.isArray(snapshot[name])) throw new TypeError(`Snapshot ${name} must be an array`);
+  return snapshot[name].map((record, index) => {
+    if (!isRecord(record)) throw new TypeError(`Snapshot ${name}[${index}] must be an object`);
+    return record;
+  });
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/src/storage/migrate.js

@@ -0,0 +1,128 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { nowIso } from '../models.js';
+import { isFileDatabase } from './sqlite/open-database.js';
+
+const DEFAULT_MIGRATIONS_DIRECTORY = new URL('./migrations/', import.meta.url);
+const CHECKSUM_UPGRADE_MIGRATION = '002-storage-integrity.sql';
+
+export function configureDatabase(db, filePath) {
+  db.pragma('foreign_keys = ON');
+  db.pragma('busy_timeout = 5000');
+  if (isFileDatabase(filePath)) db.pragma('journal_mode = WAL');
+}
+
+export function runMigrations(
+  db,
+  { migrationsDirectory = DEFAULT_MIGRATIONS_DIRECTORY } = {}
+) {
+  db.pragma('foreign_keys = ON');
+  const migrations = discoverMigrations(migrationsDirectory);
+  for (const migration of migrations) {
+    const migrate = db.transaction(() => {
+      const state = appliedMigrations(db);
+      verifyAppliedMigrations(migrations, state.records, {
+        allowMissingChecksums: hasPendingChecksumUpgrade(migrations, state)
+      });
+      if (state.records.has(migration.version)) return;
+      db.exec(migration.sql);
+      recordMigration(db, migration);
+    });
+    migrate.immediate();
+  }
+  verifyAppliedMigrations(migrations, appliedMigrations(db).records);
+}
+
+function discoverMigrations(directory) {
+  const migrations = readdirSync(directory)
+    .filter((name) => name.endsWith('.sql'))
+    .map((name) => {
+      const match = /^(\d+)-.+\.sql$/.exec(name);
+      if (!match) throw new Error(`Invalid migration filename: ${name}`);
+      const sql = readFileSync(migrationPath(directory, name), 'utf8');
+      return {
+        version: Number.parseInt(match[1], 10),
+        name,
+        sql,
+        checksum: createHash('sha256').update(sql).digest('hex')
+      };
+    })
+    .sort((left, right) => left.version - right.version || left.name.localeCompare(right.name));
+
+  for (let index = 1; index < migrations.length; index += 1) {
+    if (migrations[index - 1].version === migrations[index].version) {
+      throw new Error(`Duplicate migration version: ${migrations[index].version}`);
+    }
+  }
+  return migrations;
+}
+
+function appliedMigrations(db) {
+  const columns = db.prepare('PRAGMA table_info(schema_migrations)').all();
+  if (columns.length === 0) return { records: new Map(), supportsChecksums: false };
+
+  const supportsChecksums = columns.some((column) => column.name === 'checksum');
+  const rows = supportsChecksums
+    ? db.prepare(`
+        SELECT version, checksum FROM schema_migrations ORDER BY version
+      `).all()
+    : db.prepare(`
+        SELECT version, NULL AS checksum FROM schema_migrations ORDER BY version
+      `).all();
+  return {
+    records: new Map(rows.map((row) => [row.version, row.checksum])),
+    supportsChecksums
+  };
+}
+
+function verifyAppliedMigrations(
+  migrations,
+  applied,
+  { allowMissingChecksums = false } = {}
+) {
+  const available = new Map(migrations.map((migration) => [migration.version, migration]));
+  for (const [version, checksum] of applied) {
+    const migration = available.get(version);
+    if (!migration) {
+      throw new Error(
+        `Applied migration version ${version} is missing from the migration directory`
+      );
+    }
+    if (checksum === null && allowMissingChecksums) continue;
+    if (checksum === null) {
+      throw new Error(`Applied migration version ${version} is missing a checksum`);
+    }
+    if (migration.checksum !== checksum) {
+      throw new Error(`Migration checksum mismatch for version ${version}`);
+    }
+  }
+}
+
+function hasPendingChecksumUpgrade(migrations, state) {
+  if (state.supportsChecksums) return false;
+  const migration = migrations.find(
+    (candidate) => candidate.name === CHECKSUM_UPGRADE_MIGRATION
+  );
+  return migration !== undefined && !state.records.has(migration.version);
+}
+
+function recordMigration(db, migration) {
+  const supportsChecksums = db.prepare('PRAGMA table_info(schema_migrations)').all()
+    .some((column) => column.name === 'checksum');
+  if (supportsChecksums) {
+    db.prepare(`
+      INSERT INTO schema_migrations (version, checksum, applied_at)
+      VALUES (?, ?, ?)
+    `).run(migration.version, migration.checksum, nowIso());
+    return;
+  }
+  db.prepare(`
+    INSERT INTO schema_migrations (version, applied_at) VALUES (?, ?)
+  `).run(migration.version, nowIso());
+}
+
+function migrationPath(directory, name) {
+  return directory instanceof URL ? new URL(name, directory) : join(directory, name);
+}

package/src/storage/migrations/001-initial.sql

@@ -0,0 +1,83 @@
+PRAGMA foreign_keys = ON;
+
+CREATE TABLE IF NOT EXISTS schema_migrations (
+  version INTEGER PRIMARY KEY,
+  applied_at TEXT NOT NULL
+);
+
+CREATE TABLE spaces (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL UNIQUE,
+  kind TEXT NOT NULL CHECK (kind IN ('personal', 'public')),
+  description TEXT,
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE subscriptions (
+  personal_space_id TEXT NOT NULL REFERENCES spaces(id),
+  space_id TEXT NOT NULL REFERENCES spaces(id),
+  mode TEXT NOT NULL DEFAULT 'latest',
+  created_at TEXT NOT NULL,
+  PRIMARY KEY (personal_space_id, space_id)
+);
+
+CREATE TABLE episodes (
+  id TEXT PRIMARY KEY,
+  space_id TEXT NOT NULL REFERENCES spaces(id),
+  source_kind TEXT NOT NULL,
+  body TEXT NOT NULL,
+  source_uri TEXT,
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE facts (
+  id TEXT PRIMARY KEY,
+  space_id TEXT NOT NULL REFERENCES spaces(id),
+  subject TEXT NOT NULL,
+  predicate TEXT NOT NULL,
+  object TEXT NOT NULL,
+  source_episode_id TEXT NOT NULL REFERENCES episodes(id),
+  status TEXT NOT NULL,
+  confidence REAL NOT NULL DEFAULT 1.0,
+  sensitivity TEXT NOT NULL DEFAULT 'normal',
+  scope TEXT NOT NULL DEFAULT 'personal',
+  valid_at TEXT NOT NULL,
+  invalid_at TEXT,
+  replaced_by_fact_id TEXT REFERENCES facts(id)
+);
+
+CREATE INDEX facts_current_idx ON facts(space_id, predicate, invalid_at);
+CREATE INDEX facts_source_idx ON facts(source_episode_id);
+
+CREATE TABLE candidates (
+  id TEXT PRIMARY KEY,
+  personal_space_id TEXT NOT NULL REFERENCES spaces(id),
+  target_space_id TEXT REFERENCES spaces(id),
+  episode_id TEXT NOT NULL REFERENCES episodes(id),
+  reason TEXT NOT NULL,
+  status TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  decided_at TEXT
+);
+
+CREATE TABLE outbox (
+  id TEXT PRIMARY KEY,
+  kind TEXT NOT NULL,
+  aggregate_id TEXT NOT NULL,
+  payload_json TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending',
+  attempts INTEGER NOT NULL DEFAULT 0,
+  next_attempt_at TEXT,
+  created_at TEXT NOT NULL,
+  sent_at TEXT,
+  last_error TEXT
+);
+
+CREATE INDEX outbox_pending_idx ON outbox(status, next_attempt_at, created_at);
+
+CREATE TABLE imports (
+  content_hash TEXT PRIMARY KEY,
+  source_path TEXT NOT NULL,
+  imported_at TEXT NOT NULL
+);

package/src/storage/migrations/002-storage-integrity.sql

@@ -0,0 +1,113 @@
+CREATE TABLE schema_migrations_new (
+  version INTEGER PRIMARY KEY,
+  checksum TEXT NOT NULL,
+  applied_at TEXT NOT NULL
+);
+
+INSERT INTO schema_migrations_new (version, checksum, applied_at)
+SELECT
+  version,
+  CASE version
+    WHEN 1 THEN 'ab393d736d8ff18fde75478002b2b4b3b4d7e906974cd724058e31436fba0ea9'
+  END,
+  applied_at
+FROM schema_migrations;
+
+DROP TABLE schema_migrations;
+ALTER TABLE schema_migrations_new RENAME TO schema_migrations;
+
+CREATE TABLE facts_new (
+  id TEXT PRIMARY KEY,
+  space_id TEXT NOT NULL REFERENCES spaces(id),
+  subject TEXT NOT NULL,
+  predicate TEXT NOT NULL,
+  object TEXT NOT NULL,
+  source_episode_id TEXT NOT NULL REFERENCES episodes(id),
+  status TEXT NOT NULL CHECK (
+    status IN ('confirmed', 'observed', 'suggested', 'rejected', 'deprecated')
+  ),
+  confidence REAL NOT NULL DEFAULT 1.0 CHECK (
+    typeof(confidence) IN ('integer', 'real') AND confidence >= 0.0 AND confidence <= 1.0
+  ),
+  sensitivity TEXT NOT NULL DEFAULT 'normal' CHECK (
+    sensitivity IN ('normal', 'private', 'restricted')
+  ),
+  scope TEXT NOT NULL DEFAULT 'personal' CHECK (scope IN ('personal', 'public')),
+  valid_at TEXT NOT NULL,
+  invalid_at TEXT,
+  replaced_by_fact_id TEXT REFERENCES facts_new(id)
+);
+
+INSERT INTO facts_new (
+  id, space_id, subject, predicate, object, source_episode_id, status,
+  confidence, sensitivity, scope, valid_at, invalid_at, replaced_by_fact_id
+)
+SELECT
+  id, space_id, subject, predicate, object, source_episode_id, status,
+  confidence, sensitivity, scope, valid_at, invalid_at, NULL
+FROM facts;
+
+UPDATE facts_new
+SET replaced_by_fact_id = (
+  SELECT facts.replaced_by_fact_id
+  FROM facts
+  WHERE facts.id = facts_new.id
+);
+
+DROP TABLE facts;
+ALTER TABLE facts_new RENAME TO facts;
+CREATE INDEX facts_current_idx ON facts(space_id, predicate, invalid_at);
+CREATE INDEX facts_source_idx ON facts(source_episode_id);
+
+CREATE TABLE candidates_new (
+  id TEXT PRIMARY KEY,
+  personal_space_id TEXT NOT NULL REFERENCES spaces(id),
+  target_space_id TEXT REFERENCES spaces(id),
+  episode_id TEXT NOT NULL REFERENCES episodes(id),
+  reason TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (
+    status IN ('pending', 'synced', 'personal_only', 'ignored')
+  ),
+  created_at TEXT NOT NULL,
+  decided_at TEXT
+);
+
+INSERT INTO candidates_new (
+  id, personal_space_id, target_space_id, episode_id, reason,
+  status, created_at, decided_at
+)
+SELECT
+  id, personal_space_id, target_space_id, episode_id, reason,
+  status, created_at, decided_at
+FROM candidates;
+
+DROP TABLE candidates;
+ALTER TABLE candidates_new RENAME TO candidates;
+
+CREATE TABLE outbox_new (
+  id TEXT PRIMARY KEY,
+  kind TEXT NOT NULL,
+  aggregate_id TEXT NOT NULL,
+  payload_json TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'sent')),
+  attempts INTEGER NOT NULL DEFAULT 0 CHECK (
+    typeof(attempts) = 'integer' AND attempts >= 0
+  ),
+  next_attempt_at TEXT,
+  created_at TEXT NOT NULL,
+  sent_at TEXT,
+  last_error TEXT
+);
+
+INSERT INTO outbox_new (
+  id, kind, aggregate_id, payload_json, status, attempts,
+  next_attempt_at, created_at, sent_at, last_error
+)
+SELECT
+  id, kind, aggregate_id, payload_json, status, attempts,
+  next_attempt_at, created_at, sent_at, last_error
+FROM outbox;
+
+DROP TABLE outbox;
+ALTER TABLE outbox_new RENAME TO outbox;
+CREATE INDEX outbox_pending_idx ON outbox(status, next_attempt_at, created_at);

package/src/storage/record-validation.js

@@ -0,0 +1,46 @@
+import { CandidateStatus, FactScope, FactStatus, Sensitivity } from '../models.js';
+
+const FACT_STATUSES = new Set(Object.values(FactStatus));
+const CANDIDATE_STATUSES = new Set(Object.values(CandidateStatus));
+const SENSITIVITIES = new Set(Object.values(Sensitivity));
+const SCOPES = new Set(Object.values(FactScope));
+const OUTBOX_STATUSES = new Set(['pending', 'sent']);
+
+export function validateFactRecord(fact) {
+  requireMember('fact status', fact.status, FACT_STATUSES);
+  if (
+    typeof fact.confidence !== 'number' ||
+    !Number.isFinite(fact.confidence) ||
+    fact.confidence < 0 ||
+    fact.confidence > 1
+  ) {
+    throw new TypeError('Fact confidence must be between 0 and 1');
+  }
+  requireMember('fact sensitivity', fact.sensitivity, SENSITIVITIES);
+  requireMember('fact scope', fact.scope, SCOPES);
+  return fact;
+}
+
+export function validateCandidateRecord(candidate) {
+  requireMember('candidate status', candidate.status, CANDIDATE_STATUSES);
+  return candidate;
+}
+
+export function validateOutboxRecord(entry) {
+  requireMember('outbox status', entry.status, OUTBOX_STATUSES);
+  if (!Number.isInteger(entry.attempts) || entry.attempts < 0) {
+    throw new TypeError('Outbox attempts must be a nonnegative integer');
+  }
+  return entry;
+}
+
+export function validateSnapshotRecords(snapshot) {
+  for (const fact of snapshot.facts) validateFactRecord(fact);
+  for (const candidate of snapshot.candidates) validateCandidateRecord(candidate);
+  for (const entry of snapshot.outbox) validateOutboxRecord(entry);
+  return snapshot;
+}
+
+function requireMember(label, value, allowed) {
+  if (!allowed.has(value)) throw new TypeError(`Invalid ${label}: ${value}`);
+}

package/src/storage/snapshot-defaults.js

@@ -0,0 +1,54 @@
+import { CandidateStatus, FactStatus, nowIso } from '../models.js';
+import { validateSnapshotRecords } from './record-validation.js';
+
+export function normalizeSnapshot(snapshot = {}, { outbox = [], imports = [] } = {}) {
+  const input = cloneSnapshot(snapshot);
+  const normalized = {
+    spaces: (input.spaces ?? []).map((space) => ({
+      ...space,
+      description: space.description ?? null,
+      createdAt: space.createdAt ?? nowIso()
+    })),
+    subscriptions: (input.subscriptions ?? []).map((subscription) => ({
+      ...subscription,
+      mode: subscription.mode ?? 'latest',
+      createdAt: subscription.createdAt ?? nowIso()
+    })),
+    episodes: (input.episodes ?? []).map((episode) => ({
+      ...episode,
+      sourceUri: episode.sourceUri ?? null,
+      metadata: episode.metadata ?? {},
+      createdAt: episode.createdAt ?? nowIso()
+    })),
+    facts: (input.facts ?? []).map((fact) => ({
+      ...fact,
+      status: fact.status ?? FactStatus.CONFIRMED,
+      confidence: fact.confidence ?? 1,
+      sensitivity: fact.sensitivity ?? 'normal',
+      scope: fact.scope ?? 'personal',
+      validAt: fact.validAt ?? nowIso(),
+      invalidAt: fact.invalidAt ?? null,
+      replacedByFactId: fact.replacedByFactId ?? null
+    })),
+    candidates: (input.candidates ?? []).map(normalizeCandidate),
+    outbox: Object.hasOwn(input, 'outbox') ? input.outbox : cloneSnapshot(outbox),
+    imports: Object.hasOwn(input, 'imports') ? input.imports : cloneSnapshot(imports)
+  };
+  return validateSnapshotRecords(normalized);
+}
+
+export function cloneSnapshot(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function normalizeCandidate(candidate) {
+  const status = candidate.status ?? CandidateStatus.PENDING;
+  const createdAt = candidate.createdAt ?? nowIso();
+  return {
+    ...candidate,
+    targetSpaceId: candidate.targetSpaceId ?? null,
+    status,
+    createdAt,
+    decidedAt: candidate.decidedAt ?? (status === CandidateStatus.PENDING ? null : createdAt)
+  };
+}

package/src/storage/sqlite/candidates-repository.js

@@ -0,0 +1,84 @@
+import { randomUUID } from 'node:crypto';
+
+import { CandidateStatus, nowIso } from '../../models.js';
+import { validateCandidateRecord } from '../record-validation.js';
+import { mapCandidate } from './mapper.js';
+
+export class CandidatesRepository {
+  constructor(db) {
+    this.insertStatement = db.prepare(`
+      INSERT INTO candidates (
+        id, personal_space_id, target_space_id, episode_id, reason,
+        status, created_at, decided_at
+      ) VALUES (
+        @id, @personalSpaceId, @targetSpaceId, @episodeId, @reason,
+        @status, @createdAt, @decidedAt
+      )
+    `);
+    this.getStatement = db.prepare('SELECT * FROM candidates WHERE id = ?');
+    this.listStatement = db.prepare('SELECT * FROM candidates ORDER BY rowid');
+    this.pendingStatement = db.prepare(`
+      SELECT * FROM candidates
+      WHERE personal_space_id = ? AND status = 'pending'
+      ORDER BY rowid
+    `);
+    this.updateStatusStatement = db.prepare(`
+      UPDATE candidates SET status = ?, decided_at = ? WHERE id = ?
+    `);
+    this.deleteStatement = db.prepare('DELETE FROM candidates');
+  }
+
+  add(candidate) {
+    if (candidate.id && this.get(candidate.id)) {
+      throw new Error(`Duplicate candidate id: ${candidate.id}`);
+    }
+
+    const status = candidate.status ?? CandidateStatus.PENDING;
+    const createdAt = candidate.createdAt ?? nowIso();
+    const stored = {
+      id: candidate.id || randomUUID(),
+      personalSpaceId: candidate.personalSpaceId,
+      targetSpaceId: candidate.targetSpaceId ?? null,
+      episodeId: candidate.episodeId,
+      reason: candidate.reason,
+      status,
+      createdAt,
+      decidedAt: candidate.decidedAt ?? (
+        status === CandidateStatus.PENDING ? null : createdAt
+      )
+    };
+    validateCandidateRecord(stored);
+    this.insertStatement.run(stored);
+    return this.get(stored.id);
+  }
+
+  get(id) {
+    return mapCandidate(this.getStatement.get(id));
+  }
+
+  list() {
+    return this.listStatement.all().map(mapCandidate);
+  }
+
+  pending(personalSpaceId) {
+    return this.pendingStatement.all(personalSpaceId).map(mapCandidate);
+  }
+
+  updateStatus(id, status) {
+    const candidate = this.get(id);
+    if (!candidate) throw new Error(`Candidate not found: ${id}`);
+    const decidedAt = status === CandidateStatus.PENDING ? null : nowIso();
+    validateCandidateRecord({ ...candidate, status, decidedAt });
+    this.updateStatusStatement.run(status, decidedAt, id);
+    return this.get(id);
+  }
+
+  insertSnapshot(candidate) {
+    validateCandidateRecord(candidate);
+    this.insertStatement.run(candidate);
+  }
+
+  deleteAll() {
+    this.deleteStatement.run();
+  }
+}

package/src/storage/sqlite/episode-evidence-repository.js

@@ -0,0 +1,154 @@
+import {
+  MAX_EPISODE_METADATA_BYTES,
+  MAX_EPISODE_METADATA_FIELD_BYTES,
+  normalizeCorrectionEvidencePreviewOptions,
+  normalizeEvidencePreviewOptions,
+  previewEpisode
+} from '../episode-evidence-preview.js';
+import { sqliteEpisodeRestrictedSql } from './episode-privacy-sql.js';
+
+export class EpisodeEvidenceRepository {
+  constructor(db) {
+    this.db = db;
+    this.correctionStatements = new Map();
+    this.sourceStatement = db.prepare(sourceQuery());
+  }
+
+  source(spaceId, episodeId, options = {}) {
+    const normalized = normalizeEvidencePreviewOptions(options);
+    const row = this.sourceStatement.get({
+      spaceId, episodeId,
+      bodyChars: normalized.maxBodyBytes,
+      bodyBytes: normalized.maxBodyBytes,
+      metadataChars: MAX_EPISODE_METADATA_BYTES,
+      metadataBytes: MAX_EPISODE_METADATA_BYTES,
+      includeRestricted: Number(normalized.includeRestricted)
+    });
+    return previewEpisode(mapSourceRow(row), normalized);
+  }
+
+  corrections(spaceId, factIds, options = {}) {
+    const normalized = normalizeCorrectionEvidencePreviewOptions(options);
+    if (factIds.length === 0) return [];
+    const statement = this.#correctionStatement(factIds.length);
+    const parameters = {
+      spaceId,
+      bodyChars: normalized.maxBodyBytes,
+      bodyBytes: normalized.maxBodyBytes,
+      fieldChars: MAX_EPISODE_METADATA_FIELD_BYTES,
+      fieldBytes: MAX_EPISODE_METADATA_FIELD_BYTES,
+      correctionLimit: normalized.maxCorrectionsPerFact,
+      includeRestricted: Number(normalized.includeRestricted)
+    };
+    factIds.forEach((factId, index) => { parameters[`factId${index}`] = factId; });
+    const groups = [...new Set(factIds)].map((factId) => ({
+      factId,
+      episodes: [],
+      truncated: false
+    }));
+    const byFactId = new Map(groups.map((group) => [group.factId, group]));
+    for (const row of statement.all(parameters)) {
+      const group = byFactId.get(row.fact_id);
+      group.episodes.push(previewEpisode(
+        mapCorrectionRow(row),
+        normalized,
+        { correction: true }
+      ));
+      group.truncated = row.correction_count > normalized.maxCorrectionsPerFact;
+    }
+    return groups;
+  }
+
+  #correctionStatement(factCount) {
+    if (!this.correctionStatements.has(factCount)) {
+      this.correctionStatements.set(factCount, this.db.prepare(correctionQuery(factCount)));
+    }
+    return this.correctionStatements.get(factCount);
+  }
+}
+
+function sourceQuery() {
+  return `
+    SELECT id, space_id, source_kind,
+      substr(body, 1, @bodyChars) AS body_preview,
+      length(CAST(body AS BLOB)) > @bodyBytes AS body_truncated,
+      source_uri,
+      substr(metadata_json, 1, @metadataChars) AS metadata_preview,
+      length(CAST(metadata_json AS BLOB)) > @metadataBytes AS metadata_truncated,
+      created_at
+    FROM episodes source
+    WHERE id = @episodeId AND space_id = @spaceId
+      AND (@includeRestricted = 1 OR NOT ${sqliteEpisodeRestrictedSql('source')})
+  `;
+}
+
+function correctionQuery(factCount) {
+  const factIds = Array.from({ length: factCount }, (_, index) => `@factId${index}`).join(', ');
+  const fields = ['kind', 'factId', 'action'];
+  const selected = fields.map((field) => `
+      substr(CAST(json_extract(metadata_json, '$.${field}') AS TEXT), 1, @fieldChars)
+        AS metadata_${field.toLowerCase()}`
+  ).join(',');
+  const clipped = fields.map((field) => `
+      length(CAST(json_extract(metadata_json, '$.${field}') AS BLOB)) > @fieldBytes`
+  ).join(' OR ');
+  return `
+    WITH ranked AS (
+      SELECT correction.rowid AS correction_rowid,
+        json_extract(metadata_json, '$.factId') AS fact_id,
+        row_number() OVER (
+          PARTITION BY json_extract(metadata_json, '$.factId')
+          ORDER BY created_at DESC, correction.rowid DESC
+        ) AS correction_rank,
+        count(*) OVER (
+          PARTITION BY json_extract(metadata_json, '$.factId')
+        ) AS correction_count
+      FROM episodes correction
+      WHERE space_id = @spaceId
+        AND json_extract(metadata_json, '$.kind') = 'lens_correction'
+        AND json_extract(metadata_json, '$.factId') IN (${factIds})
+        AND (@includeRestricted = 1 OR NOT ${sqliteEpisodeRestrictedSql('correction')})
+    )
+    SELECT correction.id, correction.space_id, correction.source_kind,
+      substr(body, 1, @bodyChars) AS body_preview,
+      length(CAST(body AS BLOB)) > @bodyBytes AS body_truncated,
+      source_uri,${selected}, ranked.fact_id, ranked.correction_count,
+      ((${clipped}) OR EXISTS (
+        SELECT 1 FROM json_each(metadata_json)
+        WHERE key NOT IN ('kind', 'factId', 'action')
+      )) AS metadata_truncated,
+      correction.created_at
+    FROM ranked
+    JOIN episodes correction ON correction.rowid = ranked.correction_rowid
+    WHERE ranked.correction_rank <= @correctionLimit
+    ORDER BY ranked.fact_id, ranked.correction_rank
+  `;
+}
+
+function mapSourceRow(row) {
+  if (!row) return null;
+  return mapRow(row, row.metadata_truncated ? {} : JSON.parse(row.metadata_preview));
+}
+
+function mapCorrectionRow(row) {
+  if (!row) return null;
+  const metadata = {};
+  for (const [key, column] of [
+    ['kind', 'metadata_kind'], ['factId', 'metadata_factid'], ['action', 'metadata_action']
+  ]) if (typeof row[column] === 'string') metadata[key] = row[column];
+  return mapRow(row, metadata);
+}
+
+function mapRow(row, metadata) {
+  return {
+    id: row.id,
+    spaceId: row.space_id,
+    sourceKind: row.source_kind,
+    body: row.body_preview,
+    bodyTruncated: row.body_truncated === 1,
+    sourceUri: row.source_uri,
+    metadata,
+    metadataTruncated: row.metadata_truncated === 1,
+    createdAt: row.created_at
+  };
+}