@godspeedai/cognate-runtime-bun 0.0.0-stage → 0.1.1

package/src/governed-operation.ts

@@ -0,0 +1,248 @@
+// GovernedOperation: the single choke point for every consequential Cognate decision (migration Stage 5).
+//
+// Cognate operates; SEA-Forge governs. Two things are kept apart (authority != capability):
+//   - local policy (ActionPolicy / kernel Policy) says what this runtime is *able* to permit, and
+//   - the governance authority (SEA-Forge) says whether the operation is *authorized*.
+// In `sea-forge` mode both must allow. In `off` mode only local policy applies, and every decision says so.
+// Only `allow` proceeds. Every other disposition is refused here; later stages add constraint handling and
+// escalation. Nothing outside this file may call `ActionPolicy.authorize` or the user's kernel `Policy`.
+import type { Caller } from "@godspeedai/cognate-runtime-api";
+import type { AuthorizationRequest, Policy, PolicyDecision } from "@godspeedai/cognate-kernel-api";
+import type { ActionPolicy } from "./index.ts";
+
+export type GovernanceMode = "sea-forge" | "off";
+
+/** CEP authority dispositions. Never a boolean (CEP profile `authority_decision`). */
+export type Disposition = "allow" | "deny" | "escalate" | "unknown" | "constrained_allow" | "boundary" | "degraded";
+
+export type ActionName = Parameters<ActionPolicy["authorize"]>[0]["action"];
+
+export type GovernedOperation =
+  | { readonly kind: "action"; readonly action: ActionName; readonly caller: Caller; readonly resource: string }
+  | { readonly kind: "capability"; readonly request: AuthorizationRequest };
+
+/** One constraint the authority attached to a constrained disposition, e.g. `{ type: "timeout_secs", value: "30" }`. */
+export interface GovernanceConstraint {
+  readonly type: string;
+  readonly value: string;
+}
+
+/**
+ * Installs one kind of constraint for one operation. It returns true only when the constraint is actually
+ * in force for that operation; any other outcome (false or a throw) means the constraint is not enforced.
+ */
+export interface ConstraintEnforcer {
+  apply(constraint: GovernanceConstraint, operation: GovernedOperation): boolean | Promise<boolean>;
+}
+
+/**
+ * Which authority decision allowed an operation. It travels in the recorded decision metadata so everything
+ * downstream (the execution trace, the evidence, the settlement) can name the decision it hangs from.
+ */
+export interface AuthorityReference {
+  readonly operationId: string;
+  readonly requestEnvelopeId: string;
+  readonly decisionEnvelopeId: string;
+  readonly worldRef: string;
+  /** The authority's own record of the decision (e.g. a ledger entry), when it gave one. */
+  readonly decisionRef?: string;
+}
+
+/** An escalation that a human can approve: the approval to wait for and when its window closes. */
+export interface GovernanceEscalation {
+  readonly approvalId: string;
+  /** Epoch ms, when the authority said the approval window closes. */
+  readonly expiresAt?: number;
+}
+
+/** Revalidation after an escalation was approved: the approval being relied on. */
+export interface ApprovalReference {
+  readonly approvalId: string;
+}
+
+export type ApprovalState = "pending" | "approved" | "rejected" | "expired" | "used" | "unknown";
+
+export interface GovernanceDecision {
+  readonly disposition: Disposition;
+  readonly reason: string;
+  /** Required by CEP for boundary / constrained_allow / degraded. */
+  readonly policyBasis?: readonly string[];
+  readonly constraints?: readonly GovernanceConstraint[];
+  /** Required by CEP for degraded. Each must have an enforcer registered under `control:<name>`. */
+  readonly compensatingControls?: readonly string[];
+  /** Reference to the authority's decision record, when one exists. */
+  readonly decisionRef?: string;
+  /** Present on an `escalate` that a human approval can satisfy. */
+  readonly escalation?: GovernanceEscalation;
+  /** Which decision this was, when the authority identifies it. */
+  readonly authority?: AuthorityReference;
+}
+
+/** What SEA-Forge implements (Stage 6 supplies the CEP-backed implementation). */
+export interface GovernanceAuthority {
+  /** `approval` is set only when revalidating an operation whose escalation has since been approved. */
+  decide(operation: GovernedOperation, worldRef: string, approval?: ApprovalReference): GovernanceDecision | Promise<GovernanceDecision>;
+  /** Where an escalation stands, if the authority can say. Used only to know when to try again; never to allow. */
+  approvalState?(approvalId: string): Promise<ApprovalState>;
+}
+
+export interface GovernanceOptions {
+  readonly mode: GovernanceMode;
+  readonly authority?: GovernanceAuthority;
+  /** Immutable `world:<name>@sha256:<64 hex>` all operations of this runtime are governed against. */
+  readonly worldRef?: string;
+  /**
+   * Enforcers by constraint type (`timeout_secs`) or `control:<name>` for compensating controls. None by
+   * default, so constrained dispositions are refused until a host registers the means to honor them.
+   */
+  readonly enforcers?: Readonly<Record<string, ConstraintEnforcer>>;
+  /** When set (>0) and the authority can report approval state, poll for approved escalations this often. */
+  readonly approvalPollMs?: number;
+}
+
+export interface GovernedResult {
+  readonly allow: boolean;
+  readonly mode: GovernanceMode;
+  readonly disposition: Disposition;
+  readonly reason: string;
+  readonly decisionRef?: string;
+  /** Constraints that were enforced before this operation was allowed (empty for plain allow). */
+  readonly applied?: readonly GovernanceConstraint[];
+  /** Present when the operation was refused because a human approval could satisfy it. */
+  readonly escalation?: GovernanceEscalation;
+  /** The decision that allowed (or refused) this, for downstream trace, evidence and settlement. */
+  readonly authority?: AuthorityReference;
+}
+
+const WORLD_REF = /^world:[a-z0-9]+(?:-[a-z0-9]+)*@sha256:[0-9a-f]{64}$/;
+
+export function isWorldRef(text: unknown): text is string {
+  return typeof text === "string" && text.length <= 200 && WORLD_REF.test(text);
+}
+
+/** Fails at construction, never at first use: `sea-forge` mode without authority and a world is a bug. */
+export function validateGovernance(options: GovernanceOptions): void {
+  if (options.mode !== "sea-forge" && options.mode !== "off") throw new Error(`unsupported governance mode: ${String(options.mode)}`);
+  if (options.mode === "sea-forge") {
+    if (!options.authority) throw new Error("governance mode sea-forge requires an authority");
+    if (!isWorldRef(options.worldRef)) throw new Error("governance mode sea-forge requires a valid worldRef");
+  }
+}
+
+/** What the invoker needs to observe about one capability authorization. */
+export interface CapabilityHooks {
+  /** Set when revalidating an approved escalation. */
+  readonly approval?: ApprovalReference;
+  readonly applied?: (applied: readonly GovernanceConstraint[]) => void;
+  readonly escalated?: (escalation: GovernanceEscalation) => void;
+}
+
+export class Governor {
+  constructor(
+    private readonly local: ActionPolicy,
+    private readonly kernelPolicy: Policy,
+    private readonly options: GovernanceOptions,
+  ) {
+    validateGovernance(options);
+  }
+
+  get mode(): GovernanceMode {
+    return this.options.mode;
+  }
+
+  /** Decide one operation. Never throws for a refusal; throws only on programmer error. */
+  async govern(operation: GovernedOperation, approval?: ApprovalReference): Promise<GovernedResult> {
+    const mode = this.options.mode;
+    const localDecision = await this.localDecision(operation);
+    if (!localDecision.allow) return { allow: false, mode, disposition: "deny", reason: localDecision.reason };
+    if (mode === "off") return { allow: true, mode, disposition: "allow", reason: `${localDecision.reason} (governance off: local policy only)` };
+
+    let decision: GovernanceDecision;
+    try {
+      decision = await this.options.authority!.decide(operation, this.options.worldRef!, approval);
+    } catch (error) {
+      // An authority that cannot answer is not an authority that said yes.
+      return { allow: false, mode, disposition: "unknown", reason: `governance authority unavailable: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    return this.interpret(mode, decision, operation);
+  }
+
+  private async localDecision(operation: GovernedOperation): Promise<{ allow: boolean; reason: string }> {
+    if (operation.kind === "action") return this.local.authorize({ caller: operation.caller, action: operation.action, resource: operation.resource });
+    return this.kernelPolicy.authorize(operation.request);
+  }
+
+  private async interpret(mode: GovernanceMode, decision: GovernanceDecision, operation: GovernedOperation): Promise<GovernedResult> {
+    if (!decision || !KNOWN.has(decision.disposition)) return { allow: false, mode, disposition: "unknown", reason: "governance authority returned an unrecognized disposition" };
+    const ref = { ...(decision.decisionRef === undefined ? {} : { decisionRef: decision.decisionRef }), ...(decision.authority ? { authority: decision.authority } : {}) };
+    const refuse = (disposition: Disposition, reason: string): GovernedResult => ({ allow: false, mode, disposition, reason, ...ref });
+    if (decision.disposition === "allow") return { allow: true, mode, disposition: "allow", reason: decision.reason, ...ref };
+    if (decision.disposition === "escalate" && decision.escalation) {
+      return { ...refuse("escalate", `${decision.reason}; awaiting approval ${decision.escalation.approvalId}`), escalation: decision.escalation };
+    }
+    if (!CONSTRAINED.has(decision.disposition)) return refuse(decision.disposition, decision.reason);
+
+    // A constrained disposition is an allow only if every constraint is genuinely enforced for this operation.
+    const constraints = decision.constraints ?? [];
+    const controls = decision.compensatingControls ?? [];
+    if (constraints.length === 0 || !decision.policyBasis?.length) return refuse("unknown", `${decision.disposition} arrived without constraints and policy basis`);
+    if (decision.disposition === "degraded" && controls.length === 0) return refuse("unknown", "degraded arrived without compensating controls");
+    const enforcers = this.options.enforcers ?? {};
+    const applied: GovernanceConstraint[] = [];
+    const needed: { key: string; constraint: GovernanceConstraint }[] = [
+      ...constraints.map((constraint) => ({ key: constraint.type, constraint })),
+      ...(decision.disposition === "degraded" ? controls.map((name) => ({ key: `control:${name}`, constraint: { type: `control:${name}`, value: name } })) : []),
+    ];
+    for (const { key, constraint } of needed) {
+      const enforcer = Object.hasOwn(enforcers, key) ? enforcers[key] : undefined;
+      if (!enforcer) return refuse(decision.disposition, `${decision.disposition} requires '${key}' and no enforcer is registered: ${decision.reason}`);
+      let enforced = false;
+      try {
+        enforced = (await enforcer.apply(constraint, operation)) === true;
+      } catch {
+        enforced = false;
+      }
+      if (!enforced) return refuse(decision.disposition, `${decision.disposition} constraint '${key}' could not be enforced: ${decision.reason}`);
+      applied.push(constraint);
+    }
+    return { allow: true, mode, disposition: decision.disposition, reason: decision.reason, applied, ...ref };
+  }
+
+  /**
+   * Kernel-policy facade: the same decision, shaped as the kernel expects. `onApplied` receives the
+   * constraints that were enforced before the allow, so the invoker can put them in force for the call.
+   */
+  async governCapability(request: AuthorizationRequest, hooks: CapabilityHooks = {}): Promise<PolicyDecision> {
+    const result = await this.govern({ kind: "capability", request }, hooks.approval);
+    if (result.allow && result.applied?.length) hooks.applied?.(result.applied);
+    if (!result.allow && result.escalation) hooks.escalated?.(result.escalation);
+    // `authority` rides in the recorded decision (run.invocation metadata), so a later trace can name it.
+    return { allow: result.allow, policyId: result.mode === "sea-forge" ? "sea-forge" : "local", reason: result.reason, ...(result.authority ? { authority: result.authority } : {}) } as PolicyDecision;
+  }
+}
+
+const KNOWN: ReadonlySet<string> = new Set<Disposition>(["allow", "deny", "escalate", "unknown", "constrained_allow", "boundary", "degraded"]);
+const CONSTRAINED: ReadonlySet<string> = new Set<Disposition>(["constrained_allow", "boundary", "degraded"]);
+
+/** Largest timeout an authority may impose; a longer one is not a meaningful bound. */
+export const MAX_TIMEOUT_SECONDS = 3600;
+
+/**
+ * Enforcer for the `timeout_secs` constraint. It reports "enforced" only for capability invocations, because
+ * only the Invoker puts a deadline in force (it reads the applied constraint, aborts the provider's signal and
+ * fails the call with `deadline_exceeded`). An action has no such deadline, so the constraint cannot be honored
+ * there and the operation is refused. Register it under `enforcers: { timeout_secs: timeoutSecsEnforcer }`.
+ */
+export const timeoutSecsEnforcer: ConstraintEnforcer = {
+  apply(constraint, operation) {
+    if (operation.kind !== "capability") return false;
+    return parseTimeoutSeconds(constraint.value) !== undefined;
+  },
+};
+
+/** A whole number of seconds in 1..=MAX_TIMEOUT_SECONDS, else undefined. */
+export function parseTimeoutSeconds(value: string): number | undefined {
+  if (!/^[1-9][0-9]{0,3}$/.test(value)) return undefined;
+  const seconds = Number(value);
+  return seconds <= MAX_TIMEOUT_SECONDS ? seconds : undefined;
+}

package/src/index.ts

@@ -0,0 +1,95 @@
+import type { CognitiveIndex, Embedder, IndexDocument } from "@godspeedai/cognate-cognitive-api";
+import type { DurableStore, Json, NewEvent, OutboxIntent, StoredEvent } from "@godspeedai/cognate-events";
+import type { Component, Kernel, Policy, Principal } from "@godspeedai/cognate-kernel-api";
+import type { Projection } from "@godspeedai/cognate-projections";
+import type { AgentDefinition, Caller, RuntimeService } from "@godspeedai/cognate-runtime-api";
+import type { GovernanceOptions } from "./governed-operation.ts";
+import { startRuntime } from "./runtime.ts";
+
+export { SeaForgeAuthority, buildAuthorityRequest, buildTransitionRequest, interpretDecision, interpretSettlement, type CarriedWork, type EvidenceReceipt, type RecordedTransition, type SeaForgeAuthorityOptions, type SettlementReceipt, type WorldTransitionRequest } from "./sea-forge-authority.ts";
+export { ENV_ACTOR, ENV_MODE, ENV_SOCKET, ENV_WORLD, governanceFromEnv } from "./governance-env.ts";
+export { Governor, isWorldRef, parseTimeoutSeconds, timeoutSecsEnforcer, validateGovernance } from "./governed-operation.ts";
+export type { ApprovalReference, AuthorityReference, ApprovalState, CapabilityHooks, ConstraintEnforcer, GovernanceEscalation, Disposition, GovernanceAuthority, GovernanceConstraint, GovernanceDecision, GovernanceMode, GovernanceOptions, GovernedOperation, GovernedResult } from "./governed-operation.ts";
+
+export interface ActionPolicy {
+  /** Authorize run and continuation actions (start, cancel, resume, read artifacts). Default: deny (spec §32). */
+  authorize(request: { readonly caller: Caller; readonly action: "run.start" | "run.cancel" | "continuation.resume" | "continuation.cancel" | "run.state.update" | "thread.state.read" | "thread.state.update" | "observation.record" | "remote.offer.publish" | "remote.offer.list" | "remote.offer.revoke" | "remote.offer.invoke"; readonly resource: string }): { readonly allow: boolean; readonly reason: string };
+}
+
+export interface CognitionOptions {
+  readonly index: CognitiveIndex;
+  readonly embedder: Embedder;
+  /** Extract documents to index from committed events; defaults to indexing completed runs. */
+  readonly extract?: (event: StoredEvent) => readonly IndexDocument[];
+  /**
+   * Whether the index survives restart with its data. When false (memory, RuVector adapter), the runtime
+   * rebuilds the cognitive projection on start so the checkpoint never claims entries the index lost.
+   */
+  readonly persistent: boolean;
+}
+
+/** A run event about to be committed. */
+export type PendingEvent = NewEvent & { readonly eventId: string; readonly streamId: string; readonly recordedAt: string };
+
+/** Outbox topic whose items represent RealityTrace observations; `inspect` reports their observation ids. */
+export const OBSERVATION_OUTBOX_TOPIC = "observation.deliver";
+
+export interface RuntimeOptions {
+  /** SQLite file path, `":memory:"` for an in-memory SQLite database, or an explicit store. */
+  readonly store: string | { readonly store: DurableStore };
+  /** Kernel invocation policy for capabilities (default-deny if omitted). */
+  readonly policy: Policy;
+  readonly actions: ActionPolicy;
+  /** Governance of every consequential operation. Default `{ mode: "off" }` (local policy only) until Stage 6 wires SEA-Forge. */
+  readonly governance?: GovernanceOptions;
+  readonly agents: readonly AgentDefinition[];
+  /** Capability-providing components mounted in the root scope. */
+  readonly components?: readonly Component[];
+  readonly cognition?: CognitionOptions;
+  /** Projections kept current by the runtime; `public` ones are readable through the service. */
+  readonly projections?: readonly { readonly projection: Projection; readonly public: boolean }[];
+  /**
+   * Extra outbox intents committed atomically with each run event (spec §13.1), e.g. RealityTrace observation
+   * intents. Receives the event before commit: `eventId` is pre-assigned; `recordedAt` is provisional (= occurredAt).
+   */
+  readonly outboxFor?: (event: PendingEvent) => readonly OutboxIntent[];
+  /** Background work loop interval (run execution, resume delivery, expiry). Default 10 ms. */
+  readonly tickMs?: number;
+  readonly system?: Principal;
+}
+
+export interface CausalChain {
+  readonly correlationId: string;
+  readonly runs: readonly string[];
+  readonly events: readonly { readonly eventId: string; readonly eventType: string; readonly causationId: string | null; readonly componentId?: string; readonly fiberId?: string; readonly semanticRef?: Json }[];
+  readonly invocations: readonly { readonly capability: string; readonly providerId: string; readonly fiberId: string; readonly decision: Json }[];
+  readonly artifacts: readonly string[];
+  readonly observations: readonly string[];
+}
+
+export interface Runtime {
+  readonly service: RuntimeService;
+  readonly kernel: Kernel;
+  readonly store: DurableStore;
+  /** Reconstruct machine-readable causal identity for a correlation id (spec §33, §40.M). */
+  inspect(correlationId: string): Promise<CausalChain>;
+  /** Clear the cognitive index and rebuild it from authoritative events (spec §3.5). */
+  rebuildCognition(): Promise<void>;
+  /** Erase an event payload under retention/privacy policy; derived views and the cognitive index drop it (spec §32). */
+  erase(eventId: string, reason: string, actor: Principal): Promise<void>;
+  /**
+   * One pass over runs waiting on a governance approval: ask the authority where each approval stands, resume
+   * the approved ones and cancel the rejected or expired ones. A resume only triggers revalidation; the
+   * authority decides again when the run retries. Returns how many waits it acted on.
+   */
+  pollApprovals(): Promise<number>;
+  /** Wait until background work queued so far has been processed (tests and graceful shutdown). */
+  idle(timeoutMs?: number): Promise<void>;
+  close(): Promise<void>;
+}
+
+export function createRuntime(options: RuntimeOptions): Promise<Runtime> {
+  return startRuntime(options);
+}
+
+export type { Json };

package/src/inspect.ts

@@ -0,0 +1,58 @@
+// Causal identity reconstruction from committed envelopes (spec §33, §40.M). Uses only envelope fields and
+// metadata, so it still works after payload erasure.
+import type { ContinuationService } from "@godspeedai/cognate-continuations";
+import type { DurableStore, Json, StoredEvent } from "@godspeedai/cognate-events";
+import { field, meta } from "./fold.ts";
+import { type CausalChain, OBSERVATION_OUTBOX_TOPIC } from "./index.ts";
+
+const PAGE = 1000;
+
+export async function inspectCorrelation(store: DurableStore, continuations: ContinuationService, correlationId: string): Promise<CausalChain> {
+  const matching: StoredEvent[] = [];
+  for (let position = 0; ; ) {
+    const page = await store.readAll({ afterPosition: position, limit: PAGE });
+    for (const event of page) if (event.correlationId === correlationId) matching.push(event);
+    if (page.length < PAGE) break;
+    position = page.at(-1)!.position;
+  }
+
+  // Continuation envelopes do not carry the wait's semantic reference; the continuation record does.
+  const continuationRefs = new Map<string, Json>();
+  for (const event of matching) {
+    if (!event.streamId.startsWith("continuation-") || continuationRefs.has(event.streamId)) continue;
+    const record = await continuations.get(event.streamId.slice("continuation-".length));
+    continuationRefs.set(event.streamId, (record?.semanticRef ?? null) as unknown as Json);
+  }
+
+  const runs: string[] = [];
+  const invocations: { capability: string; providerId: string; fiberId: string; decision: Json }[] = [];
+  const artifacts: string[] = [];
+  const events = matching.map((event) => {
+    const m = meta(event);
+    if (event.eventType === "run.started" && event.runId) runs.push(event.runId);
+    const providerId = field<string>(m, "providerId");
+    if (event.eventType === "run.invocation" && providerId) {
+      invocations.push({ capability: field<string>(m, "capability") ?? "", providerId, fiberId: event.fiberId ?? field<string>(m, "fiberId") ?? providerId, decision: field(m, "decision") });
+    }
+    const artifactId = field<string>(m, "artifactId");
+    if (event.eventType === "run.artifact" && artifactId) artifacts.push(artifactId);
+    const semanticRef = (event.semanticRef as unknown as Json | undefined) ?? continuationRefs.get(event.streamId) ?? null;
+    return {
+      eventId: event.eventId,
+      eventType: event.eventType,
+      causationId: event.causationId,
+      ...(event.componentId ? { componentId: event.componentId } : {}),
+      ...(event.fiberId ? { fiberId: event.fiberId } : {}),
+      ...(semanticRef !== null ? { semanticRef } : {}),
+    };
+  });
+
+  // Observations are outbox intents on the observation topic whose source event belongs to this correlation.
+  const eventIds = new Set(matching.map((event) => event.eventId));
+  const observations = (await store.listOutbox({ topic: OBSERVATION_OUTBOX_TOPIC }))
+    .map((item) => item.payload as { eventId?: Json; observationId?: Json } | null)
+    .filter((payload): payload is { eventId: string; observationId: string } => typeof payload?.eventId === "string" && typeof payload.observationId === "string" && eventIds.has(payload.eventId))
+    .map((payload) => payload.observationId);
+
+  return { correlationId, runs, events, invocations, artifacts, observations };
+}

package/src/invoker.ts

@@ -0,0 +1,145 @@
+// Capability invocation through the kernel, with the caller's tenant and the policy decision captured per call.
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { Json } from "@godspeedai/cognate-events";
+import { type InvocationResult, isUnavailable } from "@godspeedai/cognate-kernel-api";
+import { type GovernanceEscalation, type Governor, parseTimeoutSeconds } from "./governed-operation.ts";
+import type { Component, ComponentHandle, InvocationContext, InvocationFailure, Kernel, Policy, PolicyDecision, SemanticRef } from "@godspeedai/cognate-kernel-api";
+import { messageOf, toJson } from "./fold.ts";
+
+export interface InvocationOutcome {
+  readonly capability: string;
+  readonly providerId: string | null;
+  readonly componentId: string | null;
+  readonly fiberId: string | null;
+  readonly decision: PolicyDecision | null;
+  readonly semanticRef: SemanticRef | null;
+  readonly ok: boolean;
+  readonly value: Json;
+  /** JSON form of the typed failure, e.g. `{ kind: "denied", reason }`. For "failed" kind, includes `name` (error constructor name) and `details` (error's enumerable properties as string/number/boolean/null). */
+  readonly failure: { readonly kind: InvocationFailure["kind"]; readonly [key: string]: Json } | null;
+  /** Present when the call was refused because a human approval could satisfy it; the provider did not run. */
+  readonly escalation?: GovernanceEscalation;
+}
+
+interface Slot {
+  decision?: PolicyDecision;
+  /** The approval being relied on, when this call revalidates an approved escalation. */
+  approval?: { readonly approvalId: string };
+  /** Set by the policy wrapper when authorization escalated to a human approval. */
+  escalation?: GovernanceEscalation;
+  /** Puts a governed deadline in force for this call (set by `invoke`, called by the policy wrapper). */
+  arm?: (milliseconds: number) => void;
+}
+
+export class Invoker {
+  private readonly slots = new AsyncLocalStorage<Slot>();
+  private readonly mounted: { readonly component: Component; readonly handle: ComponentHandle }[] = [];
+  private kernel: Kernel | undefined;
+
+  constructor(private readonly governor: Governor) {}
+
+  /**
+   * The policy handed to the kernel. The caller's tenant travels in the InvocationContext; this wrapper only
+   * captures the decision so it can be recorded with the invocation (spec §32, §33).
+   */
+  readonly policy: Policy = {
+    authorize: async (request) => {
+      const slot = this.slots.getStore();
+      const decision = await this.governor.governCapability(request, {
+        ...(slot?.approval ? { approval: slot.approval } : {}),
+        applied: (applied) => {
+          const seconds = applied.map((c) => (c.type === "timeout_secs" ? parseTimeoutSeconds(c.value) : undefined)).filter((n): n is number => n !== undefined);
+          if (seconds.length && slot?.arm) slot.arm(Math.min(...seconds) * 1000);
+        },
+        escalated: (escalation) => {
+          if (slot) slot.escalation = escalation;
+        },
+      });
+      if (slot) slot.decision = decision;
+      return decision;
+    },
+  };
+
+  async attach(kernel: Kernel, components: readonly Component[]): Promise<void> {
+    this.kernel = kernel;
+    for (const component of components) {
+      const handle = await kernel.mount(component);
+      this.mounted.push({ component, handle });
+    }
+    // A component that fails to activate leaves its capabilities unavailable; it does not stop the runtime.
+    await Promise.all(this.mounted.map(({ handle }) => handle.waitFor("ACTIVE", 10_000).catch(() => {})));
+  }
+
+  async invoke(request: { readonly capability: string; readonly version?: string; readonly input: Json; readonly tenant: string; readonly context: InvocationContext; readonly approval?: { readonly approvalId: string } }): Promise<InvocationOutcome> {
+    const lease = this.kernel!.resolve(request.version ? { capability: request.capability, version: request.version } : { capability: request.capability });
+    const base = { capability: request.capability, providerId: null, componentId: null, fiberId: null, decision: null, semanticRef: null, value: null };
+    if (isUnavailable(lease)) return { ...base, ok: false, failure: { kind: "unavailable", reason: lease.reason } };
+
+    const slot: Slot = request.approval ? { approval: request.approval } : {};
+    // The call gets its own signal so a governed deadline (decided during authorization, after the call has
+    // started) can abort the provider; the caller's signal still aborts it too.
+    const controller = new AbortController();
+    const upstream = request.context.signal;
+    if (upstream) {
+      if (upstream.aborted) controller.abort(upstream.reason);
+      else upstream.addEventListener("abort", () => controller.abort(upstream.reason), { once: true });
+    }
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const governedDeadline = new Promise<InvocationResult<unknown>>((resolve) => {
+      slot.arm = (milliseconds) => {
+        timer = setTimeout(() => {
+          controller.abort(new Error("governed timeout_secs exceeded"));
+          resolve({ ok: false, failure: { kind: "deadline_exceeded" } });
+        }, milliseconds);
+      };
+    });
+    const invocation = this.slots.run(slot, () => lease.invoke(request.input, { ...request.context, tenant: request.tenant, signal: controller.signal }));
+    invocation.catch(() => {});
+    const result = await Promise.race([invocation, governedDeadline]).finally(() => clearTimeout(timer));
+    const provider = this.providerOf(lease.providerId, request.capability);
+    const common = { ...base, providerId: lease.providerId, ...provider, semanticRef: lease.contract.semanticRef ?? null, ...(slot.escalation ? { escalation: slot.escalation } : {}) };
+    if (result.ok) return { ...common, decision: slot.decision ?? null, ok: true, value: toJson(result.value), failure: null };
+    const failure = result.failure;
+    const decision = failure.kind === "denied" ? failure.decision : (slot.decision ?? null);
+    return { ...common, decision, ok: false, failure: failureJson(failure) };
+  }
+
+  /** Provider fiber and component, from mounted handles (kernel-api only; no engine types). */
+  private providerOf(providerId: string, capability: string): { componentId: string | null; fiberId: string | null } {
+    const byFiber = this.mounted.find(({ handle }) => handle.fiberId === providerId);
+    const match = byFiber ?? this.mounted.find(({ component }) => component.provides?.some((c) => c.id === capability));
+    return { componentId: match?.component.id ?? null, fiberId: match?.handle.fiberId ?? providerId };
+  }
+}
+
+function failureJson(failure: InvocationFailure): NonNullable<InvocationOutcome["failure"]> {
+  switch (failure.kind) {
+    case "unavailable":
+      return { kind: failure.kind, reason: failure.reason };
+    case "denied":
+      return { kind: failure.kind, policyId: failure.decision.policyId, reason: failure.decision.reason };
+    case "failed": {
+      const result: Record<string, Json> = {
+        kind: failure.kind,
+        message: messageOf(failure.error),
+      };
+      if (failure.error instanceof Error) {
+        result.name = failure.error.name;
+        const details: Record<string, Json> = {};
+        for (const [key, value] of Object.entries(failure.error)) {
+          if (key !== "message" && key !== "stack") {
+            if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value === null) {
+              details[key] = value;
+            }
+          }
+        }
+        if (Object.keys(details).length > 0) {
+          result.details = details;
+        }
+      }
+      return result as NonNullable<InvocationOutcome["failure"]>;
+    }
+    default:
+      return { kind: failure.kind };
+  }
+}

package/src/remote-offers.ts

@@ -0,0 +1,60 @@
+// Ephemeral remote capability availability. Durable work starts only after an offer is selected
+// and represented by a normal continuation; offers themselves must not enter the event log.
+import type { Json } from "@godspeedai/cognate-events";
+import type { Caller, RemoteCapabilityOffer } from "@godspeedai/cognate-runtime-api";
+
+type StoredOffer = RemoteCapabilityOffer & { readonly tenant: string; readonly actorId: string };
+
+export class RemoteOfferRegistry {
+  private readonly offers = new Map<string, StoredOffer>();
+
+  publish(caller: Caller, scopeId: string, request: Omit<RemoteCapabilityOffer, "id" | "scopeId" | "expiresAt"> & { readonly ttlMs: number }): RemoteCapabilityOffer {
+    if (!request.leaseId || !request.agent || !request.contract.id || !request.contract.version || !request.description) throw new Error("remote offer requires lease, agent, contract, and description");
+    if (!Number.isFinite(request.ttlMs) || request.ttlMs <= 0 || request.ttlMs > 300_000) throw new Error("remote offer ttlMs must be between 1 and 300000");
+    const now = Date.now();
+    // A lease identifies one mounted client surface. Re-publish replaces its prior declaration for
+    // this contract and agent, so a remount cannot leave an old schema eligible.
+    const prior = [...this.offers.values()].find((offer) => offer.tenant === caller.tenant && offer.actorId === caller.actor.id && offer.leaseId === request.leaseId && offer.agent === request.agent && offer.contract.id === request.contract.id);
+    const offer: StoredOffer = {
+      id: prior?.id ?? crypto.randomUUID(), leaseId: request.leaseId, agent: request.agent, scopeId,
+      contract: { id: request.contract.id, version: request.contract.version, ...(request.contract.attributes ? { attributes: request.contract.attributes } : {}) },
+      description: request.description, inputSchema: request.inputSchema, ...(request.outputSchema === undefined ? {} : { outputSchema: request.outputSchema }),
+      expiresAt: now + request.ttlMs, tenant: caller.tenant, actorId: caller.actor.id,
+    };
+    this.offers.set(offer.id, offer);
+    return view(offer);
+  }
+
+  list(caller: Caller, agent: string): readonly RemoteCapabilityOffer[] {
+    this.expire();
+    return [...this.offers.values()]
+      .filter((offer) => offer.tenant === caller.tenant && offer.actorId === caller.actor.id && offer.agent === agent)
+      .sort((a, b) => a.contract.id.localeCompare(b.contract.id) || a.id.localeCompare(b.id))
+      .map(view);
+  }
+
+  take(caller: Caller, agent: string, offerId: string): RemoteCapabilityOffer | undefined {
+    this.expire();
+    const offer = this.offers.get(offerId);
+    return offer && offer.tenant === caller.tenant && offer.actorId === caller.actor.id && offer.agent === agent ? view(offer) : undefined;
+  }
+
+  revoke(caller: Caller, offerId: string): boolean {
+    const offer = this.offers.get(offerId);
+    if (!offer || offer.tenant !== caller.tenant || offer.actorId !== caller.actor.id) return false;
+    this.offers.delete(offerId);
+    return true;
+  }
+
+  private expire(): void {
+    const now = Date.now();
+    for (const [id, offer] of this.offers) if (offer.expiresAt <= now) this.offers.delete(id);
+  }
+}
+
+function view(offer: StoredOffer): RemoteCapabilityOffer {
+  const { tenant: _tenant, actorId: _actorId, ...result } = offer;
+  return result as RemoteCapabilityOffer;
+}
+
+export type RemoteOfferInput = { readonly leaseId: string; readonly agent: string; readonly contract: { readonly id: string; readonly version: string; readonly attributes?: Readonly<Record<string, Json>> }; readonly description: string; readonly inputSchema: Json; readonly outputSchema?: Json; readonly ttlMs: number };