@xemahq/kernel-contracts 0.2.1 → 0.2.3

package/src/distribution/lib/distribution-lock.ts

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+import {
+  BiomeTierSchema,
+  BiomeTargetSchema,
+  BiomeOriginSchema,
+  type BiomeTier,
+  type BiomeTarget,
+  type BiomeOrigin,
+} from '../../biome';
+
+/**
+ * A single biome as resolved into a distribution lockfile. Version-pinned and
+ * (once images are built) content-addressed. `imageDigest` is populated by the
+ * image-manifest step (`images.lock.json`) and may be absent in the pure biome
+ * lockfile before images are built.
+ */
+export interface LockedBiome {
+  id: string;
+  version: string;
+  tier: BiomeTier;
+  target: BiomeTarget;
+  /** Provenance posture from the manifest (gated by the distribution trustPolicy). */
+  origin: BiomeOrigin;
+  /** Whether the org may disable this biome once shipped (cannot-disable). */
+  mandatory: boolean;
+  /** Source repo + path the biome was resolved from (provenance for the build). */
+  repo: string;
+  path: string;
+  /**
+   * Deployable service names this biome ships (from the manifest `ships.apis[].name`).
+   * Empty for biomes with no deployable API (pure skill/agent bundles) and for
+   * web biomes (which bundle into the host shell, not their own container). This
+   * is what the deployment-roster generator reads — it runs in a standalone
+   * checkout without the biome sources, so the biome→service mapping must travel
+   * inside the lockfile, never be recomputed downstream.
+   */
+  services: readonly string[];
+  /** Set by the image-manifest resolver; `image@sha256:<digest>`. */
+  imageDigest?: string;
+}
+
+export const LockedBiomeSchema = z.object({
+  id: z.string().min(1),
+  version: z.string().min(1),
+  tier: BiomeTierSchema,
+  target: BiomeTargetSchema,
+  origin: BiomeOriginSchema,
+  mandatory: z.boolean(),
+  repo: z.string().min(1),
+  path: z.string().min(1),
+  services: z.array(z.string().min(1)).readonly(),
+  imageDigest: z.string().min(1).optional(),
+}) as z.ZodType<LockedBiome>;
+
+/**
+ * A platform-substrate service that is part of a distribution but is NOT a biome
+ * — the deployment "init system" (kernel server, host shell, opencode worker
+ * plane, docs). These always ship with any Xema deployment that includes the
+ * base layer; they are declared once on the `core` distribution and inherited
+ * via `extends`. Carried into the lock so the roster generator sees the full
+ * service set (biome services ∪ platform services) without any hardcoded floor.
+ */
+export interface LockedPlatformService {
+  name: string;
+  /** Wave/boot tier — drives ordering in the generated bring-up plan. */
+  tier: BiomeTier | 'edge';
+}
+
+export const LockedPlatformServiceSchema = z.object({
+  name: z.string().min(1),
+  tier: z.union([BiomeTierSchema, z.literal('edge')]),
+}) as z.ZodType<LockedPlatformService>;
+
+/**
+ * `DistributionLock` — the deterministic, resolved output of a `Distribution`.
+ * THE single artifact every consumer reads (deploy generator, test-suite
+ * mapping, biome-host boot filter, appliance build). No consumer re-applies the
+ * distribution rules — the lockfile is the hard boundary.
+ *
+ * `resolvedAt` / `inputHash` are stamped by the resolver tooling, not the
+ * kernel (kernel contracts hold no clock); both optional so the type is usable
+ * mid-resolution.
+ */
+export interface DistributionLock {
+  schemaVersion: 1;
+  distributionId: string;
+  biomes: readonly LockedBiome[];
+  /** Non-biome substrate services that ship with this distribution (the deploy "init system"). */
+  platformServices: readonly LockedPlatformService[];
+  /** ISO-8601 timestamp the resolver stamped (tooling-supplied). */
+  resolvedAt?: string;
+  /** Hash of the resolver inputs (manifest + index) for drift detection. */
+  inputHash?: string;
+}
+
+export const DistributionLockSchema = z.object({
+  schemaVersion: z.literal(1),
+  distributionId: z.string().min(1),
+  biomes: z.array(LockedBiomeSchema).readonly(),
+  platformServices: z.array(LockedPlatformServiceSchema).readonly(),
+  resolvedAt: z.string().min(1).optional(),
+  inputHash: z.string().min(1).optional(),
+}) as z.ZodType<DistributionLock>;
+
+/**
+ * Parse + validate a raw `distribution.lock.json`. Fail-fast on any shape error
+ * — the lockfile is the hard boundary every consumer reads, so a malformed lock
+ * must never be silently tolerated.
+ */
+export function parseDistributionLock(raw: unknown): DistributionLock {
+  const result = DistributionLockSchema.safeParse(raw);
+  if (!result.success) {
+    throw new Error(
+      `Invalid distribution.lock.json: ${result.error.issues
+        .map((i) => `[${i.path.join('.')}] ${i.message}`)
+        .join('; ')}`,
+    );
+  }
+  return result.data;
+}

package/src/distribution/lib/distribution-selector.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import {
+  BiomeTierSchema,
+  BiomeOriginSchema,
+  type BiomeTier,
+  type BiomeOrigin,
+} from '../../biome';
+
+/**
+ * A `DistributionSelector` declares which biomes an `include[]` entry pulls
+ * into a distribution. Exactly one of the three forms:
+ *
+ * - `{ tier }`     — every biome of that dependency tier (maps to the manifest
+ *                    `xema.scope` field). NEVER pulls `audience: operator`
+ *                    biomes — those require explicit `{ biome }` naming.
+ * - `{ origin }`   — every biome of that provenance posture (first/third-party).
+ * - `{ biome }`    — one biome by id, optional semver `version` range. This is
+ *                    the ONLY form that can pull an `audience: operator` biome
+ *                    (the "force it in" mechanism for our internal distribution).
+ *
+ * Selector matching is resolved against the global biome index; the resolver,
+ * not any consumer, applies these rules (the lockfile is the hard boundary).
+ */
+export type DistributionSelector =
+  | { tier: BiomeTier }
+  | { origin: BiomeOrigin }
+  | { biome: string; version?: string };
+
+export const DistributionSelectorSchema = z.union([
+  z.object({ tier: BiomeTierSchema }).strict(),
+  z.object({ origin: BiomeOriginSchema }).strict(),
+  z
+    .object({ biome: z.string().min(1), version: z.string().min(1).optional() })
+    .strict(),
+]) as z.ZodType<DistributionSelector>;

package/src/distribution/lib/distribution.ts

@@ -0,0 +1,108 @@
+import { z } from 'zod';
+import { BiomeOriginSchema, type BiomeOrigin } from '../../biome';
+import {
+  DistributionSelectorSchema,
+  type DistributionSelector,
+} from './distribution-selector';
+
+/**
+ * Schema-versioning seed for `xema-distribution.json`. Bumped via a coordinated
+ * PR on an incompatible shape change; consumers refuse versions they do not
+ * understand (fail-fast — no best-effort parse).
+ */
+export type DistributionSchemaVersion = 1;
+
+/**
+ * Trust policy of a distribution — gates which provenance postures may ship.
+ * E.g. a locked appliance distribution allows only `first-party`. Gates on
+ * `BiomeOrigin` (the posture carried on the manifest at build time), NOT on
+ * the richer install-time `BiomeTrustTier`.
+ */
+export interface DistributionTrustPolicy {
+  allow: readonly BiomeOrigin[];
+}
+
+export const DistributionTrustPolicySchema = z.object({
+  allow: z.array(BiomeOriginSchema).readonly(),
+}) as z.ZodType<DistributionTrustPolicy>;
+
+/**
+ * A platform-substrate service a distribution ships that is NOT a biome — the
+ * deployment "init system" (kernel server, host shell, opencode worker plane,
+ * docs). Declared once on the floor distribution (`core`) and inherited via
+ * `extends`. These never go through biome selectors (they are not biomes); they
+ * are carried verbatim into the lock so the deployment-roster generator sees the
+ * full service set without any hardcoded floor in the generator.
+ */
+export interface DistributionPlatformService {
+  name: string;
+  /** Wave/boot tier — drives ordering in the generated bring-up plan. */
+  tier: 'kernel' | 'system' | 'base' | 'platform' | 'edge';
+}
+
+export const DistributionPlatformServiceSchema = z.object({
+  name: z.string().min(1),
+  tier: z.enum(['kernel', 'system', 'base', 'platform', 'edge']),
+}) as z.ZodType<DistributionPlatformService>;
+
+/**
+ * `Distribution` — the top-level shape of `xema-distribution.json`: the
+ * PACKAGING primitive that declares which biomes a given Xema build ships.
+ *
+ * This is orthogonal to a biome's dependency tier (`BiomeTier`) and to where it
+ * is deployed (the deployment plane). It contains PACKAGING fields only — no
+ * infra/deploy/values config (that lives in the deployment overlay).
+ *
+ * Composition: `extends` names a parent distribution; the resolver composes
+ * parent → child, with the child's `include`/`exclude` overriding. The resolver
+ * enforces (fail-fast): kernel-tier biomes are always included and cannot be
+ * excluded; an included biome whose `requires` are absent is an error; selectors
+ * never pull `audience: operator` biomes. The deterministic resolved output is a
+ * `DistributionLock` — the single artifact every consumer reads.
+ */
+export interface Distribution {
+  schemaVersion: DistributionSchemaVersion;
+  id: string;
+  displayName: string;
+  description?: string;
+  /** Parent distribution id this one composes onto. */
+  extends?: string;
+  include: readonly DistributionSelector[];
+  /** Biome ids to remove after composition. Cannot remove a kernel-tier biome. */
+  exclude?: readonly string[];
+  trustPolicy?: DistributionTrustPolicy;
+  /**
+   * Non-biome substrate services this distribution ships (the deploy "init
+   * system"). Composed parent→child like `include` (concatenated, de-duped by
+   * name with the child winning on tier). Usually declared only on `core`.
+   */
+  platformServices?: readonly DistributionPlatformService[];
+}
+
+export const DistributionSchema = z.object({
+  schemaVersion: z.literal(1),
+  id: z.string().min(1),
+  displayName: z.string().min(1),
+  description: z.string().min(1).optional(),
+  extends: z.string().min(1).optional(),
+  include: z.array(DistributionSelectorSchema).readonly(),
+  exclude: z.array(z.string().min(1)).readonly().optional(),
+  trustPolicy: DistributionTrustPolicySchema.optional(),
+  platformServices: z.array(DistributionPlatformServiceSchema).readonly().optional(),
+}) as z.ZodType<Distribution>;
+
+/**
+ * Parse + validate a raw `xema-distribution.json`. Fail-fast on any shape error
+ * — never best-effort. Mirrors `parseBiomeManifest`.
+ */
+export function parseDistribution(raw: unknown): Distribution {
+  const result = DistributionSchema.safeParse(raw);
+  if (!result.success) {
+    throw new Error(
+      `Invalid xema-distribution.json: ${result.error.issues
+        .map((i) => `[${i.path.join('.')}] ${i.message}`)
+        .join('; ')}`,
+    );
+  }
+  return result.data;
+}

package/src/distribution/lib/image-lock.ts

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+import { BiomeTargetSchema, type BiomeTarget } from '../../biome';
+
+/**
+ * A single deployable image as resolved by the image-manifest step
+ * (`images.lock.json`). Images are CONTENT-ADDRESSED: `contentHash` is a
+ * deterministic sha256 over the biome's source directory tree, so the SAME
+ * biome source produces the SAME hash (and therefore the same image tag)
+ * across every customer/distribution. This is the delta key — CI builds an
+ * image only when its `contentHash` is not already present in the registry.
+ *
+ * `imageRef` is the untagged repository reference; the build-time tag is
+ * `${imageRef}:${contentHash}`.
+ */
+export interface LockedImage {
+  /** The biome this image is built from. */
+  biomeId: string;
+  /** Runtime surface — only `server` biomes produce a container image. */
+  target: BiomeTarget;
+  /** Untagged image repository reference, e.g. `ghcr.io/xema-dev/<biomeId>`. */
+  imageRef: string;
+  /** sha256 over the biome source tree — identical source ⇒ identical hash. */
+  contentHash: string;
+  /** Source repo segment the biome was resolved from (provenance for the build). */
+  repo: string;
+  /** Source directory path (repo-root-relative) the biome was resolved from. */
+  path: string;
+}
+
+export const LockedImageSchema = z.object({
+  biomeId: z.string().min(1),
+  target: BiomeTargetSchema,
+  imageRef: z.string().min(1),
+  contentHash: z.string().min(1),
+  repo: z.string().min(1),
+  path: z.string().min(1),
+}) as z.ZodType<LockedImage>;
+
+/**
+ * A web biome that ships in a distribution. Web biomes do NOT produce their own
+ * container image — they are static frontend bundles compiled INTO the single
+ * host-shell image (`xema-host-web`). They are listed here explicitly (never
+ * silently dropped) so the host-shell build knows exactly which web biomes to
+ * bundle for this distribution: the lockfile is the join key for the frontend
+ * too, not just the backend.
+ */
+export interface LockedWebBiome {
+  biomeId: string;
+  /** Source repo segment the web biome was resolved from. */
+  repo: string;
+  /** Source directory path (repo-root-relative) the web biome was resolved from. */
+  path: string;
+}
+
+export const LockedWebBiomeSchema = z.object({
+  biomeId: z.string().min(1),
+  repo: z.string().min(1),
+  path: z.string().min(1),
+}) as z.ZodType<LockedWebBiome>;
+
+/**
+ * `ImageLock` — the deterministic, content-addressed image manifest for a
+ * distribution. Resolved from `distribution.lock.json` by the image-manifest
+ * tooling; the delta-build planner reads it to decide which images are NEW vs
+ * already-built. Like `DistributionLock`, `resolvedAt` is stamped by the
+ * tooling (kernel contracts hold no clock) and is optional so the type is
+ * usable mid-resolution.
+ */
+export interface ImageLock {
+  schemaVersion: 1;
+  distributionId: string;
+  images: readonly LockedImage[];
+  /** Web biomes bundled into the host-shell image (no own container). */
+  webBiomes: readonly LockedWebBiome[];
+  /** ISO-8601 timestamp the resolver stamped (tooling-supplied). */
+  resolvedAt?: string;
+}
+
+export const ImageLockSchema = z.object({
+  schemaVersion: z.literal(1),
+  distributionId: z.string().min(1),
+  images: z.array(LockedImageSchema).readonly(),
+  webBiomes: z.array(LockedWebBiomeSchema).readonly(),
+  resolvedAt: z.string().min(1).optional(),
+}) as z.ZodType<ImageLock>;
+
+/**
+ * Parse + validate a raw `images.lock.json`. Fail-fast on any shape error —
+ * the image lock is the hard boundary the delta-build planner reads, so a
+ * malformed lock must never be silently tolerated.
+ */
+export function parseImageLock(raw: unknown): ImageLock {
+  const result = ImageLockSchema.safeParse(raw);
+  if (!result.success) {
+    throw new Error(
+      `Invalid images.lock.json: ${result.error.issues
+        .map((i) => `[${i.path.join('.')}] ${i.message}`)
+        .join('; ')}`,
+    );
+  }
+  return result.data;
+}

package/src/inquiry/lib/enums.ts

@@ -101,3 +101,16 @@ export enum InquiryTimeoutAction {
   APPROVE = 'approve',
   ESCALATE = 'escalate',
 }
+
+/**
+ * Terminal action when an inquiry's `escalationChain` is exhausted (the
+ * final step's deadline passed with no terminal verdict). A deliberately
+ * NARROWER closed set than `InquiryTimeoutAction`: `ESCALATE` is not
+ * representable here — escalating past the last chain step would be an
+ * infinite loop. Defaults to `REJECT` so a misconfigured chain never
+ * silently approves.
+ */
+export enum EscalationExhaustionAction {
+  REJECT = 'reject',
+  APPROVE = 'approve',
+}

package/src/inquiry/lib/inquiry.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 
 import {
+  EscalationExhaustionAction,
   InquiryKind,
   InquiryRecipientStatus,
   InquiryStatus,
@@ -51,6 +52,17 @@ export const InquirySchema = z.object({
   workflowRunId: z.string().min(1),
   jobRunId: z.string().min(1),
   kind: z.nativeEnum(InquiryKind),
+  /**
+   * Optional domain approval-card discriminator. Distinct from the
+   * structural `kind` (which selects policy + gate semantics): an
+   * `inquiryKind` selects a biome-contributed approval-card variant
+   * (custom fields + verdict shape) on the FE and a domain descriptor on
+   * the engine. `null`/absent = the generic card for the structural
+   * `kind`, which is a valid state — never a silent error. When present,
+   * the value MUST match a `ContributionKind.InquiryKind` descriptor
+   * registered with the engine (validated fail-fast at create time).
+   */
+  inquiryKind: z.string().min(1).nullable(),
   title: z.string(),
   prompt: z.record(z.string(), z.unknown()),
   policy: ReplyPolicySchema,
@@ -66,10 +78,10 @@ export const InquirySchema = z.object({
   /**
    * Action when the escalation chain is exhausted (i.e. the final
    * step's deadline passes with no terminal verdict). Closed set:
-   * `REJECT` (default) or `APPROVE`. `ESCALATE` is rejected here at
-   * the schema level — would be a runtime infinite loop.
+   * `REJECT` (default) or `APPROVE`. `ESCALATE` is not representable —
+   * escalating past the last chain step would be a runtime infinite loop.
    */
-  onEscalationExhaustion: z.enum(['reject', 'approve']),
+  onEscalationExhaustion: z.nativeEnum(EscalationExhaustionAction),
   /**
    * Zero-based pointer into `escalationChain`. Bumped each time the
    * engine advances. `0` means "still on the original recipients";
@@ -120,6 +132,12 @@ export const CreateInquiryInputSchema = z
     workflowRunId: z.string().min(1),
     jobRunId: z.string().min(1),
     kind: z.nativeEnum(InquiryKind),
+    /**
+     * Optional domain approval-card discriminator (see `InquirySchema`).
+     * Omitted = generic card for the structural `kind`. When present, the
+     * engine refuses an unregistered value fail-fast.
+     */
+    inquiryKind: z.string().min(1).optional(),
     title: z.string(),
     prompt: z.record(z.string(), z.unknown()),
     policy: ReplyPolicySchema,
@@ -127,7 +145,7 @@ export const CreateInquiryInputSchema = z
     expiresAtIso: z.string(),
     onTimeout: z.nativeEnum(InquiryTimeoutAction),
     escalationChain: z.array(EscalationStepSchema).optional(),
-    onEscalationExhaustion: z.enum(['reject', 'approve']).optional(),
+    onEscalationExhaustion: z.nativeEnum(EscalationExhaustionAction).optional(),
   })
   .superRefine((value, ctx) => {
     // ESCALATE without a chain is meaningless — would have to fall back

package/src/invocation/index.ts

@@ -0,0 +1,9 @@
+export * from './lib/invocation-mode';
+export * from './lib/isolation-level';
+export * from './lib/invocation-status';
+export * from './lib/invocation-priority';
+export * from './lib/execution-requirements';
+export * from './lib/invocation-decision';
+export * from './lib/invoke-request';
+export * from './lib/invoke-response';
+export * from './lib/invocation-record';

package/src/invocation/lib/execution-requirements.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { InvocationMode, InvocationModeSchema } from './invocation-mode';
+import { IsolationLevel, IsolationLevelSchema } from './isolation-level';
+import {
+  InvocationPriority,
+  InvocationPrioritySchema,
+} from './invocation-priority';
+
+/**
+ * Per-invocation hard limits. None are required at the contract level; an
+ * absent field means "no caller-declared limit on this axis" (the platform may
+ * still apply its own). These map directly onto the existing `composition.limits`
+ * consumed by `CompositionBudgetEnforcer` — no new enforcement engine.
+ */
+export interface InvocationLimits {
+  readonly maxDurationMs?: number;
+  readonly maxTokens?: number;
+  readonly maxToolCalls?: number;
+  readonly maxRetries?: number;
+  readonly maxCostUsd?: number;
+}
+
+export const InvocationLimitsSchema = z.object({
+  maxDurationMs: z.number().int().nonnegative().optional(),
+  maxTokens: z.number().int().nonnegative().optional(),
+  maxToolCalls: z.number().int().nonnegative().optional(),
+  maxRetries: z.number().int().nonnegative().optional(),
+  maxCostUsd: z.number().nonnegative().optional(),
+}) as z.ZodType<InvocationLimits>;
+
+/**
+ * What a biome DECLARES about how its invocation should run; the platform
+ * ENFORCES. `mode` is a hint the platform may override by policy; `isolation`
+ * defaults to `Strict` (fresh thread per invocation).
+ */
+export interface ExecutionRequirements {
+  /** Hint; the platform may override the execution mode by policy. */
+  readonly mode?: InvocationMode;
+  /** Thread-context isolation; default `Strict`. */
+  readonly isolation: IsolationLevel;
+  readonly latencyTargetMs?: number;
+  readonly priority?: InvocationPriority;
+  /** Strategy / modelClass hint for model resolution. */
+  readonly modelCapability?: string;
+  /** Deliverable-spec / JSON-schema ref the root output is validated against. */
+  readonly outputSchemaRef?: string;
+  readonly idempotencyKey?: string;
+  /** Maps to the existing `composition.limits` budget axes. */
+  readonly limits?: InvocationLimits;
+}
+
+export const ExecutionRequirementsSchema = z.object({
+  mode: InvocationModeSchema.optional(),
+  isolation: IsolationLevelSchema,
+  latencyTargetMs: z.number().int().nonnegative().optional(),
+  priority: InvocationPrioritySchema.optional(),
+  modelCapability: z.string().min(1).optional(),
+  outputSchemaRef: z.string().min(1).optional(),
+  idempotencyKey: z.string().min(1).optional(),
+  limits: InvocationLimitsSchema.optional(),
+}) as z.ZodType<ExecutionRequirements>;

package/src/invocation/lib/invocation-decision.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+
+/**
+ * One structured decision produced by a composition invocation. An invocation
+ * MAY emit multiple decisions (e.g. a classify step and a route step).
+ *
+ * `kind` is free-form at the contract layer because the set of decision kinds
+ * is open and biome-owned (e.g. `'classification'`, `'route'`); the runtime
+ * does not interpret it. `payload` carries the decision body verbatim.
+ */
+export interface InvocationDecision {
+  readonly kind: string;
+  readonly payload: Record<string, unknown>;
+  readonly confidence?: number;
+}
+
+export const InvocationDecisionSchema = z.object({
+  kind: z.string().min(1),
+  payload: z.record(z.string(), z.unknown()),
+  confidence: z.number().optional(),
+}) as z.ZodType<InvocationDecision>;

package/src/invocation/lib/invocation-mode.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+
+/**
+ * How the Composition Invocation Runtime executes an invocation.
+ *
+ * The platform owns mode selection (deterministic `selectMode`): a biome MAY
+ * hint a mode via `ExecutionRequirements.mode`, but policy may override it.
+ *
+ * - `Sync` — the caller holds the request open until the composition produces
+ *   its root structured output. The smallest correct slice (Phase 1).
+ * - `Async` — the runtime returns immediately with a `Queued`/`Running`
+ *   invocation; the caller polls the Invocation record for the terminal state.
+ * - `Event` — the runtime returns without an `output`; the result is delivered
+ *   later as a completion event the consumer subscribes to (the default at
+ *   high throughput).
+ *
+ * Closed set — adding a mode is a coordinated kernel change so producer and
+ * consumer stay in lockstep.
+ */
+export enum InvocationMode {
+  Sync = 'sync',
+  Async = 'async',
+  Event = 'event',
+}
+
+export const InvocationModeSchema = z.nativeEnum(InvocationMode);

package/src/invocation/lib/invocation-priority.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+
+/**
+ * Scheduling priority a biome may hint on an invocation. The platform owns the
+ * actual queue ordering; this is an advisory dimension carried on
+ * `ExecutionRequirements`.
+ *
+ * Closed set — adding a priority is a coordinated kernel change.
+ */
+export enum InvocationPriority {
+  Low = 'low',
+  Normal = 'normal',
+  High = 'high',
+}
+
+export const InvocationPrioritySchema = z.nativeEnum(InvocationPriority);

package/src/invocation/lib/invocation-record.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import { InvocationMode, InvocationModeSchema } from './invocation-mode';
+import { InvocationStatus, InvocationStatusSchema } from './invocation-status';
+import {
+  InvocationDecision,
+  InvocationDecisionSchema,
+} from './invocation-decision';
+
+/**
+ * The durable Invocation unit — the projection of one row the runtime persists
+ * per invocation. This is the source of truth for an invocation's lifecycle
+ * (never the underlying session).
+ *
+ * `inputRef`/`outputRef` are blob/JSON references (inline JSON in Phase 1,
+ * artifact-store refs once payloads grow). Timestamps are ISO-8601 strings.
+ */
+export interface InvocationRecord {
+  readonly id: string;
+  readonly compositionRef: string;
+  readonly orgId: string;
+  readonly projectId: string | null;
+  readonly threadKey: string;
+  readonly correlationId: string;
+  readonly idempotencyKey: string | null;
+  readonly mode: InvocationMode;
+  readonly status: InvocationStatus;
+  readonly inputRef: string;
+  readonly outputRef: string | null;
+  readonly decisions: readonly InvocationDecision[];
+  readonly costUsd: number | null;
+  readonly durationMs: number | null;
+  readonly modelRef: string | null;
+  readonly auditId: string | null;
+  readonly sessionId: string | null;
+  readonly createdAt: string;
+  readonly lastActiveAt: string;
+}
+
+export const InvocationRecordSchema = z.object({
+  id: z.string().min(1),
+  compositionRef: z.string().min(1),
+  orgId: z.string().min(1),
+  projectId: z.string().min(1).nullable(),
+  threadKey: z.string().min(1),
+  correlationId: z.string().min(1),
+  idempotencyKey: z.string().min(1).nullable(),
+  mode: InvocationModeSchema,
+  status: InvocationStatusSchema,
+  inputRef: z.string().min(1),
+  outputRef: z.string().min(1).nullable(),
+  decisions: z.array(InvocationDecisionSchema).readonly(),
+  costUsd: z.number().nullable(),
+  durationMs: z.number().nullable(),
+  modelRef: z.string().min(1).nullable(),
+  auditId: z.string().min(1).nullable(),
+  sessionId: z.string().min(1).nullable(),
+  createdAt: z.string().min(1),
+  lastActiveAt: z.string().min(1),
+}) as z.ZodType<InvocationRecord>;

package/src/invocation/lib/invocation-status.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+
+/**
+ * The runtime's durable invocation lifecycle.
+ *
+ * DISTINCT from the capability gateway's allow/deny `InvocationStatus`: the
+ * funnel decides whether a call is allowed; THIS status tracks the execution
+ * lifecycle of an allowed invocation. Do not conflate the two.
+ *
+ * - `Pending` — record created, not yet scheduled.
+ * - `Queued` — accepted onto an async/event queue.
+ * - `Running` — the composition is executing.
+ * - `Succeeded` — terminal: produced a schema-valid output.
+ * - `Failed` — terminal: execution or output-schema validation failed.
+ * - `Denied` — terminal: refused (e.g. by policy/limits) before/at execution.
+ * - `TimedOut` — terminal: exceeded a hard duration limit.
+ * - `Cancelled` — terminal: cancelled by a caller/operator.
+ *
+ * Closed set — adding a state is a coordinated kernel change.
+ */
+export enum InvocationStatus {
+  Pending = 'pending',
+  Queued = 'queued',
+  Running = 'running',
+  Succeeded = 'succeeded',
+  Failed = 'failed',
+  Denied = 'denied',
+  TimedOut = 'timed-out',
+  Cancelled = 'cancelled',
+}
+
+export const InvocationStatusSchema = z.nativeEnum(InvocationStatus);