@xemahq/kernel-contracts 0.1.0 → 0.2.1

package/src/app-runtime/lib/branding-config.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+
+/**
+ * Accepts:
+ *   - 3- or 6-digit hex (e.g. `#0a0`, `#0a0a0a`)
+ *   - 8-digit hex with alpha (e.g. `#0a0a0aff`)
+ *   - `rgb(r, g, b)` / `rgba(r, g, b, a)` (whitespace-flexible)
+ *
+ * Kept deliberately tight: the App branding contract should never silently
+ * absorb a free-form string. Anything else (CSS custom properties, named
+ * colors, `hsl(...)`, etc.) belongs in `cssTokens` where the host CSS
+ * pipeline interprets it.
+ */
+const PRIMARY_COLOR_REGEX =
+  /^(?:#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})|rgba?\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}\s*(?:,\s*(?:0|1|0?\.\d+)\s*)?\))$/;
+
+/**
+ * `BrandingConfig` — per-App visual branding (plan §5.1). Used by the
+ * public ingress (`app-runtime-api`) and any embed snippet to theme the
+ * audience-facing UI. The shape is intentionally minimal:
+ *
+ * - `displayName` is REQUIRED — every audience-facing surface needs a
+ *   human-readable label; no silent fallback to the App slug.
+ * - `primaryColor` is validated against a strict hex / rgb(a) grammar.
+ * - `cssTokens` is the escape hatch for richer theming — keys map to CSS
+ *   custom-property names (without the leading `--`); the host CSS
+ *   pipeline interprets the values.
+ */
+export interface BrandingConfig {
+  displayName: string;
+  logoUrl?: string;
+  primaryColor?: string;
+  cssTokens?: Record<string, string>;
+}
+
+export const BrandingConfigSchema = z.object({
+  displayName: z.string().min(1, {
+    message: 'BrandingConfig.displayName must be a non-empty string.',
+  }),
+  logoUrl: z
+    .string()
+    .url({
+      message: 'BrandingConfig.logoUrl must be a valid URL.',
+    })
+    .optional(),
+  primaryColor: z
+    .string()
+    .regex(PRIMARY_COLOR_REGEX, {
+      message:
+        'BrandingConfig.primaryColor must be a hex (`#rgb`, `#rrggbb`, `#rrggbbaa`) or `rgb()` / `rgba()` value. Use `cssTokens` for richer theming.',
+    })
+    .optional(),
+  cssTokens: z.record(z.string().min(1), z.string().min(1)).optional(),
+}) as z.ZodType<BrandingConfig>;

package/src/app-runtime/lib/delegated-session.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import {
+  CapabilityRefSchema,
+  type CapabilityRef,
+} from '../../capability';
+import {
+  ExecutionEnvironmentRefSchema,
+  type ExecutionEnvironmentRef,
+} from '../../execution-environment';
+
+/**
+ * Claims carried by a delegated session token minted by `app-runtime-api`
+ * for an `ExternalSubject` audience (plan §5.2):
+ *
+ * ```
+ * sub          = external-user:<externalId>     (or anon:<random>)
+ * act          = app:<appClientId>
+ * org          = <orgId>
+ * project      = <projectId>
+ * session      = <sessionId>
+ * environment         = <environmentId>                       (typically environment:public-session)
+ * capabilities = [<allowed capability refs>]
+ * exp          = short
+ * ```
+ *
+ * `exp` is a Unix-epoch second count (RFC 7519 `exp` claim shape) — the
+ * value MUST be a positive integer. Token minting is short-lived by design;
+ * downstream services MUST NOT extend it silently.
+ *
+ * `capabilities` is the closed, fully-resolved set the gateway will honor
+ * for the lifetime of this token — refs not in this list are denied at the
+ * gateway with no fallback (per the capability-protocol fail-fast rule).
+ */
+export interface DelegatedSessionClaims {
+  sub: string;
+  act: string;
+  org: string;
+  project: string;
+  session: string;
+  environment: ExecutionEnvironmentRef;
+  capabilities: CapabilityRef[];
+  exp: number;
+}
+
+export const DelegatedSessionClaimsSchema = z.object({
+  sub: z.string().min(1, {
+    message:
+      'DelegatedSessionClaims.sub must be a non-empty subject identifier (e.g. `external-user:<id>` or `anon:<random>`).',
+  }),
+  act: z.string().min(1, {
+    message:
+      'DelegatedSessionClaims.act must be a non-empty actor identifier (e.g. `app:<appClientId>`).',
+  }),
+  org: z.string().min(1, {
+    message: 'DelegatedSessionClaims.org must be a non-empty orgId.',
+  }),
+  project: z.string().min(1, {
+    message: 'DelegatedSessionClaims.project must be a non-empty projectId.',
+  }),
+  session: z.string().min(1, {
+    message: 'DelegatedSessionClaims.session must be a non-empty sessionId.',
+  }),
+  environment: ExecutionEnvironmentRefSchema,
+  capabilities: z.array(CapabilityRefSchema),
+  exp: z.number().int().positive({
+    message:
+      'DelegatedSessionClaims.exp must be a positive Unix-epoch second count (RFC 7519 `exp`).',
+  }),
+}) as z.ZodType<DelegatedSessionClaims>;

package/src/app-runtime/lib/external-subject.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+
+/**
+ * `ExternalSubject` — an app-scoped, non-Xema identity (plan §5.2). Created
+ * when an `AudiencePolicy` of kind `ExternalSubject` mints a delegated
+ * session for an upstream user (OIDC / magic-link / anon). External
+ * subjects do NOT become Xema users — they are stored and referenced only
+ * by their `externalId` under the owning `appClientId`.
+ *
+ * `createdAt` is a strict ISO-8601 datetime string at the wire boundary —
+ * no implicit timezone, no Unix-epoch fallback.
+ */
+export interface ExternalSubject {
+  externalId: string;
+  appClientId: string;
+  createdAt: string;
+  metadata?: Record<string, unknown>;
+}
+
+export const ExternalSubjectSchema = z.object({
+  externalId: z.string().min(1, {
+    message: 'ExternalSubject.externalId must be a non-empty string.',
+  }),
+  appClientId: z.string().min(1, {
+    message: 'ExternalSubject.appClientId must be a non-empty string.',
+  }),
+  createdAt: z
+    .string()
+    .datetime({
+      message:
+        'ExternalSubject.createdAt must be a strict ISO-8601 datetime string.',
+    }),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}) as z.ZodType<ExternalSubject>;

package/src/connector/index.ts

@@ -0,0 +1,8 @@
+export * from './lib/adapter-kind';
+export * from './lib/capability';
+export * from './lib/credential-kind';
+export * from './lib/onboarding-manifest';
+export * from './lib/envelope-schema';
+export * from './lib/filter-expr';
+export * from './lib/filter-expr-schema';
+export * from './lib/filter-expr-validate';

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

@@ -0,0 +1,37 @@
+/**
+ * Built-in adapter kinds.
+ *
+ * An `AdapterKind` is a *category* of external system. Each kind ships a
+ * canonical envelope schema in its owning domain service (SCM →
+ * connector-gateway-api, TRACKER → backlog-api, DOCUMENTATION →
+ * knowledge-base-api). Providers (github, gitlab, jira, …) plug into
+ * a kind by mapping their raw events onto that canonical envelope.
+ *
+ * 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
+ * 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.
+ */
+export enum BuiltInAdapterKind {
+  Scm = 'scm',
+  Tracker = 'tracker',
+  Documentation = 'documentation',
+}
+
+/**
+ * Wire-typed reference to an adapter kind. Built-in kinds use their
+ * `BuiltInAdapterKind` slug; biome-contributed kinds use whatever slug
+ * the contributing biome registered (validated at boot by
+ * integration-adapters-api).
+ *
+ * Stored as a plain string so the persistence layer (Prisma) does not
+ * have to evolve when a biome introduces a new kind. The runtime
+ * registry is the authority on which slugs are currently known.
+ */
+export type AdapterKindRef = string;
+
+export function isBuiltInAdapterKind(ref: AdapterKindRef): ref is BuiltInAdapterKind {
+  return (Object.values(BuiltInAdapterKind) as string[]).includes(ref);
+}

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

@@ -0,0 +1,29 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Connector capability refs ──
+//
+// Typed string constants for the connector capabilities exposed by the
+// capability gateway. Values are CapabilityRefs (see `@xemahq/capability-
+// 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
+// `connector-gateway-api` capability dispatcher MAY consume it directly for
+// `name`-side validation.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type { CapabilityRef } from '../../capability';
+
+export const CONNECTOR_CAPABILITY_REFS = Object.freeze({
+  ScmCreatePullRequest: 'connector:scm.create-pull-request@1' as CapabilityRef,
+  ScmMerge: 'connector:scm.merge@1' as CapabilityRef,
+  TrackerIssueCreate: 'connector:tracker.issue.create@1' as CapabilityRef,
+  TrackerIssueTransition:
+    'connector:tracker.issue.transition@1' as CapabilityRef,
+  DocsPublishPage: 'connector:docs.publish-page@1' as CapabilityRef,
+  DocsPageRead: 'connector:docs.page.read@1' as CapabilityRef,
+  ChatSendMessage: 'connector:chat.send-message@1' as CapabilityRef,
+  LlmInvoke: 'connector:llm.invoke@1' as CapabilityRef,
+  McpToolInvoke: 'connector:mcp.tool.invoke@1' as CapabilityRef,
+} as const);
+
+export type ConnectorCapabilityRefName = keyof typeof CONNECTOR_CAPABILITY_REFS;

package/src/connector/lib/capability.ts

@@ -0,0 +1,38 @@
+/**
+ * Capability slugs a biome can request against an integration. The set
+ * is *closed and built-in for v1*. Biome-contributed AdapterKinds may
+ * register additional capability slugs at boot (validated against the
+ * `^[a-z]+(\.[a-z][a-z0-9-]*)+$` shape).
+ *
+ * Slugs are `<domain>.<verb>[-qualifier]`. The first segment maps to the
+ * AdapterKind family the capability applies to; the rest names the
+ * action. Closed enum values exist for the v1 built-in kinds so consent
+ * UX and ESLint rules can switch on them exhaustively.
+ */
+export enum BuiltInCapability {
+  ScmReadRepo = 'scm.read-repo',
+  ScmReadBranch = 'scm.read-branch',
+  ScmReadCommit = 'scm.read-commit',
+  ScmReadFile = 'scm.read-file',
+  ScmWritePrComment = 'scm.write-pr-comment',
+  ScmWriteCommitStatus = 'scm.write-commit-status',
+  TrackerReadIssue = 'tracker.read-issue',
+  TrackerWriteIssue = 'tracker.write-issue',
+  TrackerWriteComment = 'tracker.write-comment',
+  TrackerTransitionStatus = 'tracker.transition-status',
+  DocumentationReadPage = 'documentation.read-page',
+  DocumentationWritePage = 'documentation.write-page',
+}
+
+/**
+ * Capability slug at the wire boundary — a string for forward
+ * compatibility with biome-contributed AdapterKinds. Validate against
+ * the shape regex at manifest-parse time.
+ */
+export type CapabilitySlug = string;
+
+export const CAPABILITY_SLUG_PATTERN = /^[a-z]+(\.[a-z][a-z0-9-]*)+$/;
+
+export function isValidCapabilitySlug(slug: string): slug is CapabilitySlug {
+  return CAPABILITY_SLUG_PATTERN.test(slug);
+}

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

@@ -0,0 +1,120 @@
+/**
+ * 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.
+ *
+ * Adding a kind here is a one-line schema change plus a matching
+ * strategy implementation under
+ * `apps/integration-adapters-api/src/credentials/strategies/<kind>/`.
+ */
+export enum CredentialKind {
+  /** GitHub App / GitLab App style installation token (per-installation, 1h). */
+  AppInstall = 'app_install',
+  /** 3-legged OAuth user-delegated token with refresh-token rotation. */
+  OAuthUser = 'oauth_user',
+  /** 2-legged OAuth client-credentials grant. */
+  OAuthClient = 'oauth_client',
+  /** Long-lived personal access token. */
+  Pat = 'pat',
+  /** Generic API key. */
+  ApiKey = 'api_key',
+  /** Long-lived bot token (Slack / Discord style). */
+  BotToken = 'bot_token',
+  /** HTTP Basic auth credential. */
+  Basic = 'basic',
+  /** Provider-scoped restricted key (Stripe restricted keys, etc.). */
+  RestrictedKey = 'restricted_key',
+  /** AWS STS AssumeRoleWithWebIdentity using a workload-identity token. */
+  IamRole = 'iam_role',
+  /**
+   * No outbound credential — provider sends signed webhooks only. The
+   * resolver returns no token; only the webhook verifier is registered.
+   */
+  SignatureOnly = 'signature_only',
+  /**
+   * SMTP wallet (one or more per org). Stored as a typed config blob —
+   * `host`, `port`, `username`, `password`, `tlsMode`, optional
+   * `fromAddress` and `fromName`. Resolved as `tokenType='header'` with
+   * the full config carried in `providerHints` so the SMTP send
+   * activity can hand it straight to nodemailer without re-decrypting.
+   */
+  SmtpAuth = 'smtp_auth',
+  /**
+   * IMAP wallet (one or more per org). Same shape as SmtpAuth minus
+   * the sender fields. Resolver carries `host`, `port`, `username`,
+   * `password`, `tlsMode` in `providerHints` for imapflow.
+   */
+  ImapAuth = 'imap_auth',
+}
+
+/**
+ * Closed TLS-mode enum shared by SMTP + IMAP wallets. `auto` lets the
+ * client library pick the right mode for the configured port:
+ *   - 465 / 993 → implicit TLS
+ *   - 587 / 143 → STARTTLS (negotiated)
+ *   - 25 (SMTP) → plain (warns; not recommended)
+ * `tls` / `starttls` / `plain` are the explicit overrides.
+ */
+export enum EmailTlsMode {
+  Auto = 'auto',
+  Tls = 'tls',
+  Starttls = 'starttls',
+  Plain = 'plain',
+}
+
+/**
+ * Wire shape of the SMTP / IMAP wallet payload as carried in
+ * `MintedToken.providerHints`. The values are always plain strings on
+ * the wire — `port` is stringified so the platform-common decoder can
+ * round-trip through any envelope without losing the type. The send /
+ * fetch activities re-parse `port` to a number at use site.
+ *
+ * Sensitive fields (`password`) are returned by the resolver only;
+ * cache the minted token, not the wallet config, and never log it.
+ */
+export interface EmailWalletHints {
+  host: string;
+  port: string;
+  username: string;
+  password: string;
+  tlsMode: EmailTlsMode;
+  /** SMTP only — default sender address for the wallet. */
+  fromAddress?: string;
+  /** SMTP only — default sender name. */
+  fromName?: string;
+}
+
+/**
+ * A minted, ready-to-use token returned by `POST /credentials/resolve`.
+ * Provider-neutral by construction — `providerHints` carries any
+ * per-provider routing data (regional endpoint, app id, …) opaquely.
+ */
+export type MintedTokenType =
+  | 'bearer'
+  | 'basic'
+  | 'aws-sigv4'
+  | 'header'
+  /**
+   * Webhook-verifier-only: `accessToken` carries the HMAC shared
+   * secret. Callers MUST NOT send this anywhere outbound; the only
+   * intended use is local signature verification on inbound webhooks.
+   */
+  | 'signature-only';
+
+export interface MintedToken {
+  tokenType: MintedTokenType;
+  accessToken: string;
+  expiresAt: string | null;
+  expiresInSec: number | null;
+  providerHints: Readonly<Record<string, string>>;
+}
+
+/**
+ * Reference to a concrete resource the credential mint is being asked
+ * to scope to. `type` identifies which `ResourceLister` produced it
+ * (e.g. `'repo'`, `'project'`, `'channel'`); `id` is provider-opaque.
+ */
+export interface ResourceRef {
+  type: string;
+  id: string;
+}

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

@@ -0,0 +1,256 @@
+import { BuiltInAdapterKind, type AdapterKindRef } from './adapter-kind';
+
+/**
+ * Canonical envelope path schemas — per built-in `(AdapterKind, EntityKind)`.
+ *
+ * The dispatcher receives a canonical webhook envelope shaped by the
+ * domain service that owns the AdapterKind (connector-gateway-api,
+ * backlog-api, knowledge-base-api). At biome-manifest validation
+ * time we want to fail fast on `FilterExpr` predicates that reference
+ * `$envelope.someFieldThatDoesNotExist`, instead of silently
+ * evaluating to `false` at dispatch.
+ *
+ * The map is keyed by `(adapterKind, entityKind)`. When a webhook
+ * filter declares its target `entityKind` (Phase 7 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-
+ * permissive but still catches the common typo class.
+ *
+ * Updates: when a domain service adds/renames a payload field, the
+ * matching entry below MUST be updated in the same PR. `crossValidate-
+ * IntegrationContract` walks every biome's filter predicates against
+ * this map at biome-host boot, so stale entries surface as cross-
+ * validation failures with named paths.
+ */
+
+/**
+ * Wildcard entityKind used when a `FilterExpr` predicate doesn't
+ * declare which entity kind it targets. Matches the union across all
+ * entity kinds the adapter owns.
+ */
+export const UNION_ENTITY_KIND = '*';
+
+/** Inherited base envelope fields (defined on `IntegrationWebhookEnvelopeDto`). */
+const BASE_ENVELOPE_PATHS = [
+  'provider',
+  'adapterKey',
+  'event',
+  'entityKind',
+  'deliveryId',
+  'occurredAt',
+  'correlationId',
+  'externalId',
+  'externalSpaceKey',
+] as const;
+
+// ── SCM per-entityKind payload paths ──
+
+const SCM_PUSH_PATHS = [
+  'payload.repositoryCloneUrl',
+  'payload.repositoryFullName',
+  'payload.authorExternalId',
+  'payload.ref',
+  'payload.branch',
+  'payload.beforeSha',
+  'payload.afterSha',
+  'payload.commitCount',
+  'payload.commits',
+  'payload.commits.sha',
+  'payload.commits.message',
+  'payload.commits.authorExternalId',
+  'payload.commits.committedAt',
+] as const;
+
+const SCM_CHANGE_REQUEST_PATHS = [
+  'payload.repositoryCloneUrl',
+  'payload.repositoryFullName',
+  'payload.authorExternalId',
+  'payload.title',
+  'payload.description',
+  'payload.state',
+  'payload.sourceBranch',
+  'payload.targetBranch',
+  'payload.headSha',
+  'payload.mergeCommitSha',
+] as const;
+
+const SCM_ISSUE_PATHS = [
+  'payload.repositoryCloneUrl',
+  'payload.repositoryFullName',
+  'payload.authorExternalId',
+  'payload.title',
+  'payload.description',
+  'payload.state',
+  'payload.labels',
+] as const;
+
+const SCM_REPOSITORY_PATHS = [
+  'payload.repositoryCloneUrl',
+  'payload.repositoryFullName',
+  'payload.action',
+  'payload.visibility',
+  'payload.previousVisibility',
+  'payload.previousRepositoryCloneUrl',
+  'payload.previousRepositoryFullName',
+] as const;
+
+const SCM_INSTALLATION_PATHS = [
+  'payload.installationId',
+  'payload.action',
+  'payload.accountLogin',
+  'payload.affectedRepositoryFullNames',
+] as const;
+
+// ── Tracker per-entityKind payload paths ──
+
+const TRACKER_ITEM_PATHS = [
+  'payload.title',
+  'payload.description',
+  'payload.type',
+  'payload.status',
+  'payload.priority',
+  'payload.tags',
+  'payload.ownerDomain',
+] as const;
+
+const TRACKER_COMMENT_PATHS = [
+  'payload.itemExternalId',
+  'payload.content',
+  'payload.authorId',
+  'payload.authorType',
+] as const;
+
+// ── Documentation per-entityKind payload paths ──
+
+const DOC_PAGE_PATHS = [
+  'payload.slug',
+  'payload.title',
+  'payload.content',
+  'payload.contentType',
+  'payload.externalParentId',
+] as const;
+
+const DOC_SPACE_PATHS = [
+  'payload.slug',
+  'payload.title',
+  'payload.description',
+] as const;
+
+/**
+ * Per-`(adapterKind, entityKind)` allowed `$envelope.*` paths. The
+ * `'*'` entityKind entry is the union across every kind for that
+ * adapter — used when a filter omits `entityKind` (today's default).
+ */
+const ENVELOPE_PATHS_BY_KIND_BY_ENTITY = new Map<
+  AdapterKindRef,
+  Map<string, ReadonlySet<string>>
+>();
+
+registerEnvelopeSchema(BuiltInAdapterKind.Scm, {
+  push: SCM_PUSH_PATHS,
+  change_request: SCM_CHANGE_REQUEST_PATHS,
+  issue: SCM_ISSUE_PATHS,
+  repository: SCM_REPOSITORY_PATHS,
+  installation: SCM_INSTALLATION_PATHS,
+});
+
+registerEnvelopeSchema(BuiltInAdapterKind.Tracker, {
+  item: TRACKER_ITEM_PATHS,
+  comment: TRACKER_COMMENT_PATHS,
+});
+
+registerEnvelopeSchema(BuiltInAdapterKind.Documentation, {
+  page: DOC_PAGE_PATHS,
+  space: DOC_SPACE_PATHS,
+});
+
+/**
+ * Register the per-entityKind permitted `$envelope.*` paths for a
+ * biome-contributed AdapterKind (Phase 7). 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.
+ *
+ * Each entry in `perEntityKind` lists the payload paths (without the
+ * `$envelope.` prefix, without the base envelope fields — those are
+ * implicitly included). The `'*'` union entry is derived automatically.
+ */
+export function registerEnvelopeSchema(
+  adapterKind: AdapterKindRef,
+  perEntityKind: Readonly<Record<string, readonly string[]>>,
+): void {
+  const perEntity = new Map<string, ReadonlySet<string>>();
+  const unionSet = new Set<string>(BASE_ENVELOPE_PATHS);
+  for (const [entityKind, paths] of Object.entries(perEntityKind)) {
+    const withBase = new Set<string>([...BASE_ENVELOPE_PATHS, ...paths]);
+    perEntity.set(entityKind, withBase);
+    for (const path of paths) unionSet.add(path);
+  }
+  perEntity.set(UNION_ENTITY_KIND, unionSet);
+  ENVELOPE_PATHS_BY_KIND_BY_ENTITY.set(adapterKind, perEntity);
+}
+
+/**
+ * Returns the set of permitted `$envelope.*` paths for the given
+ * `(adapterKind, entityKind)`. `entityKind === undefined` means
+ * "union across every entity kind under this adapter".
+ *
+ * `undefined` return: the adapter kind isn't registered (biome-
+ * contributed kind whose adapter hasn't loaded yet) — callers should
+ * skip validation rather than fail.
+ */
+export function getEnvelopeSchema(
+  adapterKind: AdapterKindRef,
+  entityKind?: string,
+): ReadonlySet<string> | undefined {
+  const perEntity = ENVELOPE_PATHS_BY_KIND_BY_ENTITY.get(adapterKind);
+  if (!perEntity) return undefined;
+  return perEntity.get(entityKind ?? UNION_ENTITY_KIND);
+}
+
+/**
+ * True iff `path` is a permitted reference under `$envelope.*` for
+ * the given `(adapterKind, entityKind)`. Numeric path segments
+ * (array indices) are normalized before lookup —
+ * `payload.commits.0.sha` matches `payload.commits.sha`.
+ *
+ * When `entityKind` is omitted, validates against the union across
+ * every entity kind for the adapter.
+ *
+ * Returns `true` when the adapter kind is unregistered OR when an
+ * `entityKind` is passed but the registered schema doesn't know it —
+ * biome-contributed kinds without a loaded schema don't break
+ * validation (the cross-validator surfaces the missing-schema case
+ * separately).
+ */
+export function isAllowedEnvelopePath(
+  adapterKind: AdapterKindRef,
+  path: string,
+  entityKind?: string,
+): boolean {
+  const schema = getEnvelopeSchema(adapterKind, entityKind);
+  if (!schema) {
+    // Either the adapter kind isn't registered, or the registered
+    // schema doesn't recognize the entityKind. Either way, fall back
+    // to the union (if any) so an unknown entityKind doesn't bomb.
+    if (entityKind !== undefined) {
+      const unionFallback = getEnvelopeSchema(adapterKind);
+      if (unionFallback) return unionFallback.has(normalizeEnvelopePath(path));
+    }
+    return true;
+  }
+  return schema.has(normalizeEnvelopePath(path));
+}
+
+/**
+ * Strip numeric-index segments from a dot-delimited path so the
+ * schema lookup sees the structural shape. `commits.0.sha` →
+ * `commits.sha`.
+ */
+function normalizeEnvelopePath(path: string): string {
+  return path
+    .split('.')
+    .filter((segment) => !/^\d+$/.test(segment))
+    .join('.');
+}