@xemahq/kernel-contracts 0.1.0

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

@@ -0,0 +1,99 @@
+import { z } from 'zod';
+
+import { CapabilityRefSchema, type CapabilityRef } from './capability-ref';
+import {
+  CapabilityRiskTierSchema,
+  type CapabilityRiskTier,
+} from './permission-profile';
+
+/**
+ * Manifest shape carried by every `ContributionKind.Capability` envelope
+ * (plan §6.H#2). One contribution = one capability ref.
+ *
+ * The shape is intentionally a value-identical subset of
+ * `RegisterCapabilityDto` (the `POST /capabilities/register` body shape on
+ * `capability-registry-api`) so that the codemod `tooling/codegen/
+ * biomes-register-capabilities.mjs` and the decorator-driven auto-register
+ * path in `@xemahq/xema-decorators`'s `XemaRuntimeModule` can both emit the
+ * SAME wire payload, regardless of which source the biome chose. Provenance
+ * (`biome.id`, `biome.version`) is stamped by the bootstrap pipeline from
+ * the discovering biome's manifest — authors do not declare it inline.
+ *
+ * Validation is fail-fast: a contribution that violates any of these
+ * constraints is rejected at boot. Silent coercion is disallowed —
+ * `inputSchema` / `outputSchema` are opaque JSON Schemas, but every other
+ * field is constrained.
+ */
+export interface CapabilityContributionManifest {
+  /** Canonical `<domain>:<resource>.<verb>@<major>` capability ref. */
+  readonly ref: CapabilityRef;
+  /** Human-readable capability title (≤ 200 chars). */
+  readonly title: string;
+  /** One-line summary surfaced to the agent (≤ 1000 chars). */
+  readonly summary: string;
+  /** Free-form natural-language side-effect summary (≤ 1000 chars). */
+  readonly sideEffects: string;
+  /** JSON Schema for the capability input — passed through verbatim. */
+  readonly inputSchema: Record<string, unknown>;
+  /** JSON Schema for the capability output — passed through verbatim. */
+  readonly outputSchema: Record<string, unknown>;
+  /** Kernel `CapabilityRiskTier` (low / medium / high / critical). */
+  readonly riskTier: CapabilityRiskTier;
+  /**
+   * Whether this capability requires explicit human approval before each
+   * call — independent of any downstream policy verdict.
+   */
+  readonly requiresApproval: boolean;
+  /**
+   * Optional example invocations surfaced to the agent. Hard-capped at 20
+   * to keep the describe-batch responses bounded.
+   */
+  readonly examples?: readonly Record<string, unknown>[];
+  /**
+   * Identifier of the EXTERNAL service this capability calls (e.g. a provider
+   * slug like `github` or an MCP server ref). Presence is the signal that the
+   * invocation needs a brokered external credential (plan §W4 / Pillar 3.2):
+   * authorization-api runs the credential-binding precedence ladder ONLY for
+   * capabilities that declare it, and the executing gateway resolves a sealed
+   * credential for that service. Absent ⇒ the capability is internal and needs
+   * no external credential. Never carries the credential itself.
+   */
+  readonly externalServiceRef?: string;
+  /**
+   * Optional descriptor-level default credential-binding ref — the
+   * `capability_default` tier of the PDP precedence ladder. Used when no
+   * explicit grant names a binding. An opaque binding id (resolved by the
+   * broker), NEVER a secret. Only meaningful alongside `externalServiceRef`.
+   */
+  readonly defaultCredentialBindingRef?: string;
+}
+
+/**
+ * Zod validator for `CapabilityContributionManifest`. The codemod and the
+ * runtime auto-register path BOTH route every candidate envelope through
+ * this schema before contacting `capability-registry-api`, so a malformed
+ * contribution fails at the boundary instead of at the wire.
+ *
+ * `inputSchema` / `outputSchema` deliberately stay `z.record(z.string(),
+ * z.unknown())` — capability-registry-api stores them as JSON and the
+ * agent-facing describe response surfaces them verbatim. Validating them
+ * as JSON Schema here would either be partial (false security) or pull in
+ * a JSON-Schema validator (kernel-leaf invariant violation).
+ */
+export const CapabilityContributionManifestSchema: z.ZodType<CapabilityContributionManifest> =
+  z.object({
+    ref: CapabilityRefSchema,
+    title: z.string().min(1).max(200),
+    summary: z.string().min(1).max(1000),
+    sideEffects: z.string().min(1).max(1000),
+    inputSchema: z.record(z.string(), z.unknown()),
+    outputSchema: z.record(z.string(), z.unknown()),
+    riskTier: CapabilityRiskTierSchema,
+    requiresApproval: z.boolean(),
+    examples: z
+      .array(z.record(z.string(), z.unknown()))
+      .max(20)
+      .optional(),
+    externalServiceRef: z.string().min(1).max(200).optional(),
+    defaultCredentialBindingRef: z.string().min(1).max(200).optional(),
+  }) as z.ZodType<CapabilityContributionManifest>;

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

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+import { CapabilityRefSchema, type CapabilityRef } from './capability-ref';
+import {
+  SubjectKind,
+  SubjectKindSchema,
+  SubjectRefSchema,
+  ActingForRefSchema,
+  subjectRefToString,
+  parseSubjectRef,
+  type SubjectRef,
+  type ActingForRef,
+} from '../../subject';
+
+/**
+ * The canonical subject taxonomy now lives in `@xemahq/subject-contracts`:
+ * one closed `SubjectKind`, the `{ kind, id, roles?, actingFor? }` `SubjectRef`,
+ * the `ActingForRef` delegation pointer, and the
+ * `subjectRefToString`/`parseSubjectRef` composite bridges. Re-exported here so
+ * existing `@xemahq/capability-contracts` importers are unaffected.
+ *
+ * NOTE: `SubjectRef.id` is the bare per-kind identifier — use
+ * `subjectRefToString` for the `"<kind>:<id>"` composite that the legacy `ref`
+ * field carried, and `parseSubjectRef` to recover it from a stored string.
+ */
+export {
+  SubjectKind,
+  SubjectKindSchema,
+  SubjectRefSchema,
+  ActingForRefSchema,
+  subjectRefToString,
+  parseSubjectRef,
+};
+export type { SubjectRef, ActingForRef };
+
+/**
+ * Per-grant runtime caps. None of these are required at the contract level;
+ * absent fields mean "no platform-imposed limit on this axis". Profiles
+ * (§30.3) may default some of them; admins may tighten or loosen per row.
+ */
+export interface GrantConstraints {
+  maxCallsPerHour?: number;
+  maxCostUsd?: number;
+  /**
+   * Free-form rate-limit token consumed by the gateway's rate-limit module
+   * (e.g. `100/min`, `1k/day`). Kept as a string at the contract layer so
+   * the parsing rules can evolve without bumping the kernel contract.
+   */
+  rateLimit?: string;
+}
+
+export const GrantConstraintsSchema = z.object({
+  maxCallsPerHour: z.number().int().nonnegative().optional(),
+  maxCostUsd: z.number().nonnegative().optional(),
+  rateLimit: z.string().min(1).optional(),
+}) as z.ZodType<GrantConstraints>;
+
+/**
+ * `CapabilityGrant` is the single row shape `authorization-api` stores
+ * (per §3.4, §30.5). One grant binds ONE `(subject, capability)` pair to a
+ * `resourceGlob`, an allowed-environment set, and optional runtime constraints.
+ *
+ * Wildcards (`kb:*@1`) are NOT represented in `capability` at the contract
+ * level — the kernel grammar in `capability-ref.ts` rejects them. Wildcard
+ * grants are stored as multiple per-verb rows OR as a separate
+ * domain-wildcard table in `authorization-api`; the choice is a Phase 3
+ * implementation detail, not a kernel concern.
+ */
+export interface CapabilityGrant {
+  grantId: string;
+  subject: SubjectRef;
+  capability: CapabilityRef;
+  /**
+   * Glob over XVFS resource refs, e.g. `xema://org/acme/project/*\/kb/**`.
+   * Authorization-api owns glob semantics (§30.4).
+   */
+  resourceGlob: string;
+  allowedEnvironments: readonly string[];
+  constraints?: GrantConstraints;
+  requiresApproval?: boolean;
+}
+
+export const CapabilityGrantSchema = z.object({
+  grantId: z.string().min(1),
+  subject: SubjectRefSchema,
+  capability: CapabilityRefSchema,
+  resourceGlob: z.string().min(1),
+  allowedEnvironments: z.array(z.string().min(1)).readonly(),
+  constraints: GrantConstraintsSchema.optional(),
+  requiresApproval: z.boolean().optional(),
+}) as z.ZodType<CapabilityGrant>;

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

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import { CapabilityRefSchema, type CapabilityRef } from './capability-ref';
+import {
+  GrantConstraintsSchema,
+  type GrantConstraints,
+} from './capability-grant';
+
+export type { GrantConstraints } from './capability-grant';
+export { GrantConstraintsSchema } from './capability-grant';
+
+/**
+ * `CapabilityPolicy` is what an `ExecutionEnvironment` carries to advertise the
+ * capability surface allowed *within* that environment (plan §3.4
+ * `ExecutionEnvironment.allowedCapabilities[]`).
+ *
+ * A environment's policy is a NECESSARY-but-not-sufficient condition for a runtime
+ * call: the environment allows the capability AND the subject has a matching
+ * `CapabilityGrant`. Failing the environment check raises
+ * `CapabilityErrorCode.CapabilityDeniedByZone`; failing the grant check
+ * raises `CapabilityErrorCode.CapabilityDeniedByGrant`.
+ */
+export interface CapabilityPolicy {
+  capability: CapabilityRef;
+  /**
+   * Resource globs allowed in this environment for this capability. The environment's
+   * policy may be stricter than any individual grant; the runtime takes
+   * the intersection at decision time.
+   */
+  allowedResources: readonly string[];
+  constraints?: GrantConstraints;
+}
+
+export const CapabilityPolicySchema = z.object({
+  capability: CapabilityRefSchema,
+  allowedResources: z.array(z.string().min(1)).readonly(),
+  constraints: GrantConstraintsSchema.optional(),
+}) as z.ZodType<CapabilityPolicy>;

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

@@ -0,0 +1,138 @@
+import { z } from 'zod';
+import { CapabilityRefParseError } from './errors';
+
+/**
+ * Canonical Capability Reference grammar (plan §3.3):
+ *
+ *   `<domain>:<resource>.<verb>@<major>`
+ *
+ * Rules — kept deliberately tight so the grammar can never silently absorb
+ * a free-form string:
+ *
+ * - `<domain>` and the first `<resource>` segment match
+ *   `/^[a-z][a-z0-9-]*$/` (kebab, must start with a letter).
+ * - The `<resource>.<verb>` portion is one OR MORE `.`-joined kebab segments
+ *   (each segment matches the same shape as `<domain>`). This permits the
+ *   examples in the plan such as `kb:page.read@1`, `connector:scm.merge@1`,
+ *   `document:render.pdf@1`, `connector:tracker.issue.create@1`, AND
+ *   nested forms such as `model-resolution:select@1` (single segment after
+ *   `:`, where the segment IS the verb on the implicit resource).
+ * - `<major>` is one or more digits (no leading sign, no float). The major
+ *   version is part of the ref itself — capability refs version like
+ *   syscalls per §3.3.
+ *
+ * Invariants enforced by `parseCapabilityRef` / `CapabilityRefSchema`:
+ *
+ * - Lowercase only. `KB:Page.Read@1` is rejected.
+ * - No whitespace, no `/`, no leading `.`, no trailing `.`.
+ * - Empty segments are rejected (`kb:.read@1`, `kb:page..read@1`).
+ * - Major MUST be a positive integer string of `\d+` shape. `@01` is
+ *   accepted as `1` (matched by `\d+`) but parsed via `Number(...)` —
+ *   downstream consumers should NOT round-trip through the string form
+ *   if they want stable formatting; use `formatCapabilityRef` instead.
+ */
+const CAPABILITY_REF_REGEX =
+  /^[a-z][a-z0-9-]*:[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*@\d+$/;
+
+/**
+ * Opaque-ish branded string type. We don't use a TS `unique symbol` brand
+ * because consumers serialize refs over the wire and Zod / JSON cannot carry
+ * a symbol; the template-literal alias still gives editor autocomplete on
+ * literal refs while accepting any string that matches the runtime regex.
+ */
+export type CapabilityRef =
+  `${string}:${string}.${string}@${number}` & {
+    readonly __capabilityRef?: never;
+  };
+
+export const CapabilityRefSchema: z.ZodType<CapabilityRef> = z
+  .string()
+  .regex(CAPABILITY_REF_REGEX, {
+    message:
+      'CapabilityRef must match <domain>:<resource>.<verb>@<major> (lowercase kebab; positive integer major).',
+  }) as unknown as z.ZodType<CapabilityRef>;
+
+export interface ParsedCapabilityRef {
+  readonly domain: string;
+  /** First segment after `:`. For single-segment refs (`x:verb@1`), equals `verbPath[0]`. */
+  readonly resource: string;
+  /**
+   * All `.`-joined segments after `:`, in order. For `kb:page.read@1` this
+   * is `['page', 'read']`. For single-segment refs (`workflow:publish@1`)
+   * this is `['publish']` and the verb is `verbPath[verbPath.length - 1]`.
+   */
+  readonly verbPath: readonly string[];
+  readonly major: number;
+  readonly raw: CapabilityRef;
+}
+
+/**
+ * Parse a `CapabilityRef` string into its structured parts. Throws
+ * `CapabilityRefParseError` (code `CAPABILITY_REF_INVALID`) on any
+ * grammar violation — never returns `null`, never silently coerces.
+ *
+ * Callers that want a non-throwing variant should run `CapabilityRefSchema`
+ * via `safeParse` first and then call `parseCapabilityRef` on the validated
+ * value.
+ */
+export function parseCapabilityRef(ref: string): ParsedCapabilityRef {
+  if (typeof ref !== 'string' || ref.length === 0) {
+    throw new CapabilityRefParseError({
+      message: 'CapabilityRef must be a non-empty string.',
+      raw: String(ref),
+    });
+  }
+  if (!CAPABILITY_REF_REGEX.test(ref)) {
+    throw new CapabilityRefParseError({
+      message: `CapabilityRef "${ref}" does not match <domain>:<resource>.<verb>@<major>.`,
+      raw: ref,
+    });
+  }
+  const atIdx = ref.lastIndexOf('@');
+  const colonIdx = ref.indexOf(':');
+  const domain = ref.slice(0, colonIdx);
+  const verbPath = ref.slice(colonIdx + 1, atIdx).split('.');
+  const majorStr = ref.slice(atIdx + 1);
+  const major = Number(majorStr);
+  if (!Number.isInteger(major) || major <= 0) {
+    throw new CapabilityRefParseError({
+      message: `CapabilityRef "${ref}" has a non-integer major "${majorStr}".`,
+      raw: ref,
+    });
+  }
+  return {
+    domain,
+    resource: verbPath[0]!,
+    verbPath,
+    major,
+    raw: ref as CapabilityRef,
+  };
+}
+
+/**
+ * Format a `CapabilityRef` from its structured parts. Performs the same
+ * validation as `parseCapabilityRef` on the resulting string and throws
+ * `CapabilityRefParseError` if the inputs produce an invalid ref — this
+ * guarantees that every value produced by `formatCapabilityRef` round-trips
+ * through `parseCapabilityRef`.
+ */
+export function formatCapabilityRef(parts: {
+  domain: string;
+  verbPath: readonly string[];
+  major: number;
+}): CapabilityRef {
+  if (parts.verbPath.length === 0) {
+    throw new CapabilityRefParseError({
+      message: 'CapabilityRef verbPath must contain at least one segment.',
+      raw: `${parts.domain}:@${parts.major}`,
+    });
+  }
+  const raw = `${parts.domain}:${parts.verbPath.join('.')}@${parts.major}`;
+  if (!CAPABILITY_REF_REGEX.test(raw)) {
+    throw new CapabilityRefParseError({
+      message: `formatCapabilityRef produced invalid ref "${raw}".`,
+      raw,
+    });
+  }
+  return raw as CapabilityRef;
+}

package/src/capability/lib/errors.ts

@@ -0,0 +1,180 @@
+import { z } from 'zod';
+
+/**
+ * Closed set of capability-layer error codes.
+ *
+ * Every denial returned by the Capability Gateway carries one of these codes
+ * so callers can branch structurally (no string parsing). The set covers:
+ *   - parse-time failures on `CapabilityRef`;
+ *   - resolution failures when no contribution implements the ref;
+ *   - the four distinct denial axes specified in §3.4 + §30.5
+ *     (environment, grant, rate-limit, human-approval);
+ *   - the "you do not even have a grant row" case that drives `xema why-denied`
+ *     suggestion `request-grant` (§31.8).
+ *
+ * Plan-of-record references: §3.3, §30.5, §31.8.
+ */
+export enum CapabilityErrorCode {
+  CapabilityRefInvalid = 'CAPABILITY_REF_INVALID',
+  CapabilityUnresolved = 'CAPABILITY_UNRESOLVED',
+  CapabilityDeniedByZone = 'CAPABILITY_DENIED_BY_ZONE',
+  CapabilityDeniedByGrant = 'CAPABILITY_DENIED_BY_GRANT',
+  CapabilityDeniedByRateLimit = 'CAPABILITY_DENIED_BY_RATE_LIMIT',
+  CapabilityRequiresApproval = 'CAPABILITY_REQUIRES_APPROVAL',
+  CapabilityRequiresGrant = 'CAPABILITY_REQUIRES_GRANT',
+  AuthorizationUnreachable = 'AUTHORIZATION_UNREACHABLE',
+  /**
+   * The invocation passed authorization but its mandatory audit record
+   * could not be persisted after retries (Gate E). The gateway refuses the
+   * invocation rather than completing it without an audit trail — surfaced
+   * as a 503 so the caller can retry (the audit write is idempotent on
+   * `auditId`). This is the fail-fast path for the audit sink; it is NEVER
+   * silently swallowed.
+   */
+  AuditLogUnavailable = 'AUDIT_LOG_UNAVAILABLE',
+  /**
+   * The invocation reached the gateway without a resolvable tenant org.
+   * authorization-api scopes every grant lookup by org; the gateway refuses
+   * at the edge with a precise code instead of letting the missing org
+   * surface as an opaque `AUTHORIZATION_UNREACHABLE` fail-closed denial. The
+   * caller must supply `orgId` (body) or `X-Xema-Org-Id` (header).
+   */
+  CapabilityInvocationMissingOrg = 'CAPABILITY_INVOCATION_MISSING_ORG',
+  /**
+   * The capability ref is owned by a runner-plane provider, but the runner
+   * selector found no live runner that satisfies the policy route hints
+   * (and obligations) for this invocation. Fail-fast — the gateway NEVER
+   * silently allows a runner-owned capability with an empty selection.
+   */
+  NoRunnerAvailable = 'NO_RUNNER_AVAILABLE',
+  /**
+   * The capability needs an external credential to execute (it declares an
+   * `externalServiceRef`), but authorization-api's credential-binding
+   * precedence resolved no permitted binding for this invocation — no explicit
+   * grant binding, no capability-descriptor default, and no project/org
+   * default. Fail-fast (plan §W4 / Pillar 3.2): the PDP returns `deny` with
+   * this code rather than letting the invocation run credential-less or letting
+   * a gateway silently pick a credential. The broker NEVER chooses a binding;
+   * the PDP is the single authority.
+   */
+  MissingCredentialBinding = 'MISSING_CREDENTIAL_BINDING',
+}
+
+export const CapabilityErrorCodeSchema = z.nativeEnum(CapabilityErrorCode);
+
+/**
+ * Discriminated "why" structure for a denial decision. One denial may carry
+ * multiple `CapabilityDenialDetail` entries (e.g. the grant exists but the
+ * resource glob does not match AND the rate-limit is exhausted).
+ *
+ * Plan-of-record reference: §31.8.
+ */
+export interface CapabilityDenialDetail {
+  code: CapabilityErrorCode;
+  detail: string;
+}
+
+export const CapabilityDenialDetailSchema = z.object({
+  code: CapabilityErrorCodeSchema,
+  detail: z.string().min(1),
+}) as z.ZodType<CapabilityDenialDetail>;
+
+/**
+ * Suggestions the Capability Gateway returns so an agent (or a human via
+ * `xema why-denied`) can self-correct without trial-and-error.
+ *
+ * Plan-of-record reference: §31.8.
+ *
+ * The discriminator `kind` is a closed set; do NOT widen with free-form
+ * strings.
+ */
+export type CapabilityDenialSuggestion =
+  | {
+      kind: 'request-grant';
+      capability: string;
+      environment?: string;
+      resource?: string;
+    }
+  | {
+      kind: 'switch-environment';
+      from: string;
+      to: string;
+    }
+  | {
+      kind: 'request-approval';
+      capability: string;
+      approver?: string;
+    };
+
+export const CapabilityDenialSuggestionSchema = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal('request-grant'),
+    capability: z.string().min(1),
+    environment: z.string().min(1).optional(),
+    resource: z.string().min(1).optional(),
+  }),
+  z.object({
+    kind: z.literal('switch-environment'),
+    from: z.string().min(1),
+    to: z.string().min(1),
+  }),
+  z.object({
+    kind: z.literal('request-approval'),
+    capability: z.string().min(1),
+    approver: z.string().min(1).optional(),
+  }),
+]) as z.ZodType<CapabilityDenialSuggestion>;
+
+/**
+ * Structured error thrown by `parseCapabilityRef` and surfaced by the
+ * Capability Gateway. Fields beyond `code` are optional because not every
+ * call site has every piece of context (parse-time errors have no subject /
+ * environment; runtime denials always do).
+ *
+ * Consumers MUST branch on `code` — never on `message` string content.
+ */
+export class CapabilityError extends Error {
+  public readonly code: CapabilityErrorCode;
+  public readonly capability: string | undefined;
+  public readonly subject: string | undefined;
+  public readonly environment: string | undefined;
+  public readonly auditId: string | undefined;
+  public readonly details: readonly CapabilityDenialDetail[] | undefined;
+
+  constructor(args: {
+    code: CapabilityErrorCode;
+    message: string;
+    capability?: string;
+    subject?: string;
+    environment?: string;
+    auditId?: string;
+    details?: readonly CapabilityDenialDetail[];
+  }) {
+    super(args.message);
+    this.name = 'CapabilityError';
+    this.code = args.code;
+    this.capability = args.capability;
+    this.subject = args.subject;
+    this.environment = args.environment;
+    this.auditId = args.auditId;
+    this.details = args.details;
+  }
+}
+
+/**
+ * Narrow `CapabilityError` thrown by `parseCapabilityRef` when the input
+ * does not match the canonical grammar. Always carries
+ * `CapabilityErrorCode.CapabilityRefInvalid`. Provided as a named subclass
+ * so call sites that only want to surface "bad ref" failures can `instanceof`
+ * without first inspecting `.code`.
+ */
+export class CapabilityRefParseError extends CapabilityError {
+  constructor(args: { message: string; raw: string }) {
+    super({
+      code: CapabilityErrorCode.CapabilityRefInvalid,
+      message: args.message,
+      capability: args.raw,
+    });
+    this.name = 'CapabilityRefParseError';
+  }
+}