@xemahq/kernel-contracts 0.50.0 → 0.57.0

package/src/space/lib/space.ts

@@ -148,48 +148,123 @@ const REQUIRED_SEGMENTS: Readonly<Record<SpaceKind, readonly SegmentKey[]>> = {
 };
 
 /**
- * Render a `SpaceRef` as its XVFS path prefix (used by `XemaObjectRef`
- * formatting and by object-registry-api projections). Returns a string
- * that starts with `/`. Fails fast if a required segment is missing.
+ * Structured, fail-fast error raised by every Space-ref grammar operation
+ * ({@link spaceRefToPath}, `parseSpaceRef`, `formatSpaceRef`). Carries a
+ * stable `code` so services can map it to a typed 400 without string-matching
+ * the message.
+ */
+export class SpaceRefParseError extends Error {
+  public readonly code = 'SPACE_REF_INVALID';
+  public readonly raw: string;
+
+  public constructor(message: string, raw: string) {
+    super(message);
+    this.name = 'SpaceRefParseError';
+    this.raw = raw;
+  }
+}
+
+/**
+ * A single Space path segment id (an orgId, projectId, appId, sessionId,
+ * biomeId or userId). Deliberately value-identical to the `XemaObjectRef`
+ * slug-segment pattern so a Space path and an object ref agree on what a
+ * legal segment is: starts alphanumeric, then alphanumerics plus `_`, `.`,
+ * `-`. No `/`, no whitespace, no `@` — those are grammar separators and
+ * would make the ref ambiguous.
+ */
+export const SPACE_SEGMENT_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
+
+/**
+ * Fail-fast guard for a Space path segment id. Enforced by BOTH the renderer
+ * ({@link spaceRefToPath}) and the parser, which is what makes parse/format
+ * exact inverses: a ref that cannot be rendered can never be produced, and a
+ * string that cannot be parsed can never be rendered.
+ */
+export function assertValidSpaceSegmentId(
+  segment: keyof SpaceRef,
+  value: string,
+  raw: string,
+): void {
+  if (!SPACE_SEGMENT_ID_PATTERN.test(value)) {
+    throw new SpaceRefParseError(
+      `Space segment "${String(segment)}" id "${value}" must match ${SPACE_SEGMENT_ID_PATTERN}.`,
+      raw,
+    );
+  }
+}
+
+function requireSpaceSegment(
+  ref: SpaceRef,
+  segment: SegmentKey,
+  raw: string,
+): string {
+  const value = ref[segment];
+  if (value === undefined || value.length === 0) {
+    throw new SpaceRefParseError(
+      `SpaceKind.${ref.tier} requires "${segment}".`,
+      raw,
+    );
+  }
+  assertValidSpaceSegmentId(segment, value, raw);
+  return value;
+}
+
+/**
+ * Render a `SpaceRef` as its canonical XVFS path prefix. Returns a string
+ * that starts with `/`. Fails fast if a required segment is missing or its id
+ * violates {@link SPACE_SEGMENT_ID_PATTERN}.
+ *
+ * This is the SINGLE canonical Space grammar — the plural-head form shared by
+ * `XemaObjectRef`, search refs, the object-registry projection and (since the
+ * X9 convergence) `formatSpaceRef`/`parseSpaceRef`:
+ *
+ * ```
+ *   /system
+ *   /users/<userId>
+ *   /biomes/<biomeId>
+ *   /sessions/<sessionId>
+ *   /orgs/<orgId>
+ *   /orgs/<orgId>/projects/<projectId>
+ *   /orgs/<orgId>/projects/<projectId>/apps/<appId>
+ * ```
+ *
+ * `User`, `Biome` and `Session` are ROOT-addressable on purpose — that is
+ * exactly what {@link REQUIRED_SEGMENTS} already declares (they require only
+ * their own id), and it is what every real producer emits: a biome-contributed
+ * skill lives at `xema://biomes/<id>/skill/<slug>` and is org-less. A ref's
+ * ancestor segments are NOT part of its identity for those tiers.
  */
 export function spaceRefToPath(ref: SpaceRef): string {
+  const raw = ref.path ?? `<SpaceKind.${ref.tier}>`;
   switch (ref.tier) {
     case SpaceKind.System:
       return '/system';
     case SpaceKind.Biome:
-      if (!ref.biomeId) {
-        throw new Error('spaceRefToPath: SpaceKind.Biome requires biomeId');
-      }
-      return `/biomes/${ref.biomeId}`;
-    case SpaceKind.Org:
-      if (!ref.orgId) {
-        throw new Error('spaceRefToPath: SpaceKind.Org requires orgId');
-      }
-      return `/orgs/${ref.orgId}`;
-    case SpaceKind.Project:
-      if (!ref.orgId || !ref.projectId) {
-        throw new Error(
-          'spaceRefToPath: SpaceKind.Project requires orgId and projectId',
-        );
-      }
-      return `/orgs/${ref.orgId}/projects/${ref.projectId}`;
-    case SpaceKind.App:
-      if (!ref.orgId || !ref.projectId || !ref.appId) {
-        throw new Error(
-          'spaceRefToPath: SpaceKind.App requires orgId, projectId, and appId',
-        );
-      }
-      return `/orgs/${ref.orgId}/projects/${ref.projectId}/apps/${ref.appId}`;
-    case SpaceKind.Session:
-      if (!ref.sessionId) {
-        throw new Error('spaceRefToPath: SpaceKind.Session requires sessionId');
-      }
-      return `/sessions/${ref.sessionId}`;
+      return `/biomes/${requireSpaceSegment(ref, 'biomeId', raw)}`;
     case SpaceKind.User:
-      if (!ref.userId) {
-        throw new Error('spaceRefToPath: SpaceKind.User requires userId');
-      }
-      return `/users/${ref.userId}`;
+      return `/users/${requireSpaceSegment(ref, 'userId', raw)}`;
+    case SpaceKind.Session:
+      return `/sessions/${requireSpaceSegment(ref, 'sessionId', raw)}`;
+    case SpaceKind.Org:
+      return `/orgs/${requireSpaceSegment(ref, 'orgId', raw)}`;
+    case SpaceKind.Project: {
+      const orgId = requireSpaceSegment(ref, 'orgId', raw);
+      const projectId = requireSpaceSegment(ref, 'projectId', raw);
+      return `/orgs/${orgId}/projects/${projectId}`;
+    }
+    case SpaceKind.App: {
+      const orgId = requireSpaceSegment(ref, 'orgId', raw);
+      const projectId = requireSpaceSegment(ref, 'projectId', raw);
+      const appId = requireSpaceSegment(ref, 'appId', raw);
+      return `/orgs/${orgId}/projects/${projectId}/apps/${appId}`;
+    }
+    default: {
+      const exhaustive: never = ref.tier;
+      throw new SpaceRefParseError(
+        `spaceRefToPath: unhandled SpaceKind "${String(exhaustive)}".`,
+        raw,
+      );
+    }
   }
 }
 

package/src/subject/lib/subject.ts

@@ -45,11 +45,27 @@ export const SubjectKindSchema = z.nativeEnum(SubjectKind);
 export interface ActingForRef {
   kind: SubjectKind;
   id: string;
+  /**
+   * The ISSUER-STAMPED OAuth client identity of this hop (`azp`, else
+   * `client_id`), when the issuer stamps it inside the hop's `act` object.
+   *
+   * `id` is the hop's `sub` — for a service-account token that is an opaque
+   * Keycloak UUID, which says nothing about WHICH service conveyed the call.
+   * The client id is the logical service name (`workflow-runtime-worker`,
+   * `agent-session-api`, …) that grants and audit trails are keyed by. It is
+   * never caller-supplied: an OAuth client cannot assert another client's id
+   * in a token the issuer signed.
+   *
+   * Absent when the issuer stamps neither claim on the hop — treat absence as
+   * "unknown", never as a match.
+   */
+  clientId?: string;
 }
 
 export const ActingForRefSchema = z.object({
   kind: SubjectKindSchema,
   id: z.string().min(1),
+  clientId: z.string().min(1).optional(),
 }) as z.ZodType<ActingForRef>;
 
 /**

package/src/surface/index.ts

@@ -0,0 +1,3 @@
+export * from './lib/surface-kind';
+export * from './lib/vista-surface';
+export * from './lib/surface-contribution';

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

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+
+/**
+ * Manifest shape carried by every `ContributionKind.SurfaceKind` envelope.
+ *
+ * One contribution = one Vista surface kind. The shape is STRUCTURALLY
+ * IDENTICAL to `WidgetContributionManifest` (see
+ * `../../widget/lib/widget-contribution.ts`) — the two planes deliberately
+ * share one contribution pattern, so the generic
+ * `BootstrapContributionsService<TKind, TManifest>` template and the biome-host
+ * `KindParser` ingest a surface kind exactly the way a widget kind is ingested.
+ * Provenance (`biomeId`, `biomeVersion`) is stamped by the ingestion pipeline
+ * from the discovering biome's manifest — authors do NOT declare it inline.
+ *
+ * A biome contributes a surface kind so its frontend biome can register a
+ * renderer for it against the `<biomeId>:<kind>` slug. The `kind` here is the
+ * BARE, biome-local kind slug; the catalogue namespaces it at ingest so it can
+ * never shadow a first-party {@link SurfaceKind}.
+ *
+ * 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 frontend — which derives the
+ * GENERIC schema-driven renderer from it — and to authoring tools; it is NOT a
+ * kernel-validated shape, because validating it as JSON Schema here would be
+ * either partial or pull in a JSON-Schema validator, violating the kernel-leaf
+ * invariant).
+ *
+ * Per the 2-file rule for a new `ContributionKind`, the kernel owns exactly
+ * this manifest schema plus the enum member; the per-kind ingestion PARSER
+ * lives in the consuming service (`biome-host-api`), not here.
+ */
+export interface SurfaceContributionManifest {
+  /**
+   * 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 surface shows + WHEN to open it (≤ 1000 chars). */
+  readonly summary: string;
+  /** JSON Schema for the surface payload — passed through verbatim. */
+  readonly payloadSchema: Record<string, unknown>;
+}
+
+const SURFACE_KIND_SLUG_REGEX = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * Zod validator for {@link SurfaceContributionManifest}. The biome-host parser
+ * and the catalogue's 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 SurfaceContributionManifestSchema: z.ZodType<SurfaceContributionManifest> =
+  z.object({
+    kind: z
+      .string()
+      .min(1)
+      .max(100)
+      .regex(
+        SURFACE_KIND_SLUG_REGEX,
+        'Surface 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<SurfaceContributionManifest>;
+
+/** Provenance of a surface-kind catalogue entry. Closed set. */
+export enum SurfaceKindSource {
+  FirstParty = 'first-party',
+  Biome = 'biome',
+}
+
+export const SurfaceKindSourceSchema = z.nativeEnum(SurfaceKindSource);
+
+/**
+ * A resolved surface-kind catalogue entry — what the surface-kind catalogue
+ * endpoint returns. It unifies the closed first-party set and the open
+ * biome-contributed set behind ONE shape the frontend consumes to know which
+ * kinds exist (and to register biome-contributed kinds into the open Vista
+ * registry with a generic schema-driven renderer).
+ *
+ * `source` discriminates provenance; `kind` is the FULLY-NAMESPACED slug the
+ * frontend registry keys by (a first-party kind is its bare enum value; a biome
+ * kind is `<biomeId>:<kind>`).
+ */
+export interface SurfaceKindCatalogueEntry {
+  readonly kind: string;
+  readonly version: number;
+  readonly displayName: string;
+  readonly summary: string;
+  readonly payloadSchema: Record<string, unknown>;
+  readonly source: SurfaceKindSource;
+  /** Present only for biome-contributed kinds. */
+  readonly biomeId?: string;
+}

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

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+
+/**
+ * `SurfaceKind` — the closed first-party set of render kinds a Vista tab can
+ * hold (Canopy Plane ④, "Vista: the render plane").
+ *
+ * Vista is the agent-driven, biome-extensible tabbed preview plane: the agent
+ * opens a tab by emitting a {@link VistaSurface} envelope, and the frontend
+ * resolves the envelope's `kind` to a renderer. Each first-party kind is a
+ * GENERIC, domain-agnostic presentation primitive — chosen to cover the
+ * broadest possible range of "thing the agent wants to show the user" without
+ * baking in any vertical semantics.
+ *
+ * ── Closed first-party set vs. open biome set ───────────────────────────────
+ * A biome contributes its OWN surface kind as a namespaced string
+ * (`<biomeId>:<kind>`) through a `ContributionKind.SurfaceKind` contribution —
+ * it never extends this enum. This is the same closed-enum + open-namespaced-
+ * string pattern as `ChatWidgetKind` (see `../../widget`): the frontend
+ * registry reserves every value below, so a biome can never shadow a
+ * first-party kind.
+ *
+ * Adding a first-party kind = one enum member here + a renderer registered
+ * into the frontend Vista registry's closed set.
+ */
+export enum SurfaceKind {
+  /** An external URL rendered in the preview chrome (address bar + frame). */
+  Url = 'url',
+  /** A first-party in-app web view (a host route rendered inside the tab). */
+  Web = 'web',
+  /** UNTRUSTED HTML rendered in an opaque-origin, script-sandboxed frame. */
+  Html = 'html',
+  /** A Markdown document. */
+  Markdown = 'markdown',
+  /** A source file with syntax highlighting. */
+  Code = 'code',
+  /** A unified diff (one or more files). */
+  Diff = 'diff',
+  /** A JSON document rendered as an inspectable tree. */
+  Json = 'json',
+  /** Generic columns + rows. The universal "show me structured records". */
+  Table = 'table',
+  /** A chart over labelled series. */
+  Chart = 'chart',
+  /** A PDF document (canvas-rendered, no script execution). */
+  Pdf = 'pdf',
+  /** A still image. */
+  Image = 'image',
+  /** Time-based media (audio/video). */
+  Media = 'media',
+  /** A Xema object rendered through its registered object view. */
+  Object = 'object',
+  /** A biome's REAL React route, reached through an `xema://biome/…` deeplink. */
+  BiomeRoute = 'biome-route',
+  /** A schema-driven form — the secure-elicitation surface. */
+  Form = 'form',
+  /** A runtime app (App Platform) rendered in its own frame. */
+  App = 'app',
+  /** A file tree / browser over a workspace or artifact set. */
+  Files = 'files',
+  /** A node-edge graph (e.g. the capability map). */
+  Graph = 'graph',
+}
+
+/** Zod mirror of {@link SurfaceKind} for wire-boundary validation. */
+export const SurfaceKindSchema = z.nativeEnum(SurfaceKind);

package/src/surface/lib/vista-surface.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+
+/**
+ * `VistaSurface` — one Vista tab. The agent opens/updates a tab by emitting
+ * this envelope; the frontend Vista registry resolves `kind` to a renderer and
+ * hands it the validated `payload`.
+ *
+ * `kind` is a first-party {@link SurfaceKind} value OR a namespaced biome
+ * string (`<biomeId>:<kind>`). `version` is the monotonic schema version for
+ * THIS kind — the frontend 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 JSON Schema; the
+ * frontend re-validates before render so a malformed payload renders the
+ * fallback rather than being dropped).
+ *
+ * Structurally this is `ChatWidgetEnvelope` plus the tab identity a preview
+ * plane needs (`tabId`, `title`, `pinned`) — deliberately so: the two planes
+ * share ONE contribution pattern, one registry core, and one three-layer
+ * renderer fallback.
+ */
+export interface VistaSurface {
+  /** Stable identity of the tab. Re-opening the same `tabId` replaces it. */
+  readonly tabId: string;
+  /** First-party {@link SurfaceKind} value, or a `<biomeId>:<kind>` slug. */
+  readonly kind: string;
+  /** Monotonic schema version for this kind's payload. */
+  readonly version: number;
+  /** Tab label. */
+  readonly title: string;
+  /** Kind-specific payload, validated + narrowed by the frontend registry. */
+  readonly payload: unknown;
+  /** A pinned tab survives the agent closing/replacing unpinned tabs. */
+  readonly pinned?: boolean;
+}
+
+/** Zod validator for {@link VistaSurface}. */
+export const VistaSurfaceSchema: z.ZodType<VistaSurface> = z.object({
+  tabId: z.string().min(1),
+  kind: z.string().min(1),
+  version: z.number().int().positive(),
+  title: z.string().min(1),
+  payload: z.unknown(),
+  pinned: z.boolean().optional(),
+}) as z.ZodType<VistaSurface>;

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

@@ -31,8 +31,12 @@ export const ChatWidgetEnvelopeSchema: z.ZodType<ChatWidgetEnvelope> = z.object(
 
 /**
  * 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.
+ * decision so the Studio debugger can see WHY. Closed set.
+ *
+ * This is the WIRE mirror. The FE runtime reason set is
+ * `ContributionFallbackReason` in `@xemahq/ui-kernel`, shared by every plane
+ * built on the two-layer contribution registry (ChatWidgets, Vista surfaces) —
+ * keep the two value-identical.
  */
 export enum ChatWidgetFallbackReason {
   UnknownKind = 'unknown-kind',

package/src/workflow/lib/enums.ts

@@ -288,13 +288,12 @@ export enum BuiltInActionId {
    * authorization decisions, so any cross-service side-effect routes
    * through this action and the router's grant resolver decides.
    *
-   * Inputs declare the `ref` (`<domain>:<resource>.<verb>@<major>`),
-   * the opaque `input` payload the bound implementation consumes, and
-   * an optional `subjectOverride` for callers that need to act as a
-   * different subject than the workflow's executing identity. The
-   * activity derives `subject` from the worker's service identity
-   * when no override is supplied and stamps `correlationId` with the
-   * workflow run id so audit-log entries stitch back to the run.
+   * Inputs declare the `ref` (`<domain>:<resource>.<verb>@<major>`) and
+   * the opaque `input` payload the bound implementation consumes. The
+   * subject is not an input: the activity always derives it from the
+   * worker's own service identity — the identity whose bearer the
+   * router verifies — and stamps `correlationId` with the workflow run
+   * id so audit-log entries stitch back to the run.
    */
   CAPABILITY_INVOKE = 'xema/capability',
   /**

package/src/capability/lib/first-party-capability-domains.ts

@@ -1,77 +0,0 @@
-import { z } from 'zod';
-
-// ═══════════════════════════════════════════════════════════════════════════
-// ── The CLOSED set of first-party capability DOMAINS ──
-//
-// A capability ref is `<domain>:<resource>.<verb>@<major>`. A DOMAIN is
-// "first-party" when a fixed in-the-box Xema platform service owns every ref
-// under it — i.e. the capability-router's static dispatch table resolves it
-// directly (never through an org-provisioned or contributed backing).
-//
-// This is the SINGLE SOURCE OF TRUTH for that membership. It exists so two
-// services can agree without one reaching into the other's code:
-//
-//   - `xema-capability-router` builds its static dispatch table from EXACTLY
-//     these keys and asserts the two agree at boot (fail-fast on drift).
-//   - `capability-registry-api` REFUSES an org `CapabilityProviderBinding`
-//     whose ref domain is in this set — an org admin must not be able to bind
-//     `kb:page.read@1` / `agent:invoke@1` / `artifact:blob.read@1` to a URL
-//     they control and silently shadow the platform data plane.
-//
-// Membership is the router's dispatch keys, in dispatch-registration order.
-// Adding/removing a first-party domain is a coordinated change here PLUS the
-// router's dispatch table — the boot assertion turns any divergence into a
-// crash rather than a silent shadow window.
-// ═══════════════════════════════════════════════════════════════════════════
-
-export const FIRST_PARTY_CAPABILITY_DOMAINS = [
-  'xema-shell',
-  'store',
-  'biome',
-  'connector',
-  'kb',
-  'agent',
-  'memory',
-  'model',
-  'model-resolution',
-  'mcp-tool',
-  'workflow',
-  'studio',
-  'interactive-session',
-  'agent-session',
-  'document',
-  'notification',
-  'space',
-  'mailops',
-  'workspace',
-  'worker-runtime',
-  'artifact',
-  'search',
-  'app',
-] as const;
-
-export type FirstPartyCapabilityDomain =
-  (typeof FIRST_PARTY_CAPABILITY_DOMAINS)[number];
-
-export const FirstPartyCapabilityDomainSchema = z.enum(
-  FIRST_PARTY_CAPABILITY_DOMAINS as unknown as [
-    FirstPartyCapabilityDomain,
-    ...FirstPartyCapabilityDomain[],
-  ],
-);
-
-const FIRST_PARTY_CAPABILITY_DOMAIN_SET: ReadonlySet<string> = new Set(
-  FIRST_PARTY_CAPABILITY_DOMAINS,
-);
-
-/**
- * `true` iff `domain` is a first-party platform capability domain. O(1)
- * membership over the closed set above. The write-path shadow refusal and the
- * router's binding-skip defense-in-depth both branch on this — never on an
- * ad-hoc string compare or a hand-maintained second list.
- */
-export function isFirstPartyCapabilityDomain(
-  domain: string,
-): domain is FirstPartyCapabilityDomain {
-  return FIRST_PARTY_CAPABILITY_DOMAIN_SET.has(domain);
-}