@abot-ai/runtime 1.0.0 → 1.2.0

package/dist/src/runtime/orchestration/role-calls/ledger.js

@@ -2,17 +2,24 @@ import { consumeUnexpectedThenable } from "../synchronous-boundary.js";
 import { createCanonicalStateHeadFactory } from "../state-head.js";
 import { ROLE_CALL_LEDGER_HEAD_KIND, } from "./contracts.js";
 import { traceRoleCallCommit, traceRoleCallCommitFault, traceRoleCallRejection, } from "./diagnostics.js";
+import { issueCanonicalRoleOperationSupervisionTransition } from "./operation-supervision-issuance.js";
+import { isRoleOperationFingerprint } from "./operation-supervision.js";
+import { createRoleCapabilitySelectionFingerprint, normalizeRoleCapabilitySelectionProjection, } from "./capability-selection-reconsideration.js";
+import { createRoleCapabilitySelectionSupervisionFingerprint } from "./capability-selection-supervision.js";
+import { isIssuedRoleCapabilitySelectionSupervisionState, issueCanonicalRoleCapabilitySelectionSupervisionTransition, resolveRoleCapabilitySelectionSupervisionIssuanceAuthority, } from "./capability-selection-supervision-issuance.js";
 import { applyRoleCallCommand, createInitialRoleCallState, sealRoleCallPolicy, validateRoleCallCandidate, } from "./reducer.js";
 import { createRoleCallTransactions } from "./transactions.js";
 import { ROLE_CALL_WORKING_DIRECTORY_MAX_LENGTH } from "./working-directory.js";
-const createRoleCallStateHead = createCanonicalStateHeadFactory({
-    compatibilityHeadKind: ROLE_CALL_LEDGER_HEAD_KIND,
-    validationLabel: "role-call ledger head",
-    validateCandidate: validateRoleCallCandidate,
-});
+const issuedRoleCallLedgerHeads = new WeakMap();
 export function createRoleCallLedger(params) {
+    const initialState = createInitialRoleCallState(params.requestId);
+    const capabilitySelectionSupervisionIssuanceAuthority = resolveRoleCapabilitySelectionSupervisionIssuanceAuthority(initialState);
+    if (!capabilitySelectionSupervisionIssuanceAuthority) {
+        throw new Error("role_call_capability_selection_supervision_issuance_authority_missing");
+    }
+    const createRoleCallStateHead = createRoleCallStateHeadFactory(capabilitySelectionSupervisionIssuanceAuthority);
     const channel = createRoleCallStateHead({
-        state: createInitialRoleCallState(params.requestId),
+        state: initialState,
         policy: sealRoleCallPolicy(params.policy),
     });
     const commitObservers = new Set();
@@ -29,10 +36,12 @@ export function createRoleCallLedger(params) {
         const commandType = classifyCommandType(input.command);
         const capturedCommand = captureCommand(input.command);
         const commandDiagnostic = projectRejectedCommand(capturedCommand);
+        const capabilityExecutionAdmission = input.capabilityExecutionAdmission;
         const result = await channel.writer.transaction({
             expectedHead: input.expectedHead,
             run(transaction) {
-                const transition = applyRoleCallCommand(transaction.head.state, capturedCommand, transaction.head.policy);
+                const admittedCommand = projectAdmittedCapabilityExecutionCommand(commandType, capturedCommand, capabilityExecutionAdmission);
+                const transition = applyRoleCallCommand(transaction.head.state, admittedCommand, transaction.head.policy, transaction.head.revision);
                 if (!transition.ok) {
                     return {
                         kind: "transition_rejected",
@@ -40,6 +49,20 @@ export function createRoleCallLedger(params) {
                         ...(transition.issues ? { issues: transition.issues } : {}),
                     };
                 }
+                if (!issueCanonicalRoleOperationSupervisionTransition({
+                    before: transaction.head.state,
+                    after: transition.state,
+                    effect: transition.effect,
+                })) {
+                    throw new Error("role_call_operation_supervision_transition_invalid");
+                }
+                if (!issueCanonicalRoleCapabilitySelectionSupervisionTransition({
+                    before: transaction.head.state,
+                    after: transition.state,
+                    effect: transition.effect,
+                })) {
+                    throw new Error("role_call_capability_selection_supervision_transition_invalid");
+                }
                 attemptedCommitEffect = transition.effect;
                 const commit = transaction.commit({
                     state: transition.state,
@@ -107,7 +130,7 @@ export function createRoleCallLedger(params) {
         return committed;
     };
     const transactions = createRoleCallTransactions(apply);
-    return Object.freeze({
+    const ledger = Object.freeze({
         current() {
             return channel.reader.current();
         },
@@ -115,6 +138,73 @@ export function createRoleCallLedger(params) {
         transactions,
         apply,
     });
+    issuedRoleCallLedgerHeads.set(ledger, () => channel.reader.current());
+    return ledger;
+}
+/** Confirms exact current-head ownership without trusting structural ledgers. */
+export function isCurrentRoleCallLedgerHead(ledger, head) {
+    return issuedRoleCallLedgerHeads.get(ledger)?.() === head;
+}
+function createRoleCallStateHeadFactory(capabilitySelectionSupervisionIssuanceAuthority) {
+    return createCanonicalStateHeadFactory({
+        compatibilityHeadKind: ROLE_CALL_LEDGER_HEAD_KIND,
+        validationLabel: "role-call ledger head",
+        validateCandidate(candidate) {
+            const issues = validateRoleCallCandidate(candidate);
+            if (isIssuedRoleCapabilitySelectionSupervisionState({
+                state: candidate.state,
+                authority: capabilitySelectionSupervisionIssuanceAuthority,
+            }) ||
+                issues.some((issue) => issue.code === "invalid_role_capability_selection_supervision" &&
+                    issue.path === "state.capabilitySelectionSupervision")) {
+                return issues;
+            }
+            return Object.freeze([
+                ...issues,
+                Object.freeze({
+                    code: "invalid_role_capability_selection_supervision",
+                    path: "state.capabilitySelectionSupervision",
+                }),
+            ]);
+        },
+    });
+}
+function projectAdmittedCapabilityExecutionCommand(commandType, command, admission) {
+    if (admission === undefined || !isCapabilityExecutionBegin(commandType)) {
+        return command;
+    }
+    return isCapabilityExecutionCurrent(admission)
+        ? command
+        : withoutTrackedActionFingerprints(commandType, command);
+}
+function isCapabilityExecutionBegin(commandType) {
+    return (commandType === "begin_capability_execution" ||
+        commandType === "begin_capability_batch");
+}
+function isCapabilityExecutionCurrent(admission) {
+    try {
+        const result = admission.isCurrent();
+        if (consumeUnexpectedThenable(result))
+            return false;
+        return result === true;
+    }
+    catch {
+        return false;
+    }
+}
+function withoutTrackedActionFingerprints(commandType, command) {
+    if (typeof command !== "object" ||
+        command === null ||
+        Array.isArray(command)) {
+        return command;
+    }
+    const untrackedCommand = { ...command };
+    delete untrackedCommand.actionFingerprint;
+    if (commandType === "begin_capability_batch" &&
+        Array.isArray(untrackedCommand.entries)) {
+        untrackedCommand.entries = untrackedCommand.entries.map((entry) => withoutTrackedActionFingerprints("begin_capability_execution", entry));
+    }
+    return untrackedCommand;
 }
 function notifyCommitObservers(observers, commit) {
     let failed = false;
@@ -260,11 +350,52 @@ function projectRejectedCommand(input) {
             ...(safeIdentifier(command.capabilityId)
                 ? { attemptedCapabilityId: command.capabilityId }
                 : {}),
+            ...(isRoleOperationFingerprint(command.actionFingerprint)
+                ? { attemptedActionFingerprint: command.actionFingerprint }
+                : {}),
             ...(isCapabilityEffect(command.declaredEffect)
                 ? { attemptedDeclaredEffect: command.declaredEffect }
                 : {}),
         });
     }
+    if (command.type === "reconsider_capability_selection") {
+        const selection = normalizeRoleCapabilitySelectionProjection(command.selection);
+        const steeringVersion = Number.isSafeInteger(command.steeringVersion)
+            ? command.steeringVersion
+            : undefined;
+        let receiptFingerprint;
+        let supervisionFingerprint;
+        if (selection && steeringVersion !== undefined && steeringVersion >= 0) {
+            receiptFingerprint = createRoleCapabilitySelectionFingerprint({
+                steeringVersion,
+                selection,
+            });
+            supervisionFingerprint =
+                createRoleCapabilitySelectionSupervisionFingerprint({
+                    steeringVersion,
+                    selection,
+                });
+        }
+        return Object.freeze({
+            ...(safeIdentifier(command.callId)
+                ? { attemptedCallId: command.callId }
+                : {}),
+            ...(Number.isInteger(command.invocationAttempt)
+                ? { attemptedInvocationAttempt: command.invocationAttempt }
+                : {}),
+            ...(steeringVersion !== undefined
+                ? { attemptedSteeringVersion: steeringVersion }
+                : {}),
+            ...(receiptFingerprint
+                ? { attemptedSelectionReceiptFingerprint: receiptFingerprint }
+                : {}),
+            ...(supervisionFingerprint
+                ? {
+                    attemptedSelectionSupervisionFingerprint: supervisionFingerprint,
+                }
+                : {}),
+        });
+    }
     if (command.type === "update_capability_scope") {
         return Object.freeze({
             ...(safeIdentifier(command.callId)

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

@@ -0,0 +1,11 @@
+import type { RoleCallCommitEffect, RoleCallState } from "./contracts.js";
+import { type RoleOperationSupervisionInterventionRecord } from "./operation-supervision.js";
+export declare function issueCanonicalRoleOperationSupervisionTransition(input: {
+    before: RoleCallState;
+    after: RoleCallState;
+    effect: RoleCallCommitEffect;
+}): boolean;
+export declare function isIssuedRoleOperationSupervisionInterventionForRequest(input: {
+    requestId: string;
+    intervention: RoleOperationSupervisionInterventionRecord;
+}): boolean;

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 {};