@mongrov/data-access 0.1.0-alpha.0

package/dist/errors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Error taxonomy for @mongrov/data-access.
+ *
+ * Full code set fills in as later phases land. This file ships the class
+ * plus the codes stubs need on day one.
+ */
+export type DataAccessErrorCode = 'authorization_denied' | 'engine_missing' | 'zod_parse_failed' | 'define_config_invalid' | 'invalid_pattern' | 'not_implemented';
+export declare class DataAccessError extends Error {
+    readonly code: DataAccessErrorCode;
+    readonly cause?: unknown;
+    constructor(code: DataAccessErrorCode, message: string, cause?: unknown);
+}
+/**
+ * Thrown when authorization hook rejects a query or mutation.
+ * See data-access/spec.md §Authorization.
+ */
+export declare class AuthorizationError extends DataAccessError {
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Thrown by unimplemented stubs. Distinct class so tests can assert on
+ * "this surface isn't wired yet" without ambiguity against runtime errors.
+ */
+export declare class NotImplementedError extends DataAccessError {
+    constructor(symbol: string);
+}
+//# 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;;;;;GAKG;AAEH,MAAM,MAAM,mBAAmB,GAC3B,sBAAsB,GACtB,gBAAgB,GAChB,kBAAkB,GAClB,uBAAuB,GACvB,iBAAiB,GACjB,iBAAiB,CAAA;AAErB,qBAAa,eAAgB,SAAQ,KAAK;IACxC,SAAgB,IAAI,EAAE,mBAAmB,CAAA;IACzC,SAAgB,KAAK,CAAC,EAAE,OAAO,CAAA;gBAEnB,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAMxE;AAED;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,eAAe;gBACzC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAI7C;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,eAAe;gBAC1C,MAAM,EAAE,MAAM;CAO3B"}

package/dist/errors.js

@@ -0,0 +1,35 @@
+/**
+ * Error taxonomy for @mongrov/data-access.
+ *
+ * Full code set fills in as later phases land. This file ships the class
+ * plus the codes stubs need on day one.
+ */
+export class DataAccessError extends Error {
+    constructor(code, message, cause) {
+        super(message);
+        this.name = 'DataAccessError';
+        this.code = code;
+        this.cause = cause;
+    }
+}
+/**
+ * Thrown when authorization hook rejects a query or mutation.
+ * See data-access/spec.md §Authorization.
+ */
+export class AuthorizationError extends DataAccessError {
+    constructor(message, cause) {
+        super('authorization_denied', message, cause);
+        this.name = 'AuthorizationError';
+    }
+}
+/**
+ * Thrown by unimplemented stubs. Distinct class so tests can assert on
+ * "this surface isn't wired yet" without ambiguity against runtime errors.
+ */
+export class NotImplementedError extends DataAccessError {
+    constructor(symbol) {
+        super('not_implemented', `${symbol} is not implemented in @mongrov/data-access@0.1.0-alpha.0`);
+        this.name = 'NotImplementedError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAIxC,YAAY,IAAyB,EAAE,OAAe,EAAE,KAAe;QACrE,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAA;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACpB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,kBAAmB,SAAQ,eAAe;IACrD,YAAY,OAAe,EAAE,KAAe;QAC1C,KAAK,CAAC,sBAAsB,EAAE,OAAO,EAAE,KAAK,CAAC,CAAA;QAC7C,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAA;IAClC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,eAAe;IACtD,YAAY,MAAc;QACxB,KAAK,CACH,iBAAiB,EACjB,GAAG,MAAM,2DAA2D,CACrE,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;IACnC,CAAC;CACF"}

package/dist/eslint/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * ESLint plugin barrel — `@mongrov/data-access/eslint`.
+ *
+ * Exposes rule modules under `rules` and a `recommended` flat-config
+ * shape under `configs.recommended` that turns the rule on at `'error'`
+ * severity. Consumers wire it up like:
+ *
+ * ```js
+ * // eslint.config.mjs
+ * import dataAccessPlugin from '@mongrov/data-access/eslint'
+ *
+ * export default [
+ *   {
+ *     plugins: { '@mongrov/data-access': dataAccessPlugin },
+ *     rules: {
+ *       '@mongrov/data-access/no-storage-engine-imports': ['error', {
+ *         allowedDirs: ['src/data'],
+ *       }],
+ *     },
+ *   },
+ * ]
+ * ```
+ *
+ * See data-access/spec.md §ESLint plugin.
+ */
+declare const rules: {
+    readonly 'no-storage-engine-imports': import("eslint").Rule.RuleModule;
+};
+declare const configs: {
+    readonly recommended: {
+        readonly plugins: readonly ["@mongrov/data-access"];
+        readonly rules: {
+            readonly "@mongrov/data-access/no-storage-engine-imports": "error";
+        };
+    };
+};
+declare const plugin: {
+    rules: {
+        readonly 'no-storage-engine-imports': import("eslint").Rule.RuleModule;
+    };
+    configs: {
+        readonly recommended: {
+            readonly plugins: readonly ["@mongrov/data-access"];
+            readonly rules: {
+                readonly "@mongrov/data-access/no-storage-engine-imports": "error";
+            };
+        };
+    };
+};
+export { rules, configs };
+export default plugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/eslint/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/eslint/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH,QAAA,MAAM,KAAK;;CAED,CAAA;AAEV,QAAA,MAAM,OAAO;;;;;;;CAOH,CAAA;AAEV,QAAA,MAAM,MAAM;;;;;;;;;;;;CAGX,CAAA;AAED,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAA;AACzB,eAAe,MAAM,CAAA"}

package/dist/eslint/index.js

@@ -0,0 +1,45 @@
+/**
+ * ESLint plugin barrel — `@mongrov/data-access/eslint`.
+ *
+ * Exposes rule modules under `rules` and a `recommended` flat-config
+ * shape under `configs.recommended` that turns the rule on at `'error'`
+ * severity. Consumers wire it up like:
+ *
+ * ```js
+ * // eslint.config.mjs
+ * import dataAccessPlugin from '@mongrov/data-access/eslint'
+ *
+ * export default [
+ *   {
+ *     plugins: { '@mongrov/data-access': dataAccessPlugin },
+ *     rules: {
+ *       '@mongrov/data-access/no-storage-engine-imports': ['error', {
+ *         allowedDirs: ['src/data'],
+ *       }],
+ *     },
+ *   },
+ * ]
+ * ```
+ *
+ * See data-access/spec.md §ESLint plugin.
+ */
+import noStorageEngineImports from './rules/no-storage-engine-imports';
+const PLUGIN_NAME = '@mongrov/data-access';
+const rules = {
+    'no-storage-engine-imports': noStorageEngineImports,
+};
+const configs = {
+    recommended: {
+        plugins: [PLUGIN_NAME],
+        rules: {
+            [`${PLUGIN_NAME}/no-storage-engine-imports`]: 'error',
+        },
+    },
+};
+const plugin = {
+    rules,
+    configs,
+};
+export { rules, configs };
+export default plugin;
+//# sourceMappingURL=index.js.map

package/dist/eslint/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/eslint/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,sBAAsB,MAAM,mCAAmC,CAAA;AAEtE,MAAM,WAAW,GAAG,sBAAsB,CAAA;AAE1C,MAAM,KAAK,GAAG;IACZ,2BAA2B,EAAE,sBAAsB;CAC3C,CAAA;AAEV,MAAM,OAAO,GAAG;IACd,WAAW,EAAE;QACX,OAAO,EAAE,CAAC,WAAW,CAAC;QACtB,KAAK,EAAE;YACL,CAAC,GAAG,WAAW,4BAA4B,CAAC,EAAE,OAAO;SACtD;KACF;CACO,CAAA;AAEV,MAAM,MAAM,GAAG;IACb,KAAK;IACL,OAAO;CACR,CAAA;AAED,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAA;AACzB,eAAe,MAAM,CAAA"}

package/dist/eslint/rules/no-storage-engine-imports.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ESLint rule — `no-storage-engine-imports`.
+ *
+ * Prevents screens (and other non-registry files) from reaching directly
+ * into the storage-engine packages (@mongrov/analytics, @mongrov/collab,
+ * @mongrov/db). All data must flow through named queries + mutations in
+ * the app's data-access registry via useAppQuery / useAppMutation.
+ *
+ * Files under `allowedDirs` are exempt so the registry itself can wire
+ * engine adapters.
+ *
+ * See data-access/spec.md §ESLint plugin.
+ */
+import type { Rule } from 'eslint';
+/** Default block list — the three storage engines the spec forbids. */
+declare const DEFAULT_BLOCKED_PACKAGES: string[];
+/** Default allow list — empty; apps supply their registry dirs. */
+declare const DEFAULT_ALLOWED_DIRS: string[];
+declare const rule: Rule.RuleModule;
+export default rule;
+export { DEFAULT_ALLOWED_DIRS, DEFAULT_BLOCKED_PACKAGES };
+//# sourceMappingURL=no-storage-engine-imports.d.ts.map

package/dist/eslint/rules/no-storage-engine-imports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-storage-engine-imports.d.ts","sourceRoot":"","sources":["../../../src/eslint/rules/no-storage-engine-imports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAQlC,uEAAuE;AACvE,QAAA,MAAM,wBAAwB,UAI7B,CAAA;AAED,mEAAmE;AACnE,QAAA,MAAM,oBAAoB,EAAE,MAAM,EAAO,CAAA;AAqBzC,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,UAyEhB,CAAA;AA2CD,eAAe,IAAI,CAAA;AACnB,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,CAAA"}

package/dist/eslint/rules/no-storage-engine-imports.js

@@ -0,0 +1,145 @@
+/**
+ * ESLint rule — `no-storage-engine-imports`.
+ *
+ * Prevents screens (and other non-registry files) from reaching directly
+ * into the storage-engine packages (@mongrov/analytics, @mongrov/collab,
+ * @mongrov/db). All data must flow through named queries + mutations in
+ * the app's data-access registry via useAppQuery / useAppMutation.
+ *
+ * Files under `allowedDirs` are exempt so the registry itself can wire
+ * engine adapters.
+ *
+ * See data-access/spec.md §ESLint plugin.
+ */
+import * as path from 'node:path';
+/** Default block list — the three storage engines the spec forbids. */
+const DEFAULT_BLOCKED_PACKAGES = [
+    '@mongrov/analytics',
+    '@mongrov/collab',
+    '@mongrov/db',
+];
+/** Default allow list — empty; apps supply their registry dirs. */
+const DEFAULT_ALLOWED_DIRS = [];
+const optionsSchema = {
+    type: 'object',
+    properties: {
+        allowedDirs: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Path segments (relative or absolute) that suppress the rule for files whose path contains any of these fragments. Typical values include the registry directory (e.g. "src/data").',
+        },
+        blockedPackages: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Package names to block. Subpaths are matched (e.g. blocking "@mongrov/db" also blocks "@mongrov/db/kv").',
+        },
+    },
+    additionalProperties: false,
+};
+const rule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow direct imports of storage-engine packages (@mongrov/analytics, @mongrov/collab, @mongrov/db). Use the data-access registry instead.',
+            recommended: true,
+            url: 'https://github.com/mongrov/mongrov-packages/tree/main/packages/data-access#eslint-plugin',
+        },
+        schema: [optionsSchema],
+        messages: {
+            blockedImport: 'Direct import of "{{importedPackage}}" is blocked in "{{file}}". Route reads through useAppQuery(name, input) and writes through useAppMutation(name) from your data-access registry, or add this directory to `allowedDirs`.',
+        },
+    },
+    create(context) {
+        const options = resolveOptions(context.options[0]);
+        const filename = context.filename ?? context.getFilename?.() ?? '<input>';
+        if (isAllowed(filename, options.allowedDirs)) {
+            return {};
+        }
+        function report(node, importedPackage) {
+            context.report({
+                node,
+                messageId: 'blockedImport',
+                data: {
+                    importedPackage,
+                    file: relativize(filename),
+                },
+            });
+        }
+        function checkSource(node, source) {
+            if (!source)
+                return;
+            const match = matchBlocked(source, options.blockedPackages);
+            if (match)
+                report(node, match);
+        }
+        return {
+            ImportDeclaration(node) {
+                // eslint's AST types leak — cast to any for the source literal.
+                const src = node.source
+                    ?.value;
+                if (typeof src === 'string') {
+                    checkSource(node, src);
+                }
+            },
+            ImportExpression(node) {
+                const src = node.source
+                    ?.value;
+                if (typeof src === 'string') {
+                    checkSource(node, src);
+                }
+            },
+            CallExpression(node) {
+                const callee = node
+                    .callee;
+                if (!callee || callee.type !== 'Identifier' || callee.name !== 'require') {
+                    return;
+                }
+                const args = node
+                    .arguments;
+                const first = args[0];
+                if (first && first.type === 'Literal' && typeof first.value === 'string') {
+                    checkSource(node, first.value);
+                }
+            },
+        };
+    },
+};
+// --- helpers ---------------------------------------------------------
+function resolveOptions(raw) {
+    return {
+        allowedDirs: raw?.allowedDirs ?? DEFAULT_ALLOWED_DIRS,
+        blockedPackages: raw?.blockedPackages ?? DEFAULT_BLOCKED_PACKAGES,
+    };
+}
+function isAllowed(filename, allowedDirs) {
+    if (allowedDirs.length === 0)
+        return false;
+    const normalized = filename.split(path.sep).join('/');
+    return allowedDirs.some((dir) => {
+        const normalizedDir = dir.split(path.sep).join('/');
+        return normalized.includes(normalizedDir);
+    });
+}
+function matchBlocked(source, blockedPackages) {
+    for (const pkg of blockedPackages) {
+        if (source === pkg || source.startsWith(`${pkg}/`)) {
+            return pkg;
+        }
+    }
+    return null;
+}
+function relativize(filename) {
+    if (filename === '<input>')
+        return filename;
+    try {
+        const rel = path.relative(process.cwd(), filename);
+        // Show relative form when it's a descendant; keep absolute when it isn't.
+        return rel.startsWith('..') ? filename : rel;
+    }
+    catch {
+        return filename;
+    }
+}
+export default rule;
+export { DEFAULT_ALLOWED_DIRS, DEFAULT_BLOCKED_PACKAGES };
+//# sourceMappingURL=no-storage-engine-imports.js.map

package/dist/eslint/rules/no-storage-engine-imports.js.map

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

package/dist/hooks.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Screen-facing hooks — useAppQuery / useAppMutation / useAppEvent +
+ * useRequestContext accessor.
+ *
+ * v0.1.0-alpha.0:
+ *   - useAppQuery (T-11 duckdb, T-12 rxdb, T-13 kv) — TanStack Query
+ *     bridge for pull engines; observable→state bridge for rxdb.
+ *   - useAppMutation (T-14) — authorize + optimistic + invalidation
+ *     with revert-on-failure via cached optimistic snapshot.
+ *   - useAppEvent (T-15) and useRequestContext (T-17) unchanged.
+ *
+ * See data-access/spec.md §Hooks.
+ */
+import type { RequestContext } from './types';
+/** T-18 — cache defaults per spec §Cache. Per-query overrides win. */
+export declare const DEFAULT_STALE_TIME = 30000;
+export declare const DEFAULT_GC_TIME = 300000;
+export interface UseAppQueryResult<TOutput> {
+    data: TOutput | undefined;
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+    isStale: boolean;
+}
+export interface UseAppMutationResult<TInput, TOutput> {
+    mutate: (input: TInput) => void;
+    mutateAsync: (input: TInput) => Promise<TOutput>;
+    loading: boolean;
+    error: Error | null;
+    data: TOutput | undefined;
+    reset: () => void;
+}
+/**
+ * T-11 (duckdb) + T-12 (rxdb) + T-13 (kv) — screen-facing query hook.
+ *
+ * duckdb/kv → TanStack `useQuery` + invalidation subscription.
+ * rxdb → observable subscription; each emission is Zod-parsed and
+ *        pushed into local state. `refetch` is a no-op (the observable
+ *        drives updates).
+ */
+export declare function useAppQuery<TInput, TOutput>(name: string, input?: TInput): UseAppQueryResult<TOutput>;
+/**
+ * T-14 — screen-facing mutation hook.
+ *
+ * Runs authorize + exec (via the app-provided config) through TanStack
+ * useMutation. On success, emits each `invalidates` entry on the event
+ * bus so subscribing queries invalidate their caches. If `optimistic`
+ * is defined, the returned `data` reflects the optimistic value while
+ * the mutation is pending and reverts on failure.
+ */
+export declare function useAppMutation<TInput, TOutput>(name: string): UseAppMutationResult<TInput, TOutput>;
+/**
+ * T-15 — subscribe to a named event for the lifetime of the mounting
+ * component. Handler runs on every emit whose name matches exactly; use
+ * the pattern form (bus.subscribePattern) directly for glob semantics.
+ *
+ * The handler ref is kept fresh so callers may pass unstable closures
+ * without churning the subscription.
+ */
+export declare function useAppEvent<TPayload>(name: string, handler: (payload: TPayload) => void): void;
+/**
+ * T-17 — read the current session's RequestContext from the provider.
+ * The provider's `context` callback is invoked on every read so
+ * callers pick up session updates without re-mounting.
+ */
+export declare function useRequestContext(): RequestContext;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH,OAAO,KAAK,EAGV,cAAc,EAEf,MAAM,SAAS,CAAA;AAEhB,sEAAsE;AACtE,eAAO,MAAM,kBAAkB,QAAS,CAAA;AACxC,eAAO,MAAM,eAAe,SAAU,CAAA;AAEtC,MAAM,WAAW,iBAAiB,CAAC,OAAO;IACxC,IAAI,EAAE,OAAO,GAAG,SAAS,CAAA;IACzB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5B,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,WAAW,oBAAoB,CAAC,MAAM,EAAE,OAAO;IACnD,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/B,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAChD,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB,IAAI,EAAE,OAAO,GAAG,SAAS,CAAA;IACzB,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAcD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,EACzC,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,MAAM,GACb,iBAAiB,CAAC,OAAO,CAAC,CA+H5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,EAC5C,IAAI,EAAE,MAAM,GACX,oBAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,CA2DvC;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAClC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,IAAI,GACnC,IAAI,CAcN;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAGlD"}

package/dist/hooks.js

@@ -0,0 +1,234 @@
+/**
+ * Screen-facing hooks — useAppQuery / useAppMutation / useAppEvent +
+ * useRequestContext accessor.
+ *
+ * v0.1.0-alpha.0:
+ *   - useAppQuery (T-11 duckdb, T-12 rxdb, T-13 kv) — TanStack Query
+ *     bridge for pull engines; observable→state bridge for rxdb.
+ *   - useAppMutation (T-14) — authorize + optimistic + invalidation
+ *     with revert-on-failure via cached optimistic snapshot.
+ *   - useAppEvent (T-15) and useRequestContext (T-17) unchanged.
+ *
+ * See data-access/spec.md §Hooks.
+ */
+import { useMutation, useQuery } from '@tanstack/react-query';
+import * as React from 'react';
+import { useDataAccessRuntime } from './context';
+import { executeQuery, runAuthorize } from './dispatcher';
+import { DataAccessError } from './errors';
+/** T-18 — cache defaults per spec §Cache. Per-query overrides win. */
+export const DEFAULT_STALE_TIME = 30000;
+export const DEFAULT_GC_TIME = 300000;
+/**
+ * T-11 (duckdb) + T-12 (rxdb) + T-13 (kv) — screen-facing query hook.
+ *
+ * duckdb/kv → TanStack `useQuery` + invalidation subscription.
+ * rxdb → observable subscription; each emission is Zod-parsed and
+ *        pushed into local state. `refetch` is a no-op (the observable
+ *        drives updates).
+ */
+export function useAppQuery(name, input) {
+    const runtime = useDataAccessRuntime();
+    const def = lookupDefinition(runtime.registry.queries, 'query', name);
+    const engine = def.config.engine;
+    const isRxdb = engine === 'rxdb';
+    const queryKey = React.useMemo(() => [name, input], [name, input]);
+    // TanStack path — active for duckdb + kv, disabled for rxdb.
+    const query = useQuery({
+        queryKey,
+        queryFn: () => executeQuery(def, input, runtime.getContext(), runtime.engines),
+        enabled: !isRxdb,
+        staleTime: def.config.staleTime ?? DEFAULT_STALE_TIME,
+        gcTime: def.config.gcTime ?? DEFAULT_GC_TIME,
+    });
+    // rxdb path — external state driven by observable emissions.
+    const [rxState, setRxState] = React.useState({ data: undefined, loading: true, error: null });
+    React.useEffect(() => {
+        if (!isRxdb)
+            return;
+        const rxEngine = runtime.engines.rxdb;
+        if (!rxEngine) {
+            setRxState({
+                data: undefined,
+                loading: false,
+                error: new DataAccessError('engine_missing', "engine 'rxdb' is not wired in this dispatcher"),
+            });
+            return;
+        }
+        const observable = def.config.query(rxEngine.db, input);
+        let cancelled = false;
+        const sub = observable.subscribe({
+            next: (value) => {
+                if (cancelled)
+                    return;
+                const parsed = def.config.output.safeParse(value);
+                if (parsed.success) {
+                    setRxState({
+                        data: parsed.data,
+                        loading: false,
+                        error: null,
+                    });
+                }
+                else {
+                    setRxState({
+                        data: undefined,
+                        loading: false,
+                        error: new DataAccessError('zod_parse_failed', `query "${name}" output failed schema validation: ${parsed.error.message}`, parsed.error),
+                    });
+                }
+            },
+            error: (err) => {
+                if (cancelled)
+                    return;
+                setRxState({
+                    data: undefined,
+                    loading: false,
+                    error: err instanceof Error ? err : new Error(String(err)),
+                });
+            },
+        });
+        return () => {
+            cancelled = true;
+            sub.unsubscribe();
+        };
+    }, [runtime, def, input, isRxdb, name]);
+    // Invalidation subscriptions — TanStack path only. rxdb self-updates
+    // via the observable stream.
+    const patterns = def.config.invalidatedBy;
+    React.useEffect(() => {
+        if (isRxdb)
+            return;
+        if (!patterns || patterns.length === 0)
+            return;
+        const unsubs = patterns.map((pattern) => runtime.bus.subscribePattern(pattern, () => {
+            runtime.queryClient.invalidateQueries({ queryKey: [name] });
+        }));
+        return () => {
+            for (const off of unsubs)
+                off();
+        };
+    }, [runtime.bus, runtime.queryClient, name, patterns, isRxdb]);
+    const refetch = React.useCallback(async () => {
+        if (isRxdb)
+            return;
+        await query.refetch();
+    }, [isRxdb, query]);
+    if (isRxdb) {
+        return {
+            data: rxState.data,
+            loading: rxState.loading,
+            error: rxState.error,
+            refetch,
+            isStale: false,
+        };
+    }
+    return {
+        data: query.data,
+        loading: query.isPending,
+        error: query.error ?? null,
+        refetch,
+        isStale: query.isStale,
+    };
+}
+/**
+ * T-14 — screen-facing mutation hook.
+ *
+ * Runs authorize + exec (via the app-provided config) through TanStack
+ * useMutation. On success, emits each `invalidates` entry on the event
+ * bus so subscribing queries invalidate their caches. If `optimistic`
+ * is defined, the returned `data` reflects the optimistic value while
+ * the mutation is pending and reverts on failure.
+ */
+export function useAppMutation(name) {
+    const runtime = useDataAccessRuntime();
+    const def = lookupDefinition(runtime.registry.mutations, 'mutation', name);
+    const [optimisticValue, setOptimisticValue] = React.useState(undefined);
+    const mutation = useMutation({
+        mutationFn: async (input) => {
+            const ctx = runtime.getContext();
+            const parsedInput = parseWithSchema(def.config.input, input, 'input', name);
+            await runAuthorize(def.config.authorize, parsedInput, ctx);
+            const raw = await def.config.exec(parsedInput, ctx);
+            return parseWithSchema(def.config.output, raw, 'output', name);
+        },
+        onMutate: (input) => {
+            if (!def.config.optimistic)
+                return undefined;
+            const ctx = runtime.getContext();
+            const value = def.config.optimistic(input, ctx);
+            setOptimisticValue(value);
+            return undefined;
+        },
+        onSuccess: () => {
+            const patterns = def.config.invalidates ?? [];
+            for (const pattern of patterns) {
+                runtime.bus.emit(pattern, undefined);
+            }
+        },
+        onSettled: () => {
+            // Clear the optimistic snapshot so subsequent mutations start
+            // clean. On failure this achieves the "revert" — mutation.data
+            // returns to undefined and the optimistic layer disappears.
+            setOptimisticValue(undefined);
+        },
+    });
+    const data = mutation.isPending && optimisticValue !== undefined
+        ? optimisticValue
+        : mutation.data;
+    return {
+        mutate: mutation.mutate,
+        mutateAsync: mutation.mutateAsync,
+        loading: mutation.isPending,
+        error: mutation.error ?? null,
+        data,
+        reset: mutation.reset,
+    };
+}
+/**
+ * T-15 — subscribe to a named event for the lifetime of the mounting
+ * component. Handler runs on every emit whose name matches exactly; use
+ * the pattern form (bus.subscribePattern) directly for glob semantics.
+ *
+ * The handler ref is kept fresh so callers may pass unstable closures
+ * without churning the subscription.
+ */
+export function useAppEvent(name, handler) {
+    const runtime = useDataAccessRuntime();
+    const handlerRef = React.useRef(handler);
+    React.useEffect(() => {
+        handlerRef.current = handler;
+    }, [handler]);
+    React.useEffect(() => {
+        const off = runtime.bus.subscribe(name, (payload) => {
+            handlerRef.current(payload);
+        });
+        return off;
+    }, [runtime.bus, name]);
+}
+/**
+ * T-17 — read the current session's RequestContext from the provider.
+ * The provider's `context` callback is invoked on every read so
+ * callers pick up session updates without re-mounting.
+ */
+export function useRequestContext() {
+    const runtime = useDataAccessRuntime();
+    return runtime.getContext();
+}
+// --- helpers ---------------------------------------------------------
+function lookupDefinition(bag, label, name) {
+    const def = bag[name];
+    if (!def) {
+        throw new DataAccessError('engine_missing', `no ${label} named "${name}" is registered`);
+    }
+    return def;
+}
+function parseWithSchema(schema, value, side, name) {
+    if (!schema)
+        return value;
+    const result = schema.safeParse(value);
+    if (!result.success) {
+        throw new DataAccessError('zod_parse_failed', `mutation "${name}" ${side} failed schema validation: ${result.error.message}`, result.error);
+    }
+    return result.data;
+}
+//# sourceMappingURL=hooks.js.map