cvx-kit 0.1.19 → 0.1.21

package/README.md

@@ -156,6 +156,16 @@ public DTO or `null`. A many edge returns a bounded native page. Junction output
 preserves duplicate edge occurrences, even when target reads are memoized.
 Missing and unreadable targets have the same public result.
 
+`defineRelations` captures table names, stored field semantics, public DTO
+validation, variants, active indexes, and relation declarations. Complete schema
+and index configuration before calling it. Later changes to source declarations
+do not affect existing registries, helpers or engines. Create a new registry to
+adopt changes. Caller-owned declarations remain mutable.
+
+Relation DTOs support `.refine()`. They reject opaque `.superRefine()` and
+`.check()` callbacks; express those validations with `.refine()` instead.
+Captured callbacks still observe application state through their closures.
+
 Variant tables keep their discriminated public unions. Use the relation callback's
 second argument, `branch('payments', 'creditor_payment').creditorId`, for a
 branch-specific reference; its tag is checked before lookup. See the
@@ -220,7 +230,7 @@ usable equality prefix, then stable index-name order, with creation-time fallbac
 `order: 'desc'` reverses the chosen native index order. Native continuation,
 split/end cursors, and page status are preserved, with external tokens protected.
 
-Page sizes are positive integers up to 100; central `maxPageSize` may lower that
+Browse page sizes are positive integers up to 100; central `maxPageSize` may lower that
 ceiling. Central budgets bound read operations, index ranges, raw candidates,
 observed/reserved document bytes, fan-out, depth, and memo entries across a
 request, including policy reads. Native request read limits may lower ceilings.
@@ -232,9 +242,47 @@ many reads. Application/helper accounting does not measure physical platform I/O
 Kit auth query contexts carry the engine's private read capability. Unknown
 contexts fail closed unless a centrally configured trusted adapter attests their
 query reader, effective policy, and security scope. Mutation/action contexts,
-search/vector optimization, arbitrary predicates/projections,
+vector search, arbitrary predicates/projections,
 and custom sorts are outside this API.
 
+Root full-text search uses a declared native search index and keeps native relevance order:
+
+```ts
+const page = await querying(ctx).tasks
+ .search('search_text', input.text)
+ .where({ status: 'open' })
+ .include({ finance: 'if-permitted' })
+ .with({ labels: true })
+ .paginate({ numItems: 25, cursor: input.cursor, scanLimit: 250 })
+```
+
+Declare `search_text` on the exact native table registered in `relations`.
+Search supports the existing root filters, field groups and nested output;
+direct `.relation(...).search(...)` is unsupported. Nested relationship pages
+remain ordinary browse pages. Root search returns `paginationMode: 'native-search'`,
+null split metadata, and no caller-pinned `endCursor`, custom order or refill.
+A short or denied-empty page can still have `isDone: false`: continue manually
+with its `continueCursor` (or `usePaginatedList().fetchNextPage()`).
+
+Search `numItems` requests a positive integer initial native target, clamped by
+central limits and the remaining branch threshold. Live windows can return more raw rows.
+`scanLimit` is a cursor-branch admission threshold: all raw candidates, including
+denied rows, count in authenticated `seen` state. A whole window can overshoot
+(e.g. seen 6 + 5 rows with limit 9 returns all authorized rows, then stops with
+`result-cap`). Replaying a cursor repeats that branch; this is no global quota.
+Root search payload accounting is separate from shared policy/relationship read,
+byte, depth and fan-out budgets. Any unfinished nested read, policy exception or
+DTO failure aborts the whole page and mints no new continuation.
+
+Project errors explicitly at registered endpoint boundaries: ordinary `authQuery`
+handlers catch and throw `new ConvexError(queryFailureContract.project(error))`
+from `cvx-kit/querying`. Effect constructors configure
+`query: { errors: queryFailureContract }` and wrap the promise in
+`Effect.tryPromise({ try: () => /* search page */, catch: error => error })`.
+The declared contract sanitizes unknown failures; do not transport raw exceptions.
+See the [search contract](skills/cvx-kit/references/querying.md#root-full-text-search)
+and [React list protocol](skills/cvx-kit/references/client-list.md).
+
 For manual projection, `tasks.toPublicDto(row)` still omits IDs and unselected
 storage fields. `tasks.toPublicDto(row, true)` or `{ _id: true }` adds the branded
 ID only. Computed extensions use matching schemas:

package/dist/errors.d.mts

@@ -1,4 +1,5 @@
-import { DeclaredError, DeclaredFailure, DecodedFailure, ErrorContract, ErrorDefinitions, ErrorDetailParser, UnknownFailure, defineErrorContract } from "./modules/contracts/errors.mjs";
+import { DeclaredError, DeclaredFailure, DecodedFailure, ErrorContract, ErrorDefinitions, ErrorDetailParser, UnknownFailure, defineErrorContract, queryErrors } from "./modules/contracts/errors.mjs";
+import { FailureHandlers, decodeFailure, matchFailure } from "./react/failures.mjs";
 //#region src/errors.d.ts
 /** Structured application error carried across Convex function boundaries. */
 export declare class KitError extends Error {
@@ -21,5 +22,5 @@ export type ErrorFactory = {
 };
 export declare const defaultErrors: ErrorFactory;
 //#endregion
-export { type DeclaredError, type DeclaredFailure, type DecodedFailure, type ErrorContract, type ErrorDefinitions, type ErrorDetailParser, type UnknownFailure, defineErrorContract };
+export { type DeclaredError, type DeclaredFailure, type DecodedFailure, type ErrorContract, type ErrorDefinitions, type ErrorDetailParser, type FailureHandlers, type UnknownFailure, decodeFailure, defineErrorContract, matchFailure, queryErrors };
 //# sourceMappingURL=errors.d.mts.map

package/dist/errors.mjs

@@ -1,2 +1,2 @@
-import{defineErrorContract as e}from"./modules/contracts/errors.mjs";var t=class extends Error{code;constructor(e){super(e.message??e.code),this.name=`KitError`,this.code=e.code}};const n={throw(e){throw new t(e)}};export{t as KitError,n as defaultErrors,e as defineErrorContract};
+import{defineErrorContract as e,queryErrors as t}from"./modules/contracts/errors.mjs";import{decodeFailure as n,matchFailure as r}from"./react/failures.mjs";var i=class extends Error{code;constructor(e){super(e.message??e.code),this.name=`KitError`,this.code=e.code}};const a={throw(e){throw new i(e)}};export{i as KitError,n as decodeFailure,a as defaultErrors,e as defineErrorContract,r as matchFailure,t as queryErrors};
 //# sourceMappingURL=errors.mjs.map

package/dist/errors.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.mjs","names":["KitError","input","defaultErrors","defineErrorContract"],"sources":["../src/errors.ts"],"sourcesContent":["/** Structured application error carried across Convex function boundaries. */\nexport class KitError extends Error {\n\treadonly code: string\n\n\tconstructor(input: { code: string; message?: string }) {\n\t\tsuper(input.message ?? input.code)\n\t\tthis.name = 'KitError'\n\t\tthis.code = input.code\n\t}\n}\n\nexport {\n\tdefineErrorContract,\n\ttype ErrorContract,\n\ttype ErrorDefinitions,\n\ttype ErrorDetailParser,\n\ttype DeclaredError,\n\ttype DeclaredFailure,\n\ttype DecodedFailure,\n\ttype UnknownFailure,\n} from './modules/contracts/errors'\n\n/**\n * Injection seam for host error policy. Hosts with their own error taxonomy\n * (e.g. an App.errors singleton) adapt it to this shape; everyone else uses\n * the default factory below.\n */\nexport type ErrorFactory = {\n\tthrow(input: { code: string; message?: string }): never\n}\n\nexport const defaultErrors: ErrorFactory = {\n\tthrow(input) {\n\t\tthrow new KitError(input)\n\t},\n}\n"],"mappings":"qEACA,IAAaA,EAAb,cAA8B,KAAM,CACnC,KAEA,YAAY,EAA2C,CACtD,MAAMC,EAAM,SAAWA,EAAM,IAAI,EACjC,KAAK,KAAO,WACZ,KAAK,KAAOA,EAAM,IACnB,CACD,EAsBA,MAAaC,EAA8B,CAC1C,MAAM,EAAO,CACZ,MAAM,IAAIF,EAASC,CAAK,CACzB,CACD"}
+{"version":3,"file":"errors.mjs","names":["KitError","input","defaultErrors","decodeFailure","defineErrorContract","matchFailure","queryErrors"],"sources":["../src/errors.ts"],"sourcesContent":["/** Structured application error carried across Convex function boundaries. */\nexport class KitError extends Error {\n\treadonly code: string\n\n\tconstructor(input: { code: string; message?: string }) {\n\t\tsuper(input.message ?? input.code)\n\t\tthis.name = 'KitError'\n\t\tthis.code = input.code\n\t}\n}\n\nexport {\n\tdefineErrorContract,\n\tqueryErrors,\n\ttype ErrorContract,\n\ttype ErrorDefinitions,\n\ttype ErrorDetailParser,\n\ttype DeclaredError,\n\ttype DeclaredFailure,\n\ttype DecodedFailure,\n\ttype UnknownFailure,\n} from './modules/contracts/errors'\n\n/**\n * Injection seam for host error policy. Hosts with their own error taxonomy\n * (e.g. an App.errors singleton) adapt it to this shape; everyone else uses\n * the default factory below.\n */\nexport type ErrorFactory = {\n\tthrow(input: { code: string; message?: string }): never\n}\n\nexport const defaultErrors: ErrorFactory = {\n\tthrow(input) {\n\t\tthrow new KitError(input)\n\t},\n}\n\n// Pure helpers do not import React or server query-engine modules.\nexport { decodeFailure, matchFailure, type FailureHandlers } from './react/failures'\n"],"mappings":"6JACA,IAAaA,EAAb,cAA8B,KAAM,CACnC,KAEA,YAAY,EAA2C,CACtD,MAAMC,EAAM,SAAWA,EAAM,IAAI,EACjC,KAAK,KAAO,WACZ,KAAK,KAAOA,EAAM,IACnB,CACD,EAuBA,MAAaC,EAA8B,CAC1C,MAAM,EAAO,CACZ,MAAM,IAAIF,EAASC,CAAK,CACzB,CACD"}

package/dist/filters.d.mts

@@ -0,0 +1,4 @@
+import { FilterContract, FilterDescriptor, SharedField, SharedFilters, defineFilterContract } from "./querying/shared/contract.mjs";
+import { FilterAst, FilterOperator, FilterScalar } from "./querying/shared/ast.mjs";
+import { evaluateFilter } from "./querying/shared/evaluate.mjs";
+export { type FilterAst, type FilterContract, type FilterDescriptor, type FilterOperator, type FilterScalar, type SharedField, type SharedFilters, defineFilterContract, evaluateFilter };

package/dist/filters.mjs

@@ -0,0 +1 @@
+import{evaluateFilter as e}from"./querying/shared/evaluate.mjs";import{defineFilterContract as t}from"./querying/shared/contract.mjs";export{t as defineFilterContract,e as evaluateFilter};

package/dist/index.d.mts

@@ -1,17 +1,17 @@
 import { AgentToolHandlers, AgentToolRecord, createAgentTools } from "./agent-tools.mjs";
 import { ErrorFactory, KitError, defaultErrors } from "./errors.mjs";
+import { ScalarFilters, ScalarSelection, ServerFilter } from "./querying/filters.mjs";
+import { DtoOptions, TIMESTAMP_FIELDS, TableBoundaryOptions, createModule, createTable, jsonSafeZid, paginated, tenantTable, zodTable, zodVariantTable } from "./zod-table.mjs";
+import { FieldReference, RelationBuilder, RelationDeclarations, RelationEdge, RelationFilterSelection, RelationFilters, RelationRegistry, RelationRegistryIdentity, RelationRow, RelationSelection, RelationTable, RelationTableHelpers, RelationTables, ThroughReference, defineRelations } from "./relations.mjs";
 import { RLSConfig, Rules, TENANT_FIELD, assertTenantOwned, composeRules, createTenantRules, requireTenantReference } from "./tenancy.mjs";
 import { Actor, AuthBundle, AuthFunctions, AuthFunctionsConfig, DefaultRole, Include, IncludedQuery, SecurityConfig, createAuthFunctions, createInclude, defaultRoleMap } from "./auth.mjs";
 import { AnyQueryMiddleware, QueryMiddleware } from "./components/foundation/modules/query/query.mjs";
 import { AnyCommandMiddleware, ApplicationCommand, AuditEntryInput, AuditWriter, AuditedOperation, AuditedRegistry, CommandConstructor, CommandDefaults, CommandMiddleware, Foundation, FoundationOptions, PermissionChecker } from "./components/foundation/client.mjs";
 import { CrudConfig, createCrudCommands } from "./crud.mjs";
-import { ScalarFilters, ScalarSelection, ServerFilter } from "./querying/filters.mjs";
-import { DtoOptions, TIMESTAMP_FIELDS, TableBoundaryOptions, createModule, createTable, jsonSafeZid, paginated, tenantTable, zodTable, zodVariantTable } from "./zod-table.mjs";
 import { RateLimiterLike, rateLimit } from "./middleware.mjs";
 import { WebhookBoundaryConfig, createWebhookBoundary, recordWebhookEvent, webhookEventsTable } from "./webhooks.mjs";
 import { createStateMachine } from "./state-machine.mjs";
 import { Change, Trigger, Triggers, appendOnly, createTriggers, noDelete, tenantOwnership, timestamps } from "./triggers.mjs";
 import { FoundationRegistry, FoundationRegistryOptions, createFoundation } from "./modules/foundation/foundation.mjs";
-import { FieldReference, RelationBuilder, RelationDeclarations, RelationEdge, RelationFilterSelection, RelationFilters, RelationRegistry, RelationRegistryIdentity, RelationRow, RelationSelection, RelationTable, RelationTableHelpers, RelationTables, ThroughReference, defineRelations } from "./relations.mjs";
 import { QueryEngineConfig, createQueryEngine } from "./querying.mjs";
 export { type Actor, type AgentToolHandlers, type AgentToolRecord, type AnyCommandMiddleware, type AnyQueryMiddleware, type ApplicationCommand, type AuditEntryInput, type AuditWriter, type AuditedOperation, type AuditedRegistry, type AuthBundle, type AuthFunctions, type AuthFunctionsConfig, type Change, type CommandConstructor, type CommandDefaults, type CommandMiddleware, type CrudConfig, type DefaultRole, type DtoOptions, type ErrorFactory, type FieldReference, Foundation, type FoundationOptions, type FoundationRegistry, type FoundationRegistryOptions, type Include, type IncludedQuery, KitError, type PermissionChecker, type QueryEngineConfig, type QueryMiddleware, type RLSConfig, type RateLimiterLike, type RelationBuilder, type RelationDeclarations, type RelationEdge, type RelationFilterSelection, type RelationFilters, type RelationRegistry, type RelationRegistryIdentity, type RelationRow, type RelationSelection, type RelationTable, type RelationTableHelpers, type RelationTables, type Rules, type ScalarFilters, type ScalarSelection, type SecurityConfig, type ServerFilter, TENANT_FIELD, TIMESTAMP_FIELDS, type TableBoundaryOptions, type ThroughReference, type Trigger, Triggers, type WebhookBoundaryConfig, appendOnly, assertTenantOwned, composeRules, createAgentTools, createAuthFunctions, createCrudCommands, createFoundation, createInclude, createModule, createQueryEngine, createStateMachine, createTable, createTenantRules, createTriggers, createWebhookBoundary, defaultErrors, defaultRoleMap, defineRelations, jsonSafeZid, noDelete, paginated, rateLimit, recordWebhookEvent, requireTenantReference, tenantOwnership, tenantTable, timestamps, webhookEventsTable, zodTable, zodVariantTable };

package/dist/modules/contracts/errors.d.mts

@@ -39,5 +39,223 @@ export type ErrorContract<Definitions extends ErrorDefinitions> = Readonly<{
 }>;
 /** Closed safe codes, allowlisted details, and a versioned checked transport union. */
 export declare function defineErrorContract<const Definitions extends ErrorDefinitions>(definitions: Definitions): ErrorContract<Definitions>;
+/** Fixed, diagnostic-free transport shared by query endpoints and client recovery. */
+export declare const queryErrors: Readonly<{
+  create: <Key extends Code<{
+    readonly 'invalid-cursor': {
+      readonly message: "Invalid cursor";
+      readonly details: {};
+    };
+    readonly FIELD_GROUP_DENIED: {
+      readonly message: "Field group access denied";
+      readonly details: {};
+    };
+    readonly QUERY_FANOUT: {
+      readonly message: "Query fan-out limit exceeded";
+      readonly details: {};
+    };
+    readonly SEARCH_TEXT_REQUIRED: {
+      readonly message: "Search text required";
+      readonly details: {};
+    };
+    readonly SEARCH_END_CURSOR_UNSUPPORTED: {
+      readonly message: "Search end cursor unsupported";
+      readonly details: {};
+    };
+    readonly SEARCH_ORDER_UNSUPPORTED: {
+      readonly message: "Search ordering unsupported";
+      readonly details: {};
+    };
+    readonly SEARCH_RELATION_UNSUPPORTED: {
+      readonly message: "Relation search unsupported";
+      readonly details: {};
+    };
+    readonly SEARCH_OPTIONS_UNSUPPORTED: {
+      readonly message: "Search options unsupported";
+      readonly details: {};
+    };
+    readonly SEARCH_PROTOCOL_UNSUPPORTED: {
+      readonly message: "Search pagination protocol unsupported";
+      readonly details: {};
+    };
+  }>>(code: Key, details: Details<{
+    readonly 'invalid-cursor': {
+      readonly message: "Invalid cursor";
+      readonly details: {};
+    };
+    readonly FIELD_GROUP_DENIED: {
+      readonly message: "Field group access denied";
+      readonly details: {};
+    };
+    readonly QUERY_FANOUT: {
+      readonly message: "Query fan-out limit exceeded";
+      readonly details: {};
+    };
+    readonly SEARCH_TEXT_REQUIRED: {
+      readonly message: "Search text required";
+      readonly details: {};
+    };
+    readonly SEARCH_END_CURSOR_UNSUPPORTED: {
+      readonly message: "Search end cursor unsupported";
+      readonly details: {};
+    };
+    readonly SEARCH_ORDER_UNSUPPORTED: {
+      readonly message: "Search ordering unsupported";
+      readonly details: {};
+    };
+    readonly SEARCH_RELATION_UNSUPPORTED: {
+      readonly message: "Relation search unsupported";
+      readonly details: {};
+    };
+    readonly SEARCH_OPTIONS_UNSUPPORTED: {
+      readonly message: "Search options unsupported";
+      readonly details: {};
+    };
+    readonly SEARCH_PROTOCOL_UNSUPPORTED: {
+      readonly message: "Search pagination protocol unsupported";
+      readonly details: {};
+    };
+  }[NoInfer<Key>]>) => Extract<Readonly<{
+    _tag: 'DeclaredError';
+    code: "FIELD_GROUP_DENIED";
+    details: {};
+    [declaredErrorBrand]: true;
+  }>, {
+    code: Key;
+  }> | Extract<Readonly<{
+    _tag: 'DeclaredError';
+    code: "QUERY_FANOUT";
+    details: {};
+    [declaredErrorBrand]: true;
+  }>, {
+    code: Key;
+  }> | Extract<Readonly<{
+    _tag: 'DeclaredError';
+    code: "SEARCH_END_CURSOR_UNSUPPORTED";
+    details: {};
+    [declaredErrorBrand]: true;
+  }>, {
+    code: Key;
+  }> | Extract<Readonly<{
+    _tag: 'DeclaredError';
+    code: "SEARCH_OPTIONS_UNSUPPORTED";
+    details: {};
+    [declaredErrorBrand]: true;
+  }>, {
+    code: Key;
+  }> | Extract<Readonly<{
+    _tag: 'DeclaredError';
+    code: "SEARCH_ORDER_UNSUPPORTED";
+    details: {};
+    [declaredErrorBrand]: true;
+  }>, {
+    code: Key;
+  }> | Extract<Readonly<{
+    _tag: 'DeclaredError';
+    code: "SEARCH_PROTOCOL_UNSUPPORTED";
+    details: {};
+    [declaredErrorBrand]: true;
+  }>, {
+    code: Key;
+  }> | Extract<Readonly<{
+    _tag: 'DeclaredError';
+    code: "SEARCH_RELATION_UNSUPPORTED";
+    details: {};
+    [declaredErrorBrand]: true;
+  }>, {
+    code: Key;
+  }> | Extract<Readonly<{
+    _tag: 'DeclaredError';
+    code: "SEARCH_TEXT_REQUIRED";
+    details: {};
+    [declaredErrorBrand]: true;
+  }>, {
+    code: Key;
+  }> | Extract<Readonly<{
+    _tag: 'DeclaredError';
+    code: "invalid-cursor";
+    details: {};
+    [declaredErrorBrand]: true;
+  }>, {
+    code: Key;
+  }>;
+  project: (error: unknown) => DecodedFailure<{
+    readonly 'invalid-cursor': {
+      readonly message: "Invalid cursor";
+      readonly details: {};
+    };
+    readonly FIELD_GROUP_DENIED: {
+      readonly message: "Field group access denied";
+      readonly details: {};
+    };
+    readonly QUERY_FANOUT: {
+      readonly message: "Query fan-out limit exceeded";
+      readonly details: {};
+    };
+    readonly SEARCH_TEXT_REQUIRED: {
+      readonly message: "Search text required";
+      readonly details: {};
+    };
+    readonly SEARCH_END_CURSOR_UNSUPPORTED: {
+      readonly message: "Search end cursor unsupported";
+      readonly details: {};
+    };
+    readonly SEARCH_ORDER_UNSUPPORTED: {
+      readonly message: "Search ordering unsupported";
+      readonly details: {};
+    };
+    readonly SEARCH_RELATION_UNSUPPORTED: {
+      readonly message: "Relation search unsupported";
+      readonly details: {};
+    };
+    readonly SEARCH_OPTIONS_UNSUPPORTED: {
+      readonly message: "Search options unsupported";
+      readonly details: {};
+    };
+    readonly SEARCH_PROTOCOL_UNSUPPORTED: {
+      readonly message: "Search pagination protocol unsupported";
+      readonly details: {};
+    };
+  }>;
+  /** Receives envelope data, e.g. ConvexError.data; never parses error messages. */
+  decode: (payload: unknown) => DecodedFailure<{
+    readonly 'invalid-cursor': {
+      readonly message: "Invalid cursor";
+      readonly details: {};
+    };
+    readonly FIELD_GROUP_DENIED: {
+      readonly message: "Field group access denied";
+      readonly details: {};
+    };
+    readonly QUERY_FANOUT: {
+      readonly message: "Query fan-out limit exceeded";
+      readonly details: {};
+    };
+    readonly SEARCH_TEXT_REQUIRED: {
+      readonly message: "Search text required";
+      readonly details: {};
+    };
+    readonly SEARCH_END_CURSOR_UNSUPPORTED: {
+      readonly message: "Search end cursor unsupported";
+      readonly details: {};
+    };
+    readonly SEARCH_ORDER_UNSUPPORTED: {
+      readonly message: "Search ordering unsupported";
+      readonly details: {};
+    };
+    readonly SEARCH_RELATION_UNSUPPORTED: {
+      readonly message: "Relation search unsupported";
+      readonly details: {};
+    };
+    readonly SEARCH_OPTIONS_UNSUPPORTED: {
+      readonly message: "Search options unsupported";
+      readonly details: {};
+    };
+    readonly SEARCH_PROTOCOL_UNSUPPORTED: {
+      readonly message: "Search pagination protocol unsupported";
+      readonly details: {};
+    };
+  }>;
+}>;
 //#endregion
 //# sourceMappingURL=errors.d.mts.map

package/dist/modules/contracts/errors.mjs

@@ -1,2 +1,2 @@
-const e=Object.freeze({_tag:`UnknownFailure`,version:1});function t(t){let a=Object.fromEntries(Object.entries(t).map(([e,t])=>{if(!e||!t.message||t.message.length>200)throw Error(`Declared errors require a code and a public message of 1–200 characters`);return[e,{message:t.message,details:{...t.details}}]})),o=/* @__PURE__ */ new WeakMap;return{create(e,t){let n;try{if(!Object.hasOwn(a,e))throw Error(`Undeclared code`);let r=a[e];n={_tag:`DeclaredFailure`,version:1,code:e,message:r.message,details:i(r,t,!1)}}catch{throw Error(`Invalid declared error details`)}let s=Object.freeze({_tag:`DeclaredError`,code:e,details:r(n.details)});return o.set(s,n),s},project(t){if(typeof t!=`object`||!t)return e;let n=o.get(t);return n?r(n):e},decode(t){try{if(!n(t)||t._tag!==`DeclaredFailure`||t.version!==1||typeof t.code!=`string`||!Object.hasOwn(a,t.code)||Object.keys(t).length!==5||![`message`,`details`,`_tag`,`version`,`code`].every(e=>Object.hasOwn(t,e)))return e;let o=a[t.code];return t.message===o.message?(r(t.details),{_tag:`DeclaredFailure`,version:1,code:t.code,message:o.message,details:i(o,t.details,!0)}):e}catch{return e}}}}function n(e){if(typeof e!=`object`||!e||Array.isArray(e))return!1;let t=Object.getPrototypeOf(e);return t===Object.prototype||t===null}function r(e,t=/* @__PURE__ */ new Set){if(e===null||typeof e==`string`||typeof e==`boolean`||typeof e==`number`&&Number.isFinite(e))return e;if(typeof e!=`object`||!e||t.has(e))throw Error(`Invalid JSON`);t.add(e);try{if(Array.isArray(e)){let n=[];for(let i=0;i<e.length;i++)n.push(r(e[i],t));return n}if(!n(e))throw Error(`Invalid JSON`);return Object.fromEntries(Object.entries(e).map(([e,n])=>[e,r(n,t)]))}finally{t.delete(e)}}function i(e,t,i){if(!n(t))throw Error(`Invalid details`);let a=Object.keys(e.details);if(i&&Object.keys(t).some(t=>!Object.hasOwn(e.details,t)))throw Error(`Undeclared detail`);return Object.fromEntries(a.map(n=>{if(!Object.hasOwn(t,n))throw Error(`Missing detail`);return[n,r(e.details[n].parse(t[n]))]}))}export{t as defineErrorContract};
+const e=Object.freeze({_tag:`UnknownFailure`,version:1});function t(t){let n=Object.fromEntries(Object.entries(t).map(([e,t])=>{if(!e||!t.message||t.message.length>200)throw Error(`Declared errors require a code and a public message of 1–200 characters`);return[e,{message:t.message,details:{...t.details}}]})),o=/* @__PURE__ */ new WeakMap;return{create(e,t){let r;try{if(!Object.hasOwn(n,e))throw Error(`Undeclared code`);let i=n[e];r={_tag:`DeclaredFailure`,version:1,code:e,message:i.message,details:a(i,t,!1)}}catch{throw Error(`Invalid declared error details`)}let s=Object.freeze({_tag:`DeclaredError`,code:e,details:i(r.details)});return o.set(s,r),s},project(t){if(typeof t!=`object`||!t)return e;let n=o.get(t);return n?i(n):e},decode(t){try{if(!r(t)||t._tag!==`DeclaredFailure`||t.version!==1||typeof t.code!=`string`||!Object.hasOwn(n,t.code)||Object.keys(t).length!==5||![`message`,`details`,`_tag`,`version`,`code`].every(e=>Object.hasOwn(t,e)))return e;let o=n[t.code];return t.message===o.message?(i(t.details),{_tag:`DeclaredFailure`,version:1,code:t.code,message:o.message,details:a(o,t.details,!0)}):e}catch{return e}}}}const n=t({"invalid-cursor":{message:`Invalid cursor`,details:{}},FIELD_GROUP_DENIED:{message:`Field group access denied`,details:{}},QUERY_FANOUT:{message:`Query fan-out limit exceeded`,details:{}},SEARCH_TEXT_REQUIRED:{message:`Search text required`,details:{}},SEARCH_END_CURSOR_UNSUPPORTED:{message:`Search end cursor unsupported`,details:{}},SEARCH_ORDER_UNSUPPORTED:{message:`Search ordering unsupported`,details:{}},SEARCH_RELATION_UNSUPPORTED:{message:`Relation search unsupported`,details:{}},SEARCH_OPTIONS_UNSUPPORTED:{message:`Search options unsupported`,details:{}},SEARCH_PROTOCOL_UNSUPPORTED:{message:`Search pagination protocol unsupported`,details:{}}});function r(e){if(typeof e!=`object`||!e||Array.isArray(e))return!1;let t=Object.getPrototypeOf(e);return t===Object.prototype||t===null}function i(e,t=/* @__PURE__ */ new Set){if(e===null||typeof e==`string`||typeof e==`boolean`||typeof e==`number`&&Number.isFinite(e))return e;if(typeof e!=`object`||!e||t.has(e))throw Error(`Invalid JSON`);t.add(e);try{if(Array.isArray(e)){let n=[];for(let r=0;r<e.length;r++)n.push(i(e[r],t));return n}if(!r(e))throw Error(`Invalid JSON`);return Object.fromEntries(Object.entries(e).map(([e,n])=>[e,i(n,t)]))}finally{t.delete(e)}}function a(e,t,n){if(!r(t))throw Error(`Invalid details`);let a=Object.keys(e.details);if(n&&Object.keys(t).some(t=>!Object.hasOwn(e.details,t)))throw Error(`Undeclared detail`);return Object.fromEntries(a.map(n=>{if(!Object.hasOwn(t,n))throw Error(`Missing detail`);return[n,i(e.details[n].parse(t[n]))]}))}export{t as defineErrorContract,n as queryErrors};
 //# sourceMappingURL=errors.mjs.map

package/dist/modules/contracts/errors.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.mjs","names":["unknownFailure","defineErrorContract","declarations","definitions","code","definition","trusted","envelope","parseDetails","details","error","copyJson","isRecord","payload","key","value","prototype","ancestors","result","index","child","fields","strict","field"],"sources":["../../../src/modules/contracts/errors.ts"],"sourcesContent":["/* oxlint-disable anti-slop/no-unknown-parameters, anti-slop/no-unknown-returns, anti-slop/no-unknown-type-aliases, anti-slop/no-runtime-typeof, anti-slop/no-unsafe-dictionary-type -- This neutral contract validates unknown transport data and an explicitly keyed code/detail declaration. */\n\n/** Explicit synchronous validators for the final public detail representation. */\nexport type ErrorDetailParser<Output = unknown> = Readonly<{\n\tparse: (value: unknown) => Output\n}>\n\nexport type ErrorDefinitions = Readonly<\n\tRecord<\n\t\tstring,\n\t\tReadonly<{\n\t\t\tmessage: string\n\t\t\tdetails: Readonly<Record<string, ErrorDetailParser>>\n\t\t}>\n\t>\n>\n\ntype Code<Definitions extends ErrorDefinitions> = Extract<keyof Definitions, string>\ntype Details<Definition extends ErrorDefinitions[string]> =\n\tDefinition extends ErrorDefinitions[string]\n\t\t? { [Field in keyof Definition['details']]: ReturnType<Definition['details'][Field]['parse']> }\n\t\t: never\n\ndeclare const declaredErrorBrand: unique symbol\n\n/** Server failures are trusted only by the contract that created them. */\nexport type DeclaredError<Definitions extends ErrorDefinitions> = {\n\t[Key in Code<Definitions>]: Readonly<{\n\t\t_tag: 'DeclaredError'\n\t\tcode: Key\n\t\tdetails: Details<Definitions[Key]>\n\t\t[declaredErrorBrand]: true\n\t}>\n}[Code<Definitions>]\n\nexport type DeclaredFailure<Definitions extends ErrorDefinitions> = {\n\t[Key in Code<Definitions>]: Readonly<{\n\t\t_tag: 'DeclaredFailure'\n\t\tversion: 1\n\t\tcode: Key\n\t\tmessage: string\n\t\tdetails: Details<Definitions[Key]>\n\t}>\n}[Code<Definitions>]\n\nexport type UnknownFailure = Readonly<{ _tag: 'UnknownFailure'; version: 1 }>\nexport type DecodedFailure<Definitions extends ErrorDefinitions> =\n\t| DeclaredFailure<Definitions>\n\t| UnknownFailure\n\nexport type ErrorContract<Definitions extends ErrorDefinitions> = Readonly<{\n\tcreate: <Key extends Code<Definitions>>(\n\t\tcode: Key,\n\t\tdetails: Details<Definitions[NoInfer<Key>]>,\n\t) => Extract<DeclaredError<Definitions>, { code: Key }>\n\tproject: (error: unknown) => DecodedFailure<Definitions>\n\t/** Receives envelope data, e.g. ConvexError.data; never parses error messages. */\n\tdecode: (payload: unknown) => DecodedFailure<Definitions>\n}>\n\nconst unknownFailure: UnknownFailure = Object.freeze({ _tag: 'UnknownFailure', version: 1 })\ntype Json = null | boolean | number | string | Json[] | { [key: string]: Json }\n\n/** Closed safe codes, allowlisted details, and a versioned checked transport union. */\nexport function defineErrorContract<const Definitions extends ErrorDefinitions>(\n\tdefinitions: Definitions,\n): ErrorContract<Definitions> {\n\t// SAFETY: the snapshot copies every declaration without changing its code, message or paired parsers.\n\tconst declarations = Object.fromEntries(\n\t\tObject.entries(definitions).map(([code, definition]) => {\n\t\t\tif (!code || !definition.message || definition.message.length > 200) {\n\t\t\t\tthrow Error('Declared errors require a code and a public message of 1–200 characters')\n\t\t\t}\n\t\t\treturn [code, { message: definition.message, details: { ...definition.details } }]\n\t\t}),\n\t) as Definitions\n\tconst trusted = new WeakMap<object, DeclaredFailure<Definitions>>()\n\treturn {\n\t\tcreate(code, details) {\n\t\t\tlet envelope: DeclaredFailure<Definitions>\n\t\t\ttry {\n\t\t\t\tif (!Object.hasOwn(declarations, code)) throw Error('Undeclared code')\n\t\t\t\tconst definition = declarations[code]\n\t\t\t\t// SAFETY: the selected closed declaration validates every field before construction.\n\t\t\t\tenvelope = {\n\t\t\t\t\t_tag: 'DeclaredFailure',\n\t\t\t\t\tversion: 1,\n\t\t\t\t\tcode,\n\t\t\t\t\tmessage: definition.message,\n\t\t\t\t\tdetails: parseDetails(definition, details, false),\n\t\t\t\t} as DeclaredFailure<Definitions>\n\t\t\t} catch {\n\t\t\t\t// Validator messages, issue paths and provider causes remain private.\n\t\t\t\tthrow Error('Invalid declared error details')\n\t\t\t}\n\t\t\t// SAFETY: identity is registered below; the inaccessible brand cannot confer trust by itself.\n\t\t\tconst error = Object.freeze({\n\t\t\t\t_tag: 'DeclaredError',\n\t\t\t\tcode,\n\t\t\t\tdetails: copyJson(envelope.details),\n\t\t\t}) as Extract<DeclaredError<Definitions>, { code: typeof code }>\n\t\t\ttrusted.set(error, envelope)\n\t\t\treturn error\n\t\t},\n\t\tproject(error) {\n\t\t\tif (error === null || typeof error !== 'object') return unknownFailure\n\t\t\tconst envelope = trusted.get(error)\n\t\t\t// SAFETY: only validated contract-owned envelopes enter the private map.\n\t\t\treturn envelope ? (copyJson(envelope) as DeclaredFailure<Definitions>) : unknownFailure\n\t\t},\n\t\tdecode(payload) {\n\t\t\ttry {\n\t\t\t\tif (\n\t\t\t\t\t!isRecord(payload) ||\n\t\t\t\t\tpayload._tag !== 'DeclaredFailure' ||\n\t\t\t\t\tpayload.version !== 1 ||\n\t\t\t\t\ttypeof payload.code !== 'string' ||\n\t\t\t\t\t!Object.hasOwn(declarations, payload.code) ||\n\t\t\t\t\tObject.keys(payload).length !== 5 ||\n\t\t\t\t\t!['message', 'details', '_tag', 'version', 'code'].every((key) =>\n\t\t\t\t\t\tObject.hasOwn(payload, key),\n\t\t\t\t\t)\n\t\t\t\t) {\n\t\t\t\t\treturn unknownFailure\n\t\t\t\t}\n\t\t\t\tconst definition = declarations[payload.code]\n\t\t\t\tif (payload.message !== definition.message) return unknownFailure\n\t\t\t\t// Validate raw transport JSON too: parsers must not hide non-JSON payloads.\n\t\t\t\tcopyJson(payload.details)\n\t\t\t\t// SAFETY: code membership and every allowlisted field have been checked independently.\n\t\t\t\treturn {\n\t\t\t\t\t_tag: 'DeclaredFailure',\n\t\t\t\t\tversion: 1,\n\t\t\t\t\tcode: payload.code,\n\t\t\t\t\tmessage: definition.message,\n\t\t\t\t\tdetails: parseDetails(definition, payload.details, true),\n\t\t\t\t} as DeclaredFailure<Definitions>\n\t\t\t} catch {\n\t\t\t\treturn unknownFailure\n\t\t\t}\n\t\t},\n\t}\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\tif (value === null || typeof value !== 'object' || Array.isArray(value)) return false\n\tconst prototype = Object.getPrototypeOf(value)\n\treturn prototype === Object.prototype || prototype === null\n}\n\n/** Copy data without invoking toJSON or retaining mutable provider objects. */\nfunction copyJson(value: unknown, ancestors = new Set<object>()): Json {\n\tif (value === null || typeof value === 'string' || typeof value === 'boolean') return value\n\tif (typeof value === 'number' && Number.isFinite(value)) return value\n\tif (typeof value !== 'object' || value === null || ancestors.has(value))\n\t\tthrow Error('Invalid JSON')\n\tancestors.add(value)\n\ttry {\n\t\tif (Array.isArray(value)) {\n\t\t\tconst result: Json[] = []\n\t\t\tfor (let index = 0; index < value.length; index++)\n\t\t\t\tresult.push(copyJson(value[index], ancestors))\n\t\t\treturn result\n\t\t}\n\t\tif (!isRecord(value)) throw Error('Invalid JSON')\n\t\treturn Object.fromEntries(\n\t\t\tObject.entries(value).map(([key, child]) => [key, copyJson(child, ancestors)]),\n\t\t)\n\t} finally {\n\t\tancestors.delete(value)\n\t}\n}\n\nfunction parseDetails<const Definition extends ErrorDefinitions[string]>(\n\tdefinition: Definition,\n\tvalue: unknown,\n\tstrict: boolean,\n): Details<Definition> {\n\tif (!isRecord(value)) throw Error('Invalid details')\n\tconst fields = Object.keys(definition.details)\n\tif (strict && Object.keys(value).some((key) => !Object.hasOwn(definition.details, key))) {\n\t\tthrow Error('Undeclared detail')\n\t}\n\t// SAFETY: each declared field is validated by its paired parser before its JSON-safe copy is returned.\n\treturn Object.fromEntries(\n\t\tfields.map((field) => {\n\t\t\tif (!Object.hasOwn(value, field)) throw Error('Missing detail')\n\t\t\treturn [field, copyJson(definition.details[field].parse(value[field]))]\n\t\t}),\n\t) as Details<Definition>\n}\n"],"mappings":"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"}
+{"version":3,"file":"errors.mjs","names":["unknownFailure","defineErrorContract","declarations","definitions","code","definition","trusted","envelope","parseDetails","details","error","copyJson","isRecord","payload","key","queryErrors","value","prototype","ancestors","result","index","child","fields","strict","field"],"sources":["../../../src/modules/contracts/errors.ts"],"sourcesContent":["/* oxlint-disable anti-slop/no-unknown-parameters, anti-slop/no-unknown-returns, anti-slop/no-unknown-type-aliases, anti-slop/no-runtime-typeof, anti-slop/no-unsafe-dictionary-type -- This neutral contract validates unknown transport data and an explicitly keyed code/detail declaration. */\n\n/** Explicit synchronous validators for the final public detail representation. */\nexport type ErrorDetailParser<Output = unknown> = Readonly<{\n\tparse: (value: unknown) => Output\n}>\n\nexport type ErrorDefinitions = Readonly<\n\tRecord<\n\t\tstring,\n\t\tReadonly<{\n\t\t\tmessage: string\n\t\t\tdetails: Readonly<Record<string, ErrorDetailParser>>\n\t\t}>\n\t>\n>\n\ntype Code<Definitions extends ErrorDefinitions> = Extract<keyof Definitions, string>\ntype Details<Definition extends ErrorDefinitions[string]> =\n\tDefinition extends ErrorDefinitions[string]\n\t\t? { [Field in keyof Definition['details']]: ReturnType<Definition['details'][Field]['parse']> }\n\t\t: never\n\ndeclare const declaredErrorBrand: unique symbol\n\n/** Server failures are trusted only by the contract that created them. */\nexport type DeclaredError<Definitions extends ErrorDefinitions> = {\n\t[Key in Code<Definitions>]: Readonly<{\n\t\t_tag: 'DeclaredError'\n\t\tcode: Key\n\t\tdetails: Details<Definitions[Key]>\n\t\t[declaredErrorBrand]: true\n\t}>\n}[Code<Definitions>]\n\nexport type DeclaredFailure<Definitions extends ErrorDefinitions> = {\n\t[Key in Code<Definitions>]: Readonly<{\n\t\t_tag: 'DeclaredFailure'\n\t\tversion: 1\n\t\tcode: Key\n\t\tmessage: string\n\t\tdetails: Details<Definitions[Key]>\n\t}>\n}[Code<Definitions>]\n\nexport type UnknownFailure = Readonly<{ _tag: 'UnknownFailure'; version: 1 }>\nexport type DecodedFailure<Definitions extends ErrorDefinitions> =\n\tDeclaredFailure<Definitions> | UnknownFailure\n\nexport type ErrorContract<Definitions extends ErrorDefinitions> = Readonly<{\n\tcreate: <Key extends Code<Definitions>>(\n\t\tcode: Key,\n\t\tdetails: Details<Definitions[NoInfer<Key>]>,\n\t) => Extract<DeclaredError<Definitions>, { code: Key }>\n\tproject: (error: unknown) => DecodedFailure<Definitions>\n\t/** Receives envelope data, e.g. ConvexError.data; never parses error messages. */\n\tdecode: (payload: unknown) => DecodedFailure<Definitions>\n}>\n\nconst unknownFailure: UnknownFailure = Object.freeze({\n\t_tag: 'UnknownFailure',\n\tversion: 1,\n})\ntype Json = null | boolean | number | string | Json[] | { [key: string]: Json }\n\n/** Closed safe codes, allowlisted details, and a versioned checked transport union. */\nexport function defineErrorContract<const Definitions extends ErrorDefinitions>(\n\tdefinitions: Definitions,\n): ErrorContract<Definitions> {\n\t// SAFETY: the snapshot copies every declaration without changing its code, message or paired parsers.\n\tconst declarations = Object.fromEntries(\n\t\tObject.entries(definitions).map(([code, definition]) => {\n\t\t\tif (!code || !definition.message || definition.message.length > 200) {\n\t\t\t\tthrow Error('Declared errors require a code and a public message of 1–200 characters')\n\t\t\t}\n\t\t\treturn [code, { message: definition.message, details: { ...definition.details } }]\n\t\t}),\n\t) as Definitions\n\tconst trusted = new WeakMap<object, DeclaredFailure<Definitions>>()\n\treturn {\n\t\tcreate(code, details) {\n\t\t\tlet envelope: DeclaredFailure<Definitions>\n\t\t\ttry {\n\t\t\t\tif (!Object.hasOwn(declarations, code)) throw Error('Undeclared code')\n\t\t\t\tconst definition = declarations[code]\n\t\t\t\t// SAFETY: the selected closed declaration validates every field before construction.\n\t\t\t\tenvelope = {\n\t\t\t\t\t_tag: 'DeclaredFailure',\n\t\t\t\t\tversion: 1,\n\t\t\t\t\tcode,\n\t\t\t\t\tmessage: definition.message,\n\t\t\t\t\tdetails: parseDetails(definition, details, false),\n\t\t\t\t} as DeclaredFailure<Definitions>\n\t\t\t} catch {\n\t\t\t\t// Validator messages, issue paths and provider causes remain private.\n\t\t\t\tthrow Error('Invalid declared error details')\n\t\t\t}\n\t\t\t// SAFETY: identity is registered below; the inaccessible brand cannot confer trust by itself.\n\t\t\tconst error = Object.freeze({\n\t\t\t\t_tag: 'DeclaredError',\n\t\t\t\tcode,\n\t\t\t\tdetails: copyJson(envelope.details),\n\t\t\t}) as Extract<DeclaredError<Definitions>, { code: typeof code }>\n\t\t\ttrusted.set(error, envelope)\n\t\t\treturn error\n\t\t},\n\t\tproject(error) {\n\t\t\tif (error === null || typeof error !== 'object') return unknownFailure\n\t\t\tconst envelope = trusted.get(error)\n\t\t\t// SAFETY: only validated contract-owned envelopes enter the private map.\n\t\t\treturn envelope ? (copyJson(envelope) as DeclaredFailure<Definitions>) : unknownFailure\n\t\t},\n\t\tdecode(payload) {\n\t\t\ttry {\n\t\t\t\tif (\n\t\t\t\t\t!isRecord(payload) ||\n\t\t\t\t\tpayload._tag !== 'DeclaredFailure' ||\n\t\t\t\t\tpayload.version !== 1 ||\n\t\t\t\t\ttypeof payload.code !== 'string' ||\n\t\t\t\t\t!Object.hasOwn(declarations, payload.code) ||\n\t\t\t\t\tObject.keys(payload).length !== 5 ||\n\t\t\t\t\t!['message', 'details', '_tag', 'version', 'code'].every((key) =>\n\t\t\t\t\t\tObject.hasOwn(payload, key),\n\t\t\t\t\t)\n\t\t\t\t) {\n\t\t\t\t\treturn unknownFailure\n\t\t\t\t}\n\t\t\t\tconst definition = declarations[payload.code]\n\t\t\t\tif (payload.message !== definition.message) return unknownFailure\n\t\t\t\t// Validate raw transport JSON too: parsers must not hide non-JSON payloads.\n\t\t\t\tcopyJson(payload.details)\n\t\t\t\t// SAFETY: code membership and every allowlisted field have been checked independently.\n\t\t\t\treturn {\n\t\t\t\t\t_tag: 'DeclaredFailure',\n\t\t\t\t\tversion: 1,\n\t\t\t\t\tcode: payload.code,\n\t\t\t\t\tmessage: definition.message,\n\t\t\t\t\tdetails: parseDetails(definition, payload.details, true),\n\t\t\t\t} as DeclaredFailure<Definitions>\n\t\t\t} catch {\n\t\t\t\treturn unknownFailure\n\t\t\t}\n\t\t},\n\t}\n}\n\n/** Fixed, diagnostic-free transport shared by query endpoints and client recovery. */\nexport const queryErrors = defineErrorContract({\n\t'invalid-cursor': { message: 'Invalid cursor', details: {} },\n\tFIELD_GROUP_DENIED: { message: 'Field group access denied', details: {} },\n\tQUERY_FANOUT: { message: 'Query fan-out limit exceeded', details: {} },\n\tSEARCH_TEXT_REQUIRED: { message: 'Search text required', details: {} },\n\tSEARCH_END_CURSOR_UNSUPPORTED: {\n\t\tmessage: 'Search end cursor unsupported',\n\t\tdetails: {},\n\t},\n\tSEARCH_ORDER_UNSUPPORTED: {\n\t\tmessage: 'Search ordering unsupported',\n\t\tdetails: {},\n\t},\n\tSEARCH_RELATION_UNSUPPORTED: {\n\t\tmessage: 'Relation search unsupported',\n\t\tdetails: {},\n\t},\n\tSEARCH_OPTIONS_UNSUPPORTED: {\n\t\tmessage: 'Search options unsupported',\n\t\tdetails: {},\n\t},\n\tSEARCH_PROTOCOL_UNSUPPORTED: {\n\t\tmessage: 'Search pagination protocol unsupported',\n\t\tdetails: {},\n\t},\n})\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\tif (value === null || typeof value !== 'object' || Array.isArray(value)) return false\n\tconst prototype = Object.getPrototypeOf(value)\n\treturn prototype === Object.prototype || prototype === null\n}\n\n/** Copy data without invoking toJSON or retaining mutable provider objects. */\nfunction copyJson(value: unknown, ancestors = new Set<object>()): Json {\n\tif (value === null || typeof value === 'string' || typeof value === 'boolean') return value\n\tif (typeof value === 'number' && Number.isFinite(value)) return value\n\tif (typeof value !== 'object' || value === null || ancestors.has(value))\n\t\tthrow Error('Invalid JSON')\n\tancestors.add(value)\n\ttry {\n\t\tif (Array.isArray(value)) {\n\t\t\tconst result: Json[] = []\n\t\t\tfor (let index = 0; index < value.length; index++)\n\t\t\t\tresult.push(copyJson(value[index], ancestors))\n\t\t\treturn result\n\t\t}\n\t\tif (!isRecord(value)) throw Error('Invalid JSON')\n\t\treturn Object.fromEntries(\n\t\t\tObject.entries(value).map(([key, child]) => [key, copyJson(child, ancestors)]),\n\t\t)\n\t} finally {\n\t\tancestors.delete(value)\n\t}\n}\n\nfunction parseDetails<const Definition extends ErrorDefinitions[string]>(\n\tdefinition: Definition,\n\tvalue: unknown,\n\tstrict: boolean,\n): Details<Definition> {\n\tif (!isRecord(value)) throw Error('Invalid details')\n\tconst fields = Object.keys(definition.details)\n\tif (strict && Object.keys(value).some((key) => !Object.hasOwn(definition.details, key))) {\n\t\tthrow Error('Undeclared detail')\n\t}\n\t// SAFETY: each declared field is validated by its paired parser before its JSON-safe copy is returned.\n\treturn Object.fromEntries(\n\t\tfields.map((field) => {\n\t\t\tif (!Object.hasOwn(value, field)) throw Error('Missing detail')\n\t\t\treturn [field, copyJson(definition.details[field].parse(value[field]))]\n\t\t}),\n\t) as Details<Definition>\n}\n"],"mappings":"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"}

package/dist/modules/effect/crud.d.mts

@@ -361,6 +361,7 @@ export declare function createEffectCrud<const Options extends EffectFoundationO
     }, z.core.$strict>;
     result: z.ZodObject<{
       page: z.ZodArray<Table["publicDto"]>;
+      paginationMode: z.ZodOptional<z.ZodLiteral<"native-search">>;
       isDone: z.ZodBoolean;
       continueCursor: z.ZodString;
       splitCursor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -368,6 +369,13 @@ export declare function createEffectCrud<const Options extends EffectFoundationO
         SplitRecommended: "SplitRecommended";
         SplitRequired: "SplitRequired";
       }>>>;
+      completeness: z.ZodOptional<z.ZodEnum<{
+        "byte-budget": "byte-budget";
+        complete: "complete";
+        "native-limit": "native-limit";
+        "result-cap": "result-cap";
+        "row-budget": "row-budget";
+      }>>;
     }, z.core.$strip>;
     handler: (input: {
       numItems: number;
@@ -392,10 +400,12 @@ export declare function createEffectCrud<const Options extends EffectFoundationO
       schema: ContractSchema;
       project: (value: {
         page: z.infer<Table["publicDto"]>[];
+        paginationMode?: "native-search" | undefined;
         isDone: boolean;
         continueCursor: string;
         splitCursor?: string | null | undefined;
         pageStatus?: "SplitRecommended" | "SplitRequired" | null | undefined;
+        completeness?: "byte-budget" | "complete" | "native-limit" | "result-cap" | "row-budget" | undefined;
       }) => unknown;
     } | undefined;
     guard?: ((context: EffectValue<ContextReturned> & Record<never, never>, input: {
@@ -425,10 +435,12 @@ export declare function createEffectCrud<const Options extends EffectFoundationO
       };
       result: {
         page: z.infer<Table["publicDto"]>[];
+        paginationMode?: "native-search" | undefined;
         isDone: boolean;
         continueCursor: string;
         splitCursor?: string | null | undefined;
         pageStatus?: "SplitRecommended" | "SplitRequired" | null | undefined;
+        completeness?: "byte-budget" | "complete" | "native-limit" | "result-cap" | "row-budget" | undefined;
       };
     }, context: EffectValue<ContextReturned>) => never) | undefined;
   } & {
@@ -441,10 +453,12 @@ export declare function createEffectCrud<const Options extends EffectFoundationO
       maximumBytesRead?: number | undefined;
     }, {
       page: z.core.input<Table["publicDto"]>[];
+      paginationMode?: "native-search" | undefined;
       isDone: boolean;
       continueCursor: string;
       splitCursor?: string | null | undefined;
       pageStatus?: "SplitRecommended" | "SplitRequired" | null | undefined;
+      completeness?: "byte-budget" | "complete" | "native-limit" | "result-cap" | "row-budget" | undefined;
     }, Record<never, never>, CallbackError<List> | CallbackError<ListGuard> | CallbackError<Policy> | CallbackError<Project>, CallbackRequirements<List> | CallbackRequirements<ListGuard> | CallbackRequirements<Policy> | CallbackRequirements<Project>>) => never) | undefined;
   } & {
     prepare?: never;
@@ -686,6 +700,7 @@ export declare function createEffectCrud<const Options extends EffectFoundationO
     }, z.core.$strict>;
     result: z.ZodObject<{
       page: z.ZodArray<Table["publicDto"]>;
+      paginationMode: z.ZodOptional<z.ZodLiteral<"native-search">>;
       isDone: z.ZodBoolean;
       continueCursor: z.ZodString;
       splitCursor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -693,6 +708,13 @@ export declare function createEffectCrud<const Options extends EffectFoundationO
         SplitRecommended: "SplitRecommended";
         SplitRequired: "SplitRequired";
       }>>>;
+      completeness: z.ZodOptional<z.ZodEnum<{
+        "byte-budget": "byte-budget";
+        complete: "complete";
+        "native-limit": "native-limit";
+        "result-cap": "result-cap";
+        "row-budget": "row-budget";
+      }>>;
     }, z.core.$strip>;
     handler: (input: {
       numItems: number;
@@ -717,10 +739,12 @@ export declare function createEffectCrud<const Options extends EffectFoundationO
       schema: ContractSchema;
       project: (value: {
         page: z.infer<Table["publicDto"]>[];
+        paginationMode?: "native-search" | undefined;
         isDone: boolean;
         continueCursor: string;
         splitCursor?: string | null | undefined;
         pageStatus?: "SplitRecommended" | "SplitRequired" | null | undefined;
+        completeness?: "byte-budget" | "complete" | "native-limit" | "result-cap" | "row-budget" | undefined;
       }) => unknown;
     } | undefined;
     guard?: ((context: EffectValue<ContextReturned> & Record<never, never>, input: {
@@ -750,10 +774,12 @@ export declare function createEffectCrud<const Options extends EffectFoundationO
       };
       result: {
         page: z.infer<Table["publicDto"]>[];
+        paginationMode?: "native-search" | undefined;
         isDone: boolean;
         continueCursor: string;
         splitCursor?: string | null | undefined;
         pageStatus?: "SplitRecommended" | "SplitRequired" | null | undefined;
+        completeness?: "byte-budget" | "complete" | "native-limit" | "result-cap" | "row-budget" | undefined;
       };
     }, context: EffectValue<ContextReturned>) => never) | undefined;
   } & {
@@ -766,10 +792,12 @@ export declare function createEffectCrud<const Options extends EffectFoundationO
       maximumBytesRead?: number | undefined;
     }, {
       page: z.core.input<Table["publicDto"]>[];
+      paginationMode?: "native-search" | undefined;
       isDone: boolean;
       continueCursor: string;
       splitCursor?: string | null | undefined;
       pageStatus?: "SplitRecommended" | "SplitRequired" | null | undefined;
+      completeness?: "byte-budget" | "complete" | "native-limit" | "result-cap" | "row-budget" | undefined;
     }, Record<never, never>, CallbackError<List> | CallbackError<ListGuard> | CallbackError<Policy> | CallbackError<Project>, CallbackRequirements<List> | CallbackRequirements<ListGuard> | CallbackRequirements<Policy> | CallbackRequirements<Project>>) => never) | undefined;
   } & {
     prepare?: never;

package/dist/querying/cursors.d.mts

@@ -1,3 +1,5 @@
+import { ManagedScope } from "./security.mjs";
+import { z } from "zod";
 import { Value } from "convex/values";
 //#region src/querying/cursors.d.ts
 /** Private engine contract. Bindings must come from trusted normalized engine state, never query args. */
@@ -33,8 +35,12 @@ export declare class CursorConfigurationError extends Error {
 }
 /** Private lazy server configuration. Call only at the first pagination boundary. */
 export declare function createEnvironmentCursorCodec(): Readonly<{
-  seal(raw: string, binding: CursorBinding): string;
-  open(token: string, binding: CursorBinding): string;
+  seal: (raw: string, binding: CursorBinding) => string;
+  open: (token: string, binding: CursorBinding) => string;
+  custom: Readonly<{
+    seal(raw: string, binding: CursorBinding): string;
+    open(token: string, binding: CursorBinding): string;
+  }>;
 }>;
 /**
  * Deterministic RFC 5297 AES-SIV: equal plaintext and binding leak equality.
@@ -43,8 +49,28 @@ export declare function createEnvironmentCursorCodec(): Readonly<{
  * must recheck current policy on every future request, including nested continuations.
  */
 export declare function createCursorCodec(config: CursorCodecConfig): Readonly<{
-  seal(raw: string, binding: CursorBinding): string;
-  open(token: string, binding: CursorBinding): string;
+  seal: (raw: string, binding: CursorBinding) => string;
+  open: (token: string, binding: CursorBinding) => string;
+  custom: Readonly<{
+    seal(raw: string, binding: CursorBinding): string;
+    open(token: string, binding: CursorBinding): string;
+  }>;
 }>;
+/** Server-derived binding supplements managed scope; opening never grants row access. */
+export interface ScopedCursorOptions<S extends z.ZodType<Value>> {
+  readonly domain: string;
+  readonly bind: Value;
+  /** Synchronous schema, applied on seal AND open. Outputs must be bounded Convex values. */
+  readonly schema: S;
+}
+/** Integrity only: consumers must recheck current authorization on every request. */
+export interface ScopedCursorCodec<S extends z.ZodType<Value>> {
+  seal(payload: z.input<S>): string;
+  open(token: string): z.output<S>;
+}
+/** Internal construction uses the configured engine's already captured key ring. */
+export declare function createScopedCursorCodec<S extends z.ZodType<Value>>(transport: ReturnType<typeof createCursorCodec>['custom'], scope: ManagedScope & {
+  readonly policyVersion: string;
+}, options: ScopedCursorOptions<S>): ScopedCursorCodec<S>;
 //#endregion
 //# sourceMappingURL=cursors.d.mts.map