@_linked/translation 0.9.3 → 0.9.5

package/src/shapes/TranslationProvider.ts

@@ -1,1927 +0,0 @@
-import { ShapeProvider } from '@_linked/server-utils/utils/ShapeProvider';
-import { callable, internal } from '@_linked/server-utils/utils/callable';
-import type {
-  GlossaryTermRecord,
-  TranslationEntryRecord,
-  TranslationMemoryMatchRecord,
-  TranslationMemoryPretranslateCandidate,
-  TranslationMemoryPretranslateReport,
-  TranslationMemoryRecord,
-  TranslationProposalDecision,
-  TranslationRevisionRecord,
-  TranslationRevisionStatus,
-  TranslationState,
-  TranslationKeyVersionRecord,
-  TranslationReleaseRecord,
-  TranslationUnitRecord,
-} from '../records.js';
-import { TranslationKey } from './TranslationKey.js';
-import { TranslationKeyVersion } from './TranslationKeyVersion.js';
-import { TranslationRelease } from './TranslationRelease.js';
-import { TranslationUnit } from './TranslationUnit.js';
-import { TranslationRevision } from './TranslationRevision.js';
-import { GlossaryTerm } from './GlossaryTerm.js';
-import type { TranslationMessages } from '../core/messages.js';
-import {
-  classifyKeyVersion,
-  createMonotonicVersionId,
-  deriveBackfillKeyVersion,
-  deriveTranslationKeyVersionContract,
-} from '../key-version.js';
-import {
-  canAuthorTranslation,
-  type TranslationAuthoringAction,
-} from '../authorization.js';
-
-export interface TranslationKeyInput {
-  appId: string;
-  key: string;
-  sourceText: string;
-  namespace?: string;
-  description?: string;
-  kind?: 'ui' | 'content';
-  ofNode?: string;
-  ofField?: string;
-  ofShape?: string;
-  ofProperty?: string;
-  ofResource?: string;
-  fromPackage?: string;
-  /** Force the override flag; when omitted it is derived (see upsertTranslationKey). */
-  overridden?: boolean;
-  format?: 'simple' | 'icu';
-  sourceLanguage?: string;
-}
-
-/** Trusted caller context, not a client payload flag. Package discovery and
- * explicit app authoring have different ownership semantics. */
-export interface TranslationKeyWriteContext {
-  createdBy?: string;
-  /**
-   * `'declaration-sync'` is a refresh from code/package declarations: it never
-   * marks a key overridden, and it leaves an existing app override untouched
-   * (answering `preservedOverride: true`). Anything else is an app edit.
-   */
-  source?: 'app-edit' | 'declaration-sync';
-}
-export interface TranslationKeyWriteResult {
-  id: string;
-  versionId: string;
-  versionCreated: boolean;
-  /** Present when a declaration refresh kept the app's override and wrote nothing. */
-  preservedOverride?: true;
-}
-
-export interface TranslationUnitInput {
-  appId: string;
-  key: string;
-  language: string;
-  text: string;
-  state?: TranslationState;
-  updatedBy?: string;
-}
-
-/** Who/what authored a unit write — recorded on its `applied` revision (AD-P). */
-export interface TranslationAuthorship {
-  /** WebID of the human author, or the MT provider IRI. */
-  author?: string;
-  authorKind?: 'human' | 'machine';
-  /** MT provider key when authorKind is 'machine'. */
-  mtProvider?: string;
-  note?: string;
-}
-
-type TranslationKeyRow = Omit<TranslationEntryRecord, 'units'>;
-type TranslationUnitRow = TranslationUnitRecord & {
-  ofKey?: { key?: string };
-  ofKeyVersion?: string | { id?: string };
-};
-type TranslationKeyVersionRow = TranslationKeyVersionRecord & {
-  ofKey?: { key?: string };
-};
-type TranslationMemoryUnitRow = {
-  id?: string | { id?: string };
-  language?: string;
-  text?: string;
-  state?: string;
-  updatedAt?: string;
-  ofKey?: { key?: string };
-  ofKeyVersion?:
-    | string
-    | {
-        id?: string;
-        sourceText?: string;
-        sourceHash?: string;
-        contractHash?: string;
-      };
-};
-
-const iri = (value: unknown): string | undefined =>
-  typeof value === 'string'
-    ? value
-    : (value as { id?: string } | undefined)?.id;
-
-const isoDate = (value: string | Date | undefined): string | undefined =>
-  value instanceof Date ? value.toISOString() : value || undefined;
-
-function toKeyVersionRecord(
-  row: TranslationKeyVersionRow,
-): TranslationKeyVersionRecord | null {
-  const id = iri((row as any).id) ?? iri(row);
-  if (!id || !row.versionId) return null;
-  return {
-    id,
-    versionId: row.versionId,
-    sourceLanguage: row.sourceLanguage || 'en',
-    sourceText: row.sourceText ?? '',
-    format: row.format === 'icu' ? 'icu' : 'simple',
-    argumentSignature: row.argumentSignature || '[]',
-    contractHash: row.contractHash || '',
-    sourceHash: row.sourceHash || '',
-    supersedes: iri(row.supersedes),
-    createdAt: isoDate(row.createdAt) || undefined,
-    createdBy: iri(row.createdBy),
-  };
-}
-
-/**
- * Shared TM/carry-forward classifier (Plan 018 §5.5). Exact source matches may
- * cross logical keys; changed-source carry-forward candidates never do.
- */
-export function classifyTranslationMemoryMatches(input: {
-  key: string;
-  language: string;
-  currentVersion: TranslationKeyVersionRecord;
-  rows?: TranslationMemoryUnitRow[];
-}): TranslationMemoryMatchRecord[] {
-  const matches: TranslationMemoryMatchRecord[] = [];
-  for (const row of input.rows ?? []) {
-    const version =
-      typeof row.ofKeyVersion === 'object' ? row.ofKeyVersion : undefined;
-    const unitId = iri(row.id);
-    const keyVersionId = iri(row.ofKeyVersion);
-    const candidateKey = row.ofKey?.key;
-    if (
-      !unitId ||
-      !keyVersionId ||
-      keyVersionId === input.currentVersion.id ||
-      !candidateKey ||
-      row.language !== input.language ||
-      row.state !== 'reviewed' ||
-      !row.text?.trim() ||
-      !version?.contractHash ||
-      version.contractHash !== input.currentVersion.contractHash
-    ) {
-      continue;
-    }
-    const exact = version.sourceHash === input.currentVersion.sourceHash;
-    if (!exact && candidateKey !== input.key) continue;
-    matches.push({
-      unitId,
-      key: candidateKey,
-      language: input.language,
-      text: row.text,
-      keyVersionId,
-      sourceText: version.sourceText ?? '',
-      sourceHash: version.sourceHash ?? '',
-      contractHash: version.contractHash,
-      kind: exact ? 'exact' : 'carry-forward',
-      updatedAt: isoDate(row.updatedAt) || undefined,
-    });
-  }
-  return matches.sort(
-    (left, right) =>
-      (left.kind === right.kind ? 0 : left.kind === 'exact' ? -1 : 1) ||
-      (right.updatedAt ?? '').localeCompare(left.updatedAt ?? '') ||
-      left.key.localeCompare(right.key),
-  );
-}
-
-/** Build the reviewed-unit index shown in the explicit TM browser. */
-export function toTranslationMemoryRecords(
-  rows: TranslationMemoryUnitRow[] = [],
-): TranslationMemoryRecord[] {
-  return rows
-    .flatMap((row): TranslationMemoryRecord[] => {
-      const version =
-        typeof row.ofKeyVersion === 'object' ? row.ofKeyVersion : undefined;
-      const unitId = iri(row.id);
-      const keyVersionId = iri(row.ofKeyVersion);
-      const key = row.ofKey?.key;
-      if (
-        !unitId ||
-        !keyVersionId ||
-        !key ||
-        !row.language ||
-        row.state !== 'reviewed' ||
-        !row.text?.trim() ||
-        !version?.sourceHash ||
-        !version.contractHash
-      ) {
-        return [];
-      }
-      return [
-        {
-          unitId,
-          key,
-          language: row.language,
-          text: row.text,
-          keyVersionId,
-          sourceText: version.sourceText ?? '',
-          sourceHash: version.sourceHash,
-          contractHash: version.contractHash,
-          updatedAt: isoDate(row.updatedAt) || undefined,
-        },
-      ];
-    })
-    .sort(
-      (left, right) =>
-        (right.updatedAt ?? '').localeCompare(left.updatedAt ?? '') ||
-        left.language.localeCompare(right.language) ||
-        left.key.localeCompare(right.key),
-    );
-}
-
-/**
- * Find current untranslated cells that can be filled without MT cost.
- * Source AND argument-contract hashes must match; the current version can
- * never source itself.
- */
-export function findExactMemoryPretranslations(input: {
-  entries: TranslationEntryRecord[];
-  memory: TranslationMemoryRecord[];
-  language: string;
-}): TranslationMemoryPretranslateCandidate[] {
-  const byContract = new Map<string, TranslationMemoryRecord[]>();
-  for (const record of input.memory) {
-    if (record.language !== input.language) continue;
-    const signature = `${record.sourceHash}\u0000${record.contractHash}`;
-    const candidates = byContract.get(signature) ?? [];
-    candidates.push(record);
-    byContract.set(signature, candidates);
-  }
-  for (const candidates of byContract.values()) {
-    candidates.sort(
-      (left, right) =>
-        (right.updatedAt ?? '').localeCompare(left.updatedAt ?? '') ||
-        left.key.localeCompare(right.key),
-    );
-  }
-
-  return input.entries.flatMap((entry) => {
-    const current = entry.currentVersion;
-    const unit = entry.units[input.language];
-    if (
-      !current?.sourceHash ||
-      !current.contractHash ||
-      unit?.text.trim()
-    ) {
-      return [];
-    }
-    const signature = `${current.sourceHash}\u0000${current.contractHash}`;
-    const match = byContract
-      .get(signature)
-      ?.find((candidate) => candidate.keyVersionId !== current.id);
-    return match
-      ? [
-          {
-            key: entry.key,
-            language: input.language,
-            unitId: match.unitId,
-            sourceKey: match.key,
-            text: match.text,
-          },
-        ]
-      : [];
-  });
-}
-
-const TRANSLATION_STATES = new Set<TranslationState>([
-  'untranslated',
-  'machine',
-  'reviewed',
-  'stale',
-]);
-
-function normalizeState(value: unknown): TranslationState {
-  return TRANSLATION_STATES.has(value as TranslationState)
-    ? (value as TranslationState)
-    : 'untranslated';
-}
-
-/**
- * Convert LINKED query rows into a deterministic, serialization-safe editor
- * contract. Exported for package-unit testing; it performs no I/O.
- */
-export function groupTranslationEntries(
-  keyRows: TranslationKeyRow[] = [],
-  unitRows: TranslationUnitRow[] = [],
-  versionRows: TranslationKeyVersionRow[] = [],
-): TranslationEntryRecord[] {
-  const entries = new Map<string, TranslationEntryRecord>();
-  const currentVersionByKey = new Map<string, string>();
-
-  for (const row of keyRows ?? []) {
-    if (!row?.key) continue;
-    const currentVersionId = iri((row as any).currentVersion);
-    if (currentVersionId) currentVersionByKey.set(row.key, currentVersionId);
-    entries.set(row.key, {
-      key: row.key,
-      namespace: row.namespace ?? '',
-      sourceText: row.sourceText ?? '',
-      description: row.description || undefined,
-      kind: row.kind === 'content' ? 'content' : 'ui',
-      format: row.format === 'icu' ? 'icu' : 'simple',
-      ofShape: iri(row.ofShape),
-      ofProperty: iri(row.ofProperty),
-      ofResource: iri(row.ofResource),
-      fromPackage: row.fromPackage || undefined,
-      overridden:
-        (row as any).overridden === true || (row as any).overridden === 'true'
-          ? true
-          : undefined,
-      versions: [],
-      units: {},
-    });
-  }
-
-  for (const row of versionRows ?? []) {
-    const key = row?.ofKey?.key;
-    const entry = key ? entries.get(key) : undefined;
-    const version = toKeyVersionRecord(row);
-    if (!entry || !version) continue;
-    entry.versions!.push(version);
-    if (currentVersionByKey.get(key!) === version.id) {
-      entry.currentVersion = version;
-    }
-  }
-  for (const entry of entries.values()) {
-    entry.versions?.sort(
-      (left, right) =>
-        (right.createdAt ?? '').localeCompare(left.createdAt ?? '') ||
-        right.versionId.localeCompare(left.versionId),
-    );
-    if (!entry.versions?.length) delete entry.versions;
-  }
-
-  const unitCandidates = new Map<
-    string,
-    { score: number; record: TranslationUnitRecord }
-  >();
-  for (const row of unitRows ?? []) {
-    const key = row?.ofKey?.key;
-    const language = row?.language;
-    const entry = key ? entries.get(key) : undefined;
-    if (!entry || !language) continue;
-    const keyVersionId = iri(row.ofKeyVersion);
-    const score =
-      keyVersionId && keyVersionId === entry.currentVersion?.id
-        ? 2
-        : keyVersionId
-          ? 1
-          : 0;
-    const candidateKey = `${key}\u0000${language}`;
-    if ((unitCandidates.get(candidateKey)?.score ?? -1) >= score) continue;
-    unitCandidates.set(candidateKey, {
-      score,
-      record: {
-        language,
-        text: row.text ?? '',
-        state:
-          entry.currentVersion && score < 2
-            ? 'stale'
-            : normalizeState(row.state),
-        origin: row.origin || undefined,
-        updatedAt: isoDate(row.updatedAt) || undefined,
-        keyVersionId,
-      },
-    });
-  }
-  for (const [candidateKey, { record }] of unitCandidates) {
-    const [key, language] = candidateKey.split('\u0000');
-    const entry = entries.get(key);
-    if (entry) entry.units[language] = record;
-  }
-
-  return [...entries.values()].sort((a, b) => a.key.localeCompare(b.key));
-}
-
-/** App-scoped key read shared by the RPC provider and managed key-sync flows. */
-export async function listTranslationKeys(data: { appId: string }) {
-  const appId = requireText(data.appId, 'appId');
-  return TranslationKey.select((k) => [
-    k.namespace,
-    k.key,
-    k.sourceText,
-    k.description,
-    k.kind,
-    k.ofNode,
-    k.ofField,
-    k.ofShape,
-    k.ofProperty,
-    k.ofResource,
-    k.fromPackage,
-    k.overridden,
-    k.format,
-    k.currentVersion,
-  ]).where((k) => k.ofApplication.equals({ id: appId } as any));
-}
-
-/**
- * App-scoped keys + grouped language units as plain records — the read behind
- * the editor RPC AND the publish/compile flow (Plan 016 P2.3). No auth of its
- * own (the RPC wrapper gates); callers on the server run it in request context.
- */
-export async function listTranslationEntries(data: {
-  appId: string;
-}): Promise<TranslationEntryRecord[]> {
-  const appId = requireText(data.appId, 'appId');
-  const [keys, units, versions] = await Promise.all([
-    TranslationKey.select((k) => [
-      k.namespace,
-      k.key,
-      k.sourceText,
-      k.description,
-      k.kind,
-      k.format,
-      k.ofShape,
-      k.ofProperty,
-      k.ofResource,
-      k.fromPackage,
-      k.overridden,
-      k.currentVersion,
-    ]).where((k) => k.ofApplication.equals({ id: appId } as any)),
-    TranslationUnit.select((u) => [
-      u.language,
-      u.text,
-      u.state,
-      u.origin,
-      u.updatedAt,
-      u.ofKeyVersion,
-      u.ofKey.select((k) => [k.key]),
-    ]).where((u) => u.ofKey.ofApplication.equals({ id: appId } as any)),
-    TranslationKeyVersion.select((v) => [
-      v.versionId,
-      v.sourceLanguage,
-      v.sourceText,
-      v.format,
-      v.argumentSignature,
-      v.contractHash,
-      v.sourceHash,
-      v.supersedes,
-      v.createdAt,
-      v.createdBy,
-      v.ofKey.select((k) => [k.key]),
-    ]).where((v) => v.ofApplication.equals({ id: appId } as any)),
-  ]);
-  return groupTranslationEntries(keys as any, units as any, versions as any);
-}
-
-export async function listTranslationKeyVersions(data: {
-  appId: string;
-  key?: string;
-}): Promise<TranslationKeyVersionRecord[]> {
-  const appId = requireText(data.appId, 'appId');
-  const keyId = data.key
-    ? keyIri(appId, requireText(data.key, 'key'))
-    : undefined;
-  const query = TranslationKeyVersion.select((v) => [
-    v.versionId,
-    v.sourceLanguage,
-    v.sourceText,
-    v.format,
-    v.argumentSignature,
-    v.contractHash,
-    v.sourceHash,
-    v.supersedes,
-    v.createdAt,
-    v.createdBy,
-  ]).where((v) =>
-    keyId
-      ? v.ofApplication
-          .equals({ id: appId } as any)
-          .and(v.ofKey.equals({ id: keyId } as any))
-      : v.ofApplication.equals({ id: appId } as any),
-  );
-  const rows = await query;
-  return (rows ?? [])
-    .map((row: any) => toKeyVersionRecord(row))
-    .filter(
-      (record): record is TranslationKeyVersionRecord => record !== null,
-    )
-    .sort(
-      (left, right) =>
-        (right.createdAt ?? '').localeCompare(left.createdAt ?? '') ||
-        right.versionId.localeCompare(left.versionId),
-    );
-}
-
-function toReleaseRecord(row: any): TranslationReleaseRecord | null {
-  const id = iri(row?.id) ?? iri(row);
-  const appId = iri(row?.ofApplication);
-  const branchId = iri(row?.branch);
-  if (!id || !appId || !branchId || !row?.releaseId) return null;
-  return {
-    id,
-    releaseId: row.releaseId,
-    appId,
-    branchId,
-    buildId: row.buildId || undefined,
-    channel: row.channel === 'production' ? 'production' : 'preview',
-    status: ['published', 'superseded', 'retired'].includes(row.status)
-      ? row.status
-      : 'draft',
-    contractSetHash: row.contractSetHash || '',
-    manifestHash: row.manifestHash || '',
-    hotfixSequence: Number(row.hotfixSequence ?? 0),
-    qualitySummary: row.qualitySummary || undefined,
-    createdAt: isoDate(row.createdAt) || '',
-    publishedAt: isoDate(row.publishedAt) || undefined,
-    supportedUntil: isoDate(row.supportedUntil) || undefined,
-    supersedes: iri(row.supersedes),
-  };
-}
-
-export async function listTranslationReleases(data: {
-  appId: string;
-}): Promise<TranslationReleaseRecord[]> {
-  const appId = requireText(data.appId, 'appId');
-  const rows = await TranslationRelease.select((release) => [
-    release.releaseId,
-    release.ofApplication,
-    release.branch,
-    release.buildId,
-    release.channel,
-    release.status,
-    release.contractSetHash,
-    release.manifestHash,
-    release.hotfixSequence,
-    release.qualitySummary,
-    release.createdAt,
-    release.publishedAt,
-    release.supportedUntil,
-    release.supersedes,
-  ]).where((release) =>
-    release.ofApplication.equals({ id: appId } as any),
-  );
-  return (rows ?? [])
-    .map(toReleaseRecord)
-    .filter((record): record is TranslationReleaseRecord => record !== null)
-    .sort((left, right) => right.createdAt.localeCompare(left.createdAt));
-}
-
-export async function createTranslationRelease(
-  data: Omit<TranslationReleaseRecord, 'id' | 'createdAt'> & {
-    createdAt?: string;
-  },
-): Promise<TranslationReleaseRecord> {
-  const appId = requireText(data.appId, 'appId');
-  const releaseId = requireText(data.releaseId, 'releaseId');
-  const branchId = requireText(data.branchId, 'branchId');
-  if (!['preview', 'production'].includes(data.channel)) {
-    throw new Error('channel must be preview or production.');
-  }
-  if (!['draft', 'published', 'superseded', 'retired'].includes(data.status)) {
-    throw new Error('Invalid translation release status.');
-  }
-  const id = `${appId.replace(/\/$/, '')}/translation/release/${encodeURIComponent(releaseId)}`;
-  const existing = await TranslationRelease.select((release) => [
-    release.releaseId,
-  ])
-    .where((release) => release.equals({ id } as any))
-    .one()
-    .catch(() => null);
-  if (existing) {
-    throw new Error(`Translation release "${releaseId}" already exists.`);
-  }
-  const createdAt = data.createdAt || new Date().toISOString();
-  await TranslationRelease.create({
-    __id: id,
-    ofApplication: { id: appId },
-    branch: { id: branchId },
-    releaseId,
-    buildId: data.buildId,
-    channel: data.channel,
-    status: data.status,
-    contractSetHash: requireText(data.contractSetHash, 'contractSetHash'),
-    manifestHash: requireText(data.manifestHash, 'manifestHash'),
-    hotfixSequence: data.hotfixSequence,
-    qualitySummary: data.qualitySummary,
-    createdAt: new Date(createdAt),
-    publishedAt: data.publishedAt ? new Date(data.publishedAt) : undefined,
-    supportedUntil: data.supportedUntil ? new Date(data.supportedUntil) : undefined,
-    supersedes: data.supersedes ? { id: data.supersedes } : undefined,
-  } as any);
-  return { ...data, id, createdAt };
-}
-
-export async function advanceTranslationReleaseHotfix(data: {
-  id: string;
-  expectedSequence: number;
-  hotfixSequence: number;
-  manifestHash: string;
-  /** When given, the release must belong to this app. */
-  appId?: string;
-}): Promise<TranslationReleaseRecord> {
-  const id = requireText(data.id, 'id');
-  const current = await TranslationRelease.select((release) => [
-    release.releaseId,
-    release.ofApplication,
-    release.branch,
-    release.buildId,
-    release.channel,
-    release.status,
-    release.contractSetHash,
-    release.manifestHash,
-    release.hotfixSequence,
-    release.qualitySummary,
-    release.createdAt,
-    release.publishedAt,
-    release.supportedUntil,
-    release.supersedes,
-  ])
-    .where((release) => release.equals({ id } as any))
-    .one()
-    .catch(() => null);
-  const record = current ? toReleaseRecord(current) : null;
-  if (!record) throw new Error(`Translation release "${id}" was not found.`);
-  if (data.appId && !sameAppId(record.appId, data.appId)) {
-    throw new Error(`Translation release "${id}" was not found.`);
-  }
-  if (record.hotfixSequence !== data.expectedSequence) {
-    throw new Error(
-      `Translation release advanced from sequence ${data.expectedSequence} to ${record.hotfixSequence}.`,
-    );
-  }
-  await TranslationRelease.update({
-    hotfixSequence: data.hotfixSequence,
-    manifestHash: requireText(data.manifestHash, 'manifestHash'),
-  } as any).for({ id } as any);
-  return {
-    ...record,
-    hotfixSequence: data.hotfixSequence,
-    manifestHash: data.manifestHash,
-  };
-}
-
-/**
- * The app a release IRI belongs to, without a trailing `/`. Release IRIs are
- * minted by `createTranslationRelease` as `<appId>/translation/release/<releaseId>`
- * with one trailing `/` of the app id dropped, so an app id `…/app/` and `…/app`
- * give the same release IRI. Compare with `sameAppId`.
- */
-function releaseAppId(id: unknown): string {
-  const clean = typeof id === 'string' ? id.trim() : '';
-  const marker = '/translation/release/';
-  const at = clean.lastIndexOf(marker);
-  if (at <= 0 || at + marker.length >= clean.length) {
-    throw new Error('Not a translation release id.');
-  }
-  return clean.slice(0, at);
-}
-
-/** Whether two app ids name the same app, as release IRIs see them. */
-function sameAppId(left: string, right: string): boolean {
-  return left.replace(/\/$/, '') === right.replace(/\/$/, '');
-}
-
-/**
- * The app id a release is stored under (`ofApplication`), when it is the app
- * its IRI names. Falls back to the app id read from the IRI, so a missing
- * release is still checked against that app.
- */
-async function storedReleaseAppId(id: string, fromIri: string): Promise<string> {
-  const row: any = await TranslationRelease.select((release) => [
-    release.ofApplication,
-  ])
-    .where((release) => release.equals({ id } as any))
-    .one()
-    .catch(() => null);
-  const stored = iri(row?.ofApplication);
-  return stored && sameAppId(stored, fromIri) ? stored : fromIri;
-}
-
-/** WebID of the signed-in caller; never a client-supplied author. */
-function actorWebIdOf(auth: any): string | undefined {
-  const webId =
-    auth?.userAccount?.accountOf?.id ??
-    auth?.webId ??
-    auth?.userAccount?.id ??
-    auth?.userAccount;
-  return typeof webId === 'string' && webId ? webId : undefined;
-}
-
-/**
- * An error the LINKED server answers with `status` instead of 500. It is
- * matched by shape (`name` + numeric `status`), as `ServerCallError.is` does,
- * so no newer `@_linked/server-utils` is needed to throw one.
- */
-function translationCallError(status: number, message: string): Error {
-  const error = new Error(message) as Error & { status: number };
-  error.name = 'ServerCallError';
-  error.status = status;
-  return error;
-}
-
-function requireText(value: string, label: string): string {
-  const clean = value?.trim();
-  if (!clean) throw new Error(`${label} is required.`);
-  return clean;
-}
-
-function keyIri(appId: string, key: string): string {
-  return `${appId.replace(/\/$/, '')}/translation/key/${encodeURIComponent(key)}`;
-}
-
-function versionIri(keyId: string, versionId: string): string {
-  return `${keyId.replace(/\/$/, '')}/version/${versionId}`;
-}
-
-function unitIri(keyVersionId: string, language: string): string {
-  return `${keyVersionId.replace(/\/$/, '')}/unit/${encodeURIComponent(language)}`;
-}
-
-/** Unique append-only revision IRI under the version-scoped cell it revises. */
-function revisionIri(keyVersionId: string, language: string): string {
-  const suffix = `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
-  return `${unitIri(keyVersionId, language)}/rev/${suffix}`;
-}
-
-async function readKeyVersion(
-  id: string,
-): Promise<TranslationKeyVersionRecord | null> {
-  const row = await TranslationKeyVersion.select((v) => [
-    v.versionId,
-    v.sourceLanguage,
-    v.sourceText,
-    v.format,
-    v.argumentSignature,
-    v.contractHash,
-    v.sourceHash,
-    v.supersedes,
-    v.createdAt,
-    v.createdBy,
-  ])
-    .where((v) => v.equals({ id } as any))
-    .one()
-    .catch(() => null);
-  return row ? toKeyVersionRecord(row as any) : null;
-}
-
-async function createTranslationKeyVersion(input: {
-  appId: string;
-  keyId: string;
-  sourceLanguage: string;
-  sourceText: string;
-  format: 'simple' | 'icu';
-  supersedes?: string;
-  createdBy?: string;
-  backfill?: boolean;
-}): Promise<TranslationKeyVersionRecord> {
-  const derived = input.backfill
-    ? await deriveBackfillKeyVersion(input)
-    : {
-        ...(await deriveTranslationKeyVersionContract(input)),
-        versionId: createMonotonicVersionId(),
-      };
-  const id = versionIri(input.keyId, derived.versionId);
-  const createdAt = new Date().toISOString();
-  await TranslationKeyVersion.create({
-    __id: id,
-    ofApplication: { id: input.appId },
-    ofKey: { id: input.keyId },
-    versionId: derived.versionId,
-    sourceLanguage: derived.sourceLanguage,
-    sourceText: derived.sourceText,
-    format: derived.format,
-    argumentSignature: derived.argumentSignature,
-    contractHash: derived.contractHash,
-    sourceHash: derived.sourceHash,
-    supersedes: input.supersedes ? { id: input.supersedes } : undefined,
-    createdAt: new Date(createdAt),
-    createdBy: input.createdBy ? { id: input.createdBy } : undefined,
-  } as any);
-  return {
-    id,
-    ...derived,
-    supersedes: input.supersedes,
-    createdAt,
-    createdBy: input.createdBy,
-  };
-}
-
-async function ensureCurrentKeyVersion(input: {
-  appId: string;
-  keyId: string;
-  currentVersion?: unknown;
-  sourceLanguage: string;
-  sourceText: string;
-  format: 'simple' | 'icu';
-  createdBy?: string;
-}): Promise<TranslationKeyVersionRecord> {
-  const currentId = iri(input.currentVersion);
-  if (currentId) {
-    const current = await readKeyVersion(currentId);
-    if (current) return current;
-  }
-  const initial = await createTranslationKeyVersion({
-    ...input,
-    backfill: true,
-  });
-  await TranslationKey.update({
-    currentVersion: { id: initial.id },
-  } as any).for({ id: input.keyId } as any);
-  return initial;
-}
-
-const REVISION_STATUSES = new Set<TranslationRevisionStatus>([
-  'applied',
-  'proposed',
-  'suggested',
-  'accepted',
-  'rejected',
-  'superseded',
-]);
-
-async function requireKeyWriteContext(input: {
-  appId: string;
-  key: string;
-  createdBy?: string;
-}): Promise<{ keyId: string; version: TranslationKeyVersionRecord }> {
-  const keyId = keyIri(input.appId, input.key);
-  const keyRow = await TranslationKey.select((k) => [
-    k.sourceText,
-    k.format,
-    k.currentVersion,
-  ])
-    .where((k) => k.equals({ id: keyId } as any))
-    .one()
-    .catch(() => null);
-  if (!keyRow) {
-    throw new Error(
-      `Translation key "${input.key}" does not exist for this app.`,
-    );
-  }
-  const version = await ensureCurrentKeyVersion({
-    appId: input.appId,
-    keyId,
-    currentVersion: (keyRow as any).currentVersion,
-    sourceLanguage: 'en',
-    sourceText: (keyRow as any).sourceText ?? '',
-    format: (keyRow as any).format === 'icu' ? 'icu' : 'simple',
-    createdBy: input.createdBy,
-  });
-  return { keyId, version };
-}
-
-/**
- * Convert LINKED revision rows into plain RPC-safe records, newest first.
- * Exported for package-unit testing; performs no I/O.
- */
-export function toRevisionRecords(
-  rows: Array<Record<string, unknown>> = [],
-): TranslationRevisionRecord[] {
-  const iri = (value: unknown): string | undefined =>
-    typeof value === 'string'
-      ? value
-      : (value as { id?: string } | undefined)?.id;
-  return rows
-    .filter((row) => typeof (row as any)?.text === 'string')
-    .map((row: any): TranslationRevisionRecord => ({
-      id: iri(row.id) ?? iri(row) ?? '',
-      key: row.ofKey?.key ?? '',
-      language: row.language ?? '',
-      text: row.text ?? '',
-      status: REVISION_STATUSES.has(row.status)
-        ? (row.status as TranslationRevisionStatus)
-        : 'applied',
-      author: iri(row.author),
-      authorKind: row.authorKind === 'machine' ? 'machine' : 'human',
-      mtProvider: row.mtProvider || undefined,
-      basedOnText: typeof row.basedOnText === 'string' ? row.basedOnText : undefined,
-      note: row.note || undefined,
-      createdAt: isoDate(row.createdAt) || undefined,
-      decidedAt: isoDate(row.decidedAt) || undefined,
-      decidedBy: iri(row.decidedBy),
-      keyVersionId: iri(row.ofKeyVersion),
-    }))
-    .sort(
-      (a, b) =>
-        (b.createdAt ?? '').localeCompare(a.createdAt ?? '') ||
-        b.id.localeCompare(a.id),
-    );
-}
-
-export async function getTranslationRevision(data: {
-  appId: string;
-  revisionId: string;
-}): Promise<TranslationRevisionRecord | null> {
-  const appId = requireText(data.appId, 'appId');
-  const revisionId = requireText(data.revisionId, 'revisionId');
-  const row = await TranslationRevision.select((revision) => [
-    revision.language,
-    revision.text,
-    revision.status,
-    revision.author,
-    revision.authorKind,
-    revision.mtProvider,
-    revision.basedOnText,
-    revision.note,
-    revision.createdAt,
-    revision.decidedAt,
-    revision.decidedBy,
-    revision.ofKeyVersion,
-    revision.ofKey.select((key) => [key.key]),
-  ])
-    .where((revision) =>
-      revision
-        .equals({ id: revisionId } as any)
-        .and(revision.ofApplication.equals({ id: appId } as any)),
-    )
-    .one()
-    .catch(() => null);
-  return row ? toRevisionRecords([row as any])[0] ?? null : null;
-}
-
-/** Pending human proposals for the app, optionally narrowed to one language. */
-export async function listTranslationProposals(data: {
-  appId: string;
-  language?: string;
-}): Promise<TranslationRevisionRecord[]> {
-  const appId = requireText(data.appId, 'appId');
-  const language = data.language?.trim();
-  const rows = await TranslationRevision.select((revision) => [
-    revision.language,
-    revision.text,
-    revision.status,
-    revision.author,
-    revision.authorKind,
-    revision.basedOnText,
-    revision.note,
-    revision.createdAt,
-    revision.ofKeyVersion,
-    revision.ofKey.select((key) => [key.key]),
-  ]).where((revision) => {
-    const base = revision.ofApplication
-      .equals({ id: appId } as any)
-      .and(revision.status.equals('proposed'));
-    return language ? base.and(revision.language.equals(language)) : base;
-  });
-  const proposals = toRevisionRecords(rows as any);
-  const entries = await listTranslationEntries({ appId });
-  const current = new Map(
-    entries.flatMap((entry) =>
-      Object.entries(entry.units).map(([unitLanguage, unit]) => [
-        `${entry.key}\u0000${unitLanguage}`,
-        unit.text,
-      ]),
-    ),
-  );
-  return proposals.map((proposal) => {
-    const currentText = current.get(`${proposal.key}\u0000${proposal.language}`) ?? '';
-    return {
-      ...proposal,
-      currentText,
-      conflicted: (proposal.basedOnText ?? '') !== currentText,
-    };
-  });
-}
-
-export async function decideTranslationProposal(
-  data: {
-    appId: string;
-    revisionId: string;
-    decision: 'accept' | 'reject';
-    note?: string;
-  },
-  reviewer?: string,
-): Promise<TranslationProposalDecision> {
-  const proposal = await getTranslationRevision({
-    appId: data.appId,
-    revisionId: data.revisionId,
-  });
-  if (!proposal || proposal.status !== 'proposed') {
-    throw new Error('This translation proposal is no longer pending.');
-  }
-  const decisionNote = data.note?.trim();
-  if (data.decision === 'reject' && !decisionNote) {
-    throw new Error('A reviewer note is required when rejecting a proposal.');
-  }
-  const now = new Date().toISOString();
-  let unit: TranslationUnitRecord | undefined;
-  if (data.decision === 'accept') {
-    const currentEntries = await listTranslationEntries({ appId: data.appId });
-    const currentText =
-      currentEntries.find(({ key }) => key === proposal.key)?.units[
-        proposal.language
-      ]?.text ?? '';
-    if ((proposal.basedOnText ?? '') !== currentText) {
-      throw new Error(
-        'This proposal conflicts with a newer translation. Review it again before accepting.',
-      );
-    }
-    await upsertTranslationUnit(
-      {
-        appId: data.appId,
-        key: proposal.key,
-        language: proposal.language,
-        text: proposal.text,
-        state: 'reviewed',
-      },
-      {
-        author: reviewer,
-        authorKind: 'human',
-        note: data.note || `Accepted proposal ${proposal.id}.`,
-      },
-    );
-    unit = {
-      language: proposal.language,
-      text: proposal.text,
-      state: 'reviewed',
-      updatedAt: now,
-    };
-    const competing = await listTranslationProposals({
-      appId: data.appId,
-      language: proposal.language,
-    });
-    await Promise.all(
-      competing
-        .filter(
-          ({ id, key }) => id !== proposal.id && key === proposal.key,
-        )
-        .map((revision) =>
-          TranslationRevision.update({
-            status: 'superseded',
-            note: `Superseded by accepted proposal ${proposal.id}.`,
-            decidedAt: new Date(now),
-            decidedBy: reviewer ? { id: reviewer } : undefined,
-          } as any).for({ id: revision.id } as any),
-        ),
-    );
-  }
-  await TranslationRevision.update({
-    status: data.decision === 'accept' ? 'accepted' : 'rejected',
-    note: decisionNote || proposal.note,
-    decidedAt: new Date(now),
-    decidedBy: reviewer ? { id: reviewer } : undefined,
-  } as any).for({ id: proposal.id } as any);
-  return {
-    revision: {
-      ...proposal,
-      status: data.decision === 'accept' ? 'accepted' : 'rejected',
-      note: decisionNote || proposal.note,
-      decidedAt: now,
-      decidedBy: reviewer,
-      conflicted: false,
-      currentText: unit?.text ?? proposal.currentText,
-    },
-    unit,
-  };
-}
-
-/**
- * Idempotent key write shared by the RPC provider and managed key-sync flows.
- * Source drift marks every existing language unit stale before returning.
- */
-export async function upsertTranslationKey(
-  data: TranslationKeyInput,
-  authorship: TranslationKeyWriteContext = {},
-): Promise<TranslationKeyWriteResult> {
-  const appId = requireText(data.appId, 'appId');
-  const key = requireText(data.key, 'key');
-  requireText(data.sourceText, 'sourceText');
-  const id = keyIri(appId, key);
-  const values = {
-    namespace: data.namespace ?? key.split('.').slice(0, -1).join('.'),
-    key,
-    sourceText: data.sourceText,
-    description: data.description,
-    kind: data.kind ?? 'ui',
-    ofApplication: { id: appId },
-    ofNode: data.ofNode ? { id: data.ofNode } : undefined,
-    ofField: data.ofField,
-    ofShape: data.ofShape ? { id: data.ofShape } : undefined,
-    ofProperty: data.ofProperty ? { id: data.ofProperty } : undefined,
-    ofResource: data.ofResource ? { id: data.ofResource } : undefined,
-    fromPackage: data.fromPackage,
-    overridden: data.overridden,
-    format: data.format ?? 'simple',
-  } as any;
-  // No catch: a failed read is not permission to create or overwrite the key.
-  const existing = await TranslationKey.select((k) => [
-    k.sourceText,
-    k.format,
-    k.ofShape,
-    k.ofProperty,
-    k.ofResource,
-    k.fromPackage,
-    k.overridden,
-    k.currentVersion,
-  ])
-    .where((k) => k.equals({ id } as any))
-    .one();
-  if (existing) {
-    const sourceChanged = (existing as any).sourceText !== data.sourceText;
-    const formatChanged =
-      ((existing as any).format ?? 'simple') !== (data.format ?? 'simple');
-    const wasOverridden = (existing as any).overridden === true;
-    if (authorship.source === 'declaration-sync' && wasOverridden) {
-      const versionId = iri((existing as any).currentVersion);
-      if (!versionId)
-        throw new Error(
-          `Translation override ${id} has no current version; refresh refused without changing its source.`
-        );
-      // No key write, version creation or unit invalidation. The declaration
-      // inventory still records the package's current source independently.
-      return { id, versionId, versionCreated: false, preservedOverride: true };
-    }
-    // AD-N ownership also covers property/resource/package declarations (help,
-    // actions, groups), not only shapes. App edits preserve the first canonical
-    // wording in the existing shapeSource carrier. Only an explicit app edit
-    // may clear the override; automatic discovery cannot clear it by payload.
-    const isDeclaredKey = !!(
-      (existing as any).ofShape ||
-      (existing as any).ofProperty ||
-      (existing as any).ofResource ||
-      (existing as any).fromPackage ||
-      data.ofShape ||
-      data.ofProperty ||
-      data.ofResource ||
-      data.fromPackage
-    );
-    if (
-      authorship.source !== 'declaration-sync' &&
-      data.overridden === undefined &&
-      isDeclaredKey &&
-      (sourceChanged || formatChanged)
-    ) {
-      values.overridden = true;
-      // Snapshot the canonical at FIRST divergence so "clear override" has a
-      // value to revert to even for a single-app project. Later edits keep the
-      // original snapshot (don't re-capture the already-overridden wording).
-      if (!wasOverridden) values.shapeSource = (existing as any).sourceText;
-    }
-    const currentVersion = await ensureCurrentKeyVersion({
-      appId,
-      keyId: id,
-      currentVersion: (existing as any).currentVersion,
-      sourceLanguage: data.sourceLanguage ?? 'en',
-      sourceText: (existing as any).sourceText ?? '',
-      format: (existing as any).format === 'icu' ? 'icu' : 'simple',
-      createdBy: authorship.createdBy,
-    });
-    const decision = classifyKeyVersion(currentVersion, {
-      sourceText: data.sourceText,
-      format: data.format ?? 'simple',
-    });
-    const nextVersion =
-      decision.action === 'create-version'
-        ? await createTranslationKeyVersion({
-            appId,
-            keyId: id,
-            sourceLanguage:
-              data.sourceLanguage ?? currentVersion.sourceLanguage ?? 'en',
-            sourceText: data.sourceText,
-            format: data.format ?? 'simple',
-            supersedes: currentVersion.id,
-            createdBy: authorship.createdBy,
-          })
-        : currentVersion;
-    values.currentVersion = { id: nextVersion.id };
-    // In the Linked mutation DSL an explicitly present `undefined` removes
-    // that predicate. A partial source edit has not requested removal of the
-    // declaration owner, help description, or existing override flag. Omit
-    // untouched fields; an explicit false (reset) remains a real write.
-    const patch = Object.fromEntries(
-      Object.entries(values).filter(([, value]) => value !== undefined)
-    );
-    await TranslationKey.update(patch as any).for({ id } as any);
-    if (decision.action === 'create-version') {
-      await TranslationUnit.update({ state: 'stale' } as any).where((u) =>
-        u.ofKey.equals({ id } as any),
-      );
-    }
-    return {
-      id,
-      versionId: nextVersion.id,
-      versionCreated: decision.action === 'create-version',
-    };
-  }
-  await TranslationKey.create({ __id: id, ...values });
-  const firstVersion = await createTranslationKeyVersion({
-    appId,
-    keyId: id,
-    sourceLanguage: data.sourceLanguage ?? 'en',
-    sourceText: data.sourceText,
-    format: data.format ?? 'simple',
-    createdBy: authorship.createdBy,
-  });
-  await TranslationKey.update({
-    currentVersion: { id: firstVersion.id },
-  } as any).for({ id } as any);
-  return { id, versionId: firstVersion.id, versionCreated: true };
-}
-
-/**
- * Append one revision WITHOUT touching the unit (Plan 017 AD-P) — the write
- * path for MT SUGGESTIONS (Slice B) and translator PROPOSALS (Slice C): a
- * pending value a reviewer/editor applies later. `basedOnText` should carry
- * the unit text visible to the author, for conflict detection at decision time.
- */
-export async function createTranslationRevision(data: {
-  appId: string;
-  key: string;
-  language: string;
-  text: string;
-  status: TranslationRevisionStatus;
-  author?: string;
-  authorKind?: 'human' | 'machine';
-  mtProvider?: string;
-  basedOnText?: string;
-  note?: string;
-}): Promise<{ id: string }> {
-  const appId = requireText(data.appId, 'appId');
-  const key = requireText(data.key, 'key');
-  const language = requireText(data.language, 'language');
-  const { keyId, version } = await requireKeyWriteContext({
-    appId,
-    key,
-    createdBy: data.author,
-  });
-  const id = revisionIri(version.id, language);
-  await TranslationRevision.create({
-    __id: id,
-    ofApplication: { id: appId },
-    ofKey: { id: keyId },
-    ofKeyVersion: { id: version.id },
-    language,
-    text: data.text,
-    status: data.status,
-    author: data.author ? { id: data.author } : undefined,
-    authorKind: data.authorKind ?? 'human',
-    mtProvider: data.mtProvider,
-    basedOnText: data.basedOnText,
-    note: data.note,
-    createdAt: new Date(),
-  } as any);
-  return { id };
-}
-
-/**
- * Idempotent unit write shared by the RPC provider, import, and (P4) MT flows.
- * Every write that CHANGES the text also records an append-only
- * `status:'applied'` `TranslationRevision` (Plan 017 AD-P) carrying the
- * previous text as `basedOnText` — the audit trail behind the history UI.
- * Re-saving identical text updates state/provenance without a revision.
- */
-export async function upsertTranslationUnit(
-  data: TranslationUnitInput,
-  authorship: TranslationAuthorship = {},
-): Promise<{ id: string; revisionId?: string }> {
-  const appId = requireText(data.appId, 'appId');
-  const key = requireText(data.key, 'key');
-  const language = requireText(data.language, 'language');
-  const author = authorship.author ?? data.updatedBy;
-  const { keyId, version } = await requireKeyWriteContext({
-    appId,
-    key,
-    createdBy: author,
-  });
-  const now = new Date().toISOString();
-  const values = {
-    ofApplication: { id: appId },
-    ofKey: { id: keyId },
-    ofKeyVersion: { id: version.id },
-    language,
-    text: data.text,
-    state: data.state ?? 'reviewed',
-    updatedAt: new Date(now),
-    updatedBy: author ? { id: author } : undefined,
-    origin: authorship.mtProvider === 'tm' ? 'tm' : '',
-  } as any;
-  const existing = await TranslationUnit.select((u) => [u.text])
-    .where((u) =>
-      u.language
-        .equals(language)
-        .and(u.ofKeyVersion.equals({ id: version.id } as any)),
-    )
-    .one()
-    .catch(() => null);
-  const id =
-    iri((existing as any)?.id) ?? unitIri(version.id, language);
-  if (existing) await TranslationUnit.update(values).for({ id } as any);
-  else await TranslationUnit.create({ __id: id, ...values });
-
-  const previousText = (existing as any)?.text as string | undefined;
-  if (existing && previousText === data.text) return { id };
-  const revisionId = revisionIri(version.id, language);
-  await TranslationRevision.create({
-    __id: revisionId,
-    ofApplication: { id: appId },
-    ofKey: { id: keyId },
-    ofKeyVersion: { id: version.id },
-    language,
-    text: data.text,
-    status: 'applied',
-    author: author ? { id: author } : undefined,
-    authorKind: authorship.authorKind ?? 'human',
-    mtProvider: authorship.mtProvider,
-    basedOnText: previousText,
-    note: authorship.note,
-    createdAt: new Date(now),
-  } as any);
-  return { id, revisionId };
-}
-
-/** One app-scoped lookup powers both exact TM and same-key carry-forward. */
-export async function listTranslationMemoryMatches(data: {
-  appId: string;
-  key: string;
-  language: string;
-}): Promise<TranslationMemoryMatchRecord[]> {
-  const appId = requireText(data.appId, 'appId');
-  const key = requireText(data.key, 'key');
-  const language = requireText(data.language, 'language');
-  const keyId = keyIri(appId, key);
-  const keyRow = await TranslationKey.select((candidate) => [
-    candidate.currentVersion,
-  ])
-    .where((candidate) => candidate.equals({ id: keyId } as any))
-    .one()
-    .catch(() => null);
-  const currentVersionId = iri((keyRow as any)?.currentVersion);
-  const currentVersion = currentVersionId
-    ? await readKeyVersion(currentVersionId)
-    : null;
-  if (!currentVersion) return [];
-
-  const rows = await TranslationUnit.select((unit) => [
-    unit.language,
-    unit.text,
-    unit.state,
-    unit.updatedAt,
-    unit.ofKey.select((candidate) => [candidate.key]),
-    unit.ofKeyVersion.select((version) => [
-      version.sourceText,
-      version.sourceHash,
-      version.contractHash,
-    ]),
-  ]).where((unit) =>
-    unit.ofApplication
-      .equals({ id: appId } as any)
-      .and(unit.language.equals(language))
-      .and(unit.state.equals('reviewed')),
-  );
-  return classifyTranslationMemoryMatches({
-    key,
-    language,
-    currentVersion,
-    rows: rows as any,
-  });
-}
-
-/** App-scoped reviewed-unit index for search, audit, and exact reuse. */
-export async function listTranslationMemory(data: {
-  appId: string;
-}): Promise<TranslationMemoryRecord[]> {
-  const appId = requireText(data.appId, 'appId');
-  const rows = await TranslationUnit.select((unit) => [
-    unit.language,
-    unit.text,
-    unit.state,
-    unit.updatedAt,
-    unit.ofKey.select((candidate) => [candidate.key]),
-    unit.ofKeyVersion.select((version) => [
-      version.sourceText,
-      version.sourceHash,
-      version.contractHash,
-    ]),
-  ]).where((unit) =>
-    unit.ofApplication
-      .equals({ id: appId } as any)
-      .and(unit.state.equals('reviewed')),
-  );
-  return toTranslationMemoryRecords(rows as any);
-}
-
-/** Preview or apply every safe exact-match TM candidate for one language. */
-export async function pretranslateFromMemory(
-  data: {
-    appId: string;
-    language: string;
-    dryRun?: boolean;
-  },
-  authorship: { author?: string } = {},
-): Promise<TranslationMemoryPretranslateReport> {
-  const appId = requireText(data.appId, 'appId');
-  const language = requireText(data.language, 'language');
-  const [entries, memory] = await Promise.all([
-    listTranslationEntries({ appId }),
-    listTranslationMemory({ appId }),
-  ]);
-  const candidates = findExactMemoryPretranslations({
-    entries,
-    memory,
-    language,
-  });
-  if (!data.dryRun) {
-    for (const candidate of candidates) {
-      await upsertTranslationUnit(
-        {
-          appId,
-          key: candidate.key,
-          language,
-          text: candidate.text,
-          state: 'machine',
-        },
-        {
-          author: authorship.author,
-          authorKind: 'machine',
-          mtProvider: 'tm',
-          note: `Exact translation-memory match from ${candidate.sourceKey}.`,
-        },
-      );
-    }
-  }
-  return {
-    language,
-    eligible: candidates.length,
-    translated: data.dryRun ? 0 : candidates.length,
-    candidates,
-  };
-}
-
-/** App-data termbase read shared by Studio, MT, and publish quality gates. */
-export async function listGlossaryTerms(data: {
-  appId: string;
-}): Promise<GlossaryTermRecord[]> {
-  requireText(data.appId, 'appId');
-  const rows = await GlossaryTerm.select((glossary) => [
-    glossary.term,
-    glossary.translation,
-    glossary.language,
-    glossary.description,
-    glossary.termType,
-    glossary.useInstead,
-    glossary.caseSensitive,
-  ]).catch(() => []);
-  return (rows ?? [])
-    .filter((row: any) => row?.term)
-    .map((row: any) => ({
-      id: typeof row.id === 'string' ? row.id : (row.id?.id ?? ''),
-      term: row.term,
-      termType:
-        row.termType === 'keep' || row.termType === 'forbid' || row.termType === 'require'
-          ? row.termType
-          : 'prefer',
-      translation: row.translation || undefined,
-      useInstead: row.useInstead || undefined,
-      language: row.language || undefined,
-      caseSensitive:
-        row.caseSensitive === true || row.caseSensitive === 'true'
-          ? true
-          : undefined,
-      description: row.description || undefined,
-    }))
-    .sort(
-      (left: GlossaryTermRecord, right: GlossaryTermRecord) =>
-        left.term.localeCompare(right.term) ||
-        (left.language ?? '').localeCompare(right.language ?? ''),
-    );
-}
-
-/**
- * Apply a server-validated memory candidate. Exact matches retain `machine`
- * state and `tm` provenance; changed-source carry-forward is an explicit
- * reviewer action and becomes reviewed.
- */
-export async function applyTranslationMemoryMatch(
-  data: {
-    appId: string;
-    key: string;
-    language: string;
-    unitId: string;
-  },
-  authorship: { author?: string } = {},
-): Promise<TranslationUnitRecord> {
-  const unitId = requireText(data.unitId, 'unitId');
-  const match = (
-    await listTranslationMemoryMatches({
-      appId: data.appId,
-      key: data.key,
-      language: data.language,
-    })
-  ).find((candidate) => candidate.unitId === unitId);
-  if (!match) {
-    throw new Error(
-      'Translation-memory candidate is no longer compatible with this key version.',
-    );
-  }
-  const state: TranslationState =
-    match.kind === 'exact' ? 'machine' : 'reviewed';
-  await upsertTranslationUnit(
-    {
-      appId: data.appId,
-      key: data.key,
-      language: data.language,
-      text: match.text,
-      state,
-    },
-    {
-      author: authorship.author,
-      authorKind: match.kind === 'exact' ? 'machine' : 'human',
-      mtProvider: match.kind === 'exact' ? 'tm' : undefined,
-      note:
-        match.kind === 'exact'
-          ? `Exact translation-memory match from ${match.key}.`
-          : `Reviewed carry-forward from ${match.keyVersionId}.`,
-    },
-  );
-  return {
-    language: data.language,
-    text: match.text,
-    state,
-    origin: match.kind === 'exact' ? 'tm' : undefined,
-    updatedAt: new Date().toISOString(),
-  };
-}
-
-/** Server boundary for app-scoped translation keys and language units. */
-export class TranslationProvider extends ShapeProvider {
-  public shape = TranslationKey;
-
-  /**
-   * Authoring gate. Reads `linkedAuth` off the request the LINKED server already
-   * populates, so this stays portable (no host-application import, AD-G).
-   *
-   * Every method except `getMessages` resolves the caller once, synchronously,
-   * before its first `await`, and uses that value for both the permission check
-   * and the recorded author. Reading the request again after an `await` could
-   * see a different call's request on this shared provider instance.
-   *
-   * Whether the caller may act on `appId` is decided by the host's resolver
-   * (`configureTranslationAuthorization`); with none configured, every
-   * authoring and read action is denied. `getMessages` stays public: it is the
-   * app's runtime string fetch, not an authoring surface.
-   *
-   * `requireActor` and `requireAccess` are `@internal()`: helpers of the
-   * methods below, never dispatched over HTTP.
-   */
-  @internal()
-  private requireActor(): string {
-    const auth = (this as any).request?.linkedAuth;
-    if (!auth?.userAccount) {
-      throw translationCallError(
-        401,
-        'Authentication required to read or edit translations.',
-      );
-    }
-    const webId = actorWebIdOf(auth);
-    if (!webId) {
-      throw new Error('Translation permission required.');
-    }
-    return webId;
-  }
-
-  @internal()
-  private async requireAccess(
-    actorWebId: string,
-    data: { appId: string; language?: string },
-    action: TranslationAuthoringAction,
-  ): Promise<void> {
-    const appId = typeof data?.appId === 'string' ? data.appId.trim() : '';
-    if (!appId) throw new Error('appId is required.');
-    if (
-      !(await canAuthorTranslation({
-        appId,
-        actorWebId,
-        action,
-        language: data?.language,
-      }))
-    ) {
-      throw new Error(`Translation ${action} permission required.`);
-    }
-  }
-
-  @callable('signed-in')
-  async listKeys(data: { appId: string }) {
-    const actor = this.requireActor();
-    await this.requireAccess(actor, { appId: data?.appId }, 'read');
-    return listTranslationKeys(data);
-  }
-
-  @callable('signed-in')
-  async listEntries(data: { appId: string }): Promise<TranslationEntryRecord[]> {
-    const actor = this.requireActor();
-    await this.requireAccess(actor, { appId: data?.appId }, 'read');
-    return listTranslationEntries(data);
-  }
-
-  @callable('signed-in')
-  async listKeyVersions(data: {
-    appId: string;
-    key?: string;
-  }): Promise<TranslationKeyVersionRecord[]> {
-    const actor = this.requireActor();
-    await this.requireAccess(actor, { appId: data?.appId }, 'read');
-    return listTranslationKeyVersions(data);
-  }
-
-  @callable('signed-in')
-  async listMemoryMatches(data: {
-    appId: string;
-    key: string;
-    language: string;
-  }): Promise<TranslationMemoryMatchRecord[]> {
-    const actor = this.requireActor();
-    await this.requireAccess(actor, { appId: data?.appId }, 'read');
-    return listTranslationMemoryMatches(data);
-  }
-
-  @callable('signed-in')
-  async proposeRevision(data: {
-    appId: string;
-    key: string;
-    language: string;
-    text: string;
-    basedOnText?: string;
-    note?: string;
-  }): Promise<{ id: string }> {
-    const actor = this.requireActor();
-    await this.requireAccess(actor, data, 'propose');
-    const currentEntries = await listTranslationEntries({ appId: data.appId });
-    const basedOnText =
-      currentEntries.find(({ key }) => key === data.key)?.units[data.language]
-        ?.text ?? '';
-    return createTranslationRevision({
-      ...data,
-      basedOnText,
-      status: 'proposed',
-      author: actor,
-      authorKind: 'human',
-    });
-  }
-
-  @callable('signed-in')
-  async listProposals(data: {
-    appId: string;
-    language?: string;
-  }): Promise<TranslationRevisionRecord[]> {
-    const actorWebId = this.requireActor();
-    await this.requireAccess(actorWebId, { appId: data?.appId }, 'read');
-    const proposals = await listTranslationProposals(data);
-    const allowed = await Promise.all(
-      proposals.map((proposal) =>
-        canAuthorTranslation({
-          appId: data.appId,
-          actorWebId,
-          action: 'read',
-          language: proposal.language,
-        }),
-      ),
-    );
-    return proposals.filter((_, index) => allowed[index]);
-  }
-
-  @callable('signed-in')
-  async decideProposal(data: {
-    appId: string;
-    revisionId: string;
-    decision: 'accept' | 'reject';
-    note?: string;
-  }): Promise<TranslationProposalDecision> {
-    const actor = this.requireActor();
-    await this.requireAccess(actor, { appId: data.appId }, 'review');
-    const proposal = await getTranslationRevision({
-      appId: data.appId,
-      revisionId: data.revisionId,
-    });
-    if (!proposal) {
-      throw new Error('This translation proposal is no longer pending.');
-    }
-    await this.requireAccess(
-      actor,
-      { appId: data.appId, language: proposal.language },
-      'review',
-    );
-    return decideTranslationProposal(data, actor);
-  }
-
-  @callable('signed-in')
-  async listMemory(data: {
-    appId: string;
-  }): Promise<TranslationMemoryRecord[]> {
-    const actor = this.requireActor();
-    await this.requireAccess(actor, { appId: data?.appId }, 'read');
-    return listTranslationMemory(data);
-  }
-
-  @callable('signed-in')
-  async pretranslateMemory(data: {
-    appId: string;
-    language: string;
-    dryRun?: boolean;
-  }): Promise<TranslationMemoryPretranslateReport> {
-    const actor = this.requireActor();
-    await this.requireAccess(actor, data, 'run-mt');
-    return pretranslateFromMemory(data, { author: actor });
-  }
-
-  @callable('signed-in')
-  async applyMemoryMatch(data: {
-    appId: string;
-    key: string;
-    language: string;
-    unitId: string;
-  }): Promise<TranslationUnitRecord> {
-    const actor = this.requireActor();
-    await this.requireAccess(actor, data, 'review');
-    return applyTranslationMemoryMatch(data, { author: actor });
-  }
-
-  @callable('signed-in')
-  async listReleases(data: {
-    appId: string;
-  }): Promise<TranslationReleaseRecord[]> {
-    const actor = this.requireActor();
-    await this.requireAccess(actor, { appId: data?.appId }, 'read');
-    return listTranslationReleases(data);
-  }
-
-  @callable('signed-in')
-  async createRelease(
-    data: Omit<TranslationReleaseRecord, 'id' | 'createdAt'> & {
-      createdAt?: string;
-    },
-  ): Promise<TranslationReleaseRecord> {
-    const actor = this.requireActor();
-    await this.requireAccess(actor, data, 'manage');
-    return createTranslationRelease(data);
-  }
-
-  @callable('signed-in')
-  async advanceReleaseHotfix(data: {
-    id: string;
-    expectedSequence: number;
-    hotfixSequence: number;
-    manifestHash: string;
-  }): Promise<TranslationReleaseRecord> {
-    const actor = this.requireActor();
-    const id = typeof data?.id === 'string' ? data.id.trim() : '';
-    const appId = await storedReleaseAppId(id, releaseAppId(id));
-    await this.requireAccess(actor, { appId }, 'manage');
-    return advanceTranslationReleaseHotfix({ ...data, appId });
-  }
-
-  @callable('signed-in')
-  async upsertKey(data: TranslationKeyInput): Promise<{ id: string }> {
-    const actor = this.requireActor();
-    await this.requireAccess(actor, data, 'manage');
-    return upsertTranslationKey(data, { createdBy: actor });
-  }
-
-  @callable('signed-in')
-  async upsertUnit(data: TranslationUnitInput): Promise<{ id: string }> {
-    const actor = this.requireActor();
-    await this.requireAccess(actor, data, 'review');
-    return upsertTranslationUnit(
-      { ...data, updatedBy: undefined },
-      { author: actor, authorKind: 'human' },
-    );
-  }
-
-  /**
-   * Glossary CRUD (Plan 017 Slice B). App-data is branch-routed per app, so
-   * every GlossaryTerm in context belongs to the calling app; the appId only
-   * anchors the IRIs. Uniqueness = (term, language) — upsert is
-   * delete-then-create on that identity.
-   */
-  @callable('signed-in')
-  async listGlossary(data: { appId: string }): Promise<GlossaryTermRecord[]> {
-    const actor = this.requireActor();
-    await this.requireAccess(actor, { appId: data?.appId }, 'read');
-    return listGlossaryTerms(data);
-  }
-
-  @callable('signed-in')
-  async upsertGlossaryTerm(data: {
-    appId: string;
-    term: string;
-    termType?: 'prefer' | 'require' | 'keep' | 'forbid';
-    translation?: string;
-    useInstead?: string;
-    language?: string;
-    caseSensitive?: boolean;
-    description?: string;
-  }): Promise<{ id: string }> {
-    const actor = this.requireActor();
-    await this.requireAccess(actor, data, 'manage');
-    const appId = requireText(data.appId, 'appId');
-    const term = requireText(data.term, 'term');
-    const language = data.language?.trim() || '';
-    const termType =
-      data.termType === 'keep' || data.termType === 'forbid' || data.termType === 'require'
-        ? data.termType
-        : 'prefer';
-    if (termType === 'require' && !data.translation?.trim()) {
-      throw new Error('A required glossary term needs a translation.');
-    }
-    const id = `${appId.replace(/\/$/, '')}/translation/glossary/${encodeURIComponent(
-      term,
-    )}--${encodeURIComponent(language || 'all')}`;
-    // Delete-then-create: INSERT DATA is add-only, re-saving would duplicate.
-    await (GlossaryTerm as any).delete({ id }).catch(() => {});
-    await GlossaryTerm.create({
-      __id: id,
-      term,
-      termType,
-      translation:
-        termType === 'prefer' || termType === 'require' ? data.translation?.trim() || undefined : undefined,
-      useInstead:
-        termType === 'forbid' ? data.useInstead?.trim() || undefined : undefined,
-      language: language || undefined,
-      caseSensitive: data.caseSensitive === true ? true : undefined,
-      description: data.description?.trim() || undefined,
-    } as any);
-    return { id };
-  }
-
-  @callable('signed-in')
-  async deleteGlossaryTerm(data: { appId: string; id: string }): Promise<{ deleted: boolean }> {
-    const actor = this.requireActor();
-    await this.requireAccess(actor, data, 'manage');
-    const appId = requireText(data.appId, 'appId');
-    const id = requireText(data.id, 'id');
-    // Only glossary nodes under this app's namespace may be deleted here.
-    if (!id.startsWith(`${appId.replace(/\/$/, '')}/translation/glossary/`)) {
-      throw new Error('Not a glossary entry of this app.');
-    }
-    await (GlossaryTerm as any).delete({ id });
-    return { deleted: true };
-  }
-
-  /** History for one (key, language) cell — newest first (Plan 017 AD-P). */
-  @callable('signed-in')
-  async listRevisions(data: {
-    appId: string;
-    key: string;
-    language: string;
-  }): Promise<TranslationRevisionRecord[]> {
-    const actor = this.requireActor();
-    await this.requireAccess(actor, { appId: data?.appId }, 'read');
-    const appId = requireText(data.appId, 'appId');
-    const key = requireText(data.key, 'key');
-    const language = requireText(data.language, 'language');
-    const keyId = keyIri(appId, key);
-    const rows = await TranslationRevision.select((r) => [
-      r.language,
-      r.text,
-      r.status,
-      r.author,
-      r.authorKind,
-      r.mtProvider,
-      r.basedOnText,
-      r.note,
-      r.createdAt,
-      r.decidedAt,
-      r.decidedBy,
-      r.ofKeyVersion,
-      r.ofKey.select((k) => [k.key]),
-    ]).where((r) =>
-      r.language.equals(language).and(r.ofKey.equals({ id: keyId } as any)),
-    );
-    return toRevisionRecords(rows as any);
-  }
-
-  @callable('public')
-  async getMessages(data: {
-    appId: string;
-    language: string;
-  }): Promise<TranslationMessages> {
-    const appId = requireText(data.appId, 'appId');
-    const language = requireText(data.language, 'language');
-    const rows = await TranslationUnit.select((u) => [
-      u.text,
-      u.ofKeyVersion,
-      u.ofKey.select((k) => [k.key, k.format, k.currentVersion]),
-    ]).where((u) =>
-      u.language
-        .equals(language)
-        .and(u.ofKey.ofApplication.equals({ id: appId } as any)),
-    );
-    return Object.fromEntries(
-      (rows ?? [])
-        .filter((row: any) => {
-          const currentVersion = iri(row.ofKey?.currentVersion);
-          const unitVersion = iri(row.ofKeyVersion);
-          return !currentVersion || currentVersion === unitVersion;
-        })
-        .map((row: any) => [
-          row.ofKey?.key,
-          row.ofKey?.format === 'icu'
-            ? { message: row.text, format: 'icu' as const }
-            : row.text,
-        ] as const)
-        .filter(([key]) => typeof key === 'string' && key.length > 0),
-    );
-  }
-}