@xemahq/kernel-contracts 0.32.0 → 0.34.0

package/src/connector/lib/connector-http-request.ts

@@ -0,0 +1,187 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────
+ * Declarative HTTP request template — the DATA face of a connector operation
+ *
+ * A connector operation whose `ConnectorAdapterKind` is
+ * {@link ConnectorAdapterKind.DeclarativeHttp} carries this template instead of
+ * a compiled code module. It is everything a GENERIC executor needs to turn a
+ * capability invocation into a single outbound HTTP call:
+ *
+ *   - `method` + `pathTemplate` (joined onto the provider's `apiBaseUrl`),
+ *   - `{placeholder}` substitution from the invocation input (deterministic,
+ *     fail-fast on a missing placeholder — never a guess),
+ *   - static/placeholder `query` + `headers`,
+ *   - a `bodyMode` selecting whether the (placeholder-stripped) input becomes a
+ *     JSON body,
+ *   - an {@link ConnectorAuthInjection} describing WHERE the resolved
+ *     credential is injected (the credential VALUE is never here — it is
+ *     resolved at execution time through the credential-broker custody seam).
+ *
+ * This is the "third-party ships a signed connector biome with a descriptor and
+ * it works with NO sidecar code" fast-path. Code adapters remain the escape
+ * hatch (a different adapter kind, hosted by `biome-adapter-host`).
+ * ─────────────────────────────────────────────────────────────────────────
+ */
+
+import { z } from 'zod';
+
+/**
+ * The HTTP verb a declarative operation issues. Closed set — a connector
+ * operation is exactly one request.
+ */
+export enum ConnectorHttpMethod {
+  Get = 'GET',
+  Post = 'POST',
+  Put = 'PUT',
+  Patch = 'PATCH',
+  Delete = 'DELETE',
+}
+
+/** Zod mirror of {@link ConnectorHttpMethod}. */
+export const ConnectorHttpMethodSchema = z.nativeEnum(ConnectorHttpMethod);
+
+/**
+ * How the generic executor injects the resolved connection credential into the
+ * outbound request. The credential VALUE comes from the custody seam at
+ * execution time; this only says WHERE it goes. Closed set.
+ */
+export enum ConnectorAuthInjectionKind {
+  /** `Authorization: Bearer <accessToken>`. */
+  BearerHeader = 'bearer_header',
+  /** `Authorization: Basic <accessToken>` (the token is already base64 `user:pass`). */
+  BasicHeader = 'basic_header',
+  /** `<headerName>: <valuePrefix?><accessToken>` — e.g. `X-Api-Key: <token>`. */
+  Header = 'header',
+  /** `?<queryParamName>=<accessToken>` — e.g. `?api_key=<token>`. */
+  QueryParam = 'query_param',
+  /**
+   * No credential injected — a public operation. Only valid when the operation
+   * declares `requiresConnection: false`; the executor asserts the pairing.
+   */
+  None = 'none',
+}
+
+/** Zod mirror of {@link ConnectorAuthInjectionKind}. */
+export const ConnectorAuthInjectionKindSchema = z.nativeEnum(
+  ConnectorAuthInjectionKind,
+);
+
+/**
+ * Whether the (placeholder-stripped) invocation input becomes an outbound
+ * request body. Closed set — kept minimal; a richer body-mapping language is a
+ * future additive member, never a free-form template string.
+ */
+export enum ConnectorHttpBodyMode {
+  /** No request body (typical for GET/DELETE). */
+  None = 'none',
+  /**
+   * The invocation input object (minus reserved/tenant keys and minus keys
+   * consumed as path/query/header placeholders) is sent as a JSON body.
+   */
+  JsonInput = 'json_input',
+}
+
+/** Zod mirror of {@link ConnectorHttpBodyMode}. */
+export const ConnectorHttpBodyModeSchema = z.nativeEnum(ConnectorHttpBodyMode);
+
+/**
+ * Where the resolved credential is injected into the outbound request. `kind`
+ * selects the injection style; the extra fields are required only for the
+ * styles that need them (validated cross-field, fail-fast).
+ */
+export interface ConnectorAuthInjection {
+  readonly kind: ConnectorAuthInjectionKind;
+  /** Header name — REQUIRED for `Header`, forbidden otherwise. */
+  readonly headerName?: string;
+  /** Optional value prefix for `Header` (e.g. `token ` → `token <secret>`). */
+  readonly valuePrefix?: string;
+  /** Query-param name — REQUIRED for `QueryParam`, forbidden otherwise. */
+  readonly queryParamName?: string;
+}
+
+/**
+ * Zod mirror of {@link ConnectorAuthInjection}. Strict + cross-field: the
+ * placement-specific field MUST be present for its kind and absent for others,
+ * so a malformed injection can never be silently under-specified.
+ */
+export const ConnectorAuthInjectionSchema = z
+  .strictObject({
+    kind: ConnectorAuthInjectionKindSchema,
+    headerName: z.string().min(1).optional(),
+    valuePrefix: z.string().optional(),
+    queryParamName: z.string().min(1).optional(),
+  })
+  .superRefine((value, ctx) => {
+    if (value.kind === ConnectorAuthInjectionKind.Header) {
+      if (value.headerName === undefined) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['headerName'],
+          message: 'auth.kind="header" requires headerName.',
+        });
+      }
+    } else if (value.headerName !== undefined) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['headerName'],
+        message: `headerName is only valid for auth.kind="header" (got "${value.kind}").`,
+      });
+    }
+    if (
+      value.kind !== ConnectorAuthInjectionKind.Header &&
+      value.valuePrefix !== undefined
+    ) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['valuePrefix'],
+        message: `valuePrefix is only valid for auth.kind="header" (got "${value.kind}").`,
+      });
+    }
+    if (value.kind === ConnectorAuthInjectionKind.QueryParam) {
+      if (value.queryParamName === undefined) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['queryParamName'],
+          message: 'auth.kind="query_param" requires queryParamName.',
+        });
+      }
+    } else if (value.queryParamName !== undefined) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['queryParamName'],
+        message: `queryParamName is only valid for auth.kind="query_param" (got "${value.kind}").`,
+      });
+    }
+  });
+
+/**
+ * A single declarative HTTP request. `pathTemplate` is joined onto the
+ * provider's `apiBaseUrl` at execution time. `pathTemplate`, `query` values and
+ * `headers` values may contain `{name}` placeholders substituted from the
+ * invocation input — a placeholder with no matching input key is a fail-fast
+ * error at execution, never a silent empty string.
+ */
+export interface ConnectorHttpRequestTemplate {
+  readonly method: ConnectorHttpMethod;
+  /** Path (joined onto provider `apiBaseUrl`); MUST start with `/`. */
+  readonly pathTemplate: string;
+  /** Static or `{placeholder}` query params. */
+  readonly query?: Readonly<Record<string, string>>;
+  /** Static or `{placeholder}` request headers (never the auth header — that is `auth`). */
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly bodyMode: ConnectorHttpBodyMode;
+  readonly auth: ConnectorAuthInjection;
+}
+
+/**
+ * Zod mirror of {@link ConnectorHttpRequestTemplate} — value-identical to the
+ * interface. Strict: unknown keys fail fast.
+ */
+export const ConnectorHttpRequestTemplateSchema = z.strictObject({
+  method: ConnectorHttpMethodSchema,
+  pathTemplate: z.string().min(1).startsWith('/'),
+  query: z.record(z.string(), z.string()).readonly().optional(),
+  headers: z.record(z.string(), z.string()).readonly().optional(),
+  bodyMode: ConnectorHttpBodyModeSchema,
+  auth: ConnectorAuthInjectionSchema,
+});

package/src/connector/lib/integration-provider-contribution.ts

@@ -24,6 +24,7 @@
 
 import { z } from 'zod';
 
+import { ConnectorAdapterKind } from './connector-adapter-kind';
 import { ConnectorDescriptorSchema } from './connector-descriptor';
 import {
   ProviderDescriptorBaseSchema,
@@ -111,6 +112,26 @@ export const IntegrationProviderContributionManifestSchema = z
       }
       seenConnectorKeys.add(connector.connectorKey);
     });
+
+    // A declarative-http operation is executed by joining its pathTemplate onto
+    // the provider's apiBaseUrl. If ANY connector ships one, the provider MUST
+    // declare apiBaseUrl — otherwise the generic executor has no base URL and
+    // would fail at invocation time. Enforce it at ingest instead (fail-fast).
+    const hasDeclarativeOperation = manifest.connectors.some((connector) =>
+      (connector.operations ?? []).some(
+        (op) => op.adapterKind === ConnectorAdapterKind.DeclarativeHttp,
+      ),
+    );
+    if (hasDeclarativeOperation && manifest.provider.apiBaseUrl === undefined) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['provider', 'apiBaseUrl'],
+        message:
+          `Provider "${manifest.provider.providerKey}" ships a declarative-http ` +
+          'connector operation but declares no apiBaseUrl — the generic ' +
+          'executor joins every operation path onto it, so it is required.',
+      });
+    }
   });
 
 export type IntegrationProviderContributionManifest = z.infer<

package/src/connector/lib/provider-descriptor.ts

@@ -147,6 +147,15 @@ export interface ProviderDescriptor {
   /** Catalog grouping label (e.g. `Email`, `Source control`, `Chat`). */
   readonly category: string;
 
+  /**
+   * Base URL every `declarative-http` operation under this provider is joined
+   * onto (e.g. `https://api.hubspot.com`). REQUIRED when any connector under
+   * this provider declares a `declarative-http` operation (enforced at the
+   * contribution boundary); absent for code / MCP / mail providers. Never
+   * carries a trailing slash by convention — the executor joins defensively.
+   */
+  readonly apiBaseUrl?: string;
+
   /** How the shared app credential authenticates. */
   readonly appAuthKind: ProviderAppAuthKind;
   /** Who shipped the provider — drives requirement scope + which admin fills. */
@@ -201,6 +210,7 @@ export const ProviderDescriptorBaseSchema = z.strictObject({
   description: z.string().min(1),
   iconName: z.string().min(1),
   category: z.string().min(1),
+  apiBaseUrl: z.string().url().optional(),
   appAuthKind: z.nativeEnum(ProviderAppAuthKind),
   origin: z.nativeEnum(ProviderOrigin),
   appCredentialSchema: z.array(CredentialFieldSpecSchema).readonly().optional(),

package/src/contribution/lib/contribution-kind.ts

@@ -2,31 +2,93 @@ import { z } from 'zod';
 
 /**
  * `ContributionKind` is the closed enum that names every kind of thing a biome
- * (biome) may contribute to the Xema OS through the Contribution Protocol
- * (XSI plane 2). Extending it is a one-line PR to the kernel.
+ * may contribute to the Xema OS through the Contribution Protocol (XSI plane 2).
+ * Extending it is a one-line PR to the kernel.
  *
- * The enum equals the SUPPORTED set: every member is either handled by a
- * biome-host `KindParser` (see `biome-host-api/src/contributions/parsers/`)
- * or is a first-class self-registration kind (`Capability`, `ResourceOwnership`,
- * `StageMachine`) whose manifest schema the kernel co-owns. Purely-decorative
- * members that duplicated a working non-contribution mechanism and had no
- * parser were culled in the H7 pass. Adding a member is a one-line PR AND
- * requires a parser (or a first-class handler) — do not re-add a decorative
- * kind with no ingestion path.
+ * The enum is a CATALOG, not a promise that biome-host parses every member.
+ * Each member falls into exactly ONE ingestion category, stated by its
+ * per-member doc-comment:
+ *
+ *   1. biome-host `KindParser` — discovered from a biome's `contributions/`
+ *      directory by `biome-host-api` and forwarded to the owning service via
+ *      the contribution-sync outbox. This is the majority; see
+ *      `biome-host-api/src/contributions/parsers/`.
+ *   2. Domain-service handler / first-class self-registration — ingested by a
+ *      service OTHER than biome-host, through its own
+ *      `BootstrapContributionsService` handler or a kernel registry adapter:
+ *        • `Capability`, `ResourceOwnership`, `SearchType` — kernel-owned
+ *          manifest schema, validated fail-fast by BOTH the biome-host parser
+ *          and the owning domain service.
+ *        • `StageMachine`, `ArtifactType`, `InquiryKind` — host-owned manifest
+ *          schema, biome-host parses and forwards to the owning host.
+ *        • `ModelResolutionDimension` — `llm-registry-api`'s
+ *          `ModelStrategyBootstrapService`, from kernel-shipped strategy YAML;
+ *          NO biome-host parser.
+ *        • `MountSource` — the kernel `@xemahq/backend-slot-registry-adapters`
+ *          adapter projecting the `MountSourceKindRegistry`; NO biome-host
+ *          parser.
+ *   3. RESERVED — declared for protocol/catalog completeness but with NO
+ *      contribution-protocol ingestion path today. Where the underlying feature
+ *      exists it ships via the convention CONTENT-DIRECTORY seeder (on-disk
+ *      presence — see the manifest reference), NOT the enum-dispatched
+ *      contribution protocol; a few members have no delivery path at all yet.
+ *      Do NOT assume a biome-host parser exists for a RESERVED member, and do
+ *      not ship a biome contribution of that kind expecting it to be ingested.
+ *
+ * This doc-comment is kept HONEST by review: a member with no biome-host parser
+ * MUST be annotated with its true category (2 or 3). An earlier revision falsely
+ * asserted "the enum equals the SUPPORTED set: every member is handled by a
+ * parser or is a first-class self-registration kind" and that decorative
+ * members "were culled in the H7 pass" — neither was true (13 members were
+ * parser-less). Adding a member is a one-line PR, but it MUST arrive with a
+ * parser OR an honest category-2/3 note.
  *
  * Enum string values match the slug spoken by the rest of the protocol
  * (Capability References, manifest declarations) so that round-tripping
- * between the enum and the wire is lossless.
+ * between the enum and the wire is lossless. The values themselves are a WIRE
+ * CONTRACT — never rename or delete a member without a migration plan.
  */
 export enum ContributionKind {
   // -- v1 seed ---------------------------------------------------------------
+  /**
+   * Category 2 (domain-service handler, NOT biome-host). Ingested by the kernel
+   * `@xemahq/backend-slot-registry-adapters` adapter
+   * (`adaptMountSourceRegistryIntoSlots`), which projects the existing
+   * `MountSourceKindRegistry` into the `BackendSlotRegistry`. That registry
+   * stays the authoritative owner and read path; there is NO biome-host parser.
+   */
   MountSource = 'mount-source',
+  /**
+   * RESERVED (category 3). No contribution-protocol parser. MCP tool
+   * descriptors ship today via the convention `mcpTools/` content directory
+   * (on-disk presence seeder). The enum-dispatched contribution path for MCP is
+   * `McpCatalog`, which HAS a parser — do not expect one here.
+   */
   McpTool = 'mcp-tool',
   WorkflowStep = 'workflow-step',
+  /**
+   * RESERVED (category 3). No ingestion path today — no parser, no
+   * content-directory seeder, no domain-service handler. The only in-tree use
+   * is a deliberate PLACEHOLDER reuse of this value in the kernel
+   * `inquiry-kind-adapter` (its own comment flags it as a placeholder, not an
+   * equivalence). A biome contribution of this kind is NOT ingested.
+   */
   GateAction = 'gate-action',
+  /**
+   * RESERVED (category 3). No ingestion path today; referenced only as a worked
+   * "a third party adds a new kind" example in the contribution test-suite.
+   */
   ChartRuntime = 'chart-runtime',
   AgentSkill = 'agent-skill',
   AgentKernel = 'agent-kernel',
+  /**
+   * Category 2 (domain-service handler, NOT biome-host). Ingested by
+   * `llm-registry-api`'s `ModelStrategyBootstrapService` — a
+   * `BootstrapContributionsService` handler that loads the kernel-shipped
+   * `strategies/*.yaml` and upserts model-resolution strategies. No biome-host
+   * parser; the manifest shape is service-local (`StrategyFileSchema`), not a
+   * kernel-owned contribution schema.
+   */
   ModelResolutionDimension = 'model-resolution-dimension',
   WidgetKind = 'widget-kind',
 
@@ -54,17 +116,34 @@ export enum ContributionKind {
 
   /** A role capability bundle contributed by a biome. */
   RoleCapability = 'role-capability',
-  /** The biome-install JSON Schema declaration shipped by a biome. */
+  /**
+   * RESERVED (category 3). No contribution-protocol parser. The install-wizard
+   * resource-selection schema ships via the convention `biomeInstallSchema/`
+   * content directory (on-disk presence seeder), not the enum-dispatched path.
+   */
   BiomeInstallSchema = 'biome-install-schema',
-  /** A UI icon asset contributed by a biome. */
+  /**
+   * RESERVED (category 3). No parser. Icon assets ship via the convention
+   * `icons/` content directory (on-disk presence seeder).
+   */
   Icon = 'icon',
   /** A project-kit bundle contributed by a biome. */
   ProjectKit = 'project-kit',
-  /** A provisioning scaffold contributed by a biome. */
+  /**
+   * RESERVED (category 3). No parser. Provisioning scaffolds ship via the
+   * convention `provisioning/` content directory (declared in
+   * `xema.provisioning[]`, parity-checked at boot), not the contribution path.
+   */
   ProvisioningScaffold = 'provisioning-scaffold',
-  /** A workspace-spec overlay contributed by a biome. */
+  /**
+   * RESERVED (category 3). No ingestion path today — no parser, no
+   * content-directory seeder, no domain-service handler.
+   */
   WorkspaceSpecOverlay = 'workspace-spec-overlay',
-  /** A system-overlay contribution shipped by a biome. */
+  /**
+   * RESERVED (category 3). No ingestion path today — no parser, no
+   * content-directory seeder, no domain-service handler.
+   */
   SystemOverlayContribution = 'system-overlay-contribution',
   /** A concrete integration provider contributed by a biome inside an
    * adapter kind. */
@@ -77,7 +156,11 @@ export enum ContributionKind {
   DeliverableSpec = 'deliverable-spec',
   /** A workspace manifest contributed by a biome. */
   WorkspaceManifest = 'workspace-manifest',
-  /** A workspace-manifest template contributed by a biome. */
+  /**
+   * RESERVED (category 3). No parser (distinct from `WorkspaceManifest`, which
+   * HAS one). Reusable workspace-manifest templates ship via the convention
+   * `workspaceManifestTemplates/` content directory (on-disk presence seeder).
+   */
   WorkspaceManifestTemplate = 'workspace-manifest-template',
   /** A tool-profile contributed by a biome. */
   ToolProfile = 'tool-profile',
@@ -85,9 +168,18 @@ export enum ContributionKind {
    * which is a single tool descriptor; an `McpCatalog` entry is a catalog
    * manifest. */
   McpCatalog = 'mcp-catalog',
-  /** An OpenCode tool descriptor contributed by a biome. */
+  /**
+   * RESERVED (category 3). No contribution-protocol parser. Agent-runtime
+   * custom tools ship via the convention `openCodeTools/` content directory,
+   * baked into the opencode-worker image at build time — not the
+   * enum-dispatched contribution path.
+   */
   OpenCodeTool = 'opencode-tool',
-  /** An OpenCode plugin descriptor contributed by a biome. */
+  /**
+   * RESERVED (category 3). No parser — the contribution-registrar explicitly
+   * does NOT route this kind. Agent-runtime plugins ship via the convention
+   * `openCodePlugins/` content directory, baked into the opencode-worker image.
+   */
   OpenCodePlugin = 'opencode-plugin',
   // -- Capability self-registration ------------------------------------------
   /**

package/src/principal/index.ts

@@ -0,0 +1,5 @@
+export * from './lib/delegation-grant';
+export * from './lib/delegation-chain';
+export * from './lib/clamp-authority';
+export * from './lib/execution-principal';
+export * from './lib/app-invocation-identity';

package/src/principal/lib/app-invocation-identity.ts

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+import {
+  SubjectKind,
+  SubjectRefSchema,
+  type SubjectRef,
+} from '../../subject';
+
+/**
+ * The two ways an app invocation names its `actor`.
+ *
+ * `AppInvocationIdentity` is SUGAR over the `ExecutionPrincipal.actor` field —
+ * it resolves to exactly one `SubjectRef` (via `resolveInvocationActor`). It
+ * adds no authority of its own; it only says WHOSE authority the app is
+ * exercising.
+ *
+ * **`AsApp` is not a bypass.** A scheduled app runs as `executor = app:<id>`
+ * WITH `actor = app:<id>` — the app IS the actor, acting purely as itself. It
+ * must hold an explicit app role IN ITS OWN app to do anything; there is no
+ * ambient "the scheduler said so" authority. A scheduled job does NOT skip row
+ * policy and does NOT skip field policy. `AsApp` narrows the app to its own
+ * granted authority exactly like any other principal — running unattended buys
+ * it nothing that running on behalf of a user would not have to earn through the
+ * same `clampAuthority` intersection.
+ */
+export enum AppInvocationMode {
+  /** The app acts on behalf of a signed-in user; `actor` is that user. */
+  OnBehalfOfUser = 'on-behalf-of-user',
+  /** The app acts as itself (e.g. a schedule); `actor === executor === app:<id>`. */
+  AsApp = 'as-app',
+}
+
+export const AppInvocationModeSchema = z.nativeEnum(AppInvocationMode);
+
+/**
+ * `OnBehalfOfUser` — the app is exercising a specific user's authority. `user`
+ * becomes `ExecutionPrincipal.actor`; the app is the `executor`.
+ */
+export interface OnBehalfOfUserIdentity {
+  mode: AppInvocationMode.OnBehalfOfUser;
+  /** The signed-in subject whose authority the app exercises. */
+  user: SubjectRef;
+  /** The app doing the acting (becomes `executor`). */
+  appId: string;
+}
+
+/**
+ * `AsApp` — the app acts as itself. `actor` and `executor` are BOTH
+ * `app:<appId>`; see the `AppInvocationMode` docblock — this is not a bypass.
+ */
+export interface AsAppIdentity {
+  mode: AppInvocationMode.AsApp;
+  /** The app acting as its own actor and executor. */
+  appId: string;
+}
+
+export type AppInvocationIdentity = OnBehalfOfUserIdentity | AsAppIdentity;
+
+const onBehalfOfUserShape = z.object({
+  mode: z.literal(AppInvocationMode.OnBehalfOfUser),
+  user: SubjectRefSchema,
+  appId: z.string().min(1),
+});
+
+const asAppShape = z.object({
+  mode: z.literal(AppInvocationMode.AsApp),
+  appId: z.string().min(1),
+});
+
+export const OnBehalfOfUserIdentitySchema =
+  onBehalfOfUserShape as z.ZodType<OnBehalfOfUserIdentity>;
+
+export const AsAppIdentitySchema = asAppShape as z.ZodType<AsAppIdentity>;
+
+export const AppInvocationIdentitySchema = z.discriminatedUnion('mode', [
+  onBehalfOfUserShape,
+  asAppShape,
+]) as z.ZodType<AppInvocationIdentity>;
+
+/**
+ * Resolve an `AppInvocationIdentity` to the `ExecutionPrincipal.actor` it is
+ * sugar for. `OnBehalfOfUser` → the named user. `AsApp` → the app itself
+ * (`app:<appId>`), which is ALSO the executor — an app acting as itself has no
+ * elevated authority (see the `AppInvocationMode` docblock). Total over the
+ * closed union; a new mode is a compile error here, never a silent default.
+ */
+export function resolveInvocationActor(
+  identity: AppInvocationIdentity,
+): SubjectRef {
+  switch (identity.mode) {
+    case AppInvocationMode.OnBehalfOfUser:
+      return identity.user;
+    case AppInvocationMode.AsApp:
+      return { kind: SubjectKind.App, id: identity.appId };
+  }
+}

package/src/principal/lib/clamp-authority.ts

@@ -0,0 +1,64 @@
+import type { CapabilityRef } from '../../capability';
+
+/**
+ * `clampAuthority` — the delegation intersection rule (plan D6).
+ *
+ *   effective(P) = grants(P.executor) ∩ effective(P.actor)
+ *
+ * The effective authority of a principal is the INTERSECTION of what the
+ * executor is granted with what the actor already effectively holds. It is
+ * NEVER a union: a delegate can only ever NARROW authority, never widen it. An
+ * app can never do more than its caller.
+ *
+ * Structurally it cannot widen, and this is the load-bearing property: every
+ * element of the returned set is drawn from `executorGrants` AND must also be
+ * present in `actorEffective`, so the result is a subset of BOTH inputs
+ * (`clamp(A, B) ⊆ A` and `clamp(A, B) ⊆ B`). There is no code path that adds a
+ * ref present in only one operand.
+ *
+ * An EMPTY intersection is the default and correct outcome — not an error, not a
+ * signal to fall back to either operand. A principal whose executor shares no
+ * capability with its actor is authorized for nothing, and that denial is the
+ * whole point (it is THE test that must exist before the Wave 10 function
+ * sandbox: a delegate holding a capability its actor lacks is denied).
+ *
+ * Pure and side-effect free. Inputs are read-only sets of `CapabilityRef`; the
+ * result is a fresh set (the smaller operand is iterated for efficiency, but the
+ * membership rule is symmetric so the result is identical either way).
+ */
+export function clampAuthority(
+  executorGrants: ReadonlySet<CapabilityRef>,
+  actorEffective: ReadonlySet<CapabilityRef>,
+): Set<CapabilityRef> {
+  const [smaller, larger] =
+    executorGrants.size <= actorEffective.size
+      ? [executorGrants, actorEffective]
+      : [actorEffective, executorGrants];
+
+  const intersection = new Set<CapabilityRef>();
+  for (const ref of smaller) {
+    if (larger.has(ref)) {
+      intersection.add(ref);
+    }
+  }
+  return intersection;
+}
+
+/**
+ * Fold `clampAuthority` down a whole chain of authority sets, in order.
+ * `clampAuthorityChain([grants(executor), effective(actor), …])` reduces every
+ * operand by intersection, so ANY empty operand collapses the whole result to
+ * empty. Every operand narrows; none widens. An empty input array is itself an
+ * empty authority set (nothing to be authorized for) — never a wildcard.
+ */
+export function clampAuthorityChain(
+  authoritySets: ReadonlyArray<ReadonlySet<CapabilityRef>>,
+): Set<CapabilityRef> {
+  if (authoritySets.length === 0) {
+    return new Set<CapabilityRef>();
+  }
+  return authoritySets.reduce<Set<CapabilityRef>>(
+    (acc, next) => clampAuthority(acc, next),
+    new Set<CapabilityRef>(authoritySets[0]),
+  );
+}