@xemahq/kernel-contracts 0.33.0 → 0.34.0

package/dist/principal/lib/delegation-chain.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DelegationChainError = exports.DelegationErrorCodeSchema = exports.DelegationErrorCode = exports.MAX_DELEGATION_DEPTH = void 0;
+exports.resolveDelegationChain = resolveDelegationChain;
+const zod_1 = require("zod");
+const subject_1 = require("../../subject");
+exports.MAX_DELEGATION_DEPTH = 3;
+var DelegationErrorCode;
+(function (DelegationErrorCode) {
+    DelegationErrorCode["ChainTooDeep"] = "DELEGATION_CHAIN_TOO_DEEP";
+    DelegationErrorCode["Cycle"] = "DELEGATION_CHAIN_CYCLE";
+    DelegationErrorCode["Discontinuous"] = "DELEGATION_CHAIN_DISCONTINUOUS";
+    DelegationErrorCode["NotAnchoredAtActor"] = "DELEGATION_CHAIN_NOT_ANCHORED_AT_ACTOR";
+    DelegationErrorCode["NotAnchoredAtExecutor"] = "DELEGATION_CHAIN_NOT_ANCHORED_AT_EXECUTOR";
+    DelegationErrorCode["EmptyChainMismatch"] = "DELEGATION_CHAIN_EMPTY_MISMATCH";
+})(DelegationErrorCode || (exports.DelegationErrorCode = DelegationErrorCode = {}));
+exports.DelegationErrorCodeSchema = zod_1.z.nativeEnum(DelegationErrorCode);
+class DelegationChainError extends Error {
+    code;
+    constructor(args) {
+        super(args.message);
+        this.name = 'DelegationChainError';
+        this.code = args.code;
+    }
+}
+exports.DelegationChainError = DelegationChainError;
+function subjectsEqual(a, b) {
+    return (0, subject_1.subjectRefToString)(a) === (0, subject_1.subjectRefToString)(b);
+}
+function resolveDelegationChain(args) {
+    const { actor, executor, chain } = args;
+    if (chain.length === 0) {
+        if (!subjectsEqual(actor, executor)) {
+            throw new DelegationChainError({
+                code: DelegationErrorCode.EmptyChainMismatch,
+                message: `Empty delegation chain requires actor === executor, but actor "${(0, subject_1.subjectRefToString)(actor)}" ≠ executor "${(0, subject_1.subjectRefToString)(executor)}".`,
+            });
+        }
+        return Object.freeze([]);
+    }
+    if (chain.length > exports.MAX_DELEGATION_DEPTH) {
+        throw new DelegationChainError({
+            code: DelegationErrorCode.ChainTooDeep,
+            message: `Delegation chain has ${chain.length} hops; the maximum is ${exports.MAX_DELEGATION_DEPTH}.`,
+        });
+    }
+    if (!subjectsEqual(chain[0].from, actor)) {
+        throw new DelegationChainError({
+            code: DelegationErrorCode.NotAnchoredAtActor,
+            message: `Delegation chain must start at actor "${(0, subject_1.subjectRefToString)(actor)}", but its first hop starts at "${(0, subject_1.subjectRefToString)(chain[0].from)}".`,
+        });
+    }
+    const last = chain[chain.length - 1];
+    if (!subjectsEqual(last.to, executor)) {
+        throw new DelegationChainError({
+            code: DelegationErrorCode.NotAnchoredAtExecutor,
+            message: `Delegation chain must end at executor "${(0, subject_1.subjectRefToString)(executor)}", but its last hop ends at "${(0, subject_1.subjectRefToString)(last.to)}".`,
+        });
+    }
+    const seen = new Set();
+    const firstKey = (0, subject_1.subjectRefToString)(chain[0].from);
+    seen.add(firstKey);
+    for (let i = 0; i < chain.length; i += 1) {
+        if (i > 0 && !subjectsEqual(chain[i - 1].to, chain[i].from)) {
+            throw new DelegationChainError({
+                code: DelegationErrorCode.Discontinuous,
+                message: `Delegation chain is not contiguous at hop ${i}: previous "to" "${(0, subject_1.subjectRefToString)(chain[i - 1].to)}" ≠ this "from" "${(0, subject_1.subjectRefToString)(chain[i].from)}".`,
+            });
+        }
+        const toKey = (0, subject_1.subjectRefToString)(chain[i].to);
+        if (seen.has(toKey)) {
+            throw new DelegationChainError({
+                code: DelegationErrorCode.Cycle,
+                message: `Delegation chain contains a cycle: subject "${toKey}" appears more than once.`,
+            });
+        }
+        seen.add(toKey);
+    }
+    return Object.freeze([...chain]);
+}
+//# sourceMappingURL=delegation-chain.js.map

package/dist/principal/lib/delegation-chain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation-chain.js","sourceRoot":"","sources":["../../../src/principal/lib/delegation-chain.ts"],"names":[],"mappings":"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"}

package/dist/principal/lib/delegation-grant.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+import { type SubjectRef } from '../../subject';
+export interface DelegationGrant {
+    from: SubjectRef;
+    to: SubjectRef;
+    grantedAt: string;
+    reason?: string;
+}
+export declare const DelegationGrantSchema: z.ZodType<DelegationGrant>;
+//# sourceMappingURL=delegation-grant.d.ts.map

package/dist/principal/lib/delegation-grant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation-grant.d.ts","sourceRoot":"","sources":["../../../src/principal/lib/delegation-grant.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAkBlE,MAAM,WAAW,eAAe;IAE9B,IAAI,EAAE,UAAU,CAAC;IAEjB,EAAE,EAAE,UAAU,CAAC;IAEf,SAAS,EAAE,MAAM,CAAC;IAElB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,qBAAqB,EAK5B,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC"}

package/dist/principal/lib/delegation-grant.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DelegationGrantSchema = void 0;
+const zod_1 = require("zod");
+const subject_1 = require("../../subject");
+exports.DelegationGrantSchema = zod_1.z.object({
+    from: subject_1.SubjectRefSchema,
+    to: subject_1.SubjectRefSchema,
+    grantedAt: zod_1.z.string().datetime(),
+    reason: zod_1.z.string().min(1).optional(),
+});
+//# sourceMappingURL=delegation-grant.js.map

package/dist/principal/lib/delegation-grant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation-grant.js","sourceRoot":"","sources":["../../../src/principal/lib/delegation-grant.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,2CAAkE;AA6BrD,QAAA,qBAAqB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC5C,IAAI,EAAE,0BAAgB;IACtB,EAAE,EAAE,0BAAgB;IACpB,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CACrC,CAA+B,CAAC"}

package/dist/principal/lib/execution-principal.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { type SubjectRef, type TokenClass } from '../../subject';
+import { type ExecutionEnvironmentRef } from '../../execution-environment';
+import { type AppChannel } from '../../app-runtime';
+import { type DelegationGrant } from './delegation-grant';
+export interface ExecutionPrincipal {
+    actor: SubjectRef;
+    executor: SubjectRef;
+    delegationChain: DelegationGrant[];
+    tokenClass: TokenClass;
+    environment: ExecutionEnvironmentRef;
+    orgId: string;
+    appId?: string;
+    releaseId?: string;
+    channel?: AppChannel;
+    tenantId?: string;
+    purpose?: string;
+}
+export declare const ExecutionPrincipalSchema: z.ZodType<ExecutionPrincipal>;
+//# sourceMappingURL=execution-principal.d.ts.map

package/dist/principal/lib/execution-principal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-principal.d.ts","sourceRoot":"","sources":["../../../src/principal/lib/execution-principal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAGL,KAAK,UAAU,EACf,KAAK,UAAU,EAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACtE,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAwBjF,MAAM,WAAW,kBAAkB;IAEjC,KAAK,EAAE,UAAU,CAAC;IAElB,QAAQ,EAAE,UAAU,CAAC;IAErB,eAAe,EAAE,eAAe,EAAE,CAAC;IAEnC,UAAU,EAAE,UAAU,CAAC;IAEvB,WAAW,EAAE,uBAAuB,CAAC;IAErC,KAAK,EAAE,MAAM,CAAC;IAEd,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,OAAO,CAAC,EAAE,UAAU,CAAC;IAErB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,wBAAwB,EAY/B,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC"}

package/dist/principal/lib/execution-principal.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecutionPrincipalSchema = void 0;
+const zod_1 = require("zod");
+const subject_1 = require("../../subject");
+const execution_environment_1 = require("../../execution-environment");
+const app_runtime_1 = require("../../app-runtime");
+const delegation_grant_1 = require("./delegation-grant");
+exports.ExecutionPrincipalSchema = zod_1.z.object({
+    actor: subject_1.SubjectRefSchema,
+    executor: subject_1.SubjectRefSchema,
+    delegationChain: zod_1.z.array(delegation_grant_1.DelegationGrantSchema),
+    tokenClass: subject_1.TokenClassSchema,
+    environment: execution_environment_1.ExecutionEnvironmentRefSchema,
+    orgId: zod_1.z.string().min(1),
+    appId: zod_1.z.string().min(1).optional(),
+    releaseId: zod_1.z.string().min(1).optional(),
+    channel: app_runtime_1.AppChannelSchema.optional(),
+    tenantId: zod_1.z.string().min(1).optional(),
+    purpose: zod_1.z.string().min(1).optional(),
+});
+//# sourceMappingURL=execution-principal.js.map

package/dist/principal/lib/execution-principal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-principal.js","sourceRoot":"","sources":["../../../src/principal/lib/execution-principal.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,2CAKuB;AACvB,uEAGqC;AACrC,mDAAsE;AACtE,yDAAiF;AAiDpE,QAAA,wBAAwB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC/C,KAAK,EAAE,0BAAgB;IACvB,QAAQ,EAAE,0BAAgB;IAC1B,eAAe,EAAE,OAAC,CAAC,KAAK,CAAC,wCAAqB,CAAC;IAC/C,UAAU,EAAE,0BAAgB;IAC5B,WAAW,EAAE,qDAA6B;IAC1C,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACnC,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACvC,OAAO,EAAE,8BAAgB,CAAC,QAAQ,EAAE;IACpC,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACtC,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CACtC,CAAkC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/kernel-contracts",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "Consolidated Xema OS kernel wire contracts — pure types + zod schemas for the kernel protocol surfaces. One package, one npm scope, wildcard per-surface subpath exports. No framework/runtime deps.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",

package/src/app-runtime/index.ts

@@ -5,4 +5,7 @@ export * from './lib/delegated-session';
 export * from './lib/app-client';
 export * from './lib/app-lockfile';
 export * from './lib/branding-config';
+export * from './lib/surface-kind';
+export * from './lib/app-channel';
+export * from './lib/app-release';
 export * from './lib/app';

package/src/app-runtime/lib/app-channel.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+
+/**
+ * `AppChannel` — the closed set of channels an App is exercised through.
+ *
+ * A channel is *which data and which definition* an invocation sees:
+ *
+ * - `Preview` — the in-progress definition and its isolated data. The
+ *   user-facing word is **"Editing"**.
+ * - `Live`    — the active release's definition and the real data. The
+ *   user-facing word is **"Live"**.
+ *
+ * A channel is NOT the same axis as an `ExecutionEnvironment`. An
+ * `ExecutionEnvironment` is *what may be touched* (which capabilities /
+ * resources are in scope); an `AppChannel` is *which definition + which data*.
+ * They are orthogonal and combine: preview RUNS IN `environment:sandbox`, live
+ * RUNS IN `environment:app`. Do not collapse the two.
+ *
+ * This enum lands in Wave 0.1 (not Wave 5) because it is keyed on well before
+ * Wave 5: Wave 1.1's `ownerRef`, Wave 3.2's `AppRoleBinding.channel`, and Wave
+ * 4.1's `AppRun.channel` all reference it. Only the enum lands now — its
+ * runtime semantics (data separation, denied side effects, no scheduled
+ * automations on preview) are Wave 5.1.
+ *
+ * Values are stable wire strings — never compare against a free-form string.
+ */
+export enum AppChannel {
+  Preview = 'preview',
+  Live = 'live',
+}
+
+export const AppChannelSchema = z.nativeEnum(AppChannel);

package/src/app-runtime/lib/app-release.ts

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+import { AppLockfileSchema, type AppLockfile } from './app-lockfile';
+
+/**
+ * `AppReleaseState` — the closed lifecycle of a single `AppRelease` row.
+ *
+ * ```
+ * preparing → prepared → activating → active → superseded
+ *      └──────────┴───────────┴──────────────→ failed
+ * ```
+ *
+ * - `preparing`  — a candidate release is being assembled (steps 1–5 of D2).
+ * - `prepared`   — assembled and validated, migration NOT yet executed.
+ * - `activating` — the migration is executing and the pointer flip is in
+ *   flight (steps 6–7).
+ * - `active`     — the pointer (`App.activeReleaseId`) currently targets this
+ *   release; it is the ONE release visible to every runtime surface.
+ * - `superseded` — was `active`, replaced by a later activation; retained for
+ *   rollback within the retention window (D3).
+ * - `failed`     — prepare or activation aborted; invisible, garbage-collected.
+ */
+export enum AppReleaseState {
+  Preparing = 'preparing',
+  Prepared = 'prepared',
+  Activating = 'activating',
+  Active = 'active',
+  Superseded = 'superseded',
+  Failed = 'failed',
+}
+
+export const AppReleaseStateSchema = z.nativeEnum(AppReleaseState);
+
+/**
+ * `AppRelease` — an immutable candidate/active snapshot of an App's published
+ * definition, its resolved lockfile, and the schema-change plan applied for it.
+ *
+ * **Publishing is a distributed release, not a transaction (D2).** The
+ * definition lives in app-forge's database, the DDL runs in an org database,
+ * the `App` lives in app-runtime, agents/skills/workflows live in their own
+ * registries, and grants live in authorization-api. **No transaction spans
+ * these five systems.** Publish therefore runs an eight-step
+ * prepare-and-activate protocol:
+ *
+ * ```
+ * 1. create an immutable candidate AppRelease           (invisible)
+ * 2. prepare the schema change plan                     (validated, not applied)
+ * 3. prepare agent / skill / workflow versions          (drafts in their registries)
+ * 4. validate capability bindings and grants            (fail here, cheaply)
+ * 5. write the immutable AppRelease manifest + lockfile
+ * 6. execute the migration                              (idempotent, one txn per plan)
+ * 7. atomically flip App.activeReleaseId                (the ONLY atomic operation)
+ * 8. publish activation through the transactional outbox
+ * ```
+ *
+ * Because no transaction spans the five systems, **the only atomic operation is
+ * flipping `App.activeReleaseId`** (step 7) — moving one pointer. Everything
+ * else is prepared idempotently and made visible only by that flip.
+ *
+ * **Preparing/prepared/failed releases are invisible + garbage-collected (D3).**
+ * A release that is not `active` (or a retained `superseded`) is visible to NO
+ * runtime surface and is garbage-collected after a TTL. Rollback is simply
+ * repointing `activeReleaseId` to a prior release — which is sound ONLY because
+ * the publish path tombstones (marks deprecated) rather than physically drops:
+ * an older release can still run against a tombstoned-but-present column.
+ */
+export interface AppRelease {
+  id: string;
+  appId: string;
+  version: number;
+  definition: unknown;
+  lockfile: AppLockfile;
+  schemaPlan: unknown;
+  state: AppReleaseState;
+  preparedAt?: string;
+  activatedAt?: string;
+}
+
+export const AppReleaseSchema = z.object({
+  id: z.string().min(1),
+  appId: z.string().min(1),
+  version: z.number().int().positive({
+    message: 'AppRelease.version must be a positive integer (1-based).',
+  }),
+  definition: z.unknown(),
+  lockfile: AppLockfileSchema,
+  schemaPlan: z.unknown(),
+  state: AppReleaseStateSchema,
+  preparedAt: z.string().min(1).optional(),
+  activatedAt: z.string().min(1).optional(),
+}) as z.ZodType<AppRelease>;

package/src/app-runtime/lib/app.ts

@@ -15,6 +15,7 @@ import { BiomeInstallSchema, type BiomeInstall } from './biome-install';
 import { AudiencePolicySchema, type AudiencePolicy } from './audience-policy';
 import { BrandingConfigSchema, type BrandingConfig } from './branding-config';
 import { AppLockfileSchema, type AppLockfile } from './app-lockfile';
+import { SurfaceKind, SurfaceKindSchema } from './surface-kind';
 
 /**
  * Per-App tightening on top of the base `CapabilityPolicy` carried by an
@@ -47,12 +48,22 @@ export const CapabilityPolicyOverrideSchema = z.object({
  *
  * Invariants enforced at parse time:
  *
- * - `installedBiomes` MUST be non-empty — an App with zero biomes has no
- *   capability surface, so this is a fail-fast policy bug.
+ * - `installedBiomes` MUST be non-empty for a `Composed` or `Coded` App — one
+ *   with zero biomes would have no capability surface, so that is a fail-fast
+ *   policy bug. A **`Declared` App is exempt**: an app-forge definition installs
+ *   no biomes at all. Its capability surface comes from `capabilityPolicy` and
+ *   the declarative runtime that hosts it, not from a biome install. Requiring a
+ *   biome here would force every declared app to fabricate one, which is how a
+ *   fail-fast invariant quietly becomes a lie.
  * - `audiences` MUST be non-empty — an App with zero audiences is
  *   unreachable; declare at least one (e.g. `InternalOrg`) explicitly.
  * - `defaultZone` and `lockfile` are REQUIRED (no implicit default environment,
  *   no "best-effort" un-pinned execution).
+ * - `surface` is REQUIRED — the tier the App is authored at (`Declared` /
+ *   `Composed` / `Coded`).
+ * - `activeReleaseId` is nullable: an App with no active release has NEVER
+ *   published. It is the ONLY atomic publish switch (D2) — moving this pointer
+ *   is what makes a prepared `AppRelease` visible to every runtime surface.
  *
  * Per-App tightening on top of a environment's `CapabilityPolicy` is carried by
  * `capabilityPolicy` (intersect-only at the gateway, never widen).
@@ -65,20 +76,40 @@ export interface App {
   capabilityPolicy: CapabilityPolicyOverride[];
   branding: BrandingConfig;
   lockfile: AppLockfile;
+  surface: SurfaceKind;
+  activeReleaseId?: string;
 }
 
-export const AppSchema = z.object({
-  ref: XemaObjectRefSchema,
-  installedBiomes: z.array(BiomeInstallSchema).min(1, {
-    message:
-      'App.installedBiomes must contain at least one BiomeInstall; an App with zero biomes has no capability surface.',
-  }),
-  defaultZone: ExecutionEnvironmentRefSchema,
-  audiences: z.array(AudiencePolicySchema).min(1, {
-    message:
-      'App.audiences must contain at least one AudiencePolicy; an App with zero audiences is unreachable.',
-  }),
-  capabilityPolicy: z.array(CapabilityPolicyOverrideSchema),
-  branding: BrandingConfigSchema,
-  lockfile: AppLockfileSchema,
-}) as z.ZodType<App>;
+export const AppSchema = z
+  .object({
+    ref: XemaObjectRefSchema,
+    installedBiomes: z.array(BiomeInstallSchema),
+    defaultZone: ExecutionEnvironmentRefSchema,
+    audiences: z.array(AudiencePolicySchema).min(1, {
+      message:
+        'App.audiences must contain at least one AudiencePolicy; an App with zero audiences is unreachable.',
+    }),
+    capabilityPolicy: z.array(CapabilityPolicyOverrideSchema),
+    branding: BrandingConfigSchema,
+    lockfile: AppLockfileSchema,
+    surface: SurfaceKindSchema,
+    activeReleaseId: z.string().min(1).optional(),
+  })
+  .superRefine((app, ctx) => {
+    // A Declared App (an app-forge definition) installs no biomes: its capability
+    // surface is `capabilityPolicy` plus the declarative runtime that hosts it.
+    // Composed and Coded Apps run biome-provided code, so zero biomes there IS a
+    // policy bug and must fail fast.
+    if (app.surface !== SurfaceKind.Declared && app.installedBiomes.length === 0) {
+      ctx.addIssue({
+        code: 'too_small',
+        minimum: 1,
+        origin: 'array',
+        inclusive: true,
+        path: ['installedBiomes'],
+        message:
+          `App.installedBiomes must contain at least one BiomeInstall for a '${app.surface}' App; ` +
+          'one with zero biomes has no capability surface. Only a `declared` App may install none.',
+      });
+    }
+  }) as unknown as z.ZodType<App>;

package/src/app-runtime/lib/branding-config.ts

@@ -15,16 +15,22 @@ const PRIMARY_COLOR_REGEX =
   /^(?:#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})|rgba?\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}\s*(?:,\s*(?:0|1|0?\.\d+)\s*)?\))$/;
 
 /**
- * `BrandingConfig` — per-App visual branding. Used by the
- * public ingress (`app-runtime-api`) and any embed snippet to theme the
- * audience-facing UI. The shape is intentionally minimal:
+ * `BrandingConfig` — per-App visual branding. The shape is intentionally
+ * minimal:
  *
  * - `displayName` is REQUIRED — every audience-facing surface needs a
  *   human-readable label; no silent fallback to the App slug.
  * - `primaryColor` is validated against a strict hex / rgb(a) grammar.
- * - `cssTokens` is the escape hatch for richer theming — keys map to CSS
- *   custom-property names (without the leading `--`); the host CSS
- *   pipeline interprets the values.
+ * - `cssTokens` is the escape hatch for richer theming — keys are intended to
+ *   map to CSS custom-property names (without the leading `--`).
+ *
+ * STATUS (2026-07-10): this is a VALIDATED CONTRACT ONLY. Nothing applies it at
+ * runtime yet — `logoUrl` and `primaryColor` never reach the DOM, and there is
+ * no host CSS pipeline reading `cssTokens`. An earlier version of this docstring
+ * claimed the public ingress themes the audience-facing UI with it; that reader
+ * does not exist. The runtime branding applier (a theming provider writing CSS
+ * custom properties, resolved per-sub-tenant from `AppRoleBinding.tenantId`) is
+ * Wave 8.4 — do not assume a value set here has any visual effect until then.
  */
 export interface BrandingConfig {
   displayName: string;

package/src/app-runtime/lib/delegated-session.ts

@@ -13,7 +13,7 @@ import {
  * for an `ExternalSubject` audience:
  *
  * ```
- * sub          = external-user:<externalId>     (or anon:<random>)
+ * sub          = external-subject:<externalId>  (or anon:<random>)
  * act          = app:<appClientId>
  * org          = <orgId>
  * project      = <projectId>
@@ -45,7 +45,7 @@ export interface DelegatedSessionClaims {
 export const DelegatedSessionClaimsSchema = z.object({
   sub: z.string().min(1, {
     message:
-      'DelegatedSessionClaims.sub must be a non-empty subject identifier (e.g. `external-user:<id>` or `anon:<random>`).',
+      'DelegatedSessionClaims.sub must be a non-empty subject identifier (e.g. `external-subject:<id>` or `anon:<random>`).',
   }),
   act: z.string().min(1, {
     message:

package/src/app-runtime/lib/surface-kind.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+
+/**
+ * `SurfaceKind` — the closed set of tiers an App surface may be authored at.
+ * "Surface" here is HOW an App is defined and rendered, escalating in the
+ * amount of hand-written code it carries:
+ *
+ * - `Declared`  — the app-forge definition only, NO code. The app is a
+ *   declarative document (audiences, biomes, capability policy, pages) that
+ *   the runtime interprets directly.
+ * - `Composed`  — the declarative definition PLUS App Functions: declarative
+ *   surface extended with small authored functions, still hosted by the
+ *   platform.
+ * - `Coded`     — an ejected, fully hand-written service + web app that the
+ *   team owns end-to-end; the platform hosts it but no longer authors it. Which
+ *   server and web frameworks an ejected app uses is a scaffold decision, not a
+ *   kernel one — this contract must never name them.
+ *
+ * NOTE: `OutputSurfaceKind` in `workflow/lib/workspace-manifest-enums.ts` is an
+ * UNRELATED workspace-manifest concept. Do not extend it and do not import it.
+ *
+ * Values are stable wire strings — never compare against a free-form string.
+ */
+export enum SurfaceKind {
+  Declared = 'declared',
+  Composed = 'composed',
+  Coded = 'coded',
+}
+
+export const SurfaceKindSchema = z.nativeEnum(SurfaceKind);

package/src/capability/index.ts

@@ -1,5 +1,6 @@
 export * from './lib/capability-ref';
 export * from './lib/connector-capability-ref';
+export * from './lib/first-party-capability-domains';
 export * from './lib/capability-grant';
 export * from './lib/capability-policy';
 export * from './lib/permission-profile';

package/src/capability/lib/first-party-capability-domains.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ── The CLOSED set of first-party capability DOMAINS ──
+//
+// A capability ref is `<domain>:<resource>.<verb>@<major>`. A DOMAIN is
+// "first-party" when a fixed in-the-box Xema platform service owns every ref
+// under it — i.e. the capability-router's static dispatch table resolves it
+// directly (never through an org-provisioned or contributed backing).
+//
+// This is the SINGLE SOURCE OF TRUTH for that membership. It exists so two
+// services can agree without one reaching into the other's code:
+//
+//   - `xema-capability-router` builds its static dispatch table from EXACTLY
+//     these keys and asserts the two agree at boot (fail-fast on drift).
+//   - `capability-registry-api` REFUSES an org `CapabilityProviderBinding`
+//     whose ref domain is in this set — an org admin must not be able to bind
+//     `kb:page.read@1` / `agent:invoke@1` / `artifact:blob.read@1` to a URL
+//     they control and silently shadow the platform data plane.
+//
+// Membership is the router's dispatch keys, in dispatch-registration order.
+// Adding/removing a first-party domain is a coordinated change here PLUS the
+// router's dispatch table — the boot assertion turns any divergence into a
+// crash rather than a silent shadow window.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export const FIRST_PARTY_CAPABILITY_DOMAINS = [
+  'xema-shell',
+  'store',
+  'biome',
+  'connector',
+  'kb',
+  'agent',
+  'memory',
+  'model',
+  'model-resolution',
+  'mcp-tool',
+  'workflow',
+  'studio',
+  'interactive-session',
+  'agent-session',
+  'document',
+  'notification',
+  'space',
+  'mailops',
+  'workspace',
+  'worker-runtime',
+  'artifact',
+  'search',
+] as const;
+
+export type FirstPartyCapabilityDomain =
+  (typeof FIRST_PARTY_CAPABILITY_DOMAINS)[number];
+
+export const FirstPartyCapabilityDomainSchema = z.enum(
+  FIRST_PARTY_CAPABILITY_DOMAINS as unknown as [
+    FirstPartyCapabilityDomain,
+    ...FirstPartyCapabilityDomain[],
+  ],
+);
+
+const FIRST_PARTY_CAPABILITY_DOMAIN_SET: ReadonlySet<string> = new Set(
+  FIRST_PARTY_CAPABILITY_DOMAINS,
+);
+
+/**
+ * `true` iff `domain` is a first-party platform capability domain. O(1)
+ * membership over the closed set above. The write-path shadow refusal and the
+ * router's binding-skip defense-in-depth both branch on this — never on an
+ * ad-hoc string compare or a hand-maintained second list.
+ */
+export function isFirstPartyCapabilityDomain(
+  domain: string,
+): domain is FirstPartyCapabilityDomain {
+  return FIRST_PARTY_CAPABILITY_DOMAIN_SET.has(domain);
+}

package/src/principal/index.ts

@@ -0,0 +1,5 @@
+export * from './lib/delegation-grant';
+export * from './lib/delegation-chain';
+export * from './lib/clamp-authority';
+export * from './lib/execution-principal';
+export * from './lib/app-invocation-identity';