@xemahq/kernel-contracts 0.14.0 → 0.16.0

package/src/agent-session/lib/lifecycle.ts

@@ -0,0 +1,156 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Agent-session lifecycle — SINGLE SOURCE OF TRUTH ──
+//
+// The closed `SessionLifecycleState` / `SessionOwnerKind` value sets + the
+// transition FSM for an agent-session row. This is the canonical Layer-0
+// contract that the persistence enum (agent-session-api Prisma `SessionStatus`
+// / `SessionOwnerKind`), the service's in-tree state machine, and the
+// runtime worker mirror ALL derive from — collapsing the former three hand-
+// maintained copies into one. Prisma cannot import a TS value, so its schema
+// re-declares the same members and CI guards parity
+// (`tooling/boundaries/check-session-enum-parity.mjs`).
+//
+// `canTransition()` is the single predicate every caller (interactive sessions
+// AND the workflow-runtime worker dispatch activity) consults before issuing a
+// state-change HTTP call, so misuse fails fast at compile time rather than as a
+// 409 from the service.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { z } from 'zod';
+
+/**
+ * Lifecycle state of an agent-session row. Value-identical to the persisted
+ * `session_status` Prisma enum. Closed set.
+ */
+export const SessionLifecycleState = {
+  creating: 'creating',
+  provisioning: 'provisioning',
+  active: 'active',
+  paused: 'paused',
+  recovering: 'recovering',
+  completing: 'completing',
+  completed: 'completed',
+  failed: 'failed',
+  archived: 'archived',
+} as const;
+
+export type SessionLifecycleStateValue =
+  (typeof SessionLifecycleState)[keyof typeof SessionLifecycleState];
+
+export const SessionLifecycleStateSchema = z.enum(
+  Object.values(SessionLifecycleState) as [
+    SessionLifecycleStateValue,
+    ...SessionLifecycleStateValue[],
+  ],
+);
+
+/**
+ * Who created the session row. Value-identical to the persisted
+ * `session_owner_kind` Prisma enum.
+ *
+ *   - `interactive_session`  — user-facing chat sessions
+ *   - `pipeline_run`         — workflow-runtime-worker redraft loop spines
+ *   - `chat_thread`          — reserved (no dispatcher today)
+ */
+export const SessionOwnerKind = {
+  interactive_session: 'interactive_session',
+  pipeline_run: 'pipeline_run',
+  chat_thread: 'chat_thread',
+} as const;
+
+export type SessionOwnerKindValue =
+  (typeof SessionOwnerKind)[keyof typeof SessionOwnerKind];
+
+export const SessionOwnerKindSchema = z.enum(
+  Object.values(SessionOwnerKind) as [
+    SessionOwnerKindValue,
+    ...SessionOwnerKindValue[],
+  ],
+);
+
+/**
+ * Per-state transition matrix. `canTransition(from, to)` returns true iff the
+ * transition is valid.
+ *
+ * Notable transitions:
+ *   - `paused → recovering` (resume claim)
+ *   - `recovering → active` (resume success)
+ *   - `recovering → paused` (resume rollback)
+ *   - `active → completing → completed` (terminal success)
+ *   - any-non-terminal → `failed` (terminal failure)
+ *   - `paused | completed | failed → archived` (cleanup sweep)
+ */
+const TRANSITIONS: Readonly<
+  Record<SessionLifecycleStateValue, ReadonlySet<SessionLifecycleStateValue>>
+> = {
+  creating: new Set([
+    SessionLifecycleState.provisioning,
+    SessionLifecycleState.failed,
+  ]),
+  provisioning: new Set([
+    SessionLifecycleState.active,
+    SessionLifecycleState.failed,
+  ]),
+  active: new Set([
+    SessionLifecycleState.paused,
+    SessionLifecycleState.completing,
+    SessionLifecycleState.failed,
+  ]),
+  paused: new Set([
+    SessionLifecycleState.recovering,
+    SessionLifecycleState.archived,
+    SessionLifecycleState.failed,
+  ]),
+  recovering: new Set([
+    SessionLifecycleState.active,
+    SessionLifecycleState.paused,
+    SessionLifecycleState.failed,
+  ]),
+  completing: new Set([
+    SessionLifecycleState.completed,
+    SessionLifecycleState.failed,
+  ]),
+  completed: new Set([SessionLifecycleState.archived]),
+  failed: new Set([SessionLifecycleState.archived]),
+  archived: new Set(),
+};
+
+export function canTransition(
+  from: SessionLifecycleStateValue,
+  to: SessionLifecycleStateValue,
+): boolean {
+  return TRANSITIONS[from].has(to);
+}
+
+/**
+ * Terminal states — no further transitions possible (except the
+ * `completed | failed → archived` cleanup sweep). Callers use this to
+ * short-circuit "is this session done?" checks.
+ */
+export function isTerminal(state: SessionLifecycleStateValue): boolean {
+  return (
+    state === SessionLifecycleState.completed ||
+    state === SessionLifecycleState.failed ||
+    state === SessionLifecycleState.archived
+  );
+}
+
+/**
+ * Pausable states — the session has a live worker that can be told to
+ * snapshot. `provisioning` is intentionally excluded: the worker isn't ready
+ * yet, so a pause request would 409. Callers receiving such a 409 should retry
+ * with backoff once `active` is reached.
+ */
+export function isPausable(state: SessionLifecycleStateValue): boolean {
+  return state === SessionLifecycleState.active;
+}
+
+/**
+ * Resumable states. `paused` is the canonical case. `failed` rows are NOT
+ * resumable from here — they require explicit operator action (the resume API
+ * would 409). `recovering` is a transient state owned by an in-flight resume;
+ * another caller observing it should back off.
+ */
+export function isResumable(state: SessionLifecycleStateValue): boolean {
+  return state === SessionLifecycleState.paused;
+}

package/src/agent-workspace/lib/workspace-layout.ts

@@ -35,19 +35,6 @@ export enum WorkspaceMount {
   Instructions = '/workspace/.xema/instructions',
 }
 
-// `WorkspaceRole` is the role the running session takes. The canonical
-// values + helpers live in `@xemahq/workflow-contracts:agent-role` —
-// re-exported here as `WorkspaceRole` for back-compat with consumers
-// that imported from this module. New code should import `AgentRunRole`
-// directly from `@xemahq/workflow-contracts`.
-export {
-  AGENT_RUN_ROLES as WORKSPACE_ROLES,
-  AGENT_RUN_ROLES_INTERACTIVE as WORKSPACE_ROLES_INTERACTIVE,
-  AGENT_RUN_ROLES_PIPELINE as WORKSPACE_ROLES_PIPELINE,
-  isAgentRunRole as isWorkspaceRole,
-  type AgentRunRole as WorkspaceRole,
-} from '../../workflow';
-
 /**
  * Mount mode the worker requests. Read-only mounts are `chmod a-w` at
  * attach-time so the kernel enforces immutability; writable mounts

package/src/biome/index.ts

@@ -7,7 +7,6 @@ export * from './lib/biome-audience';
 export * from './lib/biome-origin';
 export * from './lib/biome-trust-tier';
 export * from './lib/biome-availability-grant';
-export * from './lib/biome-api';
 export * from './lib/biome-lifecycle-hooks';
 export * from './lib/biome-engines';
 export * from './lib/biome-permissions';

package/src/biome/lib/biome-manifest.ts

@@ -13,21 +13,18 @@ import {
   MigrationRunnerKind,
   OrgDatabasePurpose,
 } from '../../org-database';
-// Import from the specific runner lib files, NOT the `../../runner` barrel.
-// The barrel re-exports `input-hash` (a server-only util with a top-level
-// `require('node:crypto')`); pulling the barrel here drags `node:crypto` into
-// every browser consumer of `@xemahq/kernel-contracts/biome` (e.g. host-web's
-// BiomeNewPage), which webpack cannot bundle (UnhandledSchemeError). These
-// three symbols carry no crypto dependency.
-import { DataLocalitySchema } from '../../runner/lib/runner-registration';
-import { RuntimeIsolationLevelSchema } from '../../runner/lib/runtime-isolation';
-import { RunnerTrustTier } from '../../runner/lib/runner';
+import {
+  DataLocalitySchema,
+  RuntimeIsolationLevelSchema,
+  RunnerTrustTier,
+} from '../../runner';
 import { z } from 'zod';
 import {
   BiomeAudience,
   BiomeAudienceSchema,
   DEFAULT_BIOME_AUDIENCE,
 } from './biome-audience';
+import { BiomeOriginSchema } from './biome-origin';
 import {
   BiomeEnginesSchema,
 } from './biome-engines';
@@ -129,18 +126,6 @@ const LEGACY_SHIPS_CONTENT_DIR: Readonly<Record<string, string>> = {
   provisioningScaffolds: 'provisioning',
 };
 
-const LEGACY_SHIPS_MODULES_DIR: Readonly<Record<string, string>> = {
-  agents: 'agents',
-  actions: 'actions',
-  mountSourceKinds: 'mount-source-kinds',
-  deliverableSpecKinds: 'deliverable-spec-kinds',
-  runtimeMountKinds: 'runtime-mount-kinds',
-  workspaceSpecOverlay: 'workspace-spec-overlay',
-  systemOverlayContributions: 'system-overlay-contributions',
-  adapterKinds: 'adapter-kinds',
-  integrationProviders: 'integration-providers',
-};
-
 /**
  * Resolve a legacy `ships.content[]` value to its conventional directory
  * name, or `null` for unknown tokens. Used by the legacy file-walk
@@ -157,21 +142,6 @@ export function contentKindToDir(kind: string): string {
   return dir;
 }
 
-/**
- * Resolve a legacy `ships.modules[]` value to its conventional directory
- * name. Same legacy-only scope as `contentKindToDir`.
- */
-export function moduleKindToDir(kind: string): string {
-  const dir = LEGACY_SHIPS_MODULES_DIR[kind];
-  if (!dir) {
-    throw new Error(
-      `biome-host-sdk: unknown legacy ships.modules[] value "${kind}". ` +
-        `Either migrate the biome to xema.contributions or extend LEGACY_SHIPS_MODULES_DIR.`,
-    );
-  }
-  return dir;
-}
-
 /**
  * Org-managed database declaration for biomes that need a dedicated
  * schema in a provisioned org database.
@@ -335,19 +305,6 @@ export const BiomeShipsSchema = z
   .strict();
 export type BiomeShips = z.infer<typeof BiomeShipsSchema>;
 
-/**
- * Manifest-shape hosting/trust posture for a server biome. Used by
- * integration-host plumbing (Phase 7) to decide whether to load
- * adapter-contribution modules in-process or via a sidecar deployment.
- * Manifests authored by Xema and audited third parties may set
- * `first-party`; everything else defaults to `third-party`.
- *
- * Kept manifest-internal (not re-exported) so it does not collide with the
- * kernel `BiomeTrustTier` provenance enum (`first-party | verified-store |
- * community-store | …`) already exposed by this package.
- */
-const ManifestBiomeTrustTierSchema = z.enum(['first-party', 'third-party']);
-
 /**
  * AdapterKind slug — accepts a built-in slug verbatim, plus any
  * lowercase kebab-case slug a biome-contributed kind could register.
@@ -765,10 +722,12 @@ const ServerBiomeXemaSchema = z
     ships: BiomeShipsSchema.optional(),
     capabilities: ServerBiomeCapabilitiesSchema.optional(),
     /**
-     * Hosting posture for adapter-contribution modules (Phase 7). Other
-     * biome kinds ignore this field. Defaults to `third-party`.
+     * Hosting/provenance posture for adapter-contribution modules (Phase 7).
+     * The same `first-party | third-party` set as {@link BiomeOrigin} (which
+     * documents this very field) — uses `BiomeOriginSchema` so the two cannot
+     * drift. Other biome kinds ignore this field. Defaults to `third-party`.
      */
-    trustTier: ManifestBiomeTrustTierSchema.optional(),
+    trustTier: BiomeOriginSchema.optional(),
     /**
      * Integration dependencies the biome needs to be useful. Surfaced
      * to the install wizard as a consent screen. Non-optional entries

package/src/biome/lib/biome-origin.ts

@@ -11,9 +11,10 @@ import { z } from 'zod';
  * and is not knowable from source. Keep the two separate — the distribution
  * trust gate operates on origin, not on install-time provenance.
  *
- * Closed set; new values are a kernel change. (Seam: the biome-sdk manifest's
- * own 2-value `BiomeTrustTierSchema` should migrate to import this enum so the
- * posture has a single source of truth.)
+ * Closed set; new values are a kernel change. This IS the single source of
+ * truth: the `xema-biome.json` manifest schema (`BiomeXemaSchema.trustTier`)
+ * validates against `BiomeOriginSchema`, and biome-sdk re-exports that schema
+ * rather than declaring its own — so the posture cannot drift.
  */
 export enum BiomeOrigin {
   FirstParty = 'first-party',

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

@@ -7,6 +7,10 @@ import {
   type BiomeTarget,
   type BiomeOrigin,
 } from '../../biome';
+import {
+  PlatformServiceTierSchema,
+  type PlatformServiceTier,
+} from './distribution';
 
 /**
  * A single biome as resolved into a distribution lockfile. Version-pinned and
@@ -63,12 +67,12 @@ export const LockedBiomeSchema = z.object({
 export interface LockedPlatformService {
   name: string;
   /** Wave/boot tier — drives ordering in the generated bring-up plan. */
-  tier: BiomeTier | 'edge';
+  tier: PlatformServiceTier;
 }
 
 export const LockedPlatformServiceSchema = z.object({
   name: z.string().min(1),
-  tier: z.union([BiomeTierSchema, z.literal('edge')]),
+  tier: PlatformServiceTierSchema,
 }) as z.ZodType<LockedPlatformService>;
 
 /**

package/src/distribution/lib/distribution.ts

@@ -1,10 +1,29 @@
 import { z } from 'zod';
-import { BiomeOriginSchema, type BiomeOrigin } from '../../biome';
+import {
+  BiomeOriginSchema,
+  BiomeTierSchema,
+  type BiomeOrigin,
+  type BiomeTier,
+} from '../../biome';
 import {
   DistributionSelectorSchema,
   type DistributionSelector,
 } from './distribution-selector';
 
+/**
+ * Wave/boot tier of a platform-substrate service — the four {@link BiomeTier}
+ * waves (`kernel | system | base | platform`) plus `edge` for the outermost,
+ * browser-facing wave. Single source of truth for BOTH the distribution
+ * manifest ({@link DistributionPlatformService}) and the resolved lock
+ * (`LockedPlatformService`), so the tier vocabulary can never drift between them.
+ */
+export type PlatformServiceTier = BiomeTier | 'edge';
+
+export const PlatformServiceTierSchema = z.union([
+  BiomeTierSchema,
+  z.literal('edge'),
+]) as z.ZodType<PlatformServiceTier>;
+
 /**
  * Schema-versioning seed for `xema-distribution.json`. Bumped via a coordinated
  * PR on an incompatible shape change; consumers refuse versions they do not
@@ -37,12 +56,12 @@ export const DistributionTrustPolicySchema = z.object({
 export interface DistributionPlatformService {
   name: string;
   /** Wave/boot tier — drives ordering in the generated bring-up plan. */
-  tier: 'kernel' | 'system' | 'base' | 'platform' | 'edge';
+  tier: PlatformServiceTier;
 }
 
 export const DistributionPlatformServiceSchema = z.object({
   name: z.string().min(1),
-  tier: z.enum(['kernel', 'system', 'base', 'platform', 'edge']),
+  tier: PlatformServiceTierSchema,
 }) as z.ZodType<DistributionPlatformService>;
 
 /**

package/src/execution-context/lib/execution-context.ts

@@ -64,14 +64,11 @@ export const ExecutionContextBiomeSchema = z.object({
  * v4.3 §A.3).
  *
  * `id` is the canonical `environment:<slug>` ref (string-typed here to
- * keep the envelope JSON-clean — the kernel-side reference type lives in
- * `@xemahq/execution-environment-contracts`).
+ * keep the envelope JSON-clean — the kernel-side reference type lives in the
+ * `@xemahq/kernel-contracts/execution-environment` surface).
  *
- * `kind` is the {@link ExecutionEnvironmentKind} value matched against the eight
- * built-in environments + the `trusted-dev` escape hatch. The internal
- * identifier `ExecutionEnvironmentKind` is still named "Zone" — the rename to
- * `ExecutionEnvironmentKind` is scheduled for Phase A.5 (plan §A.1
- * follow-up sweep), not Phase A.3.
+ * `kind` is the {@link ExecutionEnvironmentKind} value matched against the
+ * built-in environments + the `trusted-dev` escape hatch.
  */
 export interface ExecutionContextEnvironment {
   id: string;

package/src/execution-environment/lib/execution-environment.ts

@@ -53,10 +53,10 @@ export interface ParsedExecutionEnvironmentRef {
 
 /**
  * Structured error thrown by `parseEnvironmentRef` / `formatEnvironmentRef`.
- * Carries the stable `EXECUTION_ENVIRONMENT_REF_INVALID` code. Subclass
- * of `CapabilityError` so call sites that already branch on capability-
- * layer errors get this for free; the dedicated code keeps the denial
- * taxonomy crisp.
+ * A subclass of `CapabilityError` carrying `CapabilityErrorCode.CapabilityRefInvalid`
+ * — an environment ref IS a capability-layer ref, so call sites that already
+ * branch on `CapabilityRefInvalid` handle it uniformly. The subclass `name`
+ * (`ExecutionEnvironmentRefParseError`) distinguishes it for diagnostics.
  */
 export class ExecutionEnvironmentRefParseError extends CapabilityError {
   constructor(args: { message: string; raw: string }) {
@@ -69,9 +69,6 @@ export class ExecutionEnvironmentRefParseError extends CapabilityError {
   }
 }
 
-/** Stable wire code for `ExecutionEnvironmentRefParseError`. */
-export const EXECUTION_ENVIRONMENT_REF_INVALID = 'EXECUTION_ENVIRONMENT_REF_INVALID';
-
 /**
  * Parse an `ExecutionEnvironmentRef` string into its structured parts.
  * Throws `ExecutionEnvironmentRefParseError` on any grammar violation —

package/src/object/lib/xema-object-kind.ts

@@ -19,8 +19,8 @@ export enum XemaObjectKind {
   ExternalSubject = 'external-subject',
   DelegatedSession = 'delegated-session',
 
-  // Agent runtime primitives — a base kernel armed into an Agent
-  AgentKernel = 'agent-kernel',
+  // Agent runtime primitives. A "kernel" is just an Agent with no subagents —
+  // there is no separate AgentKernel object kind (unified-Agent model).
   Agent = 'agent',
   Skill = 'skill',
   Tool = 'tool',

package/src/object/lib/xema-object-ref.ts

@@ -106,10 +106,30 @@ function parseScope(segments: string[], ref: string): ScopeParse {
         consumed: 2,
       };
     }
+    case 'sessions': {
+      const sessionId = requireSegment(segments, 1, ref, 'sessionId');
+      return {
+        scope: { tier: SpaceKind.Session, sessionId },
+        consumed: 2,
+      };
+    }
     case 'orgs': {
       const orgId = requireSegment(segments, 1, ref, 'orgId');
       if (segments.length >= 4 && segments[2] === 'projects') {
         const projectId = requireSegment(segments, 3, ref, 'projectId');
+        // …/projects/<p>/apps/<a> — the App tier (most specific under a project).
+        if (segments.length >= 6 && segments[4] === 'apps') {
+          const appId = requireSegment(segments, 5, ref, 'appId');
+          return {
+            scope: {
+              tier: SpaceKind.App,
+              orgId,
+              projectId,
+              appId,
+            },
+            consumed: 6,
+          };
+        }
         return {
           scope: {
             tier: SpaceKind.Project,
@@ -127,7 +147,7 @@ function parseScope(segments: string[], ref: string): ScopeParse {
     default:
       throw new XemaObjectRefParseError(
         ref,
-        `unknown scope head "${head}" (expected one of: system, biomes, orgs, users)`,
+        `unknown scope head "${head}" (expected one of: system, biomes, orgs, users, sessions)`,
       );
   }
 }

package/src/policy/lib/obligations.ts

@@ -36,11 +36,11 @@ export const PolicyObligationKindSchema = z.nativeEnum(PolicyObligationKind);
  * (`require-runner-kind`) and by `RouteHint.preferredRunnerKind` (plan
  * v4.3 §2 / §A.4).
  *
- * This is the POLICY view of a runner — the dimension policy selects on
- * to route an invocation. Phase F will unify this with the transport-
- * level `RunnerKind` in `@xemahq/runner-contracts`
- * (Embedded/LocalModule/Remote/McpExternal); for Phase A this enum lives
- * inline in `@xemahq/policy-contracts` per the plan.
+ * This is the canonical `RunnerKind` — the policy decision layer is its
+ * primary author (policy selects on it to route an invocation), so it lives
+ * in the `policy` surface. The `runner` surface re-exports it
+ * (`runner/lib/runner-kind.ts`) so runner-side consumers get a single source
+ * of truth with no second declaration to drift against.
  */
 export enum RunnerKind {
   Local = 'local',

package/src/reference-resolution/lib/reference-resolution.ts

@@ -1,10 +1,12 @@
 // ═══════════════════════════════════════════════════════════════════════════
 // ── Reference Resolution — graceful-degradation decision (DBM.1) ──
 //
-// The ONE shared contract every resolver uses when it walks a definition's
+// The shared contract a resolver SHOULD use when it walks a definition's
 // declared references (an Agent node's `agentRef`, a skill's sub-skill, an
 // action's capability, a workflow's `uses:`) and asks "is this reference
-// available right now, and what do I do if it isn't?".
+// available right now, and what do I do if it isn't?". This is the Layer-0
+// vocabulary for DBM.1; the per-resolver wiring is rolled out incrementally,
+// so not every resolver consumes it yet.
 //
 // It exists because of DYNAMIC BIOME MODULARITY: a definition authored while
 // biome X was installed keeps referencing X's contributions after X is

package/src/runner/index.ts

@@ -8,4 +8,3 @@ export * from './lib/runner-registration';
 export * from './lib/runner-plane';
 export * from './lib/runner-job';
 export * from './lib/dispatch';
-export * from './lib/input-hash';

package/src/runner-input-hash/index.ts

@@ -0,0 +1 @@
+export * from './lib/input-hash';

package/src/{runner → runner-input-hash}/lib/input-hash.ts

@@ -24,6 +24,13 @@ import { createHash } from 'node:crypto';
  *   - arrays preserve order;
  *   - non-JSON values (`bigint`, `function`, `symbol`, non-finite numbers)
  *     are rejected — capability input is JSON, never a host object.
+ *
+ * NOTE: this is the ONE module in `@xemahq/kernel-contracts` that depends on
+ * a Node built-in (`node:crypto`). It lives in its own `runner-input-hash`
+ * subpath — separate from the `runner` contract barrel — so the rest of the
+ * package stays isomorphic and browser-bundleable. Server-only consumers
+ * (router gateway, runner verifier, kernel-server) import it from
+ * `@xemahq/kernel-contracts/runner-input-hash`.
  */
 export function canonicalCapabilityInputHash(input: unknown): string {
   const canonical = canonicalize(input === undefined ? {} : input);

package/src/search-source/lib/search-replay.ts

@@ -47,16 +47,6 @@ export function isSearchReplayCapabilityRef(ref: string): boolean {
   return SEARCH_REPLAY_REF_REGEX.test(ref);
 }
 
-/**
- * Extract the `sourceKey` (domain segment) from a replay capability ref, or
- * `null` when `ref` is not a replay ref. Used by the capability-router to map
- * a replay ref to the owning source's HTTP endpoint.
- */
-export function searchSourceKeyFromReplayRef(ref: string): string | null {
-  const match = SEARCH_REPLAY_REF_REGEX.exec(ref);
-  return match?.[1] ?? null;
-}
-
 /**
  * Backfill request search sends to a source's replay capability (via
  * capability-router — NOT a direct client call). Paginated so a large source

package/src/service-registry/lib/service-names.generated.ts

@@ -25,8 +25,10 @@ export const ServiceName = {
   BIOME_HOST_API: 'biome-host-api',
   CAPABILITY_REGISTRY_API: 'capability-registry-api',
   CATALOG_API: 'catalog-api',
+  CHANNEL_GATEWAY_API: 'channel-gateway-api',
   CONNECTOR_GATEWAY_API: 'connector-gateway-api',
   CONTAINER_REGISTRY_API: 'container-registry-api',
+  CONTROL_PLANE_API: 'control-plane-api',
   CREDENTIAL_BROKER_API: 'credential-broker-api',
   DELIVERABLE_SPECS_API: 'deliverable-specs-api',
   DESIGN_SYSTEM_BUILDER_API: 'design-system-builder-api',
@@ -53,6 +55,7 @@ export const ServiceName = {
   WORKFLOW_RUNTIME_WORKER: 'workflow-runtime-worker',
   WORKLOAD_RUNTIME_API: 'workload-runtime-api',
   WORKSPACE_GIT_API: 'workspace-git-api',
+  WORKSPACE_MATERIALIZATION_API: 'workspace-materialization-api',
   WORKSPACE_ORCHESTRATOR_API: 'workspace-orchestrator-api',
   WORKSPACE_PROXY: 'workspace-proxy',
   WORKSPACE_STORAGE_POOL_API: 'workspace-storage-pool-api',

package/src/workflow/index.ts

@@ -38,8 +38,6 @@ export * from './lib/domain-tag';
 // hierarchy, and gate-reviewer map were relocated to the software-dev biome
 // (`biomes/platform/software-dev/workflow-config/phase-config.json`) — the
 // kernel carries no domain phase enum.
-export * from './lib/workflow-stage';
 export * from './lib/phase-report';
 export * from './lib/work-item-payloads';
-export * from './lib/sampling-profiles';
 export * from './lib/canonical-concepts';

package/src/workflow/lib/catalog-taxonomies.ts

@@ -14,6 +14,8 @@
 // Resource types use "group/name" notation (e.g. "database/postgresql").
 // ═══════════════════════════════════════════════════════════════════════════
 
+import { COMPLEXITY_TIERS, type ComplexityTier } from './phase-report';
+
 // ── Common Interfaces ──────────────────────────────────────────────────
 
 /**
@@ -129,42 +131,46 @@ export const ITEM_TYPE_VALUES = ITEM_TYPE_CATALOG.map((t) => t.value);
 export type ItemType = (typeof ITEM_TYPE_VALUES)[number];
 
 // ── Complexity Tiers ───────────────────────────────────────────────────
-// Used by: pipeline runs, doc-template matching, agent model selection
-// NOTE: COMPLEXITY_TIERS and ComplexityTier are also in phase-report.ts
-// for backward compat. This is the canonical rich definition.
-
-export const COMPLEXITY_CATALOG: CatalogEntry[] = [
-  {
-    value: 'simple',
+// Used by: pipeline runs, doc-template matching, agent model selection.
+//
+// SINGLE SOURCE OF TRUTH for the value set is `COMPLEXITY_TIERS` /
+// `ComplexityTier` in ./phase-report. This catalog only layers presentation
+// metadata (label/hint/color/sortOrder) — keyed by `ComplexityTier`, so adding
+// or removing a tier in phase-report makes this a COMPILE error rather than a
+// silent drift between the two definitions.
+const COMPLEXITY_PRESENTATION: Record<
+  ComplexityTier,
+  Omit<CatalogEntry, 'value'>
+> = {
+  simple: {
     label: 'Simple',
     hint: 'Single service, few files, straightforward logic. ~1-3 day effort.',
     color: 'bg-green-100 text-green-700',
     sortOrder: 0,
   },
-  {
-    value: 'standard',
+  standard: {
     label: 'Standard',
     hint: 'Multi-file changes within 1-2 services. Moderate complexity. ~3-7 day effort.',
     color: 'bg-blue-100 text-blue-700',
     sortOrder: 1,
   },
-  {
-    value: 'complex',
+  complex: {
     label: 'Complex',
     hint: 'Multi-service changes, new APIs, database migrations. ~1-3 week effort.',
     color: 'bg-orange-100 text-orange-700',
     sortOrder: 2,
   },
-  {
-    value: 'enterprise',
+  enterprise: {
     label: 'Enterprise',
     hint: 'Cross-system integration, new microservices, major architectural changes. ~1+ month effort.',
     color: 'bg-red-100 text-red-700',
     sortOrder: 3,
   },
-];
+};
 
-export const COMPLEXITY_VALUES = COMPLEXITY_CATALOG.map((c) => c.value);
+export const COMPLEXITY_CATALOG: CatalogEntry[] = COMPLEXITY_TIERS.map(
+  (value) => ({ value, ...COMPLEXITY_PRESENTATION[value] }),
+);
 
 // ── Status Definitions ─────────────────────────────────────────────────
 // Used by: backlog items