@agent-surface/core 0.15.0 → 0.17.0

package/README.md

@@ -1,49 +1,22 @@
-# @agent-surface/core
+# `@agent-surface/core`
 
-Framework-agnostic core of [agent-surface](https://github.com/Wiseair-srl/agent-surface): a registry for declaring an explicit, semantic, typed, policy-governed *agent surface* over a frontend — and nothing more. If a component or capability is not explicitly annotated, it does not exist for the agent.
-
-Zero runtime dependencies. Provides: canonical capability ids, the `AgentSchema` layer (Standard Schema + built-in JSON Schema subset validator), component/capability definitions, the registry (registration lifecycle, availability, versioning, staleness), synchronous snapshots, the 10-phase invocation pipeline, composable policies, single-use confirmation evidence, audit sinks, and a provider-neutral toolset projection for embedded agent loops.
-
-Docs: https://agent-surface-docs.vercel.app
-
-## Install
-
-```bash
-pnpm add @agent-surface/core
-```
-
-## Use
+Framework-neutral contracts, registry, policy, confirmation, invocation and exposure gateway.
 
 ```ts
-import {
-  createAgentSurfaceRegistry,
-  defineAgentComponent,
-  observation,
-  action,
-  fromStandardSchema,
-  createAgentToolset,
-} from "@agent-surface/core";
-
-const registry = createAgentSurfaceRegistry({
-  environment: import.meta.env.DEV ? "development" : "production",
-  context: () => ({ user: authStore.user }),
+const contract = defineAgentComponentContract({
+  type: "devices.table",
+  description: "Device table",
+  observations: { readState: observationContract({ description: "State", output }) },
+  actions: { selectRows: actionContract({ description: "Select", input, effect: "local-state" }) },
 });
 
-registry.register(
-  defineAgentComponent({
-    type: "devices.table",
-    description: "Table of the devices visible on the current page",
-    observations: { readState: observation({ /* … */ }) },
-    actions: { selectRows: action({ /* … */ }) },
-  }),
-);
-
-const toolset = createAgentToolset(registry, {
-  consumer: { id: "copilot", kind: "embedded" },
-  topology: "embedded",   // required (D26): embedded → confirmations "wait",
-});                       // remote → "two-phase". No global default.
+const registry = createAgentSurfaceRegistry({ authority });
+registry.register(contract.bind({
+  observations: { readState: { read } },
+  actions: { selectRows: { execute } },
+}));
 ```
 
-React apps should use [`@agent-surface/react`](https://www.npmjs.com/package/@agent-surface/react) instead of calling `register` directly. Full specification: [docs](https://github.com/Wiseair-srl/agent-surface/tree/main/docs).
+The compiler authority is mandatory. Raw/unknown/stale/changed registrations fail closed. Use `createAgentExposureGateway(authority)` at final provider/MCP assembly.
 
-MIT © Wiseair S.r.l.
+See [Core API](../../docs/03-core-api.md).

package/dist/explain.d.ts

@@ -1,5 +1,5 @@
-import { D as DiscoveryDecision, A as AgentRouteInfo, a as AgentConsumer, b as AgentSurfaceRegistry, S as SnapshotContext } from './registry-XD1QsGQ4.js';
-export { m as matchesScope } from './registry-XD1QsGQ4.js';
+import { D as DiscoveryDecision, A as AgentRouteInfo, a as AgentConsumer, b as AgentSurfaceRegistry, S as SnapshotContext } from './registry-QvbeJMRD.js';
+export { m as matchesScope } from './registry-QvbeJMRD.js';
 
 /**
  * `explainSurface()` — the developer projection.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { J as JsonSchema, c as JsonValue, d as AgentInvocationResult, U as Unsubscribe, a as AgentConsumer, b as AgentSurfaceRegistry } from './registry-XD1QsGQ4.js';
-export { e as AGENT_CAPABILITY_ERROR_CODES, f as AgentActionContext, g as AgentActionDefinition, h as AgentActionDescriptor, i as AgentAuthorizationContext, j as AgentCapabilityDescriptorUnion, k as AgentCapabilityErrorCode, l as AgentCapabilityErrorPayload, n as AgentComponentDefinition, o as AgentComponentDescriptor, p as AgentConcurrency, q as AgentEffect, r as AgentEnvironment, s as AgentErrorRetry, t as AgentInvocation, u as AgentInvocationPolicyContext, v as AgentObservationDefinition, w as AgentObservationDescriptor, x as AgentPolicy, y as AgentPolicyContext, z as AgentProcedureBinding, B as AgentProcedureBindingRuntimeConfig, C as AgentProcedureDescriptor, E as AgentProcedureEffect, F as AgentProcedureExecutor, G as AgentProcedureRefDescriptor, H as AgentReadContext, I as AgentRegistrationHandle, A as AgentRouteInfo, K as AgentSchema, L as AgentSchemaError, M as AgentSchemaIssue, N as AgentSurfaceDefinitionError, O as AgentSurfaceDefinitionErrorCode, P as AgentSurfaceError, Q as AgentSurfaceEvent, R as AgentSurfaceLimits, T as AgentSurfaceSnapshot, V as AuditEvent, W as AuditSink, X as CONFIRMATION_ESCALATION, Y as ConfirmationController, Z as ConfirmationEscalation, _ as DEFAULT_LIMITS, D as DiscoveryDecision, $ as InvokeOptions, a0 as PendingConfirmation, a1 as PreconditionFailure, a2 as ProcedureCallInfo, a3 as RegistrationCandidate, a4 as RegistryOptions, S as SnapshotContext, a5 as StandardSchemaV1, a6 as action, a7 as audit, a8 as authenticated, a9 as composeInvokeChain, aa as consoleAuditSink, ab as createAgentSurfaceRegistry, ac as defineAgentComponent, ad as emptyObjectSchema, ae as environment, af as evaluateDiscovery, ag as fromJsonSchema, ah as fromStandardSchema, ai as hasPermission, aj as isAgentSurfaceError, ak as memoryAuditSink, al as observation, am as rateLimit, an as requireConfirmation, ao as tenantBoundary, ap as validateComponentDefinition, aq as validateJsonSchemaDocument, ar as validateValueAgainstSchema } from './registry-XD1QsGQ4.js';
+import { J as JsonSchema, c as JsonValue, d as AgentInvocationResult, U as Unsubscribe, a as AgentConsumer, b as AgentSurfaceRegistry } from './registry-QvbeJMRD.js';
+export { e as AGENT_CAPABILITY_ERROR_CODES, f as AgentActionContext, g as AgentActionContract, h as AgentActionDefinition, i as AgentActionDescriptor, j as AgentAuthorizationContext, k as AgentCapabilityDescriptorUnion, l as AgentCapabilityErrorCode, n as AgentCapabilityErrorPayload, o as AgentComponentContract, p as AgentComponentContractDefinition, q as AgentComponentDefinition, r as AgentComponentDescriptor, s as AgentComponentRuntimeBindings, t as AgentConcurrency, u as AgentEffect, v as AgentEnvironment, w as AgentErrorRetry, x as AgentExposureGateway, y as AgentInvocation, z as AgentInvocationPolicyContext, B as AgentObservationContract, C as AgentObservationDefinition, E as AgentObservationDescriptor, F as AgentPolicy, G as AgentPolicyContext, H as AgentProcedureBinding, I as AgentProcedureBindingRuntimeConfig, K as AgentProcedureContract, L as AgentProcedureContractDefinition, M as AgentProcedureDescriptor, N as AgentProcedureEffect, O as AgentProcedureExecutor, P as AgentProcedureRefDescriptor, Q as AgentReadContext, R as AgentRegistrationHandle, A as AgentRouteInfo, T as AgentSchema, V as AgentSchemaError, W as AgentSchemaIssue, X as AgentSurfaceDefinitionError, Y as AgentSurfaceDefinitionErrorCode, Z as AgentSurfaceError, _ as AgentSurfaceEvent, $ as AgentSurfaceLimits, a0 as AgentSurfaceSnapshot, a1 as AuditEvent, a2 as AuditSink, a3 as CAPABILITY_CONTRACT_FORMAT_VERSION, a4 as CONFIRMATION_ESCALATION, a5 as CapabilityAuthority, a6 as CapabilityContractEntry, a7 as CapabilityContractKind, a8 as CapabilityContractManifest, a9 as CapabilityPolicyAttachment, aa as CompiledExternalAgentTool, ab as ConfirmationController, ac as ConfirmationEscalation, ad as DEFAULT_LIMITS, D as DiscoveryDecision, ae as ExternalAgentToolContract, af as ExternalAgentToolContractDefinition, ag as ExternalCapabilityContractDigest, ah as InvokeOptions, ai as PendingConfirmation, aj as PreconditionFailure, ak as ProcedureCallInfo, al as RegistrationCandidate, am as RegistryOptions, S as SnapshotContext, an as StandardSchemaV1, ao as action, ap as actionContract, aq as assertDefinitionAuthorized, ar as audit, as as authenticated, at as authorizeAgentProcedureBinding, au as composeInvokeChain, av as consoleAuditSink, aw as createAgentExposureGateway, ax as createAgentSurfaceRegistry, ay as createCapabilityAuthority, az as defineAgentComponent, aA as defineAgentComponentContract, aB as defineAgentProcedureContract, aC as defineExternalAgentToolContract, aD as deriveAgentComponentBinding, aE as emptyObjectSchema, aF as environment, aG as evaluateDiscovery, aH as fromJsonSchema, aI as fromStandardSchema, aJ as hasPermission, aK as isAgentSurfaceError, aL as memoryAuditSink, aM as observation, aN as observationContract, aO as rateLimit, aP as requireConfirmation, aQ as tenantBoundary, aR as validateComponentDefinition, aS as validateJsonSchemaDocument, aT as validateValueAgainstSchema } from './registry-QvbeJMRD.js';
 
 /**
  * Canonical ID grammar (docs/01 §identity):

package/dist/index.js

@@ -23,6 +23,7 @@ import {
   consumerKeyOf,
   createSnapshot,
   decodeWireName,
+  deepFreeze,
   encodeWireName,
   encodeWireNameForInstance,
   environment,
@@ -1945,8 +1946,521 @@ function drainObservationQueues(internals) {
   for (const waiter of waiting) waiter.admit(false);
 }
 
+// src/sha256.ts
+var K = new Uint32Array([
+  1116352408,
+  1899447441,
+  3049323471,
+  3921009573,
+  961987163,
+  1508970993,
+  2453635748,
+  2870763221,
+  3624381080,
+  310598401,
+  607225278,
+  1426881987,
+  1925078388,
+  2162078206,
+  2614888103,
+  3248222580,
+  3835390401,
+  4022224774,
+  264347078,
+  604807628,
+  770255983,
+  1249150122,
+  1555081692,
+  1996064986,
+  2554220882,
+  2821834349,
+  2952996808,
+  3210313671,
+  3336571891,
+  3584528711,
+  113926993,
+  338241895,
+  666307205,
+  773529912,
+  1294757372,
+  1396182291,
+  1695183700,
+  1986661051,
+  2177026350,
+  2456956037,
+  2730485921,
+  2820302411,
+  3259730800,
+  3345764771,
+  3516065817,
+  3600352804,
+  4094571909,
+  275423344,
+  430227734,
+  506948616,
+  659060556,
+  883997877,
+  958139571,
+  1322822218,
+  1537002063,
+  1747873779,
+  1955562222,
+  2024104815,
+  2227730452,
+  2361852424,
+  2428436474,
+  2756734187,
+  3204031479,
+  3329325298
+]);
+function rotateRight(value, shift) {
+  return value >>> shift | value << 32 - shift;
+}
+function sha256(input) {
+  const bytes = new TextEncoder().encode(input);
+  const paddedLength = Math.ceil((bytes.length + 9) / 64) * 64;
+  const padded = new Uint8Array(paddedLength);
+  padded.set(bytes);
+  padded[bytes.length] = 128;
+  const bitLength = bytes.length * 8;
+  const view = new DataView(padded.buffer);
+  view.setUint32(paddedLength - 8, Math.floor(bitLength / 4294967296));
+  view.setUint32(paddedLength - 4, bitLength >>> 0);
+  const hash = new Uint32Array([
+    1779033703,
+    3144134277,
+    1013904242,
+    2773480762,
+    1359893119,
+    2600822924,
+    528734635,
+    1541459225
+  ]);
+  const words = new Uint32Array(64);
+  for (let offset = 0; offset < paddedLength; offset += 64) {
+    for (let index = 0; index < 16; index += 1) {
+      words[index] = view.getUint32(offset + index * 4);
+    }
+    for (let index = 16; index < 64; index += 1) {
+      const a2 = words[index - 15];
+      const b2 = words[index - 2];
+      const sigma0 = rotateRight(a2, 7) ^ rotateRight(a2, 18) ^ a2 >>> 3;
+      const sigma1 = rotateRight(b2, 17) ^ rotateRight(b2, 19) ^ b2 >>> 10;
+      words[index] = words[index - 16] + sigma0 + words[index - 7] + sigma1 >>> 0;
+    }
+    let [a, b, c, d, e, f, g, h] = hash;
+    for (let index = 0; index < 64; index += 1) {
+      const sum1 = rotateRight(e, 6) ^ rotateRight(e, 11) ^ rotateRight(e, 25);
+      const choice = e & f ^ ~e & g;
+      const temp1 = h + sum1 + choice + K[index] + words[index] >>> 0;
+      const sum0 = rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22);
+      const majority = a & b ^ a & c ^ b & c;
+      const temp2 = sum0 + majority >>> 0;
+      h = g;
+      g = f;
+      f = e;
+      e = d + temp1 >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = temp1 + temp2 >>> 0;
+    }
+    hash[0] = hash[0] + a >>> 0;
+    hash[1] = hash[1] + b >>> 0;
+    hash[2] = hash[2] + c >>> 0;
+    hash[3] = hash[3] + d >>> 0;
+    hash[4] = hash[4] + e >>> 0;
+    hash[5] = hash[5] + f >>> 0;
+    hash[6] = hash[6] + g >>> 0;
+    hash[7] = hash[7] + h >>> 0;
+  }
+  return [...hash].map((value) => value.toString(16).padStart(8, "0")).join("");
+}
+
+// src/contract.ts
+var CAPABILITY_CONTRACT_FORMAT_VERSION = 4;
+var authorityStates = /* @__PURE__ */ new WeakMap();
+var componentBindingProofs = /* @__PURE__ */ new WeakMap();
+var capabilityContractProofs = /* @__PURE__ */ new WeakMap();
+var externalToolProofs = /* @__PURE__ */ new WeakMap();
+var unsafeAuthorityTestMode = false;
+function isUnsafeAuthorityTestMode() {
+  return unsafeAuthorityTestMode;
+}
+function observationContract(contract) {
+  return contract;
+}
+function actionContract(contract) {
+  return contract;
+}
+function defineAgentComponentContract(definition, compiled) {
+  const contract = {
+    ...definition,
+    kind: "agent-component-contract",
+    bind(bindings) {
+      const observations = {};
+      for (const [name, authored] of Object.entries(definition.observations ?? {})) {
+        const runtime = bindings.observations?.[name];
+        if (!runtime?.read) {
+          throw new AgentSurfaceDefinitionError(
+            "INVALID_DEFINITION",
+            `contract "${definition.type}" observation "${name}" has no runtime binding`
+          );
+        }
+        observations[name] = {
+          description: authored.description,
+          output: authored.output,
+          read: runtime.read,
+          ...authored.meta ? { meta: authored.meta } : {},
+          ...authored.timeoutMs !== void 0 ? { timeoutMs: authored.timeoutMs } : {},
+          ...runtime.when ? { when: runtime.when } : {},
+          ...runtime.unavailableReason ? { unavailableReason: runtime.unavailableReason } : {},
+          ...runtime.policies ? { policies: runtime.policies } : {}
+        };
+      }
+      const actions = {};
+      for (const [name, authored] of Object.entries(definition.actions ?? {})) {
+        const runtime = bindings.actions?.[name];
+        if (!runtime?.execute) {
+          throw new AgentSurfaceDefinitionError(
+            "INVALID_DEFINITION",
+            `contract "${definition.type}" action "${name}" has no runtime binding`
+          );
+        }
+        actions[name] = {
+          description: authored.description,
+          input: authored.input,
+          ...authored.output ? { output: authored.output } : {},
+          effect: authored.effect,
+          execute: runtime.execute,
+          ...authored.idempotent !== void 0 ? { idempotent: authored.idempotent } : {},
+          ...authored.reversible !== void 0 ? { reversible: authored.reversible } : {},
+          ...authored.confirmation !== void 0 ? { confirmation: authored.confirmation } : {},
+          ...authored.audit !== void 0 ? { audit: authored.audit } : {},
+          ...authored.meta ? { meta: authored.meta } : {},
+          ...authored.timeoutMs !== void 0 ? { timeoutMs: authored.timeoutMs } : {},
+          ...authored.concurrency ? { concurrency: authored.concurrency } : {},
+          ...runtime.when ? { when: runtime.when } : {},
+          ...runtime.unavailableReason ? { unavailableReason: runtime.unavailableReason } : {},
+          ...runtime.precondition ? { precondition: runtime.precondition } : {},
+          ...runtime.policies ? { policies: runtime.policies } : {}
+        };
+      }
+      const bound = {
+        type: definition.type,
+        description: definition.description,
+        ...bindings.instanceId !== void 0 ? { instanceId: bindings.instanceId } : {},
+        ...bindings.parent ? { parent: bindings.parent } : {},
+        ...definition.meta ? { meta: definition.meta } : {},
+        ...bindings.internal ? { internal: bindings.internal } : {},
+        ...bindings.policies ? { policies: bindings.policies } : {},
+        ...definition.origin ? { origin: definition.origin } : {},
+        ...definition.priority !== void 0 ? { priority: definition.priority } : {},
+        ...bindings.enabled !== void 0 ? { enabled: bindings.enabled } : {},
+        ...Object.keys(observations).length > 0 ? { observations } : {},
+        ...Object.keys(actions).length > 0 ? { actions } : {},
+        ...bindings.procedures ? { procedures: bindings.procedures } : {}
+      };
+      if (compiled) componentBindingProofs.set(bound, compiled);
+      return bound;
+    }
+  };
+  return contract;
+}
+function defineAgentProcedureContract(definition, compiled) {
+  const contract = {
+    kind: "agent-procedure-contract",
+    definition
+  };
+  if (compiled) capabilityContractProofs.set(contract, compiled);
+  return contract;
+}
+function defineExternalAgentToolContract(definition, compiled) {
+  const contract = {
+    kind: "external-agent-tool-contract",
+    definition,
+    bind(binding) {
+      if (!compiled) {
+        throw new AgentSurfaceDefinitionError(
+          "INVALID_DEFINITION",
+          `external contract "${definition.id}" has no compiler provenance`
+        );
+      }
+      const tool = {
+        name: definition.id,
+        description: definition.description,
+        inputSchema: definition.input.jsonSchema,
+        execute: binding.execute
+      };
+      externalToolProofs.set(tool, compiled);
+      return tool;
+    }
+  };
+  if (compiled) capabilityContractProofs.set(contract, compiled);
+  return contract;
+}
+function deriveAgentComponentBinding(source, derived) {
+  const proof = componentBindingProofs.get(source);
+  if (proof) componentBindingProofs.set(derived, proof);
+  return derived;
+}
+function authorizeAgentProcedureBinding(contract, definition) {
+  const token = capabilityContractProofs.get(contract);
+  if (token) {
+    componentBindingProofs.set(definition, {
+      manifestHash: token.manifestHash,
+      declarationId: token.declarationId,
+      capabilities: { [token.capabilityId]: token }
+    });
+  }
+  return definition;
+}
+function manifestIndex(manifest) {
+  if (manifest.formatVersion !== CAPABILITY_CONTRACT_FORMAT_VERSION || manifest.completeness?.status !== "proven" || typeof manifest.hash !== "string" || manifest.hash.length === 0) {
+    throw new AgentSurfaceDefinitionError("INVALID_DEFINITION", "invalid compiled capability manifest");
+  }
+  const index = /* @__PURE__ */ new Map();
+  for (const entry of manifest.capabilities) {
+    const { contractHash, targets: _targets, ...contract } = entry;
+    if (sha256(canonicalContractJson(contract)) !== contractHash) {
+      throw new AgentSurfaceDefinitionError(
+        "INVALID_DEFINITION",
+        `compiled contract hash is invalid for "${entry.capabilityId}"`
+      );
+    }
+    const key = `${entry.declarationId}\0${entry.capabilityId}`;
+    if (index.has(key)) {
+      throw new AgentSurfaceDefinitionError(
+        "DUPLICATE_CAPABILITY",
+        `duplicate compiled declaration "${entry.declarationId}" for "${entry.capabilityId}"`
+      );
+    }
+    index.set(key, entry);
+  }
+  const { hash, ...payload } = manifest;
+  if (sha256(canonicalContractJson(payload)) !== hash) {
+    throw new AgentSurfaceDefinitionError("INVALID_DEFINITION", "compiled manifest hash is invalid");
+  }
+  return index;
+}
+function canonicalContractValue(value) {
+  if (value === null) return "null";
+  if (value === void 0) return "null";
+  if (typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error("contract contains a non-finite number");
+    return JSON.stringify(Object.is(value, -0) ? 0 : value);
+  }
+  if (Array.isArray(value)) return `[${value.map(canonicalContractValue).join(",")}]`;
+  const record = value;
+  return `{${Object.keys(record).sort().filter((key) => record[key] !== void 0).map((key) => `${JSON.stringify(key)}:${canonicalContractValue(record[key])}`).join(",")}}`;
+}
+function canonicalContractJson(value) {
+  return `${canonicalContractValue(value)}
+`;
+}
+function createCapabilityAuthority(manifest) {
+  const snapshot = deepFreeze(
+    JSON.parse(JSON.stringify(manifest))
+  );
+  const authority = Object.freeze({ manifest: snapshot });
+  authorityStates.set(authority, { manifest: snapshot, index: manifestIndex(snapshot) });
+  return authority;
+}
+function authorityState(authority) {
+  const state = authorityStates.get(authority);
+  if (!state) {
+    throw new AgentSurfaceDefinitionError(
+      "INVALID_DEFINITION",
+      "invalid capability authority: use compiler-generated authority"
+    );
+  }
+  return state;
+}
+function assertCapabilityAuthority(authority) {
+  authorityState(authority);
+}
+function assertToken(token, manifest, index) {
+  if (token.manifestHash !== manifest.hash) {
+    throw new AgentSurfaceDefinitionError(
+      "INVALID_DEFINITION",
+      `stale compiler token for "${token.capabilityId}": manifest hash mismatch`
+    );
+  }
+  const declared = index.get(`${token.declarationId}\0${token.capabilityId}`);
+  if (!declared) {
+    throw new AgentSurfaceDefinitionError(
+      "INVALID_DEFINITION",
+      `unknown compiled declaration "${token.declarationId}" for "${token.capabilityId}"`
+    );
+  }
+  if (declared.contractHash !== token.contractHash) {
+    throw new AgentSurfaceDefinitionError(
+      "INVALID_DEFINITION",
+      `compiled contract hash mismatch for "${token.capabilityId}"`
+    );
+  }
+}
+var CONFIRMATION_RANK = { never: 0, optional: 1, required: 2 };
+function effectiveProcedureConfirmation(binding) {
+  if (binding.ref.requiresApproval || binding.config.confirmation === "required") return "required";
+  return binding.config.confirmation ?? "never";
+}
+function runtimeCapabilities(definition) {
+  const sharedPolicies = definition.policies ?? [];
+  return [
+    ...Object.entries(definition.observations ?? {}).map(([name, observation2]) => ({
+      capabilityId: `view:${definition.type}.${name}`,
+      kind: "observation",
+      description: observation2.description,
+      effect: "read",
+      outputSchema: observation2.output.jsonSchema,
+      policies: [...sharedPolicies, ...observation2.policies ?? []]
+    })),
+    ...Object.entries(definition.actions ?? {}).map(([name, action2]) => ({
+      capabilityId: `view:${definition.type}.${name}`,
+      kind: "action",
+      description: action2.description,
+      effect: action2.effect,
+      inputSchema: action2.input.jsonSchema,
+      ...action2.output ? { outputSchema: action2.output.jsonSchema } : {},
+      confirmation: action2.confirmation ?? "never",
+      policies: [...sharedPolicies, ...action2.policies ?? []]
+    })),
+    ...(definition.procedures ?? []).map((binding) => ({
+      capabilityId: binding.ref.id,
+      kind: "procedure",
+      description: binding.ref.description,
+      effect: binding.ref.effect,
+      inputSchema: binding.ref.inputSchema,
+      ...binding.ref.outputSchema ? { outputSchema: binding.ref.outputSchema } : {},
+      confirmation: effectiveProcedureConfirmation(binding),
+      policies: [...sharedPolicies, ...binding.config.policies ?? []]
+    }))
+  ];
+}
+function assertPolicyCoverage(declared, runtime, capabilityId) {
+  for (const attachment of declared ?? []) {
+    const policy = runtime.find((candidate) => candidate.name === attachment.name);
+    const phaseImplemented = !attachment.phase || attachment.phase === "discovery" && typeof policy?.onDiscovery === "function" || attachment.phase === "authorize" && typeof policy?.onAuthorize === "function" || attachment.phase === "invoke" && typeof policy?.onInvoke === "function";
+    if (!policy || !phaseImplemented) {
+      throw new AgentSurfaceDefinitionError(
+        "INVALID_DEFINITION",
+        `capability "${capabilityId}" omits required policy "${attachment.name}"${attachment.phase ? ` at ${attachment.phase}` : ""}`
+      );
+    }
+  }
+}
+function assertRuntimeMatchesContract(runtime, declared) {
+  const mismatch = (field) => {
+    throw new AgentSurfaceDefinitionError(
+      "INVALID_DEFINITION",
+      `runtime ${field} mismatch for "${runtime.capabilityId}"`
+    );
+  };
+  if (declared.kind !== runtime.kind) mismatch("kind");
+  if (declared.description !== runtime.description) mismatch("description");
+  if (declared.effect !== runtime.effect) mismatch("effect");
+  if (!jsonDeepEqual(declared.inputSchema, runtime.inputSchema)) {
+    mismatch("input schema");
+  }
+  if (!jsonDeepEqual(declared.outputSchema, runtime.outputSchema)) {
+    mismatch("output schema");
+  }
+  const declaredConfirmation = declared.confirmation ?? "never";
+  const runtimeConfirmation = runtime.confirmation ?? "never";
+  if (CONFIRMATION_RANK[runtimeConfirmation] < CONFIRMATION_RANK[declaredConfirmation]) {
+    mismatch("confirmation");
+  }
+  assertPolicyCoverage(declared.policies, runtime.policies, runtime.capabilityId);
+}
+function assertDefinitionAuthorized(definition, authority) {
+  const state = authorityState(authority);
+  const provenance = componentBindingProofs.get(definition);
+  if (!provenance) {
+    throw new AgentSurfaceDefinitionError(
+      "INVALID_DEFINITION",
+      `raw registration "${definition.type}" rejected: bind a compiler-generated contract`
+    );
+  }
+  if (provenance.manifestHash !== state.manifest.hash) {
+    throw new AgentSurfaceDefinitionError(
+      "INVALID_DEFINITION",
+      `stale contract "${provenance.declarationId}": manifest hash mismatch`
+    );
+  }
+  const capabilities = runtimeCapabilities(definition);
+  const expected = capabilities.map((capability) => capability.capabilityId);
+  for (const capability of capabilities) {
+    const capabilityId = capability.capabilityId;
+    const token = provenance.capabilities[capabilityId];
+    if (!token) {
+      throw new AgentSurfaceDefinitionError(
+        "INVALID_DEFINITION",
+        `capability "${capabilityId}" is absent from compiled contract "${provenance.declarationId}"`
+      );
+    }
+    assertToken(token, state.manifest, state.index);
+    const declared = state.index.get(`${token.declarationId}\0${token.capabilityId}`);
+    assertRuntimeMatchesContract(capability, declared);
+  }
+  for (const capabilityId of Object.keys(provenance.capabilities)) {
+    if (!expected.includes(capabilityId)) {
+      throw new AgentSurfaceDefinitionError(
+        "INVALID_DEFINITION",
+        `binding for "${provenance.declarationId}" omits compiled capability "${capabilityId}"`
+      );
+    }
+  }
+}
+function createAgentExposureGateway(authority) {
+  const state = authorityState(authority);
+  return {
+    expose(tools) {
+      return tools.map((tool) => {
+        const token = externalToolProofs.get(tool);
+        if (!token) {
+          throw new AgentSurfaceDefinitionError(
+            "INVALID_DEFINITION",
+            `raw provider tool "${tool.name}" rejected by compiled exposure gateway`
+          );
+        }
+        assertToken(token, state.manifest, state.index);
+        const declared = state.index.get(`${token.declarationId}\0${token.capabilityId}`);
+        if (declared.kind !== "external") {
+          throw new AgentSurfaceDefinitionError(
+            "INVALID_DEFINITION",
+            `runtime kind mismatch for "${tool.name}"`
+          );
+        }
+        if (declared.capabilityId !== tool.name || declared.description !== tool.description) {
+          throw new AgentSurfaceDefinitionError(
+            "INVALID_DEFINITION",
+            `runtime external tool mismatch for "${tool.name}"`
+          );
+        }
+        if (!jsonDeepEqual(declared.inputSchema, tool.inputSchema)) {
+          throw new AgentSurfaceDefinitionError(
+            "INVALID_DEFINITION",
+            `runtime input schema mismatch for "${tool.name}"`
+          );
+        }
+        return tool;
+      });
+    }
+  };
+}
+
 // src/registry.ts
 function createAgentSurfaceRegistry(options) {
+  const unsafeTestMode = isUnsafeAuthorityTestMode();
+  if (!options?.authority && !unsafeTestMode) {
+    throw new AgentSurfaceDefinitionError(
+      "INVALID_DEFINITION",
+      "createAgentSurfaceRegistry requires a compiler-generated capability authority"
+    );
+  }
+  if (options?.authority) assertCapabilityAuthority(options.authority);
   const environment2 = options?.environment ?? "production";
   const limits = { ...DEFAULT_LIMITS, ...options?.limits ?? {} };
   const now = options?.now ?? (() => Date.now());
@@ -2093,6 +2607,10 @@ function createAgentSurfaceRegistry(options) {
     surfaceId: internals.surfaceId,
     register(definition) {
       if (internals.disposed) throw new Error("register() called on a disposed registry");
+      if (options?.authority) assertDefinitionAuthorized(definition, options.authority);
+      else if (!unsafeTestMode) {
+        throw new AgentSurfaceDefinitionError("INVALID_DEFINITION", "capability authority unavailable");
+      }
       validateComponentDefinition(definition, limits, {
         hasProcedureExecutor: internals.executor !== void 0
       });
@@ -2781,20 +3299,30 @@ export {
   AgentSchemaError,
   AgentSurfaceDefinitionError,
   AgentSurfaceError,
+  CAPABILITY_CONTRACT_FORMAT_VERSION,
   CONFIRMATION_ESCALATION,
   DEFAULT_LIMITS,
   MAX_ID_LENGTH,
   MAX_WIRE_NAME_LENGTH,
   action,
+  actionContract,
+  assertDefinitionAuthorized,
   assignWireNames,
   audit,
   authenticated,
+  authorizeAgentProcedureBinding,
   composeInvokeChain,
   consoleAuditSink,
+  createAgentExposureGateway,
   createAgentSurfaceRegistry,
   createAgentToolset,
+  createCapabilityAuthority,
   decodeWireName,
   defineAgentComponent,
+  defineAgentComponentContract,
+  defineAgentProcedureContract,
+  defineExternalAgentToolContract,
+  deriveAgentComponentBinding,
   emptyObjectSchema,
   encodeWireName,
   encodeWireNameForInstance,
@@ -2812,6 +3340,7 @@ export {
   jsonDeepEqual,
   memoryAuditSink,
   observation,
+  observationContract,
   parseCapabilityId,
   rateLimit,
   requireConfirmation,