@agentplat/inference-control 0.3.0-beta.1 → 0.3.0-beta.3

package/dist/anytime-semantic-guarantees.js

@@ -0,0 +1,817 @@
+import { digestControlJsonV1 } from "./canonical.js";
+export const ANYTIME_SEMANTIC_GUARANTEE_STATE_FORMAT_V1 = "agentplat.inference-control.anytime-semantic-guarantee-state.v1";
+export const SEMANTIC_GUARANTEE_METRICS_V1 = Object.freeze([
+    "roleCoherence",
+    "missionAlignment",
+    "contextConflict",
+    "uncertainty",
+    "courseActionDiversity",
+    "courseActionNovelty",
+]);
+const anytimeSemanticGuaranteeEngineInvokersV1 = new WeakMap();
+const semanticHorizonControlInvokersV1 = new WeakMap();
+const EXPECTED_DIRECTIONS = Object.freeze({
+    roleCoherence: "higher_is_better",
+    missionAlignment: "higher_is_better",
+    contextConflict: "lower_is_better",
+    uncertainty: "lower_is_better",
+    courseActionDiversity: "higher_is_better",
+    courseActionNovelty: "higher_is_better",
+});
+const VECTOR_KEYS = Object.freeze({
+    roleCoherence: "roleCoherenceBps",
+    missionAlignment: "missionAlignmentBps",
+    contextConflict: "contextConflictBps",
+    uncertainty: "uncertaintyBps",
+    courseActionDiversity: "courseActionDiversityBps",
+    courseActionNovelty: "courseActionNoveltyBps",
+});
+export function createAnytimeSemanticAssumptionsV1(input) {
+    const evidence = uniqueDigests(input.assumptionEvidenceDigests, "assumptionEvidenceDigests");
+    const body = {
+        schemaVersion: 1,
+        estimand: "average_conditional_mean",
+        dependenceModel: "bounded_martingale_differences",
+        observationRange: "basis_points_0_10000",
+        selectionTiming: "before_metric_observation",
+        assumptionEvidenceDigests: evidence,
+    };
+    return deepFreeze({
+        ...body,
+        assumptionsDigest: digestSemanticGuarantee("assumptions", body),
+    });
+}
+export function createAnytimeSemanticGuaranteePolicyV1(input) {
+    const policyId = input.policyId;
+    const familywiseErrorBudgetPpm = input.familywiseErrorBudgetPpm;
+    const minimumInferenceSamples = input.minimumInferenceSamples;
+    const metricInputs = input.metrics;
+    const assumptionInputs = input.assumptions;
+    identifier(policyId, "policyId");
+    integer(familywiseErrorBudgetPpm, "familywiseErrorBudgetPpm", 1, 499_999);
+    integer(minimumInferenceSamples, "minimumInferenceSamples", 1, 1_000_000_000);
+    const maximumRetainedEvidenceDigests = input.maximumRetainedEvidenceDigests ?? 128;
+    const maximumCasAttempts = input.maximumCasAttempts ?? 8;
+    integer(maximumRetainedEvidenceDigests, "maximumRetainedEvidenceDigests", 1, 10_000);
+    integer(maximumCasAttempts, "maximumCasAttempts", 1, 1_000);
+    let allocated = 0;
+    const metrics = {};
+    for (const metric of SEMANTIC_GUARANTEE_METRICS_V1) {
+        const candidate = metricInputs[metric];
+        if (!candidate)
+            throw new TypeError(`semantic_guarantee_${metric}_direction_invalid`);
+        const direction = candidate.direction;
+        const errorBudgetPpm = candidate.errorBudgetPpm;
+        const missingness = candidate.missingness;
+        if (direction !== EXPECTED_DIRECTIONS[metric])
+            throw new TypeError(`semantic_guarantee_${metric}_direction_invalid`);
+        integer(errorBudgetPpm, `${metric}.errorBudgetPpm`, 1, 499_999);
+        if (!["fail_closed", "predictable_skip", "worst_case_imputation"].includes(missingness))
+            throw new TypeError(`semantic_guarantee_${metric}_missingness_invalid`);
+        allocated += errorBudgetPpm;
+        metrics[metric] = Object.freeze({
+            direction,
+            errorBudgetPpm,
+            missingness,
+        });
+    }
+    if (allocated > familywiseErrorBudgetPpm)
+        throw new RangeError("semantic_guarantee_metric_error_budget_exceeds_familywise_budget");
+    const assumptions = createAnytimeSemanticAssumptionsV1(assumptionInputs);
+    if (Object.values(metrics).some((metric) => metric.missingness === "predictable_skip") &&
+        assumptions.assumptionEvidenceDigests.length === 0)
+        throw new TypeError("semantic_guarantee_predictable_skip_requires_assumption_evidence");
+    const body = {
+        schemaVersion: 1,
+        policyId,
+        familywiseErrorBudgetPpm,
+        boundMethod: "hoeffding_azuma_two_sided",
+        spendingSchedule: "inverse_quadratic_telescoping",
+        minimumInferenceSamples,
+        maximumRetainedEvidenceDigests,
+        maximumCasAttempts,
+        metrics,
+        assumptions,
+    };
+    return deepFreeze({
+        ...body,
+        policyDigest: digestSemanticGuarantee("policy", body),
+    });
+}
+export class InMemoryAnytimeSemanticGuaranteeStoreV1 {
+    #states = new Map();
+    #anchors = new Map();
+    async load(stateKey) {
+        return this.#states.get(stateKey) ?? null;
+    }
+    async readAnchor(stateKey) {
+        return this.#anchors.get(stateKey) ?? null;
+    }
+    async compareAndSet(input) {
+        const prior = this.#states.get(input.stateKey) ?? null;
+        if ((prior?.revision ?? null) !== input.expectedRevision ||
+            (prior?.stateDigest ?? null) !== input.expectedStateDigest)
+            return false;
+        this.#states.set(input.stateKey, deepFreeze(input.next));
+        this.#anchors.set(input.stateKey, deepFreeze({
+            revision: input.next.revision,
+            sequenceHighWater: input.next.sequenceHighWater,
+            logicalTimeHighWaterMs: input.next.logicalTimeHighWaterMs,
+            stateDigest: input.next.stateDigest,
+        }));
+        return true;
+    }
+}
+/**
+ * Portable confidence-sequence engine. It uses a fixed-time Hoeffding-Azuma
+ * bound at each inference count and an inverse-quadratic alpha-spending union
+ * bound, making all emitted intervals simultaneous across metrics and time.
+ */
+export class AnytimeSemanticGuaranteeEngineV1 {
+    policy;
+    store;
+    anchor;
+    #load;
+    #compareAndSet;
+    #readAnchor;
+    constructor(options) {
+        const policy = validatePolicy(options.policy);
+        const store = options.store ?? new InMemoryAnytimeSemanticGuaranteeStoreV1();
+        const anchor = options.monotonicAnchor ??
+            store;
+        if (typeof store.load !== "function" ||
+            typeof store.compareAndSet !== "function" ||
+            typeof anchor.readAnchor !== "function")
+            throw new TypeError("semantic_guarantee_external_monotonic_anchor_required");
+        this.policy = policy;
+        this.store = store;
+        this.anchor = anchor;
+        this.#load = store.load.bind(store);
+        this.#compareAndSet = store.compareAndSet.bind(store);
+        this.#readAnchor = anchor.readAnchor.bind(anchor);
+        Object.defineProperties(this, {
+            policy: immutableSemanticGuaranteeValue(policy),
+            store: immutableSemanticGuaranteeValue(store),
+            anchor: immutableSemanticGuaranteeValue(anchor),
+        });
+        anytimeSemanticGuaranteeEngineInvokersV1.set(this, Object.freeze({
+            append: (input) => this.#append(input),
+            current: (stateKey) => this.#current(stateKey),
+        }));
+    }
+    async append(input) {
+        return invokeAnytimeSemanticGuaranteeAppendV1(this, input);
+    }
+    async #append(input) {
+        identifier(input.stateKey, "stateKey");
+        validateSample(input.sample);
+        const sampleDigest = digestSemanticGuarantee("sample", input.sample);
+        for (let attempt = 0; attempt < this.policy.maximumCasAttempts; attempt += 1) {
+            const prior = await this.#load(input.stateKey);
+            await this.#assertStateAndAnchor(input.stateKey, prior);
+            if (prior && input.sample.sequence === prior.sequenceHighWater) {
+                if (sampleDigest !== prior.lastSampleDigest)
+                    throw new TypeError("semantic_guarantee_sample_equivocation");
+                return this.#guaranteeFrom(prior);
+            }
+            if (prior &&
+                (input.sample.sequence < prior.sequenceHighWater ||
+                    input.sample.logicalTimeMs < prior.logicalTimeHighWaterMs))
+                throw new TypeError("semantic_guarantee_sample_order_invalid");
+            const next = this.#advance(input.stateKey, prior, input.sample, sampleDigest);
+            if (await this.#compareAndSet({
+                stateKey: input.stateKey,
+                expectedRevision: prior?.revision ?? null,
+                expectedStateDigest: prior?.stateDigest ?? null,
+                next,
+            })) {
+                const committed = await this.#load(input.stateKey);
+                if (!committed || committed.stateDigest !== next.stateDigest)
+                    throw new TypeError("semantic_guarantee_commit_not_observable");
+                await this.#assertStateAndAnchor(input.stateKey, committed);
+                return this.#guaranteeFrom(committed);
+            }
+        }
+        throw new Error("semantic_guarantee_cas_retry_exhausted");
+    }
+    async current(stateKey) {
+        return invokeAnytimeSemanticGuaranteeCurrentV1(this, stateKey);
+    }
+    async #current(stateKey) {
+        identifier(stateKey, "stateKey");
+        const state = await this.#load(stateKey);
+        if (!state) {
+            if (await this.#readAnchor(stateKey))
+                throw new TypeError("semantic_guarantee_state_missing_below_anchor");
+            throw new TypeError("semantic_guarantee_has_no_samples");
+        }
+        await this.#assertStateAndAnchor(stateKey, state);
+        return this.#guaranteeFrom(state);
+    }
+    #advance(stateKey, prior, sample, sampleDigest) {
+        const metrics = {};
+        for (const metric of SEMANTIC_GUARANTEE_METRICS_V1) {
+            const existing = prior?.metrics[metric] ?? emptyAccumulator();
+            metrics[metric] = advanceAccumulator(existing, sample.metrics[VECTOR_KEYS[metric]], this.policy.metrics[metric]);
+        }
+        const revision = (prior?.revision ?? 0) + 1;
+        const body = {
+            format: ANYTIME_SEMANTIC_GUARANTEE_STATE_FORMAT_V1,
+            schemaVersion: 1,
+            stateKey,
+            policyDigest: this.policy.policyDigest,
+            assumptionsDigest: this.policy.assumptions.assumptionsDigest,
+            revision,
+            sampleCount: (prior?.sampleCount ?? 0) + 1,
+            sequenceHighWater: sample.sequence,
+            logicalTimeHighWaterMs: sample.logicalTimeMs,
+            lastSampleDigest: sampleDigest,
+            metrics,
+            recentEvidenceDigests: appendRecentUnique(prior?.recentEvidenceDigests ?? [], sample.assessmentDigest, this.policy.maximumRetainedEvidenceDigests),
+            predecessorStateDigest: prior?.stateDigest ?? null,
+        };
+        return deepFreeze({
+            ...body,
+            stateDigest: digestSemanticGuarantee("state", body),
+        });
+    }
+    #guaranteeFrom(state) {
+        const metric = (key) => boundFor(state.metrics[key], this.policy.metrics[key]);
+        return deepFreeze({
+            schemaVersion: 1,
+            stateKey: state.stateKey,
+            policyDigest: state.policyDigest,
+            assumptionsDigest: state.assumptionsDigest,
+            stateDigest: state.stateDigest,
+            throughSequence: state.sequenceHighWater,
+            throughLogicalTimeMs: state.logicalTimeHighWaterMs,
+            familywiseErrorBudgetPpm: this.policy.familywiseErrorBudgetPpm,
+            simultaneousConfidenceBasisPoints: Math.floor((1 - this.policy.familywiseErrorBudgetPpm / 1_000_000) * 10_000),
+            minimumInferenceSamples: this.policy.minimumInferenceSamples,
+            estimand: "average_conditional_mean",
+            roleCoherence: metric("roleCoherence"),
+            missionAlignment: metric("missionAlignment"),
+            contextConflict: metric("contextConflict"),
+            uncertainty: metric("uncertainty"),
+            courseActionDiversity: metric("courseActionDiversity"),
+            courseActionNovelty: metric("courseActionNovelty"),
+            evidenceDigests: state.recentEvidenceDigests,
+        });
+    }
+    async #assertStateAndAnchor(stateKey, state) {
+        const anchor = await this.#readAnchor(stateKey);
+        if (!state) {
+            if (anchor)
+                throw new TypeError("semantic_guarantee_state_missing_below_anchor");
+            return;
+        }
+        validateState(state, stateKey, this.policy);
+        if (!anchor ||
+            anchor.revision !== state.revision ||
+            anchor.sequenceHighWater !== state.sequenceHighWater ||
+            anchor.logicalTimeHighWaterMs !== state.logicalTimeHighWaterMs ||
+            anchor.stateDigest !== state.stateDigest)
+            throw new TypeError("semantic_guarantee_state_anchor_mismatch");
+    }
+}
+/** Nominal check for the concrete time-uniform guarantee engine. */
+export function isAnytimeSemanticGuaranteeEngineV1(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        anytimeSemanticGuaranteeEngineInvokersV1.has(value));
+}
+/** Appends through the construction-time engine closure. */
+export function invokeAnytimeSemanticGuaranteeAppendV1(engine, input) {
+    const invoke = typeof engine === "object" && engine !== null
+        ? anytimeSemanticGuaranteeEngineInvokersV1.get(engine)?.append
+        : undefined;
+    if (!invoke)
+        throw new TypeError("concrete_anytime_semantic_guarantee_engine_required");
+    return invoke(input);
+}
+/** Reads through the construction-time engine closure. */
+export function invokeAnytimeSemanticGuaranteeCurrentV1(engine, stateKey) {
+    const invoke = typeof engine === "object" && engine !== null
+        ? anytimeSemanticGuaranteeEngineInvokersV1.get(engine)?.current
+        : undefined;
+    if (!invoke)
+        throw new TypeError("concrete_anytime_semantic_guarantee_engine_required");
+    return invoke(stateKey);
+}
+/** Exhaustively validates a portable guarantee before it can authorize control. */
+export function validateAnytimeSemanticGuaranteeV1(input) {
+    exactKeys(input, [
+        "assumptionsDigest",
+        "contextConflict",
+        "courseActionDiversity",
+        "courseActionNovelty",
+        "estimand",
+        "evidenceDigests",
+        "familywiseErrorBudgetPpm",
+        "minimumInferenceSamples",
+        "missionAlignment",
+        "policyDigest",
+        "roleCoherence",
+        "schemaVersion",
+        "simultaneousConfidenceBasisPoints",
+        "stateDigest",
+        "stateKey",
+        "throughLogicalTimeMs",
+        "throughSequence",
+        "uncertainty",
+    ], "semantic guarantee");
+    if (input.schemaVersion !== 1)
+        throw new TypeError("semantic_guarantee_schema_invalid");
+    identifier(input.stateKey, "guarantee.stateKey");
+    digest(input.policyDigest, "guarantee.policyDigest");
+    digest(input.assumptionsDigest, "guarantee.assumptionsDigest");
+    digest(input.stateDigest, "guarantee.stateDigest");
+    integer(input.throughSequence, "guarantee.throughSequence", 1, Number.MAX_SAFE_INTEGER);
+    integer(input.throughLogicalTimeMs, "guarantee.throughLogicalTimeMs", 0, Number.MAX_SAFE_INTEGER);
+    integer(input.familywiseErrorBudgetPpm, "guarantee.familywiseErrorBudgetPpm", 1, 499_999);
+    const confidence = Math.floor((1 - input.familywiseErrorBudgetPpm / 1_000_000) * 10_000);
+    if (input.simultaneousConfidenceBasisPoints !== confidence)
+        throw new TypeError("semantic_guarantee_confidence_invalid");
+    integer(input.minimumInferenceSamples, "guarantee.minimumInferenceSamples", 1, 1_000_000_000);
+    if (input.estimand !== "average_conditional_mean")
+        throw new TypeError("semantic_guarantee_estimand_invalid");
+    uniqueDigests(input.evidenceDigests, "guarantee.evidenceDigests", false);
+    let sampleCount = null;
+    let allocatedErrorPpm = 0;
+    for (const metric of SEMANTIC_GUARANTEE_METRICS_V1) {
+        const bound = input[metric];
+        exactKeys(bound, [
+            "currentLookErrorBudgetPpm",
+            "errorBudgetPpm",
+            "inferenceCount",
+            "latestWasMissing",
+            "lowerBasisPoints",
+            "meanBasisPoints",
+            "missingCount",
+            "missingness",
+            "reportedCount",
+            "sumBasisPoints",
+            "upperBasisPoints",
+        ], `semantic guarantee ${metric}`);
+        integer(bound.reportedCount, `${metric}.reportedCount`, 0, Number.MAX_SAFE_INTEGER);
+        integer(bound.missingCount, `${metric}.missingCount`, 0, Number.MAX_SAFE_INTEGER);
+        const total = bound.reportedCount + bound.missingCount;
+        if (!Number.isSafeInteger(total))
+            throw new TypeError(`semantic_guarantee_${metric}_count_invalid`);
+        if (sampleCount === null)
+            sampleCount = total;
+        else if (sampleCount !== total)
+            throw new TypeError("semantic_guarantee_metric_sample_counts_differ");
+        integer(bound.inferenceCount, `${metric}.inferenceCount`, 0, total);
+        if (!["fail_closed", "predictable_skip", "worst_case_imputation"].includes(bound.missingness) ||
+            typeof bound.latestWasMissing !== "boolean")
+            throw new TypeError(`semantic_guarantee_${metric}_missingness_invalid`);
+        const expectedInferenceCount = bound.missingness === "worst_case_imputation"
+            ? total
+            : bound.reportedCount;
+        if (bound.inferenceCount !== expectedInferenceCount)
+            throw new TypeError(`semantic_guarantee_${metric}_inference_count_invalid`);
+        integer(bound.sumBasisPoints, `${metric}.sumBasisPoints`, 0, bound.inferenceCount * 10_000);
+        integer(bound.errorBudgetPpm, `${metric}.errorBudgetPpm`, 1, 499_999);
+        allocatedErrorPpm += bound.errorBudgetPpm;
+        validateMetricBound(bound, metric);
+    }
+    if (allocatedErrorPpm > input.familywiseErrorBudgetPpm)
+        throw new TypeError("semantic_guarantee_error_budget_invalid");
+    return deepFreeze(input);
+}
+/** Exhaustively validates a horizon decision and its exact guarantee binding. */
+export function validateSemanticHorizonDecisionV1(input, guarantee) {
+    validateAnytimeSemanticGuaranteeV1(guarantee);
+    exactKeys(input, [
+        "assumptionsDigest",
+        "controlPolicyDigest",
+        "directive",
+        "guaranteeStateDigest",
+        "policyDigest",
+        "reasonCodes",
+        "recommendedHorizonSteps",
+        "replanRequired",
+        "schemaVersion",
+    ], "semantic horizon decision");
+    if (input.schemaVersion !== 1 ||
+        !["continue", "shorten_horizon", "replan", "safe_stop"].includes(input.directive))
+        throw new TypeError("semantic_horizon_decision_directive_invalid");
+    integer(input.recommendedHorizonSteps, "semanticHorizon.recommendedHorizonSteps", 0, 1_000_000_000);
+    if ((input.directive === "safe_stop" && input.recommendedHorizonSteps !== 0) ||
+        ((input.directive === "continue" ||
+            input.directive === "shorten_horizon") &&
+            input.recommendedHorizonSteps === 0))
+        throw new TypeError("semantic_horizon_decision_horizon_invalid");
+    const replanRequired = input.directive === "replan" || input.directive === "safe_stop";
+    if (input.replanRequired !== replanRequired)
+        throw new TypeError("semantic_horizon_decision_replan_invalid");
+    digest(input.guaranteeStateDigest, "decision.guaranteeStateDigest");
+    digest(input.policyDigest, "decision.policyDigest");
+    digest(input.assumptionsDigest, "decision.assumptionsDigest");
+    digest(input.controlPolicyDigest, "decision.controlPolicyDigest");
+    if (input.guaranteeStateDigest !== guarantee.stateDigest ||
+        input.policyDigest !== guarantee.policyDigest ||
+        input.assumptionsDigest !== guarantee.assumptionsDigest)
+        throw new TypeError("semantic_horizon_decision_binding_invalid");
+    uniqueTokens(input.reasonCodes, "decision.reasonCodes");
+    return deepFreeze(input);
+}
+export function createSemanticHorizonControlPolicyV1(input) {
+    const expectedGuaranteePolicyDigest = input.expectedGuaranteePolicyDigest;
+    const expectedAssumptionsDigest = input.expectedAssumptionsDigest;
+    const nominalHorizonSteps = input.nominalHorizonSteps;
+    const cautionHorizonSteps = input.cautionHorizonSteps;
+    const replanHorizonSteps = input.replanHorizonSteps;
+    const thresholdInputs = input.thresholds;
+    digest(expectedGuaranteePolicyDigest, "expectedGuaranteePolicyDigest");
+    digest(expectedAssumptionsDigest, "expectedAssumptionsDigest");
+    integer(nominalHorizonSteps, "nominalHorizonSteps", 1, 1_000_000_000);
+    integer(cautionHorizonSteps, "cautionHorizonSteps", 1, nominalHorizonSteps);
+    integer(replanHorizonSteps, "replanHorizonSteps", 0, cautionHorizonSteps);
+    const thresholds = {};
+    for (const metric of SEMANTIC_GUARANTEE_METRICS_V1) {
+        const threshold = thresholdInputs[metric];
+        if (!threshold)
+            throw new TypeError(`semantic_horizon_${metric}_threshold_invalid`);
+        const thresholdBasisPoints = threshold.thresholdBasisPoints;
+        const enabled = threshold.enabled;
+        if (typeof enabled !== "boolean")
+            throw new TypeError(`semantic_horizon_${metric}_threshold_invalid`);
+        integer(thresholdBasisPoints, `${metric}.thresholdBasisPoints`, 0, 10_000);
+        thresholds[metric] = Object.freeze({
+            thresholdBasisPoints,
+            enabled,
+        });
+    }
+    const body = {
+        schemaVersion: 1,
+        expectedGuaranteePolicyDigest,
+        expectedAssumptionsDigest,
+        nominalHorizonSteps,
+        cautionHorizonSteps,
+        replanHorizonSteps,
+        thresholds,
+    };
+    return deepFreeze({
+        ...body,
+        controlPolicyDigest: digestSemanticGuarantee("horizon-control-policy", body),
+    });
+}
+export function createSemanticHorizonControlV1(raw) {
+    const policy = validateHorizonPolicy(raw);
+    const decide = (guarantee) => {
+        if (guarantee.policyDigest !== policy.expectedGuaranteePolicyDigest ||
+            guarantee.assumptionsDigest !== policy.expectedAssumptionsDigest)
+            throw new TypeError("semantic_horizon_guarantee_binding_invalid");
+        const missingFailClosed = [];
+        const insufficient = [];
+        const provenViolation = [];
+        const notYetGuaranteed = [];
+        for (const metric of SEMANTIC_GUARANTEE_METRICS_V1) {
+            const threshold = policy.thresholds[metric];
+            if (!threshold.enabled)
+                continue;
+            const bound = guarantee[metric];
+            if (bound.missingCount > 0 && bound.missingness === "fail_closed") {
+                missingFailClosed.push(`${metric}_missing_fail_closed`);
+                continue;
+            }
+            if (bound.inferenceCount === 0 ||
+                bound.inferenceCount < policyMinimum(guarantee, metric)) {
+                insufficient.push(`${metric}_insufficient_evidence`);
+                continue;
+            }
+            if (bound.lowerBasisPoints === null || bound.upperBasisPoints === null) {
+                insufficient.push(`${metric}_bound_unavailable`);
+                continue;
+            }
+            if (EXPECTED_DIRECTIONS[metric] === "higher_is_better") {
+                if (bound.upperBasisPoints < threshold.thresholdBasisPoints)
+                    provenViolation.push(`${metric}_threshold_violated`);
+                else if (bound.lowerBasisPoints < threshold.thresholdBasisPoints)
+                    notYetGuaranteed.push(`${metric}_threshold_not_guaranteed`);
+            }
+            else {
+                if (bound.lowerBasisPoints > threshold.thresholdBasisPoints)
+                    provenViolation.push(`${metric}_threshold_violated`);
+                else if (bound.upperBasisPoints > threshold.thresholdBasisPoints)
+                    notYetGuaranteed.push(`${metric}_threshold_not_guaranteed`);
+            }
+        }
+        let directive;
+        let recommendedHorizonSteps;
+        if (missingFailClosed.length) {
+            directive = "safe_stop";
+            recommendedHorizonSteps = 0;
+        }
+        else if (provenViolation.length) {
+            directive = "replan";
+            recommendedHorizonSteps = policy.replanHorizonSteps;
+        }
+        else if (insufficient.length || notYetGuaranteed.length) {
+            directive = "shorten_horizon";
+            recommendedHorizonSteps = policy.cautionHorizonSteps;
+        }
+        else {
+            directive = "continue";
+            recommendedHorizonSteps = policy.nominalHorizonSteps;
+        }
+        const reasonCodes = [
+            ...missingFailClosed,
+            ...provenViolation,
+            ...insufficient,
+            ...notYetGuaranteed,
+        ].sort();
+        if (!reasonCodes.length)
+            reasonCodes.push("semantic_confidence_sequences_within_thresholds");
+        return deepFreeze({
+            schemaVersion: 1,
+            directive,
+            recommendedHorizonSteps,
+            replanRequired: directive === "replan" || directive === "safe_stop",
+            reasonCodes,
+            guaranteeStateDigest: guarantee.stateDigest,
+            policyDigest: guarantee.policyDigest,
+            assumptionsDigest: guarantee.assumptionsDigest,
+            controlPolicyDigest: policy.controlPolicyDigest,
+        });
+    };
+    const control = Object.freeze({
+        decide(guarantee) {
+            return invokeSemanticHorizonControlV1(control, guarantee);
+        },
+    });
+    semanticHorizonControlInvokersV1.set(control, decide);
+    return control;
+}
+/** Nominal check for a library-created semantic horizon control. */
+export function isSemanticHorizonControlV1(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        semanticHorizonControlInvokersV1.has(value));
+}
+/** Decides through the immutable policy closure. */
+export function invokeSemanticHorizonControlV1(control, guarantee) {
+    const invoke = typeof control === "object" && control !== null
+        ? semanticHorizonControlInvokersV1.get(control)
+        : undefined;
+    if (!invoke)
+        throw new TypeError("concrete_semantic_horizon_control_required");
+    validateAnytimeSemanticGuaranteeV1(guarantee);
+    return validateSemanticHorizonDecisionV1(invoke(guarantee), guarantee);
+}
+function policyMinimum(guarantee, _metric) {
+    return guarantee.minimumInferenceSamples;
+}
+function boundFor(accumulator, policy) {
+    const count = accumulator.inferenceCount;
+    if (count === 0)
+        return deepFreeze({
+            ...accumulator,
+            meanBasisPoints: null,
+            lowerBasisPoints: null,
+            upperBasisPoints: null,
+            errorBudgetPpm: policy.errorBudgetPpm,
+            currentLookErrorBudgetPpm: null,
+            missingness: policy.missingness,
+        });
+    const exactMean = accumulator.sumBasisPoints / count;
+    const mean = Math.round(exactMean);
+    const lookErrorBudgetPpm = policy.errorBudgetPpm / count / (count + 1);
+    const alpha = lookErrorBudgetPpm / 1_000_000;
+    const margin = 10_000 * Math.sqrt(Math.log(2 / alpha) / (2 * count));
+    return deepFreeze({
+        ...accumulator,
+        meanBasisPoints: mean,
+        lowerBasisPoints: clampBps(Math.floor(exactMean - margin)),
+        upperBasisPoints: clampBps(Math.ceil(exactMean + margin)),
+        errorBudgetPpm: policy.errorBudgetPpm,
+        currentLookErrorBudgetPpm: lookErrorBudgetPpm,
+        missingness: policy.missingness,
+    });
+}
+function advanceAccumulator(prior, value, policy) {
+    if (value !== null)
+        return deepFreeze({
+            reportedCount: prior.reportedCount + 1,
+            missingCount: prior.missingCount,
+            inferenceCount: prior.inferenceCount + 1,
+            sumBasisPoints: prior.sumBasisPoints + value,
+            latestWasMissing: false,
+        });
+    const impute = policy.missingness === "worst_case_imputation";
+    const worst = policy.direction === "higher_is_better" ? 0 : 10_000;
+    return deepFreeze({
+        reportedCount: prior.reportedCount,
+        missingCount: prior.missingCount + 1,
+        inferenceCount: prior.inferenceCount + (impute ? 1 : 0),
+        sumBasisPoints: prior.sumBasisPoints + (impute ? worst : 0),
+        latestWasMissing: true,
+    });
+}
+function emptyAccumulator() {
+    return Object.freeze({
+        reportedCount: 0,
+        missingCount: 0,
+        inferenceCount: 0,
+        sumBasisPoints: 0,
+        latestWasMissing: false,
+    });
+}
+function validateState(state, stateKey, policy) {
+    if (state.format !== ANYTIME_SEMANTIC_GUARANTEE_STATE_FORMAT_V1 ||
+        state.schemaVersion !== 1 ||
+        state.stateKey !== stateKey ||
+        state.policyDigest !== policy.policyDigest ||
+        state.assumptionsDigest !== policy.assumptions.assumptionsDigest)
+        throw new TypeError("semantic_guarantee_state_binding_invalid");
+    integer(state.revision, "state.revision", 1, Number.MAX_SAFE_INTEGER);
+    integer(state.sampleCount, "state.sampleCount", 1, Number.MAX_SAFE_INTEGER);
+    if (state.revision !== state.sampleCount)
+        throw new TypeError("semantic_guarantee_state_revision_invalid");
+    integer(state.sequenceHighWater, "state.sequenceHighWater", 1, Number.MAX_SAFE_INTEGER);
+    integer(state.logicalTimeHighWaterMs, "state.logicalTimeHighWaterMs", 0, Number.MAX_SAFE_INTEGER);
+    digest(state.lastSampleDigest, "state.lastSampleDigest");
+    if (state.predecessorStateDigest !== null)
+        digest(state.predecessorStateDigest, "state.predecessorStateDigest");
+    if (state.recentEvidenceDigests.length > policy.maximumRetainedEvidenceDigests)
+        throw new TypeError("semantic_guarantee_evidence_bound_exceeded");
+    uniqueDigests(state.recentEvidenceDigests, "state.recentEvidenceDigests", false);
+    for (const metric of SEMANTIC_GUARANTEE_METRICS_V1) {
+        const value = state.metrics[metric];
+        if (!value)
+            throw new TypeError(`semantic_guarantee_${metric}_state_missing`);
+        integer(value.reportedCount, `${metric}.reportedCount`, 0, state.sampleCount);
+        integer(value.missingCount, `${metric}.missingCount`, 0, state.sampleCount);
+        integer(value.inferenceCount, `${metric}.inferenceCount`, 0, state.sampleCount);
+        integer(value.sumBasisPoints, `${metric}.sumBasisPoints`, 0, value.inferenceCount * 10_000);
+        if (value.reportedCount + value.missingCount !== state.sampleCount)
+            throw new TypeError(`semantic_guarantee_${metric}_count_invalid`);
+        const expectedInferenceCount = policy.metrics[metric].missingness === "worst_case_imputation"
+            ? state.sampleCount
+            : value.reportedCount;
+        if (value.inferenceCount !== expectedInferenceCount)
+            throw new TypeError(`semantic_guarantee_${metric}_inference_count_invalid`);
+    }
+    const { stateDigest, ...body } = state;
+    digest(stateDigest, "state.stateDigest");
+    if (digestSemanticGuarantee("state", body) !== stateDigest)
+        throw new TypeError("semantic_guarantee_state_digest_invalid");
+}
+function validatePolicy(policy) {
+    const schemaVersion = policy.schemaVersion;
+    const policyDigest = policy.policyDigest;
+    const assumptions = policy.assumptions;
+    const recreated = createAnytimeSemanticGuaranteePolicyV1({
+        policyId: policy.policyId,
+        familywiseErrorBudgetPpm: policy.familywiseErrorBudgetPpm,
+        minimumInferenceSamples: policy.minimumInferenceSamples,
+        maximumRetainedEvidenceDigests: policy.maximumRetainedEvidenceDigests,
+        maximumCasAttempts: policy.maximumCasAttempts,
+        metrics: policy.metrics,
+        assumptions: {
+            assumptionEvidenceDigests: assumptions.assumptionEvidenceDigests,
+        },
+    });
+    if (schemaVersion !== 1 ||
+        policy.boundMethod !== "hoeffding_azuma_two_sided" ||
+        policy.spendingSchedule !== "inverse_quadratic_telescoping" ||
+        policyDigest !== recreated.policyDigest ||
+        assumptions.assumptionsDigest !== recreated.assumptions.assumptionsDigest)
+        throw new TypeError("semantic_guarantee_policy_digest_invalid");
+    return recreated;
+}
+function validateHorizonPolicy(policy) {
+    const schemaVersion = policy.schemaVersion;
+    const controlPolicyDigest = policy.controlPolicyDigest;
+    const recreated = createSemanticHorizonControlPolicyV1({
+        expectedGuaranteePolicyDigest: policy.expectedGuaranteePolicyDigest,
+        expectedAssumptionsDigest: policy.expectedAssumptionsDigest,
+        nominalHorizonSteps: policy.nominalHorizonSteps,
+        cautionHorizonSteps: policy.cautionHorizonSteps,
+        replanHorizonSteps: policy.replanHorizonSteps,
+        thresholds: policy.thresholds,
+    });
+    if (schemaVersion !== 1 ||
+        controlPolicyDigest !== recreated.controlPolicyDigest)
+        throw new TypeError("semantic_horizon_control_policy_digest_invalid");
+    return recreated;
+}
+function validateSample(sample) {
+    if (!sample ||
+        typeof sample !== "object" ||
+        !sample.metrics ||
+        typeof sample.metrics !== "object")
+        throw new TypeError("semantic_guarantee_sample_invalid");
+    integer(sample.sequence, "sample.sequence", 1, Number.MAX_SAFE_INTEGER);
+    integer(sample.logicalTimeMs, "sample.logicalTimeMs", 0, Number.MAX_SAFE_INTEGER);
+    digest(sample.assessmentDigest, "sample.assessmentDigest");
+    for (const key of Object.values(VECTOR_KEYS)) {
+        const value = sample.metrics[key];
+        if (value !== null)
+            integer(value, `sample.metrics.${key}`, 0, 10_000);
+    }
+}
+function immutableSemanticGuaranteeValue(value) {
+    return {
+        value,
+        writable: false,
+        configurable: false,
+        enumerable: true,
+    };
+}
+function validateMetricBound(bound, metric) {
+    if (bound.missingCount === 0 && bound.latestWasMissing)
+        throw new TypeError(`semantic_guarantee_${metric}_latest_missing_invalid`);
+    if (bound.inferenceCount === 0) {
+        if (bound.sumBasisPoints !== 0 ||
+            bound.meanBasisPoints !== null ||
+            bound.lowerBasisPoints !== null ||
+            bound.upperBasisPoints !== null ||
+            bound.currentLookErrorBudgetPpm !== null)
+            throw new TypeError(`semantic_guarantee_${metric}_empty_bound_invalid`);
+        return;
+    }
+    const count = bound.inferenceCount;
+    const exactMean = bound.sumBasisPoints / count;
+    const expectedMean = Math.round(exactMean);
+    const expectedLook = bound.errorBudgetPpm / count / (count + 1);
+    if (typeof bound.currentLookErrorBudgetPpm !== "number" ||
+        !Number.isFinite(bound.currentLookErrorBudgetPpm) ||
+        bound.currentLookErrorBudgetPpm !== expectedLook)
+        throw new TypeError(`semantic_guarantee_${metric}_look_budget_invalid`);
+    const alpha = expectedLook / 1_000_000;
+    const margin = 10_000 * Math.sqrt(Math.log(2 / alpha) / (2 * count));
+    const expectedLower = clampBps(Math.floor(exactMean - margin));
+    const expectedUpper = clampBps(Math.ceil(exactMean + margin));
+    if (bound.meanBasisPoints !== expectedMean ||
+        bound.lowerBasisPoints !== expectedLower ||
+        bound.upperBasisPoints !== expectedUpper)
+        throw new TypeError(`semantic_guarantee_${metric}_bound_invalid`);
+}
+function exactKeys(value, expected, name) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new TypeError(`${name}_invalid`);
+    const actual = Object.keys(value).sort();
+    const canonical = [...expected].sort();
+    if (actual.length !== canonical.length ||
+        actual.some((key, index) => key !== canonical[index]))
+        throw new TypeError(`${name}_keys_invalid`);
+}
+function uniqueTokens(values, name) {
+    if (!Array.isArray(values) || values.length < 1 || values.length > 128)
+        throw new TypeError(`${name}_invalid`);
+    const prior = new Set();
+    for (const value of values) {
+        identifier(value, name);
+        if (prior.has(value))
+            throw new TypeError(`${name}_contains_duplicates`);
+        prior.add(value);
+    }
+    if (values.some((value, index) => index > 0 && values[index - 1] > value))
+        throw new TypeError(`${name}_not_canonical`);
+}
+function digestSemanticGuarantee(domain, value) {
+    return digestControlJsonV1("state", {
+        semanticGuaranteeDomain: domain,
+        value,
+    });
+}
+function uniqueDigests(values, name, sort = true) {
+    if (!Array.isArray(values))
+        throw new TypeError(`${name}_must_be_array`);
+    for (const value of values)
+        digest(value, name);
+    const unique = [...new Set(values)];
+    if (unique.length !== values.length)
+        throw new TypeError(`${name}_contains_duplicates`);
+    return Object.freeze(sort ? unique.sort() : unique);
+}
+function appendRecentUnique(prior, next, maximum) {
+    return Object.freeze([...prior.filter((value) => value !== next), next].slice(-maximum));
+}
+function digest(value, name) {
+    if (!/^sha256:[a-f0-9]{64}$/.test(value))
+        throw new TypeError(`${name}_invalid`);
+}
+function identifier(value, name) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,239}$/.test(value))
+        throw new TypeError(`${name}_invalid`);
+}
+function integer(value, name, minimum, maximum) {
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum)
+        throw new RangeError(`${name}_invalid`);
+}
+function clampBps(value) {
+    return Math.max(0, Math.min(10_000, value));
+}
+function deepFreeze(value) {
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}
+//# sourceMappingURL=anytime-semantic-guarantees.js.map