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

package/dist/cjs/shared/codec/s3/config.d.ts

@@ -0,0 +1,260 @@
+/**
+ * Hides the S3 key layout: where a row's object lives, and which keys a row may touch.
+ *
+ * An offloaded object's key is the adapter's prefix, then the row's own
+ * identifiers each base64url-encoded, then the id of the write that produced
+ * it, so a key read back from a row can be checked against the path that row
+ * could have produced before anything is read or deleted. The configuration a
+ * caller passes, its checks, the default prefix per adapter and the lifecycle
+ * rule ids derived from a prefix are part of the same layout.
+ */
+import type { DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
+import { type S3ClientConfigLike } from './client-types.js';
+/** Default S3 key prefix for offloaded payloads. */
+export declare const DEFAULT_S3_KEY_PREFIX = "langgraph-checkpoints/";
+/** S3 cap on an object key, applied to the produced offload key. */
+export declare const MAX_S3_KEY_BYTES = 1024;
+/** Configuration for offloading large payloads to S3. */
+export interface S3OffloadConfig {
+    bucketName: string;
+    keyPrefix?: string;
+    /**
+     * Serialized payloads at or above this size are offloaded (default 350 KB).
+     * Only the payload counts: the store's inline vectors live on the same item
+     * and are not part of it. The store embeds one vector per text its
+     * `index.fields` extract — a wildcard path yields one per element — each up
+     * to about 10 bytes per dimension, so three texts at 1024 dims cost roughly
+     * 30 KB. A row that payload and those vectors would take past DynamoDB's
+     * 400 KB item limit is refused with `VALIDATION` naming `index`.
+     */
+    thresholdBytes?: number;
+    serverSideEncryption?: string;
+    sseKmsKeyId?: string;
+    /**
+     * Largest object this adapter will buffer from S3 (default 50 MiB). An
+     * offloaded payload larger than it is refused at the write, and a value
+     * below `thresholdBytes` is refused at construction, so an adapter never
+     * stores an object it could not read back.
+     */
+    maxDownloadBytes?: number;
+    /**
+     * S3 client configuration (an `S3ClientConfig`). `region` defaults to the
+     * adapter's DynamoDB region.
+     */
+    clientConfig?: S3ClientConfigLike;
+}
+/**
+ * One key part, base64url-encoded.
+ *
+ * Accepts: `part` — any string, including empty.
+ *
+ * Returns: base64url text, whose alphabet (`A-Z a-z 0-9 - _`) contains neither
+ * `/` nor `.`, so an encoded part can never be mistaken for a path separator
+ * or the `.bin` suffix.
+ *
+ * Throws: nothing.
+ */
+export declare function encodeKeyPart(part: string): string;
+/**
+ * Build a fully-qualified S3 key: `${prefix}${parts, each base64url-encoded,
+ * joined with '/'}/${objectId}.bin`.
+ *
+ * `parts` are the identity of the DynamoDB row that will point at the object,
+ * and they are encoded rather than rejected: a namespace element or key may
+ * contain '/' (only the DynamoDB '#' separator is forbidden at the validation
+ * layer), and base64url's output alphabet never contains '/', so two distinct
+ * `parts` arrays can never compose one key.
+ *
+ * `objectId` names the write that uploads the object and is appended as it
+ * is, not encoded, so it must be safe in an S3 key and hold no `/`, or its
+ * segments would read as parts. The ids this package passes are both: a UUID
+ * (hex digits and `-`) and a ULID (Crockford base-32 digits).
+ *
+ * Accepts: `prefix` — the offloader's, already validated and separator-
+ * terminated. `parts` — at least one; the identity of the row that will point
+ * at the object. `objectId` — the uploading write's id: key-safe, with no `/`.
+ *
+ * Returns: the key. Under one prefix, two distinct `(parts, objectId)` pairs
+ * never compose one key, and the same prefix, parts and id always compose the
+ * same one.
+ *
+ * Throws: `VALIDATION` naming `s3Key` for an empty `parts` — an object with
+ * no row above it is outside every row's scope and could never be read back —
+ * and for a key over the 1024-byte cap. The encoding grows every part by a
+ * third, so identifiers that each pass their own length rule can still compose
+ * a key S3 would reject with a raw error.
+ */
+export declare function buildS3Key(prefix: string, parts: readonly string[], objectId: string): string;
+/**
+ * Refuse a key prefix that does not scope what it is used for.
+ *
+ * Accepts: `keyPrefix` — must be a string, non-empty, not `/`, and end in `/`.
+ * The type is checked here, before any string method is called, so every
+ * caller gets it: a number or `null` escaped as a bare `TypeError` from
+ * `keyPrefix.endsWith`. Every segment before that final `/` must be a real
+ * name: not empty, not `.`, not `..`. The whole prefix must also be free of
+ * control characters and well-formed UTF-16, the rules identifiers already
+ * meet, since it is written into log lines and into a lifecycle rule's filter.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `s3.keyPrefix`. The shape rule is reported
+ * before the segment rule, so a prefix breaking both is named by its shape.
+ *
+ * Guarantees: the prefix scopes both the objects and the lifecycle rule built
+ * from it. An empty or root prefix would make that rule expire the whole
+ * bucket, and one without a trailing `/` (`app/langgraph`) would also match
+ * every sibling starting with the same characters (`app/langgraph-other/`).
+ * An accepted prefix also survives path normalisation unchanged, which is what
+ * the segment rule buys. An S3 key is a byte string rather than a path, so
+ * `a/../b/x.bin` and `b/x.bin` are two different objects — but the IAM
+ * object-key condition a deployment writes, the lifecycle rule's
+ * `Filter.Prefix`, the console and every tool that resolves a path before
+ * matching one disagree about which. A prefix holding `..`, `.` or an empty
+ * segment therefore writes objects outside the path the deployment granted and
+ * outside the path the lifecycle rule sweeps, which is the whole job of a
+ * prefix.
+ */
+export declare function assertScopedKeyPrefix(keyPrefix: string): void;
+/**
+ * The lifecycle rule id for `prefix`: `langgraph-ttl-` plus its slug.
+ *
+ * Accepts: `prefix` — any string; trailing slashes are trimmed, and every
+ * character outside `[A-Za-z0-9-]` becomes `-`.
+ *
+ * Returns: a deterministic id that does not change with the TTL, so raising or
+ * lowering the TTL updates one rule rather than adding another. A prefix with
+ * no usable characters yields `langgraph-ttl-default`.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: the slug is not injective — `a/b/` and `a-b/` produce one id —
+ * and `ensureLifecycleRule` refuses rather than take over a rule that a
+ * different prefix already holds.
+ */
+export declare function buildLifecycleRuleId(prefix: string): string;
+/**
+ * The id of the rule that reclaims this prefix's expired delete markers:
+ * {@link buildLifecycleRuleId}'s id with a suffix of its own.
+ *
+ * Accepts: `prefix` — as {@link buildLifecycleRuleId} takes it.
+ *
+ * Returns: a second deterministic id, distinct from the expiration rule's.
+ * S3 refuses `ExpiredObjectDeleteMarker` inside an `Expiration` that also
+ * carries `Days`, so the reclaim cannot be a field on that rule and needs an
+ * id to be found by.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: it is *less* injective than the first id rather than merely as
+ * injective. On top of the slug collisions that one already has,
+ * `buildMarkerRuleId('app/')` and `buildLifecycleRuleId('app-markers/')` are
+ * one id — a clash between two prefixes whose letters and digits differ, which
+ * the first id alone cannot produce. `ensureLifecycleRule` refuses to take
+ * over either id when a different prefix already holds it, and its refusal
+ * names the suffix so the remedy fits the case.
+ */
+export declare function buildMarkerRuleId(prefix: string): string;
+/**
+ * An adapter's default S3 key prefix.
+ *
+ * Accepts: `base` — the shared prefix, ending in `/`. `adapter` — the adapter's
+ * own segment.
+ *
+ * Returns: `base` + `adapter` + `/`, so three adapters sharing one bucket write
+ * under three paths and one adapter's lifecycle rule never sweeps another's
+ * objects.
+ *
+ * Throws: nothing.
+ */
+export declare function defaultAdapterKeyPrefix(base: string, adapter: string): string;
+/**
+ * The path every key built from `parts` shares.
+ *
+ * Accepts: `prefix` — the configured key prefix, ending in `/`. `parts` —
+ * the row's identifiers; `[]` yields the prefix alone.
+ *
+ * Returns: the prefix plus the encoded parts joined by `/`, carrying neither
+ * `.bin` nor a trailing `/`.
+ *
+ * Throws: nothing.
+ */
+export declare function s3KeyScope(prefix: string, parts: readonly string[]): string;
+/**
+ * Whether `key` lies inside the path `parts` produce.
+ *
+ * Accepts: `key` — a key read back from a row, or one this package built.
+ * `parts` — the row's leading identifiers; `[]` degrades to a prefix-only
+ * check.
+ *
+ * Returns: true when the key continues below the scope (`<scope>/…`, which is
+ * every key this release writes, since the write's object id is one segment
+ * deeper) or equals it (`<scope>.bin`, the key of a store item offloaded by a
+ * release that gave the key no per-write segment).
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: an identifier sharing a leading substring with another (`t` and
+ * `t1`) never matches its scope — the parts are base64url-encoded and joined
+ * by `/`, so the comparison is segment-wise, not textual.
+ */
+export declare function isKeyInScope(key: string, prefix: string, parts: readonly string[]): boolean;
+/**
+ * Refuse a row-sourced `s3Key` outside the path the row's own identifiers
+ * produce.
+ *
+ * Accepts: as {@link isKeyInScope}.
+ *
+ * Returns: nothing: `key` is kept under its declared type, and this checks it
+ * against the scope `prefix` and `parts` compose.
+ *
+ * Throws: `VALIDATION` naming `s3Key`, quoting the key and the path the
+ * row may reference, each bounded by {@link truncateForLog}: the key comes off
+ * the row and the path is composed from an `s3.keyPrefix` checked for shape
+ * and never for length, so neither is bounded by anything this package ran.
+ * The key stays named — a bounded prefix still says which object to go and
+ * look at. It reaches the caller on all three adapters, including
+ * `history.getMessages` under `onCorruptMessage: 'skip'`, because
+ * `isPermanentPayloadLoss` does **not** classify it — an out-of-scope key is
+ * not the same kind of thing as an unreadable descriptor. An unreadable
+ * descriptor condemns the payload itself: nobody can read those bytes, so
+ * skipping the row loses nothing that was ever retrievable. An out-of-scope
+ * key says only that *this* reader may not follow it — the object is very
+ * likely intact, under the prefix that does own it — and what produced it is a
+ * `keyPrefix` pointed at the wrong place, a table shared with another tenant,
+ * or a planted row. Every one of those is a condition an operator must see and
+ * can fix. Classifying it as loss made only `history` answer with a silently
+ * shorter conversation — the one adapter that consults the classifier — which
+ * the chain then re-persisted as the truth, while the store and the saver
+ * raised on the same row. A short answer is the one failure a caller cannot
+ * detect, and one row shape must not mean two things across three adapters.
+ *
+ * Guarantees: a row is trusted for its shape, never for the object it points
+ * at. A writer able to place one row in a partition cannot make this library
+ * download or delete another tenant's object, nor make it quietly return less.
+ */
+export declare function assertKeyInScope(key: string, prefix: string, parts: readonly string[]): void;
+/** The adapters that share one bucket, each under its own default key prefix. */
+export type AdapterName = 'checkpointer' | 'store' | 'history';
+/**
+ * An adapter's `s3` option resolved into the offloader's configuration.
+ *
+ * Accepts: `s3` — as the caller gave it. `adapter` — names the default key
+ * prefix, so three adapters sharing one bucket do not share a path.
+ * `clientConfig` — the adapter's DynamoDB client config, read for its region
+ * only.
+ *
+ * Returns: `s3` with `keyPrefix` defaulted to the adapter's own path, and
+ * `clientConfig.region` filled in from the DynamoDB side when the S3 config
+ * names none. With no region on either side the field is left absent and the
+ * SDK resolves it from the environment.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: a bucket reachable only through the region the DynamoDB side was
+ * configured with is addressed in that region. The S3 SDK does not follow
+ * region redirects, so such a bucket otherwise failed with an opaque
+ * `PermanentRedirect` on the first offload.
+ */
+export declare function offloaderConfigFor(s3: S3OffloadConfig, adapter: AdapterName, clientConfig?: DynamoDBClientConfig): S3OffloadConfig;

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

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_S3_KEY_BYTES = exports.DEFAULT_S3_KEY_PREFIX = void 0;
+exports.encodeKeyPart = encodeKeyPart;
+exports.buildS3Key = buildS3Key;
+exports.assertScopedKeyPrefix = assertScopedKeyPrefix;
+exports.buildLifecycleRuleId = buildLifecycleRuleId;
+exports.buildMarkerRuleId = buildMarkerRuleId;
+exports.defaultAdapterKeyPrefix = defaultAdapterKeyPrefix;
+exports.s3KeyScope = s3KeyScope;
+exports.isKeyInScope = isKeyInScope;
+exports.assertKeyInScope = assertKeyInScope;
+exports.offloaderConfigFor = offloaderConfigFor;
+const errors_js_1 = require("../../errors/errors.js");
+const truncate_js_1 = require("../../logging/truncate.js");
+const primitives_js_1 = require("../../validation/primitives.js");
+const client_types_js_1 = require("./client-types.js");
+exports.DEFAULT_S3_KEY_PREFIX = 'langgraph-checkpoints/';
+exports.MAX_S3_KEY_BYTES = 1024;
+function encodeKeyPart(part) {
+    return Buffer.from(part, 'utf8').toString('base64url');
+}
+function buildS3Key(prefix, parts, objectId) {
+    if (parts.length === 0) {
+        throw (0, errors_js_1.validationError)('an offloaded object needs the identity of the row that points at it; parts was empty', 's3Key');
+    }
+    const encoded = [...parts.map(encodeKeyPart), objectId];
+    const key = `${prefix}${encoded.join('/')}.bin`;
+    const bytes = Buffer.byteLength(key, 'utf8');
+    if (bytes > exports.MAX_S3_KEY_BYTES) {
+        throw (0, errors_js_1.validationError)(`the offloaded S3 object key would be ${bytes} bytes; S3 caps keys at ` +
+            `${exports.MAX_S3_KEY_BYTES} — shorten the identifiers or the keyPrefix`, 's3Key');
+    }
+    return key;
+}
+const UNSCOPED_SEGMENTS = new Set(['', '.', '..']);
+function assertScopedKeyPrefix(keyPrefix) {
+    if (typeof keyPrefix !== 'string' ||
+        keyPrefix === '' ||
+        keyPrefix === '/' ||
+        !keyPrefix.endsWith('/')) {
+        throw (0, errors_js_1.validationError)('s3.keyPrefix must be a non-empty path that ends with "/" (for example "langgraph/"): ' +
+            'it scopes both the offloaded objects and the S3 lifecycle rule', 's3.keyPrefix');
+    }
+    (0, primitives_js_1.assertNoControlChars)(keyPrefix, 's3.keyPrefix');
+    (0, primitives_js_1.assertWellFormed)(keyPrefix, 's3.keyPrefix');
+    if (keyPrefix
+        .slice(0, -1)
+        .split('/')
+        .some((segment) => UNSCOPED_SEGMENTS.has(segment))) {
+        throw (0, errors_js_1.validationError)('s3.keyPrefix must name a real path: no empty, "." or ".." segment (for example ' +
+            '"langgraph/", not "../langgraph/" or "/langgraph/"). Such a prefix addresses object ' +
+            'keys outside the path the IAM policy grants and the lifecycle rule sweeps', 's3.keyPrefix');
+    }
+}
+function buildLifecycleRuleId(prefix) {
+    let trimmed = prefix;
+    while (trimmed.endsWith('/'))
+        trimmed = trimmed.slice(0, -1);
+    const slug = trimmed.replace(/[^a-zA-Z0-9-]/g, '-') || 'default';
+    return `langgraph-ttl-${slug}`;
+}
+function buildMarkerRuleId(prefix) {
+    return `${buildLifecycleRuleId(prefix)}-markers`;
+}
+function defaultAdapterKeyPrefix(base, adapter) {
+    return `${base}${adapter}/`;
+}
+function s3KeyScope(prefix, parts) {
+    return `${prefix}${parts.map(encodeKeyPart).join('/')}`;
+}
+function isKeyInScope(key, prefix, parts) {
+    const scope = s3KeyScope(prefix, parts);
+    if (parts.length === 0)
+        return key.startsWith(scope);
+    return key === `${scope}.bin` || key.startsWith(`${scope}/`);
+}
+function assertKeyInScope(key, prefix, parts) {
+    if (isKeyInScope(key, prefix, parts))
+        return;
+    throw (0, errors_js_1.validationError)(`s3Key "${(0, truncate_js_1.truncateForLog)(key)}" lies outside the S3 path this row may reference ` +
+        `("${(0, truncate_js_1.truncateForLog)(s3KeyScope(prefix, parts))}"); refusing to touch an object the row ` +
+        'does not own', 's3Key');
+}
+function offloaderConfigFor(s3, adapter, clientConfig) {
+    const region = (0, client_types_js_1.s3ClientOptions)(s3.clientConfig).region ?? clientConfig?.region;
+    return {
+        ...s3,
+        keyPrefix: s3.keyPrefix ?? defaultAdapterKeyPrefix(exports.DEFAULT_S3_KEY_PREFIX, adapter),
+        ...(region === undefined ? {} : { clientConfig: { ...s3.clientConfig, region } }),
+    };
+}

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

@@ -0,0 +1,220 @@
+/**
+ * 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 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.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
+ * 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;
+}
+/** 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
+ * 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. `pace.wait` — how to wait between re-reads; the
+ * default sleeps.
+ *
+ * Returns: nothing. Idempotent: when both rules already say this, no write is
+ * 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}); `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, 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;
+    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 {};