@xemahq/kernel-contracts 0.50.0 → 0.57.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
@@ -97,14 +170,26 @@ export const SearchTypeAuthzMappingSchema: z.ZodType<SearchTypeAuthzMapping> =
  */
 export interface SearchTypeContributionManifest {
   /**
-   * The `XemaObjectKind` this result-type covers. The object model is the
-   * identity/scope backbone — every result addresses through it.
+   * The `XemaObjectKind` this result-type covers, when one genuinely applies.
+   *
+   * OPTIONAL BY DESIGN. `XemaObjectKind` is a CLOSED kernel enum; a biome
+   * concept that has no kernel kind (an email, a backlog item, a design idea)
+   * must not be forced to mislabel itself as the nearest neighbour. Four of the
+   * five first-party contributions did exactly that — all declaring `artifact`
+   * as a closest fit — which is worse than declaring nothing: it makes the
+   * object registry claim kinds it cannot enumerate, and it reads as a real
+   * classification to anything that consumes it.
+   *
+   * Absent ⇒ the result-type is discriminated by the OPEN `docType` alone,
+   * which is what `IndexableDocument.kind` being optional already anticipates.
+   * The natural key remains `(objectKind, docType)`; a contribution must carry
+   * at least one of the two, enforced by the schema below.
    */
-  readonly objectKind: XemaObjectKind;
+  readonly objectKind?: XemaObjectKind;
   /**
-   * Optional biome sub-facet under `objectKind` (e.g. `kb_page` under
-   * `knowledge-page`). Absent ⇒ the result-type covers the kind as a whole.
-   * The natural key of a result-type is `(objectKind, docType)`.
+   * Biome sub-facet under `objectKind` (e.g. `kb_page` under `knowledge-page`),
+   * or — when no kernel kind applies — the sole discriminator for this
+   * result-type. The natural key of a result-type is `(objectKind, docType)`.
    */
   readonly docType?: string;
   /** Generic render/route hints so the frontend presents hits without a per-kind switch. */
@@ -139,27 +224,49 @@ export interface SearchTypeContributionManifest {
  * `CapabilityContributionManifestSchema`).
  */
 export const SearchTypeContributionManifestSchema: z.ZodType<SearchTypeContributionManifest> =
-  z.object({
-    objectKind: XemaObjectKindSchema,
-    docType: z.string().min(1).max(SEARCH_TYPE_STRING_MAX).optional(),
-    renderHints: SearchTypeRenderHintsSchema,
-    searchableFields: z
-      .array(z.string().min(1).max(SEARCH_TYPE_STRING_MAX))
-      .min(1)
-      .max(SEARCH_TYPE_FIELDS_MAX),
-    embeddingEligibleDefault: z.boolean(),
-    authz: SearchTypeAuthzMappingSchema,
-    searchReplayCapabilityRef: CapabilityRefSchema.optional(),
-  }) as z.ZodType<SearchTypeContributionManifest>;
+  z
+    .object({
+      objectKind: XemaObjectKindSchema.optional(),
+      docType: z.string().min(1).max(SEARCH_TYPE_STRING_MAX).optional(),
+      renderHints: SearchTypeRenderHintsSchema,
+      searchableFields: z
+        .array(z.string().min(1).max(SEARCH_TYPE_STRING_MAX))
+        .min(1)
+        .max(SEARCH_TYPE_FIELDS_MAX),
+      embeddingEligibleDefault: z.boolean(),
+      authz: SearchTypeAuthzMappingSchema,
+      searchReplayCapabilityRef: CapabilityRefSchema.optional(),
+    })
+    // Both may not be absent: the natural key is `(objectKind, docType)`, so a
+    // contribution declaring neither has no identity at all. Making `objectKind`
+    // optional must not open a hole where a result-type is unaddressable —
+    // fail fast at the boundary, exactly as before.
+    .refine(
+      (m) => m.objectKind !== undefined || m.docType !== undefined,
+      'a search-type contribution must declare objectKind, docType, or both — ' +
+        'the natural key is (objectKind, docType) and cannot be empty',
+    ) as unknown as z.ZodType<SearchTypeContributionManifest>;
 
 /**
- * The stable natural key of a result-type: `objectKind` when no `docType`, else
+ * The stable natural key of a result-type: `objectKind` when no `docType`,
+ * `docType` when no `objectKind` (a biome concept with no kernel kind), else
  * `objectKind/docType`. Centralized so the parser slug, the DB unique key, and
  * the reconciler's `seenKeyOf` all agree.
+ *
+ * The schema guarantees at least one is present; this throws rather than
+ * returning `"undefined"` if that guarantee is ever bypassed, because a
+ * silently-stringified key would collide every unkeyed result-type into one row.
  */
 export function searchTypeNaturalKey(
-  objectKind: XemaObjectKind,
+  objectKind?: XemaObjectKind,
   docType?: string,
 ): string {
+  if (objectKind === undefined && docType === undefined) {
+    throw new Error(
+      'searchTypeNaturalKey: neither objectKind nor docType was supplied — ' +
+        'a result-type must be addressable by at least one.',
+    );
+  }
+  if (objectKind === undefined) return String(docType);
   return docType ? `${objectKind}/${docType}` : String(objectKind);
 }

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();