@astilba/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rees Morris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# @astilba/core — Phase 0
+
+The **format-neutral heart** of Astilba: a canonical i18n message model, vendored
+CLDR plural rules, the `AstilbaError` class, the **round-trip message-fidelity
+harness** (a generic driver plus the `FormatAdapter` / `RenderOracle` contracts a
+syntax adapter implements), and MT masking + placeholder validation over canonical
+tokens.
+
+This package knows nothing about any specific file format or message syntax — that
+lives in a syntax adapter such as
+[`@astilba/adapter-i18next-v4`](https://github.com/astilbahq/astilba/tree/main/packages/adapter-i18next-v4)
+(internal for now, not yet published), which depends on this package and plugs in the
+native i18next-v4 parser, exporter, and render oracle. **The adapter is native i18next v4 only; ICU is rejected loudly,
+never silently approximated.**
+
+```bash
+pnpm install
+vp test           # the fidelity matrix IS the test suite
+vp run typecheck
+```
+
+## What "lossless" means here
+
+Equivalence is on **resolved `t()` output**, not file bytes. An adapter may
+renormalise freely (nested↔flat keys, key ordering, suffix re-derivation), so byte
+equality is explicitly _not_ the test. The harness drives an adapter to import a
+bundle `B → C` (canonical), export `C → B'`, and asserts that for every probe
+vector — each context value and each plural category **that has a value**, with a
+representative `count` per category — the adapter's render of `B'` is byte-identical
+to its render of `B`.
+
+## Module map
+
+| Module       | Role                                                                                                                                                                                                                               |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `model.ts`   | The canonical model: `Key → contexts → PluralSet(kind, category→Value)`. Value text is preserved byte-exact (`Value.raw`); `tokens` is a derived view used for masking/validation.                                                 |
+| `cldr.ts`    | **Vendored** CLDR plural rules — host-ICU-independent. Category sets, `select(n)`, and a representative count per category, for en/de/fr/ru/pl/ar/ja/zh/ko. Unknown languages fall back to `other`-only.                           |
+| `errors.ts`  | `AstilbaError` — one error class with an open string `code`, so each adapter declares its own code set without coupling core to a syntax.                                                                                          |
+| `harness.ts` | The generic round-trip driver (`runRoundTrip`) and the `FormatAdapter` / `RenderOracle` contracts an adapter implements. Knows only the canonical model — nothing format-specific.                                                 |
+| `mask.ts`    | MT masking/unmasking over canonical tokens plus the fail-closed, CI-failable placeholder validator. The string-entry validator takes a `Tokenizer` by injection, so it is callable standalone with any syntax adapter's tokenizer. |
+
+The model and CLDR rules are also reachable via the `@astilba/core/cldr` subpath.
+
+## MT masking & placeholder validation
+
+`maskTokens` replaces every non-text token (interpolation, `$t()` nesting, markup)
+with an opaque sentinel before an MT/LLM call — the formatter keyword and nesting
+ref live _inside_ the masked span, so the engine never translates them — and
+`unmask` restores them. `validatePlaceholderTokens` is a fail-closed check that
+every interpolation variable, formatter keyword, nesting ref (and its options), and
+markup tag survived translation unmodified; `validatePlaceholders(source,
+translated, tokenize)` is the raw-string entry point for CI.
+
+## Known Phase-0 boundaries (logged, not bugs)
+
+- **One plural _kind_ per (key, context):** the model holds either a cardinal or an
+  ordinal map per cell, so a key used as both is rejected by the adapter
+  (`INVALID_RESOURCE`) rather than silently merged.
+- The **vendored CLDR table** covers the corpus-plan languages; other languages fall
+  back to `other`-only unless a full table is vendored.

package/dist/cldr.d.ts

@@ -0,0 +1,52 @@
+import { a as PluralKind, n as CLDRCategory } from "./model-5mrSQGoC.js";
+
+//#region src/cldr.d.ts
+/** CLDR plural operands for a non-negative number `n`. */
+interface Operands {
+  n: number;
+  i: number;
+  v: number;
+  f: number;
+  t: number;
+}
+declare const operands: (input: number) => Operands;
+interface PluralRule {
+  categories: CLDRCategory[];
+  select: (n: number) => CLDRCategory;
+  /** A representative count for each category in `categories`. */
+  representative: Partial<Record<CLDRCategory, number>>;
+}
+interface LanguagePlurals {
+  cardinal: PluralRule;
+  ordinal: PluralRule;
+}
+/** Primary subtags with vendored CLDR rules. */
+declare const SUPPORTED_LANGUAGES: string[];
+/**
+ * Reduce a BCP-47 tag to its primary language subtag (`en-US` -> `en`).
+ *
+ * KNOWN LIMITATION: this collapses the region, but a few languages have
+ * region-specific CLDR plural rules — most notably `pt-PT` differs from `pt`
+ * (Brazilian). Harmless while the vendored table is small (those languages
+ * aren't in it, so both fall back to `other`-only), but when the full
+ * `make-plural` table is vendored, region-specific entries (e.g. `pt-PT`) must
+ * be looked up before the primary subtag (a v1.0 item).
+ */
+declare const primarySubtag: (language: string) => string;
+declare const isSupportedLanguage: (language: string) => boolean;
+/**
+ * Resolve a language's plural rules. Unknown languages fall back to `other`-only
+ * (graceful) — callers that need to warn can check
+ * `isSupportedLanguage` first.
+ */
+declare const getPlurals: (language: string) => LanguagePlurals;
+declare const categoriesFor: (language: string, kind: PluralKind) => CLDRCategory[];
+/** The union of cardinal + ordinal categories for a language (used by disambiguation). */
+declare const allCategoriesFor: (language: string) => Set<CLDRCategory>;
+/** Select the category for a count, honoring the ordinal flag. */
+declare const selectCategory: (language: string, count: number, ordinal: boolean) => CLDRCategory;
+/** A representative count that selects `category` for the given language/kind. */
+declare const representativeCount: (language: string, kind: "cardinal" | "ordinal", category: CLDRCategory) => number;
+//#endregion
+export { LanguagePlurals, PluralRule, SUPPORTED_LANGUAGES, allCategoriesFor, categoriesFor, getPlurals, isSupportedLanguage, operands, primarySubtag, representativeCount, selectCategory };
+//# sourceMappingURL=cldr.d.ts.map

package/dist/cldr.js

@@ -0,0 +1,258 @@
+//#region src/cldr.ts
+const operands = (input) => {
+	const n = Math.abs(input);
+	const s = n.toString();
+	const dot = s.indexOf(".");
+	if (dot === -1) return {
+		f: 0,
+		i: n,
+		n,
+		t: 0,
+		v: 0
+	};
+	const intPart = s.slice(0, dot);
+	const fracPart = s.slice(dot + 1);
+	const trimmed = fracPart.replace(/0+$/u, "");
+	return {
+		f: fracPart === "" ? 0 : Number.parseInt(fracPart, 10),
+		i: Number.parseInt(intPart, 10),
+		n,
+		t: trimmed === "" ? 0 : Number.parseInt(trimmed, 10),
+		v: fracPart.length
+	};
+};
+const inRange = (x, lo, hi) => x >= lo && x <= hi;
+/** The trivial single-category rule (Japanese, Chinese, Korean, ... and the fallback). */
+const OTHER_ONLY = {
+	categories: ["other"],
+	representative: { other: 1 },
+	select: () => "other"
+};
+/**
+* The vendored table. Keys are base languages (BCP-47 primary subtag).
+* Languages whose ordinal has no special rule use OTHER_ONLY for ordinal.
+*/
+const TABLE = {
+	ar: {
+		cardinal: {
+			categories: [
+				"zero",
+				"one",
+				"two",
+				"few",
+				"many",
+				"other"
+			],
+			representative: {
+				few: 3,
+				many: 11,
+				one: 1,
+				other: 100,
+				two: 2,
+				zero: 0
+			},
+			select: (n) => {
+				const o = operands(n);
+				if (o.n === 0) return "zero";
+				if (o.n === 1) return "one";
+				if (o.n === 2) return "two";
+				const mod100 = o.i % 100;
+				if (o.v === 0 && inRange(mod100, 3, 10)) return "few";
+				if (o.v === 0 && inRange(mod100, 11, 99)) return "many";
+				return "other";
+			}
+		},
+		ordinal: OTHER_ONLY
+	},
+	de: {
+		cardinal: {
+			categories: ["one", "other"],
+			representative: {
+				one: 1,
+				other: 2
+			},
+			select: (n) => {
+				const o = operands(n);
+				return o.i === 1 && o.v === 0 ? "one" : "other";
+			}
+		},
+		ordinal: OTHER_ONLY
+	},
+	en: {
+		cardinal: {
+			categories: ["one", "other"],
+			representative: {
+				one: 1,
+				other: 2
+			},
+			select: (n) => {
+				const o = operands(n);
+				return o.i === 1 && o.v === 0 ? "one" : "other";
+			}
+		},
+		ordinal: {
+			categories: [
+				"one",
+				"two",
+				"few",
+				"other"
+			],
+			representative: {
+				few: 3,
+				one: 1,
+				other: 4,
+				two: 2
+			},
+			select: (n) => {
+				const { i } = operands(n);
+				const mod10 = i % 10;
+				const mod100 = i % 100;
+				if (mod10 === 1 && mod100 !== 11) return "one";
+				if (mod10 === 2 && mod100 !== 12) return "two";
+				if (mod10 === 3 && mod100 !== 13) return "few";
+				return "other";
+			}
+		}
+	},
+	fr: {
+		cardinal: {
+			categories: [
+				"one",
+				"many",
+				"other"
+			],
+			representative: {
+				many: 1e6,
+				one: 1,
+				other: 2
+			},
+			select: (n) => {
+				const o = operands(n);
+				if (o.i === 0 || o.i === 1) return "one";
+				if (o.i % 1e6 === 0 && o.v === 0) return "many";
+				return "other";
+			}
+		},
+		ordinal: {
+			categories: ["one", "other"],
+			representative: {
+				one: 1,
+				other: 2
+			},
+			select: (n) => operands(n).n === 1 ? "one" : "other"
+		}
+	},
+	ja: {
+		cardinal: OTHER_ONLY,
+		ordinal: OTHER_ONLY
+	},
+	ko: {
+		cardinal: OTHER_ONLY,
+		ordinal: OTHER_ONLY
+	},
+	pl: {
+		cardinal: {
+			categories: [
+				"one",
+				"few",
+				"many",
+				"other"
+			],
+			representative: {
+				few: 2,
+				many: 5,
+				one: 1,
+				other: 1.5
+			},
+			select: (n) => {
+				const o = operands(n);
+				if (o.v !== 0) return "other";
+				if (o.i === 1) return "one";
+				const mod10 = o.i % 10;
+				const mod100 = o.i % 100;
+				if (inRange(mod10, 2, 4) && !inRange(mod100, 12, 14)) return "few";
+				return "many";
+			}
+		},
+		ordinal: OTHER_ONLY
+	},
+	ru: {
+		cardinal: {
+			categories: [
+				"one",
+				"few",
+				"many",
+				"other"
+			],
+			representative: {
+				few: 2,
+				many: 5,
+				one: 1,
+				other: 1.5
+			},
+			select: (n) => {
+				const o = operands(n);
+				if (o.v !== 0) return "other";
+				const mod10 = o.i % 10;
+				const mod100 = o.i % 100;
+				if (mod10 === 1 && mod100 !== 11) return "one";
+				if (inRange(mod10, 2, 4) && !inRange(mod100, 12, 14)) return "few";
+				return "many";
+			}
+		},
+		ordinal: OTHER_ONLY
+	},
+	zh: {
+		cardinal: OTHER_ONLY,
+		ordinal: OTHER_ONLY
+	}
+};
+const FALLBACK = {
+	cardinal: OTHER_ONLY,
+	ordinal: OTHER_ONLY
+};
+/** Primary subtags with vendored CLDR rules. */
+const SUPPORTED_LANGUAGES = Object.keys(TABLE);
+/**
+* Reduce a BCP-47 tag to its primary language subtag (`en-US` -> `en`).
+*
+* KNOWN LIMITATION: this collapses the region, but a few languages have
+* region-specific CLDR plural rules — most notably `pt-PT` differs from `pt`
+* (Brazilian). Harmless while the vendored table is small (those languages
+* aren't in it, so both fall back to `other`-only), but when the full
+* `make-plural` table is vendored, region-specific entries (e.g. `pt-PT`) must
+* be looked up before the primary subtag (a v1.0 item).
+*/
+const primarySubtag = (language) => language.toLowerCase().split(/[-_]/u)[0] ?? language.toLowerCase();
+const isSupportedLanguage = (language) => primarySubtag(language) in TABLE;
+/**
+* Resolve a language's plural rules. Unknown languages fall back to `other`-only
+* (graceful) — callers that need to warn can check
+* `isSupportedLanguage` first.
+*/
+const getPlurals = (language) => TABLE[primarySubtag(language)] ?? FALLBACK;
+const categoriesFor = (language, kind) => {
+	if (kind === "none") return ["other"];
+	const p = getPlurals(language);
+	return kind === "ordinal" ? p.ordinal.categories : p.cardinal.categories;
+};
+/** The union of cardinal + ordinal categories for a language (used by disambiguation). */
+const allCategoriesFor = (language) => {
+	const p = getPlurals(language);
+	return new Set([...p.cardinal.categories, ...p.ordinal.categories]);
+};
+/** Select the category for a count, honoring the ordinal flag. */
+const selectCategory = (language, count, ordinal) => {
+	const p = getPlurals(language);
+	return ordinal ? p.ordinal.select(count) : p.cardinal.select(count);
+};
+/** A representative count that selects `category` for the given language/kind. */
+const representativeCount = (language, kind, category) => {
+	if (kind === "cardinal" && category === "zero") return 0;
+	const p = getPlurals(language);
+	return (kind === "ordinal" ? p.ordinal : p.cardinal).representative[category] ?? 1;
+};
+//#endregion
+export { SUPPORTED_LANGUAGES, allCategoriesFor, categoriesFor, getPlurals, isSupportedLanguage, operands, primarySubtag, representativeCount, selectCategory };
+
+//# sourceMappingURL=cldr.js.map

package/dist/cldr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cldr.js","names":[],"sources":["../src/cldr.ts"],"sourcesContent":["/**\n * Vendored CLDR plural rules.\n *\n * Why vendored and not `Intl.PluralRules`: native i18next resolves plurals\n * against the END USER's ambient browser/host ICU, which drifts across CLDR\n * versions and across Bun/Node/Workers. If our exporter emits a suffix set that\n * disagrees with what the client's ICU asks for, the user sees a silent miss.\n * So we pin one table here, used by BOTH the exporter (which suffix keys to emit)\n * and the round-trip resolver (which suffix a given count selects). This makes\n * emission host-independent and the harness fully deterministic.\n *\n * Each rule carries:\n *  - `categories`: the ordered set of categories that apply to the language.\n *  - `select(n)`: the CLDR rule, count -> category.\n *  - `representative`: one count per category, for building round-trip test\n *    vectors (a representative count).\n *\n * Rules transcribed from CLDR plural-rule data. This vendored table is the\n * Phase-0 stand-in for `make-plural`; the corpus-plan languages plus a few\n * common ones are covered. Unknown languages fall back to `other`-only\n * (custom variants are opaque tags that fall back gracefully).\n */\n\nimport type { CLDRCategory, PluralKind } from \"./model.ts\";\n\n/** CLDR plural operands for a non-negative number `n`. */\ninterface Operands {\n  // absolute value\n  n: number;\n  // integer digits\n  i: number;\n  // count of visible fraction digits (with trailing zeros)\n  v: number;\n  // visible fraction digits (with trailing zeros), as integer\n  f: number;\n  // visible fraction digits (without trailing zeros), as integer\n  t: number;\n}\n\nexport const operands = (input: number): Operands => {\n  const n = Math.abs(input);\n  const s = n.toString();\n  const dot = s.indexOf(\".\");\n  if (dot === -1) {\n    return { f: 0, i: n, n, t: 0, v: 0 };\n  }\n  const intPart = s.slice(0, dot);\n  const fracPart = s.slice(dot + 1);\n  const trimmed = fracPart.replace(/0+$/u, \"\");\n  return {\n    f: fracPart === \"\" ? 0 : Number.parseInt(fracPart, 10),\n    i: Number.parseInt(intPart, 10),\n    n,\n    t: trimmed === \"\" ? 0 : Number.parseInt(trimmed, 10),\n    v: fracPart.length,\n  };\n};\n\nconst inRange = (x: number, lo: number, hi: number): boolean =>\n  x >= lo && x <= hi;\n\nexport interface PluralRule {\n  categories: CLDRCategory[];\n  select: (n: number) => CLDRCategory;\n  /** A representative count for each category in `categories`. */\n  representative: Partial<Record<CLDRCategory, number>>;\n}\n\nexport interface LanguagePlurals {\n  cardinal: PluralRule;\n  ordinal: PluralRule;\n}\n\n/** The trivial single-category rule (Japanese, Chinese, Korean, ... and the fallback). */\nconst OTHER_ONLY: PluralRule = {\n  categories: [\"other\"],\n  representative: { other: 1 },\n  select: () => \"other\",\n};\n\nconst EN_CARDINAL: PluralRule = {\n  categories: [\"one\", \"other\"],\n  representative: { one: 1, other: 2 },\n  select: (n) => {\n    const o = operands(n);\n    return o.i === 1 && o.v === 0 ? \"one\" : \"other\";\n  },\n};\n\nconst EN_ORDINAL: PluralRule = {\n  categories: [\"one\", \"two\", \"few\", \"other\"],\n  representative: { few: 3, one: 1, other: 4, two: 2 },\n  select: (n) => {\n    // CLDR ordinal categories key off the integer operand `i`, which operands()\n    // derives with Math.abs — so negative counts select the same form as i18next\n    // (raw `n % 10` would give a negative remainder and miss the `one`/`two`/`few`\n    // branches, e.g. -1 -> \"other\" instead of \"one\").\n    const { i } = operands(n);\n    const mod10 = i % 10;\n    const mod100 = i % 100;\n    // 1st, 21st\n    if (mod10 === 1 && mod100 !== 11) {\n      return \"one\";\n    }\n    // 2nd, 22nd\n    if (mod10 === 2 && mod100 !== 12) {\n      return \"two\";\n    }\n    // 3rd, 23rd\n    if (mod10 === 3 && mod100 !== 13) {\n      return \"few\";\n    }\n    // 4th, 11th, 12th, 13th\n    return \"other\";\n  },\n};\n\nconst FR_CARDINAL: PluralRule = {\n  categories: [\"one\", \"many\", \"other\"],\n  representative: { many: 1_000_000, one: 1, other: 2 },\n  select: (n) => {\n    const o = operands(n);\n    if (o.i === 0 || o.i === 1) {\n      return \"one\";\n    }\n    // CLDR fr `many`: large round numbers (10^6, ...) with no fraction digits.\n    // (i === 0 already returned `one` above, so no `i !== 0` guard is needed here.)\n    if (o.i % 1_000_000 === 0 && o.v === 0) {\n      return \"many\";\n    }\n    return \"other\";\n  },\n};\n\nconst FR_ORDINAL: PluralRule = {\n  categories: [\"one\", \"other\"],\n  representative: { one: 1, other: 2 },\n  // CLDR fr ordinal \"one\" is `n = 1` on the absolute value; operands().n applies\n  // Math.abs so -1 selects \"one\" like i18next (raw `n === 1` missed it).\n  select: (n) => (operands(n).n === 1 ? \"one\" : \"other\"),\n};\n\nconst DE_CARDINAL: PluralRule = {\n  categories: [\"one\", \"other\"],\n  representative: { one: 1, other: 2 },\n  select: (n) => {\n    const o = operands(n);\n    return o.i === 1 && o.v === 0 ? \"one\" : \"other\";\n  },\n};\n\nconst RU_CARDINAL: PluralRule = {\n  categories: [\"one\", \"few\", \"many\", \"other\"],\n  representative: { few: 2, many: 5, one: 1, other: 1.5 },\n  select: (n) => {\n    const o = operands(n);\n    // fractions\n    if (o.v !== 0) {\n      return \"other\";\n    }\n    const mod10 = o.i % 10;\n    const mod100 = o.i % 100;\n    if (mod10 === 1 && mod100 !== 11) {\n      return \"one\";\n    }\n    if (inRange(mod10, 2, 4) && !inRange(mod100, 12, 14)) {\n      return \"few\";\n    }\n    // mod10 in {0,5..9} or mod100 in 11..14\n    return \"many\";\n  },\n};\n\nconst PL_CARDINAL: PluralRule = {\n  categories: [\"one\", \"few\", \"many\", \"other\"],\n  representative: { few: 2, many: 5, one: 1, other: 1.5 },\n  select: (n) => {\n    const o = operands(n);\n    // fractions\n    if (o.v !== 0) {\n      return \"other\";\n    }\n    if (o.i === 1) {\n      return \"one\";\n    }\n    const mod10 = o.i % 10;\n    const mod100 = o.i % 100;\n    if (inRange(mod10, 2, 4) && !inRange(mod100, 12, 14)) {\n      return \"few\";\n    }\n    return \"many\";\n  },\n};\n\nconst AR_CARDINAL: PluralRule = {\n  categories: [\"zero\", \"one\", \"two\", \"few\", \"many\", \"other\"],\n  representative: { few: 3, many: 11, one: 1, other: 100, two: 2, zero: 0 },\n  select: (n) => {\n    const o = operands(n);\n    if (o.n === 0) {\n      return \"zero\";\n    }\n    if (o.n === 1) {\n      return \"one\";\n    }\n    if (o.n === 2) {\n      return \"two\";\n    }\n    const mod100 = o.i % 100;\n    if (o.v === 0 && inRange(mod100, 3, 10)) {\n      return \"few\";\n    }\n    if (o.v === 0 && inRange(mod100, 11, 99)) {\n      return \"many\";\n    }\n    return \"other\";\n  },\n};\n\n/**\n * The vendored table. Keys are base languages (BCP-47 primary subtag).\n * Languages whose ordinal has no special rule use OTHER_ONLY for ordinal.\n */\nconst TABLE: Record<string, LanguagePlurals> = {\n  ar: { cardinal: AR_CARDINAL, ordinal: OTHER_ONLY },\n  de: { cardinal: DE_CARDINAL, ordinal: OTHER_ONLY },\n  en: { cardinal: EN_CARDINAL, ordinal: EN_ORDINAL },\n  fr: { cardinal: FR_CARDINAL, ordinal: FR_ORDINAL },\n  ja: { cardinal: OTHER_ONLY, ordinal: OTHER_ONLY },\n  ko: { cardinal: OTHER_ONLY, ordinal: OTHER_ONLY },\n  pl: { cardinal: PL_CARDINAL, ordinal: OTHER_ONLY },\n  ru: { cardinal: RU_CARDINAL, ordinal: OTHER_ONLY },\n  zh: { cardinal: OTHER_ONLY, ordinal: OTHER_ONLY },\n};\n\nconst FALLBACK: LanguagePlurals = { cardinal: OTHER_ONLY, ordinal: OTHER_ONLY };\n\n/** Primary subtags with vendored CLDR rules. */\nexport const SUPPORTED_LANGUAGES: string[] = Object.keys(TABLE);\n\n/**\n * Reduce a BCP-47 tag to its primary language subtag (`en-US` -> `en`).\n *\n * KNOWN LIMITATION: this collapses the region, but a few languages have\n * region-specific CLDR plural rules — most notably `pt-PT` differs from `pt`\n * (Brazilian). Harmless while the vendored table is small (those languages\n * aren't in it, so both fall back to `other`-only), but when the full\n * `make-plural` table is vendored, region-specific entries (e.g. `pt-PT`) must\n * be looked up before the primary subtag (a v1.0 item).\n */\nexport const primarySubtag = (language: string): string =>\n  language.toLowerCase().split(/[-_]/u)[0] ?? language.toLowerCase();\n\nexport const isSupportedLanguage = (language: string): boolean =>\n  primarySubtag(language) in TABLE;\n\n/**\n * Resolve a language's plural rules. Unknown languages fall back to `other`-only\n * (graceful) — callers that need to warn can check\n * `isSupportedLanguage` first.\n */\nexport const getPlurals = (language: string): LanguagePlurals =>\n  TABLE[primarySubtag(language)] ?? FALLBACK;\n\nexport const categoriesFor = (\n  language: string,\n  kind: PluralKind\n): CLDRCategory[] => {\n  if (kind === \"none\") {\n    return [\"other\"];\n  }\n  const p = getPlurals(language);\n  return kind === \"ordinal\" ? p.ordinal.categories : p.cardinal.categories;\n};\n\n/** The union of cardinal + ordinal categories for a language (used by disambiguation). */\nexport const allCategoriesFor = (language: string): Set<CLDRCategory> => {\n  const p = getPlurals(language);\n  return new Set<CLDRCategory>([\n    ...p.cardinal.categories,\n    ...p.ordinal.categories,\n  ]);\n};\n\n/** Select the category for a count, honoring the ordinal flag. */\nexport const selectCategory = (\n  language: string,\n  count: number,\n  ordinal: boolean\n): CLDRCategory => {\n  const p = getPlurals(language);\n  return ordinal ? p.ordinal.select(count) : p.cardinal.select(count);\n};\n\n/** A representative count that selects `category` for the given language/kind. */\nexport const representativeCount = (\n  language: string,\n  kind: \"cardinal\" | \"ordinal\",\n  category: CLDRCategory\n): number => {\n  // i18next's `_zero` cardinal special-case is reached at count 0 for EVERY\n  // language, even ones whose CLDR set has no `zero` category.\n  if (kind === \"cardinal\" && category === \"zero\") {\n    return 0;\n  }\n  const p = getPlurals(language);\n  const rule = kind === \"ordinal\" ? p.ordinal : p.cardinal;\n  const rep = rule.representative[category];\n  return rep ?? 1;\n};\n"],"mappings":"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"}

package/dist/harness.d.ts

@@ -0,0 +1,68 @@
+import { i as Key, o as PluralSet, r as CanonicalModel } from "./model-5mrSQGoC.js";
+
+//#region src/harness.d.ts
+/**
+ * A format/syntax adapter's production contract: files <-> canonical model.
+ * `Files` is the adapter's on-disk shape (e.g. i18next's nested-JSON bundles);
+ * `Input` is whatever it parses from (e.g. `{ language, resources, options }`).
+ */
+interface FormatAdapter<Files = unknown, Input = unknown> {
+  readonly id: string;
+  parse: (input: Input) => CanonicalModel;
+  export: (model: CanonicalModel) => Files;
+}
+/**
+ * A probe point the harness compares between source and re-exported files. `key`
+ * and the plural classification are canonical (core); `args` is the adapter's
+ * render-argument shape (e.g. i18next `{ count, ordinal, context }`) and is
+ * opaque to the driver — it just hands it back to the oracle.
+ */
+interface Vector {
+  key: Key;
+  context: string;
+  kind: PluralSet["kind"];
+  category?: string;
+  args: unknown;
+}
+/**
+ * The per-adapter render oracle: enumerate the probe vectors for a model, and
+ * render one against a set of files (returning the resolved `t()` string, or
+ * `undefined` if it doesn't resolve). Test-only; supplied by the adapter.
+ */
+interface RenderOracle<Files = unknown> {
+  vectors: (model: CanonicalModel) => Vector[];
+  render: (files: Files, vector: Vector, language: string) => string | undefined;
+}
+interface RoundTripMismatch {
+  namespace: string;
+  base: string;
+  context: string;
+  kind: PluralSet["kind"];
+  category?: string;
+  args: unknown;
+  fromSource: string | undefined;
+  fromExported: string | undefined;
+  /** set when the source itself failed to resolve a vector the model produced */
+  note?: string;
+}
+interface RoundTripReport<Files = unknown> {
+  language: string;
+  verdict: "lossless" | "mismatch";
+  vectorCount: number;
+  mismatches: RoundTripMismatch[];
+  canonical: CanonicalModel;
+  exported: Files;
+}
+/**
+ * The generic driver: import → export → compare via the adapter's oracle. Equivalence
+ * is on resolved render output, so a re-export that renders identically to the
+ * source for every probe is lossless — regardless of how the files were renormalised.
+ */
+declare const runRoundTrip: <Files, Input extends {
+  resources: Files;
+}>(adapter: FormatAdapter<Files, Input>, oracle: RenderOracle<Files>, input: Input) => RoundTripReport<Files>;
+/** Format a non-lossless report into a human-readable failure message. */
+declare const formatMismatches: (report: RoundTripReport) => string;
+//#endregion
+export { FormatAdapter, RenderOracle, RoundTripMismatch, RoundTripReport, Vector, formatMismatches, runRoundTrip };
+//# sourceMappingURL=harness.d.ts.map

package/dist/harness.js

@@ -0,0 +1,47 @@
+//#region src/harness.ts
+/**
+* The generic driver: import → export → compare via the adapter's oracle. Equivalence
+* is on resolved render output, so a re-export that renders identically to the
+* source for every probe is lossless — regardless of how the files were renormalised.
+*/
+const runRoundTrip = (adapter, oracle, input) => {
+	const canonical = adapter.parse(input);
+	const exported = adapter.export(canonical);
+	const source = input.resources;
+	const { language } = canonical;
+	const vectors = oracle.vectors(canonical);
+	const mismatches = [];
+	for (const v of vectors) {
+		const fromSource = oracle.render(source, v, language);
+		const fromExported = oracle.render(exported, v, language);
+		const m = {
+			...v.category !== void 0 && v.category !== "" ? { category: v.category } : {},
+			args: v.args,
+			base: v.key.base,
+			context: v.context,
+			fromExported,
+			fromSource,
+			kind: v.kind,
+			namespace: v.key.namespace
+		};
+		if (fromSource === void 0) mismatches.push({
+			...m,
+			note: "source did not resolve a vector the model produced"
+		});
+		else if (fromSource !== fromExported) mismatches.push(m);
+	}
+	return {
+		canonical,
+		exported,
+		language,
+		mismatches,
+		vectorCount: vectors.length,
+		verdict: mismatches.length === 0 ? "lossless" : "mismatch"
+	};
+};
+/** Format a non-lossless report into a human-readable failure message. */
+const formatMismatches = (report) => report.mismatches.slice(0, 5).map((m) => `  ${m.namespace}:${m.base} ctx="${m.context}" ${m.kind}${m.category !== void 0 && m.category !== "" ? `/${m.category}` : ""}: source=${JSON.stringify(m.fromSource)} exported=${JSON.stringify(m.fromExported)}`).join("\n");
+//#endregion
+export { formatMismatches, runRoundTrip };
+
+//# sourceMappingURL=harness.js.map

package/dist/harness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.js","names":[],"sources":["../src/harness.ts"],"sourcesContent":["/**\n * The round-trip fidelity harness — DRIVER + contracts.\n *\n * Published as the `@astilba/core/harness` subpath, kept OUT of the stable\n * `@astilba/core` entry: the `FormatAdapter`/`RenderOracle` contracts are\n * unproven until a second (e.g. ICU) adapter implements them, so treat this\n * surface as unstable pre-1.0 — it may change in any minor.\n *\n * This is the format-neutral half: the generic loop\n *\n *     model = adapter.parse(input) ; files' = adapter.export(model)\n *     for each probe vector: assert oracle.render(sourceFiles) === oracle.render(files')\n *\n * \"Render\" is per-syntax (i18next resolves `_one`/`_ordinal_*`/`_male` suffix keys;\n * ICU resolves entirely differently), so each format adapter supplies its own\n * `RenderOracle`. The oracle is a TEST-SUPPORT capability — in production the\n * end-user's i18next does the rendering, never this. The driver knows only the\n * canonical model; it imports nothing format-specific.\n */\n\nimport type { CanonicalModel, Key, PluralSet } from \"./model.ts\";\n\n/**\n * A format/syntax adapter's production contract: files <-> canonical model.\n * `Files` is the adapter's on-disk shape (e.g. i18next's nested-JSON bundles);\n * `Input` is whatever it parses from (e.g. `{ language, resources, options }`).\n */\nexport interface FormatAdapter<Files = unknown, Input = unknown> {\n  readonly id: string;\n  parse: (input: Input) => CanonicalModel;\n  export: (model: CanonicalModel) => Files;\n}\n\n/**\n * A probe point the harness compares between source and re-exported files. `key`\n * and the plural classification are canonical (core); `args` is the adapter's\n * render-argument shape (e.g. i18next `{ count, ordinal, context }`) and is\n * opaque to the driver — it just hands it back to the oracle.\n */\nexport interface Vector {\n  key: Key;\n  context: string;\n  kind: PluralSet[\"kind\"];\n  category?: string;\n  args: unknown;\n}\n\n/**\n * The per-adapter render oracle: enumerate the probe vectors for a model, and\n * render one against a set of files (returning the resolved `t()` string, or\n * `undefined` if it doesn't resolve). Test-only; supplied by the adapter.\n */\nexport interface RenderOracle<Files = unknown> {\n  vectors: (model: CanonicalModel) => Vector[];\n  render: (\n    files: Files,\n    vector: Vector,\n    language: string\n  ) => string | undefined;\n}\n\nexport interface RoundTripMismatch {\n  namespace: string;\n  base: string;\n  context: string;\n  kind: PluralSet[\"kind\"];\n  category?: string;\n  args: unknown;\n  fromSource: string | undefined;\n  fromExported: string | undefined;\n  /** set when the source itself failed to resolve a vector the model produced */\n  note?: string;\n}\n\nexport interface RoundTripReport<Files = unknown> {\n  language: string;\n  verdict: \"lossless\" | \"mismatch\";\n  vectorCount: number;\n  mismatches: RoundTripMismatch[];\n  canonical: CanonicalModel;\n  exported: Files;\n}\n\n/**\n * The generic driver: import → export → compare via the adapter's oracle. Equivalence\n * is on resolved render output, so a re-export that renders identically to the\n * source for every probe is lossless — regardless of how the files were renormalised.\n */\nexport const runRoundTrip = <Files, Input extends { resources: Files }>(\n  adapter: FormatAdapter<Files, Input>,\n  oracle: RenderOracle<Files>,\n  input: Input\n): RoundTripReport<Files> => {\n  const canonical = adapter.parse(input);\n  const exported = adapter.export(canonical);\n  const source = input.resources;\n  const { language } = canonical;\n\n  const vectors = oracle.vectors(canonical);\n  const mismatches: RoundTripMismatch[] = [];\n  for (const v of vectors) {\n    const fromSource = oracle.render(source, v, language);\n    const fromExported = oracle.render(exported, v, language);\n    const m: RoundTripMismatch = {\n      // category is spread first (conditional key) so the remaining literal keys\n      // form a single sorted run; it never collides with the keys below.\n      ...(v.category !== undefined && v.category !== \"\"\n        ? { category: v.category }\n        : {}),\n      args: v.args,\n      base: v.key.base,\n      context: v.context,\n      fromExported,\n      fromSource,\n      kind: v.kind,\n      namespace: v.key.namespace,\n    };\n    // The model built this vector from the SOURCE, so the source MUST resolve it.\n    // If it doesn't, the harness — not the export — is broken; surface it instead\n    // of letting undefined === undefined read as a (false) match.\n    if (fromSource === undefined) {\n      mismatches.push({\n        ...m,\n        note: \"source did not resolve a vector the model produced\",\n      });\n    } else if (fromSource !== fromExported) {\n      mismatches.push(m);\n    }\n  }\n\n  return {\n    canonical,\n    exported,\n    language,\n    mismatches,\n    vectorCount: vectors.length,\n    verdict: mismatches.length === 0 ? \"lossless\" : \"mismatch\",\n  };\n};\n\n/** Format a non-lossless report into a human-readable failure message. */\nexport const formatMismatches = (report: RoundTripReport): string =>\n  report.mismatches\n    .slice(0, 5)\n    .map(\n      (m) =>\n        `  ${m.namespace}:${m.base} ctx=\"${m.context}\" ${m.kind}${\n          m.category !== undefined && m.category !== \"\" ? `/${m.category}` : \"\"\n        }: source=${JSON.stringify(m.fromSource)} exported=${JSON.stringify(m.fromExported)}`\n    )\n    .join(\"\\n\");\n"],"mappings":";;;;;;AAwFA,MAAa,gBACX,SACA,QACA,UAC2B;CAC3B,MAAM,YAAY,QAAQ,MAAM,KAAK;CACrC,MAAM,WAAW,QAAQ,OAAO,SAAS;CACzC,MAAM,SAAS,MAAM;CACrB,MAAM,EAAE,aAAa;CAErB,MAAM,UAAU,OAAO,QAAQ,SAAS;CACxC,MAAM,aAAkC,CAAC;CACzC,KAAK,MAAM,KAAK,SAAS;EACvB,MAAM,aAAa,OAAO,OAAO,QAAQ,GAAG,QAAQ;EACpD,MAAM,eAAe,OAAO,OAAO,UAAU,GAAG,QAAQ;EACxD,MAAM,IAAuB;GAG3B,GAAI,EAAE,aAAa,KAAA,KAAa,EAAE,aAAa,KAC3C,EAAE,UAAU,EAAE,SAAS,IACvB,CAAC;GACL,MAAM,EAAE;GACR,MAAM,EAAE,IAAI;GACZ,SAAS,EAAE;GACX;GACA;GACA,MAAM,EAAE;GACR,WAAW,EAAE,IAAI;EACnB;EAIA,IAAI,eAAe,KAAA,GACjB,WAAW,KAAK;GACd,GAAG;GACH,MAAM;EACR,CAAC;OACI,IAAI,eAAe,cACxB,WAAW,KAAK,CAAC;CAErB;CAEA,OAAO;EACL;EACA;EACA;EACA;EACA,aAAa,QAAQ;EACrB,SAAS,WAAW,WAAW,IAAI,aAAa;CAClD;AACF;;AAGA,MAAa,oBAAoB,WAC/B,OAAO,WACJ,MAAM,GAAG,CAAC,CAAC,CACX,KACE,MACC,KAAK,EAAE,UAAU,GAAG,EAAE,KAAK,QAAQ,EAAE,QAAQ,IAAI,EAAE,OACjD,EAAE,aAAa,KAAA,KAAa,EAAE,aAAa,KAAK,IAAI,EAAE,aAAa,GACpE,WAAW,KAAK,UAAU,EAAE,UAAU,EAAE,YAAY,KAAK,UAAU,EAAE,YAAY,GACtF,CAAC,CACA,KAAK,IAAI"}

package/dist/index.d.ts

@@ -0,0 +1,98 @@
+import { a as PluralKind, c as ValueToken, i as Key, l as keyId, n as CLDRCategory, o as PluralSet, r as CanonicalModel, s as Value, t as ALL_CLDR_CATEGORIES } from "./model-5mrSQGoC.js";
+import { LanguagePlurals, PluralRule, SUPPORTED_LANGUAGES, allCategoriesFor, categoriesFor, getPlurals, isSupportedLanguage, operands, primarySubtag, representativeCount, selectCategory } from "./cldr.js";
+
+//#region src/errors.d.ts
+/**
+ * The base error type. `AstilbaError` is the one class consumers catch
+ * (`if (e instanceof AstilbaError) e.code`); `code` is an OPEN string so each
+ * format adapter owns its own code constants without a closed core enum coupling
+ * core to any one syntax. The i18next-v4 codes + their loud, fix-it-yourself
+ * factory functions live with the adapter (errors-i18next.ts).
+ */
+/** An error code is an open string; adapters define their own (e.g. `ICU_NOT_SUPPORTED`). */
+type AstilbaErrorCode = string;
+declare class AstilbaError extends Error {
+  readonly code: string;
+  /** The fully-qualified key (`namespace:flatKey`) the problem was found at, if any. */
+  readonly key?: string;
+  readonly details?: Record<string, unknown>;
+  constructor(code: string, message: string, opts?: {
+    key?: string;
+    details?: Record<string, unknown>;
+  });
+}
+//#endregion
+//#region src/mask.d.ts
+declare const sentinel: (index: number) => string;
+/**
+ * Turns a raw value string into canonical tokens. Supplied by whichever syntax
+ * adapter is in use — the one syntax-specific dependency the string-entry validator
+ * needs, to re-tokenize an MT-returned translation that was never in the model.
+ */
+type Tokenizer = (raw: string) => ValueToken[];
+interface MaskResult {
+  masked: string;
+  /** original token raws, indexed by sentinel number */
+  parts: string[];
+}
+/**
+ * Replace interpolation / nesting / markup tokens with sentinels. Rejects loudly
+ * if the literal text already contains a reserved sentinel delimiter — rare but
+ * legal in real values (e.g. private-use-area glyphs from icon fonts like Material
+ * Icons / Nerd Fonts) — rather than letting unmask() silently corrupt it.
+ */
+declare const maskTokens: (tokens: ValueToken[]) => MaskResult;
+declare const unmask: (masked: string, parts: string[]) => string;
+interface SentinelCheck {
+  ok: boolean;
+  errors: string[];
+}
+/**
+ * Validate that an MT engine returned every sentinel exactly once, unmodified,
+ * and invented none. Reordering is allowed (target languages reorder freely);
+ * pass `requireOrder` to also assert original order.
+ */
+declare const validateSentinels: (translated: string, parts: string[], opts?: {
+  requireOrder?: boolean;
+}) => SentinelCheck;
+interface PlaceholderCheck {
+  ok: boolean;
+  errors: string[];
+}
+/**
+ * Compare a source value's tokens against its translation's tokens. Fails closed:
+ * any added, dropped, or modified placeholder/markup is an error. Catches a
+ * translated variable name, a translated formatter keyword, a mangled `$t()` ref,
+ * or a dropped tag — the exact placeholder-corruption failure mode this guards.
+ */
+declare const validatePlaceholderTokens: (source: ValueToken[], translated: ValueToken[]) => PlaceholderCheck;
+/**
+ * String-entry placeholder validator: tokenizes both sides with the supplied
+ * (syntax-specific) `tokenize` and defers to {@link validatePlaceholderTokens}.
+ * The free-utility CI check — the adapter pre-binds its tokenizer so callers get
+ * the ergonomic two-argument form.
+ */
+declare const validatePlaceholders: (source: string, translated: string, tokenize: Tokenizer) => PlaceholderCheck;
+/** The actual tokens that differ between source and translation. */
+interface PlaceholderDiff {
+  /** placeholders in `source` that the translation dropped (or has fewer of) */
+  dropped: ValueToken[];
+  /** placeholders the translation introduced that `source` did not have */
+  added: ValueToken[];
+}
+/**
+ * The structured placeholder diff: the tokens dropped from / added to a
+ * translation relative to its source. Shares {@link validatePlaceholderTokens}'s
+ * identity rule — both go through the same {@link signature}, so the diff is
+ * empty exactly when that validator reports `ok` — but returns the tokens so a
+ * caller can render a precise report and decide whether a dropped+added pair is
+ * an unambiguous "changed" or must be listed separately.
+ *
+ * @param source canonical tokens of the source value
+ * @param translated canonical tokens of the translation
+ * @returns dropped and added tokens; both empty ⇔ placeholders are preserved
+ */
+declare const placeholderDiff: (source: ValueToken[], translated: ValueToken[]) => PlaceholderDiff;
+//#endregion
+export { ALL_CLDR_CATEGORIES, AstilbaError, type AstilbaErrorCode, type CLDRCategory, type CanonicalModel, type Key, type LanguagePlurals, type MaskResult, type PlaceholderCheck, type PlaceholderDiff, type PluralKind, type PluralRule, type PluralSet, SUPPORTED_LANGUAGES, type SentinelCheck, type Tokenizer, type Value, type ValueToken, allCategoriesFor, categoriesFor, getPlurals, isSupportedLanguage, keyId, maskTokens, operands, placeholderDiff, primarySubtag, representativeCount, selectCategory, sentinel, unmask, validatePlaceholderTokens, validatePlaceholders, validateSentinels };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,202 @@
+import { SUPPORTED_LANGUAGES, allCategoriesFor, categoriesFor, getPlurals, isSupportedLanguage, operands, primarySubtag, representativeCount, selectCategory } from "./cldr.js";
+//#region src/model.ts
+const ALL_CLDR_CATEGORIES = [
+	"zero",
+	"one",
+	"two",
+	"few",
+	"many",
+	"other"
+];
+const keyId = (namespace, base) => `${namespace}:${base}`;
+//#endregion
+//#region src/errors.ts
+var AstilbaError = class extends Error {
+	code;
+	/** The fully-qualified key (`namespace:flatKey`) the problem was found at, if any. */
+	key;
+	details;
+	constructor(code, message, opts = {}) {
+		super(message);
+		this.name = "AstilbaError";
+		this.code = code;
+		this.key = opts.key;
+		this.details = opts.details;
+	}
+};
+//#endregion
+//#region src/mask.ts
+/**
+* MT masking & placeholder validation — the FORMAT-NEUTRAL core. It operates on
+* canonical `ValueToken[]` (which the model
+* already carries) instead of parsing strings itself: a syntax adapter tokenizes,
+* core masks and validates. The one place a raw string must be re-tokenized is a
+* translation returned from MT — it isn't in the model — so the string-entry
+* `validatePlaceholders` takes the adapter's `Tokenizer` by injection.
+*
+* Two jobs:
+*  1. maskTokens()/unmask(): replace every non-text token (the WHOLE token, incl.
+*     formatter and `$t()` ref name) with an opaque sentinel before an MT/LLM call,
+*     and restore it after. Because the formatter keyword and ref live INSIDE the
+*     masked span, MT never sees them — that alone defeats the "translated
+*     `one`/`other` -> `uno`/`otros`" class of bug.
+*  2. validatePlaceholderTokens(): a fail-closed, CI-failable check comparing a
+*     source value's tokens against its translation's tokens (the caller restores
+*     any masked sentinels first) — every interpolation variable, formatter
+*     keyword, nesting ref, and markup tag must survive unmodified. This is the
+*     validator shipped in the free utility.
+*
+* Sentinels use private-use-area delimiters so they carry no linguistic content
+* for an MT engine to "helpfully" translate, while still being detectable if the
+* engine mangles them.
+*/
+const OPEN = "";
+const CLOSE = "";
+const sentinel = (index) => `${OPEN}${index}${CLOSE}`;
+const SENTINEL_RE = new RegExp(`${OPEN}(\\d+)${CLOSE}`, "gu");
+/**
+* Replace interpolation / nesting / markup tokens with sentinels. Rejects loudly
+* if the literal text already contains a reserved sentinel delimiter — rare but
+* legal in real values (e.g. private-use-area glyphs from icon fonts like Material
+* Icons / Nerd Fonts) — rather than letting unmask() silently corrupt it.
+*/
+const maskTokens = (tokens) => {
+	const parts = [];
+	let masked = "";
+	for (const tok of tokens) if (tok.type === "text") {
+		if (tok.raw.includes(OPEN) || tok.raw.includes(CLOSE)) throw new AstilbaError("MASK_VALIDATION", "Value text contains a reserved masking sentinel delimiter (U+E000/U+E001); it cannot be masked without ambiguity. Strip or escape these private-use-area characters before masking.");
+		masked += tok.raw;
+	} else {
+		masked += sentinel(parts.length);
+		parts.push(tok.raw);
+	}
+	return {
+		masked,
+		parts
+	};
+};
+const unmask = (masked, parts) => masked.replace(SENTINEL_RE, (_, n) => {
+	const part = parts[Number(n)];
+	if (part === void 0) throw new AstilbaError("MASK_VALIDATION", `Unknown sentinel index ${n} during unmask.`);
+	return part;
+});
+/**
+* Validate that an MT engine returned every sentinel exactly once, unmodified,
+* and invented none. Reordering is allowed (target languages reorder freely);
+* pass `requireOrder` to also assert original order.
+*/
+const validateSentinels = (translated, parts, opts = {}) => {
+	const errors = [];
+	const seen = /* @__PURE__ */ new Map();
+	const order = [];
+	let m;
+	SENTINEL_RE.lastIndex = 0;
+	while ((m = SENTINEL_RE.exec(translated)) !== null) {
+		const idx = Number(m[1]);
+		seen.set(idx, (seen.get(idx) ?? 0) + 1);
+		order.push(idx);
+	}
+	for (let i = 0; i < parts.length; i += 1) {
+		const count = seen.get(i) ?? 0;
+		if (count === 0) errors.push(`placeholder #${i} (${parts[i]}) was dropped by MT`);
+		else if (count > 1) errors.push(`placeholder #${i} (${parts[i]}) was duplicated by MT`);
+	}
+	for (const idx of seen.keys()) if (idx >= parts.length) errors.push(`MT invented an unknown placeholder #${idx}`);
+	const stripped = translated.replace(SENTINEL_RE, "");
+	if (stripped.includes(OPEN) || stripped.includes(CLOSE)) errors.push("MT corrupted a placeholder sentinel (stray delimiter found)");
+	if (opts.requireOrder === true) {
+		const expected = [...order].toSorted((a, b) => a - b);
+		if (order.join(",") !== expected.join(",")) errors.push("placeholder order was changed");
+	}
+	return {
+		errors,
+		ok: errors.length === 0
+	};
+};
+const esc = (s) => s.replaceAll("\\", "\\\\").replaceAll("|", "\\|");
+/**
+* Canonical identity for placeholder equality, computed from the `ValueToken`
+* fields directly — variable + format for interpolation, ref for nesting, raw for
+* markup. No syntax-specific normalisation: a value and its own translation carry
+* byte-identical placeholders, so the raw canonical fields ARE the faithful
+* identity (an adapter wanting looser matching can pre-normalise its tokens before
+* calling `validatePlaceholderTokens`). Returns `null` for text (not a placeholder).
+*/
+const signature = (tok) => {
+	switch (tok.type) {
+		case "interpolation": return `interp:${esc(tok.variable)}|${esc(tok.format ?? "")}`;
+		case "nesting": return `nest:${esc(tok.ref)}|${esc(tok.options ?? "")}`;
+		case "markup": return `markup:${tok.raw}`;
+		case "text": return null;
+		default: return tok;
+	}
+};
+const bySignature = (tokens) => {
+	const groups = /* @__PURE__ */ new Map();
+	for (const tok of tokens) {
+		const sig = signature(tok);
+		if (sig === null) continue;
+		const arr = groups.get(sig);
+		if (arr) arr.push(tok);
+		else groups.set(sig, [tok]);
+	}
+	return groups;
+};
+/**
+* Compare a source value's tokens against its translation's tokens. Fails closed:
+* any added, dropped, or modified placeholder/markup is an error. Catches a
+* translated variable name, a translated formatter keyword, a mangled `$t()` ref,
+* or a dropped tag — the exact placeholder-corruption failure mode this guards.
+*/
+const validatePlaceholderTokens = (source, translated) => {
+	const src = bySignature(source);
+	const dst = bySignature(translated);
+	const errors = [];
+	for (const [sig, toks] of src) if ((dst.get(sig)?.length ?? 0) < toks.length) errors.push(`source placeholder "${sig}" is missing or altered in the translation`);
+	for (const [sig, toks] of dst) if (toks.length > (src.get(sig)?.length ?? 0)) errors.push(`translation introduced an unexpected placeholder "${sig}"`);
+	return {
+		errors,
+		ok: errors.length === 0
+	};
+};
+/**
+* String-entry placeholder validator: tokenizes both sides with the supplied
+* (syntax-specific) `tokenize` and defers to {@link validatePlaceholderTokens}.
+* The free-utility CI check — the adapter pre-binds its tokenizer so callers get
+* the ergonomic two-argument form.
+*/
+const validatePlaceholders = (source, translated, tokenize) => validatePlaceholderTokens(tokenize(source), tokenize(translated));
+/**
+* The structured placeholder diff: the tokens dropped from / added to a
+* translation relative to its source. Shares {@link validatePlaceholderTokens}'s
+* identity rule — both go through the same {@link signature}, so the diff is
+* empty exactly when that validator reports `ok` — but returns the tokens so a
+* caller can render a precise report and decide whether a dropped+added pair is
+* an unambiguous "changed" or must be listed separately.
+*
+* @param source canonical tokens of the source value
+* @param translated canonical tokens of the translation
+* @returns dropped and added tokens; both empty ⇔ placeholders are preserved
+*/
+const placeholderDiff = (source, translated) => {
+	const src = bySignature(source);
+	const dst = bySignature(translated);
+	const dropped = [];
+	const added = [];
+	for (const [sig, toks] of src) {
+		const have = dst.get(sig)?.length ?? 0;
+		for (let i = have; i < toks.length; i += 1) dropped.push(toks[i]);
+	}
+	for (const [sig, toks] of dst) {
+		const have = src.get(sig)?.length ?? 0;
+		for (let i = have; i < toks.length; i += 1) added.push(toks[i]);
+	}
+	return {
+		added,
+		dropped
+	};
+};
+//#endregion
+export { ALL_CLDR_CATEGORIES, AstilbaError, SUPPORTED_LANGUAGES, allCategoriesFor, categoriesFor, getPlurals, isSupportedLanguage, keyId, maskTokens, operands, placeholderDiff, primarySubtag, representativeCount, selectCategory, sentinel, unmask, validatePlaceholderTokens, validatePlaceholders, validateSentinels };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/model.ts","../src/errors.ts","../src/mask.ts"],"sourcesContent":["/**\n * The canonical message model.\n *\n * This is the format-agnostic centre of Astilba: every file/syntax adapter maps\n * files <-> this model. Phase 0 ships one adapter (native i18next v4) but the\n * model is deliberately syntax-neutral so ICU and other dialects can map onto it\n * later without changing it.\n *\n * Invariants worth stating out loud:\n *  - Value text is preserved EXACTLY (never mutate value bytes). `Value.raw` is\n *    the source of truth; `Value.tokens` is a derived view\n *    used only for masking/analysis and is never used to reconstruct output.\n *  - Plurals are represented STRUCTURALLY as a CLDR-category -> value map, not as\n *    suffixed flat keys. The suffix set is re-derived per target language on\n *    export, never carried through.\n */\n\n/** The six CLDR plural categories. The set that actually applies is language-dependent. */\nexport type CLDRCategory = \"zero\" | \"one\" | \"two\" | \"few\" | \"many\" | \"other\";\n\nexport const ALL_CLDR_CATEGORIES: readonly CLDRCategory[] = [\n  \"zero\",\n  \"one\",\n  \"two\",\n  \"few\",\n  \"many\",\n  \"other\",\n];\n\n/**\n * Whether a key is pluralised, and if so how.\n *  - \"none\"     -> a plain string; no plural suffix on export.\n *  - \"cardinal\" -> `_one`, `_other`, ... suffixes.\n *  - \"ordinal\"  -> `_ordinal_one`, ... suffixes (i18next v4 ordinal form).\n *\n * Note \"none\" is distinct from a single-category cardinal (e.g. Japanese, whose\n * only category is `other`): `foo` (none) and `foo_other` (cardinal) are\n * different keys and must round-trip differently.\n */\nexport type PluralKind = \"none\" | \"cardinal\" | \"ordinal\";\n\n/** A token within a value. Derived from `Value.raw`; used for masking + validation. */\nexport type ValueToken =\n  | { type: \"text\"; raw: string }\n  /** `{{var}}`, `{{var, format}}`, `{{var, format(options)}}` */\n  | {\n      type: \"interpolation\";\n      raw: string;\n      variable: string;\n      format?: string;\n    }\n  /** `$t(ref)`, `$t(ref, {\"opt\": ...})` */\n  | {\n      type: \"nesting\";\n      raw: string;\n      ref: string;\n      options?: string;\n    }\n  /** an HTML/XML tag `<...>` or an entity `&...;` — opaque markup */\n  | { type: \"markup\"; raw: string };\n\n/**\n * A translatable value. `raw` is byte-exact source; `tokens` is the parsed view.\n * `tokens.map(t => t.raw).join(\"\")` always reconstructs `raw` exactly.\n */\nexport interface Value {\n  raw: string;\n  tokens: ValueToken[];\n}\n\n/**\n * The set of values for one (base, context) cell.\n *\n *  - kind \"none\":     `values` holds a single \"other\" entry = the plain string.\n *  - kind \"cardinal\"/\"ordinal\": `values` holds the per-category plural forms.\n *  - `bare`: present only in the rare i18next case where a context key has BOTH\n *    a suffix-less form (used when `t()` is called without `count`) AND plural\n *    forms (used when `count` is given). Kept so both render paths are lossless.\n */\nexport interface PluralSet {\n  kind: PluralKind;\n  values: Map<CLDRCategory, Value>;\n  bare?: Value;\n}\n\n/**\n * A logical message: a base key with one entry per context value.\n * The no-context case is a single entry keyed \"\" (empty string).\n *\n * `base` is the full key path WITHOUT namespace and WITHOUT plural/context\n * suffixes, using the project key separator (default \".\"), e.g. `account.friend`.\n */\nexport interface Key {\n  namespace: string;\n  base: string;\n  /** contextValue -> its PluralSet. \"\" === no context. */\n  contexts: Map<string, PluralSet>;\n}\n\n/**\n * A single language's worth of canonical data. Round-trip is per-language.\n *\n * IN-MEMORY ONLY: this is `Map`-based for fast lookup, so it is NOT directly\n * JSON-serializable (`JSON.stringify` yields `{}` for the Maps). A persistence/\n * transport DTO (plain objects or a `toJSON`/`fromJSON` pair) is a v1.0 item,\n * needed once the backend stores or ships the model.\n */\nexport interface CanonicalModel {\n  /** BCP-47, e.g. `en`, `en-US`, `pt-BR`. */\n  language: string;\n  /** `${namespace}:${base}` -> Key */\n  keys: Map<string, Key>;\n}\n\nexport const keyId = (namespace: string, base: string): string =>\n  `${namespace}:${base}`;\n","/**\n * The base error type. `AstilbaError` is the one class consumers catch\n * (`if (e instanceof AstilbaError) e.code`); `code` is an OPEN string so each\n * format adapter owns its own code constants without a closed core enum coupling\n * core to any one syntax. The i18next-v4 codes + their loud, fix-it-yourself\n * factory functions live with the adapter (errors-i18next.ts).\n */\n\n/** An error code is an open string; adapters define their own (e.g. `ICU_NOT_SUPPORTED`). */\nexport type AstilbaErrorCode = string;\n\nexport class AstilbaError extends Error {\n  readonly code: string;\n  /** The fully-qualified key (`namespace:flatKey`) the problem was found at, if any. */\n  readonly key?: string;\n  readonly details?: Record<string, unknown>;\n\n  constructor(\n    code: string,\n    message: string,\n    opts: { key?: string; details?: Record<string, unknown> } = {}\n  ) {\n    super(message);\n    this.name = \"AstilbaError\";\n    this.code = code;\n    this.key = opts.key;\n    this.details = opts.details;\n  }\n}\n","/**\n * MT masking & placeholder validation — the FORMAT-NEUTRAL core. It operates on\n * canonical `ValueToken[]` (which the model\n * already carries) instead of parsing strings itself: a syntax adapter tokenizes,\n * core masks and validates. The one place a raw string must be re-tokenized is a\n * translation returned from MT — it isn't in the model — so the string-entry\n * `validatePlaceholders` takes the adapter's `Tokenizer` by injection.\n *\n * Two jobs:\n *  1. maskTokens()/unmask(): replace every non-text token (the WHOLE token, incl.\n *     formatter and `$t()` ref name) with an opaque sentinel before an MT/LLM call,\n *     and restore it after. Because the formatter keyword and ref live INSIDE the\n *     masked span, MT never sees them — that alone defeats the \"translated\n *     `one`/`other` -> `uno`/`otros`\" class of bug.\n *  2. validatePlaceholderTokens(): a fail-closed, CI-failable check comparing a\n *     source value's tokens against its translation's tokens (the caller restores\n *     any masked sentinels first) — every interpolation variable, formatter\n *     keyword, nesting ref, and markup tag must survive unmodified. This is the\n *     validator shipped in the free utility.\n *\n * Sentinels use private-use-area delimiters so they carry no linguistic content\n * for an MT engine to \"helpfully\" translate, while still being detectable if the\n * engine mangles them.\n */\n\nimport { AstilbaError } from \"./errors.ts\";\nimport type { ValueToken } from \"./model.ts\";\n\nconst OPEN = \"\\uE000\";\nconst CLOSE = \"\\uE001\";\n\nexport const sentinel = (index: number): string => `${OPEN}${index}${CLOSE}`;\n\nconst SENTINEL_RE = new RegExp(`${OPEN}(\\\\d+)${CLOSE}`, \"gu\");\n\n/**\n * Turns a raw value string into canonical tokens. Supplied by whichever syntax\n * adapter is in use — the one syntax-specific dependency the string-entry validator\n * needs, to re-tokenize an MT-returned translation that was never in the model.\n */\nexport type Tokenizer = (raw: string) => ValueToken[];\n\nexport interface MaskResult {\n  masked: string;\n  /** original token raws, indexed by sentinel number */\n  parts: string[];\n}\n\n/**\n * Replace interpolation / nesting / markup tokens with sentinels. Rejects loudly\n * if the literal text already contains a reserved sentinel delimiter — rare but\n * legal in real values (e.g. private-use-area glyphs from icon fonts like Material\n * Icons / Nerd Fonts) — rather than letting unmask() silently corrupt it.\n */\nexport const maskTokens = (tokens: ValueToken[]): MaskResult => {\n  const parts: string[] = [];\n  let masked = \"\";\n  for (const tok of tokens) {\n    if (tok.type === \"text\") {\n      if (tok.raw.includes(OPEN) || tok.raw.includes(CLOSE)) {\n        throw new AstilbaError(\n          \"MASK_VALIDATION\",\n          \"Value text contains a reserved masking sentinel delimiter \" +\n            \"(U+E000/U+E001); it cannot be masked without ambiguity. Strip or \" +\n            \"escape these private-use-area characters before masking.\"\n        );\n      }\n      masked += tok.raw;\n    } else {\n      masked += sentinel(parts.length);\n      parts.push(tok.raw);\n    }\n  }\n  return { masked, parts };\n};\n\nexport const unmask = (masked: string, parts: string[]): string =>\n  masked.replace(SENTINEL_RE, (_, n: string) => {\n    const part = parts[Number(n)];\n    if (part === undefined) {\n      throw new AstilbaError(\n        \"MASK_VALIDATION\",\n        `Unknown sentinel index ${n} during unmask.`\n      );\n    }\n    return part;\n  });\n\nexport interface SentinelCheck {\n  ok: boolean;\n  errors: string[];\n}\n\n/**\n * Validate that an MT engine returned every sentinel exactly once, unmodified,\n * and invented none. Reordering is allowed (target languages reorder freely);\n * pass `requireOrder` to also assert original order.\n */\nexport const validateSentinels = (\n  translated: string,\n  parts: string[],\n  opts: { requireOrder?: boolean } = {}\n): SentinelCheck => {\n  const errors: string[] = [];\n  const seen = new Map<number, number>();\n  const order: number[] = [];\n  let m: RegExpExecArray | null;\n  SENTINEL_RE.lastIndex = 0;\n  while ((m = SENTINEL_RE.exec(translated)) !== null) {\n    const idx = Number(m[1]);\n    seen.set(idx, (seen.get(idx) ?? 0) + 1);\n    order.push(idx);\n  }\n\n  for (let i = 0; i < parts.length; i += 1) {\n    const count = seen.get(i) ?? 0;\n    if (count === 0) {\n      errors.push(`placeholder #${i} (${parts[i]}) was dropped by MT`);\n    } else if (count > 1) {\n      errors.push(`placeholder #${i} (${parts[i]}) was duplicated by MT`);\n    }\n  }\n  for (const idx of seen.keys()) {\n    if (idx >= parts.length) {\n      errors.push(`MT invented an unknown placeholder #${idx}`);\n    }\n  }\n  // Detect a corrupted sentinel: stray delimiter chars not part of a valid token.\n  const stripped = translated.replace(SENTINEL_RE, \"\");\n  if (stripped.includes(OPEN) || stripped.includes(CLOSE)) {\n    errors.push(\"MT corrupted a placeholder sentinel (stray delimiter found)\");\n  }\n  if (opts.requireOrder === true) {\n    const expected = [...order].toSorted((a, b) => a - b);\n    if (order.join(\",\") !== expected.join(\",\")) {\n      errors.push(\"placeholder order was changed\");\n    }\n  }\n\n  return { errors, ok: errors.length === 0 };\n};\n\n// --- post-hoc placeholder validation (the free-utility CI check) -------------\n\n// Escape `\\` then `|` so the `|` field separator below is unambiguous even if a\n// variable / format / ref / options string itself contains one.\nconst esc = (s: string): string =>\n  s.replaceAll(\"\\\\\", \"\\\\\\\\\").replaceAll(\"|\", \"\\\\|\");\n\n/**\n * Canonical identity for placeholder equality, computed from the `ValueToken`\n * fields directly — variable + format for interpolation, ref for nesting, raw for\n * markup. No syntax-specific normalisation: a value and its own translation carry\n * byte-identical placeholders, so the raw canonical fields ARE the faithful\n * identity (an adapter wanting looser matching can pre-normalise its tokens before\n * calling `validatePlaceholderTokens`). Returns `null` for text (not a placeholder).\n */\nconst signature = (tok: ValueToken): string | null => {\n  switch (tok.type) {\n    case \"interpolation\": {\n      return `interp:${esc(tok.variable)}|${esc(tok.format ?? \"\")}`;\n    }\n    case \"nesting\": {\n      // options are part of the placeholder's identity: $t(a, {\"count\": 3}) and\n      // $t(a, {\"count\": 0}) render differently, so a mutated option must not pass.\n      return `nest:${esc(tok.ref)}|${esc(tok.options ?? \"\")}`;\n    }\n    case \"markup\": {\n      // one field (the whole raw tag), so no separator to disambiguate — and the\n      // `markup:` prefix keeps it distinct from interp/nesting signatures.\n      return `markup:${tok.raw}`;\n    }\n    case \"text\": {\n      return null;\n    }\n    default: {\n      // Exhaustive over ValueToken: a future variant becomes a compile error here\n      // rather than silently slipping through this fail-closed validator as text.\n      return tok satisfies never;\n    }\n  }\n};\n\n// Group tokens by signature; both the validator and the diff count from this.\nconst bySignature = (tokens: ValueToken[]): Map<string, ValueToken[]> => {\n  const groups = new Map<string, ValueToken[]>();\n  for (const tok of tokens) {\n    const sig = signature(tok);\n    if (sig === null) {\n      continue;\n    }\n    const arr = groups.get(sig);\n    if (arr) {\n      arr.push(tok);\n    } else {\n      groups.set(sig, [tok]);\n    }\n  }\n  return groups;\n};\n\nexport interface PlaceholderCheck {\n  ok: boolean;\n  errors: string[];\n}\n\n/**\n * Compare a source value's tokens against its translation's tokens. Fails closed:\n * any added, dropped, or modified placeholder/markup is an error. Catches a\n * translated variable name, a translated formatter keyword, a mangled `$t()` ref,\n * or a dropped tag — the exact placeholder-corruption failure mode this guards.\n */\nexport const validatePlaceholderTokens = (\n  source: ValueToken[],\n  translated: ValueToken[]\n): PlaceholderCheck => {\n  const src = bySignature(source);\n  const dst = bySignature(translated);\n  const errors: string[] = [];\n\n  for (const [sig, toks] of src) {\n    if ((dst.get(sig)?.length ?? 0) < toks.length) {\n      errors.push(\n        `source placeholder \"${sig}\" is missing or altered in the translation`\n      );\n    }\n  }\n  for (const [sig, toks] of dst) {\n    if (toks.length > (src.get(sig)?.length ?? 0)) {\n      errors.push(`translation introduced an unexpected placeholder \"${sig}\"`);\n    }\n  }\n\n  return { errors, ok: errors.length === 0 };\n};\n\n/**\n * String-entry placeholder validator: tokenizes both sides with the supplied\n * (syntax-specific) `tokenize` and defers to {@link validatePlaceholderTokens}.\n * The free-utility CI check — the adapter pre-binds its tokenizer so callers get\n * the ergonomic two-argument form.\n */\nexport const validatePlaceholders = (\n  source: string,\n  translated: string,\n  tokenize: Tokenizer\n): PlaceholderCheck =>\n  validatePlaceholderTokens(tokenize(source), tokenize(translated));\n\n/** The actual tokens that differ between source and translation. */\nexport interface PlaceholderDiff {\n  /** placeholders in `source` that the translation dropped (or has fewer of) */\n  dropped: ValueToken[];\n  /** placeholders the translation introduced that `source` did not have */\n  added: ValueToken[];\n}\n\n/**\n * The structured placeholder diff: the tokens dropped from / added to a\n * translation relative to its source. Shares {@link validatePlaceholderTokens}'s\n * identity rule — both go through the same {@link signature}, so the diff is\n * empty exactly when that validator reports `ok` — but returns the tokens so a\n * caller can render a precise report and decide whether a dropped+added pair is\n * an unambiguous \"changed\" or must be listed separately.\n *\n * @param source canonical tokens of the source value\n * @param translated canonical tokens of the translation\n * @returns dropped and added tokens; both empty ⇔ placeholders are preserved\n */\nexport const placeholderDiff = (\n  source: ValueToken[],\n  translated: ValueToken[]\n): PlaceholderDiff => {\n  const src = bySignature(source);\n  const dst = bySignature(translated);\n  const dropped: ValueToken[] = [];\n  const added: ValueToken[] = [];\n  for (const [sig, toks] of src) {\n    const have = dst.get(sig)?.length ?? 0;\n    for (let i = have; i < toks.length; i += 1) {\n      dropped.push(toks[i]);\n    }\n  }\n  for (const [sig, toks] of dst) {\n    const have = src.get(sig)?.length ?? 0;\n    for (let i = have; i < toks.length; i += 1) {\n      added.push(toks[i]);\n    }\n  }\n  return { added, dropped };\n};\n"],"mappings":"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"}

package/dist/model-5mrSQGoC.d.ts

@@ -0,0 +1,102 @@
+//#region src/model.d.ts
+/**
+ * The canonical message model.
+ *
+ * This is the format-agnostic centre of Astilba: every file/syntax adapter maps
+ * files <-> this model. Phase 0 ships one adapter (native i18next v4) but the
+ * model is deliberately syntax-neutral so ICU and other dialects can map onto it
+ * later without changing it.
+ *
+ * Invariants worth stating out loud:
+ *  - Value text is preserved EXACTLY (never mutate value bytes). `Value.raw` is
+ *    the source of truth; `Value.tokens` is a derived view
+ *    used only for masking/analysis and is never used to reconstruct output.
+ *  - Plurals are represented STRUCTURALLY as a CLDR-category -> value map, not as
+ *    suffixed flat keys. The suffix set is re-derived per target language on
+ *    export, never carried through.
+ */
+/** The six CLDR plural categories. The set that actually applies is language-dependent. */
+type CLDRCategory = "zero" | "one" | "two" | "few" | "many" | "other";
+declare const ALL_CLDR_CATEGORIES: readonly CLDRCategory[];
+/**
+ * Whether a key is pluralised, and if so how.
+ *  - "none"     -> a plain string; no plural suffix on export.
+ *  - "cardinal" -> `_one`, `_other`, ... suffixes.
+ *  - "ordinal"  -> `_ordinal_one`, ... suffixes (i18next v4 ordinal form).
+ *
+ * Note "none" is distinct from a single-category cardinal (e.g. Japanese, whose
+ * only category is `other`): `foo` (none) and `foo_other` (cardinal) are
+ * different keys and must round-trip differently.
+ */
+type PluralKind = "none" | "cardinal" | "ordinal";
+/** A token within a value. Derived from `Value.raw`; used for masking + validation. */
+type ValueToken = {
+  type: "text";
+  raw: string;
+} /** `{{var}}`, `{{var, format}}`, `{{var, format(options)}}` */ | {
+  type: "interpolation";
+  raw: string;
+  variable: string;
+  format?: string;
+} /** `$t(ref)`, `$t(ref, {"opt": ...})` */ | {
+  type: "nesting";
+  raw: string;
+  ref: string;
+  options?: string;
+} /** an HTML/XML tag `<...>` or an entity `&...;` — opaque markup */ | {
+  type: "markup";
+  raw: string;
+};
+/**
+ * A translatable value. `raw` is byte-exact source; `tokens` is the parsed view.
+ * `tokens.map(t => t.raw).join("")` always reconstructs `raw` exactly.
+ */
+interface Value {
+  raw: string;
+  tokens: ValueToken[];
+}
+/**
+ * The set of values for one (base, context) cell.
+ *
+ *  - kind "none":     `values` holds a single "other" entry = the plain string.
+ *  - kind "cardinal"/"ordinal": `values` holds the per-category plural forms.
+ *  - `bare`: present only in the rare i18next case where a context key has BOTH
+ *    a suffix-less form (used when `t()` is called without `count`) AND plural
+ *    forms (used when `count` is given). Kept so both render paths are lossless.
+ */
+interface PluralSet {
+  kind: PluralKind;
+  values: Map<CLDRCategory, Value>;
+  bare?: Value;
+}
+/**
+ * A logical message: a base key with one entry per context value.
+ * The no-context case is a single entry keyed "" (empty string).
+ *
+ * `base` is the full key path WITHOUT namespace and WITHOUT plural/context
+ * suffixes, using the project key separator (default "."), e.g. `account.friend`.
+ */
+interface Key {
+  namespace: string;
+  base: string;
+  /** contextValue -> its PluralSet. "" === no context. */
+  contexts: Map<string, PluralSet>;
+}
+/**
+ * A single language's worth of canonical data. Round-trip is per-language.
+ *
+ * IN-MEMORY ONLY: this is `Map`-based for fast lookup, so it is NOT directly
+ * JSON-serializable (`JSON.stringify` yields `{}` for the Maps). A persistence/
+ * transport DTO (plain objects or a `toJSON`/`fromJSON` pair) is a v1.0 item,
+ * needed once the backend stores or ships the model.
+ */
+interface CanonicalModel {
+  /** BCP-47, e.g. `en`, `en-US`, `pt-BR`. */
+  language: string;
+  /** `${namespace}:${base}` -> Key */
+  keys: Map<string, Key>;
+}
+declare const keyId: (namespace: string, base: string) => string;
+//#endregion
+export { PluralKind as a, ValueToken as c, Key as i, keyId as l, CLDRCategory as n, PluralSet as o, CanonicalModel as r, Value as s, ALL_CLDR_CATEGORIES as t };
+//# sourceMappingURL=model-5mrSQGoC.d.ts.map

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@astilba/core",
+  "version": "0.1.0",
+  "description": "Format-neutral canonical i18n message model, vendored CLDR plural rules, and the round-trip message-fidelity harness (driver + FormatAdapter/RenderOracle contracts). Syntax adapters (e.g. @astilba/adapter-i18next-v4) plug in on top.",
+  "keywords": [
+    "cldr",
+    "i18n",
+    "i18next",
+    "icu",
+    "localization",
+    "tms",
+    "translation"
+  ],
+  "homepage": "https://github.com/astilbahq/astilba/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/astilbahq/astilba/issues"
+  },
+  "license": "MIT",
+  "author": "Rees Morris",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/astilbahq/astilba.git",
+    "directory": "packages/core"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./cldr": {
+      "types": "./dist/cldr.d.ts",
+      "default": "./dist/cldr.js"
+    },
+    "./harness": {
+      "types": "./dist/harness.d.ts",
+      "default": "./dist/harness.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@types/node": "^22",
+    "publint": "^0.3.0"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "test": "vp test",
+    "typecheck": "tsc --noEmit",
+    "lint:publish": "trap 'rm -f /tmp/astilba-core-*.tgz' EXIT; pnpm pack --pack-destination /tmp >/dev/null && publint --strict /tmp/astilba-core-*.tgz && attw /tmp/astilba-core-*.tgz --profile esm-only"
+  }
+}