@xemahq/kernel-contracts 0.50.0 → 0.57.0

package/src/search-source/lib/search-ref.ts

@@ -1,8 +1,11 @@
+import { type XemaObjectRef } from '../../object';
 import {
-  parseObjectRefScopeSegments,
-  type XemaObjectRef,
-} from '../../object';
-import { SpaceKind, spaceRefToPath, type SpaceRef } from '../../space';
+  parseSpaceRefScopeSegments,
+  SpaceKind,
+  SpaceRefParseError,
+  spaceRefToPath,
+  type SpaceRef,
+} from '../../space';
 
 /**
  * The natural-key / address grammar for a searchable document:
@@ -15,9 +18,10 @@ import { SpaceKind, spaceRefToPath, type SpaceRef } from '../../space';
  * the type discriminator is `docType` (biome-owned, open), so a searchable
  * document (an email, a design-idea, a backlog item) can be addressed WITHOUT a
  * kernel object kind. The scope grammar itself is shared: this helper reuses
- * {@link parseObjectRefScopeSegments} + {@link spaceRefToPath} so the
- * `<scope-path>` portion stays value-identical to `XemaObjectRef`, and object-
- * model ref validation is untouched for object-model callers.
+ * {@link parseSpaceRefScopeSegments} + {@link spaceRefToPath} so the
+ * `<scope-path>` portion stays value-identical to `XemaObjectRef` and to a
+ * Space ref, and object-model ref validation is untouched for object-model
+ * callers.
  *
  * `docType` occupies the segment where an object ref carries `<kind>`; it is a
  * lowercase, slash-free facet slug (e.g. `kb_page`, `email_thread`). `sourceId`
@@ -96,7 +100,7 @@ export function formatSearchRef(
 /**
  * Parse a search ref back into `{ scope, docType, sourceId }`. Fail-fast on
  * every malformed input. The scope grammar is validated by the shared
- * {@link parseObjectRefScopeSegments}; the trailing two segments are the
+ * {@link parseSpaceRefScopeSegments}; the trailing two segments are the
  * `docType` and the (slash-free) `sourceId`.
  */
 export function parseSearchRef(ref: string): SearchRefParts {
@@ -115,7 +119,16 @@ export function parseSearchRef(ref: string): SearchRefParts {
     );
   }
 
-  const { scope, consumed } = parseObjectRefScopeSegments(segments, ref);
+  let scope: SpaceRef;
+  let consumed: number;
+  try {
+    ({ scope, consumed } = parseSpaceRefScopeSegments(segments, ref));
+  } catch (err) {
+    if (err instanceof SpaceRefParseError) {
+      throw new SearchRefParseError(ref, err.message);
+    }
+    throw err;
+  }
   const remaining = segments.slice(consumed);
   if (remaining.length !== 2) {
     throw new SearchRefParseError(

package/src/service-registry/lib/service-descriptor.ts

@@ -61,6 +61,11 @@ export interface ServiceEndpoint {
  *   resolved and must not register.
  * - `exposesCapabilities` / `requiresServices` carry only canonical
  *   refs / service names — no env-var URLs.
+ * - `openapiUrl`, when present, is ABSOLUTE and points at the service's
+ *   PUBLIC-surface OpenAPI document. It is declared, never derived by
+ *   convention: a consumer must not guess `<endpoint>/api/openapi.json`,
+ *   because that path serves the merged public+internal+operator document and
+ *   because a service may mount its docs elsewhere or not at all.
  */
 export interface ServiceDescriptor {
   name: string;
@@ -70,6 +75,17 @@ export interface ServiceDescriptor {
   exposesCapabilities: string[];
   requiresServices: string[];
   healthEndpoint?: string;
+  /**
+   * Absolute URL of the service's PUBLIC-surface OpenAPI document (the same
+   * subset shipped as the `openapi.public.json` build artifact).
+   *
+   * Optional because a service MAY serve no spec — Swagger can be disabled per
+   * deployment, and a non-HTTP service has none at all. Absent means exactly
+   * "this instance advertises no machine-readable API description"; consumers
+   * MUST treat absence as a hard skip and never fall back to a conventional
+   * path.
+   */
+  openapiUrl?: string;
   region?: string;
   labels?: Record<string, string>;
 }

package/src/space/lib/skill-mirror-path.ts

@@ -34,7 +34,7 @@ const SKILL_KIND_SEGMENT = 'skill';
  *       the org's own RO mount; another org's worker never mounts it.
  *
  * Returns `null` when the scope is not mirrorable from the ref alone:
- *   • User   — the ref is org-less (`xema://user/<userId>`), so it can't be
+ *   • User   — the ref is org-less (`xema://users/<userId>`), so it can't be
  *              placed under any org's templates subtree.
  *   • App / Session — runtime spaces, never own a skill bundle.
  *   • a mirrorable tier whose required id segment is absent (malformed ref).

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)}".`,
+      );
     }
   }
 }