@wildo-ai/saas-models 1.1.4 → 1.1.5

package/dist/esm/compliance/documents/governed-document-interactions.shared.schemas.js

@@ -0,0 +1,526 @@
+import { z } from "zod";
+import { GovernedDocumentAcceptanceMode, GovernedDocumentClass, GovernedDocumentInteractionKind, GovernedDocumentIsoDateTimeSchema, GovernedDocumentRefSchema, GovernedDocumentReleaseApprovalState, GovernedDocumentReleaseIdentitySchema, GovernedDocumentPublicDocumentKind, governedDocumentReleaseIdentityKey, } from "./governed-documents.shared.schemas.js";
+/**
+ * What it means for a person to have MET a governed document — the record whose absence was
+ * issue #54: *"nothing records which terms release a user accepted"*.
+ *
+ * ## Why this exists in `saas-models` and not beside the release composer
+ *
+ * `composeGovernedDocumentRelease` lives in `saas-specifications` because composing a release
+ * needs the candidate, the definition, the publication variants and the release policy — all
+ * app-creation artifacts. An INTERACTION needs none of them. It needs the release and nothing
+ * else, and its producer is the RUNTIME: measured 2026-09-12, neither `saas-backend-lib` nor
+ * `saas-frontend-lib` depends on `saas-specifications`, so a guard placed there could not be
+ * called from the only layer that will ever call it.
+ *
+ * ## It is a RECORD, not a receipt
+ *
+ * `GovernedDocumentInteractionReceipt` existed here until 2026-08-28 and was deleted with the
+ * rest of the sealed publication machine: it carried digests over canonical bytes, lived in a
+ * content-addressed store, and had never once run. Nothing of that returns. What binds this
+ * record to what the reader actually saw is the RELEASE IDENTITY — `documentRef` +
+ * `releaseId` + `releaseVersion` — which names a file in a commit, readable by anyone with the
+ * repository. That is the binding `.claude/rules/one-source-of-truth.md` Rule 0 admits, and it
+ * merges across branches, which a digest chain cannot.
+ *
+ * ## The subject is the AUDIT ACTOR, deliberately not a field here
+ *
+ * A record carrying its own `subjectRef` beside an audit envelope that already names the actor
+ * is two answers to one question, and they drift. The emitter binds this payload to the acting
+ * principal through the audit trail's own attribution, so *who* is answered once.
+ */
+export var GovernedDocumentInteractionIssueKind;
+(function (GovernedDocumentInteractionIssueKind) {
+    /**
+     * The release does not permit this interaction.
+     *
+     * Refuses, and this is the one place in this file that does. A privacy notice declares
+     * `NOTICE_DELIVERED` / `NOTICE_ACKNOWLEDGED`; recording a `CONTRACT_ACCEPTED` against it would
+     * assert that somebody entered a contract by reading a notice. The artifact would be FALSE, so
+     * the test in `.claude/rules/application-creation-directive.md` answers "fix the artifact" and
+     * a refusal is correct.
+     */
+    GovernedDocumentInteractionIssueKind["INTERACTION_KIND_NOT_PERMITTED"] = "INTERACTION_KIND_NOT_PERMITTED";
+    /**
+     * The release was not in force at the moment claimed.
+     *
+     * Also FALSE rather than unfinished: a record saying a person accepted a release before it took
+     * effect, or after it expired, describes an event that cannot have happened.
+     */
+    GovernedDocumentInteractionIssueKind["RELEASE_NOT_IN_FORCE"] = "RELEASE_NOT_IN_FORCE";
+    /**
+     * An acceptance mode was supplied for an interaction that nobody was ASKED to perform.
+     *
+     * FALSE rather than unfinished, which is why it refuses. {@link GovernedDocumentAcceptanceMode}
+     * names the notice an application gives before asking for assent — a sentence beside a button, an
+     * unticked box, or the document itself. Stamping one onto a `NOTICE_DELIVERED`, which the
+     * APPLICATION performs, or onto a `CONSENT_WITHDRAWN`, which nobody is invited to do, would claim
+     * a notice was given for an act that was never solicited.
+     *
+     * Which kinds admit a mode is settled once by {@link GOVERNED_DOCUMENT_INTERACTION_ADMITS_ACCEPTANCE_MODE}.
+     */
+    GovernedDocumentInteractionIssueKind["ACCEPTANCE_MODE_NOT_APPLICABLE"] = "ACCEPTANCE_MODE_NOT_APPLICABLE";
+    /** The composed record does not satisfy {@link GovernedDocumentInteractionSchema}. */
+    GovernedDocumentInteractionIssueKind["RECORD_INVALID"] = "RECORD_INVALID";
+})(GovernedDocumentInteractionIssueKind || (GovernedDocumentInteractionIssueKind = {}));
+/**
+ * TRUE statements about a coherent record whose surrounding WORKFLOW is unfinished.
+ *
+ * An advisory never stops the mechanism — see the issue/advisory split in
+ * `.claude/rules/application-creation-directive.md`. It travels with the record so the decision it
+ * bears on is taken where the consequence is, rather than by refusing here.
+ */
+export var GovernedDocumentInteractionAdvisoryKind;
+(function (GovernedDocumentInteractionAdvisoryKind) {
+    /**
+     * The release had not been approved when this interaction was recorded.
+     *
+     * The record is honest and the workflow is unfinished, so this MARKS rather than refuses — and
+     * the mark is carried on the record itself (`releaseApprovalState`) rather than only reported,
+     * because the question a reviewer will ask later is *was this approved AT THE TIME*, which
+     * nothing can reconstruct from a release that has since been approved.
+     *
+     * Where the refusal belongs instead is the READ that decides whether to show a person the
+     * document at all: `resolveEffectiveDocumentRelease(..., { requireApproved: true })`. That is a
+     * Gate 3 arming point per `one-source-of-truth.md` D5 — "an application may face a real user" —
+     * and it withholds an unapproved release from the surface, so no interaction with one is ever
+     * offered. Refusing HERE as well would only mean losing the evidence that it happened anyway.
+     */
+    GovernedDocumentInteractionAdvisoryKind["RELEASE_NOT_APPROVED"] = "RELEASE_NOT_APPROVED";
+    /**
+     * The act was solicited, and the record cannot say what notice preceded it.
+     *
+     * TRUE but unfinished: the interaction happened and every other field of the record stands. What
+     * is missing is the one thing that distinguishes a person who scrolled to the end of thirteen
+     * clauses from a person who pressed a button beside a sentence — so a reviewer reading this record
+     * learns only that a release id was accepted, which is the gap #1382 is about.
+     *
+     * It MARKS rather than refuses because the remedy is a surface declaring its mode, which is
+     * authoring work — `.claude/rules/application-creation-directive.md`: a required declaration whose
+     * absence stops the mechanism is the defect, not the guard. The social sign-up path (#1383) is the
+     * live instance, and this advisory is what makes its silence visible rather than indistinguishable
+     * from a form acceptance.
+     */
+    GovernedDocumentInteractionAdvisoryKind["ACCEPTANCE_MODE_NOT_RECORDED"] = "ACCEPTANCE_MODE_NOT_RECORDED";
+})(GovernedDocumentInteractionAdvisoryKind || (GovernedDocumentInteractionAdvisoryKind = {}));
+/**
+ * Which interactions an ACCEPTANCE MODE can describe — total over the vocabulary, so a kind added
+ * tomorrow is classified deliberately rather than inheriting whichever answer the code fell through
+ * to.
+ *
+ * The question each row answers is the same one: **was this person ASKED?**
+ * {@link GovernedDocumentAcceptanceMode} names the notice an application gives before soliciting
+ * assent, so it describes an act that was solicited and nothing else.
+ */
+export const GOVERNED_DOCUMENT_INTERACTION_ADMITS_ACCEPTANCE_MODE = {
+    /** The APPLICATION acted. Nobody was asked anything, so no notice preceded it. */
+    [GovernedDocumentInteractionKind.NOTICE_DELIVERED]: false,
+    /** The person acted on an invitation to confirm they had seen it — the mode names that invitation. */
+    [GovernedDocumentInteractionKind.NOTICE_ACKNOWLEDGED]: true,
+    /** The canonical case: a registration surface asked for assent in one of the three shapes. */
+    [GovernedDocumentInteractionKind.CONTRACT_ACCEPTED]: true,
+    /** Assent to a purpose, solicited the same way and describable by the same vocabulary. */
+    [GovernedDocumentInteractionKind.CONSENT_GIVEN]: true,
+    /**
+     * A withdrawal is the person acting on their OWN initiative — nothing solicits it, and a mode
+     * claiming a notice preceded it would describe an invitation nobody extended. Withdrawal must be
+     * as easy as giving, which is a property of the surface that offers it rather than a notice given
+     * before it.
+     */
+    [GovernedDocumentInteractionKind.CONSENT_WITHDRAWN]: false,
+};
+/**
+ * One person, one governed-document release, one interaction, one instant.
+ *
+ * Every field but `interactionKind` and `occurredAt` is DERIVED from the release, for the same
+ * reason the release derives most of itself from the accepted definition: restating `locale`,
+ * `jurisdictionRefs` or `documentClass` here would create a second way to disagree with the
+ * release, and the disagreement would be invisible. They are copied onto the record rather than
+ * left to a join because a record must stay readable when the release file moves on — which is
+ * the whole point of binding an acceptance to a VERSION.
+ */
+export const GovernedDocumentInteractionSchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    interactionKind: z.enum(GovernedDocumentInteractionKind),
+    release: GovernedDocumentReleaseIdentitySchema,
+    documentClass: z.enum(GovernedDocumentClass),
+    locale: z.string().trim().min(2),
+    jurisdictionRefs: z.array(GovernedDocumentRefSchema),
+    /** The release's standing AT THE MOMENT OF THE INTERACTION. Not re-derivable later. */
+    releaseApprovalState: z.enum(GovernedDocumentReleaseApprovalState),
+    /**
+     * HOW the act was obtained — the notice the person was given before performing it.
+     *
+     * Without it the strongest statement an operator can make about a recorded acceptance is *"a
+     * release id was accepted"*, which is the same sentence for somebody who read the document to its
+     * end and somebody who pressed a button beside a link. Enforceability turns on exactly this
+     * distinction, so a consent record that cannot make it is evidence of the act and not of the
+     * assent (#1382).
+     *
+     * OPTIONAL, and its absence is a fact rather than a default: it means the surface that obtained
+     * the act did not say how it asked. `advisoryKinds` carries
+     * {@link GovernedDocumentInteractionAdvisoryKind.ACCEPTANCE_MODE_NOT_RECORDED} on exactly those
+     * records, so a silent surface reads as silent rather than as the weakest mode — which it would
+     * if a default were stamped here.
+     *
+     * Absent BY RULE, with no advisory, on the kinds
+     * {@link GOVERNED_DOCUMENT_INTERACTION_ADMITS_ACCEPTANCE_MODE} marks `false`.
+     */
+    acceptanceMode: z.enum(GovernedDocumentAcceptanceMode).optional(),
+    occurredAt: GovernedDocumentIsoDateTimeSchema,
+});
+/**
+ * The slice of a release that a CONSENT SURFACE and an INTERACTION RECORD both need — and it is
+ * browser-safe, which turned out to be a property rather than a compromise.
+ *
+ * {@link composeGovernedDocumentInteraction} reads `allowedInteractionKinds`, the effective
+ * interval, `approvalState`, `identity`, `documentClass`, `locale` and `jurisdictionRefs`. It never
+ * reads `governanceScope` or `approvalDecisions` — the two fields
+ * {@link projectGovernedDocumentPublicRelease} already withholds from public consumers as internal
+ * custody detail. So the fields the mechanism needs and the fields a browser may hold are the SAME
+ * SET, and one shape can travel the whole chain: the application authors it on
+ * `compliance.governedDocumentReleases`, the backend composes records from it, and the frontend
+ * decides from it whether to render a consent control at all.
+ *
+ * Distinct from `GovernedDocumentPublicReleaseProjection`, which is narrower still and answers a
+ * different question — how to ROUTE and DISPLAY a published document. It carries neither
+ * `allowedInteractionKinds` nor `approvalState`, so a consent surface cannot be built from it.
+ */
+export const GovernedDocumentInteractionSurfaceSchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    identity: GovernedDocumentReleaseIdentitySchema,
+    documentClass: z.enum(GovernedDocumentClass),
+    locale: z.string().trim().min(2),
+    jurisdictionRefs: z.array(GovernedDocumentRefSchema),
+    /** What a person may DO with this document. An empty array means "read only"; nothing may be recorded. */
+    allowedInteractionKinds: z.array(z.enum(GovernedDocumentInteractionKind)),
+    approvalState: z.enum(GovernedDocumentReleaseApprovalState),
+    effectiveAt: GovernedDocumentIsoDateTimeSchema,
+    expiresAt: GovernedDocumentIsoDateTimeSchema.optional(),
+    /**
+     * The interactions this release says a person must perform AGAIN, because it replaced an earlier
+     * release with a change that mattered (#1258, Step 2 / R7).
+     *
+     * Projected from `materialityDecision.requiredInteractionKinds` — the governance answer a
+     * superseding release already owes ("did the change matter enough that the audience must meet the
+     * document again?"). Only the KINDS travel: the decision identity is private custody detail and this
+     * shape reaches an unauthenticated browser. Empty for a first release and for a replacement judged
+     * immaterial — a typo fix does not re-ask anybody.
+     *
+     * `.default([])` so a surface generated before this field existed still parses, and means exactly
+     * what its absence meant then: nothing is renewed.
+     */
+    renewedInteractionKinds: z.array(z.enum(GovernedDocumentInteractionKind)).default([]),
+});
+/** Explicit allow-list projection from a composed release to what a consent surface may hold. */
+export const projectGovernedDocumentInteractionSurface = (release) => GovernedDocumentInteractionSurfaceSchema.parse({
+    schemaVersion: 1,
+    identity: release.identity,
+    documentClass: release.documentClass,
+    locale: release.locale,
+    jurisdictionRefs: release.jurisdictionRefs,
+    allowedInteractionKinds: release.allowedInteractionKinds,
+    approvalState: release.approvalState,
+    effectiveAt: release.effectiveAt,
+    ...(release.expiresAt ? { expiresAt: release.expiresAt } : {}),
+    renewedInteractionKinds: release.materialityDecision?.requiredInteractionKinds ?? [],
+});
+/**
+ * Is this release in force at that instant?
+ *
+ * ONE implementation, used by {@link composeGovernedDocumentInteraction} here and by
+ * `resolveEffectiveDocumentRelease` in `saas-specifications` — which depends on this package, so
+ * the read side and the record side cannot disagree about what "in force" means. They did, briefly:
+ * writing the record's guard reproduced the interval comparison, and two copies of a half-open
+ * interval is exactly the shape where one of them ends up with `<=`.
+ *
+ * HALF-OPEN — `[effectiveAt, expiresAt)`. A release takes effect at the instant it names, and the
+ * one that replaces it takes effect at the instant the old one expires, so the boundary belongs to
+ * exactly one of them. An unparsable instant is NOT in force: it is not a time.
+ */
+export function governedDocumentReleaseIsInForce(release, at) {
+    const instant = Date.parse(at);
+    if (Number.isNaN(instant))
+        return false;
+    if (instant < Date.parse(release.effectiveAt))
+        return false;
+    return release.expiresAt === undefined || instant < Date.parse(release.expiresAt);
+}
+/**
+ * Whether an application shows, and asks people to accept, governed documents nobody has approved.
+ *
+ * ONE switch for every surface that puts a governed document in front of a person: the public page
+ * (`/privacy`, `/terms`), the registration acceptance control, the first-session acceptance gate, the
+ * consent panel's privacy-notice link, the backend's owed-acceptance derivation and the notice-delivery
+ * record. It is read from the application's configuration (`compliance.governedDocumentApprovalGate`)
+ * through {@link requiresApprovedGovernedDocuments}, never passed per call site, so the page and the
+ * acceptance surfaces cannot be armed separately (#1565). Armed on the page alone, `/terms` would answer
+ * "unavailable" while sign-up asked people to accept those same terms.
+ *
+ * What it does NOT govern is the RECORD of an act that happened: `recordGovernedDocumentAcceptances`
+ * records what a person submitted, and marks an unapproved release with `RELEASE_NOT_APPROVED` rather
+ * than dropping it, because refusing there would only lose the evidence.
+ *
+ * This is the gate point `.claude/rules/one-source-of-truth.md` D5 keeps MARKED: arming it is part of
+ * Gate 3's membership test ("an application may face a real user").
+ */
+export var GovernedDocumentApprovalGate;
+(function (GovernedDocumentApprovalGate) {
+    /**
+     * The framework default, and the posture while an application is being built: every release in
+     * force is shown and asked for, whatever its approval state. An unapproved release still says so
+     * (`approvalState` travels with it, and a record of an interaction with it carries
+     * `RELEASE_NOT_APPROVED`), so nothing unapproved is ever presented as approved — it is only not
+     * withheld.
+     */
+    GovernedDocumentApprovalGate["UNARMED"] = "unarmed";
+    /**
+     * Nothing unapproved reaches a person. An unapproved release is neither shown nor asked for, and no
+     * draft stands in for a document that has no approved release. Arm it when the application faces
+     * real users.
+     *
+     * With no approved release of a contractual document, sign-up asks for nothing. Whether an
+     * application should be allowed to go live in that state is part of Gate 3's arming decision, not of
+     * this switch.
+     */
+    GovernedDocumentApprovalGate["ARMED"] = "armed";
+})(GovernedDocumentApprovalGate || (GovernedDocumentApprovalGate = {}));
+/**
+ * Whether the application's configuration withholds unapproved governed documents — the ONE reading of
+ * {@link GovernedDocumentApprovalGate} every serving and asking surface goes through.
+ *
+ * Takes the configuration's `compliance` section (or nothing) rather than a boolean, so a call site
+ * cannot supply its own answer. An absent section, or an absent member, is the schema default: unarmed.
+ *
+ * assurance-control: WILDO.PRIVACY.CONSENT_RECORD — once armed, no person is shown or asked to accept a
+ * governed document that has not been approved, on any surface.
+ */
+export function requiresApprovedGovernedDocuments(compliance) {
+    return compliance?.governedDocumentApprovalGate === GovernedDocumentApprovalGate.ARMED;
+}
+/**
+ * Every release in force at that instant — what a registration surface asks when it needs to know
+ * which documents a person is meeting right now.
+ *
+ * Deliberately NOT the same question as `resolveEffectiveDocumentRelease`, which picks the ONE
+ * winning release for a given document, locale and jurisdiction set. This one spans documents and
+ * is total over what the application declared, so a document added to the config tomorrow is
+ * delivered without anyone editing a list.
+ *
+ * `requireApproved` drops releases nobody has approved. A surface that SHOWS or ASKS for a document
+ * passes {@link requiresApprovedGovernedDocuments}; a recorder of an act that already happened passes
+ * nothing.
+ */
+export function selectGovernedDocumentReleasesInForce(releases, at, options) {
+    const requireApproved = options?.requireApproved ?? false;
+    return releases.filter((release) => governedDocumentReleaseIsInForce(release, at)
+        && (!requireApproved || release.approvalState === GovernedDocumentReleaseApprovalState.APPROVED));
+}
+/** Why an acceptance is owed. Two different messages to the person, so two members. */
+export var GovernedDocumentAcceptanceOwedReason;
+(function (GovernedDocumentAcceptanceOwedReason) {
+    /** They have never accepted any release of this document — a stale sign-up form, or an older account. */
+    GovernedDocumentAcceptanceOwedReason["NEVER_ACCEPTED"] = "NEVER_ACCEPTED";
+    /** A release replaced the one they accepted with a change judged to require acceptance again. */
+    GovernedDocumentAcceptanceOwedReason["MATERIALLY_CHANGED"] = "MATERIALLY_CHANGED";
+})(GovernedDocumentAcceptanceOwedReason || (GovernedDocumentAcceptanceOwedReason = {}));
+/**
+ * Which documents a person owes an acceptance of, at an instant (#1258, Step 2 / R7).
+ *
+ * TOTAL over what the application declared: every in-force release that permits `CONTRACT_ACCEPTED`
+ * is considered, so a document added to the configuration tomorrow is owed by everyone the next time
+ * they arrive, with no list to maintain (`.claude/rules/derive-before-you-ask.md` rule 3).
+ *
+ * ## What counts as having accepted it
+ *
+ * Any release of the DOCUMENT — the join is `documentRef`, never `releaseId`. A release is one locale
+ * and jurisdiction pair, so keying on it would re-ask everyone who changed language: accepting the
+ * French terms is accepting the terms.
+ *
+ * ## When an earlier acceptance stops counting
+ *
+ * Only when a release of the document says so — its `renewedInteractionKinds` includes
+ * `CONTRACT_ACCEPTED`, projected from the materiality decision that replacement owed. Then an acceptance
+ * counts only if it happened at or after that release took effect. Compared on TIME, not on
+ * `releaseVersion`, because a version is counted per variant and comparing one variant's number with
+ * another's means nothing.
+ *
+ * ## The material change need not still be IN FORCE — it is transitive across replacements
+ *
+ * A replacement takes effect at the instant its predecessor expires, so only the NEWEST release is ever in
+ * force. Reading materiality from the in-force releases alone would therefore forget it: accept v1 in
+ * January, v2 changes the terms materially in March, v3 fixes a typo in June — and in July only v3 is in
+ * force, its renewal set is empty, and a person who never accepted v2's change is told they owe nothing.
+ * So the latest material change is taken over EVERY declared release of the document that took effect at or
+ * before `at`, expired or not. A release that takes effect AFTER `at` has not happened yet and never counts.
+ *
+ * What the application must keep for this to hold: the superseded releases stay declared. They do — the
+ * releases are recorded as data and only ever appended to.
+ *
+ * ## With the approval gate armed
+ *
+ * `requireApproved` ({@link requiresApprovedGovernedDocuments}) owes only APPROVED releases: a person is
+ * never asked to accept what the public page would refuse to show. A material change still counts from
+ * every declared release, approved or not, because the approved release that follows carries it.
+ *
+ * A pure function of its inputs: it reads nothing and writes nothing.
+ */
+export function governedDocumentAcceptancesOwed(input) {
+    const acceptable = selectGovernedDocumentReleasesInForce(input.releases, input.at, { requireApproved: input.requireApproved })
+        .filter((release) => release.allowedInteractionKinds.includes(GovernedDocumentInteractionKind.CONTRACT_ACCEPTED));
+    const byDocument = new Map();
+    for (const release of acceptable) {
+        const documentRef = release.identity.document.documentRef;
+        byDocument.set(documentRef, [...(byDocument.get(documentRef) ?? []), release]);
+    }
+    const atMs = Date.parse(input.at);
+    const owed = [];
+    for (const [documentRef, releases] of byDocument) {
+        const acceptedAtMs = input.accepted
+            .filter((record) => record.documentRef === documentRef)
+            .map((record) => new Date(record.acceptedAt).getTime())
+            .filter((ms) => !Number.isNaN(ms));
+        if (acceptedAtMs.length === 0) {
+            owed.push({ documentRef, reason: GovernedDocumentAcceptanceOwedReason.NEVER_ACCEPTED, releases });
+            continue;
+        }
+        const latestAcceptance = Math.max(...acceptedAtMs);
+        const latestMaterialChange = Math.max(...input.releases
+            .filter((release) => release.identity.document.documentRef === documentRef
+            && release.allowedInteractionKinds.includes(GovernedDocumentInteractionKind.CONTRACT_ACCEPTED)
+            && release.renewedInteractionKinds.includes(GovernedDocumentInteractionKind.CONTRACT_ACCEPTED)
+            && Date.parse(release.effectiveAt) <= atMs)
+            .map((release) => Date.parse(release.effectiveAt)), Number.NEGATIVE_INFINITY);
+        if (latestMaterialChange > latestAcceptance) {
+            owed.push({ documentRef, reason: GovernedDocumentAcceptanceOwedReason.MATERIALLY_CHANGED, releases });
+        }
+    }
+    return owed;
+}
+/**
+ * Compose the record of one interaction, refusing what would be false and marking what is merely
+ * unfinished.
+ *
+ * Pure: it reads the release and the two decided values, and writes nothing. The caller decides
+ * where the record goes — today, an auditable event.
+ */
+export function composeGovernedDocumentInteraction(composition) {
+    const { release, interactionKind, acceptanceMode, occurredAt } = composition;
+    const issues = [];
+    const advisories = [];
+    const releaseKey = governedDocumentReleaseIdentityKey(release.identity);
+    if (!release.allowedInteractionKinds.includes(interactionKind)) {
+        issues.push({
+            kind: GovernedDocumentInteractionIssueKind.INTERACTION_KIND_NOT_PERMITTED,
+            message: `${releaseKey} permits ${release.allowedInteractionKinds.join(", ") || "no interaction"}, so ${interactionKind} `
+                + "cannot be recorded against it.",
+        });
+    }
+    if (!governedDocumentReleaseIsInForce(release, occurredAt)) {
+        issues.push({
+            kind: GovernedDocumentInteractionIssueKind.RELEASE_NOT_IN_FORCE,
+            message: `${releaseKey} is in force from ${release.effectiveAt}${release.expiresAt ? ` until ${release.expiresAt}` : ""}, `
+                + `so nobody can have interacted with it at ${occurredAt}.`,
+        });
+    }
+    const admitsAcceptanceMode = GOVERNED_DOCUMENT_INTERACTION_ADMITS_ACCEPTANCE_MODE[interactionKind];
+    if (acceptanceMode !== undefined && !admitsAcceptanceMode) {
+        issues.push({
+            kind: GovernedDocumentInteractionIssueKind.ACCEPTANCE_MODE_NOT_APPLICABLE,
+            message: `Nobody is asked to perform a ${interactionKind}, so recording it as obtained by ${acceptanceMode} would `
+                + `claim a notice was given for an act that was never solicited (${releaseKey}).`,
+        });
+    }
+    if (acceptanceMode === undefined && admitsAcceptanceMode) {
+        advisories.push({
+            kind: GovernedDocumentInteractionAdvisoryKind.ACCEPTANCE_MODE_NOT_RECORDED,
+            message: `The surface that obtained this ${interactionKind} with ${releaseKey} did not say how it asked, so the record `
+                + "cannot distinguish a document read to its end from a sentence beside a button.",
+        });
+    }
+    if (release.approvalState === GovernedDocumentReleaseApprovalState.UNAPPROVED) {
+        advisories.push({
+            kind: GovernedDocumentInteractionAdvisoryKind.RELEASE_NOT_APPROVED,
+            message: `${releaseKey} had not been approved when this ${interactionKind} was recorded. The record stands and says so; `
+                + "withholding an unapproved release from a real reader is the read-side gate (`requireApproved`), armed at Gate 3.",
+        });
+    }
+    if (issues.length > 0)
+        return { interaction: undefined, issues, advisories };
+    const parsed = GovernedDocumentInteractionSchema.safeParse({
+        schemaVersion: 1,
+        interactionKind,
+        release: release.identity,
+        documentClass: release.documentClass,
+        locale: release.locale,
+        jurisdictionRefs: release.jurisdictionRefs,
+        releaseApprovalState: release.approvalState,
+        ...(acceptanceMode !== undefined ? { acceptanceMode } : {}),
+        occurredAt,
+    });
+    if (!parsed.success) {
+        return {
+            interaction: undefined,
+            issues: [
+                {
+                    kind: GovernedDocumentInteractionIssueKind.RECORD_INVALID,
+                    message: `The composed interaction with ${releaseKey} is not a valid record: ${parsed.error.issues.map((issue) => issue.message).join("; ")}`,
+                },
+            ],
+            advisories,
+        };
+    }
+    return { interaction: parsed.data, issues: [], advisories };
+}
+/**
+ * The ONE public document to render for a governed-document ref at an instant, or `undefined`.
+ *
+ * Total over what the application declared, so a document added to the configuration tomorrow is
+ * served without anyone editing a list — the same shape as
+ * {@link selectGovernedDocumentReleasesInForce}, and for the same reason.
+ *
+ * `requireApproved` **IS THE GATE POINT**.
+ *
+ * It defaults to `false` — deliberately, and this is the posture recorded in
+ * `.claude/rules/one-source-of-truth.md` D5: critical gate points stay MARKED in every mechanism so
+ * they can be switched on when the posture changes, and under the current YOLO posture they notify
+ * and proceed. Arming it is part of **Gate 3**'s membership test ("an application may face a real
+ * user") — the posture ends where a real user begins, by definition rather than by anyone
+ * remembering. A caller serving a page to the public passes `true`; a caller previewing what the
+ * lane drafted passes nothing.
+ *
+ * When several releases of one document are in force the LATEST EFFECTIVE wins, and ties break on
+ * the higher `releaseVersion`. Two in force at once is an authoring mistake rather than a state to
+ * refuse on a read path: refusing would take the page down over an overlap a reader cannot see,
+ * which is worse than showing the newer of two documents the publisher approved.
+ *
+ * ## The draft fallback, and its two limits (#968 decision 5)
+ *
+ * A document the application has drafted and never released is served as its UNRELEASED DRAFT, so
+ * neither a missing approval nor a missing release ever leaves a page with nothing — the page marks it
+ * as a draft. The fallback applies only when the application holds NO release of that document:
+ *
+ * - a release that exists but is not in force (scheduled, or expired) is a date, not an absence, and
+ *   showing the draft in its place would present text the application already decided to replace;
+ * - with the gate ARMED there is no fallback at all — "serve nothing unapproved to a real reader" has
+ *   no answer less approved than a draft.
+ */
+export function resolveInForcePublicDocument(documents, documentRef, at, options) {
+    const requireApproved = options?.requireApproved ?? false;
+    const released = documents.filter((document) => document.kind === GovernedDocumentPublicDocumentKind.RELEASED && document.release.identity.document.documentRef === documentRef);
+    const candidates = released.filter((document) => governedDocumentReleaseIsInForce(document.release, at)
+        && (!requireApproved || document.approvalState === GovernedDocumentReleaseApprovalState.APPROVED));
+    if (candidates.length === 0) {
+        if (released.length > 0 || requireApproved)
+            return undefined;
+        return documents.find((document) => document.kind === GovernedDocumentPublicDocumentKind.UNRELEASED_DRAFT && document.documentRef === documentRef);
+    }
+    return candidates.reduce((winner, candidate) => {
+        const winnerEffective = Date.parse(winner.release.effectiveAt);
+        const candidateEffective = Date.parse(candidate.release.effectiveAt);
+        if (candidateEffective !== winnerEffective)
+            return candidateEffective > winnerEffective ? candidate : winner;
+        return candidate.release.identity.releaseVersion > winner.release.identity.releaseVersion ? candidate : winner;
+    });
+}
+//# sourceMappingURL=governed-document-interactions.shared.schemas.js.map

package/dist/esm/compliance/documents/governed-document-interactions.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"governed-document-interactions.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/compliance/documents/governed-document-interactions.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\n\nimport {\n  GovernedDocumentAcceptanceMode,\n  GovernedDocumentClass,\n  GovernedDocumentInteractionKind,\n  GovernedDocumentIsoDateTimeSchema,\n  GovernedDocumentRefSchema,\n  GovernedDocumentReleaseApprovalState,\n  GovernedDocumentReleaseIdentitySchema,\n  GovernedDocumentPublicDocumentKind,\n  governedDocumentReleaseIdentityKey,\n  type GovernedDocumentPublicDocument,\n  type GovernedDocumentReleasedPublicDocument,\n  type GovernedDocumentRelease,\n} from \"./governed-documents.shared.schemas\";\n\n/**\n * What it means for a person to have MET a governed document — the record whose absence was\n * issue #54: *\"nothing records which terms release a user accepted\"*.\n *\n * ## Why this exists in `saas-models` and not beside the release composer\n *\n * `composeGovernedDocumentRelease` lives in `saas-specifications` because composing a release\n * needs the candidate, the definition, the publication variants and the release policy — all\n * app-creation artifacts. An INTERACTION needs none of them. It needs the release and nothing\n * else, and its producer is the RUNTIME: measured 2026-09-12, neither `saas-backend-lib` nor\n * `saas-frontend-lib` depends on `saas-specifications`, so a guard placed there could not be\n * called from the only layer that will ever call it.\n *\n * ## It is a RECORD, not a receipt\n *\n * `GovernedDocumentInteractionReceipt` existed here until 2026-08-28 and was deleted with the\n * rest of the sealed publication machine: it carried digests over canonical bytes, lived in a\n * content-addressed store, and had never once run. Nothing of that returns. What binds this\n * record to what the reader actually saw is the RELEASE IDENTITY — `documentRef` +\n * `releaseId` + `releaseVersion` — which names a file in a commit, readable by anyone with the\n * repository. That is the binding `.claude/rules/one-source-of-truth.md` Rule 0 admits, and it\n * merges across branches, which a digest chain cannot.\n *\n * ## The subject is the AUDIT ACTOR, deliberately not a field here\n *\n * A record carrying its own `subjectRef` beside an audit envelope that already names the actor\n * is two answers to one question, and they drift. The emitter binds this payload to the acting\n * principal through the audit trail's own attribution, so *who* is answered once.\n */\nexport enum GovernedDocumentInteractionIssueKind {\n  /**\n   * The release does not permit this interaction.\n   *\n   * Refuses, and this is the one place in this file that does. A privacy notice declares\n   * `NOTICE_DELIVERED` / `NOTICE_ACKNOWLEDGED`; recording a `CONTRACT_ACCEPTED` against it would\n   * assert that somebody entered a contract by reading a notice. The artifact would be FALSE, so\n   * the test in `.claude/rules/application-creation-directive.md` answers \"fix the artifact\" and\n   * a refusal is correct.\n   */\n  INTERACTION_KIND_NOT_PERMITTED = \"INTERACTION_KIND_NOT_PERMITTED\",\n  /**\n   * The release was not in force at the moment claimed.\n   *\n   * Also FALSE rather than unfinished: a record saying a person accepted a release before it took\n   * effect, or after it expired, describes an event that cannot have happened.\n   */\n  RELEASE_NOT_IN_FORCE = \"RELEASE_NOT_IN_FORCE\",\n  /**\n   * An acceptance mode was supplied for an interaction that nobody was ASKED to perform.\n   *\n   * FALSE rather than unfinished, which is why it refuses. {@link GovernedDocumentAcceptanceMode}\n   * names the notice an application gives before asking for assent — a sentence beside a button, an\n   * unticked box, or the document itself. Stamping one onto a `NOTICE_DELIVERED`, which the\n   * APPLICATION performs, or onto a `CONSENT_WITHDRAWN`, which nobody is invited to do, would claim\n   * a notice was given for an act that was never solicited.\n   *\n   * Which kinds admit a mode is settled once by {@link GOVERNED_DOCUMENT_INTERACTION_ADMITS_ACCEPTANCE_MODE}.\n   */\n  ACCEPTANCE_MODE_NOT_APPLICABLE = \"ACCEPTANCE_MODE_NOT_APPLICABLE\",\n  /** The composed record does not satisfy {@link GovernedDocumentInteractionSchema}. */\n  RECORD_INVALID = \"RECORD_INVALID\",\n}\n\nexport interface GovernedDocumentInteractionIssue {\n  readonly kind: GovernedDocumentInteractionIssueKind;\n  readonly message: string;\n}\n\n/**\n * TRUE statements about a coherent record whose surrounding WORKFLOW is unfinished.\n *\n * An advisory never stops the mechanism — see the issue/advisory split in\n * `.claude/rules/application-creation-directive.md`. It travels with the record so the decision it\n * bears on is taken where the consequence is, rather than by refusing here.\n */\nexport enum GovernedDocumentInteractionAdvisoryKind {\n  /**\n   * The release had not been approved when this interaction was recorded.\n   *\n   * The record is honest and the workflow is unfinished, so this MARKS rather than refuses — and\n   * the mark is carried on the record itself (`releaseApprovalState`) rather than only reported,\n   * because the question a reviewer will ask later is *was this approved AT THE TIME*, which\n   * nothing can reconstruct from a release that has since been approved.\n   *\n   * Where the refusal belongs instead is the READ that decides whether to show a person the\n   * document at all: `resolveEffectiveDocumentRelease(..., { requireApproved: true })`. That is a\n   * Gate 3 arming point per `one-source-of-truth.md` D5 — \"an application may face a real user\" —\n   * and it withholds an unapproved release from the surface, so no interaction with one is ever\n   * offered. Refusing HERE as well would only mean losing the evidence that it happened anyway.\n   */\n  RELEASE_NOT_APPROVED = \"RELEASE_NOT_APPROVED\",\n  /**\n   * The act was solicited, and the record cannot say what notice preceded it.\n   *\n   * TRUE but unfinished: the interaction happened and every other field of the record stands. What\n   * is missing is the one thing that distinguishes a person who scrolled to the end of thirteen\n   * clauses from a person who pressed a button beside a sentence — so a reviewer reading this record\n   * learns only that a release id was accepted, which is the gap #1382 is about.\n   *\n   * It MARKS rather than refuses because the remedy is a surface declaring its mode, which is\n   * authoring work — `.claude/rules/application-creation-directive.md`: a required declaration whose\n   * absence stops the mechanism is the defect, not the guard. The social sign-up path (#1383) is the\n   * live instance, and this advisory is what makes its silence visible rather than indistinguishable\n   * from a form acceptance.\n   */\n  ACCEPTANCE_MODE_NOT_RECORDED = \"ACCEPTANCE_MODE_NOT_RECORDED\",\n}\n\nexport interface GovernedDocumentInteractionAdvisory {\n  readonly kind: GovernedDocumentInteractionAdvisoryKind;\n  readonly message: string;\n}\n\n/**\n * Which interactions an ACCEPTANCE MODE can describe — total over the vocabulary, so a kind added\n * tomorrow is classified deliberately rather than inheriting whichever answer the code fell through\n * to.\n *\n * The question each row answers is the same one: **was this person ASKED?**\n * {@link GovernedDocumentAcceptanceMode} names the notice an application gives before soliciting\n * assent, so it describes an act that was solicited and nothing else.\n */\nexport const GOVERNED_DOCUMENT_INTERACTION_ADMITS_ACCEPTANCE_MODE: Readonly<Record<GovernedDocumentInteractionKind, boolean>> = {\n  /** The APPLICATION acted. Nobody was asked anything, so no notice preceded it. */\n  [GovernedDocumentInteractionKind.NOTICE_DELIVERED]: false,\n  /** The person acted on an invitation to confirm they had seen it — the mode names that invitation. */\n  [GovernedDocumentInteractionKind.NOTICE_ACKNOWLEDGED]: true,\n  /** The canonical case: a registration surface asked for assent in one of the three shapes. */\n  [GovernedDocumentInteractionKind.CONTRACT_ACCEPTED]: true,\n  /** Assent to a purpose, solicited the same way and describable by the same vocabulary. */\n  [GovernedDocumentInteractionKind.CONSENT_GIVEN]: true,\n  /**\n   * A withdrawal is the person acting on their OWN initiative — nothing solicits it, and a mode\n   * claiming a notice preceded it would describe an invitation nobody extended. Withdrawal must be\n   * as easy as giving, which is a property of the surface that offers it rather than a notice given\n   * before it.\n   */\n  [GovernedDocumentInteractionKind.CONSENT_WITHDRAWN]: false,\n};\n\n/**\n * One person, one governed-document release, one interaction, one instant.\n *\n * Every field but `interactionKind` and `occurredAt` is DERIVED from the release, for the same\n * reason the release derives most of itself from the accepted definition: restating `locale`,\n * `jurisdictionRefs` or `documentClass` here would create a second way to disagree with the\n * release, and the disagreement would be invisible. They are copied onto the record rather than\n * left to a join because a record must stay readable when the release file moves on — which is\n * the whole point of binding an acceptance to a VERSION.\n */\nexport const GovernedDocumentInteractionSchema = z.strictObject({\n  schemaVersion: z.literal(1),\n  interactionKind: z.enum(GovernedDocumentInteractionKind),\n  release: GovernedDocumentReleaseIdentitySchema,\n  documentClass: z.enum(GovernedDocumentClass),\n  locale: z.string().trim().min(2),\n  jurisdictionRefs: z.array(GovernedDocumentRefSchema),\n  /** The release's standing AT THE MOMENT OF THE INTERACTION. Not re-derivable later. */\n  releaseApprovalState: z.enum(GovernedDocumentReleaseApprovalState),\n  /**\n   * HOW the act was obtained — the notice the person was given before performing it.\n   *\n   * Without it the strongest statement an operator can make about a recorded acceptance is *\"a\n   * release id was accepted\"*, which is the same sentence for somebody who read the document to its\n   * end and somebody who pressed a button beside a link. Enforceability turns on exactly this\n   * distinction, so a consent record that cannot make it is evidence of the act and not of the\n   * assent (#1382).\n   *\n   * OPTIONAL, and its absence is a fact rather than a default: it means the surface that obtained\n   * the act did not say how it asked. `advisoryKinds` carries\n   * {@link GovernedDocumentInteractionAdvisoryKind.ACCEPTANCE_MODE_NOT_RECORDED} on exactly those\n   * records, so a silent surface reads as silent rather than as the weakest mode — which it would\n   * if a default were stamped here.\n   *\n   * Absent BY RULE, with no advisory, on the kinds\n   * {@link GOVERNED_DOCUMENT_INTERACTION_ADMITS_ACCEPTANCE_MODE} marks `false`.\n   */\n  acceptanceMode: z.enum(GovernedDocumentAcceptanceMode).optional(),\n  occurredAt: GovernedDocumentIsoDateTimeSchema,\n});\nexport type GovernedDocumentInteraction = z.infer<typeof GovernedDocumentInteractionSchema>;\n\n\n/**\n * The slice of a release that a CONSENT SURFACE and an INTERACTION RECORD both need — and it is\n * browser-safe, which turned out to be a property rather than a compromise.\n *\n * {@link composeGovernedDocumentInteraction} reads `allowedInteractionKinds`, the effective\n * interval, `approvalState`, `identity`, `documentClass`, `locale` and `jurisdictionRefs`. It never\n * reads `governanceScope` or `approvalDecisions` — the two fields\n * {@link projectGovernedDocumentPublicRelease} already withholds from public consumers as internal\n * custody detail. So the fields the mechanism needs and the fields a browser may hold are the SAME\n * SET, and one shape can travel the whole chain: the application authors it on\n * `compliance.governedDocumentReleases`, the backend composes records from it, and the frontend\n * decides from it whether to render a consent control at all.\n *\n * Distinct from `GovernedDocumentPublicReleaseProjection`, which is narrower still and answers a\n * different question — how to ROUTE and DISPLAY a published document. It carries neither\n * `allowedInteractionKinds` nor `approvalState`, so a consent surface cannot be built from it.\n */\nexport const GovernedDocumentInteractionSurfaceSchema = z.strictObject({\n  schemaVersion: z.literal(1),\n  identity: GovernedDocumentReleaseIdentitySchema,\n  documentClass: z.enum(GovernedDocumentClass),\n  locale: z.string().trim().min(2),\n  jurisdictionRefs: z.array(GovernedDocumentRefSchema),\n  /** What a person may DO with this document. An empty array means \"read only\"; nothing may be recorded. */\n  allowedInteractionKinds: z.array(z.enum(GovernedDocumentInteractionKind)),\n  approvalState: z.enum(GovernedDocumentReleaseApprovalState),\n  effectiveAt: GovernedDocumentIsoDateTimeSchema,\n  expiresAt: GovernedDocumentIsoDateTimeSchema.optional(),\n  /**\n   * The interactions this release says a person must perform AGAIN, because it replaced an earlier\n   * release with a change that mattered (#1258, Step 2 / R7).\n   *\n   * Projected from `materialityDecision.requiredInteractionKinds` — the governance answer a\n   * superseding release already owes (\"did the change matter enough that the audience must meet the\n   * document again?\"). Only the KINDS travel: the decision identity is private custody detail and this\n   * shape reaches an unauthenticated browser. Empty for a first release and for a replacement judged\n   * immaterial — a typo fix does not re-ask anybody.\n   *\n   * `.default([])` so a surface generated before this field existed still parses, and means exactly\n   * what its absence meant then: nothing is renewed.\n   */\n  renewedInteractionKinds: z.array(z.enum(GovernedDocumentInteractionKind)).default([]),\n});\nexport type GovernedDocumentInteractionSurface = z.infer<typeof GovernedDocumentInteractionSurfaceSchema>;\n\n/** Explicit allow-list projection from a composed release to what a consent surface may hold. */\nexport const projectGovernedDocumentInteractionSurface = (release: GovernedDocumentRelease): GovernedDocumentInteractionSurface =>\n  GovernedDocumentInteractionSurfaceSchema.parse({\n    schemaVersion: 1,\n    identity: release.identity,\n    documentClass: release.documentClass,\n    locale: release.locale,\n    jurisdictionRefs: release.jurisdictionRefs,\n    allowedInteractionKinds: release.allowedInteractionKinds,\n    approvalState: release.approvalState,\n    effectiveAt: release.effectiveAt,\n    ...(release.expiresAt ? { expiresAt: release.expiresAt } : {}),\n    renewedInteractionKinds: release.materialityDecision?.requiredInteractionKinds ?? [],\n  });\n\n\n/**\n * Is this release in force at that instant?\n *\n * ONE implementation, used by {@link composeGovernedDocumentInteraction} here and by\n * `resolveEffectiveDocumentRelease` in `saas-specifications` — which depends on this package, so\n * the read side and the record side cannot disagree about what \"in force\" means. They did, briefly:\n * writing the record's guard reproduced the interval comparison, and two copies of a half-open\n * interval is exactly the shape where one of them ends up with `<=`.\n *\n * HALF-OPEN — `[effectiveAt, expiresAt)`. A release takes effect at the instant it names, and the\n * one that replaces it takes effect at the instant the old one expires, so the boundary belongs to\n * exactly one of them. An unparsable instant is NOT in force: it is not a time.\n */\nexport function governedDocumentReleaseIsInForce(\n  release: { readonly effectiveAt: string; readonly expiresAt?: string },\n  at: string,\n): boolean {\n  const instant = Date.parse(at);\n  if (Number.isNaN(instant)) return false;\n  if (instant < Date.parse(release.effectiveAt)) return false;\n  return release.expiresAt === undefined || instant < Date.parse(release.expiresAt);\n}\n\n/**\n * Whether an application shows, and asks people to accept, governed documents nobody has approved.\n *\n * ONE switch for every surface that puts a governed document in front of a person: the public page\n * (`/privacy`, `/terms`), the registration acceptance control, the first-session acceptance gate, the\n * consent panel's privacy-notice link, the backend's owed-acceptance derivation and the notice-delivery\n * record. It is read from the application's configuration (`compliance.governedDocumentApprovalGate`)\n * through {@link requiresApprovedGovernedDocuments}, never passed per call site, so the page and the\n * acceptance surfaces cannot be armed separately (#1565). Armed on the page alone, `/terms` would answer\n * \"unavailable\" while sign-up asked people to accept those same terms.\n *\n * What it does NOT govern is the RECORD of an act that happened: `recordGovernedDocumentAcceptances`\n * records what a person submitted, and marks an unapproved release with `RELEASE_NOT_APPROVED` rather\n * than dropping it, because refusing there would only lose the evidence.\n *\n * This is the gate point `.claude/rules/one-source-of-truth.md` D5 keeps MARKED: arming it is part of\n * Gate 3's membership test (\"an application may face a real user\").\n */\nexport enum GovernedDocumentApprovalGate {\n  /**\n   * The framework default, and the posture while an application is being built: every release in\n   * force is shown and asked for, whatever its approval state. An unapproved release still says so\n   * (`approvalState` travels with it, and a record of an interaction with it carries\n   * `RELEASE_NOT_APPROVED`), so nothing unapproved is ever presented as approved — it is only not\n   * withheld.\n   */\n  UNARMED = \"unarmed\",\n  /**\n   * Nothing unapproved reaches a person. An unapproved release is neither shown nor asked for, and no\n   * draft stands in for a document that has no approved release. Arm it when the application faces\n   * real users.\n   *\n   * With no approved release of a contractual document, sign-up asks for nothing. Whether an\n   * application should be allowed to go live in that state is part of Gate 3's arming decision, not of\n   * this switch.\n   */\n  ARMED = \"armed\",\n}\n\n/**\n * Whether the application's configuration withholds unapproved governed documents — the ONE reading of\n * {@link GovernedDocumentApprovalGate} every serving and asking surface goes through.\n *\n * Takes the configuration's `compliance` section (or nothing) rather than a boolean, so a call site\n * cannot supply its own answer. An absent section, or an absent member, is the schema default: unarmed.\n *\n * assurance-control: WILDO.PRIVACY.CONSENT_RECORD — once armed, no person is shown or asked to accept a\n * governed document that has not been approved, on any surface.\n */\nexport function requiresApprovedGovernedDocuments(\n  compliance: { readonly governedDocumentApprovalGate?: GovernedDocumentApprovalGate } | undefined,\n): boolean {\n  return compliance?.governedDocumentApprovalGate === GovernedDocumentApprovalGate.ARMED;\n}\n\n/**\n * Every release in force at that instant — what a registration surface asks when it needs to know\n * which documents a person is meeting right now.\n *\n * Deliberately NOT the same question as `resolveEffectiveDocumentRelease`, which picks the ONE\n * winning release for a given document, locale and jurisdiction set. This one spans documents and\n * is total over what the application declared, so a document added to the config tomorrow is\n * delivered without anyone editing a list.\n *\n * `requireApproved` drops releases nobody has approved. A surface that SHOWS or ASKS for a document\n * passes {@link requiresApprovedGovernedDocuments}; a recorder of an act that already happened passes\n * nothing.\n */\nexport function selectGovernedDocumentReleasesInForce(\n  releases: readonly GovernedDocumentInteractionSurface[],\n  at: string,\n  options?: { readonly requireApproved?: boolean },\n): readonly GovernedDocumentInteractionSurface[] {\n  const requireApproved = options?.requireApproved ?? false;\n  return releases.filter((release) =>\n    governedDocumentReleaseIsInForce(release, at)\n    && (!requireApproved || release.approvalState === GovernedDocumentReleaseApprovalState.APPROVED));\n}\n\n/** One accepted release as the owed-acceptance derivation reads it — the persisted row's relevant slice. */\nexport interface GovernedDocumentAcceptanceRecord {\n  readonly documentRef: string;\n  readonly acceptedAt: Date | string;\n}\n\n/**\n * One document a person owes an acceptance of, and why.\n *\n * `releases` is every in-force variant of it — the obligation belongs to the document, not to a locale.\n *\n * What today's surfaces DO with that list, stated plainly because the natural reading is wrong: the\n * registration screen and the acceptance gate present EVERY variant listed and record an acceptance of\n * each, rather than choosing the one in the person's language. Choosing by locale is a refinement neither\n * surface makes yet; an application publishing one variant per document — every dogfood application —\n * never meets the difference.\n */\nexport interface GovernedDocumentAcceptanceOwed {\n  readonly documentRef: string;\n  readonly reason: GovernedDocumentAcceptanceOwedReason;\n  readonly releases: readonly GovernedDocumentInteractionSurface[];\n}\n\n/** Why an acceptance is owed. Two different messages to the person, so two members. */\nexport enum GovernedDocumentAcceptanceOwedReason {\n  /** They have never accepted any release of this document — a stale sign-up form, or an older account. */\n  NEVER_ACCEPTED = \"NEVER_ACCEPTED\",\n  /** A release replaced the one they accepted with a change judged to require acceptance again. */\n  MATERIALLY_CHANGED = \"MATERIALLY_CHANGED\",\n}\n\n/**\n * Which documents a person owes an acceptance of, at an instant (#1258, Step 2 / R7).\n *\n * TOTAL over what the application declared: every in-force release that permits `CONTRACT_ACCEPTED`\n * is considered, so a document added to the configuration tomorrow is owed by everyone the next time\n * they arrive, with no list to maintain (`.claude/rules/derive-before-you-ask.md` rule 3).\n *\n * ## What counts as having accepted it\n *\n * Any release of the DOCUMENT — the join is `documentRef`, never `releaseId`. A release is one locale\n * and jurisdiction pair, so keying on it would re-ask everyone who changed language: accepting the\n * French terms is accepting the terms.\n *\n * ## When an earlier acceptance stops counting\n *\n * Only when a release of the document says so — its `renewedInteractionKinds` includes\n * `CONTRACT_ACCEPTED`, projected from the materiality decision that replacement owed. Then an acceptance\n * counts only if it happened at or after that release took effect. Compared on TIME, not on\n * `releaseVersion`, because a version is counted per variant and comparing one variant's number with\n * another's means nothing.\n *\n * ## The material change need not still be IN FORCE — it is transitive across replacements\n *\n * A replacement takes effect at the instant its predecessor expires, so only the NEWEST release is ever in\n * force. Reading materiality from the in-force releases alone would therefore forget it: accept v1 in\n * January, v2 changes the terms materially in March, v3 fixes a typo in June — and in July only v3 is in\n * force, its renewal set is empty, and a person who never accepted v2's change is told they owe nothing.\n * So the latest material change is taken over EVERY declared release of the document that took effect at or\n * before `at`, expired or not. A release that takes effect AFTER `at` has not happened yet and never counts.\n *\n * What the application must keep for this to hold: the superseded releases stay declared. They do — the\n * releases are recorded as data and only ever appended to.\n *\n * ## With the approval gate armed\n *\n * `requireApproved` ({@link requiresApprovedGovernedDocuments}) owes only APPROVED releases: a person is\n * never asked to accept what the public page would refuse to show. A material change still counts from\n * every declared release, approved or not, because the approved release that follows carries it.\n *\n * A pure function of its inputs: it reads nothing and writes nothing.\n */\nexport function governedDocumentAcceptancesOwed(input: {\n  readonly releases: readonly GovernedDocumentInteractionSurface[];\n  readonly accepted: readonly GovernedDocumentAcceptanceRecord[];\n  readonly at: string;\n  readonly requireApproved?: boolean;\n}): readonly GovernedDocumentAcceptanceOwed[] {\n  const acceptable = selectGovernedDocumentReleasesInForce(input.releases, input.at, { requireApproved: input.requireApproved })\n    .filter((release) => release.allowedInteractionKinds.includes(GovernedDocumentInteractionKind.CONTRACT_ACCEPTED));\n\n  const byDocument = new Map<string, GovernedDocumentInteractionSurface[]>();\n  for (const release of acceptable) {\n    const documentRef = release.identity.document.documentRef;\n    byDocument.set(documentRef, [...(byDocument.get(documentRef) ?? []), release]);\n  }\n\n  const atMs = Date.parse(input.at);\n  const owed: GovernedDocumentAcceptanceOwed[] = [];\n  for (const [documentRef, releases] of byDocument) {\n    const acceptedAtMs = input.accepted\n      .filter((record) => record.documentRef === documentRef)\n      .map((record) => new Date(record.acceptedAt).getTime())\n      .filter((ms) => !Number.isNaN(ms));\n    if (acceptedAtMs.length === 0) {\n      owed.push({ documentRef, reason: GovernedDocumentAcceptanceOwedReason.NEVER_ACCEPTED, releases });\n      continue;\n    }\n    const latestAcceptance = Math.max(...acceptedAtMs);\n    const latestMaterialChange = Math.max(\n      ...input.releases\n        .filter((release) => release.identity.document.documentRef === documentRef\n          && release.allowedInteractionKinds.includes(GovernedDocumentInteractionKind.CONTRACT_ACCEPTED)\n          && release.renewedInteractionKinds.includes(GovernedDocumentInteractionKind.CONTRACT_ACCEPTED)\n          && Date.parse(release.effectiveAt) <= atMs)\n        .map((release) => Date.parse(release.effectiveAt)),\n      Number.NEGATIVE_INFINITY,\n    );\n    if (latestMaterialChange > latestAcceptance) {\n      owed.push({ documentRef, reason: GovernedDocumentAcceptanceOwedReason.MATERIALLY_CHANGED, releases });\n    }\n  }\n  return owed;\n}\n\nexport interface GovernedDocumentInteractionComposition {\n  /**\n   * The release the person actually met. Supplies class, locale, jurisdictions and permitted kinds.\n   *\n   * Typed as the SURFACE rather than the full release so the same call works from the runtime, which\n   * only ever holds the surface. A full `GovernedDocumentRelease` is structurally assignable, so a\n   * caller that has one passes it unchanged.\n   *\n   * `renewedInteractionKinds` is OMITTED from the requirement: it answers \"must the person do this\n   * again?\", which is what the OWED derivation reads, and composing a record of one act never does. It\n   * is a projection a full release does not carry under that name, so requiring it here would have\n   * quietly ended the assignability the paragraph above promises — the surface still satisfies this\n   * type, because an extra field is not a missing one.\n   */\n  readonly release: Omit<GovernedDocumentInteractionSurface, 'renewedInteractionKinds'>;\n  /** What the person did. Must be one the release permits. */\n  readonly interactionKind: GovernedDocumentInteractionKind;\n  /**\n   * The notice the surface gave before soliciting the act, when the surface declares one.\n   *\n   * The CALLER supplies it, and the caller that should is the one holding the application's own\n   * configuration — never the client whose act is being recorded. A mode travelling in from the\n   * browser would be the party whose assent is in question grading the notice it was given.\n   *\n   * Omitted when the surface does not declare a mode, which is recorded as an advisory rather than\n   * defaulted. Supplying one for a kind that admits none is an ISSUE, because it would be false.\n   */\n  readonly acceptanceMode?: GovernedDocumentAcceptanceMode;\n  /** When they did it. Must fall inside the release's effective interval. */\n  readonly occurredAt: string;\n}\n\nexport interface GovernedDocumentInteractionCompositionResult {\n  /** Absent only when `issues` is non-empty. An advisory never withholds the record. */\n  readonly interaction: GovernedDocumentInteraction | undefined;\n  readonly issues: readonly GovernedDocumentInteractionIssue[];\n  readonly advisories: readonly GovernedDocumentInteractionAdvisory[];\n}\n\n/**\n * Compose the record of one interaction, refusing what would be false and marking what is merely\n * unfinished.\n *\n * Pure: it reads the release and the two decided values, and writes nothing. The caller decides\n * where the record goes — today, an auditable event.\n */\nexport function composeGovernedDocumentInteraction(\n  composition: GovernedDocumentInteractionComposition,\n): GovernedDocumentInteractionCompositionResult {\n  const { release, interactionKind, acceptanceMode, occurredAt } = composition;\n  const issues: GovernedDocumentInteractionIssue[] = [];\n  const advisories: GovernedDocumentInteractionAdvisory[] = [];\n  const releaseKey = governedDocumentReleaseIdentityKey(release.identity);\n\n  if (!release.allowedInteractionKinds.includes(interactionKind)) {\n    issues.push({\n      kind: GovernedDocumentInteractionIssueKind.INTERACTION_KIND_NOT_PERMITTED,\n      message:\n        `${releaseKey} permits ${release.allowedInteractionKinds.join(\", \") || \"no interaction\"}, so ${interactionKind} `\n        + \"cannot be recorded against it.\",\n    });\n  }\n\n  if (!governedDocumentReleaseIsInForce(release, occurredAt)) {\n    issues.push({\n      kind: GovernedDocumentInteractionIssueKind.RELEASE_NOT_IN_FORCE,\n      message:\n        `${releaseKey} is in force from ${release.effectiveAt}${release.expiresAt ? ` until ${release.expiresAt}` : \"\"}, `\n        + `so nobody can have interacted with it at ${occurredAt}.`,\n    });\n  }\n\n  const admitsAcceptanceMode = GOVERNED_DOCUMENT_INTERACTION_ADMITS_ACCEPTANCE_MODE[interactionKind];\n  if (acceptanceMode !== undefined && !admitsAcceptanceMode) {\n    issues.push({\n      kind: GovernedDocumentInteractionIssueKind.ACCEPTANCE_MODE_NOT_APPLICABLE,\n      message:\n        `Nobody is asked to perform a ${interactionKind}, so recording it as obtained by ${acceptanceMode} would `\n        + `claim a notice was given for an act that was never solicited (${releaseKey}).`,\n    });\n  }\n  if (acceptanceMode === undefined && admitsAcceptanceMode) {\n    advisories.push({\n      kind: GovernedDocumentInteractionAdvisoryKind.ACCEPTANCE_MODE_NOT_RECORDED,\n      message:\n        `The surface that obtained this ${interactionKind} with ${releaseKey} did not say how it asked, so the record `\n        + \"cannot distinguish a document read to its end from a sentence beside a button.\",\n    });\n  }\n\n  if (release.approvalState === GovernedDocumentReleaseApprovalState.UNAPPROVED) {\n    advisories.push({\n      kind: GovernedDocumentInteractionAdvisoryKind.RELEASE_NOT_APPROVED,\n      message:\n        `${releaseKey} had not been approved when this ${interactionKind} was recorded. The record stands and says so; `\n        + \"withholding an unapproved release from a real reader is the read-side gate (`requireApproved`), armed at Gate 3.\",\n    });\n  }\n\n  if (issues.length > 0) return { interaction: undefined, issues, advisories };\n\n  const parsed = GovernedDocumentInteractionSchema.safeParse({\n    schemaVersion: 1,\n    interactionKind,\n    release: release.identity,\n    documentClass: release.documentClass,\n    locale: release.locale,\n    jurisdictionRefs: release.jurisdictionRefs,\n    releaseApprovalState: release.approvalState,\n    ...(acceptanceMode !== undefined ? { acceptanceMode } : {}),\n    occurredAt,\n  });\n  if (!parsed.success) {\n    return {\n      interaction: undefined,\n      issues: [\n        {\n          kind: GovernedDocumentInteractionIssueKind.RECORD_INVALID,\n          message: `The composed interaction with ${releaseKey} is not a valid record: ${parsed.error.issues.map((issue) => issue.message).join(\"; \")}`,\n        },\n      ],\n      advisories,\n    };\n  }\n  return { interaction: parsed.data, issues: [], advisories };\n}\n\n/**\n * The ONE public document to render for a governed-document ref at an instant, or `undefined`.\n *\n * Total over what the application declared, so a document added to the configuration tomorrow is\n * served without anyone editing a list — the same shape as\n * {@link selectGovernedDocumentReleasesInForce}, and for the same reason.\n *\n * `requireApproved` **IS THE GATE POINT**.\n *\n * It defaults to `false` — deliberately, and this is the posture recorded in\n * `.claude/rules/one-source-of-truth.md` D5: critical gate points stay MARKED in every mechanism so\n * they can be switched on when the posture changes, and under the current YOLO posture they notify\n * and proceed. Arming it is part of **Gate 3**'s membership test (\"an application may face a real\n * user\") — the posture ends where a real user begins, by definition rather than by anyone\n * remembering. A caller serving a page to the public passes `true`; a caller previewing what the\n * lane drafted passes nothing.\n *\n * When several releases of one document are in force the LATEST EFFECTIVE wins, and ties break on\n * the higher `releaseVersion`. Two in force at once is an authoring mistake rather than a state to\n * refuse on a read path: refusing would take the page down over an overlap a reader cannot see,\n * which is worse than showing the newer of two documents the publisher approved.\n *\n * ## The draft fallback, and its two limits (#968 decision 5)\n *\n * A document the application has drafted and never released is served as its UNRELEASED DRAFT, so\n * neither a missing approval nor a missing release ever leaves a page with nothing — the page marks it\n * as a draft. The fallback applies only when the application holds NO release of that document:\n *\n * - a release that exists but is not in force (scheduled, or expired) is a date, not an absence, and\n *   showing the draft in its place would present text the application already decided to replace;\n * - with the gate ARMED there is no fallback at all — \"serve nothing unapproved to a real reader\" has\n *   no answer less approved than a draft.\n */\nexport function resolveInForcePublicDocument(\n  documents: readonly GovernedDocumentPublicDocument[],\n  documentRef: string,\n  at: string,\n  options?: { readonly requireApproved?: boolean },\n): GovernedDocumentPublicDocument | undefined {\n  const requireApproved = options?.requireApproved ?? false;\n  const released = documents.filter((document): document is GovernedDocumentReleasedPublicDocument =>\n    document.kind === GovernedDocumentPublicDocumentKind.RELEASED && document.release.identity.document.documentRef === documentRef);\n  const candidates = released.filter((document) =>\n    governedDocumentReleaseIsInForce(document.release, at)\n    && (!requireApproved || document.approvalState === GovernedDocumentReleaseApprovalState.APPROVED));\n  if (candidates.length === 0) {\n    if (released.length > 0 || requireApproved) return undefined;\n    return documents.find((document) =>\n      document.kind === GovernedDocumentPublicDocumentKind.UNRELEASED_DRAFT && document.documentRef === documentRef);\n  }\n  return candidates.reduce((winner, candidate) => {\n    const winnerEffective = Date.parse(winner.release.effectiveAt);\n    const candidateEffective = Date.parse(candidate.release.effectiveAt);\n    if (candidateEffective !== winnerEffective) return candidateEffective > winnerEffective ? candidate : winner;\n    return candidate.release.identity.releaseVersion > winner.release.identity.releaseVersion ? candidate : winner;\n  });\n}\n"]}