@xemahq/kernel-contracts 0.25.0 → 0.27.0

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

@@ -1,29 +1,77 @@
 import { z } from 'zod';
 
+import {
+  XemaObjectKindSchema,
+  XemaObjectRefSchema,
+  type XemaObjectKind,
+  type XemaObjectRef,
+} from '../../object';
+import {
+  ResourceVisibilityPatternSchema,
+  type ResourceVisibilityPattern,
+} from '../../resource';
+import {
+  DataClassificationSchema,
+  SpaceRefSchema,
+  type DataClassification,
+  type SpaceRef,
+} from '../../space';
+import { SubjectRefSchema, type SubjectRef } from '../../subject';
+
 /**
- * The canonical, source-AGNOSTIC indexable document. A searchable biome
- * projects its own domain entity into this shape (producer-side) so that
- * search-api can index it WITHOUT importing the biome's client or knowing its
- * entity schema.
+ * The canonical, source-AGNOSTIC indexable document (v2, object-model-aligned).
+ * A searchable biome projects its own domain entity into this shape
+ * (producer-side) so that search-api can index it WITHOUT importing the biome's
+ * client or knowing its entity schema.
+ *
+ * v2 realigns identity + scope onto the XSI Object Model:
+ *
+ * - `ref` is the natural key — `xema://<scope-path>/<docType>/<sourceId>`
+ *   (see `formatSearchRef`). It replaces the v1 `sourceKey`+`docType`+`sourceId`
+ *   triple as the addressable, scope-correct, authz-mappable identity.
+ * - `docType` is the REQUIRED type discriminator: biome-owned, open, and
+ *   exactly what a `ContributionKind.SearchType` declares. A document is a
+ *   `kb_page`, an `email`, a `backlog_item`, … by its `docType`.
+ * - `kind` is OPTIONAL enrichment: an object-model-native producer
+ *   (knowledge-base → `KnowledgePage`, artifact-store → `Artifact`) also stamps
+ *   the kernel `XemaObjectKind`; Layer-7 biome concepts (email, design-idea)
+ *   omit it and rely on `docType` — that is why `kind` is NOT required (it would
+ *   otherwise force domain concepts into the kernel's zero-domain enum).
+ * - `scope` is the {@link SpaceRef} that replaces the flat v1 `orgId`/`projectId`
+ *   pair. search-api re-derives/validates it from the trusted event envelope —
+ *   the producer copy is advisory.
+ * - `owner`, `resourceType`, `visibility` (and optional `classification`) are
+ *   the authz descriptor: they map an instance onto the result-level permission
+ *   model (§4). `resourceType`+`visibility` drive the tier-gate + FGA push-down;
+ *   `owner` identifies the owning subject for `OwnerOnly`/`ExplicitShare`.
  *
  * Server-owned fields (vector embedding, chunk index, parent-doc linkage) are
  * NOT part of this contract — search computes them from `content`. The producer
- * supplies identity, scope, and the human/searchable text only.
- *
- * `sourceKey` + `docType` + `sourceId` is the stable natural key: re-emitting
- * the same triple is an idempotent upsert.
+ * supplies identity, scope, ownership, and the human/searchable text only.
  */
 export interface IndexableDocument {
-  /** Registered source that produced this document (e.g. `knowledge-base`). */
-  readonly sourceKey: string;
-  /** Entity kind within the source (e.g. `kb_page`, `backlog_item`). Open taxonomy owned by search. */
+  /** Natural key: `xema://<scope-path>/<docType>/<sourceId>`. */
+  readonly ref: XemaObjectRef;
+  /**
+   * REQUIRED type discriminator — the biome-owned, open facet (e.g. `kb_page`,
+   * `email`, `backlog_item`). The `SearchType` contribution declares it.
+   */
   readonly docType: string;
-  /** The source's stable primary key for this entity. */
-  readonly sourceId: string;
-  /** Tenant scope. Search re-derives/validates this from the event envelope — the producer copy is advisory. */
-  readonly orgId: string;
-  /** Project scope, when applicable. */
-  readonly projectId?: string;
+  /**
+   * OPTIONAL kernel object kind — populated only by object-model-native
+   * producers. Absent for Layer-7 biome content that has no kernel kind.
+   */
+  readonly kind?: XemaObjectKind;
+  /** Tenant/ownership scope. Search re-derives/validates this from the event envelope. */
+  readonly scope: SpaceRef;
+  /** The subject that owns this document (drives owner-scoped result authz). */
+  readonly owner: SubjectRef;
+  /** Optional data-classification for policy obligations / redaction. */
+  readonly classification?: DataClassification;
+  /** FGA/authorization resource-type slug for the result-level ListObjects push-down. */
+  readonly resourceType: string;
+  /** How this instance is shared — the result-level visibility pattern. */
+  readonly visibility: ResourceVisibilityPattern;
   readonly title?: string;
   readonly summary?: string;
   /** Full searchable text. */
@@ -62,11 +110,14 @@ export interface IndexableDocument {
  */
 export const IndexableDocumentSchema = z
   .object({
-    sourceKey: z.string().min(1),
+    ref: XemaObjectRefSchema,
     docType: z.string().min(1),
-    sourceId: z.string().min(1),
-    orgId: z.string().min(1),
-    projectId: z.string().min(1).optional(),
+    kind: XemaObjectKindSchema.optional(),
+    scope: SpaceRefSchema,
+    owner: SubjectRefSchema,
+    classification: DataClassificationSchema.optional(),
+    resourceType: z.string().min(1),
+    visibility: ResourceVisibilityPatternSchema,
     title: z.string().optional(),
     summary: z.string().optional(),
     content: z.string().optional(),

package/src/search-source/lib/search-index-event.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 
+import { SpaceRefSchema, type SpaceRef } from '../../space';
 import { IndexableDocumentSchema, type IndexableDocument } from './indexable-document';
 
 /**
@@ -25,14 +26,18 @@ export interface SearchIndexUpsert {
   readonly document: IndexableDocument;
 }
 
-/** Delete: drop the identified document (or whole source scope) from the index. */
+/**
+ * Delete: drop the identified document from the index. v2-aligned with
+ * {@link IndexableDocument} — the flat `orgId`/`projectId` pair is replaced by
+ * the {@link SpaceRef} `scope` (search derives the per-org index from it). The
+ * document is identified by `docType` + `sourceId` (the same `sourceId` that is
+ * the trailing segment of the document's `ref`).
+ */
 export interface SearchIndexDelete {
   readonly op: SearchIndexOp.Delete;
-  readonly sourceKey: string;
+  readonly scope: SpaceRef;
   readonly docType: string;
   readonly sourceId: string;
-  readonly orgId: string;
-  readonly projectId?: string;
 }
 
 export type SearchIndexChange = SearchIndexUpsert | SearchIndexDelete;
@@ -47,10 +52,8 @@ export const SearchIndexUpsertSchema = z
 export const SearchIndexDeleteSchema = z
   .object({
     op: z.literal(SearchIndexOp.Delete),
-    sourceKey: z.string().min(1),
+    scope: SpaceRefSchema,
     docType: z.string().min(1),
     sourceId: z.string().min(1),
-    orgId: z.string().min(1),
-    projectId: z.string().min(1).optional(),
   })
   .strict();

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

@@ -0,0 +1,153 @@
+import {
+  parseObjectRefScopeSegments,
+  type XemaObjectRef,
+} from '../../object';
+import { SpaceKind, spaceRefToPath, type SpaceRef } from '../../space';
+
+/**
+ * The natural-key / address grammar for a searchable document:
+ *
+ *   `xema://<scope-path>/<docType>/<sourceId>`
+ *
+ * This is a SEARCH-SOURCE-LOCAL ref helper. It deliberately does NOT go through
+ * `parseXemaObjectRef`, because that parser requires a kernel `XemaObjectKind`
+ * in the type position — and the whole point of `IndexableDocument` v2 is that
+ * 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.
+ *
+ * `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`
+ * is the source's stable per-entity id (what v1 carried as `sourceId`); it is
+ * opaque and slash-free but MAY contain other characters real ids use (`@`,
+ * `.`, `:`) — search refs are not versioned, so no `@version` suffix is parsed.
+ */
+
+const SEARCH_REF_PREFIX = 'xema://';
+
+/** A docType facet segment: lowercase, starts alnum, no slash/whitespace. */
+const DOC_TYPE_PATTERN = /^[a-z0-9][a-z0-9_.-]*$/;
+
+/**
+ * Structured error raised by {@link parseSearchRef} / {@link formatSearchRef}.
+ * Carries a stable code so callers fail-fast with a typed error (no silent
+ * fallbacks).
+ */
+export class SearchRefParseError extends Error {
+  public readonly code = 'SEARCH_REF_INVALID';
+  public readonly ref: string;
+  public readonly reason: string;
+
+  public constructor(ref: string, reason: string) {
+    super(`Invalid search ref "${ref}": ${reason}`);
+    this.name = 'SearchRefParseError';
+    this.ref = ref;
+    this.reason = reason;
+  }
+}
+
+/** Parsed parts of a search ref. */
+export interface SearchRefParts {
+  readonly scope: SpaceRef;
+  readonly docType: string;
+  readonly sourceId: string;
+}
+
+function assertValidDocType(docType: string, refForError: string): void {
+  if (!DOC_TYPE_PATTERN.test(docType)) {
+    throw new SearchRefParseError(
+      refForError,
+      `docType "${docType}" must match ${DOC_TYPE_PATTERN}`,
+    );
+  }
+}
+
+function assertValidSourceId(sourceId: string, refForError: string): void {
+  if (sourceId.length === 0) {
+    throw new SearchRefParseError(refForError, 'sourceId must be non-empty');
+  }
+  if (/[/\s]/.test(sourceId)) {
+    throw new SearchRefParseError(
+      refForError,
+      `sourceId "${sourceId}" must not contain "/" or whitespace`,
+    );
+  }
+}
+
+/**
+ * Compose a search ref `xema://<scope-path>/<docType>/<sourceId>`. Fail-fast on
+ * a malformed `docType`/`sourceId` or a scope missing a required segment
+ * ({@link spaceRefToPath} throws). Never silently coerces.
+ */
+export function formatSearchRef(
+  scope: SpaceRef,
+  docType: string,
+  sourceId: string,
+): XemaObjectRef {
+  assertValidDocType(docType, '<unformatted>');
+  assertValidSourceId(sourceId, '<unformatted>');
+  const scopePath = spaceRefToPath(scope).replace(/^\//, '');
+  return `${SEARCH_REF_PREFIX}${scopePath}/${docType}/${sourceId}` as XemaObjectRef;
+}
+
+/**
+ * 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
+ * `docType` and the (slash-free) `sourceId`.
+ */
+export function parseSearchRef(ref: string): SearchRefParts {
+  if (!ref.startsWith(SEARCH_REF_PREFIX)) {
+    throw new SearchRefParseError(ref, `must start with "${SEARCH_REF_PREFIX}"`);
+  }
+  const body = ref.slice(SEARCH_REF_PREFIX.length);
+  if (body.length === 0) {
+    throw new SearchRefParseError(ref, 'empty body after scheme');
+  }
+  const segments = body.split('/').filter((segment) => segment.length > 0);
+  if (segments.length < 3) {
+    throw new SearchRefParseError(
+      ref,
+      'must contain at least <scope>/<docType>/<sourceId>',
+    );
+  }
+
+  const { scope, consumed } = parseObjectRefScopeSegments(segments, ref);
+  const remaining = segments.slice(consumed);
+  if (remaining.length !== 2) {
+    throw new SearchRefParseError(
+      ref,
+      `expected exactly <docType>/<sourceId> after the scope segments, got ${remaining.length}`,
+    );
+  }
+
+  const [docType, sourceId] = remaining as [string, string];
+  assertValidDocType(docType, ref);
+  assertValidSourceId(sourceId, ref);
+  return { scope, docType, sourceId };
+}
+
+/**
+ * Build the {@link SpaceRef} for a search document from the flat tenant scope
+ * every producer already holds: a `Project` space when `projectId` is present,
+ * otherwise an `Org` space. Centralizes the org/project → SpaceRef mapping so
+ * all five producers construct v2 scope identically. Fail-fast on a missing
+ * `orgId` (an org-less content document is unindexable — the per-org index has
+ * nowhere to place it).
+ */
+export function searchDocumentScope(
+  orgId: string,
+  projectId?: string,
+): SpaceRef {
+  if (!orgId) {
+    throw new Error(
+      'searchDocumentScope: orgId is required to scope a searchable document',
+    );
+  }
+  return projectId
+    ? { tier: SpaceKind.Project, orgId, projectId }
+    : { tier: SpaceKind.Org, orgId };
+}