@actuarial-ts/agents 0.1.0 → 0.3.0

package/dist/promotion.d.ts

@@ -0,0 +1,295 @@
+/**
+ * promoteStudy: notebook study -> governed judgment (interchange spec rev 2.1,
+ * Section 6). A four-gate judgment chain built on createJudgmentChain:
+ *
+ *   Gate 1 "study-intake"  - schema/integrity validation via interchange
+ *                            parseDocument, ASOP 23 data review on the study's
+ *                            triangles, selection coherence (spec 3.2 rule),
+ *                            segment resolution (v1: one selection per
+ *                            segment), and the tolerance ceiling.
+ *   Gate 2 "replay-verify" - table-exact intents replayed through
+ *                            interchange/core; approx/value-only targets
+ *                            labeled verified-by-value; supportingResults
+ *                            refereed via crosscheck at the effective
+ *                            tolerance; a "disagree" verdict HARD-BLOCKS.
+ *   Gate 3 "rationale"     - a DRAFT rationale (template-assembled from the
+ *                            study narrative; options.draftRationale is the
+ *                            injection hook for future agent drafting); resume
+ *                            REQUIRES a non-blank rationale AND attestation.
+ *   Gate 4 "apply"         - deps.applySelections per selection,
+ *                            deps.runAnalysis, ledger entries carrying the
+ *                            Gate 3 rationale + attestation verbatim, and
+ *                            deps.persistNote with the trail + ledger JSON.
+ *
+ * Architecture decisions (each is load-bearing):
+ *
+ * - EAGER, DETERMINISTIC INTAKE. All Gate 1/2 computation (parse, review,
+ *   coherence, segment resolution, replay, crosschecks) runs synchronously at
+ *   chain-CONSTRUCTION time. Everything is a pure function of the study
+ *   document plus deps.resolveSegment, so a host that reconstructs the chain
+ *   after a restart (promoteStudy again with the same study) gets IDENTICAL
+ *   gates and resume schemas - which is what makes the Gate 2 hard-block
+ *   structural: when any referee verdict is "disagree", the replay-verify
+ *   resume schema literally only admits { decision: "abort" }. Mastra's own
+ *   resume validation rejects an accept; no runtime flag to lose across a
+ *   snapshot rehydration, no advisory check an agent could talk its way past.
+ *
+ * - STUDY-CONTENT FAILURES SURFACE AS GATE FAILURES. A malformed study
+ *   (BAD_INTERCHANGE), a tolerance above the host ceiling
+ *   (TOLERANCE_CEILING_EXCEEDED), an unresolvable or ambiguous segment
+ *   (SEGMENT_UNRESOLVED / SEGMENT_AMBIGUOUS), an incoherent selection under
+ *   refuse strictness (INCOHERENT_SELECTION), or an empty study (EMPTY_STUDY)
+ *   never throws out of promoteStudy itself: the captured error is thrown
+ *   from Gate 1's gatherEvidence, so the run fails AT the study-intake gate
+ *   with the named error, where the host's gate UI can render it.
+ *   promoteStudy throws synchronously only for programmer errors
+ *   (BAD_PROMOTION_OPTIONS: missing deps, non-positive ceiling, ...).
+ *
+ * - DATA REVIEW CHOICE (documented per plan task B2): where a segment group
+ *   contains exactly one paid and one incurred triangle, the full
+ *   @actuarial-ts/data reviewTriangles pair review runs (it includes the
+ *   per-triangle monotonicity and interior-missing checks). Every other core
+ *   loss triangle gets the per-triangle STRUCTURAL subset of those checks
+ *   (non-decreasing cumulative rows, interior missing cells), reported in the
+ *   same DataReviewReport shape. Non-core measures (earnedPremium, custom:*)
+ *   are exposure/reference data, not loss triangles: their review is reported
+ *   "not-evaluated" rather than silently passed - unless a selection
+ *   references one, which fails intake (BAD_INTERCHANGE from the converter).
+ *   Review findings, including fail-status checks, are EVIDENCE for the human
+ *   intake decision, not automatic blocks; only the named error classes above
+ *   block mechanically. The recommendation says so when checks fail.
+ *
+ * - PURITY. This module never reads a clock; options.now supplies every
+ *   timestamp (envelope createdAt at construction, ledger timestamps at
+ *   resume). The tenant seam is untouched: deps close over the host's own
+ *   authenticated context, and nothing model-facing exists here at all.
+ *
+ * FOOTGUN (inherited from createJudgmentChain): the returned workflow exposes
+ * .then(step), making it an ACCIDENTAL THENABLE. Never await promoteStudy's
+ * return value and never return it from an async function - assign it
+ * synchronously and register it on a Mastra instance.
+ */
+import { type LdfSelections } from "@actuarial-ts/core";
+import { type CoherenceCheck, type CrosscheckReportDoc, type SelectionDoc, type StudyBody } from "@actuarial-ts/interchange";
+import { type DataReviewReport } from "@actuarial-ts/data";
+import { type JudgmentChainWorkflow } from "./judgment.js";
+/**
+ * The host-adapter seam (spec 6 Gate 4; the workbench adapter arrives with
+ * plan task B4). resolveSegment is SYNCHRONOUS so promoteStudy can stay
+ * synchronous (the accidental-thenable footgun forbids async construction);
+ * the mutation hooks may be async - they run inside gate execution.
+ */
+export interface PromoteStudyDeps {
+    /**
+     * Maps a selection's triangle segment labels to exactly one host workspace
+     * target, or null when nothing matches (v1: no fuzzy matching). A
+     * single-segment host returns its only target regardless of labels.
+     */
+    resolveSegment(labels: Record<string, string>): string | null;
+    /**
+     * Applies one promoted selection through the host's service layer.
+     * `replayedSelections` is the core LdfSelections the replay verified;
+     * `segmentTarget` is the resolved workspace target (a two-parameter
+     * implementation that closes over its single segment may ignore it).
+     */
+    applySelections(selectionDoc: SelectionDoc, replayedSelections: LdfSelections, segmentTarget: string): Promise<void> | void;
+    /** Reruns the host analysis after the selections are applied. */
+    runAnalysis(label: string): Promise<void> | void;
+    /** Persists a completion note (called twice: trail, then ledger JSON). */
+    persistNote(text: string, author: string): Promise<void> | void;
+}
+/** Context handed to the rationale-drafting hook. */
+export interface DraftRationaleContext {
+    study: StudyBody;
+    studyIntegrity: string;
+    intake: StudyIntakeEvidence;
+    replay: ReplayVerifyEvidence;
+}
+export interface PromoteStudyOptions {
+    /**
+     * The host's replay-tolerance ceiling. The EFFECTIVE tolerance is
+     * min(study replayTolerance, ceiling); a study STATING a tolerance above
+     * the ceiling fails intake (tolerance editing is not an escape hatch).
+     */
+    toleranceCeiling: number;
+    /** Actor recorded when a resume payload names none. Default "actuary". */
+    actorDefault?: string;
+    /** Host-injected clock (purity: this package never reads Date). */
+    now: () => string;
+    /**
+     * Coherence/integrity strictness for intake. Default "refuse" (promotion
+     * is a refuse-mode consumer per spec 3.2); "warn" downgrades divergence
+     * to evidence warnings.
+     */
+    strictness?: "warn" | "refuse";
+    /**
+     * Injection hook for agent-assisted rationale drafting (spec 9.2 arrives
+     * later); the default assembles a template from the study narrative. The
+     * human always owns the final text - this drafts, never decides.
+     */
+    draftRationale?: (ctx: DraftRationaleContext) => Promise<string> | string;
+}
+/** Prominent tolerance block (spec 6 Gate 1). */
+export interface ReplayToleranceEvidence {
+    /** expectations.replayTolerance as stated, or null when the study omits it. */
+    stated: number | null;
+    /** The convention-profile default the 10x flag is measured against. */
+    profileId: string;
+    profileDefault: number;
+    /** true when the stated tolerance exceeds 10x the profile default. */
+    exceedsTenTimesProfileDefault: boolean;
+    /** The host ceiling from options. */
+    ceiling: number;
+    /** min(stated ?? profileDefault, ceiling): what Gate 2 referees at. */
+    effective: number;
+}
+export interface TriangleReviewEvidence {
+    /** paired-asop23 = reviewTriangles on a paid/incurred pair; structural =
+     * per-triangle checks; not-evaluated = non-core measure. */
+    mode: "paired-asop23" | "structural" | "not-evaluated";
+    triangles: {
+        integrity: string;
+        measure: string;
+    }[];
+    report: DataReviewReport;
+}
+export interface SegmentResolutionEvidence {
+    selectionIntegrity: string;
+    labels: Record<string, string>;
+    target: string;
+}
+export interface SelectionCoherenceEvidence {
+    selectionIntegrity: string;
+    triangleIntegrity: string;
+    coherence: CoherenceCheck;
+}
+export interface StudyIntakeEvidence {
+    study: {
+        title: string;
+        analyst: string | null;
+        sourceRef: string | null;
+        summary: string;
+        integrity: string;
+    };
+    /** FIRST, on purpose: the spec requires prominent display. */
+    replayTolerance: ReplayToleranceEvidence;
+    dataReview: TriangleReviewEvidence[];
+    coherence: SelectionCoherenceEvidence[];
+    segments: SegmentResolutionEvidence[];
+    warnings: string[];
+    /**
+     * ALWAYS populated: the verification-scope disclosure. Coherence, replay,
+     * and referee all verify the study against its OWN embedded triangle;
+     * whether that triangle IS the host workspace's book of business is not
+     * machine-verified anywhere in the chain. Stating this in the evidence
+     * keeps the gates honest about what they checked - the data-binding
+     * judgment belongs to the reviewing actuary, and the UI must say so
+     * rather than let "verified" read wider than it is.
+     */
+    workspaceBindingNote: string;
+}
+/** Per replay target: how this shore verified it (spec 3.2 capabilities). */
+export interface ReplayTargetLabel {
+    /** "12-24" for a development interval, or "tail". */
+    target: string;
+    /** exact = independently recomputed; value-only = applied as stated. */
+    capability: "exact" | "value-only";
+    /** The disclosure-honest label: replayed-exact or verified-by-value. */
+    label: "replayed-exact" | "verified-by-value";
+    note?: string;
+}
+export interface SelectionReplayEvidence {
+    selectionIntegrity: string;
+    triangleIntegrity: string;
+    segmentTarget: string;
+    targets: ReplayTargetLabel[];
+    /** Every intent judgmental/external: the whole replay is value transport. */
+    verifiedByValueOnly: boolean;
+    replayTotals: {
+        ultimate: number;
+        unpaid: number;
+    };
+}
+export interface SupportingCrosscheckEvidence {
+    resultIntegrity: string;
+    engine: {
+        name: string;
+        version: string;
+    };
+    /** null when the result could not be refereed (see reason). */
+    verdict: "agree" | "disagree" | "not-comparable" | "verified-by-value" | null;
+    report: CrosscheckReportDoc | null;
+    reason?: string;
+}
+export interface ReplayVerifyEvidence {
+    effectiveTolerance: number;
+    replays: SelectionReplayEvidence[];
+    crosschecks: SupportingCrosscheckEvidence[];
+    /** Any crosscheck verdict "disagree": the gate cannot accept (spec 6). */
+    hardBlocked: boolean;
+    /** States exactly what the verification consisted of - including, when the
+     * study carried no supportingResults, that it was coherence + replay only. */
+    verification: string;
+}
+/**
+ * A supporting result the study carries that is NOT reproducible (spec 16).
+ *
+ * A `witnessed` result attests what an engine produced on one run; re-running
+ * it does not reproduce the number. That is legitimate evidence, but it is a
+ * materially different thing from a replayable derivation, and the actuary
+ * whose attestation goes on the ledger has to know which one they are relying
+ * on. Surfacing it here is what makes the attestation informed rather than
+ * nominal — the promotion is not blocked, it is disclosed.
+ */
+export interface WitnessedResultNotice {
+    method: string;
+    engine: string;
+    seed: number | null;
+    /** The engine's own repeat-run self-check, when it performed one. */
+    stability: {
+        repeats: number;
+        byteIdentical: boolean;
+        maxRelativeDeviation: number | null;
+    } | null;
+}
+export interface RationaleEvidence {
+    draftRationale: string;
+    attestationRequired: true;
+    study: {
+        title: string;
+        sourceRef: string | null;
+        analyst: string | null;
+    };
+    /**
+     * Non-reproducible supporting results, empty when every result is
+     * deterministic or seeded-reproducible.
+     */
+    witnessedResults: WitnessedResultNotice[];
+}
+export interface ApplyEvidence {
+    applications: {
+        segmentTarget: string;
+        selectionIntegrity: string;
+        developmentCount: number;
+        tailFactor: number;
+    }[];
+    analysisLabel: string;
+    ledgerSource: string;
+}
+/** The workflow id promoteStudy builds its chain with. */
+export declare const PROMOTION_CHAIN_ID = "promote-study";
+/** See StudyIntakeEvidence.workspaceBindingNote; one constant so every
+ * intake states the same scope, verbatim. */
+export declare const WORKSPACE_BINDING_NOTE: string;
+/**
+ * Builds the promotion judgment chain for one study. SYNCHRONOUS by design
+ * (see the accidental-thenable footgun in the module doc): assign the return
+ * value and register it on a Mastra instance, exactly like any
+ * createJudgmentChain workflow; then createRun/start/resume drive the gates.
+ *
+ * Reconstruction contract: promoteStudy(deps, studyDoc, options) is
+ * deterministic given the study document and deps.resolveSegment, so a host
+ * resuming a snapshot after a restart rebuilds the identical chain.
+ */
+export declare function promoteStudy(deps: PromoteStudyDeps, studyDoc: unknown, options: PromoteStudyOptions): JudgmentChainWorkflow;
+//# sourceMappingURL=promotion.d.ts.map

package/dist/promotion.d.ts.map

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