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

package/dist/shared/codec/s3/lifecycle.d.ts

@@ -1,8 +1,166 @@
-import type { S3Client } from '@aws-sdk/client-s3';
 /**
- * Idempotently ensure a `${ttlDays}`-day expiration lifecycle rule exists for
- * `prefix`. Reads existing rules, preserves user-defined ones, and only
- * adds/updates the library's prefix-scoped rule.
+ * 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.
  */
-export declare function ensureLifecycleRule(client: S3Client, bucket: string, prefix: string, ttlDays: number): Promise<void>;
-//# sourceMappingURL=lifecycle.d.ts.map
+import type { LifecycleRule, S3Client } from '@aws-sdk/client-s3';
+import type { Logger } from '../../logging/logger';
+/**
+ * Days a released payload's noncurrent version survives behind its delete
+ * marker before S3 reclaims it. One day is the smallest the lifecycle API
+ * accepts and it rounds up to the next UTC midnight, so the window is 24-48 h:
+ * long enough to restore a payload released in error, short enough that a
+ * versioned bucket does not pay for every release it has ever made. It is a
+ * floor and never a cap — a longer retention the bucket already carries is
+ * kept, because this package has no business shortening someone else's
+ * recovery window. Inert on an unversioned bucket, which has no noncurrent
+ * versions to expire.
+ */
+export declare const S3_RELEASE_GRACE_DAYS = 1;
+/** The rules to ensure: on which bucket, for which prefix, expiring after how many days. */
+export interface LifecycleTarget {
+    readonly bucket: string;
+    readonly prefix: string;
+    readonly days: number;
+}
+/**
+ * Ensure the two rules scoped to `target.prefix` exist on `target.bucket`: a
+ * `target.days`-day expiration for current versions, and the reclaim that
+ * removes the delete marker a released payload leaves behind.
+ *
+ * Accepts: `target.prefix` — re-checked for scoping here, because these rules
+ * are the one place an unscoped prefix would destroy data outside this
+ * library's. `target.days` — the current-version expiry only. Released
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export declare function ensureLifecycleRule(client: S3Client, target: LifecycleTarget, logger: Logger): Promise<void>;
+/** The rule to build: its id, its prefix, and the days after which current versions expire. */
+interface RuleTarget {
+    readonly id: string;
+    readonly prefix: string;
+    readonly days: number;
+}
+/**
+ * The rule that expires current versions on the TTL's schedule and released
+ * ones on the grace.
+ *
+ * Accepts: `rules` — everything the bucket holds, which is what the grace is
+ * measured against. `existing` — the rule this one replaces, if any.
+ *
+ * Returns: the rule to write. Every field of `existing` this package does not
+ * manage is carried through, because the rewrite a changed TTL triggers is
+ * otherwise unrecoverable: the next call reads the rewritten rule as already
+ * correct and never restores what it dropped.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: the `Expiration` is replaced rather than merged. Merging this
+ * package's `Days` into a `Date` an operator set would change the expiry they
+ * configured, whatever the service made of the pair.
+ */
+export declare function ttlRule(rule: RuleTarget, rules: readonly LifecycleRule[], existing?: LifecycleRule): LifecycleRule;
+/**
+ * The rule that reclaims the delete marker a release leaves, once its last
+ * noncurrent version has expired.
+ *
+ * Accepts: `existing` — the rule this one replaces, if any.
+ *
+ * Returns: the rule to write, a second one rather than a field on the TTL
+ * rule: S3 refuses `ExpiredObjectDeleteMarker` inside an `Expiration` that
+ * also carries `Days`, so each rule's `Expiration` holds its own half and
+ * nothing of the other's. Fields this package does not manage are carried
+ * through as they are on the TTL rule — this id is one this package invented,
+ * but that is no reason to drop what an operator has since put on it.
+ *
+ * Throws: nothing.
+ */
+export declare function markerRule(id: string, prefix: string, existing?: LifecycleRule): LifecycleRule;
+/**
+ * Refuse to touch a rule that carries one of this prefix's ids but scopes a
+ * different prefix. Three shapes reach here: slugging maps every
+ * non-alphanumeric character to `-`, so `app/langgraph/` and `app-langgraph/`
+ * produce one id; the marker rule appends `-markers`, so `app/`'s marker id is
+ * the expiration id of `app-markers/`; and a rule written in the older schema
+ * holds an id this package would take while naming its scope in the top-level
+ * `Prefix`.
+ *
+ * Accepts: `rule` — the rule holding `id`, or nothing. `prefix` — the one this
+ * call scopes rules to.
+ *
+ * Returns: nothing: `rule` is kept under its declared type, and this checks
+ * it. A rule naming no scope anywhere is taken over, and so is one already
+ * scoping this prefix — including in the older schema, which is then upgraded
+ * to a filter.
+ *
+ * Throws: `VALIDATION` naming `s3.keyPrefix`. The id and the scope are
+ * both bounded by {@link truncateForLog}: the scope is whatever the bucket's
+ * lifecycle configuration holds, and the id is composed from an
+ * `s3.keyPrefix` checked for shape and never for length.
+ *
+ * Guarantees: the scope is read wherever the rule names it, through the same
+ * {@link scopeOf} the floor uses. Reading only `Filter.Prefix` would let a
+ * rule in the older schema through, and the rewrite would then replace its
+ * scope with this one's — so the objects that rule governs would silently
+ * lose their expiration, and a bucket-wide rule would narrow to this prefix.
+ */
+export declare function assertNoIdCollision(rule: LifecycleRule | undefined, prefix: string, id: string): void;
+/**
+ * Whether the rule the bucket carries already says what would be written.
+ *
+ * Accepts: `existing` — the held rule, or nothing. `desired` — what a write
+ * would put there.
+ *
+ * Returns: whether a write can be skipped. A rule in the older schema never
+ * matches, because it names its prefix somewhere this does not read, so it is
+ * rewritten once into a filter and matches from then on.
+ *
+ * Throws: nothing.
+ */
+export declare function alreadyCorrect(existing: LifecycleRule | undefined, desired: LifecycleRule): boolean;
+/**
+ * Report whether `bucket` keeps versions, which is the whole of the recovery
+ * window behind a released payload.
+ *
+ * Accepts: `bucket` — the offload bucket. `logger` — the adapter's; silent by
+ * default, like every other event this package emits.
+ *
+ * Returns: nothing. A versioned bucket is silent; the other two states warn
+ * and name their own remedy, because those remedies differ — a bucket that
+ * never had versioning needs it enabled, while a suspended one needs it
+ * re-enabled *and* an accounting of what suspension has already destroyed.
+ *
+ * Throws: nothing, deliberately. A failure of the call itself is a `warn` too,
+ * including the `AccessDenied` of a role that provisioned lifecycle rules
+ * yesterday without this action: a permission the call did not need then must
+ * not break it now. This runs after the rules are written for the same reason
+ * — a bucket that cannot answer still gets them.
+ *
+ * Guarantees: a bucket that has never been versioned answers with an empty
+ * body, so the absent state is `Status === undefined`. It is never the string
+ * `'Disabled'`, which this API does not return, and testing for one would read
+ * an unversioned bucket as a versioned one.
+ */
+export declare function reportBucketVersioning(client: S3Client, bucket: string, logger: Logger): Promise<void>;
+export {};

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

@@ -1,47 +1,355 @@
 "use strict";
+/**
+ * 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.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
+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 classify_1 = require("../../errors/classify");
+const errors_1 = require("../../errors/errors");
+const truncate_1 = require("../../logging/truncate");
 const client_1 = require("./client");
 const config_1 = require("./config");
-async function readRules(client, bucket) {
+/**
+ * Days a released payload's noncurrent version survives behind its delete
+ * marker before S3 reclaims it. One day is the smallest the lifecycle API
+ * accepts and it rounds up to the next UTC midnight, so the window is 24-48 h:
+ * long enough to restore a payload released in error, short enough that a
+ * versioned bucket does not pay for every release it has ever made. It is a
+ * floor and never a cap — a longer retention the bucket already carries is
+ * kept, because this package has no business shortening someone else's
+ * recovery window. Inert on an unversioned bucket, which has no noncurrent
+ * versions to expire.
+ */
+exports.S3_RELEASE_GRACE_DAYS = 1;
+async function readState(client, bucket) {
     const { GetBucketLifecycleConfigurationCommand } = await (0, client_1.loadS3Sdk)();
     try {
         const existing = await client.send(new GetBucketLifecycleConfigurationCommand({ Bucket: bucket }));
-        return existing.Rules ?? [];
+        return {
+            rules: existing.Rules ?? [],
+            transitionDefaultMinimumObjectSize: existing.TransitionDefaultMinimumObjectSize,
+        };
     }
     catch (error) {
-        if (error.name === 'NoSuchLifecycleConfiguration')
-            return [];
+        if ((0, classify_1.isMissingLifecycleConfiguration)(error))
+            return { rules: [] };
         throw error;
     }
 }
-function alreadyCorrect(rule, ttlDays) {
-    return rule?.Status === 'Enabled' && rule.Expiration?.Days === ttlDays;
+/** `rules` with `rule` replacing the one holding its id, or appended when none does. */
+function upsert(rules, rule) {
+    return rules.some((held) => held.ID === rule.ID)
+        ? rules.map((held) => (held.ID === rule.ID ? rule : held))
+        : [...rules, rule];
+}
+/** Replace the bucket's whole configuration with `rules`, carrying its own field back. */
+async function putRules(client, bucket, state, rules) {
+    const { PutBucketLifecycleConfigurationCommand } = await (0, client_1.loadS3Sdk)();
+    await client.send(new PutBucketLifecycleConfigurationCommand({
+        Bucket: bucket,
+        LifecycleConfiguration: { Rules: rules },
+        ...(state.transitionDefaultMinimumObjectSize === undefined
+            ? {}
+            : { TransitionDefaultMinimumObjectSize: state.transitionDefaultMinimumObjectSize }),
+    }));
 }
 /**
- * Idempotently ensure a `${ttlDays}`-day expiration lifecycle rule exists for
- * `prefix`. Reads existing rules, preserves user-defined ones, and only
- * adds/updates the library's prefix-scoped rule.
+ * Ensure the two rules scoped to `target.prefix` exist on `target.bucket`: a
+ * `target.days`-day expiration for current versions, and the reclaim that
+ * removes the delete marker a released payload leaves behind.
+ *
+ * Accepts: `target.prefix` — re-checked for scoping here, because these rules
+ * are the one place an unscoped prefix would destroy data outside this
+ * library's. `target.days` — the current-version expiry only. Released
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
  */
-async function ensureLifecycleRule(client, bucket, prefix, ttlDays) {
-    const ruleId = (0, config_1.buildLifecycleRuleId)(prefix);
-    const rules = await readRules(client, bucket);
-    const existing = rules.find((rule) => rule.ID === ruleId);
-    if (alreadyCorrect(existing, ttlDays))
-        return;
-    const newRule = {
-        ID: ruleId,
+async function ensureLifecycleRule(client, target, logger) {
+    (0, config_1.assertScopedKeyPrefix)(target.prefix);
+    const ttlId = (0, config_1.buildLifecycleRuleId)(target.prefix);
+    const markerId = (0, config_1.buildMarkerRuleId)(target.prefix);
+    const state = await readState(client, target.bucket);
+    const heldTtl = state.rules.find((rule) => rule.ID === ttlId);
+    const heldMarker = state.rules.find((rule) => rule.ID === markerId);
+    assertNoIdCollision(heldTtl, target.prefix, ttlId);
+    assertNoIdCollision(heldMarker, target.prefix, markerId);
+    const expiry = ttlRule({ id: ttlId, prefix: target.prefix, days: target.days }, state.rules, heldTtl);
+    const reclaim = markerRule(markerId, target.prefix, heldMarker);
+    if (!alreadyCorrect(heldTtl, expiry) || !alreadyCorrect(heldMarker, reclaim)) {
+        await putRules(client, target.bucket, state, upsert(upsert(state.rules, expiry), reclaim));
+    }
+    await reportBucketVersioning(client, target.bucket, logger);
+}
+/**
+ * The prefix a rule governs, wherever it names one: in its filter, nested
+ * under the filter's `And` beside tags or size bounds, or in the top-level
+ * `Prefix` of a rule written before `Filter` existed. `undefined` means the
+ * rule names no prefix at all — it is bucket-wide, or filtered only by tags or
+ * object size — and a rule like that governs every key here.
+ */
+function scopeOf(rule) {
+    return rule.Filter?.Prefix ?? rule.Filter?.And?.Prefix ?? rule.Prefix;
+}
+/**
+ * Whether `rule` governs every key under `prefix`.
+ *
+ * Only an enabled rule does. A disabled one expires nothing, so it cannot
+ * shorten anyone's window and must not lengthen this package's either: an
+ * operator who disables their own retention rule to hand the job over would
+ * otherwise pin this package at that rule's value for good. A rule scoped
+ * beside this prefix governs none of its keys and one scoped beneath it only
+ * some, so neither of them speaks for all of them.
+ */
+function governs(rule, prefix) {
+    const scope = scopeOf(rule);
+    return rule.Status === 'Enabled' && (scope === undefined || prefix.startsWith(scope));
+}
+/**
+ * The noncurrent retention to write: the longest one already governing these
+ * keys, and never less than the release grace.
+ *
+ * S3 honours the **shorter** of two overlapping expirations, so a rule this
+ * package does not own decides how long a released payload really survives
+ * under its prefix. Writing the grace beside a bucket-wide 90-day retention
+ * would cut that window to a day for every key here, which is the opposite of
+ * what a floor is for.
+ *
+ * The rule being replaced counts whatever its status, unlike every other rule
+ * here: that value is this package's own committed floor rather than a
+ * constraint someone else placed on these keys, and `Status` has nothing to say
+ * about it. An operator who disables the rule to pause expiry during an
+ * incident would otherwise find the recovery window cut to the grace on the
+ * next deploy — a second way down from the ratchet, and a silent one.
+ *
+ * The rule this package writes is itself in the set, so the floor ratchets: a
+ * value written once outlives the rule that justified it, and the way back
+ * down is to delete this package's rule and let it be written afresh.
+ */
+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);
+}
+/**
+ * What a rewrite carries over from the rule it replaces: everything this
+ * package does not set itself, less the top-level `Prefix`.
+ *
+ * That `Prefix` is how a rule written before `Filter` existed names its scope,
+ * and the two are alternatives rather than a pair — S3 refuses a rule carrying
+ * both, which would fail the provisioning call this package documents as a
+ * deployment step. Such a rule is upgraded to a filter, never merged with one.
+ */
+function carried(existing) {
+    const kept = { ...existing };
+    delete kept.Prefix;
+    return kept;
+}
+/**
+ * The rule that expires current versions on the TTL's schedule and released
+ * ones on the grace.
+ *
+ * Accepts: `rules` — everything the bucket holds, which is what the grace is
+ * measured against. `existing` — the rule this one replaces, if any.
+ *
+ * Returns: the rule to write. Every field of `existing` this package does not
+ * manage is carried through, because the rewrite a changed TTL triggers is
+ * otherwise unrecoverable: the next call reads the rewritten rule as already
+ * correct and never restores what it dropped.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: the `Expiration` is replaced rather than merged. Merging this
+ * package's `Days` into a `Date` an operator set would change the expiry they
+ * configured, whatever the service made of the pair.
+ */
+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),
+        },
+    };
+}
+/**
+ * The rule that reclaims the delete marker a release leaves, once its last
+ * noncurrent version has expired.
+ *
+ * Accepts: `existing` — the rule this one replaces, if any.
+ *
+ * Returns: the rule to write, a second one rather than a field on the TTL
+ * rule: S3 refuses `ExpiredObjectDeleteMarker` inside an `Expiration` that
+ * also carries `Days`, so each rule's `Expiration` holds its own half and
+ * nothing of the other's. Fields this package does not manage are carried
+ * through as they are on the TTL rule — this id is one this package invented,
+ * but that is no reason to drop what an operator has since put on it.
+ *
+ * Throws: nothing.
+ */
+function markerRule(id, prefix, existing) {
+    return {
+        ...carried(existing),
+        ID: id,
         Filter: { Prefix: prefix },
         Status: 'Enabled',
-        Expiration: { Days: ttlDays },
+        Expiration: { ExpiredObjectDeleteMarker: true },
     };
-    const merged = existing
-        ? rules.map((rule) => (rule.ID === ruleId ? newRule : rule))
-        : [...rules, newRule];
-    const { PutBucketLifecycleConfigurationCommand } = await (0, client_1.loadS3Sdk)();
-    await client.send(new PutBucketLifecycleConfigurationCommand({
-        Bucket: bucket,
-        LifecycleConfiguration: { Rules: merged },
-    }));
 }
-//# sourceMappingURL=lifecycle.js.map
+/**
+ * Refuse to touch a rule that carries one of this prefix's ids but scopes a
+ * different prefix. Three shapes reach here: slugging maps every
+ * non-alphanumeric character to `-`, so `app/langgraph/` and `app-langgraph/`
+ * produce one id; the marker rule appends `-markers`, so `app/`'s marker id is
+ * the expiration id of `app-markers/`; and a rule written in the older schema
+ * holds an id this package would take while naming its scope in the top-level
+ * `Prefix`.
+ *
+ * Accepts: `rule` — the rule holding `id`, or nothing. `prefix` — the one this
+ * call scopes rules to.
+ *
+ * Returns: nothing: `rule` is kept under its declared type, and this checks
+ * it. A rule naming no scope anywhere is taken over, and so is one already
+ * scoping this prefix — including in the older schema, which is then upgraded
+ * to a filter.
+ *
+ * Throws: `VALIDATION` naming `s3.keyPrefix`. The id and the scope are
+ * both bounded by {@link truncateForLog}: the scope is whatever the bucket's
+ * lifecycle configuration holds, and the id is composed from an
+ * `s3.keyPrefix` checked for shape and never for length.
+ *
+ * Guarantees: the scope is read wherever the rule names it, through the same
+ * {@link scopeOf} the floor uses. Reading only `Filter.Prefix` would let a
+ * rule in the older schema through, and the rewrite would then replace its
+ * scope with this one's — so the objects that rule governs would silently
+ * lose their expiration, and a bucket-wide rule would narrow to this prefix.
+ */
+function assertNoIdCollision(rule, prefix, id) {
+    if (rule === undefined)
+        return;
+    const found = scopeOf(rule);
+    if (found === undefined || found === prefix)
+        return;
+    throw (0, errors_1.validationError)(`the S3 lifecycle rule id "${(0, truncate_1.truncateForLog)(id)}" is already used by the prefix ` +
+        `"${(0, truncate_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');
+}
+/**
+ * The fields this package manages on a rule, as one value two rules compare
+ * by. Comparing whole rules would issue a write on every call over a field S3
+ * reports and this package never sets.
+ */
+function managedShape(rule) {
+    return JSON.stringify([
+        rule?.Status,
+        rule?.Filter?.Prefix,
+        rule?.Expiration?.Days,
+        rule?.Expiration?.ExpiredObjectDeleteMarker,
+        rule?.NoncurrentVersionExpiration?.NoncurrentDays,
+    ]);
+}
+/**
+ * Whether the rule the bucket carries already says what would be written.
+ *
+ * Accepts: `existing` — the held rule, or nothing. `desired` — what a write
+ * would put there.
+ *
+ * Returns: whether a write can be skipped. A rule in the older schema never
+ * matches, because it names its prefix somewhere this does not read, so it is
+ * rewritten once into a filter and matches from then on.
+ *
+ * Throws: nothing.
+ */
+function alreadyCorrect(existing, desired) {
+    return managedShape(existing) === managedShape(desired);
+}
+/**
+ * Report whether `bucket` keeps versions, which is the whole of the recovery
+ * window behind a released payload.
+ *
+ * Accepts: `bucket` — the offload bucket. `logger` — the adapter's; silent by
+ * default, like every other event this package emits.
+ *
+ * Returns: nothing. A versioned bucket is silent; the other two states warn
+ * and name their own remedy, because those remedies differ — a bucket that
+ * never had versioning needs it enabled, while a suspended one needs it
+ * re-enabled *and* an accounting of what suspension has already destroyed.
+ *
+ * Throws: nothing, deliberately. A failure of the call itself is a `warn` too,
+ * including the `AccessDenied` of a role that provisioned lifecycle rules
+ * yesterday without this action: a permission the call did not need then must
+ * not break it now. This runs after the rules are written for the same reason
+ * — a bucket that cannot answer still gets them.
+ *
+ * Guarantees: a bucket that has never been versioned answers with an empty
+ * body, so the absent state is `Status === undefined`. It is never the string
+ * `'Disabled'`, which this API does not return, and testing for one would read
+ * an unversioned bucket as a versioned one.
+ */
+async function reportBucketVersioning(client, bucket, logger) {
+    const { GetBucketVersioningCommand } = await (0, client_1.loadS3Sdk)();
+    // `s3.bucketName` is checked for being a non-empty string and never for
+    // length, so it reaches these three lines as whatever the caller's options
+    // carried. It is quoted here as the identifier it is, cut at the log cap:
+    // the line's job is to say which bucket to go and look at, and the bucket
+    // holds the rest.
+    const named = (0, truncate_1.truncateForLog)(bucket);
+    let status;
+    try {
+        status = (await client.send(new GetBucketVersioningCommand({ Bucket: bucket }))).Status;
+    }
+    catch (error) {
+        // The error's name, never its message, which can carry credential text —
+        // and read off a shape rather than an Error, because a client seam can
+        // reject with anything at all and this function promises not to throw. Cut
+        // like the bucket beside it: a name is a string the SDK or a client seam
+        // produced, `message` is already bounded where `redactedMessage` relays
+        // it, and the two are one value.
+        const reason = (0, truncate_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 });
+}