@xemahq/kernel-contracts 0.34.0 → 0.35.0

package/dist/app-runtime/index.d.ts

@@ -6,6 +6,7 @@ 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/dist/app-runtime/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/app-runtime/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/app-runtime/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC"}

package/dist/app-runtime/index.js

@@ -22,6 +22,7 @@ __exportStar(require("./lib/app-client"), exports);
 __exportStar(require("./lib/app-lockfile"), exports);
 __exportStar(require("./lib/branding-config"), exports);
 __exportStar(require("./lib/surface-kind"), exports);
+__exportStar(require("./lib/app-shell-binding"), exports);
 __exportStar(require("./lib/app-channel"), exports);
 __exportStar(require("./lib/app-release"), exports);
 __exportStar(require("./lib/app"), exports);

package/dist/app-runtime/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/app-runtime/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,sDAAoC;AACpC,wDAAsC;AACtC,yDAAuC;AACvC,0DAAwC;AACxC,mDAAiC;AACjC,qDAAmC;AACnC,wDAAsC;AACtC,qDAAmC;AACnC,oDAAkC;AAClC,oDAAkC;AAClC,4CAA0B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/app-runtime/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,sDAAoC;AACpC,wDAAsC;AACtC,yDAAuC;AACvC,0DAAwC;AACxC,mDAAiC;AACjC,qDAAmC;AACnC,wDAAsC;AACtC,qDAAmC;AACnC,0DAAwC;AACxC,oDAAkC;AAClC,oDAAkC;AAClC,4CAA0B"}

package/dist/app-runtime/lib/app-shell-binding.d.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import { AudienceKind } from './audience-policy';
+export declare enum AppShellKind {
+    Hosted = "hosted",
+    Standalone = "standalone",
+    Embedded = "embedded",
+    Headless = "headless"
+}
+export declare const AppShellKindSchema: z.ZodEnum<typeof AppShellKind>;
+export declare enum AppHostBinding {
+    Xema = "xema",
+    CustomDomain = "custom-domain",
+    PathBased = "path-based"
+}
+export declare const AppHostBindingSchema: z.ZodEnum<typeof AppHostBinding>;
+export interface AppSurfaceDimensions {
+    readonly shell: AppShellKind;
+    readonly audience: AudienceKind;
+    readonly host: AppHostBinding;
+}
+export declare const AppSurfaceDimensionsSchema: z.ZodType<AppSurfaceDimensions>;
+export declare 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[];
+}
+export declare function validateAppSurfaceCombination(dims: AppSurfaceDimensions): AppSurfaceValidation;
+export declare function isHeadlessEmbeddedContradiction(shell: AppShellKind, alsoEmbedded: boolean): boolean;
+//# sourceMappingURL=app-shell-binding.d.ts.map

package/dist/app-runtime/lib/app-shell-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-shell-binding.d.ts","sourceRoot":"","sources":["../../../src/app-runtime/lib/app-shell-binding.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAyBjD,oBAAY,YAAY;IACtB,MAAM,WAAW;IACjB,UAAU,eAAe;IACzB,QAAQ,aAAa;IACrB,QAAQ,aAAa;CACtB;AAED,eAAO,MAAM,kBAAkB,gCAA6B,CAAC;AAY7D,oBAAY,cAAc;IACxB,IAAI,SAAS;IACb,YAAY,kBAAkB;IAC9B,SAAS,eAAe;CACzB;AAED,eAAO,MAAM,oBAAoB,kCAA+B,CAAC;AAGjE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;CAC/B;AAED,eAAO,MAAM,0BAA0B,EAAE,CAAC,CAAC,OAAO,CAAC,oBAAoB,CAMzB,CAAC;AAM/C,oBAAY,sBAAsB;IAChC,kBAAkB,yBAAyB;IAC3C,gBAAgB,uBAAuB;IACvC,sBAAsB,8BAA8B;IACpD,qBAAqB,6BAA6B;CACnD;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACnD;AAsBD,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,oBAAoB,GACzB,oBAAoB,CAgCtB;AASD,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,YAAY,EACnB,YAAY,EAAE,OAAO,GACpB,OAAO,CAET"}

package/dist/app-runtime/lib/app-shell-binding.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppSurfaceConflictCode = exports.AppSurfaceDimensionsSchema = exports.AppHostBindingSchema = exports.AppHostBinding = exports.AppShellKindSchema = exports.AppShellKind = void 0;
+exports.validateAppSurfaceCombination = validateAppSurfaceCombination;
+exports.isHeadlessEmbeddedContradiction = isHeadlessEmbeddedContradiction;
+const zod_1 = require("zod");
+const audience_policy_1 = require("./audience-policy");
+var AppShellKind;
+(function (AppShellKind) {
+    AppShellKind["Hosted"] = "hosted";
+    AppShellKind["Standalone"] = "standalone";
+    AppShellKind["Embedded"] = "embedded";
+    AppShellKind["Headless"] = "headless";
+})(AppShellKind || (exports.AppShellKind = AppShellKind = {}));
+exports.AppShellKindSchema = zod_1.z.nativeEnum(AppShellKind);
+var AppHostBinding;
+(function (AppHostBinding) {
+    AppHostBinding["Xema"] = "xema";
+    AppHostBinding["CustomDomain"] = "custom-domain";
+    AppHostBinding["PathBased"] = "path-based";
+})(AppHostBinding || (exports.AppHostBinding = AppHostBinding = {}));
+exports.AppHostBindingSchema = zod_1.z.nativeEnum(AppHostBinding);
+exports.AppSurfaceDimensionsSchema = zod_1.z
+    .object({
+    shell: exports.AppShellKindSchema,
+    audience: zod_1.z.nativeEnum(audience_policy_1.AudienceKind),
+    host: exports.AppHostBindingSchema,
+})
+    .strict();
+var AppSurfaceConflictCode;
+(function (AppSurfaceConflictCode) {
+    AppSurfaceConflictCode["HeadlessWithChrome"] = "headless-with-chrome";
+    AppSurfaceConflictCode["EmbeddedIsChrome"] = "embedded-is-chrome";
+    AppSurfaceConflictCode["StandaloneNeedsOwnHost"] = "standalone-needs-own-host";
+    AppSurfaceConflictCode["EmbeddedNeedsXemaHost"] = "embedded-needs-xema-host";
+})(AppSurfaceConflictCode || (exports.AppSurfaceConflictCode = AppSurfaceConflictCode = {}));
+function validateAppSurfaceCombination(dims) {
+    const conflicts = [];
+    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 };
+}
+function isHeadlessEmbeddedContradiction(shell, alsoEmbedded) {
+    return shell === AppShellKind.Headless && alsoEmbedded;
+}
+//# sourceMappingURL=app-shell-binding.js.map

package/dist/app-runtime/lib/app-shell-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-shell-binding.js","sourceRoot":"","sources":["../../../src/app-runtime/lib/app-shell-binding.ts"],"names":[],"mappings":";;;AA8GA,sEAkCC;AASD,0EAKC;AA9JD,6BAAwB;AAExB,uDAAiD;AAyBjD,IAAY,YAKX;AALD,WAAY,YAAY;IACtB,iCAAiB,CAAA;IACjB,yCAAyB,CAAA;IACzB,qCAAqB,CAAA;IACrB,qCAAqB,CAAA;AACvB,CAAC,EALW,YAAY,4BAAZ,YAAY,QAKvB;AAEY,QAAA,kBAAkB,GAAG,OAAC,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AAY7D,IAAY,cAIX;AAJD,WAAY,cAAc;IACxB,+BAAa,CAAA;IACb,gDAA8B,CAAA;IAC9B,0CAAwB,CAAA;AAC1B,CAAC,EAJW,cAAc,8BAAd,cAAc,QAIzB;AAEY,QAAA,oBAAoB,GAAG,OAAC,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AASpD,QAAA,0BAA0B,GAAoC,OAAC;KACzE,MAAM,CAAC;IACN,KAAK,EAAE,0BAAkB;IACzB,QAAQ,EAAE,OAAC,CAAC,UAAU,CAAC,8BAAY,CAAC;IACpC,IAAI,EAAE,4BAAoB;CAC3B,CAAC;KACD,MAAM,EAAqC,CAAC;AAM/C,IAAY,sBAKX;AALD,WAAY,sBAAsB;IAChC,qEAA2C,CAAA;IAC3C,iEAAuC,CAAA;IACvC,8EAAoD,CAAA;IACpD,4EAAkD,CAAA;AACpD,CAAC,EALW,sBAAsB,sCAAtB,sBAAsB,QAKjC;AAgCD,SAAgB,6BAA6B,CAC3C,IAA0B;IAE1B,MAAM,SAAS,GAAyB,EAAE,CAAC;IAQ3C,IACE,IAAI,CAAC,KAAK,KAAK,YAAY,CAAC,UAAU;QACtC,IAAI,CAAC,IAAI,KAAK,cAAc,CAAC,SAAS,EACtC,CAAC;QACD,SAAS,CAAC,IAAI,CAAC;YACb,IAAI,EAAE,sBAAsB,CAAC,sBAAsB;YACnD,OAAO,EACL,sHAAsH;SACzH,CAAC,CAAC;IACL,CAAC;IAED,IACE,IAAI,CAAC,KAAK,KAAK,YAAY,CAAC,QAAQ;QACpC,IAAI,CAAC,IAAI,KAAK,cAAc,CAAC,IAAI,EACjC,CAAC;QACD,SAAS,CAAC,IAAI,CAAC;YACb,IAAI,EAAE,sBAAsB,CAAC,qBAAqB;YAClD,OAAO,EACL,wHAAwH;SAC3H,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;AACnD,CAAC;AASD,SAAgB,+BAA+B,CAC7C,KAAmB,EACnB,YAAqB;IAErB,OAAO,KAAK,KAAK,YAAY,CAAC,QAAQ,IAAI,YAAY,CAAC;AACzD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/kernel-contracts",
-  "version": "0.34.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

@@ -6,6 +6,7 @@ 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-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;
+}