@clossys/writer 0.3.2

package/dist/voice/derivation-coverage.d.ts

@@ -0,0 +1,168 @@
+/**
+ * `checkVoiceDerivationCoverage` — the voice half of `@clossys/
+ * strategy`'s `checkBrandCoverage`, which this file mirrors closely on
+ * purpose. Read `packages/strategy/src/brand-derivation.ts`'s header
+ * comment in full before touching this one; the design below is that
+ * file's, ported to the other side of the seam it documents.
+ *
+ * THE GAP THIS CLOSES
+ * ---------------------------------------------------------------------------
+ * A `BrandDerivation` (`strategy`) names two kinds of obligation by PLAIN
+ * STRING: `tokenSlots` and `voiceRules` — see that file's "THE NAME-ONLY
+ * SEAM, AND WHY". `checkBrandCoverage` verifies the `tokenSlots` half
+ * against a caller-supplied `brandableSlots: string[]`, in both directions.
+ * It does NOT, and by its own package's constraints CANNOT, verify the
+ * `voiceRules` half — `strategy` ships zero runtime dependencies and does
+ * not import `@clossys/writer/voice`, so it has no way to know which
+ * voice rule ids a real `VoiceRecord` actually declares. `strategy`'s own
+ * README says this plainly: "whether a `voiceRules` id resolves to a real
+ * `@clossys/writer/voice` glossary entry... [is] a later,
+ * cross-package gate's job — one with visibility into... `voice` that this
+ * package deliberately does not have." A brand attribute can oblige a voice
+ * rule that no `VoiceRecord` anywhere declares, and nothing catches it: the
+ * token half of the gate passes cleanly, because it only ever compares
+ * against a token slot list, and the voice half is never compared against
+ * anything at all. This file is that later gate — built here, in `copy`,
+ * because this is the one package that actually holds a `VoiceRecord`.
+ *
+ * THE NAME-ONLY SEAM, AND WHY
+ * ---------------------------------------------------------------------------
+ * This function takes two PLAIN STRING LISTS, `obligations` and
+ * `brandDerivedRuleIds` — the exact same discipline `BrandDerivation.
+ * voiceRules` documents for itself, carried through to this side of the
+ * seam, and the exact same shape `checkBrandCoverage` takes
+ * `brandableSlots` in. This file does not import `@clossys/
+ * strategy` or know anything about `BrandDerivation`, and it does not read
+ * a `VoiceRecord` either. Earlier revisions of this function DID take a
+ * `VoiceRecord` and scanned it for every glossary term, claim id, and
+ * pattern id, treating that whole scan as the set direction 2 had to cover.
+ * That was wrong, and it was wrong for the identical reason `strategy`
+ * cannot look up `tokens`' `brandable` flag itself: EVERY field in a
+ * `VoiceRecord` is consumer-authored, but authored is not the same claim as
+ * brand-derived. `@example/ui` ships 154 tokens and marks a curated
+ * 42 of them `brandable: true` — a deliberate subset a `BrandDerivation`'s
+ * `tokenSlots` is checked against, never the full 154. `voice` has no
+ * `brandable`-equivalent flag on a glossary entry or a claim, so scanning
+ * the whole record and calling that "the brand-derived set" silently
+ * substituted "everything a consumer happened to author" for "everything a
+ * brand attribute actually obliges" — a consumer with 200 glossary terms
+ * and one real brand obligation would need 200 `BrandDerivation.voiceRules`
+ * entries just to pass direction 2, a false-positive machine that gets
+ * disabled the first time it fires on a real record. Nothing inside a
+ * `VoiceRecord`, and nothing inside this package, can tell a brand-derived
+ * glossary term from an editorially-authored one — that judgment lives only
+ * where a `BrandDerivation` and a `VoiceRecord` are both in scope, i.e. the
+ * caller.
+ *
+ * THE CHECKER'S SEAM — READ THIS BEFORE CALLING `checkVoiceDerivationCoverage`
+ * ---------------------------------------------------------------------------
+ * Because this package cannot know which of a `VoiceRecord`'s ids a brand
+ * attribute actually derived, `checkVoiceDerivationCoverage` cannot look
+ * that set up itself. It takes it as an argument (`brandDerivedRuleIds:
+ * readonly string[]`) instead. This is deliberate, not a missing feature:
+ * the CALLER — a consumer repo that depends on both `strategy` and `copy`,
+ * or a later cross-package gate built with visibility into both — is the
+ * one place that seam can be closed for real, e.g. by flattening every
+ * `BrandDerivation.voiceRules` entry (across every derivation) into the
+ * flat `brandDerivedRuleIds` list this function takes, the same way a
+ * caller closes `checkBrandCoverage`'s seam by passing
+ * `Object.values(TOKENS).filter(t => t.brandable).map(t => t.property)`
+ * from `@example/ui/tokens`. `checkVoiceDerivationCoverage` only
+ * ever sees the two plain lists it's handed; it has no way to tell a real,
+ * current, brand-derived rule-id list from a stale or empty one, which is
+ * exactly why the degenerate cases below (an empty list either way) are
+ * treated as failures rather than silent passes — see "Fails closed",
+ * below.
+ *
+ * WHAT COUNTS AS A "VOICE RULE ID"
+ * ---------------------------------------------------------------------------
+ * This function no longer inspects a `VoiceRecord` at all, so it does not
+ * decide what counts as a rule id — the caller does, by what it puts in
+ * `brandDerivedRuleIds`. In practice that id space is still the one
+ * `strategy`'s own README names for `voiceRules`: "a real
+ * `@clossys/writer/voice` glossary entry" — i.e. a glossary term's
+ * `term` or a claim's `id` (`types.ts`'s `GlossaryEntry`/`Claim`). Earlier
+ * revisions of this file additionally counted `patterns` ids as voice rule
+ * ids by auto-deriving the whole set from a record; that widened direction
+ * 2 beyond what `strategy`'s documented `voiceRules` contract actually
+ * names, purely as a side effect of this package doing the scanning itself.
+ * With no record to scan and a caller-supplied list instead, this package
+ * no longer makes that decision — the caller decides what belongs in
+ * `brandDerivedRuleIds`, exactly as the caller decides what belongs in
+ * `checkBrandCoverage`'s `brandableSlots`.
+ *
+ * THE CHECK ITSELF — BOTH DIRECTIONS, LIKE `checkBrandCoverage`
+ * ---------------------------------------------------------------------------
+ *   1. Every id in `obligations` is named by `brandDerivedRuleIds` — an
+ *      obligation naming an id nothing derived is a stale or typo'd
+ *      reference (`obligationsMissingFromRecord`).
+ *   2. Every id in `brandDerivedRuleIds` is reached by at least one
+ *      obligation — a brand-derived rule id with no obligation behind it
+ *      is undocumented brand intent, exactly `checkBrandCoverage`'s
+ *      `slotsMissingDerivation` mirrored onto the other list
+ *      (`recordRulesNotObliged`).
+ *
+ * A ONE-DIRECTIONAL CHECKER PASSES CASE 2 AND HIDES IT — this file exists
+ * specifically because a checker that only implements direction 1 (every
+ * obligation resolves) looks complete, passes every obligation-side test,
+ * and still never notices a whole brand-derived rule id nobody obliged. See
+ * `derivation-coverage.test.ts` for the fixture built to prove this file
+ * does not make that mistake.
+ *
+ * FAILS CLOSED, IDENTICAL PRECEDENT TO `checkBrandCoverage`
+ * ---------------------------------------------------------------------------
+ * A checker given nothing to check must never report the same shape as a
+ * checker that checked everything and found it clean. Both degenerate
+ * inputs are an explicit failure, never a vacuous pass:
+ *
+ *   - `obligations.length === 0` — nothing was obliged at all. `ok: false`,
+ *     `reason: "no-obligations-provided"`.
+ *   - `brandDerivedRuleIds.length === 0` — nothing to check obligations
+ *     against. Maybe the caller forgot to pass the real list, maybe a
+ *     consumer genuinely derived zero voice rules from its brand; either
+ *     way this function cannot tell the difference, so it cannot report
+ *     success. `ok: false`, `reason: "no-brand-derived-rules-provided"`.
+ *
+ * `obligationsChecked` and `rulesChecked` are always present, in every
+ * branch, for the identical reason `checkBrandCoverage`'s own header states
+ * for `slotsChecked`/`derivationsChecked`: so "zero things were checked"
+ * and "everything checked out fine" can never be told apart by a caller who
+ * only glances at `ok`.
+ *
+ * Pure — no I/O, never throws.
+ */
+/**
+ * Why a `VoiceDerivationCoverageResult` is not `ok`, when it isn't.
+ * `"coverage-gap"` is a REAL finding — some obligation names an id nothing
+ * derived, or some brand-derived rule id is reached by no obligation —
+ * over a genuine, non-empty comparison. `"no-obligations-provided"` and
+ * `"no-brand-derived-rules-provided"` are the OTHER kind of failure:
+ * nothing meaningful was compared at all. See this file's top-of-file doc
+ * comment, "Fails closed".
+ */
+export type VoiceDerivationCoverageFailureReason = "no-obligations-provided" | "no-brand-derived-rules-provided" | "coverage-gap";
+export interface VoiceDerivationCoverageResult {
+    ok: boolean;
+    /** `obligations.length`, always present — see this file's header comment, "Fails closed". */
+    obligationsChecked: number;
+    /** `brandDerivedRuleIds.length`, always present, for the same reason. */
+    rulesChecked: number;
+    /** Direction 1: every obligation naming an id `brandDerivedRuleIds` does not declare. */
+    obligationsMissingFromRecord: string[];
+    /** Direction 2: every id in `brandDerivedRuleIds` that no obligation names. */
+    recordRulesNotObliged: string[];
+    /** Present exactly when `ok` is `false`. See `VoiceDerivationCoverageFailureReason`. */
+    reason?: VoiceDerivationCoverageFailureReason;
+}
+/**
+ * Checks whether `obligations` fully accounts for `brandDerivedRuleIds`, in
+ * both directions, and fails closed on either empty input. Pure — no I/O,
+ * never throws. See this file's top-of-file doc comment for the seam
+ * (`brandDerivedRuleIds` is caller-supplied, since this package has no way
+ * to tell a brand-derived voice rule id from any other consumer-authored
+ * one) and for why the two degenerate inputs are failures rather than
+ * vacuous passes. See `strategy`'s `checkBrandCoverage` (which this
+ * mirrors) for the precedent.
+ */
+export declare function checkVoiceDerivationCoverage(obligations: readonly string[], brandDerivedRuleIds: readonly string[]): VoiceDerivationCoverageResult;
+//# sourceMappingURL=derivation-coverage.d.ts.map

package/dist/voice/derivation-coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derivation-coverage.d.ts","sourceRoot":"","sources":["../../src/voice/derivation-coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoIG;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,oCAAoC,GAC5C,yBAAyB,GACzB,iCAAiC,GACjC,cAAc,CAAC;AAEnB,MAAM,WAAW,6BAA6B;IAC5C,EAAE,EAAE,OAAO,CAAC;IACZ,6FAA6F;IAC7F,kBAAkB,EAAE,MAAM,CAAC;IAC3B,yEAAyE;IACzE,YAAY,EAAE,MAAM,CAAC;IACrB,yFAAyF;IACzF,4BAA4B,EAAE,MAAM,EAAE,CAAC;IACvC,+EAA+E;IAC/E,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,wFAAwF;IACxF,MAAM,CAAC,EAAE,oCAAoC,CAAC;CAC/C;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,mBAAmB,EAAE,SAAS,MAAM,EAAE,GACrC,6BAA6B,CAyC/B"}

package/dist/voice/derivation-coverage.js

@@ -0,0 +1,181 @@
+/**
+ * `checkVoiceDerivationCoverage` — the voice half of `@clossys/
+ * strategy`'s `checkBrandCoverage`, which this file mirrors closely on
+ * purpose. Read `packages/strategy/src/brand-derivation.ts`'s header
+ * comment in full before touching this one; the design below is that
+ * file's, ported to the other side of the seam it documents.
+ *
+ * THE GAP THIS CLOSES
+ * ---------------------------------------------------------------------------
+ * A `BrandDerivation` (`strategy`) names two kinds of obligation by PLAIN
+ * STRING: `tokenSlots` and `voiceRules` — see that file's "THE NAME-ONLY
+ * SEAM, AND WHY". `checkBrandCoverage` verifies the `tokenSlots` half
+ * against a caller-supplied `brandableSlots: string[]`, in both directions.
+ * It does NOT, and by its own package's constraints CANNOT, verify the
+ * `voiceRules` half — `strategy` ships zero runtime dependencies and does
+ * not import `@clossys/writer/voice`, so it has no way to know which
+ * voice rule ids a real `VoiceRecord` actually declares. `strategy`'s own
+ * README says this plainly: "whether a `voiceRules` id resolves to a real
+ * `@clossys/writer/voice` glossary entry... [is] a later,
+ * cross-package gate's job — one with visibility into... `voice` that this
+ * package deliberately does not have." A brand attribute can oblige a voice
+ * rule that no `VoiceRecord` anywhere declares, and nothing catches it: the
+ * token half of the gate passes cleanly, because it only ever compares
+ * against a token slot list, and the voice half is never compared against
+ * anything at all. This file is that later gate — built here, in `copy`,
+ * because this is the one package that actually holds a `VoiceRecord`.
+ *
+ * THE NAME-ONLY SEAM, AND WHY
+ * ---------------------------------------------------------------------------
+ * This function takes two PLAIN STRING LISTS, `obligations` and
+ * `brandDerivedRuleIds` — the exact same discipline `BrandDerivation.
+ * voiceRules` documents for itself, carried through to this side of the
+ * seam, and the exact same shape `checkBrandCoverage` takes
+ * `brandableSlots` in. This file does not import `@clossys/
+ * strategy` or know anything about `BrandDerivation`, and it does not read
+ * a `VoiceRecord` either. Earlier revisions of this function DID take a
+ * `VoiceRecord` and scanned it for every glossary term, claim id, and
+ * pattern id, treating that whole scan as the set direction 2 had to cover.
+ * That was wrong, and it was wrong for the identical reason `strategy`
+ * cannot look up `tokens`' `brandable` flag itself: EVERY field in a
+ * `VoiceRecord` is consumer-authored, but authored is not the same claim as
+ * brand-derived. `@example/ui` ships 154 tokens and marks a curated
+ * 42 of them `brandable: true` — a deliberate subset a `BrandDerivation`'s
+ * `tokenSlots` is checked against, never the full 154. `voice` has no
+ * `brandable`-equivalent flag on a glossary entry or a claim, so scanning
+ * the whole record and calling that "the brand-derived set" silently
+ * substituted "everything a consumer happened to author" for "everything a
+ * brand attribute actually obliges" — a consumer with 200 glossary terms
+ * and one real brand obligation would need 200 `BrandDerivation.voiceRules`
+ * entries just to pass direction 2, a false-positive machine that gets
+ * disabled the first time it fires on a real record. Nothing inside a
+ * `VoiceRecord`, and nothing inside this package, can tell a brand-derived
+ * glossary term from an editorially-authored one — that judgment lives only
+ * where a `BrandDerivation` and a `VoiceRecord` are both in scope, i.e. the
+ * caller.
+ *
+ * THE CHECKER'S SEAM — READ THIS BEFORE CALLING `checkVoiceDerivationCoverage`
+ * ---------------------------------------------------------------------------
+ * Because this package cannot know which of a `VoiceRecord`'s ids a brand
+ * attribute actually derived, `checkVoiceDerivationCoverage` cannot look
+ * that set up itself. It takes it as an argument (`brandDerivedRuleIds:
+ * readonly string[]`) instead. This is deliberate, not a missing feature:
+ * the CALLER — a consumer repo that depends on both `strategy` and `copy`,
+ * or a later cross-package gate built with visibility into both — is the
+ * one place that seam can be closed for real, e.g. by flattening every
+ * `BrandDerivation.voiceRules` entry (across every derivation) into the
+ * flat `brandDerivedRuleIds` list this function takes, the same way a
+ * caller closes `checkBrandCoverage`'s seam by passing
+ * `Object.values(TOKENS).filter(t => t.brandable).map(t => t.property)`
+ * from `@example/ui/tokens`. `checkVoiceDerivationCoverage` only
+ * ever sees the two plain lists it's handed; it has no way to tell a real,
+ * current, brand-derived rule-id list from a stale or empty one, which is
+ * exactly why the degenerate cases below (an empty list either way) are
+ * treated as failures rather than silent passes — see "Fails closed",
+ * below.
+ *
+ * WHAT COUNTS AS A "VOICE RULE ID"
+ * ---------------------------------------------------------------------------
+ * This function no longer inspects a `VoiceRecord` at all, so it does not
+ * decide what counts as a rule id — the caller does, by what it puts in
+ * `brandDerivedRuleIds`. In practice that id space is still the one
+ * `strategy`'s own README names for `voiceRules`: "a real
+ * `@clossys/writer/voice` glossary entry" — i.e. a glossary term's
+ * `term` or a claim's `id` (`types.ts`'s `GlossaryEntry`/`Claim`). Earlier
+ * revisions of this file additionally counted `patterns` ids as voice rule
+ * ids by auto-deriving the whole set from a record; that widened direction
+ * 2 beyond what `strategy`'s documented `voiceRules` contract actually
+ * names, purely as a side effect of this package doing the scanning itself.
+ * With no record to scan and a caller-supplied list instead, this package
+ * no longer makes that decision — the caller decides what belongs in
+ * `brandDerivedRuleIds`, exactly as the caller decides what belongs in
+ * `checkBrandCoverage`'s `brandableSlots`.
+ *
+ * THE CHECK ITSELF — BOTH DIRECTIONS, LIKE `checkBrandCoverage`
+ * ---------------------------------------------------------------------------
+ *   1. Every id in `obligations` is named by `brandDerivedRuleIds` — an
+ *      obligation naming an id nothing derived is a stale or typo'd
+ *      reference (`obligationsMissingFromRecord`).
+ *   2. Every id in `brandDerivedRuleIds` is reached by at least one
+ *      obligation — a brand-derived rule id with no obligation behind it
+ *      is undocumented brand intent, exactly `checkBrandCoverage`'s
+ *      `slotsMissingDerivation` mirrored onto the other list
+ *      (`recordRulesNotObliged`).
+ *
+ * A ONE-DIRECTIONAL CHECKER PASSES CASE 2 AND HIDES IT — this file exists
+ * specifically because a checker that only implements direction 1 (every
+ * obligation resolves) looks complete, passes every obligation-side test,
+ * and still never notices a whole brand-derived rule id nobody obliged. See
+ * `derivation-coverage.test.ts` for the fixture built to prove this file
+ * does not make that mistake.
+ *
+ * FAILS CLOSED, IDENTICAL PRECEDENT TO `checkBrandCoverage`
+ * ---------------------------------------------------------------------------
+ * A checker given nothing to check must never report the same shape as a
+ * checker that checked everything and found it clean. Both degenerate
+ * inputs are an explicit failure, never a vacuous pass:
+ *
+ *   - `obligations.length === 0` — nothing was obliged at all. `ok: false`,
+ *     `reason: "no-obligations-provided"`.
+ *   - `brandDerivedRuleIds.length === 0` — nothing to check obligations
+ *     against. Maybe the caller forgot to pass the real list, maybe a
+ *     consumer genuinely derived zero voice rules from its brand; either
+ *     way this function cannot tell the difference, so it cannot report
+ *     success. `ok: false`, `reason: "no-brand-derived-rules-provided"`.
+ *
+ * `obligationsChecked` and `rulesChecked` are always present, in every
+ * branch, for the identical reason `checkBrandCoverage`'s own header states
+ * for `slotsChecked`/`derivationsChecked`: so "zero things were checked"
+ * and "everything checked out fine" can never be told apart by a caller who
+ * only glances at `ok`.
+ *
+ * Pure — no I/O, never throws.
+ */
+/**
+ * Checks whether `obligations` fully accounts for `brandDerivedRuleIds`, in
+ * both directions, and fails closed on either empty input. Pure — no I/O,
+ * never throws. See this file's top-of-file doc comment for the seam
+ * (`brandDerivedRuleIds` is caller-supplied, since this package has no way
+ * to tell a brand-derived voice rule id from any other consumer-authored
+ * one) and for why the two degenerate inputs are failures rather than
+ * vacuous passes. See `strategy`'s `checkBrandCoverage` (which this
+ * mirrors) for the precedent.
+ */
+export function checkVoiceDerivationCoverage(obligations, brandDerivedRuleIds) {
+    const obligationsChecked = obligations.length;
+    const rulesChecked = brandDerivedRuleIds.length;
+    const ruleIdSet = new Set(brandDerivedRuleIds);
+    const obligedSet = new Set(obligations);
+    const obligationsMissingFromRecord = obligations.filter((id) => !ruleIdSet.has(id));
+    const recordRulesNotObliged = brandDerivedRuleIds.filter((id) => !obligedSet.has(id));
+    if (obligationsChecked === 0) {
+        return {
+            ok: false,
+            obligationsChecked,
+            rulesChecked,
+            obligationsMissingFromRecord,
+            recordRulesNotObliged,
+            reason: "no-obligations-provided",
+        };
+    }
+    if (rulesChecked === 0) {
+        return {
+            ok: false,
+            obligationsChecked,
+            rulesChecked,
+            obligationsMissingFromRecord,
+            recordRulesNotObliged,
+            reason: "no-brand-derived-rules-provided",
+        };
+    }
+    const ok = obligationsMissingFromRecord.length === 0 && recordRulesNotObliged.length === 0;
+    return {
+        ok,
+        obligationsChecked,
+        rulesChecked,
+        obligationsMissingFromRecord,
+        recordRulesNotObliged,
+        reason: ok ? undefined : "coverage-gap",
+    };
+}
+//# sourceMappingURL=derivation-coverage.js.map

package/dist/voice/derivation-coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derivation-coverage.js","sourceRoot":"","sources":["../../src/voice/derivation-coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoIG;AA8BH;;;;;;;;;GASG;AACH,MAAM,UAAU,4BAA4B,CAC1C,WAA8B,EAC9B,mBAAsC;IAEtC,MAAM,kBAAkB,GAAG,WAAW,CAAC,MAAM,CAAC;IAC9C,MAAM,YAAY,GAAG,mBAAmB,CAAC,MAAM,CAAC;IAEhD,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAC/C,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,CAAC;IAExC,MAAM,4BAA4B,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IACpF,MAAM,qBAAqB,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAEtF,IAAI,kBAAkB,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,kBAAkB;YAClB,YAAY;YACZ,4BAA4B;YAC5B,qBAAqB;YACrB,MAAM,EAAE,yBAAyB;SAClC,CAAC;IACJ,CAAC;IAED,IAAI,YAAY,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,kBAAkB;YAClB,YAAY;YACZ,4BAA4B;YAC5B,qBAAqB;YACrB,MAAM,EAAE,iCAAiC;SAC1C,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,GAAG,4BAA4B,CAAC,MAAM,KAAK,CAAC,IAAI,qBAAqB,CAAC,MAAM,KAAK,CAAC,CAAC;IAC3F,OAAO;QACL,EAAE;QACF,kBAAkB;QAClB,YAAY;QACZ,4BAA4B;QAC5B,qBAAqB;QACrB,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,cAAc;KACxC,CAAC;AACJ,CAAC"}

package/dist/voice/fields.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The bindable/fixed split for `VoiceRecord` — the `TokenDefinition.brandable`
+ * analog for this package. See `@example/ui/tokens`' `src/tokens.ts` for
+ * the model this file ports.
+ *
+ * WHERE THE LINE ACTUALLY FALLS (a finding, not an assumption)
+ * ---------------------------------------------------------------------------
+ * In `tokens`, the split runs WITHIN one flat namespace: `styles/tokens.css`
+ * declares 154 real CSS custom properties, and only 42 of them are
+ * `brandable: true` — the other 112 (spacing, the type ramp, z-index,
+ * duration, easing, breakpoints, the neutral ramp, ...) are declared with a
+ * real value and STAY that value for every brand, forever. Both the
+ * brandable and the non-brandable tokens live in the same file, the same
+ * `TOKENS` record, distinguished only by the boolean.
+ *
+ * `VoiceRecord` does not have that shape, and pretending it does would be
+ * dishonest. Every field a `VoiceRecord` instance actually carries — `id`,
+ * both rules' `description`s, `forbiddenPronouns`, `forbiddenMarkers`,
+ * `formality`, `tone`, `glossary`, `claims`, `patterns` — is content one specific
+ * consumer authors: there is no field here that ships a working default
+ * value and stays that value for every voice the way `--spacing-lg: 16px`
+ * does for every brand. `VoiceRecord` IS the consumer-owned binding layer in
+ * its entirety, the same way `brand.css` is: nothing in `brand-template.css`
+ * is "shipped, leave it alone" either — every slot IN that file is
+ * `bindable`, by construction, because only the bindable slots were ever
+ * put in the template in the first place. The non-brandable 112 in `tokens`
+ * live in `tokens.css`, a different file `brand-template.css` never touches;
+ * `VoiceRecord`'s analog of that other file is `types.ts` and `schema.ts` —
+ * TypeScript interfaces and string-literal unions, not runtime record
+ * fields at all.
+ *
+ * So the split for voice runs BETWEEN two files, not within one:
+ *
+ *   FIXED (rule KINDS — never appear below, never appear in the template,
+ *   shipped once in `types.ts`, identical for every consumer forever):
+ *     - the shape of `VoiceRules` itself — that a voice has exactly a
+ *       `person` rule, a `tense` rule, a `formality` axis, and a `tone`
+ *       axis, no more, no fewer;
+ *     - `FormalityLevel`'s three possible values (`"casual"`, `"neutral"`,
+ *       `"formal"`) and `GlossaryStatus`'s two (`"forbidden"`,
+ *       `"preferred"`) — the ENUM, not which member a given entry picks;
+ *     - the field set of `PersonRule`, `TenseRule`, `GlossaryEntry`, and
+ *       `Claim` — that a glossary entry has a `term`/`status`/`reason`/
+ *       `alternative`/`caseSensitive` and nothing else, for instance.
+ *
+ *   BINDABLE (rule VALUES — every entry below, every one `true`, all
+ *   consumer-owned, all present in `voice-record.template.jsonc`):
+ *     - which pronouns are forbidden, which tense markers, which specific
+ *       terms are forbidden or preferred and why, which claims are
+ *       registered and whether each needs a `factRef` — the actual data
+ *       that fills the fixed shape above, one consumer's own.
+ *
+ * This file catalogs only the second half — the runtime fields of a
+ * `VoiceRecord` instance — because those are the only things a template can
+ * meaningfully hold a fill-in-the-blank for. It is `Readonly<Record<...>>`,
+ * every entry `bindable: true`, deliberately: `src/field-coverage.test.ts`
+ * still runs a two-way check against it (and a third, currently-vacuous but
+ * future-guarding check that no `bindable: false` entry is ever live in the
+ * template), the same shape as `tokens`' `brand-coverage.test.ts`, so that
+ * if a future field is ever added here as `bindable: false`, the existing
+ * tests immediately start meaning something rather than needing to be
+ * written from scratch.
+ *
+ * A LEAF, NOT A TREE — WHY ARRAYS STOP HERE
+ * ---------------------------------------------------------------------------
+ * `glossary` and `claims` are each catalogued as ONE path, not expanded
+ * into their per-entry fields (`glossary.term`, `glossary.reason`, ...).
+ * Both are variable-length collections of consumer-authored records — the
+ * PER-ENTRY shape (`GlossaryEntry`, `Claim`) is the FIXED half described
+ * above, already enumerated once in `types.ts`; re-stating it here as
+ * catalog entries would just be a second, driftable copy of the same
+ * interface. What's bindable about `glossary` and `claims` is that the
+ * ARRAY exists and a consumer populates it — exactly what one path each,
+ * marked `bindable: true`, records.
+ */
+/** One runtime field path of a `VoiceRecord` instance, and its bindable/fixed classification. */
+export interface VoiceFieldDefinition {
+    /** Dot-path from the record root, e.g. `"rules.person.forbiddenPronouns"`. Array-valued fields stop here — see this file's header comment, "A leaf, not a tree". */
+    readonly path: string;
+    /**
+     * `true` for every entry in this catalog: a rule VALUE, consumer-owned,
+     * expected to appear in `voice-record.template.jsonc`. See this file's
+     * header comment for why no `VoiceRecord` field is ever `false` here, and
+     * where the fixed half of this package's contract actually lives instead.
+     */
+    readonly bindable: boolean;
+    /** Human-readable note on what this slot holds. */
+    readonly description: string;
+}
+/**
+ * Every runtime field path a `VoiceRecord` instance carries, keyed by that
+ * same path. `src/field-coverage.test.ts` asserts, in both directions, that
+ * this set and `templates/voice-record.template.jsonc`'s own set of paths
+ * are identical.
+ */
+export declare const VOICE_FIELDS: Readonly<Record<string, VoiceFieldDefinition>>;
+/**
+ * The literal placeholder value `voice-record.template.jsonc` uses for every
+ * bindable string slot. Loud and specific on purpose — see
+ * `checker.ts`'s `findPlaceholderPaths` for why an unmissable, near-zero-
+ * collision sentinel is exactly what makes the unbound signal trustworthy:
+ * a real voice's copy of the template that forgot to fill in even one slot
+ * still trips it, and nothing a real consumer would plausibly type by
+ * coincidence ever does.
+ */
+export declare const TEMPLATE_PLACEHOLDER = "REPLACE_ME__VOICE_TEMPLATE_PLACEHOLDER";
+//# sourceMappingURL=fields.d.ts.map

package/dist/voice/fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../../src/voice/fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AAEH,iGAAiG;AACjG,MAAM,WAAW,oBAAoB;IACnC,oKAAoK;IACpK,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAmDvE,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,2CAA2C,CAAC"}

package/dist/voice/fields.js

@@ -0,0 +1,144 @@
+/**
+ * The bindable/fixed split for `VoiceRecord` — the `TokenDefinition.brandable`
+ * analog for this package. See `@example/ui/tokens`' `src/tokens.ts` for
+ * the model this file ports.
+ *
+ * WHERE THE LINE ACTUALLY FALLS (a finding, not an assumption)
+ * ---------------------------------------------------------------------------
+ * In `tokens`, the split runs WITHIN one flat namespace: `styles/tokens.css`
+ * declares 154 real CSS custom properties, and only 42 of them are
+ * `brandable: true` — the other 112 (spacing, the type ramp, z-index,
+ * duration, easing, breakpoints, the neutral ramp, ...) are declared with a
+ * real value and STAY that value for every brand, forever. Both the
+ * brandable and the non-brandable tokens live in the same file, the same
+ * `TOKENS` record, distinguished only by the boolean.
+ *
+ * `VoiceRecord` does not have that shape, and pretending it does would be
+ * dishonest. Every field a `VoiceRecord` instance actually carries — `id`,
+ * both rules' `description`s, `forbiddenPronouns`, `forbiddenMarkers`,
+ * `formality`, `tone`, `glossary`, `claims`, `patterns` — is content one specific
+ * consumer authors: there is no field here that ships a working default
+ * value and stays that value for every voice the way `--spacing-lg: 16px`
+ * does for every brand. `VoiceRecord` IS the consumer-owned binding layer in
+ * its entirety, the same way `brand.css` is: nothing in `brand-template.css`
+ * is "shipped, leave it alone" either — every slot IN that file is
+ * `bindable`, by construction, because only the bindable slots were ever
+ * put in the template in the first place. The non-brandable 112 in `tokens`
+ * live in `tokens.css`, a different file `brand-template.css` never touches;
+ * `VoiceRecord`'s analog of that other file is `types.ts` and `schema.ts` —
+ * TypeScript interfaces and string-literal unions, not runtime record
+ * fields at all.
+ *
+ * So the split for voice runs BETWEEN two files, not within one:
+ *
+ *   FIXED (rule KINDS — never appear below, never appear in the template,
+ *   shipped once in `types.ts`, identical for every consumer forever):
+ *     - the shape of `VoiceRules` itself — that a voice has exactly a
+ *       `person` rule, a `tense` rule, a `formality` axis, and a `tone`
+ *       axis, no more, no fewer;
+ *     - `FormalityLevel`'s three possible values (`"casual"`, `"neutral"`,
+ *       `"formal"`) and `GlossaryStatus`'s two (`"forbidden"`,
+ *       `"preferred"`) — the ENUM, not which member a given entry picks;
+ *     - the field set of `PersonRule`, `TenseRule`, `GlossaryEntry`, and
+ *       `Claim` — that a glossary entry has a `term`/`status`/`reason`/
+ *       `alternative`/`caseSensitive` and nothing else, for instance.
+ *
+ *   BINDABLE (rule VALUES — every entry below, every one `true`, all
+ *   consumer-owned, all present in `voice-record.template.jsonc`):
+ *     - which pronouns are forbidden, which tense markers, which specific
+ *       terms are forbidden or preferred and why, which claims are
+ *       registered and whether each needs a `factRef` — the actual data
+ *       that fills the fixed shape above, one consumer's own.
+ *
+ * This file catalogs only the second half — the runtime fields of a
+ * `VoiceRecord` instance — because those are the only things a template can
+ * meaningfully hold a fill-in-the-blank for. It is `Readonly<Record<...>>`,
+ * every entry `bindable: true`, deliberately: `src/field-coverage.test.ts`
+ * still runs a two-way check against it (and a third, currently-vacuous but
+ * future-guarding check that no `bindable: false` entry is ever live in the
+ * template), the same shape as `tokens`' `brand-coverage.test.ts`, so that
+ * if a future field is ever added here as `bindable: false`, the existing
+ * tests immediately start meaning something rather than needing to be
+ * written from scratch.
+ *
+ * A LEAF, NOT A TREE — WHY ARRAYS STOP HERE
+ * ---------------------------------------------------------------------------
+ * `glossary` and `claims` are each catalogued as ONE path, not expanded
+ * into their per-entry fields (`glossary.term`, `glossary.reason`, ...).
+ * Both are variable-length collections of consumer-authored records — the
+ * PER-ENTRY shape (`GlossaryEntry`, `Claim`) is the FIXED half described
+ * above, already enumerated once in `types.ts`; re-stating it here as
+ * catalog entries would just be a second, driftable copy of the same
+ * interface. What's bindable about `glossary` and `claims` is that the
+ * ARRAY exists and a consumer populates it — exactly what one path each,
+ * marked `bindable: true`, records.
+ */
+/**
+ * Every runtime field path a `VoiceRecord` instance carries, keyed by that
+ * same path. `src/field-coverage.test.ts` asserts, in both directions, that
+ * this set and `templates/voice-record.template.jsonc`'s own set of paths
+ * are identical.
+ */
+export const VOICE_FIELDS = {
+    id: {
+        path: "id",
+        bindable: true,
+        description: "This voice's own identifier, e.g. the product or repo it belongs to.",
+    },
+    "rules.person.description": {
+        path: "rules.person.description",
+        bindable: true,
+        description: "Human-readable statement of the person rule, e.g. \"second-person, you-voice\".",
+    },
+    "rules.person.forbiddenPronouns": {
+        path: "rules.person.forbiddenPronouns",
+        bindable: true,
+        description: "The word list `checkCopy` actually scans for — pronouns that contradict the person rule.",
+    },
+    "rules.tense.description": {
+        path: "rules.tense.description",
+        bindable: true,
+        description: "Human-readable statement of the tense rule, e.g. \"present tense, no future promises\".",
+    },
+    "rules.tense.forbiddenMarkers": {
+        path: "rules.tense.forbiddenMarkers",
+        bindable: true,
+        description: "The word list `checkCopy` actually scans for — tense markers that contradict the tense rule.",
+    },
+    "rules.formality": {
+        path: "rules.formality",
+        bindable: true,
+        description: "Which `FormalityLevel` this voice picks. Descriptive only — never read by `checkCopy`.",
+    },
+    "rules.tone": {
+        path: "rules.tone",
+        bindable: true,
+        description: "Free-text tone descriptors, e.g. [\"warm\", \"direct\", \"no jargon\"]. Descriptive only.",
+    },
+    glossary: {
+        path: "glossary",
+        bindable: true,
+        description: "This voice's own forbidden/preferred term list. Per-entry shape (`GlossaryEntry`) is fixed; the entries themselves are this consumer's own.",
+    },
+    claims: {
+        path: "claims",
+        bindable: true,
+        description: "This voice's own claims register. Per-entry shape (`Claim`) is fixed; the entries themselves are this consumer's own.",
+    },
+    patterns: {
+        path: "patterns",
+        bindable: true,
+        description: "This voice's own regex pattern rules (alternation, optional apostrophes, hard character bans). Per-entry shape (`PatternRule`) is fixed; the entries themselves are this consumer's own. Optional — a voice with no pattern rules simply omits this array (`patterns` is the one field in this catalog that is also optional at the `VoiceRecord` TYPE level, not merely defaulted at validation time — see `types.ts`'s `VoiceRecord` doc comment for why).",
+    },
+};
+/**
+ * The literal placeholder value `voice-record.template.jsonc` uses for every
+ * bindable string slot. Loud and specific on purpose — see
+ * `checker.ts`'s `findPlaceholderPaths` for why an unmissable, near-zero-
+ * collision sentinel is exactly what makes the unbound signal trustworthy:
+ * a real voice's copy of the template that forgot to fill in even one slot
+ * still trips it, and nothing a real consumer would plausibly type by
+ * coincidence ever does.
+ */
+export const TEMPLATE_PLACEHOLDER = "REPLACE_ME__VOICE_TEMPLATE_PLACEHOLDER";
+//# sourceMappingURL=fields.js.map

package/dist/voice/fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.js","sourceRoot":"","sources":["../../src/voice/fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AAiBH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAmD;IAC1E,EAAE,EAAE;QACF,IAAI,EAAE,IAAI;QACV,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,sEAAsE;KACpF;IACD,0BAA0B,EAAE;QAC1B,IAAI,EAAE,0BAA0B;QAChC,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,iFAAiF;KAC/F;IACD,gCAAgC,EAAE;QAChC,IAAI,EAAE,gCAAgC;QACtC,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,0FAA0F;KACxG;IACD,yBAAyB,EAAE;QACzB,IAAI,EAAE,yBAAyB;QAC/B,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,yFAAyF;KACvG;IACD,8BAA8B,EAAE;QAC9B,IAAI,EAAE,8BAA8B;QACpC,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,8FAA8F;KAC5G;IACD,iBAAiB,EAAE;QACjB,IAAI,EAAE,iBAAiB;QACvB,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,wFAAwF;KACtG;IACD,YAAY,EAAE;QACZ,IAAI,EAAE,YAAY;QAClB,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,2FAA2F;KACzG;IACD,QAAQ,EAAE;QACR,IAAI,EAAE,UAAU;QAChB,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,6IAA6I;KAC3J;IACD,MAAM,EAAE;QACN,IAAI,EAAE,QAAQ;QACd,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,uHAAuH;KACrI;IACD,QAAQ,EAAE;QACR,IAAI,EAAE,UAAU;QAChB,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,8bAA8b;KAC5c;CACF,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,wCAAwC,CAAC"}

package/dist/voice/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @clossys/writer/voice — public entry point. See README.md for the full
+ * picture: the machinery-vs-values split this package mirrors from
+ * @example/ui/tokens, exactly what `checkCopy` does and does not
+ * attempt, and the `factRef` seam into a separate `strategy` package this
+ * package deliberately does not import from.
+ */
+export { FORMALITY_LEVELS, GLOSSARY_STATUSES, VOICE_SEVERITIES } from "./types.js";
+export type { PersonRule, TenseRule, FormalityLevel, VoiceRules, GlossaryStatus, GlossaryEntry, Claim, VoiceChannel, VoicePattern, PatternRule, VoiceSeverity, VoiceRecord, VoiceFinding, } from "./types.js";
+export { VOICE_FIELDS, TEMPLATE_PLACEHOLDER } from "./fields.js";
+export type { VoiceFieldDefinition } from "./fields.js";
+export { validateVoiceRecordShape, parseVoiceRecord } from "./schema.js";
+export { checkCopy, auditClaimsRegister, isCiBlockingSeverity } from "./checker.js";
+export type { VoiceCheckDimension, VoiceDimensionSkip, VoiceCheckWaiver, WaivedVoiceFinding, VoiceCheckOptions, VoiceCheckReport, } from "./checker.js";
+export { checkVoiceDerivationCoverage } from "./derivation-coverage.js";
+export type { VoiceDerivationCoverageFailureReason, VoiceDerivationCoverageResult } from "./derivation-coverage.js";
+export { checkPatternSafety } from "./internal/pattern-safety.js";
+export type { PatternSafetyIssue, PatternSafetyResult } from "./internal/pattern-safety.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/voice/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/voice/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnF,YAAY,EACV,UAAU,EACV,SAAS,EACT,cAAc,EACd,UAAU,EACV,cAAc,EACd,aAAa,EACb,KAAK,EACL,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,aAAa,EACb,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACjE,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAExD,OAAO,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEzE,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpF,YAAY,EACV,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAMtB,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AACxE,YAAY,EAAE,oCAAoC,EAAE,6BAA6B,EAAE,MAAM,0BAA0B,CAAC;AAQpH,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,YAAY,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC"}