@xemahq/kernel-contracts 0.50.0 → 0.57.0

package/src/capability/lib/capability-reach.ts

@@ -0,0 +1,119 @@
+import { z } from 'zod';
+
+/**
+ * `CapabilityReach` — DECLARED answer to "how far outside the owner does
+ * invoking this capability reach?".
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * `AgentReachTier` (sandbox | as-owner | connected | full) is the CEILING a
+ * user picks for an agent. Turning that ceiling into a concrete capability set
+ * used to require a hand-maintained list in `authorization-api`
+ * (`CONNECTED_TIER_STARTER_CAPABILITIES`) — a central roster that every new
+ * integration capability had to be added to, in a different repo from the
+ * capability itself. That is the classic drift shape this platform has been
+ * removing everywhere else: the fact lives on the thing, not in a list about
+ * the thing.
+ *
+ * A capability now declares its own reach, and the tier resolves from the
+ * declarations. Adding an integration capability is a one-line declaration at
+ * the producer; no edit to `authorization-api`, and no way to forget one.
+ *
+ * PRECEDENCE — declared wins, derivation is the floor
+ * ---------------------------------------------------
+ * Absent ⇒ derived. A `connector`-kind invocation binding reaches an external
+ * system by construction, so it derives {@link CapabilityReach.Integration}
+ * with no declaration at all. Everything else derives
+ * {@link CapabilityReach.Owner}, which is the SAFE default: it grants nothing
+ * beyond what the owner already holds.
+ *
+ * A declaration may therefore only ever be needed to RAISE reach above the
+ * derived floor (an http-bound capability that nonetheless touches org-wide
+ * state, e.g. the knowledge base). It is deliberately NOT possible to declare
+ * a capability as lower-reach than its binding implies — that would let a
+ * producer opt its own connector out of the tier system.
+ */
+export enum CapabilityReach {
+  /**
+   * Confined to what the invoking subject already holds. The default, and the
+   * only reach an `as-owner` agent gets. Grants no additional authority.
+   */
+  Owner = 'owner',
+  /**
+   * Reaches a connected external system (SCM, tracker, mail, the governed
+   * public web) or org-wide shared state (the knowledge base). This is exactly
+   * the set the `connected` tier opens up.
+   */
+  Integration = 'integration',
+  /**
+   * Reaches the Xema control plane itself — installing biomes, minting
+   * credentials, altering grants. Only the `full` tier admits these, and the
+   * self-escalation guard applies independently.
+   */
+  Platform = 'platform',
+}
+
+export const CapabilityReachSchema = z.nativeEnum(CapabilityReach);
+
+/**
+ * The reach a capability has when it declares none. Kept as a named constant so
+ * the projector, the tier resolver and any future consumer cannot disagree
+ * about what "absent" means — and so the safe value is stated once, not
+ * repeated at each call site.
+ */
+export const DEFAULT_CAPABILITY_REACH = CapabilityReach.Owner;
+
+/**
+ * Which reaches a given {@link CapabilityReach} tier admits, most-restrictive
+ * first. Exported so the tier resolver reads a declared table rather than
+ * re-deriving the ordering, and so a new reach member is a compile error at
+ * every consumer rather than a silent omission.
+ */
+export const REACH_RANK: Readonly<Record<CapabilityReach, number>> = Object.freeze({
+  [CapabilityReach.Owner]: 0,
+  [CapabilityReach.Integration]: 1,
+  [CapabilityReach.Platform]: 2,
+});
+
+/** True when `candidate` is within `ceiling`. Total over the closed set. */
+export function reachWithin(candidate: CapabilityReach, ceiling: CapabilityReach): boolean {
+  return REACH_RANK[candidate] <= REACH_RANK[ceiling];
+}
+
+/**
+ * Combine a DERIVED reach with an optional DECLARED one, taking the wider of
+ * the two.
+ *
+ * This is a monotone join, NOT `declared ?? derived`, and the asymmetry is the
+ * whole safety property: a declaration may RAISE reach (the knowledge base is
+ * `Integration` despite riding an ordinary http route) but can never LOWER it.
+ * Without that, a producer could declare its own connector as `Owner` and quietly
+ * escape the tier system — the same bypass `joinAuthorityEffect` exists to
+ * prevent for the self-escalation guard.
+ *
+ * Absent declaration ⇒ the derived value, unchanged.
+ */
+export function joinReach(
+  derived: CapabilityReach,
+  declared?: CapabilityReach | undefined,
+): CapabilityReach {
+  if (declared === undefined) return derived;
+  return REACH_RANK[declared] > REACH_RANK[derived] ? declared : derived;
+}
+
+/**
+ * The reach a capability has by construction, before any declaration.
+ *
+ * A `connector`-kind invocation binding reaches a connected external system —
+ * that is what a connector IS — so it derives {@link CapabilityReach.Integration}
+ * with no author involvement. Every other binding kind derives the safe floor;
+ * raising it is the author's explicit act.
+ *
+ * Kept here, beside the enum, so the projector and the tier resolver cannot
+ * drift on what "derived" means.
+ */
+export function deriveReachFromInvocationKind(invocationKind: string): CapabilityReach {
+  return invocationKind === 'connector'
+    ? CapabilityReach.Integration
+    : DEFAULT_CAPABILITY_REACH;
+}

package/src/capability/lib/meta-tool.ts

@@ -3,23 +3,42 @@ import { z } from 'zod';
 import { CapabilityRefSchema, type CapabilityRef } from './capability-ref';
 
 /**
- * The agent-facing MCP surface collapses to exactly three
- * meta-tools. The set is CLOSED — no free-form strings — so we ship the
- * canonical names as a kernel enum that the router controller, the
- * mcp-gateway federation bridge, and any downstream client can all agree on.
+ * The agent-facing MCP surface collapses to a fixed, small set of meta-tools.
+ * The set is CLOSED — no free-form strings — so we ship the canonical names as
+ * a kernel enum that the router controller, the mcp-gateway federation bridge,
+ * and any downstream client can all agree on.
  *
  * The string values are the wire names emitted to OpenCode via the
  * mcp-gateway federation bridge (`resolveAsMetaTools()`). They are also the
  * suffix segments of the router HTTP routes:
  *
- *   POST /xema/capabilities/list      → MetaToolName.List
- *   POST /xema/capabilities/describe  → MetaToolName.Describe
- *   POST /xema/capabilities/invoke    → MetaToolName.Invoke
+ *   POST /xema/capabilities/search     → MetaToolName.Search
+ *   POST /xema/capabilities/describe   → MetaToolName.Describe
+ *   POST /xema/capabilities/invoke     → MetaToolName.Invoke
+ *   POST /xema/capabilities/plan       → MetaToolName.Plan
+ *   POST /xema/capabilities/preflight  → MetaToolName.Preflight
+ *   POST /xema/capabilities/explain    → MetaToolName.Explain
+ *
+ * `search` REPLACED the former `list` (gap X11). `list` returned the WHOLE
+ * catalogue and probed the PDP once per record, sequentially — O(catalogue)
+ * round-trips that collapse the moment capability projection takes the
+ * registry past a few hundred rows. `search` is anchor → traverse → rank over
+ * the derived capability graph and is O(neighbourhood). There is deliberately
+ * NO `list` alias: an unbounded catalogue read is not a supported operation.
+ *
+ * `plan` / `preflight` / `explain` are the graph's other three answers. They
+ * are thin, subject-scoped projections of `capability-registry-api`'s
+ * `/capability-graph/*` surface, which OWNS their wire shape — the kernel
+ * therefore names them and stops there rather than forking a second copy of
+ * those DTOs (see `docs`/`.claude/plans/canopy-universal-agent.md` §5.4).
  */
 export enum MetaToolName {
-  List = 'xema.capabilities.list',
+  Search = 'xema.capabilities.search',
   Describe = 'xema.capabilities.describe',
   Invoke = 'xema.capabilities.invoke',
+  Plan = 'xema.capabilities.plan',
+  Preflight = 'xema.capabilities.preflight',
+  Explain = 'xema.capabilities.explain',
 }
 
 export const MetaToolNameSchema = z.nativeEnum(MetaToolName);
@@ -38,16 +57,19 @@ export const META_TOOL_AUDIT_TOPIC = 'capability.invoked.v1';
  * truth.
  */
 export const META_TOOL_ROUTE_SUFFIX: Readonly<Record<MetaToolName, string>> = {
-  [MetaToolName.List]: 'list',
+  [MetaToolName.Search]: 'search',
   [MetaToolName.Describe]: 'describe',
   [MetaToolName.Invoke]: 'invoke',
+  [MetaToolName.Plan]: 'plan',
+  [MetaToolName.Preflight]: 'preflight',
+  [MetaToolName.Explain]: 'explain',
 };
 
 // ─── Shared sub-types ───────────────────────────────────────────────────────
 
 /**
  * Reference to the biome that ships a capability — surfaced on every
- * `CapabilityListEntry` + `CapabilityDescribeEntry` so the agent can show
+ * `CapabilitySearchEntry` + `CapabilityDescribeEntry` so the agent can show
  * provenance ("this tool came from biome X@1.4.0") to the human in the loop.
  */
 export interface MetaToolBiomeRef {
@@ -60,66 +82,177 @@ export const MetaToolBiomeRefSchema: z.ZodType<MetaToolBiomeRef> = z.object({
   version: z.string().min(1),
 });
 
-// ─── list ───────────────────────────────────────────────────────────────────
+/**
+ * Policy decision kinds surfaced by meta-tool projections. Mirrors
+ * `@xemahq/policy-contracts/PolicyDecisionKind` value-for-value; we redefine
+ * it here so capability-contracts stays a leaf with no upward kernel deps.
+ */
+export enum MetaToolPolicyDecision {
+  Allow = 'allow',
+  Deny = 'deny',
+  NeedsApproval = 'needs_approval',
+}
+
+export const MetaToolPolicyDecisionSchema = z.nativeEnum(MetaToolPolicyDecision);
+
+// ─── search ─────────────────────────────────────────────────────────────────
+
+/** Default / hard upper bound on one `search` page. */
+export const META_TOOL_SEARCH_DEFAULT_LIMIT = 20;
+export const META_TOOL_SEARCH_MAX_LIMIT = 50;
+
+/**
+ * How a capability reaches the anchor resource type of a search.
+ *
+ * Value-identical to `capability-registry-api`'s `NeighbourhoodRelation`
+ * (the graph owns the edges; this is the kernel vocabulary every consumer
+ * agrees on). {@link parseCapabilityRelation} fail-fasts if the two ever
+ * drift, so the mirror can never rot silently.
+ */
+export enum CapabilityRelation {
+  /** The capability's ref grammar declares the anchor as its subject. */
+  ActsOn = 'acts_on',
+  /** The capability takes a reference to the anchor type as input. */
+  Consumes = 'consumes',
+}
+
+/** Fail-fast parse of a graph-sourced relation string. Never coerces. */
+export function parseCapabilityRelation(raw: string): CapabilityRelation {
+  const values = Object.values(CapabilityRelation) as string[];
+  if (!values.includes(raw)) {
+    throw new Error(
+      `Unknown capability relation "${raw}". Expected one of ${values.join(', ')}.`,
+    );
+  }
+  return raw as CapabilityRelation;
+}
+
+/**
+ * Whether invoking a capability changes state.
+ *
+ * STRUCTURALLY derived from the capability's persisted
+ * `CapabilityInvocationBinding` — never guessed from prose (`sideEffects` is
+ * free text) and never guessed from the ref verb (an open vocabulary). An
+ * `http` binding states its method, which is decisive; every other binding
+ * kind states nothing about mutation, so it is reported as
+ * {@link CapabilityMutationClass.Undetermined} rather than assumed either way.
+ */
+export enum CapabilityMutationClass {
+  Read = 'read',
+  Mutating = 'mutating',
+  Undetermined = 'undetermined',
+}
+
+/** Where a search's anchor resource type came from. */
+export enum CapabilitySearchAnchorSource {
+  /** The caller named `resourceType` explicitly. */
+  Explicit = 'explicit',
+  /** A token of `query` matched a resource type known to the graph. */
+  DerivedFromQuery = 'derived-from-query',
+  /** No anchor — the search fell back to the bounded catalogue scan. */
+  None = 'none',
+}
 
 /**
- * Request envelope for `xema.capabilities.list`. The router carries an opaque
- * `executionContext` payload (validated server-side against
+ * Request envelope for `xema.capabilities.search`. The router carries an
+ * opaque `executionContext` payload (validated server-side against
  * `@xemahq/execution-context-contracts`) so the meta-tool surface and the
- * grant-cache key on the same shape.
+ * grant-cache key share the same shape.
  */
-export interface CapabilityListRequest {
+export interface CapabilitySearchRequest {
   readonly executionContext: Record<string, unknown>;
-  readonly includeDenied?: boolean | undefined;
+  readonly query?: string | undefined;
+  readonly domain?: string | undefined;
+  readonly resourceType?: string | undefined;
+  readonly mutating?: boolean | undefined;
+  readonly limit?: number | undefined;
+  readonly cursor?: string | undefined;
 }
 
-export const CapabilityListRequestSchema: z.ZodType<CapabilityListRequest> =
+export const CapabilitySearchRequestSchema: z.ZodType<CapabilitySearchRequest> =
   z.object({
     executionContext: z.record(z.string(), z.unknown()),
-    includeDenied: z.boolean().optional(),
+    query: z.string().optional(),
+    domain: z.string().optional(),
+    resourceType: z.string().optional(),
+    mutating: z.boolean().optional(),
+    limit: z
+      .number()
+      .int()
+      .min(1)
+      .max(META_TOOL_SEARCH_MAX_LIMIT)
+      .optional(),
+    cursor: z.string().optional(),
   });
 
 /**
- * Policy decision kinds surfaced on each `CapabilityListEntry`. Mirrors
- * `@xemahq/policy-contracts/PolicyDecisionKind` value-for-value; we redefine
- * it here so capability-contracts stays a leaf with no upward kernel deps.
+ * One search hit. Every entry returned is one the subject is AUTHORIZED to
+ * invoke — there is no `policyDecision` field and no `includeDenied` switch,
+ * because offering an action the caller cannot perform is worse than offering
+ * none (the agent will attempt it).
  */
-export enum MetaToolPolicyDecision {
-  Allow = 'allow',
-  Deny = 'deny',
-  NeedsApproval = 'needs_approval',
-}
-
-export const MetaToolPolicyDecisionSchema = z.nativeEnum(MetaToolPolicyDecision);
-
-export interface CapabilityListEntry {
+export interface CapabilitySearchEntry {
   readonly ref: CapabilityRef;
   readonly biome: MetaToolBiomeRef;
   readonly title: string;
   readonly summary: string;
   readonly riskTier: string;
-  readonly policyDecision: MetaToolPolicyDecision;
-  readonly denialReason?: string | undefined;
+  readonly requiresApproval: boolean;
+  readonly mutation: CapabilityMutationClass;
+  /** Present only on an anchored search. */
+  readonly relation?: CapabilityRelation | undefined;
+  /** `child_of` hops from the anchor. Present only on an anchored search. */
+  readonly distance?: number | undefined;
+  /** Resource type this capability touches. Present only on an anchored search. */
+  readonly resourceType?: string | undefined;
 }
 
-export const CapabilityListEntrySchema: z.ZodType<CapabilityListEntry> =
+export const CapabilitySearchEntrySchema: z.ZodType<CapabilitySearchEntry> =
   z.object({
     ref: CapabilityRefSchema,
     biome: MetaToolBiomeRefSchema,
     title: z.string().min(1),
     summary: z.string(),
     riskTier: z.string().min(1),
-    policyDecision: MetaToolPolicyDecisionSchema,
-    denialReason: z.string().optional(),
+    requiresApproval: z.boolean(),
+    mutation: z.nativeEnum(CapabilityMutationClass),
+    relation: z.nativeEnum(CapabilityRelation).optional(),
+    distance: z.number().int().min(0).optional(),
+    resourceType: z.string().optional(),
+  });
+
+export interface CapabilitySearchAnchor {
+  readonly resourceType: string | null;
+  readonly source: CapabilitySearchAnchorSource;
+}
+
+export const CapabilitySearchAnchorSchema: z.ZodType<CapabilitySearchAnchor> =
+  z.object({
+    resourceType: z.string().nullable(),
+    source: z.nativeEnum(CapabilitySearchAnchorSource),
   });
 
-export interface CapabilityListResponse {
-  readonly capabilities: readonly CapabilityListEntry[];
+export interface CapabilitySearchResponse {
+  readonly capabilities: readonly CapabilitySearchEntry[];
+  readonly anchor: CapabilitySearchAnchor;
+  /**
+   * Candidates considered before the authority filter. Compare with
+   * `capabilities.length` to see how much authority removed.
+   */
+  readonly consideredCount: number;
+  /** Opaque continuation token. Absent ⇒ this is the last page. */
+  readonly nextCursor?: string | undefined;
+  /** Graph build generation that answered an anchored search. */
+  readonly generation?: number | undefined;
 }
 
-export const CapabilityListResponseSchema: z.ZodType<CapabilityListResponse> =
+export const CapabilitySearchResponseSchema: z.ZodType<CapabilitySearchResponse> =
   z.object({
-    capabilities: z.array(CapabilityListEntrySchema).readonly(),
+    capabilities: z.array(CapabilitySearchEntrySchema).readonly(),
+    anchor: CapabilitySearchAnchorSchema,
+    consideredCount: z.number().int().min(0),
+    nextCursor: z.string().optional(),
+    generation: z.number().int().min(0).optional(),
   });
 
 // ─── describe ───────────────────────────────────────────────────────────────

package/src/capability-projection/index.ts

@@ -0,0 +1,3 @@
+export * from './lib/capability-invocation-binding';
+export * from './lib/capability-sync-manifest';
+export * from './lib/projected-capability';

package/src/capability-projection/lib/capability-invocation-binding.ts

@@ -0,0 +1,223 @@
+import { z } from 'zod';
+
+import {
+  ConnectorAdapterKind,
+  ConnectorAdapterKindSchema,
+} from '../../connector';
+
+/**
+ * ─────────────────────────────────────────────────────────────────────────
+ * `CapabilityInvocationBinding` — HOW a projected capability is actually
+ * invoked, carried as DATA on the capability itself.
+ *
+ * This is the contract that lets the capability router resolve a target by
+ * LOOKUP instead of a hand-maintained `switch` over domains: every producer
+ * that projects a capability also declares the binding that executes it.
+ *
+ * `kind` is a CLOSED set ({@link CapabilityInvocationKind}). Adding a member
+ * is a kernel change AND requires a matching dispatch branch in whatever
+ * executes bindings — do not add a member that has no executor.
+ * ─────────────────────────────────────────────────────────────────────────
+ */
+export enum CapabilityInvocationKind {
+  /** A direct HTTP call to a first-party service resolved from the registry. */
+  Http = 'http',
+  /** A connector operation executed by the connector backend. */
+  Connector = 'connector',
+  /** A workflow dispatched by slug. */
+  Workflow = 'workflow',
+  /** A tool call proxied to a registered MCP server. */
+  Mcp = 'mcp',
+  /** An in-process handler resolved by key inside the owning service. */
+  Inline = 'inline',
+}
+
+export const CapabilityInvocationKindSchema = z.nativeEnum(
+  CapabilityInvocationKind,
+);
+
+/** HTTP verbs a projected capability may bind to. Closed set. */
+export enum CapabilityHttpMethod {
+  Get = 'GET',
+  Post = 'POST',
+  Put = 'PUT',
+  Patch = 'PATCH',
+  Delete = 'DELETE',
+}
+
+export const CapabilityHttpMethodSchema = z.nativeEnum(CapabilityHttpMethod);
+
+/** Where an HTTP parameter is carried on the wire. Closed set. */
+export enum CapabilityHttpParameterIn {
+  Path = 'path',
+  Query = 'query',
+  Header = 'header',
+}
+
+export const CapabilityHttpParameterInSchema = z.nativeEnum(
+  CapabilityHttpParameterIn,
+);
+
+/**
+ * RFC-6901 JSON Pointer into the capability INPUT document. Deliberately
+ * strict — a pointer is the only supported way to address input data, so a
+ * binding can never carry a free-form expression that some executor would
+ * have to interpret heuristically.
+ */
+const JSON_POINTER_REGEX = /^(?:\/[^/]+)+$/;
+
+export const CapabilityInputPointerSchema = z.string().regex(
+  JSON_POINTER_REGEX,
+  {
+    message:
+      'inputPointer must be a non-empty RFC-6901 JSON Pointer into the capability input (e.g. `/projectId`).',
+  },
+);
+
+/** One HTTP parameter of an {@link HttpCapabilityInvocation}. */
+export interface CapabilityHttpParameterBinding {
+  /** Wire name of the parameter (path placeholder / query key / header name). */
+  readonly name: string;
+  readonly in: CapabilityHttpParameterIn;
+  /** JSON Pointer into the capability input that supplies the value. */
+  readonly inputPointer: string;
+  /** Whether the executor must refuse the call when the pointer resolves to nothing. */
+  readonly required: boolean;
+}
+
+export const CapabilityHttpParameterBindingSchema: z.ZodType<CapabilityHttpParameterBinding> =
+  z.object({
+    name: z.string().min(1).max(200),
+    in: CapabilityHttpParameterInSchema,
+    inputPointer: CapabilityInputPointerSchema,
+    required: z.boolean(),
+  }) as unknown as z.ZodType<CapabilityHttpParameterBinding>;
+
+/** How the request body of an {@link HttpCapabilityInvocation} is built. Closed set. */
+export enum CapabilityHttpBodyMode {
+  /** The whole capability input document IS the body. */
+  WholeInput = 'whole-input',
+  /** A sub-document of the capability input, addressed by `inputPointer`, is the body. */
+  InputPointer = 'input-pointer',
+}
+
+export const CapabilityHttpBodyModeSchema = z.nativeEnum(
+  CapabilityHttpBodyMode,
+);
+
+export interface CapabilityHttpBodyBinding {
+  readonly mode: CapabilityHttpBodyMode;
+  /** REQUIRED iff `mode` is `input-pointer`; MUST be absent otherwise. */
+  readonly inputPointer?: string;
+}
+
+export const CapabilityHttpBodyBindingSchema: z.ZodType<CapabilityHttpBodyBinding> =
+  z
+    .object({
+      mode: CapabilityHttpBodyModeSchema,
+      inputPointer: CapabilityInputPointerSchema.optional(),
+    })
+    .superRefine((value, ctx) => {
+      const needsPointer = value.mode === CapabilityHttpBodyMode.InputPointer;
+      if (needsPointer && value.inputPointer === undefined) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['inputPointer'],
+          message: 'inputPointer is REQUIRED when mode is `input-pointer`.',
+        });
+      }
+      if (!needsPointer && value.inputPointer !== undefined) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['inputPointer'],
+          message: 'inputPointer is only allowed when mode is `input-pointer`.',
+        });
+      }
+    }) as unknown as z.ZodType<CapabilityHttpBodyBinding>;
+
+/** Service name as registered in the kernel service registry (kebab-case). */
+const SERVICE_NAME_REGEX = /^[a-z][a-z0-9-]*$/;
+
+export interface HttpCapabilityInvocation {
+  readonly kind: CapabilityInvocationKind.Http;
+  /** Registry name of the target service — resolved, never a hardcoded host. */
+  readonly serviceName: string;
+  readonly method: CapabilityHttpMethod;
+  /** Route template with `:param` / `{param}` placeholders, always absolute. */
+  readonly path: string;
+  readonly parameters: readonly CapabilityHttpParameterBinding[];
+  /** Absent for verbs that carry no body. */
+  readonly body?: CapabilityHttpBodyBinding;
+}
+
+export interface ConnectorCapabilityInvocation {
+  readonly kind: CapabilityInvocationKind.Connector;
+  /** Connector descriptor key (e.g. `ACME_CRM`). */
+  readonly connectorKey: string;
+  /** Operation key within the connector (its capability verb). */
+  readonly operationKey: string;
+  /**
+   * The operation's OWN backend discriminator. It is part of the BINDING (not
+   * of the connector) because two operations of the same connector may be
+   * served by different backends, and it is what the capability router
+   * dispatches on today.
+   */
+  readonly adapterKind: ConnectorAdapterKind;
+}
+
+export interface WorkflowCapabilityInvocation {
+  readonly kind: CapabilityInvocationKind.Workflow;
+  readonly workflowSlug: string;
+}
+
+export interface McpCapabilityInvocation {
+  readonly kind: CapabilityInvocationKind.Mcp;
+  readonly serverId: string;
+  readonly toolName: string;
+}
+
+export interface InlineCapabilityInvocation {
+  readonly kind: CapabilityInvocationKind.Inline;
+  /** Key the owning service resolves to an in-process handler. */
+  readonly handlerKey: string;
+}
+
+export type CapabilityInvocationBinding =
+  | HttpCapabilityInvocation
+  | ConnectorCapabilityInvocation
+  | WorkflowCapabilityInvocation
+  | McpCapabilityInvocation
+  | InlineCapabilityInvocation;
+
+export const CapabilityInvocationBindingSchema: z.ZodType<CapabilityInvocationBinding> =
+  z.discriminatedUnion('kind', [
+    z.object({
+      kind: z.literal(CapabilityInvocationKind.Http),
+      serviceName: z.string().regex(SERVICE_NAME_REGEX, {
+        message: 'serviceName must be a kebab-case service-registry name.',
+      }),
+      method: CapabilityHttpMethodSchema,
+      path: z.string().startsWith('/').min(1).max(2000),
+      parameters: z.array(CapabilityHttpParameterBindingSchema),
+      body: CapabilityHttpBodyBindingSchema.optional(),
+    }),
+    z.object({
+      kind: z.literal(CapabilityInvocationKind.Connector),
+      connectorKey: z.string().min(1).max(200),
+      operationKey: z.string().min(1).max(200),
+      adapterKind: ConnectorAdapterKindSchema,
+    }),
+    z.object({
+      kind: z.literal(CapabilityInvocationKind.Workflow),
+      workflowSlug: z.string().min(1).max(200),
+    }),
+    z.object({
+      kind: z.literal(CapabilityInvocationKind.Mcp),
+      serverId: z.string().min(1).max(200),
+      toolName: z.string().min(1).max(200),
+    }),
+    z.object({
+      kind: z.literal(CapabilityInvocationKind.Inline),
+      handlerKey: z.string().min(1).max(200),
+    }),
+  ]) as unknown as z.ZodType<CapabilityInvocationBinding>;

package/src/capability-projection/lib/capability-sync-manifest.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+
+import {
+  CapabilityContributionManifestSchema,
+  type CapabilityContributionManifest,
+} from '../../capability';
+import {
+  CapabilityInvocationBindingSchema,
+  type CapabilityInvocationBinding,
+} from './capability-invocation-binding';
+
+/**
+ * ─────────────────────────────────────────────────────────────────────────
+ * `CapabilitySyncManifest` — what an AUTHOR declares when publishing a
+ * capability, on EVERY publish path.
+ *
+ * It is the kernel `CapabilityContributionManifest` (what the capability IS)
+ * plus an optional {@link CapabilityInvocationBinding} (HOW it is invoked).
+ * The two are split across subpaths on purpose — `CapabilityInvocationBinding`
+ * depends on the `connector` subpath, which in turn depends on `capability`, so
+ * putting `invocation` directly on the contribution manifest would close a
+ * subpath cycle. This composition lives HERE, next to `ProjectedCapability`,
+ * which composes the same two halves for the DERIVED path.
+ *
+ * One shape, every producer:
+ *   - a `*.capability.contribution.json` file / an `xema.contributions.inline[]`
+ *     entry, parsed by `biome-host-api`'s `CapabilityParser`;
+ *   - the `@XemaCapability` decorator's boot-time runtime sync;
+ *   - `capability-registry-api`'s own contribution-sync handler.
+ * All three end on `POST /capabilities/sync` with this exact payload.
+ *
+ * `invocation` is OPTIONAL on the contract because a capability may instead be
+ * backed by an org `CapabilityProviderBinding` or by a live runner. It is NOT a
+ * soft default: a ref with none of the three FAILS FAST at the capability-router
+ * (`CapabilityInvocationBindingMissingError`) rather than degrading.
+ *
+ * NOTE the mechanical reason this is an INTERSECTION and not a widened object:
+ * `CapabilityContributionManifestSchema` is a `z.object` and therefore STRIPS
+ * unknown keys, so parsing an envelope through it alone would silently drop the
+ * binding. Intersecting merges both parsed outputs, so the binding survives —
+ * validated by the same kernel schema every other path uses.
+ * ─────────────────────────────────────────────────────────────────────────
+ */
+export interface CapabilitySyncManifest extends CapabilityContributionManifest {
+  readonly invocation?: CapabilityInvocationBinding;
+}
+
+export const CapabilitySyncManifestSchema: z.ZodType<CapabilitySyncManifest> =
+  z.intersection(
+    CapabilityContributionManifestSchema,
+    z.object({ invocation: CapabilityInvocationBindingSchema.optional() }),
+  ) as unknown as z.ZodType<CapabilitySyncManifest>;