@noy-db/hub 0.6.0-pre.2 → 0.6.0-pre.20

package/dist/with-audit/periods/strategy.d.ts

@@ -12,21 +12,30 @@
  */
 import type { EncryptedEnvelope, NoydbStore } from '../../kernel/types.js';
 import type { LedgerStore } from '../../with-commit/history/ledger/store.js';
-import type { PeriodRecord } from './periods.js';
+import type { PeriodRecord, PeriodPartition, PartitionResolver } from './periods.js';
 /**
  * @internal
  */
 export interface PeriodsStrategy {
-    loadPeriods(adapter: NoydbStore, vault: string, decrypt: (envelope: EncryptedEnvelope) => Promise<PeriodRecord>): Promise<PeriodRecord[]>;
-    chainAnchor(records: readonly PeriodRecord[]): Promise<{
+    loadPeriods(adapter: NoydbStore, vault: string, decrypt: (id: string, envelope: EncryptedEnvelope) => Promise<PeriodRecord>): Promise<PeriodRecord[]>;
+    chainAnchor(records: readonly PeriodRecord[], partition?: PeriodPartition): Promise<{
         priorPeriodName?: string;
         priorPeriodHash: string;
     }>;
     assertTsWritable(existing: {
         ts: string | null;
         record: Record<string, unknown> | null;
-    } | null, incoming: Record<string, unknown> | null, periods: readonly PeriodRecord[]): void;
-    validatePeriodName(name: string, existing: readonly PeriodRecord[]): void;
+    } | null, incoming: Record<string, unknown> | null, periods: readonly PeriodRecord[], scope?: {
+        collection: string;
+        resolve?: PartitionResolver;
+    }): void;
+    validatePeriodName(name: string, existing: readonly PeriodRecord[], partition?: PeriodPartition): void;
+    /**
+     * Record → timeline resolver built from `withPeriods({ subjects })` (#1005).
+     * `undefined` when the caller configured no subjects, which keeps every
+     * record on the vault-wide timeline.
+     */
+    readonly partitionOf?: PartitionResolver;
     appendPeriodLedgerEntry(ledger: LedgerStore | null, actor: string, envelope: EncryptedEnvelope, periodName: string, collection?: string): Promise<void>;
 }
 export declare const NO_PERIODS: PeriodsStrategy;

package/dist/with-audit/periods/vault-facade.d.ts

@@ -3,7 +3,31 @@ import type { NoydbStore } from '../../kernel/types.js';
 import type { LedgerStore } from '../../with-commit/history/ledger/store.js';
 import type { Collection } from '../../kernel/collection.js';
 import type { PeriodsStrategy } from './strategy.js';
-import { type PeriodRecord, type TargetPurgeCount, type ClosePeriodOptions, type OpenPeriodOptions } from './periods.js';
+import { type PeriodRecord, type TargetPurgeCount, type ClosePeriodOptions, type OpenPeriodOptions, type PeriodPartition, type PeriodReopenEvent } from './periods.js';
+/** Selects one period timeline. Omit — or pass an empty tuple — for the vault-wide one (#1005). */
+export interface PeriodScope {
+    readonly partition?: PeriodPartition;
+}
+/** A scoped operation that also records a free-text justification in the audit trail. */
+export interface PeriodScopeWithReason extends PeriodScope {
+    readonly reason?: string;
+}
+/** Options for `vault.reopenPeriod()` (#1022). */
+export interface ReopenPeriodOptions extends PeriodScopeWithReason {
+    /**
+     * ISO instant after which the period re-seals BY ITSELF, with nobody acting.
+     * Omit for a window that stays open until an explicit `reclosePeriod()`.
+     *
+     * Expiry is evaluated against the clock on every write check, so a lapsed
+     * window needs no sweep, no timer and no cache invalidation to take effect.
+     */
+    readonly until?: string;
+}
+/** The persisted side of a write, as the period write-guard sees it. */
+export interface PeriodGuardPrior {
+    readonly ts: string | null;
+    readonly record: Record<string, unknown> | null;
+}
 /** Everything the moving period methods touched on the vault's `this.*`. */
 export interface VaultPeriodsDeps {
     /** Resolved periods strategy (NO_PERIODS when not configured). */
@@ -56,7 +80,7 @@ export declare class VaultPeriods {
      * read only. Idempotent: a second call is a no-op that returns the
      * same merged record without re-purging or re-appending a ledger entry.
      */
-    freezePeriod(name: string): Promise<PeriodRecord>;
+    freezePeriod(name: string, options?: PeriodScope): Promise<PeriodRecord>;
     /**
      * Archive a closed period (#613): physically relocates its in-window
      * records (those with `_ts < periodExclusiveUpperBound(endDate)`) from the
@@ -66,7 +90,7 @@ export declare class VaultPeriods {
      * through to cold) and idempotent: a second call is a no-op returning the
      * same merged record.
      */
-    archivePeriod(name: string): Promise<PeriodRecord>;
+    archivePeriod(name: string, options?: PeriodScope): Promise<PeriodRecord>;
     /**
      * Target-purge a closed period (#615): sweeps delete markers off the vault's
      * PUSH-ONLY sync targets (`backup`/`archive`) via `purgeTargets`, recording a
@@ -76,22 +100,77 @@ export declare class VaultPeriods {
      * Idempotent once run; with no push-only targets it writes no companion and
      * is re-runnable.
      */
-    purgePeriodTargets(name: string): Promise<PeriodRecord>;
+    purgePeriodTargets(name: string, options?: PeriodScope): Promise<PeriodRecord>;
     /** Merge target-purge companion fields into a fresh `PeriodRecord` copy — never mutates `periodCache`. */
     private mergeTargetPurge;
     /** Merge archive companion fields into a fresh `PeriodRecord` copy — never mutates `periodCache`. */
     private mergeArchive;
     /** Merge freeze companion fields into a fresh `PeriodRecord` copy — never mutates `periodCache`. */
     private mergeFreeze;
-    /** Return every closed / opened period in `closedAt` order, merged with any freeze + archive companions. */
-    listPeriods(): Promise<readonly PeriodRecord[]>;
-    /** Look up a single period by name, merged with its freeze + archive + target-purge companions if any. Returns `null` if not found. */
-    getPeriod(name: string): Promise<PeriodRecord | null>;
-    /** Called by the gate bus before put/delete. */
+    /**
+     * Return every closed / opened period in `closedAt` order, merged with any
+     * freeze + archive companions.
+     *
+     * With no argument this spans EVERY timeline — the pre-#1005 behaviour, and
+     * the right default for an audit sweep. Pass `{ partition }` to scope to one
+     * timeline; `{ partition: [] }` (or omitting it) means the vault-wide one.
+     */
+    listPeriods(options?: PeriodScope): Promise<readonly PeriodRecord[]>;
+    /**
+     * Look up a single period by name within one timeline, merged with its
+     * freeze + archive + target-purge companions if any. Returns `null` if not
+     * found.
+     *
+     * Names are only unique per partition (#1005), so this resolves against the
+     * VAULT-WIDE timeline unless `{ partition }` says otherwise — matching how
+     * every pre-partition period is stored.
+     */
+    getPeriod(name: string, options?: PeriodScope): Promise<PeriodRecord | null>;
+    /**
+     * The full append-only reopen/reclose log for one period (#1022) — the record
+     * an audit actually asks for, in order. `[]` when never reopened.
+     */
+    listPeriodReopens(name: string, options?: PeriodScope): Promise<readonly PeriodReopenEvent[]>;
+    /**
+     * Return a closed period to a writable state (#1022).
+     *
+     * Close is a three-state lifecycle in practice — open / closed / reopened —
+     * because a month gets closed and then a missing invoice arrives, or a filing
+     * is rejected and must be amended. That is routine, and it is supposed to
+     * leave a trail.
+     *
+     * The `_periods/<key>` record is NOT touched: the reopen is appended to a
+     * companion log, so the inter-period hash chain that proves the close
+     * happened survives the reopen intact. The chain reads *closed at T1,
+     * reopened at T2 by U, reclosed at T3*.
+     *
+     * A reopen withdraws the PERIOD's veto and nothing else. Record-level rules —
+     * an `immutableGuard` on a sent receipt, a frozen field — are separate gate
+     * handlers registered ahead of the period gate, so a reopened month cannot
+     * resurrect a document that is independently locked. Period state can only
+     * ever widen what the record-level rule already permits.
+     *
+     * Reopening an already-open window is allowed and appends another event: that
+     * is how a window gets extended, and the log keeps both.
+     */
+    reopenPeriod(name: string, options?: ReopenPeriodOptions): Promise<PeriodRecord>;
+    /**
+     * Seal a reopened period again (#1022), ending the window explicitly rather
+     * than waiting for an `until` to lapse. Appends to the same log, so the
+     * close → reopen → reclose sequence is recoverable in order.
+     */
+    reclosePeriod(name: string, options?: PeriodScopeWithReason): Promise<PeriodRecord>;
+    /** Append one entry to a period's reopen log, ledger it, and invalidate the guard's view. */
+    private appendReopenEvent;
+    /** Merge each period's reopen log onto it. One adapter listing, not one per period. */
+    private mergeReopenState;
+    /** Resolve one period within the timeline named by `options` (vault-wide when absent). */
+    private findPeriod;
+    /** Called by the gate bus before put/delete. `collection` selects the subject mapping (#1005). */
     assertTsWritable(existing: {
         ts: string | null;
         record: Record<string, unknown> | null;
-    } | null, incoming: Record<string, unknown> | null): Promise<void>;
+    } | null, incoming: Record<string, unknown> | null, collection?: string): Promise<void>;
     private loadPeriodsCache;
     /** Generic reserved-collection writer — serves `_periods` and `_period_freezes` alike. */
     private writeReserved;

package/dist/with-audit/periods/window.d.ts

@@ -6,6 +6,16 @@ export declare const PERIOD_FREEZES_COLLECTION = "_period_freezes";
 export declare const PERIOD_ARCHIVES_COLLECTION = "_period_archives";
 /** Sibling of {@link PERIODS_COLLECTION} holding target-purge companions (#615). */
 export declare const PERIOD_TARGET_PURGES_COLLECTION = "_period_target_purges";
+/**
+ * Sibling of {@link PERIODS_COLLECTION} holding reopen/reclose companions (#1022).
+ *
+ * Unlike the freeze / archive / target-purge companions — each a single,
+ * idempotent, once-only record — this one holds an APPEND-ONLY EVENT LIST,
+ * because reopening is a repeating cycle: a month can be closed, reopened,
+ * reclosed, and reopened again. The audit value is the sequence, not the
+ * latest state.
+ */
+export declare const PERIOD_REOPENS_COLLECTION = "_period_reopens";
 /**
  * Exclusive upper bound for a period's delete-marker purge window (#604).
  * Markers carry no business date (empty body), only write-time `_ts`, so freeze

package/dist/with-audit/sealed-record/index.d.ts

@@ -46,10 +46,23 @@ export { SealedRecordNotEnabledError } from '../../kernel/errors.js';
  * @param expectedCollection Collection the caller believes `recordEnvelope` is in.
  * @param expectedId         Record id the caller believes `recordEnvelope` is.
  * @returns The decrypted record body as a JSON string.
+ *
+ * ⚠️ **`recordEnvelope` must carry `_tier` and `_by`, not just the body**
+ * (#1041). They are plaintext metadata rather than secrets, but they are bound
+ * into the record's AAD, so a host handed only `{_iv, _data}` cannot
+ * reconstruct the identity the body was sealed against.
+ *
+ * That is a feature, not a tax: it means a host cannot be fed a body with its
+ * tags stripped or rewritten — a re-tiered or re-authored envelope no longer
+ * opens, even with a valid sealed CEK.
  */
 export declare function openSealedRecord(sealedCekEnvelope: SealedCekDeliveryEnvelope, recordEnvelope: {
     readonly _iv: string;
     readonly _data: string;
+    /** Bound into the AAD since #1093 — a rewound body no longer opens. */
+    readonly _v: number;
+    readonly _tier?: number | undefined;
+    readonly _by?: string | undefined;
 }, recipientSealer: {
     unseal(bytes: Uint8Array): Promise<Uint8Array>;
 }, expectedCollection: string, expectedId: string): Promise<string>;

package/dist/with-audit/tiers/index.d.ts

@@ -23,7 +23,7 @@
 export { withTiers } from './active.js';
 export { NO_TIERS, type TiersStrategy } from './strategy.js';
 export { TiersNotEnabledError } from '../../kernel/errors.js';
-import { type RecordCodec, type EnclaveKey, type SealedShredSlot } from '../../kernel/enclave/index.js';
+import { type RecordIdentity, type RecordCodec, type EnclaveKey, type SealedShredSlot } from '../../kernel/enclave/index.js';
 import type { UnlockedKeyring } from '../../with-party/team/keyring.js';
 import type { Lru } from '../../kernel/cache/index.js';
 import type { BlobFieldsConfig } from '../../with-shape/blobs/blob-compaction.js';
@@ -123,7 +123,22 @@ export interface TiersContext<T> {
      * pre-move body whenever `fromTier > 0`. No-op when history is disabled
      * (folds the `historyConfig.enabled` gate so `tiers/index.ts` stays simple).
      */
-    saveHistorySnapshot(id: string, envelope: EncryptedEnvelope): Promise<void>;
+    /**
+     * Persist a `_history` snapshot of `version`, sealed against the address it
+     * will be STORED at (#1041).
+     *
+     * Takes a **sealer**, not a finished envelope, because the destination
+     * identity is not knowable here: only the history strategy owns the
+     * `_history` layout. It hands the address in; the caller seals to it.
+     *
+     * ⚠️ The identity passed to `rewrapBodyToDek` must be what a READER will
+     * recompute — `recordAadFor(address, finalEnvelope)`. A tier-move snapshot
+     * strips `_tier`/`_elevatedBy` but KEEPS `_by`, so the destination is
+     * `{...address, by: envelope._by}` with no tier. Sealing against the bare
+     * address would produce history nothing can open, and the failure would
+     * surface only when someone reads it.
+     */
+    saveHistorySnapshot(id: string, version: number, seal: (address: RecordIdentity) => Promise<EncryptedEnvelope>): Promise<void>;
     /**
      * `true` iff a real history strategy is wired (not `NO_HISTORY`) AND not
      * explicitly disabled via `historyConfig.enabled`. `putAtTier` checks this

package/dist/with-cargo/adopt-partition.d.ts

@@ -12,7 +12,7 @@ import type { NoydbStore } from '../kernel/types.js';
 import type { SealingKeyProvider } from '../with-party/team/managed-secret.js';
 import type { ShamirRecoveryProvider } from '../with-party/team/shamir-recovery-provider.js';
 import type { RecoveryEnrollmentInput } from '../with-party/team/rotate-recover.js';
-import type { TransferSealPayload } from '../with-pod/bundle.js';
+import type { TransferSealPayload } from '../with-pod/pod.js';
 /**
  * Reverse of `sealDeks`. Imports the transfer key, decrypts the
  * sealed `{ collection: base64(rawDEK) }` map (layout iv(12)‖ct‖tag), and

package/dist/with-cargo/extract-partition.d.ts

@@ -10,7 +10,7 @@ import type { Vault } from '../kernel/vault.js';
 import type { EncryptedEnvelope } from '../kernel/types.js';
 import { type EnclaveKey } from '../kernel/enclave/index.js';
 import { type WalkClosureOptions, type DanglingRefNotice } from './walk-closure.js';
-import { type TransferSealPayload } from '../with-pod/bundle.js';
+import { type TransferSealPayload } from '../with-pod/pod.js';
 /** Re-keyed collections snapshot + the fresh DEKs used. */
 export interface ReKeyResult {
     readonly collections: Record<string, Record<string, EncryptedEnvelope>>;

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

@@ -37,10 +37,10 @@ export type { ExtractPartitionResult } from './extract-partition.js';
 export { adoptPartition, unsealDeks, createOwnerOnAdoptedPartition } from './adopt-partition.js';
 export type { AdoptPartitionOptions, AdoptPartitionResult, CreateOwnerResult, CreateOwnerOptions, CreateOwnerStandardOptions, CreateOwnerManagedOptions, } from './adopt-partition.js';
 export { TransferSealError, AdoptionStateError, PartitionExtractionError } from '../kernel/errors.js';
-export type { WriteHook } from '../port/with/write-hooks.js';
+export type { WriteHook, WriteEvent } from '../port/with/write-hooks.js';
 export type { WriteQueue } from '../kernel/write-queue.js';
 export type { WriteConflict } from '../kernel/types.js';
 export type { AccessibleVault } from '../kernel/types.js';
 export type { Unsubscribe } from '../kernel/types.js';
 export type { ExtractPartitionOptions } from './extract-partition.js';
-export type { TransferSealPayload } from '../with-pod/bundle.js';
+export type { TransferSealPayload } from '../with-pod/pod.js';

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

@@ -1,5 +1,31 @@
+import type { RecordIdentity } from '../../kernel/enclave/index.js';
 import type { NoydbStore, EncryptedEnvelope, HistoryOptions, PruneOptions } from '../../kernel/types.js';
 import { type EnclaveKey } from '../../kernel/enclave/index.js';
+/**
+ * The identity a history snapshot is **sealed against** — its STORAGE location,
+ * not the live record it is a copy of (#1041).
+ *
+ * ## Why storage, and why this is a decision rather than a detail
+ *
+ * A snapshot is a copy, so two identities are available: the live record
+ * (`collection`/`recordId`) or where the bytes actually land
+ * (`_history`/`historyId(...)`). They are not equivalent under attack.
+ *
+ * Binding the LIVE identity makes a snapshot's AAD **indistinguishable from the
+ * live record's at the same version** — so an untrusted store could serve a
+ * history entry *as the current record* and the client would accept it. It also
+ * leaves entries relocatable within `_history`.
+ *
+ * Binding STORAGE identity closes both. The cost is that the id must be known
+ * *before* the envelope is sealed, where `saveHistory` previously derived it
+ * *after* (from `envelope._v`) — which is precisely the restructure this
+ * function exists to make possible.
+ *
+ * `saveHistory` uses this too, so the sealed identity and the put location have
+ * **one definition** and cannot drift apart. Changing the layout here changes
+ * both at once, by construction.
+ */
+export declare function historyIdentity(collection: string, recordId: string, version: number): RecordIdentity;
 /** Save a history entry (a complete encrypted envelope snapshot). */
 export declare function saveHistory(adapter: NoydbStore, vault: string, collection: string, recordId: string, envelope: EncryptedEnvelope): Promise<void>;
 /** Get history entries for a record, sorted newest-first. */

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

@@ -17,7 +17,7 @@
  */
 export { withHistory } from './active.js';
 export type { HistoryStrategy } from './strategy.js';
-export { saveHistory, getHistory, getVersionEnvelope, pruneHistory, clearHistory, } from './history.js';
+export { saveHistory, historyIdentity, getHistory, getVersionEnvelope, pruneHistory, clearHistory, } from './history.js';
 export { diff, formatDiff } from './diff.js';
 export type { ChangeType, DiffEntry } from './diff.js';
 export { LedgerStore, LEDGER_COLLECTION, LEDGER_DELTAS_COLLECTION, envelopePayloadHash, } from './ledger/store.js';
@@ -30,3 +30,4 @@ export { VaultInstant, CollectionInstant } from './time-machine.js';
 export type { VaultEngine } from './time-machine.js';
 /** The un-opted-in stub for this service — exported so callers can compare against it (#844). */
 export { NO_HISTORY } from './strategy.js';
+export type { RecordIdentity } from '../../kernel/enclave/index.js';

package/dist/with-commit/history/ledger/store.d.ts

@@ -237,7 +237,13 @@ export declare class LedgerStore {
      * version/timestamp/actor) fully intact for audit purposes.
      */
     purgeRecordDeltas(collection: string, id: string): Promise<number>;
-    /** Encrypt a JSON Patch into an envelope for storage. Mirrors encryptEntry. */
+    /**
+     * Encrypt a JSON Patch into an envelope for storage. Mirrors encryptEntry.
+     *
+     * `index` is the ledger index this delta will be stored under — the caller
+     * knows it before the entry exists, and it is what makes the envelope's
+     * identity bindable (#1051).
+     */
     private encryptDelta;
     /**
      * Read all entries in ascending-index order. Used internally by

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

@@ -33,7 +33,7 @@ import type { LedgerStore } from './ledger/store.js';
 import type { JsonPatch } from './ledger/patch.js';
 import type { DiffEntry } from './diff.js';
 import type { VaultInstant, VaultEngine } from './time-machine.js';
-import type { EnclaveKey } from '../../kernel/enclave/index.js';
+import type { EnclaveKey, RecordIdentity } from '../../kernel/enclave/index.js';
 /**
  * Options accepted by `HistoryStrategy.buildLedger`. Mirrors the
  * `LedgerStore` constructor verbatim — kept in this file so `core`
@@ -58,6 +58,16 @@ export interface HistoryStrategy {
      * `NO_HISTORY`.
      */
     saveHistory(adapter: NoydbStore, vault: string, collection: string, recordId: string, envelope: EncryptedEnvelope): Promise<void>;
+    /**
+     * The identity a snapshot of `collection/recordId@version` must be **sealed
+     * against** — its `_history` storage location (#1041).
+     *
+     * On the port because the kernel writes history snapshots but must not import
+     * `with-commit` to learn its layout. Exposing it here keeps the derivation in
+     * the module that owns the layout, and `saveHistory` uses the same function,
+     * so the sealed identity and the put location cannot drift.
+     */
+    historyIdentity(collection: string, recordId: string, version: number): RecordIdentity;
     /**
      * List history envelopes for a record, newest first. Throws under
      * `NO_HISTORY` — callers reach this via `collection.history()` /

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

@@ -1,8 +1,3 @@
-/**
- * @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';

package/dist/with-commit/vault-head/active.d.ts

@@ -0,0 +1,2 @@
+import { type VaultHeadStrategy, type WithVaultHeadOptions } from './strategy.js';
+export declare function withVaultHead(opts?: WithVaultHeadOptions): VaultHeadStrategy;

package/dist/with-commit/vault-head/head.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The vault head's storage layer (#1044).
+ *
+ * A bucket is an ordinary encrypted record at `_head/<collection>::<n>`, so it
+ * inherits #1041's identity binding for free: the store cannot relocate a
+ * bucket, re-author it, or serve one bucket's bytes as another's. What it can
+ * still do is serve an OLD bucket, which is why {@link readBucket} enforces
+ * monotonicity against the caller's own record of what it last wrote.
+ *
+ * @packageDocumentation
+ */
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+import type { NoydbStore } from '../../kernel/types.js';
+/** `{ recordId → version }` for one bucket. */
+export type BucketBody = Record<string, number>;
+/**
+ * FNV-1a over `collection/id`. A hash, not a cipher: the bucket a record lands
+ * in is not secret — the store already sees which bucket was written, and it
+ * already saw the record's own address. Choosing something stronger would buy
+ * nothing and cost every write.
+ */
+export declare function bucketIndex(collection: string, id: string, buckets: number): number;
+export declare function bucketId(collection: string, id: string, buckets: number): string;
+export declare function readBucket(store: NoydbStore, vault: string, dek: EnclaveKey, bucket: string): Promise<{
+    body: BucketBody;
+    version: number;
+}>;
+export declare function writeBucket(store: NoydbStore, vault: string, dek: EnclaveKey, bucket: string, body: BucketBody, expectedVersion: number): Promise<void>;

package/dist/with-commit/vault-head/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@noy-db/hub/vault-head` — detect a store that WITHHOLDS (#1044).
+ *
+ * @packageDocumentation
+ */
+export { withVaultHead } from './active.js';
+export { verifyVaultHead, type HeadDiscrepancy, type HeadVerifyResult, type HeadVerdict, type HeadUnverifiableReason } from './verify.js';
+export { NO_VAULT_HEAD, VAULT_HEAD_COLLECTION, DEFAULT_HEAD_BUCKETS, type VaultHeadStrategy, type WithVaultHeadOptions, type HeadEntry, } from './strategy.js';
+export type { NoydbStore, EncryptedEnvelope } from '../../kernel/types.js';
+export type { EnclaveKey } from '../../kernel/enclave/index.js';

package/dist/with-commit/vault-head/strategy.d.ts

@@ -0,0 +1,127 @@
+/**
+ * `withVaultHead()` — the opt-in detector for **omission** (#1044).
+ *
+ * ## What it is for, and what it deliberately is not
+ *
+ * #1041 made every envelope self-authenticating at its identity, and #1042
+ * made the merge reject one that is not. What neither can catch is **absence**:
+ * a store that serves a genuine, unmodified `v1` when `v7` exists, or serves
+ * nothing at all. An authentic old envelope is indistinguishable from an
+ * authentic current one without external knowledge of what *should* be there.
+ *
+ * The head is that external knowledge: an authenticated `{id → version}`
+ * manifest the client writes and the store cannot forge. It is **not** a Merkle
+ * chain over content — content integrity is already handled, so the head needs
+ * only versions.
+ *
+ * ## Why it is opt-in when AAD is not
+ *
+ * AAD costs nothing to coordinate and closes *alteration*, so it is kernel. The
+ * head costs a write per commit and needs anti-entropy; on a single-device
+ * offline vault it defends against nothing. Making it kernel would tax every
+ * user for a multi-writer property. ADR 0003, Decision 3.
+ *
+ * `SECURITY.md` states the split exactly: a store cannot alter, relocate,
+ * re-tier, re-author or rewind a record; **without `withVaultHead()` it can
+ * still withhold or omit.**
+ *
+ * ## Bucketed, and why that is not a compromise
+ *
+ * ADR 0003 left head granularity open and asked for it to be sized early.
+ * Measured, at the documented 50K-record vault ceiling:
+ *
+ * | shape | write cost per commit | detection |
+ * |---|---|---|
+ * | one per-vault manifest | **1.1 MiB** | per-record |
+ * | one per collection | the same problem, renamed | per-record |
+ * | **bucketed, 256 buckets** | **~4.4 KiB** | per-record |
+ *
+ * Bucketing changes *only* write amplification. Each bucket still lists every
+ * one of its records' versions, so detection stays per-record — which is why
+ * this is not a trade-off between cost and strength. Verifying one pulled
+ * record reads one bucket rather than a megabyte.
+ *
+ * ## Wired as a bus OBSERVER, not a call in `collection.ts`
+ *
+ * That is what `kernel-surface` means by "register on the ServiceBus instead of
+ * growing this file", and it keeps the hot write path untouched for anyone who
+ * has not opted in: nothing is registered at all, so `hasHandlers` stays false
+ * and the dispatch never happens.
+ *
+ * Both `afterPut` AND `afterDelete`, because a delete is a version bump like
+ * any other. A head that stopped tracking deleted records would let a store
+ * resurrect one by withholding the tombstone — precisely the omission this
+ * exists to catch.
+ *
+ * ⚠️ The registration must be UNCONDITIONAL on anything but `enabled`. Its first
+ * draft sat inside `#registerForgetHooks()`, which returns early when no forget
+ * subjects are declared, so the head silently recorded nothing unless the vault
+ * happened to use an unrelated feature. The tests caught it only because they
+ * asserted a COUNT rather than "no error" — a head that records nothing raises
+ * no errors and sweeps perfectly clean.
+ *
+ * @packageDocumentation
+ */
+import type { NoydbStore, EncryptedEnvelope } from '../../kernel/types.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+/** Reserved collection the head's buckets live in. */
+export declare const VAULT_HEAD_COLLECTION: "_head";
+/** Default bucket count — see the sizing table above. */
+export declare const DEFAULT_HEAD_BUCKETS = 256;
+export interface WithVaultHeadOptions {
+    /**
+     * How many buckets the manifest is split across. Higher means smaller writes
+     * and more reads to sweep the whole vault; lower means the opposite.
+     * Changing it on an existing vault re-homes every entry, so treat it as a
+     * layout decision rather than a tuning knob.
+     */
+    readonly buckets?: number;
+}
+/** One record's expected state, as the client last committed it. */
+export interface HeadEntry {
+    readonly collection: string;
+    readonly id: string;
+    readonly version: number;
+}
+export interface VaultHeadStrategy {
+    /**
+     * Is the head actually keeping a manifest?
+     *
+     * An explicit flag rather than an identity check against the stub: the kernel
+     * decides whether to register the write-path observer at all, and
+     * `port-layering` forbids it importing `NO_VAULT_HEAD` to compare. Without
+     * this, every write in a vault that never opted in would still pay a cache
+     * lookup and a no-op call.
+     */
+    readonly enabled: boolean;
+    /** Bucket a record id lands in — pure, so callers can pre-group a batch. */
+    bucketFor(collection: string, id: string): string;
+    /**
+     * Record `entry` as the client's expectation for that record.
+     *
+     * Called on every committed write, INSIDE the same logical operation, so
+     * there is no window where the record exists and the head does not know it.
+     */
+    note(store: NoydbStore, vault: string, getDEK: (collection: string) => Promise<EnclaveKey>, entry: HeadEntry): Promise<void>;
+    /**
+     * What the client expects for `collection/id`, or `null` if the head has
+     * never seen it.
+     */
+    expected(store: NoydbStore, vault: string, getDEK: (collection: string) => Promise<EnclaveKey>, collection: string, id: string): Promise<number | null>;
+    /**
+     * Every record the head knows about in `collection` — the set a sweep
+     * compares against what the store actually serves, which is how DELETION
+     * SUPPRESSION is caught. A withheld record is absent from the store but
+     * present here.
+     */
+    knownIn(store: NoydbStore, vault: string, getDEK: (collection: string) => Promise<EnclaveKey>, collection: string): Promise<ReadonlyMap<string, number>>;
+}
+/**
+ * The un-opted-in stub. `note` is a NO-OP rather than a throw: the write path
+ * calls it unconditionally, and a vault without the head must simply not keep
+ * one. The READ side throws, because asking what the head expects when there is
+ * no head is a caller error, not a silent "nothing to report" — the latter
+ * would look exactly like a clean sweep.
+ */
+export declare const NO_VAULT_HEAD: VaultHeadStrategy;
+export type { EncryptedEnvelope };

package/dist/with-commit/vault-head/verify.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The sweep — comparing what the head expects against what the store serves (#1044).
+ *
+ * This is the only place absence becomes visible. #1041 and #1042 can reject a
+ * record that lies about itself; neither can notice one that never arrived, or
+ * one served at an older version than the client wrote. Both are indistinguishable
+ * from the truth without an independent record of what should be there.
+ *
+ * @packageDocumentation
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+import type { VaultHeadStrategy } from './strategy.js';
+/** One record the store is not serving faithfully. */
+export interface HeadDiscrepancy {
+    readonly collection: string;
+    readonly id: string;
+    /** What the client last committed. */
+    readonly expected: number;
+    /**
+     * What the store serves now — or `null` when it serves nothing.
+     *
+     * The two are different attacks wearing the same result. `null` is
+     * **suppression**: the record is gone. A lower number is **rollback**: an
+     * authentic older version served in place of the current one, which is the
+     * case no amount of per-envelope authentication can see.
+     */
+    readonly actual: number | null;
+    readonly kind: 'withheld' | 'rolled-back';
+}
+/**
+ * Why a sweep could not reach a conclusion.
+ *
+ * - `'no-expectations'` — the head holds nothing for this collection. A fresh
+ *   vault, a head switched on after the fact, or a **restore from a snapshot**:
+ *   `_head` is `_`-prefixed, so `loadAll` excludes it and a restored vault has
+ *   no head to compare against.
+ * - `'store-cannot-cas'` — the store does not advertise `capabilities.casAtomic`,
+ *   so two writers racing on one bucket can silently lose an entry. A lost entry
+ *   is a record the sweep stops expecting, which is a false clean.
+ */
+export type HeadUnverifiableReason = 'no-expectations' | 'store-cannot-cas';
+/**
+ * ## Three-way, deliberately (#1101)
+ *
+ * - `'verified'` — the head held expectations, every one was met, and the store
+ *   can serialize head writes.
+ * - `'unverifiable'` — the sweep could not conclude. See `because`.
+ * - `'tampered'` — at least one discrepancy. Positive evidence, so it wins over
+ *   any `unverifiable` reason present at the same time.
+ *
+ * **The middle value is the point, and collapsing it is wrong in a different
+ * direction each way:** folded into "clean" it hides withholding, which is the
+ * one thing this service exists to catch; folded into "tampered" it cries wolf
+ * on a vault that is merely unexamined.
+ *
+ * That is not hypothetical. #1044's own first bug was a head that recorded
+ * nothing and swept **perfectly clean** — the degraded state rendered
+ * identically to a healthy one, which is why its test asserts `checked` before
+ * anything else. A two-way verdict makes that state a supported outcome.
+ */
+export type HeadVerdict = 'verified' | 'unverifiable' | 'tampered';
+export interface HeadVerifyResult {
+    readonly verdict: HeadVerdict;
+    readonly checked: number;
+    readonly discrepancies: readonly HeadDiscrepancy[];
+    /**
+     * Non-empty only when `verdict === 'unverifiable'`.
+     *
+     * There is deliberately no `clean: boolean`. It could not distinguish "no
+     * expectations" from "all expectations met" — both rendered `true` — and that
+     * indistinguishability *was* the defect. Replacing it rather than keeping it
+     * alongside forces every caller to face the three-way.
+     */
+    readonly because: readonly HeadUnverifiableReason[];
+}
+/**
+ * Sweep one collection.
+ *
+ * **A record the store serves that the head does NOT know is not reported.**
+ * That is not an oversight: the head can be enabled on an existing vault, and
+ * every pre-existing record would otherwise read as an anomaly. The head's
+ * claim is one-directional — *what I wrote must still be there* — and an
+ * unknown record simply falls outside it.
+ *
+ * **A HIGHER version than expected is also not reported**, for the same reason:
+ * another device legitimately advanced it. The head detects going backwards, not
+ * moving forwards.
+ */
+export declare function verifyVaultHead(head: VaultHeadStrategy, store: NoydbStore, vault: string, getDEK: (collection: string) => Promise<EnclaveKey>, collection: string): Promise<HeadVerifyResult>;