ai-capability-framework 1.0.3 → 1.1.0

package/dist/runtime/bounded-json.js

@@ -0,0 +1,74 @@
+/** Bounds strict JSON while traversing, before allocating a complete serialization or clone. */
+export function boundedJsonSnapshot(value, maxBytes) {
+    let bytes = 0;
+    const ancestors = new Set();
+    const add = (text) => {
+        bytes += Buffer.byteLength(text);
+        if (bytes > maxBytes)
+            throw invalid();
+        return text;
+    };
+    const walk = (entry, depth) => {
+        if (depth > 32)
+            throw invalid();
+        if (entry === null || typeof entry === "boolean" || typeof entry === "number" && Number.isFinite(entry)) {
+            return add(JSON.stringify(entry));
+        }
+        if (typeof entry === "string") {
+            if (entry.length > maxBytes)
+                throw invalid();
+            return add(JSON.stringify(entry));
+        }
+        if (typeof entry !== "object" || !entry || ancestors.has(entry) || Object.getOwnPropertySymbols(entry).length)
+            throw invalid();
+        const array = Array.isArray(entry);
+        if (array ? entry.length > maxBytes : ![Object.prototype, null].includes(Object.getPrototypeOf(entry)))
+            throw invalid();
+        ancestors.add(entry);
+        try {
+            const descriptors = Object.getOwnPropertyDescriptors(entry);
+            const keys = Object.keys(descriptors);
+            if (keys.length > maxBytes)
+                throw invalid();
+            if (array) {
+                if (keys.length !== entry.length + 1)
+                    throw invalid();
+                const pieces = [add("[")];
+                for (let index = 0; index < entry.length; index++) {
+                    const descriptor = descriptors[String(index)];
+                    if (!descriptor || !descriptor.enumerable || !("value" in descriptor))
+                        throw invalid();
+                    if (index)
+                        pieces.push(add(","));
+                    pieces.push(walk(descriptor.value, depth + 1));
+                }
+                pieces.push(add("]"));
+                return pieces.join("");
+            }
+            const pieces = [add("{")];
+            for (const [index, key] of keys.sort().entries()) {
+                const descriptor = descriptors[key];
+                if (!descriptor.enumerable || !("value" in descriptor))
+                    throw invalid();
+                if (index)
+                    pieces.push(add(","));
+                pieces.push(add(JSON.stringify(key)), add(":"), walk(descriptor.value, depth + 1));
+            }
+            pieces.push(add("}"));
+            return pieces.join("");
+        }
+        finally {
+            ancestors.delete(entry);
+        }
+    };
+    return JSON.parse(walk(value, 0));
+}
+export function deepFreeze(value) {
+    if (value && typeof value === "object") {
+        for (const entry of Object.values(value))
+            deepFreeze(entry);
+        Object.freeze(value);
+    }
+    return value;
+}
+function invalid() { return new Error("Bounded finite JSON without accessors or cycles is required."); }

package/dist/runtime/eligibility.d.ts

@@ -0,0 +1,4 @@
+import type { CapabilityEligibilityResult, CapabilityRouteRequest } from "./types.js";
+/** Enumerates the full eligible registry without scoring or count truncation. */
+export declare function filterEligibleCapabilities(request: CapabilityRouteRequest): CapabilityEligibilityResult;
+//# sourceMappingURL=eligibility.d.ts.map

package/dist/runtime/eligibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eligibility.d.ts","sourceRoot":"","sources":["../../src/runtime/eligibility.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAsB,2BAA2B,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAU1G,iFAAiF;AACjF,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,sBAAsB,GAAG,2BAA2B,CAUvG"}

package/dist/runtime/eligibility.js

@@ -0,0 +1,128 @@
+import { isRestrictedCapability } from "../adapter-common.js";
+import { readOnlyBlocks } from "../controls/index.js";
+const riskRank = {
+    none: 0,
+    low: 1,
+    medium: 2,
+    high: 3,
+    critical: 4
+};
+/** Enumerates the full eligible registry without scoring or count truncation. */
+export function filterEligibleCapabilities(request) {
+    const eligible = [];
+    const excluded = [];
+    const maxRiskTier = request.maxRiskTier ?? request.builtContext.runtimeContext.autonomy.maxRiskTier;
+    for (const capability of request.registry.capabilities) {
+        const reason = exclusionReason(request, capability, maxRiskTier);
+        if (reason)
+            excluded.push({ capabilityId: capability.manifest.id, reason });
+        else
+            eligible.push(capability);
+    }
+    return { eligible, excluded };
+}
+function exclusionReason(request, loadedCapability, maxRiskTier) {
+    const capability = loadedCapability.manifest;
+    if (request.includeCapabilityIds && !request.includeCapabilityIds.includes(capability.id)) {
+        return "Capability was not explicitly included.";
+    }
+    if (request.excludeCapabilityIds?.includes(capability.id)) {
+        return "Capability was explicitly excluded.";
+    }
+    const statusReason = statusExclusionReason(request, capability);
+    if (statusReason) {
+        return statusReason;
+    }
+    if (riskRank[capability.risk_tier] > riskRank[maxRiskTier]) {
+        return `Capability risk tier ${capability.risk_tier} exceeds ${maxRiskTier}.`;
+    }
+    if (isRestrictedCapability(capability) && !request.includeRestricted) {
+        return "Restricted side-effect capability was excluded.";
+    }
+    const controlsReason = controlsExclusionReason(request, loadedCapability);
+    if (controlsReason) {
+        return controlsReason;
+    }
+    const contextReason = requiredContextReason(capability, request.builtContext.runtimeContext);
+    if (contextReason) {
+        return contextReason;
+    }
+    const permissionReason = permissionExclusionReason(request, capability);
+    if (permissionReason) {
+        return permissionReason;
+    }
+    if (request.allowedDomains && (!capability.domain || !request.allowedDomains.includes(capability.domain))) {
+        return "Capability domain was not allowed.";
+    }
+    if (request.allowedCapabilityTypes && !request.allowedCapabilityTypes.includes(capability.capability_type)) {
+        return "Capability type was not allowed.";
+    }
+    return null;
+}
+function controlsExclusionReason(request, loadedCapability) {
+    if (!request.controls) {
+        return null;
+    }
+    const decision = request.controls.evaluate({
+        capability: loadedCapability,
+        capabilityId: loadedCapability.manifest.id,
+        domain: loadedCapability.manifest.domain,
+        operation: "export",
+        registry: request.registry,
+        riskTier: loadedCapability.manifest.risk_tier,
+        runtimeContext: request.builtContext.runtimeContext
+    });
+    if (decision.status === "denied") {
+        return decision.reasons[0]?.message ?? "Capability was denied by runtime controls.";
+    }
+    if (decision.status === "read_only" && readOnlyBlocks({
+        capability: loadedCapability,
+        capabilityId: loadedCapability.manifest.id,
+        operation: "export",
+        runtimeContext: request.builtContext.runtimeContext
+    })) {
+        return decision.reasons[0]?.message ?? "Read-only controls exclude this capability.";
+    }
+    return null;
+}
+function statusExclusionReason(request, capability) {
+    switch (capability.status) {
+        case "active":
+            return null;
+        case "disabled":
+            return request.includeDisabledForTests ? null : "Disabled capability was excluded.";
+        case "deprecated":
+            return request.includeDeprecated ? null : "Deprecated capability was excluded.";
+        case "draft":
+            return request.includeDraft ? null : "Draft capability was excluded.";
+        case "experimental":
+            return request.includeExperimental ? null : "Experimental capability was excluded.";
+    }
+}
+function requiredContextReason(capability, context) {
+    if (capability.authorization.requires_user_context && !hasText(context.subject.userId)) {
+        return "Capability requires user context.";
+    }
+    if (capability.authorization.tenant_scoped && !hasText(context.account.tenantId)) {
+        return "Capability requires tenant context.";
+    }
+    if (!hasText(context.account.accountId)) {
+        return "Runtime account context is required.";
+    }
+    return null;
+}
+function permissionExclusionReason(request, capability) {
+    const override = request.capabilityPermissions?.[capability.id];
+    if (override && !override.allowed) {
+        return override.reason ?? "Capability permission adapter denied access.";
+    }
+    const permissionSet = new Set([
+        ...request.builtContext.runtimeContext.subject.permissions,
+        ...(override?.permissions ?? [])
+    ]);
+    const missingPermission = capability.authorization.permissions.find((permission) => !permissionSet.has(permission));
+    return missingPermission ? `Missing permission ${missingPermission}.` : null;
+}
+function hasText(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}

package/dist/runtime/index.d.ts

@@ -8,6 +8,10 @@ export { buildRuntimeContext, DefaultContextBuilder, StaticAuthPlatformAdapter,
 export { DefaultPolicyBroker } from "./policy.js";
 export { DefaultRedactionPolicy } from "./redaction.js";
 export { DefaultCapabilityRouter, formatCapabilitySliceForModel } from "./router.js";
+export { filterEligibleCapabilities } from "./eligibility.js";
 export { InMemoryApprovalStore, InMemoryIdempotencyStore, InMemoryPreparedActionStore } from "./stores.js";
-export type { AicfActionLifecycleManagerOptions, AicfActionState, AicfActionVerificationState, AicfAccountContext, AicfApprovalDecision, AicfApprovalRequirement, AicfApprovalStore, AicfAuditEvent, AicfAuditSink, AicfAuthPlatformAdapter, AicfAutonomyContext, AicfBuiltContext, AicfCapabilityHandler, AicfCapabilityRouter, AicfCommitActionInput, AicfCommittedAction, AicfCommitResult, AicfContextBuilder, AicfContextBuilderInput, AicfContextItem, AicfHostPolicyHook, AicfIdempotencyStore, AicfPolicyBroker, AicfPolicyDecision, AicfPolicyDecisionStatus, AicfPolicyEvaluationInput, AicfPolicyReason, AicfPrepareActionInput, AicfPreparedAction, AicfPreparedActionPreview, AicfPreparedActionUpdateStateInput, AicfPreparedActionVerification, AicfPreparedActionStore, AicfRedaction, AicfRedactionPolicy, AicfRecordApprovalInput, AicfRuntimeContext, AicfRuntimeControls, AicfRuntimeEnvironment, AicfRuntimeErrorCode, AicfRuntimeEnvelopeError, AicfRuntimeToolResultEnvelope, AicfRuntimeUserInput, AicfRuntimeWarning, AicfSubjectContext, AicfToolExecutionRequest, AicfToolExecutorOptions, AicfToolResultOperation, AicfToolResultStatus, AicfVerificationResult, AicfWorkflowContext, BuildRuntimeContextInput, CapabilityRouteRequest, CapabilitySlice, CapabilitySliceItem, CreateToolEnvelopeInput, JsonObject, JsonValue, LoadedCapabilityManifest, ManifestRegistry, ModelSafeEnvelopeOptions, RuntimeCapabilitySlice } from "./types.js";
+export type { AicfActionLifecycleManagerOptions, AicfActionState, AicfActionVerificationState, AicfAccountContext, AicfApprovalDecision, AicfApprovalRequirement, AicfApprovalStore, AicfAuditEvent, AicfAuditSink, AicfAuthPlatformAdapter, AicfAutonomyContext, AicfBuiltContext, AicfCapabilityHandler, AicfCapabilityRouter, AicfCommitActionInput, AicfCommittedAction, AicfCommitResult, AicfContextBuilder, AicfContextBuilderInput, AicfContextItem, AicfHostPolicyHook, AicfIdempotencyStore, AicfPolicyBroker, AicfPolicyDecision, AicfPolicyDecisionStatus, AicfPolicyEvaluationInput, AicfPolicyReason, AicfPrepareActionInput, AicfPreparedAction, AicfPreparedActionPreview, AicfPreparedActionUpdateStateInput, AicfPreparedActionVerification, AicfPreparedActionStore, AicfRedaction, AicfRedactionPolicy, AicfRecordApprovalInput, AicfRuntimeContext, AicfRuntimeControls, AicfRuntimeEnvironment, AicfRuntimeErrorCode, AicfRuntimeEnvelopeError, AicfRuntimeToolResultEnvelope, AicfRuntimeUserInput, AicfRuntimeWarning, AicfSubjectContext, AicfToolExecutionRequest, AicfToolExecutorOptions, AicfToolResultOperation, AicfToolResultStatus, AicfVerificationResult, AicfWorkflowContext, BuildRuntimeContextInput, CapabilityRouteRequest, CapabilityEligibilityResult, CapabilitySlice, CapabilitySliceItem, CreateToolEnvelopeInput, JsonObject, JsonValue, LoadedCapabilityManifest, ManifestRegistry, ModelSafeEnvelopeOptions, RuntimeCapabilitySlice } from "./types.js";
+export { createAicfProviderRun } from "./provider-run.js";
+export type { AicfProviderRun, CreateAicfProviderRunOptions, ProviderRunSnapshot, ProviderAttemptInput, ProviderAttemptResult, ProviderBudgetScope, ProviderBudgetLedger, ProviderUsage, ModelUsage, UsageQuantity, ProviderModelConfiguration, ProviderTraceMetadata } from "./provider-types.js";
+export type { ProviderDiagnostic, ProviderStage, ProviderInvocation, ProviderUsageTotals, ProviderStageUsage, ProviderAttemptReservation, ProviderAttemptSettlement, ProviderBudgetReservation, ProviderFailureCode } from "./provider-types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACjF,OAAO,EACL,kBAAkB,EAClB,2BAA2B,EAC3B,6BAA6B,EAC7B,uBAAuB,EACxB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,yBAAyB,EACzB,sBAAsB,EACvB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,uBAAuB,EAAE,6BAA6B,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,2BAA2B,EAC5B,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,iCAAiC,EACjC,eAAe,EACf,2BAA2B,EAC3B,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,uBAAuB,EACvB,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,wBAAwB,EACxB,yBAAyB,EACzB,gBAAgB,EAChB,sBAAsB,EACtB,kBAAkB,EAClB,yBAAyB,EACzB,kCAAkC,EAClC,8BAA8B,EAC9B,uBAAuB,EACvB,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,wBAAwB,EACxB,6BAA6B,EAC7B,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,EACvB,uBAAuB,EACvB,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,wBAAwB,EACxB,sBAAsB,EACtB,eAAe,EACf,mBAAmB,EACnB,uBAAuB,EACvB,UAAU,EACV,SAAS,EACT,wBAAwB,EACxB,gBAAgB,EAChB,wBAAwB,EACxB,sBAAsB,EACvB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACjF,OAAO,EACL,kBAAkB,EAClB,2BAA2B,EAC3B,6BAA6B,EAC7B,uBAAuB,EACxB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,yBAAyB,EACzB,sBAAsB,EACvB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,uBAAuB,EAAE,6BAA6B,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,2BAA2B,EAC5B,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,iCAAiC,EACjC,eAAe,EACf,2BAA2B,EAC3B,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,uBAAuB,EACvB,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,wBAAwB,EACxB,yBAAyB,EACzB,gBAAgB,EAChB,sBAAsB,EACtB,kBAAkB,EAClB,yBAAyB,EACzB,kCAAkC,EAClC,8BAA8B,EAC9B,uBAAuB,EACvB,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,wBAAwB,EACxB,6BAA6B,EAC7B,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,EACvB,uBAAuB,EACvB,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,wBAAwB,EACxB,sBAAsB,EACtB,2BAA2B,EAC3B,eAAe,EACf,mBAAmB,EACnB,uBAAuB,EACvB,UAAU,EACV,SAAS,EACT,wBAAwB,EACxB,gBAAgB,EAChB,wBAAwB,EACxB,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,YAAY,EAAE,eAAe,EAAE,4BAA4B,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,aAAa,EAAE,UAAU,EAAE,aAAa,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACnS,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,kBAAkB,EAC1G,0BAA0B,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/runtime/index.js

@@ -8,4 +8,6 @@ export { buildRuntimeContext, DefaultContextBuilder, StaticAuthPlatformAdapter,
 export { DefaultPolicyBroker } from "./policy.js";
 export { DefaultRedactionPolicy } from "./redaction.js";
 export { DefaultCapabilityRouter, formatCapabilitySliceForModel } from "./router.js";
+export { filterEligibleCapabilities } from "./eligibility.js";
 export { InMemoryApprovalStore, InMemoryIdempotencyStore, InMemoryPreparedActionStore } from "./stores.js";
+export { createAicfProviderRun } from "./provider-run.js";

package/dist/runtime/provider-attempt.d.ts

@@ -0,0 +1,11 @@
+import type { BudgetUsage } from "../controls/types.js";
+import type { ProviderAttemptInput, ProviderAttemptResult, ProviderBudgetScope, ProviderStageUsage } from "./provider-types.js";
+export interface ProviderAttemptObserver {
+    attemptId?: string;
+    update(receipt: ProviderStageUsage): void;
+    accountingFailed(): void;
+    projectedUsage(requested: BudgetUsage): BudgetUsage;
+}
+/** A single attempt. The completion remains observed after the caller's cancellation race. */
+export declare function executeProviderAttempt<T, C extends string>(input: ProviderAttemptInput<T, C>, budget: ProviderBudgetScope, observer?: ProviderAttemptObserver): Promise<ProviderAttemptResult<T, C>>;
+//# sourceMappingURL=provider-attempt.d.ts.map

package/dist/runtime/provider-attempt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-attempt.d.ts","sourceRoot":"","sources":["../../src/runtime/provider-attempt.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,KAAK,EACV,oBAAoB,EAAE,qBAAqB,EAAE,mBAAmB,EAChE,kBAAkB,EACnB,MAAM,qBAAqB,CAAC;AAG7B,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC1C,gBAAgB,IAAI,IAAI,CAAC;IACzB,cAAc,CAAC,SAAS,EAAE,WAAW,GAAG,WAAW,CAAC;CACrD;AAED,8FAA8F;AAC9F,wBAAsB,sBAAsB,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,EAC9D,KAAK,EAAE,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,mBAAmB,EAAE,QAAQ,CAAC,EAAE,uBAAuB,GACjG,OAAO,CAAC,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAqItC"}

package/dist/runtime/provider-attempt.js

@@ -0,0 +1,221 @@
+import { performance } from "node:perf_hooks";
+import { stopGate, stopReason } from "./provider-stop.js";
+import { aggregateProviderUsage, knownUsage, ownValue, usageQuantities, validReportedUsage } from "./provider-usage.js";
+/** A single attempt. The completion remains observed after the caller's cancellation race. */
+export async function executeProviderAttempt(input, budget, observer) {
+    const request = Object.freeze({ ...input, configuration: Object.freeze({ ...input.configuration }) });
+    if (!request.runId?.trim() || !request.requestId?.trim() || !Number.isFinite(request.deadlineAt)
+        || !validConfiguration(request.configuration, request.stage)
+        || !positive(request.attempt ?? 1)
+        || !positive(request.maxInputTokens) || !["embedding_build", "query_embedding"].includes(request.stage) && !positive(request.maxOutputTokens)
+        || request.maxOutputTokens !== undefined && !positive(request.maxOutputTokens)
+        || typeof request.mock !== "boolean" || !Number.isSafeInteger(budget.policy.maxProviderCallsPerRun) || budget.policy.maxProviderCallsPerRun < 0
+        || !budget.ledger || typeof budget.ledger.reserve !== "function" || typeof budget.ledger.settle !== "function"
+        || request.maxEstimatedCostPerCall !== undefined && !nonnegative(request.maxEstimatedCostPerCall)
+        || budget.policy.maxEstimatedCostPerRun !== undefined && request.maxEstimatedCostPerCall === undefined) {
+        throw new Error("Provider attempts require valid invocation bounds, token limits and a finite shared budget.");
+    }
+    const started = performance.now();
+    let attempted = false;
+    let reasonCode;
+    let progress = { usage: {}, providerAttempts: 1, completedResponses: 0 };
+    const attempt = request.attempt ?? 1;
+    const receipt = (outcome, pending = false) => ({
+        ...(observer?.attemptId ? { attemptId: observer.attemptId } : {}), ...(reasonCode ? { reasonCode } : {}),
+        stage: request.stage, configuration: request.configuration, mock: request.mock, outcome, pending, cacheHits: 0,
+        providerAttempts: progress.providerAttempts, completedResponses: progress.completedResponses,
+        retryAttempts: Math.max(0, progress.providerAttempts - 1), repairAttempts: request.stage === "selection_repair" ? 1 : 0,
+        elapsedMs: performance.now() - started, ...usageQuantities(progress.usage, progress.providerAttempts === 0 && progress.completedResponses === 0)
+    });
+    const usage = (outcome, pending = false) => {
+        const entry = receipt(outcome, pending);
+        if (attempted)
+            observer?.update(entry);
+        return aggregateProviderUsage(attempted ? [entry] : [], performance.now() - started);
+    };
+    const failed = (code, pending = false, issues = []) => {
+        reasonCode = code;
+        return { code, issues, usage: usage(progress.completedResponses ? "discarded"
+                : code === "cancelled" || code === "deadline_exceeded" ? "cancelled" : "failed", pending) };
+    };
+    const requestedUsage = { providerCalls: 1, inputTokens: request.maxInputTokens,
+        ...(request.maxOutputTokens === undefined ? {} : { outputTokens: request.maxOutputTokens }), retries: 0,
+        ...(request.maxEstimatedCostPerCall === undefined ? {} : { estimatedCost: request.maxEstimatedCostPerCall }) };
+    const guard = () => {
+        const stop = stopReason(request);
+        if (stop)
+            return stop;
+        if (budget.policy.maxProviderCallsPerRun === 0)
+            return "budget_denied";
+        const code = request.guard?.();
+        if (code)
+            return code;
+        if (request.controls?.evaluate({ operation: "provider_call", providerId: request.configuration.provider,
+            model: request.configuration.model, runtimeContext: request.runtimeContext,
+            usage: observer?.projectedUsage(requestedUsage) ?? requestedUsage }).status === "denied")
+            return "control_denied";
+        return undefined;
+    };
+    try {
+        const code = guard();
+        if (code)
+            return failed(code);
+    }
+    catch {
+        observer?.accountingFailed();
+        return failed("accounting_unavailable");
+    }
+    const controller = new AbortController();
+    const gate = stopGate(request, controller);
+    const settle = async (id, outcome, noAttempt = false) => {
+        try {
+            await budget.ledger.settle(id, { outcome, usage: noAttempt ? {} : { ...progress.usage },
+                providerAttempts: noAttempt ? 0 : progress.providerAttempts, completedResponses: noAttempt ? 0 : progress.completedResponses,
+                elapsedMs: performance.now() - started });
+            return true;
+        }
+        catch {
+            observer?.accountingFailed();
+            return false;
+        }
+    };
+    try {
+        const reservation = Promise.resolve().then(() => budget.ledger.reserve({ runId: request.runId, requestId: request.requestId,
+            deadlineAt: request.deadlineAt, signal: controller.signal, stage: request.stage, attempt,
+            configuration: request.configuration, policy: budget.policy, requestedUsage
+        })).then(value => ({ value }), () => ({ error: true }));
+        const reserved = await Promise.race([reservation, gate.promise]);
+        if (typeof reserved === "string") {
+            void reservation.then(async (result) => {
+                if ("error" in result)
+                    observer?.accountingFailed();
+                if ("value" in result && result.value.status === "reserved")
+                    await settle(result.value.reservationId, "cancelled", true);
+            }).catch(() => observer?.accountingFailed());
+            return failed(reserved);
+        }
+        if ("error" in reserved || !reserved.value || !["denied", "reserved"].includes(reserved.value.status)) {
+            observer?.accountingFailed();
+            return failed("accounting_unavailable");
+        }
+        if (reserved.value.status === "denied")
+            return failed("budget_denied");
+        const id = reserved.value.reservationId;
+        if (typeof id !== "string" || !id.trim()) {
+            observer?.accountingFailed();
+            return failed("accounting_unavailable");
+        }
+        let before;
+        try {
+            before = guard();
+        }
+        catch {
+            before = "accounting_unavailable";
+            observer?.accountingFailed();
+        }
+        if (before) {
+            const settled = await Promise.race([settle(id, "cancelled", true), gate.promise]);
+            return failed(settled === false ? "accounting_unavailable" : before);
+        }
+        attempted = true;
+        observer?.update(receipt("completed", true));
+        const completion = (async () => {
+            let code;
+            let value;
+            let issues = [];
+            try {
+                const response = await request.invoke({ signal: controller.signal, deadlineAt: request.deadlineAt, attempt, beforeProviderCall: () => {
+                        const changed = guard();
+                        if (changed)
+                            throw new ProviderPreflightError(changed);
+                    } });
+                progress.completedResponses = 1;
+                progress.usage = knownUsage(ownValue(response, "usage"));
+                const reported = ownValue(response, "providerAttempts");
+                if (Number.isSafeInteger(reported) && reported >= 0)
+                    progress.providerAttempts = Math.max(1, reported);
+                if (reported !== 1 || !validReportedUsage(ownValue(response, "usage"))
+                    || progress.usage.inputTokens !== undefined && progress.usage.inputTokens > request.maxInputTokens
+                    || request.maxOutputTokens !== undefined && progress.usage.outputTokens !== undefined && progress.usage.outputTokens > request.maxOutputTokens)
+                    code = request.protocolError ?? "provider_unavailable";
+                else {
+                    const validated = request.validate(response);
+                    value = validated.value;
+                    code = validated.code;
+                    issues = validated.issues ?? [];
+                }
+            }
+            catch (error) {
+                if (!progress.completedResponses) {
+                    progress.usage = knownUsage(ownValue(error, "usage"));
+                    const reported = ownValue(error, "providerAttempts"), responses = ownValue(error, "completedResponses");
+                    if (Number.isSafeInteger(reported) && reported >= 0)
+                        progress.providerAttempts = reported;
+                    if (Number.isSafeInteger(responses) && responses >= 0)
+                        progress.completedResponses = responses;
+                    progress.providerAttempts = Math.max(progress.providerAttempts, progress.completedResponses);
+                    code = error instanceof ProviderPreflightError ? error.code : "provider_unavailable";
+                }
+                else
+                    code = request.protocolError ?? "provider_unavailable";
+            }
+            try {
+                if (request.estimateCost && progress.usage.estimatedCost === undefined && progress.providerAttempts > 0) {
+                    const cost = request.estimateCost(Object.freeze({ ...progress.usage }), request.configuration);
+                    if (cost !== undefined && !nonnegative(cost)) {
+                        code = "accounting_unavailable";
+                        observer?.accountingFailed();
+                    }
+                    else if (cost !== undefined)
+                        progress.usage.estimatedCost = cost;
+                }
+                const changed = guard();
+                if (changed)
+                    code = changed;
+            }
+            catch {
+                code = "accounting_unavailable";
+                observer?.accountingFailed();
+            }
+            const stop = stopReason(request);
+            if (stop)
+                code = stop;
+            const outcome = code ? progress.completedResponses ? "discarded" : stop ? "cancelled" : "failed" : "completed";
+            if (!await settle(id, outcome))
+                code = "accounting_unavailable";
+            try {
+                const changed = guard();
+                if (changed)
+                    code = changed;
+            }
+            catch {
+                code = "accounting_unavailable";
+                observer?.accountingFailed();
+            }
+            return code ? failed(code, false, issues) : { value, issues, usage: usage("completed") };
+        })().catch(() => { observer?.accountingFailed(); return failed("accounting_unavailable"); });
+        const finished = await Promise.race([completion, gate.promise]);
+        return typeof finished === "string" ? failed(finished, true) : finished;
+    }
+    finally {
+        gate.dispose();
+    }
+}
+function positive(value) { return typeof value === "number" && Number.isSafeInteger(value) && value > 0; }
+function nonnegative(value) { return typeof value === "number" && Number.isFinite(value) && value >= 0; }
+function validConfiguration(value, stage) {
+    const embedding = ["embedding_build", "query_embedding"].includes(stage);
+    return [value.provider, value.model, value.configurationId].every(item => typeof item === "string" && !!item.trim())
+        && (value.revision === undefined || typeof value.revision === "string" && !!value.revision.trim())
+        && Object.keys(value).every(key => ["provider", "model", "configurationId", "revision", ...(embedding ? ["dimensions"] : [])].includes(key));
+}
+class ProviderPreflightError extends Error {
+    code;
+    providerAttempts = 0;
+    completedResponses = 0;
+    usage = {};
+    constructor(code) {
+        super("Provider preflight denied the attempt.");
+        this.code = code;
+    }
+}

package/dist/runtime/provider-run.d.ts

@@ -0,0 +1,10 @@
+import type { AicfProviderRun, CreateAicfProviderRunOptions, ProviderTraceMetadata } from "./provider-types.js";
+export declare function isAicfProviderRun(value: unknown): value is AicfProviderRun;
+/** One in-process run journal; enforcement remains in the supplied reservation ledger. */
+export declare function createAicfProviderRun(options: CreateAicfProviderRunOptions): AicfProviderRun;
+export declare function assertProviderRunScope(run: AicfProviderRun, runId: string, budget?: {
+    ledger: unknown;
+    policy: unknown;
+}): void;
+export declare function sanitizeProviderTraceMetadata(metadata: ProviderTraceMetadata): Record<string, import("../types.js").JsonValue>;
+//# sourceMappingURL=provider-run.d.ts.map

package/dist/runtime/provider-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-run.d.ts","sourceRoot":"","sources":["../../src/runtime/provider-run.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,eAAe,EAAE,4BAA4B,EACzB,qBAAqB,EAC1C,MAAM,qBAAqB,CAAC;AAI7B,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E;AAED,0FAA0F;AAC1F,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,eAAe,CAsE5F;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAG/H;AAGD,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,aAAa,EAAE,SAAS,CAAC,CAkB9H"}

package/dist/runtime/provider-run.js

@@ -0,0 +1,123 @@
+import { isDeepStrictEqual } from "node:util";
+import { performance } from "node:perf_hooks";
+import { executeProviderAttempt } from "./provider-attempt.js";
+import { aggregateProviderUsage, freezeProviderValue } from "./provider-usage.js";
+const issued = new WeakSet();
+export function isAicfProviderRun(value) {
+    return !!value && typeof value === "object" && issued.has(value);
+}
+/** One in-process run journal; enforcement remains in the supplied reservation ledger. */
+export function createAicfProviderRun(options) {
+    if (!options.runId?.trim() || !Number.isFinite(options.deadlineAt) || !options.budget?.ledger
+        || typeof options.budget.ledger.reserve !== "function" || typeof options.budget.ledger.settle !== "function"
+        || !Number.isSafeInteger(options.budget.policy.maxProviderCallsPerRun) || options.budget.policy.maxProviderCallsPerRun < 1
+        || options.signal !== undefined && !(options.signal instanceof AbortSignal))
+        throw new Error("A provider run requires a run ID, deadline and finite budget.");
+    const runId = options.runId, deadlineAt = options.deadlineAt, signal = options.signal;
+    const budget = Object.freeze({ ledger: options.budget.ledger, policy: freezeProviderValue(structuredClone(options.budget.policy)) });
+    const sourcePolicy = options.budget.policy;
+    const started = performance.now();
+    const records = new Map();
+    const diagnostics = [];
+    const events = [];
+    let sequence = 0, broken = false;
+    const diagnostic = (code) => { if (!diagnostics.some(item => item.code === code) && diagnostics.length < 16)
+        diagnostics.push({ code, message: "A managed provider-run boundary reported a failure." }); };
+    const record = (type, requestId, metadata) => {
+        if (events.length >= 256) {
+            diagnostic("trace_overflow");
+            return;
+        }
+        const event = freezeProviderValue({ type, runId: bounded(runId), requestId: bounded(requestId), timestamp: new Date().toISOString(),
+            attributes: sanitizeProviderTraceMetadata(metadata) });
+        events.push(event);
+        try {
+            void Promise.resolve(options.traceSink?.emit(event)).catch(() => diagnostic("trace_sink_failed"));
+        }
+        catch {
+            diagnostic("trace_sink_failed");
+        }
+    };
+    const snapshot = () => {
+        const stages = [...records.values()];
+        const elapsedMs = performance.now() - started;
+        return freezeProviderValue({ runId, usage: aggregateProviderUsage(stages, elapsedMs), elapsedMs,
+            attemptElapsedMs: stages.reduce((sum, item) => sum + item.elapsedMs, 0), pendingAttempts: stages.filter(item => item.pending).length,
+            diagnostics: diagnostics.map(item => ({ ...item })), events: [...events] });
+    };
+    const run = {
+        runId, deadlineAt, signal, budget, record, snapshot,
+        async attempt(input) {
+            if (input.runId !== undefined && input.runId !== runId || input.runtimeContext && input.runtimeContext.runId !== runId)
+                throw new Error("Provider run ID mismatch.");
+            if (!isDeepStrictEqual(sourcePolicy, budget.policy)) {
+                broken = true;
+                diagnostic("accounting_unavailable");
+            }
+            const attemptId = runId + ":" + ++sequence;
+            const signals = [signal, input.signal].filter((item) => !!item);
+            let lastPending = true;
+            return executeProviderAttempt({ ...input, runId, deadlineAt: Math.min(deadlineAt, input.deadlineAt ?? Infinity),
+                signal: signals.length ? AbortSignal.any(signals) : undefined,
+                guard: () => broken ? "accounting_unavailable" : input.guard?.()
+            }, budget, {
+                attemptId,
+                accountingFailed() { broken = true; diagnostic("accounting_unavailable"); },
+                projectedUsage(requested) {
+                    const stages = [...records.values()];
+                    const result = { ...requested, runtimeMs: performance.now() - started };
+                    for (const [key, quantity] of [["inputTokens", "inputTokens"], ["outputTokens", "outputTokens"], ["estimatedCost", "estimatedCost"]])
+                        result[key] = (requested[key] ?? 0) + stages.reduce((sum, item) => sum + item[quantity].knownSubtotal, 0);
+                    result.providerCalls = (requested.providerCalls ?? 0) + stages.reduce((sum, item) => sum + item.providerAttempts, 0);
+                    // The current pending record already represents this attempt after reservation.
+                    if (records.has(attemptId))
+                        result.providerCalls -= records.get(attemptId).providerAttempts;
+                    return result;
+                },
+                update(receipt) {
+                    const first = !records.has(attemptId);
+                    records.set(attemptId, freezeProviderValue({ ...receipt, attemptId }));
+                    if (first || lastPending && !receipt.pending)
+                        record(first ? "provider.attempt.start" : "provider.attempt.end", input.requestId, {
+                            attemptId, stage: receipt.stage, configurationId: receipt.configuration.configurationId, provider: receipt.configuration.provider,
+                            model: receipt.configuration.model, mock: receipt.mock, outcome: receipt.outcome, reasonCode: receipt.reasonCode, pending: receipt.pending,
+                            providerAttempts: receipt.providerAttempts, completedResponses: receipt.completedResponses, elapsedMs: receipt.elapsedMs,
+                            inputTokens: receipt.inputTokens, outputTokens: receipt.outputTokens, totalTokens: receipt.totalTokens,
+                            cachedInputTokens: receipt.cachedInputTokens, reasoningTokens: receipt.reasoningTokens, estimatedCost: receipt.estimatedCost
+                        });
+                    lastPending = receipt.pending;
+                }
+            });
+        }
+    };
+    issued.add(run);
+    return Object.freeze(run);
+}
+export function assertProviderRunScope(run, runId, budget) {
+    if (!isAicfProviderRun(run) || run.runId !== runId || budget && (budget.ledger !== run.budget.ledger
+        || !isDeepStrictEqual(budget.policy, run.budget.policy)))
+        throw new Error("The provider run and budget scope conflict.");
+}
+function bounded(value) { return value.slice(0, 160); }
+export function sanitizeProviderTraceMetadata(metadata) {
+    const result = {};
+    const strings = ["stage", "outcome", "reasonCode", "queryId", "configurationId", "provider", "model", "fingerprint", "corpusFingerprint",
+        "indexFingerprint", "retrievalPolicyFingerprint", "eligibilityFingerprint", "attemptId"];
+    for (const key of strings) {
+        const value = Object.getOwnPropertyDescriptor(metadata, key)?.value;
+        if (typeof value === "string")
+            result[key] = bounded(value);
+    }
+    for (const key of ["candidateCount", "taskCount", "providerAttempts", "completedResponses", "elapsedMs", "pending", "mock"]) {
+        const value = Object.getOwnPropertyDescriptor(metadata, key)?.value;
+        if (typeof value === "boolean" || typeof value === "number" && Number.isFinite(value) && value >= 0)
+            result[key] = value;
+    }
+    for (const key of ["inputTokens", "outputTokens", "totalTokens", "cachedInputTokens", "reasoningTokens", "estimatedCost"]) {
+        const value = Object.getOwnPropertyDescriptor(metadata, key)?.value;
+        if (value && typeof value.complete === "boolean" && Number.isFinite(value.knownSubtotal) && value.knownSubtotal >= 0
+            && (value.total === null || Number.isFinite(value.total) && value.total >= 0))
+            result[key] = { total: value.total, knownSubtotal: value.knownSubtotal, complete: value.complete };
+    }
+    return result;
+}

package/dist/runtime/provider-stop.d.ts

@@ -0,0 +1,9 @@
+import type { ProviderInvocation } from "./provider-types.js";
+export declare function stopReason(request: Pick<ProviderInvocation, "signal" | "deadlineAt">): "cancelled" | "deadline_exceeded" | undefined;
+export declare function stopGate(request: ProviderInvocation & {
+    deadlineAt: number;
+}, controller: AbortController): {
+    promise: Promise<"cancelled" | "deadline_exceeded">;
+    dispose: () => void;
+};
+//# sourceMappingURL=provider-stop.d.ts.map

package/dist/runtime/provider-stop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-stop.d.ts","sourceRoot":"","sources":["../../src/runtime/provider-stop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,wBAAgB,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,kBAAkB,EAAE,QAAQ,GAAG,YAAY,CAAC,GAAG,WAAW,GAAG,mBAAmB,GAAG,SAAS,CAIpI;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,EAAE,UAAU,EAAE,eAAe;;;EAczG"}