@xemahq/kernel-contracts 0.2.2 → 0.3.0

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

@@ -26,6 +26,15 @@ export interface LockedBiome {
   /** 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;
 }
@@ -39,9 +48,29 @@ export const LockedBiomeSchema = z.object({
   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
@@ -56,6 +85,8 @@ 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. */
@@ -66,6 +97,7 @@ 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>;

package/src/distribution/lib/distribution.ts

@@ -26,6 +26,25 @@ 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.
@@ -52,6 +71,12 @@ export interface Distribution {
   /** 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({
@@ -63,6 +88,7 @@ export const DistributionSchema = z.object({
   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>;
 
 /**

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

@@ -36,6 +36,28 @@ export const LockedImageSchema = z.object({
   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
@@ -48,6 +70,8 @@ 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;
 }
@@ -56,6 +80,7 @@ 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>;
 

package/src/widget/index.ts

@@ -0,0 +1,4 @@
+export * from './lib/chat-widget-kind';
+export * from './lib/chat-widget-payloads';
+export * from './lib/chat-widget-envelope';
+export * from './lib/widget-contribution';

package/src/widget/lib/chat-widget-envelope.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+
+/**
+ * `ChatWidgetEnvelope` — a single widget instance recorded on an assistant
+ * message's `metadata.widgets[]` and rendered by the host-web ChatWidget
+ * registry (HANDOFF §3.2).
+ *
+ * `kind` is a first-party {@link ChatWidgetKind} value OR a namespaced biome
+ * string (`<biomeId>:<kind>`). `version` is the monotonic schema version for
+ * THIS kind — the FE renders the registered renderer when `version <=
+ * supportedVersion`, else a safe fallback card. `payload` is the kind-specific
+ * payload (validated by the producer against the kind's schema; the FE
+ * re-validates before render so a malformed payload renders the fallback rather
+ * than being dropped).
+ *
+ * This is the kernel-canonical mirror of the FE `ChatWidgetEnvelope` interface
+ * — keep the shapes value-identical.
+ */
+export interface ChatWidgetEnvelope {
+  readonly kind: string;
+  readonly version: number;
+  readonly payload: unknown;
+}
+
+/** Zod validator for {@link ChatWidgetEnvelope}. */
+export const ChatWidgetEnvelopeSchema: z.ZodType<ChatWidgetEnvelope> = z.object({
+  kind: z.string().min(1),
+  version: z.number().int().positive(),
+  payload: z.unknown(),
+});
+
+/**
+ * Why a widget fell back to the safe card — populated on the FE resolved
+ * decision so the Studio debugger can see WHY. Mirror of the FE
+ * `ChatWidgetFallbackReason`. Closed set.
+ */
+export enum ChatWidgetFallbackReason {
+  UnknownKind = 'unknown-kind',
+  InvalidPayload = 'invalid-payload',
+  UnsupportedVersion = 'unsupported-version',
+}

package/src/widget/lib/chat-widget-kind.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+
+/**
+ * `ChatWidgetKind` — the closed first-party set of rich in-chat widget kinds an
+ * agent may render through the generic `render_widget` tool (see the Xema OS
+ * ChatWidget feature). Each kind is a GENERIC, domain-agnostic presentation
+ * primitive — chosen to cover the broadest possible range of "structured thing
+ * the agent wants to show the user" without baking in any vertical semantics.
+ *
+ * ── Value-identity invariant ────────────────────────────────────────────────
+ * This enum is the kernel-canonical mirror of the host-web FE model
+ * (`submodules/xema-host-web/src/views/project/sessions/thin/chat-widget-model.ts`,
+ * `ChatWidgetKind`). The two MUST stay value-identical: the FE consumes this
+ * contract via the frontend-bridge sync, and the registry resolves a payload to
+ * a renderer by matching `kind`. Adding a generic kind = add the enum member in
+ * BOTH places (the "2-file rule") plus a payload schema below.
+ *
+ * ── Closed first-party set vs. open biome set ───────────────────────────────
+ * A biome contributes its OWN widget kind as a namespaced string
+ * (`<biomeId>:<kind>`) through a `widget-kind` contribution — it never extends
+ * this enum. This mirrors the closed-enum + open-namespaced-string pattern used
+ * by the FE registry's `registerChatWidget`.
+ */
+export enum ChatWidgetKind {
+  /** A checklist / plan (todo items with status). The agent's "here's the plan". */
+  Plan = 'plan',
+  /** A single-file unified diff (path + hunks). "Here's the change I propose." */
+  Diff = 'diff',
+  /** A suspended capability call awaiting human approval, keyed by approval id. */
+  Approval = 'approval',
+  /** A generic columns + rows table. The universal "show me structured records". */
+  Table = 'table',
+  /** A compact bar/line chart over labelled series. "Visualise these numbers." */
+  Chart = 'chart',
+  /** A header-only file-change summary (path + add/del counts), no hunks. */
+  FileEdit = 'file-edit',
+}
+
+/** Zod mirror of {@link ChatWidgetKind} for wire-boundary validation. */
+export const ChatWidgetKindSchema = z.nativeEnum(ChatWidgetKind);
+
+/**
+ * The chart shapes the first-party `chart` widget can draw. Closed set — kept
+ * value-identical with the FE's `ChatChartKind`.
+ */
+export enum ChatChartKind {
+  Bar = 'bar',
+  Line = 'line',
+}
+
+export const ChatChartKindSchema = z.nativeEnum(ChatChartKind);

package/src/widget/lib/chat-widget-payloads.ts

@@ -0,0 +1,130 @@
+import { z } from 'zod';
+
+import { ChatChartKindSchema, ChatWidgetKind } from './chat-widget-kind';
+
+/**
+ * Per-kind payload contracts for the first-party {@link ChatWidgetKind} set.
+ *
+ * These schemas are the WIRE contract the `render_widget` tool validates against
+ * before a widget envelope is recorded onto an assistant message's
+ * `metadata.widgets[]`. They are kept STRUCTURALLY value-identical with the FE
+ * narrowing validators in
+ * `submodules/xema-host-web/src/views/project/sessions/thin/chat-widget-builtins.tsx`
+ * — the FE re-validates client-side (so a future/unknown payload still routes to
+ * the safe fallback card), but the runtime fails fast on a bad payload so a
+ * malformed widget never reaches the transcript.
+ *
+ * Zero runtime deps beyond zod (kernel-leaf invariant).
+ */
+
+/** Mirror of the FE `TodoState` (session-kit). Closed set. */
+export enum WidgetTodoState {
+  Todo = 'todo',
+  Active = 'active',
+  Done = 'done',
+}
+export const WidgetTodoStateSchema = z.nativeEnum(WidgetTodoState);
+
+/** A single plan/checklist item. Mirrors session-kit `TodoItem`. */
+export const PlanWidgetItemSchema = z.object({
+  label: z.string().min(1),
+  state: WidgetTodoStateSchema,
+});
+
+/** `plan` payload — a titled checklist of todo items. */
+export const PlanWidgetPayloadSchema = z.object({
+  title: z.string().optional(),
+  items: z.array(PlanWidgetItemSchema),
+});
+export type PlanWidgetPayload = z.infer<typeof PlanWidgetPayloadSchema>;
+
+/**
+ * `diff` payload — a single-file unified diff. `hunks` are raw diff lines whose
+ * first character is the marker (`+`/`-`/space). Mirrors session-kit `DiffFile`.
+ */
+export const DiffWidgetPayloadSchema = z.object({
+  path: z.string().min(1),
+  add: z.number(),
+  del: z.number(),
+  hunks: z.array(z.string()).optional(),
+});
+export type DiffWidgetPayload = z.infer<typeof DiffWidgetPayloadSchema>;
+
+/** `file-edit` payload — a header-only file change summary (no hunks). */
+export const FileEditWidgetPayloadSchema = z.object({
+  path: z.string().min(1),
+  summary: z.string().optional(),
+  add: z.number(),
+  del: z.number(),
+});
+export type FileEditWidgetPayload = z.infer<typeof FileEditWidgetPayloadSchema>;
+
+/**
+ * `approval` payload — the suspended capability call awaiting approval, keyed by
+ * the session it belongs to. The FE mounts the same Pillar-3 inline approval
+ * card from this id.
+ */
+export const ApprovalWidgetPayloadSchema = z.object({
+  sessionId: z.string().min(1),
+  accent: z.string().optional(),
+});
+export type ApprovalWidgetPayload = z.infer<typeof ApprovalWidgetPayloadSchema>;
+
+/** A `table` column descriptor. */
+export const TableWidgetColumnSchema = z.object({
+  key: z.string().min(1),
+  label: z.string().min(1),
+});
+
+/** `table` payload — generic columns + rows. Cells are strings or numbers. */
+export const TableWidgetPayloadSchema = z.object({
+  columns: z.array(TableWidgetColumnSchema),
+  rows: z.array(z.record(z.string(), z.union([z.string(), z.number()]))),
+});
+export type TableWidgetPayload = z.infer<typeof TableWidgetPayloadSchema>;
+
+/** A single chart series (one bar/line group). */
+export const ChartWidgetSeriesSchema = z.object({
+  label: z.string().min(1),
+  points: z.array(z.object({ x: z.string(), y: z.number() })),
+});
+
+/** `chart` payload — a compact bar/line chart over labelled series. */
+export const ChartWidgetPayloadSchema = z.object({
+  kind: ChatChartKindSchema,
+  series: z.array(ChartWidgetSeriesSchema),
+});
+export type ChartWidgetPayload = z.infer<typeof ChartWidgetPayloadSchema>;
+
+/**
+ * The closed registry of first-party kind → payload schema. The single source
+ * of truth the `render_widget` tool & runtime use to validate a first-party
+ * widget payload by `kind`. Adding a generic kind = one enum member + one schema
+ * here + the FE mirror (the "2-file rule").
+ */
+export const FIRST_PARTY_WIDGET_PAYLOAD_SCHEMAS: Readonly<
+  Record<ChatWidgetKind, z.ZodTypeAny>
+> = {
+  [ChatWidgetKind.Plan]: PlanWidgetPayloadSchema,
+  [ChatWidgetKind.Diff]: DiffWidgetPayloadSchema,
+  [ChatWidgetKind.Approval]: ApprovalWidgetPayloadSchema,
+  [ChatWidgetKind.Table]: TableWidgetPayloadSchema,
+  [ChatWidgetKind.Chart]: ChartWidgetPayloadSchema,
+  [ChatWidgetKind.FileEdit]: FileEditWidgetPayloadSchema,
+};
+
+/**
+ * The current schema version for each first-party kind. Bumped when a kind's
+ * payload schema changes shape; the FE renders the registered renderer only
+ * when `envelope.version <= supportedVersion`, else the safe fallback.
+ */
+export const FIRST_PARTY_WIDGET_VERSIONS: Readonly<
+  Record<ChatWidgetKind, number>
+> = {
+  [ChatWidgetKind.Plan]: 1,
+  [ChatWidgetKind.Diff]: 1,
+  [ChatWidgetKind.Approval]: 1,
+  [ChatWidgetKind.Table]: 1,
+  [ChatWidgetKind.Chart]: 1,
+  [ChatWidgetKind.FileEdit]: 1,
+};

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

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+
+/**
+ * Manifest shape carried by every `ContributionKind.WidgetKind` envelope.
+ *
+ * One contribution = one widget kind. The shape mirrors
+ * `CapabilityContributionManifest` (see `../capability/lib/capability-contribution.ts`)
+ * so the generic `BootstrapContributionsService<TKind, TManifest>` template and
+ * the codemod can ingest it the same way every other contribution kind is
+ * ingested. Provenance (`biomeId`, `biomeVersion`) is stamped by the bootstrap
+ * pipeline from the discovering biome's manifest — authors do NOT declare it
+ * inline.
+ *
+ * A biome contributes a widget kind so its frontend biome can register a
+ * renderer for it via `registerChatWidget('<biomeId>:<kind>', …)`. The
+ * `kind` here is the BARE, biome-local kind slug; the catalogue namespaces it
+ * to `<biomeId>:<kind>` at ingest so it can never shadow a first-party kind.
+ *
+ * Validation is fail-fast: a contribution that violates any constraint is
+ * rejected at boot. `payloadSchema` is an opaque JSON Schema passed through
+ * verbatim (the catalogue surfaces it to the FE and to authoring tools; it is
+ * NOT a kernel-validated shape — validating it as JSON Schema here would be
+ * either partial or pull in a JSON-Schema validator, violating the kernel-leaf
+ * invariant).
+ */
+export interface WidgetContributionManifest {
+  /**
+   * Biome-local kind slug (lowercase, hyphenated). Namespaced to
+   * `<biomeId>:<kind>` by the catalogue — a biome can never claim a bare
+   * first-party kind.
+   */
+  readonly kind: string;
+  /** Monotonic schema version for this kind's payload. */
+  readonly version: number;
+  /** Human-readable display name surfaced in the catalogue (≤ 200 chars). */
+  readonly displayName: string;
+  /** One-line summary of WHAT the widget shows + WHEN to use it (≤ 1000 chars). */
+  readonly summary: string;
+  /** JSON Schema for the widget payload — passed through verbatim. */
+  readonly payloadSchema: Record<string, unknown>;
+}
+
+const WIDGET_KIND_SLUG_REGEX = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * Zod validator for {@link WidgetContributionManifest}. The bootstrap template
+ * and the catalogue's `POST /widget-kinds/register` route BOTH route every
+ * candidate manifest through this before persisting, so a malformed
+ * contribution fails at the boundary instead of at render time.
+ */
+export const WidgetContributionManifestSchema: z.ZodType<WidgetContributionManifest> =
+  z.object({
+    kind: z
+      .string()
+      .min(1)
+      .max(100)
+      .regex(
+        WIDGET_KIND_SLUG_REGEX,
+        'Widget kind slug must be lowercase letters, digits, and hyphens (start with a letter).',
+      ),
+    version: z.number().int().positive(),
+    displayName: z.string().min(1).max(200),
+    summary: z.string().min(1).max(1000),
+    payloadSchema: z.record(z.string(), z.unknown()),
+  }) as z.ZodType<WidgetContributionManifest>;
+
+/**
+ * A resolved widget-kind catalogue entry — what `GET /widget-kinds` returns. It
+ * unifies the closed first-party set and the open biome-contributed set behind
+ * ONE shape the FE consumes to know which kinds exist (and to register
+ * biome-contributed kinds into the open FE registry).
+ *
+ * `source` discriminates provenance; `kind` is the FULLY-NAMESPACED slug the FE
+ * registry keys by (a first-party kind is its bare enum value; a biome kind is
+ * `<biomeId>:<kind>`).
+ */
+export interface WidgetKindCatalogueEntry {
+  readonly kind: string;
+  readonly version: number;
+  readonly displayName: string;
+  readonly summary: string;
+  readonly payloadSchema: Record<string, unknown>;
+  readonly source: WidgetKindSource;
+  /** Present only for biome-contributed kinds. */
+  readonly biomeId?: string;
+}
+
+/** Provenance of a catalogue entry. Closed set. */
+export enum WidgetKindSource {
+  FirstParty = 'first-party',
+  Biome = 'biome',
+}
+
+export const WidgetKindSourceSchema = z.nativeEnum(WidgetKindSource);