@xemahq/kernel-contracts 0.1.0

package/dist/workflow/lib/workspace-manifest-enums.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MANIFEST_GIT_PUSH_CONCURRENCY_MODES = exports.ManifestGitPushConcurrencyMode = exports.MANIFEST_GIT_PUSH_BRANCH_SUFFIXES = exports.ManifestGitPushBranchSuffix = exports.MANIFEST_SURFACES = exports.ManifestSurface = exports.OUTPUT_SURFACE_KINDS = exports.OutputSurfaceKind = exports.CREDENTIAL_KINDS = exports.CredentialKind = exports.TOOLSET_KEYS = exports.ToolsetKey = void 0;
+var ToolsetKey;
+(function (ToolsetKey) {
+    ToolsetKey["READ"] = "read";
+    ToolsetKey["WRITE"] = "write";
+    ToolsetKey["EXEC"] = "exec";
+    ToolsetKey["WEB"] = "web";
+    ToolsetKey["MCP"] = "mcp";
+    ToolsetKey["DELEGATE"] = "delegate";
+})(ToolsetKey || (exports.ToolsetKey = ToolsetKey = {}));
+exports.TOOLSET_KEYS = [
+    ToolsetKey.READ,
+    ToolsetKey.WRITE,
+    ToolsetKey.EXEC,
+    ToolsetKey.WEB,
+    ToolsetKey.MCP,
+    ToolsetKey.DELEGATE,
+];
+var CredentialKind;
+(function (CredentialKind) {
+    CredentialKind["LLM_PROVIDER"] = "llm-provider";
+    CredentialKind["SCM_TOKEN"] = "scm-token";
+    CredentialKind["OAUTH_BEARER"] = "oauth-bearer";
+    CredentialKind["MCP_AUTH"] = "mcp-auth";
+    CredentialKind["WALLET_ENTRY"] = "wallet-entry";
+    CredentialKind["GENERIC_SECRET"] = "generic-secret";
+})(CredentialKind || (exports.CredentialKind = CredentialKind = {}));
+exports.CREDENTIAL_KINDS = [
+    CredentialKind.LLM_PROVIDER,
+    CredentialKind.SCM_TOKEN,
+    CredentialKind.OAUTH_BEARER,
+    CredentialKind.MCP_AUTH,
+    CredentialKind.WALLET_ENTRY,
+    CredentialKind.GENERIC_SECRET,
+];
+var OutputSurfaceKind;
+(function (OutputSurfaceKind) {
+    OutputSurfaceKind["NONE"] = "none";
+    OutputSurfaceKind["WEB"] = "web";
+    OutputSurfaceKind["STATIC"] = "static";
+    OutputSurfaceKind["APP"] = "app";
+    OutputSurfaceKind["TUNNEL"] = "tunnel";
+})(OutputSurfaceKind || (exports.OutputSurfaceKind = OutputSurfaceKind = {}));
+exports.OUTPUT_SURFACE_KINDS = [
+    OutputSurfaceKind.NONE,
+    OutputSurfaceKind.WEB,
+    OutputSurfaceKind.STATIC,
+    OutputSurfaceKind.APP,
+    OutputSurfaceKind.TUNNEL,
+];
+var ManifestSurface;
+(function (ManifestSurface) {
+    ManifestSurface["WORKFLOW"] = "workflow";
+    ManifestSurface["AGENT_SESSION"] = "agent-session";
+})(ManifestSurface || (exports.ManifestSurface = ManifestSurface = {}));
+exports.MANIFEST_SURFACES = [
+    ManifestSurface.WORKFLOW,
+    ManifestSurface.AGENT_SESSION,
+];
+var ManifestGitPushBranchSuffix;
+(function (ManifestGitPushBranchSuffix) {
+    ManifestGitPushBranchSuffix["SESSION_ID"] = "sessionId";
+    ManifestGitPushBranchSuffix["PROJECT_ID"] = "projectId";
+})(ManifestGitPushBranchSuffix || (exports.ManifestGitPushBranchSuffix = ManifestGitPushBranchSuffix = {}));
+exports.MANIFEST_GIT_PUSH_BRANCH_SUFFIXES = [
+    ManifestGitPushBranchSuffix.SESSION_ID,
+    ManifestGitPushBranchSuffix.PROJECT_ID,
+];
+var ManifestGitPushConcurrencyMode;
+(function (ManifestGitPushConcurrencyMode) {
+    ManifestGitPushConcurrencyMode["FORCE"] = "force";
+    ManifestGitPushConcurrencyMode["LEASE"] = "lease";
+})(ManifestGitPushConcurrencyMode || (exports.ManifestGitPushConcurrencyMode = ManifestGitPushConcurrencyMode = {}));
+exports.MANIFEST_GIT_PUSH_CONCURRENCY_MODES = [
+    ManifestGitPushConcurrencyMode.FORCE,
+    ManifestGitPushConcurrencyMode.LEASE,
+];
+//# sourceMappingURL=workspace-manifest-enums.js.map

package/dist/workflow/lib/workspace-manifest-enums.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-manifest-enums.js","sourceRoot":"","sources":["../../../src/workflow/lib/workspace-manifest-enums.ts"],"names":[],"mappings":";;;AAqBA,IAAY,UAOX;AAPD,WAAY,UAAU;IACpB,2BAAa,CAAA;IACb,6BAAe,CAAA;IACf,2BAAa,CAAA;IACb,yBAAW,CAAA;IACX,yBAAW,CAAA;IACX,mCAAqB,CAAA;AACvB,CAAC,EAPW,UAAU,0BAAV,UAAU,QAOrB;AAEY,QAAA,YAAY,GAA0B;IACjD,UAAU,CAAC,IAAI;IACf,UAAU,CAAC,KAAK;IAChB,UAAU,CAAC,IAAI;IACf,UAAU,CAAC,GAAG;IACd,UAAU,CAAC,GAAG;IACd,UAAU,CAAC,QAAQ;CACX,CAAC;AAcX,IAAY,cAOX;AAPD,WAAY,cAAc;IACxB,+CAA6B,CAAA;IAC7B,yCAAuB,CAAA;IACvB,+CAA6B,CAAA;IAC7B,uCAAqB,CAAA;IACrB,+CAA6B,CAAA;IAC7B,mDAAiC,CAAA;AACnC,CAAC,EAPW,cAAc,8BAAd,cAAc,QAOzB;AAEY,QAAA,gBAAgB,GAA8B;IACzD,cAAc,CAAC,YAAY;IAC3B,cAAc,CAAC,SAAS;IACxB,cAAc,CAAC,YAAY;IAC3B,cAAc,CAAC,QAAQ;IACvB,cAAc,CAAC,YAAY;IAC3B,cAAc,CAAC,cAAc;CACrB,CAAC;AAYX,IAAY,iBAMX;AAND,WAAY,iBAAiB;IAC3B,kCAAa,CAAA;IACb,gCAAW,CAAA;IACX,sCAAiB,CAAA;IACjB,gCAAW,CAAA;IACX,sCAAiB,CAAA;AACnB,CAAC,EANW,iBAAiB,iCAAjB,iBAAiB,QAM5B;AAEY,QAAA,oBAAoB,GAAiC;IAChE,iBAAiB,CAAC,IAAI;IACtB,iBAAiB,CAAC,GAAG;IACrB,iBAAiB,CAAC,MAAM;IACxB,iBAAiB,CAAC,GAAG;IACrB,iBAAiB,CAAC,MAAM;CAChB,CAAC;AAQX,IAAY,eAGX;AAHD,WAAY,eAAe;IACzB,wCAAqB,CAAA;IACrB,kDAA+B,CAAA;AACjC,CAAC,EAHW,eAAe,+BAAf,eAAe,QAG1B;AAEY,QAAA,iBAAiB,GAA+B;IAC3D,eAAe,CAAC,QAAQ;IACxB,eAAe,CAAC,aAAa;CACrB,CAAC;AAUX,IAAY,2BAGX;AAHD,WAAY,2BAA2B;IACrC,uDAAwB,CAAA;IACxB,uDAAwB,CAAA;AAC1B,CAAC,EAHW,2BAA2B,2CAA3B,2BAA2B,QAGtC;AAEY,QAAA,iCAAiC,GAA2C;IACvF,2BAA2B,CAAC,UAAU;IACtC,2BAA2B,CAAC,UAAU;CAC9B,CAAC;AAMX,IAAY,8BAGX;AAHD,WAAY,8BAA8B;IACxC,iDAAe,CAAA;IACf,iDAAe,CAAA;AACjB,CAAC,EAHW,8BAA8B,8CAA9B,8BAA8B,QAGzC;AAEY,QAAA,mCAAmC,GAA8C;IAC5F,8BAA8B,CAAC,KAAK;IACpC,8BAA8B,CAAC,KAAK;CAC5B,CAAC"}

package/package.json

@@ -0,0 +1,173 @@
+{
+  "name": "@xemahq/kernel-contracts",
+  "version": "0.1.0",
+  "description": "Consolidated Xema OS kernel wire contracts — pure types + zod schemas for the 22 protocol surfaces (agent-composition, agent-workspace, biome, capability, contribution, document-templates/themes, entitlement, execution-context/environment, kernel-state, llm-gateway, mcp-tool, object, policy, runner, search-source, service-registry, skill, space, subject, workflow). One package, one npm scope, per-surface subpath exports. No framework/runtime deps.",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.json && node scripts/emit-awp-spec.mjs",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "check:boundary": "node scripts/check-subpath-dag.mjs"
+  },
+  "devDependencies": {
+    "@eslint/js": "catalog:",
+    "@types/node": "catalog:",
+    "eslint": "catalog:",
+    "eslint-config-prettier": "catalog:",
+    "eslint-plugin-import": "^2.31.0",
+    "prettier": "catalog:",
+    "typescript": "catalog:",
+    "typescript-eslint": "catalog:"
+  },
+  "dependencies": {
+    "zod": "catalog:"
+  },
+  "exports": {
+    "./agent-composition": {
+      "types": "./dist/agent-composition/index.d.ts",
+      "xema-source": "./src/agent-composition/index.ts",
+      "default": "./dist/agent-composition/index.js"
+    },
+    "./agent-workspace": {
+      "types": "./dist/agent-workspace/index.d.ts",
+      "xema-source": "./src/agent-workspace/index.ts",
+      "default": "./dist/agent-workspace/index.js"
+    },
+    "./biome": {
+      "types": "./dist/biome/index.d.ts",
+      "xema-source": "./src/biome/index.ts",
+      "default": "./dist/biome/index.js"
+    },
+    "./capability": {
+      "types": "./dist/capability/index.d.ts",
+      "xema-source": "./src/capability/index.ts",
+      "default": "./dist/capability/index.js"
+    },
+    "./contribution": {
+      "types": "./dist/contribution/index.d.ts",
+      "xema-source": "./src/contribution/index.ts",
+      "default": "./dist/contribution/index.js"
+    },
+    "./document-templates": {
+      "types": "./dist/document-templates/index.d.ts",
+      "xema-source": "./src/document-templates/index.ts",
+      "default": "./dist/document-templates/index.js"
+    },
+    "./document-themes": {
+      "types": "./dist/document-themes/index.d.ts",
+      "xema-source": "./src/document-themes/index.ts",
+      "default": "./dist/document-themes/index.js"
+    },
+    "./entitlement": {
+      "types": "./dist/entitlement/index.d.ts",
+      "xema-source": "./src/entitlement/index.ts",
+      "default": "./dist/entitlement/index.js"
+    },
+    "./execution-context": {
+      "types": "./dist/execution-context/index.d.ts",
+      "xema-source": "./src/execution-context/index.ts",
+      "default": "./dist/execution-context/index.js"
+    },
+    "./execution-environment": {
+      "types": "./dist/execution-environment/index.d.ts",
+      "xema-source": "./src/execution-environment/index.ts",
+      "default": "./dist/execution-environment/index.js"
+    },
+    "./kernel-state": {
+      "types": "./dist/kernel-state/index.d.ts",
+      "xema-source": "./src/kernel-state/index.ts",
+      "default": "./dist/kernel-state/index.js"
+    },
+    "./llm-gateway": {
+      "types": "./dist/llm-gateway/index.d.ts",
+      "xema-source": "./src/llm-gateway/index.ts",
+      "default": "./dist/llm-gateway/index.js"
+    },
+    "./mcp-tool": {
+      "types": "./dist/mcp-tool/index.d.ts",
+      "xema-source": "./src/mcp-tool/index.ts",
+      "default": "./dist/mcp-tool/index.js"
+    },
+    "./object": {
+      "types": "./dist/object/index.d.ts",
+      "xema-source": "./src/object/index.ts",
+      "default": "./dist/object/index.js"
+    },
+    "./policy": {
+      "types": "./dist/policy/index.d.ts",
+      "xema-source": "./src/policy/index.ts",
+      "default": "./dist/policy/index.js"
+    },
+    "./runner": {
+      "types": "./dist/runner/index.d.ts",
+      "xema-source": "./src/runner/index.ts",
+      "default": "./dist/runner/index.js"
+    },
+    "./search-source": {
+      "types": "./dist/search-source/index.d.ts",
+      "xema-source": "./src/search-source/index.ts",
+      "default": "./dist/search-source/index.js"
+    },
+    "./service-registry": {
+      "types": "./dist/service-registry/index.d.ts",
+      "xema-source": "./src/service-registry/index.ts",
+      "default": "./dist/service-registry/index.js"
+    },
+    "./skill": {
+      "types": "./dist/skill/index.d.ts",
+      "xema-source": "./src/skill/index.ts",
+      "default": "./dist/skill/index.js"
+    },
+    "./space": {
+      "types": "./dist/space/index.d.ts",
+      "xema-source": "./src/space/index.ts",
+      "default": "./dist/space/index.js"
+    },
+    "./subject": {
+      "types": "./dist/subject/index.d.ts",
+      "xema-source": "./src/subject/index.ts",
+      "default": "./dist/subject/index.js"
+    },
+    "./workflow": {
+      "types": "./dist/workflow/index.d.ts",
+      "xema-source": "./src/workflow/index.ts",
+      "default": "./dist/workflow/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "agent-composition": ["dist/agent-composition/index.d.ts"],
+      "agent-workspace": ["dist/agent-workspace/index.d.ts"],
+      "biome": ["dist/biome/index.d.ts"],
+      "capability": ["dist/capability/index.d.ts"],
+      "contribution": ["dist/contribution/index.d.ts"],
+      "document-templates": ["dist/document-templates/index.d.ts"],
+      "document-themes": ["dist/document-themes/index.d.ts"],
+      "entitlement": ["dist/entitlement/index.d.ts"],
+      "execution-context": ["dist/execution-context/index.d.ts"],
+      "execution-environment": ["dist/execution-environment/index.d.ts"],
+      "kernel-state": ["dist/kernel-state/index.d.ts"],
+      "llm-gateway": ["dist/llm-gateway/index.d.ts"],
+      "mcp-tool": ["dist/mcp-tool/index.d.ts"],
+      "object": ["dist/object/index.d.ts"],
+      "policy": ["dist/policy/index.d.ts"],
+      "runner": ["dist/runner/index.d.ts"],
+      "search-source": ["dist/search-source/index.d.ts"],
+      "service-registry": ["dist/service-registry/index.d.ts"],
+      "skill": ["dist/skill/index.d.ts"],
+      "space": ["dist/space/index.d.ts"],
+      "subject": ["dist/subject/index.d.ts"],
+      "workflow": ["dist/workflow/index.d.ts"]
+    }
+  }
+}

package/src/agent-composition/index.ts

@@ -0,0 +1,17 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Agent Composition Contracts — Barrel Export ──
+//
+// Kernel (Layer 1) contracts for the Agent Composition primitive and the
+// Model Resolution Matrix. Pure types + closed enums — zero runtime deps,
+// no NestJS, no Prisma.
+//
+// Shared between llm-registry-api (composition + model-resolution modules),
+// agent-session-api, the workflow DSL, and the frontend Agent Studio.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/capability-layer';
+export * from './lib/composition';
+export * from './lib/composition-limits-schema';
+export * from './lib/composition-workspace';
+export * from './lib/intrinsic-floor';
+export * from './lib/model-resolution-matrix';

package/src/agent-composition/lib/capability-layer.ts

@@ -0,0 +1,46 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── CapabilityLayer ──
+//
+// The capability envelope attached to an Agent Composition: what the
+// composition is allowed to do at runtime (write policy, repo access,
+// knowledge-base writes, allowed Xema-namespaced tools).
+//
+// This SUPERSEDES `RoleCapabilityProfile` (workflow-contracts/role-capability.ts).
+// Phase 6 collapses role-capability profiles into this layer; until then the
+// two coexist and `role-capability.ts` remains the data source.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Closed write-policy taxonomy.
+ * - `read-only`: does not mutate the workspace; output flows out-of-band.
+ * - `own-pages-only`: may only write declared deliverable files.
+ * - `full-write`: may write anywhere the workspace permits.
+ */
+export const COMPOSITION_WRITE_POLICIES = [
+  'read-only',
+  'own-pages-only',
+  'full-write',
+] as const;
+export type CompositionWritePolicy =
+  (typeof COMPOSITION_WRITE_POLICIES)[number];
+
+/**
+ * Repo-write capability.
+ * - `never`: blanket deny repo writes.
+ * - `when-granted`: repo writes allowed iff the dispatch supplied repo slugs.
+ */
+export const COMPOSITION_REPO_POLICIES = ['never', 'when-granted'] as const;
+export type CompositionRepoPolicy =
+  (typeof COMPOSITION_REPO_POLICIES)[number];
+
+/**
+ * The capability envelope of a composition node. Resolved into each
+ * invocation's `context.json` authority block.
+ */
+export interface CapabilityLayer {
+  readonly writePolicy: CompositionWritePolicy;
+  readonly mayEditRepos: CompositionRepoPolicy;
+  readonly mayWriteKnowledgeBase: boolean;
+  /** Closed allowlist of Xema-namespaced tools (e.g. `xema_memory_set`). */
+  readonly allowedXemaTools: readonly string[];
+}

package/src/agent-composition/lib/composition-limits-schema.ts

@@ -0,0 +1,38 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── CompositionLimits — Zod schema ──
+//
+// Validates the runtime envelope a coordinator-style composition node
+// declares on itself (and inherits to descendants). Used by:
+//   - the workflow DSL compiler — validates `with.composition.limits` on
+//     the `xema/agent@2.x` action variant at workflow compile time.
+//   - the activity-level enforcer — re-parses author-supplied limits at
+//     dispatch boundary so a malformed snapshot fails-fast instead of
+//     silently disabling enforcement.
+//
+// `maxDepth`, `maxFanout`, `maxSpawns` are required positive integers.
+// `tokenBudget` is optional — omitting it disables the token check
+// (unlimited). Until a graceful-drain / partial-emit path exists, a
+// token-budget breach loses all in-flight work; phases should opt in
+// only after measuring real usage. The four counters are independent —
+// the enforcer fires on whichever breaches first.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { z } from 'zod';
+
+import type { CompositionLimits } from './composition';
+
+/**
+ * Zod schema for {@link CompositionLimits}. Structural counters
+ * (`maxDepth` / `maxFanout` / `maxSpawns`) are strict positive integers.
+ * `tokenBudget` is optional; when omitted, the enforcer treats it as
+ * unlimited (no token-budget check). Authors who want NO enforcement at
+ * all must omit the entire `limits` block.
+ */
+export const CompositionLimitsSchema: z.ZodType<CompositionLimits> = z
+  .object({
+    maxDepth: z.number().int().positive(),
+    maxFanout: z.number().int().positive(),
+    maxSpawns: z.number().int().positive(),
+    tokenBudget: z.number().int().positive().optional(),
+  })
+  .strict();

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

@@ -0,0 +1,210 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Composition Workspace block ──
+//
+// The AUTHORED source of the workspace's filesystem-layout / persistence /
+// environment configuration. A `Composition` arms an agent with skills +
+// tools (the recursive `CompositionNode` tree); the `workspace` block
+// declares the SHAPE of `/workspace/` that agent runs inside —
+// persist-paths, env vars, and the live output-surface.
+//
+// `WorkspaceSpec` (`@xemahq/agent-workspace-contracts`) is a DERIVED
+// projection: the resolution service projects `Composition.workspace`
+// onto the resolved `WorkspaceSpec` so workspace-tree consumers read one
+// resolved spec without re-resolving the composition.
+//
+// This block absorbs the layout/persistence/env portion of the retiring
+// `WorkspaceManifest` — the agent/skill/tool-selection portion already
+// moved to `CompositionNode`. Templates (the manifest's Handlebars
+// seed-files) become skill-bundle resources served by skill-registry-api,
+// so they are NOT modelled here.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type {
+  WorkingFileBinding,
+  WorkspaceEnvVar,
+  WorkspacePersistenceSpec,
+} from '../../agent-workspace';
+import type {
+  AgentRunRole,
+  OutputSurfaceKind,
+} from '../../workflow';
+
+export type {
+  WorkingFileBinding,
+  WorkspaceEnvVar,
+  WorkspacePersistenceSpec,
+} from '../../agent-workspace';
+
+/**
+ * Single-port (default) vs. multi-app output surface. `multi` lets
+ * workspace-proxy's output-surface supervisor allocate a port per detected app
+ * target and emit one gateway route per app — used by webapp studios
+ * that scaffold N apps under one composition.
+ */
+export enum CompositionOutputSurfaceMode {
+  Single = 'single',
+  Multi = 'multi',
+}
+
+/**
+ * Output-surface declaration consumed by workspace-proxy. Mirrors
+ * the layout portion of the legacy `ManifestOutputSurface` — the only
+ * part of the manifest's `outputSurface` block that is genuinely a
+ * workspace-layout concern (not agent/skill/tool selection).
+ *
+ * Field applicability by `kind`:
+ *   - `none`: no other fields used.
+ *   - `web`: `port` (required by DSL schema when `mode !== 'multi'`),
+ *     `healthPath`, `autoOpen`, `mode`. The workspace-proxy output-surface
+ *     supervisor spawns / discovers dev-server processes and proxies
+ *     their HTTP ports.
+ *   - `static`: `root` (required, workspace-relative directory served
+ *     as a static site by the baked `static-artifact-server.mjs`),
+ *     `defaultDocument` (defaults to `index.html`), `autoOpen`. No
+ *     `port` — the supervisor assigns one from its pool. No `mode` —
+ *     static surfaces are always single-app.
+ *   - `app` / `tunnel`: reserved for future surface kinds; field set
+ *     mirrors `web`.
+ */
+export interface CompositionOutputSurface {
+  readonly kind: OutputSurfaceKind;
+  readonly port?: number;
+  readonly healthPath?: string;
+  /** Auto-open the preview pane on first ready signal. */
+  readonly autoOpen?: boolean;
+  /** Single-port (default) vs. multi-app output surface. */
+  readonly mode?: CompositionOutputSurfaceMode;
+  /**
+   * Workspace-relative directory served as a static site. Required and
+   * only meaningful when `kind === 'static'`. The DSL schema enforces
+   * the cross-field rule.
+   */
+  readonly root?: string;
+  /**
+   * Default document name served for directory requests in a `static`
+   * surface. Defaults to `index.html` when omitted. Ignored for other
+   * kinds.
+   */
+  readonly defaultDocument?: string;
+}
+
+/**
+ * The agent run-config the composer needs that is NOT carried by the
+ * `CompositionNode` tree. The node tree pins WHICH agent runs; these
+ * three fields pin the run FRAMING (phase + role + deliverable
+ * contract) the renderer + system-overlay are driven by.
+ *
+ * `role` is the canonical {@link AgentRunRole}. `phase` /
+ * `deliverableSpecRef` are carried verbatim from the source manifest's
+ * `spec.agent` block — they MAY still hold a `${input.x}` token, which
+ * the workspace pipeline resolves against the run's bind inputs (the
+ * same fail-fast interpolation grammar `env` values use).
+ */
+export interface CompositionAgentRunConfig {
+  readonly phase: string;
+  readonly role: AgentRunRole;
+  readonly deliverableSpecRef?: string;
+}
+
+/**
+ * The user-data MOUNT LAYOUT block — the residual that survived the
+ * `workspace-manifests-api` retirement (Phase 10, Step 3d). It is the
+ * authored description of the `/workspace/` filesystem SHAPE: which
+ * AWP user-data slots (`inputs`, `references`, `uploads`,
+ * `deliverables`, `repos`, `deliverable-specs`, …) are enabled, their
+ * per-slot read/write mode, the agent run-config, the manifest's
+ * declared inputs, and the profile's seed files.
+ *
+ * It is NOT derivable from the kernel AWP spec alone: the slot SET and
+ * per-slot MODE genuinely vary per profile (a reviewer composition
+ * mounts `deliverables` read-only; an engineer composition mounts
+ * `repos` read-write; a document composition mounts `deliverables`
+ * read-only). The composition boot-seeder projects it from the
+ * `extends:`-FLATTENED source workspace manifest's RAW spec; the
+ * `agent-session-runtime` composer re-compiles it with the run's bind
+ * inputs (so `${input.x}` tokens in seed-file vars resolve against the
+ * real session inputs, never against a seed-time placeholder).
+ *
+ * `mounts` / `seedFiles` / `inputs` carry the manifest DSL's RAW spec
+ * fragment shapes verbatim. They are typed loosely here (`unknown`
+ * values) on purpose: the manifest DSL (`@xemahq/workspace-manifest-dsl`)
+ * is a runtime package (Zod, js-yaml) and this kernel contract package
+ * is dependency-free; the consuming workspace pipeline re-validates the
+ * fragments with the DSL's `WorkspaceManifestSchema` when it
+ * reconstructs + compiles the manifest.
+ */
+export interface CompositionMountLayout {
+  /**
+   * Raw `spec.mounts` block — user-data mount declarations keyed by AWP
+   * slot key. Each value is the manifest DSL `ManifestMountDeclaration`
+   * (`boolean` | `{ mode? }` | per-slot config). Platform-rendered
+   * slots are NEVER present — the composer auto-emits them.
+   */
+  readonly mounts: Readonly<Record<string, unknown>>;
+  /** Agent run-config (phase + role + deliverable contract). */
+  readonly agentRunConfig: CompositionAgentRunConfig;
+  /**
+   * Raw `spec.seedFiles` array — manifest DSL `ManifestSeedFile`
+   * entries (`{ path, slot?, template?, content?, vars? }`). `vars` may
+   * carry `${input.x}` tokens; the workspace pipeline resolves them
+   * when it re-compiles the manifest with the run's bind inputs.
+   */
+  readonly seedFiles: readonly Readonly<Record<string, unknown>>[];
+  /**
+   * Raw `spec.inputs` block — manifest DSL `ManifestInputDeclaration`
+   * map. Carried so the workspace pipeline can bind session-supplied
+   * `customConfig.manifestInputs` against the declared inputs before
+   * re-compiling. Empty when the manifest declared no inputs.
+   */
+  readonly inputs: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Authored workspace-layout config carried on a `Composition`. Every
+ * field is optional + additive — a composition that declares no
+ * `workspace` block produces a `WorkspaceSpec` with no projected
+ * `persistence` / `env` (the AWP base slots still apply).
+ */
+export interface CompositionWorkspace {
+  /**
+   * Workspace-relative persist-paths + per-slot policy overrides.
+   * Authoritative SOURCE projected onto `WorkspaceSpec.persistence`.
+   */
+  readonly persistence?: WorkspacePersistenceSpec;
+  /**
+   * Environment variables applied to the agent runtime before dispatch.
+   * Authoritative SOURCE projected onto `WorkspaceSpec.env`. Values may
+   * use `${input.x}` interpolation in the authored form; the projection
+   * resolves them before they reach `WorkspaceSpec`.
+   */
+  readonly env?: readonly WorkspaceEnvVar[];
+  /**
+   * Output-surface declaration. Optional — omitted for
+   * compositions that do not expose an output surface.
+   */
+  readonly outputSurface?: CompositionOutputSurface;
+  /**
+   * The user-data mount layout — which AWP slots the profile enables,
+   * per-slot mode, the agent run-config, and seed files. The residual
+   * the Agent Composition primitive absorbed from `WorkspaceManifest`
+   * in Phase 10, Step 3d. Optional + additive — a composition with no
+   * `mountLayout` runs on the AWP base slots alone with no seed files.
+   */
+  readonly mountLayout?: CompositionMountLayout;
+  /**
+   * Working files the platform materialises for this session.
+   *
+   * Each entry declares ONE file the platform writes into `/workspace/`
+   * before the agent's first turn and keeps in sync with its source
+   * (e.g. a KB page) for the lifetime of the session. The worker's
+   * working-file engine dispatches by `sourceKind` — `kb-page` is the
+   * kernel-shipped adapter; biomes ship more.
+   *
+   * Authored `path` / `sourceRef` values may carry `${input.x}` tokens;
+   * the composition resolution pass interpolates them before they reach
+   * `WorkspaceSpec.workingFiles`. Optional + additive — compositions
+   * that declare no working files (the common case) keep the worker's
+   * engine idle.
+   */
+  readonly workingFiles?: readonly WorkingFileBinding[];
+}