@intx/inference 0.1.2 → 0.3.0

package/dist/assembly.js

@@ -0,0 +1,133 @@
+// Reactor assembly helper.
+//
+// `createReactorAssembly` is the canonical way to construct a reactor when the
+// caller wants the standard wiring: a default size-cap tool-result transform,
+// authz as a before-tool extension, an audit collector that flushes at
+// checkpoint and shutdown boundaries, and a `BlobReader` over the supplied
+// context store. Future reactor consumers (the harness today; in-process agent
+// runtimes tomorrow) should use this helper rather than calling `createReactor`
+// directly so the wiring stays consistent across composition points.
+import { getLogger } from "@intx/log";
+import { createBlobReader, } from "@intx/types/runtime";
+import { createAuditCollector } from "./audit-collector.js";
+import { createAuthzExtension, } from "./authz-extension.js";
+import { createReactor, } from "./reactor.js";
+import { createSizeCapTransform } from "./transforms/index.js";
+const logger = getLogger(["interchange", "assembly"]);
+const DEFAULT_SIZE_CAP_MAX_CHARS = 10_000;
+/**
+ * Build the standard reactor wiring. This is the canonical reactor-assembly
+ * path: any consumer that needs the default size-cap transform, authz, audit
+ * collection, and blob reader should call this helper instead of constructing
+ * a `ReactorConfig` by hand. Direct `createReactor` use is reserved for
+ * reactor-internal tests and any future consumer that genuinely needs a
+ * different composition.
+ */
+export function createReactorAssembly(config) {
+    const { sessionId, director, source, failOverToNextSource, resetToPreferredSource, toolRunner, contextStore, onEvent, authorize, toolDefinitions, auditStore, beforeToolExtensions: callerBeforeToolExtensions, toolResultTransforms: callerToolResultTransforms, contextTransforms, compactors, sizeCapMaxChars, afterCheckpoint: callerAfterCheckpoint, onShutdown: callerOnShutdown, deps, correlationValidator, inferenceRunner, gateTimeout, shutdownTimeoutMs, } = config;
+    // Audit collector is created up-front so the authz extension can route its
+    // decisions through `onDecision`. When no auditStore is supplied, no
+    // collector is created and authz runs without decision recording.
+    const auditCollector = auditStore !== undefined ? createAuditCollector(sessionId) : undefined;
+    // When an audit collector is present, intercept the reactor's event stream
+    // to feed it tool.start / tool.done events (the collector correlates these
+    // with authz decisions by callId). message.received is reactor-internal and
+    // is forwarded to the caller but not to the collector. Without a collector,
+    // the caller's onEvent is used directly.
+    const composedOnEvent = auditCollector !== undefined
+        ? (event) => {
+            if (event.type !== "message.received") {
+                auditCollector.onEvent(event);
+            }
+            onEvent(event);
+        }
+        : onEvent;
+    // Authz is composed in front of any caller-supplied before-tool extensions
+    // so policy enforcement runs first. Without authz, the caller's list (if
+    // any) is passed through unchanged.
+    const authzExtension = authorize !== undefined
+        ? createAuthzExtension({
+            authorize,
+            ...(auditCollector !== undefined
+                ? { onDecision: (d) => auditCollector.onDecision(d) }
+                : {}),
+            ...(toolDefinitions !== undefined ? { toolDefinitions } : {}),
+        })
+        : undefined;
+    const composedBeforeToolExtensions = authzExtension !== undefined
+        ? [authzExtension, ...(callerBeforeToolExtensions ?? [])]
+        : callerBeforeToolExtensions;
+    // The size-cap transform is always prepended so oversized payloads spill
+    // before any caller transform sees them. Caller transforms run after and
+    // can rely on the inline content already being bounded.
+    const sizeCapTransform = createSizeCapTransform({
+        maxChars: sizeCapMaxChars ?? DEFAULT_SIZE_CAP_MAX_CHARS,
+        contextStore,
+    });
+    const composedToolResultTransforms = [
+        sizeCapTransform,
+        ...(callerToolResultTransforms ?? []),
+    ];
+    // Audit flush wraps the caller's lifecycle hooks: the helper's flush runs
+    // first so the records produced by the just-completed cycle are persisted
+    // before the caller's hook observes the checkpoint or shutdown boundary.
+    async function flushAudit() {
+        if (auditCollector === undefined || auditStore === undefined)
+            return;
+        const records = auditCollector.flush();
+        if (records.length > 0) {
+            await auditStore.commitAudit(records);
+        }
+    }
+    const composedAfterCheckpoint = auditCollector !== undefined
+        ? async () => {
+            await flushAudit();
+            if (callerAfterCheckpoint !== undefined) {
+                await callerAfterCheckpoint();
+            }
+        }
+        : callerAfterCheckpoint;
+    const composedOnShutdown = auditCollector !== undefined
+        ? async () => {
+            const inflight = auditCollector.pending();
+            if (inflight > 0) {
+                logger.warn `${inflight} audit records in flight at shutdown, these tool calls will not be recorded`;
+            }
+            await flushAudit();
+            if (callerOnShutdown !== undefined) {
+                await callerOnShutdown();
+            }
+        }
+        : callerOnShutdown;
+    // exactOptionalPropertyTypes is on: only set optional keys when defined.
+    const reactorConfig = {
+        sessionId,
+        director,
+        source,
+        ...(failOverToNextSource !== undefined ? { failOverToNextSource } : {}),
+        ...(resetToPreferredSource !== undefined ? { resetToPreferredSource } : {}),
+        toolRunner,
+        contextStore,
+        onEvent: composedOnEvent,
+        deps,
+        toolResultTransforms: composedToolResultTransforms,
+        ...(composedBeforeToolExtensions !== undefined
+            ? { beforeToolExtensions: composedBeforeToolExtensions }
+            : {}),
+        ...(contextTransforms !== undefined ? { contextTransforms } : {}),
+        ...(compactors !== undefined ? { compactors } : {}),
+        ...(composedAfterCheckpoint !== undefined
+            ? { afterCheckpoint: composedAfterCheckpoint }
+            : {}),
+        ...(composedOnShutdown !== undefined
+            ? { onShutdown: composedOnShutdown }
+            : {}),
+        ...(correlationValidator !== undefined ? { correlationValidator } : {}),
+        ...(inferenceRunner !== undefined ? { inferenceRunner } : {}),
+        ...(gateTimeout !== undefined ? { gateTimeout } : {}),
+        ...(shutdownTimeoutMs !== undefined ? { shutdownTimeoutMs } : {}),
+    };
+    const reactor = createReactor(reactorConfig);
+    const blobReader = createBlobReader(contextStore);
+    return { reactor, blobReader, auditCollector };
+}

package/dist/audit-collector.d.ts

@@ -0,0 +1,10 @@
+import type { AuditRecord } from "@intx/types/audit";
+import type { InferenceEvent } from "@intx/types/runtime";
+import type { AuthzDecision } from "./authz-extension.js";
+export type AuditCollector = {
+    onEvent(event: InferenceEvent): void;
+    onDecision(decision: AuthzDecision): void;
+    flush(): AuditRecord[];
+    pending(): number;
+};
+export declare function createAuditCollector(sessionId: string): AuditCollector;

package/dist/audit-collector.js

@@ -0,0 +1,139 @@
+// Audit collector: accumulates tool invocation records for persistence.
+//
+// The collector correlates three data sources into complete AuditRecord
+// objects:
+//   1. tool.start events — tool name and arguments (allowed calls only)
+//   2. AuthzDecision via onDecision — governance decision
+//   3. tool.done events — result and completion metadata
+//
+// Correlation is by callId. For blocked calls, no tool.start is emitted;
+// the collector creates the record from the buffered decision and the
+// tool.done event alone.
+//
+// Wiring: the caller must connect onDecision to the authz extension's
+// onDecision callback, and onEvent to the reactor's event stream. The
+// types alone do not enforce this — it is a composition-layer concern.
+import { getLogger } from "@intx/log";
+const logger = getLogger(["interchange", "audit-collector"]);
+function coerceContent(content) {
+    if (typeof content === "string")
+        return content;
+    if (typeof content === "object" && content !== null) {
+        // content is a non-null object — compatible with Record<string, unknown>
+        // but TypeScript can't verify the index signature without a cast.
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- non-null object is structurally compatible with Record<string, unknown> but TS won't widen
+        return content;
+    }
+    throw new Error(`Unexpected tool result content type: ${typeof content}`);
+}
+function mapGrant(g) {
+    return {
+        id: g.id,
+        resource: g.resource,
+        action: g.action,
+        effect: g.effect,
+        origin: g.origin,
+        specificity: g.specificity,
+    };
+}
+function decisionToAuthz(d) {
+    return {
+        effect: d.effect,
+        resolvedBy: d.resolvedBy ? mapGrant(d.resolvedBy) : null,
+        matchingGrants: d.matchingGrants.map(mapGrant),
+        blocked: d.blocked,
+        ...(d.blockReason !== undefined ? { blockReason: d.blockReason } : {}),
+    };
+}
+export function createAuditCollector(sessionId) {
+    const decisions = new Map();
+    const pendingRecords = new Map();
+    const completed = [];
+    function onDecision(decision) {
+        decisions.set(decision.callId, decision);
+    }
+    function onEvent(event) {
+        if (event.type === "tool.start") {
+            const call = event.data.call;
+            const decision = decisions.get(call.id);
+            decisions.delete(call.id);
+            pendingRecords.set(call.id, {
+                callId: call.id,
+                tool: call.name,
+                arguments: call.arguments,
+                authz: decision ? decisionToAuthz(decision) : null,
+            });
+            return;
+        }
+        if (event.type === "tool.done") {
+            const result = event.data.result;
+            const pending = pendingRecords.get(result.callId);
+            if (pending) {
+                pendingRecords.delete(result.callId);
+                completed.push({
+                    callId: pending.callId,
+                    tool: pending.tool,
+                    arguments: pending.arguments,
+                    authz: pending.authz,
+                    result: {
+                        content: coerceContent(result.content),
+                        isError: result.isError === true,
+                    },
+                    timestamp: new Date().toISOString(),
+                    sessionId,
+                    seq: event.seq,
+                });
+                return;
+            }
+            // Blocked call: no tool.start was emitted. Build the record from
+            // the buffered decision and the tool.done event.
+            const decision = decisions.get(result.callId);
+            if (decision === undefined) {
+                // Orphaned tool.done: no tool.start or authz decision was recorded.
+                // Emit a degraded record rather than crashing the session — the audit
+                // system is observational infrastructure and must not veto execution.
+                logger.warn `Orphaned tool.done for callId "${result.callId}": no tool.start or authz decision was recorded`;
+                completed.push({
+                    callId: result.callId,
+                    tool: "$orphaned",
+                    arguments: {},
+                    authz: null,
+                    result: {
+                        content: coerceContent(result.content),
+                        isError: result.isError === true,
+                    },
+                    timestamp: new Date().toISOString(),
+                    sessionId,
+                    seq: event.seq,
+                });
+                return;
+            }
+            decisions.delete(result.callId);
+            completed.push({
+                callId: result.callId,
+                tool: decision.tool,
+                arguments: {},
+                authz: decisionToAuthz(decision),
+                result: {
+                    content: coerceContent(result.content),
+                    isError: result.isError === true,
+                },
+                timestamp: new Date().toISOString(),
+                sessionId,
+                seq: event.seq,
+            });
+        }
+    }
+    function flush() {
+        return completed.splice(0);
+    }
+    function pendingCount() {
+        return pendingRecords.size + decisions.size;
+    }
+    return {
+        onEvent,
+        onDecision,
+        flush,
+        pending: pendingCount,
+    };
+}

package/dist/auth.d.ts

@@ -0,0 +1,24 @@
+import type { InferenceSource } from "@intx/types/runtime";
+/**
+ * Sentinel for headers that carry the API key verbatim (no prefix).
+ * Used by providers like Anthropic (`x-api-key`) and Google
+ * (`x-goog-api-key`) that accept the raw credential.
+ */
+export declare const CREDENTIAL_SENTINEL = "<inject:credential>";
+/**
+ * Sentinel for headers that carry a Bearer-prefixed API key. Used by
+ * providers that follow the `Authorization: Bearer <token>` convention
+ * (OpenAI, OpenAI-compatible).
+ */
+export declare const BEARER_CREDENTIAL_SENTINEL = "<inject:bearer-credential>";
+/**
+ * Replace credential sentinels in a header map with material derived
+ * from the inference source. Returns a new object; the input is not
+ * mutated. Non-sentinel header values pass through unchanged.
+ *
+ * A header value that contains a sentinel as a substring but is not
+ * exactly equal to it is left alone -- partial replacement would be
+ * surprising, and no legitimate adapter constructs sentinel-bearing
+ * composite values.
+ */
+export declare function injectCredentials(headers: Record<string, string>, source: InferenceSource): Record<string, string>;

package/{src/auth.ts → dist/auth.js}

@@ -1,5 +1,3 @@
-import type { InferenceSource } from "@intx/types/runtime";
-
 // Sentinel placeholder strings adapters use in their built request
 // headers to declare which credential the harness should fill at send
 // time. The harness scans every header value and replaces exact-match
@@ -18,21 +16,18 @@ import type { InferenceSource } from "@intx/types/runtime";
 // keyword prefix that would never appear in a legitimate header value:
 // matching is exact, but defense-in-depth ensures a literal echo from
 // an upstream system can't accidentally trigger replacement.
-
 /**
  * Sentinel for headers that carry the API key verbatim (no prefix).
  * Used by providers like Anthropic (`x-api-key`) and Google
  * (`x-goog-api-key`) that accept the raw credential.
  */
 export const CREDENTIAL_SENTINEL = "<inject:credential>";
-
 /**
  * Sentinel for headers that carry a Bearer-prefixed API key. Used by
  * providers that follow the `Authorization: Bearer <token>` convention
  * (OpenAI, OpenAI-compatible).
  */
 export const BEARER_CREDENTIAL_SENTINEL = "<inject:bearer-credential>";
-
 /**
  * Replace credential sentinels in a header map with material derived
  * from the inference source. Returns a new object; the input is not
@@ -43,19 +38,18 @@ export const BEARER_CREDENTIAL_SENTINEL = "<inject:bearer-credential>";
  * surprising, and no legitimate adapter constructs sentinel-bearing
  * composite values.
  */
-export function injectCredentials(
-  headers: Record<string, string>,
-  source: InferenceSource,
-): Record<string, string> {
-  const result: Record<string, string> = {};
-  for (const [name, value] of Object.entries(headers)) {
-    if (value === CREDENTIAL_SENTINEL) {
-      result[name] = source.apiKey;
-    } else if (value === BEARER_CREDENTIAL_SENTINEL) {
-      result[name] = `Bearer ${source.apiKey}`;
-    } else {
-      result[name] = value;
+export function injectCredentials(headers, source) {
+    const result = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (value === CREDENTIAL_SENTINEL) {
+            result[name] = source.apiKey;
+        }
+        else if (value === BEARER_CREDENTIAL_SENTINEL) {
+            result[name] = `Bearer ${source.apiKey}`;
+        }
+        else {
+            result[name] = value;
+        }
     }
-  }
-  return result;
+    return result;
 }

package/dist/authz-extension.d.ts

@@ -0,0 +1,46 @@
+import type { BeforeToolExtension, ToolDefinition } from "@intx/types/runtime";
+import type { Effect } from "@intx/types/authz";
+export type AuthzMatchedGrant = {
+    id: string;
+    resource: string;
+    action: string;
+    effect: Effect;
+    origin: "system" | "role" | "creator" | "invoker";
+    specificity: number;
+};
+export type AuthzCallResult = {
+    effect: Effect | null;
+    matchingGrants: AuthzMatchedGrant[];
+    resolvedBy: AuthzMatchedGrant | null;
+};
+export type AuthzDecision = {
+    callId: string;
+    tool: string;
+    resource: string;
+    action: string;
+    effect: Effect | null;
+    resolvedBy: AuthzMatchedGrant | null;
+    matchingGrants: AuthzMatchedGrant[];
+    blocked: boolean;
+    blockReason: string | undefined;
+    error: string | undefined;
+};
+export type AuthzExtensionOptions<Ctx = unknown> = {
+    authorize: (resource: string, action: string, context: Ctx) => Promise<AuthzCallResult>;
+    onDecision?: (decision: AuthzDecision) => void;
+    /**
+     * Deadline applied to an approval suspension, in milliseconds from the
+     * moment the `ask` effect is hit. Defaults to `DEFAULT_APPROVAL_TIMEOUT_MS`.
+     */
+    approvalTimeoutMs?: number;
+    /**
+     * Tool definitions the extension can be asked to authorize, used to build the
+     * approver-facing snapshot at the `ask` branch. Presence is a contract: when
+     * supplied, every tool this extension authorizes must appear here, and an
+     * `ask` for a tool that does not is a wiring defect that throws. Omitted
+     * entirely, the extension produces no snapshot — a mode for callers that
+     * never register a suspension with the hub.
+     */
+    toolDefinitions?: readonly ToolDefinition[];
+};
+export declare function createAuthzExtension<Ctx = unknown>(opts: AuthzExtensionOptions<Ctx>): BeforeToolExtension;

package/dist/authz-extension.js

@@ -0,0 +1,184 @@
+// Authz-based BeforeToolExtension.
+//
+// Creates an extension that authorizes tool calls against a policy before
+// execution. The caller provides a pre-bound authorize function that
+// encapsulates store, principal, tenant, and condition registry details.
+//
+// Effects:
+//   allow  → tool proceeds
+//   deny   → tool blocked
+//   ask    → tool suspended (parked awaiting an external approval decision)
+//   null   → tool blocked (fail-closed: no grants matched)
+//
+// The action is always "invoke" — all tool calls are invocations. If
+// additional action granularity is needed later, the action becomes a
+// parameter.
+//
+// Signal propagation into the authorize function is deferred — the caller
+// can capture the signal in their closure if cancellation is needed.
+//
+// The onDecision callback must not throw. If it does, the exception is
+// logged but swallowed so it cannot interfere with the authorization
+// decision or mask the original error.
+// Default deadline for an approval suspension when the caller does not supply
+// one. Matches the reactor's DEFAULT_GATE_TIMEOUT_MS (one hour); the value is
+// duplicated rather than imported to avoid a dependency from the pure-policy
+// extension onto the reactor module.
+const DEFAULT_APPROVAL_TIMEOUT_MS = 3_600_000;
+function formatBlockReason(effect, resource, action) {
+    switch (effect) {
+        case "deny":
+            return `Denied by policy: ${resource}/${action}`;
+        case null:
+            return `No matching grants for ${resource}/${action}`;
+    }
+}
+function safeOnDecision(callback, decision) {
+    if (callback === undefined)
+        return;
+    try {
+        callback(decision);
+    }
+    catch {
+        // onDecision must not throw. If it does, swallow the exception so
+        // it cannot interfere with the authorization decision or mask the
+        // original error from authorize().
+    }
+}
+export function createAuthzExtension(opts) {
+    // The reactor does not know workflow concepts; per-call context is the
+    // caller's domain. The third arg is plumbing here -- if the caller
+    // needs to attach context (workflow step, tenant id, request id), they
+    // do so by closure on the authorize function. The empty object is the
+    // safe default at this layer.
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- the inference layer has no domain knowledge to construct a Ctx; callers that need a populated context use closure capture on the authorize function (see @intx/workflow's AuthorizeContext)
+    const emptyContext = Object.freeze({});
+    // One-shot bypass tokens, keyed on ToolCall.id. A token authorizes a single
+    // re-dispatch of an already-approved call to skip the `ask` gate it would
+    // otherwise re-hit. Held in memory only, within the resumed reactor cycle
+    // that grants and consumes it: a durable allow would outlive the cycle and
+    // defeat the one-shot intent, and a crash between grant and consume simply
+    // re-drives from the durable log and re-grants.
+    const approvedOnce = new Set();
+    // Name → definition lookup for building the approval snapshot at the `ask`
+    // branch. `undefined` (not merely empty) means the caller wired no tool
+    // definitions and wants no snapshot; a defined map means every authorizable
+    // tool must be present, so a lookup miss is a wiring defect that throws. The
+    // sentinel keeps those two contracts distinguishable at the lookup site.
+    const toolDefinitionsByName = opts.toolDefinitions !== undefined
+        ? new Map(opts.toolDefinitions.map((def) => [def.name, def]))
+        : undefined;
+    return {
+        grantOneShot(id) {
+            approvedOnce.add(id);
+        },
+        async beforeTool(call) {
+            const resource = `tool:${call.name}`;
+            const action = "invoke";
+            let result;
+            try {
+                result = await opts.authorize(resource, action, emptyContext);
+            }
+            catch (cause) {
+                const msg = cause instanceof Error ? cause.message : String(cause);
+                const decision = {
+                    callId: call.id,
+                    tool: call.name,
+                    resource,
+                    action,
+                    effect: null,
+                    resolvedBy: null,
+                    matchingGrants: [],
+                    blocked: true,
+                    blockReason: `Authorization failed: ${msg}`,
+                    error: msg,
+                };
+                safeOnDecision(opts.onDecision, decision);
+                throw cause;
+            }
+            // An `ask` effect suspends the call rather than blocking it, so it is
+            // neither cleanly blocked nor allowed: the decision records
+            // `blocked: false` with no block reason. Only `deny`/null (fail-closed)
+            // are blocks.
+            const blockReason = result.effect === "deny" || result.effect === null
+                ? formatBlockReason(result.effect, resource, action)
+                : undefined;
+            const decision = {
+                callId: call.id,
+                tool: call.name,
+                resource,
+                action,
+                effect: result.effect,
+                resolvedBy: result.resolvedBy,
+                matchingGrants: result.matchingGrants,
+                blocked: blockReason !== undefined,
+                blockReason,
+                error: undefined,
+            };
+            safeOnDecision(opts.onDecision, decision);
+            // A one-shot token only authorizes bypassing an `ask` gate. If the
+            // resolved effect is anything else, the grant changed underneath the
+            // token: drop it and let the normal path decide, rather than silently
+            // allowing a call the policy no longer parks.
+            if (approvedOnce.has(call.id) && result.effect !== "ask") {
+                approvedOnce.delete(call.id);
+            }
+            if (blockReason !== undefined) {
+                return { type: "block", reason: blockReason };
+            }
+            if (result.effect === "ask") {
+                // A prior approval authorized this exact call to run once. Consume the
+                // token (delete-on-read) and allow it through instead of suspending,
+                // so a re-dispatched approved call does not re-park on its own gate.
+                if (approvedOnce.has(call.id)) {
+                    approvedOnce.delete(call.id);
+                    return { type: "allow" };
+                }
+                // Mint the correlationId once here so it is the single source of
+                // identity for both the gate and the persisted operation. The
+                // reactor persists the operation, so this id survives a restart.
+                const correlationId = crypto.randomUUID();
+                const timeoutAt = Date.now() + (opts.approvalTimeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS);
+                const gateId = `pending-${correlationId}`;
+                // Build the approver-facing snapshot when tool definitions are wired.
+                // A wired extension must have a definition for every tool it can
+                // authorize, so a miss is a wiring defect rather than a fallback. An
+                // unwired extension produces no snapshot: such callers never register
+                // the suspension with the hub, so the downstream required-snapshot
+                // validator never sees them.
+                let approvalSnapshot;
+                if (toolDefinitionsByName !== undefined) {
+                    const def = toolDefinitionsByName.get(call.name);
+                    if (def === undefined) {
+                        throw new Error(`Tool "${call.name}" was authorized with effect "ask" but has ` +
+                            `no definition in the resolved tool set; the approval ` +
+                            `snapshot cannot be built. This is a wiring defect: every ` +
+                            `tool the authz extension can authorize must be present in ` +
+                            `toolDefinitions.`);
+                    }
+                    approvalSnapshot = {
+                        name: call.name,
+                        description: def.description,
+                        inputSchema: def.inputSchema,
+                        arguments: call.arguments,
+                    };
+                }
+                const pendingOp = {
+                    correlationId,
+                    kind: "approval",
+                    registeredAt: Date.now(),
+                    gateId,
+                    timeoutAt,
+                    suspendedCall: call,
+                    ...(approvalSnapshot !== undefined ? { approvalSnapshot } : {}),
+                };
+                return {
+                    type: "suspend",
+                    gate: { type: "approval", gateId, correlationId, timeoutAt },
+                    pendingOp,
+                };
+            }
+            return { type: "allow" };
+        },
+    };
+}

package/dist/correlation.d.ts

@@ -0,0 +1,26 @@
+import type { InboundMessage, PendingOperation } from "@intx/types/runtime";
+/**
+ * Validates whether an inbound message is an authentic response to a
+ * registered pending operation. Consumers provide this at reactor construction
+ * time to enforce sender identity and signature checks.
+ */
+export interface CorrelationValidator {
+    /**
+     * Return true if `message` is a valid resolution for `pending`.
+     * False causes the message to be delivered as a regular uncorrelated event.
+     */
+    validate(pending: PendingOperation, message: InboundMessage): Promise<boolean>;
+}
+/**
+ * Tracks pending async operations. Each entry maps a correlation ID to the
+ * operation metadata and the gate that is waiting for it.
+ */
+export declare function createCorrelationRegistry(): {
+    register: (op: PendingOperation) => void;
+    lookup: (correlationId: string) => PendingOperation | undefined;
+    findByGateId: (gateId: string) => PendingOperation | undefined;
+    remove: (correlationId: string) => boolean;
+    all: () => PendingOperation[];
+    hasAny: () => boolean;
+};
+export type CorrelationRegistry = ReturnType<typeof createCorrelationRegistry>;

package/dist/correlation.js

@@ -0,0 +1,39 @@
+// Correlation registry and validator interface for the agent reactor.
+//
+// Correlation connects outbound async tool calls to inbound responses. The
+// reactor owns the matching; the director does not participate.
+//
+// (INFERENCE.md § Correlation)
+/**
+ * Tracks pending async operations. Each entry maps a correlation ID to the
+ * operation metadata and the gate that is waiting for it.
+ */
+export function createCorrelationRegistry() {
+    const operations = new Map();
+    function register(op) {
+        if (operations.has(op.correlationId)) {
+            throw new Error(`Correlation ID "${op.correlationId}" is already registered`);
+        }
+        operations.set(op.correlationId, op);
+    }
+    function lookup(correlationId) {
+        return operations.get(correlationId);
+    }
+    function findByGateId(gateId) {
+        for (const op of operations.values()) {
+            if (op.gateId === gateId)
+                return op;
+        }
+        return undefined;
+    }
+    function remove(correlationId) {
+        return operations.delete(correlationId);
+    }
+    function all() {
+        return Array.from(operations.values());
+    }
+    function hasAny() {
+        return operations.size > 0;
+    }
+    return { register, lookup, findByGateId, remove, all, hasAny };
+}