@wildo-ai/saas-models 1.1.4 → 1.1.6

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

@@ -0,0 +1,463 @@
+import { z } from "zod";
+import { GovernedDocumentAcceptanceMode, GovernedDocumentClass, GovernedDocumentInteractionKind, GovernedDocumentReleaseApprovalState, type GovernedDocumentPublicDocument, type GovernedDocumentRelease } from "./governed-documents.shared.schemas";
+/**
+ * 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 declare enum 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.
+     */
+    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.
+     */
+    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}.
+     */
+    ACCEPTANCE_MODE_NOT_APPLICABLE = "ACCEPTANCE_MODE_NOT_APPLICABLE",
+    /** The composed record does not satisfy {@link GovernedDocumentInteractionSchema}. */
+    RECORD_INVALID = "RECORD_INVALID"
+}
+export interface GovernedDocumentInteractionIssue {
+    readonly kind: GovernedDocumentInteractionIssueKind;
+    readonly message: string;
+}
+/**
+ * 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 declare enum 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.
+     */
+    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.
+     */
+    ACCEPTANCE_MODE_NOT_RECORDED = "ACCEPTANCE_MODE_NOT_RECORDED"
+}
+export interface GovernedDocumentInteractionAdvisory {
+    readonly kind: GovernedDocumentInteractionAdvisoryKind;
+    readonly message: string;
+}
+/**
+ * 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 declare const GOVERNED_DOCUMENT_INTERACTION_ADMITS_ACCEPTANCE_MODE: Readonly<Record<GovernedDocumentInteractionKind, boolean>>;
+/**
+ * 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 declare const GovernedDocumentInteractionSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    interactionKind: z.ZodEnum<typeof GovernedDocumentInteractionKind>;
+    release: z.ZodObject<{
+        document: z.ZodObject<{
+            documentRef: z.core.$ZodBranded<z.ZodString, "GovernedDocumentRef", "out">;
+            documentVersion: z.ZodNumber;
+        }, z.core.$strict>;
+        releaseId: z.core.$ZodBranded<z.ZodString, "GovernedDocumentRef", "out">;
+        releaseVersion: z.ZodNumber;
+    }, z.core.$strict>;
+    documentClass: z.ZodEnum<typeof GovernedDocumentClass>;
+    locale: z.ZodString;
+    jurisdictionRefs: z.ZodArray<z.core.$ZodBranded<z.ZodString, "GovernedDocumentRef", "out">>;
+    /** The release's standing AT THE MOMENT OF THE INTERACTION. Not re-derivable later. */
+    releaseApprovalState: z.ZodEnum<typeof 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.ZodOptional<z.ZodEnum<typeof GovernedDocumentAcceptanceMode>>;
+    occurredAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type GovernedDocumentInteraction = z.infer<typeof GovernedDocumentInteractionSchema>;
+/**
+ * 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 declare const GovernedDocumentInteractionSurfaceSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    identity: z.ZodObject<{
+        document: z.ZodObject<{
+            documentRef: z.core.$ZodBranded<z.ZodString, "GovernedDocumentRef", "out">;
+            documentVersion: z.ZodNumber;
+        }, z.core.$strict>;
+        releaseId: z.core.$ZodBranded<z.ZodString, "GovernedDocumentRef", "out">;
+        releaseVersion: z.ZodNumber;
+    }, z.core.$strict>;
+    documentClass: z.ZodEnum<typeof GovernedDocumentClass>;
+    locale: z.ZodString;
+    jurisdictionRefs: z.ZodArray<z.core.$ZodBranded<z.ZodString, "GovernedDocumentRef", "out">>;
+    /** What a person may DO with this document. An empty array means "read only"; nothing may be recorded. */
+    allowedInteractionKinds: z.ZodArray<z.ZodEnum<typeof GovernedDocumentInteractionKind>>;
+    approvalState: z.ZodEnum<typeof GovernedDocumentReleaseApprovalState>;
+    effectiveAt: z.ZodISODateTime;
+    expiresAt: z.ZodOptional<z.ZodISODateTime>;
+    /**
+     * 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.ZodDefault<z.ZodArray<z.ZodEnum<typeof GovernedDocumentInteractionKind>>>;
+}, z.core.$strict>;
+export type GovernedDocumentInteractionSurface = z.infer<typeof GovernedDocumentInteractionSurfaceSchema>;
+/** Explicit allow-list projection from a composed release to what a consent surface may hold. */
+export declare const projectGovernedDocumentInteractionSurface: (release: GovernedDocumentRelease) => GovernedDocumentInteractionSurface;
+/**
+ * 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 declare function governedDocumentReleaseIsInForce(release: {
+    readonly effectiveAt: string;
+    readonly expiresAt?: string;
+}, at: string): boolean;
+/**
+ * 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 declare enum 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.
+     */
+    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.
+     */
+    ARMED = "armed"
+}
+/**
+ * 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 declare function requiresApprovedGovernedDocuments(compliance: {
+    readonly governedDocumentApprovalGate?: GovernedDocumentApprovalGate;
+} | undefined): boolean;
+/**
+ * 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 declare function selectGovernedDocumentReleasesInForce(releases: readonly GovernedDocumentInteractionSurface[], at: string, options?: {
+    readonly requireApproved?: boolean;
+}): readonly GovernedDocumentInteractionSurface[];
+/** One accepted release as the owed-acceptance derivation reads it — the persisted row's relevant slice. */
+export interface GovernedDocumentAcceptanceRecord {
+    readonly documentRef: string;
+    readonly acceptedAt: Date | string;
+}
+/**
+ * One document a person owes an acceptance of, and why.
+ *
+ * `releases` is every in-force variant of it — the obligation belongs to the document, not to a locale.
+ *
+ * What today's surfaces DO with that list, stated plainly because the natural reading is wrong: the
+ * registration screen and the acceptance gate present EVERY variant listed and record an acceptance of
+ * each, rather than choosing the one in the person's language. Choosing by locale is a refinement neither
+ * surface makes yet; an application publishing one variant per document — every dogfood application —
+ * never meets the difference.
+ */
+export interface GovernedDocumentAcceptanceOwed {
+    readonly documentRef: string;
+    readonly reason: GovernedDocumentAcceptanceOwedReason;
+    readonly releases: readonly GovernedDocumentInteractionSurface[];
+}
+/** Why an acceptance is owed. Two different messages to the person, so two members. */
+export declare enum GovernedDocumentAcceptanceOwedReason {
+    /** They have never accepted any release of this document — a stale sign-up form, or an older account. */
+    NEVER_ACCEPTED = "NEVER_ACCEPTED",
+    /** A release replaced the one they accepted with a change judged to require acceptance again. */
+    MATERIALLY_CHANGED = "MATERIALLY_CHANGED"
+}
+/**
+ * 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 declare function governedDocumentAcceptancesOwed(input: {
+    readonly releases: readonly GovernedDocumentInteractionSurface[];
+    readonly accepted: readonly GovernedDocumentAcceptanceRecord[];
+    readonly at: string;
+    readonly requireApproved?: boolean;
+}): readonly GovernedDocumentAcceptanceOwed[];
+export interface GovernedDocumentInteractionComposition {
+    /**
+     * The release the person actually met. Supplies class, locale, jurisdictions and permitted kinds.
+     *
+     * Typed as the SURFACE rather than the full release so the same call works from the runtime, which
+     * only ever holds the surface. A full `GovernedDocumentRelease` is structurally assignable, so a
+     * caller that has one passes it unchanged.
+     *
+     * `renewedInteractionKinds` is OMITTED from the requirement: it answers "must the person do this
+     * again?", which is what the OWED derivation reads, and composing a record of one act never does. It
+     * is a projection a full release does not carry under that name, so requiring it here would have
+     * quietly ended the assignability the paragraph above promises — the surface still satisfies this
+     * type, because an extra field is not a missing one.
+     */
+    readonly release: Omit<GovernedDocumentInteractionSurface, 'renewedInteractionKinds'>;
+    /** What the person did. Must be one the release permits. */
+    readonly interactionKind: GovernedDocumentInteractionKind;
+    /**
+     * The notice the surface gave before soliciting the act, when the surface declares one.
+     *
+     * The CALLER supplies it, and the caller that should is the one holding the application's own
+     * configuration — never the client whose act is being recorded. A mode travelling in from the
+     * browser would be the party whose assent is in question grading the notice it was given.
+     *
+     * Omitted when the surface does not declare a mode, which is recorded as an advisory rather than
+     * defaulted. Supplying one for a kind that admits none is an ISSUE, because it would be false.
+     */
+    readonly acceptanceMode?: GovernedDocumentAcceptanceMode;
+    /** When they did it. Must fall inside the release's effective interval. */
+    readonly occurredAt: string;
+}
+export interface GovernedDocumentInteractionCompositionResult {
+    /** Absent only when `issues` is non-empty. An advisory never withholds the record. */
+    readonly interaction: GovernedDocumentInteraction | undefined;
+    readonly issues: readonly GovernedDocumentInteractionIssue[];
+    readonly advisories: readonly GovernedDocumentInteractionAdvisory[];
+}
+/**
+ * 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 declare function composeGovernedDocumentInteraction(composition: GovernedDocumentInteractionComposition): GovernedDocumentInteractionCompositionResult;
+/**
+ * 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 declare function resolveInForcePublicDocument(documents: readonly GovernedDocumentPublicDocument[], documentRef: string, at: string, options?: {
+    readonly requireApproved?: boolean;
+}): GovernedDocumentPublicDocument | undefined;
+//# sourceMappingURL=governed-document-interactions.shared.schemas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"governed-document-interactions.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/compliance/documents/governed-document-interactions.shared.schemas.ts"],"names":[],"mappings":"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"}