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

package/dist/with-commit/history/time-machine.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Time-machine queries — point-in-time reads reconstructed from the
+ * existing history + ledger infrastructure.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * const vault = await db.openVault('acme', { passphrase })
+ * const q1End = vault.at('2026-03-31T23:59:59Z')
+ * const invoice = await q1End.collection<Invoice>('invoices').get('inv-001')
+ * // → the record as it stood at the close of Q1 2026
+ * ```
+ *
+ * ## How it works
+ *
+ * Every write path already fans out into two persistence lanes:
+ *
+ * 1. `saveHistory(...)` persists a **full encrypted envelope snapshot**
+ *    per version under the `_history` collection (one envelope per
+ *    version, keyed by `{collection}:{id}:{paddedVersion}`). Each
+ *    envelope carries its own `_ts` (the write timestamp).
+ * 2. `ledger.append(...)` appends a hash-chained audit entry that
+ *    records the `op` (put / delete), `version`, and `ts`.
+ *
+ * Reconstruction at a target timestamp T is therefore:
+ *
+ * - Find the newest history envelope for `(collection, id)` whose
+ *   `_ts ≤ T` — that's the state the record was in at T.
+ * - Check the ledger for any `op: 'delete'` entry for the same
+ *   `(collection, id)` with `entry.ts` in `(latestEnvelope._ts, T]` —
+ *   if present, the record was deleted before T, so return `null`.
+ * - Decrypt the surviving envelope with the current collection DEK
+ *   (DEKs are per-collection but stable across versions — the same
+ *   key encrypts v1 and v15 of a record).
+ *
+ * No delta replay. The existing `history.ts` module already stores
+ * complete snapshots; we just pick the right one.
+ *
+ * ## Read-only contract
+ *
+ * Every write method on `CollectionInstant` throws
+ * {@link ReadOnlyAtInstantError}. A historical view is a *read*
+ * surface — mutating the past would require either a branch/shadow
+ * mechanism (tracked under shadow vaults) or a rewrite of
+ * history, which breaks the ledger's tamper-evidence guarantee.
+ *
+ * @module
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import type { LedgerStore } from './ledger/store.js';
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+/**
+ * Narrow view of a {@link Vault}'s internals that
+ * {@link VaultInstant} needs. Passed in by `Vault.at()` rather than
+ * constructed here so all crypto + adapter access stays inside the
+ * Vault class.
+ *
+ * Not exported from the public barrel — consumers should get a
+ * `VaultInstant` via `vault.at(ts)`, never by constructing one
+ * directly.
+ */
+export interface VaultEngine {
+    readonly adapter: NoydbStore;
+    /** Vault name (the compartment). */
+    readonly name: string;
+    /**
+     * `true` when the vault was opened with a passphrase (the normal
+     * case). `false` in plaintext-mode vaults (`encrypt: false`) — in
+     * that case `envelope._data` is raw JSON and we skip the DEK lookup.
+     */
+    readonly encrypted: boolean;
+    /**
+     * Resolves the DEK used to decrypt a given collection's envelopes.
+     * Not called when `encrypted` is false.
+     */
+    getDEK(collection: string): Promise<EnclaveKey>;
+    /**
+     * Lazily-initialised ledger. We consult it to detect deletes that
+     * happened between the latest history snapshot and the target
+     * timestamp. `null` when history is disabled for this vault — in
+     * that case time-machine reads fall back to history-only
+     * reconstruction (which may miss deletes).
+     */
+    getLedger(): LedgerStore | null;
+}
+/**
+ * A vault at a fixed instant. Produced by `vault.at(timestamp)`.
+ * Carries no session state of its own — every read is a fresh
+ * lookup through the vault's adapter.
+ *
+ * Cheap to construct; safe to throw away. Create one per query.
+ */
+export declare class VaultInstant {
+    private readonly engine;
+    /** Fully-resolved target timestamp (ISO-8601 UTC). */
+    readonly timestamp: string;
+    constructor(engine: VaultEngine, 
+    /** Fully-resolved target timestamp (ISO-8601 UTC). */
+    timestamp: string);
+    /** Get a point-in-time view of a collection. */
+    collection<T = unknown>(name: string): CollectionInstant<T>;
+}
+/**
+ * A read-only collection view anchored to a past instant.
+ *
+ * Every write method throws {@link ReadOnlyAtInstantError} — see the
+ * module docstring for why. The read surface is intentionally smaller
+ * than the live {@link Collection}: `get` and `list` cover the
+ * "what did the books look like on date X" use case without pulling
+ * in the full query DSL / joins / aggregates at this stage. Follow-up
+ * work tracked under.
+ */
+export declare class CollectionInstant<T = unknown> {
+    private readonly engine;
+    private readonly targetTs;
+    readonly name: string;
+    constructor(engine: VaultEngine, targetTs: string, name: string);
+    /**
+     * Return the record as it existed at the target timestamp, or
+     * `null` if the record had not been created yet or had already been
+     * deleted by then.
+     *
+     * Gated on the LIVE record's current tier — #730, mirroring the #712
+     * read-gate `history()`/`getVersion()` already apply: an elevated record
+     * is invisible through the whole time-machine surface, not just a
+     * decrypt failure. See {@link resolveVisibleEnvelope}.
+     *
+     * Decrypts through {@link openEnvelopeJson}, the `_cek`-aware envelope
+     * body opener — a snapshot from a `perRecordKeys` collection is encrypted
+     * under its own per-record CEK (wrapped in `_cek`), not the collection
+     * DEK directly.
+     */
+    get(id: string): Promise<T | null>;
+    /**
+     * IDs of records that existed (had at least one `put` and were not
+     * subsequently deleted) at the target timestamp.
+     *
+     * Implemented as a linear scan over history + ledger. Performance
+     * is bounded by total history size (not live-vault size), so the
+     * memory-first vault-scale cap (1K–50K records × average history
+     * depth) still applies.
+     */
+    list(): Promise<string[]>;
+    put(_id: string, _record: T): Promise<never>;
+    delete(_id: string): Promise<never>;
+    update(_id: string, _patch: Partial<T>): Promise<never>;
+    /**
+     * {@link resolveEnvelope}, additionally gated on the record's LIVE
+     * (current, not historical) tier — #730. Mirrors the #712 read-gate
+     * `history()`/`getVersion()` apply: history snapshots keep their
+     * tier-0-wrapped CEKs and carry no `_tier` of their own, so an elevated
+     * record's prior versions would otherwise stay tier-0-decryptable here.
+     * `null` for a resolved envelope carrying its own `_tier > 0` (a
+     * tier-aware snapshot reached some other way) or whose LIVE record is
+     * currently elevated — both `get()` and `list()` route through this so
+     * the invisibility law holds on the whole time-machine read surface, not
+     * just a decrypt failure.
+     */
+    private resolveVisibleEnvelope;
+    /**
+     * Return the envelope that represents the record's state at
+     * `targetTs`, accounting for deletes. `null` if the record didn't
+     * exist at that instant.
+     *
+     * ## Why we use the ledger as the authoritative timeline
+     *
+     * The per-version history snapshots saved by `saveHistory()` do
+     * carry a `_ts` field, but that timestamp is the moment the
+     * snapshot was *captured* (i.e. the instant right before the
+     * subsequent overwrite), not the original write time. The ledger,
+     * by contrast, records `ts` at the moment of each `put` / `delete`
+     * — it's the only source that tracks the real timeline. So:
+     *
+     *   1. Walk the ledger; find the latest entry for `(collection, id)`
+     *      with `ts ≤ targetTs`.
+     *   2. If that entry is a `delete`, the record was gone at the
+     *      target instant — return null.
+     *   3. Otherwise it's a `put` with a specific `version`. Load the
+     *      envelope for that version from history, falling back to the
+     *      live collection for the most recent version.
+     *
+     * ## Fallback when the ledger is disabled
+     *
+     * If the vault has history disabled, `getLedger()` returns null and
+     * we fall back to comparing envelope `_ts` fields. This is
+     * approximate and gets the *last write* right but may confuse the
+     * intermediate versions; adopters needing accurate time-machine
+     * reads should leave history enabled.
+     */
+    private resolveEnvelope;
+    private resolveViaLedger;
+    private resolveViaEnvelopeTs;
+    /**
+     * Fetch the envelope for a specific version. The live record (most
+     * recent put) lives in the main collection; prior versions live in
+     * `_history`. We check live first because the common case after a
+     * delete is that we're trying to load the last-live version from
+     * history, and skipping live for the current-version case avoids a
+     * redundant lookup.
+     */
+    private loadVersion;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * @category capability
+ * Deferred-numbering config descriptor. See
+ * docs/superpowers/specs/2026-06-08-sealed-numbering-and-store-clock-design.md.
+ */
+/** A registered deferred-numbering series. */
+export interface DeferredNumberingConfig {
+    /** Series name — the key passed to `vault.sequence(series)`. */
+    readonly series: string;
+    /** Collection holding the records to number. */
+    readonly collection: string;
+    /** Field on each record where the assigned serial is written. */
+    readonly field: string;
+    /**
+     * Minimum wall-clock age (ms) before an entry is eligible at a pass, in
+     * addition to the interval commit-wait. Default 0 — the store-clock
+     * interval (`storeLatest ≤ now.earliest`) is the correctness mechanism.
+     */
+    readonly settleWindowMs: number;
+}
+/** Declare a deferred-numbering series. Pass the result in `createNoydb({ numbering: [...] })`. */
+export declare function withDeferredNumbering(config: {
+    series: string;
+    collection: string;
+    field: string;
+    settleWindowMs?: number;
+}): DeferredNumberingConfig;

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,59 @@
+import type { Vault } from '../../kernel/vault.js';
+import type { TierMoveResult } from '../../with-audit/tiers/index.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<TierMoveResult>;
+    };
+    /**
+     * 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';