@clossys/writer 0.4.0 → 0.5.1

package/README.md

@@ -66,6 +66,13 @@ remains the only required first-day assessment.
   `VoiceChannel`.
 - `@clossys/writer/voice-record.template.jsonc` is an annotated,
   unbound template to copy into a consumer repository and fill in.
+- `@clossys/writer/front-door` exports `resolveFrontDoorCopy` and its types
+  for browser rendering with immutable shipped English defaults. It accepts
+  only key and nouns; it exposes no registry or approval overrides. Returned
+  values and provenance do not share private catalog state. Package defaults
+  are not consumer approval; consumer registries use the strict root APIs.
+- `@clossys/writer/front-door.en.json` is the shipped English front-door
+  catalog (`FRONT_DOOR_COPY_EN`) as a `CopyRegistry` JSON file.
 
 ```ts
 import {
@@ -107,7 +114,8 @@ registered `CopyRecord`. It exits 0 when clean, 1 when it finds traceability
 issues, and 2 when it cannot run.
 
 This package does not resolve a claim's `factRef`, infer tone or grammar, or
-ship actual product language. Those decisions remain with the consumer and the
+ship actual product language, except for the 63 English front-door defaults in
+"Front-door copy" below. Those decisions remain with the consumer and the
 product's facts system.
 
 ## Resolving copy for a surface
@@ -136,6 +144,51 @@ unknown ID, locale mismatch, draft/retired entry, missing placeholder value,
 or unexpected value. Locale fallback belongs to a consumer-owned registry
 selector, rather than an implicit package policy.
 
+Both `resolveCopyRef` and `createCopyResolver` take an optional third
+argument, `CopyResolveOptions`:
+
+```ts
+import { createCopyResolver, type CopyRegistry, type CopyResolveOptions } from "@clossys/writer";
+
+declare const registry: CopyRegistry;
+const options: CopyResolveOptions = { target: "preview", acceptDelegateInProduction: false, now: new Date() };
+const resolve = createCopyResolver(registry, options);
+```
+
+- `target` (`CopyResolveTarget`, `"preview" | "production"`, default
+  `"production"`) — which audience this resolution is for. An owner-approved
+  entry resolves on either target. A delegate-approved entry resolves freely
+  on `"preview"` but is refused on `"production"`
+  (`"delegate-approval-refused"`) unless the caller opts in, with
+  `acceptDelegateInProduction: true` or with `approvalPlan`.
+- `acceptDelegateInProduction` (default `false`) — only meaningful when
+  `target` is `"production"`; set it to `true` to accept a delegate's
+  sign-off as sufficient to publish, not just to preview.
+- `approvalPlan` (`Uint8Array`, optional) — the bytes of an Advisor plan
+  record, read by the caller. Consulted only for a delegate-approved entry on
+  `"production"` when `acceptDelegateInProduction` is not `true`; see
+  "Production authority from an approved plan" below. Passing it together with
+  `acceptDelegateInProduction: true`, or passing anything that is not a
+  `Uint8Array`, is `"invalid-options"`.
+- `now` (default `new Date()`, evaluated per call) — the clock staleness and
+  expiry are measured against; a test fixes it to make an assertion
+  deterministic.
+
+Three new refusal reasons follow directly from an entry's approval record
+(see "Delegated approval" below for what the record itself contains):
+`"approval-stale"` (the recorded fingerprint no longer matches the entry's
+current text), `"approval-expired"` (a delegate record's `expiresAt` has
+passed), and `"delegate-approval-refused"` (a delegate record on
+`"production"` without `acceptDelegateInProduction: true` or an authorizing
+`approvalPlan`; when a plan was given, the issue's `planRefusal`
+(`CopyResolvePlanRefusal`) says why it did not authorize the entry). A malformed
+`CopyResolveOptions` itself is `"invalid-options"`, checked and refused
+before anything else so a broken options object never silently falls back
+to defaults. An `approved` entry that carries no `approval` record at all
+resolves exactly as it always has, on either target, with no `approval` key
+on the returned `CopyResolution` — this is unchanged, on-by-default
+behavior, not an opt-in.
+
 The default `writer-check` command also runs two registry-only gates against
 the same `CopyRegistry` file a surface renders from:
 
@@ -150,6 +203,513 @@ the same `CopyRegistry` file a surface renders from:
   gate (built-in defaults for `display-heading`, `eyebrow`, and `button` when
   `maxWords` is omitted).
 
+## Site identity copy (`site.name` / `site.tagline`)
+
+A site's name and tagline are a reserved copy kind: two entries in the same
+`CopyRegistry` a surface renders from, under the ids `SITE_NAME_COPY_ID`
+(`"site.name"`) and `SITE_TAGLINE_COPY_ID` (`"site.tagline"`, both listed in
+`SITE_IDENTITY_COPY_IDS`). `resolveSiteIdentity` resolves both through
+`resolveCopyRef`, so the approval policy in "Resolving copy for a surface"
+applies to each without a second code path: the entry must be `approved`, a
+recorded approval must still match the entry's current text, a delegate
+approval must not have expired, and a delegate approval is refused on
+`"production"` unless `acceptDelegateInProduction` is set.
+
+```ts
+import { resolveSiteIdentity, type CopyRegistry } from "@clossys/writer";
+
+declare const registry: CopyRegistry;
+const result = resolveSiteIdentity(registry, { target: "production", locale: "en" });
+
+if (!result.complete) {
+  for (const issue of result.issues) console.error(issue.field, issue.reason, issue.message);
+} else if (result.identity) {
+  const { name, tagline } = result.identity;
+}
+```
+
+The second argument is `CopyResolveOptions` (`target`, `acceptDelegateInProduction`,
+`now`) plus an optional `locale`, which is passed to the resolver as the
+requested locale of each entry. A malformed options object, or a blank or
+non-string `locale`, is reported as `"invalid-options"` rather than thrown.
+
+The result is all-or-nothing. Both entries are always attempted, and every
+problem is returned in one pass, each `SiteIdentityIssue` tagged with the
+`field` (`"name"` or `"tagline"`) it belongs to. `identity` (the two strings)
+and `resolutions` (each field's `CopyResolution`, with its registry, revision,
+locale, source and approval provenance) are present only when both resolved;
+when either fails neither is returned, so a caller cannot end up with half an
+identity. An issue's `reason` is any `CopyResolveIssueReason`, or one of two
+reasons specific to this kind:
+
+- `"site-identity-placeholder"` — the entry declares placeholders, or its text
+  contains braces the resolver would rewrite. A name and a tagline are literal
+  text, not templates.
+- `"site-identity-blank"` — the resolved text is empty after trimming.
+
+`resolveSiteIdentity` does not modify the registry and returns the same result
+for the same registry and options (pass `now` to fix the clock). Consuming it
+is a separate change: a publisher page-metadata builder is not part of this
+package, and nothing here reads a brand-facts record.
+
+## Messaging kit (`messaging.pitch.*` / `messaging.boilerplate.*`)
+
+The short, medium and long "about us" texts a consumer reuses in press,
+footers and email are a reserved copy kind too: six entries in the same
+`CopyRegistry`, under the ids in `MESSAGING_KIT_COPY_IDS`, in this order:
+
+- `messaging.pitch.one-liner`, `messaging.pitch.elevator`,
+  `messaging.pitch.paragraph`
+- `messaging.boilerplate.short`, `messaging.boilerplate.medium`,
+  `messaging.boilerplate.long`
+
+`resolveMessagingKit` resolves each through `resolveCopyRef`, so the approval
+policy in "Resolving copy for a surface" applies unchanged and there is no
+second text store or approval path. No copy ships in this package; the words
+are the consumer's own.
+
+```ts
+import { resolveMessagingKit, type CopyRegistry } from "@clossys/writer";
+
+declare const registry: CopyRegistry;
+const result = resolveMessagingKit(registry, { target: "production", locale: "en" });
+
+if (!result.complete) {
+  for (const issue of result.issues) console.error(issue.field, issue.reason, issue.message);
+} else if (result.kit) {
+  const { pitch, boilerplate } = result.kit;
+  console.log(pitch.oneLiner, boilerplate.long);
+}
+```
+
+The options are the same as for `resolveSiteIdentity`: `CopyResolveOptions`
+plus an optional `locale`; malformed options are reported as
+`"invalid-options"`, not thrown. The result is all-or-nothing: all six entries
+are attempted, every problem is returned in id order with its `field`
+(`"pitch.oneLiner"` through `"boilerplate.long"`), and `kit` and `resolutions`
+exist only when there are no issues. An issue's `reason` is any
+`CopyResolveIssueReason` (each refusal keeps the resolver's own reason), or
+one of three specific to this kind:
+
+- `"messaging-placeholder"` — the entry declares placeholders, or its text
+  contains braces the resolver would rewrite.
+- `"messaging-blank"` — the resolved text is empty after trimming.
+- `"messaging-ladder-order"` — `countCopyWords` does not strictly increase
+  within a ladder (one-liner, elevator, paragraph; then short, medium, long).
+  It is reported on the later field. The two ladders are not compared with
+  each other, and there are no other word targets.
+
+The placeholder-value reasons of `resolveCopyRef` (`"missing-placeholder-value"`
+and `"unexpected-placeholder-value"`) never surface from this function: a kit
+entry is literal text, so every one of them is reported as
+`"messaging-placeholder"`, once per field.
+
+This function judges approval and shape, not wording. For the words of a pitch
+or boilerplate, run `checkCopy` over each resolved text, and run
+`auditClaimsRegister` over the claims register that backs it.
+
+An FAQ and a tagline are out of scope (`site.tagline` already exists).
+
+## Front-door copy (`front-door.*`)
+
+The words on a sign-in page and the pages around it are a reserved copy kind
+too, so each page does not carry its own. An id is
+`front-door.<state>.<slot>`, where the slot is one of `title`, `description`,
+`label`, `primary`, `secondary`, `notice` or `alt`. This version ships 63
+ids, listed in `FRONT_DOOR_COPY_IDS` (typed as `FrontDoorKey`), as
+`FRONT_DOOR_COPY_EN`, a `CopyRegistry` with the id `front-door`, locale `en`
+and revision `1`; the same registry ships as data in
+`@clossys/writer/front-door.en.json`. They are US English and cover these
+states: sign-in, password, code, reset, activation, request-access,
+forgot-password, identifier-not-found, the field notices (identifier-required,
+password-required, code-required, network), the status notices (unavailable,
+rate-limited, locked, expired, signed-out), the weak-password and
+name-required notices, and the pages error, not-found,
+not-authorized, access-pending and service-unavailable, plus an internal-note
+label:
+
+| Id | Text |
+| --- | --- |
+| `front-door.sign-in.title` | Sign in |
+| `front-door.sign-in.description` | Continue to {surface}. |
+| `front-door.sign-in.label` | Email |
+| `front-door.sign-in.primary` | Continue |
+| `front-door.password.title` | Enter your password |
+| `front-door.password.description` | Signing in as {identifier}. |
+| `front-door.password.label` | Password |
+| `front-door.password.primary` | Sign in |
+| `front-door.password.secondary` | Use a different email |
+| `front-door.identifier-not-found.notice` | We couldn’t find an account for that email. Check it and try again. |
+| `front-door.forgot-password.label` | Forgot password? |
+| `front-door.password.notice` | That password isn’t right. Try again. |
+| `front-door.sign-in.alt` | Sign in to {brand} |
+| `front-door.code.title` | Verify your sign-in |
+| `front-door.code.description` | Enter your verification code to continue. |
+| `front-door.code.label` | Code |
+| `front-door.code.primary` | Verify |
+| `front-door.code.secondary` | Send a new code |
+| `front-door.code.notice` | That code isn’t right or has expired. Try again. |
+| `front-door.unavailable.notice` | Sign-in isn’t available right now. Try again in a few minutes. |
+| `front-door.rate-limited.notice` | Too many attempts. Wait a few minutes, then try again. |
+| `front-door.locked.notice` | This account is temporarily locked after too many attempts. Try again later. |
+| `front-door.expired.notice` | Your session expired. Sign in again to continue. |
+| `front-door.signed-out.notice` | You’re signed out. |
+| `front-door.error.title` | This page didn’t load |
+| `front-door.error.description` | Something went wrong. Error: {digest}. |
+| `front-door.error.primary` | Try again |
+| `front-door.not-found.title` | Page not found |
+| `front-door.not-found.description` | This page doesn’t exist or has moved. |
+| `front-door.not-found.primary` | Go to {surface} |
+| `front-door.not-authorized.title` | You don’t have access |
+| `front-door.not-authorized.description` | {identifier} doesn’t have access to {surface}. |
+| `front-door.not-authorized.primary` | Switch account |
+| `front-door.not-authorized.secondary` | Sign out |
+| `front-door.access-pending.title` | Access pending |
+| `front-door.access-pending.description` | Your access to {surface} awaits approval. Check back later. |
+| `front-door.access-pending.primary` | Sign out |
+| `front-door.service-unavailable.title` | {surface} isn’t available |
+| `front-door.service-unavailable.description` | This is temporary. Try again soon. |
+| `front-door.service-unavailable.primary` | Try again |
+| `front-door.request-access.description` | Don’t have an account? |
+| `front-door.request-access.label` | {requestAccessLabel} |
+| `front-door.reset.title` | Reset your password |
+| `front-door.reset.description` | Enter your email and we’ll send you a code. |
+| `front-door.reset.label` | New password |
+| `front-door.reset.primary` | Send code |
+| `front-door.reset.secondary` | Back to sign in |
+| `front-door.reset.notice` | Password updated. Sign in with your new password. |
+| `front-door.activation.title` | Set up your account |
+| `front-door.activation.description` | You’re invited to {surface}. Choose a password to finish. |
+| `front-door.activation.primary` | Activate account |
+| `front-door.activation.notice` | This invitation has expired or was already used. Ask for a new invitation. |
+| `front-door.internal-note.label` | Internal |
+| `front-door.identifier-required.notice` | Enter your email. |
+| `front-door.password-required.notice` | Enter your password. |
+| `front-door.code-required.notice` | Enter the code. |
+| `front-door.network.notice` | Couldn’t reach {surface}. Check your connection and try again. |
+| `front-door.password-weak.notice` | That password isn’t strong enough. Use a longer one you haven’t used anywhere else. |
+| `front-door.reset-code.primary` | Reset password |
+| `front-door.activation.label` | Password |
+| `front-door.activation-first-name.label` | First name |
+| `front-door.activation-last-name.label` | Last name |
+| `front-door.name-required.notice` | Enter your first and last name. |
+
+A `{token}` in a text is a noun from the closed set `FRONT_DOOR_NOUNS`:
+`brand`, `surface`, `identifier`, `digest` and `requestAccessLabel` (typed as
+`FrontDoorNoun`; a caller's values are `FrontDoorNouns`). The defaults are
+marked `approved` and carry no approval record: that is the package's own
+statement about shipped defaults, not a consumer's sign-off.
+
+`resolveFrontDoorCopy(key, nouns)` resolves one entry through
+`resolveCopyRef` and never throws. It hands the resolver only the nouns that
+entry declares, so a known noun the entry does not use is dropped. The result
+is `{ complete, text?, resolution?, issues }`; `text` and `resolution` exist
+only when `issues` is empty. An issue's `reason` is one of:
+
+- `"unknown-copy-id"` — the id is not in `FRONT_DOOR_COPY_IDS`.
+- `"missing-noun"` — a noun the entry declares is absent or blank.
+- `"unknown-noun"` — a noun name outside `FRONT_DOOR_NOUNS`.
+
+```ts
+import { resolveFrontDoorCopy } from "@clossys/writer";
+
+const heading = resolveFrontDoorCopy("front-door.password.title", {});
+const line = resolveFrontDoorCopy("front-door.password.description", {
+  identifier: "ana@example.test",
+  brand: "Acme",
+});
+
+if (line.complete) {
+  console.log(heading.text, line.text); // "Enter your password" "Signing in as ana@example.test."
+} else {
+  for (const issue of line.issues) console.error(issue.reason, issue.noun, issue.message);
+}
+```
+
+A site overrides one entry by registering the same id in its own registry and
+resolving it with `resolveCopyRef`; the defaults are the fallback, not a lock.
+Other states and a JSON file of the catalog are not in this version.
+
+## Delegated approval — who approved this copy, and is it still that text?
+
+`status: "approved"` says an entry may render. It does not say who decided
+that, when, or whether the sentence has since changed underneath the
+decision. `CopyRegistryEntry.approval` (`CopyApproval`) answers all three.
+`writer-check approve` writes the record, so nobody has to hand-edit it into
+a registry or into code; `writer-check approval-state` reports approval state
+set in source instead. `textFingerprint` is a content hash rather than a
+human-maintained counter for the same reason `fingerprint.ts` gives for
+translation provenance.
+
+```json
+{
+  "id": "site.home.title",
+  "text": "Home title copy.",
+  "context": "home hero",
+  "status": "approved",
+  "approval": {
+    "approvedBy": "delegate",
+    "approvedAt": "2026-09-27T00:00:00.000Z",
+    "textFingerprint": "bb46f6c7794911342f760f6e9e46f1f6ca31d0d306c9b301a1069f4b6ff6966c",
+    "fingerprintAlgorithm": "sha256",
+    "delegate": { "id": "delegate-a", "scope": ["site.home"] },
+    "pendingOwnerReview": true,
+    "expiresAt": "2026-10-27T00:00:00.000Z"
+  }
+}
+```
+
+(`textFingerprint` above is `computeCopyFingerprint("Home title copy.")` —
+a 64-character `sha256` hex digest of that entry's own `text`, computed by
+`writer-check approve`.)
+
+- **`approvedBy`** (`CopyApprover`, `"owner" | "delegate"`) — who recorded
+  this approval.
+- **`textFingerprint`**/**`fingerprintAlgorithm`** — pin the record to the
+  EXACT text that was approved. The moment `text` changes, a fresh
+  `computeCopyFingerprint(entry.text)` no longer matches, and the record is
+  `"approval-stale"` — an error, not a warning — until it is approved again.
+  This is the same content-derived-over-hand-maintained argument
+  `fingerprint.ts` already makes for translation staleness, applied to
+  approval staleness instead.
+- **`delegate`** (`CopyDelegateScope`, `{ id, scope }`) — required when
+  `approvedBy` is `"delegate"`, forbidden when it is `"owner"`. `id` is an
+  opaque identifier, never a personal name. `scope` is one or more
+  dot-separated entry-id namespaces the delegate may approve: an entry is in
+  scope when its id equals a scope item or starts with `item + "."` —
+  `["site.home"]` covers `site.home` and `site.home.title`, never
+  `site.homepage.title`. `isEntryInDelegateScope(entryId, scope)` is the
+  exported predicate.
+- **`pendingOwnerReview`** — required (and only meaningful) on a delegate
+  record. A delegate's approval is enough for the entry to resolve — see
+  `target`/`acceptDelegateInProduction` above — but it is a warning
+  (`"approval-pending-owner-review"`), not an error, until an owner durably
+  confirms it. Approving the SAME entry again with `--by owner` REPLACES the
+  delegate's record with the owner's own — that replacement, not a separate
+  "review" action, is how a pending delegate approval is durably confirmed.
+- **`expiresAt`** — delegate records only, an ISO 8601 UTC timestamp
+  strictly after `approvedAt`. Once `now` reaches it, the record is
+  `"approval-expired"` — an error, mutually exclusive with `"approval-stale"`
+  (staleness, the more fundamental problem, takes priority when a record is
+  somehow both).
+
+### Production authority from an approved plan
+
+`acceptDelegateInProduction: true` is a bare flag: it records no reason. The
+other way to let a delegate-approved entry resolve on `"production"` is
+`approvalPlan`, the bytes of an Advisor plan record whose own approval covers
+the delegation. The plan declares it in an optional top-level member,
+`delegatedCopyApproval` (`{ "target": "production", "scopes": ["site.home"] }`),
+defined by the plan contract and its
+[digest definition](https://github.com/clossys/foundry/blob/main/docs/contracts/advisor-plan-digest.md);
+the [contract](https://github.com/clossys/foundry/blob/main/docs/contracts/advisor-plan.json)
+and the digest page live in the public repository, not shipped in this
+package. `scopes` is optional; when present it is a non-empty list of copy
+entry-id namespaces (`site.home`, not `site.home.*`). Writer reads no file:
+the caller passes the bytes.
+
+```ts
+import { createCopyResolver, planDelegateCopyAuthority, type CopyRegistry } from "@clossys/writer";
+
+declare const registry: CopyRegistry;
+declare const planBytes: Uint8Array; // the plan file's bytes, read by the caller
+const authority = planDelegateCopyAuthority(planBytes);
+if (!authority.authorized) throw new Error(`plan does not authorize delegate copy: ${authority.refusal}`);
+const resolved = createCopyResolver(registry, { target: "production", approvalPlan: planBytes })({ id: "home.title" });
+const digest = resolved?.approval?.approvedBy === "delegate" ? resolved.approval.authorizingPlanDigest : undefined;
+```
+
+A delegate-approved entry resolves on `"production"` under `approvalPlan` when
+Writer itself has established each of these from the bytes it was given:
+
+- the bytes are strict JSON: valid UTF-8, no byte-order mark, and no key
+  repeated at any depth;
+- the plan they encode passes the plan contract's schema and its code rules
+  R1 to R12 and, for `delegatedCopyApproval`, the schema's own checks (a
+  non-empty `scopes` list of well-formed namespaces, a known `target`, no
+  unknown key). Repeating a scope item is accepted and only redundant;
+- the plan declares `delegatedCopyApproval`;
+- the plan's latest decision by time has chosen `"approved"` and names a
+  `subjectDigest` equal to the canonical digest Writer computed from those
+  same bytes. Decisions that tie at the same instant must all approve and
+  name one digest; a decision time that does not parse authorizes nothing.
+  The digest covers `delegatedCopyApproval` and its `scopes`, so adding,
+  removing or editing either after an approval leaves the plan unapproved
+  for this purpose until a new approval names the new digest;
+- the entry's id is inside the declared `scopes`, when scopes are declared.
+  An entry is inside a scope when its id equals a scope item or starts with
+  `item + "."`, as for a delegate's own scope: `site.home` covers
+  `site.home` and `site.home.title`, not `site.homepage.title`. Without
+  `scopes` the declaration covers every entry. The entry's own
+  `approval.delegate.scope` is enforced as before, so both lists must hold.
+
+`planDelegateCopyAuthority(bytes)` is the pure function that does this. It
+returns a `PlanDelegateCopyAuthority`: `{ authorized: true, planDigest,
+scopes? }` (`scopes` present only when the plan declares them) or
+`{ authorized: false, refusal, violations? }`, where `refusal` is a
+`PlanDelegateCopyRefusal` and `violations` (only with `"plan-invalid"`) lists
+each failed rule and position, never a value. Nothing in the result quotes the
+plan. The refusal codes:
+
+- `"plan-not-bytes"` — the argument is not a `Uint8Array` (a string, a parsed
+  object, a `DataView` and a `Uint16Array` are all refused).
+- `"plan-unreadable"` — the bytes are not strict JSON (invalid UTF-8, a
+  byte-order mark, a syntax error, or a repeated key).
+- `"plan-invalid"` — the plan fails the contract's schema or code rules, which
+  includes a `delegatedCopyApproval` that is malformed, has an empty `scopes`
+  list or an unknown `target`, and a decision time that does not parse.
+- `"delegated-copy-approval-absent"` — the plan does not declare
+  `delegatedCopyApproval`.
+- `"no-decisions"` — the plan has no decisions.
+- `"decision-time-unparseable"` — a decision's time does not parse (a valid
+  plan cannot reach this; it is kept as a second check).
+- `"latest-decision-not-approved"` — a decision at the latest time has not
+  chosen `"approved"`, so a later deferral or rejection withdraws the grant.
+- `"approval-without-subject-digest"` — an approving decision at the latest
+  time names no well-formed `subjectDigest`, so it binds no bytes.
+- `"latest-decisions-disagree"` — decisions tied at the latest time name
+  different digests.
+- `"subject-digest-mismatch"` — the latest approval names a digest other than
+  this plan's own: the plan changed after it, or the approval belongs to
+  another plan.
+
+`resolveCopyRef` adds one more code of its own, in `CopyResolvePlanRefusal`
+(`PlanDelegateCopyRefusal` plus this value): `"entry-outside-plan-scopes"` —
+the plan authorizes delegate copy but its `scopes` do not include the entry.
+
+**What the resolution reports.** `CopyResolution.approval` is a
+`CopyResolutionApproval`: `{ approvedBy: "owner", pendingOwnerReview: false }`
+or `{ approvedBy: "delegate", pendingOwnerReview, authorizingPlanDigest? }`.
+`authorizingPlanDigest` is the plan's canonical digest and is present only when
+an `approvalPlan` authorized the entry on `"production"`. It is absent when
+`acceptDelegateInProduction` authorized it and on `"preview"`, so a
+plan-authorized resolution can be told from a flag-authorized one by whether
+the key is a string.
+
+**Precedence.** An entry's own `"approval-stale"` and `"approval-expired"`
+outrank every plan outcome. `acceptDelegateInProduction: true` together with
+`approvalPlan` is `"invalid-options"`, so two authorities never compete. On
+`"preview"` the plan is accepted and ignored, and no digest is reported; the
+plan is likewise unread for an owner-approved entry or one with no approval
+record. It is evaluated on each call and not cached.
+
+**What this does not prove.**
+
+- Who wrote the decision. Nothing in the file shows that the latest decision is
+  genuine; that depends on where the plan file is committed and who could
+  commit it. Anyone able to write the file can append an approval naming the
+  digest.
+- Where the bytes came from. The plan is caller-supplied bytes, and Writer
+  verifies no provenance. A caller that controls the call could equally pass
+  `acceptDelegateInProduction: true`; the plan route adds a recorded,
+  digest-bound reason, not a boundary against the caller.
+- Any link between the registry and the plan. The plan names no registry,
+  revision or entry fingerprint, so it covers delegate approvals in scope that
+  were recorded before or after the plan's approval. Entry-level staleness and
+  expiry still apply.
+- Expiry. The plan's approval has none: it holds until the file changes or a
+  later decision withdraws it.
+- More than one subject. One latest decision binds one subject, so a decision
+  naming an apply-bundle digest grants nothing here.
+- A narrow grant. A `delegatedCopyApproval` without `scopes` covers every
+  entry; the grant is visible only as the missing member.
+
+### `writer-check approve` — write or revoke a record
+
+```bash
+writer-check approve <registry-file> <entry-id>... --by owner
+writer-check approve <registry-file> <entry-id>... --by delegate --delegate <id> --scope <ns>[,<ns>...] [--expires <ISO>]
+writer-check approve <registry-file> <entry-id>... --revoke
+```
+
+Every field the command writes is either computed (`approvedAt` from the
+clock, `textFingerprint` from the entry's current `text`) or copied from an
+argument the command validated. Approving sets `status: "approved"`; a
+delegate record is written with `pendingOwnerReview: true`. Multiple entry
+ids are **all-or-nothing**: if any named id is unknown, retired, or (for a
+delegate approval) outside `--scope`, every problem is printed and nothing
+is written, including for the ids that would otherwise have succeeded. The
+command leaves every other field, the key order and `revision` as they
+were, and writes 2-space JSON to a temp file in the same directory before
+renaming it into place. `--revoke` returns every named entry to `"draft"`
+and removes its `approval` record.
+
+Exit codes: `0` written (every named entry approved or revoked, the file on
+disk now reflects it), `1` refused (an unknown, retired, or out-of-scope
+entry id was named; nothing written), `2` could not run (bad arguments, or
+the registry file is missing/unreadable/not valid JSON/fails schema
+validation; nothing written).
+
+### `writer-check approval-state` — is the registry current, and does source respect it?
+
+```bash
+writer-check approval-state <registry-file> <scan-dir> [--extensions <ext>[,<ext>...]] [--format json] [--now <ISO>]
+```
+
+Reports approval state from two independent angles in one run, because
+either can fail without the other noticing:
+
+- **Registry findings** (`assessCopyApprovals`, above): `"approval-stale"`
+  and `"approval-expired"` are errors; a missing record
+  (`"approval-record-missing"`) or a delegate record still
+  `pendingOwnerReview` (`"approval-pending-owner-review"`) is a warning —
+  legitimately approved for now, just not yet durably so.
+- **Source findings** (`scanApprovalBypass`/`checkApprovalBypass`,
+  `approval-bypass.ts`): does consumer code in `scan-dir` route copy through
+  the resolver, or around it? `"approval-set-in-code"` — the code itself
+  declares approval (`status: "approved"`, an `approvedBy`/
+  `pendingOwnerReview` property or member assignment) — and
+  `"copy-read-without-resolver"` — the code imports the registry file and
+  reads its content some way other than passing it whole to
+  `createCopyResolver`/`resolveCopyRef`/`validateCopyRegistryShape`, or
+  calling `parseCopyRegistry` only when its return value is passed to
+  `createCopyResolver` or `resolveCopyRef` — are both errors. An unresolvable registry
+  load (a dynamic `import()`/`require()`, an unbound `require`, a
+  re-export) or a string that merely names the registry file is reported as
+  `unchecked`, not a finding: an incomplete picture, never assumed clean.
+
+**The coupled-file limit, stated plainly**: only files that import
+`@clossys/writer` (any subpath) or import the registry file itself are
+examined. A file that copies registry data without importing either —
+pasted JSON, data fetched at runtime, a registry handed in from an
+uncoupled module — is not examined by this gate. Other known gaps: specifier
+matching is exact (an extension-less or aliased specifier is not
+recognised) and the registry-file match is by basename, which is broad
+enough that a distinctive registry filename (not `index.json`) is worth
+choosing; there is no scope tracking, so a local variable that happens to
+share a flagged binding's name is flagged too; a type assertion or `satisfies`
+between the registry binding and the closing `)` of an allowed resolver call
+is refused (for example `createCopyResolver(registry as CopyRegistry)` is not
+a pass — the resolver accepts `unknown`, so no cast is needed); and only a directly written `"approved"` string
+literal is caught — a value built at runtime is not.
+
+**Verdict precedence**: the same "a violation outranks an incomplete
+picture" ternary `checkAddressability` and `checkPassageComposition` both
+use. `"violated"` whenever at least one error-severity finding exists
+(registry or source), regardless of what is unchecked; `"indeterminate"`
+only with zero error findings and something left unchecked, unparseable, or
+zero files scanned; `"satisfied"` otherwise. Warnings are reported but do
+not change the verdict.
+
+Exit codes: `1` any error-severity finding (a registry error or any
+approval-bypass finding); else `2` any unchecked registry load/reference,
+any file that failed to parse, or zero files scanned; else `0`. Warnings
+never change the exit code.
+
+`--format json` prints exactly one object to stdout:
+
+```
+{
+  verdict: "violated" | "indeterminate" | "satisfied",
+  findings: Array<
+    | { source: "registry", rule, severity, entryId, message }
+    | { source: "source", rule, severity, file, line, message }
+  >,
+  unchecked: Array<{ file, line, kind, detail }>,
+  counts: { errors, warnings, unchecked, filesScanned, coupledFiles }
+}
+```
+
 ## Where this package sits on i18n
 
 "i18n" is two different things, and this package deliberately does only one
@@ -680,12 +1240,28 @@ The root entry point exports the copy registry and traceability surface:
   `createCopyResolver`, `resolveCopyRef`, `checkCopyRecord`, `CopyRecord`,
   `CopyRegistry`, `CopyEntry`, `CopyRegistryEntry`, `CopyRef`, `CopyResolution`,
   `CopyResolver`, `CopySource`, `CopyLocale`, `CopyValue`, `CopyEntryStatus`,
-  `CopyResolveIssue`, `CopyResolveIssueReason`, `CopyResolveResult`,
+  `CopyResolveIssue`, `CopyResolveIssueReason`, `CopyResolveOptions`,
+  `CopyResolveResult`, `CopyResolveTarget`,
   `CopyEntryId`, `CopyFinding`, `CopyRegistryReadIssue`,
   `CopyRegistryReadIssueReason`, `CopyRegistryReadResult`,
   `CopyEntryCheckResult`, `CopyEntrySkip`, `CopyRecordCheckOptions`,
   `CopyRecordCheckReport`, `CopyRecordFinding`, and
   `CopyRecordWaivedFinding`.
+- Site identity (see above): `resolveSiteIdentity`, `SITE_NAME_COPY_ID`,
+  `SITE_TAGLINE_COPY_ID`, `SITE_IDENTITY_COPY_IDS`, `SiteIdentityField`,
+  `SiteIdentityIssue`, `SiteIdentityIssueReason`, `SiteIdentityOptions`, and
+  `SiteIdentityResolution`.
+- Messaging kit (see above): `resolveMessagingKit`, `MESSAGING_KIT_COPY_IDS`,
+  `MESSAGING_PITCH_ONE_LINER_COPY_ID`, `MESSAGING_PITCH_ELEVATOR_COPY_ID`,
+  `MESSAGING_PITCH_PARAGRAPH_COPY_ID`, `MESSAGING_BOILERPLATE_SHORT_COPY_ID`,
+  `MESSAGING_BOILERPLATE_MEDIUM_COPY_ID`, `MESSAGING_BOILERPLATE_LONG_COPY_ID`,
+  `MessagingKit`, `MessagingKitField`, `MessagingKitIssue`,
+  `MessagingKitIssueReason`, `MessagingKitOptions`, `MessagingKitResolution`,
+  and `MessagingKitResolutions`.
+- Front-door copy (see above): `resolveFrontDoorCopy`, `isFrontDoorCopyId`,
+  `FRONT_DOOR_COPY_EN`, `FRONT_DOOR_COPY_IDS`, `FRONT_DOOR_NOUNS`,
+  `FrontDoorKey`, `FrontDoorNoun`, `FrontDoorNouns`, `FrontDoorCopyIssue`,
+  `FrontDoorCopyIssueReason`, and `FrontDoorCopyResolution`.
 - Translation provenance and fingerprinting (see "Where this package sits
   on i18n" above): `CopyTranslationProvenance`, `computeCopyFingerprint`,
   and `COPY_FINGERPRINT_ALGORITHM`.
@@ -726,6 +1302,20 @@ The root entry point exports the copy registry and traceability surface:
   `PassageRegistryReadResult`, `PassageTermReference`,
   `PassageUnclassifiedItem`, `PassageVerdict`, `PassageViolation`, and
   `PassageViolationRule`.
+- Delegated approval (see above): `CopyApproval`, `CopyApprover`,
+  `CopyDelegateScope`, `assessCopyApprovals`, `isEntryInDelegateScope`,
+  `CopyApprovalFinding`, `CopyApprovalFindingRule`, `checkApprovalBypass`,
+  `extractApprovalBypass`, `scanApprovalBypass`, `ApprovalBypassExtractResult`,
+  `ApprovalBypassFinding`, `ApprovalBypassGateResult`, `ApprovalBypassRule`,
+  `ApprovalBypassScanOptions`, `ApprovalBypassScanResult`,
+  `ApprovalBypassUncheckedItem`, and `ApprovalBypassVerdict`. The commands
+  that write and report on this state, `writer-check approve` and
+  `writer-check approval-state`, are CLI-only and not exported from
+  `index.ts`.
+- Production authority from an approved plan (see above):
+  `planDelegateCopyAuthority`, `PlanDelegateCopyAuthority`,
+  `PlanDelegateCopyRefusal`, `CopyResolutionApproval`, and
+  `CopyResolvePlanRefusal`.
 
 The voice names described under Public entry points are re-exported from the
 root and from `@clossys/writer/voice`, including the rule-vocabulary