@xemahq/kernel-contracts 0.1.0

package/src/contribution/lib/contribution.ts

@@ -0,0 +1,209 @@
+import { z } from 'zod';
+import { ContributionKind, ContributionKindSchema } from './contribution-kind';
+import {
+  ContributionSource,
+  ContributionSourceSchema,
+} from './contribution-source';
+
+/**
+ * Contribution slug grammar.
+ *
+ * Every contribution is addressed as `<namespace>/<local-slug>` where:
+ * - `<namespace>` is either `system` (kernel-shipped contributions) or a
+ *   biome (biome) id; lowercase letters, digits, and hyphens.
+ * - `<local-slug>` is the kind-local identifier; lowercase letters, digits,
+ *   hyphens, dots, and nested `/` segments allowed (e.g. `scm/create-pr`).
+ *
+ * The slug MUST be unique within a `(kind, source)` registry shard — see
+ * `createContributionRegistry`.
+ */
+const SLUG_NAMESPACE = '[a-z][a-z0-9-]*';
+const SLUG_LOCAL = '[a-z0-9][a-z0-9._-]*(?:/[a-z0-9][a-z0-9._-]*)*';
+export const CONTRIBUTION_SLUG_REGEX = new RegExp(
+  `^${SLUG_NAMESPACE}/${SLUG_LOCAL}$`,
+);
+
+export const ContributionSlugSchema = z
+  .string()
+  .regex(
+    CONTRIBUTION_SLUG_REGEX,
+    'Contribution slug must match `<namespace>/<local-slug>` (lowercase, hyphens, dots, slashes).',
+  );
+
+/** Matcher for a bare namespace segment (no `/`). */
+const CONTRIBUTION_NAMESPACE_REGEX = new RegExp(`^${SLUG_NAMESPACE}$`);
+
+/** The canonical namespace for kernel-shipped (System-source) contributions. */
+export const SYSTEM_CONTRIBUTION_NAMESPACE = 'system';
+
+/**
+ * Coerce an arbitrary provenance token (a biome id, scope key, or the
+ * `__platform__` sentinel) into a contract-legal contribution namespace
+ * (`[a-z][a-z0-9-]*`).
+ *
+ * The transform is deterministic and total:
+ * - drop any `<prefix>:` qualifier (e.g. `biome:agent-runtime` → `agent-runtime`);
+ * - lowercase, then replace every run of illegal characters with a single `-`;
+ * - trim leading/trailing `-`, and drop a leading run of digits so the first
+ *   character is a letter (the regex requires `[a-z]` first).
+ *
+ * Throws fail-fast if no legal namespace can be derived (e.g. the input has
+ * no letters), rather than silently emitting an invalid slug.
+ */
+export function sanitizeContributionNamespace(raw: string): string {
+  const afterColon = raw.includes(':') ? raw.slice(raw.lastIndexOf(':') + 1) : raw;
+  const collapsed = afterColon
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/^[0-9]+/, '');
+  const namespace = collapsed.replace(/^-+/, '');
+  if (!CONTRIBUTION_NAMESPACE_REGEX.test(namespace)) {
+    throw new Error(
+      `Cannot derive a contract-legal contribution namespace from "${raw}" — ` +
+        `result "${namespace}" does not match ${SLUG_NAMESPACE}.`,
+    );
+  }
+  return namespace;
+}
+
+/**
+ * Compose a contract-legal contribution envelope slug `<namespace>/<localSlug>`.
+ *
+ * `localSlug` is the bare, kind-local identifier stored on the manifest/DB row
+ * (e.g. `scm/create-pr`); it is preserved verbatim. `namespace` is sanitized
+ * via {@link sanitizeContributionNamespace}. The composed slug is validated
+ * against {@link ContributionSlugSchema} so a malformed `localSlug` fails fast
+ * here rather than at the SDK ingest boundary.
+ *
+ * Centralizes the namespacing every contribution producer needs so the ENVELOPE
+ * slug satisfies the kernel grammar while the BARE `localSlug` keeps flowing
+ * through `manifest` to the handler unchanged.
+ */
+export function composeContributionSlug(
+  namespace: string,
+  localSlug: string,
+): string {
+  const ns = sanitizeContributionNamespace(namespace);
+  return ContributionSlugSchema.parse(`${ns}/${localSlug}`);
+}
+
+/**
+ * Loose semver matcher accepting the standard `MAJOR.MINOR.PATCH` shape plus
+ * the optional pre-release and build-metadata tails. We deliberately do NOT
+ * pull in a semver lib at this layer — the kernel contract only needs the
+ * shape; richer comparison lives downstream.
+ */
+export const CONTRIBUTION_VERSION_REGEX =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+
+export const ContributionVersionSchema = z
+  .string()
+  .regex(
+    CONTRIBUTION_VERSION_REGEX,
+    'Contribution version must be valid semver (MAJOR.MINOR.PATCH[-pre][+build]).',
+  );
+
+/**
+ * Generic Contribution envelope. Every entry in the Backend Slot Registry,
+ * regardless of `kind`, carries this shape. Kind-specific contracts packages
+ * own their own `TManifest` Zod schemas and feed them to
+ * `contributionEnvelopeSchema` to get a fully-typed runtime validator.
+ *
+ * See plan-of-record §12.2 for the prose definition.
+ */
+export interface Contribution<
+  TKind extends ContributionKind,
+  TManifest,
+> {
+  readonly kind: TKind;
+  readonly slug: string;
+  readonly source: ContributionSource;
+  readonly version: string;
+  readonly manifest: TManifest;
+}
+
+/**
+ * Factory producing a strongly-typed Zod schema for a single `kind`.
+ *
+ * The factory pins `kind` to a literal so the resulting schema rejects
+ * cross-kind envelopes at the wire and so TypeScript narrows `kind` to
+ * `TKind` (not the full union) when consumers `parse()`.
+ */
+export function contributionEnvelopeSchema<
+  TKind extends ContributionKind,
+  TManifest,
+>(
+  kind: TKind,
+  manifestSchema: z.ZodType<TManifest>,
+): z.ZodType<Contribution<TKind, TManifest>> {
+  // `z.literal` on an enum value gives us "this exact kind" at runtime
+  // and a discriminated narrowing at the type level.
+  return z.object({
+    kind: z.literal(kind),
+    slug: ContributionSlugSchema,
+    source: ContributionSourceSchema,
+    version: ContributionVersionSchema,
+    manifest: manifestSchema,
+  }) as z.ZodType<Contribution<TKind, TManifest>>;
+}
+
+/**
+ * Untyped envelope schema — accepts any `ContributionKind` and an opaque
+ * manifest. Useful for the slot registry's first-pass decode before
+ * routing the envelope to the kind-specific schema.
+ */
+export const AnyContributionEnvelopeSchema = z.object({
+  kind: ContributionKindSchema,
+  slug: ContributionSlugSchema,
+  source: ContributionSourceSchema,
+  version: ContributionVersionSchema,
+  manifest: z.unknown(),
+});
+
+export type AnyContribution = z.infer<typeof AnyContributionEnvelopeSchema>;
+
+/**
+ * Per-invocation context passed to a `ContributionKindHandler.ingest` call.
+ * Carries the provenance of the contribution so handlers can stamp registry
+ * rows with the biome that shipped them without re-deriving it from the
+ * slug. Closed shape — extending it is a coordinated kernel change.
+ */
+export interface ContributionIngestContext {
+  readonly biomeId: string;
+  readonly biomeVersion: string;
+}
+
+/**
+ * Per-kind ingestion handler. Phase C of the Xema OS plan replaces 14 hand-
+ * rolled `Bootstrap*Service` seeders with a single generic
+ * `BootstrapContributionsService<TKind, TManifest>` template (see plan §6
+ * C.3) whose only per-kind specialisation is an implementation of this
+ * interface.
+ *
+ * Implementations MUST:
+ * - pin `kind` to the concrete `ContributionKind` they handle so the
+ *   dispatcher can route by kind;
+ * - expose `manifestSchema` so the generic bootstrap template can validate
+ *   each candidate envelope's `manifest` payload at the wire boundary
+ *   (fail-fast — no silent coercion, no partial ingest);
+ * - be idempotent — the bootstrap service replays contributions on every
+ *   biome reload.
+ */
+export interface ContributionKindHandler<
+  TManifest,
+  TKind extends ContributionKind = ContributionKind,
+> {
+  readonly kind: TKind;
+  /**
+   * Zod schema for `TManifest`. The generic bootstrap template feeds every
+   * incoming envelope's `manifest` field through this before dispatching to
+   * `ingest`, so handler implementations can assume a fully-validated
+   * payload.
+   */
+  readonly manifestSchema: z.ZodType<TManifest>;
+  ingest(
+    contribution: Contribution<TKind, TManifest>,
+    ctx: ContributionIngestContext,
+  ): Promise<void>;
+}

package/src/contribution/lib/registry.ts

@@ -0,0 +1,100 @@
+import type { Contribution } from './contribution';
+import type { ContributionKind } from './contribution-kind';
+
+/**
+ * Structured error codes raised by the in-process per-kind registry.
+ * Closed set — extending requires updating both this enum and the
+ * registry implementation in one PR.
+ */
+export enum ContributionRegistryErrorCode {
+  DuplicateSlug = 'CONTRIBUTION_DUPLICATE_SLUG',
+  KindMismatch = 'CONTRIBUTION_KIND_MISMATCH',
+}
+
+/**
+ * Thrown by `ContributionRegistry` operations. Carries a structured `code`
+ * so callers can branch on the reason without string-matching the message.
+ */
+export class ContributionRegistryError extends Error {
+  public readonly code: ContributionRegistryErrorCode;
+  public readonly kind: ContributionKind;
+  public readonly slug: string;
+
+  public constructor(args: {
+    code: ContributionRegistryErrorCode;
+    kind: ContributionKind;
+    slug: string;
+    message: string;
+  }) {
+    super(args.message);
+    this.name = 'ContributionRegistryError';
+    this.code = args.code;
+    this.kind = args.kind;
+    this.slug = args.slug;
+  }
+}
+
+/**
+ * Pure in-process per-kind registry interface. One registry instance per
+ * `(ContributionKind, TManifest)` pair. The Backend Slot Registry is the
+ * union catalog over many of these, indexed by `ContributionKind`.
+ *
+ * Implementations MUST:
+ * - fail-fast on duplicate slug registration (no silent overwrite);
+ * - reject entries whose `kind` does not match the registry's pinned kind;
+ * - return readonly snapshots from `list()` so callers cannot mutate state.
+ */
+export interface ContributionRegistry<
+  TKind extends ContributionKind,
+  TManifest,
+> {
+  readonly kind: TKind;
+  register(entry: Contribution<TKind, TManifest>): void;
+  get(slug: string): Contribution<TKind, TManifest> | undefined;
+  list(): readonly Contribution<TKind, TManifest>[];
+}
+
+/**
+ * Factory for the canonical in-process registry. The returned registry is
+ * the plain reference implementation — no persistence, no eventing — and is
+ * the building block the Backend Slot Registry composes per kind.
+ *
+ * Fails fast (throws `ContributionRegistryError`) on:
+ * - duplicate slug within the same registry instance;
+ * - an entry whose `kind` differs from the registry's pinned `kind`.
+ */
+export function createContributionRegistry<
+  TKind extends ContributionKind,
+  TManifest,
+>(kind: TKind): ContributionRegistry<TKind, TManifest> {
+  const entries = new Map<string, Contribution<TKind, TManifest>>();
+
+  return {
+    kind,
+    register(entry) {
+      if (entry.kind !== kind) {
+        throw new ContributionRegistryError({
+          code: ContributionRegistryErrorCode.KindMismatch,
+          kind,
+          slug: entry.slug,
+          message: `Cannot register contribution of kind "${entry.kind}" in a registry pinned to kind "${kind}".`,
+        });
+      }
+      if (entries.has(entry.slug)) {
+        throw new ContributionRegistryError({
+          code: ContributionRegistryErrorCode.DuplicateSlug,
+          kind,
+          slug: entry.slug,
+          message: `Contribution "${entry.slug}" is already registered for kind "${kind}".`,
+        });
+      }
+      entries.set(entry.slug, entry);
+    },
+    get(slug) {
+      return entries.get(slug);
+    },
+    list() {
+      return Array.from(entries.values());
+    },
+  };
+}

package/src/document-templates/index.ts

@@ -0,0 +1,24 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Document Templates — Kernel Contracts ──
+//
+// Kernel (Layer 1) contracts for the Document Template primitive. Pure
+// types + closed enums — zero runtime deps, no NestJS, no Prisma.
+//
+// A Document Template binds a category of document (open string: report,
+// sales-proposal, letter, lookbook, …) to:
+//   - a kernel-closed `RenderingShape` (PAGINATED / ANIMATED_SLIDES /
+//     SINGLE_PAGE) that picks the renderer,
+//   - default geometry (page format + orientation),
+//   - a default theme reference,
+//   - a skill bundle (the sub-skills the agent loads when authoring),
+//   - optional sub-agents (when category-specific work needs its own
+//     model / tools / context),
+//   - optional seed content (skeleton HTML inserted on document create).
+//
+// Templates are *content* (shipped by biomes / orgs / users), not
+// kernel concepts. The kernel commits to the SHAPE of a template, not
+// the set of templates that exist.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/rendering-shape';
+export * from './lib/document-template';

package/src/document-templates/lib/document-template.ts

@@ -0,0 +1,88 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── DocumentTemplate ──
+//
+// The open registry entry that binds a document CATEGORY (sales-proposal,
+// report, letter, lookbook, …) to its kernel-closed RenderingShape +
+// default geometry + default theme + skill bundle + (optionally) sub-
+// agents + (optionally) seed content.
+//
+// Templates are content. Biomes, orgs, and users contribute them.
+// Adding a new category is shipping a new template manifest + the
+// sub-skills it references — NEVER a kernel change.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type { RenderingShape } from './rendering-shape';
+
+/**
+ * Scope under which a template is registered.
+ *
+ * - `SYSTEM` — kernel/platform-shipped (today: only the document-buddy
+ *   biome's built-ins ship under SYSTEM via the biome-folder seeder).
+ * - `BIOME` — contributed by an installed biome (other than the
+ *   document-buddy seed).
+ * - `ORG` — authored by an organization (via the design-system-builder
+ *   document-variant flow once that ships).
+ *
+ * Resolution precedence — most specific wins — is the same 5-tier rule
+ * used by skills and other biome-contributed primitives:
+ *   USER > ORG > PROJECT > BIOME > SYSTEM. (Templates are scoped only
+ *   to the three values above today; the wider 5-tier set leaves room
+ *   for project + user template variants without a future kernel
+ *   change.)
+ */
+export enum DocumentTemplateScope {
+  SYSTEM = 'SYSTEM',
+  BIOME = 'BIOME',
+  ORG = 'ORG',
+}
+
+/**
+ * Manifest the registry persists for one document template.
+ *
+ * `category` is intentionally a free-form string. The kernel never
+ * enumerates categories — that is the whole point of treating templates
+ * as content. Two biomes MAY ship templates in the same category (e.g.
+ * two `sales-proposal` variants); the registry surfaces both and the FE
+ * groups them by category.
+ *
+ * `skillRefs` are skill slugs the authoring agent loads on session bind.
+ * Today's pattern is hierarchical (e.g.
+ * `document-editor-rich/categories/sales-proposal`); the kernel does
+ * not interpret the strings, just hands them to skill-registry-api.
+ *
+ * `subAgents` are agent slugs delegated as sub-agents on the session's
+ * Agent Composition. The bar for declaring one is "needs its own model,
+ * tools, or context"; most templates leave this empty and rely on
+ * sub-skills (cheap, shared context).
+ *
+ * `seedContent` is optional HTML inserted into the new document's
+ * Page.content at create time. It uses the closed component-class
+ * vocabulary (see `@xemahq/document-themes-contracts`) so it renders
+ * correctly under any theme.
+ *
+ * `previewThumbnailUrl` is the URL the FE template gallery shows.
+ * Resolves to a static asset under the contributing biome's bundle.
+ */
+export interface DocumentTemplateManifest {
+  readonly slug: string;
+  readonly name: string;
+  readonly description: string;
+  readonly category: string;
+  readonly renderingShape: RenderingShape;
+  readonly defaultThemeRef: string;
+  readonly defaultPageFormat: string;
+  readonly defaultOrientation: 'PORTRAIT' | 'LANDSCAPE';
+  readonly skillRefs: readonly string[];
+  readonly subAgents?: readonly string[];
+  readonly seedContent?: string;
+  readonly previewThumbnailUrl?: string;
+  readonly version: string;
+  readonly scope: DocumentTemplateScope;
+}
+
+/**
+ * Wire-shape reference to a template — `<scope>:<slug>` (system or
+ * biome) or `<scope>:<orgId>:<slug>` (org). The kb-api template
+ * registry parses these into a `DocumentTemplateManifest` lookup.
+ */
+export type DocumentTemplateRef = string;

package/src/document-templates/lib/index.ts

@@ -0,0 +1,2 @@
+export * from './rendering-shape';
+export * from './document-template';

package/src/document-templates/lib/rendering-shape.ts

@@ -0,0 +1,48 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── RenderingShape ──
+//
+// Closed kernel enum that decides WHICH renderer materialises a rich
+// document at view, print, and export time. The only kernel-closed
+// dimension of a document — everything else (category, theme, skill
+// bundle) is template metadata (open).
+//
+// Adding a new shape is a coordinated kernel change: the enum here, the
+// Prisma enum on `pages.rendering_shape`, the FE branch in
+// `RichDocumentCanvas`, the server-side branch in `document-render-api`,
+// and a new `rendering-shape/<key>/SKILL.md` so the authoring agent
+// knows the patterns. Three shapes are sufficient for v1; resist
+// inventing a fourth before a concrete consumer demands it.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * The closed set of rendering pipelines a rich document can take.
+ *
+ * - `PAGINATED` — Paged.js in the browser preview, Chrome's native
+ *   `@page` rules at PDF export time. Multi-page reports, letters,
+ *   case studies, sales proposals, technical specs.
+ * - `ANIMATED_SLIDES` — Reveal.js slideshow with fragments + speaker
+ *   notes + fullscreen presenter mode. PDF export via Reveal's
+ *   `?print-pdf` flow (one PDF page per slide). EDIT-mode is still a
+ *   vertical stack of sized sheets — Reveal only loads in PRESENT.
+ * - `SINGLE_PAGE` — One white sheet, no pagination. Envelopes, lookbook
+ *   spreads, single-screen layouts.
+ */
+export enum RenderingShape {
+  PAGINATED = 'PAGINATED',
+  ANIMATED_SLIDES = 'ANIMATED_SLIDES',
+  SINGLE_PAGE = 'SINGLE_PAGE',
+}
+
+/** Total runtime guard projected over the closed set. */
+const RENDERING_SHAPE_VALUES: ReadonlySet<RenderingShape> = new Set([
+  RenderingShape.PAGINATED,
+  RenderingShape.ANIMATED_SLIDES,
+  RenderingShape.SINGLE_PAGE,
+]);
+
+export function isRenderingShape(value: unknown): value is RenderingShape {
+  return (
+    typeof value === 'string' &&
+    RENDERING_SHAPE_VALUES.has(value as RenderingShape)
+  );
+}

package/src/document-themes/index.ts

@@ -0,0 +1,21 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Document Themes — Kernel Contracts ──
+//
+// Kernel (Layer 1) contracts for the Document Theme primitive. Pure
+// types + closed enums — zero runtime deps, no NestJS, no Prisma.
+//
+// A Document Theme is a swappable styling layer for rich documents:
+//   - `manifest.json` — slug, name, description, supported shapes, version
+//   - `theme.json`    — token pack (CSS variables: color, type, space, …)
+//   - `theme.css`     — component CSS using ONLY the closed semantic-class
+//                       vocabulary declared in this package
+//
+// Swapping a theme on a document changes the visual identity (typography,
+// color, spacing, callout chrome) WITHOUT touching the document content
+// or its paper geometry. Themes are forbidden from setting page-frame
+// width/height — that is kernel-owned via the page row's pageFormat +
+// orientation.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/document-theme';
+export * from './lib/component-vocabulary';

package/src/document-themes/lib/component-vocabulary.ts

@@ -0,0 +1,100 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Closed component-class vocabulary ──
+//
+// THE contract that makes "swap the theme → boom, same content, new
+// look" true. Skills emit ONLY these classes; themes style ONLY these
+// classes. Adding a class is a coordinated change to the vocabulary
+// here PLUS at least the system default theme.
+//
+// The classes are organised by purpose. Each group is a frozen tuple so
+// runtime callers can iterate it deterministically (for validation,
+// theme-completeness lints, etc.). Tests in the kb-api theme module
+// assert every theme's `theme.css` selects every class in this list.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export const STRUCTURE_CLASSES = [
+  'xema-cover',
+  'xema-toc',
+  'xema-section',
+  'xema-sidebar',
+  'xema-footer',
+] as const;
+export type StructureClass = (typeof STRUCTURE_CLASSES)[number];
+
+export const TYPE_CLASSES = [
+  'xema-display',
+  'xema-title',
+  'xema-subtitle',
+  'xema-body',
+  'xema-caption',
+  'xema-overline',
+] as const;
+export type TypeClass = (typeof TYPE_CLASSES)[number];
+
+export const CALLOUT_CLASSES = [
+  'xema-callout--info',
+  'xema-callout--warn',
+  'xema-callout--success',
+  'xema-callout--danger',
+  'xema-pull-quote',
+] as const;
+export type CalloutClass = (typeof CALLOUT_CLASSES)[number];
+
+export const DATA_CLASSES = [
+  'xema-data-table',
+  'xema-kpi',
+  'xema-chart',
+  'xema-figure',
+] as const;
+export type DataClass = (typeof DATA_CLASSES)[number];
+
+/**
+ * Slide vocabulary — emitted only by ANIMATED_SLIDES documents. Reveal.js
+ * uses native `<section>` for slide boundaries; we add the `xema-slide`
+ * class so themes can style slides as a recognisable unit + we add
+ * fragment + speaker-notes hooks under the same prefix.
+ */
+export const SLIDE_CLASSES = [
+  'xema-slide',
+  'xema-slide-fragment',
+  'xema-slide-notes',
+] as const;
+export type SlideClass = (typeof SLIDE_CLASSES)[number];
+
+export const LETTER_CLASSES = [
+  'xema-letterhead',
+  'xema-address-block',
+  'xema-signature',
+] as const;
+export type LetterClass = (typeof LETTER_CLASSES)[number];
+
+/**
+ * The union of every class in the vocabulary. Use this as the only
+ * allowed lookup type when checking whether a class belongs to the
+ * vocabulary.
+ */
+export type DocumentComponentClass =
+  | StructureClass
+  | TypeClass
+  | CalloutClass
+  | DataClass
+  | SlideClass
+  | LetterClass;
+
+/** Flat readonly array for iteration / completeness checks. */
+export const ALL_COMPONENT_CLASSES: readonly DocumentComponentClass[] = [
+  ...STRUCTURE_CLASSES,
+  ...TYPE_CLASSES,
+  ...CALLOUT_CLASSES,
+  ...DATA_CLASSES,
+  ...SLIDE_CLASSES,
+  ...LETTER_CLASSES,
+];
+
+const VOCABULARY_SET: ReadonlySet<string> = new Set(ALL_COMPONENT_CLASSES);
+
+export function isDocumentComponentClass(
+  value: unknown,
+): value is DocumentComponentClass {
+  return typeof value === 'string' && VOCABULARY_SET.has(value);
+}