@datafn/core 0.0.1 → 0.0.2

package/dist/index.d.ts

@@ -1,26 +1,125 @@
+/**
+ * DataFn Error Types and Envelopes
+ */
+type DatafnErrorCode = "SCHEMA_INVALID" | "INVALID_CAPABILITY" | "INVALID_CAPABILITY_CONFIG" | "CAPABILITY_FIELD_COLLISION" | "CAPABILITY_DEPENDENCY" | "DFQL_INVALID" | "DFQL_UNKNOWN_RESOURCE" | "DFQL_UNKNOWN_FIELD" | "DFQL_UNKNOWN_RELATION" | "DFQL_UNSUPPORTED" | "DFQL_ABORTED" | "LIMIT_EXCEEDED" | "FORBIDDEN" | "NOT_FOUND" | "CONFLICT" | "INTERNAL"
+/** LOW-026: Network/transport-layer errors (timeouts, connection refused, etc.) */
+ | "TRANSPORT_ERROR";
+type DatafnError = {
+    code: DatafnErrorCode;
+    message: string;
+    details?: unknown;
+};
+type DatafnEnvelope<T> = {
+    ok: true;
+    result: T;
+} | {
+    ok: false;
+    error: DatafnError;
+};
+/**
+ * Helper functions for creating envelopes
+ */
+declare function ok<T>(result: T): DatafnEnvelope<T>;
+declare function err<T = never>(code: DatafnErrorCode, message: string, details?: unknown): DatafnEnvelope<T>;
+
+type SimpleCapability = "timestamps" | "audit" | "trash" | "archivable";
+type AccessLevel = "viewer" | "editor" | "owner";
+type ShareableVisibilityDefault = "ns" | "private" | "shared";
+type ShareablePrincipalMode = "opaque-id";
+type ShareableRelationInheritance = {
+    enabled: boolean;
+    relations?: string[];
+    requireRelateConsent?: boolean;
+};
+type ShareableCapability = {
+    shareable: {
+        levels: AccessLevel[];
+        default?: "private" | "shared";
+        visibilityDefault?: ShareableVisibilityDefault;
+        supportsScopeGrants?: boolean;
+        crossNsShareable?: boolean;
+        principalMode?: ShareablePrincipalMode;
+        relationInheritance?: ShareableRelationInheritance;
+    };
+};
+type CapabilityEntry = SimpleCapability | ShareableCapability;
+type SchemaCapabilities = CapabilityEntry[];
+type ResourceCapabilities = CapabilityEntry[] | {
+    exclude: SimpleCapability[];
+};
+type CapabilityKey = SimpleCapability | "shareable";
+type CapabilityFieldDef = Pick<DatafnFieldSchema, "name" | "type" | "required" | "nullable" | "readonly" | "default">;
+declare const CAPABILITY_FIELD_DEFS: Record<CapabilityKey, CapabilityFieldDef[]>;
+type RelationCapabilityKey = "timestamps" | "audit";
+/**
+ * Field definitions injected into join tables for each relation capability.
+ * Same field names as resource capabilities; kept separate for clarity.
+ */
+declare const RELATION_CAPABILITY_FIELD_DEFS: Record<RelationCapabilityKey, CapabilityFieldDef[]>;
+/**
+ * Returns the field names injected by the given resolved relation capabilities.
+ * Output is deduplicated and ordered deterministically (canonical capability order).
+ */
+declare function getRelationCapabilityFieldNames(caps: string[]): string[];
+declare function resolveCapabilities(globalCaps?: SchemaCapabilities, resourceCaps?: ResourceCapabilities): CapabilityEntry[];
+declare function getCapabilityFields(resolvedCaps: CapabilityEntry[]): DatafnFieldSchema[];
+
 /**
  * DataFn Schema Types
  */
+
 type DatafnSchema = {
+    capabilities?: SchemaCapabilities;
     resources: DatafnResourceSchema[];
     relations?: DatafnRelationSchema[];
+    /** Defaults to true. Set to false to disable row-level namespace isolation. */
+    namespaced?: boolean;
+};
+/**
+ * Permissions policy shape for server-side authorization enforcement.
+ * All field arrays are optional; if omitted, no fields are accessible.
+ */
+type DatafnPermissionsPolicy = {
+    /**
+     * Read policy: controls which fields can be selected and filtered.
+     */
+    read?: {
+        fields: string[];
+    };
+    /**
+     * Write policy: controls which fields can be written via mutations.
+     */
+    write?: {
+        fields: string[];
+    };
+    /**
+     * Optional owner field for owner-scoped resources.
+     * When set, additional owner-based authorization checks can be performed.
+     */
+    ownerField?: string;
 };
 type DatafnResourceSchema = {
     name: string;
     version: number;
     idPrefix?: string;
     isRemoteOnly?: boolean;
+    /**
+     * Resource capabilities.
+     * For shareable resources, SPV2 extends shareable config with
+     * visibility/membership/scope-related options while preserving legacy fields.
+     */
+    capabilities?: ResourceCapabilities;
     fields: DatafnFieldSchema[];
     indices?: {
         base?: string[];
         search?: string[];
         vector?: string[];
     } | string[];
-    permissions?: unknown;
+    permissions?: DatafnPermissionsPolicy;
 };
 type DatafnFieldSchema = {
     name: string;
-    type: "string" | "number" | "boolean" | "object" | "array" | "date" | "file";
+    type: "string" | "number" | "boolean" | "object" | "array" | "date" | "file" | "json";
     required: boolean;
     nullable?: boolean;
     readonly?: boolean;
@@ -35,6 +134,7 @@ type DatafnFieldSchema = {
     encrypt?: boolean;
     volatile?: boolean;
 };
+type RelationSimpleCapability = "timestamps" | "audit";
 type DatafnRelationSchema = {
     from: string | string[];
     to: string | string[];
@@ -44,16 +144,70 @@ type DatafnRelationSchema = {
     cache?: boolean;
     metadata?: Array<{
         name: string;
-        type: "string" | "number" | "boolean" | "date" | "object";
+        type: "string" | "number" | "boolean" | "date" | "object" | "json";
     }>;
     fkField?: string;
     pathField?: string;
+    joinTable?: string;
+    joinColumns?: {
+        from: string;
+        to: string;
+    };
+    capabilities?: RelationSimpleCapability[];
 };
+/**
+ * Type-safe schema definition helper.
+ * Uses const generic to preserve literal field name types and constrain
+ * index entries to only declared field names within each resource.
+ */
+type DatafnFieldInput = {
+    readonly name: string;
+    readonly type: DatafnFieldSchema["type"];
+    readonly required: boolean;
+    readonly [k: string]: unknown;
+};
+type DatafnIndicesInput<FieldName extends string> = {
+    readonly base?: readonly FieldName[];
+    readonly search?: readonly FieldName[];
+    readonly vector?: readonly FieldName[];
+} | readonly FieldName[];
+type SchemaCapabilitiesInput = readonly CapabilityEntry[];
+type ResourceCapabilitiesInput = SchemaCapabilitiesInput | {
+    readonly exclude: readonly SimpleCapability[];
+};
+type DatafnResourceBase = {
+    readonly name: string;
+    readonly version: number;
+    readonly idPrefix?: string;
+    readonly isRemoteOnly?: boolean;
+    readonly capabilities?: ResourceCapabilitiesInput;
+    readonly fields: readonly DatafnFieldInput[];
+    readonly indices?: DatafnIndicesInput<string>;
+    readonly permissions?: DatafnPermissionsPolicy;
+    readonly [k: string]: unknown;
+};
+type ValidateResources<R extends readonly DatafnResourceBase[]> = {
+    readonly [K in keyof R]: R[K] extends {
+        readonly fields: readonly {
+            readonly name: infer N extends string;
+        }[];
+    } ? Omit<R[K], "indices"> & {
+        readonly indices?: DatafnIndicesInput<N>;
+    } : R[K];
+};
+declare function defineSchema<const T extends {
+    readonly capabilities?: SchemaCapabilitiesInput;
+    readonly resources: readonly DatafnResourceBase[];
+    readonly relations?: readonly DatafnRelationSchema[] | DatafnRelationSchema[];
+    readonly namespaced?: boolean;
+}>(schema: T & {
+    readonly resources: ValidateResources<T["resources"]>;
+}): T & DatafnSchema;
 /**
  * Event Types
  */
 interface DatafnEvent {
-    type: "mutation_applied" | "mutation_rejected" | "sync_applied" | "sync_failed";
+    type: "mutation_applied" | "mutation_rejected" | "sync_applied" | "sync_failed" | "sync_retry" | "connectivity_changed" | "ws_connected" | "ws_disconnected";
     resource?: string;
     ids?: string[];
     mutationId?: string;
@@ -62,6 +216,8 @@ interface DatafnEvent {
     context?: unknown;
     action?: string;
     fields?: string[];
+    system?: boolean;
+    fromRemoteTab?: boolean;
 }
 type DatafnEventFilter = Partial<{
     type: DatafnEvent["type"] | Array<DatafnEvent["type"]>;
@@ -71,6 +227,7 @@ type DatafnEventFilter = Partial<{
     action: string | string[];
     fields: string | string[];
     contextKeys: string[];
+    context: Record<string, unknown>;
 }>;
 /**
  * Signal Type
@@ -78,7 +235,51 @@ type DatafnEventFilter = Partial<{
 interface DatafnSignal<T> {
     get(): T;
     subscribe(handler: (value: T) => void): () => void;
+    readonly loading: boolean;
+    readonly error: DatafnError | null;
+    readonly refreshing: boolean;
+    readonly nextCursor: string | null | undefined;
+    dispose(): void;
+}
+/**
+ * Logger interface for structured, pluggable logging.
+ */
+interface DatafnLogger {
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+    debug(message: string, context?: Record<string, unknown>): void;
 }
+/**
+ * Limits configuration for server-side enforcement.
+ */
+type DatafnLimitsConfig = {
+    maxLimit?: number;
+    maxTransactSteps?: number;
+    maxPayloadBytes?: number;
+    maxPullLimit?: number;
+    maxBatchSize?: number;
+    maxCloneRecords?: number;
+    idempotencyTtlMs?: number;
+    idempotencyMaxEntries?: number;
+    maxSelectTokens?: number;
+    maxFilterKeysPerLevel?: number;
+    maxSortFields?: number;
+    maxAggregations?: number;
+    maxSearchQueryLength?: number;
+    maxLikePatternLength?: number;
+    maxIdLength?: number;
+    maxFilterDepth?: number;
+};
+/**
+ * WebSocket configuration for connection limits and heartbeat.
+ */
+type DatafnWsConfig = {
+    maxConnections?: number;
+    maxConnectionsPerNamespace?: number;
+    heartbeatIntervalMs?: number;
+    heartbeatTimeoutMs?: number;
+};
 /**
  * Plugin Types
  */
@@ -94,38 +295,29 @@ interface DatafnPlugin {
     afterQuery?: (ctx: DatafnHookContext, q: unknown, result: unknown) => Promise<unknown> | unknown;
     beforeMutation?: (ctx: DatafnHookContext, m: unknown | unknown[]) => Promise<unknown> | unknown;
     afterMutation?: (ctx: DatafnHookContext, m: unknown | unknown[], result: unknown) => Promise<void> | void;
-    beforeSync?: (ctx: DatafnHookContext, phase: "seed" | "clone" | "pull" | "push", payload: unknown) => Promise<unknown> | unknown;
-    afterSync?: (ctx: DatafnHookContext, phase: "seed" | "clone" | "pull" | "push", payload: unknown, result: unknown) => Promise<void> | void;
+    beforeSync?: (ctx: DatafnHookContext, phase: "seed" | "clone" | "pull" | "push" | "cloneUp" | "reconcile", payload: unknown) => Promise<unknown> | unknown;
+    afterSync?: (ctx: DatafnHookContext, phase: "seed" | "clone" | "pull" | "push" | "cloneUp" | "reconcile", payload: unknown, result: unknown) => Promise<void> | void;
 }
 
-/**
- * DataFn Error Types and Envelopes
- */
-type DatafnErrorCode = "SCHEMA_INVALID" | "DFQL_INVALID" | "DFQL_UNKNOWN_RESOURCE" | "DFQL_UNKNOWN_FIELD" | "DFQL_UNKNOWN_RELATION" | "DFQL_UNSUPPORTED" | "LIMIT_EXCEEDED" | "FORBIDDEN" | "NOT_FOUND" | "CONFLICT" | "INTERNAL";
-type DatafnError = {
-    code: DatafnErrorCode;
-    message: string;
-    details?: unknown;
-};
-type DatafnEnvelope<T> = {
-    ok: true;
-    result: T;
-} | {
-    ok: false;
-    error: DatafnError;
-};
-/**
- * Helper functions for creating envelopes
- */
-declare function ok<T>(result: T): DatafnEnvelope<T>;
-declare function err<T = never>(code: DatafnErrorCode, message: string, details?: unknown): DatafnEnvelope<T>;
-
 /**
  * Schema Validation
  *
  * Validates and normalizes DataFn schemas according to SCHEMA-001.
  */
 
+/**
+ * Resolves and validates relation capability declarations.
+ * Returns canonical ordered, deduplicated array, or error.
+ * - Returns ok([]) when capabilities is undefined.
+ * - Rejects non-array, non-string entries, and unknown capability values.
+ * - Returns deterministic canonical order: ["timestamps", "audit"] subset.
+ */
+declare function resolveRelationCapabilities(capabilities: unknown): DatafnEnvelope<RelationSimpleCapability[]>;
+/**
+ * Returns whether namespace isolation is enabled for a given schema.
+ * Default is `true`.
+ */
+declare function isNamespaced(schema: DatafnSchema): boolean;
 /**
  * Validates a schema and returns a normalized version.
  *
@@ -140,6 +332,20 @@ declare function err<T = never>(code: DatafnErrorCode, message: string, details?
  */
 declare function validateSchema(schema: unknown): DatafnEnvelope<DatafnSchema>;
 
+/**
+ * Composable namespace helper.
+ *
+ * Joins non-empty string segments with `:` to form a namespace string.
+ *
+ * @example
+ * ns("org-acme", "user-123")    // => "org-acme:user-123"
+ * ns("user-1")                  // => "user-1"
+ * ns("org", "project", "user")  // => "org:project:user"
+ * ns("org", "", "user")         // => "org:user" (empty filtered)
+ * ns()                          // throws Error
+ */
+declare function ns(...segments: string[]): string;
+
 /**
  * DFQL Normalization
  *
@@ -151,6 +357,11 @@ declare function validateSchema(schema: unknown): DatafnEnvelope<DatafnSchema>;
  * - Sorts object keys alphabetically
  * - Removes undefined values
  * - Preserves arrays, primitives, and null as-is
+ *
+ * LOW-023: undefined vs null semantics:
+ * - `null` is preserved as `null` (explicit absence of a value — serialisable to JSON)
+ * - `undefined` is stripped from the output (non-serialisable; treated as "not set")
+ * This mirrors JSON.stringify behavior and ensures stable cache keys across environments.
  */
 declare function normalizeDfql(value: unknown): unknown;
 /**
@@ -175,4 +386,331 @@ declare function dfqlKey(value: unknown): string;
  */
 declare function unwrapEnvelope<T>(env: DatafnEnvelope<T>): T;
 
-export { type DatafnEnvelope, type DatafnError, type DatafnErrorCode, type DatafnEvent, type DatafnEventFilter, type DatafnFieldSchema, type DatafnHookContext, type DatafnPlugin, type DatafnRelationSchema, type DatafnResourceSchema, type DatafnSchema, type DatafnSignal, dfqlKey, err, normalizeDfql, ok, unwrapEnvelope, validateSchema };
+type DfqlSort = string[];
+type DfqlCursor = {
+    after?: Record<string, unknown>;
+    before?: Record<string, unknown>;
+};
+type DfqlQuery = {
+    resource: string;
+    version: number;
+    select?: string[];
+    omit?: string[];
+    filters?: Record<string, unknown>;
+    search?: Record<string, unknown>;
+    sort?: DfqlSort;
+    limit?: number;
+    offset?: number;
+    cursor?: DfqlCursor;
+    count?: boolean;
+    groupBy?: string[];
+    aggregations?: Record<string, unknown>;
+    having?: Record<string, unknown>;
+    signal?: AbortSignal;
+};
+type DfqlQueryFragment = Omit<DfqlQuery, "resource" | "version">;
+type DfqlMutation = {
+    resource: string;
+    version: number;
+    operation: string;
+    id?: string | string[];
+    record?: Record<string, unknown>;
+    records?: Array<Record<string, unknown>>;
+    clientId?: string;
+    mutationId?: string;
+    timestamp?: number | string;
+    context?: unknown;
+    relations?: Record<string, unknown>;
+    if?: Record<string, unknown>;
+    cascade?: unknown;
+    silent?: boolean;
+    system?: boolean;
+    debounceKey?: string;
+    debounceMs?: number;
+};
+type DfqlMutationFragment = Omit<DfqlMutation, "resource" | "version">;
+type DfqlTransact = {
+    transactionId?: string;
+    atomic?: boolean;
+    steps: Array<{
+        query?: DfqlQuery;
+        mutation?: DfqlMutation;
+    }>;
+};
+
+/**
+ * Built-in KV resource utilities
+ */
+
+/**
+ * Canonical KV resource name
+ */
+declare const KV_RESOURCE_NAME = "kv";
+/**
+ * Generate the canonical KV id from a key.
+ * Mapping: kvId(key) = "kv:" + key
+ */
+declare function kvId(key: string): string;
+/**
+ * Ensure the schema includes the built-in KV resource.
+ * If schema already has resource "kv", validates it is compatible.
+ * Otherwise appends a resource definition for KV.
+ */
+declare function ensureBuiltinKv(schema: DatafnSchema): DatafnSchema;
+
+/**
+ * Shared join store key utilities.
+ *
+ * These functions provide the single canonical derivation of join store names
+ * used by both client and server across all sync operations.
+ */
+
+/**
+ * Derive the logical join store key used by clients and change tracking.
+ * Format: join_{fromResource}_{relationName}_{toResource}
+ */
+declare function getJoinStoreKey(from: string, relation: string, to: string): string;
+/**
+ * Derive the actual DB table name for a join table.
+ * Format: __datafn_join_{fromResource}_{relationName}
+ * Can be overridden by relation.joinTable in schema.
+ */
+declare function getJoinTableName(from: string, relation: string, joinTable?: string): string;
+/**
+ * Enumerate all logical join store keys for a schema's many-many relations.
+ * Handles multi-resource from/to arrays.
+ * Useful for building cursor maps, reconcile payloads, and similar operations.
+ *
+ * @param relations - Array of relation schema definitions
+ * @param resourceFilter - Optional set of resource names; if provided, only
+ *   joins whose `from` resource is in this set are included.
+ */
+declare function enumerateJoinStoreKeys(relations: DatafnRelationSchema[], resourceFilter?: Set<string>): string[];
+
+interface SchemaIndex {
+    resourcesByName: Map<string, DatafnResourceSchema>;
+    fieldsByResource: Map<string, Map<string, DatafnFieldSchema>>;
+    /** All relations involving the resource (as from OR inverse to). */
+    relationsByResource: Map<string, DatafnRelationSchema[]>;
+    /** Relations where the resource is the from side. */
+    relationsFromResource: Map<string, DatafnRelationSchema[]>;
+}
+declare function buildSchemaIndex(schema: DatafnSchema): SchemaIndex;
+declare function getResource(index: SchemaIndex, name: string): DatafnResourceSchema | undefined;
+declare function getField(index: SchemaIndex, resource: string, field: string): DatafnFieldSchema | undefined;
+declare function getRelationsFrom(index: SchemaIndex, resource: string): DatafnRelationSchema[];
+declare function getRelation(index: SchemaIndex, fromResource: string, relationName: string): DatafnRelationSchema | undefined;
+declare function getRelationTarget(relation: DatafnRelationSchema): string;
+/**
+ * Find a relation by name in either direction (forward or inverse).
+ * Checks both `relation === relationName` (from side) and `inverse === relationName` (to side).
+ */
+declare function findRelationBidirectional(schema: DatafnSchema, resource: string, relationName: string): DatafnRelationSchema | undefined;
+
+/** Map non-$-prefixed operator names to core's $-prefixed equivalents. */
+declare const OP_REMAP: Record<string, string>;
+/** Recursively remap non-$-prefixed operator names to core's $-prefixed form. */
+declare function normalizeFilterOps(filters: Record<string, unknown>): Record<string, unknown>;
+interface FilterEvalOptions {
+    resolveRelation?: (resource: string, recordId: string, relationName: string) => Record<string, unknown>[];
+    resource?: string;
+}
+/**
+ * Evaluate a DFQL filter against a single record.
+ * Supports: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $contains, $startsWith, $endsWith,
+ *           $like, $ilike, $not_like, $not_ilike, $is_null, $is_not_null, $is_empty, $is_not_empty,
+ *           $before, $after, $between, $not_between, $and, $or.
+ * Returns true if the record matches all filter conditions.
+ */
+declare function evaluateFilter(record: Record<string, unknown>, filters: Record<string, unknown>, opts?: FilterEvalOptions, _depth?: number): boolean;
+
+/**
+ * Shared relation payload normalization utilities.
+ * Used by both server mutation executor and offline client.
+ */
+/**
+ * Normalized relation payload item.
+ */
+interface NormalizedRelation {
+    toId: string;
+    metadata: Record<string, unknown>;
+}
+/**
+ * Normalize relation payload to consistent format.
+ * - String -> [{ toId, metadata: {} }]
+ * - String[] -> [{ toId, metadata: {} }, ...]
+ * - Object with $ref -> [{ toId: $ref, metadata: {...rest} }]
+ * - Array of above -> flatten
+ */
+declare function normalizeRelationPayload(payload: unknown): NormalizedRelation[];
+
+/**
+ * Shared aggregation computation.
+ * Used by both server and client offline aggregate query execution.
+ */
+/**
+ * Calculate an aggregation over a set of records for a given op and field.
+ * Null-safe: null/undefined values are excluded from sum/min/max/avg.
+ * Returns null for empty sets (SQL semantics).
+ */
+declare function calculateAggregation(op: string, field: string, records: Record<string, unknown>[]): unknown;
+
+interface SortTerm {
+    field: string;
+    direction: "asc" | "desc";
+}
+/**
+ * Parse DFQL sort strings into structured sort terms.
+ * Handles "field", "field:asc", "field:desc", "-field".
+ * Returns [] for undefined or empty input.
+ */
+declare function parseSortTerms(sort: string[] | undefined): SortTerm[];
+/**
+ * Sort records by the given terms with a stable id tie-breaker.
+ * Null values sort after non-null in ascending order (before in descending).
+ */
+declare function sortRecords(records: Record<string, unknown>[], terms: SortTerm[]): Record<string, unknown>[];
+
+interface SelectToken {
+    path: string[];
+    baseName: string;
+    directive: string | undefined;
+}
+/**
+ * Parse a DFQL select token string into its structured components.
+ * Examples: "id" → {path:["id"], baseName:"id", directive:undefined}
+ *           "tags.*" → {path:["tags","*"], baseName:"tags", directive:"*"}
+ *           "tasks.tags.*" → {path:["tasks","tags","*"], baseName:"tasks", directive:"tags.*"}
+ */
+declare function parseSelectToken(token: string): SelectToken;
+
+/**
+ * Shared date conversion utilities (DTE-001, DTE-002)
+ */
+
+/**
+ * Convert a Date, ISO string, or epoch number to epoch milliseconds.
+ * Idempotent: if already a number, returns it directly.
+ */
+declare function toEpochMs(value: unknown): number;
+/**
+ * Convert an epoch number, ISO string, or Date to a Date object.
+ * Idempotent: if already a Date, returns it directly.
+ */
+declare function fromEpochMs(value: unknown): Date;
+type FieldLike = Pick<DatafnFieldSchema, "name" | "type">;
+/**
+ * Mutate record in place: convert date-typed fields to epoch milliseconds.
+ *
+ * LOW-024: This function intentionally mutates the record in-place and returns it
+ * (callers rely on the mutation side-effect, as verified by existing tests).
+ * If a non-mutating variant is needed, create a separate helper that copies first.
+ */
+declare function coerceDateFieldsToEpoch(record: Record<string, unknown>, fields: FieldLike[]): Record<string, unknown>;
+/**
+ * Mutate record in place: convert date-typed fields to Date objects.
+ *
+ * LOW-024: This function intentionally mutates the record in-place and returns it
+ * (callers rely on the mutation side-effect, as verified by existing tests).
+ * If a non-mutating variant is needed, create a separate helper that copies first.
+ */
+declare function parseDateFieldsToDate(record: Record<string, unknown>, fields: FieldLike[]): Record<string, unknown>;
+
+/**
+ * Shared validation primitives for DataFn.
+ * - Prototype pollution key checking (recursive)
+ * - Field value type validation against schema types
+ */
+/**
+ * Recursively checks a value for prototype pollution keys.
+ * Returns `{ ok: true }` if clean, or `{ ok: false, key }` with the first offending key found.
+ */
+declare function checkPrototypePollution(obj: unknown): {
+    ok: boolean;
+    key?: string;
+};
+/**
+ * Validates a field value against its declared schema type.
+ * Returns `{ ok: true }` if valid, or `{ ok: false, error }` with a descriptive message.
+ */
+declare function validateFieldValue(schemaType: string, value: unknown, nullable: boolean): {
+    ok: boolean;
+    error?: string;
+};
+
+/**
+ * Generic plugin hook runner (HKS-001)
+ * Fail-closed for before hooks, fail-open for after hooks.
+ */
+
+interface HookError {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+type BeforeHookResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: HookError;
+};
+/**
+ * Run a before-style hook across plugins filtered by env.
+ * Fail-closed: first error stops the chain and returns { ok: false, error }.
+ * Each hook's return value (if defined) becomes the new payload.
+ *
+ * @param preArgs Optional args inserted before payload in hook call: hook(ctx, ...preArgs, payload)
+ */
+declare function runBeforeHook<T = unknown>(plugins: DatafnPlugin[], env: "client" | "server", hookName: keyof DatafnPlugin, ctx: DatafnHookContext, payload: T, preArgs?: unknown[]): Promise<BeforeHookResult<T>>;
+/**
+ * Run an after-style hook across plugins filtered by env.
+ * Fail-open: errors are logged but do not stop the chain.
+ *
+ * @param preArgs Optional args inserted before payload in hook call: hook(ctx, ...preArgs, payload, result)
+ */
+declare function runAfterHook(plugins: DatafnPlugin[], env: "client" | "server", hookName: keyof DatafnPlugin, ctx: DatafnHookContext, payload: unknown, result: unknown, preArgs?: unknown[]): Promise<void>;
+
+interface SearchProvider {
+    readonly name: string;
+    search(params: {
+        resource: string;
+        query: string;
+        type?: "fullText" | "semantic";
+        fields?: string[];
+        limit?: number;
+        prefix?: boolean;
+        fuzzy?: boolean | number;
+        fieldBoosts?: Record<string, number>;
+        signal?: AbortSignal;
+    }): Promise<string[]>;
+    searchAll?(params: {
+        query: string;
+        resources?: string[];
+        fields?: string[];
+        limit?: number;
+        limitPerResource?: number;
+        prefix?: boolean;
+        fuzzy?: boolean | number;
+        fieldBoosts?: Record<string, number>;
+        signal?: AbortSignal;
+    }): Promise<Array<{
+        resource: string;
+        id: string;
+        score: number;
+    }>>;
+    updateIndices(params: {
+        resource: string;
+        records: Record<string, unknown>[];
+        operation: "upsert" | "delete";
+    }): Promise<void>;
+    initialize?(config: {
+        resources: Array<{
+            name: string;
+            searchFields: string[];
+        }>;
+    }): Promise<void>;
+    dispose?(): Promise<void>;
+}
+
+export { type AccessLevel, type BeforeHookResult, CAPABILITY_FIELD_DEFS, type CapabilityEntry, type DatafnEnvelope, type DatafnError, type DatafnErrorCode, type DatafnEvent, type DatafnEventFilter, type DatafnFieldSchema, type DatafnHookContext, type DatafnLimitsConfig, type DatafnLogger, type DatafnPlugin, type DatafnRelationSchema, type DatafnResourceSchema, type DatafnSchema, type DatafnSignal, type DatafnWsConfig, type DfqlCursor, type DfqlMutation, type DfqlMutationFragment, type DfqlQuery, type DfqlQueryFragment, type DfqlSort, type DfqlTransact, type FilterEvalOptions, type HookError, KV_RESOURCE_NAME, type NormalizedRelation, OP_REMAP, RELATION_CAPABILITY_FIELD_DEFS, type RelationSimpleCapability, type ResourceCapabilities, type SchemaCapabilities, type SchemaIndex, type SearchProvider, type SelectToken, type ShareableCapability, type SimpleCapability, type SortTerm, buildSchemaIndex, calculateAggregation, checkPrototypePollution, coerceDateFieldsToEpoch, defineSchema, dfqlKey, ensureBuiltinKv, enumerateJoinStoreKeys, err, evaluateFilter, findRelationBidirectional, fromEpochMs, getCapabilityFields, getField, getJoinStoreKey, getJoinTableName, getRelation, getRelationCapabilityFieldNames, getRelationTarget, getRelationsFrom, getResource, isNamespaced, kvId, normalizeDfql, normalizeFilterOps, normalizeRelationPayload, ns, ok, parseDateFieldsToDate, parseSelectToken, parseSortTerms, resolveCapabilities, resolveRelationCapabilities, runAfterHook, runBeforeHook, sortRecords, toEpochMs, unwrapEnvelope, validateFieldValue, validateSchema };