@x12i/memorix-scoper-contracts 1.0.0

package/README.md

@@ -0,0 +1,9 @@
+# @x12i/memorix-scoper-contracts
+
+Zod schemas, evidence types, and normalized error codes for Memorix Scoper.
+
+```ts
+import { ScopeRequestSchema, ScoperError } from "@x12i/memorix-scoper-contracts";
+```
+
+JSON Schema files: package export `./json-schema/*` → `schemas/`.

package/dist/errors.d.ts

@@ -0,0 +1,24 @@
+/** Normalized Scoper / SDK error codes. */
+export declare const SCOPER_ERROR_CODES: readonly ["INVALID_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "READ_NOT_FOUND", "BUDGET_EXCEEDED", "RESULT_TOO_LARGE", "CATALOG_REJECTED", "DECODER_REJECTED", "UNSUPPORTED_CONTRACT_VERSION", "UPSTREAM_CONTRACT_MISMATCH", "ESTATE_PATH_UNAVAILABLE", "NEXUM_EXPLORE_UNAVAILABLE", "PROVIDER_NOT_IMPLEMENTED", "RECURSIVE_SCOPE_CALL", "REASONER_INVALID_PLAN", "REASONER_REPAIR_FAILED", "UPSTREAM_UNAVAILABLE", "TIMEOUT", "INTERNAL", "FEATURE_DISABLED"];
+export type ScoperErrorCode = (typeof SCOPER_ERROR_CODES)[number];
+export declare class ScoperError extends Error {
+    readonly code: ScoperErrorCode;
+    readonly details?: unknown;
+    readonly retryable: boolean;
+    constructor(code: ScoperErrorCode, message: string, options?: {
+        details?: unknown;
+        retryable?: boolean;
+        cause?: unknown;
+    });
+    toJSON(): {
+        name: string;
+        code: "INVALID_REQUEST" | "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "READ_NOT_FOUND" | "BUDGET_EXCEEDED" | "RESULT_TOO_LARGE" | "CATALOG_REJECTED" | "DECODER_REJECTED" | "UNSUPPORTED_CONTRACT_VERSION" | "UPSTREAM_CONTRACT_MISMATCH" | "ESTATE_PATH_UNAVAILABLE" | "NEXUM_EXPLORE_UNAVAILABLE" | "PROVIDER_NOT_IMPLEMENTED" | "RECURSIVE_SCOPE_CALL" | "REASONER_INVALID_PLAN" | "REASONER_REPAIR_FAILED" | "UPSTREAM_UNAVAILABLE" | "TIMEOUT" | "INTERNAL" | "FEATURE_DISABLED";
+        message: string;
+        details: unknown;
+        retryable: boolean;
+    };
+}
+export declare function isScoperError(err: unknown): err is ScoperError;
+/** Map provider / dispatcher / Memorix platform errors into normalized Scoper codes. */
+export declare function normalizeUpstreamError(err: unknown): ScoperError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,eAAO,MAAM,kBAAkB,ycAsBrB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;gBAG1B,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;IASvE,MAAM;;;;;;;CASP;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,WAAW,CAE9D;AAED,wFAAwF;AACxF,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,CA0BhE"}

package/dist/errors.js

@@ -0,0 +1,70 @@
+/** Normalized Scoper / SDK error codes. */
+export const SCOPER_ERROR_CODES = [
+    "INVALID_REQUEST",
+    "UNAUTHORIZED",
+    "FORBIDDEN",
+    "NOT_FOUND",
+    "READ_NOT_FOUND",
+    "BUDGET_EXCEEDED",
+    "RESULT_TOO_LARGE",
+    "CATALOG_REJECTED",
+    "DECODER_REJECTED",
+    "UNSUPPORTED_CONTRACT_VERSION",
+    "UPSTREAM_CONTRACT_MISMATCH",
+    "ESTATE_PATH_UNAVAILABLE",
+    "NEXUM_EXPLORE_UNAVAILABLE",
+    "PROVIDER_NOT_IMPLEMENTED",
+    "RECURSIVE_SCOPE_CALL",
+    "REASONER_INVALID_PLAN",
+    "REASONER_REPAIR_FAILED",
+    "UPSTREAM_UNAVAILABLE",
+    "TIMEOUT",
+    "INTERNAL",
+    "FEATURE_DISABLED",
+];
+export class ScoperError extends Error {
+    code;
+    details;
+    retryable;
+    constructor(code, message, options) {
+        super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = "ScoperError";
+        this.code = code;
+        this.details = options?.details;
+        this.retryable = options?.retryable ?? false;
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            details: this.details,
+            retryable: this.retryable,
+        };
+    }
+}
+export function isScoperError(err) {
+    return err instanceof ScoperError;
+}
+/** Map provider / dispatcher / Memorix platform errors into normalized Scoper codes. */
+export function normalizeUpstreamError(err) {
+    if (err instanceof ScoperError)
+        return err;
+    const anyErr = err;
+    const platformCode = anyErr?.body?.error?.code ?? anyErr?.code ?? "";
+    const message = anyErr?.message ?? (err instanceof Error ? err.message : String(err));
+    if (platformCode === "READ_NOT_FOUND" || anyErr?.statusCode === 404) {
+        return new ScoperError("READ_NOT_FOUND", message, { details: err });
+    }
+    if (platformCode === "PROVIDER_NOT_IMPLEMENTED") {
+        return new ScoperError("PROVIDER_NOT_IMPLEMENTED", message, { details: err });
+    }
+    if (platformCode === "ESTATE_PATH_UNAVAILABLE") {
+        return new ScoperError("ESTATE_PATH_UNAVAILABLE", message, { details: err });
+    }
+    if (/timeout/i.test(message) || platformCode === "TIMEOUT") {
+        return new ScoperError("TIMEOUT", message, { details: err, retryable: true });
+    }
+    return new ScoperError("UPSTREAM_UNAVAILABLE", message, { details: err, retryable: true });
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/evidence.d.ts

@@ -0,0 +1,2 @@
+export * from "./schemas/evidence.js";
+//# sourceMappingURL=evidence.d.ts.map

package/dist/evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../src/evidence.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC"}

package/dist/evidence.js

@@ -0,0 +1,2 @@
+export * from "./schemas/evidence.js";
+//# sourceMappingURL=evidence.js.map

package/dist/evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.js","sourceRoot":"","sources":["../src/evidence.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./schemas/index.js";
+export * from "./errors.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./schemas/index.js";
+export * from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC"}

package/dist/schemas/catalog.d.ts

@@ -0,0 +1,441 @@
+import { z } from "zod";
+export declare const CatalogCapabilitySchema: z.ZodEnum<["subjects.get", "subjects.list", "subjects.query", "subjects.getNexumSnapshot", "estate.startSession", "estate.getBag", "estate.query", "explore.query", "catalog.describe"]>;
+export type CatalogCapability = z.infer<typeof CatalogCapabilitySchema>;
+export declare const CatalogEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    capability: z.ZodEnum<["subjects.get", "subjects.list", "subjects.query", "subjects.getNexumSnapshot", "estate.startSession", "estate.getBag", "estate.query", "explore.query", "catalog.describe"]>;
+    objectType: z.ZodOptional<z.ZodString>;
+    contentType: z.ZodOptional<z.ZodString>;
+    description: z.ZodString;
+    version: z.ZodString;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    requiresFeature: z.ZodOptional<z.ZodString>;
+    epistemicDefault: z.ZodOptional<z.ZodEnum<["OBSERVED", "INFERRED", "POLICY_CANDIDATE", "REACHABLE", "UNKNOWN"]>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    capability: "subjects.get" | "subjects.list" | "subjects.query" | "subjects.getNexumSnapshot" | "estate.startSession" | "estate.getBag" | "estate.query" | "explore.query" | "catalog.describe";
+    description: string;
+    version: string;
+    enabled: boolean;
+    objectType?: string | undefined;
+    contentType?: string | undefined;
+    requiresFeature?: string | undefined;
+    epistemicDefault?: "OBSERVED" | "INFERRED" | "POLICY_CANDIDATE" | "REACHABLE" | "UNKNOWN" | undefined;
+}, {
+    id: string;
+    capability: "subjects.get" | "subjects.list" | "subjects.query" | "subjects.getNexumSnapshot" | "estate.startSession" | "estate.getBag" | "estate.query" | "explore.query" | "catalog.describe";
+    description: string;
+    version: string;
+    objectType?: string | undefined;
+    contentType?: string | undefined;
+    enabled?: boolean | undefined;
+    requiresFeature?: string | undefined;
+    epistemicDefault?: "OBSERVED" | "INFERRED" | "POLICY_CANDIDATE" | "REACHABLE" | "UNKNOWN" | undefined;
+}>;
+export type CatalogEntry = z.infer<typeof CatalogEntrySchema>;
+export declare const CatalogSchema: z.ZodObject<{
+    version: z.ZodString;
+    entries: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        capability: z.ZodEnum<["subjects.get", "subjects.list", "subjects.query", "subjects.getNexumSnapshot", "estate.startSession", "estate.getBag", "estate.query", "explore.query", "catalog.describe"]>;
+        objectType: z.ZodOptional<z.ZodString>;
+        contentType: z.ZodOptional<z.ZodString>;
+        description: z.ZodString;
+        version: z.ZodString;
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        requiresFeature: z.ZodOptional<z.ZodString>;
+        epistemicDefault: z.ZodOptional<z.ZodEnum<["OBSERVED", "INFERRED", "POLICY_CANDIDATE", "REACHABLE", "UNKNOWN"]>>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        capability: "subjects.get" | "subjects.list" | "subjects.query" | "subjects.getNexumSnapshot" | "estate.startSession" | "estate.getBag" | "estate.query" | "explore.query" | "catalog.describe";
+        description: string;
+        version: string;
+        enabled: boolean;
+        objectType?: string | undefined;
+        contentType?: string | undefined;
+        requiresFeature?: string | undefined;
+        epistemicDefault?: "OBSERVED" | "INFERRED" | "POLICY_CANDIDATE" | "REACHABLE" | "UNKNOWN" | undefined;
+    }, {
+        id: string;
+        capability: "subjects.get" | "subjects.list" | "subjects.query" | "subjects.getNexumSnapshot" | "estate.startSession" | "estate.getBag" | "estate.query" | "explore.query" | "catalog.describe";
+        description: string;
+        version: string;
+        objectType?: string | undefined;
+        contentType?: string | undefined;
+        enabled?: boolean | undefined;
+        requiresFeature?: string | undefined;
+        epistemicDefault?: "OBSERVED" | "INFERRED" | "POLICY_CANDIDATE" | "REACHABLE" | "UNKNOWN" | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    entries: {
+        id: string;
+        capability: "subjects.get" | "subjects.list" | "subjects.query" | "subjects.getNexumSnapshot" | "estate.startSession" | "estate.getBag" | "estate.query" | "explore.query" | "catalog.describe";
+        description: string;
+        version: string;
+        enabled: boolean;
+        objectType?: string | undefined;
+        contentType?: string | undefined;
+        requiresFeature?: string | undefined;
+        epistemicDefault?: "OBSERVED" | "INFERRED" | "POLICY_CANDIDATE" | "REACHABLE" | "UNKNOWN" | undefined;
+    }[];
+    version: string;
+}, {
+    entries: {
+        id: string;
+        capability: "subjects.get" | "subjects.list" | "subjects.query" | "subjects.getNexumSnapshot" | "estate.startSession" | "estate.getBag" | "estate.query" | "explore.query" | "catalog.describe";
+        description: string;
+        version: string;
+        objectType?: string | undefined;
+        contentType?: string | undefined;
+        enabled?: boolean | undefined;
+        requiresFeature?: string | undefined;
+        epistemicDefault?: "OBSERVED" | "INFERRED" | "POLICY_CANDIDATE" | "REACHABLE" | "UNKNOWN" | undefined;
+    }[];
+    version: string;
+}>;
+export type Catalog = z.infer<typeof CatalogSchema>;
+export declare const RetrievalStepSchema: z.ZodObject<{
+    id: z.ZodString;
+    capability: z.ZodEnum<["subjects.get", "subjects.list", "subjects.query", "subjects.getNexumSnapshot", "estate.startSession", "estate.getBag", "estate.query", "explore.query", "catalog.describe"]>;
+    catalogEntryId: z.ZodString;
+    args: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    parallelGroup: z.ZodOptional<z.ZodString>;
+    required: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    capability: "subjects.get" | "subjects.list" | "subjects.query" | "subjects.getNexumSnapshot" | "estate.startSession" | "estate.getBag" | "estate.query" | "explore.query" | "catalog.describe";
+    catalogEntryId: string;
+    args: Record<string, unknown>;
+    required: boolean;
+    parallelGroup?: string | undefined;
+}, {
+    id: string;
+    capability: "subjects.get" | "subjects.list" | "subjects.query" | "subjects.getNexumSnapshot" | "estate.startSession" | "estate.getBag" | "estate.query" | "explore.query" | "catalog.describe";
+    catalogEntryId: string;
+    args?: Record<string, unknown> | undefined;
+    parallelGroup?: string | undefined;
+    required?: boolean | undefined;
+}>;
+export type RetrievalStep = z.infer<typeof RetrievalStepSchema>;
+export declare const EvidenceSelectionSchema: z.ZodObject<{
+    stepId: z.ZodString;
+    refs: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"subject">;
+        orgId: z.ZodString;
+        objectType: z.ZodString;
+        contentType: z.ZodString;
+        recordId: z.ZodString;
+        revision: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "subject";
+        orgId: string;
+        objectType: string;
+        contentType: string;
+        recordId: string;
+        revision?: string | number | undefined;
+    }, {
+        kind: "subject";
+        orgId: string;
+        objectType: string;
+        contentType: string;
+        recordId: string;
+        revision?: string | number | undefined;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"estate-bag">;
+        orgId: z.ZodString;
+        sessionId: z.ZodString;
+        bagId: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "estate-bag";
+        orgId: string;
+        sessionId: string;
+        bagId: string;
+        path?: string | undefined;
+    }, {
+        kind: "estate-bag";
+        orgId: string;
+        sessionId: string;
+        bagId: string;
+        path?: string | undefined;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"knowledge-explore">;
+        orgId: z.ZodString;
+        exploreQueryId: z.ZodString;
+        nodeIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "knowledge-explore";
+        orgId: string;
+        exploreQueryId: string;
+        nodeIds?: string[] | undefined;
+    }, {
+        kind: "knowledge-explore";
+        orgId: string;
+        exploreQueryId: string;
+        nodeIds?: string[] | undefined;
+    }>]>, "many">>;
+    maxItems: z.ZodOptional<z.ZodNumber>;
+    epistemic: z.ZodOptional<z.ZodEnum<["OBSERVED", "INFERRED", "POLICY_CANDIDATE", "REACHABLE", "UNKNOWN"]>>;
+    notes: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    stepId: string;
+    epistemic?: "OBSERVED" | "INFERRED" | "POLICY_CANDIDATE" | "REACHABLE" | "UNKNOWN" | undefined;
+    refs?: ({
+        kind: "subject";
+        orgId: string;
+        objectType: string;
+        contentType: string;
+        recordId: string;
+        revision?: string | number | undefined;
+    } | {
+        kind: "estate-bag";
+        orgId: string;
+        sessionId: string;
+        bagId: string;
+        path?: string | undefined;
+    } | {
+        kind: "knowledge-explore";
+        orgId: string;
+        exploreQueryId: string;
+        nodeIds?: string[] | undefined;
+    })[] | undefined;
+    maxItems?: number | undefined;
+    notes?: string | undefined;
+}, {
+    stepId: string;
+    epistemic?: "OBSERVED" | "INFERRED" | "POLICY_CANDIDATE" | "REACHABLE" | "UNKNOWN" | undefined;
+    refs?: ({
+        kind: "subject";
+        orgId: string;
+        objectType: string;
+        contentType: string;
+        recordId: string;
+        revision?: string | number | undefined;
+    } | {
+        kind: "estate-bag";
+        orgId: string;
+        sessionId: string;
+        bagId: string;
+        path?: string | undefined;
+    } | {
+        kind: "knowledge-explore";
+        orgId: string;
+        exploreQueryId: string;
+        nodeIds?: string[] | undefined;
+    })[] | undefined;
+    maxItems?: number | undefined;
+    notes?: string | undefined;
+}>;
+export type EvidenceSelection = z.infer<typeof EvidenceSelectionSchema>;
+export declare const RetrievalPlanSchema: z.ZodObject<{
+    planId: z.ZodString;
+    rationale: z.ZodString;
+    steps: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        capability: z.ZodEnum<["subjects.get", "subjects.list", "subjects.query", "subjects.getNexumSnapshot", "estate.startSession", "estate.getBag", "estate.query", "explore.query", "catalog.describe"]>;
+        catalogEntryId: z.ZodString;
+        args: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        parallelGroup: z.ZodOptional<z.ZodString>;
+        required: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        capability: "subjects.get" | "subjects.list" | "subjects.query" | "subjects.getNexumSnapshot" | "estate.startSession" | "estate.getBag" | "estate.query" | "explore.query" | "catalog.describe";
+        catalogEntryId: string;
+        args: Record<string, unknown>;
+        required: boolean;
+        parallelGroup?: string | undefined;
+    }, {
+        id: string;
+        capability: "subjects.get" | "subjects.list" | "subjects.query" | "subjects.getNexumSnapshot" | "estate.startSession" | "estate.getBag" | "estate.query" | "explore.query" | "catalog.describe";
+        catalogEntryId: string;
+        args?: Record<string, unknown> | undefined;
+        parallelGroup?: string | undefined;
+        required?: boolean | undefined;
+    }>, "many">;
+    selections: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        stepId: z.ZodString;
+        refs: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+            kind: z.ZodLiteral<"subject">;
+            orgId: z.ZodString;
+            objectType: z.ZodString;
+            contentType: z.ZodString;
+            recordId: z.ZodString;
+            revision: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+        }, "strip", z.ZodTypeAny, {
+            kind: "subject";
+            orgId: string;
+            objectType: string;
+            contentType: string;
+            recordId: string;
+            revision?: string | number | undefined;
+        }, {
+            kind: "subject";
+            orgId: string;
+            objectType: string;
+            contentType: string;
+            recordId: string;
+            revision?: string | number | undefined;
+        }>, z.ZodObject<{
+            kind: z.ZodLiteral<"estate-bag">;
+            orgId: z.ZodString;
+            sessionId: z.ZodString;
+            bagId: z.ZodString;
+            path: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            kind: "estate-bag";
+            orgId: string;
+            sessionId: string;
+            bagId: string;
+            path?: string | undefined;
+        }, {
+            kind: "estate-bag";
+            orgId: string;
+            sessionId: string;
+            bagId: string;
+            path?: string | undefined;
+        }>, z.ZodObject<{
+            kind: z.ZodLiteral<"knowledge-explore">;
+            orgId: z.ZodString;
+            exploreQueryId: z.ZodString;
+            nodeIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            kind: "knowledge-explore";
+            orgId: string;
+            exploreQueryId: string;
+            nodeIds?: string[] | undefined;
+        }, {
+            kind: "knowledge-explore";
+            orgId: string;
+            exploreQueryId: string;
+            nodeIds?: string[] | undefined;
+        }>]>, "many">>;
+        maxItems: z.ZodOptional<z.ZodNumber>;
+        epistemic: z.ZodOptional<z.ZodEnum<["OBSERVED", "INFERRED", "POLICY_CANDIDATE", "REACHABLE", "UNKNOWN"]>>;
+        notes: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        stepId: string;
+        epistemic?: "OBSERVED" | "INFERRED" | "POLICY_CANDIDATE" | "REACHABLE" | "UNKNOWN" | undefined;
+        refs?: ({
+            kind: "subject";
+            orgId: string;
+            objectType: string;
+            contentType: string;
+            recordId: string;
+            revision?: string | number | undefined;
+        } | {
+            kind: "estate-bag";
+            orgId: string;
+            sessionId: string;
+            bagId: string;
+            path?: string | undefined;
+        } | {
+            kind: "knowledge-explore";
+            orgId: string;
+            exploreQueryId: string;
+            nodeIds?: string[] | undefined;
+        })[] | undefined;
+        maxItems?: number | undefined;
+        notes?: string | undefined;
+    }, {
+        stepId: string;
+        epistemic?: "OBSERVED" | "INFERRED" | "POLICY_CANDIDATE" | "REACHABLE" | "UNKNOWN" | undefined;
+        refs?: ({
+            kind: "subject";
+            orgId: string;
+            objectType: string;
+            contentType: string;
+            recordId: string;
+            revision?: string | number | undefined;
+        } | {
+            kind: "estate-bag";
+            orgId: string;
+            sessionId: string;
+            bagId: string;
+            path?: string | undefined;
+        } | {
+            kind: "knowledge-explore";
+            orgId: string;
+            exploreQueryId: string;
+            nodeIds?: string[] | undefined;
+        })[] | undefined;
+        maxItems?: number | undefined;
+        notes?: string | undefined;
+    }>, "many">>;
+    answerDraft: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    planId: string;
+    rationale: string;
+    steps: {
+        id: string;
+        capability: "subjects.get" | "subjects.list" | "subjects.query" | "subjects.getNexumSnapshot" | "estate.startSession" | "estate.getBag" | "estate.query" | "explore.query" | "catalog.describe";
+        catalogEntryId: string;
+        args: Record<string, unknown>;
+        required: boolean;
+        parallelGroup?: string | undefined;
+    }[];
+    selections: {
+        stepId: string;
+        epistemic?: "OBSERVED" | "INFERRED" | "POLICY_CANDIDATE" | "REACHABLE" | "UNKNOWN" | undefined;
+        refs?: ({
+            kind: "subject";
+            orgId: string;
+            objectType: string;
+            contentType: string;
+            recordId: string;
+            revision?: string | number | undefined;
+        } | {
+            kind: "estate-bag";
+            orgId: string;
+            sessionId: string;
+            bagId: string;
+            path?: string | undefined;
+        } | {
+            kind: "knowledge-explore";
+            orgId: string;
+            exploreQueryId: string;
+            nodeIds?: string[] | undefined;
+        })[] | undefined;
+        maxItems?: number | undefined;
+        notes?: string | undefined;
+    }[];
+    answerDraft?: string | undefined;
+}, {
+    planId: string;
+    rationale: string;
+    steps: {
+        id: string;
+        capability: "subjects.get" | "subjects.list" | "subjects.query" | "subjects.getNexumSnapshot" | "estate.startSession" | "estate.getBag" | "estate.query" | "explore.query" | "catalog.describe";
+        catalogEntryId: string;
+        args?: Record<string, unknown> | undefined;
+        parallelGroup?: string | undefined;
+        required?: boolean | undefined;
+    }[];
+    selections?: {
+        stepId: string;
+        epistemic?: "OBSERVED" | "INFERRED" | "POLICY_CANDIDATE" | "REACHABLE" | "UNKNOWN" | undefined;
+        refs?: ({
+            kind: "subject";
+            orgId: string;
+            objectType: string;
+            contentType: string;
+            recordId: string;
+            revision?: string | number | undefined;
+        } | {
+            kind: "estate-bag";
+            orgId: string;
+            sessionId: string;
+            bagId: string;
+            path?: string | undefined;
+        } | {
+            kind: "knowledge-explore";
+            orgId: string;
+            exploreQueryId: string;
+            nodeIds?: string[] | undefined;
+        })[] | undefined;
+        maxItems?: number | undefined;
+        notes?: string | undefined;
+    }[] | undefined;
+    answerDraft?: string | undefined;
+}>;
+export type RetrievalPlan = z.infer<typeof RetrievalPlanSchema>;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/schemas/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/schemas/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,uBAAuB,0LAUlC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAY7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGxB,CAAC;AAEH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpD,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;EAO9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQlC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAM9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/schemas/catalog.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { EvidenceRefSchema } from "./evidence.js";
+export const CatalogCapabilitySchema = z.enum([
+    "subjects.get",
+    "subjects.list",
+    "subjects.query",
+    "subjects.getNexumSnapshot",
+    "estate.startSession",
+    "estate.getBag",
+    "estate.query",
+    "explore.query",
+    "catalog.describe",
+]);
+export const CatalogEntrySchema = z.object({
+    id: z.string().min(1),
+    capability: CatalogCapabilitySchema,
+    objectType: z.string().optional(),
+    contentType: z.string().optional(),
+    description: z.string().min(1),
+    version: z.string().min(1),
+    enabled: z.boolean().default(true),
+    requiresFeature: z.string().optional(),
+    epistemicDefault: z
+        .enum(["OBSERVED", "INFERRED", "POLICY_CANDIDATE", "REACHABLE", "UNKNOWN"])
+        .optional(),
+});
+export const CatalogSchema = z.object({
+    version: z.string().min(1),
+    entries: z.array(CatalogEntrySchema),
+});
+export const RetrievalStepSchema = z.object({
+    id: z.string().min(1),
+    capability: CatalogCapabilitySchema,
+    catalogEntryId: z.string().min(1),
+    args: z.record(z.unknown()).default({}),
+    parallelGroup: z.string().optional(),
+    required: z.boolean().default(true),
+});
+export const EvidenceSelectionSchema = z.object({
+    stepId: z.string().min(1),
+    refs: z.array(EvidenceRefSchema).optional(),
+    maxItems: z.number().int().positive().optional(),
+    epistemic: z
+        .enum(["OBSERVED", "INFERRED", "POLICY_CANDIDATE", "REACHABLE", "UNKNOWN"])
+        .optional(),
+    notes: z.string().optional(),
+});
+export const RetrievalPlanSchema = z.object({
+    planId: z.string().min(1),
+    rationale: z.string().min(1),
+    steps: z.array(RetrievalStepSchema).min(1),
+    selections: z.array(EvidenceSelectionSchema).default([]),
+    answerDraft: z.string().optional(),
+});
+//# sourceMappingURL=catalog.js.map

package/dist/schemas/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../src/schemas/catalog.ts"],"names":[],"mappings":"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"}