@xemahq/kernel-contracts 0.1.0

package/src/space/lib/space-ref-parser.ts

@@ -0,0 +1,198 @@
+import { SpaceKind, type SpaceRef } from './space';
+
+// SpaceRef URI grammar (plan §2 + §6.A.2):
+//
+//   xema://system
+//   xema://org/<org>
+//   xema://org/<org>/project/<project>
+//   xema://org/<org>/project/<project>/app/<app>
+//   xema://org/<org>/project/<project>/app/<app>/session/<session>
+//   xema://org/<org>/project/<project>/app/<app>/biome/<biome>
+//   xema://user/<user>
+//
+// The grammar is closed and ordered. Every segment identifier matches
+// `/^[a-z0-9][a-z0-9_-]*$/`. `system` is the rootless kind. `user` is a
+// sibling of `org` (a User Space is owned by the person, not an org).
+// Bound to the SpaceKind enum — adding a new kind requires extending both.
+
+const SCHEME = 'xema://';
+const IDENT_REGEX = /^[a-z0-9][a-z0-9_-]*$/;
+
+const SEGMENT_KEYS = ['org', 'project', 'app', 'session', 'biome', 'user'] as const;
+type SegmentKey = (typeof SEGMENT_KEYS)[number];
+
+const SEGMENT_KEY_SET: ReadonlySet<string> = new Set(SEGMENT_KEYS);
+
+// Ordered prefix chains — the deepest segment determines `tier`.
+// Each chain must be a strict prefix of one canonical path.
+const KIND_BY_DEEPEST_SEGMENT: Readonly<Record<SegmentKey, SpaceKind>> = {
+  org: SpaceKind.Org,
+  project: SpaceKind.Project,
+  app: SpaceKind.App,
+  session: SpaceKind.Session,
+  biome: SpaceKind.Biome,
+  user: SpaceKind.User,
+};
+
+// Maps URI segment keys to the corresponding SpaceRef field name.
+const FIELD_OF: Readonly<Record<SegmentKey, keyof SpaceRef>> = {
+  org: 'orgId',
+  project: 'projectId',
+  app: 'appId',
+  session: 'sessionId',
+  biome: 'biomeId',
+  user: 'userId',
+};
+
+// Allowed parent for each segment — enforces the canonical ordering.
+const PARENT_OF: Readonly<Record<SegmentKey, SegmentKey | null>> = {
+  org: null,
+  project: 'org',
+  app: 'project',
+  session: 'app',
+  biome: 'app',
+  user: null,
+};
+
+export class SpaceRefParseError extends Error {
+  readonly raw: string;
+  constructor(message: string, raw: string) {
+    super(message);
+    this.name = 'SpaceRefParseError';
+    this.raw = raw;
+  }
+}
+
+export function parseSpaceRef(uri: string): SpaceRef {
+  if (typeof uri !== 'string' || uri.length === 0) {
+    throw new SpaceRefParseError('SpaceRef URI must be a non-empty string.', String(uri));
+  }
+  if (!uri.startsWith(SCHEME)) {
+    throw new SpaceRefParseError(`SpaceRef URI must start with "${SCHEME}".`, uri);
+  }
+  const body = uri.slice(SCHEME.length);
+  if (body.length === 0) {
+    throw new SpaceRefParseError('SpaceRef URI has empty body after scheme.', uri);
+  }
+  const parts = body.split('/');
+
+  if (parts.length === 1 && parts[0] === 'system') {
+    return { tier: SpaceKind.System, path: uri };
+  }
+
+  if (parts.length % 2 !== 0) {
+    throw new SpaceRefParseError(
+      `SpaceRef URI body must be pairs of <segment>/<id> (got ${parts.length} parts).`,
+      uri,
+    );
+  }
+
+  const segments: Partial<Record<SegmentKey, string>> = {};
+  let lastSegment: SegmentKey | null = null;
+
+  for (let i = 0; i < parts.length; i += 2) {
+    const key = parts[i]!;
+    const value = parts[i + 1]!;
+    if (!SEGMENT_KEY_SET.has(key)) {
+      throw new SpaceRefParseError(
+        `SpaceRef URI has unknown segment key "${key}". Allowed: ${SEGMENT_KEYS.join(', ')}.`,
+        uri,
+      );
+    }
+    const typedKey = key as SegmentKey;
+    if (segments[typedKey] !== undefined) {
+      throw new SpaceRefParseError(`SpaceRef URI repeats segment "${key}".`, uri);
+    }
+    if (!IDENT_REGEX.test(value)) {
+      throw new SpaceRefParseError(
+        `SpaceRef URI segment "${key}" has invalid id "${value}".`,
+        uri,
+      );
+    }
+    const expectedParent = PARENT_OF[typedKey];
+    if (expectedParent !== lastSegment) {
+      throw new SpaceRefParseError(
+        `SpaceRef URI segment "${key}" must follow "${expectedParent ?? '(root)'}", got "${lastSegment ?? '(root)'}".`,
+        uri,
+      );
+    }
+    segments[typedKey] = value;
+    lastSegment = typedKey;
+  }
+
+  if (lastSegment === null) {
+    throw new SpaceRefParseError('SpaceRef URI parsed no segments.', uri);
+  }
+
+  const tier = KIND_BY_DEEPEST_SEGMENT[lastSegment];
+  const ref: SpaceRef = { tier, path: uri };
+  for (const segKey of SEGMENT_KEYS) {
+    const segValue = segments[segKey];
+    if (segValue !== undefined) {
+      const fieldName = FIELD_OF[segKey];
+      (ref as unknown as Record<string, string>)[fieldName] = segValue;
+    }
+  }
+  return ref;
+}
+
+export function formatSpaceRef(ref: SpaceRef): string {
+  if (ref.tier === SpaceKind.System) {
+    return `${SCHEME}system`;
+  }
+  const out: string[] = [SCHEME];
+  const append = (key: SegmentKey, value: string | undefined): void => {
+    if (value === undefined) {
+      throw new SpaceRefParseError(
+        `formatSpaceRef: missing required segment "${key}" for tier "${ref.tier}".`,
+        ref.tier,
+      );
+    }
+    if (!IDENT_REGEX.test(value)) {
+      throw new SpaceRefParseError(
+        `formatSpaceRef: segment "${key}" id "${value}" violates grammar.`,
+        ref.tier,
+      );
+    }
+    if (out.length > 1) out.push('/');
+    out.push(`${key}/${value}`);
+  };
+
+  switch (ref.tier) {
+    case SpaceKind.User:
+      append('user', ref.userId);
+      break;
+    case SpaceKind.Org:
+      append('org', ref.orgId);
+      break;
+    case SpaceKind.Project:
+      append('org', ref.orgId);
+      append('project', ref.projectId);
+      break;
+    case SpaceKind.App:
+      append('org', ref.orgId);
+      append('project', ref.projectId);
+      append('app', ref.appId);
+      break;
+    case SpaceKind.Session:
+      append('org', ref.orgId);
+      append('project', ref.projectId);
+      append('app', ref.appId);
+      append('session', ref.sessionId);
+      break;
+    case SpaceKind.Biome:
+      append('org', ref.orgId);
+      append('project', ref.projectId);
+      append('app', ref.appId);
+      append('biome', ref.biomeId);
+      break;
+    default: {
+      const exhaustive: never = ref.tier;
+      throw new SpaceRefParseError(
+        `formatSpaceRef: unhandled SpaceKind "${String(exhaustive)}".`,
+        String(exhaustive),
+      );
+    }
+  }
+  return out.join('');
+}

package/src/space/lib/space-traversal.ts

@@ -0,0 +1,55 @@
+import { formatSpaceRef } from './space-ref-parser';
+import { SpaceKind, type SpaceRef } from './space';
+
+// Closest-first ancestor walk. For a Project space the walk is
+// [Project, Org, System]; for a Session space it is
+// [Session, App, Project, Org, System]; for a User space it is
+// [User, System]. Used by policy resolution: "most-specific match wins".
+//
+// Implementation: derive each ancestor by stripping the deepest segment.
+// We rebuild via formatSpaceRef so the returned `path` is always canonical.
+export function walkAncestors(ref: SpaceRef): SpaceRef[] {
+  const out: SpaceRef[] = [];
+  let current: SpaceRef | null = ref;
+  while (current !== null) {
+    out.push(current);
+    current = parentOf(current);
+  }
+  return out;
+}
+
+function parentOf(ref: SpaceRef): SpaceRef | null {
+  switch (ref.tier) {
+    case SpaceKind.System:
+      return null;
+    case SpaceKind.User:
+    case SpaceKind.Org:
+      return { tier: SpaceKind.System, path: formatSpaceRef({ tier: SpaceKind.System }) };
+    case SpaceKind.Project: {
+      const parent: SpaceRef = { tier: SpaceKind.Org };
+      if (ref.orgId !== undefined) parent.orgId = ref.orgId;
+      parent.path = formatSpaceRef(parent);
+      return parent;
+    }
+    case SpaceKind.App: {
+      const parent: SpaceRef = { tier: SpaceKind.Project };
+      if (ref.orgId !== undefined) parent.orgId = ref.orgId;
+      if (ref.projectId !== undefined) parent.projectId = ref.projectId;
+      parent.path = formatSpaceRef(parent);
+      return parent;
+    }
+    case SpaceKind.Session:
+    case SpaceKind.Biome: {
+      const parent: SpaceRef = { tier: SpaceKind.App };
+      if (ref.orgId !== undefined) parent.orgId = ref.orgId;
+      if (ref.projectId !== undefined) parent.projectId = ref.projectId;
+      if (ref.appId !== undefined) parent.appId = ref.appId;
+      parent.path = formatSpaceRef(parent);
+      return parent;
+    }
+    default: {
+      const exhaustive: never = ref.tier;
+      throw new Error(`walkAncestors: unhandled SpaceKind "${String(exhaustive)}".`);
+    }
+  }
+}

package/src/space/lib/space.ts

@@ -0,0 +1,173 @@
+import { z } from 'zod';
+
+/**
+ * Closed kind set — Spaces have exactly these 7 layers (plan v4.3 §2/§3
+ * vocabulary). Replaces the legacy 5-tier `ScopeTier` (System / Biome /
+ * Org / Project / User) by adding `App` and `Session` for the runtime
+ * ownership plane introduced in Phase A.2.
+ *
+ * Precedence is **most specific wins**:
+ *   User > Session > Biome > App > Project > Org > System
+ * applied by `walkAncestors` in `./space-traversal`.
+ */
+export enum SpaceKind {
+  System = 'system',
+  Org = 'org',
+  Project = 'project',
+  App = 'app',
+  Session = 'session',
+  Biome = 'biome',
+  User = 'user',
+}
+
+/** Closed data-classification set used by policy obligations + redaction. */
+export enum DataClassification {
+  Public = 'public',
+  Internal = 'internal',
+  Confidential = 'confidential',
+  Secret = 'secret',
+  Regulated = 'regulated',
+}
+
+/**
+ * `SpaceRef` — the canonical structured pointer to a Space.
+ *
+ * The `tier` field carries the {@link SpaceKind} value. Each tier
+ * requires the matching `<x>Id` segment to be set; ancestor segments
+ * MAY be populated when known (e.g. a `Project` ref carries both
+ * `orgId` and `projectId`). Optional `path` carries the fully-formatted
+ * `xema://...` URI when materialised.
+ *
+ * Phase A.2 (plan v4.3) — value-identical rename from `ScopeRef`. Field
+ * names (`tier`, `orgId`, `projectId`, `biomeId`, `userId`) are
+ * unchanged so the rename is a single identifier swap at every consumer.
+ */
+export interface SpaceRef {
+  tier: SpaceKind;
+  orgId?: string;
+  projectId?: string;
+  appId?: string;
+  sessionId?: string;
+  biomeId?: string;
+  userId?: string;
+  path?: string;
+  classification?: DataClassification;
+}
+
+export const SpaceKindSchema = z.nativeEnum(SpaceKind);
+export const DataClassificationSchema = z.nativeEnum(DataClassification);
+
+type SegmentKey =
+  | 'orgId'
+  | 'projectId'
+  | 'appId'
+  | 'sessionId'
+  | 'biomeId'
+  | 'userId';
+
+const spaceRefBaseShape = {
+  tier: SpaceKindSchema,
+  orgId: z.string().min(1).optional(),
+  projectId: z.string().min(1).optional(),
+  appId: z.string().min(1).optional(),
+  sessionId: z.string().min(1).optional(),
+  biomeId: z.string().min(1).optional(),
+  userId: z.string().min(1).optional(),
+  path: z.string().min(1).optional(),
+  classification: DataClassificationSchema.optional(),
+} as const;
+
+type SpaceRefValidated = z.infer<z.ZodObject<typeof spaceRefBaseShape>>;
+
+function validateSpaceRefSegments(
+  value: SpaceRefValidated,
+  ctx: z.RefinementCtx,
+): void {
+  const required = REQUIRED_SEGMENTS[value.tier];
+  for (const key of required) {
+    const segValue = value[key as keyof SpaceRefValidated];
+    if (!segValue) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `SpaceKind.${value.tier} requires ${key}`,
+        path: [key],
+      });
+    }
+  }
+}
+
+export const SpaceRefSchema = z
+  .object(spaceRefBaseShape)
+  .superRefine(validateSpaceRefSegments);
+
+const REQUIRED_SEGMENTS: Readonly<Record<SpaceKind, readonly SegmentKey[]>> = {
+  [SpaceKind.System]: [],
+  [SpaceKind.Org]: ['orgId'],
+  [SpaceKind.Project]: ['orgId', 'projectId'],
+  [SpaceKind.App]: ['orgId', 'projectId', 'appId'],
+  [SpaceKind.Session]: ['sessionId'],
+  [SpaceKind.Biome]: ['biomeId'],
+  [SpaceKind.User]: ['userId'],
+};
+
+/**
+ * Render a `SpaceRef` as its XVFS path prefix (used by `XemaObjectRef`
+ * formatting and by object-registry-api projections). Returns a string
+ * that starts with `/`. Fails fast if a required segment is missing.
+ */
+export function spaceRefToPath(ref: SpaceRef): string {
+  switch (ref.tier) {
+    case SpaceKind.System:
+      return '/system';
+    case SpaceKind.Biome:
+      if (!ref.biomeId) {
+        throw new Error('spaceRefToPath: SpaceKind.Biome requires biomeId');
+      }
+      return `/biomes/${ref.biomeId}`;
+    case SpaceKind.Org:
+      if (!ref.orgId) {
+        throw new Error('spaceRefToPath: SpaceKind.Org requires orgId');
+      }
+      return `/orgs/${ref.orgId}`;
+    case SpaceKind.Project:
+      if (!ref.orgId || !ref.projectId) {
+        throw new Error(
+          'spaceRefToPath: SpaceKind.Project requires orgId and projectId',
+        );
+      }
+      return `/orgs/${ref.orgId}/projects/${ref.projectId}`;
+    case SpaceKind.App:
+      if (!ref.orgId || !ref.projectId || !ref.appId) {
+        throw new Error(
+          'spaceRefToPath: SpaceKind.App requires orgId, projectId, and appId',
+        );
+      }
+      return `/orgs/${ref.orgId}/projects/${ref.projectId}/apps/${ref.appId}`;
+    case SpaceKind.Session:
+      if (!ref.sessionId) {
+        throw new Error('spaceRefToPath: SpaceKind.Session requires sessionId');
+      }
+      return `/sessions/${ref.sessionId}`;
+    case SpaceKind.User:
+      if (!ref.userId) {
+        throw new Error('spaceRefToPath: SpaceKind.User requires userId');
+      }
+      return `/users/${ref.userId}`;
+  }
+}
+
+/**
+ * `Space` — the persisted Space row shape consumed across services.
+ * Domain services own their own storage; this is the wire contract used
+ * by the object-registry-api projection and by policy decisions.
+ */
+export interface Space {
+  id: string;
+  ref: SpaceRef;
+  displayName: string;
+  parentId?: string;
+  classification?: DataClassification;
+  createdAt: string;
+  updatedAt: string;
+  labels?: Record<string, string>;
+}

package/src/subject/index.ts

@@ -0,0 +1,2 @@
+export * from './lib/subject';
+export * from './lib/token-class';

package/src/subject/lib/subject.ts

@@ -0,0 +1,111 @@
+import { z } from 'zod';
+
+/**
+ * Canonical, closed subject taxonomy for Xema (the single source of truth).
+ *
+ * Every Xema invocation has exactly one Subject; the kind tells policy how to
+ * interpret `id` (e.g. a Keycloak user id vs an agent slug vs a service-account
+ * name vs an opaque external-session id) and which obligations apply.
+ *
+ * This is the UNION of the historically-divergent enums that previously lived
+ * in `@xemahq/capability-contracts` and `@xemahq/execution-context-contracts`.
+ * Both now re-export from here. Closed set — adding a kind is a kernel change
+ * (boundary CI rejects an unknown discriminator at runtime via the schema).
+ *
+ * NOTE: `workflow` is intentionally NOT a SubjectKind. A workflow run acts as a
+ * `service` (or `agent`) subject distinguished by its `TokenClass`
+ * (`workflow_runtime_token`) — token class is orthogonal to subject kind, so we
+ * do not double-encode it here.
+ */
+export enum SubjectKind {
+  User = 'user',
+  Agent = 'agent',
+  App = 'app',
+  AppClient = 'app-client',
+  Service = 'service',
+  Group = 'group',
+  Role = 'role',
+  Runner = 'runner',
+  ExternalSubject = 'external-subject',
+  Anon = 'anon',
+}
+
+export const SubjectKindSchema = z.nativeEnum(SubjectKind);
+
+/**
+ * Delegation pointer. Set on `SubjectRef.actingFor` when the present Subject is
+ * acting on behalf of another Subject (e.g. an agent invoking a capability
+ * under a user's authority). Policy MUST evaluate BOTH the acting subject and
+ * the principal — never conflate or drop the `actingFor` half.
+ *
+ * For multi-hop delegation (external visitor → agent-session → agent → owner)
+ * carry the full ordered chain on `RequestContext.actorChain`; `actingFor` is
+ * the single immediate principal.
+ */
+export interface ActingForRef {
+  kind: SubjectKind;
+  id: string;
+}
+
+export const ActingForRefSchema = z.object({
+  kind: SubjectKindSchema,
+  id: z.string().min(1),
+}) as z.ZodType<ActingForRef>;
+
+/**
+ * `SubjectRef` — the canonical pointer to who is invoking a capability.
+ *
+ * Shape: `{ kind, id, roles?, actingFor? }`. `id` is the bare per-kind
+ * identifier (NOT a `kind:id` composite — use `subjectRefToString` when a
+ * composite string is needed, e.g. for OpenFGA object ids or grant-table refs).
+ * `roles` is an OPAQUE array of role identifiers — the closed dictionary is
+ * owned by `authorization-api` + the org policy bundle, not by the kernel.
+ */
+export interface SubjectRef {
+  kind: SubjectKind;
+  id: string;
+  roles?: string[];
+  actingFor?: ActingForRef;
+}
+
+export const SubjectRefSchema = z.object({
+  kind: SubjectKindSchema,
+  id: z.string().min(1),
+  roles: z.array(z.string().min(1)).optional(),
+  actingFor: ActingForRefSchema.optional(),
+}) as z.ZodType<SubjectRef>;
+
+/**
+ * Render a subject to its canonical composite string `"<kind>:<id>"` — the
+ * encoding used for OpenFGA object ids and the `authorization-api` grant-table
+ * `subjectRef` column. Lossless inverse of `parseSubjectRef`: `id` may itself
+ * contain `:` (only the kind prefix is split off), so round-tripping is stable.
+ */
+export function subjectRefToString(
+  subject: Pick<SubjectRef, 'kind' | 'id'>,
+): string {
+  return `${subject.kind}:${subject.id}`;
+}
+
+/**
+ * Parse a canonical composite string `"<kind>:<id>"` back into a `SubjectRef`.
+ * Splits ONLY on the first `:` so ids containing colons survive. Fail-fast on a
+ * missing/empty id or an unknown kind — never silently coerce.
+ */
+export function parseSubjectRef(ref: string): SubjectRef {
+  const firstColon = ref.indexOf(':');
+  if (firstColon <= 0 || firstColon === ref.length - 1) {
+    throw new Error(
+      `Invalid subject ref "${ref}": expected "<kind>:<id>" with a non-empty kind and id.`,
+    );
+  }
+  const kind = ref.slice(0, firstColon);
+  const id = ref.slice(firstColon + 1);
+  const parsed = SubjectKindSchema.safeParse(kind);
+  if (!parsed.success) {
+    throw new Error(
+      `Invalid subject ref "${ref}": "${kind}" is not a known SubjectKind.`,
+    );
+  }
+  return { kind: parsed.data, id };
+}

package/src/subject/lib/token-class.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+
+/**
+ * Closed set of token classes Xema mints and enforces. The class is an explicit
+ * minted claim (`token_class`) — it is orthogonal to `SubjectKind` and travels
+ * with the subject on `RequestContext.tokenClass`. Guards enforce class
+ * boundaries (e.g. `ServiceActorGuard` admits ONLY `service_jwt`; the
+ * capability-router/public-gateway edges admit the scoped runtime/session
+ * classes on invoke routes via `@RequireTokenClass`).
+ *
+ * - `user_jwt`               — browser/user login token (browser-safe APIs, public gateway).
+ * - `service_jwt`            — trusted platform service-to-service token (internal APIs, capability-router).
+ * - `agent_runtime_token`    — scoped agent token; may invoke capabilities per grants, NOT call internal s2s APIs.
+ * - `workflow_runtime_token` — scoped workflow-run token; same constraints as agent.
+ * - `external_session_token` — scoped website-visitor/public-session token; only its channel/session surface.
+ * - `runner_attestation_token` — biome-runner token for register/heartbeat/claim-work.
+ */
+export enum TokenClass {
+  UserJwt = 'user_jwt',
+  ServiceJwt = 'service_jwt',
+  AgentRuntimeToken = 'agent_runtime_token',
+  WorkflowRuntimeToken = 'workflow_runtime_token',
+  ExternalSessionToken = 'external_session_token',
+  RunnerAttestationToken = 'runner_attestation_token',
+}
+
+export const TokenClassSchema = z.nativeEnum(TokenClass);

package/src/workflow/index.ts

@@ -0,0 +1,45 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Workflow Contracts — Barrel Export ──
+//
+// Types + enums shared between workflow-engine-api, workflow-runtime-worker,
+// and the frontend client. Runtime-framework-agnostic. No NestJS, no Prisma.
+//
+// Consumers import specific symbols; never re-declare these shapes locally.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/enums';
+export * from './lib/temporal-namespace';
+export * from './lib/platform-task-queue';
+export * from './lib/errors';
+export * from './lib/snapshot-ref';
+export * from './lib/action-ref';
+export * from './lib/artifact-ref';
+export * from './lib/activity-outputs';
+export * from './lib/mount-plan';
+export * from './lib/agent-role';
+export * from './lib/role-capability';
+export * from './lib/concurrency-group';
+export * from './lib/trigger-payload';
+export * from './lib/compiled-run';
+export * from './lib/variable-requirement';
+export * from './lib/compiled-workspace-manifest';
+export * from './lib/workspace-manifest-enums';
+export * from './lib/model-ref';
+export * from './lib/job-run';
+export * from './lib/run-progress';
+export * from './lib/deliverable-result';
+export * from './lib/review-subject/index';
+export * from './lib/briefcase';
+
+// Workflow-domain types absorbed from the deleted pipeline-contracts package.
+export * from './lib/catalog-taxonomies';
+export * from './lib/domain-tag';
+// Generic ordered-stage contract. The software-delivery-specific stage list,
+// hierarchy, and gate-reviewer map were relocated to the software-dev biome
+// (`biomes/platform/software-dev/workflow-config/phase-config.json`) — the
+// kernel carries no domain phase enum.
+export * from './lib/workflow-stage';
+export * from './lib/phase-report';
+export * from './lib/work-item-payloads';
+export * from './lib/sampling-profiles';
+export * from './lib/canonical-concepts';

package/src/workflow/lib/action-ref.ts

@@ -0,0 +1,48 @@
+import { ActionExecutionKind, ActionKind, TaskQueueName } from './enums';
+
+/**
+ * Immutable reference to a specific action version resolved at compile time.
+ * The compiler replaces authored `uses: xema/<id>@<ver>` strings with this
+ * structure so the engine + worker never re-resolve at runtime (defensively
+ * against action-manifest drift between compile and execute).
+ */
+export interface ActionRef {
+  /** Action id, e.g. `xema/agent`. For reusable workflows, `xema://workflow/<slug>`. */
+  readonly id: string;
+  /** Semantic version — resolved from `@<ver>` against the action-manifest registry. */
+  readonly version: string;
+  /** sha256 of the resolved action manifest YAML. Used for audit + cache keys. */
+  readonly manifestSha256: string;
+  /** How this action executes under Temporal. Fixed at the manifest level. */
+  readonly executionKind: ActionExecutionKind;
+  /** Temporal task queue this action executes on. Fixed at the manifest level. */
+  readonly taskQueue: TaskQueueName;
+  /**
+   * Semantic category of the action — drives consumer presentation
+   * (FE canvas shape, badge icon, narration colour). Closed enum at
+   * the kernel boundary; unknown strings from third-party manifests
+   * MUST be treated as `GENERIC` by consumers. Pinned at compile time
+   * from the manifest's `spec.actionKind`. Reusable workflows + legacy
+   * un-manifested actions get `GENERIC` (or `DISPATCH` for reusables).
+   */
+  readonly actionKind: ActionKind;
+  /** True if `uses:` resolves to a reusable workflow rather than a built-in/custom action. */
+  readonly isReusableWorkflow: boolean;
+  /**
+   * JSON Schema for the action's `with:` block, copied verbatim from
+   * `spec.inputs` of the resolved manifest at compile time. The worker
+   * validates each materialized `with:` payload against this schema before
+   * dispatching the activity, so the manifest's `pattern` / `enum` /
+   * `required` declarations are enforced at the engine boundary instead of
+   * silently surviving until a downstream service rejects them.
+   *
+   * Pinned at compile time on purpose: a workflow run validates against the
+   * SAME schema that was in effect when the run was compiled, even if a
+   * newer manifest version has been published since. No drift.
+   *
+   * Null only for reusable-workflow jobs (their `with:` is the parent
+   * workflow's `workflow_call.inputs`, validated by the child compile pass)
+   * and for legacy/un-manifested actions.
+   */
+  readonly inputsSchema: Readonly<Record<string, unknown>> | null;
+}