fuli-context 0.2.0

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

@@ -0,0 +1,52 @@
+import { randomUUID } from 'node:crypto';
+
+import { nowIso } from '../../models.js';
+import { mapSpace } from './mapper.js';
+
+export class SpacesRepository {
+  constructor(db) {
+    this.insertStatement = db.prepare(`
+      INSERT INTO spaces (id, name, kind, description, created_at)
+      VALUES (@id, @name, @kind, @description, @createdAt)
+    `);
+    this.listStatement = db.prepare('SELECT * FROM spaces ORDER BY rowid');
+    this.findByNameStatement = db.prepare('SELECT * FROM spaces WHERE name = ?');
+    this.getStatement = db.prepare('SELECT * FROM spaces WHERE id = ?');
+    this.deleteStatement = db.prepare('DELETE FROM spaces');
+  }
+
+  create(name, kind, description = null) {
+    const existing = this.findByName(name);
+    if (existing) return existing;
+
+    const space = {
+      id: randomUUID(),
+      name,
+      kind,
+      description,
+      createdAt: nowIso()
+    };
+    this.insertStatement.run(space);
+    return this.get(space.id);
+  }
+
+  list() {
+    return this.listStatement.all().map(mapSpace);
+  }
+
+  findByName(name) {
+    return mapSpace(this.findByNameStatement.get(name));
+  }
+
+  get(id) {
+    return mapSpace(this.getStatement.get(id));
+  }
+
+  insertSnapshot(space) {
+    this.insertStatement.run(space);
+  }
+
+  deleteAll() {
+    this.deleteStatement.run();
+  }
+}

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

@@ -0,0 +1,54 @@
+import { nowIso } from '../../models.js';
+import { mapSubscription } from './mapper.js';
+
+export class SubscriptionsRepository {
+  constructor(db) {
+    this.insertStatement = db.prepare(`
+      INSERT INTO subscriptions (personal_space_id, space_id, mode, created_at)
+      VALUES (@personalSpaceId, @spaceId, @mode, @createdAt)
+    `);
+    this.getStatement = db.prepare(`
+      SELECT * FROM subscriptions
+      WHERE personal_space_id = ? AND space_id = ?
+    `);
+    this.listStatement = db.prepare('SELECT * FROM subscriptions ORDER BY rowid');
+    this.forPersonalSpaceStatement = db.prepare(`
+      SELECT * FROM subscriptions WHERE personal_space_id = ? ORDER BY rowid
+    `);
+    this.deleteStatement = db.prepare('DELETE FROM subscriptions');
+  }
+
+  subscribe(personalSpaceId, spaceId, mode = 'latest') {
+    const existing = this.get(personalSpaceId, spaceId);
+    if (existing) return existing;
+
+    const subscription = {
+      personalSpaceId,
+      spaceId,
+      mode,
+      createdAt: nowIso()
+    };
+    this.insertStatement.run(subscription);
+    return this.get(personalSpaceId, spaceId);
+  }
+
+  list() {
+    return this.listStatement.all().map(mapSubscription);
+  }
+
+  forPersonalSpace(personalSpaceId) {
+    return this.forPersonalSpaceStatement.all(personalSpaceId).map(mapSubscription);
+  }
+
+  insertSnapshot(subscription) {
+    this.insertStatement.run(subscription);
+  }
+
+  deleteAll() {
+    this.deleteStatement.run();
+  }
+
+  get(personalSpaceId, spaceId) {
+    return mapSubscription(this.getStatement.get(personalSpaceId, spaceId));
+  }
+}

package/src/storage/sqlite-store.js

@@ -0,0 +1,159 @@
+import { configureDatabase, runMigrations } from './migrate.js';
+import { CandidatesRepository } from './sqlite/candidates-repository.js';
+import { EpisodeEvidenceRepository } from './sqlite/episode-evidence-repository.js';
+import { registerEpisodePrivacyFunction } from './sqlite/episode-privacy-sql.js';
+import { EpisodesRepository } from './sqlite/episodes-repository.js';
+import { FactsRepository } from './sqlite/facts-repository.js';
+import { ImportsRepository } from './sqlite/imports-repository.js';
+import { OutboxRepository } from './sqlite/outbox-repository.js';
+import { openDatabase } from './sqlite/open-database.js';
+import { SnapshotRepository } from './sqlite/snapshot-repository.js';
+import { SpacesRepository } from './sqlite/spaces-repository.js';
+import { SubscriptionsRepository } from './sqlite/subscriptions-repository.js';
+
+export class SqliteStore {
+  #db;
+  #repositories;
+  #schemaVersionsStatement;
+  #transactionActive = false;
+
+  constructor(filePath = '.fuli/context.db') {
+    this.#db = openDatabase(filePath);
+    try {
+      configureDatabase(this.#db, filePath);
+      runMigrations(this.#db);
+      this.#repositories = createRepositories(this.#db);
+      this.#schemaVersionsStatement = this.#db.prepare(`
+        SELECT version FROM schema_migrations ORDER BY version
+      `);
+    } catch (error) {
+      this.#db.close();
+      throw error;
+    }
+  }
+
+  transaction(fn, { mode = 'default' } = {}) {
+    if (this.#transactionActive) {
+      throw new TypeError('Nested SqliteStore transactions are not supported');
+    }
+    if (fn.constructor?.name === 'AsyncFunction') {
+      throw new TypeError('Transaction callback must be synchronous');
+    }
+
+    this.#transactionActive = true;
+    try {
+      const transaction = this.#db.transaction(() => {
+        const result = fn(this);
+        if (isThenable(result)) {
+          if (typeof result.catch === 'function') result.catch(() => {});
+          throw new TypeError('Transaction callback must be synchronous');
+        }
+        return result;
+      });
+      const run = mode === 'immediate' ? transaction.immediate : transaction;
+      if (typeof run !== 'function') throw new TypeError(`Unsupported transaction mode: ${mode}`);
+      return run();
+    } finally {
+      this.#transactionActive = false;
+    }
+  }
+
+  createSpace(name, kind, description = null) {
+    return this.#repositories.spaces.create(name, kind, description);
+  }
+
+  listSpaces() { return this.#repositories.spaces.list(); }
+  findSpaceByName(name) { return this.#repositories.spaces.findByName(name); }
+  getSpace(id) { return this.#repositories.spaces.get(id); }
+
+  subscribe(personalSpaceId, spaceId, mode = 'latest') {
+    return this.#repositories.subscriptions.subscribe(personalSpaceId, spaceId, mode);
+  }
+
+  listSubscriptions() { return this.#repositories.subscriptions.list(); }
+  subscriptionsFor(personalSpaceId) {
+    return this.#repositories.subscriptions.forPersonalSpace(personalSpaceId);
+  }
+
+  addEpisode(spaceId, sourceKind, body, sourceUri = null, metadata = {}) {
+    return this.#repositories.episodes.add(spaceId, sourceKind, body, sourceUri, metadata);
+  }
+
+  getEpisode(id) { return this.#repositories.episodes.get(id); }
+  listEpisodes() { return this.#repositories.episodes.list(); }
+  episodeEvidencePreview(spaceId, episodeId, options = {}) {
+    return this.#repositories.episodeEvidence.source(spaceId, episodeId, options);
+  }
+  correctionEpisodeEvidencePreviews(spaceId, factIds, options = {}) {
+    return this.#repositories.episodeEvidence.corrections(spaceId, factIds, options);
+  }
+  addFact(fact) { return this.#repositories.facts.add(fact); }
+  getFact(id) { return this.#repositories.facts.get(id); }
+  updateFact(id, updates) { return this.#repositories.facts.update(id, updates); }
+  invalidateFact(id, replacedByFactId = null) {
+    return this.#repositories.facts.invalidate(id, replacedByFactId);
+  }
+
+  currentFacts(spaceId) { return this.#repositories.facts.current(spaceId); }
+  listFacts(options = {}) { return this.#repositories.facts.list(options); }
+  timeline(spaceId, subject) { return this.#repositories.facts.timeline(spaceId, subject); }
+  searchFacts(spaceIds, query, options = {}) {
+    return this.#repositories.facts.search(spaceIds, query, options);
+  }
+  searchFactsPage(spaceIds, query, options = {}) {
+    return this.#repositories.facts.searchPage(spaceIds, query, options);
+  }
+
+  addCandidate(candidate) { return this.#repositories.candidates.add(candidate); }
+  getCandidate(id) { return this.#repositories.candidates.get(id); }
+  listCandidates() { return this.#repositories.candidates.list(); }
+  pendingCandidates(personalSpaceId) {
+    return this.#repositories.candidates.pending(personalSpaceId);
+  }
+
+  updateCandidateStatus(id, status) {
+    return this.#repositories.candidates.updateStatus(id, status);
+  }
+
+  enqueueOutbox(entry) { return this.#repositories.outbox.enqueue(entry); }
+  listPendingOutbox(at) { return this.#repositories.outbox.listPending(at); }
+  markOutboxSent(id, sentAt) { return this.#repositories.outbox.markSent(id, sentAt); }
+  markOutboxFailed(id, error, nextAttemptAt = null) {
+    return this.#repositories.outbox.markFailed(id, error, nextAttemptAt);
+  }
+
+  hasImport(contentHash) { return this.#repositories.imports.has(contentHash); }
+  recordImport(record) { return this.#repositories.imports.record(record); }
+  exportSnapshot() { return this.#repositories.snapshot.export(); }
+  importSnapshot(snapshot) { return this.#repositories.snapshot.import(snapshot); }
+
+  schemaVersions() {
+    return this.#schemaVersionsStatement.pluck().all();
+  }
+
+  close() {
+    if (this.#db.open) this.#db.close();
+  }
+}
+
+function createRepositories(db) {
+  registerEpisodePrivacyFunction(db);
+  const repositories = {
+    spaces: new SpacesRepository(db),
+    subscriptions: new SubscriptionsRepository(db),
+    episodes: new EpisodesRepository(db),
+    episodeEvidence: new EpisodeEvidenceRepository(db),
+    facts: new FactsRepository(db),
+    candidates: new CandidatesRepository(db),
+    outbox: new OutboxRepository(db),
+    imports: new ImportsRepository(db)
+  };
+  repositories.snapshot = new SnapshotRepository(db, repositories);
+  return repositories;
+}
+
+function isThenable(value) {
+  return value !== null &&
+    (typeof value === 'object' || typeof value === 'function') &&
+    typeof value.then === 'function';
+}

package/src/storage/stable-json.js

@@ -0,0 +1,24 @@
+export function stableJson(value) {
+  return JSON.stringify(sortJsonValue(value));
+}
+
+function sortJsonValue(value) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') {
+    if (Number.isFinite(value)) return value;
+    throw new TypeError('Snapshot must contain only finite JSON numbers');
+  }
+  if (Array.isArray(value)) return value.map(sortJsonValue);
+  if (isPlainObject(value)) {
+    return Object.fromEntries(
+      Object.keys(value).sort().map((key) => [key, sortJsonValue(value[key])])
+    );
+  }
+  throw new TypeError('Snapshot must contain only JSON values');
+}
+
+function isPlainObject(value) {
+  if (!value || typeof value !== 'object') return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}

package/src/storage/store-port.js

@@ -0,0 +1,20 @@
+export const STORE_METHODS = Object.freeze([
+  'transaction',
+  'createSpace', 'listSpaces', 'findSpaceByName', 'getSpace',
+  'subscribe', 'listSubscriptions', 'subscriptionsFor',
+  'addEpisode', 'getEpisode', 'listEpisodes',
+  'episodeEvidencePreview', 'correctionEpisodeEvidencePreviews',
+  'addFact', 'getFact', 'updateFact', 'invalidateFact',
+  'currentFacts', 'listFacts', 'timeline', 'searchFacts', 'searchFactsPage',
+  'addCandidate', 'getCandidate', 'listCandidates',
+  'pendingCandidates', 'updateCandidateStatus',
+  'enqueueOutbox', 'listPendingOutbox', 'markOutboxSent', 'markOutboxFailed',
+  'hasImport', 'recordImport',
+  'exportSnapshot', 'importSnapshot', 'close'
+]);
+
+export function assertStorePort(store) {
+  const missing = STORE_METHODS.filter((name) => typeof store?.[name] !== 'function');
+  if (missing.length) throw new TypeError(`Store Port missing: ${missing.join(', ')}`);
+  return store;
+}

package/src/store.js

@@ -0,0 +1,2 @@
+export { FileStore } from './storage/file-store.js';
+export { SqliteStore } from './storage/sqlite-store.js';

package/src/workspace-protocol/array-validation.js

@@ -0,0 +1,19 @@
+export function rejectDuplicateValues(
+  values,
+  context,
+  pathForIndex = (index) => [index],
+) {
+  const seen = new Set();
+
+  values.forEach((value, index) => {
+    if (seen.has(value)) {
+      context.addIssue({
+        code: 'custom',
+        path: pathForIndex(index),
+        message: 'Duplicate values are not allowed',
+      });
+    }
+
+    seen.add(value);
+  });
+}

package/src/workspace-protocol/base64url-contract.js

@@ -0,0 +1,27 @@
+import { Buffer } from 'node:buffer';
+
+import { z } from 'zod';
+
+export function createCanonicalBase64UrlSchema(byteLength) {
+  if (!Number.isSafeInteger(byteLength) || byteLength < 0) {
+    throw new TypeError('byteLength must be a non-negative safe integer');
+  }
+
+  const encodedLength = Math.ceil(byteLength * 4 / 3);
+
+  return z
+    .string()
+    .length(encodedLength)
+    .refine((value) => {
+      if (!/^[A-Za-z0-9_-]*$/u.test(value)) {
+        return false;
+      }
+
+      const decoded = Buffer.from(value, 'base64url');
+
+      return (
+        decoded.byteLength === byteLength
+        && decoded.toString('base64url') === value
+      );
+    });
+}

package/src/workspace-protocol/constants.js

@@ -0,0 +1,37 @@
+export const WORKSPACE_PROTOCOL_VERSION = '1';
+
+export const ProviderCapability = Object.freeze({
+  QUERY: 'query',
+  SYNC: 'sync',
+  PUBLISH: 'publish',
+  REVIEW: 'review',
+});
+
+export const WorkspaceVisibility = Object.freeze({
+  PUBLIC: 'public',
+  UNLISTED: 'unlisted',
+  PRIVATE: 'private',
+});
+
+export const WorkspaceRole = Object.freeze({
+  MEMBER: 'member',
+  MAINTAINER: 'maintainer',
+});
+
+export const ProposalStatus = Object.freeze({
+  EFFECTIVE: 'effective',
+  PENDING_REVIEW: 'pending_review',
+  REJECTED: 'rejected',
+});
+
+export const FactState = Object.freeze({
+  ACTIVE: 'active',
+  SUPERSEDED: 'superseded',
+  RETRACTED: 'retracted',
+  DISPUTED: 'disputed',
+});
+
+export const FactCertainty = Object.freeze({
+  CONFIRMED: 'confirmed',
+  KNOWN_UNKNOWN: 'known_unknown',
+});

package/src/workspace-protocol/error-contract.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+
+import { idSchema } from './scalar-contract.js';
+import { createPreservedSemanticTextSchema } from './text-contract.js';
+
+export const ProtocolErrorCode = Object.freeze({
+  AUTHENTICATION_REQUIRED: 'AUTHENTICATION_REQUIRED',
+  FORBIDDEN: 'FORBIDDEN',
+  NOT_FOUND: 'NOT_FOUND',
+  VALIDATION_FAILED: 'VALIDATION_FAILED',
+  IDEMPOTENCY_CONFLICT: 'IDEMPOTENCY_CONFLICT',
+  REVISION_CONFLICT: 'REVISION_CONFLICT',
+  CURSOR_EXPIRED: 'CURSOR_EXPIRED',
+  RATE_LIMITED: 'RATE_LIMITED',
+  PROVIDER_UNAVAILABLE: 'PROVIDER_UNAVAILABLE',
+  PROTOCOL_INCOMPATIBLE: 'PROTOCOL_INCOMPATIBLE',
+});
+
+export const protocolErrorResponseSchema = z.strictObject({
+  code: z.enum(Object.values(ProtocolErrorCode)),
+  message: createPreservedSemanticTextSchema(500),
+  traceId: idSchema,
+  retryAfterSeconds: z.number().int().min(1).max(86_400).optional(),
+});

package/src/workspace-protocol/fact-contract.js

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+
+import { rejectDuplicateValues } from './array-validation.js';
+import { FactCertainty, FactState } from './constants.js';
+import {
+  idSchema,
+  revisionSchema,
+  sha256Schema,
+  sourceUriSchema,
+  timestampSchema,
+} from './scalar-contract.js';
+import {
+  createPreservedContentTextSchema,
+  createPreservedSemanticTextSchema,
+} from './text-contract.js';
+
+export const sourceReferenceSchema = z.strictObject({
+  episodeId: idSchema,
+  kind: z.string().regex(/^[A-Za-z][A-Za-z0-9._-]{0,63}$/u),
+  uri: sourceUriSchema.nullable(),
+  capturedAt: timestampSchema,
+  contentHash: sha256Schema,
+});
+
+export const factProjectionSchema = z
+  .strictObject({
+    id: idSchema,
+    subject: createPreservedSemanticTextSchema(500),
+    predicate: createPreservedSemanticTextSchema(160),
+    object: createPreservedContentTextSchema(20_000),
+    state: z.enum(Object.values(FactState)),
+    certainty: z.enum(Object.values(FactCertainty)),
+    validFrom: timestampSchema,
+    validTo: timestampSchema.nullable(),
+    recordedAt: timestampSchema,
+    revision: revisionSchema,
+    sources: z.array(sourceReferenceSchema).min(1).max(20),
+    replaces: z.array(idSchema).max(50),
+    replacedBy: z.array(idSchema).max(50),
+  })
+  .superRefine((fact, context) => {
+    rejectDuplicateValues(
+      fact.sources.map(({ episodeId }) => episodeId),
+      context,
+      (index) => ['sources', index, 'episodeId'],
+    );
+    rejectDuplicateValues(
+      fact.replaces,
+      context,
+      (index) => ['replaces', index],
+    );
+    rejectDuplicateValues(
+      fact.replacedBy,
+      context,
+      (index) => ['replacedBy', index],
+    );
+
+    fact.replaces.forEach((id, index) => {
+      if (id === fact.id) {
+        context.addIssue({
+          code: 'custom',
+          path: ['replaces', index],
+          message: 'A fact cannot replace itself',
+        });
+      }
+    });
+
+    const replacedIds = new Set(fact.replaces);
+
+    fact.replacedBy.forEach((id, index) => {
+      if (id === fact.id) {
+        context.addIssue({
+          code: 'custom',
+          path: ['replacedBy', index],
+          message: 'A fact cannot be replaced by itself',
+        });
+      }
+
+      if (replacedIds.has(id)) {
+        context.addIssue({
+          code: 'custom',
+          path: ['replacedBy', index],
+          message: 'Replacement relationships cannot overlap',
+        });
+      }
+    });
+
+    if (
+      fact.validTo !== null
+      && Date.parse(fact.validTo) < Date.parse(fact.validFrom)
+    ) {
+      context.addIssue({
+        code: 'custom',
+        path: ['validTo'],
+        message: 'validTo cannot be earlier than validFrom',
+      });
+    }
+
+    const recordedAtEpoch = Date.parse(fact.recordedAt);
+
+    fact.sources.forEach(({ capturedAt }, index) => {
+      if (Date.parse(capturedAt) > recordedAtEpoch) {
+        context.addIssue({
+          code: 'custom',
+          path: ['sources', index, 'capturedAt'],
+          message: 'Source capture time cannot follow fact recording time',
+        });
+      }
+    });
+  });

package/src/workspace-protocol/governance-contract.js

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+
+import { idSchema, timestampSchema } from './scalar-contract.js';
+import { createPreservedSemanticTextSchema } from './text-contract.js';
+import { parseProtocolValue } from './validation.js';
+
+const semanticGovernanceTextSchema = createPreservedSemanticTextSchema(500);
+
+export const joinRequestSchema = z.strictObject({
+  requestId: idSchema,
+  workspaceId: idSchema,
+  requesterId: idSchema,
+  message: semanticGovernanceTextSchema.nullable(),
+  createdAt: timestampSchema,
+  status: z.enum(['pending', 'approved', 'rejected']),
+});
+
+export const joinDecisionSchema = z.strictObject({
+  decision: z.enum(['approve', 'reject']),
+  reason: semanticGovernanceTextSchema,
+});
+
+export const proposalDecisionSchema = z.strictObject({
+  decision: z.enum([
+    'accept_new',
+    'keep_current',
+    'keep_both',
+    'request_source',
+  ]),
+  reason: semanticGovernanceTextSchema,
+});
+
+export function parseJoinRequest(value) {
+  return parseProtocolValue(joinRequestSchema, value, 'Join request');
+}
+
+export function parseJoinDecision(value) {
+  return parseProtocolValue(joinDecisionSchema, value, 'Join decision');
+}
+
+export function parseProposalDecision(value) {
+  return parseProtocolValue(
+    proposalDecisionSchema,
+    value,
+    'Proposal decision',
+  );
+}

package/src/workspace-protocol/index.js

@@ -0,0 +1,53 @@
+export {
+  FactCertainty,
+  FactState,
+  ProposalStatus,
+  ProviderCapability,
+  WORKSPACE_PROTOCOL_VERSION,
+  WorkspaceRole,
+  WorkspaceVisibility,
+} from './constants.js';
+export {
+  parseProtocolValue,
+  ProtocolValidationError,
+} from './validation.js';
+export {
+  ProtocolErrorCode,
+  protocolErrorResponseSchema,
+} from './error-contract.js';
+export {
+  parseProviderManifest,
+  parseWorkspaceDescriptor,
+  providerManifestSchema,
+  workspaceDescriptorSchema,
+} from './manifest-contract.js';
+export {
+  factProjectionSchema,
+  sourceReferenceSchema,
+} from './fact-contract.js';
+export {
+  contextPackSchema,
+  parseContextPack,
+  parseWorkspaceQuery,
+  workspaceQuerySchema,
+} from './query-contract.js';
+export {
+  parsePublicationProposal,
+  parsePublicationResult,
+  publicationProposalSchema,
+  publicationResultSchema,
+  publicationSigningBytes,
+} from './publication-contract.js';
+export {
+  parseSyncPage,
+  syncPageSchema,
+  workspaceEventSchema,
+} from './sync-contract.js';
+export {
+  joinDecisionSchema,
+  joinRequestSchema,
+  parseJoinDecision,
+  parseJoinRequest,
+  parseProposalDecision,
+  proposalDecisionSchema,
+} from './governance-contract.js';

package/src/workspace-protocol/json-budget.js

@@ -0,0 +1,19 @@
+import { Buffer } from 'node:buffer';
+
+export function utf8JsonByteLength(value) {
+  return Buffer.byteLength(JSON.stringify(value), 'utf8');
+}
+
+export function refineUtf8JsonByteBudget(
+  value,
+  context,
+  maxBytes,
+  label,
+) {
+  if (utf8JsonByteLength(value) > maxBytes) {
+    context.addIssue({
+      code: 'custom',
+      message: `${label} exceeds the aggregate UTF-8 JSON byte budget`,
+    });
+  }
+}