fuli-context 0.2.0

package/src/storage/sqlite/episode-privacy-sql.js

@@ -0,0 +1,33 @@
+import { isRestrictedEpisode } from '../../security/episode-visibility.js';
+
+const FUNCTION_NAME = 'episode_evidence_is_restricted';
+
+export function registerEpisodePrivacyFunction(db) {
+  db.function(
+    FUNCTION_NAME,
+    { deterministic: true },
+    (sourceKind, body, sourceUri, metadataJson) => Number(isRestrictedEpisode({
+      sourceKind,
+      body,
+      sourceUri,
+      metadata: parseMetadata(metadataJson)
+    }))
+  );
+}
+
+export function sqliteEpisodeRestrictedSql(alias) {
+  return `${FUNCTION_NAME}(
+    ${alias}.source_kind,
+    ${alias}.body,
+    ${alias}.source_uri,
+    ${alias}.metadata_json
+  ) = 1`;
+}
+
+function parseMetadata(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return { invalidMetadataRestricted: 'password=invalid-metadata' };
+  }
+}

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

@@ -0,0 +1,52 @@
+import { randomUUID } from 'node:crypto';
+
+import { nowIso } from '../../models.js';
+import { mapEpisode } from './mapper.js';
+
+export class EpisodesRepository {
+  constructor(db) {
+    this.insertStatement = db.prepare(`
+      INSERT INTO episodes (
+        id, space_id, source_kind, body, source_uri, metadata_json, created_at
+      ) VALUES (
+        @id, @spaceId, @sourceKind, @body, @sourceUri, @metadataJson, @createdAt
+      )
+    `);
+    this.getStatement = db.prepare('SELECT * FROM episodes WHERE id = ?');
+    this.listStatement = db.prepare('SELECT * FROM episodes ORDER BY rowid');
+    this.deleteStatement = db.prepare('DELETE FROM episodes');
+  }
+
+  add(spaceId, sourceKind, body, sourceUri = null, metadata = {}) {
+    const episode = {
+      id: randomUUID(),
+      spaceId,
+      sourceKind,
+      body,
+      sourceUri,
+      metadataJson: JSON.stringify(metadata),
+      createdAt: nowIso()
+    };
+    this.insertStatement.run(episode);
+    return this.get(episode.id);
+  }
+
+  get(id) {
+    return mapEpisode(this.getStatement.get(id));
+  }
+
+  list() {
+    return this.listStatement.all().map(mapEpisode);
+  }
+
+  insertSnapshot(episode) {
+    this.insertStatement.run({
+      ...episode,
+      metadataJson: JSON.stringify(episode.metadata)
+    });
+  }
+
+  deleteAll() {
+    this.deleteStatement.run();
+  }
+}

package/src/storage/sqlite/fact-search-repository.js

@@ -0,0 +1,162 @@
+import { isRestrictedFact } from '../../security/fact-visibility.js';
+import { searchTextSortKey } from '../fact-search-order.js';
+import { sqliteEpisodeRestrictedSql } from './episode-privacy-sql.js';
+import { mapFact } from './mapper.js';
+
+export class FactSearchRepository {
+  constructor(db) {
+    this.db = db;
+    this.statements = new Map();
+    this.omissionStatements = new Map();
+    registerSearchFunctions(db);
+  }
+
+  search(spaceIds, query, {
+    includeHistorical = false,
+    scope = null,
+    limit = null,
+    excludeRestricted = false,
+    safeSourceSpaceId = null,
+    maxObjectBytes = null
+  } = {}) {
+    return this.searchPage(spaceIds, query, {
+      includeHistorical,
+      scope,
+      limit,
+      excludeRestricted,
+      safeSourceSpaceId,
+      maxObjectBytes
+    }).facts;
+  }
+
+  searchPage(spaceIds, query, options = {}) {
+    const {
+      includeHistorical = false,
+      scope = null,
+      limit = null,
+      excludeRestricted = false,
+      safeSourceSpaceId = null,
+      maxObjectBytes = null
+    } = options;
+    if (spaceIds.length === 0) return { facts: [], objectLimitTruncated: false };
+    if (limit !== null && (!Number.isInteger(limit) || limit <= 0)) {
+      throw new TypeError('Fact search limit must be a positive integer');
+    }
+
+    const shape = {
+      spaceCount: spaceIds.length,
+      includeHistorical,
+      scoped: scope !== null,
+      limited: limit !== null,
+      excludeRestricted: excludeRestricted === true,
+      safeSourceRequired: safeSourceSpaceId !== null,
+      objectBytesBounded: maxObjectBytes !== null
+    };
+    const parameters = [...spaceIds];
+    if (scope !== null) parameters.push(scope);
+    if (safeSourceSpaceId !== null) parameters.push(safeSourceSpaceId);
+    if (maxObjectBytes !== null) parameters.push(maxObjectBytes);
+    parameters.push(query.toLowerCase());
+    const factParameters = limit === null ? parameters : [...parameters, limit];
+    const facts = this.#statement(shape).all(...factParameters).map(mapFact);
+    const objectLimitTruncated = maxObjectBytes === null
+      ? false
+      : this.#omissionStatement(shape).pluck().get(...parameters) === 1;
+    return { facts, objectLimitTruncated };
+  }
+
+  #statement(shape) {
+    const key = Object.values(shape).join(':');
+    if (!this.statements.has(key)) {
+      this.statements.set(key, this.db.prepare(buildSearchQuery(shape)));
+    }
+    return this.statements.get(key);
+  }
+
+  #omissionStatement(shape) {
+    const key = Object.values(shape).join(':');
+    if (!this.omissionStatements.has(key)) {
+      this.omissionStatements.set(key, this.db.prepare(buildOmissionQuery(shape)));
+    }
+    return this.omissionStatements.get(key);
+  }
+}
+
+function buildOmissionQuery(shape) {
+  return `SELECT EXISTS (
+    SELECT 1 FROM facts
+    WHERE ${buildWhereClause(shape, { oversized: true })}
+    LIMIT 1
+  )`;
+}
+
+function registerSearchFunctions(db) {
+  db.function('fact_search_text_sort_key', { deterministic: true }, searchTextSortKey);
+  db.function('fact_search_is_restricted', { deterministic: true },
+    (subject, predicate, object, sensitivity) => Number(isRestrictedFact({
+      subject, predicate, object, sensitivity
+    })));
+}
+
+function buildSearchQuery({
+  spaceCount,
+  includeHistorical,
+  scoped,
+  limited,
+  excludeRestricted,
+  safeSourceRequired,
+  objectBytesBounded
+}) {
+  const shape = {
+    spaceCount,
+    includeHistorical,
+    scoped,
+    excludeRestricted,
+    safeSourceRequired,
+    objectBytesBounded
+  };
+  const orderClause = limited
+    ? 'ORDER BY valid_at DESC, fact_search_text_sort_key(id) ASC LIMIT ?'
+    : 'ORDER BY rowid';
+  return `
+    SELECT * FROM facts
+    WHERE ${buildWhereClause(shape)}
+    ${orderClause}
+  `;
+}
+
+function buildWhereClause({
+  spaceCount,
+  includeHistorical,
+  scoped,
+  excludeRestricted,
+  safeSourceRequired,
+  objectBytesBounded
+}, { oversized = false } = {}) {
+  const placeholders = Array.from({ length: spaceCount }, () => '?').join(', ');
+  const currentClause = includeHistorical
+    ? ''
+    : "AND invalid_at IS NULL AND status NOT IN ('rejected', 'deprecated')";
+  const scopeClause = scoped ? 'AND scope = ?' : '';
+  const restrictedClause = excludeRestricted
+    ? `AND fact_search_is_restricted(
+      subject, predicate, object, sensitivity
+    ) = 0`
+    : '';
+  const sourceClause = safeSourceRequired ? `AND EXISTS (
+    SELECT 1 FROM episodes source
+    WHERE source.id = source_episode_id
+      AND source.space_id = ?
+      AND NOT ${sqliteEpisodeRestrictedSql('source')}
+  )` : '';
+  const objectBytesClause = objectBytesBounded
+    ? `AND length(CAST(object AS BLOB)) ${oversized ? '>' : '<='} ?`
+    : '';
+  return `space_id IN (${placeholders})
+      ${currentClause}
+      ${scopeClause}
+      ${restrictedClause}
+      ${sourceClause}
+      ${objectBytesClause}
+      AND instr(lower(subject || ' ' || predicate || ' ' || object), ?) > 0`;
+}

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

@@ -0,0 +1,146 @@
+import { randomUUID } from 'node:crypto';
+
+import { FactStatus, nowIso } from '../../models.js';
+import { validateFactRecord } from '../record-validation.js';
+import { FactSearchRepository } from './fact-search-repository.js';
+import { mapFact } from './mapper.js';
+
+export class FactsRepository {
+  constructor(db) {
+    this.factSearch = new FactSearchRepository(db);
+    this.insertStatement = db.prepare(`
+      INSERT INTO facts (
+        id, space_id, subject, predicate, object, source_episode_id, status,
+        confidence, sensitivity, scope, valid_at, invalid_at, replaced_by_fact_id
+      ) VALUES (
+        @id, @spaceId, @subject, @predicate, @object, @sourceEpisodeId, @status,
+        @confidence, @sensitivity, @scope, @validAt, @invalidAt, @replacedByFactId
+      )
+    `);
+    this.getStatement = db.prepare('SELECT * FROM facts WHERE id = ?');
+    this.updateStatement = db.prepare(`
+      UPDATE facts SET
+        space_id = @spaceId,
+        subject = @subject,
+        predicate = @predicate,
+        object = @object,
+        source_episode_id = @sourceEpisodeId,
+        status = @status,
+        confidence = @confidence,
+        sensitivity = @sensitivity,
+        scope = @scope,
+        valid_at = @validAt,
+        invalid_at = @invalidAt,
+        replaced_by_fact_id = @replacedByFactId
+      WHERE id = @id
+    `);
+    this.currentStatement = db.prepare(`
+      SELECT * FROM facts
+      WHERE space_id = ?
+        AND invalid_at IS NULL
+        AND status NOT IN ('rejected', 'deprecated')
+      ORDER BY rowid
+    `);
+    this.currentListStatement = db.prepare(`
+      SELECT * FROM facts
+      WHERE invalid_at IS NULL AND status NOT IN ('rejected', 'deprecated')
+      ORDER BY rowid
+    `);
+    this.fullListStatement = db.prepare('SELECT * FROM facts ORDER BY rowid');
+    this.timelineStatement = db.prepare(`
+      SELECT * FROM facts
+      WHERE space_id = ? AND subject = ?
+      ORDER BY valid_at, rowid
+    `);
+    this.replaceLinkStatement = db.prepare(`
+      UPDATE facts SET replaced_by_fact_id = ? WHERE id = ?
+    `);
+    this.deleteStatement = db.prepare('DELETE FROM facts');
+  }
+
+  add(fact) {
+    if (fact.id && this.get(fact.id)) {
+      throw new Error(`Duplicate fact id: ${fact.id}`);
+    }
+
+    const stored = {
+      id: fact.id || randomUUID(),
+      spaceId: fact.spaceId,
+      subject: fact.subject,
+      predicate: fact.predicate,
+      object: fact.object,
+      sourceEpisodeId: fact.sourceEpisodeId,
+      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
+    };
+    validateFactRecord(stored);
+    this.insertStatement.run(stored);
+    return this.get(stored.id);
+  }
+
+  get(id) {
+    return mapFact(this.getStatement.get(id));
+  }
+
+  update(id, updates) {
+    const existing = this.get(id);
+    if (!existing) throw new Error(`Fact not found: ${id}`);
+
+    const stored = { ...existing, ...updates, id };
+    validateFactRecord(stored);
+    this.updateStatement.run(stored);
+    return this.get(id);
+  }
+
+  invalidate(id, replacedByFactId = null) {
+    const fact = this.get(id);
+    if (!fact || fact.invalidAt) return;
+    this.updateStatement.run({
+      ...fact,
+      invalidAt: nowIso(),
+      replacedByFactId
+    });
+  }
+
+  current(spaceId) {
+    return this.currentStatement.all(spaceId).map(mapFact);
+  }
+
+  list({ includeHistorical = false } = {}) {
+    const statement = includeHistorical ? this.fullListStatement : this.currentListStatement;
+    return statement.all().map(mapFact);
+  }
+
+  timeline(spaceId, subject) {
+    return this.timelineStatement.all(spaceId, subject).map(mapFact);
+  }
+
+  search(spaceIds, query, options = {}) {
+    return this.factSearch.search(spaceIds, query, options);
+  }
+
+  searchPage(spaceIds, query, options = {}) {
+    return this.factSearch.searchPage(spaceIds, query, options);
+  }
+
+  insertSnapshot(fact, { deferReplacement = false } = {}) {
+    validateFactRecord(fact);
+    this.insertStatement.run({
+      ...fact,
+      replacedByFactId: deferReplacement ? null : fact.replacedByFactId
+    });
+  }
+
+  restoreReplacement(id, replacedByFactId) {
+    this.replaceLinkStatement.run(replacedByFactId, id);
+  }
+
+  deleteAll() {
+    this.deleteStatement.run();
+  }
+}

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

@@ -0,0 +1,39 @@
+import { mapImport } from './mapper.js';
+
+export class ImportsRepository {
+  constructor(db) {
+    this.insertStatement = db.prepare(`
+      INSERT INTO imports (content_hash, source_path, imported_at)
+      VALUES (@contentHash, @sourcePath, @importedAt)
+    `);
+    this.hasStatement = db.prepare(`
+      SELECT 1 FROM imports WHERE content_hash = ?
+    `);
+    this.listStatement = db.prepare('SELECT * FROM imports ORDER BY rowid');
+    this.deleteStatement = db.prepare('DELETE FROM imports');
+  }
+
+  has(contentHash) {
+    return this.hasStatement.get(contentHash) !== undefined;
+  }
+
+  record(record) {
+    if (this.has(record.contentHash)) {
+      throw new Error(`Duplicate import content hash: ${record.contentHash}`);
+    }
+    this.insertStatement.run(record);
+    return { ...record };
+  }
+
+  listAll() {
+    return this.listStatement.all().map(mapImport);
+  }
+
+  insertSnapshot(record) {
+    this.insertStatement.run(record);
+  }
+
+  deleteAll() {
+    this.deleteStatement.run();
+  }
+}

package/src/storage/sqlite/mapper.js

@@ -0,0 +1,84 @@
+export function mapSpace(row) {
+  return row ? {
+    id: row.id,
+    name: row.name,
+    kind: row.kind,
+    description: row.description,
+    createdAt: row.created_at
+  } : null;
+}
+
+export function mapSubscription(row) {
+  return row ? {
+    personalSpaceId: row.personal_space_id,
+    spaceId: row.space_id,
+    mode: row.mode,
+    createdAt: row.created_at
+  } : null;
+}
+
+export function mapEpisode(row) {
+  return row ? {
+    id: row.id,
+    spaceId: row.space_id,
+    sourceKind: row.source_kind,
+    body: row.body,
+    sourceUri: row.source_uri,
+    metadata: JSON.parse(row.metadata_json),
+    createdAt: row.created_at
+  } : null;
+}
+
+export function mapFact(row) {
+  return row ? {
+    id: row.id,
+    spaceId: row.space_id,
+    subject: row.subject,
+    predicate: row.predicate,
+    object: row.object,
+    sourceEpisodeId: row.source_episode_id,
+    status: row.status,
+    confidence: row.confidence,
+    sensitivity: row.sensitivity,
+    scope: row.scope,
+    validAt: row.valid_at,
+    invalidAt: row.invalid_at,
+    replacedByFactId: row.replaced_by_fact_id
+  } : null;
+}
+
+export function mapCandidate(row) {
+  return row ? {
+    id: row.id,
+    personalSpaceId: row.personal_space_id,
+    targetSpaceId: row.target_space_id,
+    episodeId: row.episode_id,
+    reason: row.reason,
+    status: row.status,
+    createdAt: row.created_at,
+    decidedAt: row.decided_at
+  } : null;
+}
+
+export function mapOutbox(row) {
+  return row ? {
+    id: row.id,
+    kind: row.kind,
+    aggregateId: row.aggregate_id,
+    payload: JSON.parse(row.payload_json),
+    status: row.status,
+    attempts: row.attempts,
+    nextAttemptAt: row.next_attempt_at,
+    createdAt: row.created_at,
+    sentAt: row.sent_at,
+    lastError: row.last_error
+  } : null;
+}
+
+export function mapImport(row) {
+  return row ? {
+    contentHash: row.content_hash,
+    sourcePath: row.source_path,
+    importedAt: row.imported_at
+  } : null;
+}

package/src/storage/sqlite/open-database.js

@@ -0,0 +1,15 @@
+import { mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+import Database from 'better-sqlite3';
+
+export function openDatabase(filePath) {
+  if (isFileDatabase(filePath)) {
+    mkdirSync(dirname(resolve(filePath)), { recursive: true });
+  }
+  return new Database(filePath);
+}
+
+export function isFileDatabase(filePath) {
+  return typeof filePath === 'string' && filePath !== ':memory:' && filePath !== '';
+}

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

@@ -0,0 +1,103 @@
+import { randomUUID } from 'node:crypto';
+
+import { nowIso } from '../../models.js';
+import { validateOutboxRecord } from '../record-validation.js';
+import { mapOutbox } from './mapper.js';
+
+export class OutboxRepository {
+  constructor(db) {
+    this.insertStatement = db.prepare(`
+      INSERT INTO outbox (
+        id, kind, aggregate_id, payload_json, status, attempts,
+        next_attempt_at, created_at, sent_at, last_error
+      ) VALUES (
+        @id, @kind, @aggregateId, @payloadJson, @status, @attempts,
+        @nextAttemptAt, @createdAt, @sentAt, @lastError
+      )
+    `);
+    this.getStatement = db.prepare('SELECT * FROM outbox WHERE id = ?');
+    this.listStatement = db.prepare('SELECT * FROM outbox ORDER BY rowid');
+    this.pendingStatement = db.prepare(`
+      SELECT * FROM outbox
+      WHERE status = 'pending'
+        AND (next_attempt_at IS NULL OR next_attempt_at <= ?)
+      ORDER BY created_at, rowid
+    `);
+    this.markSentStatement = db.prepare(`
+      UPDATE outbox SET
+        status = 'sent', next_attempt_at = NULL, sent_at = ?, last_error = NULL
+      WHERE id = ?
+    `);
+    this.markFailedStatement = db.prepare(`
+      UPDATE outbox SET
+        status = 'pending', attempts = attempts + 1,
+        next_attempt_at = ?, last_error = ?
+      WHERE id = ?
+    `);
+    this.deleteStatement = db.prepare('DELETE FROM outbox');
+  }
+
+  enqueue(entry) {
+    if (entry.id && this.get(entry.id)) {
+      throw new Error(`Duplicate outbox id: ${entry.id}`);
+    }
+
+    const stored = {
+      id: entry.id || randomUUID(),
+      kind: entry.kind,
+      aggregateId: entry.aggregateId,
+      payloadJson: JSON.stringify(entry.payload),
+      status: entry.status ?? 'pending',
+      attempts: entry.attempts ?? 0,
+      nextAttemptAt: entry.nextAttemptAt ?? null,
+      createdAt: entry.createdAt ?? nowIso(),
+      sentAt: entry.sentAt ?? null,
+      lastError: entry.lastError ?? null
+    };
+    validateOutboxRecord(stored);
+    this.insertStatement.run(stored);
+    return this.get(stored.id);
+  }
+
+  listPending(at = nowIso()) {
+    return this.pendingStatement.all(at).map(mapOutbox);
+  }
+
+  markSent(id, sentAt = nowIso()) {
+    this.require(id);
+    this.markSentStatement.run(sentAt, id);
+    return this.get(id);
+  }
+
+  markFailed(id, error, nextAttemptAt = null) {
+    this.require(id);
+    this.markFailedStatement.run(nextAttemptAt, error, id);
+    return this.get(id);
+  }
+
+  get(id) {
+    return mapOutbox(this.getStatement.get(id));
+  }
+
+  listAll() {
+    return this.listStatement.all().map(mapOutbox);
+  }
+
+  insertSnapshot(entry) {
+    validateOutboxRecord(entry);
+    this.insertStatement.run({
+      ...entry,
+      payloadJson: JSON.stringify(entry.payload)
+    });
+  }
+
+  deleteAll() {
+    this.deleteStatement.run();
+  }
+
+  require(id) {
+    const row = this.get(id);
+    if (!row) throw new Error(`Outbox row not found: ${id}`);
+    return row;
+  }
+}

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

@@ -0,0 +1,69 @@
+import { cloneSnapshot, normalizeSnapshot } from '../snapshot-defaults.js';
+
+export class SnapshotRepository {
+  constructor(db, repositories) {
+    this.db = db;
+    this.repositories = repositories;
+  }
+
+  export() {
+    const repositories = this.repositories;
+    return cloneSnapshot({
+      spaces: repositories.spaces.list(),
+      subscriptions: repositories.subscriptions.list(),
+      episodes: repositories.episodes.list(),
+      facts: repositories.facts.list({ includeHistorical: true }),
+      candidates: repositories.candidates.list(),
+      outbox: repositories.outbox.listAll(),
+      imports: repositories.imports.listAll()
+    });
+  }
+
+  import(snapshot) {
+    const current = this.export();
+    const normalized = normalizeSnapshot(snapshot, {
+      outbox: current.outbox,
+      imports: current.imports
+    });
+    const replaceOutbox = Object.hasOwn(snapshot, 'outbox');
+    const replaceImports = Object.hasOwn(snapshot, 'imports');
+    const apply = () => this.replace(normalized, { replaceOutbox, replaceImports });
+
+    if (this.db.inTransaction) apply();
+    else this.db.transaction(apply)();
+  }
+
+  replace(snapshot, { replaceOutbox, replaceImports }) {
+    const repositories = this.repositories;
+    repositories.subscriptions.deleteAll();
+    repositories.candidates.deleteAll();
+    repositories.facts.deleteAll();
+    repositories.episodes.deleteAll();
+    if (replaceOutbox) repositories.outbox.deleteAll();
+    if (replaceImports) repositories.imports.deleteAll();
+    repositories.spaces.deleteAll();
+
+    for (const space of snapshot.spaces) repositories.spaces.insertSnapshot(space);
+    for (const subscription of snapshot.subscriptions) {
+      repositories.subscriptions.insertSnapshot(subscription);
+    }
+    for (const episode of snapshot.episodes) repositories.episodes.insertSnapshot(episode);
+    for (const fact of snapshot.facts) {
+      repositories.facts.insertSnapshot(fact, { deferReplacement: true });
+    }
+    for (const fact of snapshot.facts) {
+      if (fact.replacedByFactId) {
+        repositories.facts.restoreReplacement(fact.id, fact.replacedByFactId);
+      }
+    }
+    for (const candidate of snapshot.candidates) {
+      repositories.candidates.insertSnapshot(candidate);
+    }
+    if (replaceOutbox) {
+      for (const entry of snapshot.outbox) repositories.outbox.insertSnapshot(entry);
+    }
+    if (replaceImports) {
+      for (const record of snapshot.imports) repositories.imports.insertSnapshot(record);
+    }
+  }
+}