@xemahq/kernel-contracts 0.22.2 → 0.23.0

package/src/capability/lib/shell-command-descriptor.ts

@@ -5,7 +5,7 @@ import { CapabilityRefSchema, type CapabilityRef } from './capability-ref';
  * Stub for a JSON Schema reference. Modelled as `{ $ref: string }` so
  * downstream services (notably `xema-shell-api`) can plug in their richer
  * `JsonSchemaRef` shape without the kernel having to know about JSON Schema
- * machinery. Phase-1A intentional scope limit.
+ * machinery. An intentional scope limit.
  */
 export interface JsonSchemaRefStub {
   $ref: string;
@@ -16,7 +16,7 @@ export const JsonSchemaRefStubSchema = z.object({
 }) as z.ZodType<JsonSchemaRefStub>;
 
 /**
- * `ShellCommandDescriptor` — plan §31.5. Single source of truth for human
+ * `ShellCommandDescriptor` — single source of truth for human
  * help (`xema help <cmd>`), agent help (the `xema-shell:run@1` self-describe
  * surface), and the host UI's command palette.
  *
@@ -28,7 +28,7 @@ export const JsonSchemaRefStubSchema = z.object({
  * depend on `@xemahq/xema-object-contracts`, which would form a kernel cycle
  * if `xema-object-contracts` ever needed a `CapabilityRef`.
  *
- * `safeForAgents` is enforced by `xema-capability-router` per §31.7 — the
+ * `safeForAgents` is enforced by `xema-capability-router` — the
  * descriptor is the source of truth; the gateway never relaxes it.
  */
 export interface ShellCommandDescriptor {

package/src/connector/index.ts

@@ -2,6 +2,8 @@ export * from './lib/adapter-kind';
 export * from './lib/capability';
 export * from './lib/credential-kind';
 export * from './lib/onboarding-manifest';
+export * from './lib/provider-descriptor';
+export * from './lib/connector-descriptor';
 export * from './lib/envelope-schema';
 export * from './lib/filter-expr';
 export * from './lib/filter-expr-schema';

package/src/connector/lib/adapter-kind.ts

@@ -9,7 +9,7 @@
  *
  * The set is *built-in-closed but biome-extensible*: biomes may
  * contribute additional kinds via the future `AdapterContribution`
- * registry (Phase 7). The closed enum below names only the kinds the
+ * registry. The closed enum below names only the kinds the
  * platform ships out-of-the-box. Anything outside this list MUST be
  * either a built-in plus a biome contribution, or routed through an
  * opaque `AdapterKindRef` string captured below.

package/src/connector/lib/capability-refs.ts

@@ -6,7 +6,7 @@
 // contracts`); they version like syscalls (`@1`, `@2`, ...) and the runtime
 // MUST refuse to dispatch a major version it has not registered.
 //
-// Source of truth: plan §17.2-B item 2. This file is the registry seed; the
+// This file is the registry seed; the
 // `connector-gateway-api` capability dispatcher MAY consume it directly for
 // `name`-side validation.
 // ═══════════════════════════════════════════════════════════════════════════

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

@@ -0,0 +1,67 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────
+ * Connector descriptor — a capability surface authenticated by ONE provider
+ *
+ * A **Connector** is what a user actually connects: Gmail, Google Drive,
+ * generic IMAP, generic SMTP, a GitHub SCM connector. Every connector names
+ * the **Provider** it authenticates against (`providerKey`) and the incremental
+ * OAuth `scopes` it needs from that provider. The catalog groups connectors by
+ * provider so ONE app credential (per `ProviderDescriptor`) backs many
+ * connectors.
+ *
+ * This descriptor is the connector-registry face of an
+ * `IntegrationProviderModule`: the module carries the executable
+ * webhook/action/resource handlers; this descriptor carries the
+ * *catalog + connect* metadata the framework needs
+ * to render the provider-grouped catalog, drive consent with the right scopes,
+ * and resolve the right per-connection credential kind.
+ * ─────────────────────────────────────────────────────────────────────────
+ */
+
+import type { AdapterKindRef } from './adapter-kind';
+import type { CredentialKind } from './credential-kind';
+
+/**
+ * A connector in the catalog. `connectorKey` aligns with the persisted
+ * `ConnectorKind` wire value (e.g. `GMAIL`, `IMAP_GENERIC`, `SMTP_GENERIC`)
+ * but is typed as a string here to keep the kernel `connector` contract
+ * package free of the persisted `ConnectorKind` enum (which lives in
+ * platform-common's integration-webhooks); the connector-gateway maps the two.
+ */
+export interface ConnectorDescriptor {
+  /** Stable connector key — aligns with the persisted `ConnectorKind`. */
+  readonly connectorKey: string;
+  /** Human-readable name — `Gmail`, `Generic IMAP`. */
+  readonly displayName: string;
+  /** One-sentence description shown on the connector row. */
+  readonly description: string;
+  /** Lucide-react icon name; may differ from the provider's icon. */
+  readonly iconName: string;
+
+  /** The provider (authenticating authority) this connector belongs to. */
+  readonly providerKey: string;
+
+  /**
+   * Incremental OAuth scopes this connector requests from its provider. Empty
+   * for connectors whose provider `appAuthKind` is `None` (IMAP/SMTP). When a
+   * second connector of the same OAuth provider is connected, the consent
+   * driver requests the UNION of already-granted + these scopes (incremental
+   * consent) so one app credential accrues capability without re-consent for
+   * scopes already held.
+   */
+  readonly scopes: readonly string[];
+
+  /**
+   * How an individual connection to THIS connector authenticates at runtime
+   * (the per-connection wallet/token). `oauth_user` for OAuth connectors,
+   * `imap_auth` / `smtp_auth` for the mail wallets, `pat` / `api_key`, …
+   */
+  readonly connectionCredentialKind: CredentialKind;
+
+  /**
+   * The adapter category this connector plugs into (`mail`, `scm`, …). Drives
+   * where normalized inbound envelopes are forwarded and which project-binding
+   * surface the connector appears under.
+   */
+  readonly adapterKind: AdapterKindRef;
+}

package/src/connector/lib/credential-kind.ts

@@ -1,11 +1,10 @@
 /**
  * Closed enum of credential strategies the platform knows how to mint,
- * cache, refresh and revoke. Biomes contributing new providers (Phase
- * 7) MUST declare one of these — they never ship custom mint code.
+ * cache, refresh and revoke. Biomes contributing new providers MUST
+ * declare one of these — they never ship custom mint code.
  *
  * Adding a kind here is a one-line schema change plus a matching
- * strategy implementation under
- * `apps/integration-adapters-api/src/credentials/strategies/<kind>/`.
+ * strategy implementation for that kind.
  */
 export enum CredentialKind {
   /** GitHub App / GitLab App style installation token (per-installation, 1h). */

package/src/connector/lib/envelope-schema.ts

@@ -11,7 +11,7 @@ import { BuiltInAdapterKind, type AdapterKindRef } from './adapter-kind';
  * evaluating to `false` at dispatch.
  *
  * The map is keyed by `(adapterKind, entityKind)`. When a webhook
- * filter declares its target `entityKind` (Phase 7 manifest field),
+ * filter declares its target `entityKind` (a manifest field),
  * the cross-validator narrows path checking to that entry. Filters
  * that omit `entityKind` fall back to the `UNION_ENTITY_KIND` entry,
  * which collects every path across the adapter's entity kinds — over-
@@ -167,7 +167,7 @@ registerEnvelopeSchema(BuiltInAdapterKind.Documentation, {
 
 /**
  * Register the per-entityKind permitted `$envelope.*` paths for a
- * biome-contributed AdapterKind (Phase 7). Built-in kinds are pre-
+ * biome-contributed AdapterKind. Built-in kinds are pre-
  * registered above. Re-registering an existing kind REPLACES its
  * entry set — `integration-adapters-api`'s registry is the authority,
  * so biome upgrades surface here.

package/src/connector/lib/filter-expr-validate.ts

@@ -56,7 +56,7 @@ export interface FilterExprPathIssue {
  * Statically validate that every `$envelope.*` path the predicate
  * references is permitted by the canonical envelope schema for
  * `(adapterKind, entityKind)`. `$selector` paths are NOT validated
- * here — selectors are opaque-by-design (Phase 3 lock-in): their
+ * here — selectors are opaque-by-design: their
  * shape is governed by the biome's install JSON Schema, not by a
  * kernel-level path map.
  *

package/src/connector/lib/filter-expr.ts

@@ -184,6 +184,8 @@ function scalarEqual(a: unknown, b: unknown): boolean {
  */
 const REGEX_CACHE = new Map<string, RegExp>();
 const REGEX_MAX_LEN = 256;
+/** Cap on distinct compiled patterns retained, to bound memory in a long-lived process. */
+const REGEX_CACHE_MAX = 1_000;
 
 function compileRegex(pattern: string): RegExp {
   const cached = REGEX_CACHE.get(pattern);
@@ -198,6 +200,12 @@ function compileRegex(pattern: string): RegExp {
   }
   try {
     const re = new RegExp(pattern);
+    // Evict the oldest entry (Map preserves insertion order) once the cache is
+    // full, so an unbounded stream of distinct patterns cannot grow it forever.
+    if (REGEX_CACHE.size >= REGEX_CACHE_MAX) {
+      const oldest = REGEX_CACHE.keys().next().value;
+      if (oldest !== undefined) REGEX_CACHE.delete(oldest);
+    }
     REGEX_CACHE.set(pattern, re);
     return re;
   } catch (cause) {

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

@@ -0,0 +1,181 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────
+ * Provider descriptor — the authenticating authority ("app") behind N connectors
+ *
+ * A **Provider** is the identity/authority a set of connectors authenticates
+ * against — e.g. `google`, `microsoft`, `github`, `slack`, `smtp`, `imap`.
+ * ONE provider owns ONE **app credential** (a Google Cloud OAuth client, a
+ * GitHub App private key, …) and fans out to MANY **connectors** (Gmail,
+ * Google Drive, Google Calendar …), each of which reuses that single app
+ * credential with its own incremental scopes.
+ *
+ * This is the "Google is a world" fix: the catalog lists connectors grouped
+ * under one provider card; the app credential is provided once (by a platform
+ * admin, or overridden per-org as BYO) and every connector under the provider
+ * reuses it. Adding a new Google service later is a new *connector* with new
+ * scopes — never a new credential and never a framework change.
+ *
+ * The descriptor is a **runtime contract** describing how a provider's app
+ * credential is obtained and where it lives. Actual secret VALUES are never
+ * carried here — only the SCHEMA of what an admin must supply
+ * (`appCredentialSchema`) and non-secret OAuth endpoint metadata. Secrets are
+ * held by the credential broker + custody, referenced by env-var name or
+ * custody ref, never inlined.
+ * ─────────────────────────────────────────────────────────────────────────
+ */
+
+import type { CredentialFieldSpec } from './onboarding-manifest';
+
+/**
+ * How a provider's APP-level credential authenticates. This is distinct from
+ * a *connector's* per-connection `CredentialKind` (how an individual user/
+ * mailbox connection authenticates) — it describes the shared "app" that the
+ * platform/org registers once.
+ */
+export enum ProviderAppAuthKind {
+  /**
+   * 3-legged OAuth: the app is a registered OAuth client (clientId/secret).
+   * Connecting a connector runs an authorization-code consent redirect using
+   * the app credential + the connector's scopes. e.g. Google, Microsoft,
+   * Slack.
+   */
+  OAuth2 = 'oauth2',
+  /**
+   * App-installation flow (GitHub App / GitLab App / Atlassian Connect): the
+   * app authenticates via an app id + private key and the user installs it
+   * onto their account/org. e.g. GitHub.
+   */
+  AppInstall = 'app_install',
+  /**
+   * No shared app credential at all — every connection carries its own
+   * complete secret (a mailbox host+user+password, a raw API key). The
+   * connector is connectable with NO platform/org setup. e.g. generic SMTP,
+   * generic IMAP.
+   */
+  None = 'none',
+}
+
+/**
+ * Who shipped a provider. Determines WHICH admin fulfils its app-credential
+ * requirement and at which scope the requirement is registered.
+ *
+ *  - `kernel`   — a first-party provider baked into the platform.
+ *  - `platform` — shipped by a platform (Layer-2) service/biome installed
+ *                 platform-wide; platform admin fulfils it.
+ *  - `biome`    — introduced by a biome. When that biome is installed at ORG
+ *                 scope, the requirement is org-scoped (the org admin BYO-fills
+ *                 it) because the platform never shipped the provider.
+ */
+export enum ProviderOrigin {
+  Kernel = 'kernel',
+  Platform = 'platform',
+  Biome = 'biome',
+}
+
+/**
+ * The two scopes at which a provider's APP credential can be provisioned.
+ * Deliberately a SEPARATE, minimal enum from the 5-tier ownership
+ * `ScopeSource` and from the credential-broker's per-connection
+ * `CredentialScopeTier` — app-credential provisioning is a strict 2-tier
+ * concern: a platform-wide default that an org may override.
+ *
+ * Resolution precedence (narrowest wins):
+ *
+ *   Org (BYO)  >  Platform (default)  >  [legacy env-var fallback]  >  unset
+ *
+ * An unset REQUIRED app credential is surfaced to the correct admin and the
+ * connector reports "needs setup" — it never silently falls through to an
+ * unauthenticated request.
+ */
+export enum ProviderCredentialScope {
+  Platform = 'platform',
+  Org = 'org',
+}
+
+/** Precedence order for app-credential resolution — index 0 wins. */
+export const PROVIDER_CREDENTIAL_SCOPE_ORDER: readonly ProviderCredentialScope[] =
+  [ProviderCredentialScope.Org, ProviderCredentialScope.Platform];
+
+/**
+ * Non-secret OAuth endpoint metadata for a `ProviderAppAuthKind.OAuth2`
+ * provider. Client id/secret are NOT here — they are the app credential,
+ * resolved from a provision (or the legacy env fallback) at consent time.
+ */
+export interface ProviderOAuthEndpoints {
+  /** Authorization-code consent endpoint (where the user is redirected). */
+  readonly authorizationUrl: string;
+  /** Token-exchange endpoint (code→token, refresh-token rotation). */
+  readonly tokenUrl: string;
+  /**
+   * Extra authorize-request params a provider needs to actually mint a
+   * refresh token / do incremental consent. Non-secret. e.g. Google needs
+   * `{ access_type: 'offline', include_granted_scopes: 'true', prompt:
+   * 'consent' }`. Kept explicit rather than hardcoded in the driver so a new
+   * OAuth provider is pure data.
+   */
+  readonly extraAuthorizeParams?: Readonly<Record<string, string>>;
+  /**
+   * Legacy env-var NAMES the OAuth driver falls back to for the app
+   * client id / secret when no provision exists yet (bootstrap before the
+   * platform-admin UI is used). Never the secret itself. Optional — a
+   * provider with no env fallback simply reports "needs setup" until an
+   * admin provisions it.
+   */
+  readonly clientIdEnvVar?: string;
+  readonly clientSecretEnvVar?: string;
+}
+
+/**
+ * A first-class Provider (authenticating authority). Registered in the
+ * provider registry alongside — but distinct from — the connectors that
+ * reference it via `Connector.providerKey`.
+ */
+export interface ProviderDescriptor {
+  /** Stable lowercase slug — `google`, `microsoft`, `github`, `smtp`. */
+  readonly providerKey: string;
+  /** Human-readable name — `Google`, `Microsoft`, `Generic SMTP`. */
+  readonly displayName: string;
+  /** One-sentence description shown on the provider card. */
+  readonly description: string;
+  /** Lucide-react icon name; frontend maps to a component. */
+  readonly iconName: string;
+  /** Catalog grouping label (e.g. `Email`, `Source control`, `Chat`). */
+  readonly category: string;
+
+  /** How the shared app credential authenticates. */
+  readonly appAuthKind: ProviderAppAuthKind;
+  /** Who shipped the provider — drives requirement scope + which admin fills. */
+  readonly origin: ProviderOrigin;
+
+  /**
+   * Schema of the app-credential fields an admin must supply to register the
+   * app (Google → clientId/clientSecret[/pubsubTopic]; GitHub App → appId/
+   * privateKey/webhookSecret). Empty/omitted when `appAuthKind = None`
+   * (nothing to provision — the connector is immediately connectable).
+   */
+  readonly appCredentialSchema?: readonly CredentialFieldSpec[];
+
+  /**
+   * OAuth endpoint metadata — REQUIRED when `appAuthKind = OAuth2`, absent
+   * otherwise.
+   */
+  readonly oauthEndpoints?: ProviderOAuthEndpoints;
+
+  /**
+   * Whether an org may override the platform-default app credential with its
+   * own (BYO app). `false` pins the provider to the platform provision only.
+   * Ignored when `appAuthKind = None` (there is no shared app to override).
+   */
+  readonly allowOrgOverride: boolean;
+}
+
+/**
+ * True when a provider needs an app credential provisioned before any of its
+ * connectors can be connected (i.e. anything other than `None`). Callers use
+ * this to decide whether to surface a "needs setup" state and to whom.
+ */
+export function providerRequiresAppCredential(
+  provider: Pick<ProviderDescriptor, 'appAuthKind'>,
+): boolean {
+  return provider.appAuthKind !== ProviderAppAuthKind.None;
+}

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

@@ -5,16 +5,15 @@ import { z } from 'zod';
  * (biome) may contribute to the Xema OS through the Contribution Protocol
  * (XSI plane 2). Extending it is a one-line PR to the kernel.
  *
- * The seed set is documented in the Xema OS plan-of-record §12.1. Each
- * additional value below the v1 seed (e.g. `ShellCommand`, `DoctorCheck`) is
- * pulled from a specific section of the same plan and is cited inline.
+ * The v1 seed set is grouped first below. Each additional value beyond the
+ * v1 seed (e.g. `ShellCommand`, `DoctorCheck`) extends the closed enum.
  *
  * 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.
  */
 export enum ContributionKind {
-  // -- v1 seed (plan §12.1) -------------------------------------------------
+  // -- v1 seed ---------------------------------------------------------------
   ConnectorBinding = 'connector-binding',
   MountSource = 'mount-source',
   McpTool = 'mcp-tool',
@@ -29,13 +28,13 @@ export enum ContributionKind {
   ModelResolutionDimension = 'model-resolution-dimension',
   WidgetKind = 'widget-kind',
 
-  // -- Xema Shell additions (plan §31.5 / §31.9) ---------------------------
-  /** A command descriptor contributed to the Xema Shell. Plan §31.5. */
+  // -- Xema Shell additions --------------------------------------------------
+  /** A command descriptor contributed to the Xema Shell. */
   ShellCommand = 'shell-command',
-  /** A `xema doctor` health check contributed by a biome. Plan §31.9. */
+  /** A `xema doctor` health check contributed by a biome. */
   DoctorCheck = 'doctor-check',
 
-  // -- Registry gaps closed (plan §17.12) ----------------------------------
+  // -- Registry gaps closed --------------------------------------------------
   /**
    * An artifact type contributed by a biome to the artifact-store schema-
    * version registry (`ArtifactTypeRegistryService`). The registry adapter
@@ -49,8 +48,8 @@ export enum ContributionKind {
    */
   InquiryKind = 'inquiry-kind',
 
-  // -- Phase C absorption (plan §6 C.2) ------------------------------------
-  // The Phase-C "Contribution Protocol" rollup is the single source of
+  // -- Contribution-absorption additions -------------------------------------
+  // The "Contribution Protocol" rollup is the single source of
   // truth for every kind of contribution a biome can ship. A biome's
   // `contributions/` directory replaces the legacy `content/` + `modules/`
   // seeders. Per-kind handlers are wired through
@@ -105,7 +104,7 @@ export enum ContributionKind {
   /** A runtime-mount kind module contributed by a biome. */
   RuntimeMountKind = 'runtime-mount-kind',
 
-  // -- Phase H#2: capability self-registration (plan §6.H) -----------------
+  // -- Capability self-registration ------------------------------------------
   /**
    * A `CapabilityRef` descriptor contributed by a biome — title, summary,
    * I/O schemas, risk tier, and approval flag. The boot-time codemod
@@ -122,7 +121,7 @@ export enum ContributionKind {
    */
   Capability = 'capability',
 
-  // -- Phase 5: resource-ownership self-registration -----------------------
+  // -- Resource-ownership self-registration ----------------------------------
   /**
    * A resource-instance ownership/visibility declaration contributed by a
    * biome — `resourceType` + `resourceId` + a `ResourceVisibilityPattern` +

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

@@ -2,8 +2,7 @@ import { z } from 'zod';
 
 /**
  * `ContributionSource` is the 5-tier scope at which a Contribution lives.
- * Value-identical to `SkillSpace` and `AgentSpace` (see
- * `.claude/rules/skills-and-composition.md`) — the three enums share ONE
+ * Value-identical to `SkillSpace` and `AgentSpace` — the three enums share ONE
  * ownership / scope model and must not drift.
  *
  * Precedence — **most specific wins**:

package/src/contribution/lib/contribution.ts

@@ -109,8 +109,6 @@ export const ContributionVersionSchema = z
  * regardless of `kind`, carries this shape. Kind-specific contracts packages
  * own their own `TManifest` Zod schemas and feed them to
  * `contributionEnvelopeSchema` to get a fully-typed runtime validator.
- *
- * See plan-of-record §12.2 for the prose definition.
  */
 export interface Contribution<
   TKind extends ContributionKind,
@@ -175,11 +173,10 @@ export interface ContributionIngestContext {
 }
 
 /**
- * Per-kind ingestion handler. Phase C of the Xema OS plan replaces 14 hand-
+ * Per-kind ingestion handler. The Contribution Protocol replaces 14 hand-
  * rolled `Bootstrap*Service` seeders with a single generic
- * `BootstrapContributionsService<TKind, TManifest>` template (see plan §6
- * C.3) whose only per-kind specialisation is an implementation of this
- * interface.
+ * `BootstrapContributionsService<TKind, TManifest>` template whose only
+ * per-kind specialisation is an implementation of this interface.
  *
  * Implementations MUST:
  * - pin `kind` to the concrete `ContributionKind` they handle so the

package/src/document-render/lib/render-enums.ts

@@ -1,7 +1,6 @@
 /**
  * Closed enums for the render service wire. Real TS enums (not
- * string-literal unions) so OpenAPI/Orval emit stable enum schemas — see
- * `docs/API_STANDARDS.md` and `.claude/rules/backend.md`.
+ * string-literal unions) so OpenAPI/Orval emit stable enum schemas.
  */
 
 /**

package/src/execution-context/lib/caller.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 
 /**
- * Closed caller-kind set (plan v4.3 §A.3).
+ * Closed caller-kind set.
  *
  * Distinguishes how the invocation entered the system — drives audit
  * shape, default obligations (e.g. `Web` callers default to `audit` +
@@ -21,7 +21,7 @@ export const CallerKindSchema = z.nativeEnum(CallerKind);
 /**
  * `Caller` — entry-point envelope captured on every invocation.
  *
- * v4.3 contract shape per plan §A.3:
+ * Contract shape:
  *   { kind: CallerKind; appId?; sessionId?; ip?; userAgent? }
  *
  * `appId` and `sessionId` are populated when the caller is an embedded

package/src/execution-context/lib/execution-context.ts

@@ -30,8 +30,7 @@ import {
 } from './subject';
 
 /**
- * Closed biome trust-tier set referenced by `ExecutionContext.biome`
- * (plan v4.3 §A.3).
+ * Closed biome trust-tier set referenced by `ExecutionContext.biome`.
  *
  * Tier ordering goes Untrusted → Community → Verified → Official; OPA
  * policy bundles MAY gate a capability to a minimum tier, but the kernel
@@ -48,8 +47,8 @@ export enum BiomeTrustTier {
 export const BiomeTrustTierSchema = z.nativeEnum(BiomeTrustTier);
 
 /**
- * Biome attestation block carried on `ExecutionContext.biome` (plan
- * v4.3 §A.3). Set when the capability is provided by a biome (vs. an
+ * Biome attestation block carried on `ExecutionContext.biome`.
+ * Set when the capability is provided by a biome (vs. an
  * embedded built-in). `signatureVerified` is the Cosign verdict from the
  * biome-fetcher-api at install time.
  */
@@ -68,8 +67,7 @@ export const ExecutionContextBiomeSchema = z.object({
 }) as z.ZodType<ExecutionContextBiome>;
 
 /**
- * Environment block carried on `ExecutionContext.environment` (plan
- * v4.3 §A.3).
+ * Environment block carried on `ExecutionContext.environment`.
  *
  * `id` is the canonical `environment:<slug>` ref (string-typed here to
  * keep the envelope JSON-clean — the kernel-side reference type lives in the
@@ -89,8 +87,7 @@ export const ExecutionContextEnvironmentSchema = z.object({
 }) as z.ZodType<ExecutionContextEnvironment>;
 
 /**
- * Capability block carried on `ExecutionContext.capability` (plan
- * v4.3 §A.3).
+ * Capability block carried on `ExecutionContext.capability`.
  *
  * `ref` is the canonical capability reference (`<biome>:<verb>@<major>`).
  * `inputHash` is an optional SHA-256 fingerprint of the JSON-serialised
@@ -108,7 +105,7 @@ export const ExecutionContextCapabilitySchema = z.object({
 }) as z.ZodType<ExecutionContextCapability>;
 
 /**
- * Resource block carried on `ExecutionContext.resource` (plan v4.3 §A.3).
+ * Resource block carried on `ExecutionContext.resource`.
  *
  * Set when the invocation targets a specific persistent object (a
  * XemaObject, a document, an SCM file). `ref` is the resource reference
@@ -127,8 +124,7 @@ export const ExecutionContextResourceSchema = z.object({
 }) as z.ZodType<ExecutionContextResource>;
 
 /**
- * Constraints block carried on `ExecutionContext.constraints` (plan
- * v4.3 §A.3).
+ * Constraints block carried on `ExecutionContext.constraints`.
  *
  * Per-invocation caps + flags the gateway derives from the caller's
  * grant, the org's environment policy, and the capability's defaults.
@@ -155,14 +151,14 @@ export const ExecutionContextConstraintsSchema = z.object({
 }) as z.ZodType<ExecutionContextConstraints>;
 
 /**
- * `ExecutionContext` — the per-invocation envelope (plan v4.3 §A.3).
+ * `ExecutionContext` — the per-invocation envelope.
  *
- * Constructed by `biomes/xema-capability-router/api/xema-capability-router` at the gateway boundary,
+ * Constructed by the capability router at the gateway boundary,
  * passed verbatim to `authorization-api` for the policy check, and
  * forwarded to the dispatched runner. Audit, policy, and runner all
  * read the SAME shape — no parallel envelopes.
  *
- * Wave 4 (Phase A.5) wires this through `dispatch.service.ts`. This
+ * The dispatch pipeline wires this through at runtime. This
  * package is contract-only — no consumer rewiring lives here.
  */
 export interface ExecutionContext {
@@ -180,15 +176,13 @@ export interface ExecutionContext {
   /**
    * RFC 8693 delegation chain (`act`), outermost-acting-first. Built at the
    * gateway from `RequestContext.actorChain` and carried through policy → audit
-   * → credential-broker. Empty/omitted for a non-delegated invocation
-   * (plan §W4 / Pillar 3.2).
+   * → credential-broker. Empty/omitted for a non-delegated invocation.
    */
   actorChain?: ActingForRef[];
   /**
    * Opaque credential-binding id the PDP selected for this invocation
    * (`PolicyDecision.credentialBindingId`). When present, the executing
-   * gateway/runner resolves it via the credential-broker. NEVER a secret
-   * (plan §W4 / Pillar 3.2).
+   * gateway/runner resolves it via the credential-broker. NEVER a secret.
    */
   credentialBindingId?: string;
   /**

package/src/execution-environment/lib/approval-rule.ts

@@ -5,8 +5,8 @@ import {
 } from '../../capability';
 
 /**
- * Per-environment approval rule (plan §3.4 `ExecutionEnvironment.approvalRules[]`,
- * §30.7 Human-in-the-loop approval at runtime).
+ * Per-environment approval rule (`ExecutionEnvironment.approvalRules[]`):
+ * human-in-the-loop approval at runtime.
  *
  * When a runtime invocation matches a rule whose `capability` ref covers the
  * call, the gateway suspends the invocation, emits an `ApprovalRequested`