fuli-context 0.4.0 → 0.7.2

package/src/lens/lens-correction-service.js

@@ -1,81 +0,0 @@
-import { nowIso, FactScope, FactStatus, isCurrentFact } from '../models.js';
-import { ApplicationError, ApplicationErrorCode } from '../app/application-error.js';
-import { assertStorePort } from '../storage/store-port.js';
-import { writePersonalFact } from './lens-fact-writer.js';
-import { assertSafeLensTexts, requirePersonalSpace } from './lens-input.js';
-
-const ACTIONS = new Set(['replace', 'reject', 'deprecate']);
-const CORRECTABLE_STATUSES = new Set([
-  FactStatus.CONFIRMED,
-  FactStatus.OBSERVED,
-  FactStatus.SUGGESTED
-]);
-const IMMEDIATE = { mode: 'immediate' };
-
-export class LensCorrectionService {
-  constructor(store) {
-    assertStorePort(store);
-    this.store = store;
-  }
-
-  correctUserFact({ personalSpaceId, factId, action, value, sourceText, sourceKind = 'correction' }) {
-    if (!ACTIONS.has(action)) {
-      throw new ApplicationError(ApplicationErrorCode.VALIDATION, `Unknown correction action: ${action}`);
-    }
-
-    requirePersonalSpace(this.store, personalSpaceId);
-    assertSafeLensTexts([sourceText]);
-    if (action === 'replace') assertSafeLensTexts([value]);
-
-    const original = this.#requireCurrentFact(personalSpaceId, factId);
-    if (action === 'replace') assertSafeLensTexts([original.subject, original.predicate]);
-
-    return this.store.transaction(() => {
-      requirePersonalSpace(this.store, personalSpaceId);
-      const current = this.#requireCurrentFact(personalSpaceId, factId);
-      assertSafeLensTexts([sourceText]);
-      if (action === 'replace') assertSafeLensTexts([current.subject, current.predicate, value]);
-
-      const episode = this.store.addEpisode(
-        personalSpaceId,
-        sourceKind,
-        sourceText,
-        null,
-        { kind: 'lens_correction', factId: current.id, action }
-      );
-
-      if (action === 'replace') {
-        const fact = writePersonalFact(this.store, {
-          spaceId: personalSpaceId,
-          subject: current.subject,
-          predicate: current.predicate,
-          object: value,
-          sourceEpisodeId: episode.id,
-          status: FactStatus.CONFIRMED,
-          sensitivity: current.sensitivity,
-          confidence: current.confidence,
-          scope: FactScope.PERSONAL
-        });
-        this.store.invalidateFact(current.id, fact.id);
-        return { episode, fact, replacedFact: this.store.getFact(current.id) };
-      }
-
-      const fact = this.store.updateFact(current.id, {
-        status: action === 'reject' ? FactStatus.REJECTED : FactStatus.DEPRECATED,
-        invalidAt: nowIso()
-      });
-      return { episode, fact };
-    }, IMMEDIATE);
-  }
-
-  #requireCurrentFact(personalSpaceId, factId) {
-    const fact = this.store.getFact(factId);
-    if (!fact || fact.spaceId !== personalSpaceId || fact.scope !== FactScope.PERSONAL) {
-      throw new ApplicationError(ApplicationErrorCode.NOT_FOUND, `Lens fact not found: ${factId}`);
-    }
-    if (!isCurrentFact(fact) || !CORRECTABLE_STATUSES.has(fact.status)) {
-      throw new ApplicationError(ApplicationErrorCode.VALIDATION, `Lens fact is not current: ${factId}`);
-    }
-    return fact;
-  }
-}

package/src/lens/lens-fact-writer.js

@@ -1,85 +0,0 @@
-import { FactScope, FactStatus } from '../models.js';
-
-const STATUS_RANK = Object.freeze({
-  [FactStatus.SUGGESTED]: 1,
-  [FactStatus.OBSERVED]: 2,
-  [FactStatus.CONFIRMED]: 3
-});
-
-export function writePersonalFact(store, input) {
-  const equivalent = equivalentCurrentFacts(store, input);
-  const fact = store.addFact({
-    spaceId: input.spaceId,
-    subject: input.subject,
-    predicate: input.predicate,
-    object: input.object,
-    sourceEpisodeId: input.sourceEpisodeId,
-    status: input.status,
-    confidence: input.confidence,
-    sensitivity: input.sensitivity,
-    scope: FactScope.PERSONAL
-  });
-  const candidates = [...equivalent, fact];
-  const winner = candidates.reduce(strongerOrLater);
-  for (const candidate of candidates) {
-    if (candidate.id !== winner.id) store.invalidateFact(candidate.id, winner.id);
-  }
-  return store.getFact(fact.id);
-}
-
-export function writePersonalFactSpecs(store, input) {
-  const facts = [];
-  for (const spec of input.specs) {
-    if (spec.kind === 'replacement') {
-      facts.push(...writeReplacement(store, input, spec));
-      continue;
-    }
-    facts.push(writePersonalFact(store, {
-      ...input,
-      subject: spec.subject ?? input.subject,
-      predicate: spec.predicate,
-      object: spec.object,
-      status: FactStatus.CONFIRMED
-    }));
-  }
-  return facts;
-}
-
-function writeReplacement(store, input, spec) {
-  const subject = spec.subject ?? input.subject;
-  const oldFacts = store.currentFacts(input.spaceId).filter(
-    (fact) => fact.subject === subject && fact.object === spec.oldValue
-  );
-  const predicates = oldFacts.length
-    ? [...new Set(oldFacts.map((fact) => fact.predicate))]
-    : ['has_replacement'];
-  return predicates.map((predicate) => {
-    const fact = writePersonalFact(store, {
-      ...input,
-      subject,
-      predicate,
-      object: spec.newValue,
-      status: FactStatus.CONFIRMED
-    });
-    for (const previous of oldFacts.filter((item) => item.predicate === predicate)) {
-      store.invalidateFact(previous.id, fact.id);
-    }
-    return fact;
-  });
-}
-
-function equivalentCurrentFacts(store, input) {
-  return store.currentFacts(input.spaceId).filter((fact) =>
-    fact.subject === input.subject &&
-    fact.predicate === input.predicate &&
-    fact.object === input.object
-  );
-}
-
-function strongerOrLater(current, candidate) {
-  return rank(candidate.status) >= rank(current.status) ? candidate : current;
-}
-
-function rank(status) {
-  return STATUS_RANK[status] ?? 0;
-}

package/src/lens/lens-input.js

@@ -1,62 +0,0 @@
-import { ApplicationError, ApplicationErrorCode } from '../app/application-error.js';
-import { Sensitivity, SpaceKind } from '../models.js';
-import { detectSensitiveContent } from '../security/sensitive-content.js';
-
-export function validateLensWriteInput(
-  store,
-  { personalSpaceId, texts, sensitivity, confidence }
-) {
-  requirePersonalSpace(store, personalSpaceId);
-  assertSafeLensTexts(texts);
-  if (!Object.values(Sensitivity).includes(sensitivity)) {
-    throw new ApplicationError(
-      ApplicationErrorCode.VALIDATION,
-      `Invalid sensitivity: ${sensitivity}`
-    );
-  }
-  if (
-    typeof confidence !== 'number' ||
-    !Number.isFinite(confidence) ||
-    confidence < 0 ||
-    confidence > 1
-  ) {
-    throw new ApplicationError(
-      ApplicationErrorCode.VALIDATION,
-      'Confidence must be between 0 and 1'
-    );
-  }
-}
-
-export function requirePersonalSpace(store, spaceId) {
-  const space = store.getSpace(spaceId);
-  if (!space) {
-    throw new ApplicationError(
-      ApplicationErrorCode.NOT_FOUND,
-      `Personal space not found: ${spaceId}`
-    );
-  }
-  if (space.kind !== SpaceKind.PERSONAL) {
-    throw new ApplicationError(
-      ApplicationErrorCode.VALIDATION,
-      `Space is not personal: ${spaceId}`
-    );
-  }
-  return space;
-}
-
-export function assertSafeLensTexts(texts) {
-  for (const text of texts) {
-    if (typeof text !== 'string' || text.length === 0) {
-      throw new ApplicationError(
-        ApplicationErrorCode.VALIDATION,
-        'Lens text must be a nonempty string'
-      );
-    }
-    if (detectSensitiveContent(text).restricted) {
-      throw new ApplicationError(
-        ApplicationErrorCode.VALIDATION,
-        'Sensitive content is not allowed in Personal Lens'
-      );
-    }
-  }
-}

package/src/lens/lens-query-projection.js

@@ -1,87 +0,0 @@
-import { FactScope, FactStatus, isCurrentFact } from '../models.js';
-import { isRestrictedEpisode } from '../security/episode-visibility.js';
-import { isRestrictedFact } from '../security/fact-visibility.js';
-
-export function isInjectableFact(
-  fact,
-  { includeObserved, includeSuggested, includeRestricted }
-) {
-  if (fact.invalidAt) return false;
-  if (fact.status === FactStatus.CONFIRMED) return isVisibleFact(fact, includeRestricted);
-  if (fact.status === FactStatus.OBSERVED && includeObserved) {
-    return isVisibleFact(fact, includeRestricted);
-  }
-  if (fact.status === FactStatus.SUGGESTED && includeSuggested) {
-    return isVisibleFact(fact, includeRestricted);
-  }
-  return false;
-}
-
-export function isSearchableFact(fact, { includeHistorical, includeRestricted }) {
-  return (includeHistorical || isCurrentFact(fact)) && isVisibleFact(fact, includeRestricted);
-}
-
-export function buildCorrectionIndex(groups, personalSpaceId, includeRestricted) {
-  const index = new Map();
-  for (const group of groups) {
-    if (typeof group.factId !== 'string') continue;
-    const episodes = group.episodes.filter((episode) =>
-      episode.spaceId === personalSpaceId &&
-      episode.metadata?.kind === 'lens_correction' &&
-      episode.metadata?.factId === group.factId &&
-      (includeRestricted || !isRestrictedEpisode(episode))
-    );
-    index.set(group.factId, {
-      episodes,
-      truncated: group.truncated === true || episodes.length < group.episodes.length
-    });
-  }
-  return index;
-}
-
-export function projectSearchFact(
-  store,
-  fact,
-  evidenceEpisode,
-  personalSpaceId,
-  correctionIndex,
-  includeRestricted
-) {
-  const sourceEpisode = safePersonalEpisode(
-    evidenceEpisode,
-    personalSpaceId,
-    includeRestricted
-  );
-  const replacement = fact.replacedByFactId ? store.getFact(fact.replacedByFactId) : null;
-  const replacementFact = replacement?.spaceId === personalSpaceId &&
-    replacement.scope === FactScope.PERSONAL &&
-    isVisibleFact(replacement, includeRestricted)
-    ? replacement
-    : null;
-  return {
-    fact: projectSearchFactDto(fact, sourceEpisode, replacementFact),
-    current: isCurrentFact(fact),
-    sourceEpisode,
-    replacementFact,
-    correctionEpisodes: correctionIndex.get(fact.id)?.episodes ?? [],
-    correctionEpisodesTruncated: correctionIndex.get(fact.id)?.truncated ?? false
-  };
-}
-
-function projectSearchFactDto(fact, sourceEpisode, replacementFact) {
-  return {
-    ...fact,
-    sourceEpisodeId: sourceEpisode?.id ?? null,
-    replacedByFactId: replacementFact?.id ?? null
-  };
-}
-
-function isVisibleFact(fact, includeRestricted) {
-  return includeRestricted === true || !isRestrictedFact(fact);
-}
-
-export function safePersonalEpisode(episode, personalSpaceId, includeRestricted) {
-  if (!episode || episode.spaceId !== personalSpaceId) return null;
-  if (!includeRestricted && isRestrictedEpisode(episode)) return null;
-  return episode;
-}

package/src/lens/lens-query-ranking.js

@@ -1,62 +0,0 @@
-import { FactStatus } from '../models.js';
-
-export { compareSearchFacts } from '../storage/fact-search-order.js';
-
-export const BOUNDARY_PREDICATES = Object.freeze([
-  'has_boundary',
-  'has_access_boundary',
-  'does_not_want',
-  'avoids',
-  'forbids'
-]);
-export const BOUNDARY_PREFIXES = Object.freeze([
-  'boundary_',
-  'does_not_',
-  'avoids_',
-  'forbids_',
-  'must_not_'
-]);
-
-const STATUS_RANK = Object.freeze({
-  [FactStatus.SUGGESTED]: 1,
-  [FactStatus.OBSERVED]: 2,
-  [FactStatus.CONFIRMED]: 3
-});
-
-export function taskTokens(task) {
-  return new Set(normalizedTokens(task));
-}
-
-export function compareLensFacts(left, right, terms) {
-  return compareNumber(isBoundary(right), isBoundary(left)) ||
-    compareNumber(termMatches(right, terms), termMatches(left, terms)) ||
-    compareNumber(STATUS_RANK[right.status] ?? 0, STATUS_RANK[left.status] ?? 0) ||
-    compareText(right.validAt, left.validAt) ||
-    compareText(left.id, right.id);
-}
-
-function termMatches(fact, terms) {
-  const factTokens = new Set(normalizedTokens(`${fact.subject} ${fact.predicate} ${fact.object}`));
-  let matches = 0;
-  for (const term of terms) if (factTokens.has(term)) matches += 1;
-  return matches;
-}
-
-function normalizedTokens(text) {
-  return String(text).normalize('NFKC').toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
-}
-
-function isBoundary(fact) {
-  return BOUNDARY_PREDICATES.includes(fact.predicate) ||
-    BOUNDARY_PREFIXES.some((prefix) => fact.predicate.startsWith(prefix));
-}
-
-function compareNumber(left, right) {
-  return left - right;
-}
-
-function compareText(left, right) {
-  const first = String(left ?? '');
-  const second = String(right ?? '');
-  return first === second ? 0 : (first < second ? -1 : 1);
-}

package/src/lens/lens-query.js

@@ -1,143 +0,0 @@
-import { ApplicationError, ApplicationErrorCode } from '../app/application-error.js';
-import { FactScope } from '../models.js';
-import { requirePersonalSpace } from './lens-input.js';
-import {
-  BOUNDARY_PREDICATES,
-  BOUNDARY_PREFIXES,
-  compareLensFacts,
-  taskTokens
-} from './lens-query-ranking.js';
-import {
-  isInjectableFact,
-  projectSearchFact,
-  safePersonalEpisode
-} from './lens-query-projection.js';
-import { LensSearchQuery } from './lens-search-query.js';
-
-export { BOUNDARY_PREDICATES, BOUNDARY_PREFIXES };
-export {
-  DEFAULT_SEARCH_USER_CONTEXT_LIMIT,
-  MAX_SEARCH_USER_CONTEXT_LIMIT
-} from './lens-search-query.js';
-
-export class LensQuery extends LensSearchQuery {
-  getUserLens(input) {
-    return this.#getUserLens(input, true);
-  }
-
-  #getUserLens({
-    personalSpaceId,
-    task,
-    budget,
-    includeObserved = true,
-    includeSuggested = false,
-    includeRestricted = false
-  }, redactRelations) {
-    requirePersonalSpace(this.store, personalSpaceId);
-    validateTask(task);
-    validateBudget(budget);
-
-    const terms = taskTokens(task);
-    const allowRestricted = includeRestricted === true;
-    const facts = this.store.currentFacts(personalSpaceId)
-      .filter((fact) => fact.spaceId === personalSpaceId && fact.scope === FactScope.PERSONAL)
-      .filter((fact) => isInjectableFact(fact, {
-        includeObserved,
-        includeSuggested,
-        includeRestricted: allowRestricted
-      }))
-      .sort((left, right) => compareLensFacts(left, right, terms));
-    const selected = [];
-    const lines = [];
-    let bytes = 0;
-
-    for (const fact of facts) {
-      const line = formatFactLine(fact);
-      const nextBytes = bytes + (lines.length ? 1 : 0) + Buffer.byteLength(line, 'utf8');
-      if (nextBytes > budget) continue;
-      selected.push(fact);
-      lines.push(line);
-      bytes = nextBytes;
-    }
-
-    return {
-      personalSpaceId,
-      task,
-      text: lines.join('\n'),
-      facts: redactRelations
-        ? selected.map((fact) => {
-          const source = this.store.episodeEvidencePreview(
-            personalSpaceId,
-            fact.sourceEpisodeId,
-            { includeRestricted: allowRestricted, maxBodyBytes: 0 }
-          );
-          return projectSearchFact(
-            this.store,
-            fact,
-            source,
-            personalSpaceId,
-            new Map(),
-            allowRestricted
-          ).fact;
-        })
-        : selected,
-      estimatedTokens: bytes,
-      truncated: selected.length < facts.length
-    };
-  }
-
-  getUserLensView(input) {
-    return this.store.transaction(() => {
-      const lens = this.#getUserLens(input, false);
-      const entries = [];
-      for (const fact of lens.facts) {
-        const source = safePersonalEpisode(
-          this.store.episodeEvidencePreview(
-            lens.personalSpaceId,
-            fact.sourceEpisodeId,
-            { includeRestricted: input.includeRestricted === true, maxBodyBytes: 0 }
-          ),
-          lens.personalSpaceId,
-          input.includeRestricted === true
-        );
-        if (source) entries.push(projectLensViewEntry(fact, source));
-      }
-      return {
-        entries,
-        truncated: lens.truncated || entries.length < lens.facts.length
-      };
-    });
-  }
-
-}
-
-function validateTask(task) {
-  if (typeof task !== 'string') {
-    throw new ApplicationError(ApplicationErrorCode.VALIDATION, 'Task must be a string');
-  }
-}
-
-function validateBudget(budget) {
-  if (!Number.isInteger(budget) || budget <= 0) {
-    throw new ApplicationError(ApplicationErrorCode.VALIDATION, 'Budget must be a positive integer');
-  }
-}
-
-function formatFactLine(fact) {
-  return `${fact.subject} ${fact.predicate} ${fact.object} (${fact.status})`;
-}
-
-function projectLensViewEntry(fact, source) {
-  return {
-    subject: fact.subject,
-    predicate: fact.predicate,
-    object: fact.object,
-    status: fact.status,
-    validAt: fact.validAt,
-    source: {
-      kind: source.sourceKind,
-      uri: source.sourceUri,
-      createdAt: source.createdAt
-    }
-  };
-}

package/src/lens/lens-resource-projection.js

@@ -1,93 +0,0 @@
-import { detectSensitiveContent } from '../security/sensitive-content.js';
-
-export function projectCurrentFact(fact) {
-  return compactFact(fact);
-}
-
-export function isSafeResourceFact(fact) {
-  return compactFact(fact) !== null;
-}
-
-export function projectHistoryItem(item) {
-  const fact = compactFact(item.fact);
-  if (!fact) return null;
-  return {
-    current: item.current,
-    fact,
-    source: compactEpisode(item.sourceEpisode),
-    replacementFact: compactFact(item.replacementFact),
-    correctionEpisodes: item.correctionEpisodes.map(compactCorrection).filter(Boolean)
-  };
-}
-
-export function projectSubscription(subscription, space) {
-  if (![
-    space?.id,
-    space?.name,
-    space?.kind,
-    subscription?.mode,
-    subscription?.createdAt
-  ].every(isSafeResourceText)) return null;
-  const compactSpace = { id: space.id, name: space.name, kind: space.kind };
-  if (isSafeResourceText(space.description)) {
-    compactSpace.description = space.description;
-  }
-  return {
-    space: compactSpace,
-    mode: subscription.mode,
-    createdAt: subscription.createdAt
-  };
-}
-
-function compactFact(fact) {
-  if (!fact || ![
-    fact.id,
-    fact.subject,
-    fact.predicate,
-    fact.object,
-    fact.status,
-    fact.validAt
-  ].every(isSafeResourceText)) return null;
-  if (!Number.isFinite(fact.confidence) || fact.confidence < 0 || fact.confidence > 1) {
-    return null;
-  }
-  return {
-    id: fact.id,
-    subject: fact.subject,
-    predicate: fact.predicate,
-    object: fact.object,
-    status: fact.status,
-    confidence: fact.confidence,
-    validAt: fact.validAt
-  };
-}
-
-function compactEpisode(episode) {
-  if (!episode) return null;
-  if (![
-    episode.id,
-    episode.sourceKind,
-    episode.createdAt
-  ].every(isSafeResourceText)) return null;
-  if (!isSafeResourceText(episode.sourceUri, { nullable: true })) return null;
-  return {
-    id: episode.id,
-    kind: episode.sourceKind,
-    uri: episode.sourceUri,
-    createdAt: episode.createdAt
-  };
-}
-
-function compactCorrection(episode) {
-  const compact = compactEpisode(episode);
-  if (!compact || !isSafeResourceText(episode.metadata?.action)) return null;
-  return {
-    ...compact,
-    action: episode.metadata.action
-  };
-}
-
-export function isSafeResourceText(value, { nullable = false } = {}) {
-  if (value === null || value === undefined) return nullable;
-  return typeof value === 'string' && !detectSensitiveContent(value).restricted;
-}

package/src/lens/lens-resource-selection.js

@@ -1,45 +0,0 @@
-const EMPTY_ARRAY_BYTES = 2;
-const HISTORY_ENVELOPE_RESERVE_BYTES = 1024;
-
-export function selectCurrentFacts(facts, budgetBytes) {
-  const selected = [];
-  const lines = [];
-  let bytes = 0;
-  for (const fact of facts) {
-    const line = `${fact.subject} ${fact.predicate} ${fact.object} (${fact.status})`;
-    const nextBytes = bytes + (lines.length ? 1 : 0) + Buffer.byteLength(line, 'utf8');
-    if (nextBytes > budgetBytes) continue;
-    selected.push(fact);
-    lines.push(line);
-    bytes = nextBytes;
-  }
-  return {
-    facts: selected,
-    text: lines.join('\n'),
-    truncated: selected.length < facts.length
-  };
-}
-
-export function selectHistoryItems(items, { limit, budgetBytes }) {
-  const selected = [];
-  const itemsBudget = budgetBytes - HISTORY_ENVELOPE_RESERVE_BYTES;
-  let itemsBytes = EMPTY_ARRAY_BYTES;
-  let truncated = false;
-
-  for (const item of items) {
-    if (selected.length >= limit) {
-      truncated = true;
-      break;
-    }
-    const itemBytes = Buffer.byteLength(JSON.stringify(item), 'utf8');
-    const nextItemsBytes = itemsBytes + (selected.length ? 1 : 0) + itemBytes;
-    if (nextItemsBytes > itemsBudget) {
-      truncated = true;
-      continue;
-    }
-    selected.push(item);
-    itemsBytes = nextItemsBytes;
-  }
-
-  return { items: selected, itemsBytes, truncated };
-}