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

package/dist/shared/validation/ttl.js

@@ -1,34 +1,132 @@
 "use strict";
+/**
+ * Hides how a `ttl` option becomes an expiry.
+ *
+ * A caller gives days or seconds. The one-unit rule, the five-year cap, the
+ * epoch second DynamoDB's TTL attribute takes, and the S3 lifecycle days that
+ * keep an offloaded object alive past its row's sweep lag are all derived
+ * here, so the two spellings of the `ttl` option are accepted or rejected
+ * alike and no reader re-derives one unit from the other itself. A stored
+ * row's own epoch-second `ttl` is converted to milliseconds for `Date` where
+ * that row is read, not here.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.S3_LIFECYCLE_SWEEP_MARGIN_DAYS = exports.MAX_TTL_SECONDS = exports.MAX_TTL_DAYS = void 0;
 exports.resolveTtlSeconds = resolveTtlSeconds;
 exports.calculateTtlTimestamp = calculateTtlTimestamp;
-exports.resolveTtlDaysCeil = resolveTtlDaysCeil;
-const constants_1 = require("../constants");
+exports.lifecycleExpirationDays = lifecycleExpirationDays;
+const errors_1 = require("../errors/errors");
+const option_shape_1 = require("./option-shape");
 const primitives_1 = require("./primitives");
 const SECONDS_PER_DAY = 24 * 60 * 60;
-/** Validate a {@link TtlOption} and resolve it to a positive number of seconds. */
+/** Maximum TTL expressed in days (5 years). */
+exports.MAX_TTL_DAYS = 365 * 5;
+/** Maximum TTL expressed in seconds: the same five years as {@link MAX_TTL_DAYS}. */
+exports.MAX_TTL_SECONDS = exports.MAX_TTL_DAYS * 24 * 60 * 60;
+/**
+ * Extra days an S3 lifecycle rule adds over the TTL it backs. DynamoDB's TTL
+ * sweep can lag up to ~48 h past the `ttl` timestamp; the offloaded object
+ * must outlive its row, never the other way round.
+ */
+exports.S3_LIFECYCLE_SWEEP_MARGIN_DAYS = 2;
+/**
+ * The units {@link TtlOption} declares. `allKeysOf<TtlOption>` cannot check
+ * this list: over a union its parameter is itself a union of one key map per
+ * shape, so `{ days: 'days' }` alone satisfies the first shape and compiles.
+ * Listing the keys of every shape as one record restores the check, so leaving
+ * a unit out, inventing one, or adding a shape to the union without listing
+ * its unit here fails to compile.
+ */
+const TTL_KEYS = (0, option_shape_1.allKeysOf)({
+    days: 'days',
+    seconds: 'seconds',
+});
+/** Positive integer no greater than `max`, with a message that names what the cap means. */
+function assertWithinCap(value, field, max) {
+    (0, primitives_1.assertInteger)(value, field, { min: 1 });
+    if (value > max) {
+        throw (0, errors_1.validationError)(`${field} must be <= ${max} (five years)`, field);
+    }
+}
+/**
+ * Reject a `ttl` that is not an object at all, carries a key other than a
+ * unit, or names neither unit or both. The stray key is checked before the
+ * units, so `{ day: 1 }` names the key the caller wrote rather than a unit it
+ * did not.
+ */
+function assertOneUnit(ttl) {
+    if (typeof ttl !== 'object' || ttl === null) {
+        throw (0, errors_1.validationError)('ttl must be an object: { days } or { seconds }', 'ttl');
+    }
+    (0, option_shape_1.assertShape)(ttl, TTL_KEYS, 'ttl');
+    const days = 'days' in ttl;
+    const seconds = 'seconds' in ttl;
+    if (days && seconds) {
+        throw (0, errors_1.validationError)('ttl must specify either ttl.days or ttl.seconds, not both', 'ttl');
+    }
+    if (!days && !seconds) {
+        throw (0, errors_1.validationError)('ttl must specify either ttl.days or ttl.seconds', 'ttl');
+    }
+}
+/**
+ * A {@link TtlOption} resolved to a positive number of seconds.
+ *
+ * Accepts: `ttl` — declared as the two-shape union; a JavaScript caller, or a
+ * config built from JSON, can also reach `undefined`, a non-object, `{}`, an
+ * object carrying both keys and one carrying any other key, and each is
+ * rejected. Within a shape the value must be an integer of at least 1.
+ *
+ * Returns: whole seconds, `days × 86400` for the days form.
+ *
+ * Throws: `VALIDATION`, in this order, naming `ttl` for a value that is not
+ * an object, `ttl.<key>` for a key other than `days` or `seconds`, `ttl` for
+ * an object naming neither unit or both, and `ttl.days` or `ttl.seconds` for a
+ * value outside 1..five years. Both forms share that cap, so the two spellings
+ * of one duration are accepted or rejected alike.
+ */
 function resolveTtlSeconds(ttl) {
+    assertOneUnit(ttl);
     if ('days' in ttl) {
-        (0, primitives_1.validateInteger)(ttl.days, 'ttl.days', { min: 1, max: constants_1.MAX_TTL_DAYS });
+        assertWithinCap(ttl.days, 'ttl.days', exports.MAX_TTL_DAYS);
         return ttl.days * SECONDS_PER_DAY;
     }
-    (0, primitives_1.validateInteger)(ttl.seconds, 'ttl.seconds', { min: 1, max: constants_1.MAX_TTL_SECONDS });
+    assertWithinCap(ttl.seconds, 'ttl.seconds', exports.MAX_TTL_SECONDS);
     return ttl.seconds;
 }
 /**
- * Resolve a {@link TtlOption} into a DynamoDB TTL attribute value: the Unix
- * epoch (seconds) at which the item expires.
+ * The value DynamoDB's TTL attribute takes for an item written now: the Unix
+ * epoch second at which it expires.
+ *
+ * Accepts: `ttl` — as {@link resolveTtlSeconds}. `now` — a clock returning
+ * epoch **milliseconds**, defaulting to `Date.now`; supplied by tests and by
+ * the adapters' clock seam.
  *
- * @param now - Clock seam returning epoch milliseconds. Defaults to `Date.now`.
+ * Returns: `floor(now() / 1000) + resolveTtlSeconds(ttl)`. Whole seconds,
+ * because DynamoDB reads the attribute as an epoch-second Number
+ * (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/time-to-live-ttl-before-you-start.html).
+ *
+ * Throws: whatever {@link resolveTtlSeconds} throws.
  */
 function calculateTtlTimestamp(ttl, now = Date.now) {
     return Math.floor(now() / 1000) + resolveTtlSeconds(ttl);
 }
-/** Resolve a {@link TtlOption} to whole days, rounded up so the S3 lifecycle
- * expiration never fires before DynamoDB's own TTL sweep (which can lag up
- * to ~48h past the TTL timestamp) — expiring the S3 object first would leave
- * a live DynamoDB item pointing at a deleted payload. */
-function resolveTtlDaysCeil(ttl) {
-    return Math.ceil(resolveTtlSeconds(ttl) / SECONDS_PER_DAY);
+/**
+ * The `Days` of the S3 lifecycle expiration rule that backs a TTL.
+ *
+ * Accepts: `ttl` — as {@link resolveTtlSeconds}.
+ *
+ * Returns: the TTL rounded **up** to whole days plus
+ * {@link S3_LIFECYCLE_SWEEP_MARGIN_DAYS}, so always at least
+ * `1 + margin`.
+ *
+ * Throws: whatever {@link resolveTtlSeconds} throws.
+ *
+ * Guarantees: the object outlives the row that points at it. S3 expires an
+ * object at the first midnight UTC at least `Days` after creation, while
+ * DynamoDB may keep an expired item for up to 48 hours past its `ttl`
+ * (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/howitworks-ttl.html);
+ * the margin covers that lag, which a bare `{ days: N }` did not.
+ */
+function lifecycleExpirationDays(ttl) {
+    return Math.ceil(resolveTtlSeconds(ttl) / SECONDS_PER_DAY) + exports.S3_LIFECYCLE_SWEEP_MARGIN_DAYS;
 }
-//# sourceMappingURL=ttl.js.map

package/dist/store/actions/list-namespaces.d.ts

@@ -1,9 +1,79 @@
-import type { ListNamespacesOperation } from '@langchain/langgraph-checkpoint';
+/**
+ * Hides how the distinct namespaces are found and held in one order.
+ *
+ * A listing reads every live row it can reach — one partition when its first
+ * prefix condition opens with concrete labels, the whole table otherwise —
+ * keeps the namespaces every condition matches, truncates and deduplicates
+ * them, and sorts them by one pinned collation with its ties settled. A caller
+ * paging by `offset` gets the same order on every call and every host.
+ */
+import type { MatchCondition } from '@langchain/langgraph-checkpoint';
+import type { ParsedList } from '../internal/parse';
 import type { StoreContext } from '../internal/setup';
 /**
- * List distinct namespaces (truncated to `maxDepth`) that satisfy every match
- * condition, sorted, with offset/limit applied. A concrete prefix root scopes
- * the read to a native Query; otherwise it falls back to a filtered Scan.
+ * Whether `namespace` satisfies one match condition. `condition.matchType` is
+ * `'prefix'` or `'suffix'`, already refused otherwise by the parser that built
+ * `condition` (`parseMatchCondition` in `parse.ts`).
+ *
+ * Accepts: `condition.path` — elements, where `'*'` matches any one element;
+ * longer than the namespace never matches, and empty matches every namespace.
+ *
+ * Returns: whether the condition holds.
+ *
+ * Throws: nothing.
+ */
+export declare function matchNamespace(namespace: string[], condition: MatchCondition): boolean;
+/**
+ * Cap a namespace to at most `maxDepth` elements.
+ *
+ * Accepts: `maxDepth` — absent returns the namespace unchanged; otherwise a
+ * parsed positive integer (see `parseListOperation` for what a negative or
+ * zero value did here).
+ *
+ * Returns: the namespace, truncated from the end; shorter than `maxDepth` is
+ * returned whole.
+ *
+ * Throws: nothing.
+ */
+export declare function truncateDepth(namespace: string[], maxDepth?: number): string[];
+/**
+ * Leading concrete (non-wildcard) elements of the first prefix condition.
+ *
+ * Accepts: `conditions` — absent, empty, suffix-only, or a prefix condition
+ * starting with `'*'` all yield nothing to scope by.
+ *
+ * Returns: the concrete leading elements, which name a partition and a sort-key
+ * prefix the listing can be read from. An empty result means the listing cannot
+ * be scoped to one partition and falls back to a Scan.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: the root is only ever a *superset* of what the conditions select
+ * — every condition is still applied to each namespace read — so scoping can
+ * never drop a namespace that belongs in the answer.
+ */
+export declare function prefixRoot(conditions?: MatchCondition[]): string[];
+/**
+ * The distinct namespaces satisfying every match condition.
+ *
+ * Accepts: `op` — parsed; every match condition must hold, absent or empty
+ * matches every namespace. A concrete prefix root scopes the read to one
+ * partition's Query, and anything else — a suffix condition, a leading `*`, no
+ * conditions — spans the table and is one of the four reads allowed to Scan
+ * (`test/static/guards/scan-sites.ts`).
+ * `op.maxDepth` — namespaces are truncated to it and then
+ * deduplicated, so `['a','b']` and `['a','c']` list once as `['a']`.
+ * `op.offset` and `op.limit` — a `limit` of 0 returns an empty listing without reading.
+ *
+ * Returns: the namespaces, sorted, then `limit` of them from `offset`.
+ *
+ * Throws: `RESULT_TRUNCATED` when `maxScanItems` is reached while rows
+ * remain, so a partial listing is never returned as a complete one;
+ * `FORMAT_UNSUPPORTED` for a store item a newer release wrote.
+ *
+ * Guarantees: every live row is read — the answer is about which namespaces
+ * exist, and paging over it must not depend on which rows were read first. That
+ * is also why the sort is total (see {@link compareNamespaces}), and why a
+ * `limit` of 0 is answered ahead of the read rather than by slicing one.
  */
-export declare function listNamespaces(context: StoreContext, op: ListNamespacesOperation): Promise<string[][]>;
-//# sourceMappingURL=list-namespaces.d.ts.map
+export declare function listNamespaces(context: StoreContext, op: ParsedList): Promise<string[][]>;

package/dist/store/actions/list-namespaces.js

@@ -1,55 +1,197 @@
 "use strict";
+/**
+ * Hides how the distinct namespaces are found and held in one order.
+ *
+ * A listing reads every live row it can reach — one partition when its first
+ * prefix condition opens with concrete labels, the whole table otherwise —
+ * keeps the namespaces every condition matches, truncates and deduplicates
+ * them, and sorts them by one pinned collation with its ties settled. A caller
+ * paging by `offset` gets the same order on every call and every host.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchNamespace = matchNamespace;
+exports.truncateDepth = truncateDepth;
+exports.prefixRoot = prefixRoot;
 exports.listNamespaces = listNamespaces;
+const clock_1 = require("../../shared/clock");
 const paginate_1 = require("../../shared/dynamodb/paginate");
-const scan_1 = require("../../shared/dynamodb/scan");
-const item_mapper_1 = require("../internal/item-mapper");
-const keys_1 = require("../internal/keys");
-const namespace_match_1 = require("../internal/namespace-match");
-const query_1 = require("../internal/query");
-const validation_1 = require("../internal/validation");
-function namespaceSource(context, op) {
-    const root = (0, namespace_match_1.prefixRoot)(op.matchConditions);
+const table_schema_1 = require("../../shared/dynamodb/table-schema");
+const rows_1 = require("../internal/rows");
+const WILDCARD = '*';
+function segmentMatches(actual, path) {
+    return path.every((element, index) => element === WILDCARD || element === actual[index]);
+}
+/**
+ * Whether `namespace` satisfies one match condition. `condition.matchType` is
+ * `'prefix'` or `'suffix'`, already refused otherwise by the parser that built
+ * `condition` (`parseMatchCondition` in `parse.ts`).
+ *
+ * Accepts: `condition.path` — elements, where `'*'` matches any one element;
+ * longer than the namespace never matches, and empty matches every namespace.
+ *
+ * Returns: whether the condition holds.
+ *
+ * Throws: nothing.
+ */
+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.
+ *
+ * Accepts: `maxDepth` — absent returns the namespace unchanged; otherwise a
+ * parsed positive integer (see `parseListOperation` for what a negative or
+ * zero value did here).
+ *
+ * Returns: the namespace, truncated from the end; shorter than `maxDepth` is
+ * returned whole.
+ *
+ * Throws: nothing.
+ */
+function truncateDepth(namespace, maxDepth) {
+    return maxDepth === undefined ? namespace : namespace.slice(0, maxDepth);
+}
+/**
+ * Leading concrete (non-wildcard) elements of the first prefix condition.
+ *
+ * Accepts: `conditions` — absent, empty, suffix-only, or a prefix condition
+ * starting with `'*'` all yield nothing to scope by.
+ *
+ * Returns: the concrete leading elements, which name a partition and a sort-key
+ * prefix the listing can be read from. An empty result means the listing cannot
+ * be scoped to one partition and falls back to a Scan.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: the root is only ever a *superset* of what the conditions select
+ * — every condition is still applied to each namespace read — so scoping can
+ * never drop a namespace that belongs in the answer.
+ */
+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;
+}
+function namespaceSource(context, op, now) {
+    const root = prefixRoot(op.matchConditions);
     if (root.length > 0) {
         return (0, paginate_1.paginateQuery)({
+            retry: context.retry,
             client: context.client,
-            params: (0, query_1.scopedQuery)(context.tableName, root),
+            params: (0, table_schema_1.withoutExpired)((0, rows_1.projectKeys)((0, rows_1.scopedQuery)(context.tableName, root)), now),
             maxItems: context.maxScanItems,
         });
     }
-    return (0, scan_1.paginateScan)({
+    return (0, paginate_1.paginateScan)({
+        retry: context.retry,
         client: context.client,
-        params: (0, query_1.storeScan)(context.tableName),
+        params: (0, table_schema_1.withoutExpired)((0, rows_1.projectKeys)((0, rows_1.storeScan)(context.tableName)), now),
         maxItems: context.maxScanItems,
     });
 }
 /**
- * List distinct namespaces (truncated to `maxDepth`) that satisfy every match
- * condition, sorted, with offset/limit applied. A concrete prefix root scopes
- * the read to a native Query; otherwise it falls back to a filtered Scan.
+ * The collation namespaces are sorted by, pinned to one locale.
+ *
+ * `InMemoryStore` sorts with bare `localeCompare`
+ * (`@langchain/langgraph-checkpoint@1.1.5` `dist/store/memory.js:119`), which
+ * means "in the host's default locale" — and locales disagree: `'ä'` sorts
+ * before `'z'` in German and after it in Swedish. A listing paged by `offset`
+ * is a position a caller holds between two calls, so an order that changes
+ * with the host answering the call cuts the same listing in two places and the
+ * caller misses one namespace and sees another twice. Matching the reference
+ * there is not possible anyway, because the reference's own order varies with
+ * its host; what is possible is matching it on every host that agrees with
+ * this locale, and being deterministic on the rest.
+ *
+ * `en` is the locale to pin because ICU applies no tailoring to it — its order
+ * is the untailored root order — and because it is the one locale a Node built
+ * with small ICU still carries, so this cannot degrade to a different order on
+ * a minimal runtime.
+ */
+const NAMESPACE_COLLATOR = new Intl.Collator('en');
+/**
+ * Order two namespaces by the reference store's collation, pinned, with its
+ * ties settled.
+ *
+ * The collation is {@link NAMESPACE_COLLATOR} on the joined namespace — the
+ * comparison `InMemoryStore` makes, held to one locale. Collation calls some
+ * *distinct* strings equal — `'café'` written precomposed and decomposed is
+ * one such pair — and the reference then leaves their order to insertion
+ * order. Here that would be the order DynamoDB happened to return the rows in,
+ * so the same listing could place a page boundary between them differently on
+ * two calls and a page could skip one namespace while repeating another. The
+ * tie-break settles exactly those pairs and never reorders a pair the
+ * collation itself orders.
+ */
+function compareNamespaces(a, b) {
+    const left = a.join(table_schema_1.KEY_SEPARATOR);
+    const right = b.join(table_schema_1.KEY_SEPARATOR);
+    const collated = NAMESPACE_COLLATOR.compare(left, right);
+    // `Number(left > right)` keeps the comparator total: 0 for a pair that really is equal.
+    return collated !== 0 ? collated : left < right ? -1 : Number(left > right);
+}
+/**
+ * The distinct namespaces satisfying every match condition.
+ *
+ * Accepts: `op` — parsed; every match condition must hold, absent or empty
+ * matches every namespace. A concrete prefix root scopes the read to one
+ * partition's Query, and anything else — a suffix condition, a leading `*`, no
+ * conditions — spans the table and is one of the four reads allowed to Scan
+ * (`test/static/guards/scan-sites.ts`).
+ * `op.maxDepth` — namespaces are truncated to it and then
+ * deduplicated, so `['a','b']` and `['a','c']` list once as `['a']`.
+ * `op.offset` and `op.limit` — a `limit` of 0 returns an empty listing without reading.
+ *
+ * Returns: the namespaces, sorted, then `limit` of them from `offset`.
+ *
+ * Throws: `RESULT_TRUNCATED` when `maxScanItems` is reached while rows
+ * remain, so a partial listing is never returned as a complete one;
+ * `FORMAT_UNSUPPORTED` for a store item a newer release wrote.
+ *
+ * Guarantees: every live row is read — the answer is about which namespaces
+ * exist, and paging over it must not depend on which rows were read first. That
+ * is also why the sort is total (see {@link compareNamespaces}), and why a
+ * `limit` of 0 is answered ahead of the read rather than by slicing one.
  */
 async function listNamespaces(context, op) {
-    (0, validation_1.validatePaging)(op.offset, op.limit);
-    (0, validation_1.validateMaxDepth)(op.maxDepth);
+    // A zero page is answered before the read. This listing is the one that can
+    // never stop early — every live row must be seen before the namespaces can
+    // be sorted and sliced — so scanning the whole table to slice nothing out of
+    // it is the entire cost for none of the answer.
+    if (op.limit === 0)
+        return [];
+    const now = (0, clock_1.nowSeconds)();
     const seen = new Set();
     const namespaces = [];
-    for await (const raw of namespaceSource(context, op)) {
-        const record = (0, item_mapper_1.narrowStoreRecord)(raw);
-        if (!record)
+    for await (const raw of namespaceSource(context, op, now)) {
+        const record = (0, rows_1.parseStoreRow)(raw);
+        if (!record || (0, table_schema_1.isExpiredRow)(record, now))
             continue;
         const namespace = record.namespace;
         if (op.matchConditions &&
-            !op.matchConditions.every((condition) => (0, namespace_match_1.matchNamespace)(namespace, condition))) {
+            !op.matchConditions.every((condition) => matchNamespace(namespace, condition))) {
             continue;
         }
-        const truncated = (0, namespace_match_1.truncateDepth)(namespace, op.maxDepth);
-        const dedupeKey = truncated.join(keys_1.NAMESPACE_SEPARATOR);
+        const truncated = truncateDepth(namespace, op.maxDepth);
+        const dedupeKey = truncated.join(table_schema_1.KEY_SEPARATOR);
         if (seen.has(dedupeKey))
             continue;
         seen.add(dedupeKey);
         namespaces.push(truncated);
     }
-    namespaces.sort((a, b) => a.join(keys_1.NAMESPACE_SEPARATOR).localeCompare(b.join(keys_1.NAMESPACE_SEPARATOR)));
+    namespaces.sort(compareNamespaces);
     return namespaces.slice(op.offset, op.offset + op.limit);
 }
-//# sourceMappingURL=list-namespaces.js.map

package/dist/store/actions/put.d.ts

@@ -1,11 +1,36 @@
-import type { PutOperation } from '@langchain/langgraph-checkpoint';
+/**
+ * Hides the order a put happens in.
+ *
+ * A put reads the row it replaces for its `createdAt`, embeds once — a vector
+ * per extracted path onto the row, or one vector for the `vectorBackend`,
+ * never both — writes the row, and only then syncs the backend, best-effort.
+ * A `null` value takes the delete path instead. A caller hands over an item;
+ * that the table commits first and the vector copy follows is decided here.
+ */
+import type { ParsedDelete, ParsedPut } from '../internal/parse';
 import type { StoreContext } from '../internal/setup';
 /**
- * Store, update, or delete an item (null deletes). The value is encoded
- * (optional compression/S3 offload, nonced per call so a failed write can never
- * delete the previous payload) and `createdAt` is preserved across updates; a
- * computed embedding is sent to a configured `vectorBackend` instead of being
- * stored on the item — DynamoDB always holds the canonical item.
+ * Store, update or delete an item.
+ *
+ * Accepts: `op` — parsed; a `ParsedDelete` removes the item, a `ParsedPut` is
+ * stored, its value encoded with optional compression and S3 offload under
+ * this row's own path, in an object named by this put's own id. `op.index` —
+ * `false` stores the item without indexing it and clears any vector it had, an
+ * array overrides the configured fields for this put, and absent uses the
+ * store's configuration.
+ *
+ * Returns: nothing. Deleting an item that is not there is not an error.
+ *
+ * Throws: `VALIDATION` naming `value` for a value that JSON cannot represent —
+ * refused at the write rather than stored as a row that can never be read back;
+ * `S3_OFFLOAD_FAILED`; whatever the write throws.
+ *
+ * Guarantees: DynamoDB holds the canonical item — the vector index is synced
+ * afterwards and best-effort, so a backend outage never fails a put or leaves a
+ * half-written item. `createdAt` survives every update. The superseded payload
+ * is deleted only once the new row is committed, and this put's own upload
+ * only once a read proves its write did not land. Neither release reads the
+ * row first: each put uploads under a key ending in an id of its own, so the
+ * object a put uploads is named only by that put's own rows.
  */
-export declare function putItem(context: StoreContext, op: PutOperation): Promise<void>;
-//# sourceMappingURL=put.d.ts.map
+export declare function putItem(context: StoreContext, op: ParsedPut | ParsedDelete): Promise<void>;

package/dist/store/actions/put.js

@@ -1,85 +1,78 @@
 "use strict";
+/**
+ * Hides the order a put happens in.
+ *
+ * A put reads the row it replaces for its `createdAt`, embeds once — a vector
+ * per extracted path onto the row, or one vector for the `vectorBackend`,
+ * never both — writes the row, and only then syncs the backend, best-effort.
+ * A `null` value takes the delete path instead. A caller hands over an item;
+ * that the table commits first and the vector copy follows is decided here.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.putItem = putItem;
 const node_crypto_1 = require("node:crypto");
 const clock_1 = require("../../shared/clock");
-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 ttl_1 = require("../../shared/validation/ttl");
-const index_sync_1 = require("../internal/index-sync");
-const item_mapper_1 = require("../internal/item-mapper");
-const keys_1 = require("../internal/keys");
-const persist_1 = require("../internal/persist");
-const read_existing_1 = require("../internal/read-existing");
+const item_write_1 = require("../internal/item-write");
+const rows_1 = require("../internal/rows");
 const semantic_search_1 = require("../internal/semantic-search");
-const validation_1 = require("../internal/validation");
-const write_verify_1 = require("../internal/write-verify");
+const vector_index_1 = require("../internal/vector-index");
 /**
- * Delete the item and, when a vector backend is configured, drop its vector.
- *
- * A retry-exhausted failure is *ambiguous*: the delete may have landed
- * server-side with only its acknowledgement lost. Mirroring `persistRecord`'s
- * treatment of an ambiguous put, that case is resolved with a
- * strongly-consistent read — if the row is genuinely gone the delete
- * succeeded, so the S3-orphan cleanup and the vector-backend delete must still
- * run rather than being skipped for a write that actually happened. Any other
- * failure, or a row still present, propagates unchanged.
+ * The vectors a put stores on the row: one per extracted path, scored by best
+ * match on read. Not computed when a `vectorBackend` holds the vectors, which
+ * takes a single vector per item instead (see {@link itemVector}).
  */
-async function deleteStoreItem(context, op, pk, sk) {
-    const existing = context.offloader ? await (0, read_existing_1.readExisting)(context, pk, sk) : undefined;
-    try {
-        await (0, retry_1.withDynamoDBRetry)(() => context.client.delete({ TableName: context.tableName, Key: { PK: pk, SK: sk } }));
-    }
-    catch (error) {
-        const landed = (0, write_verify_1.isRetryExhausted)(error) && (await (0, write_verify_1.rowIsAbsent)(context, { PK: pk, SK: sk }));
-        if (!landed)
-            throw error;
-    }
-    if (context.offloader) {
-        await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)(existing?.value ? [existing.value] : []), 'store.delete', context.logger);
-    }
-    if (context.vectorBackend) {
-        await (0, index_sync_1.syncVectorIndex)(context.vectorBackend, op.namespace, op.key, undefined, context.logger);
-    }
-}
-/** Compute the embedding for a put, honoring `op.index` (false disables it). */
-async function resolveEmbedding(context, op, value) {
+async function resolvePassages(context, op, value) {
     if (op.index === false)
         return undefined;
-    return (0, semantic_search_1.embedValue)(context, value, Array.isArray(op.index) ? op.index : undefined);
+    return (0, semantic_search_1.embedPassages)(context, value, op.index);
 }
 /**
- * Store, update, or delete an item (null deletes). The value is encoded
- * (optional compression/S3 offload, nonced per call so a failed write can never
- * delete the previous payload) and `createdAt` is preserved across updates; a
- * computed embedding is sent to a configured `vectorBackend` instead of being
- * stored on the item — DynamoDB always holds the canonical item.
+ * Store, update or delete an item.
+ *
+ * Accepts: `op` — parsed; a `ParsedDelete` removes the item, a `ParsedPut` is
+ * stored, its value encoded with optional compression and S3 offload under
+ * this row's own path, in an object named by this put's own id. `op.index` —
+ * `false` stores the item without indexing it and clears any vector it had, an
+ * array overrides the configured fields for this put, and absent uses the
+ * store's configuration.
+ *
+ * Returns: nothing. Deleting an item that is not there is not an error.
+ *
+ * Throws: `VALIDATION` naming `value` for a value that JSON cannot represent —
+ * refused at the write rather than stored as a row that can never be read back;
+ * `S3_OFFLOAD_FAILED`; whatever the write throws.
+ *
+ * Guarantees: DynamoDB holds the canonical item — the vector index is synced
+ * afterwards and best-effort, so a backend outage never fails a put or leaves a
+ * half-written item. `createdAt` survives every update. The superseded payload
+ * is deleted only once the new row is committed, and this put's own upload
+ * only once a read proves its write did not land. Neither release reads the
+ * row first: each put uploads under a key ending in an id of its own, so the
+ * object a put uploads is named only by that put's own rows.
  */
 async function putItem(context, op) {
-    (0, validation_1.validateNamespace)(op.namespace);
-    (0, validation_1.validateKey)(op.key);
-    const pk = (0, keys_1.partitionKey)(op.namespace);
-    const sk = (0, keys_1.sortKey)(op.namespace, op.key);
-    if (op.value === null) {
-        await deleteStoreItem(context, op, pk, sk);
+    if (op.kind === 'delete') {
+        await (0, item_write_1.deleteStoreItem)(context, op.address);
         return;
     }
+    const { namespace, key } = op.address;
     const value = op.value;
     const timestamp = (0, clock_1.nowIso)();
-    const existing = await (0, read_existing_1.readExisting)(context, pk, sk);
-    const embedding = await resolveEmbedding(context, op, value);
+    const existing = await (0, rows_1.readExisting)(context, (0, rows_1.itemRowKey)(op.address));
+    // The two indexing modes are exclusive, so only one of them embeds: the row
+    // carries a vector per extracted path, while a configured backend takes one
+    // vector per item because that is what its `upsert` contract addresses.
+    const embedding = await (0, vector_index_1.itemVector)(context, op);
+    const embeddings = context.vectorBackend ? undefined : await resolvePassages(context, op, value);
     const ttlTimestamp = context.ttl ? (0, ttl_1.calculateTtlTimestamp)(context.ttl) : undefined;
-    const record = await (0, item_mapper_1.buildStoreItem)(context, op.namespace, op.key, value, {
+    const record = await (0, rows_1.buildStoreRow)(context, { namespace, key }, value, {
         createdAt: existing.createdAt ?? timestamp,
         updatedAt: timestamp,
-        embedding: context.vectorBackend ? undefined : embedding,
+        embeddings,
         ttlTimestamp,
-        nonce: (0, node_crypto_1.randomUUID)(),
+        rev: (0, node_crypto_1.randomUUID)(),
     });
-    await (0, persist_1.persistRecord)(context, record, existing);
-    if (context.vectorBackend) {
-        await (0, index_sync_1.syncVectorIndex)(context.vectorBackend, op.namespace, op.key, embedding, context.logger);
-    }
+    await (0, item_write_1.persistRow)(context, record, existing);
+    await (0, vector_index_1.syncItemVector)(context, op.address, embedding);
 }
-//# sourceMappingURL=put.js.map