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

package/dist/store/internal/index-reconcile.js

@@ -1,118 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.collectReconcileTargets = collectReconcileTargets;
-exports.pushEmbeddings = pushEmbeddings;
-exports.selectOrphans = selectOrphans;
-exports.pruneOrphans = pruneOrphans;
-const clock_1 = require("../../shared/clock");
-const expiry_1 = require("../../shared/dynamodb/expiry");
-const paginate_1 = require("../../shared/dynamodb/paginate");
-const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
-const item_mapper_1 = require("./item-mapper");
-const keys_1 = require("./keys");
-const query_1 = require("./query");
-const semantic_search_1 = require("./semantic-search");
-const write_verify_1 = require("./write-verify");
-/** Stable, collision-free identity for a (namespace, key) pair. */
-function refIdentity(namespace, key) {
-    return JSON.stringify([...namespace, key]);
-}
-/**
- * Enumerate the live (unexpired) items under `prefix`, then recompute their
- * embeddings in batches. A failed embedding rejects the whole reconcile: a
- * skipped item would leave the live set and {@link selectOrphans} would prune
- * its still-valid vector.
- */
-async function collectReconcileTargets(context, prefix, signal) {
-    const now = (0, clock_1.nowSeconds)();
-    const live = [];
-    const source = (0, paginate_1.paginateQuery)({
-        retry: (0, retry_policy_1.retryFor)(context, signal),
-        signal,
-        client: context.client,
-        params: (0, expiry_1.withoutExpired)((0, query_1.scopedQuery)(context.tableName, prefix), now),
-        maxItems: context.maxScanItems,
-    });
-    for await (const raw of source) {
-        const record = (0, item_mapper_1.narrowStoreRecord)(raw);
-        if (!record) {
-            context.logger.warn('reconcileVectorIndex: skipped a row that is not a store item', {
-                sortKey: raw.SK,
-            });
-            continue;
-        }
-        if ((0, expiry_1.isExpiredRow)(record, now) || !(0, keys_1.namespaceMatchesPrefix)(record.namespace, prefix))
-            continue;
-        const item = await (0, item_mapper_1.readStoreItem)(context, record);
-        live.push({
-            namespace: record.namespace,
-            key: record.key,
-            value: item.value,
-        });
-    }
-    const embeddings = await (0, semantic_search_1.embedValues)(context, live.map((entry) => entry.value));
-    return live.map((entry, i) => ({
-        namespace: entry.namespace,
-        key: entry.key,
-        embedding: embeddings[i],
-    }));
-}
-/** Re-push every live embedding to the backend; returns the upsert count. */
-async function pushEmbeddings(backend, targets) {
-    let upserted = 0;
-    for (const target of targets) {
-        if (!target.embedding)
-            continue;
-        await backend.upsert(target.namespace, target.key, target.embedding);
-        upserted += 1;
-    }
-    return upserted;
-}
-/** Refs present in the backend but absent from `live` — orphans to prune. */
-function selectOrphans(backendRefs, live) {
-    const liveKeys = new Set(live
-        .filter((target) => target.embedding !== undefined)
-        .map((target) => refIdentity(target.namespace, target.key)));
-    return backendRefs.filter((ref) => !liveKeys.has(refIdentity(ref.namespace, ref.key)));
-}
-/**
- * True when a candidate's canonical item is confirmed absent right now. The
- * live-set snapshot and this read are not one point in time, so an item
- * written between them looks orphaned even though it is live — and deleting
- * its vector would silently drop a just-written item out of semantic search.
- */
-async function confirmedGone(context, ref) {
-    return (0, write_verify_1.rowIsAbsent)(context, {
-        PK: (0, keys_1.partitionKey)(ref.namespace),
-        SK: (0, keys_1.sortKey)(ref.namespace, ref.key),
-    });
-}
-/** Delete backend vectors with no canonical item; returns the prune count. */
-async function pruneOrphans(context, backend, prefix, live) {
-    if (!backend.listKeys) {
-        context.logger.info('reconcileVectorIndex prune skipped: backend has no listKeys', { prefix });
-        return 0;
-    }
-    const candidates = selectOrphans(await backend.listKeys(prefix), live);
-    /**
-     * Every item the snapshot actually saw, embedded or not. A candidate in here
-     * is prunable on the evidence already gathered — its item exists but yields
-     * no embedding (its indexable text became empty), so its vector really is
-     * stale. Only a candidate the snapshot never saw at all is ambiguous.
-     */
-    const observed = new Set(live.map((target) => refIdentity(target.namespace, target.key)));
-    let pruned = 0;
-    for (const ref of candidates) {
-        if (!observed.has(refIdentity(ref.namespace, ref.key)) &&
-            !(await confirmedGone(context, ref))) {
-            context.logger.info('reconcileVectorIndex: kept a vector whose item reappeared', {
-                namespace: ref.namespace,
-                key: ref.key,
-            });
-            continue;
-        }
-        await backend.delete(ref.namespace, ref.key);
-        pruned += 1;
-    }
-    return pruned;
-}

package/dist/store/internal/index-sync.d.ts

@@ -1,10 +0,0 @@
-import type { Logger } from '../../shared/logging/logger';
-import type { VectorBackend } from '../vector-backend';
-/**
- * Best-effort sync of one item's embedding to the vector backend after the
- * canonical DynamoDB write has already succeeded. A present embedding upserts;
- * its absence deletes any stale vector. Failures are logged at `warn` and
- * swallowed — the canonical item stands and `reconcileVectorIndex` repairs any
- * drift — so a backend hiccup never fails an otherwise-successful put.
- */
-export declare function syncVectorIndex(backend: VectorBackend, namespace: string[], key: string, embedding: number[] | undefined, logger: Logger): Promise<void>;

package/dist/store/internal/index-sync.js

@@ -1,25 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.syncVectorIndex = syncVectorIndex;
-/**
- * Best-effort sync of one item's embedding to the vector backend after the
- * canonical DynamoDB write has already succeeded. A present embedding upserts;
- * its absence deletes any stale vector. Failures are logged at `warn` and
- * swallowed — the canonical item stands and `reconcileVectorIndex` repairs any
- * drift — so a backend hiccup never fails an otherwise-successful put.
- */
-async function syncVectorIndex(backend, namespace, key, embedding, logger) {
-    try {
-        if (embedding)
-            await backend.upsert(namespace, key, embedding);
-        else
-            await backend.delete(namespace, key);
-    }
-    catch (error) {
-        logger.warn('store.put vector-index sync failed; reconcileVectorIndex will repair', {
-            namespace,
-            key,
-            message: error.message,
-        });
-    }
-}

package/dist/store/internal/item-mapper.d.ts

@@ -1,27 +0,0 @@
-import type { Item } from '@langchain/langgraph-checkpoint';
-import type { DocItem } from '../../shared/dynamodb/types';
-import type { StoreItemRecord } from '../types';
-import type { JsonValue } from './filter';
-import type { StoreContext } from './setup';
-/**
- * Narrow a raw scanned row to a {@link StoreItemRecord}, or `undefined` for a
- * foreign row on a shared table (no `namespace`) — and for a row whose
- * `namespace`/`key` attributes disagree with the DynamoDB key it was found at.
- * The attributes name the S3 path the row may reference, so they must be bound
- * to the partition the row actually lives in: a writer confined to its own
- * partition can then never make a row speak for another tenant's objects.
- */
-export declare function narrowStoreRecord(raw: DocItem): StoreItemRecord | undefined;
-/** Fields controlling a stored item's timestamps, embedding, ttl, and S3 key nonce. */
-export interface BuildItemOptions {
-    createdAt: string;
-    updatedAt: string;
-    embedding?: number[];
-    ttlTimestamp?: number;
-    /** Per-call nonce: uniquifies the S3 key and becomes the row's revision token. */
-    nonce?: string;
-}
-/** Encode a value into the DynamoDB record for a stored item. */
-export declare function buildStoreItem(context: StoreContext, namespace: string[], key: string, value: Record<string, JsonValue>, options: BuildItemOptions): Promise<StoreItemRecord>;
-/** Decode a DynamoDB record back into a store {@link Item}. */
-export declare function readStoreItem(context: StoreContext, record: StoreItemRecord): Promise<Item>;

package/dist/store/internal/item-mapper.js

@@ -1,61 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.narrowStoreRecord = narrowStoreRecord;
-exports.buildStoreItem = buildStoreItem;
-exports.readStoreItem = readStoreItem;
-const codec_1 = require("../../shared/codec/codec");
-const encode_1 = require("../../shared/codec/encode");
-const keys_1 = require("./keys");
-/**
- * Narrow a raw scanned row to a {@link StoreItemRecord}, or `undefined` for a
- * foreign row on a shared table (no `namespace`) — and for a row whose
- * `namespace`/`key` attributes disagree with the DynamoDB key it was found at.
- * The attributes name the S3 path the row may reference, so they must be bound
- * to the partition the row actually lives in: a writer confined to its own
- * partition can then never make a row speak for another tenant's objects.
- */
-function narrowStoreRecord(raw) {
-    if (!Array.isArray(raw.namespace) || typeof raw.key !== 'string')
-        return undefined;
-    const record = raw;
-    const consistent = record.PK === (0, keys_1.partitionKey)(record.namespace) &&
-        record.SK === (0, keys_1.sortKey)(record.namespace, record.key);
-    return consistent ? record : undefined;
-}
-/** Map a store context to the codec collaborators. */
-function storeCodecDeps(context) {
-    return { serde: context.serde, compression: context.compression, offloader: context.offloader };
-}
-/** Encode a value into the DynamoDB record for a stored item. */
-async function buildStoreItem(context, namespace, key, value, options) {
-    const descriptor = await (0, encode_1.encodePayload)(value, storeCodecDeps(context), {
-        keyParts: options.nonce === undefined ? [...namespace, key] : [...namespace, key, options.nonce],
-    });
-    const record = {
-        PK: (0, keys_1.partitionKey)(namespace),
-        SK: (0, keys_1.sortKey)(namespace, key),
-        namespace,
-        key,
-        value: descriptor,
-        createdAt: options.createdAt,
-        updatedAt: options.updatedAt,
-    };
-    if (options.embedding)
-        record.embedding = options.embedding;
-    if (options.ttlTimestamp !== undefined)
-        record.ttl = options.ttlTimestamp;
-    if (options.nonce !== undefined)
-        record.rev = options.nonce;
-    return record;
-}
-/** Decode a DynamoDB record back into a store {@link Item}. */
-async function readStoreItem(context, record) {
-    const value = await (0, codec_1.decodePayload)(record.value, storeCodecDeps(context), [...record.namespace, record.key]);
-    return {
-        namespace: record.namespace,
-        key: record.key,
-        value,
-        createdAt: new Date(record.createdAt),
-        updatedAt: new Date(record.updatedAt),
-    };
-}

package/dist/store/internal/keys.d.ts

@@ -1,17 +0,0 @@
-/** Separator joining namespace elements (and the trailing key) in the sort key. */
-export declare const NAMESPACE_SEPARATOR = "#";
-/** Partition key for an item: the adapter tag plus the scope-root element. */
-export declare function partitionKey(namespace: string[]): string;
-/** Sort key: the rest of the namespace plus the key, separator-joined. */
-export declare function sortKey(namespace: string[], key: string): string;
-/**
- * `begins_with` prefix selecting a scoped subtree within `prefix[0]`'s
- * partition. Terminated with the separator so `['users','u1']` does not match a
- * sibling like `u10`. An empty rest yields '' (matches the whole partition).
- */
-export declare function sortKeyPrefix(prefix: string[]): string;
-/**
- * True when `namespace` starts with `prefix`, compared element-by-element (not
- * as a string prefix, so ["userspace"] does not match prefix ["users"]).
- */
-export declare function namespaceMatchesPrefix(namespace: string[], prefix: string[]): boolean;

package/dist/store/internal/keys.js

@@ -1,41 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.NAMESPACE_SEPARATOR = void 0;
-exports.partitionKey = partitionKey;
-exports.sortKey = sortKey;
-exports.sortKeyPrefix = sortKeyPrefix;
-exports.namespaceMatchesPrefix = namespaceMatchesPrefix;
-/** Separator joining namespace elements (and the trailing key) in the sort key. */
-exports.NAMESPACE_SEPARATOR = '#';
-/**
- * Adapter tag prefixed to every store partition key — see the equivalent in
- * checkpointer/internal/keys.ts for why the three adapters' partitions must
- * not overlap on a shared table.
- */
-const ADAPTER_PARTITION_PREFIX = `STORE${exports.NAMESPACE_SEPARATOR}`;
-/** Partition key for an item: the adapter tag plus the scope-root element. */
-function partitionKey(namespace) {
-    return `${ADAPTER_PARTITION_PREFIX}${namespace[0]}`;
-}
-/** Sort key: the rest of the namespace plus the key, separator-joined. */
-function sortKey(namespace, key) {
-    return [...namespace.slice(1), key].join(exports.NAMESPACE_SEPARATOR);
-}
-/**
- * `begins_with` prefix selecting a scoped subtree within `prefix[0]`'s
- * partition. Terminated with the separator so `['users','u1']` does not match a
- * sibling like `u10`. An empty rest yields '' (matches the whole partition).
- */
-function sortKeyPrefix(prefix) {
-    const rest = prefix.slice(1);
-    return rest.length === 0 ? '' : `${rest.join(exports.NAMESPACE_SEPARATOR)}${exports.NAMESPACE_SEPARATOR}`;
-}
-/**
- * True when `namespace` starts with `prefix`, compared element-by-element (not
- * as a string prefix, so ["userspace"] does not match prefix ["users"]).
- */
-function namespaceMatchesPrefix(namespace, prefix) {
-    if (prefix.length > namespace.length)
-        return false;
-    return prefix.every((element, index) => namespace[index] === element);
-}

package/dist/store/internal/namespace-match.d.ts

@@ -1,11 +0,0 @@
-import type { MatchCondition } from '@langchain/langgraph-checkpoint';
-/** True when `namespace` satisfies a prefix/suffix match condition (with `*`). */
-export declare function matchNamespace(namespace: string[], condition: MatchCondition): boolean;
-/** Cap a namespace to at most `maxDepth` elements (no-op when undefined). */
-export declare function truncateDepth(namespace: string[], maxDepth?: number): string[];
-/**
- * Leading concrete (non-wildcard) elements of the first prefix condition. An
- * empty result means the listing cannot be scoped to a single partition and
- * must fall back to a Scan.
- */
-export declare function prefixRoot(conditions?: MatchCondition[]): string[];

package/dist/store/internal/namespace-match.js

@@ -1,40 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.matchNamespace = matchNamespace;
-exports.truncateDepth = truncateDepth;
-exports.prefixRoot = prefixRoot;
-const WILDCARD = '*';
-function segmentMatches(actual, path) {
-    return path.every((element, index) => element === WILDCARD || element === actual[index]);
-}
-/** True when `namespace` satisfies a prefix/suffix match condition (with `*`). */
-function matchNamespace(namespace, condition) {
-    const { matchType, path } = condition;
-    if (path.length > namespace.length)
-        return false;
-    const slice = matchType === 'prefix'
-        ? namespace.slice(0, path.length)
-        : namespace.slice(namespace.length - path.length);
-    return segmentMatches(slice, path);
-}
-/** Cap a namespace to at most `maxDepth` elements (no-op when undefined). */
-function truncateDepth(namespace, maxDepth) {
-    return maxDepth === undefined ? namespace : namespace.slice(0, maxDepth);
-}
-/**
- * Leading concrete (non-wildcard) elements of the first prefix condition. An
- * empty result means the listing cannot be scoped to a single partition and
- * must fall back to a Scan.
- */
-function prefixRoot(conditions) {
-    const prefixCondition = conditions?.find((condition) => condition.matchType === 'prefix');
-    if (!prefixCondition)
-        return [];
-    const root = [];
-    for (const element of prefixCondition.path) {
-        if (element === WILDCARD)
-            break;
-        root.push(element);
-    }
-    return root;
-}

package/dist/store/internal/option-validation.d.ts

@@ -1,13 +0,0 @@
-import type { DynamoDBStoreOptions } from '../types';
-/**
- * Validate every store option at construction, shared options first.
- *
- * A `vectorBackend` without an `index` is rejected outright rather than
- * silently degrading: with no embeddings configured, every `put` would compute
- * no vector and instruct the backend to *delete* the item's entry instead of
- * indexing it, and `search()` would fall through to an unranked scan-order
- * listing with no `.score` field and no error — a semantic query returning a
- * normal-looking but meaningless response. `reconcileVectorIndex` already
- * refused this exact misconfiguration.
- */
-export declare function validateStoreOptions(options: DynamoDBStoreOptions): void;

package/dist/store/internal/option-validation.js

@@ -1,77 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateStoreOptions = validateStoreOptions;
-const errors_1 = require("../../shared/errors/errors");
-const options_1 = require("../../shared/validation/options");
-const primitives_1 = require("../../shared/validation/primitives");
-const score_direction_1 = require("./score-direction");
-/**
- * Reject an `index` that cannot actually embed. `IndexConfig` mandates
- * `embeddings`, but a JavaScript caller can omit it or pass the wrong shape,
- * and the failure then surfaced as a raw `TypeError` deep inside the first
- * `put()`/`search()` rather than this library's typed error at construction.
- *
- * Both methods are required: documents are embedded with `embedDocuments()`
- * on `put()` and queries with `embedQuery()` on `search()`. `dims` is only
- * compared against returned vectors when it is a positive integer, so a
- * configuration that omits it keeps working.
- */
-function assertUsableIndex(index) {
-    if (!index)
-        return;
-    const embeddings = index.embeddings;
-    const missing = ['embedQuery', 'embedDocuments'].find((method) => typeof embeddings?.[method] !== 'function');
-    if (missing === undefined)
-        return;
-    throw new errors_1.ValidationError(`\`index.embeddings\` must be an Embeddings implementation exposing ${missing}(); ` +
-        'documents are embedded with embedDocuments() on put() and queries with embedQuery() ' +
-        'on search()', 'index');
-}
-/**
- * Reject a `vectorScoreDirection` outside the declared union.
- *
- * {@link toRelevanceScores} treats anything it does not recognise as a no-op —
- * the only safe default, since guessing would invert a ranking — so a mistyped
- * or config-file-sourced value would otherwise leave a distance backend ranked
- * backwards with no error and no warning anywhere. Same premise as
- * {@link assertUsableIndex}: a JavaScript caller can pass a string the type
- * never admits.
- */
-function assertScoreDirection(direction) {
-    if (direction === undefined || score_direction_1.VECTOR_SCORE_DIRECTIONS.includes(direction))
-        return;
-    throw new errors_1.ValidationError(`vectorScoreDirection must be one of ${score_direction_1.VECTOR_SCORE_DIRECTIONS.join(' | ')}; received ` +
-        `${JSON.stringify(direction)}, which would be left in the backend's own direction and ` +
-        'could rank a distance backend backwards', 'vectorScoreDirection');
-}
-/** Both in-memory caps must be positive integers; 0 would silently return nothing. */
-function validateLimits(options) {
-    if (options.maxScanItems !== undefined) {
-        (0, primitives_1.validateInteger)(options.maxScanItems, 'maxScanItems', { min: 1 });
-    }
-    if (options.maxSearchCandidates !== undefined) {
-        (0, primitives_1.validateInteger)(options.maxSearchCandidates, 'maxSearchCandidates', { min: 1 });
-    }
-}
-/**
- * Validate every store option at construction, shared options first.
- *
- * A `vectorBackend` without an `index` is rejected outright rather than
- * silently degrading: with no embeddings configured, every `put` would compute
- * no vector and instruct the backend to *delete* the item's entry instead of
- * indexing it, and `search()` would fall through to an unranked scan-order
- * listing with no `.score` field and no error — a semantic query returning a
- * normal-looking but meaningless response. `reconcileVectorIndex` already
- * refused this exact misconfiguration.
- */
-function validateStoreOptions(options) {
-    (0, options_1.validateBaseAdapterOptions)(options);
-    validateLimits(options);
-    if (options.vectorBackend && !options.index) {
-        throw new errors_1.ValidationError('vectorBackend requires a configured `index` (embeddings); without one no embedding ' +
-            'is computed, every put would clear the item vector, and search would silently return ' +
-            'unranked, score-less results', 'vectorBackend');
-    }
-    assertUsableIndex(options.index);
-    assertScoreDirection(options.vectorScoreDirection);
-}

package/dist/store/internal/overwrite-swap.d.ts

@@ -1,32 +0,0 @@
-import type { StoreItemRecord } from '../types';
-import { type ExistingRecordMeta } from './read-existing';
-import type { StoreContext } from './setup';
-/**
- * Commit `record`, re-reading and retrying while another writer holds the row,
- * and return the state this write actually superseded — the only descriptor
- * safe to delete afterwards.
- *
- * Without the swap both racers read the same previous descriptor, both commit,
- * and both delete it, orphaning the loser's own upload. Retrying against the
- * *re-read* state is what makes each writer supersede exactly one payload.
- *
- * A rejection is not proof a competitor won: `withDynamoDBRetry` retries
- * transient errors, so an attempt can commit server-side, its response can be
- * lost, and the retried put can hit the row it just wrote and fail the same
- * guard — indistinguishable from a competitor's win by the rejection alone.
- * Each attempt's pinned observation is captured in `attempted` before the
- * put, so that when a re-read finds the row already holding *this call's
- * own* `rev`, the swap returns whatever `attempted` held — never this
- * record's own just-committed value, which would strand the live row
- * pointing at a deleted object. That comparison is guarded on `rev` being
- * set: `rev` is optional on the record type, and an unnonced record against a
- * pre-0.9.0 revision-less row would otherwise match `undefined === undefined`
- * and claim a race it never entered.
- *
- * On exhaustion the write proceeds unconditionally and warns. That is
- * deliberate: the fallback is precisely the pre-0.9.0 behaviour — one possible
- * orphan, reclaimed by a lifecycle rule — so pathological contention degrades
- * instead of turning a working put into an error. `createdAt` is refreshed from
- * each re-read so a row created by whoever won keeps its true creation time.
- */
-export declare function putWithRevisionSwap(context: StoreContext, record: StoreItemRecord, existing: ExistingRecordMeta): Promise<ExistingRecordMeta>;

package/dist/store/internal/overwrite-swap.js

@@ -1,68 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.putWithRevisionSwap = putWithRevisionSwap;
-const conditional_put_1 = require("../../shared/dynamodb/conditional-put");
-const retry_1 = require("../../shared/dynamodb/retry");
-const read_existing_1 = require("./read-existing");
-/** Put the record, optionally pinned to the revision the caller observed. */
-async function put(context, record, observed) {
-    const guard = observed ? (0, conditional_put_1.revisionGuard)(conditional_put_1.REVISION_ATTRIBUTE, observed) : {};
-    await (0, retry_1.withDynamoDBRetry)(() => context.client.put({ TableName: context.tableName, Item: record, ...guard }), context.retry);
-}
-/**
- * Commit `record`, re-reading and retrying while another writer holds the row,
- * and return the state this write actually superseded — the only descriptor
- * safe to delete afterwards.
- *
- * Without the swap both racers read the same previous descriptor, both commit,
- * and both delete it, orphaning the loser's own upload. Retrying against the
- * *re-read* state is what makes each writer supersede exactly one payload.
- *
- * A rejection is not proof a competitor won: `withDynamoDBRetry` retries
- * transient errors, so an attempt can commit server-side, its response can be
- * lost, and the retried put can hit the row it just wrote and fail the same
- * guard — indistinguishable from a competitor's win by the rejection alone.
- * Each attempt's pinned observation is captured in `attempted` before the
- * put, so that when a re-read finds the row already holding *this call's
- * own* `rev`, the swap returns whatever `attempted` held — never this
- * record's own just-committed value, which would strand the live row
- * pointing at a deleted object. That comparison is guarded on `rev` being
- * set: `rev` is optional on the record type, and an unnonced record against a
- * pre-0.9.0 revision-less row would otherwise match `undefined === undefined`
- * and claim a race it never entered.
- *
- * On exhaustion the write proceeds unconditionally and warns. That is
- * deliberate: the fallback is precisely the pre-0.9.0 behaviour — one possible
- * orphan, reclaimed by a lifecycle rule — so pathological contention degrades
- * instead of turning a working put into an error. `createdAt` is refreshed from
- * each re-read so a row created by whoever won keeps its true creation time.
- */
-async function putWithRevisionSwap(context, record, existing) {
-    let observed = existing;
-    for (let attempt = 1; attempt <= conditional_put_1.OVERWRITE_CAS_MAX_ATTEMPTS; attempt++) {
-        const attempted = observed;
-        try {
-            await put(context, record, attempted);
-            return attempted;
-        }
-        catch (error) {
-            if (!(0, conditional_put_1.isConditionalCheckFailed)(error))
-                throw error;
-            /** The rejection carries the row that turned it away; the read is spent only when it does not. */
-            const rejected = (0, conditional_put_1.rejectedItem)(error);
-            observed = rejected
-                ? (0, read_existing_1.existingFrom)(rejected)
-                : await (0, read_existing_1.readExisting)(context, record.PK, record.SK);
-            if (record.rev !== undefined && observed.revision === record.rev)
-                return attempted;
-            /** A row that vanished between attempts (a concurrent delete) makes this a fresh creation. */
-            record.createdAt = observed.exists
-                ? (observed.createdAt ?? record.createdAt)
-                : record.updatedAt;
-        }
-    }
-    context.logger.warn('store.put: compare-and-swap exhausted; overwriting unconditionally, which can orphan one ' +
-        'S3 object under a concurrent put (reclaimed by ensureS3LifecycleRule)', { namespace: record.namespace, key: record.key, attempts: conditional_put_1.OVERWRITE_CAS_MAX_ATTEMPTS });
-    await put(context, record);
-    return observed;
-}

package/dist/store/internal/persist.d.ts

@@ -1,28 +0,0 @@
-import type { StoreItemRecord } from '../types';
-import type { ExistingRecordMeta } from './read-existing';
-import type { StoreContext } from './setup';
-/**
- * Put the record and clean up whichever side is now dead.
- *
- * The compare-and-swap path runs **only when an offloader is configured**:
- * without one there is no S3 object to orphan, so a plain last-write-wins put
- * stays correct and costs no extra write capacity (DynamoDB charges for a
- * failed conditional write too). With one, the swap is what lets this call
- * delete exactly the payload it superseded rather than a descriptor a racer may
- * already have replaced.
- *
- * Every failure reaching the catch arrives after at least one put was issued —
- * `putWithRevisionSwap` only re-reads from inside its own catch — so none of
- * them proves a non-commit on its own: a put can commit server-side and lose
- * its response, and a `ConditionalCheckFailedException` is as consistent with
- * hitting the row this call just wrote as with a competitor's win. The row is
- * therefore read back (`verifyWriteLanded`) before anything is deleted. Only a
- * confirmed `'not-landed'` deletes this record's own nonced object; a confirmed
- * `'landed'` cleans up the previous object like the success path and swallows
- * the error, and an `'unverified'` read deletes nothing and rethrows — leaking
- * one object at worst rather than stranding a live row pointing at a deleted
- * one. The verification compares the per-call `rev`, so an inline record is
- * verified too: a lost acknowledgement of an inline overwrite used to be
- * reported as a failure while the previous offloaded object was never cleaned.
- */
-export declare function persistRecord(context: StoreContext, record: StoreItemRecord, existing: ExistingRecordMeta): Promise<void>;

package/dist/store/internal/persist.js

@@ -1,64 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.persistRecord = persistRecord;
-const descriptor_keys_1 = require("../../shared/codec/descriptor-keys");
-const orphans_1 = require("../../shared/codec/s3/orphans");
-const retry_1 = require("../../shared/dynamodb/retry");
-const overwrite_swap_1 = require("./overwrite-swap");
-const write_verify_1 = require("./write-verify");
-/**
- * Best-effort delete of one descriptor's S3 object. `scope` is passed for a
- * descriptor read back from the row (the superseded value) and omitted for
- * this call's own upload.
- */
-async function cleanUp(context, descriptor, label, scope) {
-    if (!context.offloader || !descriptor)
-        return;
-    await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)([descriptor]), label, context.logger, scope === undefined ? {} : { scope });
-}
-/**
- * Put the record and clean up whichever side is now dead.
- *
- * The compare-and-swap path runs **only when an offloader is configured**:
- * without one there is no S3 object to orphan, so a plain last-write-wins put
- * stays correct and costs no extra write capacity (DynamoDB charges for a
- * failed conditional write too). With one, the swap is what lets this call
- * delete exactly the payload it superseded rather than a descriptor a racer may
- * already have replaced.
- *
- * Every failure reaching the catch arrives after at least one put was issued —
- * `putWithRevisionSwap` only re-reads from inside its own catch — so none of
- * them proves a non-commit on its own: a put can commit server-side and lose
- * its response, and a `ConditionalCheckFailedException` is as consistent with
- * hitting the row this call just wrote as with a competitor's win. The row is
- * therefore read back (`verifyWriteLanded`) before anything is deleted. Only a
- * confirmed `'not-landed'` deletes this record's own nonced object; a confirmed
- * `'landed'` cleans up the previous object like the success path and swallows
- * the error, and an `'unverified'` read deletes nothing and rethrows — leaking
- * one object at worst rather than stranding a live row pointing at a deleted
- * one. The verification compares the per-call `rev`, so an inline record is
- * verified too: a lost acknowledgement of an inline overwrite used to be
- * reported as a failure while the previous offloaded object was never cleaned.
- */
-async function persistRecord(context, record, existing) {
-    let superseded = existing;
-    try {
-        if (context.offloader) {
-            superseded = await (0, overwrite_swap_1.putWithRevisionSwap)(context, record, existing);
-        }
-        else {
-            await (0, retry_1.withDynamoDBRetry)(() => context.client.put({ TableName: context.tableName, Item: record }), context.retry);
-        }
-    }
-    catch (error) {
-        const verdict = await (0, write_verify_1.verifyWriteLanded)(context, record);
-        if (verdict === 'not-landed')
-            await cleanUp(context, record.value, 'store.put');
-        if (verdict !== 'landed')
-            throw error;
-    }
-    await cleanUp(context, superseded.value, 'store.put.overwrite', [
-        ...record.namespace,
-        record.key,
-    ]);
-}