@xemahq/kernel-contracts 0.23.0 → 0.23.2

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

@@ -5,6 +5,10 @@ import {
   type BiomeTier,
   type BiomeOrigin,
 } from '../../biome';
+import {
+  BiomeInstallPolicySchema,
+  type BiomeInstallPolicy,
+} from './install-policy';
 
 /**
  * A `DistributionSelector` declares which biomes an `include[]` entry pulls
@@ -26,22 +30,43 @@ import {
  * property a biome self-declares in its manifest — the same biome can be
  * force-on in one distribution and optional/installable in another.
  *
+ * **`installPolicy`** (on the `{ tier }` and `{ biome }` forms) stamps the
+ * package-model install policy per selector — e.g.
+ * `{ tier: "base", installPolicy: "default-selected" }` plus
+ * `{ biome: "backlog", installPolicy: "optional" }`. Resolution: kernel- and
+ * system-tier biomes are ALWAYS `required` (resolver invariant); otherwise the
+ * most specific matching selector wins (`{ biome }` beats `{ tier }`;
+ * conflicting policies at the same specificity fail-fast); no selector policy
+ * → `default-selected`. Like `mandatory`, never manifest-sourced.
+ *
  * Selector matching is resolved against the global biome index; the resolver,
  * not any consumer, applies these rules (the lockfile is the hard boundary).
  */
 export type DistributionSelector =
-  | { tier: BiomeTier; mandatory?: boolean }
+  | { tier: BiomeTier; mandatory?: boolean; installPolicy?: BiomeInstallPolicy }
   | { origin: BiomeOrigin }
-  | { biome: string; version?: string; mandatory?: boolean };
+  | {
+      biome: string;
+      version?: string;
+      mandatory?: boolean;
+      installPolicy?: BiomeInstallPolicy;
+    };
 
 export const DistributionSelectorSchema = z.union([
-  z.object({ tier: BiomeTierSchema, mandatory: z.boolean().optional() }).strict(),
+  z
+    .object({
+      tier: BiomeTierSchema,
+      mandatory: z.boolean().optional(),
+      installPolicy: BiomeInstallPolicySchema.optional(),
+    })
+    .strict(),
   z.object({ origin: BiomeOriginSchema }).strict(),
   z
     .object({
       biome: z.string().min(1),
       version: z.string().min(1).optional(),
       mandatory: z.boolean().optional(),
+      installPolicy: BiomeInstallPolicySchema.optional(),
     })
     .strict(),
 ]) as z.ZodType<DistributionSelector>;

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);