Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

95.2 KB
Raw Blame
// Every piece of user-visible copy is drawn through a `t('…')` literal, and a key
// that never reached the bundles renders as the raw key: removing a provider
// showed `settings.models.sourceDetail.gone` where a sentence belonged.
//
// So the guard states the property — every key the app can be known to ask for
// has copy in BOTH locales — and EXTRACTS the key list from the components
// themselves. A key, or a whole new surface added later, is covered without
// editing this file, which a hand-written list could never promise.
//
// The root is `src/`, so the property belongs to the app rather than to one
// directory. It was scoped to the Model Hub for exactly as long as it had to be:
// eight keys on three other surfaces had copy in neither locale, four of them
// rendering raw keys, and the root widened in the change that wrote them.
//
// Resolution runs through a real i18next instance instead of walking the JSON,
// because the bundles use two shapes a plain path walk reports as missing and
// the app depends on: plural families (`usageSummary_one` with no plain key)
// and flat dotted keys (`"vendor.hint"` sitting inside `field`, found by
// `ignoreJSONStructure`). The audit that opened this lane walked paths, and
// called 12 keys missing that the runtime resolves.
//
// A key alone does not say which copy it needs, though, which is why the sweep
// reads the syntax tree rather than the bytes: `count` is what selects a plural
// family, and each plural CATEGORY of the locale is a separate string. So a call
// site's arguments are part of what is collected, and every piece of copy the
// call can reach has to be present — never merely one of them. Requiring only
// one let a half-translated family pass: a locale that keeps `_one` and loses
// `_other` renders the raw key the moment a real call passes 2, and a call
// passing no count renders the raw key against a family that has no plain key.
//
// `count` is one of the options the call site hands over, and the same reading
// answers the other one that changes what "has copy" means. A caller that uses
// `returnObjects` to consume a LIST needs an array rather than an object or a
// plain string, even if the latter looks renderable. Both are read off the call
// rather than listed as keys here, so a list consumer is covered when added.
//
// That axis is closed by a MODEL rather than by a list of options, which is what
// it finally became: one question — how much copy does this call DEMAND — with
// three answers. `exact`, the options were a readable object literal, so `count`
// and `returnObjects` say precisely which shape the call consumes. `any`, the
// options arrived as an identifier, a conditional, or a spread (6 sites), so
// nothing can be claimed about the shape and the honest demand is that the name
// resolve at all. `none`, the call carries its own `defaultValue`, so it renders
// that when the bundles have nothing and can never show a raw key.
//
// An earlier round called `defaultValue` disjoint from literal keys "by
// construction": all 42 sites named a dynamic key, so none could hide a literal.
// Expanding templates (below) broke that — 18 of those sites now name a key this
// file knows, 7 distinct — and the disjointness was never the point. A demand of
// `none` narrows what EXISTENCE asks and narrows nothing else: the name still
// enters the candidate pool, so copy kept in one locale and dropped from the
// other is still a PARITY gap, still one locale rendering an English fallback
// beside a translated surface. There is no `context` anywhere in `src/`. A
// fourth option would arrive with its own meaning of "has copy" and belongs in
// this question the same way these three do.
//
// Reading the tree is also what lets the sweep follow the app's second way of
// naming a key: an `i18nKey`, which `<Trans>` takes as a prop when the copy wraps
// a link, and which a component's own table carries to hand to `t()` later.
//
// Neither site reliably hands over a bare literal, though, so what is taken from
// one is the SET of values it can be statically KNOWN to name: both branches of a
// ternary, either side of a `??` fallback, through any number of wrappers that
// preserve the value, and — because the sweep runs against a TYPED program — the
// product of a template whose substitutions each have a finite string-literal
// type. A leaf the compiler cannot narrow that far stays invisible. Recognising
// shapes one at a time instead is what left `remoteAccess.flowStep1` and the 94
// keys named through a conditional or a fallback deletable while this guard was
// green.
//
// That template case is the round a reviewer proved with a deletion: `App.tsx`
// writes t(`remoteAuthorization.${state}.title`), and `state` is a four-member
// union, so four real keys were nameable only there and deletable in silence.
// Reading the parts cannot answer it — TypeScript types the whole expression as
// plain `string` — so the sweep asks the CHECKER what each substitution can be
// and expands only when every member of that type is a string literal. 113 of
// the app's 164 template sites answer; 51 stay genuinely dynamic. The cost is a
// `ts.Program` over `src/`: 513 root files, ~1.5s, pinned here so a later
// blow-up to ten seconds is noticed rather than absorbed.
//
// A union is an UPPER BOUND on what reaches a call site, though, never the exact
// set. Two spans of one template can be correlated by dataflow that expanding
// each span independently cannot see, and a runtime guard can narrow a value in
// ways the compiler does not track. So expansion also names a few combinations
// the app can never ask for — six today — and those are classified in the
// residue pin below, exactly like a Monaco token or a storage key. That is what
// an upper bound costs, and it fails in the safe direction: a name too many gets
// classified by hand, a name too few goes unnoticed forever.
//
// All of that is the EXPRESSION axis, and it is only half of what this file
// needs, because it says nothing about the POSITIONS a key is written in.
// Calling the class closed on the expression axis alone is what let an earlier
// round land: `steps/TelegramConfig.tsx` hands `shared/ProxyUrlField` a literal
// `labelKey`, `lib/agentGraph.ts` keeps a whole table of them, and 75 keys reach
// `t()` only that way, through eighteen differently-named props. Adding those
// names here would be the same enumeration a fourth time.
//
// So this file states THREE properties, and only the first needs positions.
//
//   EXISTENCE — every key a `t()` or an `i18nKey` position can be KNOWN to name,
//   written as a literal or assembled by a template the checker can expand, has
//   the copy that call demands in both locales. Position-bound of necessity: to
//   demand that a key exist, something has to know it is a key. It asks nothing
//   of a name NO locale resolves, because nothing at a call site can tell a key
//   deleted from both bundles apart from a name that was never a key — that is
//   RESIDUE's question, so the two partition rather than overlap, and such a
//   name still fails one property over, as an unclassified newcomer in the pin.
//
//   PARITY — every name the app can ask for — every dotted string literal
//   anywhere in `src/`, plus every key expanded out of a template — that
//   resolves in EITHER locale resolves in BOTH. No positions, no prop names, no
//   dataflow beyond that expansion: a name becomes a candidate because of how it
//   READS or how it was assembled, and the bundles decide
//   whether it is a key. `labelKey="telegramConfig.proxyUrl"` is covered not
//   because this file learned the name `labelKey` but because that string is in
//   the bundles — so a prop, a data table, or a carrier nobody has invented yet
//   is covered without editing this file. "Resolves" means the locale RENDERS
//   copy for it, bare or against any plural category the locale selects, so a
//   family kept in one locale and dropped from the other is a gap here rather
//   than a stem that quietly falls out.
//
// What PARITY cannot do is find a key missing from BOTH locales: a name absent
// from both is indistinguishable from a Monaco theme token, an event-channel
// name, or a storage key, and 67 of those sit in `src/` today. EXISTENCE cannot
// cover that case either, for the same reason and by the same deliberate
// deferral — delete `telegramConfig.proxyUrl` from both bundles and neither
// property notices, while `ProxyUrlField` renders the raw key.
//
//   RESIDUE — the names that resolve in NEITHER locale are pinned, by exact set
//   equality, to the classified list below. Not a count: a count lets one name
//   leave as another enters. A key deleted from both bundles joins that set, the
//   set stops matching, and the suite fails. This is the only property that can
//   catch that, which is why the other two hand it the case rather than each
//   guessing at it.
//
// The pin is an enumeration, which is what the three rounds above kept getting
// wrong — but it enumerates the RESIDUE, not the positions, and that inverts the
// failure direction. A position this file has not heard of silently falls out of
// coverage; a literal this list has not heard of fails loudly and has to be
// classified. Same shape as `scripts/lint-baseline.mjs`, which pins this repo's
// known lint violations for the same reason.
//
// So the cost of the pin is a line whenever a genuinely new non-key dotted
// literal appears, and what it buys is exactly this, no more: no LITERAL-NAMED
// key, and no key assembled by a template whose substitutions are a finite
// string-literal union, can leave the bundles unnoticed — whatever position it
// was written in.
//
// Not more than that, and the residual is worth stating precisely rather than
// rounding away. 51 template sites stay genuinely dynamic, so the keys only they
// name remain invisible here. And 852 of the bundles' 4264 leaves are reached by
// no name in `src/` at all: pinning THOSE would be a maintenance contract over
// copy that churns with every feature, not over 67 stable non-keys, so it is a
// separate decision rather than something this change makes on the way past —
// tracked in #1968.
//
// All three ask about COPY rather than about a key existing, and that is the last
// thing worth saying here. Asking whether a key EXISTS is a weaker question that
// looks identical until a value goes empty, and it cost two rounds of one root
// cause: a `returnObjects` array emptied in one locale passed, then a key blanked
// to `''` in BOTH locales passed as well, resolving everywhere and so never
// reaching RESIDUE while the surface rendered a blank label.
//
// Copy is a LEAF — `rendersAsCopy`, one definition, one site: a nonblank string
// that is not the key echoed back. Whitespace-only counts as blank, because a
// value that renders as nothing is empty of copy whichever character made it so.
// Nothing else is copy; nobody renders a subtree.
//
// What differs is the CONTAINER it has to arrive in, and that is a property of
// the NAME — not of the property doing the asking, which is the reading that had
// to be corrected and is what #1969 was opened for. There are three:
//
//   COPY, the DEFAULT. Something renders this name's value directly: a plain
//   `t()`, a `labelKey` a component hands to `t()` later, an `i18nKey` on a
//   `<Trans>`. An object passes none of them — i18next hands a plain call its
//   diagnostic instead of a string — and neither does a list.
//
//   LIST, where a call site reads `returnObjects` and maps what comes back.
//   A nonempty list of copy, because a locale that keeps the array and
//   empties an entry renders a blank row rather than a raw key.
//
//   SUBTREE, where the name is not a key at all but a PREFIX its component
//   completes at runtime: `HarnessPage` writes `harness.runStatus` and asks for
//   `harness.runStatus.queued`. Nobody renders the node itself, so the question
//   is whether copy lives UNDER it — and dropping that whole subtree from one
//   locale is a real gap, so the name is still watched rather than excused.
//
// The first two are READ off the app: `returnObjects` at a call site says LIST,
// and every other way a name is written says COPY. The third cannot be read,
// because a prefix is precisely a name no call site names — that is why it reads
// like a leaf — so it is ENUMERATED in `KEY_PREFIXES` below, inverted exactly
// like the residue pin: two names today, measured on this head rather than
// carried over as a count, and a third has to be classified before it passes.
//
// Leaf BY DEFAULT is the whole of the correction. Asking the subtree question by
// default is what let two escapes through a green suite: a name whose only call
// carries a `defaultValue` (`harness.createDialog.kindTask`) and a name no call
// site names at all (`telegramConfig.proxyUrl` via `labelKey`) both fell back to
// it, so turning either into an object in BOTH locales passed while the surface
// rendered i18next's diagnostic. A name with copy UNDER it is not thereby a name
// that IS copy; the two escapes were that one sentence read backwards.
//
// So the subtree reading is the exception and owns exactly the enumerated names.
// A `defaultValue` still narrows what EXISTENCE asks — that call cannot show a
// raw key — and it narrows nothing about the value that IS there: absence and a
// broken present value are different facts, and conflating them was the first
// escape. The permission runs one way for the same reason: a pinned prefix
// cannot excuse a copy-demanding call on that same name, because EXISTENCE
// reads the call and never consults the pin.
//
// That whole claim is about copy being THERE. Whether the copy is RIGHT —
// accurate, idiomatic, actually translated rather than English pasted into
// `zh.json` — no scanner decides, and this one does not pretend to. Nor does it
// read further than the call: the guard reads the call site's OPTIONS, it does
// not guess the consumer's TypeScript assertion. `as string[]` on a `t()` result
// is a claim the compiler accepts and nobody checks; that is a product-code
// question, tracked in #1967, not something this file can see.
import { readdirSync, readFileSync } from 'node:fs';
import { dirname, join, relative, resolve, sep } from 'node:path';
import { fileURLToPath } from 'node:url';

import { createInstance, type i18n as I18n } from 'i18next';
import * as ts from 'typescript';
import { describe, expect, it } from 'vitest';

import en from './en.json';
import zh from './zh.json';

const APP_SOURCE = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const MODEL_HUB = join('components', 'settings', 'models');

/**
 * A call site: the key it names, and how much copy the call demands of it.
 *
 * `demand` is the options axis asked as ONE question rather than as a list of
 * options, so it stays total over that axis:
 *
 *   exact — the options were readable, so the shape the call consumes is known
 *   exactly, and `counted` and `listed` say what it is.
 *   any — the options could not be read: an identifier, a conditional, or an
 *   object hiding a spread. Weaker than `counted` and `listed` both being
 *   false, which is a claim about what the call passes.
 *   none — the call carries its own `defaultValue`, so it renders that when the
 *   bundles have nothing and can never show a raw key.
 *
 * A name still has to agree across locales under every demand, including
 * `none`: copy kept in one locale and dropped from the other leaves the other
 * rendering an English fallback. So `demand` narrows what EXISTENCE asks, never
 * whether PARITY and RESIDUE see the name.
 */
type Demand = 'exact' | 'any' | 'none';
type Reference = { key: string; counted: boolean; listed: boolean; demand: Demand };

/** How a reference reads in a failure report: the key, and how it was called. */
const label = (reference: Reference): string => {
  if (reference.demand === 'any') return `${reference.key} (opaque options)`;
  const called = [reference.counted ? 'count' : '', reference.listed ? 'returnObjects' : ''].filter(Boolean);
  return called.length > 0 ? `${reference.key} (${called.join(', ')})` : reference.key;
};

/**
 * What makes two references the SAME reference — and it is not how one reads.
 *
 * `label` is free to leave a field out, because a report annotated with every
 * `defaultValue` call would only ever be noise. Deduplicating by it therefore
 * merged what it chose not to distinguish: `t('x')` and
 * `t('x', { defaultValue })` were one entry, the later file won, and the exact
 * call's demand for copy vanished into a call that demands none. So identity is
 * read off the reference itself rather than written out — a field added to
 * `Reference` is part of it the moment it exists, which is the only version of
 * this that cannot drift again.
 */
const identity = (reference: Reference): string =>
  JSON.stringify(Object.entries(reference).sort(([left], [right]) => left.localeCompare(right)));

/** The written name of an object-literal property or a JSX attribute. */
const nameOf = (node: ts.Node | undefined): string | undefined =>
  (node !== undefined && (ts.isIdentifier(node) || ts.isStringLiteralLike(node)) ? node.text : undefined);

const passesOption = (options: ts.Expression | undefined, name: string): boolean =>
  options !== undefined
  && ts.isObjectLiteralExpression(options)
  && options.properties.some((property) => nameOf(property.name) === name);

/**
 * How much copy the call DEMANDS of its key — the options axis as one question.
 *
 * A spread or a computed name inside the object is as unreadable as an
 * identifier standing where the object should be: `{ ...options }` may carry
 * `count`, so claiming the call passes none of it would demand a bare key of a
 * plural family. `defaultValue` is decided first because seeing it is enough —
 * whatever else the object hides, that call renders its own fallback.
 */
const demandOf = (options: ts.Expression | undefined): Demand => {
  if (options === undefined) return 'exact';
  if (!ts.isObjectLiteralExpression(options)) return 'any';
  if (passesOption(options, 'defaultValue')) return 'none';
  return options.properties.every((property) => nameOf(property.name) !== undefined) ? 'exact' : 'any';
};

/** The operators that pick one of their operands, so both can name a key. */
const CHOICE_OPERATORS = new Set<ts.SyntaxKind>([
  ts.SyntaxKind.AmpersandAmpersandToken,
  ts.SyntaxKind.BarBarToken,
  ts.SyntaxKind.QuestionQuestionToken,
]);

/**
 * The strings a TYPE can be known to be — finite, or nothing at all.
 *
 * A union answers only if every member is a string literal: one `string` member
 * makes the whole set open, and an open set is not something this file may
 * expand. `undefined` therefore means "unknowable", never "empty".
 */
const literalTypes = (type: ts.Type): string[] | undefined => {
  const parts = type.isUnion() ? type.types : [type];
  const strings: string[] = [];
  for (const part of parts) {
    if (!part.isStringLiteral()) return undefined;
    strings.push(part.value);
  }
  return strings.length > 0 ? strings : undefined;
};

/**
 * Every key an expression can be statically KNOWN to name — the one thing this
 * file asks of a key expression, and the whole of its boundary.
 *
 * A key argument is often not a bare literal. It is a ternary picking a title
 * (`t(adding ? '…addTitle' : '…editTitle')`), a `??` naming the fallback
 * (`t(item?.labelKey ?? 'nav.settings')`), a template assembling a family
 * member (`` t(`remoteAuthorization.${state}.title`) ``), or any of those
 * wrapped in something that does not change the value. So an expression yields
 * a SET: a choice contributes every branch, a wrapper is transparent, a
 * template contributes every string its substitutions can produce, and a
 * literal is itself.
 *
 * A substitution is read from the TYPE when a checker is available, which is
 * the only thing here that needs one. `state: 'revoked' | 'unavailable'` is a
 * finite set of strings, so the template names a finite set of keys, and
 * knowing that costs a `ts.Program`. Nothing else in this file does — the
 * syntax tree answers every other shape, and a template of literals
 * (`` `${adding ? 'add' : 'edit'}.title` ``) expands with no checker at all.
 *
 * Every remaining leaf yields nothing and stays invisible by design — a
 * variable, property, or call result whose type is `string`, and an index into
 * a lookup table. Those are the app's genuinely dynamic keys, which is also
 * where its `defaultValue` fallbacks live; this guard cannot know what they
 * resolve to and does not guess. A choice or a template with one unknowable
 * part still protects the parts it can read, rather than giving up on the whole
 * call.
 *
 * Being total over the knowable forms rather than a list of recognised ones is
 * the point: a shape nobody enumerated was a key this guard silently stopped
 * protecting, and shapes were exactly what kept getting missed.
 */
const staticKeys = (node: ts.Expression | undefined, checker?: ts.TypeChecker): string[] => {
  if (node === undefined) return [];
  if (ts.isStringLiteralLike(node)) return [node.text];
  // Wrappers that preserve the value: `('k')`, `'k' as const`, `'k' satisfies T`,
  // `<T>'k'`, `k!`.
  if (
    ts.isParenthesizedExpression(node)
    || ts.isAsExpression(node)
    || ts.isSatisfiesExpression(node)
    || ts.isTypeAssertionExpression(node)
    || ts.isNonNullExpression(node)
  ) {
    return staticKeys(node.expression, checker);
  }
  if (ts.isConditionalExpression(node)) {
    return [...staticKeys(node.whenTrue, checker), ...staticKeys(node.whenFalse, checker)];
  }
  if (ts.isBinaryExpression(node) && CHOICE_OPERATORS.has(node.operatorToken.kind)) {
    return [...staticKeys(node.left, checker), ...staticKeys(node.right, checker)];
  }
  if (ts.isTemplateExpression(node)) {
    // The product of the parts, in order. TypeScript itself types this
    // expression as plain `string` outside a const context, so the spans are
    // expanded here rather than asked of the whole template.
    let assembled = [node.head.text];
    for (const span of node.templateSpans) {
      const parts = staticKeys(span.expression, checker);
      if (parts.length === 0) return [];
      assembled = assembled.flatMap((prefix) => parts.map((part) => `${prefix}${part}${span.literal.text}`));
    }
    return assembled;
  }
  if (checker !== undefined) {
    const known = literalTypes(checker.getTypeAtLocation(node));
    if (known !== undefined) return known;
  }
  return [];
};

/**
 * `t(…)`, whose options say what copy the call needs.
 *
 * The options argument is READABLE when it is an object literal whose every
 * property NAMES itself: then every option the call passes is written there, so
 * the demand is exact. `count` selects a
 * plural family, `returnObjects` says the caller maps a list, and
 * `defaultValue` says the call renders its own fallback, which demands no copy
 * at all. That is the whole options axis the app uses; there is no `context`
 * in `src/`.
 *
 * Anything else — an identifier, a conditional, an object hiding a spread —
 * demands `any`: not "no options", which is what this file used to read it as,
 * but "unknown options". Those are different claims, and conflating them made
 * `` t(`settings.models.shell.${key}`, allDirect ? { count } : undefined) ``
 * look like an uncounted call against a plural-only family.
 */
const translationCall = (node: ts.Node, checker?: ts.TypeChecker): Reference[] => {
  if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression) || node.expression.text !== 't') {
    return [];
  }
  const [key, options] = node.arguments;
  const demand = demandOf(options);
  const counted = passesOption(options, 'count');
  const listed = passesOption(options, 'returnObjects');
  return staticKeys(key, checker).map((found) => ({ key: found, counted, listed, demand }));
};

/**
 * An `i18nKey` naming a key, in either place the app writes one: the prop
 * `<Trans>` takes, and a property in a component's own table of keys.
 *
 * `<Trans count={…}>` selects a plural exactly as `t()` does, so a sibling
 * `count` attribute counts. A table property has no call of its own to read —
 * the `t(row.i18nKey)` that consumes it is a dynamic key — so it is probed
 * uncounted, which against a plural-only family fails rather than passes.
 *
 * A `PropertySignature` in a type (`i18nKey: string`) declares no value at all
 * and so is not one of these; a value that is there but dynamic yields nothing,
 * exactly as it does at a `t()` call.
 */
const i18nKeyReference = (node: ts.Node, checker?: ts.TypeChecker): Reference[] => {
  if (ts.isJsxAttribute(node) && nameOf(node.name) === 'i18nKey') {
    const value = node.initializer;
    const counted = ts.isJsxAttributes(node.parent)
      && node.parent.properties.some((property) => ts.isJsxAttribute(property) && nameOf(property.name) === 'count');
    const keys = value !== undefined && ts.isJsxExpression(value)
      ? staticKeys(value.expression, checker)
      : staticKeys(value, checker);
    return keys.map((found) => ({ key: found, counted, listed: false, demand: 'exact' }));
  }
  if (ts.isPropertyAssignment(node) && nameOf(node.name) === 'i18nKey') {
    return staticKeys(node.initializer, checker).map((found) => ({ key: found, counted: false, listed: false, demand: 'exact' }));
  }
  return [];
};

/**
 * Every key a source file can be statically known to name — at a `t()` call or
 * an `i18nKey` — with the argument shape that decides which copy that key needs.
 *
 * Read from the syntax tree, so the callee itself is the whole test of what a
 * translation call is: a page's own `jsonInit('POST')` and a `request.t(…)`
 * member call are not one. What each site's key expression yields is
 * `staticKeys`, and nothing here widens or narrows that. The keys a frozen
 * contract declares are covered by the models page's own
 * `contractLocaleKeys.test.ts`.
 *
 * `counted` and `listed` are what the call can be SEEN to pass, and they mean
 * something only under a demand of `exact`; anything unreadable answers `any`
 * instead of claiming the call passes nothing. What stays a residual is a bare
 * `t(…)` that is not i18next at all: it would be asked for copy it does not
 * need, and that is a loud failure someone looks at, never a raw key shipped
 * past a green CI.
 *
 * A key's namespace is not part of this: every `useTranslation()` in the app
 * takes the default one, so a key resolves against `translation` exactly as the
 * probes below resolve it.
 *
 * The checker is optional because only one shape needs it — a template whose
 * substitution is a typed variable. Without one the sweep is narrower, never
 * wrong.
 */
const referencesIn = (file: ts.SourceFile, checker?: ts.TypeChecker): Reference[] => {
  const found = new Map<string, Reference>();
  const visit = (node: ts.Node) => {
    // Keyed by the whole shape, because one key named by a counted and by an
    // uncounted call site needs both kinds of copy to be there — and one named
    // by an exact call and by a call carrying its own fallback still has to
    // answer the exact one.
    for (const reference of [...translationCall(node, checker), ...i18nKeyReference(node, checker)]) {
      found.set(identity(reference), reference);
    }
    ts.forEachChild(node, visit);
  };
  visit(file);
  return [...found.values()].sort((a, b) => label(a).localeCompare(label(b)));
};

export const collectReferences = (source: string, fileName = 'fixture.tsx'): Reference[] =>
  referencesIn(
    ts.createSourceFile(
      fileName,
      source,
      ts.ScriptTarget.Latest,
      true,
      fileName.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
    ),
  );

/** A string that READS like a key: dotted segments, nothing else assumed. */
const DOTTED = /^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z0-9_]+)+$/;

/**
 * Every dotted string literal a source file writes, wherever it sits — the
 * PARITY property's whole input, and the reason that property needs no positions.
 *
 * This asks nothing about how the literal is used. It is not an argument to
 * anything, not an attribute of anything; it is a string in the file that reads
 * like a key. So a literal handed over as `labelKey`, parked in a lookup table,
 * held in a `const`, or written into a carrier that does not exist yet is picked
 * up identically, and no name has to be enumerated for any of them.
 *
 * A literal that is not a key comes along too — a Monaco theme token, an
 * event-channel name, a storage key. That is deliberate: the bundles decide.
 * Absent from both locales, it is not a key and PARITY has nothing to say about
 * it; present in one, it is a key one locale lost.
 *
 * Read from the syntax tree rather than the bytes, so a dotted string inside a
 * comment or a longer sentence is not mistaken for a literal the app writes.
 */
export const collectDottedLiterals = (source: string, fileName = 'fixture.tsx'): string[] => {
  const file = ts.createSourceFile(
    fileName,
    source,
    ts.ScriptTarget.Latest,
    true,
    fileName.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
  );
  const found = new Set<string>();
  const visit = (node: ts.Node) => {
    if (ts.isTypeNode(node)) return;
    if (ts.isStringLiteralLike(node) && DOTTED.test(node.text)) found.add(node.text);
    ts.forEachChild(node, visit);
  };
  visit(file);
  return [...found].sort((a, b) => a.localeCompare(b));
};

const sourceFiles = (dir: string): string[] =>
  readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
    const path = join(dir, entry.name);
    if (entry.isDirectory()) return sourceFiles(path);
    if (!/\.tsx?$/.test(entry.name) || /\.test\.tsx?$/.test(entry.name)) return [];
    return [path];
  });

/**
 * The whole app as one typed program, which is what makes a template key
 * knowable.
 *
 * Built from an explicit walk of `src/` rather than from a tsconfig, because
 * `tsconfig.app.json` does not include `App.tsx` — and `App.tsx` is where
 * `` t(`remoteAuthorization.${state}.title`) `` is written. A program that
 * silently omitted it would expand nothing there and stay green, which is the
 * failure this whole file exists to refuse.
 *
 * The options are the app's, inline: a tsconfig that stops covering a file is
 * exactly the input this must not depend on. `paths` matters because a source
 * file imports `@/…`, and an unresolved import types its values as `any`, which
 * is not a finite union and so expands to nothing.
 *
 * Cost, measured: ~2s over 513 files, once for the suite. That is the price of
 * the type checker and it is pinned here so a later blow-up — a 10s program —
 * is noticed as a regression rather than absorbed.
 */
const typedApp = (files: string[]): ts.Program =>
  ts.createProgram(files, {
    target: ts.ScriptTarget.ES2022,
    module: ts.ModuleKind.ESNext,
    moduleResolution: ts.ModuleResolutionKind.Bundler,
    jsx: ts.JsxEmit.ReactJSX,
    strict: true,
    noEmit: true,
    skipLibCheck: true,
    esModuleInterop: true,
    resolveJsonModule: true,
    baseUrl: resolve(APP_SOURCE, '..'),
    paths: { '@/*': ['src/*'] },
  });

const referencedCallSites = (): Reference[] => {
  const files = sourceFiles(APP_SOURCE);
  const program = typedApp(files);
  const checker = program.getTypeChecker();
  const found = new Map<string, Reference>();
  for (const file of files) {
    const source = program.getSourceFile(file);
    // A file the program could not load would silently contribute no keys.
    expect(source, `${relative(APP_SOURCE, file)} is missing from the program`).toBeDefined();
    for (const reference of referencesIn(source as ts.SourceFile, checker)) {
      found.set(identity(reference), reference);
    }
  }
  return [...found.values()].sort((a, b) => label(a).localeCompare(label(b)));
};

/** The app's locales, and the bundle each one resolves against. */
const BUNDLES: { lng: string; bundle: unknown }[] = [
  { lng: 'en', bundle: en },
  { lng: 'zh', bundle: zh },
];

/** One locale, resolved with no fallback: a zh gap must not be filled by en. */
const localeInstance = (lng: string, bundle: unknown): I18n => {
  const instance = createInstance();
  void instance.init({
    lng,
    fallbackLng: false,
    resources: { [lng]: { translation: bundle as Record<string, unknown> } },
  });
  return instance;
};

/**
 * One count per plural category the locale can select, taken from
 * `Intl.PluralRules` — the same source i18next resolves its `_one` / `_other`
 * suffixes from. So en asks for both halves of a family, and zh, which selects
 * only `other`, asks for the half it can actually reach; a locale added later
 * brings its own categories instead of a number this file guessed. A category
 * no count in range selects would drop out of the requirement silently, so it
 * throws instead.
 */
const countsByLocale = new Map<string, number[]>();
const representativeCounts = (lng: string): number[] => {
  const memoised = countsByLocale.get(lng);
  if (memoised !== undefined) return memoised;
  const computed = computeRepresentativeCounts(lng);
  countsByLocale.set(lng, computed);
  return computed;
};

const computeRepresentativeCounts = (lng: string): number[] => {
  const rules = new Intl.PluralRules(lng);
  const categories = rules.resolvedOptions().pluralCategories;
  const reached = new Map<string, number>();
  for (let count = 0; count <= 200 && reached.size < categories.length; count += 1) {
    const category = rules.select(count);
    if (!reached.has(category)) reached.set(category, count);
  }
  const unreached = categories.filter((category) => !reached.has(category));
  if (unreached.length > 0) throw new Error(`no probe count selects ${lng} plural ${unreached.join(', ')}`);
  return [...reached.values()];
};

/** Every options object a readable call site can reach, and so must have copy for. */
const probes = (lng: string, reference: Reference): Record<string, unknown>[] =>
  (reference.counted ? representativeCounts(lng).map((count) => ({ count })) : [{}]);

/**
 * Whether a bundle VALUE carries something to render. This is the file's only
 * notion of a key being there, and every property below is stated through it.
 *
 * Asking the value rather than a `t()` projection is what makes it position-free
 * and option-free. The projection needed the call's position to find the key AND
 * the call's options to see the value: a list consumer using `returnObjects`
 * would map the result as an array, while a probe without that option gets
 * i18next's "returned an object instead of string" diagnostic — a nonempty
 * string, which passes even though the consumer cannot render any rows.
 *
 * A collection has to be nonempty AND renderable in every slot, because a locale
 * that keeps the array and empties an entry renders a blank row rather than a raw
 * key, and a blank row is still missing copy.
 *
 * The boundary is exactly this and no wider: a value is renderable when it is a
 * nonblank string that is not the key itself, or a nonempty collection whose
 * every entry is renderable. Whitespace-only counts as blank, because a value
 * that renders as nothing is empty of copy whichever character made it so.
 * Whether the copy is CORRECT — right register, right meaning, right locale —
 * is not decidable here and stays human territory.
 */
const rendersAsCopy = (value: unknown, key: string): boolean =>
  typeof value === 'string' && value.trim() !== '' && value !== key;

/**
 * Whether copy lives UNDER a name — the SUBTREE question, and the only one that
 * says yes to a node nothing renders.
 *
 * This is what a key PREFIX needs and what nothing else may have. It was the
 * file's default reading once, and defaulting to it is the bug in #1969: it
 * answers "is there copy beneath this name", which is true of every prefix and
 * also true of a leaf someone replaced with an object, and the second case is a
 * surface rendering i18next's diagnostic. So it is reached only through the
 * `subtree` container below, which only an enumerated name is given.
 */
const hasCopyUnder = (value: unknown, key: string): boolean => {
  if (typeof value === 'string') return rendersAsCopy(value, key);
  if (Array.isArray(value)) return value.length > 0 && value.every((entry) => hasCopyUnder(entry, key));
  if (typeof value === 'object' && value !== null) {
    const entries = Object.values(value);
    return entries.length > 0 && entries.every((entry) => hasCopyUnder(entry, key));
  }
  return false;
};

/**
 * The container a name's value has to arrive in, and the whole table of them.
 *
 * One table, so the three properties cannot disagree about what a shape means:
 * EXISTENCE asks it about the container a CALL consumes, PARITY and RESIDUE ask
 * it about the container a NAME is written for, and a shape closed in one is
 * closed in all three. That is the invariant the two escapes broke — they were
 * asked a weaker question than the call sites beside them.
 *
 * A LIST has to be nonempty and copy in every slot for the reason a `returnObjects`
 * consumer maps it: a blank row is missing copy, not a row that happens to be short.
 */
type Container = 'copy' | 'list' | 'subtree';

const ARRIVES: Record<Container, (value: unknown, key: string) => boolean> = {
  copy: rendersAsCopy,
  list: (value, key) =>
    Array.isArray(value) && value.length > 0 && value.every((entry) => rendersAsCopy(entry, key)),
  subtree: hasCopyUnder,
};

/** Whether a value arrives in ANY container the asker can render it out of. */
const arrivesIn = (value: unknown, key: string, containers: readonly Container[]): boolean =>
  containers.some((container) => ARRIVES[container](value, key));

/**
 * Whether a locale resolves a literal INTO a container the asker renders it out
 * of — meaning it renders copy for it, bare or against any plural category the
 * locale selects.
 *
 * The container is handed in rather than assumed, because "resolves" was the
 * word doing the conflating: it used to mean the subtree reading everywhere it
 * was called, which is the right question for a prefix and too weak for every
 * other name.
 *
 * Renders, not merely exists. `instance.exists()` was the earlier answer and it
 * is presence only, which cost two review rounds of the same root cause: an
 * emptied `returnObjects` array passed, and then a key blanked to `''` in BOTH
 * locales passed as well, resolving everywhere and so never reaching RESIDUE
 * while `ProxyUrlField` rendered a blank label. Both are the same mistake, asking
 * whether a key is there instead of whether copy is. So there is one predicate
 * and "resolves" means one thing file-wide: EXISTENCE, PARITY and RESIDUE all
 * inherit it, and no value-shaped hole can be open in one and closed in another.
 *
 * What that ruling settled is VALIDITY, and presence is a different fact that
 * still has to be asked somewhere — see `presentFor` below, the one place it is.
 *
 * The plural half matters: a family with no plain key (`usageSummary_one` and
 * `_other`, no `usageSummary`) renders nothing bare, so asking only that way
 * would drop every family out of PARITY and miss the locale that kept the family
 * while the other lost it.
 */
const resolvesIn = (
  instance: I18n,
  lng: string,
  key: string,
  containers: readonly Container[],
): boolean =>
  arrivesIn(instance.t(key, { returnObjects: true }), key, containers) ||
  representativeCounts(lng).some((count) =>
    arrivesIn(instance.t(key, { count, returnObjects: true }), key, containers),
  );

/**
 * Whether the bundle HAS an entry for this name under these options — presence,
 * which is the other fact, and the only question `exists()` is asked here.
 *
 * Presence and validity are not the same question and one predicate cannot be
 * both. `resolvesIn` above says whether copy comes back; this says whether
 * anything is there at all. Answering the second with the first is the #1969
 * conflation one level up, and it is what let two calls through: a name whose
 * value does not fit the container someone picked looked ABSENT, so every call
 * to it was excused as "the bundles never had this".
 *
 * So no approximation is invented for it. `value !== key` looks like presence
 * and is not: a bundle may store the key AS its value, and the real resolver
 * separates the two — `card.echo: 'card.echo'` is present (invalid copy someone
 * must fix), `card.absent` is absent (a fallback may legitimately cover it),
 * and both hand `t()` back the same string. Only `exists()` tells them apart.
 *
 * The options are handed in rather than dropped, because presence is per
 * SELECTED FORM: with only `card_one` present, `{ count: 1 }` exists and
 * `{ count: 2 }` does not. A defaulted call reaching the second renders its own
 * fallback and is owed nothing, which is legitimate and must not be failed
 * merely because a sibling category is there.
 */
const presentFor = (instance: I18n, key: string, options: Record<string, unknown>): boolean =>
  instance.exists(key, { ...options, returnObjects: true });

/**
 * The names that are key PREFIXES rather than keys, pinned by hand.
 *
 * A prefix is a name whose component completes it at runtime, so it resolves to
 * an object node and nothing renders it directly. That cannot be READ off the
 * app — the completion is `` t(`${prefix}.${status}`) ``, a template over a value
 * no type narrows — which is why this is a list and every other container is a
 * measurement.
 *
 * Inverted like the residue pin below, and for the identical reason: an
 * unclassified prefix must not sit here quietly. A name that turns into an
 * object without being classified resolves in no container, so it falls to
 * RESIDUE and the pin above fails; adding a line here is a deliberate claim that
 * the name is a namespace and not copy someone broke.
 *
 * The permission is one-way. It relaxes what PARITY and RESIDUE ask of a NAME;
 * it never reaches EXISTENCE, which reads the call site and asks the exact
 * container that call consumes. So pinning a name here cannot excuse a plain
 * `t()` on it — the test below states that, and no name in `src/` is both.
 *
 * Measured on this head: 3454 candidate names, 2 of them object nodes. The
 * earlier census counted three, and `workbench.modules.agents` is no longer one
 * — `CapabilityTabs` names `workbench.modules.agents.title`, a leaf, and the
 * bare prefix survives only in a doc comment, which the collector does not read.
 */
const KEY_PREFIXES = [
  // `HarnessPage` picks one of these into `statusLabelPrefix` and completes it
  // with a chip's option, which is typed `readonly string[]` — so the template
  // expands to nothing and only `${prefix}.${status}` is ever rendered.
  'harness.runStatus',
  'harness.statusFilter',
];

/**
 * Every dotted literal in `src/` that resolves in NEITHER locale, pinned exactly.
 *
 * These read like keys and are not keys. Each one is classified, because the
 * whole value of the pin is that an unclassified literal cannot sit here quietly:
 * adding a line is a deliberate claim that the string is not copy, and deleting
 * copy that something still references shows up as an unexplained new entry.
 *
 * There are no plural stems in this list. Families fold into PARITY through
 * `resolvesIn`, so a stem whose family exists resolves and never reaches here.
 */
const NON_KEY_LITERALS = [
  // Monaco theme tokens and editor actions. Read by the editor, never by i18next.
  'editor.action.selectAll',
  'editor.background',
  'editor.lineHighlightBackground',
  'editor.selectionBackground',
  'editorGutter.background',
  'editorIndentGuide.background1',
  'editorLineNumber.activeForeground',
  'editorLineNumber.foreground',
  'editorWidget.background',
  'minimap.background',

  // Event-channel names. `ApiContext.tsx` publishes and subscribes by these.
  'authorization.changed',
  'bots.changed',
  'definitions.updated',
  'inbox.session.updated',
  'inbox.unread.changed',
  'message.new',
  'message.updated',
  'notifications.preferences.updated',
  'projects.changed',
  'queue.updated',
  'remote.authorization',
  'remote_access.quality.changed',
  'runs.updated',
  'session.activity',
  'session.status',
  'turn.end',
  'turn.start',
  'vaults.updated',
  'workbench.events.bridge.status',
  // Event-channel names on the vault sandbox bridge and the permissions surface.
  'confirm.surface',
  'instance.permissions.mutate',
  'ui.hide',
  'ui.show',
  'vault.state',

  // Server error codes. `serverCopy.ts` renders these through a `defaultValue`,
  // so the server's own message shows when the client has no copy for the code.
  'modelHub.errors.backend_model_catalog_invalid',
  'modelHub.errors.backend_model_conflict',
  'modelHub.errors.backend_model_duplicate',
  'modelHub.errors.backend_model_id_invalid',
  'modelHub.errors.backend_model_in_route',
  'modelHub.errors.backend_model_locked',
  'modelHub.errors.backend_model_origin_immutable',
  'modelHub.errors.candidate_suppliers_changed',
  'modelHub.errors.engine_down',
  'modelHub.errors.models_dev_unavailable',
  'modelHub.errors.native_login_in_progress',
  'modelHub.errors.native_subscription_exists',
  'modelHub.errors.submission_rejected_other_attempt',

  // Storage keys. Namespaced on purpose, which is also why they read like keys.
  'avibe.agents.tab.v1',
  'avibe.editor.fontSize.v1',
  'avibe.editor.recents.v1',
  'avibe.pet.devBinding',
  'avibe.sidebar.sections.v1',
  'avibe.terminal.fontSize.v1',
  'avibe.terminal.sessionId',
  'avibe.vault.crypto',
  'avibe.workbench.windows.v1',
  'vibe.webPush.deviceId',
  'vibe.webPush.endpoints',

  // Config field paths, addressed against the V2 config rather than a bundle.
  'agents.opencode.active_turn_timeout_seconds',
  'agents.opencode.error_retry_limit',
  'platforms.enabled',

  // Not keys in any sense: a package name, a host, a filename, a sample domain.
  'Thumbs.db',
  'opencode.ai',
  'qrcode.react',
  'relay.example',

  // Dead literals, removal tracked. `CreateViaChatDialog.tsx` builds these and
  // feeds them through a `defaultValue` chain into `harness.createDialog.*`,
  // which does exist in both locales, so the rendered copy is correct. The
  // comment there claims they are kept for a translation linter, which is not
  // true of this guard. Deleting product code is out of scope for this PR.
  'workbench.createDialog.kindTask',
  'workbench.createDialog.kindWatch',
];

/** Every dotted literal the app carries, wherever it sits, sorted. */
const appDottedLiterals = (): string[] => {
  const literals = new Set<string>();
  for (const file of sourceFiles(APP_SOURCE)) {
    for (const found of collectDottedLiterals(readFileSync(file, 'utf8'), file)) literals.add(found);
  }
  return [...literals].sort((a, b) => a.localeCompare(b));
};

/**
 * Every name the app can ask a bundle for: the dotted literals it writes, plus
 * the keys its call sites are known to name.
 *
 * Those two nearly coincide, and the difference is the whole point — a key no
 * literal spells. `remoteAuthorization.revoked.title` is assembled from a
 * template, so it appears nowhere in `src/` as a string, and deleting it from
 * BOTH locales was invisible to every property in this file until the
 * expansion above put the assembled name into this pool.
 */
const appCandidateKeys = (referenced: Reference[]): string[] =>
  [...new Set([...appDottedLiterals(), ...referenced.map((reference) => reference.key)])]
    .sort((a, b) => a.localeCompare(b));

/**
 * The container a NAME has to arrive in — the contract PARITY and RESIDUE hold
 * it to, as opposed to the one EXISTENCE reads off a single call.
 *
 * Leaf by default, which is the correction. A name is copy unless the app can be
 * SEEN to consume it another way (`returnObjects` at some call site) or it is a
 * pinned prefix. So a key named only through a carrier prop, and a key named
 * only by a call carrying its own `defaultValue`, are both held to the shape
 * their consumer renders — which is what neither was before.
 *
 * `listed` is read off the same collector every other fact here comes from, so
 * this enumerates no positions and no prop names: a second `returnObjects`
 * consumer is covered the day it is written.
 *
 * One name, one answer — and that is sound only because this side is not the
 * only side. A name with both a `returnObjects` consumer and a plain one gets
 * `list` here, so the array it holds is a key the bundles have rather than a
 * gap; the plain call that cannot render that array is still failed, by
 * EXISTENCE, which reads each call rather than this table. Neither reading can
 * stand in for the other, and the permission runs one way only: PARITY and
 * RESIDUE consult this, EXISTENCE never does.
 */
export type Containers = (key: string) => readonly Container[];

const AS_COPY: Containers = () => ['copy'];

const containersFor = (referenced: Reference[]): Containers => {
  const listed = new Set(referenced.filter((reference) => reference.listed).map((reference) => reference.key));
  return (key) => (KEY_PREFIXES.includes(key) ? ['subtree'] : listed.has(key) ? ['list'] : ['copy']);
};

/** The literals no locale resolves, sorted for comparison against the pin. */
export const residueOf = (
  literals: string[],
  bundles: { lng: string; bundle: unknown }[],
  containers: Containers = AS_COPY,
): string[] => {
  const locales = bundles.map(({ lng, bundle }) => ({ lng, instance: localeInstance(lng, bundle) }));
  return literals
    .filter((key) => !locales.some(({ lng, instance }) => resolvesIn(instance, lng, key, containers(key))))
    .sort((a, b) => a.localeCompare(b));
};

/** A literal one locale resolves and another does not: a key someone lost. */
type ParityGap = { key: string; present: string[]; absent: string[] };

/**
 * PARITY over whatever literals it is handed, against whatever bundles it is
 * handed — so the fixture below can pin its boundaries on locales it controls.
 *
 * A literal no locale resolves is not a key and yields nothing. One every locale
 * resolves is fine. Anything in between is the gap this reports.
 */
export const parityGaps = (
  literals: string[],
  bundles: { lng: string; bundle: unknown }[],
  containers: Containers = AS_COPY,
): ParityGap[] => {
  const locales = bundles.map(({ lng, bundle }) => ({ lng, instance: localeInstance(lng, bundle) }));
  return literals.flatMap((key) => {
    const present = locales
      .filter(({ lng, instance }) => resolvesIn(instance, lng, key, containers(key)))
      .map(({ lng }) => lng);
    if (present.length === 0 || present.length === locales.length) return [];
    return [{ key, present, absent: locales.map(({ lng }) => lng).filter((lng) => !present.includes(lng)) }];
  });
};

/**
 * The symptom this guard exists for, stated exactly: nothing the call site can
 * render comes back.
 *
 * A call site names an exact shape, and only copy in THAT shape reaches a screen
 * through it. A plain call renders the value itself, so the value has to be a
 * string; turn it into an object and i18next hands back its diagnostic instead
 * of copy. A call reading `returnObjects` maps the value, so it has to be a list
 * of strings; turn it into an object, a plain string, or a list of objects and
 * a list consumer throws on `.map` or hands React an object child.
 *
 * That shape is read off the call, exactly as `count` is, so a second site
 * asking for a list is covered without naming its keys here.
 *
 * The subtree reading (`hasCopyUnder`) is deliberately NOT reachable here. It
 * answers a different question — does this NAME have copy under it — which is
 * the right question for a pinned prefix and the wrong one anywhere a value is
 * rendered, because no consumer renders a subtree.
 */
const consumable = (value: unknown, reference: Reference): boolean =>
  arrivesIn(value, reference.key, [reference.listed ? 'list' : 'copy']);

/**
 * What a locale owes a call site, which is exactly what the call demands.
 *
 * An `exact` call names its own shape, so every option set it can reach has to
 * come back consumable. An `any` call names none of it: the options could hide
 * a `count`, a `returnObjects`, or a `defaultValue`, and picking one shape would
 * be inventing a fact. So it is asked for EITHER container a call can consume —
 * the weakest honest demand, and still not the subtree one, because whichever
 * options that call passes, i18next hands it a string it renders or a list it
 * maps and never a node anything renders. Reading the subtree question here was
 * the same conflation #1969 names, one call shape over.
 *
 * A `none` call is asked the same question wherever its key is THERE. Carrying
 * a `defaultValue` buys exactly one thing — the key may be missing — and buys it
 * per selected form, since that is how i18next spends it. Where the form is
 * absent the fallback renders and nothing is owed; where it is present the
 * fallback is never reached, i18next hands back the stored value, and that value
 * faces the same container and the same plural probes as a call carrying none.
 * Excusing the whole call was the second escape of this round: a defaulted call
 * on a pinned prefix rendered a node's diagnostic while the guard stayed silent,
 * and the prefix pin could not catch it because a prefix pin is name-side.
 *
 * The residual is stated rather than hidden: an opaque options object that
 * hides a `defaultValue` would be asked for copy the call does not need. That
 * is a loud failure someone reads, never a raw key shipped past a green CI, and
 * of the 6 opaque sites in `src/` today none is one.
 */
const missingCopy = (instance: I18n, lng: string, reference: Reference): boolean =>
  (reference.demand === 'any'
    ? !resolvesIn(instance, lng, reference.key, ['copy', 'list'])
    : probes(lng, reference).some((options) =>
      (presentFor(instance, reference.key, options)
        ? !consumable(instance.t(reference.key, { ...options, returnObjects: true }), reference)
        : reference.demand !== 'none'),
    ));

describe('app i18n key coverage', () => {
  const referenced = referencedCallSites();
  const appContainers = containersFor(referenced);

  it('collects the literal keys and how they are called, and only those, from a source file', () => {
    // The forward guard on the collector itself: a coverage test whose collector
    // silently stops matching reports coverage it never had. So this pins the
    // whole boundary rather than a sample of it — every static form the collector
    // must see through, every dynamic leaf it must decline, the two places a key
    // is named, all three demands and one name carrying two of them, and
    // `count`, whose loss would quietly stop asking for plural copy. A form
    // added to `staticKeys` later, or an options shape read differently, fails
    // here until it is stated.
    const fixture = `
      const label = t('fixture.literal');
      const quoted = t("fixture.double");
      const wrapped = t(
        'fixture.wrapped',
        { count: 2 },
      );
      const shorthand = t('fixture.shorthand', { count });
      const alongside = t('fixture.alongside', { count: total, name: 'x' });
      const interpolated = t('fixture.interpolated', { name: 'x' });
      const nested = t('fixture.outer', { hint: t('fixture.inner', { count: 3 }) });

      // How much copy the call DEMANDS. Options nobody can read are unknown, not
      // absent — an object hiding a spread or a computed name included, since
      // either may be the \`count\` that picks a plural family. A call carrying its
      // own fallback demands nothing, and is still a name the bundles must agree
      // on, so it is collected rather than dropped.
      const spread = t('fixture.spread', { ...options });
      const computedOption = t('fixture.computed', { [dynamicOption]: 2 });
      const carriedOptions = t('fixture.carried', options);
      const chosenOptions = t('fixture.chosen', many ? { count } : undefined);
      const defaulted = t('fixture.defaulted', { defaultValue: 'Background work' });
      const defaultedHiding = t('fixture.defaultedSpread', { defaultValue: 'x', ...options });

      // One name, two demands. The call that carries a fallback cannot answer
      // for the one that does not, so neither absorbs the other.
      const both = t('fixture.both');
      const bothDefaulted = t('fixture.both', { defaultValue: 'x' });

      // A template is the product of its parts, and needs no checker when every
      // part is written out.
      const assembled = t(\`fixture.\${'left'}.\${'tail'}\`);
      const branched = t(\`fixture.\${adding ? 'on' : 'off'}.label\`, { count: total });

      // Choices: every branch can be the key that renders.
      const ternary = t(adding ? 'fixture.yes' : 'fixture.no');
      const chained = t(a ? 'fixture.a' : b ? 'fixture.b' : 'fixture.c');
      const fallback = t(item?.labelKey ?? 'fixture.fallback');
      const orElse = t(override || 'fixture.orElse');
      const andThen = t(ready && 'fixture.andThen');
      const eitherPlural = t(many ? 'fixture.oneWay' : 'fixture.otherWay', { count: total });

      // Wrappers that preserve the value.
      const parenthesised = t(('fixture.paren'));
      const asserted = t('fixture.asserted' as const);
      const insisted = t('fixture.bang'!);

      // A choice with one dynamic branch still protects the branch it can read.
      const partly = t(known ? 'fixture.knownBranch' : row.key);

      // Both places a key is named carry a choice too.
      const wrapping = <Trans i18nKey="fixture.trans" components={{ link: <a /> }} />;
      const braced = <Trans i18nKey={'fixture.braced'} />;
      const plural = <Trans i18nKey="fixture.transCount" count={total} />;
      const transChoice = <Trans i18nKey={outgoing ? 'fixture.transYes' : 'fixture.transNo'} />;
      const rows = [{ id: 'x', i18nKey: 'fixture.table' }];
      const tableChoice = [{ i18nKey: outgoing ? 'fixture.tableYes' : 'fixture.tableNo' }];

      // Dynamic leaves: nothing statically known, so nothing collected.
      type Row = { i18nKey: string };
      const computed = <Trans i18nKey={dynamic} />;
      const carried = { i18nKey: pickKey(row) };
      const looked = t(LABEL_KEY[kind]);
      const held = t(messageKey);
      const reached = t(def.titleKey);
      const eitherDynamic = t(row.key ?? LABEL_KEY[kind]);
      void jsonInit('POST');
      void request.t('fixture.member');
      void t(\`fixture.\${dynamic}\`);
    `;
    expect(collectReferences(fixture)).toEqual([
      { key: 'fixture.a', counted: false, listed: false, demand: 'exact' },
      { key: 'fixture.alongside', counted: true, listed: false, demand: 'exact' },
      { key: 'fixture.andThen', counted: false, listed: false, demand: 'exact' },
      { key: 'fixture.asserted', counted: false, listed: false, demand: 'exact' },
      { key: 'fixture.b', counted: false, listed: false, demand: 'exact' },
      { key: 'fixture.bang', counted: false, listed: false, demand: 'exact' },
      { key: 'fixture.both', counted: false, listed: false, demand: 'exact' },
      { key: 'fixture.both', counted: false, listed: false, demand: 'none' },
      { key: 'fixture.braced', counted: false, listed: false, demand: 'exact' },
      { key: 'fixture.c', counted: false, listed: false, demand: 'exact' },
      { key: 'fixture.carried', counted: false, listed: false, demand: 'any' },
      { key: 'fixture.chosen', counted: false, listed: false, demand: 'any' },
      { key: 'fixture.computed', counted: false, listed: false, demand: 'any' },
      { key: 'fixture.defaulted', counted: false, listed: false, demand: 'none' },
      { key: 'fixture.defaultedSpread', counted: false, listed: false, demand: 'none' },
      { key: 'fixture.double', counted: false, listed: false, demand: 'exact' },
      { key: 'fixture.fallback', counted: false, listed: false, demand: 'exact' },
      { key: 'fixture.inner', counted: true, listed: false, demand: 'exact' },
      { key: 'fixture.interpolated', counted: false, listed: false, demand: 'exact' },
      { key: 'fixture.knownBranch', counted: false, listed: false, demand: 'exact' },
      { key: 'fixture.left.tail', counted: false, listed: false, demand: 'exact' },
      { key: 'fixture.literal', counted: false, listed: false, demand: 'exact' },
      { key: 'fixture.no', counted: false, listed: false, demand: 'exact' },
      { key: 'fixture.off.label', counted: true, listed: false, demand: 'exact' },
      { key: 'fixture.on.label', counted: true, listed: false, demand: 'exact' },
      { key: 'fixture.oneWay', counted: true, listed: false, demand: 'exact' },
      { key: 'fixture.orElse', counted: false, listed: false, demand: 'exact' },
      { key: 'fixture.otherWay', counted: true, listed: false, demand: 'exact' },
      { key: 'fixture.outer', counted: false, listed: false, demand: 'exact' },
      { key: 'fixture.paren', counted: false, listed: false, demand: 'exact' },
      { key: 'fixture.shorthand', counted: true, listed: false, demand: 'exact' },
      { key: 'fixture.spread', counted: false, listed: false, demand: 'any' },
      { key: 'fixture.table', counted: false, listed: false, demand: 'exact' },
      { key: 'fixture.tableNo', counted: false, listed: false, demand: 'exact' },
      { key: 'fixture.tableYes', counted: false, listed: false, demand: 'exact' },
      { key: 'fixture.trans', counted: false, listed: false, demand: 'exact' },
      { key: 'fixture.transCount', counted: true, listed: false, demand: 'exact' },
      { key: 'fixture.transNo', counted: false, listed: false, demand: 'exact' },
      { key: 'fixture.transYes', counted: false, listed: false, demand: 'exact' },
      { key: 'fixture.wrapped', counted: true, listed: false, demand: 'exact' },
      { key: 'fixture.yes', counted: false, listed: false, demand: 'exact' },
    ]);
  });

  it('tells two references apart by every field one carries', () => {
    // Which is why the dedup key is read off the reference rather than written
    // out: a field added to `Reference` later belongs to its identity without
    // anyone remembering to say so. The length check is the same argument
    // applied to this test — the variants below are a list, and a list goes
    // stale exactly when the identity it stands for does.
    const base: Reference = { key: 'a.b', counted: false, listed: false, demand: 'exact' };
    expect(Object.keys(base)).toHaveLength(4);
    const variants: Reference[] = [
      { ...base, key: 'a.c' },
      { ...base, counted: true },
      { ...base, listed: true },
      { ...base, demand: 'any' },
      { ...base, demand: 'none' },
    ];
    expect(new Set([base, ...variants].map(identity)).size).toBe(variants.length + 1);
  });

  it('reads its key list out of the whole app, not one directory', () => {
    // Not a floor on the count, which would only say the scan found something.
    // The scan must have walked past the directory this guard started in — the
    // narrower root passed while eight keys on other surfaces had no copy — and
    // it must reach every way the app's own code names a key, each anchored on a
    // real site that was demonstrably escaping before it did.
    const files = sourceFiles(APP_SOURCE).map((file) => relative(APP_SOURCE, file));
    expect(files.some((file) => file.startsWith(`${MODEL_HUB}${sep}`))).toBe(true);
    expect(files.some((file) => !file.startsWith(`${MODEL_HUB}${sep}`))).toBe(true);
    // The raw key that opened the lane, on the source remove flow.
    expect(referenced).toContainEqual({ key: 'settings.models.sourceDetail.gone', counted: false, listed: false, demand: 'exact' });
    // The `<Trans>` prop carrying the Avibe Cloud link.
    expect(referenced).toContainEqual({ key: 'remoteAccess.flowStep1', counted: false, listed: false, demand: 'exact' });
    // Both branches of the permissions dialog title, and the inner branch of its
    // nested conflict ternary.
    expect(referenced).toContainEqual({ key: 'permissions.access.addTitle', counted: false, listed: false, demand: 'exact' });
    expect(referenced).toContainEqual({ key: 'permissions.access.editTitle', counted: false, listed: false, demand: 'exact' });
    expect(referenced).toContainEqual({ key: 'permissions.states.pairingChangedBody', counted: false, listed: false, demand: 'exact' });
    // The `??` fallbacks: the settings breadcrumb and the OAuth success toast.
    expect(referenced).toContainEqual({ key: 'nav.settings', counted: false, listed: false, demand: 'exact' });
    expect(referenced).toContainEqual({ key: 'settings.models.oauth.status.success', counted: false, listed: false, demand: 'exact' });
    // A counted site, which needs copy no bare probe asks for.
    expect(referenced.some((reference) => reference.counted)).toBe(true);
    // A key no literal in `src/` spells, assembled from a template whose
    // substitution the type checker pins to a finite set of strings. `App.tsx`
    // writes `` t(`remoteAuthorization.${state}.title`) `` and nothing else
    // names these; before the program above, deleting them was invisible here.
    expect(referenced.map((reference) => reference.key)).toEqual(
      expect.arrayContaining([
        'remoteAuthorization.revoked.title',
        'remoteAuthorization.revoked.body',
        'remoteAuthorization.unavailable.title',
        'remoteAuthorization.unavailable.body',
      ]),
    );
    // DirectHome is native-only. Widening its props to every backend made the
    // checker demand nonexistent Avibe Direct prose. Brand names themselves
    // now belong to catalog metadata; exact/defaulted dedup stays covered by
    // fixture.both in the collector test above.
    for (const backend of ['claude', 'codex', 'opencode']) {
      expect(referenced).toContainEqual({ key: `settings.models.direct.backend.${backend}.detail`, counted: false, listed: false, demand: 'exact' });
    }
    expect(referenced.some(({ key }) => key === 'settings.models.direct.backend.vibey.detail')).toBe(false);
  });

  // A name the bundles never had is not an existence gap: nothing here can tell
  // it apart from a key someone deleted, which is RESIDUE's question and where
  // it gets classified by hand. So the properties partition rather than overlap,
  // and a key deleted from BOTH locales still fails — as an unclassified
  // newcomer in the pin, naming itself just as loudly.
  //
  // The partition is on PRESENCE, which is the whole of this round's correction.
  // Asking `residueOf` instead asked "does the value fit the container I chose",
  // and every answer of no was read as "the bundles never had this": an array
  // key looked absent under `AS_COPY`, so a plain `t()` that renders `[object
  // Object]` on it was skipped here, and the name side let the array through.
  // That is a name-level classification cancelling a per-call demand — the exact
  // thing the one-way rule promises cannot happen. It cannot now: presence is
  // container-free, so `containersFor` is unreachable from this property, and a
  // key present in ANY form reaches the per-call check for EVERY call to it.
  const absentEverywhere = (() => {
    const probesByLocale = BUNDLES.map(({ lng, bundle }) => ({
      instance: localeInstance(lng, bundle),
      options: [{}, ...representativeCounts(lng).map((count) => ({ count }))],
    }));
    return new Set(
      referenced
        .map((reference) => reference.key)
        .filter((key) =>
          probesByLocale.every(({ instance, options }) =>
            options.every((probe) => !presentFor(instance, key, probe)),
          ),
        ),
    );
  })();

  it.each(BUNDLES)('translates every referenced call site in $lng', ({ lng, bundle }) => {
    const instance = localeInstance(lng, bundle);
    expect(
      referenced
        .filter((reference) => !absentEverywhere.has(reference.key))
        .filter((reference) => missingCopy(instance, lng, reference))
        .map(label),
    ).toEqual([]);
  });

  it('reports a NAME as having copy under it when any leaf under it renders', () => {
    // The subtree question, which now belongs to a PINNED PREFIX and to nothing
    // else. `harness.runStatus` is one: `HarnessPage` completes it at runtime, so
    // it resolves to an object node, and dropping that whole subtree from one
    // locale is a real gap — which is why the object branch is load-bearing here.
    // Defaulting to it is the #1969 escape, and the two tests after this one hold
    // the default and the call site to the container each actually renders.
    expect(hasCopyUnder('Disclosure', 'k')).toBe(true);
    expect(hasCopyUnder('', 'k')).toBe(false);
    expect(hasCopyUnder('   ', 'k')).toBe(false);
    expect(hasCopyUnder('k', 'k')).toBe(false); // i18next echoes the key when it has none
    expect(hasCopyUnder(['one', 'two'], 'k')).toBe(true);
    expect(hasCopyUnder([], 'k')).toBe(false); // the disclosure list, emptied
    expect(hasCopyUnder(['one', ''], 'k')).toBe(false); // a blank row is missing copy too
    expect(hasCopyUnder({ a: 'one' }, 'k')).toBe(true); // a prefix: copy lives under it
    expect(hasCopyUnder({}, 'k')).toBe(false);
    expect(hasCopyUnder(undefined, 'k')).toBe(false);
    expect(hasCopyUnder(42, 'k')).toBe(false);
  });

  it('decides a NAME by the container its consumers render, leaf unless told otherwise', () => {
    // The other half of the same table, asked of a NAME rather than of a call —
    // and the half #1969 was opened for. Stated as the total table again: every
    // shape i18next returns, judged in each container a name can be written for.
    //
    // The `copy` column is the default and the correction. An object under it is
    // the escape: both reported keys turned into one and the suite stayed green,
    // because the default used to be the `subtree` column instead.
    const table: Array<{ value: unknown; copy: boolean; list: boolean; subtree: boolean; why: string }> = [
      { value: 'Copy', copy: true, list: false, subtree: true, why: 'a leaf is copy and is copy under itself' },
      { value: '', copy: false, list: false, subtree: false, why: 'blank' },
      { value: '   ', copy: false, list: false, subtree: false, why: 'renders as nothing' },
      { value: 'k', copy: false, list: false, subtree: false, why: 'i18next echoing the key' },
      { value: ['one', 'two'], copy: false, list: true, subtree: true, why: 'a list is mapped, never rendered bare' },
      { value: [], copy: false, list: false, subtree: false, why: 'the disclosure list, emptied' },
      { value: ['one', ''], copy: false, list: false, subtree: false, why: 'a blank row is missing copy' },
      { value: [{ text: 'one' }], copy: false, list: false, subtree: true, why: 'rows of objects render nothing' },
      { value: { label: 'Copy' }, copy: false, list: false, subtree: true, why: 'a prefix, and NOT copy by default' },
      { value: {}, copy: false, list: false, subtree: false, why: 'empty' },
      { value: undefined, copy: false, list: false, subtree: false, why: 'no value at all' },
      { value: null, copy: false, list: false, subtree: false, why: 'no value at all' },
      { value: 42, copy: false, list: false, subtree: false, why: 'not copy' },
      { value: true, copy: false, list: false, subtree: false, why: 'not copy' },
    ];

    for (const row of table) {
      expect(arrivesIn(row.value, 'k', ['copy']), `copy: ${row.why}`).toBe(row.copy);
      expect(arrivesIn(row.value, 'k', ['list']), `list: ${row.why}`).toBe(row.list);
      expect(arrivesIn(row.value, 'k', ['subtree']), `subtree: ${row.why}`).toBe(row.subtree);
      // An opaque call site names one of the first two and cannot say which, so
      // it is asked for either — and never for the third.
      expect(arrivesIn(row.value, 'k', ['copy', 'list']), `either: ${row.why}`).toBe(row.copy || row.list);
    }
  });

  it('holds a defaulted-only key and a carrier-only key to the shape their consumer renders', () => {
    // #1969, both escapes, through the real properties rather than a helper: a
    // key named ONLY by a call carrying its own `defaultValue`, and a key named
    // by no call site at all, each turned into a nonempty object in BOTH locales.
    //
    // Neither reaches EXISTENCE — one demands no copy, the other has no call to
    // read — so the name-side contract is the only thing that can see them, and
    // under the old default it saw an object with copy under it and said yes.
    const defaulted = collectReferences(`
      const title = t('harness.createDialog.kindTask', { defaultValue: 'Background work' });
    `);
    expect(defaulted.map((reference) => reference.demand)).toEqual(['none']);
    const carrierOnly = collectDottedLiterals(`
      const Field = () => <ProxyUrlField labelKey="telegramConfig.proxyUrl" />;
    `);
    expect(collectReferences('const Field = () => <ProxyUrlField labelKey="telegramConfig.proxyUrl" />;')).toEqual([]);

    const names = [...defaulted.map((reference) => reference.key), ...carrierOnly];
    const asObjects = (kindTask: unknown, proxyUrl: unknown) => ({
      harness: { createDialog: { kindTask } },
      telegramConfig: { proxyUrl },
    });

    // As shipped: leaves, so both resolve and neither property has anything to say.
    const copy = [
      { lng: 'en', bundle: asObjects('Scheduled task', 'Proxy URL (optional)') },
      { lng: 'zh', bundle: asObjects('后台任务', '代理地址(可选)') },
    ];
    expect(parityGaps(names, copy)).toEqual([]);
    expect(residueOf(names, copy)).toEqual([]);

    // M21 and M22: an object in every locale. Nothing renders a node, so no
    // locale resolves either name and both fall to the pin — the same landing as
    // blanking them, because it is the same loss of copy.
    const node = { title: 'Scheduled task' };
    const mutated = [
      { lng: 'en', bundle: asObjects(node, { label: 'Proxy URL (optional)' }) },
      { lng: 'zh', bundle: asObjects({ title: '后台任务' }, { label: '代理地址(可选)' }) },
    ];
    expect(parityGaps(names, mutated)).toEqual([]);
    expect(residueOf(names, mutated)).toEqual(['harness.createDialog.kindTask', 'telegramConfig.proxyUrl']);
    expect(NON_KEY_LITERALS).not.toContain('harness.createDialog.kindTask');
    expect(NON_KEY_LITERALS).not.toContain('telegramConfig.proxyUrl');

    // A list is refused on the same ground and for the same reason: `t()` at a
    // carrier hands React an array, not the label the surface asked for.
    const listed = [
      { lng: 'en', bundle: asObjects('Scheduled task', ['Proxy URL (optional)']) },
      { lng: 'zh', bundle: asObjects('后台任务', ['代理地址(可选)']) },
    ];
    expect(residueOf(names, listed)).toEqual(['telegramConfig.proxyUrl']);

    // Broken in ONE locale only, which is the commoner accident: a parity gap
    // rather than residue, so the name is reported instead of silently pinned.
    const half = [
      { lng: 'en', bundle: asObjects('Scheduled task', 'Proxy URL (optional)') },
      { lng: 'zh', bundle: asObjects(node, { label: '代理地址(可选)' }) },
    ];
    expect(parityGaps(names, half)).toEqual([
      { key: 'harness.createDialog.kindTask', present: ['en'], absent: ['zh'] },
      { key: 'telegramConfig.proxyUrl', present: ['en'], absent: ['zh'] },
    ]);

    // And absence is still its own fact, distinct from a broken present value: a
    // `defaultValue` call renders its fallback when the key is gone from every
    // locale, so that name lands in the pin rather than in EXISTENCE. Which
    // container it would have been held to never enters the question.
    const gone = [
      { lng: 'en', bundle: { telegramConfig: { proxyUrl: 'Proxy URL (optional)' } } },
      { lng: 'zh', bundle: { telegramConfig: { proxyUrl: '代理地址(可选)' } } },
    ];
    expect(residueOf(names, gone)).toEqual(['harness.createDialog.kindTask']);
  });

  it('lets a pinned prefix resolve to a node, and lets it excuse nothing else', () => {
    // The exception, and its boundary. `containersFor` is the app's own resolver,
    // so what this pins is the rule the properties above actually run under.
    const prefixed = [
      { lng: 'en', bundle: { harness: { runStatus: { queued: 'Queued' }, other: { queued: 'Queued' } } } },
      { lng: 'zh', bundle: { harness: { runStatus: { queued: '排队中' }, other: { queued: '排队中' } } } },
    ];
    const names = ['harness.runStatus', 'harness.other'];

    // Leaf by default: the identical node resolves at neither name.
    expect(residueOf(names, prefixed)).toEqual(['harness.other', 'harness.runStatus']);
    // Pinned: the prefix resolves, and the name beside it — same shape, same
    // subtree, not enumerated — still does not.
    expect(residueOf(names, prefixed, containersFor([]))).toEqual(['harness.other']);

    // A `returnObjects` consumer is READ rather than pinned, and it buys a list
    // and only a list: the object that a prefix may be is still residue here.
    expect(
      parityGaps(['harness.runStatus'], [prefixed[0], { lng: 'zh', bundle: { harness: {} } }], containersFor([])),
    ).toEqual([{ key: 'harness.runStatus', present: ['en'], absent: ['zh'] }]);

    // And the permission does not reach EXISTENCE, which reads the call: a plain
    // `t()` on a pinned prefix is still missing the copy it renders.
    const plain: Reference = { key: 'harness.runStatus', counted: false, listed: false, demand: 'exact' };
    expect(missingCopy(localeInstance('en', prefixed[0].bundle), 'en', plain)).toBe(true);
  });

  it('pins the prefixes against the bundles, and keeps them out of copy-demanding calls', () => {
    // Both directions, on the real bundles. A pinned name that is no longer a
    // node has a stale exemption; a pinned name something renders directly would
    // be an exemption cancelling a real demand, which is the one-way rule.
    for (const { lng, bundle } of BUNDLES) {
      const instance = localeInstance(lng, bundle);
      for (const prefix of KEY_PREFIXES) {
        const value = instance.t(prefix, { returnObjects: true });
        expect(Array.isArray(value) || typeof value !== 'object', `${prefix} in ${lng} is no longer a node`).toBe(false);
        expect(resolvesIn(instance, lng, prefix, ['subtree']), `${prefix} in ${lng} has no copy under it`).toBe(true);
      }
    }
    // Every demand, defaulted included: a `defaultValue` covers a name the
    // bundles lack, and a pinned prefix is by definition a name they have, so it
    // buys that call nothing and the exemption must not read as if it did.
    expect(
      referenced
        .filter((reference) => KEY_PREFIXES.includes(reference.key))
        .map(label),
    ).toEqual([]);
  });

  it('decides a CALL by the exact shape it consumes, over every shape i18next returns', () => {
    // Nobody renders a subtree. A call site renders either the value (plain) or
    // each entry of it (`returnObjects`), so what reaches a screen is always a
    // LEAF string, and the container it has to arrive in is fixed by the call.
    //
    // Stated as a total table rather than as the cases a review has reached so
    // far: every shape i18next can hand back, judged under both call shapes. The
    // call shapes are exhaustive because the options census above measured them
    // — `count` selects which copy, `returnObjects` selects the container, and no
    // third option in `src/` changes either. A value shape added to this table
    // must be classified; one omitted fails to compile the row it belongs in.
    const plain: Reference = { key: 'k', counted: false, listed: false, demand: 'exact' };
    const listed: Reference = { key: 'k', counted: false, listed: true, demand: 'exact' };

    const table: Array<{ value: unknown; plain: boolean; listed: boolean; why: string }> = [
      { value: 'Copy', plain: true, listed: false, why: 'a string is copy; `.map` throws on it' },
      { value: '', plain: false, listed: false, why: 'blank' },
      { value: '   ', plain: false, listed: false, why: 'renders as nothing' },
      { value: 'k', plain: false, listed: false, why: 'i18next echoing the key' },
      { value: ['one', 'two'], plain: false, listed: true, why: 'a list; rendered directly it is not copy' },
      { value: [], plain: false, listed: false, why: 'the disclosure list, emptied' },
      { value: ['one', ''], plain: false, listed: false, why: 'a blank row is missing copy' },
      { value: [{ text: 'one' }], plain: false, listed: false, why: 'React throws on an object child' },
      { value: [['one']], plain: false, listed: false, why: 'a nested list is not a row of copy' },
      { value: { label: 'Copy' }, plain: false, listed: false, why: 'a prefix, not copy any call renders' },
      { value: {}, plain: false, listed: false, why: 'empty' },
      { value: undefined, plain: false, listed: false, why: 'no value at all' },
      { value: null, plain: false, listed: false, why: 'no value at all' },
      { value: 42, plain: false, listed: false, why: 'not copy' },
      { value: true, plain: false, listed: false, why: 'not copy' },
    ];

    for (const row of table) {
      expect(consumable(row.value, plain), `plain: ${row.why}`).toBe(row.plain);
      expect(consumable(row.value, listed), `listed: ${row.why}`).toBe(row.listed);
    }
  });

  it('requires a list where the call site reads returnObjects, not merely copy', () => {
    // The options axis, stated as a fixture. `count` decides WHICH copy a call can
    // reach; `returnObjects` decides what SHAPE it can consume. Both are read off
    // the call, so neither is a list of keys here and a new call site inherits.
    const source = `
      const lines = t(custom ? 'fixture.listA' : 'fixture.listB', { returnObjects: true });
      const plain = t('fixture.plain');
    `;
    const references = collectReferences(source);
    expect(references).toEqual([
      { key: 'fixture.listA', counted: false, listed: true, demand: 'exact' },
      { key: 'fixture.listB', counted: false, listed: true, demand: 'exact' },
      { key: 'fixture.plain', counted: false, listed: false, demand: 'exact' },
    ]);

    const listed: Reference = { key: 'fixture.listA', counted: false, listed: true, demand: 'exact' };
    const check = (value: unknown) =>
      missingCopy(localeInstance('en', { fixture: { listA: value } }), 'en', listed);

    expect(check(['one', 'two'])).toBe(false);
    // These shapes read as copy but fail when a list consumer calls `.map`.
    // Renderable is not enough here.
    expect(check({ 0: 'one', 1: 'two' })).toBe(true);
    expect(check('one, two')).toBe(true);
    // And a plain call is unaffected: a string is all it ever needed.
    expect(missingCopy(localeInstance('en', { fixture: { plain: 'Plain' } }), 'en', {
      key: 'fixture.plain', counted: false, listed: false, demand: 'exact',
    })).toBe(false);

    // The whole options axis, measured on this head rather than assumed: the app
    // passes exactly three i18next options at a `t()` call, across 4024 of them.
    // `count` and `returnObjects` are modelled above. `defaultValue` is the third
    // (42 sites) and is answered by `demand`, not by a claim that it never meets
    // a key this guard knows — it does, at 18 of those sites, since templates
    // started expanding. There is no `context` anywhere in `src/`.
  });

  it('separates a name being THERE from its value being copy, one selected form at a time', () => {
    // What a `defaultValue` actually buys, and the fact only the resolver holds.
    // A defaulted call is owed nothing where its key is MISSING and everything
    // where its key is present, so presence decides which — per selected form,
    // because that is how i18next spends the fallback.
    const call = (bundle: unknown, reference: Reference) =>
      missingCopy(localeInstance('en', bundle), 'en', reference);
    const counted = (over: Partial<Reference> = {}): Reference =>
      ({ key: 'card.count', counted: true, listed: false, demand: 'none', ...over });

    // Partial availability with a fallback, which is the POSITIVE control: `one`
    // is there and valid, `other` is not there at all, and the call renders its
    // own default. Failing this because a sibling category exists would reject
    // the one thing a `defaultValue` is for.
    expect(call({ card: { count_one: 'One' } }, counted())).toBe(false);
    // The same bundle, no fallback: a form the call can reach and the bundle
    // lacks is still a gap, which is what keeps this from excusing everything.
    expect(call({ card: { count_one: 'One' } }, counted({ demand: 'exact' }))).toBe(true);
    // Present and malformed, the NEGATIVE control: the fallback is never reached
    // because the key is there, so the stored value renders — and a blank
    // category is missing copy whether or not the call carries a default.
    expect(call({ card: { count_one: 'One', count_other: '' } }, counted())).toBe(true);
    expect(call({ card: { count_one: 'One', count_other: '' } }, counted({ demand: 'exact' }))).toBe(true);

    // Why presence is asked of the resolver and not of the value: a bundle may
    // store the key AS its value. That is present and invalid — copy someone has
    // to write — while the absent name is a fallback legitimately covering a
    // missing key, and `t()` hands back the same string for both.
    const echo: Reference = { key: 'card.echo', counted: false, listed: false, demand: 'none' };
    expect(call({ card: { echo: 'card.echo' } }, echo)).toBe(true);
    expect(call({ card: {} }, echo)).toBe(false);

    // The escapes this round closed, at the boundary that closes them. Each name
    // is fine on the NAME side — one is a list-shaped fixture, one is a pinned
    // prefix — and neither classification reaches a call it cannot serve.
    const onList = (over: Partial<Reference> = {}): Reference =>
      ({ key: 'fixture.rows', counted: false, listed: false, demand: 'exact', ...over });
    const rows = { fixture: { rows: ['one', 'two'] } };
    expect(call(rows, onList())).toBe(true); // a plain call renders `[object Object]`
    expect(call(rows, onList({ demand: 'none' }))).toBe(true); // and a default does not cover a present key
    expect(call(rows, onList({ listed: true }))).toBe(false); // the consumer that reads it is untouched

    expect(call(
      { harness: { runStatus: { queued: 'Queued' } } },
      { key: 'harness.runStatus', counted: false, listed: false, demand: 'none' },
    )).toBe(true);

    // A counted list, every reachable form asked: a valid `one` cannot carry an
    // empty `other` past this, though the name resolves on either side of it.
    const list: Reference = { key: 'probe.rows', counted: true, listed: true, demand: 'exact' };
    expect(call({ probe: { rows_one: ['Row'], rows_other: [] } }, list)).toBe(true);
    expect(call({ probe: { rows_one: ['Row'], rows_other: ['Rows'] } }, list)).toBe(false);
  });

  it('collects dotted literals wherever they sit, with no position enumerated', () => {
    // PARITY's input, and the reason it needs no positions: every one of these is
    // collected by the same rule, and none of the carriers is named anywhere in
    // this file. The key-prop forms are the ones that were escaping — a literal
    // `labelKey` on a component that later calls `t(labelKey)`, and the data
    // tables in `lib/agentGraph.ts` and `SettingsLayout.tsx` that hold keys as
    // values. A carrier invented later is picked up without editing this file.
    const fixture = `
      const called = t('fixture.called');
      const attr = <ProxyUrlField labelKey="fixture.attrLabel" hintKey="fixture.attrHint" />;
      const braced = <Panel titleKey={'fixture.braced'} />;
      const table = [{ labelKey: 'fixture.tableLabel', bodyKey: 'fixture.tableBody' }];
      const held = 'fixture.held';
      const invented = <Thing someKeyNobodyEnumerated="fixture.invented" />;
      const nested = { deep: { deeper: ['fixture.inArray'] } };
      const notAKey = 'editor.background';
      const alsoNot = 'avibe.editor.fontSize.v1';
      // fixture.inAComment must not be collected
      const sentence = 'Read the fixture.docs page for more';
      const single = 'undotted';
      const templated = \`fixture.\${dynamic}\`;
      type Prefix = TranslationSuffix<'fixture.typeOnly'>;
      interface Carrier { key: 'fixture.interfaceOnly' }
      const alias = 'fixture.castValue' as 'fixture.castType';
      const checked = 'fixture.satisfiesValue' satisfies 'fixture.satisfiesType';
      const jsx = <Thing title={'fixture.jsxValue' as const} />;
      enum State { Ready = 'fixture.enumValue' }
      const typed = 'fixture.runtime' satisfies TranslationKey;
      const asserted = 'fixture.asserted' as TranslationKey;
    `;
    expect(collectDottedLiterals(fixture)).toEqual([
      'avibe.editor.fontSize.v1',
      'editor.background',
      'fixture.asserted',
      'fixture.attrHint',
      'fixture.attrLabel',
      'fixture.braced',
      'fixture.called',
      'fixture.castValue',
      'fixture.enumValue',
      'fixture.held',
      'fixture.inArray',
      'fixture.invented',
      'fixture.jsxValue',
      'fixture.runtime',
      'fixture.satisfiesValue',
      'fixture.tableBody',
      'fixture.tableLabel',
    ]);
  });

  it('reports a literal one locale lost, and stays silent on what is not a key', () => {
    // PARITY's boundaries, pinned on bundles this test owns, so a scanner
    // regression fails here rather than in production. The classes are the ones
    // measured in `src/`: a key one locale dropped, a plural family one locale
    // dropped, and the 61 literals that are not keys at all.
    const gaps = parityGaps(
      [
        'card.title',
        'card.subtitle',
        'card.count',
        'card.total',
        'editor.background',
        'projects.changed',
        'agents.opencode.error_retry_limit',
        'avibe.editor.fontSize.v1',
      ],
      [
        {
          lng: 'en',
          bundle: {
            card: {
              title: 'Title',
              subtitle: 'Subtitle',
              count_one: 'one model',
              count_other: '{{count}} models',
              total_one: 'one total',
              total_other: '{{count}} total',
            },
          },
        },
        {
          lng: 'zh',
          // `subtitle` dropped outright; `total` dropped as a whole family.
          bundle: { card: { title: '标题', count_other: '{{count}} 个模型' } },
        },
      ],
    );
    expect(gaps).toEqual([
      { key: 'card.subtitle', present: ['en'], absent: ['zh'] },
      // A family kept in en and dropped in zh is a gap, not a stem that falls out:
      // neither locale resolves `card.total` bare, so only the plural probe sees it.
      { key: 'card.total', present: ['en'], absent: ['zh'] },
    ]);
    // `card.count` resolves in both — zh selects only `other`, and asking for the
    // category zh cannot reach would make every plural family a false gap.
    // The rest resolve in neither locale, so PARITY says nothing about them:
    // a Monaco theme token, an event-channel name, a config field path, a storage
    // key. Staying quiet is what makes them RESIDUE's problem, below.
  });

  it('fails the pin when a carrier-only key is deleted from every locale', () => {
    // The mutation that produced the pin, kept as a fixture. `labelKey` is a
    // carrier: no `t()` or `i18nKey` position names this key, so EXISTENCE
    // cannot see it, and once both locales drop it PARITY cannot either.
    const source = `
      const Field = () => <ProxyUrlField labelKey="telegramConfig.proxyUrl" />;
    `;
    const literals = collectDottedLiterals(source);
    const bundles = [
      { lng: 'en', bundle: { telegramConfig: { botToken: 'Bot token' } } },
      { lng: 'zh', bundle: { telegramConfig: { botToken: '机器人令牌' } } },
    ];

    // Both locales lost it, so it reads as residue rather than as a parity gap.
    expect(parityGaps(literals, bundles)).toEqual([]);
    expect(residueOf(literals, bundles)).toEqual(['telegramConfig.proxyUrl']);

    // Which is the whole point: it is not in the pinned list, so the pin fails.
    expect(NON_KEY_LITERALS).not.toContain('telegramConfig.proxyUrl');
  });

  it('hands a call-site key no locale resolves to the pin, and keeps the name either way', () => {
    // The partition, from the call-site side. This is the key a reviewer deleted
    // from both bundles to show the guard silent — `App.tsx` names it through a
    // template the checker now expands. Even so, EXISTENCE cannot be the one to
    // answer: nothing at a call site tells a key deleted from every locale apart
    // from a name that was never a key, which is why it steps aside and the pin
    // names it instead. Two properties, one case, no overlap.
    const referenced = collectReferences(`
      const Banner = () => <p>{t('remoteAuthorization.revoked.title')}</p>;
    `);
    const names = referenced.map((reference) => reference.key);
    const gone = [
      { lng: 'en', bundle: { remoteAuthorization: { revoked: { body: 'Access was revoked.' } } } },
      { lng: 'zh', bundle: { remoteAuthorization: { revoked: { body: '访问已被撤销。' } } } },
    ];
    expect(parityGaps(names, gone)).toEqual([]);
    expect(residueOf(names, gone)).toEqual(['remoteAuthorization.revoked.title']);
    expect(NON_KEY_LITERALS).not.toContain('remoteAuthorization.revoked.title');

    // And a demand of `none` narrows only what copy is required, never whether
    // the name is watched: a call carrying its own fallback still may not have
    // copy in one locale and an English fallback in the other.
    const defaulted = collectReferences(`
      const title = t('harness.createDialog.kindTask', { defaultValue: 'Background work' });
    `);
    expect(defaulted).toEqual([
      { key: 'harness.createDialog.kindTask', counted: false, listed: false, demand: 'none' },
    ]);
    expect(
      parityGaps(defaulted.map((reference) => reference.key), [
        { lng: 'en', bundle: { harness: { createDialog: { kindTask: 'Background work' } } } },
        { lng: 'zh', bundle: { harness: { createDialog: { kindWatch: '后台监听' } } } },
      ]),
    ).toEqual([{ key: 'harness.createDialog.kindTask', present: ['en'], absent: ['zh'] }]);
  });

  it('treats a blanked value as missing copy, in one locale or in every locale', () => {
    // A key can be emptied as well as deleted, and an empty value renders a blank
    // label rather than a raw key, which is the quieter of the two failures. The
    // earlier `exists()` predicate said yes to both bundles here and the suite
    // stayed green; asking the VALUE moves each case to the property that owns it.
    const source = `
      const Field = () => <ProxyUrlField labelKey="telegramConfig.proxyUrl" />;
    `;
    const literals = collectDottedLiterals(source);
    const copy = (proxyUrl: string, botToken: string) => ({ telegramConfig: { proxyUrl, botToken } });

    // Blanked in one locale: the other still renders it, so it is a parity gap.
    const oneBlank = [
      { lng: 'en', bundle: copy('Proxy URL', 'Bot token') },
      { lng: 'zh', bundle: copy('', '机器人令牌') },
    ];
    expect(parityGaps(literals, oneBlank)).toEqual([
      { key: 'telegramConfig.proxyUrl', present: ['en'], absent: ['zh'] },
    ]);
    expect(residueOf(literals, oneBlank)).toEqual([]);

    // Blanked in every locale: nothing renders it, so it falls to the pin —
    // the same landing as deleting it outright, because it is the same loss.
    const allBlank = [
      { lng: 'en', bundle: copy('', 'Bot token') },
      { lng: 'zh', bundle: copy('   ', '机器人令牌') },
    ];
    expect(parityGaps(literals, allBlank)).toEqual([]);
    expect(residueOf(literals, allBlank)).toEqual(['telegramConfig.proxyUrl']);
    expect(NON_KEY_LITERALS).not.toContain('telegramConfig.proxyUrl');

    // Whitespace is blank: `zh` above holds three spaces, and a value that
    // renders as nothing is empty of copy whichever character made it so.
  });

  it('pins the names that are not keys, so no key can leave both locales unseen', () => {
    // Exact set equality, not a count: a count lets one literal leave as another
    // enters. Sorted on both sides so the list above can stay grouped by class.
    expect(residueOf(appCandidateKeys(referenced), BUNDLES, appContainers)).toEqual(
      [...NON_KEY_LITERALS].sort((a, b) => a.localeCompare(b)),
    );
  });

  it('keeps every name the app can ask for resolving in both locales or neither', () => {
    expect(parityGaps(appCandidateKeys(referenced), BUNDLES, appContainers)).toEqual([]);
  });
});