@cloudbitmaps/core 0.9.0 → 0.11.0

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

@@ -0,0 +1,198 @@
+/**
+ * The retention **sweep** — the thing that acts on the policies `setSegmentRetention` records.
+ *
+ * `retireExpired` enumerates the registry, selects the segments whose `expiresAt` has passed, and retires each
+ * one through {@link dropSegment}. It deliberately **delegates rather than reimplements**: the registry → Storage
+ * ordering, the re-sweep for an object a load was still writing, and the `generationsRemaining` report are all
+ * load-bearing and already live there. A sweep that open-coded the deletions would be a second
+ * implementation of the most dangerous ordering in the library.
+ *
+ * **This is a call, not a daemon.** Nothing here schedules itself. You run it from whatever heartbeat your
+ * deployment already has — an EventBridge rule, a Kubernetes CronJob, a queue consumer, the job that runs your
+ * loads — and the library stays a library: it has to behave identically in a Lambda, an edge isolate and a
+ * long-lived server, and a timer that only works in one of those is worse than none.
+ *
+ * Three properties make it safe to point at a fleet:
+ *
+ *  - **`dryRun` at the sweep level.** `dropSegment`'s `confirmSegment` guard is vacuous in a loop (it is the same
+ *    variable twice), so the meaningful preview is here: it reports what it *would* retire, per segment, and
+ *    touches nothing.
+ *  - **A per-cycle `limit`.** Clock skew, a bad backfill, or a namespace-wide policy mistake should cost one
+ *    bounded batch, not the fleet. When the limit bites, the result says so (`limited: true`) rather than looking
+ *    like a completed sweep.
+ *  - **A ledger, never an exception.** A per-segment fault is recorded and the sweep continues — the caller's
+ *    load-bearing question is *which* segments were retired, and a throw from the middle of the loop answers it
+ *    for none of them while having already retired some. Same posture as `eraseNamespace`.
+ *
+ * It also **purges the tombstones its own retirements leave behind**. A retired segment that had a registry row
+ * gets a `destroyed` row, and one dead row per retired daily bucket — or per retired dedup wave — is exactly the
+ * registry litter `dropSegment` already refuses to create for a row-less accumulator. Purging is narrow on
+ * purpose: only a tombstone carrying the **stamp this sweep writes on its own retirements** (so it is attributably
+ * ours: a crypto-shred's tombstone does not carry it, unless the shred lands between this sweep's re-read of the
+ * row and its drop, which then reports the tombstone dropped and stamps it), only after a grace period, and only
+ * once Storage is provably empty for it —
+ * because deleting the row is what makes the name reusable and takes the segment out of reach of
+ * the generation collection.
+ */
+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;
+/**
+ * Default delay before a retirement's own tombstone row is purged: 24 h.
+ *
+ * The row is a fence — while it exists, a load refuses the segment, so
+ * a load that was mid-write when the drop landed cannot resurrect it. That window is
+ * seconds to minutes in practice; a day of margin costs one tiny row and removes any need to reason about it.
+ */
+export declare const DEFAULT_TOMBSTONE_GRACE_MS = 86400000;
+export interface RetireExpiredOptions {
+    /** Scope the sweep to one namespace. Omit to sweep every namespace the registry knows. */
+    readonly namespace?: string;
+    /**
+     * The instant to compare policies against (epoch-ms). Required here because `core/` takes its time from the
+     * caller, never from the platform — `store.retireExpired()` fills it in from the store's clock.
+     */
+    readonly now: number;
+    /** Maximum segments to retire in this cycle (default 100). */
+    readonly limit?: number;
+    /** Report what would be retired and change nothing. */
+    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. */
+    readonly maxScanSegments?: number;
+    /**
+     * **Where the candidates come from.**
+     *
+     * - `'fleet'` (default) — drain `registry.list()` and filter. Cost tracks the **fleet**, every cycle, even
+     *   when nothing expires. Complete by construction: it cannot miss a policy.
+     * - `'index'` — read only the due buckets of the due index. Cost tracks **what is
+     *   expiring**. Each candidate's live row is still re-read before anything is decided, so a stale pointer
+     *   costs one read and retires nothing.
+     *
+     * **`'index'` is not a drop-in replacement for `'fleet'`; it is the fast half of a pair.** A policy whose
+     * pointer write failed (`indexed: false`), or whose ref is too long to index, has no pointer — so a
+     * deployment that *only* ever runs `'index'` will never retire those. Run `'fleet'` periodically as the
+     * repair pass. The default is `'fleet'` because it is complete by construction.
+     */
+    readonly scan?: 'fleet' | 'index';
+    /**
+     * **The shards this worker owns**, with {@link totalShards}. Without them every replica sweeps the whole
+     * fleet and contends over the same segments. A stable hash of the segment key, so a worker owns the same slice
+     * across restarts.
+     */
+    readonly shards?: readonly number[];
+    /** Total shards the fleet is split into. Required with {@link shards}; ignored without it. */
+    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.
+     */
+    readonly lookbackBuckets?: number;
+    /**
+     * Whether to delete the tombstone rows this sweep's own past retirements left (default `true`). Set `false` to
+     * keep every one of them — the right choice if something outside this library treats the presence of a
+     * `destroyed` row as an attestation. That includes the row of a retirement whose drop found no Storage
+     * generation to delete and left none behind: with the default that row is deleted in the same pass, since it
+     * would do nothing but fence the name against every writer, and with `false` it stays, stamped like any other
+     * of this sweep's tombstones, so a later sweep with purging on deletes it once `tombstoneGraceMs` has passed.
+     * While it stays, it fences the name like every kept tombstone. What records a retirement either way is its
+     * ledger entry, and its `segment.dispose` event (`generationsDeleted: 0` for an empty one) when an `audit` sink
+     * is passed.
+     *
+     * Two knobs rather than one `number | 'never'`, deliberately: `0` would have had to mean "purge immediately"
+     * here while `cache.genTtlMs: 0` in this same library means "never refresh on a timer", and one option whose
+     * 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). */
+    readonly tombstoneGraceMs?: number;
+}
+/** What happened to one segment in a sweep. */
+export type RetireEntry = {
+    readonly segment: string;
+    readonly namespace?: string;
+    /** Retired: `result` is `dropSegment`'s full report — **check `generationsRemaining`**. */
+    readonly action: 'retired';
+    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.
+     */
+    readonly fault?: `failed: ${string}`;
+} | {
+    readonly segment: string;
+    readonly namespace?: string;
+    /** `dryRun` only — what a real sweep would have retired, with `dropSegment`'s own preview attached. */
+    readonly action: 'would-retire';
+    readonly expiresAt: number;
+    readonly result: DropResult;
+} | {
+    readonly segment: string;
+    readonly namespace?: string;
+    /** A tombstone row from an earlier retirement was deleted (or would be, under `dryRun`). */
+    readonly action: 'purged-tombstone' | 'would-purge-tombstone';
+} | {
+    readonly segment: string;
+    readonly namespace?: string;
+    readonly action: 'skipped';
+    /**
+     * `'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.
+     * `'tombstone-not-empty'` — a tombstone whose Storage generations are not gone even after a GC
+     * attempt, so its row is kept: the row is what keeps the segment reachable by the generation collection and
+     * refused by every writer. Several causes, all self-healing: the storage really could not be reclaimed,
+     * the collection *declined* because the row changed underneath it (`WriteConflictError`, which this
+     * sweep swallows deliberately), or this was a `dryRun`, which reports the reason without attempting the
+     * collection at all. Except under `dryRun` the next cycle retries.
+     * `'policy-changed'` — the live row no longer says "expired" (a `clearRetention`, a new `expiresAt`, or
+     * someone else's drop landed between the enumeration and this segment's turn). Not an error: the sweep
+     * 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.
+     */
+    readonly reason: 'invalid-policy' | 'limit' | 'tombstone-not-empty' | 'policy-changed' | `failed: ${string}`;
+};
+export interface RetireExpiredResult {
+    /** Registry rows enumerated. */
+    readonly scanned: number;
+    /** Rows whose policy said "expired" — including any the `limit` deferred. */
+    readonly eligible: number;
+    /**
+     * Segments **actually retired**. Zero under `dryRun` — see `wouldRetire`. Kept honest because this is the field
+     * most likely to end up on a dashboard: a counter that means "deleted" in one mode and
+     * "would delete" in another produces phantom deletions on any graph that does not also join on `dryRun`.
+     */
+    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. */
+    readonly tombstonesPurged: number;
+    /** True when `limit` cut the cycle short — **more segments are still eligible**. Re-run. */
+    readonly limited: boolean;
+    readonly dryRun: boolean;
+    /** Per-segment ledger. Inspect it: a `skipped` or failed entry is a segment that still holds data. */
+    readonly entries: readonly RetireEntry[];
+}
+/**
+ * How many past buckets an index scan reads besides the current one. A week: long enough that a weekend outage
+ * or a paused schedule recovers on its own, short enough that a cycle is eight list calls rather than hundreds.
+ */
+export declare const DEFAULT_LOOKBACK_BUCKETS = 7;
+/**
+ * Retire every segment whose retention policy has expired, and clean up the tombstones earlier sweeps left.
+ *
+ * Returns a ledger; **never throws for a per-segment fault** (those become entries). It does throw for a bad
+ * argument, and for a fleet larger than `maxScanSegments` — a scan that cannot be held in memory is a fail-loud
+ * condition, not a partial result to be mistaken for a complete sweep.
+ */
+export declare function retireExpired(deps: DropDeps, options: RetireExpiredOptions): Promise<RetireExpiredResult>;

package/dist/core/retention.d.ts

@@ -0,0 +1,67 @@
+import type { GovernanceMeta, IRegistryDriver, SegmentRef } from './ports.js';
+/**
+ * The smallest accepted `expiresAt`: 2001-09-09, the point below which an epoch-**seconds** value would land.
+ *
+ * This is a deliberate guard against the single most damaging typo available here. `Date.now() / 1000 + 30 * 86400`
+ * is a natural thing to write, and it produces a number ~1.8 billion — an instant in **1970**, which is to say
+ * *already expired*. Without this check, that typo is not a validation error, it is a sweep that retires the
+ * segment on its very next pass. Anything below this floor is far likelier to be seconds than a genuine intent to
+ * expire a segment two decades ago, and the caller who really means "retire it now" can say so with `dropSegment`.
+ */
+export declare const MIN_EXPIRES_AT_MS = 1000000000000;
+/** A segment's retention policy: the instant it becomes eligible for retirement. */
+export interface RetentionPolicy {
+    /**
+     * Absolute epoch-**milliseconds**. Once `now >= expiresAt`, a retention sweep may retire the segment — tombstone
+     * it and delete its Storage generations. A value in the past is legal (backfilling a policy onto existing
+     * buckets is a normal thing to do) and means "eligible on the next sweep".
+     */
+    readonly expiresAt: number;
+}
+export interface RetentionDeps {
+    readonly registry: IRegistryDriver;
+}
+export interface SetRetentionResult {
+    readonly segment: string;
+    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.
+     */
+    readonly createdRow: boolean;
+    /**
+     * True iff the **due-index pointer** for this policy was written, so a fast sweep will find this segment by
+     * reading only its expiry day instead of scanning the fleet.
+     *
+     * `false` is a **degradation, not an error**, and the policy is committed either way: either the ref is too
+     * long to encode into one index-row name, or the pointer write failed. The full-scan repair pass still sees
+     * the segment's own row, so it is retired on the repair cadence rather than the fast one — slower, never
+     * never. Alarm on a *sustained* run of `false`, not on one.
+     */
+    readonly indexed: boolean;
+}
+/**
+ * Read the policy off a registry row's `retention` metadata. Returns `null` when there is no policy, and
+ * `'invalid'` when the key is present but unusable (wrong type, or below the epoch-seconds floor).
+ *
+ * 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.
+ */
+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). */
+export declare function getSegmentRetention(ref: SegmentRef, deps: RetentionDeps): Promise<RetentionPolicy | null | 'invalid'>;
+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
+ * becomes a deletion.
+ *
+ * Other `retention` keys are left in place; if removing the expiry empties the metadata, the field is cleared.
+ */
+export declare function clearSegmentRetention(ref: SegmentRef, deps: RetentionDeps): Promise<boolean>;

package/dist/core/retry.d.ts

@@ -0,0 +1,69 @@
+/**
+ * `withRetry` — the one retry/backoff primitive.
+ *
+ * A pure, storage-agnostic helper: it knows nothing about HTTP, AWS, or any SDK. It retries an operation
+ * while the operation keeps failing with a **retryable** error (by default {@link TransientError}), waiting
+ * a bounded, jittered, exponentially-growing delay between attempts. Time and randomness are **injected**
+ * (the determinism seam) — production wires a `setTimeout`-backed clock + a real RNG; the
+ * tests wire virtual ones — so a backoff schedule is replayable from a seed and unit tests run with no
+ * real sleeping.
+ *
+ * It deliberately does **not** retry deterministic failures ({@link WriteConflictError},
+ * {@link ValidationError}, {@link IntegrityError}, {@link NotFoundError}, …): retrying those either can't
+ * help or would be incorrect. A pointer conflict is retried by a *separate* loop inside
+ * the publish, because each attempt must re-read the row and re-decide — a blind replay of the same
+ * compare-and-swap would either fail again on a stale token or, worse, advance a pointer whose state has
+ * changed underneath it. A write-once object collision is never replayed at all: the generation number is
+ * taken, so the caller has to pick a new one.
+ */
+import type { Clock, Rng } from './determinism.js';
+export interface RetryPolicy {
+    /** Total attempts including the first (so `maxAttempts: 4` = 1 try + 3 retries). Must be ≥ 1. */
+    readonly maxAttempts: number;
+    /** Delay before the first retry, in ms. Grows by `backoffFactor` each subsequent retry. */
+    readonly baseDelayMs: number;
+    /** Upper bound on a single (pre-jitter) delay, in ms — caps the exponential growth. */
+    readonly maxDelayMs: number;
+    /** Exponential growth factor between retries (e.g. 2 ⇒ base, 2·base, 4·base, …). */
+    readonly backoffFactor: number;
+    /**
+     * `'full'` ⇒ the actual wait is uniform in `[0, computed]` (AWS-recommended full jitter: decorrelates
+     * concurrent retriers so they don't reconverge into a thundering herd). `'none'` ⇒ wait exactly `computed`.
+     */
+    readonly jitter: 'full' | 'none';
+}
+/**
+ * Conservative defaults: 4 attempts, 50ms → 100 → 200 (×2), capped at 2s, full jitter. Tuned for a cloud
+ * backend's brief throttle/5xx blip — enough to ride out a transient fault without turning a hard outage
+ * into a long hang. Override per store (`retry`) or per read source (`RetryingStorageChunkSource`) if your latency
+ * budget differs.
+ */
+export declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+export interface RetryDeps {
+    readonly clock: Clock;
+    readonly rng: Rng;
+    /** Override which errors are retryable. Default: any {@link TransientError}. */
+    readonly isRetryable?: (err: unknown) => boolean;
+    /**
+     * Optional hook (observability) fired before each backoff wait. `attempt` is 1-based (the one that failed).
+     * Best-effort: an error it throws is swallowed, so it can neither stop the retry nor change the error thrown.
+     */
+    readonly onRetry?: (info: {
+        attempt: number;
+        delayMs: number;
+        err: unknown;
+    }) => void;
+}
+/**
+ * Backoff delay (ms) for the retry that follows a given 1-based attempt, before jitter is applied. Exposed
+ * for tests. `attempt` 1 ⇒ `baseDelayMs`, 2 ⇒ `base·factor`, … capped at `maxDelayMs`.
+ */
+export declare function backoffDelayMs(policy: RetryPolicy, attempt: number): number;
+/** Apply the policy's jitter to a computed delay using the injected RNG. */
+export declare function applyJitter(policy: RetryPolicy, delayMs: number, rng: Rng): number;
+/**
+ * Run `op`, retrying transient failures per `policy`. Resolves with `op`'s result, or rejects with the last
+ * error once attempts are exhausted (or immediately for a non-retryable error). The thrown error is always
+ * 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>;

package/dist/core/rollback.d.ts

@@ -0,0 +1,75 @@
+/**
+ * `listGenerations` and `rollbackSegment` — see what a segment has been, and put it back.
+ *
+ * Immutable generations mean the previous version of a segment is usually still sitting in the bucket: a load
+ * that replaced it did not overwrite anything, it wrote a new object and moved a pointer. So recovering from a
+ * bad load is, in principle, moving the pointer back, which no load, publish or sweep can do, because every other
+ * write path in the library only ever advances the pointer, and refuses a move that would lower it.
+ *
+ * That refusal is right for a *writer*: a load whose ids came from upstream loses nothing by being out-raced, and
+ * letting it regress the pointer would let a slow loader silently undo a fast one. It is wrong for an *operator*,
+ * who has looked at the segment, decided the current generation is wrong, and knows which one they want. So
+ * rollback is the one call that moves the pointer backwards, and it is deliberately not reachable from any
+ * automatic path — no sweep, no retry, no reconciliation calls it.
+ *
+ * It is audited for the same reason. Every other pointer move can be reconstructed from "a load happened"; this
+ * one is a human overriding the ordering rule the rest of the system relies on, which is exactly the event an
+ * Art. 30 record or an incident review wants to find.
+ */
+import { type IAuditSink } from './audit.js';
+import type { IStorageDriver, IRegistryDriver, SegmentRef } from './ports.js';
+/** What the generation helpers need: the objects, and the pointer that says which one is current. */
+export interface GenerationListDeps {
+    readonly storage: IStorageDriver;
+    readonly registry: IRegistryDriver;
+}
+/** One generation present in the bucket. */
+export interface GenerationEntry {
+    readonly generation: number;
+    /** Whether the registry pointer currently names this generation. */
+    readonly current: boolean;
+}
+/**
+ * Every generation still present for a segment, ascending, with the current one marked.
+ *
+ * This is what the bucket holds, not what the segment has ever been: generation collection deletes superseded
+ * objects, so the list is the grace window plus whatever has not been collected yet. It is the set a
+ * {@link rollbackSegment} can choose from, which is the reason to look at it.
+ *
+ * One registry read and one `list` call, whether or not the segment has a registry row, so it also finds the
+ * objects a purged row left behind. It does not open the objects, so it costs nothing per generation and tells you
+ * nothing about their contents — read the sizes through the store's own report if you need them.
+ */
+export declare function listGenerations(ref: SegmentRef, deps: GenerationListDeps): Promise<GenerationEntry[]>;
+export interface RollbackResult {
+    /** The generation the pointer named before the rollback. `null` when the segment had no current generation. */
+    readonly fromGeneration: number | null;
+    /** The generation the pointer names now. */
+    readonly generation: number;
+}
+/**
+ * Move a segment's pointer **back** to a generation that is still in the bucket.
+ *
+ * The only non-forward-only publish in the library, and the only one an operator has to ask for by name. It
+ * refuses rather than guesses:
+ *
+ * - 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;
+ * - rolling to the generation **already current** is a no-op that reports itself, not an error.
+ *
+ * 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*
+ * `currentGen`, where generation collection never looks. They stay until a load numbers above them (collection
+ * then keeps the newest `keep` of what is below its pointer), `dropSegment` deletes them, or a subject erasure
+ * deletes them: all of those present when it rewrites, and only those holding the id when the current generation does not.
+ * Not collecting them is a deliberate trade: an operator who has just undone a bad load should not have the
+ * evidence collected out from under them, while a rollback target that still holds erased data would make the
+ * erasure undoable by an ordinary operator action.
+ */
+export declare function rollbackSegment(ref: SegmentRef, toGeneration: number, deps: GenerationListDeps, options?: {
+    audit?: IAuditSink;
+    allowForward?: boolean;
+}): Promise<RollbackResult>;

package/dist/core/validate.d.ts

@@ -0,0 +1,44 @@
+import type { ChunkRef, SegmentRef } from './ports.js';
+/**
+ * The most an encoded name may occupy in a physical key.
+ *
+ * S3's limit is 1024 bytes for the WHOLE key, which also carries the caller's prefix, the namespace, a fixed
+ * infix (`/segments/`) and the `.<generation>.crbm` suffix. 256 leaves generous room for all of that with both
+ * a namespace and a segment at the ceiling.
+ */
+export declare const MAX_NAME_LENGTH = 256;
+/**
+ * How long a name is once storage has it — the longer of the two encodings.
+ *
+ * Exported because anything that composes a name out of other names (the due index does) has to measure it the
+ * same way, and a second copy of that rule is how the two drifted apart before.
+ */
+export declare function encodedNameLength(value: string): number;
+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
+ * expiring segment in `cbm.due.<bucket>` (see `due-index.ts`). **One constant, read by both sides** — the
+ * application-facing checks below refuse it in a name an application passes in, and the due index writes and
+ * recognises its rows by it — so the two cannot drift.
+ *
+ * Only this exact prefix is reserved, not `cbm.` as a whole: `cbm.dueX`, `cbm.due` and `cbmdue.eu` are ordinary
+ * namespaces. Every fleet-wide enumeration skips the rows of a reserved namespace as bookkeeping, so a segment
+ * there would be invisible to an erasure, a consistency check, an export and a retention sweep.
+ *
+ * Internal: not exported from any entry. The flavor keeps a copy for its own facade checks, and a test pins the
+ * two together.
+ */
+export declare const RESERVED_NAMESPACE_PREFIX = "cbm.due.";
+/** Does this namespace start with {@link RESERVED_NAMESPACE_PREFIX}? `undefined` (no namespace) never does. */
+export declare function isReservedNamespace(namespace: string | undefined): boolean;
+/**
+ * Validate a namespace an application names, as a segment ref's namespace or as a `namespace` option that scopes
+ * a scan: the name rules, and **not** in the reserved namespace. Internal; the public `validateSegmentRef` of
+ * `@cloudbitmaps/core/driver-kit` is the name rules only, which is what a driver needs, since the due index's own
+ * 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;
+/** Validate a chunk ref: the segment/namespace rules plus `chunkKey` ∈ `[0, 65535]` (a u16). A driver-boundary check. */
+export declare function validateChunkRef(ref: ChunkRef): void;

package/dist/driver-kit.d.ts

@@ -0,0 +1,9 @@
+export type { GenKey, IRegistryDriver, IStorageDriver, SegmentRef, StorageBackend, StorageCaps, } from './core/ports.js';
+export { brandAsBackend, STORAGE_BACKEND } from './core/ports.js';
+export { IntegrityError, isNotFoundError, isValidationError, isWriteConflictError, NotFoundError, TransientError, ValidationError, WriteConflictError, } from './core/errors.js';
+export { validateSegmentRef } from './core/validate.js';
+export type { BlobSink } from './core/blob.js';
+export { MAX_ROW_BYTES, ObjectStoreRegistry, ObjectVersionRaced, } from './drivers/_shared/object-registry.js';
+export type { ObjectRegistryStore, ObjectRow } from './drivers/_shared/object-registry.js';
+export { encodeNameForKey, encodeNameForPath, namespaceKeyPart, namespacePathPart, } from './drivers/_shared/keys.js';
+export { normalizeObjectPrefix, prefixPart } from './drivers/_shared/object-registry-keys.js';