lambder 7.2.5 → 8.0.2

package/dist/shared/LambderI18n.d.ts

@@ -106,17 +106,16 @@ export interface LambderI18nInstance<TLanguages extends Record<string, LambderLa
         [D in TDefault]: Partial<Record<keyof TContract, never>>;
     } & TExt): LambderI18nInstance<TLanguages, TDefault, TEnforced, TContract & TExt[TDefault]>;
     /**
-     * Run the loaders a language has in this instance and in every instance
-     * sharing its root, and resolve once their dictionaries are merged.
-     * Defaults to the active language; resolves at once when nothing is left
-     * to load. Until then `t` falls back per key to the default language, so
-     * await it before the first render, and before `setLanguage` to switch
-     * without a flash of the default language. Change listeners fire once
-     * per load, however many calls share it. A loader that answered never
-     * runs again; one that rejected rejects this call and runs again on the
-     * next. Creating an extension loads nothing: one created after its
-     * language was loaded awaits its own `loadLanguage()`, which runs only
-     * what is still missing.
+     * Run the loaders a language has in this instance and every instance
+     * sharing its root, resolving once their dictionaries are merged.
+     * Defaults to the active language. Until then `t` falls back per key to
+     * the default language, so await it before the first render, and before
+     * `setLanguage` to switch without a flash of the default language.
+     * Change listeners fire once per load, however many calls share it. A
+     * loader that answered never runs again; one that rejected rejects this
+     * call and is retried on the next. Creating an extension loads nothing:
+     * one created after its language was loaded needs its own
+     * `loadLanguage()`, which runs only what is still missing.
      */
     loadLanguage(code?: keyof TLanguages & string): Promise<void>;
     /** Merge additional translations at runtime (e.g. fetched from an API). Notifies change listeners. */

package/dist/shared/LambderI18n.js

@@ -9,9 +9,14 @@
 // ---------------------------------------------------------------------------
 // Implementation
 // ---------------------------------------------------------------------------
-/** Islamery-style browser detection: ordered prefs, full code then primary subtag. */
+/**
+ * Browser detection: ordered prefs, full code then primary subtag. Only in a
+ * page, where there is a document: Node 21 and later, Deno and Bun define
+ * `navigator.languages` too, from the process locale, and a server's locale
+ * is not its reader's.
+ */
 const detectBrowserLanguage = (isCode) => {
-    if (typeof navigator === "undefined")
+    if (typeof document === "undefined" || typeof navigator === "undefined")
         return null;
     const prefs = navigator.languages?.length ? navigator.languages : [navigator.language];
     for (const pref of prefs ?? []) {
@@ -30,33 +35,37 @@ class LanguageState {
     defaultLanguage;
     customDetect;
     override = null;
-    detected = null;
+    /** A throwing detector is reported once rather than on every t() call that runs it. */
+    detectorFailureReported = false;
     listeners = new Set();
     constructor(isCode, defaultLanguage, customDetect) {
         this.isCode = isCode;
         this.defaultLanguage = defaultLanguage;
         this.customDetect = customDetect;
     }
+    /**
+     * The active language: the one set, else detected afresh on every read.
+     * Detection is cheap, and what it reads lives outside this instance (the
+     * path an SPA navigates, the browser's languages), so remembering its
+     * first answer would keep a page on /en/ after it moved to /tr/.
+     */
     resolve() {
         if (this.override)
             return this.override;
-        if (this.detected)
-            return this.detected;
         // Fail-open: a broken app detector must not take down every t() call.
         let custom = null;
         try {
             custom = this.customDetect?.();
         }
         catch (err) {
-            console.error("LambderI18n: detectLanguage threw; continuing detection chain.", err);
+            if (!this.detectorFailureReported) {
+                this.detectorFailureReported = true;
+                console.error("LambderI18n: detectLanguage threw; continuing detection chain.", err);
+            }
         }
-        if (custom && this.isCode(custom)) {
-            this.detected = custom;
+        if (custom && this.isCode(custom))
             return custom;
-        }
-        const browser = detectBrowserLanguage(this.isCode);
-        this.detected = browser ?? this.defaultLanguage;
-        return this.detected;
+        return detectBrowserLanguage(this.isCode) ?? this.defaultLanguage;
     }
     set(code) {
         if (!this.isCode(code))
@@ -68,7 +77,6 @@ class LanguageState {
     }
     reset() {
         this.override = null;
-        this.detected = null;
         this.notify(this.resolve());
     }
     /** Re-notify listeners without a language change (e.g. dictionaries changed). */
@@ -91,14 +99,18 @@ class LanguageState {
         }
     }
 }
+/**
+ * Fills `{name}` tokens in one pass over the template, so a value is inserted
+ * as it is: a display name "Eve {org}" stays that, rather than having its own
+ * `{org}` filled by the next parameter. A token with no parameter stays.
+ * Own properties only, through Object.prototype.hasOwnProperty rather than
+ * Object.hasOwn: this runs in the browser bundle, and a browser without
+ * ES2022 (Safari before 15.4) would throw on the first parameterised text.
+ */
 const interpolate = (text, params) => {
     if (!params)
         return text;
-    let out = text;
-    for (const [token, value] of Object.entries(params)) {
-        out = out.split(`{${token}}`).join(String(value));
-    }
-    return out;
+    return text.replace(/\{([^{}]+)\}/g, (token, name) => Object.prototype.hasOwnProperty.call(params, name) ? String(params[name]) : token);
 };
 const layerLookup = (layer, lang, key) => {
     for (let node = layer; node; node = node.parent) {
@@ -151,9 +163,9 @@ const startLayerLoad = (core, layer, lang, loader) => {
     const load = Promise.resolve()
         .then(loader)
         .then((loaded) => {
-        // A loader that answered is spent even when its answer is refused:
-        // running it again would fetch the same file and fail the same
-        // way. Only a loader that rejected stays, to be retried.
+        // A loader that answered is spent even when its answer is refused,
+        // since running it again would fail the same way. Only a loader
+        // that rejected stays, to be retried.
         layer.loaders.delete(lang);
         if (layer.loaders.size === 0)
             core.lazyLayers.delete(layer);

package/dist/shared/contracts/LambderCache.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The cache vocabulary every cache in Lambder shares: how an entry is
+ * addressed, what writing and listing take, and the methods an app calls.
+ *
+ * Kept apart from LambderDdbCache for the reason the rate-limit and
+ * idempotency contracts are: an app that types its caches against this
+ * interface can hold a LambderMemoryCache in a test and a LambderDdbCache in
+ * production without the test's import graph ever reaching the DynamoDB
+ * store. Pure and dependency-free.
+ */
+/**
+ * Where a value lives. A plain string addresses one entry. `{ pk, sk }` puts
+ * the entry in a partition it can share with others, so a group can be
+ * listed or dropped in one call: `{ pk: "store:nyc-01", sk: "1700:1800" }`
+ * keeps every cached window of one store together.
+ */
+export type LambderCacheKey = string | {
+    pk: string;
+    sk: string;
+};
+export interface LambderCacheSetOptions {
+    /** How long the entry lives. Default: the cache's own defaultTtlSeconds. */
+    ttlSeconds?: number;
+}
+export interface LambderCacheListOptions {
+    /** Only sort keys starting with this prefix. */
+    prefix?: string;
+    /** Cap on RESULTS, not on entries read. */
+    limit?: number;
+}
+/**
+ * What an app asks of a cache. LambderDdbCache and LambderMemoryCache
+ * implement it with the same rules (the same key limits, the same JSON round
+ * trip, the same expiry), so code written against this interface behaves the
+ * same over either.
+ *
+ * Values are JSON: what `set` is handed is stored as its JSON text and `get`
+ * hands back a parse of it, never the object that was stored.
+ */
+export interface LambderCache {
+    /** The value, or undefined when it is absent or past its TTL. */
+    get<T>(key: LambderCacheKey): Promise<T | undefined>;
+    has(key: LambderCacheKey): Promise<boolean>;
+    /** Stores the value's JSON; throws for a value JSON cannot represent (undefined, a function). */
+    set<T>(key: LambderCacheKey, value: T, options?: LambderCacheSetOptions): Promise<void>;
+    /** True when there was a live entry to delete: a load in progress for the key, or an entry past its TTL, is none. */
+    delete(key: LambderCacheKey): Promise<boolean>;
+    /** Drops every entry stored under one `pk` and answers how many live ones there were. */
+    deletePartition(partition: string): Promise<number>;
+    /** The live sort keys stored under one `pk`, in sort-key order. Plain-string entries have none, so they never appear. */
+    listSortKeys(partition: string, options?: LambderCacheListOptions): Promise<string[]>;
+    /**
+     * The cached value, or the loader's once it has been stored, as the
+     * stored JSON either way, so the call that filled the entry answers what
+     * every later one does. Concurrent calls for one key in one process share
+     * a single load, each handed a parse of its own, so one caller's change to
+     * its answer never shows in another's. A loader's undefined is not cached
+     * (return null to cache "not found"), and a value the cache fails to store
+     * is handed back uncached, as the same JSON. So is the value of a load
+     * that a `set`, `delete` or `deletePartition` of the key overtook: the
+     * loader may have read its source before that write, so its value never
+     * lands over it. An invalid option throws before anything is read or
+     * loaded.
+     */
+    getOrSet<T>(key: LambderCacheKey, loader: () => Promise<T>, options?: LambderCacheSetOptions): Promise<T>;
+}

package/dist/shared/contracts/LambderCache.js

@@ -0,0 +1,11 @@
+/**
+ * The cache vocabulary every cache in Lambder shares: how an entry is
+ * addressed, what writing and listing take, and the methods an app calls.
+ *
+ * Kept apart from LambderDdbCache for the reason the rate-limit and
+ * idempotency contracts are: an app that types its caches against this
+ * interface can hold a LambderMemoryCache in a test and a LambderDdbCache in
+ * production without the test's import graph ever reaching the DynamoDB
+ * store. Pure and dependency-free.
+ */
+export {};

package/dist/shared/contracts/LambderFileSource.d.ts

@@ -5,12 +5,12 @@ export type LambderFile = {
 };
 /**
  * Where an app's files come from: the `files` option at creation, read by
- * servePublicFiles, serveIndexHtml, res.file and res.templateFile alike,
- * through the instance's one reader (LambderFiles). Implement `read` over
- * any backing store: LambderLocalFileSource (a folder), LambderS3FileSource
- * (S3, or R2 and other S3-compatible stores), LambderHttpFileSource (any
- * origin serving files by path), or your own. The reader does the rest for
- * every source: path rule, memory cache, mime fallback from the extension.
+ * servePublicFiles, serveIndexHtml, res.file and res.templateFile alike
+ * through the instance's one reader (LambderFiles), which adds the path rule,
+ * memory cache and mime fallback for every source. Implement `read` over any
+ * backing store, or use LambderLocalFileSource (a folder),
+ * LambderS3FileSource (S3, R2 and other S3-compatible stores) or
+ * LambderHttpFileSource (any origin serving files by path).
  */
 export interface LambderFileSource {
     /**

package/dist/shared/contracts/LambderFileSource.js

@@ -2,14 +2,11 @@
  * Where an app's files come from: the interface, and the one helper its
  * remote implementations share.
  *
- * Declared in shared/ beside LambderSessionStore, LambderRateLimiter and
- * LambderIdempotencyStore, so all four store families read the same way: the
- * interface here, the implementations in stores/ (LambderLocalFileSource,
- * LambderS3FileSource, LambderHttpFileSource). core/ names the interface and
- * nothing else of the family.
- *
- * What reads through a source is the instance's reader, LambderFiles: it owns
- * the path rule, the memory cache and the mime fallback.
+ * Laid out like the other store families (LambderSessionStore,
+ * LambderRateLimiter, LambderIdempotencyStore): the interface here, the
+ * implementations in stores/. core/ names only the interface. The instance's
+ * reader, LambderFiles, reads through a source and owns the path rule, the
+ * memory cache and the mime fallback.
  */
 /**
  * A file a remote store returned: the store's Content-Type unless it is a

package/dist/shared/contracts/LambderIdempotencyStore.d.ts

@@ -3,11 +3,10 @@
  * answer looks like, what claiming a scope reports, and the four methods the
  * idempotency engine asks of a store.
  *
- * Kept apart from the engine for the same reason LambderRateLimiter is:
- * a store implements this and nothing else, and importing it from the engine
- * would pull the engine (and through it the refusal machinery) into every
- * store's import graph. Pure and dependency-free, so the mock runtime and the
- * browser entry can resolve it.
+ * Kept apart from the engine, like LambderRateLimiter: a store implements this
+ * and nothing else, and importing it from the engine would pull the engine
+ * and its refusal machinery into every store's import graph. Dependency-free,
+ * so the mock runtime and the browser entry can resolve it.
  */
 /** A stored answer: what a completed record replays. */
 export type LambderIdempotencyDoneRecord = {
@@ -15,12 +14,22 @@ export type LambderIdempotencyDoneRecord = {
     /** Response headers stored with the record (normalized multi-value map). */
     headers: Record<string, string[]>;
     body: string;
+    /**
+     * The request the answer belongs to, as a digest of its payload: a key
+     * reused for a different request is refused rather than handed this
+     * answer. The engine's fingerprints are never empty, so a store that
+     * holds a record it cannot tie to a request (one another writer left in
+     * its table) reports the empty string, which matches no request and has
+     * the key refused as reused.
+     */
+    fingerprint: string;
 };
 export type LambderIdempotencyBeginResult = {
     state: "new";
     ownerToken: string;
 } | {
     state: "pending";
+    fingerprint: string;
 } | ({
     state: "done";
 } & LambderIdempotencyDoneRecord);
@@ -29,38 +38,58 @@ export type LambderIdempotencyBeginResult = {
  * atomically, settled by the claim's owner. LambderDdbIdempotencyStore and
  * LambderMemoryIdempotencyStore implement it; an app may bring its own.
  *
- * The rules an implementation has to keep are the ones tests/store-conformance
- * asserts against every implementation, and the three that are easy to get
- * wrong are worth naming here.
+ * tests/store-conformance asserts the rules against every implementation.
+ * Four are easy to get wrong:
  *
  * A read hands back a COPY of the record, never the stored object, because a
  * caller applies its own headers onto what it gets back.
  *
- * A write takes a copy too: complete() must not keep the caller's record or
- * its headers map, because that object goes on being used after the call
- * returns (the pipeline writes the call's own headers into it on the way
- * out). A store that retained it would let one request's Set-Cookie become
- * part of the stored answer and replay to everybody else. A store that goes
- * over the wire gets this for free, since serializing IS the copy; one that
- * keeps the record in the process has to make it.
+ * A write takes a copy too: the pipeline keeps writing the call's own headers
+ * into the record after complete() returns, so a store that retained it
+ * would let one request's Set-Cookie join the stored answer and replay to
+ * everybody else. A store that serializes over the wire copies for free; one
+ * that keeps the record in the process has to copy it.
  *
- * Size decides before ownership does, so an answer too big to store reports
+ * Size decides before ownership, so an answer too big to store reports
  * "too-large" even when the claim has meanwhile been lost. The engine
- * releases the claim either way, so the order only shows in which reason it
- * is told, but an implementation that inverted it would disagree with every
- * other one.
+ * releases the claim either way and only the reported reason differs, but an
+ * implementation with the order inverted would disagree with every other.
+ *
+ * abandon() releases a PENDING claim and nothing else: a stored record stays,
+ * even when the owner that stored it asks. The engine abandons after any
+ * complete() that throws, and one whose response was lost may have landed;
+ * deleting what it stored would run the operation again on the retry that
+ * should have replayed it.
  */
 export interface LambderIdempotencyStore {
     /** The stored answer when a completed, unexpired record exists, null otherwise (absent, pending, or expired). */
     peek(scopeKey: string): Promise<LambderIdempotencyDoneRecord | null>;
-    /** Claims the scope: "new" with the ownerToken to settle with, "pending" when another request owns it, "done" with the answer to replay. */
+    /**
+     * Claims the scope: "new" with the ownerToken to settle with, "pending"
+     * when another request owns it, "done" with the answer to replay. The
+     * claim keeps `fingerprint`, and "pending" and "done" report the one the
+     * scope holds, so the engine can tell a retry from a different request.
+     * A store that refuses the claim with no record to show for it (no room
+     * to hold one) reports the caller's own: the engine then answers the
+     * in-flight 409, which a client retries under the same key, rather than
+     * the key-reused one, which would move its key on.
+     */
     begin(scopeKey: string, options: {
         pendingTtlSeconds: number;
+        fingerprint: string;
     }): Promise<LambderIdempotencyBeginResult>;
-    /** Stores the answer over the claim: "stored", "too-large" (nothing written; release the claim), or "lost" (the claim expired and a retry took the scope). */
+    /**
+     * Stores the answer over the claim, with the fingerprint of the request
+     * it answers: "stored", "too-large" (nothing written; release the claim),
+     * or "lost" (the claim expired and a retry took the scope).
+     */
     complete(scopeKey: string, ownerToken: string, record: LambderIdempotencyDoneRecord & {
         ttlSeconds: number;
     }): Promise<"stored" | "too-large" | "lost">;
-    /** Releases the claim without storing; a lost claim makes this a silent no-op. */
+    /**
+     * Releases the owner's claim while it is still pending, so a retry can
+     * execute. A lost claim, or one already settled by complete(), makes
+     * this a silent no-op.
+     */
     abandon(scopeKey: string, ownerToken: string): Promise<void>;
 }

package/dist/shared/contracts/LambderIdempotencyStore.js

@@ -3,10 +3,9 @@
  * answer looks like, what claiming a scope reports, and the four methods the
  * idempotency engine asks of a store.
  *
- * Kept apart from the engine for the same reason LambderRateLimiter is:
- * a store implements this and nothing else, and importing it from the engine
- * would pull the engine (and through it the refusal machinery) into every
- * store's import graph. Pure and dependency-free, so the mock runtime and the
- * browser entry can resolve it.
+ * Kept apart from the engine, like LambderRateLimiter: a store implements this
+ * and nothing else, and importing it from the engine would pull the engine
+ * and its refusal machinery into every store's import graph. Dependency-free,
+ * so the mock runtime and the browser entry can resolve it.
  */
 export {};

package/dist/shared/contracts/LambderRateLimiter.d.ts

@@ -3,11 +3,10 @@
  * policy may cap, the policy shape, what an exceeded check reports, and the
  * one method the rate-limit engine asks of a limiter.
  *
- * Kept apart from the DynamoDB limiter on purpose. The engine needs only this
- * table, and importing it from the store would pull the DynamoDB SDK loader
- * into the engine's import graph, which is what kept the policy layer from
- * running anywhere but inside a Lambda. Pure and dependency-free, so the
- * mock runtime and the browser entry can resolve it.
+ * Kept apart from the DynamoDB limiter on purpose: importing it from the
+ * store would pull the DynamoDB SDK loader into the engine's import graph and
+ * keep the policy layer from running anywhere but inside a Lambda. Pure and
+ * dependency-free, so the mock runtime and the browser entry can resolve it.
  */
 /**
  * The fixed windows a policy may cap, smallest first (the evaluation order),
@@ -53,19 +52,32 @@ export type LambderRateLimitResult = false | LambderRateLimitExceeded;
  * DynamoDB limiter and the in-memory one implement it; an app may bring its
  * own (Redis, a database) by implementing this one method.
  *
- * The engine validates a policy before it ever reaches here, so every capped
- * window arrives as a non-negative whole number and a limiter never has to
- * invent an answer for a nonsense one. A caller reaching isRateLimited
- * directly owes the same precondition: the two shipped implementations
- * disagree on a negative cap (one refuses the first attempt, the other allows
- * it) because neither was ever meant to be asked.
+ * The engine validates a policy before it reaches here, so every capped
+ * window arrives as a non-negative whole number. A caller reaching
+ * isRateLimited directly owes the same precondition: the two shipped
+ * implementations disagree on a negative cap (one refuses the first attempt,
+ * the other allows it), since neither is meant to be asked.
  *
  * The tracker key is bounded there too: the variable half of it (a custom
- * key handler's return, a session key) is replaced by its own sha256 past
- * 1024 UTF-8 bytes, so an implementation with a key limit of its own never
- * meets a key it has to refuse. That matters because a limiter's refusal is a
- * throw, and a throw is what failOpen swallows into no limit at all.
+ * key handler's return, a session key) is replaced by its own sha256 once it
+ * passes 1024 UTF-8 bytes as written into the key, so an implementation with
+ * a key limit of its own never meets a key it has to refuse. That matters
+ * because a limiter's refusal is a throw, and a throw is what failOpen
+ * swallows into no limit at all.
+ *
+ * A limiter that answers a run of requests with one continuing failure (the
+ * DynamoDB limiter, for a flooded partition it cannot size) may throw the
+ * same error object for each of them: the engine logs a failure once, not
+ * once per request that meets it.
  */
 export interface LambderRateLimiter {
     isRateLimited(trackerKey: string, policy: LambderRateLimitPolicy): Promise<LambderRateLimitResult>;
+    /**
+     * The clock the windows are computed against, in epoch milliseconds, for
+     * a limiter that keeps one of its own (an injected test clock). A
+     * refusal's `resetAt` is a second on this clock, so the engine reads the
+     * Retry-After against it. Optional: without it, the engine reads
+     * Date.now().
+     */
+    clockMilliseconds?(): number;
 }

package/dist/shared/contracts/LambderRateLimiter.js

@@ -3,11 +3,10 @@
  * policy may cap, the policy shape, what an exceeded check reports, and the
  * one method the rate-limit engine asks of a limiter.
  *
- * Kept apart from the DynamoDB limiter on purpose. The engine needs only this
- * table, and importing it from the store would pull the DynamoDB SDK loader
- * into the engine's import graph, which is what kept the policy layer from
- * running anywhere but inside a Lambda. Pure and dependency-free, so the
- * mock runtime and the browser entry can resolve it.
+ * Kept apart from the DynamoDB limiter on purpose: importing it from the
+ * store would pull the DynamoDB SDK loader into the engine's import graph and
+ * keep the policy layer from running anywhere but inside a Lambda. Pure and
+ * dependency-free, so the mock runtime and the browser entry can resolve it.
  */
 /**
  * The fixed windows a policy may cap, smallest first (the evaluation order),

package/dist/shared/contracts/LambderSessionStore.d.ts

@@ -3,12 +3,11 @@
  * it rests in.
  *
  * The manager owns the model (token format, hashing, expiry, sliding
- * writes, dataRefresh, regeneration); a store owns nothing but the five
- * operations below, keyed by the two hashes. LambderDdbSessionStore is the
- * DynamoDB implementation and LambderMemorySessionStore the in-memory one;
- * an app may bring its own (Redis, a database) by implementing this
- * interface. Records written by one store read back through another with
- * the same shape, because the shape is the manager's, not the store's.
+ * writes, dataRefresh, regeneration); a store owns only the operations
+ * below, keyed by the two hashes. LambderDdbSessionStore and
+ * LambderMemorySessionStore implement it, and an app may bring its own
+ * (Redis, a database). The record shape is the manager's, so records written
+ * by one store read back through another.
  */
 /**
  * A session record. The two hashes are the record's identity: the partition
@@ -17,7 +16,7 @@
  * stored, so a read of the store yields no usable credentials.
  */
 export type LambderSessionRecord<SessionData = unknown> = {
-    /** Salted sha256 of the sessionKey: the partition every session of one subject shares. */
+    /** HMAC-SHA256 of the sessionKey keyed by the salt: the partition every session of one subject shares. */
     sessionKeyHash: string;
     /** sha256 of the sort-key secret the client's session cookie carries. */
     secretHash: string;
@@ -37,36 +36,76 @@ export type LambderSessionRecord<SessionData = unknown> = {
      * session's own expiresAt.
      */
     dataExpiresAt?: number;
+    /**
+     * How many writes `data` and `dataExpiresAt` have had: 0 when the record
+     * is created, and one more on every update that writes either of them,
+     * which the store adds in the same atomic write. A conditioned update
+     * names the version it read (see LambderSessionStore.update).
+     */
+    dataVersion: number;
 };
+/**
+ * The fields of a stored session a write may change: the data and its
+ * refresh deadline, and the sliding expiry. A session's identity, its CSRF
+ * hash, its subject and its creation are fixed when it is created, and its
+ * dataVersion is the store's to advance, never the caller's to set.
+ */
+export type LambderSessionChanges<SessionData = unknown> = Partial<Pick<LambderSessionRecord<SessionData>, "data" | "dataExpiresAt" | "lastAccessedAt" | "expiresAt">>;
+/**
+ * What an update found: `"updated"` when it applied, `"missing"` when the
+ * record is gone (a logout, a password change, an expiry), and `"stale"`
+ * when the record exists but its dataVersion is no longer the one the
+ * update was conditioned on, so something else wrote its data or its
+ * refresh deadline in between.
+ */
+export type LambderSessionUpdateResult = "updated" | "missing" | "stale";
 export interface LambderSessionStore<SessionData = unknown> {
     /**
-     * Whether records live only for as long as this process does. The session
-     * manager reads it to refuse a non-cryptographic LambderSessionCrypto
-     * over a store that outlives the process: hashing that is not hashing is
-     * survivable in memory for a development run and never survivable at
-     * rest, where the records would be usable credentials.
+     * Whether records live only as long as this process. The session manager
+     * reads it to refuse a non-cryptographic LambderSessionCrypto over a store
+     * that outlives the process: fake hashing is tolerable in memory for a
+     * development run, but at rest the records would be usable credentials.
      */
     readonly isMemoryOnly: boolean;
     /**
      * The record under the two hashes, or null. A failing read throws; the
      * manager wraps it as a LambderSessionReadError.
      *
-     * A store MAY hand back a record that is past its expiresAt: a DynamoDB
-     * TTL deletes within days rather than at the second, and an implementation
-     * over a plain table has nothing that sweeps at all. Expiry is the
-     * manager's to enforce, and it does, on every read. A store that drops
-     * expired records itself is doing housekeeping, not policy.
+     * A store MAY hand back a record past its expiresAt: a DynamoDB TTL
+     * deletes within days rather than at the second, and a plain table has
+     * nothing that sweeps at all. The manager enforces expiry on every read;
+     * a store that drops expired records itself is doing housekeeping, not
+     * policy.
      */
     get(sessionKeyHash: string, secretHash: string): Promise<LambderSessionRecord<SessionData> | null>;
-    /** Writes the record, replacing any under the same hashes. */
-    put(record: LambderSessionRecord<SessionData>): Promise<void>;
-    delete(sessionKeyHash: string, secretHash: string): Promise<void>;
-    /** Every secretHash stored under the partition: the sessions of one subject. */
-    listSecretHashes(sessionKeyHash: string): Promise<string[]>;
+    /** Writes a new record, and throws when one already exists under the two hashes: a session is minted once and never overwritten. */
+    create(record: LambderSessionRecord<SessionData>): Promise<void>;
     /**
-     * Stamps dataExpiresAt on one record, only if it still exists: neither
-     * resurrects a session deleted in between nor overwrites a concurrent
-     * write. A record that no longer exists is skipped silently.
+     * Changes the named fields of an existing record and no others, and only
+     * while it exists: an update never brings back a session deleted in
+     * between, which is what keeps a logout, "log out everywhere" or a
+     * password change from being undone by a write already in flight.
+     *
+     * An update whose changes carry `data` or `dataExpiresAt` also adds one
+     * to the record's dataVersion, in the same atomic write (DynamoDB's
+     * `ADD`), even when the value written equals the one stored. With
+     * `condition`, the update applies only while the record's dataVersion is
+     * still `condition.dataVersion`, and answers "stale" otherwise, so data
+     * derived from an earlier read cannot land over a concurrent refresh,
+     * data write or expireSessionDataAllByKey. The version is what makes
+     * that hold: a deadline compared in whole seconds cannot show a mark
+     * that wrote the value already stored, or two marks in one second.
      */
-    markDataExpired(sessionKeyHash: string, secretHash: string, at: number): Promise<void>;
+    update(sessionKeyHash: string, secretHash: string, changes: LambderSessionChanges<SessionData>, condition?: {
+        dataVersion: number;
+    }): Promise<LambderSessionUpdateResult>;
+    /**
+     * Removes the record and hands back what it held at that moment, or null
+     * when there was none: rotation carries the stored record over, not the
+     * one a request read earlier, and mints nothing when a logout got there
+     * first.
+     */
+    delete(sessionKeyHash: string, secretHash: string): Promise<LambderSessionRecord<SessionData> | null>;
+    /** Every secretHash stored under the partition, read consistently: the sessions of one subject, including one created a moment ago. */
+    listSecretHashes(sessionKeyHash: string): Promise<string[]>;
 }

package/dist/shared/contracts/LambderSessionStore.js

@@ -3,11 +3,10 @@
  * it rests in.
  *
  * The manager owns the model (token format, hashing, expiry, sliding
- * writes, dataRefresh, regeneration); a store owns nothing but the five
- * operations below, keyed by the two hashes. LambderDdbSessionStore is the
- * DynamoDB implementation and LambderMemorySessionStore the in-memory one;
- * an app may bring its own (Redis, a database) by implementing this
- * interface. Records written by one store read back through another with
- * the same shape, because the shape is the manager's, not the store's.
+ * writes, dataRefresh, regeneration); a store owns only the operations
+ * below, keyed by the two hashes. LambderDdbSessionStore and
+ * LambderMemorySessionStore implement it, and an app may bring its own
+ * (Redis, a database). The record shape is the manager's, so records written
+ * by one store read back through another.
  */
 export {};