@xemahq/kernel-contracts 0.33.0 → 0.35.0

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

package/src/principal/lib/app-invocation-identity.ts

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+import {
+  SubjectKind,
+  SubjectRefSchema,
+  type SubjectRef,
+} from '../../subject';
+
+/**
+ * The two ways an app invocation names its `actor`.
+ *
+ * `AppInvocationIdentity` is SUGAR over the `ExecutionPrincipal.actor` field —
+ * it resolves to exactly one `SubjectRef` (via `resolveInvocationActor`). It
+ * adds no authority of its own; it only says WHOSE authority the app is
+ * exercising.
+ *
+ * **`AsApp` is not a bypass.** A scheduled app runs as `executor = app:<id>`
+ * WITH `actor = app:<id>` — the app IS the actor, acting purely as itself. It
+ * must hold an explicit app role IN ITS OWN app to do anything; there is no
+ * ambient "the scheduler said so" authority. A scheduled job does NOT skip row
+ * policy and does NOT skip field policy. `AsApp` narrows the app to its own
+ * granted authority exactly like any other principal — running unattended buys
+ * it nothing that running on behalf of a user would not have to earn through the
+ * same `clampAuthority` intersection.
+ */
+export enum AppInvocationMode {
+  /** The app acts on behalf of a signed-in user; `actor` is that user. */
+  OnBehalfOfUser = 'on-behalf-of-user',
+  /** The app acts as itself (e.g. a schedule); `actor === executor === app:<id>`. */
+  AsApp = 'as-app',
+}
+
+export const AppInvocationModeSchema = z.nativeEnum(AppInvocationMode);
+
+/**
+ * `OnBehalfOfUser` — the app is exercising a specific user's authority. `user`
+ * becomes `ExecutionPrincipal.actor`; the app is the `executor`.
+ */
+export interface OnBehalfOfUserIdentity {
+  mode: AppInvocationMode.OnBehalfOfUser;
+  /** The signed-in subject whose authority the app exercises. */
+  user: SubjectRef;
+  /** The app doing the acting (becomes `executor`). */
+  appId: string;
+}
+
+/**
+ * `AsApp` — the app acts as itself. `actor` and `executor` are BOTH
+ * `app:<appId>`; see the `AppInvocationMode` docblock — this is not a bypass.
+ */
+export interface AsAppIdentity {
+  mode: AppInvocationMode.AsApp;
+  /** The app acting as its own actor and executor. */
+  appId: string;
+}
+
+export type AppInvocationIdentity = OnBehalfOfUserIdentity | AsAppIdentity;
+
+const onBehalfOfUserShape = z.object({
+  mode: z.literal(AppInvocationMode.OnBehalfOfUser),
+  user: SubjectRefSchema,
+  appId: z.string().min(1),
+});
+
+const asAppShape = z.object({
+  mode: z.literal(AppInvocationMode.AsApp),
+  appId: z.string().min(1),
+});
+
+export const OnBehalfOfUserIdentitySchema =
+  onBehalfOfUserShape as z.ZodType<OnBehalfOfUserIdentity>;
+
+export const AsAppIdentitySchema = asAppShape as z.ZodType<AsAppIdentity>;
+
+export const AppInvocationIdentitySchema = z.discriminatedUnion('mode', [
+  onBehalfOfUserShape,
+  asAppShape,
+]) as z.ZodType<AppInvocationIdentity>;
+
+/**
+ * Resolve an `AppInvocationIdentity` to the `ExecutionPrincipal.actor` it is
+ * sugar for. `OnBehalfOfUser` → the named user. `AsApp` → the app itself
+ * (`app:<appId>`), which is ALSO the executor — an app acting as itself has no
+ * elevated authority (see the `AppInvocationMode` docblock). Total over the
+ * closed union; a new mode is a compile error here, never a silent default.
+ */
+export function resolveInvocationActor(
+  identity: AppInvocationIdentity,
+): SubjectRef {
+  switch (identity.mode) {
+    case AppInvocationMode.OnBehalfOfUser:
+      return identity.user;
+    case AppInvocationMode.AsApp:
+      return { kind: SubjectKind.App, id: identity.appId };
+  }
+}

package/src/principal/lib/clamp-authority.ts

@@ -0,0 +1,64 @@
+import type { CapabilityRef } from '../../capability';
+
+/**
+ * `clampAuthority` — the delegation intersection rule (plan D6).
+ *
+ *   effective(P) = grants(P.executor) ∩ effective(P.actor)
+ *
+ * The effective authority of a principal is the INTERSECTION of what the
+ * executor is granted with what the actor already effectively holds. It is
+ * NEVER a union: a delegate can only ever NARROW authority, never widen it. An
+ * app can never do more than its caller.
+ *
+ * Structurally it cannot widen, and this is the load-bearing property: every
+ * element of the returned set is drawn from `executorGrants` AND must also be
+ * present in `actorEffective`, so the result is a subset of BOTH inputs
+ * (`clamp(A, B) ⊆ A` and `clamp(A, B) ⊆ B`). There is no code path that adds a
+ * ref present in only one operand.
+ *
+ * An EMPTY intersection is the default and correct outcome — not an error, not a
+ * signal to fall back to either operand. A principal whose executor shares no
+ * capability with its actor is authorized for nothing, and that denial is the
+ * whole point (it is THE test that must exist before the Wave 10 function
+ * sandbox: a delegate holding a capability its actor lacks is denied).
+ *
+ * Pure and side-effect free. Inputs are read-only sets of `CapabilityRef`; the
+ * result is a fresh set (the smaller operand is iterated for efficiency, but the
+ * membership rule is symmetric so the result is identical either way).
+ */
+export function clampAuthority(
+  executorGrants: ReadonlySet<CapabilityRef>,
+  actorEffective: ReadonlySet<CapabilityRef>,
+): Set<CapabilityRef> {
+  const [smaller, larger] =
+    executorGrants.size <= actorEffective.size
+      ? [executorGrants, actorEffective]
+      : [actorEffective, executorGrants];
+
+  const intersection = new Set<CapabilityRef>();
+  for (const ref of smaller) {
+    if (larger.has(ref)) {
+      intersection.add(ref);
+    }
+  }
+  return intersection;
+}
+
+/**
+ * Fold `clampAuthority` down a whole chain of authority sets, in order.
+ * `clampAuthorityChain([grants(executor), effective(actor), …])` reduces every
+ * operand by intersection, so ANY empty operand collapses the whole result to
+ * empty. Every operand narrows; none widens. An empty input array is itself an
+ * empty authority set (nothing to be authorized for) — never a wildcard.
+ */
+export function clampAuthorityChain(
+  authoritySets: ReadonlyArray<ReadonlySet<CapabilityRef>>,
+): Set<CapabilityRef> {
+  if (authoritySets.length === 0) {
+    return new Set<CapabilityRef>();
+  }
+  return authoritySets.reduce<Set<CapabilityRef>>(
+    (acc, next) => clampAuthority(acc, next),
+    new Set<CapabilityRef>(authoritySets[0]),
+  );
+}

package/src/principal/lib/delegation-chain.ts

@@ -0,0 +1,145 @@
+import { z } from 'zod';
+import { subjectRefToString, type SubjectRef } from '../../subject';
+import type { DelegationGrant } from './delegation-grant';
+
+/**
+ * Maximum number of hops permitted in a single delegation chain. Delegation is
+ * bounded: user → app → workflow → agent is the deepest legitimate path, so a
+ * chain of more than THREE grants is rejected outright. This is a hard cap, not
+ * a truncation point — an over-long chain is an error, never silently clipped.
+ */
+export const MAX_DELEGATION_DEPTH = 3;
+
+/**
+ * Closed set of delegation-chain validation failures. Every rejection carries a
+ * structured code so callers branch without string parsing.
+ */
+export enum DelegationErrorCode {
+  /** The chain has more hops than `MAX_DELEGATION_DEPTH`. */
+  ChainTooDeep = 'DELEGATION_CHAIN_TOO_DEEP',
+  /** A subject appears more than once across the chain — a delegation cycle. */
+  Cycle = 'DELEGATION_CHAIN_CYCLE',
+  /** Hop `i`'s `to` is not hop `i+1`'s `from` — the chain is not contiguous. */
+  Discontinuous = 'DELEGATION_CHAIN_DISCONTINUOUS',
+  /** The chain's first `from` is not the principal's `actor`. */
+  NotAnchoredAtActor = 'DELEGATION_CHAIN_NOT_ANCHORED_AT_ACTOR',
+  /** The chain's last `to` is not the principal's `executor`. */
+  NotAnchoredAtExecutor = 'DELEGATION_CHAIN_NOT_ANCHORED_AT_EXECUTOR',
+  /**
+   * The chain is empty but `actor` and `executor` differ. An empty chain is
+   * only valid for a self-acting principal (`actor === executor`, e.g. a
+   * scheduled `AsApp` app); claiming delegation with no hops is malformed.
+   */
+  EmptyChainMismatch = 'DELEGATION_CHAIN_EMPTY_MISMATCH',
+}
+
+export const DelegationErrorCodeSchema = z.nativeEnum(DelegationErrorCode);
+
+/**
+ * Structured, fail-fast error thrown by `resolveDelegationChain`. Never a
+ * warning, never a coercion — an invalid chain aborts resolution.
+ */
+export class DelegationChainError extends Error {
+  readonly code: DelegationErrorCode;
+
+  constructor(args: { code: DelegationErrorCode; message: string }) {
+    super(args.message);
+    this.name = 'DelegationChainError';
+    this.code = args.code;
+  }
+}
+
+function subjectsEqual(a: SubjectRef, b: SubjectRef): boolean {
+  return subjectRefToString(a) === subjectRefToString(b);
+}
+
+/**
+ * Validate a delegation chain against its principal's `actor`/`executor`
+ * endpoints and return the (frozen) chain when it is well-formed.
+ *
+ * Fail-fast — throws `DelegationChainError` on ANY of:
+ *
+ *  - a chain longer than `MAX_DELEGATION_DEPTH` (`ChainTooDeep`);
+ *  - a cycle: any subject appearing twice in the hop sequence (`Cycle`);
+ *  - a chain whose first `from` is not `actor` (`NotAnchoredAtActor`);
+ *  - a chain whose last `to` is not `executor` (`NotAnchoredAtExecutor`);
+ *  - a non-contiguous chain where hop i's `to` ≠ hop i+1's `from`
+ *    (`Discontinuous`);
+ *  - an empty chain when `actor` ≠ `executor` (`EmptyChainMismatch`).
+ *
+ * Cycles and over-depth are ERRORS, never truncations: the chain is rejected
+ * whole, never clipped to fit.
+ */
+export function resolveDelegationChain(args: {
+  actor: SubjectRef;
+  executor: SubjectRef;
+  chain: readonly DelegationGrant[];
+}): readonly DelegationGrant[] {
+  const { actor, executor, chain } = args;
+
+  // Empty chain: only a self-acting principal (actor === executor) may omit
+  // delegation. Anything else is a delegation claim with no proof.
+  if (chain.length === 0) {
+    if (!subjectsEqual(actor, executor)) {
+      throw new DelegationChainError({
+        code: DelegationErrorCode.EmptyChainMismatch,
+        message: `Empty delegation chain requires actor === executor, but actor "${subjectRefToString(
+          actor,
+        )}" ≠ executor "${subjectRefToString(executor)}".`,
+      });
+    }
+    return Object.freeze([]);
+  }
+
+  if (chain.length > MAX_DELEGATION_DEPTH) {
+    throw new DelegationChainError({
+      code: DelegationErrorCode.ChainTooDeep,
+      message: `Delegation chain has ${chain.length} hops; the maximum is ${MAX_DELEGATION_DEPTH}.`,
+    });
+  }
+
+  // Anchor: first from === actor, last to === executor.
+  if (!subjectsEqual(chain[0]!.from, actor)) {
+    throw new DelegationChainError({
+      code: DelegationErrorCode.NotAnchoredAtActor,
+      message: `Delegation chain must start at actor "${subjectRefToString(
+        actor,
+      )}", but its first hop starts at "${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 "${subjectRefToString(
+        executor,
+      )}", but its last hop ends at "${subjectRefToString(last.to)}".`,
+    });
+  }
+
+  // Contiguity + cycle detection over the node sequence
+  // [from0, to0, to1, …, toN-1].
+  const seen = new Set<string>();
+  const firstKey = 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" "${subjectRefToString(
+          chain[i - 1]!.to,
+        )}" ≠ this "from" "${subjectRefToString(chain[i]!.from)}".`,
+      });
+    }
+    const toKey = 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]);
+}

package/src/principal/lib/delegation-grant.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { SubjectRefSchema, type SubjectRef } from '../../subject';
+
+/**
+ * `DelegationGrant` — one hop in a delegation chain. It records HOW authority
+ * moved from one subject to the next, so the PDP and the audit trail can prove
+ * the path an invocation took (user → app → workflow → agent → connector)
+ * rather than collapsing it to "the workflow service called a connector".
+ *
+ * Deliberately minimal — `{ from, to, grantedAt, reason? }` — and it does NOT
+ * carry a per-hop capability subset. Justification: effective authority is
+ * resolved by `clampAuthority` as `grants(executor) ∩ effective(actor)` from the
+ * authorization plane's grant tables keyed by SUBJECT, not from data embedded in
+ * the chain. A grant here is a PROVENANCE record (who handed authority to whom,
+ * when, and why), never a capability carrier — putting a capability set on the
+ * hop would duplicate the clamp responsibility and create a second, forgeable
+ * source of truth for "what may this delegate do". `grantedAt` (ISO-8601) plus
+ * an optional human `reason` is the whole audit payload a hop needs.
+ */
+export interface DelegationGrant {
+  /** The subject handing authority DOWN at this hop. */
+  from: SubjectRef;
+  /** The subject RECEIVING authority at this hop. */
+  to: SubjectRef;
+  /** ISO-8601 timestamp at which this hop was minted. */
+  grantedAt: string;
+  /** Optional human-readable rationale for the delegation (audit only). */
+  reason?: string;
+}
+
+export const DelegationGrantSchema = z.object({
+  from: SubjectRefSchema,
+  to: SubjectRefSchema,
+  grantedAt: z.string().datetime(),
+  reason: z.string().min(1).optional(),
+}) as z.ZodType<DelegationGrant>;

package/src/principal/lib/execution-principal.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import {
+  SubjectRefSchema,
+  TokenClassSchema,
+  type SubjectRef,
+  type TokenClass,
+} from '../../subject';
+import {
+  ExecutionEnvironmentRefSchema,
+  type ExecutionEnvironmentRef,
+} from '../../execution-environment';
+import { AppChannelSchema, type AppChannel } from '../../app-runtime';
+import { DelegationGrantSchema, type DelegationGrant } from './delegation-grant';
+
+/**
+ * `ExecutionPrincipal` — the SINGLE delegation contract (plan D5).
+ *
+ * The tree previously answered "who is acting, on whose behalf, with what
+ * authority" in six divergent coats: `SubjectKind`, `TokenClass`,
+ * `SubjectRef.actingFor`, delegated sessions, external subjects, anonymous
+ * sessions, and a PDP "delegation clamp". `ExecutionPrincipal` is the one
+ * answer. It SURVIVES the whole hop path user → app → workflow → agent →
+ * connector — if it did not, the audit trail would collapse to "the workflow
+ * service called a connector" and the PDP could not prove HOW authority was
+ * delegated.
+ *
+ * - `actor` is the ORIGINAL human or external subject whose authority is being
+ *   exercised. `executor` is what is actually running (app | workflow | agent |
+ *   service). Effective authority is `clampAuthority(grants(executor),
+ *   effective(actor))` — an intersection, never a union.
+ * - `delegationChain` records every hop; `resolveDelegationChain` bounds it to
+ *   `MAX_DELEGATION_DEPTH` and rejects cycles fail-fast.
+ * - `channel` (preview/live), `appId`, `releaseId`, `tenantId`, `purpose` are
+ *   the invocation-context fields the PDP and audit trail stamp; all optional
+ *   because not every principal is an app invocation.
+ */
+export interface ExecutionPrincipal {
+  /** The original human or external subject on whose behalf execution runs. */
+  actor: SubjectRef;
+  /** What is actually running: app | workflow | agent | service. */
+  executor: SubjectRef;
+  /** Ordered record of how authority moved from `actor` to `executor`. */
+  delegationChain: DelegationGrant[];
+  /** The minted token class carried by this invocation. */
+  tokenClass: TokenClass;
+  /** The permission-plane environment this invocation is tagged with. */
+  environment: ExecutionEnvironmentRef;
+  /** The single tenant org this invocation is fenced to. */
+  orgId: string;
+  /** The app being invoked, when this is an app invocation. */
+  appId?: string;
+  /** The pinned release of `appId`, when applicable. */
+  releaseId?: string;
+  /** Which definition + data the invocation sees (preview | live). */
+  channel?: AppChannel;
+  /** Sub-tenant scope within `orgId`, when the app is multi-tenant. */
+  tenantId?: string;
+  /** Free-form audit annotation of why this invocation is happening. */
+  purpose?: string;
+}
+
+export const ExecutionPrincipalSchema = z.object({
+  actor: SubjectRefSchema,
+  executor: SubjectRefSchema,
+  delegationChain: z.array(DelegationGrantSchema),
+  tokenClass: TokenClassSchema,
+  environment: ExecutionEnvironmentRefSchema,
+  orgId: z.string().min(1),
+  appId: z.string().min(1).optional(),
+  releaseId: z.string().min(1).optional(),
+  channel: AppChannelSchema.optional(),
+  tenantId: z.string().min(1).optional(),
+  purpose: z.string().min(1).optional(),
+}) as z.ZodType<ExecutionPrincipal>;