@xemahq/kernel-contracts 0.7.0 → 0.9.0

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

@@ -18,18 +18,30 @@ import {
  *                    the ONLY form that can pull an `audience: operator` biome
  *                    (the "force it in" mechanism for our internal distribution).
  *
+ * **`mandatory`** (on the `{ tier }` and `{ biome }` forms; defaults `false`) is
+ * the DISTRIBUTION's force-on decision: a biome resolves to
+ * `LockedBiome.mandatory = true` (always-on, org cannot disable) iff ANY
+ * matching selector sets `mandatory: true`, OR it is kernel-tier (a platform
+ * invariant the resolver enforces regardless of selectors). Mandatory is NOT a
+ * property a biome self-declares in its manifest — the same biome can be
+ * force-on in one distribution and optional/installable in another.
+ *
  * 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 }
+  | { tier: BiomeTier; mandatory?: boolean }
   | { origin: BiomeOrigin }
-  | { biome: string; version?: string };
+  | { biome: string; version?: string; mandatory?: boolean };
 
 export const DistributionSelectorSchema = z.union([
-  z.object({ tier: BiomeTierSchema }).strict(),
+  z.object({ tier: BiomeTierSchema, mandatory: z.boolean().optional() }).strict(),
   z.object({ origin: BiomeOriginSchema }).strict(),
   z
-    .object({ biome: z.string().min(1), version: z.string().min(1).optional() })
+    .object({
+      biome: z.string().min(1),
+      version: z.string().min(1).optional(),
+      mandatory: z.boolean().optional(),
+    })
     .strict(),
 ]) as z.ZodType<DistributionSelector>;

package/src/invocation/lib/invoke-request.ts

@@ -5,7 +5,7 @@ import {
 } from './execution-requirements';
 
 /**
- * The wire body for `composition:invoke@1` — what a caller sends through the
+ * The wire body for `agent:invoke@1` — what a caller sends through the
  * capability funnel to execute a published composition.
  *
  * `AgentInvokeRequestSchema` is the fail-fast validator the runtime

package/src/invocation/lib/invoke-response.ts

@@ -7,7 +7,7 @@ import {
 } from './invocation-decision';
 
 /**
- * The response the runtime returns for a `composition:invoke@1` call.
+ * The response the runtime returns for a `agent:invoke@1` call.
  *
  * In `Sync` mode `output` carries the composition root structured output. In
  * `Event` mode `output` is omitted and the consumer subscribes to the result

package/src/resource/index.ts

@@ -0,0 +1,22 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// @xemahq/kernel-contracts/resource — Xema-as-Code wire contracts.
+//
+// Pure types + Zod schemas for the declarative provisioning (IaC) surface of
+// the tenant/runtime plane: the closed `XemaResourceKind` set, the
+// `ResourceManagedBy` ownership marker, the `ResourceDeclaration` envelope and
+// the `XemaManifest` (`xema.yaml`) document, plus the server-side `Stack` state
+// and the `ResourcePlan` diff vocabulary.
+//
+// A DAG LEAF on purpose: per-kind `spec` bodies are validated by the owning
+// domain service (which holds the authoritative DTO), so this surface drags no
+// cross-subpath dependency into the kernel. The Terraform provider, the first-
+// party `xema.yaml` apply, and the frontend all converge on these contracts.
+// Zero runtime deps beyond `zod`.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/resource-kind';
+export * from './lib/resource-managed-by';
+export * from './lib/resource-declaration';
+export * from './lib/xema-manifest';
+export * from './lib/stack';
+export * from './lib/plan';

package/src/resource/lib/plan.ts

@@ -0,0 +1,83 @@
+import { z } from 'zod';
+import { XemaResourceKind, XemaResourceKindSchema } from './resource-kind';
+
+/**
+ * `ResourceChangeAction` — the closed set of actions a `plan` may attribute to
+ * a single resource, mirroring Terraform's plan vocabulary.
+ *
+ * - `Create`  — declared, no physical resource yet.
+ * - `Update`  — declared spec differs from the last-applied spec (in-place).
+ * - `Replace` — a change to an immutable field; the resource is destroyed and
+ *   recreated (e.g. a slug/ref that the owning service treats as immutable).
+ * - `Delete`  — present in the Stack mapping but absent from the new manifest.
+ * - `NoOp`    — declared spec equals applied state; nothing to do.
+ */
+export enum ResourceChangeAction {
+  Create = 'create',
+  Update = 'update',
+  Replace = 'replace',
+  Delete = 'delete',
+  NoOp = 'noop',
+}
+
+export const ResourceChangeActionSchema = z.nativeEnum(ResourceChangeAction);
+
+/**
+ * A per-field before/after, populated for `Update`/`Replace` so the plan is
+ * legible to a human reviewing `xema plan` (and to the FE drift view).
+ */
+export interface ResourceFieldDiff {
+  from: unknown;
+  to: unknown;
+}
+
+export const ResourceFieldDiffSchema = z.object({
+  from: z.unknown(),
+  to: z.unknown(),
+}) as z.ZodType<ResourceFieldDiff>;
+
+/**
+ * `ResourceChange` — one planned action against one resource.
+ *
+ * `driftFromActual` is true when the *current actual* state read back from the
+ * owning service differs from the Stack's last-applied state — i.e. someone
+ * changed it out-of-band (the frontend, a direct API call). This is what makes
+ * the behavior Terraform-exact: drift is surfaced at plan time, and `apply`
+ * reconciles the resource back to the declared spec.
+ */
+export interface ResourceChange {
+  kind: XemaResourceKind;
+  /** `"<kind>.<id>"` logical ref. */
+  logicalId: string;
+  action: ResourceChangeAction;
+  /** Present when the resource already has a physical identity. */
+  physicalId?: string;
+  driftFromActual?: boolean;
+  diff?: Record<string, ResourceFieldDiff>;
+}
+
+export const ResourceChangeSchema = z.object({
+  kind: XemaResourceKindSchema,
+  logicalId: z.string().min(1),
+  action: ResourceChangeActionSchema,
+  physicalId: z.string().min(1).optional(),
+  driftFromActual: z.boolean().optional(),
+  diff: z.record(z.string(), ResourceFieldDiffSchema).optional(),
+}) as z.ZodType<ResourceChange>;
+
+/**
+ * `ResourcePlan` — the full diff produced by `POST /stacks/:name/plan`: the
+ * ordered set of changes plus whether any out-of-band drift was detected. An
+ * `apply` executes exactly this plan.
+ */
+export interface ResourcePlan {
+  stackName: string;
+  changes: readonly ResourceChange[];
+  driftDetected: boolean;
+}
+
+export const ResourcePlanSchema = z.object({
+  stackName: z.string().min(1),
+  changes: z.array(ResourceChangeSchema).readonly(),
+  driftDetected: z.boolean(),
+}) as z.ZodType<ResourcePlan>;

package/src/resource/lib/resource-declaration.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import { XemaResourceKind, XemaResourceKindSchema } from './resource-kind';
+
+/**
+ * A logical reference to another declared resource within the same manifest,
+ * encoded as `"<kind>.<id>"` (e.g. `"project.web-app"`). Used by `dependsOn`
+ * to order an `apply` and to wire one resource's output into another's spec.
+ */
+export type ResourceLogicalRef = string;
+
+/**
+ * `ResourceDeclaration` — one resource entry in a `XemaManifest`. The `spec`
+ * is intentionally opaque at the kernel layer (`Record<string, unknown>`): the
+ * owning domain service holds the authoritative per-kind schema and validates
+ * it at the wire. This keeps the `resource` subpath a DAG leaf while still
+ * giving the control-plane a stable envelope to plan/diff against.
+ *
+ * - `id`         — the author-chosen logical id, unique per `kind` within a
+ *   manifest. Stable across applies; this is what the Stack maps to a physical
+ *   id. Never the server-generated UUID.
+ * - `managedKey` — the natural key the owning service upserts on. Defaults to
+ *   `id` when omitted. For resources whose natural key is already a slug/ref
+ *   (space ref, skill slug, environment slug) the author may set it explicitly.
+ * - `dependsOn`  — `"<kind>.<id>"` refs that must be applied first.
+ */
+export interface ResourceDeclaration {
+  kind: XemaResourceKind;
+  id: string;
+  managedKey?: string;
+  dependsOn?: readonly ResourceLogicalRef[];
+  spec: Record<string, unknown>;
+}
+
+const LOGICAL_REF_RE = /^[a-z0-9-]+\.[A-Za-z0-9._-]+$/;
+
+export const ResourceLogicalRefSchema = z
+  .string()
+  .regex(LOGICAL_REF_RE, {
+    message:
+      'A resource ref must be "<kind>.<id>" (e.g. "project.web-app").',
+  });
+
+export const ResourceDeclarationSchema = z.object({
+  kind: XemaResourceKindSchema,
+  id: z
+    .string()
+    .min(1)
+    .regex(/^[A-Za-z0-9._-]+$/, {
+      message:
+        'ResourceDeclaration.id must be a stable slug ([A-Za-z0-9._-]+).',
+    }),
+  managedKey: z.string().min(1).optional(),
+  dependsOn: z.array(ResourceLogicalRefSchema).readonly().optional(),
+  spec: z.record(z.string(), z.unknown()),
+}) as z.ZodType<ResourceDeclaration>;
+
+/** The `"<kind>.<id>"` logical ref for a declaration. */
+export function logicalRefOf(
+  decl: Pick<ResourceDeclaration, 'kind' | 'id'>,
+): ResourceLogicalRef {
+  return `${decl.kind}.${decl.id}`;
+}
+
+/** The natural key a declaration upserts on (`managedKey` or `id`). */
+export function managedKeyOf(decl: ResourceDeclaration): string {
+  return decl.managedKey ?? decl.id;
+}

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

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+
+/**
+ * `XemaResourceKind` — the closed set of platform resources that can be
+ * declared as code (Terraform / first-party `xema.yaml`) and reconciled by the
+ * control-plane. Each value is the canonical, wire-stable slug for the resource
+ * kind; the Terraform provider exposes it as `xema_<kind_with_underscores>`
+ * (e.g. `model-resolution-rule` → `xema_model_resolution_rule`).
+ *
+ * This is intentionally a LEAF surface: the kinds are plain slugs and the
+ * per-kind `spec` body is validated by the owning domain service (which holds
+ * the authoritative DTO), NOT here — so adding a resource never drags a
+ * cross-subpath dependency into the kernel. Extending the set is a one-line PR.
+ *
+ * The set mirrors the provisionable resource inventory of the tenant/runtime
+ * plane (see the Xema-as-Code plan). The operator/packaging plane
+ * (`Distribution`) is a SEPARATE surface and is not a member here.
+ */
+export enum XemaResourceKind {
+  Org = 'org',
+  Project = 'project',
+  Portal = 'portal',
+  BiomeInstall = 'biome-install',
+  Provider = 'provider',
+  Model = 'model',
+  ModelResolutionRule = 'model-resolution-rule',
+  Skill = 'skill',
+  Agent = 'agent',
+  Role = 'role',
+  Grant = 'grant',
+  Space = 'space',
+  Environment = 'environment',
+  Team = 'team',
+  DeliverableSpec = 'deliverable-spec',
+}
+
+export const XemaResourceKindSchema = z.nativeEnum(XemaResourceKind);

package/src/resource/lib/resource-managed-by.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+
+/**
+ * `ResourceManagedBy` — the ownership marker stamped on every provisionable
+ * resource row. This single concept powers three behaviors with one switch:
+ *
+ * - `Seeder`  — owned by a boot/event reconciler (e.g. portals derived from
+ *   installed web biomes). The reconciler may create/update/retire these.
+ *   Retire-removed deletes ONLY `Seeder`-owned rows whose `managedKey` no
+ *   longer appears in the desired set.
+ * - `Iac`     — owned by a declarative source (Terraform / `xema.yaml`).
+ *   Declared-state-wins: `plan` surfaces drift, `apply` reconciles back. No
+ *   reconciler touches a row it does not own.
+ * - `Ui`      — created/edited through the frontend (or adopted away from a
+ *   `Seeder`/`Iac` owner when a user customizes it). Never auto-reverted.
+ * - `System`  — kernel/platform-shipped and immutable from any provisioning
+ *   surface.
+ *
+ * Adoption (`Seeder`/`Iac` → `Ui`) is the explicit "I now own this by hand"
+ * action; it is the inverse of `import` (`Ui` → `Iac`).
+ */
+export enum ResourceManagedBy {
+  Ui = 'ui',
+  Iac = 'iac',
+  Seeder = 'seeder',
+  System = 'system',
+}
+
+export const ResourceManagedBySchema = z.nativeEnum(ResourceManagedBy);

package/src/resource/lib/stack.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { XemaResourceKind, XemaResourceKindSchema } from './resource-kind';
+import { XemaManifest, XemaManifestSchema } from './xema-manifest';
+
+/**
+ * `ResourceMapping` — one row of a Stack's logical→physical binding, the
+ * server-side equivalent of a single entry in a Terraform/CloudFormation state
+ * file. It records which physical (server-generated) resource a declared
+ * logical id resolved to, plus the content hash of the spec that was last
+ * applied — the basis for drift detection on the native `xema.yaml` path.
+ */
+export interface ResourceMapping {
+  /** `"<kind>.<id>"` — the manifest logical ref. */
+  logicalId: string;
+  kind: XemaResourceKind;
+  /** The server-generated identity of the materialized resource. */
+  physicalId: string;
+  /** The natural key the owning service upserts on. */
+  managedKey: string;
+  /** sha256 of the spec last successfully applied for this resource. */
+  lastAppliedHash: string;
+}
+
+export const ResourceMappingSchema = z.object({
+  logicalId: z.string().min(1),
+  kind: XemaResourceKindSchema,
+  physicalId: z.string().min(1),
+  managedKey: z.string().min(1),
+  lastAppliedHash: z.string().min(1),
+}) as z.ZodType<ResourceMapping>;
+
+/**
+ * `Stack` — a named, org-scoped declarative state. It is the CloudFormation
+ * stack / Terraform state-file analogue that control-plane-api persists for the
+ * first-party `xema.yaml` path: the last-applied manifest plus the logical→
+ * physical mappings used to plan the next apply and detect out-of-band drift.
+ *
+ * The Terraform provider does NOT use a Stack — Terraform Core owns its own
+ * state. A Stack exists only for the native YAML / FE export-import surface.
+ */
+export interface Stack {
+  schemaVersion: 1;
+  stackId: string;
+  orgId: string;
+  name: string;
+  /** The manifest from the most recent successful apply (absent before first). */
+  lastAppliedManifest?: XemaManifest;
+  mappings: readonly ResourceMapping[];
+  /** ISO-8601 timestamp of the last apply. */
+  updatedAt?: string;
+}
+
+export const StackSchema = z.object({
+  schemaVersion: z.literal(1),
+  stackId: z.string().min(1),
+  orgId: z.string().min(1),
+  name: z.string().min(1),
+  lastAppliedManifest: XemaManifestSchema.optional(),
+  mappings: z.array(ResourceMappingSchema).readonly(),
+  updatedAt: z.string().min(1).optional(),
+}) as z.ZodType<Stack>;

package/src/resource/lib/xema-manifest.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import {
+  ResourceDeclaration,
+  ResourceDeclarationSchema,
+  logicalRefOf,
+} from './resource-declaration';
+
+/**
+ * Schema-versioning seed for the first-party `xema.yaml` document. Bumped via a
+ * coordinated PR on an incompatible shape change; consumers refuse versions
+ * they do not understand (fail-fast — never best-effort parse). Mirrors the
+ * `Distribution` / `AppLockfile` versioning discipline.
+ */
+export type XemaManifestApiVersion = 'xema/v1';
+
+/**
+ * `XemaManifest` — the top-level shape of a first-party `xema.yaml`: a
+ * declarative description of a set of platform resources for one org, applied
+ * as a named Stack. This is the CloudFormation-equivalent document; the
+ * Terraform provider expresses the same resources as HCL and does not use this
+ * shape (Terraform Core owns its own state), but both converge on the same
+ * resource APIs and the same `ResourceDeclaration` envelope.
+ *
+ * `stack` is the logical state name. When omitted, the applying surface (the
+ * `xema` CLI or control-plane-api) supplies it (e.g. from `--stack`). The org
+ * is NEVER encoded in the document — it comes from the authenticated apply
+ * context, so the same manifest is portable across orgs.
+ */
+export interface XemaManifest {
+  apiVersion: XemaManifestApiVersion;
+  stack?: string;
+  resources: readonly ResourceDeclaration[];
+}
+
+export const XemaManifestSchema = z
+  .object({
+    apiVersion: z.literal('xema/v1'),
+    stack: z.string().min(1).optional(),
+    resources: z.array(ResourceDeclarationSchema).readonly(),
+  })
+  .superRefine((manifest, ctx) => {
+    // (kind, id) must be unique — it is the join key the Stack maps to a
+    // physical id. A duplicate would make the mapping ambiguous.
+    const seen = new Set<string>();
+    manifest.resources.forEach((decl, index) => {
+      const ref = logicalRefOf(decl);
+      if (seen.has(ref)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['resources', index],
+          message: `Duplicate resource ref "${ref}" — every (kind, id) must be unique within a manifest.`,
+        });
+      }
+      seen.add(ref);
+    });
+    // dependsOn refs must resolve within the manifest — fail-fast on a dangling
+    // dependency rather than silently dropping ordering.
+    manifest.resources.forEach((decl, index) => {
+      for (const dep of decl.dependsOn ?? []) {
+        if (!seen.has(dep)) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['resources', index, 'dependsOn'],
+            message: `dependsOn "${dep}" does not match any resource declared in this manifest.`,
+          });
+        }
+      }
+    });
+  }) as unknown as z.ZodType<XemaManifest>;
+
+/**
+ * Parse + validate a raw `xema.yaml` document. Fail-fast on any shape error,
+ * duplicate ref, or dangling dependency — never best-effort. Mirrors
+ * `parseDistribution`.
+ */
+export function parseXemaManifest(raw: unknown): XemaManifest {
+  const result = XemaManifestSchema.safeParse(raw);
+  if (!result.success) {
+    throw new Error(
+      `Invalid xema.yaml: ${result.error.issues
+        .map((i) => `[${i.path.join('.')}] ${i.message}`)
+        .join('; ')}`,
+    );
+  }
+  return result.data;
+}