@xemahq/kernel-contracts 0.50.0 → 0.56.0

package/src/search/lib/route-template.ts

@@ -0,0 +1,381 @@
+/**
+ * `routeTemplate` — the deep-link grammar a search RESULT-TYPE contributes so a
+ * hit can be turned into a concrete frontend URL WITHOUT any consumer
+ * hardcoding a per-kind switch.
+ *
+ * A template is a path pattern such as
+ * `/spaces/projects/{projectId}/design-system-builder/{sourceId}`. The
+ * placeholder vocabulary is a CLOSED set ({@link SearchRouteTemplateVariable})
+ * — exactly the fields a caller is guaranteed to hold for a search hit or an
+ * object ref. Anything outside that set is a contribution bug, rejected at
+ * parse time rather than discovered as a broken link in production.
+ *
+ * Everything here is fail-fast: an unknown placeholder, a malformed template,
+ * or a placeholder with no value at expansion time throws
+ * {@link SearchRouteTemplateError}. Expansion NEVER leaves a `{x}` in the
+ * output and NEVER silently drops a segment — a half-substituted URL is worse
+ * than no URL, because it looks clickable.
+ */
+
+/**
+ * The closed set of placeholders a `routeTemplate` may reference.
+ *
+ * Every member has exactly ONE documented supply route — see
+ * {@link SEARCH_ROUTE_TEMPLATE_VARIABLE_SOURCE}:
+ *
+ * | Variable        | Source       | Search hit                              | Object ref                     |
+ * | --------------- | ------------ | --------------------------------------- | ------------------------------ |
+ * | `orgId`         | `scope`      | the hit's tenant org                    | the ref's scope org            |
+ * | `projectId`     | `scope`      | the hit's project (org-wide ⇒ n/a)      | the ref's scope project        |
+ * | `docType`       | `identity`   | the hit's open, biome-owned facet       | n/a (object refs carry a kind) |
+ * | `objectKind`    | `identity`   | the registered result-type's kind       | the ref's `XemaObjectKind`     |
+ * | `sourceId`      | `identity`   | the source's stable entity id           | n/a                            |
+ * | `title`         | `identity`   | the hit's title                         | n/a                            |
+ * | `slug`          | `projected`  | `IndexableDocument.routeParams.slug`    | the ref's slug segment         |
+ * | `containerSlug` | `projected`  | `IndexableDocument.routeParams.containerSlug` | n/a                      |
+ *
+ * `scope`/`identity` variables are derived by the PLATFORM from the hit or ref
+ * itself — always available, never declared. `projected` variables can only
+ * come from the owning source, so a result-type that references one MUST
+ * declare it in `renderHints.routeParams`; a template referencing an
+ * undeclared projected variable is rejected at contribution-parse time
+ * (see `assertSearchRouteTemplateSatisfiable`). That is what keeps a
+ * slug-based route from silently becoming a dead link.
+ *
+ * A template referencing a variable the caller cannot supply at EXPANSION time
+ * still simply does not expand for that caller (fail-fast, no URL) — a
+ * result-type may legitimately declare a route only the object-ref caller can
+ * resolve.
+ *
+ * Adding a member is a deliberate kernel change: it must be classified in
+ * {@link SEARCH_ROUTE_TEMPLATE_VARIABLE_SOURCE}, and every consumer that
+ * expands a template must be able to supply the new value.
+ */
+export enum SearchRouteTemplateVariable {
+  /** Owning organization id. */
+  OrgId = 'orgId',
+  /** Owning project id. Absent for org-wide documents. */
+  ProjectId = 'projectId',
+  /** The open, biome-contributed doc-type facet. */
+  DocType = 'docType',
+  /** The `XemaObjectKind` the result-type covers. */
+  ObjectKind = 'objectKind',
+  /** The source's stable per-entity id (what a search ref addresses). */
+  SourceId = 'sourceId',
+  /**
+   * The instance's own URL slug — the human-readable, route-bearing key a
+   * slug-addressed frontend uses instead of an opaque id. Projected by the
+   * producer onto `IndexableDocument.routeParams.slug`; an object ref supplies
+   * it intrinsically from its slug segment.
+   */
+  Slug = 'slug',
+  /** The instance's human title. */
+  Title = 'title',
+  /**
+   * The slug of the instance's IMMEDIATE container — the collection a
+   * slug-addressed route nests the instance under (a knowledge-base space, a
+   * folder, a collection). Kernel-neutral on purpose: it is NOT the Xema
+   * `SpaceRef` tier (that is `orgId`/`projectId`), it is the domain container
+   * whose slug occupies a route segment. Projected by the producer onto
+   * `IndexableDocument.routeParams.containerSlug`; an object ref cannot supply
+   * it, so a container-nested template resolves for hits only.
+   */
+  ContainerSlug = 'containerSlug',
+}
+
+/**
+ * Where the value of a {@link SearchRouteTemplateVariable} comes from. Closed
+ * set — the classification is what makes "can this contribution actually supply
+ * this placeholder?" a decidable, parse-time question.
+ */
+export enum SearchRouteVariableSource {
+  /** Derived by the platform from the result's `SpaceRef` scope. */
+  Scope = 'scope',
+  /** Carried by the result's own identity (hit fields / ref segments). */
+  Identity = 'identity',
+  /**
+   * Projected by the OWNING SOURCE — the producer stamps it on
+   * `IndexableDocument.routeParams` (and/or an object ref carries it). The
+   * platform cannot derive it, so a result-type must DECLARE it in
+   * `renderHints.routeParams` before a template may reference it.
+   */
+  Projected = 'projected',
+}
+
+/**
+ * The single source-of-truth classification of every placeholder. Frozen: a
+ * consumer must not be able to reclassify a variable at runtime.
+ */
+export const SEARCH_ROUTE_TEMPLATE_VARIABLE_SOURCE: Readonly<
+  Record<SearchRouteTemplateVariable, SearchRouteVariableSource>
+> = Object.freeze({
+  [SearchRouteTemplateVariable.OrgId]: SearchRouteVariableSource.Scope,
+  [SearchRouteTemplateVariable.ProjectId]: SearchRouteVariableSource.Scope,
+  [SearchRouteTemplateVariable.DocType]: SearchRouteVariableSource.Identity,
+  [SearchRouteTemplateVariable.ObjectKind]: SearchRouteVariableSource.Identity,
+  [SearchRouteTemplateVariable.SourceId]: SearchRouteVariableSource.Identity,
+  [SearchRouteTemplateVariable.Title]: SearchRouteVariableSource.Identity,
+  [SearchRouteTemplateVariable.Slug]: SearchRouteVariableSource.Projected,
+  [SearchRouteTemplateVariable.ContainerSlug]:
+    SearchRouteVariableSource.Projected,
+});
+
+/**
+ * The placeholders a result-type must DECLARE (`renderHints.routeParams`) and a
+ * producer must STAMP (`IndexableDocument.routeParams`) before a template may
+ * reference them. Derived from {@link SEARCH_ROUTE_TEMPLATE_VARIABLE_SOURCE} so
+ * the two can never drift.
+ */
+export const SEARCH_ROUTE_PROJECTED_VARIABLES: ReadonlySet<SearchRouteTemplateVariable> =
+  new Set(
+    (
+      Object.values(SearchRouteTemplateVariable) as SearchRouteTemplateVariable[]
+    ).filter(
+      (variable) =>
+        SEARCH_ROUTE_TEMPLATE_VARIABLE_SOURCE[variable] ===
+        SearchRouteVariableSource.Projected,
+    ),
+  );
+
+/** Whether a placeholder must be projected by the owning source. */
+export function isProjectedSearchRouteVariable(
+  variable: SearchRouteTemplateVariable,
+): boolean {
+  return SEARCH_ROUTE_PROJECTED_VARIABLES.has(variable);
+}
+
+/**
+ * Every legal placeholder name, as a lookup set. Frozen so a consumer cannot
+ * widen the vocabulary at runtime.
+ */
+export const SEARCH_ROUTE_TEMPLATE_VARIABLES: ReadonlySet<string> = new Set(
+  Object.values(SearchRouteTemplateVariable),
+);
+
+/**
+ * Matches one `{placeholder}` occurrence. Deliberately permissive about the
+ * NAME (`[A-Za-z0-9_]+`) so an unknown-but-well-formed placeholder is reported
+ * as "unknown variable" rather than "malformed template" — the actionable
+ * message is the whole point.
+ *
+ * Global flag: callers must not rely on `lastIndex` (use `matchAll`, or reset).
+ */
+export const SEARCH_ROUTE_TEMPLATE_PLACEHOLDER_PATTERN = /\{([A-Za-z0-9_]+)\}/g;
+
+/**
+ * Structured error raised by every function in this module. Carries a stable
+ * `code` so HTTP edges can map it to a typed response instead of a 500.
+ */
+export class SearchRouteTemplateError extends Error {
+  public readonly code = 'SEARCH_ROUTE_TEMPLATE_INVALID';
+  public readonly template: string;
+  public readonly reason: string;
+
+  public constructor(template: string, reason: string) {
+    super(`Invalid search route template "${template}": ${reason}`);
+    this.name = 'SearchRouteTemplateError';
+    this.template = template;
+    this.reason = reason;
+  }
+}
+
+function allowedVariableList(): string {
+  return [...SEARCH_ROUTE_TEMPLATE_VARIABLES].sort().join(', ');
+}
+
+/**
+ * Assert a `routeTemplate` is well-formed. A template MUST:
+ *
+ *  - be non-empty and start with `/` (it is a site-relative path, never an
+ *    absolute URL and never a relative fragment);
+ *  - contain no whitespace;
+ *  - contain no empty path segment (`//`);
+ *  - use only well-formed `{name}` placeholders whose `name` is a
+ *    {@link SearchRouteTemplateVariable}.
+ *
+ * Throws {@link SearchRouteTemplateError} on the first violation. Never
+ * "repairs" a template.
+ */
+export function assertValidSearchRouteTemplate(template: string): void {
+  if (template.length === 0) {
+    throw new SearchRouteTemplateError(template, 'must be non-empty');
+  }
+  if (!template.startsWith('/')) {
+    throw new SearchRouteTemplateError(
+      template,
+      'must be a site-relative path starting with "/"',
+    );
+  }
+  if (/\s/.test(template)) {
+    throw new SearchRouteTemplateError(template, 'must not contain whitespace');
+  }
+  if (template.includes('//')) {
+    throw new SearchRouteTemplateError(
+      template,
+      'must not contain an empty path segment ("//")',
+    );
+  }
+
+  // Strip well-formed placeholders; any residual brace is a malformed one.
+  const residue = template.replace(
+    SEARCH_ROUTE_TEMPLATE_PLACEHOLDER_PATTERN,
+    '',
+  );
+  if (residue.includes('{') || residue.includes('}')) {
+    throw new SearchRouteTemplateError(
+      template,
+      'contains a malformed placeholder — every placeholder must be "{name}" with name matching [A-Za-z0-9_]+',
+    );
+  }
+
+  for (const name of readTemplateVariableNames(template)) {
+    if (!SEARCH_ROUTE_TEMPLATE_VARIABLES.has(name)) {
+      throw new SearchRouteTemplateError(
+        template,
+        `unknown placeholder "{${name}}" — allowed placeholders are: ${allowedVariableList()}`,
+      );
+    }
+  }
+}
+
+/**
+ * Assert a `routeTemplate` can ACTUALLY be expanded by the result-type that
+ * declares it — the second half of contribution-parse-time validation.
+ *
+ * {@link assertValidSearchRouteTemplate} answers "is this placeholder in the
+ * closed vocabulary?"; this answers "can this contribution supply it?". Every
+ * {@link SearchRouteVariableSource.Projected} placeholder a template references
+ * MUST appear in `provided` (the contribution's `renderHints.routeParams`,
+ * i.e. what the producer stamps on `IndexableDocument.routeParams`).
+ * `scope`/`identity` placeholders are derived by the platform and are never
+ * declared.
+ *
+ * Also rejects a DEAD declaration — a `provided` entry the template never
+ * references — because an unused supply promise is a contribution bug that
+ * silently misleads the next reader.
+ *
+ * Throws {@link SearchRouteTemplateError} on the first violation.
+ */
+export function assertSearchRouteTemplateSatisfiable(
+  template: string,
+  provided: readonly SearchRouteTemplateVariable[],
+): void {
+  assertValidSearchRouteTemplate(template);
+
+  const declared = new Set<SearchRouteTemplateVariable>();
+  for (const variable of provided) {
+    if (!SEARCH_ROUTE_TEMPLATE_VARIABLES.has(variable)) {
+      throw new SearchRouteTemplateError(
+        template,
+        `declared route param "${String(variable)}" is not a search route variable — ` +
+          `allowed variables are: ${allowedVariableList()}`,
+      );
+    }
+    if (!isProjectedSearchRouteVariable(variable)) {
+      throw new SearchRouteTemplateError(
+        template,
+        `route param "${variable}" must not be declared — it is supplied by the platform ` +
+          `(source "${SEARCH_ROUTE_TEMPLATE_VARIABLE_SOURCE[variable]}"), not by the producer. ` +
+          `Only ${projectedVariableList()} may be declared.`,
+      );
+    }
+    if (declared.has(variable)) {
+      throw new SearchRouteTemplateError(
+        template,
+        `route param "${variable}" is declared more than once`,
+      );
+    }
+    declared.add(variable);
+  }
+
+  const referenced = new Set(
+    readTemplateVariableNames(template) as SearchRouteTemplateVariable[],
+  );
+
+  for (const variable of referenced) {
+    if (isProjectedSearchRouteVariable(variable) && !declared.has(variable)) {
+      throw new SearchRouteTemplateError(
+        template,
+        `placeholder "{${variable}}" is projected by the owning source, but this result-type ` +
+          `does not declare it in renderHints.routeParams — the template could never expand. ` +
+          `Either declare it (and stamp it on IndexableDocument.routeParams) or drop it from the template.`,
+      );
+    }
+  }
+
+  for (const variable of declared) {
+    if (!referenced.has(variable)) {
+      throw new SearchRouteTemplateError(
+        template,
+        `route param "${variable}" is declared but never referenced by the template — ` +
+          'remove the dead declaration',
+      );
+    }
+  }
+}
+
+function projectedVariableList(): string {
+  return [...SEARCH_ROUTE_PROJECTED_VARIABLES].sort().join(', ');
+}
+
+/** Raw placeholder names, in order of first appearance, duplicates removed. */
+function readTemplateVariableNames(template: string): string[] {
+  const seen = new Set<string>();
+  for (const match of template.matchAll(
+    SEARCH_ROUTE_TEMPLATE_PLACEHOLDER_PATTERN,
+  )) {
+    const name = match[1];
+    if (name !== undefined) {
+      seen.add(name);
+    }
+  }
+  return [...seen];
+}
+
+/**
+ * The distinct {@link SearchRouteTemplateVariable}s a template references, in
+ * order of first appearance. Validates first, so the result is always a
+ * well-typed subset of the closed vocabulary — consumers use this to decide
+ * whether they can supply everything a template needs BEFORE attempting an
+ * expansion.
+ */
+export function extractSearchRouteTemplateVariables(
+  template: string,
+): SearchRouteTemplateVariable[] {
+  assertValidSearchRouteTemplate(template);
+  return readTemplateVariableNames(template) as SearchRouteTemplateVariable[];
+}
+
+/**
+ * Expand a `routeTemplate` into a concrete site-relative URL.
+ *
+ * Validates the template first, then substitutes every placeholder. Each
+ * substituted value is `encodeURIComponent`-escaped because it occupies a
+ * single path segment — a value containing `/`, `?`, `#` or a space must not
+ * be able to change the shape of the resulting path.
+ *
+ * Fail-fast: a placeholder whose value is missing, `undefined`, or the empty
+ * string throws {@link SearchRouteTemplateError}. There is no partial
+ * expansion and no silent drop.
+ */
+export function expandSearchRouteTemplate(
+  template: string,
+  values: Readonly<Partial<Record<SearchRouteTemplateVariable, string>>>,
+): string {
+  assertValidSearchRouteTemplate(template);
+
+  return template.replace(
+    SEARCH_ROUTE_TEMPLATE_PLACEHOLDER_PATTERN,
+    (_match, rawName: string) => {
+      const name = rawName as SearchRouteTemplateVariable;
+      const value = values[name];
+      if (value === undefined || value.length === 0) {
+        throw new SearchRouteTemplateError(
+          template,
+          `no value supplied for placeholder "{${name}}" — the template cannot be expanded in this context`,
+        );
+      }
+      return encodeURIComponent(value);
+    },
+  );
+}

package/src/search/lib/search-contribution.ts

@@ -6,6 +6,12 @@ import {
   ResourceVisibilityPattern,
   ResourceVisibilityPatternSchema,
 } from '../../resource';
+import {
+  SEARCH_ROUTE_PROJECTED_VARIABLES,
+  SearchRouteTemplateError,
+  SearchRouteTemplateVariable,
+  assertSearchRouteTemplateSatisfiable,
+} from './route-template';
 
 /**
  * Maximum length of the short identifier / label strings on a search-type
@@ -41,22 +47,89 @@ export interface SearchTypeRenderHints {
   readonly icon?: string;
   /**
    * Optional deep-link route template with `{placeholder}` segments the
-   * frontend fills from a result's fields (e.g. `/kb/{orgId}/pages/{slug}`).
-   * ≤ 500 chars. Absent ⇒ the result is not directly deep-linkable.
+   * consumer fills from a result's fields (e.g.
+   * `/spaces/projects/{projectId}/documents/{containerSlug}/{slug}`). ≤ 500
+   * chars. Absent ⇒ the result is not directly deep-linkable.
+   *
+   * The placeholder vocabulary is the CLOSED
+   * {@link SearchRouteTemplateVariable} set and the syntax + SATISFIABILITY are
+   * validated by {@link assertSearchRouteTemplateSatisfiable} — a malformed
+   * template, an unknown placeholder, or a projected placeholder this
+   * result-type does not declare in {@link routeParams} is rejected at
+   * contribution-parse time AND at the owning service's wire, never discovered
+   * as a broken link. Expand with `expandSearchRouteTemplate`.
    */
   readonly routeTemplate?: string;
+  /**
+   * The PROJECTED route variables this result-type supplies — the ones the
+   * platform cannot derive from a hit's scope/identity, so the producer must
+   * stamp them on `IndexableDocument.routeParams` (an object ref additionally
+   * carries `slug` intrinsically). Currently
+   * {@link SEARCH_ROUTE_PROJECTED_VARIABLES}: `slug`, `containerSlug`.
+   *
+   * This is the contribution's SUPPLY CONTRACT and it is enforced both ways:
+   * a `routeTemplate` referencing a projected variable that is not listed here
+   * is rejected, and a variable listed here that the template never references
+   * is rejected as a dead declaration. Absent ⇒ the template may only use
+   * platform-derived (`scope`/`identity`) variables.
+   *
+   * Only meaningful together with a `routeTemplate`; declaring it alone is a
+   * contribution bug and is rejected.
+   */
+  readonly routeParams?: readonly SearchRouteTemplateVariable[];
 }
 
+/**
+ * Hard cap on declared route params: the projected vocabulary itself is the
+ * ceiling — a contribution can never legitimately declare more entries than
+ * there are projected variables.
+ */
+const SEARCH_TYPE_ROUTE_PARAMS_MAX = SEARCH_ROUTE_PROJECTED_VARIABLES.size;
+
 export const SearchTypeRenderHintsSchema: z.ZodType<SearchTypeRenderHints> =
-  z.object({
-    label: z.string().min(1).max(SEARCH_TYPE_STRING_MAX),
-    icon: z.string().min(1).max(SEARCH_TYPE_STRING_MAX).optional(),
-    routeTemplate: z
-      .string()
-      .min(1)
-      .max(SEARCH_TYPE_ROUTE_TEMPLATE_MAX)
-      .optional(),
-  }) as z.ZodType<SearchTypeRenderHints>;
+  z
+    .object({
+      label: z.string().min(1).max(SEARCH_TYPE_STRING_MAX),
+      icon: z.string().min(1).max(SEARCH_TYPE_STRING_MAX).optional(),
+      routeTemplate: z
+        .string()
+        .min(1)
+        .max(SEARCH_TYPE_ROUTE_TEMPLATE_MAX)
+        .optional(),
+      routeParams: z
+        .array(z.nativeEnum(SearchRouteTemplateVariable))
+        .max(SEARCH_TYPE_ROUTE_PARAMS_MAX)
+        .optional(),
+    })
+    .superRefine((value, ctx) => {
+      if (value.routeTemplate === undefined) {
+        if (value.routeParams !== undefined) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['routeParams'],
+            message:
+              'routeParams declares route variables but no routeTemplate uses them — ' +
+              'a supply declaration without a template is dead weight.',
+          });
+        }
+        return;
+      }
+      try {
+        assertSearchRouteTemplateSatisfiable(
+          value.routeTemplate,
+          value.routeParams ?? [],
+        );
+      } catch (error) {
+        if (!(error instanceof SearchRouteTemplateError)) {
+          throw error;
+        }
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['routeTemplate'],
+          message: error.reason,
+        });
+      }
+    }) as z.ZodType<SearchTypeRenderHints>;
 
 /**
  * `SearchTypeAuthzMapping` — how instances of this result-type map onto the

package/src/search-source/lib/indexable-document.ts

@@ -10,6 +10,10 @@ import {
   ResourceVisibilityPatternSchema,
   type ResourceVisibilityPattern,
 } from '../../resource';
+import {
+  SEARCH_ROUTE_PROJECTED_VARIABLES,
+  SearchRouteTemplateVariable,
+} from '../../search';
 import {
   DataClassificationSchema,
   SpaceRefSchema,
@@ -89,6 +93,24 @@ export interface IndexableDocument {
   readonly updatedAt?: string;
   /** Free-form per-source metadata carried verbatim onto the index document. */
   readonly metadata?: Readonly<Record<string, unknown>>;
+  /**
+   * Deep-link route parameters this source PROJECTS onto the document so a
+   * search hit can be expanded into the biome's real frontend URL.
+   *
+   * Keys are the CLOSED {@link SEARCH_ROUTE_PROJECTED_VARIABLES} subset of
+   * {@link SearchRouteTemplateVariable} — the placeholders the platform cannot
+   * derive from a hit's scope/identity (`slug`, `containerSlug`). This is
+   * deliberately NOT `metadata`: it is a typed, closed-key contract validated
+   * at the wire, because a mistyped key here is a dead deep link, and search's
+   * whole route story depends on it being exactly what the owning biome's
+   * `SearchType` contribution declared in `renderHints.routeParams`.
+   *
+   * Omitted ⇒ the source projects no route params; a template referencing one
+   * simply does not expand for this document (no URL, never a broken URL).
+   */
+  readonly routeParams?: Readonly<
+    Partial<Record<SearchRouteTemplateVariable, string>>
+  >;
   /**
    * Whether this document should receive a vector embedding (semantic search),
    * declared by the SOURCE. Search is source-agnostic: it never inspects a
@@ -104,6 +126,27 @@ export interface IndexableDocument {
   readonly embeddingEligible?: boolean;
 }
 
+/** Max length of a single projected route-param value (one URL path segment). */
+const SEARCH_ROUTE_PARAM_VALUE_MAX = 200;
+
+/**
+ * Wire schema for `IndexableDocument.routeParams`. `.strict()` on purpose: the
+ * key set is the CLOSED projected vocabulary, so a platform-derived key
+ * (`orgId`, `sourceId`, …) or a typo (`pageSlug`) is a hard validation failure
+ * at the wire — exactly the class of bug that used to surface only as a dead
+ * link in production.
+ */
+export const SearchRouteParamsSchema = z
+  .object(
+    Object.fromEntries(
+      [...SEARCH_ROUTE_PROJECTED_VARIABLES].map((variable) => [
+        variable,
+        z.string().min(1).max(SEARCH_ROUTE_PARAM_VALUE_MAX).optional(),
+      ]),
+    ) as Record<SearchRouteTemplateVariable, z.ZodOptional<z.ZodString>>,
+  )
+  .strict();
+
 /**
  * Wire schema for {@link IndexableDocument}. search-api validates every consumed
  * upsert against this and dead-letters on failure — no silent thin-index.
@@ -130,6 +173,7 @@ export const IndexableDocumentSchema = z
     createdAt: z.string().optional(),
     updatedAt: z.string().optional(),
     metadata: z.record(z.string(), z.unknown()).optional(),
+    routeParams: SearchRouteParamsSchema.optional(),
     embeddingEligible: z.boolean().optional(),
   })
   .strict();

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).