@xemahq/kernel-contracts 0.3.7 → 0.4.0

package/dist/agent-composition/lib/composition-workspace.d.ts

@@ -15,7 +15,7 @@ export interface CompositionOutputSurface {
     readonly defaultDocument?: string;
 }
 export interface CompositionAgentRunConfig {
-    readonly phase: string;
+    readonly stage: string;
     readonly role: AgentRunRole;
     readonly deliverableSpecRef?: string;
 }

package/dist/agent-composition/lib/model-resolution-matrix.d.ts

@@ -3,14 +3,14 @@ export declare enum ResolutionDimension {
     Agent = "agent",
     Skill = "skill",
     Project = "project",
-    Group = "group",
+    Stage = "stage",
     Purpose = "purpose"
 }
 export interface ModelMatrixSelector {
     readonly agent?: string;
     readonly skill?: string;
     readonly project?: string;
-    readonly group?: string;
+    readonly stage?: string;
     readonly purpose?: string;
     readonly extra?: Readonly<Record<string, string>>;
 }
@@ -24,7 +24,7 @@ export interface ModelResolutionContext {
     readonly agentSlug: string;
     readonly projectId?: string;
     readonly skillSlug?: string;
-    readonly groupKey?: string;
+    readonly stageKey?: string;
     readonly purpose?: string;
     readonly extra?: Readonly<Record<string, string>>;
 }

package/dist/agent-composition/lib/model-resolution-matrix.js

@@ -6,7 +6,7 @@ var ResolutionDimension;
     ResolutionDimension["Agent"] = "agent";
     ResolutionDimension["Skill"] = "skill";
     ResolutionDimension["Project"] = "project";
-    ResolutionDimension["Group"] = "group";
+    ResolutionDimension["Stage"] = "stage";
     ResolutionDimension["Purpose"] = "purpose";
 })(ResolutionDimension || (exports.ResolutionDimension = ResolutionDimension = {}));
 //# sourceMappingURL=model-resolution-matrix.js.map

package/dist/agent-workspace/awp-spec.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://xema.dev/schemas/awp-spec.v1.json",
-  "emittedAt": "2026-06-12T14:43:51.031Z",
+  "emittedAt": "2026-06-13T09:08:25.716Z",
   "spec": {
     "id": "awp/v1",
     "version": "1.2.0",

package/dist/agent-workspace/lib/context-json.d.ts

@@ -8,7 +8,7 @@ export interface ContextInvocation {
     readonly surface: InvocationSurface;
     readonly attempt: number;
     readonly runId: string | null;
-    readonly groupKey: string | null;
+    readonly stageKey: string | null;
     readonly sessionId: string | null;
 }
 export interface ContextAuthority {

package/dist/llm-gateway/lib/caller.d.ts

@@ -9,6 +9,6 @@ export interface LlmCaller {
     id: string;
     orgId: string;
     projectId?: string;
-    groupKey?: string;
+    stageKey?: string;
 }
 //# sourceMappingURL=caller.d.ts.map

package/dist/workflow/lib/compiled-workspace-manifest.d.ts

@@ -28,7 +28,7 @@ export interface CompiledWorkspaceManifest {
 }
 export interface CompiledManifestAgent {
     readonly slug: string;
-    readonly groupKey: string;
+    readonly stageKey: string;
     readonly role: AgentRunRole;
     readonly deliverableSpecRef?: string;
     readonly defaultModel?: ModelRef;

package/dist/workflow/lib/mount-plan.d.ts

@@ -53,7 +53,7 @@ export type MountSource = {
     readonly kind: 'agent-definition';
     readonly orgId: string;
     readonly agentSlug: string;
-    readonly groupKey: string;
+    readonly stageKey: string;
     readonly agentMode: 'primary' | 'subagent';
 } | {
     readonly kind: 'skill-bundle';
@@ -63,7 +63,7 @@ export type MountSource = {
     readonly orgId: string;
     readonly sectionKey: string;
     readonly agentSlug?: string;
-    readonly groupKey?: string;
+    readonly stageKey?: string;
 } | ({
     readonly kind: 'rendered-agents-md';
 } & RenderedAgentRunContextParams) | ({
@@ -75,7 +75,7 @@ export interface RenderedAgentRunContextParams {
     readonly orgId: string;
     readonly projectId: string;
     readonly agentSlug: string;
-    readonly groupKey: string;
+    readonly stageKey: string;
     readonly role: AgentRunRole;
     readonly sessionId?: string;
     readonly runId?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/kernel-contracts",
-  "version": "0.3.7",
+  "version": "0.4.0",
   "description": "Consolidated Xema OS kernel wire contracts — pure types + zod schemas for the 32 kernel protocol surfaces. One package, one npm scope, wildcard per-surface subpath exports. No framework/runtime deps.",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

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

@@ -93,17 +93,17 @@ export interface CompositionOutputSurface {
 /**
  * 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
+ * three fields pin the run FRAMING (stage + role + deliverable
  * contract) the renderer + system-overlay are driven by.
  *
- * `role` is the canonical {@link AgentRunRole}. `phase` /
+ * `role` is the canonical {@link AgentRunRole}. `stage` /
  * `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 stage: string;
   readonly role: AgentRunRole;
   readonly deliverableSpecRef?: string;
 }
@@ -143,7 +143,7 @@ export interface CompositionMountLayout {
    * slots are NEVER present — the composer auto-emits them.
    */
   readonly mounts: Readonly<Record<string, unknown>>;
-  /** Agent run-config (phase + role + deliverable contract). */
+  /** Agent run-config (stage + role + deliverable contract). */
   readonly agentRunConfig: CompositionAgentRunConfig;
   /**
    * Raw `spec.seedFiles` array — manifest DSL `ManifestSeedFile`

package/src/agent-composition/lib/model-resolution-matrix.ts

@@ -18,20 +18,20 @@
 import type { ModelRef } from '../../workflow';
 
 /**
- * Open registry of matrix dimensions. v1 ships agent/skill/project/group;
+ * Open registry of matrix dimensions. v1 ships agent/skill/project/stage;
  * v1.1 adds `purpose` for non-agent invocations (memory summarization,
  * embedding, reorganization). New dimensions are added here + carried in
  * `ModelMatrixSelector.extra` (untyped) or as a typed first-class field.
  *
- * The `group` dimension is the kernel-neutral name for a sub-app's
- * structural grouping tag on a job (e.g. the software-dev biome maps
- * its `phaseKey:` YAML field onto this dimension at compile time).
+ * The `stage` dimension is the kernel-neutral name for a sub-app's
+ * structural workflow-stage tag on a job (e.g. the software-dev biome maps
+ * its `stageKey:` YAML field onto this dimension at compile time).
  */
 export enum ResolutionDimension {
   Agent = 'agent',
   Skill = 'skill',
   Project = 'project',
-  Group = 'group',
+  Stage = 'stage',
   Purpose = 'purpose',
 }
 
@@ -47,11 +47,11 @@ export interface ModelMatrixSelector {
   /** Match when the invocation's project id equals this value. */
   readonly project?: string;
   /**
-   * Match when the invocation's structural group key equals this value.
-   * Kernel-neutral name; the software-dev biome's `phaseKey:` YAML field
+   * Match when the invocation's structural stage key equals this value.
+   * Kernel-neutral name; the software-dev biome's `stageKey:` YAML field
    * is mapped onto this dimension by the DSL compiler.
    */
-  readonly group?: string;
+  readonly stage?: string;
   /**
    * Match when the invocation's non-agent purpose equals this value. Used
    * for system flows that route LLM calls outside the agent/skill model —
@@ -84,7 +84,7 @@ export interface ModelResolutionContext {
   readonly agentSlug: string;
   readonly projectId?: string;
   readonly skillSlug?: string;
-  readonly groupKey?: string;
+  readonly stageKey?: string;
   /**
    * Non-agent invocation purpose (e.g. memory summarization/embedding).
    * Optional — agent and skill invocations leave this undefined.

package/src/agent-workspace/lib/context-json.ts

@@ -29,7 +29,7 @@ export interface ContextInvocation {
   readonly surface: InvocationSurface;
   readonly attempt: number;
   readonly runId: string | null;
-  readonly groupKey: string | null;
+  readonly stageKey: string | null;
   readonly sessionId: string | null;
 }
 

package/src/llm-gateway/lib/caller.ts

@@ -32,9 +32,9 @@ export enum LlmCallerKind {
  * - `kind` + `id` together identify the originating object.
  * - `orgId` is always present (billing/audit anchor).
  * - `projectId` is set when the call is project-scoped (most are).
- * - `groupKey` is set when the caller is tied to a workflow's structural
- *   group bucket. Kernel-neutral name; a sub-app biome (e.g. software-dev)
- *   maps its own `phaseKey` value onto this field at compile time.
+ * - `stageKey` is set when the caller is tied to a workflow's structural
+ *   stage bucket. Kernel-neutral name; a sub-app biome (e.g. software-dev)
+ *   maps its own `stageKey` YAML value onto this field at compile time.
  *
  * Adding new fields is non-breaking; renaming or repurposing existing
  * ones is breaking and requires updates on both gateway and consumers.
@@ -44,5 +44,5 @@ export interface LlmCaller {
   id: string;
   orgId: string;
   projectId?: string;
-  groupKey?: string;
+  stageKey?: string;
 }

package/src/workflow/lib/compiled-run.ts

@@ -19,7 +19,7 @@ import type { WorkflowVariableRequirement } from './variable-requirement';
  *     :ref`, reconstructing the compiled workspace manifest from the
  *     resolved composition's `workspace.mountLayout` block.
  *   • `inline` — short-form `with.mounts` whose agent metadata
- *     (`agentSlug`, `groupKey`, `deliverableSpecRef`, every entry in
+ *     (`agentSlug`, `stageKey`, `deliverableSpecRef`, every entry in
  *     `mounts`) is fully literal at compile time. The compiler runs
  *     `compileManifest()` once and embeds the result so the worker
  *     skips both the DB round-trip and the runtime synthesis step.

package/src/workflow/lib/compiled-workspace-manifest.ts

@@ -66,7 +66,7 @@ export interface CompiledWorkspaceManifest {
 
 export interface CompiledManifestAgent {
   readonly slug: string;
-  readonly groupKey: string;
+  readonly stageKey: string;
   /**
    * Canonical {@link AgentRunRole}. Validated by the DSL's
    * `ManifestAgentBlockSchema` at compile time, so the runtime can

package/src/workflow/lib/mount-plan.ts

@@ -116,7 +116,7 @@ export type MountSource =
       readonly kind: 'agent-definition';
       readonly orgId: string;
       readonly agentSlug: string;
-      readonly groupKey: string;
+      readonly stageKey: string;
       /**
        * Frontmatter `mode` for the rendered .opencode/agents/<slug>.md
        * file. Per OpenCode docs, primary agents and sub-agents share the
@@ -141,7 +141,7 @@ export type MountSource =
       readonly orgId: string;
       readonly sectionKey: string;
       readonly agentSlug?: string;
-      readonly groupKey?: string;
+      readonly stageKey?: string;
     }
   | ({ readonly kind: 'rendered-agents-md' } & RenderedAgentRunContextParams)
   | ({ readonly kind: 'rendered-system-overlay' } & RenderedAgentRunContextParams)
@@ -170,7 +170,7 @@ export interface RenderedAgentRunContextParams {
   readonly orgId: string;
   readonly projectId: string;
   readonly agentSlug: string;
-  readonly groupKey: string;
+  readonly stageKey: string;
   readonly role: AgentRunRole;
   readonly sessionId?: string;
   readonly runId?: string;

package/src/workflow/lib/workflow-stage.ts

@@ -9,7 +9,7 @@
 //
 // A stage is identified by a free-form `stageKey` string. The artifact
 // natural key already `_`-encodes this value (`{kind}:{workflowRunId}:
-// {groupKey|_}:{scope|_}:{slug}`), and the workflow engine sequences jobs
+// {stageKey|_}:{scope|_}:{slug}`), and the workflow engine sequences jobs
 // via explicit `needs:` dependency edges — neither needs a closed enum.
 //
 // Biomes that DO define an ordered stage list (e.g. for a phase rail or a
@@ -33,7 +33,7 @@ export enum WorkflowStageCategory {
 
 /**
  * A single ordered workflow stage. `stageKey` is the value that flows onto
- * a job's `groupKey` and into the artifact natural key — a free-form
+ * a job's `stageKey` and into the artifact natural key — a free-form
  * string the kernel never validates against a closed set.
  */
 export interface WorkflowStage {