@cloudbitmaps/core 0.21.0 → 0.23.0

package/dist/core/registry-scan.d.ts

@@ -15,11 +15,6 @@ export declare function drainRegistry(registry: IRegistryDriver, options: {
     namespace?: string;
     maxScanSegments: number;
     op: string;
-    /**
-     * How a caller of `op` raises the ceiling, completing "Narrow it with `namespace`, or …" in the refusal.
-     * Defaults to raising `maxScanSegments`, which is right wherever `op` takes that option itself.
-     */
-    raise?: string;
     /**
      * Whether the caller could scope the scan down to a `namespace`. Defaults to true; `eraseNamespace` is already
      * one namespace, so it passes false and the refusal does not tell it to narrow what it cannot.

package/dist/core/retention-sweep.d.ts

@@ -2,8 +2,24 @@ import { type IAuditSink } from './audit.js';
 import type { DropDeps, DropResult } from './erasure.js';
 /** Default cap on retirements per sweep — a bounded batch, so a policy mistake costs one batch, not the fleet. */
 export declare const DEFAULT_RETIRE_LIMIT = 100;
+/**
+ * The shortest `tombstoneGraceMs` a sweep takes: one hour. A first load whose create got no answer is sent again, and a
+ * tombstone purged before that copy arrives lets it create the row again over the purged name, wrapped key included.
+ * A grace of seconds is for a test, which advances an injected clock.
+ */
+export declare const MIN_TOMBSTONE_GRACE_MS = 3600000;
+/**
+ * Options of a retention sweep: the instant to judge policies at (`now`), which segments it considers, how many it
+ * retires in one call, how it finds them, whether it only reports (`dryRun`), where retirements are audited (`audit`),
+ * and whether and when it purges the tombstones of earlier retirements.
+ */
 export interface RetireExpiredOptions {
-    /** Scope the sweep to one namespace. Omit to sweep every namespace the registry knows. */
+    /**
+     * Scope the sweep to one namespace. Omit to sweep every namespace the registry knows, segments loaded with no
+     * namespace included. `'_default'`, the label the export tool and the disaster-recovery samples print, and the
+     * bucket's object keys use, for those segments, is an ordinary namespace name here: it scopes the sweep to a
+     * namespace of that name, not to them.
+     */
     readonly namespace?: string;
     /**
      * The instant to compare policies against (epoch-ms). Required here because `core/` takes its time from the
@@ -11,7 +27,7 @@ export interface RetireExpiredOptions {
      */
     readonly now: number;
     /**
-     * Maximum segments to retire in this cycle (default 100). It also bounds the purges attempted (a purge the registry
+     * Maximum segments to retire in this cycle (default 100; an integer of at least 1, `null` refused). It also bounds the purges attempted (a purge the registry
      * refuses is not charged; {@link RetireExpiredResult.purgeFaults} says how purging stops after refusals), the
      * due-index pointers to nothing one call removes, and, counted apart from the retirements, the tombstones this sweep
      * did not write whose pointers one call removes.
@@ -21,7 +37,10 @@ export interface RetireExpiredOptions {
     readonly dryRun?: boolean;
     /** Forwarded to each `dropSegment`, so every retirement lands in the audit trail as `segment.dispose`. */
     readonly audit?: IAuditSink;
-    /** Ceiling on rows enumerated (default 250,000); exceeding it throws. */
+    /**
+     * Ceiling on rows enumerated (default 250,000); exceeding it throws. On an `'index'` scan the check runs before
+     * each pointer's row is read, so live rows equal to the ceiling followed by a pointer whose row is gone throw too.
+     */
     readonly maxScanSegments?: number;
     /**
      * **Where the candidates come from.**
@@ -41,6 +60,8 @@ export interface RetireExpiredOptions {
      * tombstone under the day the tombstone's grace ends, and the scan reads it back with the expiry pointers. A pointer
      * whose segment is gone is removed once read, by an index scan in the buckets it reads, and by an unscoped `'fleet'`
      * scan (no `namespace`) in every bucket.
+     *
+     * Any other value, a misspelt `'index'` or a `null` included, throws `ValidationError` rather than running the fleet scan.
      */
     readonly scan?: 'fleet' | 'index';
     /**
@@ -49,14 +70,17 @@ export interface RetireExpiredOptions {
      * across restarts.
      */
     readonly shards?: readonly number[];
-    /** Total shards the fleet is split into. Required with {@link shards}; ignored without it. */
+    /**
+     * Total shards the fleet is split into. Required with {@link shards}; ignored without it. `shards` must list at least
+     * one number from 0 to `totalShards - 1`, each once, else `ValidationError`.
+     */
     readonly totalShards?: number;
     /**
      * How many **past** buckets an `'index'` scan reads besides the current one (default 7, one per day).
      * A sweep that did not run — scaled to zero, a failed deploy, a paused
      * schedule — leaves its buckets behind, and this is how far back a later cycle reaches for them. Bounded so a
      * long outage costs a bounded number of list calls per cycle rather than one per day since the epoch;
-     * anything older is the `'fleet'` repair pass's job.
+     * anything older is the `'fleet'` repair pass's job. An integer from 0 to 3660 on either scan, else `ValidationError`.
      */
     readonly lookbackBuckets?: number;
     /**
@@ -76,7 +100,13 @@ export interface RetireExpiredOptions {
      * zero is the opposite of another's is a reading hazard for whoever tunes both.
      */
     readonly purgeTombstones?: boolean;
-    /** How long a retirement's tombstone must age before this sweep deletes it (default 24 h). */
+    /**
+     * How long a retirement's tombstone must age before this sweep deletes it: at least one hour (`ValidationError`
+     * below), 24 h by default. The floor keeps the tombstone in place longer than a first load's create can take to be
+     * sent again after it got no answer, which would otherwise create the row again over the purged name, wrapped key
+     * included. Keep it well above the longest time a first load's registry write can still arrive (seconds on S3 and
+     * GCS, over a minute on Azure Blob at the SDK's default retry schedule). `null` is refused.
+     */
     readonly tombstoneGraceMs?: number;
 }
 /** What happened to one segment in a sweep. */
@@ -88,10 +118,13 @@ export type RetireEntry = {
     readonly expiresAt: number;
     readonly result: DropResult;
     /**
-     * Present when the retirement **completed the destructive part and then faulted** — the tombstone is written
-     * and the segment reads empty, but something after that (the Storage sweep) threw. The storage may not be fully
-     * reclaimed; re-run. Reported as `retired` rather than `skipped` because the segment really is retired, and
-     * saying otherwise is the one thing a caller cannot recover from.
+     * Present when the **tombstone landed and the retirement then faulted**: its storage sweep or listing threw, or
+     * the shred's own write got no answer that a read of the row could settle (then no `segment.erase` was emitted:
+     * record the crypto-shred yourself). `result.generationsRemaining` lists what a listing of the bucket found after
+     * the fault (the generations the row named, when that listing failed too). A sweep's re-run does not collect
+     * those objects inside `tombstoneGraceMs`: run `store.dropSegment(ref, { confirmSegment })`. Reported as `retired`
+     * rather than `skipped` because the segment really is retired, and saying otherwise is the one thing a caller
+     * cannot recover from.
      */
     readonly fault?: `failed: ${string}`;
 } | {
@@ -114,7 +147,8 @@ export type RetireEntry = {
      * `'invalid-policy'` — the row has an `expiresAt` that is not usable (hand-edited, or restored from another
      * schema). Reported rather than ignored: reading as "never expires" on a segment someone believes is
      * expiring is the silence that costs a retention commitment.
-     * `'limit'` — eligible, but this cycle's `limit` was already spent. Re-run to continue.
+     * `'limit'` — never written: a segment the cycle's `limit` deferred gets no entry, and
+     * {@link RetireExpiredResult.limited} is what says the cap cut the pass short. Re-run to continue.
      * `'tombstone-not-empty'` — a tombstone whose Storage generations are not gone even after a GC
      * attempt, so its row is kept, and, unless the collection lost a race to a write of the row, a refused purge
      * (see {@link RetireExpiredResult.purgeFaults}): the row is what keeps the segment reachable by the generation collection and
@@ -127,9 +161,14 @@ export type RetireEntry = {
      * re-reads before every deletion precisely so cancelling an expiry works on a sweep already in flight.
      * `` `failed: …` `` — any fault, isolated to this segment. A fault that happened *after* the tombstone
      * landed is reported as `retired` with a `fault` instead, because that segment IS retired.
+     * When the row cannot be read afterwards either, the reason says the tombstone may have landed.
      */
     readonly reason: 'invalid-policy' | 'limit' | 'tombstone-not-empty' | 'policy-changed' | `failed: ${string}`;
 };
+/**
+ * What a retention sweep did: the rows it read, what it retired, and a ledger entry for each segment it acted on or
+ * skipped.
+ */
 export interface RetireExpiredResult {
     /** Registry rows enumerated. */
     readonly scanned: number;
@@ -146,11 +185,15 @@ export interface RetireExpiredResult {
     readonly retired: number;
     /** Segments a real sweep **would** have retired. Only ever non-zero under `dryRun`. */
     readonly wouldRetire: number;
-    /** Tombstone rows actually deleted. Zero under `dryRun`; the `would-purge-tombstone` entries carry the preview. */
+    /**
+     * Tombstone rows this sweep saw deleted. Zero under `dryRun`; the `would-purge-tombstone` entries carry the preview.
+     * A purge another sweep made at the same moment is counted by both.
+     */
     readonly tombstonesPurged: number;
     /**
-     * True when `limit` cut the cycle short — **more segments are still eligible**. Re-run. The cap on removing pointers
-     * of tombstones this sweep did not write leaves it false.
+     * True when `limit` cut the pass short — **more work remains**: retirements, or purges of this sweep's tombstones,
+     * which the same `limit` counts. Re-run. The cap on removing pointers of tombstones this sweep did not write leaves
+     * it false.
      */
     readonly limited: boolean;
     /**
@@ -163,7 +206,7 @@ export interface RetireExpiredResult {
      *
      * A refused purge is not charged to `limit`, so retirements go on: a tombstone that cannot be purged does not hold
      * the segments behind it past their expiry. **Purging stops for the rest of the call after
-     * {@link MAX_CONSECUTIVE_PURGE_FAULTS} (3) refused purges in a row**, and a purge that succeeds starts the count
+     * 3 refused purges in a row**, and a purge that succeeds starts the count
      * again. A blanket refusal therefore costs three attempts a call, and a refusal particular to one row (a blob with a
      * snapshot, an object under a legal hold) holds nothing behind it. The next call tries again. Check this field; a
      * ledger entry for each is `skipped`, but a caller that reads only `retired` sees none of it.
@@ -171,8 +214,10 @@ export interface RetireExpiredResult {
     readonly purgeFaults: number;
     /** The first of those faults, as a ledger reason (`failed: …` with the provider's message). Absent when there were none. */
     readonly firstPurgeFault?: `failed: ${string}`;
+    /** Whether the sweep was a dry run, which changes nothing. */
     readonly dryRun: boolean;
-    /** Per-segment ledger. Inspect it: a `skipped` or failed entry is a segment that still holds data. */
+    /** Per-segment ledger. Inspect it: a `skipped` or failed entry is a segment that still holds data, except one whose reason says the row could
+     * not be read afterwards: its tombstone may have landed. */
     readonly entries: readonly RetireEntry[];
 }
 /**

package/dist/core/retention.d.ts

@@ -22,15 +22,23 @@ export interface RetentionPolicy {
 export interface RetentionDeps extends ChurnDeps {
     readonly registry: IRegistryDriver;
 }
+/**
+ * What setting a segment's retention policy did: the policy now stored, and whether it created the row and wrote the
+ * due-index pointer.
+ */
 export interface SetRetentionResult {
+    /** The segment's name. */
     readonly segment: string;
+    /** The segment's namespace, or `undefined` for the default one. */
     readonly namespace?: string;
     /** The policy now stored on the row. */
     readonly expiresAt: number;
     /**
      * True iff this call **minted the registry row** — a policy recorded before the segment's first load. The
      * segment is now enumerable by `registry.list()` and therefore by every fleet-wide operation; the row claims no
-     * Storage generation (`currentGen: null`), so reads answer empty until the first load publishes onto it.
+     * Storage generation (`currentGen: null`), so reads answer empty until the first load publishes onto it. A create
+     * that got no answer is read back and counts when the row carries this call's write token: a later policy or lease
+     * write does not hide it, and a later load's publish does (the call then decides again, and answers `false`).
      */
     readonly createdRow: boolean;
     /**
@@ -59,7 +67,7 @@ export declare function withoutSweepMark(meta: GovernanceMeta | undefined): Gove
  * The three-way answer exists so a fleet sweep can *report* a malformed policy instead of choosing between two
  * bad options: treating it as "no policy" hides an operator error on a segment someone believes is expiring, and
  * throwing aborts a ledger over one bad row. Nothing writes an invalid policy through
- * {@link setSegmentRetention} — hand-edited rows, an older/newer writer, or a restore are how it happens.
+ * `store.setRetention` — hand-edited rows, an older/newer writer, or a restore are how it happens.
  */
 export declare function readRetentionPolicy(meta: GovernanceMeta | undefined): RetentionPolicy | null | 'invalid';
 /** The stored policy for one segment, or `null` if it has none (and `'invalid'` for a malformed one). */
@@ -70,14 +78,17 @@ export declare function getSegmentRetention(ref: SegmentRef, deps: RetentionDeps
  * Idempotent and safe to re-run: writing the same instant twice is a no-op in effect. Other keys already in the
  * row's `retention` metadata are preserved — this owns one key, not the whole object.
  *
- * Refuses a `destroyed` segment: a tombstone has nothing left to retire, and putting a policy on one would make
- * a sweep repeatedly "retire" bytes that are already gone.
+ * Refuses a `destroyed` segment: a sweep never retires a tombstone (it purges only its own, by their stamp), so a
+ * policy on one would never act. Objects a destroy left in the bucket are deleted by `dropSegment` on the tombstone,
+ * not by a policy.
  */
 export declare function setSegmentRetention(ref: SegmentRef, deps: RetentionDeps, policy: RetentionPolicy): Promise<SetRetentionResult>;
 /**
- * Remove a segment's expiry so no sweep will retire it. Returns whether a policy was actually removed (`false`
- * for a segment with no row, or one that had no policy) — a separate verb from setting one, because "cancel the
- * expiry" and "expire at time T" are different intents and a magic sentinel value for the first is how a typo
+ * Remove a segment's expiry so no sweep will retire it. Returns whether this call removed a policy (`false` for a
+ * segment with no row, or one that had no policy, and also when a write that got no answer cannot be shown to be this
+ * call's and the row holds no expiry: the expiry is gone either way, and its due-index pointer is removed. A later
+ * write that set an expiry is cleared too, and the answer is `true`). A separate verb from setting one, because "cancel
+ * the expiry" and "expire at time T" are different intents and a magic sentinel value for the first is how a typo
  * becomes a deletion.
  *
  * Other `retention` keys are left in place; if removing the expiry empties the metadata, the field is cleared.

package/dist/core/retry.d.ts

@@ -1,4 +1,8 @@
 import type { Clock, Rng } from './determinism.js';
+/**
+ * How the store retries a transient read: attempts, exponential backoff with a cap, and jitter. By default 4 attempts,
+ * a 50 ms base delay, ×2, a 2 s cap and full jitter; the store's `retry` option overrides them a field at a time.
+ */
 export interface RetryPolicy {
     /** Total attempts including the first (so `maxAttempts: 4` = 1 try + 3 retries). Must be ≥ 1. */
     readonly maxAttempts: number;
@@ -44,7 +48,7 @@ export declare function backoffDelayMs(policy: RetryPolicy, attempt: number): nu
 /** Apply the policy's jitter to a computed delay using the injected RNG. */
 export declare function applyJitter(policy: RetryPolicy, delayMs: number, rng: Rng): number;
 /** A clock that can wait: the one member {@link jitteredWait} uses. */
-interface Sleeper {
+export interface Sleeper {
     readonly sleep?: ((ms: number) => Promise<void>) | undefined;
 }
 /**
@@ -79,4 +83,3 @@ export declare function checkedRetryPolicy(policy: RetryPolicy): RetryPolicy;
  * the *operation's* error — never a wrapper — so callers keep their typed-error branching.
  */
 export declare function withRetry<T>(op: () => Promise<T>, policy: RetryPolicy, deps: RetryDeps): Promise<T>;
-export {};

package/dist/core/rollback.d.ts

@@ -17,8 +17,12 @@ export interface GenerationListDeps extends ChurnDeps {
 }
 /** One generation present in the bucket. */
 export interface GenerationEntry {
+    /** The generation's number. */
     readonly generation: number;
-    /** Whether the registry pointer currently names this generation. */
+    /**
+     * Whether the registry pointer currently names this generation. `false` for every generation of a destroyed
+     * segment: a destroyed row keeps the pointer it had, but no read resolves a generation through it.
+     */
     readonly current: boolean;
     /**
      * Whether the row's record of the generations it published, `knownGens`, names this generation. A rollback onto a known
@@ -51,6 +55,7 @@ export interface GenerationEntry {
  * carries the id count and metadata its row records, from the same read.
  */
 export declare function listGenerations(ref: SegmentRef, deps: GenerationListDeps): Promise<GenerationEntry[]>;
+/** What a rollback moved: the generation the pointer named before, and the one it names now. */
 export interface RollbackResult {
     /** The generation the pointer named before the rollback. `null` when the segment had no current generation. */
     readonly fromGeneration: number | null;
@@ -75,8 +80,8 @@ export interface RollbackResult {
  * - a generation whose object is **not in the bucket** — collected, or never written — is refused with
  *   `NotFoundError` rather than pointed at, because a pointer naming a missing object is the one state the whole
  *   design exists to avoid;
- * - a **crypto-shredded** segment is refused: every generation of it is unreadable, so a rollback would produce a
- *   segment that resolves and then fails;
+ * - a **destroyed** segment (crypto-shredded, destroyed in the clear or dropped) is refused: no generation resolves
+ *   through a destroyed row, so moving its pointer would change nothing a reader sees;
  * - a target that is **not what the row says the segment is** is refused with `IntegrityError`: a cleartext object
  *   under a row with keys, or an encrypted one under a row with none, either of which every read would then refuse.
  *   One tail read of the target decides it, as does a footer that fails its own checks;
@@ -109,15 +114,21 @@ export interface RollbackResult {
  * failure of the keystore is thrown. After the swap the target's footer is read once more, and the pointer put back,
  * restoring the summary and the record the row had, unless it is still the object that was read: collection can delete a
  * target below the old pointer between the read and the swap, and an erasure can delete one above it and a load take its
- * number. A swap that gets no answer is settled by reading the row: one the row shows landed, the row being the one the
- * swap leaves, is checked as any swap is, and otherwise its `TransientError` is thrown, since it may have landed or may
- * still land, and a re-run finds the pointer where it is. A write by another writer is not taken for it, unless it leaves
- * the very row this swap would. On a cleartext segment two writes can: another rollback onto the same target, whatever
- * row it read, and a load that wrote under that number the very object the rollback read and carried the ledger the
- * rollback would (a load that carries a usable ledger, as one with a `keep` above 64 does; over a row with no usable
- * ledger the rollback writes none and a load seeds one, so those rows differ). On an encrypted segment a rollback with no
- * key at hand writes no summary, so another such rollback onto the same target can too. That call then reports and
- * audits the move as its own; the pointer is where it asked for it.
+ * number. A swap that meets a conflict or gets no answer is settled by reading the row. On a registry that reports its
+ * writes' tokens, one the row shows landed, its pointer at the target over the token of a swap this call sent, is
+ * checked as any swap is, the move audited and reported, whatever else was written to the row since (a lease, a
+ * retention or residency write, or a write of the ledger alone). Otherwise the call throws, and nothing is audited or
+ * deleted: the `WriteConflictError` after a conflict, and the `TransientError` after no answer, since it may have
+ * landed or may still land and a re-run finds the pointer where it is. Another writer's write of the same pointer is not
+ * taken for it, another rollback's identical move included, and neither is a write that renewed the row's `pointerId` over
+ * this swap, which cannot be told from it. A registry that reports no tokens settles a swap that got no answer by the
+ * row it would leave, and never settles a conflict as landed. Over such a registry a write by another writer is not
+ * taken for the swap unless it leaves the very row this swap would. On a cleartext segment two writes can: another
+ * rollback onto the same target, whatever row it read, and a load that wrote under that number the very object the
+ * rollback read and carried the ledger the rollback would (a load that carries a usable ledger, as one with a `keep`
+ * above 64 does; over a row with no usable ledger the rollback writes none and a load seeds one, so those rows differ).
+ * On an encrypted segment a rollback with no key at hand writes no summary, so another such rollback onto the same
+ * target can too. That call then reports and audits the move as its own; the pointer is where it asked for it.
  *
  * What it does **not** do is delete anything. The generations above the new pointer stay in the bucket, which is
  * what makes the rollback reversible — roll forward again by naming one of them. They are also then *above*

package/dist/core/validate.d.ts

@@ -16,6 +16,19 @@ export declare function isWellFormedString(value: string): boolean;
  * same way, and a second copy of that rule is how the two drifted apart before.
  */
 export declare function encodedNameLength(value: string): number;
+/**
+ * The keys a segment ref takes: its address, and the two a `segments()` row also carries so a listing row can be
+ * passed straight back. `discover.ts` holds this list to `SegmentInfo` at compile time, so a field added there is a
+ * type error until it is listed here.
+ */
+export declare const REF_KEYS: readonly ["segment", "namespace", "currentGen", "status"];
+/**
+ * Throws `ValidationError` unless `ref` is an object whose `segment` and, when given, `namespace` are valid names, and
+ * which holds no other key: a misspelt `namespace` would otherwise address the segment of that name in the default
+ * namespace. The keys it takes are a port's: `segment`, `namespace`, a `GenKey`'s `generation`, a `ChunkRef`'s
+ * `chunkKey`, and a registry row's own fields and a `segments()` row's, so a row a driver listed can be passed back.
+ * It does not refuse a reserved namespace, which a driver must be able to store.
+ */
 export declare function validateSegmentRef(ref: SegmentRef): void;
 /**
  * The namespace prefix the library keeps for its own bookkeeping: the due index stores one pointer row per
@@ -40,8 +53,26 @@ export declare function isReservedNamespace(namespace: string | undefined): bool
  * rows live in the reserved namespace and go through the drivers.
  */
 export declare function validateUserNamespace(namespace: string): void;
-/** Validate a segment ref an application hands in: the name rules, and a namespace outside the reserved prefix. */
-export declare function validateUserRef(ref: SegmentRef): void;
+/**
+ * The keys a driver port takes beyond a ref's own. The store hands its ports a generation key (a ref and a
+ * `generation`) or a chunk ref (a ref and a `chunkKey`) wherever they name a segment, and an operator repairing a
+ * registry hands them a row from `registry.list()` or `get()`, whose fields are fixed and listed here. A test holds
+ * the row fields to `RegistryRecord`'s.
+ */
+export declare const PORT_KEYS: readonly string[];
+/**
+ * Refuse a segment ref that holds a key it does not take, naming each such key, and a value that is a segment
+ * handle or an array rather than a ref. A misspelt `namespace` would otherwise address the segment of that name in
+ * the default namespace, and a drop, a rollback or a crypto-shred would act on the wrong segment. Only the ref's own
+ * enumerable string keys are read, one whose value is `undefined` included. `verb` names the call in the message.
+ */
+export declare function refuseUnknownRefKeys(ref: object, verb: string, extraKeys?: readonly string[]): void;
+/**
+ * Validate a segment ref an application hands in: the name rules, and a namespace outside the reserved prefix. With
+ * `verb`, the call a caller made, it also refuses a key a ref does not take, beyond `extraKeys`; leave `verb` out only
+ * for an internal key that extends a ref with keys of its own.
+ */
+export declare function validateUserRef(ref: SegmentRef, verb?: string, extraKeys?: readonly string[]): void;
 /**
  * Validate the keys of a `getChunks` stream: in ascending order, a key may repeat. Checked before anything is
  * resolved or read, so a caller's mistake costs no request.

package/dist/driver-kit.d.ts

@@ -1,7 +1,12 @@
-export type { GenKey, IRegistryDriver, IStorageDriver, SegmentRef, StorageBackend, StorageCaps, StorageDeleteOptions, TailRead, } from './core/ports.js';
+export type { GenKey, IRegistryDriver, IStorageDriver, LifecycleVerdict, SegmentRef, StorageBackend, StorageCaps, StorageDeleteOptions, TailRead, } from './core/ports.js';
 export { brandAsBackend, STORAGE_BACKEND } from './core/ports.js';
-export type { IMetricsSink, MetricEvent } from './core/metrics.js';
-export { IntegrityError, isIntegrityError, isNotFoundError, isTransientError, isValidationError, isWriteConflictError, NotFoundError, TransientError, ValidationError, WriteConflictError, } from './core/errors.js';
+export type { ClearRegistrySummary, GenerationMetadata, GovernanceMeta, KnownGeneration, LeaseEntry, NewRegistryRecord, RegCaps, RegistryPatch, RegistryRecord, RegistryStatus, RegistrySummary, RegistryWriteOptions, SealedRegistrySummary, Token, } from './core/ports.js';
+export type { ChunkRead, ChunkRef, GenerationSummary, ReadChunksOptions, SegmentSize, StorageChunkSource, } from './core/ports.js';
+export type { Aead, AeadSealed, IKeystore, WrappedDek } from './core/crypto.js';
+export type { Entropy } from './core/determinism.js';
+export type { IMetricsSink, MetricEvent, MetricOpName } from './core/metrics.js';
+export { CloudRoaringError, errorKind, IntegrityError, NotFoundError, TransientError, unsettledConflict, ValidationError, WriteConflictError, } from './core/errors.js';
+export type { ErrorKind } from './core/errors.js';
 export { RESOLVED_FIELDS, pointerIdOf, renewPointer, renewsPointer } from './core/pointer-id.js';
 export { validateSegmentRef } from './core/validate.js';
 export type { BlobSink } from './core/blob.js';
@@ -10,6 +15,6 @@ export type { ObjectRegistryStore, ObjectRow } from './drivers/_shared/object-re
 export { encodeNameForKey, encodeNameForPath, namespaceKeyPart, namespacePathPart, } from './drivers/_shared/keys.js';
 export { normalizeObjectPrefix, prefixPart } from './drivers/_shared/object-registry-keys.js';
 export { parseGenerationFromKey, segmentObjectPrefix, storageObjectKey, } from './drivers/_shared/object-keys.js';
-export { refuseUnknownOptions, requireBool, requirePositiveInt } from './drivers/_shared/options.js';
+export { checkDeleteOptions, checkRegistryWriteOptions, refuseUnknownOptions, requireBool, requireNonEmptyString, requirePositiveInt, } from './drivers/_shared/options.js';
 export { isTransportFault, toTransient } from './drivers/_shared/faults.js';
 export { concatBytes } from './drivers/_shared/bytes.js';

package/dist/driver-kit.js

@@ -1,5 +1,26 @@
+import {
+  mapWithConcurrency
+} from "./chunk-CGILDXGP.js";
 import {
   DEFAULT_NAMESPACE,
+  applyRegistryPatch,
+  checkDeleteOptions,
+  checkRegistryWriteOptions,
+  entropyIsAvailable,
+  namespaceKeyPart,
+  namespacePathPart,
+  newIncarnationToken,
+  nextRegistryToken,
+  parseRegistryEnvelope,
+  recordFromNew,
+  requirePositiveInt,
+  serializeRegistryEnvelope,
+  validateNewRegistryRecord,
+  validateRegistryPatch,
+  webCryptoEntropy
+} from "./chunk-7GT632UF.js";
+import {
+  CloudRoaringError,
   IntegrityError,
   NotFoundError,
   RESOLVED_FIELDS,
@@ -7,37 +28,24 @@ import {
   TransientError,
   ValidationError,
   WriteConflictError,
-  applyRegistryPatch,
   brandAsBackend,
   decodeNameFromKey,
   encodeNameForKey,
   encodeNameForPath,
-  entropyIsAvailable,
-  isIntegrityError,
-  isNotFoundError,
+  errorKind,
   isTransientError,
-  isValidationError,
+  isUnsettledConflict,
   isWriteConflictError,
-  mapWithConcurrency,
-  namespaceKeyPart,
-  namespacePathPart,
-  newIncarnationToken,
-  nextRegistryToken,
-  parseRegistryEnvelope,
   pointerIdOf,
-  recordFromNew,
   refuseUnknownOptions,
   renewPointer,
   renewsPointer,
   requireBool,
   requireInteger,
-  requirePositiveInt,
-  serializeRegistryEnvelope,
-  validateNewRegistryRecord,
-  validateRegistryPatch,
-  validateSegmentRef,
-  webCryptoEntropy
-} from "./chunk-IGLIZBR7.js";
+  requireNonEmptyString,
+  unsettledConflict,
+  validateSegmentRef
+} from "./chunk-MVUD4R72.js";
 
 // src/drivers/_shared/object-registry-keys.ts
 var REGISTRY_SUFFIX = ".reg";
@@ -52,6 +60,12 @@ function prefixPart(prefix) {
 }
 function normalizeObjectPrefix(prefix) {
   if (prefix === void 0) return void 0;
+  const given = prefix;
+  if (typeof given !== "string") {
+    throw new ValidationError(
+      `prefix must be a string; got ${given === null ? "null" : Array.isArray(given) ? "array" : typeof given}`
+    );
+  }
   for (const ch of prefix) {
     const code = ch.charCodeAt(0);
     if (code < 32 || code === 127) {
@@ -121,6 +135,7 @@ var MAX_DELETE_ATTEMPTS = 8;
 var MAX_READ_ATTEMPTS = 8;
 var LIST_READ_CONCURRENCY = 48;
 var ObjectVersionRaced = class extends Error {
+  /** Builds the error naming the object whose pinned version vanished. */
   constructor(objectKey) {
     super(`registry object was overwritten mid-read: ${objectKey}`);
     this.name = "ObjectVersionRaced";
@@ -143,6 +158,10 @@ var ObjectStoreRegistry = class {
   prefix;
   now;
   entropy;
+  /**
+   * Strong reads, always. `canWrite` is `false` when the runtime has no source of random bytes for tokens, and
+   * `conditionalDelete` is `true` when the store deletes a row only while it is still the version read.
+   */
   capabilities() {
     const conditionalDelete = this.removesRows();
     return entropyIsAvailable(this.entropy) ? { strongRead: true, conditionalDelete } : { strongRead: true, canWrite: false, conditionalDelete };
@@ -164,7 +183,13 @@ var ObjectStoreRegistry = class {
     this.observed.set(row.env.record, { key, bytes: row.bytes, version: row.version });
     return row.env.record;
   }
+  /**
+   * Write a new row, create-only over none or over a tombstone. `held: null` is the publish's contract: its caller read
+   * the row absent. A direct caller that passes it over a tombstone may see a conflict when the read-back after the
+   * lost create faults, though no live row exists.
+   */
   async create(ref, record, options) {
+    checkRegistryWriteOptions(options);
     const checked = validateNewRegistryRecord(record);
     const key = registryObjectKey(this.prefix, ref);
     let lost;
@@ -176,9 +201,16 @@ var ObjectStoreRegistry = class {
         lost = err;
       }
     }
-    const current = await this.readRow(key);
+    let current;
+    try {
+      current = await this.readRow(key);
+    } catch (err) {
+      if (lost !== void 0 && isTransientError(err)) throw lost;
+      throw err;
+    }
     if (current !== null && !current.env.deleted) {
-      throw new WriteConflictError(`registry row already exists for segment ${ref.segment}`);
+      const message = `registry row already exists for segment ${ref.segment}`;
+      throw isUnsettledConflict(lost) ? unsettledConflict(message) : new WriteConflictError(message);
     }
     if (lost !== void 0 && current === null) throw lost;
     return this.createOver(key, ref, checked, current ?? void 0, options);
@@ -195,6 +227,7 @@ var ObjectStoreRegistry = class {
     return { token };
   }
   async compareAndSwap(ref, expected, patch, options) {
+    checkRegistryWriteOptions(options);
     const checked = validateRegistryPatch(patch);
     const key = registryObjectKey(this.prefix, ref);
     const current = this.observedRow(key, expected, options?.held) ?? await this.readRow(key);
@@ -334,8 +367,10 @@ function segmentObjectPrefix(prefix, ref) {
   return `${prefixPart(prefix)}${namespaceKeyPart(ref.namespace)}/segments/${encodeNameForKey(ref.segment)}.`;
 }
 function storageObjectKey(prefix, key) {
+  validateSegmentRef(key);
   requireInteger(key.generation, { min: 0, what: "generation" });
-  return `${segmentObjectPrefix(prefix, key)}${key.generation}${SUFFIX}`;
+  const ref = { segment: key.segment, namespace: key.namespace };
+  return `${segmentObjectPrefix(prefix, ref)}${key.generation}${SUFFIX}`;
 }
 function parseGenerationFromKey(segmentPrefix, objectKey) {
   if (!objectKey.startsWith(segmentPrefix) || !objectKey.endsWith(SUFFIX)) return null;
@@ -378,6 +413,7 @@ function concatBytes(parts) {
   return out;
 }
 export {
+  CloudRoaringError,
   IntegrityError,
   MAX_ROW_BYTES,
   NotFoundError,
@@ -389,15 +425,13 @@ export {
   ValidationError,
   WriteConflictError,
   brandAsBackend,
+  checkDeleteOptions,
+  checkRegistryWriteOptions,
   concatBytes,
   encodeNameForKey,
   encodeNameForPath,
-  isIntegrityError,
-  isNotFoundError,
-  isTransientError,
+  errorKind,
   isTransportFault,
-  isValidationError,
-  isWriteConflictError,
   namespaceKeyPart,
   namespacePathPart,
   normalizeObjectPrefix,
@@ -408,10 +442,12 @@ export {
   renewPointer,
   renewsPointer,
   requireBool,
+  requireNonEmptyString,
   requirePositiveInt,
   segmentObjectPrefix,
   storageObjectKey,
   toTransient,
+  unsettledConflict,
   validateSegmentRef
 };
 //# sourceMappingURL=driver-kit.js.map