@startsimpli/integrations 0.2.19 → 0.2.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.19",
+  "version": "0.2.20",
   "description": "Provider-agnostic types, API clients, hooks, and UI primitives for email + calendar integrations across StartSimpli apps.",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/__tests__/translation-corpus.test.ts

@@ -0,0 +1,428 @@
+/**
+ * THE CLIENT CORPUS — ingestion, term extraction, memory, isolation
+ * (bd startsim-ppfl, RED).
+ *
+ * The bead asks for four things and this file is all four:
+ *
+ *   - client documents ingest, and terminology is extracted with the right
+ *     candidates surfaced FOR HUMAN CONFIRMATION — "an unconfirmed
+ *     auto-extracted term must not silently become authoritative";
+ *   - an approved translation pair becomes a memory entry and is hit on a
+ *     matching later segment;
+ *   - an accepted human edit becomes a new entry;
+ *   - one client's corpus is unreachable from another client's tenant.
+ *
+ * THE ISOLATION CASES ARE THE POINT OF THE LANE. `startsim-hopl` sells "one
+ * client's material never appears against another's", and a glossary term is
+ * the sharpest possible violation of it: short, memorable, and it would surface
+ * INSIDE ANOTHER CLIENT'S TRANSLATED DOCUMENT, in their own language, looking
+ * entirely legitimate.
+ *
+ * Every case here runs against records deliberately mixed across two orgs —
+ * the same posture `corpus-scope.test.ts` already takes, which assumes the query
+ * layer DOES NOT hold the line and proves the output is safe anyway.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { FIXTURE_ORG, FIXTURE_OTHER_ORG } from '../corpus/fixtures';
+import {
+  TRANSLATION_TYPE_KEYS,
+  applyTermVerdict,
+  exactMemoryHit,
+  extractTermCandidates,
+  fuzzyMemoryMatches,
+  glossaryForSegment,
+  ingestForTranslation,
+  memoryUnitFromReviewerEdit,
+  normalizeForMemory,
+  readAllGlossaryTerms,
+  scopedMemory,
+  scopedTerms,
+  type GlossaryTermRecord,
+  type MemoryUnitRecord,
+  type TranslationCorpusApi,
+} from '../corpus/translation';
+import type { CorpusPage, CorpusScope, SourceDocument } from '../corpus/types';
+
+const TANDEM: CorpusScope = { orgId: FIXTURE_ORG };
+const NORTHWIND: CorpusScope = { orgId: FIXTURE_OTHER_ORG };
+
+const EN_AR = { sourceLocale: 'en', targetLocale: 'ar' };
+
+function doc(
+  id: string,
+  body: string,
+  scope: CorpusScope = TANDEM,
+  title = 'Client document',
+): SourceDocument {
+  return {
+    id,
+    title,
+    body,
+    sections: [],
+    occurredAt: '2026-03-01T00:00:00.000Z',
+    source: 'upload',
+    sourceLabel: 'Upload',
+    sourceRef: id,
+    participants: [],
+    scope,
+  };
+}
+
+function term(
+  over: Partial<GlossaryTermRecord> & Pick<GlossaryTermRecord, 'sourceTerm'>,
+): GlossaryTermRecord {
+  return {
+    id: `term-${over.sourceTerm}`,
+    sourceLocale: 'en',
+    targetLocale: 'ar',
+    targetTerm: 'اتفاقية التسوية',
+    status: 'approved',
+    occurrences: 3,
+    documentIds: ['doc-1'],
+    scope: TANDEM,
+    ...over,
+  };
+}
+
+function unit(over: Partial<MemoryUnitRecord> & Pick<MemoryUnitRecord, 'sourceText'>): MemoryUnitRecord {
+  return {
+    id: `unit-${over.sourceText.slice(0, 12)}`,
+    sourceLocale: 'en',
+    targetLocale: 'ar',
+    targetText: 'نص تجريبي',
+    sourceHash: over.sourceText.trim().toLowerCase(),
+    origin: 'reviewer_edit',
+    approved: true,
+    scope: TANDEM,
+    ...over,
+  };
+}
+
+// ---------------------------------------------------------------------------
+
+describe('ingestion', () => {
+  it('writes rows of the translation types and NOTHING else', () => {
+    // A connector that quietly invents a sixth entity_type is a schema change
+    // nobody reviewed. Generic envelope, declared types, no surprises.
+    const writes = ingestForTranslation(doc('doc-1', 'The settlement agreement is enclosed.'), {
+      scope: TANDEM,
+    });
+
+    const types = new Set(writes.map((w) => w.entity_type));
+    for (const type of types) {
+      expect(Object.values(TRANSLATION_TYPE_KEYS)).toContain(type);
+    }
+    expect(writes.length).toBeGreaterThan(0);
+  });
+
+  it('carries an external_id on every row, so a re-ingest converges instead of duplicating', () => {
+    const writes = ingestForTranslation(doc('doc-1', 'The settlement agreement is enclosed.'), {
+      scope: TANDEM,
+    });
+
+    for (const write of writes) expect(write.external_id).toBeTruthy();
+    expect(new Set(writes.map((w) => w.external_id)).size).toBe(writes.length);
+  });
+});
+
+describe('term extraction proposes, it does not decide', () => {
+  // Planted terms repeat; the noise does not. That is the whole signal, and it
+  // is why `minOccurrences` is a parameter rather than a constant.
+  const documents = [
+    doc(
+      'doc-1',
+      [
+        'The settlement agreement was signed on Tuesday.',
+        'A settlement agreement binds both parties.',
+        'Northwind Logistics accepted the settlement agreement.',
+        'Force majeure applies to Northwind Logistics only.',
+        'The force majeure clause was invoked.',
+        'Somebody left a blue umbrella in the lobby.',
+      ].join(' '),
+    ),
+    doc('doc-2', 'Northwind Logistics confirmed the force majeure position.'),
+  ];
+
+  const options = { scope: TANDEM, ...EN_AR, minOccurrences: 2 };
+
+  it('yields the planted terms', () => {
+    const candidates = extractTermCandidates(documents, options);
+    const sources = candidates.map((c) => c.sourceTerm.toLowerCase());
+
+    expect(sources).toContain('settlement agreement');
+    expect(sources).toContain('force majeure');
+    expect(sources).toContain('northwind logistics');
+  });
+
+  it('does NOT yield the planted noise', () => {
+    const candidates = extractTermCandidates(documents, options);
+    const sources = candidates.map((c) => c.sourceTerm.toLowerCase());
+
+    // Occurs once, and is not terminology however memorable it is.
+    expect(sources).not.toContain('blue umbrella');
+  });
+
+  it('marks every extracted term a CANDIDATE, never approved, never binding', () => {
+    // The rule the bead puts in capitals. A glossary that fills itself is a
+    // glossary the client never agreed to — and adherence is measured against it.
+    const candidates = extractTermCandidates(documents, options);
+
+    expect(candidates.length).toBeGreaterThan(0);
+    for (const candidate of candidates) {
+      expect(candidate.status).toBe('candidate');
+      expect(candidate.targetTerm).toBe('');
+    }
+  });
+
+  it('never proposes a term a human already rejected', () => {
+    const rejected = term({ sourceTerm: 'force majeure', status: 'rejected' });
+
+    const candidates = extractTermCandidates(documents, { ...options, known: [rejected] });
+
+    expect(candidates.map((c) => c.sourceTerm.toLowerCase())).not.toContain('force majeure');
+  });
+
+  it('promotes a term only through an explicit verdict', () => {
+    const candidate = term({ sourceTerm: 'settlement agreement', status: 'candidate', targetTerm: '' });
+
+    const approved = applyTermVerdict(candidate, {
+      status: 'approved',
+      targetTerm: 'اتفاقية التسوية',
+    });
+
+    expect(approved.status).toBe('approved');
+    expect(approved.targetTerm).toBe('اتفاقية التسوية');
+  });
+});
+
+describe('glossary lookup', () => {
+  const present = term({ sourceTerm: 'settlement agreement' });
+  const absent = term({ sourceTerm: 'force majeure', id: 'term-fm' });
+  const candidate = term({
+    sourceTerm: 'settlement agreement',
+    id: 'term-candidate',
+    status: 'candidate',
+    targetTerm: '',
+  });
+
+  it('returns only the terms whose source form OCCURS in the segment', () => {
+    // The prompt scales with the text, not with the glossary.
+    const got = glossaryForSegment('Please review the settlement agreement.', [present, absent]);
+
+    expect(got.map((t) => t.id)).toEqual([present.id]);
+  });
+
+  it('never returns an unconfirmed candidate, even when it occurs', () => {
+    const got = glossaryForSegment('Please review the settlement agreement.', [candidate]);
+
+    expect(got).toEqual([]);
+  });
+
+  it('matches case-insensitively without matching a different word', () => {
+    expect(
+      glossaryForSegment('The SETTLEMENT AGREEMENT is enclosed.', [present]).map((t) => t.id),
+    ).toEqual([present.id]);
+    expect(glossaryForSegment('The settlement is enclosed.', [present])).toEqual([]);
+  });
+});
+
+describe('translation memory', () => {
+  const stored = unit({
+    sourceText: 'The quarterly report is ready for your review.',
+    targetText: 'نص تجريبي: التقرير ربع السنوي جاهز للمراجعة.',
+  });
+
+  it('hits exactly after normalising whitespace and case', () => {
+    const hit = exactMemoryHit(
+      '  the QUARTERLY   report is ready for your review.  ',
+      [stored],
+      { scope: TANDEM, ...EN_AR },
+    );
+
+    expect(hit?.id).toBe(stored.id);
+    expect(hit?.targetText).toBe(stored.targetText);
+  });
+
+  it('does NOT hit after a material change', () => {
+    // A different number is a different sentence. Normalisation must not eat it.
+    const hit = exactMemoryHit(
+      'The monthly report is ready for your review.',
+      [stored],
+      { scope: TANDEM, ...EN_AR },
+    );
+
+    expect(hit).toBeNull();
+  });
+
+  it('normalises whitespace and case but preserves the material content', () => {
+    expect(normalizeForMemory('  The   Report  ')).toBe(normalizeForMemory('the report'));
+    expect(normalizeForMemory('12 seats')).not.toBe(normalizeForMemory('13 seats'));
+  });
+
+  it('never serves an unapproved unit', () => {
+    const draft = unit({ sourceText: stored.sourceText, id: 'draft', approved: false });
+
+    expect(exactMemoryHit(stored.sourceText, [draft], { scope: TANDEM, ...EN_AR })).toBeNull();
+  });
+
+  it('does not hit across a language pair', () => {
+    const zh = unit({ sourceText: stored.sourceText, id: 'zh', targetLocale: 'zh' });
+
+    expect(
+      exactMemoryHit(stored.sourceText, [zh], { scope: TANDEM, sourceLocale: 'en', targetLocale: 'ar' }),
+    ).toBeNull();
+  });
+
+  it('returns fuzzy neighbours ordered by score and honours the limit', () => {
+    const near = unit({ sourceText: 'The quarterly report is ready for review.', id: 'near' });
+    const mid = unit({ sourceText: 'The quarterly report will be ready soon.', id: 'mid' });
+    const far = unit({ sourceText: 'Parking allocation for the London office.', id: 'far' });
+
+    const matches = fuzzyMemoryMatches(stored.sourceText, [far, mid, near], {
+      scope: TANDEM,
+      ...EN_AR,
+      limit: 2,
+    });
+
+    expect(matches).toHaveLength(2);
+    expect(matches[0]!.unit.id).toBe('near');
+    expect(matches[0]!.score).toBeGreaterThan(matches[1]!.score);
+    expect(matches.map((m) => m.unit.id)).not.toContain('far');
+  });
+});
+
+describe('a reviewer edit becomes memory', () => {
+  it('creates an approved unit that a later identical segment hits exactly', () => {
+    // THE SINGLE TEST THAT PROVES "it learns from your material". Without it the
+    // reviewer corrects the same term forever, which is the upkeep trap that
+    // makes people abandon tools.
+    const source = 'Please review the settlement agreement before Friday.';
+    const edited = 'نص تجريبي مصحَّح: اتفاقية التسوية.';
+
+    const created = memoryUnitFromReviewerEdit(
+      { sourceText: source, editedTargetText: edited, ...EN_AR },
+      TANDEM,
+    );
+
+    expect(created.origin).toBe('reviewer_edit');
+    expect(created.approved).toBe(true);
+
+    const hit = exactMemoryHit(source, [created], { scope: TANDEM, ...EN_AR });
+    // BYTE-IDENTICAL. A reviewer who fixed it once must never see it wrong again.
+    expect(hit?.targetText).toBe(edited);
+  });
+});
+
+describe('isolation between clients', () => {
+  const mine = term({ sourceTerm: 'settlement agreement', id: 'mine', scope: TANDEM });
+  const theirs = term({ sourceTerm: 'settlement agreement', id: 'theirs', scope: NORTHWIND });
+  const myUnit = unit({ sourceText: 'Shared sentence.', id: 'my-unit', scope: TANDEM });
+  const theirUnit = unit({ sourceText: 'Shared sentence.', id: 'their-unit', scope: NORTHWIND });
+
+  it('does not return another tenant’s glossary term, and SAYS it dropped one', () => {
+    const read = scopedTerms([mine, theirs], TANDEM);
+
+    expect(read.kept.map((t) => t.id)).toEqual(['mine']);
+    // Non-zero and surfaced — a silent zero here is how a leak stays invisible.
+    expect(read.droppedOutOfScope).toBe(1);
+  });
+
+  it('does not return another tenant’s memory unit, and SAYS it dropped one', () => {
+    const read = scopedMemory([myUnit, theirUnit], TANDEM);
+
+    expect(read.kept.map((u) => u.id)).toEqual(['my-unit']);
+    expect(read.droppedOutOfScope).toBe(1);
+  });
+
+  it('never serves a foreign memory unit as an exact hit', () => {
+    // The worst case in the lane: a fluent, confident, correctly-formatted
+    // translation sourced from another customer's approved wording.
+    const hit = exactMemoryHit('Shared sentence.', [theirUnit], { scope: TANDEM, ...EN_AR });
+
+    expect(hit).toBeNull();
+  });
+
+  it('never offers a foreign unit as a fuzzy example', () => {
+    const matches = fuzzyMemoryMatches('Shared sentence.', [theirUnit], {
+      scope: TANDEM,
+      ...EN_AR,
+      limit: 5,
+    });
+
+    expect(matches).toEqual([]);
+  });
+
+  it('returns NOTHING for a principal carrying no org claim', () => {
+    // A missing claim must read as "nothing", never as "unscoped, so everything".
+    const read = scopedTerms([mine, theirs], { orgId: '' });
+
+    expect(read.kept).toEqual([]);
+    expect(read.droppedOutOfScope).toBe(2);
+  });
+
+  /**
+   * The RLS half of bd startsim-ppfl item 7 is NOT in this repository.
+   *
+   * It belongs to `tenant-starter`, a separate Django project with its own
+   * runner (`DJANGO_DEBUG=true .venv/bin/python manage.py test`, sqlite, its own
+   * venv — NOT the main-backend Docker stack). There is no `tenant-starter`
+   * checkout in this worktree, so the test cannot be written here, and writing
+   * a TypeScript imitation of it would be worse than leaving it undone: it would
+   * look like coverage of a database guarantee it does not touch.
+   *
+   * `startsim-bfem` already records this as UNVERIFIED, owner Quinn.
+   */
+  it.todo(
+    'reading outside org_scope() returns nothing rather than everything — tenant-starter, not this repo',
+  );
+});
+
+describe('paging', () => {
+  /** Three pages of two. A reader that stops at the first sees a third of the glossary. */
+  function pagedApi(): TranslationCorpusApi {
+    const all = [
+      term({ sourceTerm: 'alpha', id: 't1' }),
+      term({ sourceTerm: 'bravo', id: 't2' }),
+      term({ sourceTerm: 'charlie', id: 't3' }),
+      term({ sourceTerm: 'delta', id: 't4' }),
+      term({ sourceTerm: 'echo', id: 't5' }),
+      term({ sourceTerm: 'foxtrot', id: 't6' }),
+    ];
+    const PAGE = 2;
+    return {
+      async listGlossaryTerms({ page = 1 }): Promise<CorpusPage<GlossaryTermRecord>> {
+        const start = (page - 1) * PAGE;
+        const results = all.slice(start, start + PAGE);
+        return {
+          count: all.length,
+          // The server ignores `pageSize`, exactly as the live tenant does.
+          next: start + PAGE < all.length ? `?page=${page + 1}` : null,
+          previous: page > 1 ? `?page=${page - 1}` : null,
+          results,
+        };
+      },
+      async listMemoryUnits(): Promise<CorpusPage<MemoryUnitRecord>> {
+        return { count: 0, next: null, previous: null, results: [] };
+      },
+    };
+  }
+
+  it('reads the glossary PAST the first page', async () => {
+    const read = await readAllGlossaryTerms(pagedApi(), TANDEM);
+
+    expect(read.kept).toHaveLength(6);
+    expect(read.kept.map((t) => t.id)).toEqual(['t1', 't2', 't3', 't4', 't5', 't6']);
+  });
+
+  it('scope-filters every page, not just the first', async () => {
+    const read = await readAllGlossaryTerms(pagedApi(), NORTHWIND);
+
+    // Every fixture term belongs to tandem, so a northwind principal gets none
+    // — and is TOLD that six rows were dropped rather than shown an empty
+    // glossary that looks like a clean read.
+    expect(read.kept).toEqual([]);
+    expect(read.droppedOutOfScope).toBe(6);
+  });
+});

package/src/corpus/translation.ts

@@ -0,0 +1,321 @@
+/**
+ * THE CLIENT CORPUS FOR TRANSLATION — glossary and translation memory
+ * (bd startsim-ppfl RED / bd startsim-364c GREEN).
+ *
+ * CONTRACT AND STUBS ONLY. Every function throws `NotImplementedError`, so the
+ * tests in `../__tests__/translation-corpus.test.ts` fail on missing BEHAVIOUR
+ * rather than on a missing module.
+ *
+ * ── WHY THIS LIVES IN THE CORPUS PACKAGE ───────────────────────────────────
+ * `startsim-3o4e` decides the whole mechanism is glossary + translation-memory
+ * injection — there is no fine-tune. So "the client's own stuff" is a CORPUS
+ * question, and this package already owns the three hard parts of that:
+ *
+ *   - the generic `TenantEntity` envelope (`./entities`), so a glossary term
+ *     and a memory unit are rows of a new `entity_type` and NOT new models
+ *     (feedback_brutally_generic);
+ *   - the scope guard (`./retrieval`), which already partitions a candidate set
+ *     and SURFACES the drop count rather than swallowing it — which is exactly
+ *     the shape isolation needs;
+ *   - a Porter stemmer and a Jaccard (`./text`), which term extraction and
+ *     fuzzy memory both want and neither should reimplement.
+ *
+ * ── THE ONE RULE THE BEAD PUTS IN CAPITALS ─────────────────────────────────
+ * AN UNCONFIRMED AUTO-EXTRACTED TERM MUST NOT SILENTLY BECOME AUTHORITATIVE.
+ * Extraction proposes; a human disposes. `status: 'candidate'` is never
+ * binding, never injected into a prompt, and never counted in an adherence
+ * score — because a glossary that fills itself is a glossary the client did not
+ * agree to, and `startsim-r9q8` measures adherence AGAINST it.
+ *
+ * ── ISOLATION IS THE POINT, NOT A FEATURE ──────────────────────────────────
+ * `startsim-hopl` sells "one client's material never appears against
+ * another's". A glossary term is the sharpest possible violation of that: it is
+ * short, memorable, and it would appear IN ANOTHER CLIENT'S TRANSLATED
+ * DOCUMENT. So every read here is scope-partitioned and every drop is counted.
+ */
+
+import type { CorpusPage, CorpusScope, SourceDocument } from './types';
+
+/**
+ * The `entity_type` keys translation adds. Defaults, not a closed set — the
+ * same convention as `DEFAULT_TYPE_KEYS` in `./entities`.
+ */
+export interface TranslationTypeKeys {
+  glossaryTerm: string;
+  memoryUnit: string;
+  /** The client's ingested source document, reusing the corpus document type. */
+  sourceDocument: string;
+}
+
+export const TRANSLATION_TYPE_KEYS: TranslationTypeKeys = {
+  glossaryTerm: 'glossary_term',
+  memoryUnit: 'translation_memory_unit',
+  sourceDocument: 'source_document',
+};
+
+/**
+ * Where a term is in its life.
+ *
+ * `candidate` — proposed by extraction, NOT authoritative, NOT binding.
+ * `approved`  — a human ruled on it. Only these bind.
+ * `rejected`  — a human ruled against it. Kept so extraction stops re-proposing.
+ */
+export type TermStatus = 'candidate' | 'approved' | 'rejected';
+
+export interface GlossaryTermRecord {
+  id: string;
+  sourceLocale: string;
+  targetLocale: string;
+  sourceTerm: string;
+  /** Empty while a candidate — nobody has said what it should be yet. */
+  targetTerm: string;
+  status: TermStatus;
+  /** Brand and entity names: `sourceTerm` must survive verbatim. */
+  doNotTranslate?: boolean;
+  /** How often extraction saw it. Evidence for a human, never a promotion rule. */
+  occurrences: number;
+  /** Which document(s) it came from, so a reviewer can check the claim. */
+  documentIds: string[];
+  scope: CorpusScope;
+}
+
+/** Where a memory unit came from. A reviewer edit is the one that matters. */
+export type MemoryOrigin = 'machine' | 'reviewer_edit' | 'imported';
+
+export interface MemoryUnitRecord {
+  id: string;
+  sourceLocale: string;
+  targetLocale: string;
+  sourceText: string;
+  targetText: string;
+  /**
+   * The NORMALISED source, which is what an exact match compares. Stored rather
+   * than recomputed so a normalisation change is visible as a migration instead
+   * of silently repartitioning the memory.
+   */
+  sourceHash: string;
+  origin: MemoryOrigin;
+  /** Only an approved unit is served. A machine draft is not memory. */
+  approved: boolean;
+  scope: CorpusScope;
+}
+
+/** A row as the tenant's generic upsert takes it. */
+export interface TenantEntityWrite {
+  entity_type: string;
+  external_id: string;
+  name: string;
+  data: Record<string, unknown>;
+}
+
+export class NotImplementedError extends Error {
+  constructor(what: string) {
+    super(`${what} is not implemented (bd startsim-ppfl is RED; bd startsim-364c implements it)`);
+    this.name = 'NotImplementedError';
+  }
+}
+
+// ---------------------------------------------------------------------------
+//  ingestion
+// ---------------------------------------------------------------------------
+
+export interface IngestOptions {
+  scope: CorpusScope;
+  typeKeys?: TranslationTypeKeys;
+}
+
+/**
+ * A client document, as rows.
+ *
+ * Returns WRITES rather than performing them, so the test can assert what would
+ * be written without a tenant — and so ingestion stays pure, like every other
+ * mapper in this package.
+ */
+export function ingestForTranslation(
+  _document: SourceDocument,
+  _options: IngestOptions,
+): TenantEntityWrite[] {
+  throw new NotImplementedError('ingestForTranslation');
+}
+
+// ---------------------------------------------------------------------------
+//  term extraction — proposes, never decides
+// ---------------------------------------------------------------------------
+
+export interface ExtractTermsOptions {
+  scope: CorpusScope;
+  sourceLocale: string;
+  targetLocale: string;
+  /** Terms already ruled on, so a rejected term is not proposed again. */
+  known?: readonly GlossaryTermRecord[];
+  /** How many times a phrase must occur before it is worth a human's attention. */
+  minOccurrences?: number;
+  maxCandidates?: number;
+}
+
+/**
+ * Propose glossary candidates from the client's own documents.
+ *
+ * EVERY RETURNED TERM IS `status: 'candidate'`. There is no code path in this
+ * module that produces an `approved` term without a human verdict.
+ */
+export function extractTermCandidates(
+  _documents: readonly SourceDocument[],
+  _options: ExtractTermsOptions,
+): GlossaryTermRecord[] {
+  throw new NotImplementedError('extractTermCandidates');
+}
+
+/** Record a human's verdict. The ONLY route from `candidate` to `approved`. */
+export function applyTermVerdict(
+  _term: GlossaryTermRecord,
+  _verdict: { status: 'approved' | 'rejected'; targetTerm?: string; doNotTranslate?: boolean },
+): GlossaryTermRecord {
+  throw new NotImplementedError('applyTermVerdict');
+}
+
+// ---------------------------------------------------------------------------
+//  glossary lookup — scales with the text, not with the glossary
+// ---------------------------------------------------------------------------
+
+/**
+ * The BINDING terms whose source form occurs in `segmentText`.
+ *
+ * Two filters, both load-bearing: occurrence (so the prompt scales with the
+ * page, not the glossary) and status (so a candidate never reaches a model).
+ */
+export function glossaryForSegment(
+  _segmentText: string,
+  _terms: readonly GlossaryTermRecord[],
+): GlossaryTermRecord[] {
+  throw new NotImplementedError('glossaryForSegment');
+}
+
+// ---------------------------------------------------------------------------
+//  translation memory
+// ---------------------------------------------------------------------------
+
+/**
+ * The comparable form of a source string: whitespace collapsed, case folded,
+ * bidi isolates stripped. A MATERIAL change — a different word, a different
+ * number — must survive normalisation and defeat the match.
+ */
+export function normalizeForMemory(_text: string): string {
+  throw new NotImplementedError('normalizeForMemory');
+}
+
+export interface MemoryLookupOptions {
+  scope: CorpusScope;
+  sourceLocale: string;
+  targetLocale: string;
+}
+
+/** An exact hit, or null. Costs nothing and makes no provider call. */
+export function exactMemoryHit(
+  _segmentText: string,
+  _units: readonly MemoryUnitRecord[],
+  _options: MemoryLookupOptions,
+): MemoryUnitRecord | null {
+  throw new NotImplementedError('exactMemoryHit');
+}
+
+export interface FuzzyMatch {
+  unit: MemoryUnitRecord;
+  /** 0..1. Higher is closer. */
+  score: number;
+}
+
+export interface FuzzyOptions extends MemoryLookupOptions {
+  limit?: number;
+  minScore?: number;
+}
+
+/** Neighbours, best first, capped. Offered to the model as EXAMPLES, never as answers. */
+export function fuzzyMemoryMatches(
+  _segmentText: string,
+  _units: readonly MemoryUnitRecord[],
+  _options: FuzzyOptions,
+): FuzzyMatch[] {
+  throw new NotImplementedError('fuzzyMemoryMatches');
+}
+
+/**
+ * A reviewer's accepted edit, as a memory unit.
+ *
+ * `startsim-witd`: without this "the reviewer corrects the same term forever,
+ * which is exactly the upkeep trap that makes people abandon tools."
+ */
+export function memoryUnitFromReviewerEdit(
+  _edit: {
+    sourceText: string;
+    editedTargetText: string;
+    sourceLocale: string;
+    targetLocale: string;
+  },
+  _scope: CorpusScope,
+): MemoryUnitRecord {
+  throw new NotImplementedError('memoryUnitFromReviewerEdit');
+}
+
+// ---------------------------------------------------------------------------
+//  isolation
+// ---------------------------------------------------------------------------
+
+export interface ScopedRead<T> {
+  kept: T[];
+  /** NON-ZERO IS A BUG UPSTREAM AND SOMEBODY NEEDS TO SEE IT. Never swallowed. */
+  droppedOutOfScope: number;
+}
+
+/**
+ * Partition glossary terms by the asking principal's scope.
+ *
+ * A THIRD check, after the tenant API's `org_id` filter and Postgres RLS, for
+ * the reason `./retrieval` already states: if any layer above hands back a row
+ * it should not have, the OUTPUT must still not contain it.
+ */
+export function scopedTerms(
+  _terms: readonly GlossaryTermRecord[],
+  _scope: CorpusScope,
+): ScopedRead<GlossaryTermRecord> {
+  throw new NotImplementedError('scopedTerms');
+}
+
+export function scopedMemory(
+  _units: readonly MemoryUnitRecord[],
+  _scope: CorpusScope,
+): ScopedRead<MemoryUnitRecord> {
+  throw new NotImplementedError('scopedMemory');
+}
+
+// ---------------------------------------------------------------------------
+//  paging
+// ---------------------------------------------------------------------------
+
+/**
+ * The read side of the corpus, paged.
+ *
+ * PAST THE FIRST PAGE, for the reason `./extract` documents from the wire: the
+ * tenant's `EntityViewSet` pages with DRF's default and ignores `page_size`, so
+ * a caller that reads one page and calls it the glossary silently stops seeing
+ * terms at whatever `PAGE_SIZE` happens to be. A glossary that quietly truncates
+ * is an adherence score that is quietly wrong.
+ */
+export interface TranslationCorpusApi {
+  listGlossaryTerms(query: {
+    page?: number;
+    pageSize?: number;
+  }): Promise<CorpusPage<GlossaryTermRecord>>;
+  listMemoryUnits(query: {
+    page?: number;
+    pageSize?: number;
+  }): Promise<CorpusPage<MemoryUnitRecord>>;
+}
+
+export function readAllGlossaryTerms(
+  _api: TranslationCorpusApi,
+  _scope: CorpusScope,
+  _options?: { maxPages?: number },
+): Promise<ScopedRead<GlossaryTermRecord>> {
+  throw new NotImplementedError('readAllGlossaryTerms');
+}