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

package/dist/with-shape/schema-update/fence-controller.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Vault-level schema-fence controller.
+ *
+ * Owns the open-time generation snapshot, the pending-cutover registry,
+ * and the cutover orchestration. 3a: single-client (the caller is the
+ * migrator). 3b: a cooperative ack-barrier — after `draining`, the
+ * migrator waits for the active client set (registry heartbeats) to ack
+ * the draining generation before transforming. No leader election.
+ *
+ * The transport is the injected {@link CoordinationProvider} port: the
+ * default {@link StoreCoordinationProvider} maps it onto today's
+ * `_meta/schema-fence` store ops, so behavior is byte-for-byte the same;
+ * `by-tabs` / `by-peer` swap in real-time push transports.
+ */
+import { type FenceState } from './fence.js';
+import type { TransformFn } from './types.js';
+import { type CoordinationProvider } from '../../port/by/index.js';
+/** Runs one collection's transform; supplied by the Vault (binds to a Collection). */
+export type RunTransform = (collection: string, transform: TransformFn) => Promise<void>;
+export declare class SchemaFenceController {
+    #private;
+    constructor(opts: {
+        coordination: CoordinationProvider;
+        vault: string;
+        onFlush: () => Promise<void>;
+        /** Stable per-instance id; the migrator excludes itself from the barrier. */
+        clientId?: string;
+        /**
+         * Accepted for wiring symmetry with {@link FenceWatcher}, but the migrator
+         * never reports its own presence (it excludes itself from the barrier), so
+         * it carries no session of its own.
+         */
+        sessionId?: string;
+        now?: () => number;
+        staleMs?: number;
+        quiesceTimeoutMs?: number;
+        emit?: (e: {
+            currentSchemaVersion: number;
+            fenceState: FenceState;
+        }) => void;
+    });
+    /** Capture the generation snapshot at vault-open. */
+    init(): Promise<void>;
+    /** Record a per-collection pending cutover (from a registration `cutover` decision). */
+    registerPendingCutover(collection: string, transform: TransformFn): void;
+    /** Write-path gate. Throws when behind, fenced, or this collection is cutover-pending. */
+    assertWritable(collection: string): Promise<void>;
+    /**
+     * Admin trigger. Drain → wait for the active set to quiesce (or time out)
+     * → migrate each pending transform → bump → complete → normal. The
+     * migrator excludes itself from the barrier (it drained synchronously
+     * inside {@link runDrainBarrier}). `onPoll` (tests) advances other clients
+     * between barrier checks; production falls back to a short real delay.
+     */
+    runCutover(run: RunTransform, opts?: {
+        onPoll?: () => Promise<void>;
+    }): Promise<{
+        migrated: number;
+    }>;
+    /** Recover a stuck drain: reset fenceState to normal at the current version (no bump). */
+    abort(): Promise<void>;
+}

package/dist/with-shape/schema-update/fence-watcher.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Per-client schema-fence watcher. Watches the fence via the injected
+ * {@link CoordinationProvider}; on `draining` it drains in-flight writes
+ * and reports presence (its ack); emits a same-instance signal on every
+ * state transition (for UI). Driven by an interval in production and by
+ * explicit `check()`/`beat()` in tests.
+ *
+ * The transport is the coordination port: the default
+ * {@link StoreCoordinationProvider} maps `reportPresence` →
+ * `_meta/schema-fence:client:<id>` and `readFence` → `_meta/schema-fence`,
+ * so behavior is byte-for-byte the same; `by-tabs` / `by-peer` swap in
+ * real-time push transports.
+ */
+import { type FenceState } from './fence.js';
+import type { CoordinationProvider } from '../../port/by/index.js';
+export interface FenceWatcherEvent {
+    readonly currentSchemaVersion: number;
+    readonly fenceState: FenceState;
+}
+export declare class FenceWatcher {
+    #private;
+    constructor(opts: {
+        coordination: CoordinationProvider;
+        vault: string;
+        clientId: string;
+        sessionId?: string;
+        onFlush: () => Promise<void>;
+        now?: () => number;
+        emit?: (e: FenceWatcherEvent) => void;
+    });
+    /** Publish liveness (and the current ack) without changing quiesce state. */
+    beat(): Promise<void>;
+    /** Poll the fence; quiesce on draining; emit on transitions. */
+    check(): Promise<void>;
+    start(intervalMs: number): void;
+    stop(): void;
+}

package/dist/with-shape/schema-update/fence.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Schema-fence document. Vault-level generation counter + drain
+ * state, stored at `_meta/schema-fence` using the plaintext-envelope
+ * pattern of `_meta/policy` (no PII — a counter + a state enum).
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+export type FenceState = 'normal' | 'draining' | 'migrating' | 'complete';
+export interface FenceDoc {
+    readonly currentSchemaVersion: number;
+    readonly fenceState: FenceState;
+}
+export declare const FENCE_RECORD_ID = "schema-fence";
+export declare const DEFAULT_FENCE: FenceDoc;
+export declare function loadFence(store: NoydbStore, vault: string): Promise<FenceDoc>;
+export declare function saveFence(store: NoydbStore, vault: string, fence: FenceDoc): Promise<void>;

package/dist/with-shape/schema-update/gate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Per-collection write gate. Holds the (async) update decision
+ * computed at registration; `Collection.put`/`delete` await it before
+ * writing and throw the strategy's rejection error.
+ *
+ * Detection FAILURE (the promise rejecting) is deliberately NOT a write
+ * block — schema detection is a fingerprint safety net, not a correctness
+ * invariant (matches how persisted-schema write failures are swallowed).
+ * Only an explicit `reject` decision blocks writes.
+ */
+import type { UpdateDecision } from './types.js';
+export declare class SchemaUpdateGate {
+    #private;
+    constructor(decision: Promise<UpdateDecision>);
+    assertWritable(): Promise<void>;
+}

package/dist/with-shape/schema-update/index.d.ts

@@ -0,0 +1,6 @@
+export type { SchemaDelta, FieldChange, UpdateContext, UpdateDecision, TransformFn, SchemaUpdateStrategy, } from './types.js';
+export { computeSchemaDelta } from './delta.js';
+export { evaluateStrategies } from './dispatch.js';
+export { blindUpdate, additiveOnly, lockSchema } from './strategies.js';
+export { coordinatedCutover } from './cutover.js';
+export { SchemaUpdateGate } from './gate.js';

package/dist/with-shape/schema-update/store-coordination-provider.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Store-backed default {@link CoordinationProvider}.
+ *
+ * Maps the five coordination-port methods onto today's `_meta/schema-fence`
+ * store ops so that, with no `by-*` provider injected, the fence service
+ * reproduces its current store-polling behavior byte-for-byte. The `observe*`
+ * methods are poll-emit (the legacy {@link FenceWatcher} model); `by-tabs` /
+ * `by-peer` override them with real-time push.
+ *
+ * @module
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import type { Unsubscribe } from '../../port/with/write-hooks.js';
+import type { CoordinationProvider, FenceState, WriterPresence } from '../../port/by/types.js';
+export declare class StoreCoordinationProvider implements CoordinationProvider {
+    #private;
+    constructor(store: NoydbStore, opts?: {
+        pollIntervalMs?: number;
+    });
+    setFence(vault: string, fence: FenceState): Promise<void>;
+    readFence(vault: string): Promise<FenceState>;
+    observeFence(vault: string, onChange: (f: FenceState) => void): Unsubscribe;
+    reportPresence(vault: string, p: WriterPresence): Promise<void>;
+    observePresence(vault: string, onChange: (writers: readonly WriterPresence[]) => void): Unsubscribe;
+    reachableWriters(vault: string, o: {
+        staleMs: number;
+        now: number;
+    }): Promise<readonly WriterPresence[]>;
+}

package/dist/with-shape/schema-update/strategies.d.ts

@@ -0,0 +1,12 @@
+import type { SchemaUpdateStrategy } from './types.js';
+/** Allow any schema change. Explicit blind / back-compat. */
+export declare function blindUpdate(): SchemaUpdateStrategy;
+/** Allow additive changes; reject non-additive ones. The safety backstop. */
+export declare function additiveOnly(): SchemaUpdateStrategy;
+/**
+ * Reject schema changes. With `fields`, reject only when one of those
+ * fields is added/removed/changed; otherwise reject any non-`none` delta.
+ */
+export declare function lockSchema(opts?: {
+    readonly fields?: readonly string[];
+}): SchemaUpdateStrategy;

package/dist/with-shape/schema-update/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Schema-update strategy framework types (M12 §3a).
+ *
+ * The hub core detects a schema change (SchemaDelta) and dispatches it
+ * through a collection's ordered strategy list. Strategies decide what
+ * happens; the core only knows this interface.
+ */
+/** A single changed top-level property in a schema delta. */
+export interface FieldChange {
+    readonly field: string;
+    /** True when the field's required-ness flipped. */
+    readonly requiredChanged: boolean;
+    /** True when the field's subschema shape changed. */
+    readonly shapeChanged: boolean;
+}
+/** The classified difference between a stored and a freshly-derived schema. */
+export interface SchemaDelta {
+    readonly collection: string;
+    readonly kind: 'none' | 'additive' | 'non-additive';
+    /** Top-level properties present in the new schema but not the old. */
+    readonly added: readonly string[];
+    /** Top-level properties present in the old schema but not the new. */
+    readonly removed: readonly string[];
+    /** Top-level properties present in both but altered. */
+    readonly changed: readonly FieldChange[];
+}
+/** Context handed to a strategy alongside the delta. */
+export interface UpdateContext {
+    readonly collection: string;
+}
+/** Bulk transform run by the coordinatedCutover strategy. */
+export type TransformFn = (doc: Record<string, unknown>) => Record<string, unknown>;
+/**
+ * A strategy's verdict on a detected schema change.
+ * - `allow`   — no objection; the dispatcher falls through to the next strategy.
+ * - `reject`  — terminal: refuse the change; `error` is thrown at the write path.
+ * - `cutover` — terminal: run a coordinated drain-barrier (handled by coordinatedCutover).
+ * New terminal actions may be added without breaking existing strategies.
+ */
+export type UpdateDecision = {
+    readonly action: 'allow';
+} | {
+    readonly action: 'reject';
+    readonly error: Error;
+} | {
+    readonly action: 'cutover';
+    readonly transform: TransformFn;
+};
+/** A pluggable schema-evolution policy. */
+export interface SchemaUpdateStrategy {
+    readonly name: string;
+    onSchemaDelta(delta: SchemaDelta, ctx: UpdateContext): UpdateDecision | Promise<UpdateDecision>;
+}

package/dist/with-store/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `@noy-db/hub` store routing + middleware — opt-in service.
+ *
+ * Store routing (multiplex by collection/size/age) and composable store
+ * middleware (retry, logging, metrics, circuit-breaker, cache, health-check).
+ * Root-barrel-only: no dedicated `@noy-db/hub/with-store` subpath export —
+ * consumers reach these through the main `@noy-db/hub` entry.
+ *
+ * Named re-exports (not `export *`) so tsup keeps the barrel populated
+ * even with `sideEffects: false`.
+ */
+export { routeStore } from './route-store.js';
+export type { RouteStoreOptions, RoutedNoydbStore, BlobStoreRoute, AgeRoute, BlobLifecyclePolicy, OverrideTarget, OverrideOptions, SuspendOptions, RouteStatus, } from './route-store.js';
+export { wrapStore, withRetry, withLogging, withMetrics, withCircuitBreaker, withCache, withHealthCheck, } from './store-middleware.js';
+export type { StoreMiddleware, RetryOptions, LoggingOptions, LogLevel, MetricsOptions, StoreOperation, CircuitBreakerOptions, StoreCacheOptions, HealthCheckOptions, } from './store-middleware.js';

package/dist/with-store/lazy/active.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Enable the lazy service (#267 Track A tail — lazy-mode promoted out of
+ * `routing` into its own opt-in service).
+ *
+ * Pass to `createNoydb({ lazyStrategy: withLazy() })` to explicitly opt
+ * into lazy mode's bounded-LRU working set for collections declared with
+ * `prefetch: false` + a `cache` budget. Behavior is identical to the
+ * deprecated implicit path (which warns once and will be removed at 1.0) —
+ * opting in is the forward-stable spelling and the catalog's contract.
+ */
+import type { LazyStrategy } from './strategy.js';
+export declare function withLazy(): LazyStrategy;

package/dist/with-store/lazy/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@noy-db/hub/lazy` — subpath export for the lazy service (#267).
+ *
+ * Lazy mode skips bulk hydration: a collection declared with
+ * `prefetch: false` + a `cache` budget reads per-id from the store into a
+ * bounded LRU working set (`list()`/`query()` throw — use `scan()` or
+ * per-id `get()`). Opt in with `lazyStrategy: withLazy()` in createNoydb.
+ *
+ * Named re-exports (not `export *`) so tsup keeps the barrel populated
+ * even with `sideEffects: false`.
+ */
+export { withLazy } from './active.js';
+export { IMPLICIT_LAZY, type LazyStrategy } from './strategy.js';
+export type { CacheOptions, CacheStats } from '../../kernel/collection.js';

package/dist/with-store/lazy/strategy.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Service-side shim for the lazy strategy seam (#267). The contract itself
+ * lives on the `/with` port (`src/port/with/lazy-strategy.ts`) so the
+ * kernel spine can hold the back-compat default without a spine→service
+ * static import (the port-layering rule). This file keeps the conventional
+ * `<service>/{strategy,active,index}.ts` layout.
+ * @internal
+ */
+export { IMPLICIT_LAZY, buildLazyCache, type LazyStrategy } from '../../port/with/lazy-strategy.js';

package/dist/with-store/route-store.d.ts

@@ -0,0 +1,259 @@
+/**
+ * Store router / multiplexer.
+ *
+ * Dispatches `NoydbStore` operations to different backends based on
+ * collection type, record size, record age, collection name, or vault name.
+ *
+ * ```ts
+ * const db = await createNoydb({
+ *   store: routeStore({
+ *     default: dynamo({ table: 'myapp' }),
+ *     blobs: s3Store({ bucket: 'myapp-blobs' }),
+ *   }),
+ * })
+ * ```
+ *
+ * @module
+ */
+import type { NoydbStore } from '../kernel/types.js';
+/**
+ * Size-tiered blob routing configuration.
+ *
+ * Routes blob chunks to different stores based on byte size. Small blobs
+ * (under `threshold`) stay in the primary or `small` store; large blobs
+ * go to `large`. This lets you keep DynamoDB as the default while sending
+ * large binary objects to S3.
+ */
+export interface BlobStoreRoute {
+    /** Store for small blobs (under threshold). Falls back to `default`. */
+    readonly small?: NoydbStore;
+    /** Store for large blobs (over threshold). */
+    readonly large: NoydbStore;
+    /** Size threshold in bytes. Default: `400 * 1024` (DynamoDB item limit). */
+    readonly threshold?: number;
+}
+/**
+ * Blob lifecycle management policies evaluated during `compact()`.
+ *
+ * Controls orphan cleanup, cold-tier archival, and hard deletion of
+ * blobs that are no longer referenced by any record.
+ */
+export interface BlobLifecyclePolicy {
+    /** Delete orphan blobs (refCount: 0) after this many days. Default: 7. */
+    readonly orphanRetentionDays?: number;
+    /** Move blobs not accessed in this many days to the cold blob store. */
+    readonly archiveAfterDays?: number;
+    /** Store for archived blobs. Required if archiveAfterDays is set. */
+    readonly archiveStore?: NoydbStore;
+    /** Hard-delete archived blobs after this many days. */
+    readonly expireAfterDays?: number;
+}
+/**
+ * Age-based hot/cold tiering configuration.
+ *
+ * Records whose `_ts` timestamp is older than `coldAfterDays` are migrated
+ * to the `cold` store during `compact()`. Reads transparently fall through
+ * to the cold store when the hot store returns null, so callers don't need
+ * to know which tier a record lives in.
+ */
+export interface AgeRoute {
+    /** Store for records older than the cutoff. */
+    readonly cold: NoydbStore;
+    /**
+     * Days after last modification before a record is cold-eligible for the
+     * ROLLING `compact(vault)` migrator. Omit for period-driven archival only
+     * (`compact(vault, { before })`), where the cutoff is supplied per call.
+     */
+    readonly coldAfterDays?: number;
+    /**
+     * Collections that participate in age tiering.
+     * Empty array or omitted = all user collections (excluding `_` prefixed).
+     */
+    readonly collections?: string[];
+}
+/**
+ * Options for `routeStore()` — the store multiplexer.
+ *
+ * At minimum, provide a `default` store. All other fields are optional
+ * extensions for specific routing scenarios (blobs → S3, geographic sharding,
+ * age-based tiering, etc.).
+ */
+export interface RouteStoreOptions {
+    /** Default store for all unmatched operations. */
+    readonly default: NoydbStore;
+    /**
+     * Route blob chunk data to a separate store.
+     * - Pass a `NoydbStore` for simple prefix routing (all chunks → that store).
+     * - Pass `{ small?, large, threshold? }` for size-tiered routing.
+     */
+    readonly blobs?: NoydbStore | BlobStoreRoute;
+    /** Route all blob metadata (index, slots, versions) to the blobs store too. Default: false. */
+    readonly routeBlobMeta?: boolean;
+    /** Route specific user collections to dedicated stores. */
+    readonly routes?: Record<string, NoydbStore>;
+    /** Route by vault name (prefix patterns, e.g. `'EU-'`). */
+    readonly vaultRoutes?: Record<string, NoydbStore>;
+    /**
+     * Age-based tiering: records older than `coldAfterDays` are read from
+     * the cold store. A background `compact()` method migrates them.
+     */
+    readonly age?: AgeRoute;
+    /**
+     * Content-aware blob routing.
+     * Route blob chunks by MIME type glob pattern. The MIME type is stored
+     * in `BlobObject` and matched at read time via `storeHint`.
+     */
+    readonly blobRoutes?: Record<string, NoydbStore>;
+    /**
+     * Blob lifecycle policies.
+     * Evaluated during `compact()`.
+     */
+    readonly blobLifecycle?: BlobLifecyclePolicy;
+    /**
+     * Quota-aware overflow.
+     * When the default store's usage exceeds the threshold, new writes
+     * overflow to the specified store.
+     */
+    readonly overflow?: NoydbStore;
+    /**
+     * Quota threshold (0-1). Default: 0.8 (overflow at 80% usage).
+     * Only effective when `overflow` is set.
+     */
+    readonly quotaThreshold?: number;
+}
+/**
+ * Named route that can be overridden or suspended at runtime.
+ *
+ * Built-in names: `'default'`, `'blobs'`, `'cold'`.
+ * Custom names: any collection name from `routes`, any vault prefix from
+ * `vaultRoutes`, or any sync target label.
+ */
+export type OverrideTarget = 'default' | 'blobs' | 'cold' | (string & {});
+/**
+ * Options for `RoutedNoydbStore.override()`.
+ *
+ * Controls whether the new store is pre-populated with data from the
+ * original store before the switch takes effect.
+ */
+export interface OverrideOptions {
+    /**
+     * Hydrate the override store from the original before activating.
+     * - `true` — copy all data for all vaults.
+     * - `string[]` — copy only named collections.
+     * Makes `override()` async — returns a Promise.
+     */
+    hydrate?: boolean | string[];
+}
+/**
+ * Options for `RoutedNoydbStore.suspend()`.
+ *
+ * A suspended route becomes a null store: reads return null/[], writes
+ * are dropped (or buffered if `queue: true`). Useful for maintenance
+ * windows or restricted-network scenarios.
+ */
+export interface SuspendOptions {
+    /**
+     * Buffer write operations during suspension. On `resume()`, queued
+     * writes are replayed against the restored store.
+     */
+    queue?: boolean;
+    /**
+     * Maximum queued operations. When exceeded, oldest entries are dropped.
+     * Default: 10_000.
+     */
+    maxQueueSize?: number;
+}
+/**
+ * Snapshot of the current override and suspend state of a `RoutedNoydbStore`.
+ * Returned by `routeStatus()` for diagnostics and health dashboards.
+ */
+export interface RouteStatus {
+    /** Active overrides: route name → override store name. */
+    readonly overrides: Record<string, string>;
+    /** Currently suspended routes. */
+    readonly suspended: string[];
+    /** Queued writes per suspended route (only for routes suspended with `queue: true`). */
+    readonly queued: Record<string, number>;
+}
+/**
+ * Extended `NoydbStore` returned by `routeStore()`.
+ *
+ * Satisfies the full `NoydbStore` contract plus adds runtime control
+ * methods for overriding, suspending, and inspecting routes.
+ */
+export interface RoutedNoydbStore extends NoydbStore {
+    /**
+     * Migrate records to the cold store. Only applies when `age.cold` is
+     * configured. With `{ before }`, migrates records whose `_ts < before`
+     * (period-driven archival); without, uses the rolling `coldAfterDays`.
+     * Returns the number of records migrated.
+     */
+    compact(vault: string, opts?: {
+        before?: string;
+    }): Promise<number>;
+    /**
+     * Override a named route at runtime.
+     *
+     * The override persists until `clearOverride()` is called or the
+     * instance is closed. In-flight operations complete on the original
+     * store; new operations use the override.
+     *
+     * Options:
+     * - `hydrate: true` — async: copies all data from the original store
+     *   into the override before activating the switch.
+     * - `hydrate: ['invoices', 'clients']` — copies only named collections.
+     *
+     * Use cases:
+     * - Shared device: `await store.override('default', memory(), { hydrate: true })`
+     * - Restricted network: `store.override('blobs', localFile(...))`
+     */
+    override(route: OverrideTarget, store: NoydbStore, opts?: OverrideOptions): void | Promise<void>;
+    /** Clear a runtime override, reverting to the original store. */
+    clearOverride(route: OverrideTarget): void;
+    /**
+     * Suspend a route entirely. Operations to suspended stores become
+     * no-ops (puts silently dropped, gets return null, lists return []).
+     *
+     * Options:
+     * - `queue: true` — buffer write operations (put/delete) during
+     *   suspension. When `resume()` is called, queued writes are replayed
+     *   against the restored store.
+     *
+     * Returns a `SuspendHandle` when `queue: true`, for inspecting queue state.
+     */
+    suspend(route: OverrideTarget, opts?: SuspendOptions): void;
+    /**
+     * Resume a previously suspended route.
+     * If the route was suspended with `queue: true`, replays queued writes.
+     * Returns the number of replayed operations.
+     */
+    resume(route: OverrideTarget): Promise<number>;
+    /** Snapshot the current override/suspend state for diagnostics. */
+    routeStatus(): RouteStatus;
+    /**
+     * Resolve the physical backend a vault id maps to via the geographic
+     * `vaultRoutes` prefix routing (collection-independent), falling back to
+     * the `default` store. Used by the federation data-residency guard
+     * to read the placement backend's `capabilities.region`.
+     */
+    resolveBackend(vaultId: string): NoydbStore;
+}
+/**
+ * Create a store multiplexer that dispatches operations to different backends
+ * based on collection type, record size, record age, vault prefix, or
+ * runtime overrides.
+ *
+ * ```ts
+ * const store = routeStore({
+ *   default: dynamo({ table: 'myapp' }),
+ *   blobs: s3({ bucket: 'myapp-blobs' }),
+ *   routes: { auditLog: s3({ bucket: 'myapp-audit' }) },
+ * })
+ * ```
+ *
+ * The returned store satisfies `NoydbStore` and can be passed directly to
+ * `createNoydb({ store })`. It also exposes additional methods
+ * (`override`, `suspend`, `resume`, `routeStatus`, `compact`) for runtime
+ * control and maintenance.
+ */
+export declare function routeStore(opts: RouteStoreOptions): RoutedNoydbStore;