@clossys/writer 0.3.2

package/dist/locale-coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locale-coverage.js","sourceRoot":"","sources":["../src/locale-coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoJG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAgExD,SAAS,OAAO,CACd,YAAwB,EACxB,eAA6B,EAC7B,aAA2B,EAC3B,OAA8B;IAE9B,OAAO;QACL,YAAY;QACZ,eAAe;QACf,aAAa;QACb,cAAc,EAAE,EAAE;QAClB,cAAc,EAAE,EAAE;QAClB,gBAAgB,EAAE,CAAC;QACnB,QAAQ,EAAE,CAAC,OAAO,CAAC;QACnB,QAAQ,EAAE,KAAK;KAChB,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,MAA6B;IAClD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAc,CAAC;IACnC,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACrB,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAChB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,oCAAoC,CAC3C,WAA8B,EAC9B,WAA8B,EAC9B,YAAwB,EACxB,YAAwB,EACxB,QAAiC;IAEjC,gFAAgF;IAChF,IAAI,WAAW,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QAC1C,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,oCAAoC;YAC1C,QAAQ,EAAE,SAAS;YACnB,OAAO,EAAE,UAAU,WAAW,CAAC,EAAE,gBAAgB,YAAY,oJAAoJ;YACjN,IAAI,EAAE,WAAW,CAAC,EAAE;YACpB,MAAM,EAAE,YAAY;YACpB,OAAO,EAAE,WAAW,CAAC,EAAE;SACxB,CAAC,CAAC;IACL,CAAC;SAAM,CAAC;QACN,MAAM,kBAAkB,GAAG,sBAAsB,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QACpE,IAAI,WAAW,CAAC,WAAW,CAAC,iBAAiB,KAAK,kBAAkB,EAAE,CAAC;YACrE,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,6BAA6B;gBACnC,QAAQ,EAAE,SAAS;gBACnB,OAAO,EAAE,UAAU,WAAW,CAAC,EAAE,gBAAgB,YAAY,uDAAuD,WAAW,CAAC,WAAW,CAAC,iBAAiB,yBAAyB,YAAY,qCAAqC,kBAAkB,iDAAiD;gBAC1S,IAAI,EAAE,WAAW,CAAC,EAAE;gBACpB,MAAM,EAAE,YAAY;gBACpB,OAAO,EAAE,WAAW,CAAC,EAAE;aACxB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC;IACnE,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC;IAEnE,KAAK,MAAM,IAAI,IAAI,kBAAkB,EAAE,CAAC;QACtC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAClC,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,uCAAuC;gBAC7C,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,UAAU,WAAW,CAAC,EAAE,gBAAgB,YAAY,8BAA8B,IAAI,4BAA4B,YAAY,8GAA8G;gBACrP,IAAI,EAAE,WAAW,CAAC,EAAE;gBACpB,MAAM,EAAE,YAAY;gBACpB,OAAO,EAAE,WAAW,CAAC,EAAE;aACxB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,kBAAkB,EAAE,CAAC;QACtC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAClC,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,qCAAqC;gBAC3C,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,UAAU,WAAW,CAAC,EAAE,gBAAgB,YAAY,4BAA4B,IAAI,4BAA4B,YAAY,kEAAkE,IAAI,qBAAqB;gBAChO,IAAI,EAAE,WAAW,CAAC,EAAE;gBACpB,MAAM,EAAE,YAAY;gBACpB,OAAO,EAAE,WAAW,CAAC,EAAE;aACxB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,mBAAmB,CACjC,UAAiD,EACjD,YAAwB,EACxB,eAAsC;IAEtC,MAAM,QAAQ,GAAG,aAAa,CAAC,eAAe,CAAC,CAAC;IAChD,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,KAAK,YAAY,CAAC,CAAC;IAE3E,6EAA6E;IAC7E,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,OAAO,CAAC,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE;YACpD,IAAI,EAAE,qCAAqC;YAC3C,QAAQ,EAAE,OAAO;YACjB,OAAO,EACL,+KAA+K;SAClL,CAAC,CAAC;IACL,CAAC;IAED,6EAA6E;IAC7E,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;QACrC,OAAO,OAAO,CAAC,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE;YACpD,IAAI,EAAE,4CAA4C;YAClD,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,iBAAiB,YAAY,wCAAwC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,SAAS,4EAA4E;YAC1L,MAAM,EAAE,YAAY;SACrB,CAAC,CAAC;IACL,CAAC;IAED,0EAA0E;IAC1E,MAAM,eAAe,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAChD,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,OAAO,OAAO,CAAC,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE;YACpD,IAAI,EAAE,+BAA+B;YACrC,QAAQ,EAAE,OAAO;YACjB,OAAO,EACL,kHAAkH;SACrH,CAAC,CAAC;IACL,CAAC;IAED,6EAA6E;IAC7E,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,YAAY,CAAC,EAAE,CAAC;QAC7C,OAAO,OAAO,CAAC,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE;YACpD,IAAI,EAAE,uCAAuC;YAC7C,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,iBAAiB,YAAY,2HAA2H;YACjK,MAAM,EAAE,YAAY;SACrB,CAAC,CAAC;IACL,CAAC;IAED,4EAA4E;IAC5E,MAAM,eAAe,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC;IACjD,MAAM,mBAAmB,GAAG,yBAAyB,CAAC,eAAe,CAAC,CAAC;IACvE,IAAI,mBAAmB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,QAAQ,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChG,OAAO,OAAO,CAAC,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE;YACpD,IAAI,EAAE,yCAAyC;YAC/C,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,mCAAmC,YAAY,kCAAkC,MAAM,EAAE;YAClG,MAAM,EAAE,YAAY;SACrB,CAAC,CAAC;IACL,CAAC;IACD,MAAM,cAAc,GAAG,eAA+B,CAAC;IAEvD,uFAAuF;IACvF,IAAI,cAAc,CAAC,MAAM,KAAK,YAAY,EAAE,CAAC;QAC3C,OAAO,OAAO,CAAC,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE;YACpD,IAAI,EAAE,iDAAiD;YACvD,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,2CAA2C,YAAY,sBAAsB,cAAc,CAAC,MAAM,oIAAoI;YAC/O,MAAM,EAAE,YAAY;SACrB,CAAC,CAAC;IACL,CAAC;IAED,6EAA6E;IAC7E,IAAI,cAAc,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxC,OAAO,OAAO,CAAC,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE;YACpD,IAAI,EAAE,qCAAqC;YAC3C,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,kBAAkB,YAAY,sJAAsJ;YAC7L,MAAM,EAAE,YAAY;SACrB,CAAC,CAAC;IACL,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3E,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAC7C,MAAM,cAAc,GAAiB,EAAE,CAAC;IACxC,MAAM,cAAc,GAAyB,EAAE,CAAC;IAEhD,KAAK,MAAM,MAAM,IAAI,aAAa,EAAE,CAAC;QACnC,yEAAyE;QACzE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,EAAE,CAAC;YACvC,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,uBAAuB,EAAE,CAAC,CAAC;YACjE,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,uCAAuC;gBAC7C,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,WAAW,MAAM,4KAA4K;gBACtM,MAAM;aACP,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,MAAM,eAAe,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;QAC3C,MAAM,mBAAmB,GAAG,yBAAyB,CAAC,eAAe,CAAC,CAAC;QACvE,IAAI,mBAAmB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACnC,MAAM,MAAM,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,QAAQ,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAChG,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,yBAAyB,EAAE,CAAC,CAAC;YACnE,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,yCAAyC;gBAC/C,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,4BAA4B,MAAM,wEAAwE,MAAM,EAAE;gBAC3H,MAAM;aACP,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,MAAM,cAAc,GAAG,eAA+B,CAAC;QAEvD,IAAI,cAAc,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YACrC,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,iCAAiC,EAAE,CAAC,CAAC;YAC3E,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,iDAAiD;gBACvD,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,oCAAoC,MAAM,sBAAsB,cAAc,CAAC,MAAM,4GAA4G;gBAC1M,MAAM;aACP,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,yEAAyE;QACzE,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC5B,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;QAErF,KAAK,MAAM,KAAK,IAAI,cAAc,CAAC,OAAO,EAAE,CAAC;YAC3C,MAAM,WAAW,GAAG,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAC7C,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjB,QAAQ,CAAC,IAAI,CAAC;oBACZ,IAAI,EAAE,+BAA+B;oBACrC,QAAQ,EAAE,OAAO;oBACjB,OAAO,EAAE,UAAU,KAAK,CAAC,EAAE,8BAA8B,YAAY,uCAAuC,MAAM,IAAI;oBACtH,IAAI,EAAE,KAAK,CAAC,EAAE;oBACd,MAAM;oBACN,OAAO,EAAE,KAAK,CAAC,EAAE;iBAClB,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YACD,kEAAkE;YAClE,gEAAgE;YAChE,+DAA+D;YAC/D,0DAA0D;YAC1D,oCAAoC,CAAC,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;QAC3F,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,cAAc,CAAC,OAAO,EAAE,CAAC;YAC3C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;gBAC7B,QAAQ,CAAC,IAAI,CAAC;oBACZ,IAAI,EAAE,gCAAgC;oBACtC,QAAQ,EAAE,SAAS;oBACnB,OAAO,EAAE,UAAU,KAAK,CAAC,EAAE,uBAAuB,MAAM,8CAA8C,YAAY,6DAA6D;oBAC/K,IAAI,EAAE,KAAK,CAAC,EAAE;oBACd,MAAM;oBACN,OAAO,EAAE,KAAK,CAAC,EAAE;iBAClB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,YAAY;QACZ,eAAe,EAAE,QAAQ;QACzB,aAAa;QACb,cAAc;QACd,cAAc;QACd,gBAAgB,EAAE,cAAc,CAAC,OAAO,CAAC,MAAM;QAC/C,QAAQ;QACR,QAAQ,EAAE,cAAc,CAAC,MAAM,KAAK,CAAC;KACtC,CAAC;AACJ,CAAC"}

package/dist/passage.d.ts

@@ -0,0 +1,294 @@
+/**
+ * The PASSAGE LAYER — issue #373. `@example/copy` (now `writer`,
+ * per issue #373's own retargeting comment) has terms (a glossary) and
+ * entries (single addressable strings) and nothing between them.
+ * `@clossys/designer` has tokens, atoms, AND BLOCKS. This file is the
+ * missing middle: a `Passage` composes `CopyEntry`/glossary-term
+ * REFERENCES the way a block composes atoms — never a raw sentence of its
+ * own. Terms ≈ tokens, entries ≈ atoms, passages ≈ blocks, documents (a
+ * later, composition-layer concern, out of scope here — see the issue)
+ * ≈ views.
+ *
+ * WHERE THE MIRROR STOPS. This file deliberately does NOT port
+ * `@clossys/designer/tokens`' `brandable` boolean onto a `Passage`
+ * field. In tokens, `brandable` marks a subset WITHIN one namespace (154
+ * ship, 42 are brandable). The voice record's own consumer/machinery
+ * split runs between FILES instead (a consumer's own `VoiceRecord` vs.
+ * this package's shipped machinery) — forcing a boolean into a field here
+ * would be false symmetry with a split that does not exist at this
+ * layer. This file mirrors the LADDER (structure: terms/entries/passages/
+ * documents), not the binding mechanism.
+ *
+ * ============================================================================
+ * WHAT A `Passage` IS
+ * ============================================================================
+ *
+ * One reusable, addressable unit of composed language — an empty-state
+ * (title + body + action), an FAQ item (question + answer), an error
+ * (message + recovery) — never a single string, and never real prose of
+ * its own. `fields` is a plain `Record<string, unknown>` AT THE TYPE
+ * LEVEL, deliberately: a field's value is exactly what
+ * `classifyPassageField`/`checkPassageComposition` below classify at
+ * RUNTIME, not what a compile-time type could statically forbid a
+ * malformed registry file (real JSON on disk, not TypeScript-checked
+ * code) from containing. See "THE TERNARY" below for why a field holding
+ * a raw literal string must reach the GATE as a real, reportable
+ * violation rather than being rejected upstream as a schema error.
+ *
+ * This file ships no example content of anyone's real copy — the same
+ * "vocabulary layer, never a source of real words" constraint `types.ts`
+ * documents for `CopyEntry`/`CopyRecord`. Every fixture in this package's
+ * own tests is structural placeholder text, never something a product
+ * would actually show a user.
+ *
+ * ============================================================================
+ * THE GATE, WITH THE TERNARY (issue #373)
+ * ============================================================================
+ *
+ *   0 — SATISFIED: every passage references only entries and terms, and
+ *       at least one passage was evaluated.
+ *   1 — VIOLATED: a passage inlines a literal string instead of
+ *       referencing an entry (the verbal equivalent of a hardcoded color
+ *       instead of a token), OR a passage references another passage's
+ *       OWN INTERNALS (`{ ref: "passage", id, field }`) rather than
+ *       composing entries/terms the way a block composes atoms, never
+ *       reaching directly into a sibling block's own implementation.
+ *   2 — INDETERMINATE: the registry could not be read/parsed/validated,
+ *       zero passages were evaluated (an empty `passages: []`), or a
+ *       field's value could not be confidently classified as any of the
+ *       above (not a string, not a recognized `{ ref: ... }` shape).
+ *
+ * PRECEDENCE — a real violation outranks an incomplete picture. This
+ * package already settled this exact question for a different gate
+ * (`addressability.ts`, issue #407/#433): letting "at least one
+ * unclassifiable field" outrank a confirmed violation would make the
+ * `"violated"` branch practically unreachable the moment a registry ever
+ * mixes a genuinely new/unknown field shape in with a real inlined
+ * literal — the identical collapse #407 fixed for addressability is fixed
+ * here from the start, not discovered later. `checkPassageComposition`
+ * applies the same "violated wins" ordering `checkAddressability` does.
+ *
+ * ============================================================================
+ * THE ADVERSARIAL SEPARATION (the weaker tool this gate must beat)
+ * ============================================================================
+ *
+ * A weaker tool that only checks "every referenced entry id exists"
+ * passes a passage built ENTIRELY from inline literals, because such a
+ * passage has ZERO references for that tool to check — nothing to
+ * validate is indistinguishable, to that tool, from everything being
+ * valid. The separating fixture: a passage with zero references and real
+ * prose sitting directly in its fields. The reference-checker reports
+ * clean (0 references, 0 problems). This gate must exit 1 — see
+ * `passage.adversarial.test.ts`, which runs both tools against the
+ * identical fixture in the same test, plus the sanity check that the weak
+ * tool is not simply broken (it correctly reports 0 when references truly
+ * do all exist).
+ *
+ * ============================================================================
+ * WHAT THIS GATE DELIBERATELY DOES NOT DO
+ * ============================================================================
+ *
+ *   - It does not verify a referenced entry id or term actually EXISTS in
+ *     a real `CopyRecord`/glossary. That is a DIFFERENT, weaker question
+ *     ("does this id resolve") than the one this gate answers ("is this
+ *     field a reference at all, or a smuggled-in literal") — the same
+ *     split `addressability.ts` draws from `copy-gate.ts`'s traceability
+ *     check (see that file's own top doc comment: "this gate has no
+ *     `CopyRecord` input at all"). A gate with visibility into both a
+ *     `PassageRecord` and a real `CopyRecord`/glossary to check
+ *     referential integrity is a different, later gate — precisely the
+ *     "weaker tool" this file's own adversarial proof names and beats on
+ *     the property that actually matters here: composition purity.
+ *   - It does not resolve/render a passage into text. Rendering a
+ *     `Passage` against a real `CopyRecord`/`VoiceRecord` glossary is a
+ *     consumer-owned, later concern — this file only ever validates
+ *     SHAPE and COMPOSITION PURITY.
+ */
+/**
+ * A stable address for one `Passage`, unique within its `PassageRecord`.
+ * Same shape as `CopyEntryId` (`types.ts`) — dot-separated, lowercase,
+ * kebab-case within each segment, at least one dot — deliberately
+ * duplicated as its own regex below rather than importing `CopyEntryId`'s
+ * private pattern: `schema.ts` does not export `COPY_ENTRY_ID_RE`, and
+ * this package's own precedent (`addressability.ts`'s locally redefined
+ * `SKIP_FILE_RE`) is to redefine a small, unexported pattern locally
+ * rather than reach across a file boundary for it.
+ */
+export type PassageId = string;
+/**
+ * A reference to a registered `CopyEntry`, by id. This — and
+ * `PassageTermReference` below — are the ONLY two shapes a `Passage`
+ * field may validly hold; see this file's top doc comment, "THE GATE".
+ */
+export interface PassageEntryReference {
+    ref: "entry";
+    id: string;
+}
+/** A reference to a glossary term (see `@clossys/writer/voice`'s `GlossaryEntry.term`), by its term string. */
+export interface PassageTermReference {
+    ref: "term";
+    term: string;
+}
+/** The two valid reference shapes a `Passage` field may hold. */
+export type PassageReference = PassageEntryReference | PassageTermReference;
+/**
+ * One reusable, addressable unit of composed language. `fields` is
+ * intentionally `Record<string, unknown>`, not `Record<string,
+ * PassageReference>` — see this file's top doc comment for why a field's
+ * actual value is a runtime classification question, not a compile-time
+ * type guarantee, for data that arrives as real (possibly malformed) JSON
+ * on disk.
+ */
+export interface Passage {
+    /** Stable address. Unique within the `PassageRecord` it belongs to — see `PassageId`. */
+    id: PassageId;
+    /**
+     * Where this passage appears — a screen name, a component, a flow.
+     * Required, mirroring `CopyEntry.context`'s own "unlocatable copy is
+     * not reviewable copy" rule, restated once more here because it is the
+     * identical rule at one layer up: an unlocatable passage is not
+     * reviewable either.
+     */
+    context: string;
+    /**
+     * Named slots this passage composes — e.g. `{ title: {...}, body:
+     * {...}, action: {...} }` for an empty-state. Each value should be a
+     * `PassageReference`; whether it actually is one is exactly what
+     * `checkPassageComposition` (via `classifyPassageField`) determines.
+     */
+    fields: Record<string, unknown>;
+}
+/** One consumer's complete, registered set of passages. The "brand.css" of this file — foundry ships the schema this conforms to, never a real instance of it. */
+export interface PassageRecord {
+    id: string;
+    passages: Passage[];
+}
+/**
+ * One thing `validatePassageRecordShape` found wrong with a candidate
+ * `PassageRecord`/`Passage`. Deliberately the same shape as `CopyFinding`
+ * (`types.ts`) — `rule`/`severity`/`message`/optional `path` — so a
+ * caller already handling one kind of finding in this package does not
+ * need a second mental model for this one. Defined fresh here rather than
+ * imported: this file does not import from `types.ts` at all (see this
+ * file's top doc comment on why passages never reach for a `CopyRecord`).
+ */
+export interface PassageFinding {
+    rule: string;
+    severity: "error";
+    message: string;
+    path?: string;
+}
+/**
+ * Validates that `value` conforms to the `PassageRecord` shape. Returns a
+ * `PassageFinding[]`; empty means `value` is a well-formed `PassageRecord`.
+ * Never throws — mirrors `schema.ts`'s `validateCopyRecordShape` exactly:
+ * any input, including `null`/a string/a wildly malformed object,
+ * produces findings rather than an exception.
+ */
+export declare function validatePassageRecordShape(value: unknown): PassageFinding[];
+/**
+ * Parses `value` as a `PassageRecord`, throwing a plain `Error` (never a
+ * `PassageFinding[]`) if it does not conform — mirrors `schema.ts`'s
+ * `parseCopyRecord` exactly, including the two-pass validate-then-build
+ * shape and why (see that function's own doc comment for the fuller
+ * argument).
+ */
+export declare function parsePassageRecord(value: unknown): PassageRecord;
+/**
+ * Why `path` did not become a usable `PassageRecord`. Mirrors
+ * `registry.ts`'s `CopyRegistryReadIssueReason` exactly — see that type's
+ * own doc comment for what each reason means.
+ */
+export type PassageRegistryReadIssueReason = "unreadable" | "unparseable" | "invalid-schema";
+export interface PassageRegistryReadIssue {
+    reason: PassageRegistryReadIssueReason;
+    detail: string;
+}
+export interface PassageRegistryReadResult {
+    path: string;
+    record?: PassageRecord;
+    issues: PassageRegistryReadIssue[];
+    /** `true` exactly when `issues` is empty and `record` is populated — see `registry.ts`'s `CopyRegistryReadResult.complete` for why this is the shared one-boolean-read contract across this package. */
+    complete: boolean;
+}
+/**
+ * Reads and validates the `PassageRecord` at `path`. Never throws: every
+ * failure — an unreadable file, invalid JSON, or a schema violation — is
+ * recorded into `issues` and reflected in `.complete`. Mirrors
+ * `registry.ts`'s `readCopyRecord` exactly, including the discipline it
+ * documents: an unreadable/invalid registry is "could not run" (fed into
+ * exit `2` by the CLI), never a clean pass produced from a record this
+ * function could not actually trust.
+ */
+export declare function readPassageRecord(path: string): PassageRegistryReadResult;
+export type PassageFieldClassification = "entry-reference" | "term-reference" | "inline-literal" | "passage-internals-reference" | "unclassifiable";
+interface PassageFieldClassificationResult {
+    classification: PassageFieldClassification;
+    detail: string;
+}
+/**
+ * Classifies one `Passage` field's raw value into exactly one of the five
+ * `PassageFieldClassification` outcomes. Pure — no I/O, never throws on
+ * any input shape.
+ *
+ *   - A plain string is ALWAYS `"inline-literal"` — real prose (or
+ *     anything else) sitting directly in the field instead of a
+ *     reference. This is the shape the adversarial proof's separating
+ *     fixture is built from — see this file's top doc comment.
+ *   - `{ ref: "entry", id: <non-empty string> }` is `"entry-reference"`.
+ *   - `{ ref: "term", term: <non-empty string> }` is `"term-reference"`.
+ *   - `{ ref: "passage", ... }` — REGARDLESS of what else it carries — is
+ *     always `"passage-internals-reference"`: a passage may compose
+ *     entries and terms, never reach directly into another passage's own
+ *     fields. This is a VIOLATION, not something this function treats as
+ *     merely unclassifiable, because the shape is unambiguous the moment
+ *     `ref === "passage"` is seen.
+ *   - `{ ref: "entry" | "term", ... }` with a missing/malformed
+ *     `id`/`term` is `"unclassifiable"` — the AUTHOR'S intent (compose an
+ *     entry or a term) is legible, but the reference itself is broken, so
+ *     this function refuses to guess which finding shape to promote it
+ *     to rather than silently treating a broken reference as either
+ *     "fine" or "definitely a literal."
+ *   - Anything else (a number, boolean, null, array, or an object with no
+ *     recognized `ref`) is `"unclassifiable"`.
+ */
+export declare function classifyPassageField(value: unknown): PassageFieldClassificationResult;
+export type PassageViolationRule = "field-inlines-literal" | "field-references-passage-internals";
+export interface PassageViolation {
+    passageId: PassageId;
+    field: string;
+    rule: PassageViolationRule;
+    message: string;
+}
+export interface PassageUnclassifiedItem {
+    passageId: PassageId;
+    field: string;
+    detail: string;
+}
+export type PassageVerdict = "satisfied" | "violated" | "indeterminate";
+export interface PassageGateResult {
+    verdict: PassageVerdict;
+    violations: PassageViolation[];
+    /** Every field this gate could not confidently classify — never silently dropped. See `classifyPassageField`'s own doc comment. */
+    unclassified: PassageUnclassifiedItem[];
+    /** How many passages had at least one field examined. Required to be > 0 for a satisfied verdict — see this file's top doc comment, "THE GATE". */
+    passagesEvaluated: number;
+    /** Human-readable reasons coverage is incomplete — empty for `"satisfied"`. Non-empty for `"violated"` too is possible (a real violation AND unclassified fields in the same run) — only `"indeterminate"` requires this to be non-empty. */
+    reasons: string[];
+}
+/**
+ * Pure — takes an already-parsed `PassageRecord` (see `readPassageRecord`/
+ * `parsePassageRecord`), classifies every field of every passage, and
+ * decides the ternary verdict. Never throws, does no I/O.
+ *
+ * PRECEDENCE: a real violation wins over an incomplete picture — see this
+ * file's top doc comment, "THE TERNARY", for why this mirrors
+ * `checkAddressability`'s own post-#407 ordering rather than the older
+ * "indeterminate wins" precedence `checkCopyTraceability`/`scan.ts` still
+ * use for a different reason (see `checkAddressability`'s own doc comment
+ * for the fuller argument against letting a permanent-in-practice
+ * coverage gap make a real violation unreachable).
+ */
+export declare function checkPassageComposition(record: PassageRecord): PassageGateResult;
+export {};
+//# sourceMappingURL=passage.d.ts.map

package/dist/passage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"passage.d.ts","sourceRoot":"","sources":["../src/passage.ts"],"names":[],"mappings":"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"}