@xemahq/kernel-contracts 0.25.0 → 0.27.0

package/dist/search-source/lib/indexable-document.js

@@ -2,13 +2,20 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.IndexableDocumentSchema = void 0;
 const zod_1 = require("zod");
+const object_1 = require("../../object");
+const resource_1 = require("../../resource");
+const space_1 = require("../../space");
+const subject_1 = require("../../subject");
 exports.IndexableDocumentSchema = zod_1.z
     .object({
-    sourceKey: zod_1.z.string().min(1),
+    ref: object_1.XemaObjectRefSchema,
     docType: zod_1.z.string().min(1),
-    sourceId: zod_1.z.string().min(1),
-    orgId: zod_1.z.string().min(1),
-    projectId: zod_1.z.string().min(1).optional(),
+    kind: object_1.XemaObjectKindSchema.optional(),
+    scope: space_1.SpaceRefSchema,
+    owner: subject_1.SubjectRefSchema,
+    classification: space_1.DataClassificationSchema.optional(),
+    resourceType: zod_1.z.string().min(1),
+    visibility: resource_1.ResourceVisibilityPatternSchema,
     title: zod_1.z.string().optional(),
     summary: zod_1.z.string().optional(),
     content: zod_1.z.string().optional(),

package/dist/search-source/lib/indexable-document.js.map

@@ -1 +1 @@
-{"version":3,"file":"indexable-document.js","sourceRoot":"","sources":["../../../src/search-source/lib/indexable-document.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AA8DX,QAAA,uBAAuB,GAAG,OAAC;KACrC,MAAM,CAAC;IACN,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACvC,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,IAAI,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACpC,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,QAAQ,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;IACtD,iBAAiB,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAC1C,CAAC;KACD,MAAM,EAAE,CAAC"}
+{"version":3,"file":"indexable-document.js","sourceRoot":"","sources":["../../../src/search-source/lib/indexable-document.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAExB,yCAKsB;AACtB,6CAGwB;AACxB,uCAKqB;AACrB,2CAAkE;AA4FrD,QAAA,uBAAuB,GAAG,OAAC;KACrC,MAAM,CAAC;IACN,GAAG,EAAE,4BAAmB;IACxB,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,IAAI,EAAE,6BAAoB,CAAC,QAAQ,EAAE;IACrC,KAAK,EAAE,sBAAc;IACrB,KAAK,EAAE,0BAAgB;IACvB,cAAc,EAAE,gCAAwB,CAAC,QAAQ,EAAE;IACnD,YAAY,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/B,UAAU,EAAE,0CAA+B;IAC3C,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,IAAI,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACpC,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,QAAQ,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;IACtD,iBAAiB,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAC1C,CAAC;KACD,MAAM,EAAE,CAAC"}

package/dist/search-source/lib/search-index-event.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { type SpaceRef } from '../../space';
 import { type IndexableDocument } from './indexable-document';
 export declare enum SearchIndexOp {
     Upsert = "upsert",
@@ -12,21 +13,32 @@ export interface SearchIndexUpsert {
 }
 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;
 export declare const SearchIndexUpsertSchema: z.ZodObject<{
     op: z.ZodLiteral<SearchIndexOp.Upsert>;
     document: z.ZodObject<{
-        sourceKey: z.ZodString;
+        ref: z.ZodString & z.ZodType<`xema://${string}`, string, z.core.$ZodTypeInternals<`xema://${string}`, string>>;
         docType: z.ZodString;
-        sourceId: z.ZodString;
-        orgId: z.ZodString;
-        projectId: z.ZodOptional<z.ZodString>;
+        kind: z.ZodOptional<z.ZodEnum<typeof import("../../object").XemaObjectKind>>;
+        scope: z.ZodObject<{
+            tier: z.ZodEnum<typeof import("../../space").SpaceKind>;
+            orgId: z.ZodOptional<z.ZodString>;
+            projectId: z.ZodOptional<z.ZodString>;
+            appId: z.ZodOptional<z.ZodString>;
+            sessionId: z.ZodOptional<z.ZodString>;
+            biomeId: z.ZodOptional<z.ZodString>;
+            userId: z.ZodOptional<z.ZodString>;
+            path: z.ZodOptional<z.ZodString>;
+            classification: z.ZodOptional<z.ZodEnum<typeof import("../../space").DataClassification>>;
+        }, z.core.$strip>;
+        owner: z.ZodType<import("../../subject").SubjectRef, unknown, z.core.$ZodTypeInternals<import("../../subject").SubjectRef, unknown>>;
+        classification: z.ZodOptional<z.ZodEnum<typeof import("../../space").DataClassification>>;
+        resourceType: z.ZodString;
+        visibility: z.ZodEnum<typeof import("../../resource").ResourceVisibilityPattern>;
         title: z.ZodOptional<z.ZodString>;
         summary: z.ZodOptional<z.ZodString>;
         content: z.ZodOptional<z.ZodString>;
@@ -44,10 +56,18 @@ export declare const SearchIndexUpsertSchema: z.ZodObject<{
 }, z.core.$strict>;
 export declare const SearchIndexDeleteSchema: z.ZodObject<{
     op: z.ZodLiteral<SearchIndexOp.Delete>;
-    sourceKey: z.ZodString;
+    scope: z.ZodObject<{
+        tier: z.ZodEnum<typeof import("../../space").SpaceKind>;
+        orgId: z.ZodOptional<z.ZodString>;
+        projectId: z.ZodOptional<z.ZodString>;
+        appId: z.ZodOptional<z.ZodString>;
+        sessionId: z.ZodOptional<z.ZodString>;
+        biomeId: z.ZodOptional<z.ZodString>;
+        userId: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodString>;
+        classification: z.ZodOptional<z.ZodEnum<typeof import("../../space").DataClassification>>;
+    }, z.core.$strip>;
     docType: z.ZodString;
     sourceId: z.ZodString;
-    orgId: z.ZodString;
-    projectId: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 //# sourceMappingURL=search-index-event.d.ts.map

package/dist/search-source/lib/search-index-event.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search-index-event.d.ts","sourceRoot":"","sources":["../../../src/search-source/lib/search-index-event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAKvF,oBAAY,aAAa;IACvB,MAAM,WAAW;IACjB,MAAM,WAAW;CAClB;AAQD,eAAO,MAAM,8BAA8B,EAAG,qBAA8B,CAAC;AAC7E,eAAO,MAAM,8BAA8B,EAAG,qBAA8B,CAAC;AAG7E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAC,MAAM,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;CACtC;AAGD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAC,MAAM,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,GAAG,iBAAiB,CAAC;AAEtE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;kBAKzB,CAAC;AAEZ,eAAO,MAAM,uBAAuB;;;;;;;kBASzB,CAAC"}
+{"version":3,"file":"search-index-event.d.ts","sourceRoot":"","sources":["../../../src/search-source/lib/search-index-event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAKvF,oBAAY,aAAa;IACvB,MAAM,WAAW;IACjB,MAAM,WAAW;CAClB;AAQD,eAAO,MAAM,8BAA8B,EAAG,qBAA8B,CAAC;AAC7E,eAAO,MAAM,8BAA8B,EAAG,qBAA8B,CAAC;AAG7E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAC,MAAM,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;CACtC;AASD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAC,MAAM,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,GAAG,iBAAiB,CAAC;AAEtE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAKzB,CAAC;AAEZ,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;kBAOzB,CAAC"}

package/dist/search-source/lib/search-index-event.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SearchIndexDeleteSchema = exports.SearchIndexUpsertSchema = exports.SEARCH_INDEX_DELETE_EVENT_TYPE = exports.SEARCH_INDEX_UPSERT_EVENT_TYPE = exports.SearchIndexOp = void 0;
 const zod_1 = require("zod");
+const space_1 = require("../../space");
 const indexable_document_1 = require("./indexable-document");
 var SearchIndexOp;
 (function (SearchIndexOp) {
@@ -19,11 +20,9 @@ exports.SearchIndexUpsertSchema = zod_1.z
 exports.SearchIndexDeleteSchema = zod_1.z
     .object({
     op: zod_1.z.literal(SearchIndexOp.Delete),
-    sourceKey: zod_1.z.string().min(1),
+    scope: space_1.SpaceRefSchema,
     docType: zod_1.z.string().min(1),
     sourceId: zod_1.z.string().min(1),
-    orgId: zod_1.z.string().min(1),
-    projectId: zod_1.z.string().min(1).optional(),
 })
     .strict();
 //# sourceMappingURL=search-index-event.js.map

package/dist/search-source/lib/search-index-event.js.map

@@ -1 +1 @@
-{"version":3,"file":"search-index-event.js","sourceRoot":"","sources":["../../../src/search-source/lib/search-index-event.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAExB,6DAAuF;AAKvF,IAAY,aAGX;AAHD,WAAY,aAAa;IACvB,kCAAiB,CAAA;IACjB,kCAAiB,CAAA;AACnB,CAAC,EAHW,aAAa,6BAAb,aAAa,QAGxB;AAQY,QAAA,8BAA8B,GAAG,qBAA8B,CAAC;AAChE,QAAA,8BAA8B,GAAG,qBAA8B,CAAC;AAoBhE,QAAA,uBAAuB,GAAG,OAAC;KACrC,MAAM,CAAC;IACN,EAAE,EAAE,OAAC,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC;IACnC,QAAQ,EAAE,4CAAuB;CAClC,CAAC;KACD,MAAM,EAAE,CAAC;AAEC,QAAA,uBAAuB,GAAG,OAAC;KACrC,MAAM,CAAC;IACN,EAAE,EAAE,OAAC,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC;IACnC,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CACxC,CAAC;KACD,MAAM,EAAE,CAAC"}
+{"version":3,"file":"search-index-event.js","sourceRoot":"","sources":["../../../src/search-source/lib/search-index-event.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAExB,uCAA4D;AAC5D,6DAAuF;AAKvF,IAAY,aAGX;AAHD,WAAY,aAAa;IACvB,kCAAiB,CAAA;IACjB,kCAAiB,CAAA;AACnB,CAAC,EAHW,aAAa,6BAAb,aAAa,QAGxB;AAQY,QAAA,8BAA8B,GAAG,qBAA8B,CAAC;AAChE,QAAA,8BAA8B,GAAG,qBAA8B,CAAC;AAwBhE,QAAA,uBAAuB,GAAG,OAAC;KACrC,MAAM,CAAC;IACN,EAAE,EAAE,OAAC,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC;IACnC,QAAQ,EAAE,4CAAuB;CAClC,CAAC;KACD,MAAM,EAAE,CAAC;AAEC,QAAA,uBAAuB,GAAG,OAAC;KACrC,MAAM,CAAC;IACN,EAAE,EAAE,OAAC,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC;IACnC,KAAK,EAAE,sBAAc;IACrB,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAC5B,CAAC;KACD,MAAM,EAAE,CAAC"}

package/dist/search-source/lib/search-ref.d.ts

@@ -0,0 +1,17 @@
+import { type XemaObjectRef } from '../../object';
+import { type SpaceRef } from '../../space';
+export declare class SearchRefParseError extends Error {
+    readonly code = "SEARCH_REF_INVALID";
+    readonly ref: string;
+    readonly reason: string;
+    constructor(ref: string, reason: string);
+}
+export interface SearchRefParts {
+    readonly scope: SpaceRef;
+    readonly docType: string;
+    readonly sourceId: string;
+}
+export declare function formatSearchRef(scope: SpaceRef, docType: string, sourceId: string): XemaObjectRef;
+export declare function parseSearchRef(ref: string): SearchRefParts;
+export declare function searchDocumentScope(orgId: string, projectId?: string): SpaceRef;
+//# sourceMappingURL=search-ref.d.ts.map

package/dist/search-source/lib/search-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-ref.d.ts","sourceRoot":"","sources":["../../../src/search-source/lib/search-ref.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAA6B,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAkCvE,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAgB,IAAI,wBAAwB;IAC5C,SAAgB,GAAG,EAAE,MAAM,CAAC;IAC5B,SAAgB,MAAM,EAAE,MAAM,CAAC;gBAEZ,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAM/C;AAGD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AA4BD,wBAAgB,eAAe,CAC7B,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,aAAa,CAKf;AAQD,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CA6B1D;AAUD,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EAAE,MAAM,GACjB,QAAQ,CASV"}

package/dist/search-source/lib/search-ref.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SearchRefParseError = void 0;
+exports.formatSearchRef = formatSearchRef;
+exports.parseSearchRef = parseSearchRef;
+exports.searchDocumentScope = searchDocumentScope;
+const object_1 = require("../../object");
+const space_1 = require("../../space");
+const SEARCH_REF_PREFIX = 'xema://';
+const DOC_TYPE_PATTERN = /^[a-z0-9][a-z0-9_.-]*$/;
+class SearchRefParseError extends Error {
+    code = 'SEARCH_REF_INVALID';
+    ref;
+    reason;
+    constructor(ref, reason) {
+        super(`Invalid search ref "${ref}": ${reason}`);
+        this.name = 'SearchRefParseError';
+        this.ref = ref;
+        this.reason = reason;
+    }
+}
+exports.SearchRefParseError = SearchRefParseError;
+function assertValidDocType(docType, refForError) {
+    if (!DOC_TYPE_PATTERN.test(docType)) {
+        throw new SearchRefParseError(refForError, `docType "${docType}" must match ${DOC_TYPE_PATTERN}`);
+    }
+}
+function assertValidSourceId(sourceId, refForError) {
+    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`);
+    }
+}
+function formatSearchRef(scope, docType, sourceId) {
+    assertValidDocType(docType, '<unformatted>');
+    assertValidSourceId(sourceId, '<unformatted>');
+    const scopePath = (0, space_1.spaceRefToPath)(scope).replace(/^\//, '');
+    return `${SEARCH_REF_PREFIX}${scopePath}/${docType}/${sourceId}`;
+}
+function parseSearchRef(ref) {
+    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 } = (0, object_1.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;
+    assertValidDocType(docType, ref);
+    assertValidSourceId(sourceId, ref);
+    return { scope, docType, sourceId };
+}
+function searchDocumentScope(orgId, projectId) {
+    if (!orgId) {
+        throw new Error('searchDocumentScope: orgId is required to scope a searchable document');
+    }
+    return projectId
+        ? { tier: space_1.SpaceKind.Project, orgId, projectId }
+        : { tier: space_1.SpaceKind.Org, orgId };
+}
+//# sourceMappingURL=search-ref.js.map

package/dist/search-source/lib/search-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-ref.js","sourceRoot":"","sources":["../../../src/search-source/lib/search-ref.ts"],"names":[],"mappings":";;;AAoFA,0CASC;AAQD,wCA6BC;AAUD,kDAYC;AAxJD,yCAGsB;AACtB,uCAAuE;AAwBvE,MAAM,iBAAiB,GAAG,SAAS,CAAC;AAGpC,MAAM,gBAAgB,GAAG,wBAAwB,CAAC;AAOlD,MAAa,mBAAoB,SAAQ,KAAK;IAC5B,IAAI,GAAG,oBAAoB,CAAC;IAC5B,GAAG,CAAS;IACZ,MAAM,CAAS;IAE/B,YAAmB,GAAW,EAAE,MAAc;QAC5C,KAAK,CAAC,uBAAuB,GAAG,MAAM,MAAM,EAAE,CAAC,CAAC;QAChD,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAXD,kDAWC;AASD,SAAS,kBAAkB,CAAC,OAAe,EAAE,WAAmB;IAC9D,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,mBAAmB,CAC3B,WAAW,EACX,YAAY,OAAO,gBAAgB,gBAAgB,EAAE,CACtD,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,mBAAmB,CAAC,QAAgB,EAAE,WAAmB;IAChE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,mBAAmB,CAAC,WAAW,EAAE,4BAA4B,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,mBAAmB,CAC3B,WAAW,EACX,aAAa,QAAQ,sCAAsC,CAC5D,CAAC;IACJ,CAAC;AACH,CAAC;AAOD,SAAgB,eAAe,CAC7B,KAAe,EACf,OAAe,EACf,QAAgB;IAEhB,kBAAkB,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IAC7C,mBAAmB,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;IAC/C,MAAM,SAAS,GAAG,IAAA,sBAAc,EAAC,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC3D,OAAO,GAAG,iBAAiB,GAAG,SAAS,IAAI,OAAO,IAAI,QAAQ,EAAmB,CAAC;AACpF,CAAC;AAQD,SAAgB,cAAc,CAAC,GAAW;IACxC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,mBAAmB,CAAC,GAAG,EAAE,oBAAoB,iBAAiB,GAAG,CAAC,CAAC;IAC/E,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACjD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,mBAAmB,CAAC,GAAG,EAAE,yBAAyB,CAAC,CAAC;IAChE,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACzE,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,mBAAmB,CAC3B,GAAG,EACH,oDAAoD,CACrD,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAA,oCAA2B,EAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACvE,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC3C,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,mBAAmB,CAC3B,GAAG,EACH,uEAAuE,SAAS,CAAC,MAAM,EAAE,CAC1F,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,GAAG,SAA6B,CAAC;IAC1D,kBAAkB,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACjC,mBAAmB,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACnC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AACtC,CAAC;AAUD,SAAgB,mBAAmB,CACjC,KAAa,EACb,SAAkB;IAElB,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,uEAAuE,CACxE,CAAC;IACJ,CAAC;IACD,OAAO,SAAS;QACd,CAAC,CAAC,EAAE,IAAI,EAAE,iBAAS,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE;QAC/C,CAAC,CAAC,EAAE,IAAI,EAAE,iBAAS,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC;AACrC,CAAC"}

package/dist/search-source/lib/search-replay.d.ts

@@ -22,11 +22,24 @@ export declare const SearchReplayRequestSchema: z.ZodObject<{
 }, z.core.$strict>;
 export declare const SearchReplayResponseSchema: z.ZodObject<{
     documents: z.ZodArray<z.ZodObject<{
-        sourceKey: z.ZodString;
+        ref: z.ZodString & z.ZodType<`xema://${string}`, string, z.core.$ZodTypeInternals<`xema://${string}`, string>>;
         docType: z.ZodString;
-        sourceId: z.ZodString;
-        orgId: z.ZodString;
-        projectId: z.ZodOptional<z.ZodString>;
+        kind: z.ZodOptional<z.ZodEnum<typeof import("../../object").XemaObjectKind>>;
+        scope: z.ZodObject<{
+            tier: z.ZodEnum<typeof import("../../space").SpaceKind>;
+            orgId: z.ZodOptional<z.ZodString>;
+            projectId: z.ZodOptional<z.ZodString>;
+            appId: z.ZodOptional<z.ZodString>;
+            sessionId: z.ZodOptional<z.ZodString>;
+            biomeId: z.ZodOptional<z.ZodString>;
+            userId: z.ZodOptional<z.ZodString>;
+            path: z.ZodOptional<z.ZodString>;
+            classification: z.ZodOptional<z.ZodEnum<typeof import("../../space").DataClassification>>;
+        }, z.core.$strip>;
+        owner: z.ZodType<import("../../subject").SubjectRef, unknown, z.core.$ZodTypeInternals<import("../../subject").SubjectRef, unknown>>;
+        classification: z.ZodOptional<z.ZodEnum<typeof import("../../space").DataClassification>>;
+        resourceType: z.ZodString;
+        visibility: z.ZodEnum<typeof import("../../resource").ResourceVisibilityPattern>;
         title: z.ZodOptional<z.ZodString>;
         summary: z.ZodOptional<z.ZodString>;
         content: z.ZodOptional<z.ZodString>;

package/dist/search-source/lib/search-replay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search-replay.d.ts","sourceRoot":"","sources":["../../../src/search-source/lib/search-replay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AASvF,eAAO,MAAM,6BAA6B,EAAG,eAAwB,CAAC;AAOtE,eAAO,MAAM,8BAA8B,EAAG,CAAU,CAAC;AAWzD,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEnE;AAcD,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEhE;AAOD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAOD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACjD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,eAAO,MAAM,yBAAyB;;;;;kBAO3B,CAAC;AAEZ,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;kBAK5B,CAAC"}
+{"version":3,"file":"search-replay.d.ts","sourceRoot":"","sources":["../../../src/search-source/lib/search-replay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AASvF,eAAO,MAAM,6BAA6B,EAAG,eAAwB,CAAC;AAOtE,eAAO,MAAM,8BAA8B,EAAG,CAAU,CAAC;AAWzD,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEnE;AAcD,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEhE;AAOD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAOD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACjD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,eAAO,MAAM,yBAAyB;;;;;kBAO3B,CAAC;AAEZ,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAK5B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/kernel-contracts",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "Consolidated Xema OS kernel wire contracts — pure types + zod schemas for the kernel protocol surfaces. One package, one npm scope, wildcard per-surface subpath exports. No framework/runtime deps.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",

package/src/biome/index.ts

@@ -5,6 +5,7 @@ export * from './lib/biome-tier';
 export * from './lib/biome-target';
 export * from './lib/biome-audience';
 export * from './lib/biome-origin';
+export * from './lib/biome-kind';
 export * from './lib/biome-trust-tier';
 export * from './lib/biome-availability-grant';
 export * from './lib/biome-lifecycle-hooks';

package/src/biome/lib/biome-kind.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+
+/**
+ * `BiomeKind` — WHAT kind of thing a biome is, orthogonal to its dependency
+ * tier (`BiomeTier`), audience (`BiomeAudience`), origin (`BiomeOrigin`), and
+ * install scope (`BiomeScope`). Declared as `xema.kind` in `xema-biome.json`.
+ *
+ * A Connector is NOT a new installable kind — it reuses the entire
+ * distribution / signing / source-registry / `biome-fetcher` machinery
+ * unchanged. `kind` is only a MARKER that lets the platform (a) list connectors
+ * in a dedicated store catalog, (b) enforce the connector-biome boundary
+ * (`tooling/boundaries/check-connector-biome.mjs`: a connector ships ≥1
+ * `integration-provider` contribution, NO web pages / product BFF, and NO
+ * cross-biome dependency), and (c) govern connectors distinctly. See
+ * `.claude/plans/connector-architecture-convergence.md`.
+ *
+ *  - `app`       — a normal product biome (the default): may ship web pages, a
+ *    product BFF, agents, workflows, and depend on other biomes.
+ *  - `connector` — a constrained, credential-bearing capability provider (a
+ *    Connector Biome). Governed by the connector-biome boundary check.
+ *  - `library`   — a biome that only contributes reusable content (skills,
+ *    capabilities, tool profiles) with no standalone product surface.
+ *
+ * Closed set; new values are a kernel change. OPTIONAL on the manifest — an
+ * existing `xema-biome.json` that omits `kind` stays valid and resolves to the
+ * default (`app`) via {@link DEFAULT_BIOME_KIND} / `getBiomeKind`.
+ */
+export enum BiomeKind {
+  App = 'app',
+  Connector = 'connector',
+  Library = 'library',
+}
+
+export const BiomeKindSchema = z.nativeEnum(BiomeKind);
+
+/** The default kind applied when a manifest omits `xema.kind`. */
+export const DEFAULT_BIOME_KIND = BiomeKind.App;

package/src/biome/lib/biome-manifest.ts

@@ -25,6 +25,7 @@ import {
   DEFAULT_BIOME_AUDIENCE,
 } from './biome-audience';
 import { BiomeOriginSchema } from './biome-origin';
+import { BiomeKind, BiomeKindSchema, DEFAULT_BIOME_KIND } from './biome-kind';
 import {
   BiomeEnginesSchema,
 } from './biome-engines';
@@ -544,6 +545,16 @@ const XsiManifestExtensionsShape = {
    * option). Resolve via `isBiomeStoreListed` — never read raw.
    */
   storeListed: z.boolean().optional(),
+  /**
+   * WHAT kind of biome this is — `app` (default) | `connector` | `library`.
+   * OPTIONAL and ADDITIVE: an existing manifest that omits it stays valid and
+   * resolves to `app` via `getBiomeKind`. A `connector`-kind biome is a
+   * constrained capability provider enforced by
+   * `tooling/boundaries/check-connector-biome.mjs`. Resolve via `getBiomeKind`
+   * / `isConnectorBiome` — never read `xema.kind` raw, so the default is
+   * applied in exactly one place. See `BiomeKind` in `./biome-kind`.
+   */
+  kind: BiomeKindSchema.optional(),
 } as const;
 
 /**
@@ -1085,3 +1096,21 @@ export function isBiomeStoreListed(manifest: BiomeManifest): boolean {
   }
   return manifest.xema.storeListed ?? true;
 }
+
+/**
+ * Effective kind of a biome, applying the default (`app`) when the manifest
+ * omits `xema.kind`. Never read `xema.kind` raw — go through this so the
+ * default is applied in exactly one place.
+ */
+export function getBiomeKind(manifest: BiomeManifest): BiomeKind {
+  return manifest.xema.kind ?? DEFAULT_BIOME_KIND;
+}
+
+/**
+ * Whether the biome is a Connector Biome (`xema.kind: "connector"`). A
+ * connector is a constrained capability provider — see
+ * `tooling/boundaries/check-connector-biome.mjs` for the enforced constraints.
+ */
+export function isConnectorBiome(manifest: BiomeManifest): boolean {
+  return getBiomeKind(manifest) === BiomeKind.Connector;
+}

package/src/connector/index.ts

@@ -1,4 +1,5 @@
 export * from './lib/adapter-kind';
+export * from './lib/connector-adapter-kind';
 export * from './lib/capability';
 export * from './lib/credential-kind';
 export * from './lib/onboarding-manifest';

package/src/connector/lib/connector-adapter-kind.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+
+/**
+ * `ConnectorAdapterKind` — the unifying BACKEND discriminator for how a
+ * connector operation is actually executed server-side. It is deliberately
+ * hidden from agents: every operation is projected into ONE canonical
+ * `connector:<provider>.<verb>@N` capability and exposed through the single
+ * transparent capability-MCP; the adapter kind selects which backend the
+ * capability router dispatches to, but never leaks into the agent-facing tool
+ * surface.
+ *
+ * This enum is what converges the two historically-parallel connector paths —
+ * the `integration-provider` module path (`connector-gateway-api`) and the
+ * external-MCP / OpenAPI→MCP path (`mcp-gateway-api`) — into two BACKENDS of
+ * ONE Connector concept. See
+ * `.claude/plans/connector-architecture-convergence.md`.
+ *
+ *  - `native-provider` — a biome-shipped `IntegrationProviderModule` executes
+ *    the operation directly (the curated, code-capable connector: Gmail
+ *    module, an SCM connector, …).
+ *  - `external-mcp`    — the operation is fulfilled by proxying a tool call to
+ *    a registered external MCP server (the ad-hoc `OrgMcpServer` path).
+ *  - `openapi-bridge`  — the operation is fulfilled by an OpenAPI spec bridged
+ *    into a tool (the "user adds openapi.json → MCP" path).
+ *  - `email`           — the operation is fulfilled by the generic
+ *    `smtp`/`imap` gateway built-ins (mail send/fetch).
+ *
+ * Closed set; adding a member is a kernel change AND requires a matching
+ * dispatch branch in the capability router — do not add a member that has no
+ * backend.
+ */
+export enum ConnectorAdapterKind {
+  NativeProvider = 'native-provider',
+  ExternalMcp = 'external-mcp',
+  OpenApiBridge = 'openapi-bridge',
+  Email = 'email',
+}
+
+/**
+ * Zod mirror of {@link ConnectorAdapterKind} — value-identical to the enum.
+ * Used wherever an adapter kind crosses a trust boundary (a connector
+ * operation descriptor inside an `integration-provider` contribution).
+ */
+export const ConnectorAdapterKindSchema = z.nativeEnum(ConnectorAdapterKind);

package/src/connector/lib/connector-descriptor.ts

@@ -20,10 +20,74 @@
 
 import { z } from 'zod';
 
+import { CapabilityRefSchema, type CapabilityRef } from '../../capability';
+
 import { CredentialKind } from './credential-kind';
+import {
+  ConnectorAdapterKind,
+  ConnectorAdapterKindSchema,
+} from './connector-adapter-kind';
 
 import type { AdapterKindRef } from './adapter-kind';
 
+/**
+ * One executable operation a connector projects into the capability plane.
+ *
+ * Each operation maps 1:1 onto a canonical `connector:<provider>.<verb>@N`
+ * {@link CapabilityRef} (`capabilityRef`) and names the {@link
+ * ConnectorAdapterKind} backend that fulfils it (`adapterKind`). Declaring
+ * operations on a descriptor makes the contribution → capability projection
+ * MECHANICAL: the connector registry emits one capability per operation rather
+ * than requiring a hand-authored capability contribution per verb.
+ *
+ * The block is ADDITIVE and OPTIONAL on {@link ConnectorDescriptor}: a
+ * descriptor that omits `operations` behaves exactly as before (its
+ * capabilities, if any, are declared out-of-band). When present, every
+ * operation is self-describing enough to drive the projection with no
+ * heuristics.
+ */
+export interface ConnectorOperationDescriptor {
+  /**
+   * The canonical capability this operation is exposed as. MUST be a
+   * `connector:<provider>.<verb>@<major>` ref — the ONE agent-facing grammar;
+   * the divergent `<slug>:<tool>@1` external-MCP grammar is retired in favour
+   * of this.
+   */
+  readonly capabilityRef: CapabilityRef;
+  /**
+   * The BACKEND that executes this operation. Hidden from agents — it only
+   * selects the capability-router dispatch path.
+   */
+  readonly adapterKind: ConnectorAdapterKind;
+  /**
+   * Incremental OAuth scopes THIS operation needs from the connector's
+   * provider, on top of what the connection already holds. A subset of the
+   * connector's `scopes`; empty for operations whose provider `appAuthKind` is
+   * `None` (IMAP/SMTP) or that need no additional scope. Drives the union the
+   * consent driver requests when the operation's capability is first granted.
+   */
+  readonly scopes: readonly string[];
+  /**
+   * Whether executing this operation requires a resolved per-connection
+   * credential (a user/org token/password) via the credential broker. Almost
+   * always `true`; `false` only for operations backed purely by the provider's
+   * app credential with no per-connection secret. Explicit (never defaulted)
+   * so the broker resolution requirement is stated, not inferred.
+   */
+  readonly requiresConnection: boolean;
+}
+
+/**
+ * Zod mirror of {@link ConnectorOperationDescriptor} — value-identical to the
+ * interface. Strict: unknown keys fail fast.
+ */
+export const ConnectorOperationDescriptorSchema = z.strictObject({
+  capabilityRef: CapabilityRefSchema,
+  adapterKind: ConnectorAdapterKindSchema,
+  scopes: z.array(z.string()).readonly(),
+  requiresConnection: z.boolean(),
+});
+
 /**
  * A connector in the catalog. `connectorKey` aligns with the persisted
  * `ConnectorKind` wire value (e.g. `GMAIL`, `IMAP_GENERIC`, `SMTP_GENERIC`)
@@ -67,6 +131,14 @@ export interface ConnectorDescriptor {
    * surface the connector appears under.
    */
   readonly adapterKind: AdapterKindRef;
+
+  /**
+   * The executable operations this connector projects into the capability
+   * plane. OPTIONAL and ADDITIVE — a descriptor without it is unchanged; when
+   * present, each entry drives a mechanical capability projection (see
+   * {@link ConnectorOperationDescriptor}).
+   */
+  readonly operations?: readonly ConnectorOperationDescriptor[];
 }
 
 /**
@@ -85,12 +157,34 @@ export const ConnectorDescriptorSchema = z.strictObject({
   scopes: z.array(z.string()).readonly(),
   connectionCredentialKind: z.nativeEnum(CredentialKind),
   adapterKind: z.string().min(1),
+  operations: z.array(ConnectorOperationDescriptorSchema).readonly().optional(),
 });
 
 // Compile-time value-identity guards: schema output <=> interface. The tuple
 // export exists only so `noUnusedLocals` sees a use; no contract meaning.
+// `AllowUndefinedOptionals` bridges zod's `?: T | undefined` optionals to the
+// interfaces' exact optionals (`exactOptionalPropertyTypes`) — runtime shape
+// is identical.
 type AssertExtends<T extends U, U> = T;
+type AllowUndefinedOptionals<T> = T extends readonly (infer E)[]
+  ? readonly AllowUndefinedOptionals<E>[]
+  : T extends object
+    ? { [K in keyof T]: AllowUndefinedOptionals<T[K]> | undefined }
+    : T;
+export type ConnectorOperationDescriptorValueIdentityGuards = [
+  AssertExtends<
+    z.infer<typeof ConnectorOperationDescriptorSchema>,
+    ConnectorOperationDescriptor
+  >,
+  AssertExtends<
+    ConnectorOperationDescriptor,
+    z.infer<typeof ConnectorOperationDescriptorSchema>
+  >,
+];
 export type ConnectorDescriptorValueIdentityGuards = [
-  AssertExtends<z.infer<typeof ConnectorDescriptorSchema>, ConnectorDescriptor>,
+  AssertExtends<
+    z.infer<typeof ConnectorDescriptorSchema>,
+    AllowUndefinedOptionals<ConnectorDescriptor>
+  >,
   AssertExtends<ConnectorDescriptor, z.infer<typeof ConnectorDescriptorSchema>>,
 ];

package/src/object/lib/xema-object-ref.ts

@@ -69,7 +69,7 @@ const SLUG_SEGMENT = '[a-zA-Z0-9][a-zA-Z0-9_.-]*';
 const SLUG_PATTERN = new RegExp(`^${SLUG_SEGMENT}(?:/${SLUG_SEGMENT})*$`);
 const VERSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.+-]*$/;
 
-interface ScopeParse {
+export interface ScopeParse {
   scope: SpaceRef;
   consumed: number;
 }
@@ -87,7 +87,19 @@ function requireSegment(
   return value;
 }
 
-function parseScope(segments: string[], ref: string): ScopeParse {
+/**
+ * Parse the leading scope segments of a `xema://` ref path into a
+ * {@link SpaceRef} plus the number of segments consumed. Shared by
+ * {@link parseXemaObjectRef} and the search-source `parseSearchRef` helper so
+ * the `xema://<scope-path>/...` scope grammar (plural `orgs`/`projects`, the
+ * same one {@link spaceRefToPath} formats) lives in exactly ONE place. The
+ * caller owns whatever follows the scope (a `<kind>/<slug>` for objects, a
+ * `<docType>/<sourceId>` for search refs).
+ */
+export function parseObjectRefScopeSegments(
+  segments: string[],
+  ref: string,
+): ScopeParse {
   const head = requireSegment(segments, 0, ref, 'scope');
   switch (head) {
     case 'system':
@@ -198,7 +210,7 @@ export function parseXemaObjectRef(ref: string): XemaObjectRefParts {
     );
   }
 
-  const { scope, consumed } = parseScope(segments, ref);
+  const { scope, consumed } = parseObjectRefScopeSegments(segments, ref);
   const remaining = segments.slice(consumed);
   if (remaining.length < 2) {
     throw new XemaObjectRefParseError(

package/src/search-source/index.ts

@@ -1,4 +1,5 @@
 export * from './lib/indexable-document';
+export * from './lib/search-ref';
 export * from './lib/search-index-event';
 export * from './lib/search-source-descriptor';
 export * from './lib/search-replay';