fuli-context 0.2.0

package/src/storage/file-store.js

@@ -0,0 +1,437 @@
+import { randomUUID } from 'node:crypto';
+
+import { CandidateStatus, FactStatus, isCurrentFact, nowIso } from '../models.js';
+import { FileEpisodeIndex } from './file/episode-index.js';
+import {
+  fileCorrectionEpisodeEvidencePreviews,
+  fileEpisodeEvidencePreview
+} from './file/episode-evidence.js';
+import { searchFileFacts, searchFileFactsPage } from './file/fact-search.js';
+import { readJsonFile, writeJsonFileAtomic } from './json-file.js';
+import {
+  validateCandidateRecord,
+  validateFactRecord,
+  validateOutboxRecord
+} from './record-validation.js';
+import { normalizeSnapshot } from './snapshot-defaults.js';
+
+export class FileStore {
+  #committedData;
+  #episodeIndex;
+
+  constructor(filePath, { jsonFileIo } = {}) {
+    this.filePath = filePath;
+    this.memoryOnly = filePath === ':memory:';
+    this.jsonFileIo = jsonFileIo;
+    this.transactionActive = false;
+    this.transactionDirty = false;
+    this.data = this.memoryOnly ? normalizeSnapshot() : this.#load();
+    this.#committedData = cloneData(this.data);
+    this.#episodeIndex = new FileEpisodeIndex(this.data.episodes);
+  }
+
+  transaction(fn, _options = {}) {
+    if (this.transactionActive) {
+      throw new TypeError('Nested FileStore transactions are not supported');
+    }
+
+    if (fn.constructor?.name === 'AsyncFunction') {
+      throw new TypeError('Transaction callback must be synchronous');
+    }
+
+    const snapshot = cloneData(this.data);
+    this.transactionActive = true;
+    this.transactionDirty = false;
+    try {
+      const result = fn(this);
+      if (isThenable(result)) {
+        if (typeof result.catch === 'function') result.catch(() => {});
+        throw new TypeError('Transaction callback must be synchronous');
+      }
+
+      const dirty = this.transactionDirty;
+      this.transactionActive = false;
+      this.transactionDirty = false;
+      if (dirty) this.#commit();
+      return result;
+    } catch (error) {
+      this.data = snapshot;
+      this.#episodeIndex.rebuild(this.data.episodes);
+      this.transactionActive = false;
+      this.transactionDirty = false;
+      throw error;
+    }
+  }
+
+  createSpace(name, kind, description = null) {
+    const existing = this.findSpaceByName(name);
+    if (existing) return existing;
+
+    const space = {
+      id: randomUUID(),
+      name,
+      kind,
+      description,
+      createdAt: nowIso()
+    };
+    this.data.spaces.push(space);
+    this.#save();
+    return cloneData(space);
+  }
+
+  listSpaces() {
+    return cloneData(this.data.spaces);
+  }
+
+  findSpaceByName(name) {
+    return cloneData(this.data.spaces.find((space) => space.name === name) ?? null);
+  }
+
+  getSpace(id) {
+    return cloneData(this.data.spaces.find((space) => space.id === id) ?? null);
+  }
+
+  subscribe(personalSpaceId, spaceId, mode = 'latest') {
+    const existing = this.data.subscriptions.find(
+      (subscription) =>
+        subscription.personalSpaceId === personalSpaceId && subscription.spaceId === spaceId
+    );
+    if (existing) return cloneData(existing);
+
+    const subscription = { personalSpaceId, spaceId, mode, createdAt: nowIso() };
+    this.data.subscriptions.push(subscription);
+    this.#save();
+    return cloneData(subscription);
+  }
+
+  listSubscriptions() {
+    return cloneData(this.data.subscriptions);
+  }
+
+  subscriptionsFor(personalSpaceId) {
+    return cloneData(this.data.subscriptions.filter(
+      (subscription) => subscription.personalSpaceId === personalSpaceId
+    ));
+  }
+
+  addEpisode(spaceId, sourceKind, body, sourceUri = null, metadata = {}) {
+    const episode = {
+      id: randomUUID(),
+      spaceId,
+      sourceKind,
+      body,
+      sourceUri,
+      metadata: cloneData(metadata),
+      createdAt: nowIso()
+    };
+    this.data.episodes.push(episode);
+    this.#episodeIndex.add(episode);
+    this.#save();
+    return cloneData(episode);
+  }
+
+  getEpisode(id) {
+    return cloneData(this.#episodeIndex.get(id));
+  }
+
+  listEpisodes() {
+    return cloneData(this.data.episodes);
+  }
+
+  episodeEvidencePreview(spaceId, episodeId, options = {}) {
+    return cloneData(fileEpisodeEvidencePreview(
+      this.#episodeIndex,
+      spaceId,
+      episodeId,
+      options
+    ));
+  }
+
+  correctionEpisodeEvidencePreviews(spaceId, factIds, options = {}) {
+    return cloneData(fileCorrectionEpisodeEvidencePreviews(
+      this.#episodeIndex,
+      spaceId,
+      factIds,
+      options
+    ));
+  }
+
+  addFact(fact) {
+    if (fact.id && this.data.facts.some((item) => item.id === 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.data.facts.push(stored);
+    this.#save();
+    return cloneData(stored);
+  }
+
+  getFact(id) {
+    return cloneData(this.data.facts.find((fact) => fact.id === id) ?? null);
+  }
+
+  updateFact(id, updates) {
+    const fact = this.data.facts.find((item) => item.id === id);
+    if (!fact) {
+      throw new Error(`Fact not found: ${id}`);
+    }
+
+    const updated = { ...fact, ...updates, id };
+    validateFactRecord(updated);
+    Object.assign(fact, updated);
+    this.#save();
+    return cloneData(fact);
+  }
+
+  invalidateFact(factId, replacedByFactId = null) {
+    const fact = this.data.facts.find((item) => item.id === factId);
+    if (!fact || fact.invalidAt) return;
+
+    fact.invalidAt = nowIso();
+    fact.replacedByFactId = replacedByFactId;
+    this.#save();
+  }
+
+  currentFacts(spaceId) {
+    return cloneData(
+      this.data.facts.filter((fact) => fact.spaceId === spaceId && isCurrentFact(fact))
+    );
+  }
+
+  listFacts(options = {}) {
+    const includeHistorical = options.includeHistorical ?? false;
+    return cloneData(
+      this.data.facts.filter((fact) => includeHistorical || isCurrentFact(fact))
+    );
+  }
+
+  timeline(spaceId, subject) {
+    return cloneData(this.data.facts
+      .filter((fact) => fact.spaceId === spaceId && fact.subject === subject)
+      .sort((left, right) => left.validAt.localeCompare(right.validAt)));
+  }
+
+  searchFacts(spaceIds, query, options = {}) {
+    return cloneData(searchFileFacts(
+      this.data.facts,
+      this.#episodeIndex,
+      spaceIds,
+      query,
+      options
+    ));
+  }
+
+  searchFactsPage(spaceIds, query, options = {}) {
+    return cloneData(searchFileFactsPage(
+      this.data.facts,
+      this.#episodeIndex,
+      spaceIds,
+      query,
+      options
+    ));
+  }
+
+  addCandidate(candidate) {
+    if (candidate.id && this.data.candidates.some((item) => item.id === 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.data.candidates.push(stored);
+    this.#save();
+    return cloneData(stored);
+  }
+
+  pendingCandidates(personalSpaceId) {
+    return cloneData(this.data.candidates.filter(
+      (candidate) =>
+        candidate.personalSpaceId === personalSpaceId &&
+        candidate.status === CandidateStatus.PENDING
+    ));
+  }
+
+  getCandidate(id) {
+    return cloneData(this.data.candidates.find((candidate) => candidate.id === id) ?? null);
+  }
+
+  listCandidates() {
+    return cloneData(this.data.candidates);
+  }
+
+  updateCandidateStatus(id, status) {
+    const candidate = this.data.candidates.find((item) => item.id === id);
+    if (!candidate) {
+      throw new Error(`Candidate not found: ${id}`);
+    }
+
+    const updated = {
+      ...candidate,
+      status,
+      decidedAt: status === CandidateStatus.PENDING ? null : nowIso()
+    };
+    validateCandidateRecord(updated);
+    Object.assign(candidate, updated);
+    this.#save();
+    return cloneData(candidate);
+  }
+
+  enqueueOutbox(entry) {
+    if (entry.id && this.data.outbox.some((item) => item.id === entry.id)) {
+      throw new Error(`Duplicate outbox id: ${entry.id}`);
+    }
+
+    const row = {
+      id: entry.id || randomUUID(),
+      kind: entry.kind,
+      aggregateId: entry.aggregateId,
+      payload: cloneData(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(row);
+    this.data.outbox.push(row);
+    this.#save();
+    return cloneData(row);
+  }
+
+  listPendingOutbox(at = nowIso()) {
+    return cloneData(this.data.outbox
+      .filter(
+        (row) =>
+          row.status === 'pending' &&
+          (row.nextAttemptAt === null || row.nextAttemptAt <= at)
+      )
+      .sort((left, right) => left.createdAt.localeCompare(right.createdAt)));
+  }
+
+  markOutboxSent(id, sentAt = nowIso()) {
+    const row = this.data.outbox.find((item) => item.id === id);
+    if (!row) {
+      throw new Error(`Outbox row not found: ${id}`);
+    }
+
+    row.status = 'sent';
+    row.nextAttemptAt = null;
+    row.sentAt = sentAt;
+    row.lastError = null;
+    this.#save();
+    return cloneData(row);
+  }
+
+  markOutboxFailed(id, error, nextAttemptAt = null) {
+    const row = this.data.outbox.find((item) => item.id === id);
+    if (!row) {
+      throw new Error(`Outbox row not found: ${id}`);
+    }
+
+    row.status = 'pending';
+    row.attempts += 1;
+    row.nextAttemptAt = nextAttemptAt;
+    row.lastError = error;
+    this.#save();
+    return cloneData(row);
+  }
+
+  hasImport(contentHash) {
+    return this.data.imports.some((record) => record.contentHash === contentHash);
+  }
+
+  recordImport(record) {
+    if (this.hasImport(record.contentHash)) {
+      throw new Error(`Duplicate import content hash: ${record.contentHash}`);
+    }
+
+    const stored = cloneData(record);
+    this.data.imports.push(stored);
+    this.#save();
+    return cloneData(stored);
+  }
+
+  exportSnapshot() {
+    return cloneData(this.data);
+  }
+
+  importSnapshot(snapshot) {
+    this.data = normalizeSnapshot(snapshot, {
+      outbox: this.data.outbox,
+      imports: this.data.imports
+    });
+    this.#episodeIndex.rebuild(this.data.episodes);
+    this.#save();
+  }
+
+  close() {}
+
+  #load() {
+    return normalizeSnapshot(readJsonFile(this.filePath, {}));
+  }
+
+  #save() {
+    if (this.transactionActive) {
+      this.transactionDirty = true;
+      return;
+    }
+
+    try {
+      this.#commit();
+    } catch (error) {
+      this.data = cloneData(this.#committedData);
+      this.#episodeIndex.rebuild(this.data.episodes);
+      throw error;
+    }
+  }
+
+  #commit() {
+    this.#persist();
+    this.#committedData = cloneData(this.data);
+  }
+
+  #persist() {
+    if (this.memoryOnly) return;
+    writeJsonFileAtomic(this.filePath, this.data, this.jsonFileIo);
+  }
+}
+
+function cloneData(data) {
+  return JSON.parse(JSON.stringify(data));
+}
+
+function isThenable(value) {
+  return value !== null &&
+    (typeof value === 'object' || typeof value === 'function') &&
+    typeof value.then === 'function';
+}

package/src/storage/import-json.js

@@ -0,0 +1,70 @@
+import { createHash } from 'node:crypto';
+
+import { nowIso } from '../models.js';
+import { validateLegacySnapshot } from './legacy-snapshot-validation.js';
+import { stableJson } from './stable-json.js';
+
+export function importJsonSnapshot(store, snapshot, sourcePath = '<memory>', options = {}) {
+  return applyPreparedJsonSnapshot(store, prepareJsonSnapshot(snapshot, sourcePath), options);
+}
+
+export function prepareJsonSnapshot(snapshot, sourcePath = '<memory>') {
+  validateSourcePath(sourcePath);
+  const normalized = validateLegacySnapshot(snapshot);
+  const canonicalSnapshot = JSON.parse(stableJson(normalized));
+  const contentHash = hashSnapshot(canonicalSnapshot);
+  return deepFreeze({ snapshot: deepFreeze(canonicalSnapshot), sourcePath, contentHash });
+}
+
+export function applyPreparedJsonSnapshot(store, prepared, { replace = false } = {}) {
+  const verified = verifyPreparedSnapshot(prepared);
+  let imported = false;
+
+  store.transaction(() => {
+    if (store.hasImport(verified.contentHash)) return;
+    if (!replace && !isEmptySnapshot(store.exportSnapshot())) {
+      throw new Error('Destination snapshot is not empty; pass replace: true to replace it');
+    }
+
+    store.importSnapshot(verified.snapshot);
+    store.recordImport({
+      contentHash: verified.contentHash,
+      sourcePath: verified.sourcePath,
+      importedAt: nowIso()
+    });
+    imported = true;
+  }, { mode: 'immediate' });
+
+  return { imported, contentHash: verified.contentHash };
+}
+
+function verifyPreparedSnapshot(prepared) {
+  if (!prepared || typeof prepared !== 'object' || Array.isArray(prepared)) {
+    throw new TypeError('Prepared snapshot must be an object');
+  }
+  const verified = prepareJsonSnapshot(prepared.snapshot, prepared.sourcePath);
+  if (prepared.contentHash !== verified.contentHash) {
+    throw new Error('Prepared snapshot content hash does not match its snapshot');
+  }
+  return verified;
+}
+
+function hashSnapshot(snapshot) {
+  return createHash('sha256').update(stableJson(snapshot)).digest('hex');
+}
+
+function validateSourcePath(sourcePath) {
+  if (typeof sourcePath !== 'string' || sourcePath.length === 0) {
+    throw new TypeError('Import source path must be a nonempty string');
+  }
+}
+
+function isEmptySnapshot(snapshot) {
+  return Object.values(snapshot).every((collection) => Array.isArray(collection) && collection.length === 0);
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}

package/src/storage/json-file.js

@@ -0,0 +1,41 @@
+import { randomUUID } from 'node:crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync
+} from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+
+const DEFAULT_IO = Object.freeze({ mkdirSync, renameSync, rmSync, writeFileSync });
+
+export function readJsonFile(filePath, fallback) {
+  if (!existsSync(filePath)) return fallback;
+
+  const raw = readFileSync(filePath, 'utf8');
+  return raw.trim() ? JSON.parse(raw) : fallback;
+}
+
+export function writeJsonFileAtomic(filePath, value, io = {}) {
+  const fileIo = { ...DEFAULT_IO, ...io };
+  const directory = dirname(filePath);
+  const tempPath = join(directory, `.${basename(filePath)}.${randomUUID()}.tmp`);
+
+  fileIo.mkdirSync(directory, { recursive: true });
+  try {
+    fileIo.writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, {
+      encoding: 'utf8',
+      flag: 'wx'
+    });
+    fileIo.renameSync(tempPath, filePath);
+  } catch (error) {
+    try {
+      fileIo.rmSync(tempPath, { force: true });
+    } catch {
+      // Preserve the write or rename failure that caused cleanup.
+    }
+    throw error;
+  }
+}

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

@@ -0,0 +1,152 @@
+import { CandidateStatus, FactStatus, SpaceKind } from '../models.js';
+import {
+  validateCandidateRecord,
+  validateFactRecord,
+  validateOutboxRecord
+} from './record-validation.js';
+
+export function validateLegacyRecords(snapshot) {
+  requireUnique(snapshot.spaces, 'space', (record) => record.id);
+  requireUnique(snapshot.spaces, 'space name', (record) => record.name);
+  requireUnique(snapshot.episodes, 'episode', (record) => record.id);
+  requireUnique(snapshot.facts, 'fact', (record) => record.id);
+  requireUnique(snapshot.candidates, 'candidate', (record) => record.id);
+  requireUnique(snapshot.outbox ?? [], 'outbox', (record) => record.id);
+  requireUnique(snapshot.imports ?? [], 'import', (record) => record.contentHash);
+  requireUnique(snapshot.subscriptions, 'subscription', subscriptionKey);
+  for (const space of snapshot.spaces) validateSpace(space);
+  for (const subscription of snapshot.subscriptions) validateSubscription(subscription);
+  for (const episode of snapshot.episodes) validateEpisode(episode);
+  for (const fact of snapshot.facts) validateFact(fact);
+  for (const candidate of snapshot.candidates) validateCandidate(candidate);
+  for (const entry of snapshot.outbox ?? []) validateOutbox(entry);
+  for (const record of snapshot.imports ?? []) {
+    requireStrings(record, 'import', ['contentHash', 'sourcePath', 'importedAt']);
+  }
+  validateReferences(snapshot);
+}
+function validateSpace(space) {
+  requireStrings(space, 'space', ['id', 'name', 'kind']);
+  if (!Object.values(SpaceKind).includes(space.kind)) {
+    throw new TypeError(`Invalid space kind: ${space.kind}`);
+  }
+  nullableString(space, 'description');
+  optionalString(space, 'createdAt');
+}
+
+function validateSubscription(subscription) {
+  requireStrings(subscription, 'subscription', ['personalSpaceId', 'spaceId']);
+  optionalString(subscription, 'mode');
+  optionalString(subscription, 'createdAt');
+}
+
+function validateEpisode(episode) {
+  requireStrings(episode, 'episode', ['id', 'spaceId', 'sourceKind', 'body']);
+  nullableString(episode, 'sourceUri');
+  optionalString(episode, 'createdAt');
+}
+
+function validateFact(fact) {
+  requireStrings(fact, 'fact', ['id', 'spaceId', 'subject', 'predicate', 'object', 'sourceEpisodeId']);
+  optionalString(fact, 'validAt');
+  nullableString(fact, 'invalidAt');
+  nullableString(fact, 'replacedByFactId');
+  validateFactRecord({
+    ...fact,
+    status: fact.status ?? FactStatus.CONFIRMED,
+    confidence: fact.confidence ?? 1,
+    sensitivity: fact.sensitivity ?? 'normal',
+    scope: fact.scope ?? 'personal'
+  });
+}
+
+function validateCandidate(candidate) {
+  requireStrings(candidate, 'candidate', ['id', 'personalSpaceId', 'episodeId', 'reason']);
+  nullableString(candidate, 'targetSpaceId');
+  optionalString(candidate, 'createdAt');
+  nullableString(candidate, 'decidedAt');
+  validateCandidateRecord({ ...candidate, status: candidate.status ?? CandidateStatus.PENDING });
+}
+
+function validateOutbox(entry) {
+  requireStrings(entry, 'outbox', ['id', 'kind', 'aggregateId']);
+  optionalString(entry, 'createdAt');
+  nullableString(entry, 'nextAttemptAt');
+  nullableString(entry, 'sentAt');
+  nullableString(entry, 'lastError');
+  validateOutboxRecord({ ...entry, status: entry.status ?? 'pending', attempts: entry.attempts ?? 0 });
+}
+
+function validateReferences(snapshot) {
+  const spaces = ids(snapshot.spaces);
+  const episodes = ids(snapshot.episodes);
+  const facts = ids(snapshot.facts);
+  for (const subscription of snapshot.subscriptions) {
+    requireReference(spaces, subscription.personalSpaceId, 'Subscription references missing personal space');
+    requireReference(spaces, subscription.spaceId, 'Subscription references missing space');
+  }
+  for (const episode of snapshot.episodes) {
+    requireReference(spaces, episode.spaceId, `Episode ${episode.id} references missing space`);
+  }
+  for (const fact of snapshot.facts) {
+    requireReference(spaces, fact.spaceId, `Fact ${fact.id} references missing space`);
+    requireReference(episodes, fact.sourceEpisodeId, `Fact ${fact.id} references missing episode`);
+    if (fact.replacedByFactId) {
+      requireReference(facts, fact.replacedByFactId, `Fact ${fact.id} references missing replacement fact`);
+    }
+  }
+  for (const candidate of snapshot.candidates) {
+    requireReference(spaces, candidate.personalSpaceId, `Candidate ${candidate.id} references missing personal space`);
+    if (candidate.targetSpaceId) {
+      requireReference(spaces, candidate.targetSpaceId, `Candidate ${candidate.id} references missing target space`);
+    }
+    requireReference(episodes, candidate.episodeId, `Candidate ${candidate.id} references missing episode`);
+  }
+}
+
+function requireUnique(records, label, identifier) {
+  const seen = new Set();
+  for (const record of records) {
+    const value = identifier(record);
+    if (typeof value !== 'string' || value.length === 0) throw new TypeError(`${label} id must be a nonempty string`);
+    if (seen.has(value)) {
+      const suffix = label === 'subscription' || label.endsWith('name')
+        ? `: ${value}`
+        : ` id: ${value}`;
+      throw new Error(`Duplicate ${label}${suffix}`);
+    }
+    seen.add(value);
+  }
+}
+
+function requireStrings(record, label, fields) {
+  for (const field of fields) {
+    if (typeof record[field] !== 'string' || record[field].length === 0) {
+      throw new TypeError(`${label} ${field} must be a nonempty string`);
+    }
+  }
+}
+
+function optionalString(record, field) {
+  if (record[field] !== undefined && typeof record[field] !== 'string') {
+    throw new TypeError(`${field} must be a string when provided`);
+  }
+}
+
+function nullableString(record, field) {
+  if (record[field] !== undefined && record[field] !== null && typeof record[field] !== 'string') {
+    throw new TypeError(`${field} must be a string or null`);
+  }
+}
+
+function subscriptionKey(record) {
+  return `${record.personalSpaceId} -> ${record.spaceId}`;
+}
+
+function requireReference(validIds, id, message) {
+  if (!validIds.has(id)) throw new Error(`${message}: ${id}`);
+}
+
+function ids(records) {
+  return new Set(records.map((record) => record.id));
+}