@xemahq/kernel-contracts 0.33.0 → 0.35.0

package/dist/principal/lib/clamp-authority.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clampAuthority = clampAuthority;
+exports.clampAuthorityChain = clampAuthorityChain;
+function clampAuthority(executorGrants, actorEffective) {
+    const [smaller, larger] = executorGrants.size <= actorEffective.size
+        ? [executorGrants, actorEffective]
+        : [actorEffective, executorGrants];
+    const intersection = new Set();
+    for (const ref of smaller) {
+        if (larger.has(ref)) {
+            intersection.add(ref);
+        }
+    }
+    return intersection;
+}
+function clampAuthorityChain(authoritySets) {
+    if (authoritySets.length === 0) {
+        return new Set();
+    }
+    return authoritySets.reduce((acc, next) => clampAuthority(acc, next), new Set(authoritySets[0]));
+}
+//# sourceMappingURL=clamp-authority.js.map

package/dist/principal/lib/clamp-authority.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clamp-authority.js","sourceRoot":"","sources":["../../../src/principal/lib/clamp-authority.ts"],"names":[],"mappings":";;AA4BA,wCAgBC;AASD,kDAUC;AAnCD,SAAgB,cAAc,CAC5B,cAA0C,EAC1C,cAA0C;IAE1C,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,GACrB,cAAc,CAAC,IAAI,IAAI,cAAc,CAAC,IAAI;QACxC,CAAC,CAAC,CAAC,cAAc,EAAE,cAAc,CAAC;QAClC,CAAC,CAAC,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC;IAEvC,MAAM,YAAY,GAAG,IAAI,GAAG,EAAiB,CAAC;IAC9C,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,IAAI,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACpB,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC;AASD,SAAgB,mBAAmB,CACjC,aAAwD;IAExD,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO,IAAI,GAAG,EAAiB,CAAC;IAClC,CAAC;IACD,OAAO,aAAa,CAAC,MAAM,CACzB,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,cAAc,CAAC,GAAG,EAAE,IAAI,CAAC,EACxC,IAAI,GAAG,CAAgB,aAAa,CAAC,CAAC,CAAC,CAAC,CACzC,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import { type SubjectRef } from '../../subject';
+import type { DelegationGrant } from './delegation-grant';
+export declare const MAX_DELEGATION_DEPTH = 3;
+export declare enum DelegationErrorCode {
+    ChainTooDeep = "DELEGATION_CHAIN_TOO_DEEP",
+    Cycle = "DELEGATION_CHAIN_CYCLE",
+    Discontinuous = "DELEGATION_CHAIN_DISCONTINUOUS",
+    NotAnchoredAtActor = "DELEGATION_CHAIN_NOT_ANCHORED_AT_ACTOR",
+    NotAnchoredAtExecutor = "DELEGATION_CHAIN_NOT_ANCHORED_AT_EXECUTOR",
+    EmptyChainMismatch = "DELEGATION_CHAIN_EMPTY_MISMATCH"
+}
+export declare const DelegationErrorCodeSchema: z.ZodEnum<typeof DelegationErrorCode>;
+export declare class DelegationChainError extends Error {
+    readonly code: DelegationErrorCode;
+    constructor(args: {
+        code: DelegationErrorCode;
+        message: string;
+    });
+}
+export declare function resolveDelegationChain(args: {
+    actor: SubjectRef;
+    executor: SubjectRef;
+    chain: readonly DelegationGrant[];
+}): readonly DelegationGrant[];
+//# sourceMappingURL=delegation-chain.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"delegation-chain.d.ts","sourceRoot":"","sources":["../../../src/principal/lib/delegation-chain.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAsB,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAQ1D,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAMtC,oBAAY,mBAAmB;IAE7B,YAAY,8BAA8B;IAE1C,KAAK,2BAA2B;IAEhC,aAAa,mCAAmC;IAEhD,kBAAkB,2CAA2C;IAE7D,qBAAqB,8CAA8C;IAMnE,kBAAkB,oCAAoC;CACvD;AAED,eAAO,MAAM,yBAAyB,uCAAoC,CAAC;AAM3E,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;gBAEvB,IAAI,EAAE;QAAE,IAAI,EAAE,mBAAmB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;CAKjE;AAuBD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,KAAK,EAAE,UAAU,CAAC;IAClB,QAAQ,EAAE,UAAU,CAAC;IACrB,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;CACnC,GAAG,SAAS,eAAe,EAAE,CAoE7B"}

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.35.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,8 @@ 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-shell-binding';
+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-shell-binding.ts

@@ -0,0 +1,159 @@
+import { z } from 'zod';
+
+import { AudienceKind } from './audience-policy';
+
+/**
+ * D14 — Shell, audience and host are THREE ORTHOGONAL dimensions of an App.
+ * A public page is not necessarily embedded; a standalone app may be anonymous
+ * or internally authenticated. This file owns two of the three closed dimensions
+ * (the third, audience, is the existing {@link AudienceKind} — D14 forbids
+ * minting a second audience enum) and the rules for which COMBINATIONS are legal.
+ *
+ * The legality rules live here, in the kernel, next to the dimensions they
+ * constrain — not scattered across each consumer. app-forge's publish path calls
+ * {@link validateAppSurfaceCombination}; it does not re-encode the rules.
+ */
+
+/**
+ * `AppShellKind` — how much host chrome / navigation / layout an App surface
+ * carries. Owns: chrome, nav, layout.
+ *
+ * - `Hosted`     — rendered inside the Xema host shell (rail, topbar, org switch).
+ * - `Standalone` — its own full-page surface, no host shell (e.g. a custom domain).
+ * - `Embedded`   — rendered inside a third-party page via an iframe/snippet.
+ * - `Headless`   — no UI at all; an API/automation surface.
+ *
+ * Values are stable wire strings — never compare against a free-form string.
+ */
+export enum AppShellKind {
+  Hosted = 'hosted',
+  Standalone = 'standalone',
+  Embedded = 'embedded',
+  Headless = 'headless',
+}
+
+export const AppShellKindSchema = z.nativeEnum(AppShellKind);
+
+/**
+ * `AppHostBinding` — where an App is served from. Owns: origin, CSP, cookies,
+ * SEO, certificates.
+ *
+ * - `Xema`         — under a Xema-owned origin/path.
+ * - `CustomDomain` — the customer's own domain (needs ACME cert issuance).
+ * - `PathBased`    — a path on a shared host, not its own origin.
+ *
+ * Values are stable wire strings.
+ */
+export enum AppHostBinding {
+  Xema = 'xema',
+  CustomDomain = 'custom-domain',
+  PathBased = 'path-based',
+}
+
+export const AppHostBindingSchema = z.nativeEnum(AppHostBinding);
+
+/** The three-dimension surface descriptor an App declares. */
+export interface AppSurfaceDimensions {
+  readonly shell: AppShellKind;
+  readonly audience: AudienceKind;
+  readonly host: AppHostBinding;
+}
+
+export const AppSurfaceDimensionsSchema: z.ZodType<AppSurfaceDimensions> = z
+  .object({
+    shell: AppShellKindSchema,
+    audience: z.nativeEnum(AudienceKind),
+    host: AppHostBindingSchema,
+  })
+  .strict() as z.ZodType<AppSurfaceDimensions>;
+
+/**
+ * A single reason a `(shell, audience, host)` combination is illegal. `code` is a
+ * closed set so consumers can branch on it; `message` is human-facing.
+ */
+export enum AppSurfaceConflictCode {
+  HeadlessWithChrome = 'headless-with-chrome',
+  EmbeddedIsChrome = 'embedded-is-chrome',
+  StandaloneNeedsOwnHost = 'standalone-needs-own-host',
+  EmbeddedNeedsXemaHost = 'embedded-needs-xema-host',
+}
+
+export interface AppSurfaceConflict {
+  readonly code: AppSurfaceConflictCode;
+  readonly message: string;
+}
+
+export interface AppSurfaceValidation {
+  readonly ok: boolean;
+  readonly conflicts: readonly AppSurfaceConflict[];
+}
+
+/**
+ * Validate a `(shell, audience, host)` combination against D14's legality rules.
+ * PURE and total — returns every conflict, never throws. The empty-conflict case
+ * is `ok: true`.
+ *
+ * Rules (each with a reason, so the publish screen can explain it):
+ * - `Headless` is a NO-UI surface, so it cannot also be `Embedded` (which is a UI
+ *   shell). `headless` + `embedded` is the canonical contradiction the plan names.
+ * - `Embedded` IS a chrome mode; it is meaningful only for a UI shell, so an
+ *   `Embedded` + `Headless` pairing is caught by the same rule from the other side.
+ * - `Standalone` (its own full-page surface) implies its own origin — it cannot be
+ *   `PathBased` (a path on a shared host). `custom-domain` or `xema` are fine.
+ * - `Embedded` is served to a third-party page and relies on the Xema origin's
+ *   CSP/cookies, so it must be `Xema`-hosted, not a `CustomDomain`/`PathBased`.
+ *
+ * `public-anon` + `custom-domain` is explicitly LEGAL (a public citizen portal on
+ * the customer's own domain) — there is no rule against it, so it returns `ok`.
+ * Audience does not currently gate shell/host on its own; the dimension is passed
+ * so the rules can grow without a signature change.
+ */
+export function validateAppSurfaceCombination(
+  dims: AppSurfaceDimensions,
+): AppSurfaceValidation {
+  const conflicts: AppSurfaceConflict[] = [];
+
+  // The headless+embedded contradiction cannot be expressed as a SINGLE
+  // AppShellKind value (they are distinct enum members), so a surface with one
+  // declared shell is internally consistent on that axis. A consumer that models
+  // "embedded" as a separate flag alongside the shell must use
+  // isHeadlessEmbeddedContradiction() to reject the pair — documented there.
+
+  if (
+    dims.shell === AppShellKind.Standalone &&
+    dims.host === AppHostBinding.PathBased
+  ) {
+    conflicts.push({
+      code: AppSurfaceConflictCode.StandaloneNeedsOwnHost,
+      message:
+        'A standalone app has its own full-page surface and cannot be path-based on a shared host; use xema or custom-domain.',
+    });
+  }
+
+  if (
+    dims.shell === AppShellKind.Embedded &&
+    dims.host !== AppHostBinding.Xema
+  ) {
+    conflicts.push({
+      code: AppSurfaceConflictCode.EmbeddedNeedsXemaHost,
+      message:
+        "An embedded app is served into a third-party page and relies on the Xema origin's CSP/cookies; it must be xema-hosted.",
+    });
+  }
+
+  return { ok: conflicts.length === 0, conflicts };
+}
+
+/**
+ * The `headless` + `embedded` contradiction the plan names explicitly. Because
+ * `AppShellKind` is a single value, a surface cannot BE both at once — but a
+ * consumer that models shell as a SET, or that derives "embedded" from a separate
+ * `embed` flag alongside a `headless` shell, must reject the pair. This helper
+ * makes that cross-field rule reusable and named, so no consumer re-encodes it.
+ */
+export function isHeadlessEmbeddedContradiction(
+  shell: AppShellKind,
+  alsoEmbedded: boolean,
+): boolean {
+  return shell === AppShellKind.Headless && alsoEmbedded;
+}

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