@startsimpli/integrations 0.2.19 → 0.2.21

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');
+}