Memory Layer — API Reference

interface IEntity extends ScopeFields {
  id: EntityId;                 // opaque string; typically "ent_<uuid>"
  type: string;                 // open string; see well-known types below
  displayName: string;          // human-readable primary name
  aliases?: string[];           // alternate display forms (NOT lookup keys)
  identifiers: Identifier[];    // lookup keys (uniqueness-bearing)
  metadata?: Record<string, unknown>;  // type-specific fields
  archived?: boolean;
  identityEmbedding?: number[]; // for semantic entity resolution (populated async)
  version: number;              // optimistic concurrency token
  createdAt: Date;
  updatedAt: Date;
  groupId?: string;             // from ScopeFields — group-scoped entity
  ownerId?: string;             // from ScopeFields — user-scoped entity
}

interface IFact extends ScopeFields {
  id: FactId;
  subjectId: EntityId;
  predicate: string;            // e.g. 'works_at', 'committed_to', 'profile'
  kind: 'atomic' | 'document';

  // Payload — atomic uses (objectId XOR value), document uses details.
  objectId?: EntityId;
  value?: unknown;
  details?: string;

  // Retrieval
  summaryForEmbedding?: string; // document kind: short gist, embedded in place of details
  embedding?: number[];         // populated async by the embedding queue
  isSemantic?: boolean;         // computed at write time; gates embedding eligibility

  // Quality + provenance
  confidence?: number;          // 0..1; default 1.0 for ranking
  sourceSignalId?: string;      // opaque signal reference (memory layer doesn't interpret)
  derivedBy?: string;           // rule-engine rule id if inferred

  // Salience
  importance?: number;          // 0..1; default 0.5. Ranking multiplier.

  // Multi-entity binding
  contextIds?: EntityId[];      // entities this fact is "about" beyond subject/object

  // Lifecycle
  supersedes?: FactId;          // predecessor id (archived when this fact is written)
  archived?: boolean;
  isAggregate?: boolean;        // $inc counters; never superseded

  // Temporal
  observedAt?: Date;
  validFrom?: Date;
  validUntil?: Date;

  metadata?: Record<string, unknown>;
  createdAt: Date;
  groupId?: string;
  ownerId?: string;
}

interface Identifier {
  kind: string;           // 'email' | 'slack_id' | 'phone' | 'domain' | 'github' | 'legal_name' | 'ticker' | ...
  value: string;          // the id itself; stored lowercase internally
  isPrimary?: boolean;    // optional display hint
  verified?: boolean;
  source?: string;        // which signal/source added it
  addedAt?: Date;
}

interface ScopeFields {
  groupId?: string;
  ownerId?: string;
}

interface ScopeFilter {
  groupId?: string;   // caller's group
  userId?: string;    // caller's user id
}

class MemorySystem implements IDisposable {
  constructor(config: MemorySystemConfig);
}

interface MemorySystemConfig {
  store: IMemoryStore;                         // required
  embedder?: IEmbedder;                         // optional; enables semantic search + identity embedding
  profileGenerator?: IProfileGenerator;         // optional; enables regenerateProfile + auto-regen
  ruleEngine?: IRuleEngine;                     // optional; enables deriveFactsFor
  profileRegenerationThreshold?: number;        // default 3 new atomic facts
  topFactsRanking?: RankingConfig;              // default half-life 90d, min confidence 0.2
  embeddingQueue?: EmbeddingQueueConfig;        // default concurrency 4, retries 3
  entityResolution?: EntityResolutionConfig;    // default threshold 0.90, minFuzzy 0.85, identityEmbedding enabled
  predicates?: PredicateRegistry;               // optional; canonicalization + defaults + auto-supersede (see below)
  predicateMode?: 'permissive' | 'strict';      // default 'permissive'; strict rejects unknowns
  predicateAutoSupersede?: boolean;             // default true; controls singleValued auto-supersede
  onChange?: (event: ChangeEvent) => void;      // fire-and-forget event hook
}

upsertEntity(
  input: Partial<IEntity> & {
    identifiers: Identifier[];   // may be empty array for projects/topics without external keys
    displayName: string;
    type: string;
  },
  scope: ScopeFilter,
): Promise<UpsertEntityResult>;

interface UpsertEntityResult {
  entity: IEntity;
  created: boolean;
  mergedIdentifiers: number;    // count of new identifiers added to existing entity
  mergeCandidates: EntityId[];  // other entities that matched by some identifiers
}

upsertEntityBySurface(
  input: UpsertBySurfaceInput,
  scope: ScopeFilter,
  opts?: UpsertBySurfaceOptions,
): Promise<UpsertBySurfaceResult>;

interface UpsertBySurfaceInput {
  surface: string;                   // raw text as extracted by LLM
  type: string;
  identifiers?: Identifier[];
  aliases?: string[];                // alternate forms spotted nearby
  contextEntityIds?: EntityId[];     // siblings in the extraction — for disambiguation
}

interface UpsertBySurfaceOptions {
  autoResolveThreshold?: number;     // override default (0.90)
}

interface UpsertBySurfaceResult {
  entity: IEntity;
  resolved: boolean;                 // true = matched existing, false = created new
  mergeCandidates: EntityCandidate[]; // near-matches for human review
}

resolveEntity(
  query: ResolveEntityQuery,
  scope: ScopeFilter,
  opts?: ResolveEntityOptions,
): Promise<EntityCandidate[]>;

interface ResolveEntityQuery {
  surface: string;
  type?: string;
  identifiers?: Identifier[];
  contextEntityIds?: EntityId[];
}

interface ResolveEntityOptions {
  limit?: number;        // default 5
  threshold?: number;    // default 0.5 (inclusive minimum confidence)
}

interface EntityCandidate {
  entity: IEntity;
  confidence: number;    // 0..1
  matchedOn: 'identifier' | 'displayName' | 'alias' | 'fuzzy' | 'embedding';
}

getEntity(id: EntityId, scope: ScopeFilter): Promise<IEntity | null>;

searchEntities(
  query: string,
  opts: { types?: string[]; limit?: number; cursor?: string },
  scope: ScopeFilter,
): Promise<Page<IEntity>>;

mergeEntities(winnerId: EntityId, loserId: EntityId, scope: ScopeFilter): Promise<IEntity>;

archiveEntity(id: EntityId, scope: ScopeFilter): Promise<void>;

deleteEntity(id: EntityId, scope: ScopeFilter, opts?: { hard?: boolean }): Promise<void>;

updateEntityMetadata(
  id: EntityId,
  patch: Record<string, unknown>,
  scope: ScopeFilter,
): Promise<IEntity>;

// Mark a task as done
await memory.updateEntityMetadata(taskId, { state: 'done', completedAt: new Date() }, scope);

addFact(
  input: Partial<IFact> & {
    subjectId: EntityId;
    predicate: string;
    kind: FactKind;
  },
  scope: ScopeFilter,
): Promise<IFact>;

addFacts(inputs: Array<...>, scope: ScopeFilter): Promise<IFact[]>;

supersedeFact(
  oldId: FactId,
  newInput: Partial<IFact> & { predicate: string; kind: FactKind; subjectId: EntityId },
  scope: ScopeFilter,
): Promise<IFact>;

archiveFact(id: FactId, scope: ScopeFilter): Promise<void>;

getContext(
  entityId: EntityId,
  opts: ContextOptions,
  scope: ScopeFilter,
): Promise<EntityView>;

interface ContextOptions {
  topFactsLimit?: number;              // default 15
  include?: ('documents' | 'semantic' | 'neighbors')[];
  tiers?: 'full' | 'minimal';          // default 'full' → includes relatedTasks + relatedEvents
  documentPredicates?: string[];       // filter document tier
  semanticQuery?: string;              // required for semantic tier
  semanticTopK?: number;               // default 5
  neighborPredicates?: string[];
  neighborDepth?: number;              // default 1
  asOf?: Date;                         // temporal view
  relatedTasksLimit?: number;          // default 15
  relatedEventsLimit?: number;         // default 15
  recentEventsWindowDays?: number;     // default 90
}

interface EntityView {
  entity: IEntity;
  profile: IFact | null;               // most-specific visible profile; null if none
  topFacts: IFact[];                   // subject OR object OR contextIds, ranked
  relatedTasks?: RelatedTask[];        // default-on (unless tiers:'minimal')
  relatedEvents?: RelatedEvent[];      // default-on (unless tiers:'minimal')
  documents?: IFact[];                 // if include: ['documents']
  semantic?: Array<{ fact: IFact; score: number }>;  // if include: ['semantic']
  neighbors?: Neighborhood;            // if include: ['neighbors']
}

interface RelatedTask { task: IEntity; role: string; }  // role: 'assigned_to' | 'reporter_of' | 'project_of' | 'context_of'
interface RelatedEvent { event: IEntity; role: string; when?: Date; }

getProfile(entityId: EntityId, scope: ScopeFilter): Promise<IFact | null>;

traverse(
  entityId: EntityId,
  opts: TraversalOptions,
  scope: ScopeFilter,
): Promise<Neighborhood>;

interface TraversalOptions {
  predicates?: string[];        // filter edge predicates
  direction: 'out' | 'in' | 'both';
  maxDepth: number;             // required hard bound
  limit?: number;               // max nodes returned
  asOf?: Date;
}

interface Neighborhood {
  nodes: Array<{ entity: IEntity; depth: number }>;
  edges: Array<{ fact: IFact; from: EntityId; to: EntityId; depth: number }>;
}

semanticSearch(
  query: string,
  filter: FactFilter,
  scope: ScopeFilter,
  topK?: number,    // default 5
): Promise<Array<{ fact: IFact; score: number }>>;

regenerateProfile(
  entityId: EntityId,
  targetScope: ScopeFields,
  trigger?: 'threshold' | 'manual',
): Promise<IFact>;

deriveFactsFor(entityId: EntityId, scope: ScopeFilter): Promise<IFact[]>;

flushEmbeddings(): Promise<void>;     // await all pending embedding jobs
pendingEmbeddings(): number;           // count of queued + in-flight

destroy(): void;                 // sync, idempotent; stops queue, rejects further ops
shutdown(): Promise<void>;       // flushes queue, then destroys; calls store.shutdown if present
isDestroyed: boolean;

// Input types — adapter assigns id + version + timestamps on create.
type NewEntity = Omit<IEntity, 'id' | 'version' | 'createdAt' | 'updatedAt'>;
type NewFact   = Omit<IFact,   'id' | 'createdAt'>;

interface IMemoryStore {
  // ===== Entities (required) =====
  createEntity(input: NewEntity): Promise<IEntity>;                      // returns with id populated
  createEntities(inputs: NewEntity[]): Promise<IEntity[]>;
  updateEntity(entity: IEntity): Promise<void>;                          // version must be stored+1
  getEntity(id: EntityId, scope: ScopeFilter): Promise<IEntity | null>;
  findEntitiesByIdentifier(kind: string, value: string, scope: ScopeFilter): Promise<IEntity[]>;
  searchEntities(query: string, opts: EntitySearchOptions, scope: ScopeFilter): Promise<Page<IEntity>>;
  listEntities(filter: EntityListFilter, opts: ListOptions, scope: ScopeFilter): Promise<Page<IEntity>>;
  archiveEntity(id: EntityId, scope: ScopeFilter): Promise<void>;
  deleteEntity(id: EntityId, scope: ScopeFilter): Promise<void>;

  // ===== Facts (required) =====
  createFact(input: NewFact): Promise<IFact>;                            // returns with id populated
  createFacts(inputs: NewFact[]): Promise<IFact[]>;
  getFact(id: FactId, scope: ScopeFilter): Promise<IFact | null>;
  findFacts(filter: FactFilter, opts: FactQueryOptions, scope: ScopeFilter): Promise<Page<IFact>>;
  updateFact(id: FactId, patch: Partial<IFact>, scope: ScopeFilter): Promise<void>;
  countFacts(filter: FactFilter, scope: ScopeFilter): Promise<number>;

  // ===== Graph (optional) =====
  traverse?(startId: EntityId, opts: TraversalOptions, scope: ScopeFilter): Promise<Neighborhood>;

  // ===== Vector (optional) =====
  semanticSearch?(
    queryVector: number[],
    filter: FactFilter,
    opts: SemanticSearchOptions,
    scope: ScopeFilter,
  ): Promise<Array<{ fact: IFact; score: number }>>;

  // ===== Lifecycle =====
  destroy(): void;
  shutdown?(): Promise<void>;
}

class InMemoryAdapter implements IMemoryStore {
  constructor(opts?: { entities?: IEntity[]; facts?: IFact[] });
}

class MongoMemoryAdapter implements IMemoryStore {
  constructor(opts: MongoMemoryAdapterOptions);
}

interface MongoMemoryAdapterOptions {
  entities: IMongoCollectionLike<IEntity>;
  facts: IMongoCollectionLike<IFact>;
  useNativeGraphLookup?: boolean;             // default false; requires facts.aggregate
  vectorIndexName?: string;                   // Atlas Vector Search index name
  vectorCandidateMultiplier?: number;         // default 10
  factsCollectionName?: string;               // required for useNativeGraphLookup
  defaultPageSize?: number;                   // default 100
}

interface IMongoCollectionLike<T extends { id: string }> {
  // Writes
  insertOne(doc: T): Promise<void>;
  insertMany(docs: T[]): Promise<void>;
  updateOne(filter, update, opts?): Promise<MongoUpdateResult>;
  deleteOne(filter): Promise<void>;
  deleteMany(filter): Promise<void>;
  bulkWrite?(ops): Promise<void>;

  // Reads
  findOne(filter, opts?): Promise<T | null>;
  find(filter, opts?): Promise<T[]>;
  countDocuments(filter): Promise<number>;
  aggregate?(pipeline): Promise<unknown[]>;

  // Index management
  createIndex?(spec, opts?): Promise<void>;

  // Transactions
  withTransaction?<R>(fn: () => Promise<R>): Promise<R>;
}

class RawMongoCollection<T> implements IMongoCollectionLike<T> {
  constructor(col: RawMongoDriverCollection<T>, client?: RawMongoClientLike);
}

class MeteorMongoCollection<T> implements IMongoCollectionLike<T> {
  constructor(col: MeteorCollectionLike<T>);
}

ensureIndexes(args: { entities; facts }): Promise<void>;

class EntityResolver {
  constructor(hooks: ResolverMemoryHooks, config?: EntityResolutionConfig);
  resolve(query, scope, opts?): Promise<EntityCandidate[]>;
  upsertBySurface(input, scope, opts?): Promise<UpsertBySurfaceResult>;
}

interface EntityResolutionConfig {
  autoResolveThreshold?: number;       // default 0.90 (conservative)
  minFuzzyRatio?: number;              // default 0.85
  enableIdentityEmbedding?: boolean;   // default true
}

function normalizedLevenshteinRatio(a: string, b: string): number;  // 0..1
function normalizeSurface(s: string): string;

function buildIdentityString(args: {
  type: string;
  displayName: string;
  aliases: string[];
  identifiers: Identifier[];
}): string;

class ConnectorEmbedder implements IEmbedder {
  constructor(config: ConnectorEmbedderConfig);
  static withProvider(args: { provider; model; dimensions; requestedDimensions? }): ConnectorEmbedder;
  readonly dimensions: number;
  embed(text): Promise<number[]>;
  embedBatch(texts): Promise<number[][]>;
}

interface ConnectorEmbedderConfig {
  connector: string;              // registered connector name
  model: string;                  // e.g. 'text-embedding-3-small'
  dimensions: number;             // matches model output (or MRL-reduced target)
  requestedDimensions?: number;   // passed to provider for MRL models
}

class ConnectorProfileGenerator implements IProfileGenerator {
  constructor(config: ConnectorProfileGeneratorConfig);
  static withAgent(args: { agent; promptTemplate?; temperature?; maxOutputTokens? }): ConnectorProfileGenerator;
  generate(input: ProfileGeneratorInput): Promise<{ details: string; summaryForEmbedding: string }>;
  destroy(): void;
}

interface ConnectorProfileGeneratorConfig {
  connector: string;
  model: string;                                     // e.g. 'claude-sonnet-4-6'
  promptTemplate?: (ctx: ProfileGeneratorInput) => string; // override defaultProfilePrompt
  temperature?: number;                              // default 0.3
  maxOutputTokens?: number;                          // default undefined (provider ceiling)
}

function createMemorySystemWithConnectors(
  config: MemorySystemWithConnectorsConfig,
): MemorySystem;

type MemorySystemWithConnectorsConfig = Omit<MemorySystemConfig, 'embedder' | 'profileGenerator'> & {
  connectors?: {
    embedding?: ConnectorEmbedderConfig;
    profile?: ConnectorProfileGeneratorConfig;
  };
};

function defaultProfilePrompt(ctx: ProfileGeneratorInput): string;

function defaultExtractionPrompt(ctx: ExtractionPromptContext): string;

interface ExtractionPromptContext {
  signalText?: string;
  signalThread?: SignalThreadMessage[];
  signalSourceDescription?: string;       // e.g. "email from john@acme.com"
  targetScope?: ScopeFields;
  knownEntities?: IEntity[];              // pre-loaded candidates to hint at
  referenceDate?: Date;                   // for relative dates like "next Friday"
  predicateRegistry?: PredicateRegistry;
  maxPredicatesPerCategory?: number;
  preResolvedBindings?: PreResolvedBinding[];
  extractableEntityTypes?: readonly string[];
  priorFacts?: IFact[];                   // enables reconciliation operations
  anchors?: Anchor[];
  eagerness?: EagernessProfile;
  anchorContextDescription?: string;
  negativeExamples?: Array<{ snippet: string; reason?: string }>;
  priorThreadContext?: Array<{ header: string; body: string }>;
  subjectOfHintsEnabled?: boolean;
}

class ExtractionResolver {
  constructor(memory: MemorySystem);

  resolveAndIngest(
    output: ExtractionOutput,
    sourceSignalId: string,
    scope: ScopeFilter,
    opts?: ExtractionResolverOptions,
  ): Promise<IngestionResult>;
}

interface ExtractionOutput {
  mentions: Record<string, ExtractionMention>;   // label → mention
  facts: ExtractionFactSpec[];
}

interface ExtractionMention {
  surface: string;
  type: string;
  identifiers?: Identifier[];
  aliases?: string[];
}

interface ExtractionFactSpec {
  subject: string;                         // mention label
  predicate: string;
  object?: string;                         // mention label (relational)
  value?: unknown;                         // attribute value
  details?: string;
  summaryForEmbedding?: string;
  confidence?: number;
  importance?: number;
  contextIds?: string[];                   // mention labels
  kind?: FactKind;                         // default 'atomic'
  validFrom?: string | Date;
  validUntil?: string | Date;
  observedAt?: string | Date;
}

interface IngestionResult {
  entities: Array<{
    label: string;
    entity: IEntity;
    resolved: boolean;
    mergeCandidates: EntityCandidate[];
  }>;
  facts: IFact[];
  mergeCandidates: Array<{
    label: string;
    surface: string;
    candidates: EntityCandidate[];
  }>;
  unresolved: Array<{ where: string; reason: string }>;
}

interface ExtractionResolverOptions {
  autoResolveThreshold?: number;
  preResolved?: Record<string, EntityId>;   // label → entity id
}

class SignalIngestor {
  constructor(config: SignalIngestorConfig);
  registerAdapter(adapter: SignalSourceAdapter<unknown>): this;
  hasAdapter(kind: string): boolean;
  ingest<TRaw>(input: IngestSignalInput<TRaw>): Promise<IngestionResult>;
  ingestText(input: IngestTextInput): Promise<IngestionResult>;
  ingestExtracted(input: IngestExtractedInput): Promise<IngestionResult>;
}

interface SignalSourceAdapter<TRaw = unknown> {
  readonly kind: string;
  extract(raw: TRaw): ExtractedSignal;
}

interface ExtractedSignal {
  signalText: string;
  signalSourceDescription?: string;
  participants: ParticipantSeed[];
}

interface ParticipantSeed {
  role: string;                    // 'from' | 'to' | 'cc' | 'author' | …
  identifiers: Identifier[];       // MUST be non-empty (strong only)
  displayName?: string;
  aliases?: string[];
  type?: string;                   // default 'person'
}

interface IExtractor {
  extract(prompt: string): Promise<ExtractionOutput>;
}

function scoreFact(fact: IFact, config: RankingConfig, now: Date): number;
function rankFacts(facts: IFact[], config: RankingConfig, now: Date): IFact[];

interface RankingConfig {
  predicateWeights?: Record<string, number>;     // default 1.0
  recencyHalfLifeDays?: number;                  // default 90
  minConfidence?: number;                        // default 0.2
}

interface PredicateDefinition {
  name: string;                         // canonical snake_case — the id
  description: string;
  category: string;                     // 'identity' | 'task' | 'communication' | …
  payloadKind?: 'relational' | 'attribute' | 'narrative';
  subjectTypes?: string[];
  objectTypes?: string[];
  inverse?: string;                     // e.g. reports_to ↔ manages
  aliases?: string[];                   // alternate surface forms → this
  defaultImportance?: number;           // 0..1
  rankingWeight?: number;               // default 1.0 in RankingConfig
  isAggregate?: boolean;                // updates in place; mutually exclusive with singleValued
  singleValued?: boolean;               // auto-supersede prior on new write
  examples?: string[];
}

class PredicateRegistry {
  static standard(): PredicateRegistry;                // 44-predicate starter set
  static empty(): PredicateRegistry;

  register(def: PredicateDefinition): this;
  registerAll(defs: PredicateDefinition[]): this;
  unregister(name: string): this;

  get(nameOrAlias: string): PredicateDefinition | null;
  has(nameOrAlias: string): boolean;

  canonicalize(input: string): string;

  list(filter?: { categories?: string[]; subjectType?: string }): PredicateDefinition[];
  categories(): string[];

  renderForPrompt(opts?: {
    categories?: string[];
    subjectType?: string;
    maxPerCategory?: number;                            // default 5
  }): string;

  toRankingWeights(base?: Record<string, number>): Record<string, number>;
}

import { MemorySystem, PredicateRegistry } from 'oneringai';

// Use the standard library as-is.
const memory = new MemorySystem({
  store,
  predicates: PredicateRegistry.standard(),
});

// Extend the standard library with your own predicates.
const custom = PredicateRegistry.standard();
custom.register({
  name: 'invested_in',
  description: 'Investor relationship.',
  category: 'task',
  rankingWeight: 1.3,
  defaultImportance: 0.9,
});
const memory2 = new MemorySystem({ store, predicates: custom });

// Build your own vocabulary from scratch.
const domain = PredicateRegistry.empty().registerAll([
  { name: 'patient_of', description: 'Patient-doctor relation.', category: 'clinical' },
  // ...
]);
const memory3 = new MemorySystem({ store, predicates: domain, predicateMode: 'strict' });

const prompt = defaultExtractionPrompt({
  signalText,
  predicateRegistry: PredicateRegistry.standard(),
  maxPredicatesPerCategory: 5,         // default
});

type AccessLevel = 'none' | 'read' | 'write';  // 'write' implies 'read'
type Permission = 'read' | 'write';

interface Permissions {
  group?: AccessLevel;   // what group members (non-owner) can do
  world?: AccessLevel;   // what callers outside the group (or everyone, when groupless) can do
}

DEFAULT_GROUP_LEVEL = 'read'    // meaningful only when groupId is set
DEFAULT_WORLD_LEVEL = 'read'

function canAccess(
  record: { ownerId?: string; groupId?: string; permissions?: Permissions },
  caller: ScopeFilter,
  need: Permission,
): boolean;

function effectivePermissions(
  record,
): { group: AccessLevel; world: AccessLevel };   // applies defaults

function assertCanAccess(
  record: { id?: string; ... },
  caller: ScopeFilter,
  need: Permission,
  recordKind: 'entity' | 'fact',
): void;    // throws PermissionDeniedError on denial

function levelGrants(level: AccessLevel, need: Permission): boolean;

class OwnerRequiredError extends Error {
  recordKind: 'entity' | 'fact';
}

class PermissionDeniedError extends Error {
  recordId: string;
  recordKind: 'entity' | 'fact';
  operation: Permission;
}

acl?: ACLEntry[];           // explicit grants — caller-set
readPrincipals?:  string[]; // materialized at the storage boundary — LIBRARY-OWNED, never set by hand
writePrincipals?: string[]; // ⊆ readPrincipals

interface ACLEntry {
  principal: Principal;               // a token string (see helpers)
  actions: Array<'read' | 'write'>;   // [] grants nothing
}

principals?: string[];   // PRESENCE is authoritative (any length, incl. empty).
                         // Present → principal model (readPrincipals ∩ principals); userId/groupId ignored for access.
                         // Empty → authorizes nothing. Absent → legacy owner/group/world path.

// Replace a record's explicit acl and re-materialize its token arrays. Requires write. Returns the updated record.
setAccess(kind: 'entity' | 'fact', id: string, acl: ACLEntry[], scope: ScopeFilter): Promise<IEntity | IFact>;

// THE MIGRATION GATE. Materialize read/writePrincipals on every entity + fact (live AND archived) from their
// ownerId/groupId/permissions/acl. Idempotent; { force } rewrites all; batchSize clamps to [1, 1000] (default 500).
// MUST run to completion before any caller passes scope.principals (principal callers have no legacy fallback).
backfillAccessPrincipals(
  scope: ScopeFilter,
  opts?: { batchSize?: number; force?: boolean },
): Promise<{ entitiesScanned: number; entitiesUpdated: number; factsScanned: number; factsUpdated: number }>;

// Token builders + parser
const PRINCIPAL_WORLD: 'world';
function principalUser(id): Principal;     function principalEntity(id): Principal;
function principalGroup(id): Principal;    function principalService(name): Principal;
function parsePrincipal(p): { kind: 'user'|'entity'|'group'|'service'|'world'|'unknown'; id?: string };

// Projection + materialization
function materializePrincipals(input: AccessInput): { readPrincipals: string[]; writePrincipals: string[] };
function fromLibraryPermissions(perms, ownerId, groupId): AccessInput;   // {group, world} defaults
function fromNimbleAudit(isPublic, ownerId, groupId, acl?): AccessInput; // {isPublic} host shape
function principalsForLibraryRecord(rec): { readPrincipals: string[]; writePrincipals: string[] };

// Filters + checks + merge helpers
function readFilterForPrincipals(p: string[]):  { readPrincipals:  { $in: string[] } };
function writeFilterForPrincipals(p: string[]): { writePrincipals: { $in: string[] } };
function canByPrincipals(record, principals: string[], need: 'read' | 'write'): boolean;
function patchTouchesAccessFields(patch): boolean;   // gate re-materialization on partial updates
function rewritePrincipalReferences(arr, fromEntityId, toEntityId): string[] | undefined;
function rewriteAclPrincipalReferences(acl, fromEntityId, toEntityId): ACLEntry[] | undefined;

// Types: Principal, PrincipalKind, ParsedPrincipal, ACLEntry, AccessInput, MaterializedPrincipals

type ChangeEvent =
  | { type: 'entity.upsert'; entity: IEntity; created: boolean }
  | { type: 'entity.archive'; entityId: EntityId }
  | { type: 'entity.merge'; winnerId: EntityId; loserId: EntityId }
  | { type: 'fact.add'; fact: IFact }
  | { type: 'fact.archive'; factId: FactId }
  | { type: 'fact.supersede'; oldId: FactId; newId: FactId }
  | { type: 'profile.regenerate'; entityId: EntityId; scope: ScopeFields; factId: FactId };