@xemahq/kernel-contracts 0.23.1 → 0.23.3

package/src/distribution/lib/distribution.ts

@@ -24,6 +24,25 @@ export const PlatformServiceTierSchema = z.union([
   z.literal('edge'),
 ]) as z.ZodType<PlatformServiceTier>;
 
+/**
+ * Canonical boot/wave rank of every tier token — THE single vocabulary source
+ * for tier ordering across the boot graph, the CLI launcher's wave derivation,
+ * and the deploy-roster generators. Lower boots first. `infra` (-1) is the
+ * pre-wave: submodules + the external generic plane (identity, event-hub,
+ * secrets, llm-gateway, keycloak, postgres, etcd) that always boot before the
+ * Xema service mesh. Do NOT redeclare local tier-rank maps in consumers.
+ */
+export const PLATFORM_SERVICE_TIER_RANK: Readonly<
+  Record<PlatformServiceTier | 'infra', number>
+> = {
+  infra: -1,
+  kernel: 0,
+  system: 1,
+  base: 2,
+  platform: 3,
+  edge: 4,
+};
+
 /**
  * Schema-versioning seed for `xema-distribution.json`. Bumped via a coordinated
  * PR on an incompatible shape change; consumers refuse versions they do not

package/src/distribution/lib/install-policy.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+
+/**
+ * `BiomeInstallPolicy` — the package-model install policy a DISTRIBUTION stamps
+ * on every resolved biome (never manifest-sourced; the same biome can be
+ * `required` in one edition and `optional` in another).
+ *
+ * - `required`         — always installed AND always launched. Kernel- and
+ *                        system-tier biomes are forced to this by the resolver
+ *                        (a platform invariant, regardless of selectors).
+ * - `default-selected` — shipped and launched by default; a deployment may
+ *                        opt out.
+ * - `optional`         — shipped in the lock (catalog-visible, image built)
+ *                        but launched only when explicitly selected.
+ *
+ * Orthogonal to `LockedBiome.mandatory`, which is the org-DISABLE governance
+ * flag (may the org switch it off once shipped) — installPolicy decides what
+ * comes up by default; mandatory decides what can be turned off.
+ */
+export enum BiomeInstallPolicy {
+  Required = 'required',
+  DefaultSelected = 'default-selected',
+  Optional = 'optional',
+}
+
+export const BiomeInstallPolicySchema = z.nativeEnum(BiomeInstallPolicy);
+
+/**
+ * `BiomeLaunchMode` — WHERE/HOW a biome's services are launched. A distribution
+ * decision applied at resolve time (never manifest-sourced — the biome only
+ * declares WHAT it is).
+ *
+ * - `static`           — launched as regular services in the static roster
+ *                        (dev launcher waves + prod services.yaml). The default
+ *                        semantics when the lock field is absent.
+ * - `per-installation` — a sidecar-host template instantiated dynamically by
+ *                        biome-host-api once a biome is installed; NOT a
+ *                        statically-launched service, so static rosters must
+ *                        not boot it standalone.
+ */
+export enum BiomeLaunchMode {
+  Static = 'static',
+  PerInstallation = 'per-installation',
+}
+
+export const BiomeLaunchModeSchema = z.nativeEnum(BiomeLaunchMode);

package/src/workflow/lib/enums.ts

@@ -219,6 +219,29 @@ export enum BuiltInActionId {
   PUBLISH_KB = 'xema/publish-kb',
   SCM_CHECKOUT = 'software-dev/scm-checkout',
   SCM_MERGE = 'software-dev/scm-merge',
+  /**
+   * Create (or idempotently ensure) a work branch on the project's bound
+   * SCM repository via connector-gateway-api's
+   * `POST /projects/:projectId/git/branches`. Shipped by the software-dev
+   * biome; the flagship delivery pipeline uses it to mint the run's
+   * deterministic work branch before the engineering phase starts.
+   */
+  SCM_BRANCH = 'software-dev/scm-branch',
+  /**
+   * Open (or idempotently reuse) a change request / pull request from a
+   * source branch to a target branch via connector-gateway-api's
+   * `POST /projects/:projectId/change-requests`. Shipped by the
+   * software-dev biome.
+   */
+  SCM_OPEN_PR = 'software-dev/scm-open-pr',
+  /**
+   * Transition backlog items linked to the run (or an explicit item-id
+   * set) to a target status via backlog-api's
+   * `PATCH /items/:id/status`. Shipped by the software-dev biome; the
+   * flagship delivery pipeline uses it post-merge to close out the
+   * items the run delivered.
+   */
+  BACKLOG_SYNC = 'software-dev/backlog-sync',
   WEBHOOK = 'xema/webhook',
   HTTP = 'xema/http',
   WAIT = 'xema/wait',

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

@@ -42,6 +42,12 @@ export enum RunActivityKind {
   REVIEW_POSTING = 'review_posting',
   SCM_MERGE = 'scm_merge',
   SCM_CHECKOUT = 'scm_checkout',
+  /** Work-branch creation via `software-dev/scm-branch`. */
+  SCM_BRANCH = 'scm_branch',
+  /** Change-request / PR opening via `software-dev/scm-open-pr`. */
+  SCM_OPEN_PR = 'scm_open_pr',
+  /** Backlog item status transitions via `software-dev/backlog-sync`. */
+  BACKLOG_SYNC = 'backlog_sync',
   KB_PUBLISH = 'kb_publish',
   WEBHOOK = 'webhook',
   HTTP = 'http',