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

package/dist/shared/codec/json-serde.js

@@ -1,191 +0,0 @@
-"use strict";
-/**
- * Hides the JSON form: writing it, reading it, and recognising it.
- *
- * The default serde writes a value as JSON under the `json` type and reads
- * back only that type; the codec also asks, when a serde refuses stored bytes,
- * whether those bytes are still JSON at all, which tells a corrupt payload from
- * a serde that would not reconstruct it.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.JSON_SERDE = void 0;
-exports.bytesHoldDeclaredForm = bytesHoldDeclaredForm;
-const base_error_1 = require("../errors/base-error");
-const error_code_1 = require("../errors/error-code");
-const errors_1 = require("../errors/errors");
-const truncate_1 = require("../logging/truncate");
-/**
- * A plain JSON serializer implementing LangGraph's `SerializerProtocol`:
- * the default `serde` of `DynamoDBStore` and `DynamoDBChatMessageHistory`, and
- * the alternative a `DynamoDBSaver` can be given in place of LangGraph's
- * `JsonPlusSerializer`.
- *
- * It is exported so that choice is available. The checkpointer's default
- * revives a stored `{"lc": …}` record by instantiating the class the record
- * names, so the row selects which constructor runs on read; this serializer
- * runs `JSON.parse` and nothing else, and reconstructs no class at all.
- * Reading with it is the narrower trust boundary, and the price is stated
- * below: it stores the JSON projection of a value, not the value.
- *
- * `dumpsTyped` accepts any value `JSON.stringify` can represent and refuses the
- * rest. A value it cannot represent — `undefined`, a function, a symbol —
- * stringifies to `undefined` and would be stored as **zero bytes**, which reads
- * back as a parse error; a circular structure or a `BigInt` makes it throw. Both
- * are reported as `VALIDATION` naming `value`, at the write, rather than
- * as an unreadable row later — with the refusal attached as `cause` and never
- * quoted into the message, which for a circular structure names the caller's
- * own properties and classes.
- *
- * What it represents, it represents as JSON, which is lossy in ways nothing
- * records: a `Map` or `Set` stores as `{}`, an object key whose value is
- * `undefined` is dropped and an array element is stored as `null`, `NaN` and
- * `Infinity` store as `null`, `-0` as `0`, a `Uint8Array` as an index-keyed
- * object and a `Date` as an ISO string. The README's *Table schema* section
- * holds the whole table, against the checkpointer default column by column.
- *
- * `loadsTyped` reads only the `json` form it writes, and says
- * so before it looks at a byte. Any other declared form is a `VALIDATION` error
- * naming `serde`, because it says what *this* reader may rebuild and not that
- * the payload is damaged. Bytes of that form which do not parse are
- * `PAYLOAD_CORRUPT`, because they can never be read and the caller should
- * report rather than retry; a `data` that is not bytes at all is a
- * `VALIDATION` naming `data`, because that is the caller's mistake and
- * not a row's.
- *
- * Frozen for the reason {@link ErrorCode} is: one object, shared by every
- * adapter in the process that did not pass a `serde` of its own, and
- * reachable from the package root. An assignment to `dumpsTyped` by any one
- * consumer would silently change how every other one writes.
- */
-exports.JSON_SERDE = {
-    async dumpsTyped(value) {
-        let text;
-        try {
-            text = JSON.stringify(value);
-        }
-        catch (error) {
-            // The refusal travels as `cause`, never as text. V8 writes the path it
-            // walked into the message it throws for a circular structure, quoting
-            // the caller's own property names and constructor names — and this
-            // package does not compose a public `err.message` out of a caller's
-            // identifiers, which an application may print, log or return in a
-            // response. `redactedMessage` removes credential shapes, not names, so
-            // it never covered this. A caller who wants the path reads `cause`.
-            throw (0, errors_1.validationError)('value cannot be serialized as JSON — a circular structure, or a value JSON has no ' +
-                'encoding for such as a BigInt; the refusal itself is attached as `cause`', 'value', (0, base_error_1.toError)(error));
-        }
-        if (text === undefined) {
-            throw (0, errors_1.validationError)('value has no JSON representation (undefined, a function or a symbol), so it cannot be ' +
-                'stored; store null instead to record an absent value', 'value');
-        }
-        // `dumpsTyped` stays `async` because the two throws above must reach a
-        // caller as a rejection even when it is called without `await` (a bare
-        // `.catch()`), which a plain synchronous throw would not do. Returning
-        // `Promise.resolve(...)` here — rather than the bare tuple — is what
-        // satisfies `require-await`: the rule accepts a `return` of a thenable
-        // value in place of an explicit `await`, and needs no `await` to do it.
-        return Promise.resolve([JSON_SERDE_TYPE, new TextEncoder().encode(text)]);
-    },
-    async loadsTyped(type, data) {
-        // The declared form is honoured, and honoured first. Ignoring it left this
-        // serializer answering for forms it has no grammar for: a row stamped
-        // `bytes` by the checkpointer's default — what that serializer writes for a
-        // raw `Uint8Array` — parsed here as JSON and returned a *different value*
-        // whenever those bytes happened to be valid JSON, and returned this
-        // serializer's own `PAYLOAD_CORRUPT` when they were not. The second reading
-        // is the one that cost data: the codec passes an already-branded refusal
-        // through untouched, so `bytesHoldDeclaredForm` never ran, the row was
-        // filed as permanent loss, and history's default `onCorruptMessage: 'skip'`
-        // dropped the message. The same row read through the checkpointer's own
-        // default was reported as a refusal instead, so which serde an adapter
-        // carried decided whether a turn survived the read.
-        //
-        // A form this serializer cannot rebuild a value from is a statement about
-        // this reader, not about the payload, so it names `serde` — the same brand
-        // the codec puts on `JsonPlusSerializer`'s `Unknown serialization type`,
-        // which is what makes the two agree. The type is quoted from the row, so it
-        // is bounded, for the reason `truncateForLog` states.
-        if (type !== JSON_SERDE_TYPE) {
-            throw (0, errors_1.validationError)(`this serializer reads only the \`${JSON_SERDE_TYPE}\` form it writes, and this payload ` +
-                `declares ${(0, truncate_1.truncateForLog)(String(JSON.stringify(type)))}; read the row with the ` +
-                'serializer that wrote it, or rewrite the row', 'serde');
-        }
-        let text;
-        // The decode is inside a guard of its own because it fails for a different
-        // reason than the parse does, and names it separately. UTF-8 decoding is
-        // lenient — a malformed byte becomes U+FFFD rather than an error — so the
-        // only way `TextDecoder` refuses is a `data` that is not bytes at all,
-        // which is the caller's mistake and not a corrupt row. The codec always
-        // passes a `Uint8Array`; a direct caller passing anything else would
-        // otherwise get a bare `TypeError` from Node naming an argument called
-        // "list".
-        try {
-            text = typeof data === 'string' ? data : new TextDecoder().decode(data);
-        }
-        catch (error) {
-            throw (0, errors_1.validationError)('data must be the bytes or text this serializer wrote, as a Uint8Array or a string', 'data', error);
-        }
-        try {
-            // Same reasoning as `dumpsTyped`'s final return: see its comment.
-            return Promise.resolve(JSON.parse(text));
-        }
-        catch (error) {
-            throw new base_error_1.DynamoDBLangGraphError('the stored payload is not the JSON this serializer wrote, so it cannot be decoded', error_code_1.ErrorCode.PAYLOAD_CORRUPT, {}, error);
-        }
-    },
-};
-Object.freeze(exports.JSON_SERDE);
-/**
- * The one `serdeType` whose grammar this package can check for itself: the type
- * `JSON_SERDE` stamps on everything it writes, and the one LangGraph's
- * own `JsonPlusSerializer` stamps on every value but a raw `Uint8Array`, which
- * it stamps `bytes`.
- *
- * The one constant is shared by the serializer that writes this form and the
- * check that re-derives it, within this module. They had each decided
- * separately what they understood: the check took any other type at its
- * word, while `JSON_SERDE` ignored the declared type and ran `JSON.parse` on
- * whatever it was handed. A row declaring a form neither of them writes was
- * therefore classified one way through one serializer and the opposite way
- * through the other — and a row declaring `bytes`, which the checkpointer's
- * default writes for a raw `Uint8Array`, decoded to a *different value*
- * rather than failing at all when its bytes happened to parse as JSON.
- */
-const JSON_SERDE_TYPE = 'json';
-/**
- * Whether stored bytes are still the form the row that holds them declares.
- *
- * This is the structural question behind the two ways a decode fails —
- * `PAYLOAD_CORRUPT` for bytes no reader can decode, and the `serde` refusal for
- * bytes *this* reader will not rebuild a value from — and it is the only one
- * this package can answer on its own. `SerializerProtocol` offers no way to ask
- * a serde whether it parsed the bytes before deciding not to reconstruct what
- * they name, and the refusal it throws is a caller's object: its class, its
- * fields and its prose are all whatever that caller chose. Classifying a
- * payload by any of those would make the code mean "a third party said so",
- * which is exactly what neither code may mean.
- *
- * Accepts: `serdeType` — the type stamped on the row, as the descriptor carries
- * it. `bytes` — what the row stored, already decompressed.
- *
- * Returns: whether the bytes still parse as the declared form. A type this
- * package has no grammar for is taken at its word and answers `true`, so its
- * serde's refusal is reported rather than written off: dropping a payload this
- * reader merely cannot check would lose data on nothing but its own ignorance.
- *
- * Throws: **nothing**, for any bytes. It is called from inside the `catch` that
- * is classifying a decode failure, where a throw would replace the failure
- * being reported — and the value it is handed came off a row, so it may be
- * anything that row's writer stored.
- */
-function bytesHoldDeclaredForm(serdeType, bytes) {
-    if (serdeType !== JSON_SERDE_TYPE)
-        return true;
-    try {
-        JSON.parse(new TextDecoder().decode(bytes));
-        return true;
-    }
-    catch {
-        return false;
-    }
-}

package/dist/shared/codec/s3/client-types.js

@@ -1,26 +0,0 @@
-"use strict";
-/**
- * Hides the S3 SDK's own types from this package's declarations.
- *
- * The S3 client, its config and a command are described by the members this
- * package touches, so no shipped declaration imports the optional
- * `@aws-sdk/client-s3` peer and a caller without it installed still compiles
- * (record 1). A real `S3Client` or `S3ClientConfig` satisfies these shapes as
- * it is, so a caller who has the SDK passes its own values unchanged.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.s3ClientOptions = s3ClientOptions;
-/**
- * The options of a config, read through the structural type.
- *
- * Accepts: a config as the caller gave it, or nothing.
- *
- * Returns: the same object seen as {@link S3ClientOptions} so `region` and
- * `maxAttempts` can be read; an absent config reads as empty rather than
- * needing a guard at every call site.
- *
- * Throws: nothing.
- */
-function s3ClientOptions(config) {
-    return (config ?? {});
-}

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

@@ -1,97 +0,0 @@
-"use strict";
-/**
- * Hides that the S3 SDK is loaded on first use, and how its client is set up.
- *
- * An adapter without offload never imports the optional peer; the first
- * offload does, once, and a missing install surfaces as `VALIDATION` naming
- * the remedy (record 1). The client built here defaults to no retries of its
- * own — `maxAttempts: 1` — so this package's retry is the only layer unless a
- * caller's own `maxAttempts` overrides it (record 14), and its idle timer
- * bounds a stalled transfer without bounding a slow one.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadS3Sdk = loadS3Sdk;
-exports.createDefaultS3Client = createDefaultS3Client;
-const client_1 = require("../../dynamodb/client");
-const errors_1 = require("../../errors/errors");
-/** Codes Node and bundlers use for an import that cannot be resolved. */
-const MISSING_MODULE_CODES = ['ERR_MODULE_NOT_FOUND', 'MODULE_NOT_FOUND'];
-let sdkPromise;
-/**
- * Convert a failed import of the optional peer into a typed error that names
- * the remedy. Any other failure (a broken build, a syntax error inside the
- * package) passes through unchanged.
- */
-function wrapMissingPeer(error) {
-    const code = error.code;
-    if (code !== undefined && MISSING_MODULE_CODES.includes(code)) {
-        throw (0, errors_1.validationError)('S3 offload requires the optional peer @aws-sdk/client-s3 (npm install @aws-sdk/client-s3); ' +
-            'bundlers must keep it installed or external', 's3', error);
-    }
-    throw error;
-}
-/**
- * The optional `@aws-sdk/client-s3` peer, imported on first use.
- *
- * Accepts: nothing. Concurrent callers share one import.
- *
- * Returns: the module, cached for every later call.
- *
- * Throws: `VALIDATION` naming `s3` when the package is not installed,
- * carrying the install command; any other import failure — a broken build, a
- * syntax error inside the package — passes through unchanged. A failure is not
- * cached, so an install or a fixed bundle succeeds on a later call.
- */
-async function loadS3Sdk() {
-    if (!sdkPromise) {
-        sdkPromise = import('@aws-sdk/client-s3').catch((error) => {
-            sdkPromise = undefined;
-            return wrapMissingPeer(error);
-        });
-    }
-    return sdkPromise;
-}
-/**
- * An `S3Client` built from `config` with the lazily-loaded SDK.
- *
- * Accepts: `config` — any `S3ClientConfig`; an explicit `maxAttempts` or
- * `requestHandler` wins over the defaults below.
- *
- * Returns: the client. The caller owns it and destroys it.
- *
- * Throws: whatever {@link loadS3Sdk} throws.
- *
- * Guarantees: `maxAttempts` defaults to 1, so the SDK performs no retries of
- * its own and this library's retry, backoff and classification are the only
- * retry layer — the same default `resolveDynamoDBClient` applies on the
- * DynamoDB side. A default request handler bounds a transfer that has
- * stalled, which `maxAttempts` alone does not; a `requestHandler` in `config`
- * replaces it whole rather than merging with it.
- */
-async function createDefaultS3Client(config) {
-    const { S3Client: S3ClientCtor } = await loadS3Sdk();
-    // One field, where the DynamoDB client gets three, and the asymmetry is
-    // deliberate. `requestTimeout` bounds request creation until response
-    // *headers* arrive, and a `PutObject`'s headers arrive only once the whole
-    // body has been uploaded — so here it would be a bound on upload duration,
-    // over payloads running from the offload threshold to the download cap, and
-    // a legitimate large upload on a slow link would be destroyed for being
-    // slow. `socketTimeout` is an idle timer that any activity in either
-    // direction resets, so it separates a stalled transfer from a slow one.
-    // `throwOnRequestTimeout` is absent because without a request timeout it has
-    // nothing to act on, and `connectionTimeout` because its timer counts the
-    // wait behind the agent's sockets, which this path fans out across.
-    //
-    // What this bounds is a transfer stalled after its socket was assigned, not
-    // the whole attempt: nothing here bounds the time a request spends queued
-    // for a socket, and an idle timer is not a deadline, so a large upload's
-    // total duration stays unbounded. At or above 2 MiB the SDK sends
-    // `Expect: 100-continue` and the handler then waits six seconds for the
-    // continue on a throwaway agent, so the five-second idle timer is what
-    // fires first — the one place the two timers race.
-    return new S3ClientCtor({
-        maxAttempts: 1,
-        requestHandler: { socketTimeout: client_1.DEFAULT_SOCKET_TIMEOUT_MS },
-        ...config,
-    });
-}

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

@@ -1,355 +0,0 @@
-"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");
-/**
- * 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 {
-            rules: existing.Rules ?? [],
-            transitionDefaultMinimumObjectSize: existing.TransitionDefaultMinimumObjectSize,
-        };
-    }
-    catch (error) {
-        if ((0, classify_1.isMissingLifecycleConfiguration)(error))
-            return { rules: [] };
-        throw error;
-    }
-}
-/** `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 }),
-    }));
-}
-/**
- * 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, 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: { ExpiredObjectDeleteMarker: true },
-    };
-}
-/**
- * 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 });
-}