@noy-db/hub 0.3.0-pre.8 → 0.3.0

package/dist/kernel/query/scan-builder.d.ts

@@ -0,0 +1,334 @@
+/**
+ * Streaming scan builder with filter + aggregate support.
+ *
+ * `Collection.scan()` now returns a `ScanBuilder<T>` that
+ * implements `AsyncIterable<T>` (for existing `for await … of`
+ * consumers) AND exposes chainable `.where()` / `.filter()` clauses
+ * plus a `.aggregate(spec)` async terminal that reduces the scan
+ * stream through the same reducer protocol as `Query.aggregate()`
+ *.
+ *
+ * **Memory model:** O(reducers), not O(records). The aggregate
+ * terminal initializes one state per reducer, iterates through the
+ * scan one record at a time via `for await`, applies every reducer's
+ * `step` per record, and never collects the stream into an array.
+ * This is what makes `scan().aggregate()` suitable for collections
+ * that don't fit in memory — the bound is a code-level invariant
+ * visible in the function body, not a runtime assertion.
+ *
+ * **Paginated iteration:** the builder holds a `pageProvider`
+ * closure that maps `(cursor, limit) → Promise<page>`, plumbed by
+ * `Collection.scan()` to `collection.listPage(...)`. The page
+ * iterator walks cursors forward until exhaustion, same as the
+ * previous async-generator `scan()` did.
+ *
+ * **Backward compatibility:** existing `for await (const rec of
+ * collection.scan()) { … }` code continues to work because
+ * `ScanBuilder` implements `[Symbol.asyncIterator]`. The previous
+ * signature returned an `AsyncIterableIterator<T>` (which has both
+ * `[Symbol.asyncIterator]` and `.next()`). We verified at grep time
+ * that no call sites use `.next()` on the scan result directly, so
+ * the narrowed interface is safe.
+ *
+ * **Immutability:** each `.where()` / `.filter()` call returns a
+ * fresh builder sharing the same page provider and page size. This
+ * lets a base scan be reused for multiple parallel aggregations:
+ *
+ * ```ts
+ * const scan = invoices.scan()
+ * const [open, paid] = await Promise.all([
+ *   scan.where('status', '==', 'open').aggregate({ n: count() }),
+ *   scan.where('status', '==', 'paid').aggregate({ n: count() }),
+ * ])
+ * ```
+ *
+ * Note that each aggregation pays a full scan — there's no shared
+ * iteration across the two. Multi-way aggregation in a single pass
+ * is out of scope; consumers who need it should build a compound spec
+ * and run a single `.aggregate({ openN, paidN })` at the DSL level.
+ *
+ * **Out of scope for (tracked separately):**
+ *   - `scan().aggregate().live()` — unbounded scan + change-stream
+ *     reconciliation is a design problem, not just a code one
+ *   - `scan().groupBy().aggregate()` — high-cardinality grouping on
+ *     huge collections would re-introduce the O(groups) memory
+ *     problem that aggregate fixes
+ *   - Parallel scan across pages — race-safe page cursor contracts
+ *     are not in the adapter API yet
+ *   - `scan().join(...)` — tracked under  (streaming join)
+ */
+import type { QueryField } from '../types.js';
+import type { ReducerBuilder } from '../../with-lookup/aggregate/reducers.js';
+import type { Clause, Operator } from './predicate.js';
+import type { AggregateSpec, AggregateResult } from '../../with-lookup/aggregate/aggregation.js';
+import type { JoinContext, JoinLeg } from './join.js';
+import type { ViaPipeline } from '../via/pipeline.js';
+/**
+ * Page provider — the Collection-shaped hook the builder calls to
+ * walk cursors forward. Kept as a structural interface so tests can
+ * wire up a synthetic provider without pulling in the full
+ * Collection class. Collection's `listPage` matches this shape
+ * exactly.
+ */
+export interface ScanPageProvider<T> {
+    listPage(opts: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        items: T[];
+        nextCursor: string | null;
+    }>;
+}
+/**
+ * Chainable streaming scan. Implements `AsyncIterable<T>` for
+ * drop-in use with `for await … of`; adds `.where()` / `.filter()`
+ * chainable clauses and a `.aggregate(spec)` async terminal.
+ *
+ * The builder is immutable per operation — each chained call
+ * returns a fresh `ScanBuilder` sharing the same page provider and
+ * page size. The original builder is never mutated, so it's safe
+ * to reuse across multiple parallel consumers.
+ */
+export declare class ScanBuilder<T, S extends keyof T = never, M extends keyof T & string = never> implements AsyncIterable<T> {
+    private readonly pageProvider;
+    private readonly pageSize;
+    private readonly clauses;
+    /**
+     * Zero-or-more join legs to apply per record as the stream flows.
+     * Each leg attaches the resolved right-side record (or null) under
+     * its alias. — streaming joins.
+     *
+     * Joins are evaluated AFTER clauses, so a `where()` filtered-out
+     * record never triggers a right-side lookup. This is the same
+     * ordering as `Query.toArray()` (clauses first, joins after) and
+     * keeps the streaming path from doing wasted work.
+     */
+    private readonly joins;
+    /**
+     * Join resolution context. Required for `.join()` to translate a
+     * field name into a target collection + ref mode and to resolve
+     * the right-side `JoinableSource`. Optional because tests
+     * construct ScanBuilder directly with synthetic page providers
+     * that don't know about ref() — calling `.join()` without a
+     * context throws with an actionable error.
+     */
+    private readonly joinContext;
+    /**
+     * The backing collection's compiled Via pipeline (money now; more Via
+     * features later). When it declares a result decode, yielded records
+     * are decoded (e.g. money: stored scaled-int → canonical decimal) so
+     * `scan()` agrees with `get()`/`list()`/`query().toArray()`. Decoded
+     * with `'raw'` (canonical decimal, no locale-formatted virtuals) since
+     * the scan stream carries no locale context, mirroring `Query.toArray()`.
+     */
+    private readonly via;
+    constructor(pageProvider: ScanPageProvider<T>, pageSize?: number, clauses?: readonly Clause[], joins?: readonly JoinLeg[], joinContext?: JoinContext, via?: ViaPipeline);
+    /**
+     * Decode this scan's Via-covered fields on a record (e.g. money: stored
+     * scaled-int → canonical decimal). No-op when the Via pipeline declares
+     * no result decode. See {@link via}.
+     */
+    private decodeVia;
+    /**
+     * Add a field comparison. Runs per record as the scan stream
+     * flows through, so non-matching records are dropped before they
+     * reach `.aggregate()` or the iteration consumer. Multiple
+     * `.where()` calls are AND-combined — same semantics as
+     * `Query.where()`.
+     *
+     * Clauses cannot use the secondary-index fast path here because
+     * the scan sources records from the adapter's paginator, not from
+     * the in-memory cache where indexes live. Index-accelerated scans
+     * are a future optimization — the current implementation
+     * evaluates clauses per record in O(1) per clause.
+     *
+     * Consults the Via pipeline's posture before building a clause (#629
+     * Task 8): a field whose posture is `queryable: 'none'` throws
+     * `FieldNotQueryableError` here, at the call site — same gate as
+     * `Query.where()`.
+     */
+    where(field: QueryField<T, S>, op: Operator, value: unknown): ScanBuilder<T, S, M>;
+    /**
+     * Escape hatch: add an arbitrary predicate function. Same
+     * non-serializable caveat as `Query.filter()` — filter clauses
+     * don't round-trip through `toPlan()`. Prefer `.where()` when
+     * possible.
+     */
+    filter(fn: (record: T) => boolean): ScanBuilder<T, S, M>;
+    /**
+     * Resolve a `ref()`-declared foreign key per record as the scan
+     * stream flows, attaching the right-side record (or null) under
+     * `opts.as`. — streaming joins over `scan()`.
+     *
+     * ```ts
+     * for await (const inv of invoices.scan().join('clientId', { as: 'client' })) {
+     *   await processInvoice(inv) // inv.client is attached
+     * }
+     *
+     * // Or terminate with .aggregate() for streaming joined aggregation
+     * const { total } = await invoices.scan()
+     *   .where('status', '==', 'open')
+     *   .join('clientId', { as: 'client' })
+     *   .aggregate({ total: sum('amount') })
+     * ```
+     *
+     * **The key difference from eager `.join()`:** the LEFT
+     * side streams page-by-page from the adapter and is never
+     * materialized. Memory ceiling on the left is O(pageSize), not
+     * O(rowCount). This is what makes streaming joins suitable for
+     * collections that exceed the eager join's 50_000-row ceiling.
+     *
+     * **Right-side strategy** is auto-selected per leg:
+     *   - **Indexed** — right source exposes `lookupById`, so each
+     *     left row costs O(1). This is the common path for
+     *     Collection right sides, which back `lookupById` with a Map
+     *     lookup over the in-memory cache. The right collection must
+     *     be in eager mode (the same constraint as eager join's
+     *     `querySourceForJoin` from ).
+     *   - **Hash** — right source has only `snapshot()`. Build a
+     *     `Map<id, record>` once at iteration start, probe per left
+     *     row. Same correctness, same per-row cost as the indexed
+     *     path; the difference is the upfront cost of materializing
+     *     the right side once.
+     *
+     * Both strategies hold the right side in memory for the duration
+     * of the iteration. The "streaming" property applies to the LEFT
+     * side only — true left-and-right streaming joins (where neither
+     * side fits in memory) require a sort-merge join planner that's
+     * out of scope for.
+     *
+     * **Ref-mode semantics** match eager `.join()` exactly:
+     *   - `strict`  → throws `DanglingReferenceError` mid-stream
+     *     when a left record points at a non-existent right id.
+     *     The throw aborts the async iterator — consumers should
+     *     wrap the `for await` in try/catch if they want to recover.
+     *   - `warn`    → attaches `null` and emits a one-shot warning
+     *     per unique dangling pair (deduped via the same warn
+     *     channel as eager join).
+     *   - `cascade` → attaches `null` silently. A delete-time mode;
+     *     dangling refs at read time are mid-flight or pre-existing
+     *     orphans, not a DSL error.
+     *
+     * Left records with null/undefined FK values attach `null`
+     * regardless of mode — same "no reference at all" policy as
+     * eager join and write-time `enforceRefsOnPut`.
+     *
+     * **Multi-FK chaining** is supported via repeated `.join()`
+     * calls: each leg resolves an independent ref. Each leg
+     * independently picks its right-side strategy and applies its
+     * own ref mode.
+     *
+     * **Joins are NOT applied** to a `.aggregate()` terminal that
+     * doesn't reference joined fields — wait, that's not quite
+     * right. The streaming path actually DOES apply joins before
+     * `.aggregate()` because the join attaches a field that the
+     * spec might reference. Unlike `Query.aggregate()` (which skips
+     * joins entirely as a projection-only short-circuit), the
+     * streaming aggregation can't know whether the spec touches a
+     * joined field, so it always applies joins. Consumers who want
+     * unjoined streaming aggregation should leave `.join()` off the
+     * chain — the chain is composable for a reason.
+     *
+     *  constraint #1 — every JoinLeg carries `partitionScope:
+     * 'all'` plumbed through but never read by. Same seam as
+     * eager join.
+     */
+    join<As extends string, R = unknown>(field: QueryField<T, S>, opts: {
+        as: As;
+    }): ScanBuilder<T & Record<As, R | null>, S, M>;
+    /**
+     * Iterate the scan as an async iterable. Walks the page
+     * provider's cursors forward until exhaustion, applying every
+     * clause per record — only matching records are yielded.
+     *
+     * Backward-compatible with the previous async-generator `scan()`
+     * return type for `for await … of` consumers.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    /**
+     * Per-leg right-side resolution state. Built once at iteration
+     * start and reused for every left record. Two strategies:
+     *
+     *   - `lookupById`: present when the right source exposes the
+     *     hook directly (typical Collection right side). Per-row
+     *     cost is O(1).
+     *   - `hashByPrimaryKey`: built from `snapshot()` when no
+     *     lookupById. Per-row cost is O(1) after the upfront O(N)
+     *     materialization. Same as eager join's hash strategy.
+     *
+     * `warnedKeys` is the per-leg dedup set for ref-mode 'warn'. We
+     * key on `field→target:refId` so the same dangling pair only
+     * warns once per iteration. The dedup is per-iteration, not
+     * per-process — a long-running scan that re-iterates would warn
+     * again, which is the desired behavior (the data may have
+     * changed between iterations).
+     */
+    private buildJoinResolvers;
+    /**
+     * Resolve a single join leg for one left record and return the
+     * left record with the joined field attached under
+     * `leg.as`. Pure function over `(left, resolver)`; never
+     * mutates the input.
+     *
+     * Ref-mode dispatch matches eager `applyJoins` from :
+     *   - null/undefined FK → attach null silently (always allowed)
+     *   - dangling FK + strict → throw `DanglingReferenceError`
+     *   - dangling FK + warn → attach null, warn-once per pair
+     *   - dangling FK + cascade → attach null silently
+     */
+    private applyOneJoinStreaming;
+    /**
+     * Reduce the scan stream through a named set of reducers and
+     * return the final aggregated shape.
+     *
+     * Memory is O(reducers): one mutable state slot per spec key.
+     * Records flow through the pipeline one at a time via
+     * `for await` and are discarded after their `step()` is applied
+     * — never collected into an array. This is the distinguishing
+     * property from `Query.aggregate()`, which materializes the full
+     * match set first.
+     *
+     * Reuses the same reducer protocol as `Query.aggregate()`,
+     * so `count()`, `sum(field)`, `avg(field)`, `min(field)`,
+     * `max(field)` all work unchanged. The `{ seed }` parameter
+     * plumbing from  constraint #2 is honored transparently — the
+     * factories ignore it in and the scan executor never
+     * touches the per-reducer state construction.
+     *
+     * **Returns a Promise**, unlike `Query.aggregate().run()` which
+     * is synchronous. The scan is inherently async because it walks
+     * adapter pages, so the terminal has to be too. Consumers
+     * destructure with await:
+     *
+     * ```ts
+     * const { total, n } = await invoices.scan()
+     *   .where('year', '==', 2025)
+     *   .aggregate({ total: sum('amount'), n: count() })
+     * ```
+     *
+     * **No `.live()` in.** `scan().aggregate().live()` would
+     * require reconciling an unbounded streaming iteration with a
+     * change-stream subscription — a design problem, not just a code
+     * one. Consumers with huge collections and live needs should
+     * narrow with `.where()` enough to fit in the 50k `query()`
+     * limit and use `query().aggregate().live()` instead.
+     *
+     * Consults the Via pipeline's posture before reducing (#629 Task 8 review
+     * fix wave 1): a reducer over a field whose posture is `queryable: 'none'`
+     * throws `FieldNotQueryableError` here, metadata-only — via
+     * `ViaPipeline.refuseUnqueryableReducers`, NOT the full `wrapReducers`
+     * (which would also activate money's exact-reducer rewrite, a path this
+     * method has never run and must not start running as a side effect of
+     * this gate).
+     */
+    aggregate<Spec extends AggregateSpec>(spec: Spec): Promise<AggregateResult<Spec>>;
+    aggregate<Spec extends AggregateSpec>(build: (b: ReducerBuilder<T, S, M>) => Spec): Promise<AggregateResult<Spec>>;
+    /**
+     * Evaluate the clause list against a single record. Linear in
+     * the clause count; short-circuits on first false. Clauses on a
+     * scan are always re-evaluated per record — no index-accelerated
+     * path, because the stream sources records from the adapter
+     * paginator, not from the in-memory cache where indexes live.
+     */
+    private recordMatches;
+}

package/dist/kernel/refs.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Foreign-key references — the soft-FK mechanism.
+ *
+ * A collection declares its references as metadata at construction
+ * time:
+ *
+ * ```ts
+ * import { ref } from '@noy-db/hub'
+ *
+ * const invoices = company.collection<Invoice>('invoices', {
+ *   refs: {
+ *     clientId: ref('clients'),            // default: strict
+ *     categoryId: ref('categories', 'warn'),
+ *     parentId:  ref('invoices', 'cascade'), // self-reference OK
+ *   },
+ * })
+ * ```
+ *
+ * Three modes:
+ *
+ *   - **strict** — the default. `put()` rejects records whose
+ *     reference target doesn't exist, and `delete()` of the target
+ *     rejects if any strict-referencing records still exist.
+ *     Matches SQL's default FK semantics.
+ *
+ *   - **warn** — both operations succeed unconditionally. Broken
+ *     references surface only through
+ *     `vault.checkIntegrity()`, which walks every collection
+ *     and reports orphans. Use when you want soft validation for
+ *     imports from messy sources.
+ *
+ *   - **cascade** — `put()` is same as warn. `delete()` of the
+ *     target deletes every referencing record. Cycles are detected
+ *     and broken via an in-progress set, so mutual cascades
+ *     terminate instead of recursing forever.
+ *
+ * Cross-vault refs are explicitly rejected: if the target
+ * name contains a `/`, `ref()` throws `RefScopeError`. Cross-
+ * vault refs need an auth story (multi-keyring reads) that
+ * doesn't ship — tracked for.
+ */
+import { NoydbError } from './errors.js';
+/** The three enforcement modes. Default for new refs is `'strict'`. */
+export type RefMode = 'strict' | 'warn' | 'cascade';
+/**
+ * Descriptor returned by `ref()`. Collections accept a
+ * `Record<string, RefDescriptor>` in their options. The key is the
+ * field name on the record (top-level only — dotted paths are out of
+ * scope), the value describes which target collection the
+ * field references and under what mode.
+ *
+ * The descriptor carries only plain data so it can be serialized,
+ * passed around, and introspected without any class machinery.
+ */
+export interface RefDescriptor {
+    readonly target: string;
+    readonly mode: RefMode;
+    /**
+     * Present and `true` only for an array ref (`refArray()`): the
+     * field holds an ARRAY of ids, each validated against `target`
+     * independently (M:N). Absent for a scalar `ref()`. The same `mode`
+     * semantics apply per element — strict rejects on a missing element at
+     * put + blocks delete of a referenced target; cascade deletes every
+     * record whose array contains the deleted id; warn surfaces orphans
+     * only via `checkIntegrity()`.
+     */
+    readonly isArray?: true;
+}
+/** Runtime predicate: is this an array ref (`refArray()`) vs a scalar `ref()`? */
+export declare function isRefArray(desc: RefDescriptor): boolean;
+/**
+ * Thrown when a strict reference is violated — either `put()` with a
+ * missing target id, or `delete()` of a target that still has
+ * strict-referencing records.
+ *
+ * Carries structured detail so UI code (and a potential future
+ * devtools panel) can render "client X cannot be deleted because
+ * invoices 1, 2, and 3 reference it" instead of a bare error string.
+ */
+export declare class RefIntegrityError extends NoydbError {
+    readonly collection: string;
+    readonly id: string;
+    readonly field: string;
+    readonly refTo: string;
+    readonly refId: string | null;
+    constructor(opts: {
+        collection: string;
+        id: string;
+        field: string;
+        refTo: string;
+        refId: string | null;
+        message: string;
+    });
+}
+/**
+ * Thrown when `ref()` is called with a target name that looks like
+ * a cross-vault reference (contains a `/`). Separate error
+ * class because the fix is different: RefIntegrityError means "data
+ * is wrong"; RefScopeError means "the ref declaration is wrong".
+ */
+export declare class RefScopeError extends NoydbError {
+    constructor(target: string);
+}
+/**
+ * Helper constructor. Thin wrapper around the object literal so user
+ * code reads like `ref('clients')` instead of `{ target: 'clients',
+ * mode: 'strict' }` — this is the only ergonomics reason it exists.
+ *
+ * Validates the target name eagerly so a misconfigured ref declaration
+ * fails at collection construction time, not at the first put.
+ */
+export declare function ref(target: string, mode?: RefMode): RefDescriptor;
+/**
+ * Array reference — the many-to-many soft-FK. The field holds an
+ * array of ids; each element is validated against `target` independently.
+ *
+ * ```ts
+ * const orders = company.collection<Order>('orders', {
+ *   refs: { productIds: refArray('products', 'warn') },
+ * })
+ * ```
+ *
+ * Same three `mode` semantics as `ref()`, applied per element:
+ *   - **strict** — `put()` rejects if ANY element's target is missing;
+ *     `delete()` of a target is blocked while any record's array still
+ *     contains its id.
+ *   - **warn** — both succeed; orphaned elements surface via
+ *     `vault.checkIntegrity()` (one violation per dangling element).
+ *   - **cascade** — `delete()` of a target deletes every record whose
+ *     array contains its id (cycle-safe, like scalar cascade).
+ *
+ * A `null`/`undefined` field is allowed (no links). Non-array values, or
+ * non-string/number elements, are an integrity error. Cross-vault targets
+ * are rejected exactly as in `ref()`.
+ */
+export declare function refArray(target: string, mode?: RefMode): RefDescriptor;
+/**
+ * Per-vault registry of reference declarations.
+ *
+ * The registry is populated by `Collection` constructors (which pass
+ * their `refs` option through the Vault) and consulted by the
+ * Vault on every `put` / `delete` and by `checkIntegrity`. A
+ * single instance lives on the Vault for its lifetime; there's
+ * no global state.
+ *
+ * The data structure is two parallel maps:
+ *
+ *   - `outbound`: `collection → { field → RefDescriptor }` — what
+ *     refs does `collection` declare? Used on put to check
+ *     strict-target-exists and on checkIntegrity to walk each
+ *     collection's outbound refs.
+ *
+ *   - `inbound`:  `target → Array<{ collection, field, mode }>` —
+ *     which collections reference `target`? Used on delete to find
+ *     the records that might be affected by cascade / strict.
+ *
+ * The two views are kept in sync by `register()` and never mutated
+ * otherwise — refs can't be unregistered at runtime in.
+ */
+export declare class RefRegistry {
+    private readonly outbound;
+    private readonly inbound;
+    /**
+     * Register the refs declared by a single collection. Idempotent in
+     * the happy path — calling twice with the same data is a no-op.
+     * Calling twice with DIFFERENT data throws, because silent
+     * overrides would be confusing ("I changed the ref and it doesn't
+     * update" vs "I declared the same collection twice with different
+     * refs and the second call won").
+     */
+    register(collection: string, refs: Record<string, RefDescriptor>): void;
+    /** Get the outbound refs declared by a collection (or `{}` if none). */
+    getOutbound(collection: string): Record<string, RefDescriptor>;
+    /** Get the inbound refs that target a given collection (or `[]`). */
+    getInbound(target: string): ReadonlyArray<{
+        collection: string;
+        field: string;
+        mode: RefMode;
+        isArray?: true;
+    }>;
+    /**
+     * Iterate every (collection → refs) pair that has at least one
+     * declared reference. Used by `checkIntegrity` to walk the full
+     * universe of outbound refs without needing to track collection
+     * names elsewhere.
+     */
+    entries(): Array<[string, Record<string, RefDescriptor>]>;
+    /** Clear the registry. Test-only escape hatch; never called from production code. */
+    clear(): void;
+}
+/**
+ * Shape of a single violation reported by `vault.checkIntegrity()`.
+ *
+ * `refId` is the value we saw in the referencing field — it's the
+ * ID we expected to find in `refTo`, but didn't. Left as `unknown`
+ * because records are loosely typed at the integrity-check layer.
+ */
+export interface RefViolation {
+    readonly collection: string;
+    readonly id: string;
+    readonly field: string;
+    readonly refTo: string;
+    readonly refId: unknown;
+    readonly mode: RefMode;
+}

package/dist/kernel/schema.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Standard Schema v1 integration.
+ *
+ * This file is the entry point for **schema validation**. Any
+ * validator that implements the [Standard Schema v1
+ * protocol](https://standardschema.dev) — Zod, Valibot, ArkType, Effect
+ * Schema, etc. — can be attached to a `Collection` or `defineNoydbStore`
+ * and will:
+ *
+ *   1. Validate the record BEFORE encryption on `put()` — bad data is
+ *      rejected at the store boundary with a rich issue list.
+ *   2. Validate the record AFTER decryption on `get()`/`list()`/`query()`
+ *      — stored data that has drifted from the current schema throws
+ *      loudly instead of silently propagating garbage to the UI.
+ *
+ * ## Why vendor the types?
+ *
+ * Standard Schema is a protocol, not a library. The spec is <200 lines of
+ * TypeScript and has no runtime. There's an official `@standard-schema/spec`
+ * types package on npm, but pulling it in would add a dependency edge
+ * purely for type definitions. Vendoring the minimal surface keeps
+ * `@noy-db/core` at **zero runtime dependencies** and gives us freedom to
+ * evolve the helpers without a version-lock on the spec package.
+ *
+ * If the spec changes in a breaking way (unlikely — it's frozen at v1),
+ * we update this file and bump our minor.
+ *
+ * ## Why not just run `schema.parse(value)` directly?
+ *
+ * Because then we'd be locked to whichever validator happens to have
+ * `.parse`. Standard Schema's `'~standard'.validate` contract is the same
+ * across every implementation and includes a structured issues list,
+ * which is much more useful than a thrown error for programmatic error
+ * handling (e.g., rendering field-level messages in a Vue component).
+ */
+/**
+ * The Standard Schema v1 protocol. A schema is any object that exposes a
+ * `'~standard'` property with `version: 1` and a `validate` function.
+ *
+ * The type parameters are:
+ *   - `Input`  — the type accepted by `validate` (what the user passes in)
+ *   - `Output` — the type produced by `validate` (what we store/return,
+ *                may differ from Input if the schema transforms or coerces)
+ *
+ * In most cases `Input === Output`, but validators that transform
+ * (Zod's `.transform`, Valibot's `transform`, etc.) can narrow or widen.
+ *
+ * We intentionally keep the `types` field `readonly` and optional — the
+ * spec marks it as optional because it's only used for inference, and
+ * not every implementation bothers populating it at runtime.
+ */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardSchemaV1SyncResult<Output> | Promise<StandardSchemaV1SyncResult<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        } | undefined;
+    };
+}
+/**
+ * The result of a single call to `schema['~standard'].validate`. Either
+ * `{ value }` on success or `{ issues }` on failure — never both.
+ *
+ * The spec allows `issues` to be undefined on success (and some
+ * validators leave it that way), so consumers should discriminate on
+ * `issues?.length` rather than on truthiness of `value`.
+ */
+export type StandardSchemaV1SyncResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly value?: undefined;
+    readonly issues: readonly StandardSchemaV1Issue[];
+};
+/**
+ * A single validation issue. The `message` is always present; the `path`
+ * is optional and points at the offending field when the schema tracks
+ * it (virtually every validator does for object types).
+ *
+ * The path is deliberately permissive — both a plain `PropertyKey` and a
+ * `{ key }` wrapper are allowed so validators that wrap path segments in
+ * objects (Zod does this in some modes) don't need special handling.
+ */
+export interface StandardSchemaV1Issue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | {
+        readonly key: PropertyKey;
+    }> | undefined;
+}
+/**
+ * Infer the output type of a Standard Schema. Consumers use this to
+ * pull the type out of a schema instance when they want to declare a
+ * Collection<T> or defineNoydbStore<T> with `T` derived from the schema.
+ *
+ * Example:
+ * ```ts
+ * const InvoiceSchema = z.object({ id: z.string(), amount: z.number() })
+ * type Invoice = InferOutput<typeof InvoiceSchema>
+ * ```
+ */
+export type InferOutput<T extends StandardSchemaV1> = T extends StandardSchemaV1<unknown, infer O> ? O : never;
+/**
+ * Validate an input value against a schema. Throws
+ * `SchemaValidationError` if the schema rejects, with the rich issue
+ * list attached. Otherwise returns the (possibly transformed) output
+ * value.
+ *
+ * The `context` string is included in the thrown error's message so the
+ * caller knows where the failure happened (e.g. `"put(inv-001)"`) without
+ * every caller having to wrap the throw in a try/catch.
+ *
+ * This function is ALWAYS async because some validators (notably Effect
+ * Schema and Zod's `.refine` with async predicates) can return a
+ * Promise. We `await` the result unconditionally to normalize the
+ * contract — the extra microtask is free compared to the cost of an
+ * encrypt/decrypt round-trip.
+ */
+export declare function validateSchemaInput<Output>(schema: StandardSchemaV1<unknown, Output>, value: unknown, context: string): Promise<Output>;
+/**
+ * Validate an already-stored value coming OUT of the collection. This
+ * is a distinct helper from `validateSchemaInput` because the error
+ * semantics differ: an output-validation failure means the data in
+ * storage has drifted from the current schema (an unexpected state),
+ * whereas an input-validation failure means the user passed bad data
+ * (an expected state for a UI that isn't guarding its inputs).
+ *
+ * We still throw — silently returning bad data would be worse — but
+ * the error carries `direction: 'output'` so upstream code (and a
+ * potential migrate hook) can distinguish the two cases.
+ */
+export declare function validateSchemaOutput<Output>(schema: StandardSchemaV1<unknown, Output>, value: unknown, context: string): Promise<Output>;