@noy-db/hub 0.3.0-pre.1 → 0.3.0-pre.11

package/dist/with-commit/numbering/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @category capability
+ * Deferred numbering engine — store-clock-ordered, gap-free serials assigned
+ * at an explicit numbering pass. See the design spec.
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+import type { DeferredNumberingConfig } from './descriptor.js';
+export declare const NUMBERING_HEAD_COLLECTION = "_numbering_head";
+export declare const NUMBERING_PENDING_COLLECTION = "_numbering_pending";
+export interface Assignment {
+    recordId: string;
+    serial: number;
+}
+export declare class DeferredNumberingStore {
+    private readonly adapter;
+    private readonly vault;
+    private readonly encrypted;
+    private readonly getDEK;
+    private readonly actor;
+    private readonly configs;
+    /**
+     * Stamp a serial onto a USER record THROUGH the Collection layer (so the
+     * cache, indexes, and MVs stay coherent — the engine must NOT write user
+     * collections at the raw adapter level). Returns false if the record is
+     * gone (the engine then skips it without burning a serial). Provided by the
+     * vault; unit tests pass a Map-backed double.
+     */
+    private readonly stamp;
+    /** In-process registry: `${series}::${recordId}` → resolver for the live next() Promise. */
+    private readonly waiters;
+    private readonly dekCache;
+    constructor(opts: {
+        adapter: NoydbStore;
+        vault: string;
+        encrypted: boolean;
+        getDEK: (collectionName: string) => Promise<EnclaveKey>;
+        actor: string;
+        configs: Map<string, DeferredNumberingConfig>;
+        stamp: (collection: string, recordId: string, field: string, serial: number) => Promise<boolean>;
+    });
+    has(series: string): boolean;
+    private dek;
+    private readJson;
+    private writeJson;
+    private pendingId;
+    /** Current last-assigned serial for a series (0 if none). */
+    peek(series: string): Promise<number>;
+    /**
+     * Enqueue a record for numbering: stamp it with the current store clock and
+     * durably write a pending entry. The returned Promise resolves once the
+     * record is durably enqueued; its `assigned` field resolves with the serial
+     * at the next pass (the record's `field` is the durable source of truth —
+     * `assigned` is an in-process convenience that a crash may drop).
+     */
+    enqueue(series: string, recordId: string): Promise<{
+        assigned: Promise<number>;
+    }>;
+    private listPending;
+    /**
+     * Run a numbering pass for `series`: select entries provably settled
+     * (`storeLatest ≤ now.earliest` — commit-wait), order by
+     * `(storeEarliest, recordId)`, assign serials after the head, stamp each
+     * record's field, advance the head with one CAS, and consume the entries.
+     * Idempotent/convergent: a losing concurrent pass returns `[]` and the next
+     * pass reconciles. Resolves any in-process enqueue() `assigned` Promises.
+     */
+    runPass(series: string): Promise<Assignment[]>;
+}

package/dist/with-commit/sequence/active.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Enable the atomic-sequence capability.
+ * Pass to `createNoydb({ sequenceStrategy: withSequence() })` to make
+ * `vault.sequence('name').next()` / `.peek()` / `.seedTo()` live. The
+ * {@link SequenceStore} CAS engine is statically imported here, so it is pulled
+ * into the bundle only when `withSequence()` is referenced (the floor never
+ * imports it).
+ */
+import type { SequenceStrategy } from './strategy.js';
+export declare function withSequence(): SequenceStrategy;

package/dist/with-commit/sequence/index.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Atomic sequence primitive — online-coordinated gap-free numbering.
+ *
+ * `vault.sequence('invoice-2026').next()` returns 1, 2, 3, … with no
+ * gaps and no duplicates, even under concurrent callers. Each named
+ * sequence is an independent counter record at `_sequences/<name>`,
+ * incremented with an optimistic compare-and-swap retry loop — the same
+ * proven pattern as the ledger head (`history/ledger/store.ts`).
+ *
+ * **Explicitly online-only.** Gap-free numbering requires single-authority
+ * serialization, which an offline / non-CAS store cannot provide. `next()`
+ * throws {@link SequenceOfflineError} unless the backing store advertises
+ * `capabilities.casAtomic`. This is a deliberate, honest wall — an offline
+ * writer cannot safely allocate a global sequence number.
+ *
+ * Note on "gap-free": the *sequence* is gap-free (each `next()` yields a
+ * unique, +1 value). If a caller discards a value without using it, that
+ * is a gap in *usage*, not in the sequence — assign each `next()` result
+ * to its record in the same operation.
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+export { withSequence } from './active.js';
+export { NO_SEQUENCE, type SequenceStrategy } from './strategy.js';
+export { SequenceNotEnabledError } from '../../kernel/errors.js';
+export declare const SEQUENCE_COLLECTION = "_sequences";
+/** Options for `SequenceHandle.next`. Deferred-numbering series use `for`; the CAS counter ignores all of these. */
+export interface NextOptions {
+    /** Deferred mode: the record id to number. Ignored by the CAS counter. */
+    readonly for?: string;
+    /** Deferred mode: reject after this many ms if still unsealed (reserved; not yet enforced in this slice). */
+    readonly timeoutMs?: number;
+}
+/**
+ * Partitioning for a CAS sequence. A partitioned sequence is an
+ * independent counter scoped to one tuple of values — e.g.
+ * `sequence('invoice', { partition: [2026, 'EU'] })` numbers EU-2026 invoices
+ * separately from `[2026, 'US']` and from the bare `invoice` series.
+ *
+ * Partition components are URI-encoded (so `/`, null bytes and other
+ * separators in a value can never collide with the structural separators) and
+ * `'/'`-joined, then appended to the series with a null-byte (`\x00`)
+ * separator. The null byte is illegal in a plain series name, which guarantees
+ * a partitioned key is always disjoint from any unpartitioned series.
+ */
+export interface SequenceOptions {
+    /** Partition tuple. Each component is URI-encoded and `'/'`-joined. */
+    readonly partition?: readonly (string | number)[];
+    /**
+     * Render template for the serial string. When set, `vault.sequence`
+     * returns a {@link FormattedSequenceHandle} whose `next()` resolves to
+     * `{ serial, formatted }`. Tokens:
+     * - `{seq}` — the allocated integer
+     * - `{seq:0N}` — zero-padded to width N (e.g. `{seq:04}` → `0001`)
+     * - `{partition.i}` — the i-th `partition` component (original value)
+     *
+     * Any other token, or a `{partition.i}` index beyond the supplied
+     * `partition`, throws `ValidationError` at `vault.sequence()` construction.
+     * Per-partition reset is inherent: a new partition tuple starts at 1.
+     */
+    readonly format?: string;
+}
+/**
+ * A formatted sequence handle. Identical to {@link SequenceHandle}
+ * except `next()` also returns the rendered `formatted` string. `peek()` /
+ * `seedTo()` operate on the underlying integer counter, unchanged.
+ */
+export interface FormattedSequenceHandle {
+    /** Allocate the next value and return it with its rendered serial string. */
+    next(opts?: NextOptions): Promise<{
+        serial: number;
+        formatted: string;
+    }>;
+    /** Read the current integer value without allocating. Returns 0 if never used. */
+    peek(): Promise<number>;
+    /** Set-if-greater on the underlying integer counter. See {@link SequenceHandle.seedTo}. */
+    seedTo(n: number): Promise<void>;
+}
+/**
+ * Validate a sequence `format` against the supplied partition and return a
+ * pure `(serial) => string` renderer. Eager validation: every token is
+ * checked now, so a bad pattern throws `ValidationError` at construction —
+ * never at `next()` time.
+ */
+export declare function compileSequenceFormat(format: string, series: string, partition: readonly (string | number)[] | undefined): (serial: number) => string;
+/**
+ * Resolve the CAS storage key for a (series, partition) pair.
+ *
+ * With no partition the key is `series` verbatim. With a partition the key is
+ * `${series}\x00${parts}` where `parts` is each component passed through
+ * `encodeURIComponent(String(part))` and `'/'`-joined. The null-byte separator
+ * is illegal in a plain series name, so partitioned keys never collide with
+ * unpartitioned ones; URI-encoding keeps any component containing `/` distinct
+ * from a multi-component partition.
+ *
+ * @throws {ValidationError} if any partition component is empty after `String()`
+ *   or is a non-finite number (`NaN`, `±Infinity`).
+ */
+export declare function resolveSequenceKey(series: string, opts?: SequenceOptions): string;
+export interface SequenceHandle {
+    /** Atomically allocate and return the next value (1, 2, 3, …). Deferred series resolve at the next pass. */
+    next(opts?: NextOptions): Promise<number>;
+    /** Read the current value without allocating. Returns 0 if never used. */
+    peek(): Promise<number>;
+    /**
+     * Set-if-greater: advance the counter to at least `n`. A no-op if the
+     * current value is already `>= n` (so it never rewinds), and `seedTo(0)` is
+     * a no-op. Idempotent and CAS-safe under concurrent `next()` / `seedTo()`.
+     *
+     * Use after a bundle / CSV import to fast-forward the counter past the
+     * highest imported serial, so subsequent `next()` calls cannot re-use a
+     * number that is already on a record.
+     *
+     * Online-only: throws {@link SequenceOfflineError} on a non-CAS store.
+     */
+    seedTo(n: number): Promise<void>;
+}
+/** Per-call context the vault assembles to build a {@link SequenceStore}. */
+export interface SequenceStoreOptions {
+    adapter: NoydbStore;
+    vault: string;
+    encrypted: boolean;
+    getDEK: (collectionName: string) => Promise<EnclaveKey>;
+    actor: string;
+}
+export declare class SequenceStore {
+    private readonly adapter;
+    private readonly vault;
+    private readonly encrypted;
+    private readonly getDEK;
+    private readonly actor;
+    /**
+     * Memoized DEK promise. The `_sequences` collection DEK is created on
+     * first access; without sharing one promise, a burst of concurrent
+     * `next()` calls would each trigger DEK creation and diverge (one
+     * writer's ciphertext unreadable by another). One shared promise → one
+     * DEK.
+     */
+    private dekPromise;
+    constructor(opts: SequenceStoreOptions);
+    /** A handle bound to one sequence name. */
+    handle(name: string): SequenceHandle;
+    private assertOnline;
+    private dek;
+    private read;
+    private encryptState;
+    peek(name: string): Promise<number>;
+    next(name: string): Promise<number>;
+    seedTo(name: string, n: number): Promise<void>;
+}

package/dist/with-commit/sequence/strategy.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Sequence capability strategy — the single on-demand factory the vault routes
+ * `vault.sequence()` through to build its atomic-CAS {@link SequenceStore}. The
+ * active engine ({@link withSequence}) constructs the real store (kept out of
+ * the floor bundle — the store class is reached only via the opt-in
+ * `active.ts` chunk); {@link NO_SEQUENCE} throws. The vault always assembles the
+ * per-call {@link SequenceStoreOptions} and delegates here, so an un-opted-in
+ * caller hits `NO_SEQUENCE`'s throw at `vault.sequence()`.
+ *
+ * Note: `vault.sequence()` is synchronous, so the factory is a plain (sync)
+ * constructor — the engine is tree-shaken by reachability (only `withSequence()`
+ * pulls `active.ts`, which statically imports the store), not by a dynamic
+ * import. Deferred-numbering series (`withDeferredNumbering`) are a distinct
+ * capability and are NOT routed through this strategy.
+ * @internal
+ */
+import type { SequenceStore, SequenceStoreOptions } from './index.js';
+export interface SequenceStrategy {
+    createStore(opts: SequenceStoreOptions): SequenceStore;
+}
+/**
+ * No-op stub — the floor default. The capability factory throws
+ * {@link SequenceNotEnabledError}; opt in with `sequenceStrategy: withSequence()`
+ * in createNoydb. @internal
+ */
+export declare const NO_SEQUENCE: SequenceStrategy;

package/dist/with-commit/tx/active.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Active transactions strategy. Only reachable via `@noy-db/hub/tx`.
+ */
+import type { TxStrategy } from './strategy.js';
+import type { TransactionInvariant } from './invariants.js';
+/**
+ * Options for {@link withTransactions}. Currently only commit-time
+ * changeset `invariants` (see {@link TransactionInvariant}).
+ */
+export interface TransactionStrategyOptions {
+    /**
+     * Commit-time set-level invariants run over the changeset on every
+     * commit (ordinary AND amendment). See {@link TransactionInvariant}.
+     */
+    invariants?: ReadonlyArray<TransactionInvariant>;
+}
+/**
+ * Build the default transactions strategy. Pass into
+ * `createNoydb({ txStrategy: withTransactions() })` to enable
+ * `db.transaction(fn)` (and `db.transaction({ dryRun: true }, fn)`).
+ *
+ * Supply `{ invariants }` to register commit-time changeset invariants —
+ * set-level constraints that fire after the writes commit and revert the
+ * transaction on a throw. Unlike `amendment.invariant`, these run for
+ * ordinary `db.transaction(fn)` calls (and amendments) with no role gate.
+ */
+export declare function withTransactions(opts?: TransactionStrategyOptions): TxStrategy;

package/dist/with-commit/tx/dry-run.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Dry-run transactions. Runs the tx body to STAGE ops, then builds
+ * the directly-affected diff (before = current committed via collection.get,
+ * after = staged record) and collects guard violations — without executing
+ * phase 2. No adapter writes, no write-hooks, no commit. MV/derivation
+ * cascade is NOT simulated (v2). Mirrors the guard loop in
+ * `Collection._putInternal` — keep the two in sync.
+ */
+import type { Noydb } from '../../kernel/noydb.js';
+import { TxContext } from './transaction.js';
+export interface AffectedDocument {
+    readonly vault: string;
+    readonly op: 'create' | 'update' | 'delete';
+    readonly collection: string;
+    readonly docId: string;
+    readonly before: unknown;
+    readonly after: unknown;
+}
+export interface GuardViolation {
+    readonly vault: string;
+    readonly collection: string;
+    readonly docId: string;
+    readonly message: string;
+}
+export interface DryRunResult {
+    readonly affected: ReadonlyArray<AffectedDocument>;
+    readonly guardViolations: ReadonlyArray<GuardViolation>;
+}
+export declare function runDryRun(db: Noydb, fn: (tx: TxContext) => unknown): Promise<DryRunResult>;

package/dist/with-commit/tx/elevated-handle.d.ts

@@ -0,0 +1,58 @@
+import type { Vault } from '../../kernel/vault.js';
+/**
+ * Reserved collection that holds the audit ledger of elevation
+ * sessions. One envelope per `vault.elevate(...)` call.
+ */
+export declare const ELEVATION_AUDIT_COLLECTION = "_elevation_audit";
+/**
+ * Scoped handle returned by `vault.elevate(...)`. Writes through this
+ * handle land at the elevated tier with `authorization: 'elevation'`
+ * stamped on the audit event; reads stay on the original `Vault`.
+ *
+ * The handle lazily checks its TTL on every operation, so a
+ * forgotten `release()` cannot keep elevated writes alive past
+ * `expiresAt` — the next call simply throws
+ * {@link ElevationExpiredError}.
+ *
+ * Naming note: the issue's spec text used `elevated.session`
+ * for this field; we name the field `handle` to avoid conflicting
+ * with the codebase's existing `SessionToken` value type. The
+ * semantics are unchanged.
+ */
+export declare class ElevatedHandle {
+    /** Target tier this handle writes at. */
+    readonly tier: number;
+    /** Audit string stamped on every cross-tier event. */
+    readonly reason: string;
+    /** Absolute expiration in ms (Date.now()). */
+    readonly expiresAt: number;
+    private released;
+    private readonly vault;
+    private readonly onRelease;
+    constructor(opts: {
+        vault: Vault;
+        tier: number;
+        reason: string;
+        expiresAt: number;
+        onRelease: () => void;
+    });
+    /**
+     * Scoped collection accessor. Returns a thin wrapper exposing the
+     * single elevated operation (`put`). Reads, deletes, queries —
+     * everything else — should go through the original `vault`'s
+     * `collection(...)`, which keeps "writes elevated, reads
+     * unprivileged" trivially true.
+     */
+    collection<T>(name: string): {
+        put(id: string, record: T): Promise<void>;
+    };
+    /**
+     * Manually revert the elevation. Idempotent — calling twice (or
+     * after the TTL expired) is a safe no-op. The vault's
+     * active-elevation slot is cleared so a subsequent
+     * `vault.elevate(...)` succeeds without throwing
+     * {@link AlreadyElevatedError}.
+     */
+    release(): Promise<void>;
+    private assertActive;
+}

package/dist/with-commit/tx/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Multi-record transactions subpath barrel.
+ *
+ * Public entry point is `db.transaction(fn)`; these types are exported
+ * so consumers can annotate transaction-body signatures in their own
+ * code.
+ */
+export { withTransactions } from './active.js';
+export type { TransactionStrategyOptions } from './active.js';
+export type { TxStrategy } from './strategy.js';
+export type { TransactionInvariant } from './invariants.js';
+export { TxContext, TxVault, TxCollection, runTransaction } from './transaction.js';
+export type { AmendmentTxOptions } from './transaction.js';

package/dist/with-commit/tx/invariants.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Commit-time changeset invariants for ordinary transactions.
+ *
+ * Today the only set-level invariant hook is `amendment.invariant`, which
+ * fires solely inside `db.transaction({ amendment: true }, …)` and requires
+ * an admin/owner role plus a registered guard. That is the right shape for
+ * the WORM-override path, but normal application transactions also need
+ * cross-record invariants that hold on every commit — e.g. niwat's
+ * `assertR1` ("every payment is 100% receipted").
+ *
+ * `withTransactions({ invariants: [...] })` registers such invariants. Each
+ * one names a `scope` (a collection) and a `check(changes, ctx)` callback
+ * that receives the commit's change-set for that collection.
+ *
+ * ## Semantics
+ *
+ * - **`scope`** is a collection name. An invariant fires only when the
+ *   committed transaction wrote at least one record in that collection.
+ * - **When** — at commit, AFTER Phase 2 has executed all staged ops (so
+ *   `after` reflects the written record), and after the amendment commit
+ *   phase. It runs for BOTH ordinary and amendment transactions — an
+ *   amendment is still a commit and is still subject to these invariants.
+ * - **`changes`** — one `{ before, after }` pair per touched id (deduped to
+ *   the last write per id, preserving write order). `before` is the
+ *   plaintext prior record (captured in Phase 1 before the overwrite),
+ *   `null` for an insert. `after` is the written record, `null` for a
+ *   delete.
+ * - **Throw → revert.** A throw reverts every executed op (via the shared
+ *   `revertExecuted` unwind) and is surfaced as `InvariantError` (an
+ *   `InvariantError` thrown by the check passes through unwrapped).
+ *
+ * ```ts
+ * createNoydb({ txStrategy: withTransactions({
+ *   invariants: [{
+ *     scope: 'payments',
+ *     check(changes) {
+ *       for (const { after } of changes) {
+ *         const p = after as Payment | null
+ *         if (p && p.receiptAmount !== p.amount) {
+ *           throw new InvariantError('R1: payment not fully receipted')
+ *         }
+ *       }
+ *     },
+ *   }],
+ * }) })
+ * ```
+ */
+import type { GuardChange, GuardContext } from '../../with-audit/guards/types.js';
+/**
+ * A commit-time set-level invariant for ordinary (and amendment)
+ * transactions. See module docs for full semantics.
+ */
+export interface TransactionInvariant {
+    /**
+     * The collection this invariant watches. The `check` fires only when the
+     * committed transaction wrote at least one record in this collection.
+     */
+    readonly scope: string;
+    /**
+     * Validate the change-set for {@link scope}. `changes` carries one
+     * `{ before, after }` pair per touched id (deduped to last-write,
+     * write-order preserved); `before` is the plaintext prior record (null
+     * on insert), `after` is the written record (null on delete). Throw to
+     * revert the whole transaction — the throw is surfaced as
+     * `InvariantError`.
+     */
+    check: (changes: ReadonlyArray<GuardChange<unknown>>, ctx: GuardContext<unknown>) => Promise<void> | void;
+}

package/dist/with-commit/tx/strategy.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Strategy seam for the optional multi-record transaction service.
+ * `runTransaction` is only reachable through `withTransactions()`
+ * exported from `@noy-db/hub/tx`. Consumers who don't use
+ * `db.transaction(fn)` ship none of the ~288 LOC.
+ *
+ * @internal
+ */
+import type { Noydb } from '../../kernel/noydb.js';
+import type { TxContext, AmendmentTxOptions } from './transaction.js';
+import type { DryRunResult } from './dry-run.js';
+import type { TransactionInvariant } from './invariants.js';
+/**
+ * @internal
+ */
+export interface TxStrategy {
+    runTransaction<T>(db: Noydb, fn: (tx: TxContext) => Promise<T> | T, options?: AmendmentTxOptions, txInvariants?: ReadonlyArray<TransactionInvariant>): Promise<T>;
+    runDryRun(db: Noydb, fn: (tx: TxContext) => unknown): Promise<DryRunResult>;
+}
+/**
+ * @internal
+ */
+export declare const NO_TX: TxStrategy;