@farukada/aws-langgraph-dynamodb-ts 1.0.0-rc.2 → 1.0.0

package/dist/{shared → cjs/shared}/codec/s3/lifecycle.d.ts

@@ -2,13 +2,16 @@
  * Hides the bucket lifecycle configuration this package maintains.
  *
  * Two rules per prefix — one expiring objects a day after the ttl plus the
- * sweep margin and keeping a released payload's noncurrent version for a grace
- * window, one reclaiming expired delete markers — are written without
- * disturbing any other rule on the bucket, rewritten only when they differ,
- * and followed by a report of whether the bucket keeps versions at all.
+ * sweep margin and keeping a released payload's noncurrent version for a
+ * grace window, one reclaiming expired delete markers — are written beside
+ * whatever else the read that built the write showed, rewritten only when
+ * they differ. A lifecycle GET carries no version, so a later read can show
+ * less than an earlier one; a rule that read does not show — this package's
+ * own included — is dropped by the write built from it. This is followed by
+ * a report of whether the bucket keeps versions at all.
  */
 import type { LifecycleRule, S3Client } from '@aws-sdk/client-s3';
-import type { Logger } from '../../logging/logger';
+import type { Logger } from '../../logging/logger.js';
 /**
  * Days a released payload's noncurrent version survives behind its delete
  * marker before S3 reclaims it. One day is the smallest the lifecycle API
@@ -27,6 +30,12 @@ export interface LifecycleTarget {
     readonly prefix: string;
     readonly days: number;
 }
+/** Rounds {@link ensureLifecycleRule} polls before it reports a writer it cannot outlast. */
+export declare const LIFECYCLE_SETTLE_WRITES = 5;
+/** How {@link ensureLifecycleRule} waits between re-reads; a test passes one that takes no time. */
+export interface LifecyclePace {
+    wait?: (delayMs: number) => Promise<void>;
+}
 /**
  * Ensure the two rules scoped to `target.prefix` exist on `target.bucket`: a
  * `target.days`-day expiration for current versions, and the reclaim that
@@ -38,24 +47,69 @@ export interface LifecycleTarget {
  * versions are governed by the release grace instead (see {@link ttlRule}),
  * which is a floor measured against every rule already governing these keys.
  * Both are inert on an unversioned bucket, which keeps no noncurrent version
- * and leaves no marker.
+ * and leaves no marker. `pace.wait` — how to wait between re-reads; the
+ * default sleeps.
  *
  * Returns: nothing. Idempotent: when both rules already say this, no write is
- * issued. The bucket's versioning state is reported either way, because the
- * containment a released payload depends on is missing or present regardless
- * of whether this particular call had a rule to write.
+ * issued. Otherwise it writes them, waits, and re-reads. A bucket's
+ * configuration is served eventually consistently rather than
+ * read-your-writes
+ * (https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html, "Amazon
+ * S3 data consistency model": "Bucket configurations have an eventual
+ * consistency model"), and S3 documents specifically that a lifecycle
+ * configuration can take a few minutes to fully propagate
+ * (https://docs.aws.amazon.com/AmazonS3/latest/userguide/how-to-set-lifecycle-configuration-intro.html,
+ * "Lifecycle configuration propagation delay"). So a re-read that still shows
+ * the same rules — by id and the fields this comparison examines — as the
+ * read behind this call's last write is treated as that lag, not as loss, and
+ * prompts another wait rather than another write; a re-read that instead
+ * shows some *other* configuration, still without this call's rules, is a
+ * competing writer, and the rules are written again, merged with whatever
+ * that read now holds. The waits (1, 2, 4, 8 s) and the five-round limit are
+ * this library's own polling policy — a choice, not a bound AWS documents.
+ * `CONTENTION` is reserved for a writer this call never once found the bucket
+ * at rest for: it fires only when every one of the five rounds needs a
+ * write, meaning no re-read this call took ever agreed with the one before
+ * it. A last round that writes without reaching that count, or that finds
+ * only lag, ends the same way instead — a `warn` and a normal return: the
+ * rules were written, only their visibility could not be confirmed here, and
+ * a later call (or the same one, run again after a few minutes) can still
+ * find them settled. The bucket's versioning state is reported on every exit
+ * the loop itself chooses — settled, lag, a late rival, or `CONTENTION` —
+ * because the containment a released payload depends on is missing or
+ * present regardless of how this call ended. A read or write failure, or a
+ * `VALIDATION` `planRules` raises from a re-read, propagates directly instead
+ * and skips it, the same as it would skip any other cleanup this never got
+ * to.
  *
  * Throws: `VALIDATION` naming `s3.keyPrefix` for an unscoped prefix, or when
  * either rule id this prefix produces is already held by a different prefix
- * (see {@link assertNoIdCollision}); otherwise whatever the SDK rejects with. A
- * bucket with no lifecycle configuration at all is not an error — S3 reports
- * `NoSuchLifecycleConfiguration` and this starts from an empty rule set.
- *
- * Guarantees: rules this package did not write are preserved, and so is the
- * bucket-level `TransitionDefaultMinimumObjectSize` — a Put replaces the whole
- * configuration, so dropping it would silently reset the bucket to the default.
+ * (see {@link assertNoIdCollision}); `CONTENTION` when every one of the five
+ * rounds this call polls needs a write — a competing writer replacing the
+ * configuration on every single re-read, never once leaving it long enough
+ * for lag alone to explain what this call sees; otherwise whatever the SDK
+ * rejects with. A bucket with no lifecycle configuration at all is not an
+ * error — S3 reports `NoSuchLifecycleConfiguration` and this starts from an
+ * empty rule set.
+ *
+ * Guarantees: a write carries forward whatever its own read showed — every
+ * rule this package did not add or replace, and the bucket-level
+ * `TransitionDefaultMinimumObjectSize` — because a Put replaces the whole
+ * configuration and dropping either would silently reset the bucket. That
+ * guarantee is only as good as the read, though: a lifecycle GET carries no
+ * version, so a later read can show less than an earlier one, and a rule —
+ * this package's own included — that a write's own read does not show is
+ * dropped by that write, whether or not it is genuinely still on the bucket.
+ * Building each write from a read taken right before it, rather than from a
+ * plan an earlier wait left stale, narrows this without closing it: a rule a
+ * competing writer added is carried forward when this call's own next
+ * re-read happens to show it, and lost when a still staler one does not.
+ * None of this reaches a *different* call's own first read either: run
+ * provisioning calls one at a time, and when more than one adapter or
+ * process shares a bucket, re-run each after a few minutes once every one of
+ * them has run.
  */
-export declare function ensureLifecycleRule(client: S3Client, target: LifecycleTarget, logger: Logger): Promise<void>;
+export declare function ensureLifecycleRule(client: S3Client, target: LifecycleTarget, logger: Logger, pace?: LifecyclePace): Promise<void>;
 /** The rule to build: its id, its prefix, and the days after which current versions expire. */
 interface RuleTarget {
     readonly id: string;

package/dist/cjs/shared/codec/s3/lifecycle.js

@@ -0,0 +1,223 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIFECYCLE_SETTLE_WRITES = exports.S3_RELEASE_GRACE_DAYS = void 0;
+exports.ensureLifecycleRule = ensureLifecycleRule;
+exports.ttlRule = ttlRule;
+exports.markerRule = markerRule;
+exports.assertNoIdCollision = assertNoIdCollision;
+exports.alreadyCorrect = alreadyCorrect;
+exports.reportBucketVersioning = reportBucketVersioning;
+const retry_js_1 = require("../../dynamodb/retry.js");
+const base_error_js_1 = require("../../errors/base-error.js");
+const classify_js_1 = require("../../errors/classify.js");
+const error_code_js_1 = require("../../errors/error-code.js");
+const errors_js_1 = require("../../errors/errors.js");
+const truncate_js_1 = require("../../logging/truncate.js");
+const client_js_1 = require("./client.js");
+const config_js_1 = require("./config.js");
+exports.S3_RELEASE_GRACE_DAYS = 1;
+async function readState(client, bucket) {
+    const { GetBucketLifecycleConfigurationCommand } = await (0, client_js_1.loadS3Sdk)();
+    try {
+        const existing = await client.send(new GetBucketLifecycleConfigurationCommand({ Bucket: bucket }));
+        return {
+            rules: existing.Rules ?? [],
+            transitionDefaultMinimumObjectSize: existing.TransitionDefaultMinimumObjectSize,
+        };
+    }
+    catch (error) {
+        if ((0, classify_js_1.isMissingLifecycleConfiguration)(error))
+            return { rules: [] };
+        throw error;
+    }
+}
+function upsert(rules, rule) {
+    return rules.some((held) => held.ID === rule.ID)
+        ? rules.map((held) => (held.ID === rule.ID ? rule : held))
+        : [...rules, rule];
+}
+async function putRules(client, bucket, state, rules) {
+    const { PutBucketLifecycleConfigurationCommand } = await (0, client_js_1.loadS3Sdk)();
+    await client.send(new PutBucketLifecycleConfigurationCommand({
+        Bucket: bucket,
+        LifecycleConfiguration: { Rules: rules },
+        ...(state.transitionDefaultMinimumObjectSize === undefined
+            ? {}
+            : { TransitionDefaultMinimumObjectSize: state.transitionDefaultMinimumObjectSize }),
+    }));
+}
+exports.LIFECYCLE_SETTLE_WRITES = 5;
+const LIFECYCLE_SETTLE_BASE_MS = 1_000;
+function planRules(state, target, ids) {
+    const heldTtl = state.rules.find((rule) => rule.ID === ids.ttl);
+    const heldMarker = state.rules.find((rule) => rule.ID === ids.marker);
+    assertNoIdCollision(heldTtl, target.prefix, ids.ttl);
+    assertNoIdCollision(heldMarker, target.prefix, ids.marker);
+    const expiry = ttlRule({ id: ids.ttl, prefix: target.prefix, days: target.days }, state.rules, heldTtl);
+    const reclaim = markerRule(ids.marker, target.prefix, heldMarker);
+    return {
+        settled: alreadyCorrect(heldTtl, expiry) && alreadyCorrect(heldMarker, reclaim),
+        rules: upsert(upsert(state.rules, expiry), reclaim),
+    };
+}
+function delayForAttempt(attempt) {
+    return LIFECYCLE_SETTLE_BASE_MS * 2 ** (attempt - 1);
+}
+function ruleFingerprint(rule) {
+    return JSON.stringify([
+        rule.ID,
+        rule.Status,
+        scopeOf(rule),
+        rule.Expiration?.Days,
+        rule.Expiration?.ExpiredObjectDeleteMarker,
+        rule.Expiration?.Date,
+        rule.NoncurrentVersionExpiration?.NoncurrentDays,
+    ]);
+}
+function sameRuleSet(a, b) {
+    const fingerprint = (rules) => rules.map(ruleFingerprint).sort().join('\n');
+    return fingerprint(a) === fingerprint(b);
+}
+function lifecycleContention(target) {
+    return new base_error_js_1.DynamoDBLangGraphError(`the lifecycle configuration of bucket ${(0, truncate_js_1.truncateForLog)(target.bucket)} kept losing the ` +
+        `rules for ${(0, truncate_js_1.truncateForLog)(target.prefix)} to a different configuration: every one of ` +
+        `the ${exports.LIFECYCLE_SETTLE_WRITES} rounds this call polls needed a write, another writer ` +
+        'replacing it on every re-read; run ensureS3LifecycleRule again once that writer has ' +
+        'finished', error_code_js_1.ErrorCode.CONTENTION, {});
+}
+function warnLifecyclePending(target, logger) {
+    logger.warn('ensureS3LifecycleRule: wrote the lifecycle rules but a re-read did not show them within the ' +
+        'polling window; S3 documents that propagation can take a few minutes, so this is most ' +
+        'likely lag rather than a lost write — call ensureS3LifecycleRule() again later to confirm', { bucket: (0, truncate_js_1.truncateForLog)(target.bucket), prefix: (0, truncate_js_1.truncateForLog)(target.prefix) });
+}
+async function ensureLifecycleRule(client, target, logger, pace = {}) {
+    (0, config_js_1.assertScopedKeyPrefix)(target.prefix);
+    const ids = {
+        ttl: (0, config_js_1.buildLifecycleRuleId)(target.prefix),
+        marker: (0, config_js_1.buildMarkerRuleId)(target.prefix),
+    };
+    const wait = pace.wait ?? ((delayMs) => (0, retry_js_1.sleep)(delayMs));
+    let before = [];
+    let writes = 0;
+    let contended = false;
+    for (let attempt = 0;; attempt += 1) {
+        if (attempt > 0)
+            await wait(delayForAttempt(attempt));
+        const state = await readState(client, target.bucket);
+        const plan = planRules(state, target, ids);
+        if (plan.settled)
+            break;
+        const lastAttempt = attempt === exports.LIFECYCLE_SETTLE_WRITES - 1;
+        if (attempt > 0 && sameRuleSet(state.rules, before)) {
+            if (lastAttempt) {
+                warnLifecyclePending(target, logger);
+                break;
+            }
+            logger.debug('ensureS3LifecycleRule: a re-read still shows what was there before this write; ' +
+                'waiting for it to propagate', { attempt, waitedMs: delayForAttempt(attempt) });
+            continue;
+        }
+        if (attempt > 0) {
+            logger.debug('ensureS3LifecycleRule: a re-read shows a different configuration without these ' +
+                'rules; writing them again', { attempt, waitedMs: delayForAttempt(attempt) });
+        }
+        await putRules(client, target.bucket, state, plan.rules);
+        writes += 1;
+        before = state.rules;
+        if (lastAttempt) {
+            if (writes === exports.LIFECYCLE_SETTLE_WRITES)
+                contended = true;
+            else
+                warnLifecyclePending(target, logger);
+            break;
+        }
+    }
+    await reportBucketVersioning(client, target.bucket, logger);
+    if (contended)
+        throw lifecycleContention(target);
+}
+function scopeOf(rule) {
+    return rule.Filter?.Prefix ?? rule.Filter?.And?.Prefix ?? rule.Prefix;
+}
+function governs(rule, prefix) {
+    const scope = scopeOf(rule);
+    return rule.Status === 'Enabled' && (scope === undefined || prefix.startsWith(scope));
+}
+function noncurrentDays(rules, prefix, existing) {
+    const held = rules
+        .filter((rule) => governs(rule, prefix))
+        .map((rule) => rule.NoncurrentVersionExpiration?.NoncurrentDays ?? 0);
+    return Math.max(...held, existing?.NoncurrentVersionExpiration?.NoncurrentDays ?? 0, exports.S3_RELEASE_GRACE_DAYS);
+}
+function carried(existing) {
+    const kept = { ...existing };
+    delete kept.Prefix;
+    return kept;
+}
+function ttlRule(rule, rules, existing) {
+    return {
+        ...carried(existing),
+        ID: rule.id,
+        Filter: { Prefix: rule.prefix },
+        Status: 'Enabled',
+        Expiration: { Days: rule.days },
+        NoncurrentVersionExpiration: {
+            ...existing?.NoncurrentVersionExpiration,
+            NoncurrentDays: noncurrentDays(rules, rule.prefix, existing),
+        },
+    };
+}
+function markerRule(id, prefix, existing) {
+    return {
+        ...carried(existing),
+        ID: id,
+        Filter: { Prefix: prefix },
+        Status: 'Enabled',
+        Expiration: { ExpiredObjectDeleteMarker: true },
+    };
+}
+function assertNoIdCollision(rule, prefix, id) {
+    if (rule === undefined)
+        return;
+    const found = scopeOf(rule);
+    if (found === undefined || found === prefix)
+        return;
+    throw (0, errors_js_1.validationError)(`the S3 lifecycle rule id "${(0, truncate_js_1.truncateForLog)(id)}" is already used by the prefix ` +
+        `"${(0, truncate_js_1.truncateForLog)(found)}"; an id is the key ` +
+        'prefix with every non-alphanumeric character replaced by "-", and the marker rule appends ' +
+        '"-markers" to that, so "a/b/" takes the id of "a-b/" and "app/" takes the marker id of ' +
+        '"app-markers/" — choose an s3.keyPrefix that produces neither id of any other prefix on ' +
+        'this bucket', 's3.keyPrefix');
+}
+function managedShape(rule) {
+    return JSON.stringify([
+        rule?.Status,
+        rule?.Filter?.Prefix,
+        rule?.Expiration?.Days,
+        rule?.Expiration?.ExpiredObjectDeleteMarker,
+        rule?.NoncurrentVersionExpiration?.NoncurrentDays,
+    ]);
+}
+function alreadyCorrect(existing, desired) {
+    return managedShape(existing) === managedShape(desired);
+}
+async function reportBucketVersioning(client, bucket, logger) {
+    const { GetBucketVersioningCommand } = await (0, client_js_1.loadS3Sdk)();
+    const named = (0, truncate_js_1.truncateForLog)(bucket);
+    let status;
+    try {
+        status = (await client.send(new GetBucketVersioningCommand({ Bucket: bucket }))).Status;
+    }
+    catch (error) {
+        const reason = (0, truncate_js_1.truncateForLog)(error?.name ?? 'unknown');
+        logger.warn('ensureS3LifecycleRule: could not read the offload bucket versioning state, so whether a released payload is recoverable is unknown; the lifecycle rules were written, and the role needs s3:GetBucketVersioning', { bucket: named, reason });
+        return;
+    }
+    if (status === 'Enabled')
+        return;
+    if (status === undefined) {
+        logger.warn('ensureS3LifecycleRule: versioning is off on the offload bucket, so releasing a payload deletes it outright with no recovery window; enable bucket versioning to gain one', { bucket: named });
+        return;
+    }
+    logger.warn('ensureS3LifecycleRule: versioning is suspended on the offload bucket, so releasing a payload deletes it outright; re-enable versioning, and note that the payloads released while it was suspended are already gone', { bucket: named });
+}

package/dist/{shared → cjs/shared}/codec/s3/offloader.d.ts

@@ -9,9 +9,10 @@
  * never deletes outside the row's own path, and logs rather than throws.
  */
 import type { S3Client } from '@aws-sdk/client-s3';
-import { DynamoDBLangGraphError } from '../../errors/base-error';
-import { type Logger } from '../../logging/logger';
-import { S3OffloadConfig } from './config';
+import { type RetryAttemptInfo } from '../../dynamodb/retry.js';
+import { DynamoDBLangGraphError } from '../../errors/base-error.js';
+import { type Logger } from '../../logging/logger.js';
+import { S3OffloadConfig } from './config.js';
 /** Default payload size that triggers S3 offload (350 KB; 50 KB under the DDB 400 KB cap). */
 export declare const DEFAULT_S3_THRESHOLD_BYTES: number;
 /** Default S3 server-side encryption algorithm. */
@@ -41,9 +42,11 @@ export declare class S3Offloader {
     private readonly sseKmsKeyId?;
     private readonly maxDownloadBytes;
     private readonly config;
+    private readonly logger;
     /**
      * Accepts: `config` — already validated by the adapter that builds this, with
-     * its key prefix resolved to the adapter's own path.
+     * its key prefix resolved to the adapter's own path. `logger` — the
+     * adapter's, which each S3 transfer retry is reported to at `debug`.
      *
      * Returns: an offloader whose S3 client is built lazily, on the first
      * operation that needs one.
@@ -52,7 +55,7 @@ export declare class S3Offloader {
      * import is warmed so the failure surfaces, typed, on the first S3 operation
      * rather than on the first oversize payload days later.
      */
-    constructor(config: S3OffloadConfig);
+    constructor(config: S3OffloadConfig, logger?: Logger);
     private getClient;
     /**
      * Whether `data` is large enough to warrant S3 offload.
@@ -117,6 +120,12 @@ export declare class S3Offloader {
      * object belonging to another row.
      */
     assertOwnedKey(key: string, scope: readonly string[]): void;
+    /**
+     * The line one S3 transfer retry writes: the message a DynamoDB retry writes,
+     * so a count of retries by error name covers both, plus the transfer it was.
+     * The error is quoted by name only, bounded like every other quoted name.
+     */
+    private retryReporter;
     /**
      * Upload `data` under `key`, writing only while the key is free.
      *
@@ -129,8 +138,10 @@ export declare class S3Offloader {
      * attempt of this upload did (see `uploadObject`); the caller's obligation is
      * the same either way.
      *
-     * Throws: `S3_OFFLOAD_FAILED` carrying the key; `ABORTED` when the signal
-     * fires, which is the caller's own stop rather than a failed offload.
+     * Throws: `VALIDATION` naming `payload` for bytes over `maxDownloadBytes`,
+     * before any request; `S3_OFFLOAD_FAILED` carrying the key; `ABORTED` when
+     * the signal fires, which is the caller's own stop rather than a failed
+     * offload.
      */
     upload(key: string, data: Uint8Array, row: BacklinkRow, signal?: AbortSignal): Promise<string>;
     /**
@@ -170,11 +181,17 @@ export declare class S3Offloader {
      * reported rather than enforced.
      *
      * Returns: nothing. Rules that are already correct are left alone, so this
-     * is safe to call on every deploy.
+     * is safe to call on every deploy. When it writes the rules but cannot
+     * confirm within its polling window that a re-read shows them — S3
+     * documents that a lifecycle configuration can take minutes to propagate —
+     * it logs a `warn` and returns rather than throwing: the rules were
+     * written, and a later call can confirm them.
      *
      * Throws: `VALIDATION` naming `s3.keyPrefix` when a rule id this prefix
      * would take is already held by a different prefix; whatever reading or
-     * writing the bucket's lifecycle configuration throws.
+     * writing the bucket's lifecycle configuration throws; `CONTENTION` when
+     * every one of the five rounds this call polls needs a write — a competing
+     * writer replacing the configuration on every single re-read.
      */
     ensureLifecycleRule(ttlDays: number, logger: Logger): Promise<void>;
     /**
@@ -202,6 +219,8 @@ export interface UploadParams {
     metadata?: Record<string, string>;
     /** The caller's cancellation; absent, the upload cannot be interrupted. */
     signal?: AbortSignal;
+    /** Called before each retry's backoff, as `withRetry` calls it. */
+    onRetry?: (info: RetryAttemptInfo) => void;
 }
 /**
  * Upload `data` to S3 unless an object already exists under `key`, wrapping
@@ -229,7 +248,8 @@ export interface UploadParams {
  * carrying the key and the underlying error, after three attempts on a
  * transient failure. Its message quotes the SDK's, with credential shapes
  * redacted — a signing failure names the key it signed with, and this message
- * reaches `err.message` on a public error.
+ * reaches `err.message` on a public error. Its context carries the S3
+ * failure's `awsErrorName`, `httpStatusCode` and `requestId` when it was AWS's.
  *
  * Guarantees: a cancelled upload leaves at most the object it was writing, at
  * a key ending in this write's own object id, which no row names because the
@@ -250,19 +270,23 @@ export interface StoredObject {
  *
  * Accepts: `object.maxBytes` — the largest object this call will buffer.
  * `signal` — cancels the request, and with it a body already streaming.
+ * `onRetry` — called before each retry's backoff.
  *
  * Returns: the object's bytes.
  *
  * Throws: `ABORTED` when the signal fires, unwrapped; `S3_OFFLOAD_FAILED`
  * naming the key — for an object over `maxBytes`, for a response with no body,
  * and for any SDK failure that survives the retries. Its message quotes the
- * underlying one with credential shapes redacted; the SDK error is kept as
- * `cause`, so `NoSuchKey` stays distinguishable
- * ({@link isMissingObjectError}).
+ * underlying one with credential shapes redacted; the failure is kept as
+ * `cause` — the SDK error itself for a failure that was not retried, the
+ * `RETRY_EXHAUSTED` error wrapping it once the retry budget is spent — so
+ * `NoSuchKey` stays distinguishable ({@link isMissingObjectError}). Its context carries the S3 failure's
+ * `awsErrorName`, `httpStatusCode` and `requestId` when it was AWS's.
  *
  * Guarantees: an object over the cap is refused from its declared
- * `ContentLength` before the body is touched, and while streaming when the
- * length is absent, so a replaced or hostile object cannot exhaust memory.
+ * `ContentLength` before the body is touched, and that body is destroyed
+ * rather than left open, and while streaming when the length is absent, so a
+ * replaced or hostile object cannot exhaust memory.
  * Transient failures are retried by this package alone — the client is built
  * with `maxAttempts: 1`.
  *
@@ -274,7 +298,7 @@ export interface StoredObject {
  * leaves nothing behind at all — no local file, no partial object, and the
  * chunks already buffered are dropped with the call.
  */
-export declare function downloadObject(client: S3Client, object: StoredObject, signal?: AbortSignal): Promise<Uint8Array>;
+export declare function downloadObject(client: S3Client, object: StoredObject, signal?: AbortSignal, onRetry?: (info: RetryAttemptInfo) => void): Promise<Uint8Array>;
 /** The part of an S3 `GetObject` body this module relies on. */
 export interface S3Body {
     transformToByteArray(): Promise<Uint8Array>;
@@ -360,17 +384,6 @@ export interface BacklinkRow {
  * Throws: nothing.
  */
 export declare function backlinkMetadata(row: BacklinkRow): Record<string, string>;
-/**
- * The total UTF-8 bytes `metadata` costs against S3's 2 KB user-metadata cap.
- *
- * Accepts: any metadata map. Names and values both count, which is how S3
- * measures it.
- *
- * Returns: the byte total.
- *
- * Throws: nothing.
- */
-export declare function metadataBytes(metadata: Record<string, string>): number;
 /** What one release of orphaned objects needs. */
 export interface OrphanRelease {
     /** The keys to delete; an absent or empty one is skipped. */
@@ -397,8 +410,8 @@ export interface OrphanRelease {
  *
  * Returns: nothing.
  *
- * Throws: **nothing**, ever. This is the library's sole non-throwing path: a
- * cleanup failure must not mask the write failure that caused it. Every
+ * Throws: **nothing**, ever: a cleanup failure must not mask the write
+ * failure that caused it. Every
  * outcome that is not a clean delete is logged at `warn`, carrying counts and
  * the failing error's *name* — never its message, which can hold a credential
  * fragment. A `logger` that throws is one more thing this absorbs (see