@abot-ai/runtime 1.0.0 → 1.1.0

package/dist/src/runtime/orchestration/role-calls/operation-supervision-issuance.js

@@ -0,0 +1,66 @@
+import { isSameRoleOperationIdentity, } from "./operation-supervision.js";
+const issuedInterventionRequestIds = new WeakMap();
+export function issueCanonicalRoleOperationSupervisionTransition(input) {
+    if (input.effect.type === "operation_supervision_intervened") {
+        const intervention = findCanonicalInterventionRecord({
+            before: input.before,
+            after: input.after,
+            effect: input.effect,
+        });
+        if (!intervention)
+            return false;
+        issuedInterventionRequestIds.set(intervention, input.before.requestId);
+        return true;
+    }
+    if (input.effect.type === "capability_execution_settled" ||
+        input.effect.type === "capability_batch_settled") {
+        return true;
+    }
+    return input.after.operationSupervision === input.before.operationSupervision;
+}
+export function isIssuedRoleOperationSupervisionInterventionForRequest(input) {
+    return (issuedInterventionRequestIds.get(input.intervention) === input.requestId);
+}
+function findCanonicalInterventionRecord(input) {
+    const before = input.before.operationSupervision;
+    const after = input.after.operationSupervision;
+    const effect = input.effect;
+    const entryIndex = before.entries.findIndex((entry) => isSameRoleOperationIdentity(entry, effect));
+    if (after === before ||
+        entryIndex < 0 ||
+        after.entries.length !== before.entries.length ||
+        after.interventions.length !== before.interventions.length + 1 ||
+        hasChangedUnrelatedEntry(before.entries, after.entries, entryIndex) ||
+        !before.interventions.every((intervention, index) => after.interventions[index] === intervention)) {
+        return undefined;
+    }
+    const warning = before.entries[entryIndex];
+    const intervened = after.entries[entryIndex];
+    const intervention = after.interventions[after.interventions.length - 1];
+    if (warning?.stage !== "warning" ||
+        intervened?.stage !== "intervened" ||
+        !intervention ||
+        !hasMatchingInterventionEvidence(warning, effect) ||
+        !hasMatchingInterventionEvidence(intervened, effect) ||
+        !hasMatchingInterventionEvidence(intervention, effect) ||
+        !hasMatchingInterventionAttempt(intervened, effect) ||
+        !hasMatchingInterventionAttempt(intervention, effect)) {
+        return undefined;
+    }
+    return intervention;
+}
+function hasChangedUnrelatedEntry(before, after, changedIndex) {
+    return before.some((entry, index) => index !== changedIndex && after[index] !== entry);
+}
+function hasMatchingInterventionEvidence(evidence, effect) {
+    return (isSameRoleOperationIdentity(evidence, effect) &&
+        evidence.priorOutcome === effect.priorOutcome &&
+        evidence.outcomeFingerprint === effect.outcomeFingerprint &&
+        evidence.originExecutionId === effect.originExecutionId &&
+        evidence.matchingOutcomeCount === effect.matchingOutcomeCount);
+}
+function hasMatchingInterventionAttempt(intervention, effect) {
+    return (intervention.interventionCount === effect.interventionCount &&
+        intervention.interventionCallId === effect.callId &&
+        intervention.interventionInvocationAttempt === effect.invocationAttempt);
+}

package/dist/src/runtime/orchestration/role-calls/operation-supervision-projection.d.ts

@@ -0,0 +1,16 @@
+import type { RoleCallFrame, RoleCallLedgerHead } from "./contracts.js";
+export declare const ROLE_OPERATION_SUPERVISION_NOTICE_KIND: "runtime_operation_supervision_v1";
+export type RoleOperationSupervisionNotice = Readonly<{
+    kind: typeof ROLE_OPERATION_SUPERVISION_NOTICE_KIND;
+    authority: "runtime_state";
+    presenceEffect: "passive_mechanical_intervention_not_user_intent";
+    stage: "warning" | "intervention";
+    actionFingerprint: string;
+    priorOutcome: "succeeded" | "failed";
+    outcomeFingerprint: string;
+    originExecutionId: string;
+    matchingOutcomeCount: 2;
+    interventionCount: 0 | 1;
+}>;
+/** Projects only supervision evidence created for this exact activation. */
+export declare function projectImmediateRoleOperationSupervisionNotices(head: RoleCallLedgerHead, call: RoleCallFrame): readonly RoleOperationSupervisionNotice[];

package/dist/src/runtime/orchestration/role-calls/operation-supervision-projection.js

@@ -0,0 +1,52 @@
+import { isSameRoleOperationIdentity, } from "./operation-supervision.js";
+export const ROLE_OPERATION_SUPERVISION_NOTICE_KIND = "runtime_operation_supervision_v1";
+/** Projects only supervision evidence created for this exact activation. */
+export function projectImmediateRoleOperationSupervisionNotices(head, call) {
+    if (!isCurrentActiveCall(head, call))
+        return Object.freeze([]);
+    const interventions = head.state.operationSupervision.entries.filter((entry) => entry.stage === "intervened" &&
+        entry.interventionCallId === call.callId &&
+        entry.interventionInvocationAttempt + 1 === call.activationCount);
+    if (interventions.length > 0) {
+        return Object.freeze(interventions
+            .map((entry) => entry.stage === "intervened" ? createNotice(entry) : undefined)
+            .filter((notice) => notice !== undefined));
+    }
+    const notices = findImmediateSettledExecutions(head, call).flatMap((execution) => {
+        const actionFingerprint = execution.actionFingerprint;
+        if (!actionFingerprint)
+            return [];
+        const warning = head.state.operationSupervision.entries.find((entry) => entry.stage === "warning" &&
+            isSameRoleOperationIdentity(entry, {
+                capabilityId: execution.capabilityId,
+                actionFingerprint,
+            }) &&
+            entry.originExecutionId === execution.executionId);
+        return warning?.stage === "warning" ? [createNotice(warning)] : [];
+    });
+    return Object.freeze(notices);
+}
+function createNotice(entry) {
+    return Object.freeze({
+        kind: ROLE_OPERATION_SUPERVISION_NOTICE_KIND,
+        authority: "runtime_state",
+        presenceEffect: "passive_mechanical_intervention_not_user_intent",
+        stage: entry.stage === "intervened" ? "intervention" : "warning",
+        actionFingerprint: entry.actionFingerprint,
+        priorOutcome: entry.priorOutcome,
+        outcomeFingerprint: entry.outcomeFingerprint,
+        originExecutionId: entry.originExecutionId,
+        matchingOutcomeCount: entry.matchingOutcomeCount,
+        interventionCount: entry.stage === "intervened" ? entry.interventionCount : 0,
+    });
+}
+function findImmediateSettledExecutions(head, call) {
+    return head.state.capabilityExecutions.filter((execution) => execution.status === "settled" &&
+        execution.callId === call.callId &&
+        execution.invocationAttempt + 1 === call.activationCount);
+}
+function isCurrentActiveCall(head, call) {
+    return (head.state.phase === "running" &&
+        head.state.activeCallId === call.callId &&
+        call.status === "active");
+}

package/dist/src/runtime/orchestration/role-calls/operation-supervision-state-validation.d.ts

@@ -0,0 +1,3 @@
+import { type RoleOperationSupervisionSettlement, type RoleOperationSupervisionState } from "./operation-supervision.js";
+export declare function isRoleOperationSupervisionSettlementHistoryValid(settlements: readonly RoleOperationSupervisionSettlement[]): boolean;
+export declare function isRoleOperationSupervisionState(value: unknown): value is RoleOperationSupervisionState;

package/dist/src/runtime/orchestration/role-calls/operation-supervision-state-validation.js

@@ -0,0 +1,151 @@
+import { advanceRoleOperationSupervisionSettlement, createInitialRoleOperationSupervisionState, findRoleOperationSupervisionEntry, isRoleOperationFingerprint, isRoleOperationOutcomeFingerprintForOutcome, ROLE_OPERATION_INTERVENTION_LIMIT, ROLE_OPERATION_REPEAT_EXECUTION_LIMIT, } from "./operation-supervision.js";
+import { isRoleCapabilityId } from "./contracts.js";
+export function isRoleOperationSupervisionSettlementHistoryValid(settlements) {
+    let state = createInitialRoleOperationSupervisionState();
+    for (const settlement of settlements) {
+        const fingerprint = settlement.actionFingerprint;
+        const outcomeFingerprint = settlement.outcomeFingerprint;
+        if (fingerprint && outcomeFingerprint) {
+            const existing = findRoleOperationSupervisionEntry(state, {
+                capabilityId: settlement.capabilityId,
+                actionFingerprint: fingerprint,
+            });
+            if (existing?.stage === "warning" &&
+                existing.outcomeFingerprint === outcomeFingerprint) {
+                return false;
+            }
+        }
+        state = advanceRoleOperationSupervisionSettlement(state, settlement);
+    }
+    return true;
+}
+export function isRoleOperationSupervisionState(value) {
+    if (!isRecord(value) || !hasExactKeys(value, ["entries", "interventions"])) {
+        return false;
+    }
+    if (!Array.isArray(value.entries) || !Array.isArray(value.interventions)) {
+        return false;
+    }
+    const fingerprintsByCapability = new Map();
+    for (const entry of value.entries) {
+        if (!isRoleOperationSupervisionEntry(entry))
+            return false;
+        if (!registerUniqueOperationIdentity(fingerprintsByCapability, entry)) {
+            return false;
+        }
+    }
+    const interventionFingerprintsByCapability = new Map();
+    const latestAttemptByCall = new Map();
+    for (const intervention of value.interventions) {
+        if (!isRoleOperationSupervisionInterventionRecord(intervention)) {
+            return false;
+        }
+        if (!registerUniqueOperationIdentity(interventionFingerprintsByCapability, intervention)) {
+            return false;
+        }
+        const latestAttempt = latestAttemptByCall.get(intervention.interventionCallId);
+        if (latestAttempt !== undefined &&
+            intervention.interventionInvocationAttempt <= latestAttempt) {
+            return false;
+        }
+        latestAttemptByCall.set(intervention.interventionCallId, intervention.interventionInvocationAttempt);
+    }
+    return true;
+}
+function isRoleOperationSupervisionEntry(value) {
+    if (!isRecord(value) || !isBaseEntry(value))
+        return false;
+    if (value.stage === "tracking") {
+        return (hasExactKeys(value, [
+            "stage",
+            "capabilityId",
+            "actionFingerprint",
+            "priorOutcome",
+            "outcomeFingerprint",
+            "originExecutionId",
+            "matchingOutcomeCount",
+        ]) && value.matchingOutcomeCount === 1);
+    }
+    if (value.stage === "warning") {
+        return (hasExactKeys(value, [
+            "stage",
+            "capabilityId",
+            "actionFingerprint",
+            "priorOutcome",
+            "outcomeFingerprint",
+            "originExecutionId",
+            "matchingOutcomeCount",
+        ]) && value.matchingOutcomeCount === ROLE_OPERATION_REPEAT_EXECUTION_LIMIT);
+    }
+    return (value.stage === "intervened" &&
+        hasExactKeys(value, [
+            "stage",
+            "capabilityId",
+            "actionFingerprint",
+            "priorOutcome",
+            "outcomeFingerprint",
+            "originExecutionId",
+            "matchingOutcomeCount",
+            "interventionCount",
+            "interventionCallId",
+            "interventionInvocationAttempt",
+        ]) &&
+        value.matchingOutcomeCount === ROLE_OPERATION_REPEAT_EXECUTION_LIMIT &&
+        value.interventionCount === ROLE_OPERATION_INTERVENTION_LIMIT &&
+        isBoundedIdentifier(value.interventionCallId) &&
+        Number.isSafeInteger(value.interventionInvocationAttempt) &&
+        value.interventionInvocationAttempt >= 1);
+}
+function isRoleOperationSupervisionInterventionRecord(value) {
+    return (isRecord(value) &&
+        hasExactKeys(value, [
+            "capabilityId",
+            "actionFingerprint",
+            "priorOutcome",
+            "outcomeFingerprint",
+            "originExecutionId",
+            "matchingOutcomeCount",
+            "interventionCount",
+            "interventionCallId",
+            "interventionInvocationAttempt",
+        ]) &&
+        isSupervisionEvidence(value) &&
+        value.matchingOutcomeCount === ROLE_OPERATION_REPEAT_EXECUTION_LIMIT &&
+        value.interventionCount === ROLE_OPERATION_INTERVENTION_LIMIT &&
+        isBoundedIdentifier(value.interventionCallId) &&
+        Number.isSafeInteger(value.interventionInvocationAttempt) &&
+        value.interventionInvocationAttempt >= 1);
+}
+function isBaseEntry(value) {
+    return ((value.stage === "tracking" ||
+        value.stage === "warning" ||
+        value.stage === "intervened") &&
+        isSupervisionEvidence(value));
+}
+function isSupervisionEvidence(value) {
+    return (isRoleCapabilityId(value.capabilityId) &&
+        isRoleOperationFingerprint(value.actionFingerprint) &&
+        (value.priorOutcome === "succeeded" || value.priorOutcome === "failed") &&
+        isRoleOperationOutcomeFingerprintForOutcome(value.outcomeFingerprint, value.priorOutcome) &&
+        isBoundedIdentifier(value.originExecutionId));
+}
+function registerUniqueOperationIdentity(fingerprintsByCapability, identity) {
+    const fingerprints = fingerprintsByCapability.get(identity.capabilityId) ?? new Set();
+    if (fingerprints.has(identity.actionFingerprint))
+        return false;
+    fingerprints.add(identity.actionFingerprint);
+    fingerprintsByCapability.set(identity.capabilityId, fingerprints);
+    return true;
+}
+function isBoundedIdentifier(value) {
+    return typeof value === "string" && value.length > 0 && value.length <= 128;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasExactKeys(value, keys) {
+    const actual = Object.keys(value).sort();
+    const expected = [...keys].sort();
+    return (actual.length === expected.length &&
+        actual.every((key, index) => key === expected[index]));
+}

package/dist/src/runtime/orchestration/role-calls/operation-supervision.d.ts

@@ -0,0 +1,112 @@
+import type { RoleCallCommitEffect, RoleCallLedgerCommitResult, RoleCallLedgerHead, RoleCapabilityObservedEffect } from "./contracts.js";
+export declare const ROLE_OPERATION_FINGERPRINT_PATTERN: RegExp;
+export declare const ROLE_OPERATION_FAILURE_FINGERPRINT_PATTERN: RegExp;
+export declare const ROLE_OPERATION_REPEAT_EXECUTION_LIMIT: 2;
+export declare const ROLE_OPERATION_INTERVENTION_LIMIT: 1;
+export type RoleOperationFingerprint = string;
+export type RoleOperationOutcome = "succeeded" | "failed";
+export type RoleOperationOutcomeFingerprint = string;
+export type RoleOperationIdentity = Readonly<{
+    capabilityId: string;
+    actionFingerprint: RoleOperationFingerprint;
+}>;
+type RoleOperationSupervisionEntryBase = RoleOperationIdentity & Readonly<{
+    priorOutcome: RoleOperationOutcome;
+    outcomeFingerprint: RoleOperationOutcomeFingerprint;
+    originExecutionId: string;
+}>;
+export type RoleOperationSupervisionInterventionRecord = RoleOperationSupervisionEntryBase & Readonly<{
+    matchingOutcomeCount: typeof ROLE_OPERATION_REPEAT_EXECUTION_LIMIT;
+    interventionCount: typeof ROLE_OPERATION_INTERVENTION_LIMIT;
+    interventionCallId: string;
+    interventionInvocationAttempt: number;
+}>;
+export type RoleOperationSupervisionEntry = (RoleOperationSupervisionEntryBase & Readonly<{
+    stage: "tracking";
+    matchingOutcomeCount: 1;
+}>) | (RoleOperationSupervisionEntryBase & Readonly<{
+    stage: "warning";
+    matchingOutcomeCount: typeof ROLE_OPERATION_REPEAT_EXECUTION_LIMIT;
+}>) | (RoleOperationSupervisionInterventionRecord & Readonly<{
+    stage: "intervened";
+}>);
+export type RoleOperationSupervisionState = Readonly<{
+    entries: readonly RoleOperationSupervisionEntry[];
+    interventions: readonly RoleOperationSupervisionInterventionRecord[];
+}>;
+export type RoleOperationSupervisionAttemptDecision = Readonly<{
+    disposition: "execute";
+}> | Readonly<{
+    disposition: "intervene";
+    state: RoleOperationSupervisionState;
+    entry: Extract<RoleOperationSupervisionEntry, {
+        stage: "intervened";
+    }>;
+}> | Readonly<{
+    disposition: "reject";
+    issueCode: "operation_supervision_limit_exceeded";
+}>;
+export type RoleOperationSupervisionBatchAttemptDecision = Readonly<{
+    disposition: "execute";
+}> | Readonly<{
+    disposition: "intervene";
+    entryIndex: number;
+    state: RoleOperationSupervisionState;
+    entry: Extract<RoleOperationSupervisionEntry, {
+        stage: "intervened";
+    }>;
+}> | Readonly<{
+    disposition: "reject";
+    issueCode: "operation_supervision_limit_exceeded";
+}>;
+export type RoleOperationSupervisionSettlement = Readonly<{
+    capabilityId: string;
+    actionFingerprint?: RoleOperationFingerprint;
+    outcome: RoleOperationOutcome;
+    outcomeFingerprint?: RoleOperationOutcomeFingerprint;
+    observedEffect: RoleCapabilityObservedEffect;
+    originExecutionId: string;
+}>;
+export type RoleCallOperationSupervisionInterventionCommit = Readonly<{
+    ok: true;
+    status: "committed";
+    previousHead: RoleCallLedgerHead;
+    head: RoleCallLedgerHead;
+    effect: Extract<RoleCallCommitEffect, {
+        type: "operation_supervision_intervened";
+    }>;
+}>;
+export declare function createInitialRoleOperationSupervisionState(): RoleOperationSupervisionState;
+export declare function assessRoleOperationSupervisionAttempt(input: {
+    state: RoleOperationSupervisionState;
+    callId: string;
+    invocationAttempt: number;
+    capabilityId: string;
+    actionFingerprint: RoleOperationFingerprint | undefined;
+}): RoleOperationSupervisionAttemptDecision;
+export declare function assessRoleOperationSupervisionBatchAttempt(input: {
+    state: RoleOperationSupervisionState;
+    callId: string;
+    invocationAttempt: number;
+    attempts: readonly Readonly<{
+        capabilityId: string;
+        actionFingerprint?: RoleOperationFingerprint;
+    }>[];
+}): RoleOperationSupervisionBatchAttemptDecision;
+export declare function advanceRoleOperationSupervisionSettlement(current: RoleOperationSupervisionState, settlement: RoleOperationSupervisionSettlement): RoleOperationSupervisionState;
+export declare function isSuccessfulObservedMutation(input: Readonly<{
+    outcome: unknown;
+    observedEffect: unknown;
+}>): boolean;
+export declare function replayRoleOperationSupervisionSettlements(settlements: readonly RoleOperationSupervisionSettlement[]): RoleOperationSupervisionState;
+export declare function replayRoleOperationSupervisionEvidence(input: {
+    settlements: readonly RoleOperationSupervisionSettlement[];
+    interventions: readonly RoleOperationSupervisionInterventionRecord[];
+}): RoleOperationSupervisionState | undefined;
+export declare function advanceRoleOperationSupervisionIntervention(current: RoleOperationSupervisionState, intervention: RoleOperationSupervisionInterventionRecord): RoleOperationSupervisionState | undefined;
+export declare function findRoleOperationSupervisionEntry(state: RoleOperationSupervisionState, identity: RoleOperationIdentity): RoleOperationSupervisionEntry | undefined;
+export declare function isSameRoleOperationIdentity(left: RoleOperationIdentity, right: RoleOperationIdentity): boolean;
+export declare function isRoleOperationFingerprint(value: unknown): value is RoleOperationFingerprint;
+export declare function isRoleOperationOutcomeFingerprintForOutcome(value: unknown, outcome: RoleOperationOutcome): value is RoleOperationOutcomeFingerprint;
+export declare function requireRoleCallOperationSupervisionInterventionCommit(commit: RoleCallLedgerCommitResult): RoleCallOperationSupervisionInterventionCommit;
+export {};

package/dist/src/runtime/orchestration/role-calls/operation-supervision.js

@@ -0,0 +1,197 @@
+export const ROLE_OPERATION_FINGERPRINT_PATTERN = /^sha256:[a-f0-9]{64}$/;
+export const ROLE_OPERATION_FAILURE_FINGERPRINT_PATTERN = /^sha256:[a-f0-9]{64}$/;
+export const ROLE_OPERATION_REPEAT_EXECUTION_LIMIT = 2;
+export const ROLE_OPERATION_INTERVENTION_LIMIT = 1;
+export function createInitialRoleOperationSupervisionState() {
+    return Object.freeze({
+        entries: Object.freeze([]),
+        interventions: Object.freeze([]),
+    });
+}
+export function assessRoleOperationSupervisionAttempt(input) {
+    if (!input.actionFingerprint) {
+        return Object.freeze({ disposition: "execute" });
+    }
+    const entry = findRoleOperationSupervisionEntry(input.state, {
+        capabilityId: input.capabilityId,
+        actionFingerprint: input.actionFingerprint,
+    });
+    if (!entry || entry.stage === "tracking") {
+        return Object.freeze({ disposition: "execute" });
+    }
+    if (entry.stage === "intervened") {
+        return Object.freeze({
+            disposition: "reject",
+            issueCode: "operation_supervision_limit_exceeded",
+        });
+    }
+    const intervention = Object.freeze({
+        capabilityId: entry.capabilityId,
+        actionFingerprint: entry.actionFingerprint,
+        priorOutcome: entry.priorOutcome,
+        outcomeFingerprint: entry.outcomeFingerprint,
+        originExecutionId: entry.originExecutionId,
+        matchingOutcomeCount: entry.matchingOutcomeCount,
+        interventionCount: ROLE_OPERATION_INTERVENTION_LIMIT,
+        interventionCallId: input.callId,
+        interventionInvocationAttempt: input.invocationAttempt,
+    });
+    const intervenedState = advanceRoleOperationSupervisionIntervention(input.state, intervention);
+    if (!intervenedState) {
+        throw new Error("role_operation_supervision_intervention_state_invalid");
+    }
+    const intervenedEntry = findRoleOperationSupervisionEntry(intervenedState, {
+        capabilityId: entry.capabilityId,
+        actionFingerprint: entry.actionFingerprint,
+    });
+    if (intervenedEntry?.stage !== "intervened") {
+        throw new Error("role_operation_supervision_intervention_entry_missing");
+    }
+    return Object.freeze({
+        disposition: "intervene",
+        state: intervenedState,
+        entry: intervenedEntry,
+    });
+}
+export function assessRoleOperationSupervisionBatchAttempt(input) {
+    let intervention;
+    for (let entryIndex = 0; entryIndex < input.attempts.length; entryIndex += 1) {
+        const attempt = input.attempts[entryIndex];
+        const decision = assessRoleOperationSupervisionAttempt({
+            state: input.state,
+            callId: input.callId,
+            invocationAttempt: input.invocationAttempt,
+            capabilityId: attempt.capabilityId,
+            actionFingerprint: attempt.actionFingerprint,
+        });
+        if (decision.disposition === "reject")
+            return decision;
+        if (decision.disposition === "intervene" && !intervention) {
+            intervention = Object.freeze({
+                ...decision,
+                entryIndex,
+            });
+        }
+    }
+    return intervention ?? Object.freeze({ disposition: "execute" });
+}
+export function advanceRoleOperationSupervisionSettlement(current, settlement) {
+    if (isSuccessfulObservedMutation(settlement)) {
+        return createInitialRoleOperationSupervisionState();
+    }
+    if (!settlement.actionFingerprint ||
+        !settlement.outcomeFingerprint ||
+        !isRoleOperationOutcomeFingerprintForOutcome(settlement.outcomeFingerprint, settlement.outcome)) {
+        return current;
+    }
+    const trackedSettlement = Object.freeze({
+        capabilityId: settlement.capabilityId,
+        actionFingerprint: settlement.actionFingerprint,
+        outcome: settlement.outcome,
+        outcomeFingerprint: settlement.outcomeFingerprint,
+        observedEffect: settlement.observedEffect,
+        originExecutionId: settlement.originExecutionId,
+    });
+    const existing = findRoleOperationSupervisionEntry(current, trackedSettlement);
+    if (!existing) {
+        return appendRoleOperationSupervisionEntry(current, createTrackingEntry(trackedSettlement));
+    }
+    if (existing.stage === "intervened")
+        return current;
+    if (existing.outcomeFingerprint !== trackedSettlement.outcomeFingerprint) {
+        return replaceRoleOperationSupervisionEntry(current, createTrackingEntry(trackedSettlement));
+    }
+    return replaceRoleOperationSupervisionEntry(current, Object.freeze({
+        stage: "warning",
+        capabilityId: trackedSettlement.capabilityId,
+        actionFingerprint: trackedSettlement.actionFingerprint,
+        priorOutcome: trackedSettlement.outcome,
+        outcomeFingerprint: trackedSettlement.outcomeFingerprint,
+        originExecutionId: trackedSettlement.originExecutionId,
+        matchingOutcomeCount: ROLE_OPERATION_REPEAT_EXECUTION_LIMIT,
+    }));
+}
+export function isSuccessfulObservedMutation(input) {
+    return input.outcome === "succeeded" && input.observedEffect === "mutation";
+}
+export function replayRoleOperationSupervisionSettlements(settlements) {
+    return settlements.reduce(advanceRoleOperationSupervisionSettlement, createInitialRoleOperationSupervisionState());
+}
+export function replayRoleOperationSupervisionEvidence(input) {
+    let state = replayRoleOperationSupervisionSettlements(input.settlements);
+    for (const intervention of input.interventions) {
+        const next = advanceRoleOperationSupervisionIntervention(state, intervention);
+        if (!next)
+            return undefined;
+        state = next;
+    }
+    return state;
+}
+export function advanceRoleOperationSupervisionIntervention(current, intervention) {
+    const warning = findRoleOperationSupervisionEntry(current, intervention);
+    if (warning?.stage !== "warning" ||
+        !isInterventionBoundToWarning(intervention, warning)) {
+        return undefined;
+    }
+    const intervenedEntry = Object.freeze({
+        stage: "intervened",
+        ...intervention,
+    });
+    return Object.freeze({
+        entries: Object.freeze(current.entries.map((entry) => isSameRoleOperationIdentity(entry, intervenedEntry)
+            ? intervenedEntry
+            : entry)),
+        interventions: Object.freeze([...current.interventions, intervention]),
+    });
+}
+export function findRoleOperationSupervisionEntry(state, identity) {
+    return state.entries.find((entry) => isSameRoleOperationIdentity(entry, identity));
+}
+export function isSameRoleOperationIdentity(left, right) {
+    return (left.capabilityId === right.capabilityId &&
+        left.actionFingerprint === right.actionFingerprint);
+}
+export function isRoleOperationFingerprint(value) {
+    return (typeof value === "string" && ROLE_OPERATION_FINGERPRINT_PATTERN.test(value));
+}
+export function isRoleOperationOutcomeFingerprintForOutcome(value, outcome) {
+    return outcome === "succeeded"
+        ? value === "succeeded"
+        : typeof value === "string" &&
+            ROLE_OPERATION_FAILURE_FINGERPRINT_PATTERN.test(value);
+}
+export function requireRoleCallOperationSupervisionInterventionCommit(commit) {
+    if (!commit.ok || commit.effect.type !== "operation_supervision_intervened") {
+        throw new Error("role_operation_supervision_intervention_commit_invalid");
+    }
+    return commit;
+}
+function createTrackingEntry(settlement) {
+    return Object.freeze({
+        stage: "tracking",
+        capabilityId: settlement.capabilityId,
+        actionFingerprint: settlement.actionFingerprint,
+        priorOutcome: settlement.outcome,
+        outcomeFingerprint: settlement.outcomeFingerprint,
+        originExecutionId: settlement.originExecutionId,
+        matchingOutcomeCount: 1,
+    });
+}
+function appendRoleOperationSupervisionEntry(state, entry) {
+    return Object.freeze({
+        entries: Object.freeze([...state.entries, entry]),
+        interventions: state.interventions,
+    });
+}
+function replaceRoleOperationSupervisionEntry(state, replacement) {
+    return Object.freeze({
+        entries: Object.freeze(state.entries.map((entry) => isSameRoleOperationIdentity(entry, replacement) ? replacement : entry)),
+        interventions: state.interventions,
+    });
+}
+function isInterventionBoundToWarning(intervention, warning) {
+    return (intervention.priorOutcome === warning.priorOutcome &&
+        intervention.outcomeFingerprint === warning.outcomeFingerprint &&
+        intervention.originExecutionId === warning.originExecutionId &&
+        intervention.matchingOutcomeCount === warning.matchingOutcomeCount);
+}

package/dist/src/runtime/orchestration/role-calls/reconsideration-cause.d.ts

@@ -0,0 +1,26 @@
+export declare const ROLE_CAPABILITY_RECONSIDERATION_REASON_MAX_LENGTH = 320;
+export declare const ROLE_CAPABILITY_RECONSIDERATION_STAGE_MAX_LENGTH = 128;
+export declare const ROLE_CAPABILITY_RECONSIDERATION_ISSUE_CODE_MAX_LENGTH = 128;
+export declare const ROLE_CAPABILITY_RECONSIDERATION_ISSUE_PATH_MAX_LENGTH = 512;
+export declare const ROLE_CAPABILITY_RECONSIDERATION_ISSUE_LIMIT_MAX = 16;
+export declare const ROLE_CAPABILITY_RECONSIDERATION_REPAIR_LIMIT_MAX = 16;
+export type RoleCapabilityRefinementDecline = Readonly<{
+    invocationIndex: number;
+    reason: string;
+}>;
+export type RoleCapabilityRefinementValidationIssue = Readonly<{
+    code: string;
+    path: string;
+}>;
+export type RoleCapabilitySelectionReconsiderationCause = Readonly<{
+    kind: "refinement_declined";
+    entries: readonly RoleCapabilityRefinementDecline[];
+}> | Readonly<{
+    kind: "refinement_invalid_output";
+    validationStage: string;
+    issues: readonly RoleCapabilityRefinementValidationIssue[];
+    repairAttempts: number;
+    repeatedInvalidOutput: boolean;
+}>;
+export declare function normalizeRoleCapabilitySelectionReconsiderationCause(input: unknown): RoleCapabilitySelectionReconsiderationCause | undefined;
+export declare function isReconsiderationCauseBoundToInvocationCount(input: unknown, invocationCount: number): boolean;