@xemahq/kernel-contracts 0.50.0 → 0.56.0

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

@@ -1,198 +1,223 @@
-import { SpaceKind, type SpaceRef } from './space';
-
-// SpaceRef URI grammar:
+import {
+  assertValidSpaceSegmentId,
+  SpaceKind,
+  SpaceRefParseError,
+  spaceRefToPath,
+  type SpaceRef,
+} from './space';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// THE Space URI grammar. ONE grammar, platform-wide.
 //
 //   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>
+//   xema://users/<userId>
+//   xema://biomes/<biomeId>
+//   xema://sessions/<sessionId>
+//   xema://orgs/<orgId>
+//   xema://orgs/<orgId>/projects/<projectId>
+//   xema://orgs/<orgId>/projects/<projectId>/apps/<appId>
+//
+// Historical note (X9 convergence): this module used to implement a SECOND,
+// incompatible grammar — singular `org`/`project`/`app` key/id pairs that
+// additionally NESTED session and biome under app
+// (`xema://org/a/project/p/app/x/session/y`). It disagreed with
+// `spaceRefToPath` (the plural form that `XemaObjectRef`, search refs and the
+// object-registry projection all use) for the Biome, Session and User tiers,
+// so `formatSpaceRef` and `spaceRefToPath` were not inverses and a ref could
+// not survive a round trip through both. The singular grammar LOST and was
+// deleted outright — no shim, no dual-read. Reasons, in order of weight:
 //
-// 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.
+//   1. `REQUIRED_SEGMENTS` in `./space` already declares Session/Biome/User as
+//      root-addressable (they require ONLY their own id). The singular parser
+//      contradicted the kernel's own SpaceRef schema.
+//   2. Every real producer of a Biome- or Session-scoped ref in the platform
+//      (skill-registry, llm-registry, artifact-store, workflow-engine, xvfs)
+//      constructs `{ tier, biomeId }` / `{ tier, sessionId }` with no org,
+//      project or app. `formatSpaceRef` THREW on all of them.
+//   3. The plural grammar was already the persisted/wire form for object refs,
+//      search refs and XVFS scope paths; only Space rows used the singular one.
+//
+// `parse` and `format` here are exact inverses over canonical inputs, and
+// `formatSpaceRef` is defined as `xema://` + `spaceRefToPath`, so the two
+// renderers cannot drift again.
+// ═══════════════════════════════════════════════════════════════════════════
 
 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];
+/** Plural scope heads the grammar admits. Closed set. */
+enum SpaceRefScopeHead {
+  System = 'system',
+  Users = 'users',
+  Biomes = 'biomes',
+  Sessions = 'sessions',
+  Orgs = 'orgs',
+  Projects = 'projects',
+  Apps = 'apps',
+}
 
-const SEGMENT_KEY_SET: ReadonlySet<string> = new Set(SEGMENT_KEYS);
+const SPACE_REF_SCOPE_HEADS: readonly string[] =
+  Object.values(SpaceRefScopeHead);
 
-// 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,
-};
+export { SpaceRefParseError };
 
-// 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',
-};
+/** Result of consuming the leading scope segments of a `xema://` path. */
+export interface SpaceRefScopeParse {
+  scope: SpaceRef;
+  consumed: number;
+}
+
+function requireSegment(
+  segments: readonly string[],
+  index: number,
+  raw: string,
+  label: string,
+): string {
+  const value = segments[index];
+  if (value === undefined || value.length === 0) {
+    throw new SpaceRefParseError(
+      `SpaceRef URI is missing the "${label}" segment.`,
+      raw,
+    );
+  }
+  return value;
+}
 
-// 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,
-};
+function takeId(
+  segments: readonly string[],
+  index: number,
+  raw: string,
+  field: keyof SpaceRef,
+): string {
+  const value = requireSegment(segments, index, raw, String(field));
+  assertValidSpaceSegmentId(field, value, raw);
+  return value;
+}
 
-export class SpaceRefParseError extends Error {
-  readonly raw: string;
-  constructor(message: string, raw: string) {
-    super(message);
-    this.name = 'SpaceRefParseError';
-    this.raw = raw;
+/**
+ * Consume the LEADING scope segments of a `xema://` path body and return the
+ * {@link SpaceRef} they denote plus how many segments were eaten. Shared by
+ * {@link parseSpaceRef} (which additionally requires the scope to consume the
+ * WHOLE body), `parseXemaObjectRef` (which owns the trailing `<kind>/<slug>`)
+ * and `parseSearchRef` (which owns the trailing `<docType>/<sourceId>`), so
+ * the scope grammar lives in exactly ONE place.
+ */
+export function parseSpaceRefScopeSegments(
+  segments: readonly string[],
+  raw: string,
+): SpaceRefScopeParse {
+  const head = requireSegment(segments, 0, raw, 'scope');
+  switch (head) {
+    case SpaceRefScopeHead.System:
+      return { scope: { tier: SpaceKind.System }, consumed: 1 };
+    case SpaceRefScopeHead.Biomes:
+      return {
+        scope: {
+          tier: SpaceKind.Biome,
+          biomeId: takeId(segments, 1, raw, 'biomeId'),
+        },
+        consumed: 2,
+      };
+    case SpaceRefScopeHead.Users:
+      return {
+        scope: {
+          tier: SpaceKind.User,
+          userId: takeId(segments, 1, raw, 'userId'),
+        },
+        consumed: 2,
+      };
+    case SpaceRefScopeHead.Sessions:
+      return {
+        scope: {
+          tier: SpaceKind.Session,
+          sessionId: takeId(segments, 1, raw, 'sessionId'),
+        },
+        consumed: 2,
+      };
+    case SpaceRefScopeHead.Orgs: {
+      const orgId = takeId(segments, 1, raw, 'orgId');
+      if (segments.length >= 4 && segments[2] === SpaceRefScopeHead.Projects) {
+        const projectId = takeId(segments, 3, raw, 'projectId');
+        // …/projects/<p>/apps/<a> — the App tier (most specific under a project).
+        if (segments.length >= 6 && segments[4] === SpaceRefScopeHead.Apps) {
+          return {
+            scope: {
+              tier: SpaceKind.App,
+              orgId,
+              projectId,
+              appId: takeId(segments, 5, raw, 'appId'),
+            },
+            consumed: 6,
+          };
+        }
+        return {
+          scope: { tier: SpaceKind.Project, orgId, projectId },
+          consumed: 4,
+        };
+      }
+      return { scope: { tier: SpaceKind.Org, orgId }, consumed: 2 };
+    }
+    default:
+      throw new SpaceRefParseError(
+        `SpaceRef URI has unknown scope head "${head}". Allowed: ${SPACE_REF_SCOPE_HEADS.join(', ')}.`,
+        raw,
+      );
   }
 }
 
+/**
+ * Parse a full `xema://…` Space URI. Unlike
+ * {@link parseSpaceRefScopeSegments}, the scope MUST consume the entire body —
+ * a trailing `<kind>/<slug>` makes it an object ref, not a Space ref, and is a
+ * fail-fast error here rather than a silently-ignored suffix.
+ *
+ * The returned ref carries `path` set to the CANONICAL rendering, so
+ * `formatSpaceRef(parseSpaceRef(uri)) === uri` for every canonical `uri`.
+ */
 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));
+    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);
+    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).`,
+      'SpaceRef URI has empty body after scheme.',
       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;
+  const segments = body.split('/');
+  if (segments.some((segment) => segment.length === 0)) {
+    throw new SpaceRefParseError(
+      'SpaceRef URI has an empty path segment (leading, trailing or doubled "/").',
+      uri,
+    );
   }
 
-  if (lastSegment === null) {
-    throw new SpaceRefParseError('SpaceRef URI parsed no segments.', uri);
+  const { scope, consumed } = parseSpaceRefScopeSegments(segments, uri);
+  if (consumed !== segments.length) {
+    throw new SpaceRefParseError(
+      `SpaceRef URI has ${segments.length - consumed} trailing segment(s) after the scope — a Space ref addresses a Space, not an object inside it.`,
+      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;
+  scope.path = formatSpaceRef(scope);
+  return scope;
 }
 
+/**
+ * Render a `SpaceRef` as its canonical `xema://…` URI. Defined as the scheme
+ * plus {@link spaceRefToPath}, so the URI form and the XVFS path form can
+ * never disagree again. Fails fast on a missing or malformed segment.
+ */
 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('');
+  return `${SCHEME}${spaceRefToPath(ref).slice(1)}`;
 }

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

@@ -1,13 +1,28 @@
 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".
+// Closest-first ancestor walk. The chain MUST agree with the URI grammar in
+// `./space-ref-parser` — an ancestor is exactly "this ref with its deepest
+// segment stripped", so the walk is the structural reading of the same
+// canonical path:
 //
-// Implementation: derive each ancestor by stripping the deepest segment.
-// We rebuild via formatSpaceRef so the returned `path` is always canonical.
+//   /orgs/a/projects/p/apps/x  →  [App, Project, Org, System]
+//   /orgs/a/projects/p         →  [Project, Org, System]
+//   /sessions/s                →  [Session, System]
+//   /biomes/b                  →  [Biome, System]
+//   /users/u                   →  [User, System]
+//
+// Session, Biome and User are ROOTS (parent = System). Before the X9
+// convergence this file nested Session and Biome under App while the path
+// renderer emitted them at the root, so `walkAncestors` THREW for every
+// Biome-scoped ref the platform actually produces (`{ tier: Biome, biomeId }`
+// carries no appId, and rendering the synthesised App parent failed). Keeping
+// the hierarchy and the grammar in lockstep is what makes `parentOf` total.
+//
+// Used by policy resolution ("most-specific match wins"), by
+// space-registry-api to pin `Space.parentId` from `walkAncestors(ref)[1]`, and
+// by capability-registry-api's `SPACE_KIND_PARENT` derivation — all three read
+// the hierarchy from HERE and never restate it.
 export function walkAncestors(ref: SpaceRef): SpaceRef[] {
   const out: SpaceRef[] = [];
   let current: SpaceRef | null = ref;
@@ -18,13 +33,22 @@ export function walkAncestors(ref: SpaceRef): SpaceRef[] {
   return out;
 }
 
+function systemParent(): SpaceRef {
+  return {
+    tier: SpaceKind.System,
+    path: formatSpaceRef({ tier: SpaceKind.System }),
+  };
+}
+
 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.Session:
+    case SpaceKind.Biome:
+      return systemParent();
     case SpaceKind.Project: {
       const parent: SpaceRef = { tier: SpaceKind.Org };
       if (ref.orgId !== undefined) parent.orgId = ref.orgId;
@@ -38,18 +62,11 @@ function parentOf(ref: SpaceRef): SpaceRef | null {
       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)}".`);
+      throw new Error(
+        `walkAncestors: unhandled SpaceKind "${String(exhaustive)}".`,
+      );
     }
   }
 }

package/src/space/lib/space.ts

@@ -148,48 +148,123 @@ const REQUIRED_SEGMENTS: Readonly<Record<SpaceKind, readonly SegmentKey[]>> = {
 };
 
 /**
- * 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.
+ * Structured, fail-fast error raised by every Space-ref grammar operation
+ * ({@link spaceRefToPath}, `parseSpaceRef`, `formatSpaceRef`). Carries a
+ * stable `code` so services can map it to a typed 400 without string-matching
+ * the message.
+ */
+export class SpaceRefParseError extends Error {
+  public readonly code = 'SPACE_REF_INVALID';
+  public readonly raw: string;
+
+  public constructor(message: string, raw: string) {
+    super(message);
+    this.name = 'SpaceRefParseError';
+    this.raw = raw;
+  }
+}
+
+/**
+ * A single Space path segment id (an orgId, projectId, appId, sessionId,
+ * biomeId or userId). Deliberately value-identical to the `XemaObjectRef`
+ * slug-segment pattern so a Space path and an object ref agree on what a
+ * legal segment is: starts alphanumeric, then alphanumerics plus `_`, `.`,
+ * `-`. No `/`, no whitespace, no `@` — those are grammar separators and
+ * would make the ref ambiguous.
+ */
+export const SPACE_SEGMENT_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
+
+/**
+ * Fail-fast guard for a Space path segment id. Enforced by BOTH the renderer
+ * ({@link spaceRefToPath}) and the parser, which is what makes parse/format
+ * exact inverses: a ref that cannot be rendered can never be produced, and a
+ * string that cannot be parsed can never be rendered.
+ */
+export function assertValidSpaceSegmentId(
+  segment: keyof SpaceRef,
+  value: string,
+  raw: string,
+): void {
+  if (!SPACE_SEGMENT_ID_PATTERN.test(value)) {
+    throw new SpaceRefParseError(
+      `Space segment "${String(segment)}" id "${value}" must match ${SPACE_SEGMENT_ID_PATTERN}.`,
+      raw,
+    );
+  }
+}
+
+function requireSpaceSegment(
+  ref: SpaceRef,
+  segment: SegmentKey,
+  raw: string,
+): string {
+  const value = ref[segment];
+  if (value === undefined || value.length === 0) {
+    throw new SpaceRefParseError(
+      `SpaceKind.${ref.tier} requires "${segment}".`,
+      raw,
+    );
+  }
+  assertValidSpaceSegmentId(segment, value, raw);
+  return value;
+}
+
+/**
+ * Render a `SpaceRef` as its canonical XVFS path prefix. Returns a string
+ * that starts with `/`. Fails fast if a required segment is missing or its id
+ * violates {@link SPACE_SEGMENT_ID_PATTERN}.
+ *
+ * This is the SINGLE canonical Space grammar — the plural-head form shared by
+ * `XemaObjectRef`, search refs, the object-registry projection and (since the
+ * X9 convergence) `formatSpaceRef`/`parseSpaceRef`:
+ *
+ * ```
+ *   /system
+ *   /users/<userId>
+ *   /biomes/<biomeId>
+ *   /sessions/<sessionId>
+ *   /orgs/<orgId>
+ *   /orgs/<orgId>/projects/<projectId>
+ *   /orgs/<orgId>/projects/<projectId>/apps/<appId>
+ * ```
+ *
+ * `User`, `Biome` and `Session` are ROOT-addressable on purpose — that is
+ * exactly what {@link REQUIRED_SEGMENTS} already declares (they require only
+ * their own id), and it is what every real producer emits: a biome-contributed
+ * skill lives at `xema://biomes/<id>/skill/<slug>` and is org-less. A ref's
+ * ancestor segments are NOT part of its identity for those tiers.
  */
 export function spaceRefToPath(ref: SpaceRef): string {
+  const raw = ref.path ?? `<SpaceKind.${ref.tier}>`;
   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}`;
+      return `/biomes/${requireSpaceSegment(ref, 'biomeId', raw)}`;
     case SpaceKind.User:
-      if (!ref.userId) {
-        throw new Error('spaceRefToPath: SpaceKind.User requires userId');
-      }
-      return `/users/${ref.userId}`;
+      return `/users/${requireSpaceSegment(ref, 'userId', raw)}`;
+    case SpaceKind.Session:
+      return `/sessions/${requireSpaceSegment(ref, 'sessionId', raw)}`;
+    case SpaceKind.Org:
+      return `/orgs/${requireSpaceSegment(ref, 'orgId', raw)}`;
+    case SpaceKind.Project: {
+      const orgId = requireSpaceSegment(ref, 'orgId', raw);
+      const projectId = requireSpaceSegment(ref, 'projectId', raw);
+      return `/orgs/${orgId}/projects/${projectId}`;
+    }
+    case SpaceKind.App: {
+      const orgId = requireSpaceSegment(ref, 'orgId', raw);
+      const projectId = requireSpaceSegment(ref, 'projectId', raw);
+      const appId = requireSpaceSegment(ref, 'appId', raw);
+      return `/orgs/${orgId}/projects/${projectId}/apps/${appId}`;
+    }
+    default: {
+      const exhaustive: never = ref.tier;
+      throw new SpaceRefParseError(
+        `spaceRefToPath: unhandled SpaceKind "${String(exhaustive)}".`,
+        raw,
+      );
+    }
   }
 }
 

package/src/subject/lib/subject.ts

@@ -45,11 +45,27 @@ export const SubjectKindSchema = z.nativeEnum(SubjectKind);
 export interface ActingForRef {
   kind: SubjectKind;
   id: string;
+  /**
+   * The ISSUER-STAMPED OAuth client identity of this hop (`azp`, else
+   * `client_id`), when the issuer stamps it inside the hop's `act` object.
+   *
+   * `id` is the hop's `sub` — for a service-account token that is an opaque
+   * Keycloak UUID, which says nothing about WHICH service conveyed the call.
+   * The client id is the logical service name (`workflow-runtime-worker`,
+   * `agent-session-api`, …) that grants and audit trails are keyed by. It is
+   * never caller-supplied: an OAuth client cannot assert another client's id
+   * in a token the issuer signed.
+   *
+   * Absent when the issuer stamps neither claim on the hop — treat absence as
+   * "unknown", never as a match.
+   */
+  clientId?: string;
 }
 
 export const ActingForRefSchema = z.object({
   kind: SubjectKindSchema,
   id: z.string().min(1),
+  clientId: z.string().min(1).optional(),
 }) as z.ZodType<ActingForRef>;
 
 /**

package/src/surface/index.ts

@@ -0,0 +1,3 @@
+export * from './lib/surface-kind';
+export * from './lib/vista-surface';
+export * from './lib/surface-contribution';