lambder 14.1.1 → 15.0.2

package/dist/stores/LambderDdbCache.js

@@ -2,12 +2,15 @@ import { createDynamoClientLoader, isConditionalCheckFailure } from "./LambderDd
 import { getCrypto } from "../shared/util/LambderNodeModules.js";
 import { LambderExpiringMap } from "../shared/util/LambderExpiringMap.js";
 import { assertPositiveInteger } from "../shared/util/LambderOptionChecks.js";
-import { compressText, restoreText, LambderCompressionError } from "../shared/wire/LambderCompressionCodec.js";
+import { LambderCompressionError } from "../shared/wire/LambderCompressionCodec.js";
 import { resolveCompressionOption, } from "../shared/wire/LambderCompressionOption.js";
 import { LRUCache } from "lru-cache";
 import { cacheMemoryKeyOf, decodeCacheSortKey, encodeCacheSortKey, normalizeCacheKey, normalizeCachePartition, } from "./LambderCacheKeys.js";
 import { DEFAULT_MAX_VALUE_BYTES, DEFAULT_TTL_SECONDS, resolveCacheTtlSeconds, resolveGetOrSetOptions, serializeCacheValue, } from "./LambderCacheValues.js";
 import { LambderCacheFiller } from "./LambderCacheFiller.js";
+import { restoreStoredText, storedTextOf } from "./LambderStoredText.js";
+import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
+import { delegateToTwin, registerSwappableInstance } from "../shared/util/LambderSwappableInstances.js";
 const DEFAULT_CHUNK_BYTES = 350 * 1024;
 const MAX_SAFE_CHUNK_BYTES = 380 * 1024;
 const DEFAULT_MEMORY_BYTES = 16 * 1024 * 1024;
@@ -155,6 +158,10 @@ class LocalWriteLedger {
         return Math.floor(this.now() / 1000) + RECENT_WRITE_SECONDS;
     }
 }
+/** Every LambderCache member, which the swap door hands to a memory twin. */
+const CACHE_MEMBERS = {
+    get: true, has: true, set: true, delete: true, deletePartition: true, listSortKeys: true, getOrSet: true,
+};
 /**
  * Persistent JSON cache backed by DynamoDB.
  *
@@ -235,6 +242,18 @@ export class LambderDdbCache {
         this.localWrites = new LocalWriteLedger(this.now);
         this.ready = createDynamoClientLoader({ user: "LambderDdbCache", region: options.region, client: options.client });
         this.filler = new LambderCacheFiller(`DynamoDB cache failed open in ${this.namespace}`);
+        registerSwappableInstance(this);
+    }
+    /**
+     * Puts a memory twin under this cache in place, for `lambder/testing`:
+     * every LambderCache member answers from the twin from then on. The twin
+     * is built with this cache's own default TTL, size limit and clock, so a
+     * test meets the rules this cache was configured with. Keyed by a symbol
+     * no entry point exports; see registerSwappableInstance.
+     */
+    [LAMBDER_BACKEND_SWAP](twins) {
+        const twin = twins.cache({ defaultTtlSeconds: this.defaultTtlSeconds, maxValueBytes: this.maxValueBytes, now: this.now });
+        delegateToTwin(this, twin, CACHE_MEMBERS);
     }
     async get(key) {
         return await this.getByAddress(normalizeCacheKey(key));
@@ -358,9 +377,7 @@ export class LambderDdbCache {
     async setByAddress(address, value, ttlSeconds, leaseOwner) {
         const { json, utf8 } = serializeCacheValue(value, this.maxValueBytes);
         const input = Buffer.from(utf8.buffer, utf8.byteOffset, utf8.byteLength);
-        const brotli = this.compression && input.length >= this.compression.minBytes ? this.compression : null;
-        const encoding = brotli ? "br" : "identity";
-        const stored = brotli ? await compressText(input, "br", brotli.quality) : input;
+        const { encoding, stored } = await storedTextOf(input, this.compression);
         if (stored.length > this.maxValueBytes) {
             throw new Error(`Stored cache value exceeds maxValueBytes (${stored.length} > ${this.maxValueBytes})`);
         }
@@ -881,9 +898,11 @@ export class LambderDdbCache {
             }
         }
     }
-    /** The JSON text of a stored payload. */
+    /** The JSON text of a stored payload, restored under maxValueBytes, the most this cache writes. */
     async decode(stored, encoding, uncompressedBytes) {
-        return encoding === "br" ? await restoreText(stored, "br", { declaredBytes: uncompressedBytes }) : stored.toString("utf8");
+        if (encoding === "identity")
+            return stored.toString("utf8");
+        return await restoreStoredText(stored, uncompressedBytes, { user: "LambderDdbCache", maxTextBytes: this.maxValueBytes });
     }
     remember(key, stored, encoding, uncompressedBytes, expiresAt) {
         if (!this.memory)

package/dist/stores/LambderDdbIdempotencyStore.d.ts

@@ -75,8 +75,9 @@ export declare class LambderDdbIdempotencyStore implements LambderIdempotencySto
     /**
      * A stored item's response body: plain (`body`) or Brotli (`bodyBr` +
      * `bodyBytes`). The stored length is the decompression budget, so it is
-     * checked here the way the headers are: a record declaring more than this
-     * store ever writes is unusable, not an invitation to allocate it.
+     * checked against the ceiling the way the headers are checked: a record
+     * declaring more than this store ever writes is unusable, not an
+     * invitation to allocate it.
      */
     private static readItemBody;
     /** A stored answer as the engine reads it, with every field of the record checked rather than cast. */
@@ -113,8 +114,9 @@ export declare class LambderDdbIdempotencyStore implements LambderIdempotencySto
      * compression off, stay plain. Returns:
      *
      * - "stored": the record is in place and will replay.
-     * - "too-large": even compressed, the body exceeds the item budget;
-     *   nothing was written and the caller should release the claim.
+     * - "too-large": the body is past the store's ceiling, or even
+     *   compressed it exceeds the item budget; nothing was written and the
+     *   caller should release the claim.
      * - "lost": the ownerToken no longer matches, i.e. the claim expired and
      *   a retry took the scope over; nothing was written.
      */

package/dist/stores/LambderDdbIdempotencyStore.js

@@ -1,6 +1,6 @@
-import { assertPartitionKeyFits, createDynamoClientLoader, isConditionalCheckFailure, } from "./LambderDdbSdk.js";
+import { assertPartitionKeyFits, createDynamoClientLoader, isConditionalCheckFailure, storedNumber, } from "./LambderDdbSdk.js";
+import { restoreStoredText, storedTextOf } from "./LambderStoredText.js";
 import { getCrypto } from "../shared/util/LambderNodeModules.js";
-import { compressText, restoreText } from "../shared/wire/LambderCompressionCodec.js";
 import { resolveCompressionOption, } from "../shared/wire/LambderCompressionOption.js";
 /** Bodies of 1KB or more are stored Brotli-compressed by default; smaller ones stay plain. */
 const COMPRESSION_DEFAULTS = { minBytes: 1024, quality: 5 };
@@ -11,15 +11,13 @@ const COMPRESSION_DEFAULTS = { minBytes: 1024, quality: 5 };
  */
 const MAX_STORED_BODY_BYTES = 350_000;
 /**
- * Ceiling on a stored body's declared length, the budget the restore
- * decompresses under. The store's own writes stay far inside it (a response
- * that reaches a client is a few megabytes at most, and the compressed bytes
- * must fit MAX_STORED_BODY_BYTES), so a record declaring more is not this
- * store's, and trusting it would let a few hundred kilobytes of Brotli expand
- * until the function dies. The cache bounds the same number against its
- * maxValueBytes.
+ * Ceiling on a stored body, in UTF-8 bytes: the most the store writes and the
+ * most it restores (see LambderStoredText). A response that reaches a client
+ * is a few megabytes at most, so a body past it answers "too-large", and a
+ * record declaring more is not this store's. The cache bounds the same
+ * number against its maxValueBytes.
  */
-const MAX_REPLAY_BODY_BYTES = 32 * 1024 * 1024;
+const BODY_CEILING = { user: "LambderDdbIdempotencyStore", maxTextBytes: 32 * 1024 * 1024 };
 /**
  * What an item that keeps no fingerprint reports: one no request matches,
  * since the engine's fingerprints are never empty. Such an item was not
@@ -29,16 +27,6 @@ const MAX_REPLAY_BODY_BYTES = 32 * 1024 * 1024;
  * free and running the request over it.
  */
 const UNKNOWN_REQUEST_FINGERPRINT = "";
-/**
- * A number attribute as stored, or the fallback when it is missing or not a
- * number. `Number(undefined)` and `Number("nope")` are both NaN, which every
- * later comparison answers false to: a NaN expiry reads as "not expired" and
- * a NaN status code reaches the client as one.
- */
-const storedNumber = (raw, fallback) => {
-    const value = Number(raw);
-    return Number.isFinite(value) ? value : fallback;
-};
 /** 16 random bytes, hex, through the optional-crypto seam so a bundler's browser stub cannot break the import. */
 const newOwnerToken = async () => {
     const crypto = await getCrypto();
@@ -138,18 +126,15 @@ export class LambderDdbIdempotencyStore {
     /**
      * A stored item's response body: plain (`body`) or Brotli (`bodyBr` +
      * `bodyBytes`). The stored length is the decompression budget, so it is
-     * checked here the way the headers are: a record declaring more than this
-     * store ever writes is unusable, not an invitation to allocate it.
+     * checked against the ceiling the way the headers are checked: a record
+     * declaring more than this store ever writes is unusable, not an
+     * invitation to allocate it.
      */
     static async readItemBody(item) {
         const compressed = item.bodyBr?.B;
         if (!compressed)
             return item.body?.S ?? "";
-        const declaredBytes = storedNumber(item.bodyBytes?.N, 0);
-        if (declaredBytes > MAX_REPLAY_BODY_BYTES) {
-            throw new Error(`LambderDdbIdempotencyStore: the stored body declares ${declaredBytes} bytes, over the ${MAX_REPLAY_BODY_BYTES}-byte replay limit, so the record is unusable.`);
-        }
-        return await restoreText(compressed, "br", { declaredBytes });
+        return await restoreStoredText(compressed, storedNumber(item.bodyBytes?.N, 0), BODY_CEILING);
     }
     /** A stored answer as the engine reads it, with every field of the record checked rather than cast. */
     static async answerOf(item) {
@@ -252,37 +237,32 @@ export class LambderDdbIdempotencyStore {
      * compression off, stay plain. Returns:
      *
      * - "stored": the record is in place and will replay.
-     * - "too-large": even compressed, the body exceeds the item budget;
-     *   nothing was written and the caller should release the claim.
+     * - "too-large": the body is past the store's ceiling, or even
+     *   compressed it exceeds the item budget; nothing was written and the
+     *   caller should release the claim.
      * - "lost": the ownerToken no longer matches, i.e. the claim expired and
      *   a retry took the scope over; nothing was written.
      */
     async complete(scopeKey, ownerToken, { statusCode, headers, body, fingerprint, ttlSeconds }) {
         const nowSeconds = this.nowSeconds();
         const rawBody = Buffer.from(body, "utf8");
-        let bodyAttributes;
-        // A zero-length body is never compressed, whatever minBytes says: it
-        // would be stored as `bodyBr` with `bodyBytes: 0`, and a declared
-        // length of zero is one the codec refuses on the way back, so the
-        // record would be unreadable for its whole TTL and every retry would
-        // execute again. The plain path stores it as the empty string, which
-        // reads back as one.
-        if (this.compression && rawBody.byteLength > 0 && rawBody.byteLength >= this.compression.minBytes) {
-            const compressed = await compressText(rawBody, "br", this.compression.quality);
-            if (compressed.byteLength > MAX_STORED_BODY_BYTES)
-                return "too-large";
-            // bodyBytes bounds and verifies decompression on read.
-            bodyAttributes = { bodyBr: { B: compressed }, bodyBytes: { N: String(rawBody.byteLength) } };
-        }
-        else {
-            // The budget is on what actually gets stored, so the plain path is
-            // measured too. Without this an oversized body reaches DynamoDB and
-            // comes back as a ValidationException, which is not a
-            // ConditionalCheckFailedException and so escapes as a store error.
-            if (rawBody.byteLength > MAX_STORED_BODY_BYTES)
-                return "too-large";
-            bodyAttributes = { body: { S: body } };
-        }
+        // Past the ceiling, the record would be one the store refuses to
+        // read back, however small its compressed bytes.
+        if (rawBody.byteLength > BODY_CEILING.maxTextBytes)
+            return "too-large";
+        const text = await storedTextOf(rawBody, this.compression);
+        // The budget is on what actually gets stored, plain or compressed.
+        // Without it an oversized body reaches DynamoDB and comes back as a
+        // ValidationException, which is not a ConditionalCheckFailedException
+        // and so escapes as a store error.
+        if (text.stored.byteLength > MAX_STORED_BODY_BYTES)
+            return "too-large";
+        // bodyBytes bounds and verifies decompression on read. The plain path
+        // stores the body as a string, an empty one included, which reads
+        // back as one.
+        const bodyAttributes = text.encoding === "br"
+            ? { bodyBr: { B: text.stored }, bodyBytes: { N: String(text.textBytes) } }
+            : { body: { S: body } };
         try {
             const { client, sdk } = await this.ready();
             await client.send(new sdk.PutItemCommand({

package/dist/stores/LambderDdbOneShotSecretStore.d.ts

@@ -1,5 +1,6 @@
 import type { DynamoDBClient } from "@aws-sdk/client-dynamodb";
 import type { LambderOneShotIssueOutcome, LambderOneShotSecretDraft, LambderOneShotSecretRecord, LambderOneShotSecretStore } from "../shared/contracts/LambderOneShotSecretStore.js";
+import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
 export interface LambderDdbOneShotSecretStoreOptions {
     tableName: string;
     /** Region the client is created for on first use; the SDK's default chain otherwise. */
@@ -44,6 +45,16 @@ export declare class LambderDdbOneShotSecretStore implements LambderOneShotSecre
     readonly keyPrefix: string;
     private readonly ready;
     constructor(options: LambderDdbOneShotSecretStoreOptions);
+    /**
+     * Puts a memory twin under this store in place, for `lambder/testing`:
+     * every LambderOneShotSecretStore member answers from the twin from then
+     * on, so the LambderOneShotSecrets built over this store issues and
+     * verifies in memory. Keyed by a symbol no entry point exports; see
+     * registerSwappableInstance.
+     */
+    [LAMBDER_BACKEND_SWAP](twins: {
+        oneShotSecretStore(): LambderOneShotSecretStore;
+    }): void;
     private scopeKey;
     private digestKey;
     /**

package/dist/stores/LambderDdbOneShotSecretStore.js

@@ -1,5 +1,7 @@
-import { assertPartitionKeyFits, createDynamoClientLoader, isConditionalCheckFailure, } from "./LambderDdbSdk.js";
+import { assertPartitionKeyFits, createDynamoClientLoader, isConditionalCheckFailure, storedNumber, } from "./LambderDdbSdk.js";
 import { randomSecret } from "../shared/util/LambderSignedClaims.js";
+import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
+import { delegateToTwin, registerSwappableInstance } from "../shared/util/LambderSwappableInstances.js";
 /**
  * Why each item of a cancelled transaction was refused, in the order the
  * items were sent, or null when the error is not a cancelled transaction.
@@ -46,10 +48,9 @@ const sendRetryingConflicts = async (write) => {
         }
     }
 };
-/** A number attribute as stored, or the fallback when it is missing or not a number, since NaN compares false to everything. */
-const storedNumber = (raw, fallback) => {
-    const value = Number(raw);
-    return Number.isFinite(value) ? value : fallback;
+/** Every LambderOneShotSecretStore member, which the swap door hands to a memory twin. */
+const ONE_SHOT_SECRET_STORE_MEMBERS = {
+    issue: true, findByScope: true, findByDigest: true, attempt: true, consume: true, retire: true,
 };
 /**
  * One-shot secrets in DynamoDB, under the store's prefix, so the table can be
@@ -92,6 +93,17 @@ export class LambderDdbOneShotSecretStore {
         this.tableName = options.tableName;
         this.keyPrefix = options.keyPrefix ?? "OTS";
         this.ready = createDynamoClientLoader({ user: "LambderDdbOneShotSecretStore", region: options.region, client: options.client });
+        registerSwappableInstance(this);
+    }
+    /**
+     * Puts a memory twin under this store in place, for `lambder/testing`:
+     * every LambderOneShotSecretStore member answers from the twin from then
+     * on, so the LambderOneShotSecrets built over this store issues and
+     * verifies in memory. Keyed by a symbol no entry point exports; see
+     * registerSwappableInstance.
+     */
+    [LAMBDER_BACKEND_SWAP](twins) {
+        delegateToTwin(this, twins.oneShotSecretStore(), ONE_SHOT_SECRET_STORE_MEMBERS);
     }
     scopeKey(scope) {
         return {

package/dist/stores/LambderDdbSdk.d.ts

@@ -1,24 +1,27 @@
 /**
  * The DynamoDB SDK, loaded on first use.
  *
- * `@aws-sdk/client-dynamodb` and `@aws-sdk/lib-dynamodb` are optional peer
- * dependencies: an app that uses no DynamoDB store should neither install
- * them nor pay for loading them, and a module-level import would cost every
- * cold start and make every bundled Lambder app reference both packages. So
- * the session manager and the stores import their types only and take the
+ * `@aws-sdk/client-dynamodb` is an optional peer dependency: an app that uses
+ * no DynamoDB store should neither install it nor pay for loading it, and a
+ * module-level import would cost every cold start and make every bundled
+ * Lambder app reference it. So the stores import its types only and take the
  * classes from here the first time they touch the table, as
- * LambderS3FileSource and LambderInvokeCaller do. One loader per package,
- * memoized for the container's life; a missing package fails that first call
- * with the install hint rather than failing the import of lambder itself.
+ * LambderS3FileSource and LambderInvokeCaller do. One loader, memoized for
+ * the container's life; a missing package fails that first call with the
+ * install hint rather than failing the import of lambder itself.
+ *
+ * Every store speaks the item-level API, attribute values and all, so they
+ * take one client type and need one package. The session store, the one
+ * whose items hold an app's JSON, converts it with marshallJsonValue and
+ * unmarshallJsonValue below, so no store needs `@aws-sdk/lib-dynamodb`.
  *
  * The facts about DynamoDB itself that every store must agree on live here
- * too: a conditional write's refusal is an answer rather than a failure, and
- * a partition key has a limit that keys built from caller data can pass.
+ * too: a conditional write's refusal is an answer rather than a failure, a
+ * partition key and an item each have a limit that caller data can pass, and
+ * a number attribute read back may be missing or not a number.
  */
-import type { DynamoDBClient } from "@aws-sdk/client-dynamodb";
-import type { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
+import type { AttributeValue, DynamoDBClient } from "@aws-sdk/client-dynamodb";
 type LambderDynamoClientSdk = typeof import("@aws-sdk/client-dynamodb");
-type LambderDynamoDocumentSdk = typeof import("@aws-sdk/lib-dynamodb");
 /** What every DynamoDB-backed store needs before it can touch its table: the SDK, and a client made with it. */
 export type LambderDynamoClientReady = {
     client: DynamoDBClient;
@@ -42,22 +45,6 @@ export declare const createDynamoClientLoader: (options: {
     region?: string;
     client?: DynamoDBClient;
 }) => (() => Promise<LambderDynamoClientReady>);
-/** What the session store needs before its first table call: the document SDK, and a document client made with it. */
-export type LambderDynamoDocumentClientReady = {
-    client: DynamoDBDocumentClient;
-    sdk: LambderDynamoDocumentSdk;
-};
-/**
- * The document-client twin of createDynamoClientLoader, for the one store
- * that speaks the document API. A supplied client is taken as is, and then
- * only `@aws-sdk/lib-dynamodb` is loaded: the item-level package is needed
- * only to construct a client of our own.
- */
-export declare const createDynamoDocumentClientLoader: (options: {
-    user: string;
-    region?: string;
-    client?: DynamoDBDocumentClient;
-}) => (() => Promise<LambderDynamoDocumentClientReady>);
 /**
  * Whether DynamoDB refused a write because its condition did not hold, which
  * is how every conditional write here reports the thing it was testing for: a
@@ -106,4 +93,47 @@ export declare const assertPartitionKeyFits: (options: {
     partitionKey: string;
     remedy: string;
 }) => string;
+/** DynamoDB's own limit on one item, its attribute names and values together: 400 KB. */
+export declare const MAX_ITEM_BYTES: number;
+/**
+ * The size DynamoDB counts for one attribute value against its item limit: a
+ * string's UTF-8 bytes, a binary's bytes, one byte for a boolean or null, a
+ * byte per two significant digits of a number and one more, and for a map
+ * or a list three bytes plus, per element, one byte, its name (a map's) and
+ * its value. These are the rules DynamoDB states for its item limit, so a
+ * store can refuse an item by its size before the table answers it with a
+ * ValidationException, which is not a ConditionalCheckFailedException and
+ * so escapes as a store error that names nothing the app can act on. The
+ * set types are sized nowhere because no store writes one.
+ */
+export declare const attributeValueBytes: (value: AttributeValue) => number;
+/**
+ * A JSON value as the attribute DynamoDB keeps it: a string as `S`, a number
+ * as `N` in its shortest round-trip text, a boolean as `BOOL`, null as
+ * `NULL`, an array as `L` and an object as `M`. This is what
+ * `@aws-sdk/lib-dynamodb`'s document client writes for the same value, so an
+ * item written either way reads back through unmarshallJsonValue.
+ *
+ * JSON only, as the name says: anything JSON.parse cannot hand back (an
+ * undefined, a non-finite number, a function, a Set, a class instance) is
+ * refused rather than guessed at. Map entries are built with
+ * Object.fromEntries so that a `__proto__` key, which JSON.parse keeps as an
+ * own key, stays an entry rather than setting the prototype of the map.
+ */
+export declare const marshallJsonValue: (value: unknown) => AttributeValue;
+/**
+ * The JSON value an attribute holds: the inverse of marshallJsonValue, and
+ * the reading of what the document client wrote for one. A number reads as
+ * the JS number its text names, as JSON.parse would read the same text. An
+ * attribute JSON has no form for (a binary, a set) throws: it was not
+ * written from JSON, so it is not this store's.
+ */
+export declare const unmarshallJsonValue: (attribute: AttributeValue) => unknown;
+/**
+ * A number attribute as stored, or the fallback when it is missing or not a
+ * number. `Number(undefined)` and `Number("nope")` are both NaN, which every
+ * later comparison answers false to: a NaN expiry reads as "not expired" and
+ * a NaN status code reaches the client as one.
+ */
+export declare const storedNumber: (raw: string | undefined, fallback: number) => number;
 export {};

package/dist/stores/LambderDdbSdk.js

@@ -1,33 +1,32 @@
 /**
  * The DynamoDB SDK, loaded on first use.
  *
- * `@aws-sdk/client-dynamodb` and `@aws-sdk/lib-dynamodb` are optional peer
- * dependencies: an app that uses no DynamoDB store should neither install
- * them nor pay for loading them, and a module-level import would cost every
- * cold start and make every bundled Lambder app reference both packages. So
- * the session manager and the stores import their types only and take the
+ * `@aws-sdk/client-dynamodb` is an optional peer dependency: an app that uses
+ * no DynamoDB store should neither install it nor pay for loading it, and a
+ * module-level import would cost every cold start and make every bundled
+ * Lambder app reference it. So the stores import its types only and take the
  * classes from here the first time they touch the table, as
- * LambderS3FileSource and LambderInvokeCaller do. One loader per package,
- * memoized for the container's life; a missing package fails that first call
- * with the install hint rather than failing the import of lambder itself.
+ * LambderS3FileSource and LambderInvokeCaller do. One loader, memoized for
+ * the container's life; a missing package fails that first call with the
+ * install hint rather than failing the import of lambder itself.
+ *
+ * Every store speaks the item-level API, attribute values and all, so they
+ * take one client type and need one package. The session store, the one
+ * whose items hold an app's JSON, converts it with marshallJsonValue and
+ * unmarshallJsonValue below, so no store needs `@aws-sdk/lib-dynamodb`.
  *
  * The facts about DynamoDB itself that every store must agree on live here
- * too: a conditional write's refusal is an answer rather than a failure, and
- * a partition key has a limit that keys built from caller data can pass.
+ * too: a conditional write's refusal is an answer rather than a failure, a
+ * partition key and an item each have a limit that caller data can pass, and
+ * a number attribute read back may be missing or not a number.
  */
 import { withInstallHint } from "./LambderSdkInstallHint.js";
 let clientSdk;
-let documentSdk;
-/** `@aws-sdk/client-dynamodb`, for the item-level API the stores speak and the client the session manager wraps. */
+/** `@aws-sdk/client-dynamodb`, for the item-level API every store speaks. */
 const loadDynamoClientSdk = (user) => {
     clientSdk ??= withInstallHint(import("@aws-sdk/client-dynamodb"), "@aws-sdk/client-dynamodb", user, () => { clientSdk = undefined; });
     return clientSdk;
 };
-/** `@aws-sdk/lib-dynamodb`, the document client the session manager reads and writes through. */
-const loadDynamoDocumentSdk = (user) => {
-    documentSdk ??= withInstallHint(import("@aws-sdk/lib-dynamodb"), "@aws-sdk/lib-dynamodb", user, () => { documentSdk = undefined; });
-    return documentSdk;
-};
 /**
  * The default clients, one per region ("" for the SDK's default chain),
  * shared by every store not given a client of its own. A client is a
@@ -37,7 +36,6 @@ const loadDynamoDocumentSdk = (user) => {
  * first request.
  */
 const defaultClients = new Map();
-const defaultDocumentClients = new Map();
 const defaultClientFor = (sdk, region) => {
     let client = defaultClients.get(region ?? "");
     if (!client) {
@@ -68,32 +66,6 @@ export const createDynamoClientLoader = (options) => {
         return readyPromise;
     };
 };
-/**
- * The document-client twin of createDynamoClientLoader, for the one store
- * that speaks the document API. A supplied client is taken as is, and then
- * only `@aws-sdk/lib-dynamodb` is loaded: the item-level package is needed
- * only to construct a client of our own.
- */
-export const createDynamoDocumentClientLoader = (options) => {
-    let readyPromise;
-    const build = async () => {
-        if (options.client)
-            return { sdk: await loadDynamoDocumentSdk(options.user), client: options.client };
-        const [clientSdk, sdk] = await Promise.all([loadDynamoClientSdk(options.user), loadDynamoDocumentSdk(options.user)]);
-        // Over the same shared client the item-level stores use, so the
-        // session store's calls go through that one connection pool too.
-        let client = defaultDocumentClients.get(options.region ?? "");
-        if (!client) {
-            client = sdk.DynamoDBDocumentClient.from(defaultClientFor(clientSdk, options.region));
-            defaultDocumentClients.set(options.region ?? "", client);
-        }
-        return { sdk, client };
-    };
-    return () => {
-        readyPromise ??= build().catch((error) => { readyPromise = undefined; throw error; });
-        return readyPromise;
-    };
-};
 /**
  * Whether DynamoDB refused a write because its condition did not hold, which
  * is how every conditional write here reports the thing it was testing for: a
@@ -152,3 +124,103 @@ export const assertPartitionKeyFits = (options) => {
     }
     return options.partitionKey;
 };
+/** DynamoDB's own limit on one item, its attribute names and values together: 400 KB. */
+export const MAX_ITEM_BYTES = 400 * 1024;
+/**
+ * The significant digits of a number attribute's text: what DynamoDB stores
+ * of it. Leading and trailing zeroes are not stored, nor are the sign, the
+ * point and an exponent.
+ */
+const significantDigits = (numberText) => Math.max(numberText.replace(/^[-+]/, "").split(/e/i)[0].replace(".", "").replace(/^0+/, "").replace(/0+$/, "").length, 1);
+/**
+ * The size DynamoDB counts for one attribute value against its item limit: a
+ * string's UTF-8 bytes, a binary's bytes, one byte for a boolean or null, a
+ * byte per two significant digits of a number and one more, and for a map
+ * or a list three bytes plus, per element, one byte, its name (a map's) and
+ * its value. These are the rules DynamoDB states for its item limit, so a
+ * store can refuse an item by its size before the table answers it with a
+ * ValidationException, which is not a ConditionalCheckFailedException and
+ * so escapes as a store error that names nothing the app can act on. The
+ * set types are sized nowhere because no store writes one.
+ */
+export const attributeValueBytes = (value) => {
+    if (value.S !== undefined)
+        return Buffer.byteLength(value.S, "utf8");
+    if (value.N !== undefined)
+        return Math.ceil(significantDigits(value.N) / 2) + 1;
+    if (value.B !== undefined)
+        return value.B.byteLength;
+    if (value.BOOL !== undefined || value.NULL !== undefined)
+        return 1;
+    if (value.L !== undefined)
+        return value.L.reduce((total, element) => total + 1 + attributeValueBytes(element), 3);
+    if (value.M !== undefined) {
+        return Object.entries(value.M).reduce((total, [name, element]) => total + 1 + Buffer.byteLength(name, "utf8") + attributeValueBytes(element), 3);
+    }
+    throw new Error(`attributeValueBytes cannot size an attribute of type ${Object.keys(value).join(", ") || "none"}`);
+};
+/**
+ * A JSON value as the attribute DynamoDB keeps it: a string as `S`, a number
+ * as `N` in its shortest round-trip text, a boolean as `BOOL`, null as
+ * `NULL`, an array as `L` and an object as `M`. This is what
+ * `@aws-sdk/lib-dynamodb`'s document client writes for the same value, so an
+ * item written either way reads back through unmarshallJsonValue.
+ *
+ * JSON only, as the name says: anything JSON.parse cannot hand back (an
+ * undefined, a non-finite number, a function, a Set, a class instance) is
+ * refused rather than guessed at. Map entries are built with
+ * Object.fromEntries so that a `__proto__` key, which JSON.parse keeps as an
+ * own key, stays an entry rather than setting the prototype of the map.
+ */
+export const marshallJsonValue = (value) => {
+    if (value === null)
+        return { NULL: true };
+    if (typeof value === "string")
+        return { S: value };
+    if (typeof value === "boolean")
+        return { BOOL: value };
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error(`marshallJsonValue cannot store the number ${value}: JSON has no such value.`);
+        return { N: String(value) };
+    }
+    if (Array.isArray(value))
+        return { L: value.map(marshallJsonValue) };
+    if (typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
+        return { M: Object.fromEntries(Object.entries(value).map(([name, element]) => [name, marshallJsonValue(element)])) };
+    }
+    throw new Error(`marshallJsonValue cannot store a value of type ${value === undefined ? "undefined" : typeof value}: it is not JSON.`);
+};
+/**
+ * The JSON value an attribute holds: the inverse of marshallJsonValue, and
+ * the reading of what the document client wrote for one. A number reads as
+ * the JS number its text names, as JSON.parse would read the same text. An
+ * attribute JSON has no form for (a binary, a set) throws: it was not
+ * written from JSON, so it is not this store's.
+ */
+export const unmarshallJsonValue = (attribute) => {
+    if (attribute.S !== undefined)
+        return attribute.S;
+    if (attribute.N !== undefined)
+        return Number(attribute.N);
+    if (attribute.BOOL !== undefined)
+        return attribute.BOOL;
+    if (attribute.NULL !== undefined)
+        return null;
+    if (attribute.L !== undefined)
+        return attribute.L.map(unmarshallJsonValue);
+    if (attribute.M !== undefined) {
+        return Object.fromEntries(Object.entries(attribute.M).map(([name, element]) => [name, unmarshallJsonValue(element)]));
+    }
+    throw new Error(`unmarshallJsonValue cannot read an attribute of type ${Object.keys(attribute).join(", ") || "none"} as JSON.`);
+};
+/**
+ * A number attribute as stored, or the fallback when it is missing or not a
+ * number. `Number(undefined)` and `Number("nope")` are both NaN, which every
+ * later comparison answers false to: a NaN expiry reads as "not expired" and
+ * a NaN status code reaches the client as one.
+ */
+export const storedNumber = (raw, fallback) => {
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : fallback;
+};