effect-dynamodb 1.0.0 → 1.2.0

package/dist/Entity.js

@@ -11,6 +11,7 @@ import { DynamoClient } from "./DynamoClient.js";
 import { getEncoding, getIdentifierField, isConfiguredModel, isHidden, isRef, isRefField, } from "./DynamoModel.js";
 import * as DynamoSchema from "./DynamoSchema.js";
 import { CascadePartialFailure, ConditionalCheckFailed, ItemNotFound, isAwsConditionalCheckFailed, isAwsTransactionCancelled, OptimisticLockError, RefNotFound, TransactionOverflow, UniqueConstraintViolation, ValidationError, } from "./Errors.js";
+import { makeBoundDelete, makeBoundPut, makeBoundUpdate } from "./internal/BoundCrud.js";
 import { BoundQueryImpl } from "./internal/BoundQuery.js";
 import { compileExpr, createConditionOps, isExpr, parseShorthand, parseSimpleShorthand, } from "./internal/Expr.js";
 import { compilePath, createPathBuilder } from "./internal/PathBuilder.js";
@@ -100,7 +101,7 @@ const makeImpl = (config) => {
     const isSchemaClass = typeof rawModel === "function";
     const modelFields = getFields(rawModel);
     const hasHiddenFields = Object.values(modelFields).some(isHidden);
-    const systemFields = resolveSystemFields(config.timestamps, config.versioned);
+    const systemFields = resolveSystemFields(config.timestamps, config.versioned, config.timeSeries);
     // ---------------------------------------------------------------------------
     // Validate indexes
     // ---------------------------------------------------------------------------
@@ -123,6 +124,82 @@ const makeImpl = (config) => {
             }
         }
     }
+    // ---------------------------------------------------------------------------
+    // Validate timeSeries config (EDD-9010..9016)
+    // ---------------------------------------------------------------------------
+    if (config.timeSeries !== undefined && config.timeSeries !== null) {
+        const ts = config.timeSeries;
+        const orderBy = ts.orderBy;
+        // EDD-9010: orderBy must name a model field
+        if (!(orderBy in modelFields)) {
+            throw new Error(`[EDD-9010] Entity "${config.entityType}": timeSeries.orderBy "${orderBy}" does not name a model field. ` +
+                `Valid model fields: ${Object.keys(modelFields).sort().join(", ")}`);
+        }
+        // EDD-9011: orderBy must not be a primary-key composite (PK or SK)
+        const primary = config.indexes.primary;
+        const pkSkComposites = new Set([...primary.pk.composite, ...primary.sk.composite]);
+        if (pkSkComposites.has(orderBy)) {
+            throw new Error(`[EDD-9011] Entity "${config.entityType}": timeSeries.orderBy "${orderBy}" must not appear ` +
+                `in the primary key pk or sk composite — it shadows the #e# event-SK infix.`);
+        }
+        // EDD-9012: mutually exclusive with versioned
+        if (config.versioned !== undefined && config.versioned !== null && config.versioned !== false) {
+            throw new Error(`[EDD-9012] Entity "${config.entityType}": timeSeries and versioned are mutually exclusive. ` +
+                `Pick one consistency model per entity.`);
+        }
+        // EDD-9015: mutually exclusive with softDelete
+        if (config.softDelete !== undefined &&
+            config.softDelete !== null &&
+            config.softDelete !== false) {
+            throw new Error(`[EDD-9015] Entity "${config.entityType}": timeSeries and softDelete are mutually exclusive. ` +
+                `Append on a soft-deleted item would land on a new empty row — not a sound resurrection model.`);
+        }
+        // EDD-9016: appendInput is required
+        if (ts.appendInput === undefined || ts.appendInput === null) {
+            throw new Error(`[EDD-9016] Entity "${config.entityType}": timeSeries.appendInput is required. ` +
+                `Define a Schema.Struct whose fields are the subset of the model allowed in .append() input. ` +
+                `Fields outside appendInput are preserved on the current item — this is the enrichment-preservation guarantee. ` +
+                `To opt out (dangerous), pass the full model schema explicitly.`);
+        }
+        const appendInputFields = (() => {
+            const ai = ts.appendInput;
+            if ("fields" in ai && typeof ai.fields === "object") {
+                return Object.keys(ai.fields);
+            }
+            throw new Error(`[EDD-9016] Entity "${config.entityType}": timeSeries.appendInput must be a Schema.Struct or Schema.Class (.fields required).`);
+        })();
+        const appendInputFieldSet = new Set(appendInputFields);
+        // EDD-9013: appendInput must include orderBy + all PK/SK composites
+        if (!appendInputFieldSet.has(orderBy)) {
+            throw new Error(`[EDD-9013] Entity "${config.entityType}": timeSeries.appendInput must include orderBy "${orderBy}". ` +
+                `Without it .append() cannot evaluate the CAS condition.`);
+        }
+        for (const composite of pkSkComposites) {
+            if (!appendInputFieldSet.has(composite)) {
+                throw new Error(`[EDD-9013] Entity "${config.entityType}": timeSeries.appendInput missing primary-key composite "${composite}". ` +
+                    `Every PK/SK composite must appear in appendInput so the event can be addressed.`);
+            }
+        }
+        // EDD-9014: orderBy must not name a ref field or ref-derived ${name}Id field
+        for (const fieldName of Object.keys(modelFields)) {
+            if (isRefField(fieldName, config.model)) {
+                if (orderBy === fieldName || orderBy === `${fieldName}Id`) {
+                    throw new Error(`[EDD-9014] Entity "${config.entityType}": timeSeries.orderBy "${orderBy}" names a ref ` +
+                        `or ref-derived id field. Refs are create-time denormalisations and cannot serve as the event clock.`);
+                }
+            }
+        }
+        // Also: appendInput must not declare any ref-derived ${name}Id field —
+        // ref changes go through .update(), not .append() (§4.6).
+        for (const fieldName of Object.keys(modelFields)) {
+            if (isRefField(fieldName, config.model)) {
+                if (appendInputFieldSet.has(`${fieldName}Id`)) {
+                    throw new Error(`[EDD-9014] Entity "${config.entityType}": timeSeries.appendInput must not include ref-derived ` +
+                        `"${fieldName}Id" — refs cannot be reassigned via .append(). Use .update() to change a ref.`);
+                }
+            }
+        }
+    }
     const resolvedRefs = config.refs
         ? Object.entries(config.refs).map(([fieldName, refValue]) => {
             // Extract entity from shorthand or expanded form
@@ -182,7 +259,7 @@ const makeImpl = (config) => {
     }
     // Resolve identifier field name from model annotation
     const resolvedIdentifier = getIdentifierField(config.model)?.name;
-    const schemas = buildDerivedSchemas(modelFields, allIndexes, systemFields, resolvedRefs, immutableFields, resolvedIdentifier);
+    const schemas = buildDerivedSchemas(modelFields, allIndexes, systemFields, resolvedRefs, immutableFields, resolvedIdentifier, config.timeSeries);
     // schema and tableTag are injected via _configure() when the entity is registered
     // on a Table and bound through DynamoClient.make(). They are captured by operation
     // closures and resolved at runtime (inside Effects), not at definition time.
@@ -1137,46 +1214,6 @@ const makeImpl = (config) => {
             setClauses.push(`${nameKey} = ${valKey}`);
             counter++;
         }
-        // Shared sets for GSI removal detection (used by both compose and REMOVE)
-        const removedSet = uState.remove ? new Set(uState.remove) : undefined;
-        const pkCompositeSet = new Set(primaryKeyComposites(config.indexes));
-        // Compose GSI keys for indexes whose composites are in the update,
-        // filtering out any GSI whose composites are targeted by REMOVE
-        const indexesForGsiUpdate = removedSet
-            ? (() => {
-                const filtered = {};
-                for (const [indexName, indexDef] of Object.entries(allIndexes)) {
-                    if (!("index" in indexDef)) {
-                        filtered[indexName] = indexDef;
-                        continue;
-                    }
-                    const gsiComposites = [...indexDef.pk.composite, ...indexDef.sk.composite].filter((attr) => !pkCompositeSet.has(attr));
-                    if (!gsiComposites.some((attr) => removedSet.has(attr))) {
-                        filtered[indexName] = indexDef;
-                    }
-                }
-                return filtered;
-            })()
-            : allIndexes;
-        let gsiKeys;
-        try {
-            gsiKeys = KeyComposer.composeGsiKeysForUpdate(schema, entityType, entityVersion, indexesForGsiUpdate, hydratedUpdates, decodedKey);
-        }
-        catch (e) {
-            return yield* new ValidationError({
-                entityType,
-                operation: "update.gsiComposites",
-                cause: e instanceof Error ? e.message : e,
-            });
-        }
-        for (const [field, value] of Object.entries(gsiKeys)) {
-            const nameKey = `#u${counter}`;
-            const valKey = `:u${counter}`;
-            names[nameKey] = field;
-            values[valKey] = toAttributeValue(value);
-            setClauses.push(`${nameKey} = ${valKey}`);
-            counter++;
-        }
         // Add updatedAt timestamp (encoding-aware)
         if (systemFields.updatedAt) {
             const nameKey = `#u${counter}`;
@@ -1221,6 +1258,7 @@ const makeImpl = (config) => {
             }
         }
         // REMOVE
+        const removedSet = uState.remove ? new Set(uState.remove) : undefined;
         if (uState.remove) {
             for (const attr of uState.remove) {
                 const nameKey = `#r${removeClauses.length}`;
@@ -1228,22 +1266,23 @@ const makeImpl = (config) => {
                 removeClauses.push(nameKey);
             }
         }
-        // Cascade REMOVE to GSI key fields: when a removed attribute is a GSI
-        // composite, the GSI pk/sk fields must also be removed so the item drops
-        // out of the sparse index.
-        if (removedSet) {
-            for (const [, indexDef] of Object.entries(allIndexes)) {
-                if (!("index" in indexDef))
-                    continue;
-                const gsiComposites = [...indexDef.pk.composite, ...indexDef.sk.composite].filter((attr) => !pkCompositeSet.has(attr));
-                if (gsiComposites.some((attr) => removedSet.has(attr))) {
-                    for (const keyField of [indexDef.pk.field, indexDef.sk.field]) {
-                        const nameKey = `#r${removeClauses.length}`;
-                        names[nameKey] = keyField;
-                        removeClauses.push(nameKey);
-                    }
-                }
-            }
+        // Policy-aware GSI key composition. One call covers SETs (full
+        // recompose or half-wise), sparse dropout REMOVEs, and cascade
+        // REMOVEs when an Entity.remove() targets a GSI composite.
+        // See DESIGN.md §7 Policy-Aware GSI Composition.
+        const gsiUpdate = KeyComposer.composeGsiKeysForUpdatePolicyAware(schema, entityType, entityVersion, allIndexes, hydratedUpdates, decodedKey, { removedSet });
+        for (const [field, value] of Object.entries(gsiUpdate.sets)) {
+            const nameKey = `#u${counter}`;
+            const valKey = `:u${counter}`;
+            names[nameKey] = field;
+            values[valKey] = toAttributeValue(value);
+            setClauses.push(`${nameKey} = ${valKey}`);
+            counter++;
+        }
+        for (const keyField of gsiUpdate.removes) {
+            const nameKey = `#r${removeClauses.length}`;
+            names[nameKey] = keyField;
+            removeClauses.push(nameKey);
         }
         // ADD (atomic numeric increment / set addition)
         if (uState.add) {
@@ -1727,6 +1766,292 @@ const makeImpl = (config) => {
         return yield* decodeAs(raw, result.Attributes, mode);
     }), self, input);
     // ---------------------------------------------------------------------------
+    // append operation — time-series primitive (only when `timeSeries` configured)
+    //
+    // Two-item `TransactWriteItems`:
+    //  - UpdateItem on current: scoped SET (appendInput fields only) + CAS on
+    //    `orderBy`, with GSI keys recomposed when any appendInput field is a
+    //    GSI composite. `createdAt` uses if_not_exists on first append.
+    //  - Put of event: full decoded input + __edd_e__ + _ttl (if configured),
+    //    GSI keys stripped, SK replaced with `<currentSk>#e#<orderByValue>`.
+    //
+    // On TransactionCancelled or ConditionalCheckFailed, we issue a follow-up
+    // GetItem on the primary key and return `{ applied: false, reason: "stale",
+    // current }`. On success, same follow-up GetItem yields the post-append
+    // current. See `docs/designs/timeseries.md` §4.
+    // ---------------------------------------------------------------------------
+    const timeSeriesConfig = config.timeSeries;
+    const append = (input, userCondition) => Effect.gen(function* () {
+        if (!timeSeriesConfig) {
+            return yield* new ValidationError({
+                entityType,
+                operation: "append",
+                cause: "Entity is not configured with timeSeries. .append() requires timeSeries config.",
+            });
+        }
+        const client = yield* DynamoClient;
+        const { name: tableName } = yield* tableTag;
+        const orderByField = timeSeriesConfig.orderBy;
+        const ttlDuration = timeSeriesConfig.ttl;
+        const appendInputSchema = schemas.appendInputSchema;
+        // Decode input via appendInputSchema
+        const decodedInput = yield* Schema.decodeUnknownEffect(appendInputSchema)(input).pipe(Effect.mapError((cause) => new ValidationError({
+            entityType,
+            operation: "append.decode",
+            cause,
+        })));
+        const decoded = decodedInput;
+        // Compose current-item primary key (pk + sk derived from PK/SK composites in decoded)
+        const primary = config.indexes.primary;
+        const pkValue = KeyComposer.composePk(schema, entityType, primary, decoded);
+        const currentSk = KeyComposer.composeSk(schema, entityType, entityVersion, primary, decoded);
+        const marshalledKey = toAttributeMap({
+            [primary.pk.field]: pkValue,
+            [primary.sk.field]: currentSk,
+        });
+        // Prepare domain-serialised values for the item build.
+        // Build a shallow copy and apply date serialization (per fieldEncodings)
+        // before marshalling. This mirrors the put path.
+        const serialisedInput = { ...decoded };
+        serializeDateFields(serialisedInput);
+        // ---------- Build UpdateItem (scoped SET + CAS) ----------
+        const setClauses = [];
+        const names = {};
+        const values = {};
+        let counter = 0;
+        // Only fields named in appendInput (the serialisedInput object). This is
+        // the enrichment-preservation contract — fields outside appendInput are
+        // never touched. PK composites ARE included: they're stored as regular
+        // attributes on the item (mirrors `.put()`), and though their values
+        // never change, writing them on every append makes the first append
+        // (where the row doesn't yet exist) materialise the row correctly.
+        const pkCompositeSet = new Set(primaryKeyComposites(config.indexes));
+        for (const [attr, val] of Object.entries(serialisedInput)) {
+            if (val === undefined)
+                continue;
+            const nameKey = `#a${counter}`;
+            const valKey = `:a${counter}`;
+            names[nameKey] = resolveDbName(attr);
+            values[valKey] = toAttributeValue(val);
+            setClauses.push(`${nameKey} = ${valKey}`);
+            counter++;
+        }
+        // GSI key recomposition: any GSI whose composites are touched by input.
+        // Reuses the policy-aware helper from `.update()`. PK composites are
+        // excluded from the update payload — they're already in the key and
+        // never change during an append. Non-PK composites in appendInput that
+        // overlap a GSI's composites trigger per-GSI resolution via indexPolicy.
+        const nonPkAppendFields = {};
+        for (const [attr, val] of Object.entries(decoded)) {
+            if (!pkCompositeSet.has(attr)) {
+                nonPkAppendFields[attr] = val;
+            }
+        }
+        // At append-time, indexPolicy is restricted to composites that are
+        // members of appendInput. Non-appendInput composites are owned by
+        // other writers and are by contract never touched by .append(); their
+        // policy cannot fire at append-time. Each GSI's indexPolicy return is
+        // filtered to appendInput attrs only — non-appendInput keys fall through
+        // to the implicit `"preserve"` default, leaving the half containing
+        // them untouched.
+        const appendInputFieldSet = new Set(Object.keys(appendInputSchema
+            .fields ?? {}));
+        const policyAwareIndexes = {};
+        for (const [indexName, indexDef] of Object.entries(allIndexes)) {
+            if (!indexDef.indexPolicy) {
+                policyAwareIndexes[indexName] = indexDef;
+                continue;
+            }
+            const originalPolicy = indexDef.indexPolicy;
+            policyAwareIndexes[indexName] = {
+                ...indexDef,
+                indexPolicy: (item) => {
+                    const raw = originalPolicy(item);
+                    const filtered = {};
+                    for (const [attr, policy] of Object.entries(raw)) {
+                        if (appendInputFieldSet.has(attr) && policy !== undefined) {
+                            filtered[attr] = policy;
+                        }
+                    }
+                    return filtered;
+                },
+            };
+        }
+        const gsiUpdate = KeyComposer.composeGsiKeysForUpdatePolicyAware(schema, entityType, entityVersion, policyAwareIndexes, nonPkAppendFields, decoded);
+        for (const [field, value] of Object.entries(gsiUpdate.sets)) {
+            const nameKey = `#a${counter}`;
+            const valKey = `:a${counter}`;
+            names[nameKey] = field;
+            values[valKey] = toAttributeValue(value);
+            setClauses.push(`${nameKey} = ${valKey}`);
+            counter++;
+        }
+        const appendRemoveClauses = [];
+        for (const keyField of gsiUpdate.removes) {
+            const nameKey = `#a${counter}`;
+            names[nameKey] = keyField;
+            appendRemoveClauses.push(nameKey);
+            counter++;
+        }
+        // Entity type discriminator — idempotent; ensures existing items
+        // without __edd_e__ still get tagged on first append.
+        {
+            const nameKey = `#a${counter}`;
+            const valKey = `:a${counter}`;
+            names[nameKey] = "__edd_e__";
+            values[valKey] = toAttributeValue(entityType);
+            setClauses.push(`${nameKey} = ${valKey}`);
+            counter++;
+        }
+        // createdAt (if configured) — if_not_exists so subsequent appends leave it alone
+        if (systemFields.createdAt) {
+            const nameKey = `#a${counter}`;
+            const valKey = `:a${counter}`;
+            names[nameKey] = systemFields.createdAt;
+            values[valKey] = toAttributeValue(generateTimestamp(systemFields.createdAtEncoding));
+            setClauses.push(`${nameKey} = if_not_exists(${nameKey}, ${valKey})`);
+            counter++;
+        }
+        // CAS condition: attribute_not_exists(#pk) OR #ob < :newOb
+        names["#_tspk"] = primary.pk.field;
+        names["#_tsob"] = resolveDbName(orderByField);
+        // The comparison uses the stored domain-value representation — for
+        // DateTime.Utc this is ISO (lexicographic == chronological), for numbers
+        // it's numeric, for strings it's lexicographic. Matches how the current
+        // item stores `orderByField`.
+        const newObValue = serialisedInput[orderByField];
+        values[":_tsNewOb"] = toAttributeValue(newObValue);
+        const casCondition = "attribute_not_exists(#_tspk) OR #_tsob < :_tsNewOb";
+        let finalCondition = casCondition;
+        if (userCondition !== undefined) {
+            const uc = compileCondition(userCondition, resolveDbName);
+            finalCondition = `(${casCondition}) AND (${uc.expression})`;
+            Object.assign(names, uc.names);
+            Object.assign(values, uc.values);
+        }
+        const exprParts = [];
+        if (setClauses.length > 0)
+            exprParts.push(`SET ${setClauses.join(", ")}`);
+        if (appendRemoveClauses.length > 0)
+            exprParts.push(`REMOVE ${appendRemoveClauses.join(", ")}`);
+        const updateExpression = exprParts.join(" ");
+        // ---------- Build Put of event item ----------
+        const eventSk = KeyComposer.composeEventSk(currentSk, newObValue, schema.casing);
+        const eventItem = { ...decoded };
+        // Serialise date fields to storage format for the Put
+        serializeDateFields(eventItem);
+        // Rename domain → DB names for the Put (matches put path)
+        renameToDynamo(eventItem);
+        // pk + sk (event)
+        eventItem[primary.pk.field] = pkValue;
+        eventItem[primary.sk.field] = eventSk;
+        // __edd_e__
+        eventItem.__edd_e__ = entityType;
+        // _ttl
+        if (ttlDuration) {
+            eventItem._ttl = Math.floor(Date.now() / 1000) + Duration.toSeconds(ttlDuration);
+        }
+        // Events never participate in indexes: strip any GSI key fields that the
+        // naive spread above may have carried over. gsiKeys weren't written into
+        // eventItem (only decoded fields are), but defensively clear them.
+        for (const field of gsiKeyFields()) {
+            delete eventItem[field];
+        }
+        const marshalledEventItem = toAttributeMap(eventItem);
+        // ---------- Execute TransactWriteItems ----------
+        const transactResult = yield* client
+            .transactWriteItems({
+            TransactItems: [
+                {
+                    Update: {
+                        TableName: tableName,
+                        Key: marshalledKey,
+                        UpdateExpression: updateExpression,
+                        ConditionExpression: finalCondition,
+                        ExpressionAttributeNames: names,
+                        ExpressionAttributeValues: values,
+                    },
+                },
+                {
+                    Put: {
+                        TableName: tableName,
+                        Item: marshalledEventItem,
+                    },
+                },
+            ],
+        })
+            .pipe(Effect.matchEffect({
+            onSuccess: () => Effect.succeed({ stale: false }),
+            onFailure: (err) => {
+                // TransactionCancelled or ConditionalCheckFailed at the transaction
+                // level both map to "stale" (can't distinguish CAS from user-cond
+                // in v1 — see §12 decision 5).
+                if (isAwsTransactionCancelled(err.cause) || isAwsConditionalCheckFailed(err.cause)) {
+                    return Effect.succeed({ stale: true });
+                }
+                return Effect.fail(err);
+            },
+        }));
+        // Follow-up GetItem to read the current (post-append on success, winning
+        // state on stale). One read is required either way — the contract
+        // returns `Model` which demands the full row including enrichment.
+        const followUp = yield* client.getItem({
+            TableName: tableName,
+            Key: marshalledKey,
+        });
+        if (!followUp.Item) {
+            // TTL race or out-of-band delete — surface as a DynamoClientError
+            // (the previous state vanished under us). This is NOT a stale result.
+            return yield* Effect.fail(new ValidationError({
+                entityType,
+                operation: "append.followUp",
+                cause: "Current item not found after append — possible TTL race or concurrent delete.",
+            }));
+        }
+        const rawCurrent = fromAttributeMap(followUp.Item);
+        const currentModel = yield* decodeAs(rawCurrent, followUp.Item, "model");
+        if (transactResult.stale) {
+            return {
+                applied: false,
+                reason: "stale",
+                current: currentModel,
+            };
+        }
+        return { applied: true, current: currentModel };
+    });
+    // ---------------------------------------------------------------------------
+    // history operation — BoundQuery for event items only
+    // ---------------------------------------------------------------------------
+    const history = (key) => {
+        if (!timeSeriesConfig) {
+            throw new Error(`[EDD-9010] Entity "${entityType}": .history() requires timeSeries config on the entity.`);
+        }
+        const decodedKey = Schema.decodeUnknownSync(schemas.keySchema)(key);
+        const primary = config.indexes.primary;
+        const pkValue = KeyComposer.composePk(schema, entityType, primary, decodedKey);
+        const currentSk = KeyComposer.composeSk(schema, entityType, entityVersion, primary, decodedKey);
+        const prefix = KeyComposer.composeEventSkPrefix(currentSk, schema.casing);
+        const decodeHistory = (raw) => {
+            renameFromDynamo(raw);
+            deserializeDateFields(raw);
+            return Schema.decodeUnknownEffect(schemas.historyRecordSchema)(raw).pipe(Effect.map(attachPrototype), Effect.mapError((cause) => new ValidationError({
+                entityType,
+                operation: "history.decode",
+                cause,
+            })));
+        };
+        return Query.make({
+            tableName: "",
+            indexName: undefined,
+            pkField: primary.pk.field,
+            pkValue,
+            skField: primary.sk.field,
+            entityTypes: [entityType],
+            decoder: (raw) => decodeHistory(raw),
+            resolveTableName: tableTag.useSync((tc) => tc.name),
+        }).pipe(Query.where({ beginsWith: prefix }));
+    };
+    // ---------------------------------------------------------------------------
     // query namespace
     // ---------------------------------------------------------------------------
     const queryNamespace = {};
@@ -2170,6 +2495,7 @@ const makeImpl = (config) => {
         softDelete: config.softDelete,
         unique: config.unique,
         identifier: resolvedIdentifier,
+        timeSeries: config.timeSeries,
         _resolvedRefs: resolvedRefs,
         /** @internal Full decode pipeline: rename + date deser + schema decode. Used by Batch/Aggregate. */
         _decodeRecord: decodeRecord,
@@ -2206,6 +2532,8 @@ const makeImpl = (config) => {
         restore,
         purge,
         deleted: { get: deletedGet, list: deletedList },
+        append,
+        history,
         set,
         expectedVersion,
         query: queryNamespace,
@@ -2238,26 +2566,12 @@ const makeImpl = (config) => {
 export const bind = (entity) => Effect.gen(function* () {
     const ctx = yield* Effect.context();
     const provide = (effect) => Effect.provide(effect, ctx);
-    // Helper: apply combinators to an EntityUpdate, then run in record mode + provide
-    const applyUpdate = (op, combinators) => {
-        let result = op;
-        for (const fn of combinators)
-            result = fn(result);
-        return provide(result._run("record"));
-    };
-    // Helper: apply combinators to an EntityPut, then run in record mode + provide
-    const applyPut = (op, combinators) => {
-        let result = op;
-        for (const fn of combinators)
-            result = fn(result);
-        return provide(result._run("record"));
-    };
-    // Helper: apply combinators to an EntityDelete, then asEffect + provide
-    const applyDelete = (op, combinators) => {
-        let result = op;
-        for (const fn of combinators)
-            result = fn(result);
-        return provide(result.asEffect());
+    // Shared config for the bound-CRUD builders — pre-resolved services plus
+    // a typed PathBuilder/ConditionOps so `.condition((t, ops) => ...)` works.
+    const boundCrudConfig = {
+        pathBuilder: createPathBuilder(),
+        conditionOps: createConditionOps(),
+        provide,
     };
     // Helper: apply query combinators then execute
     const applyQuery = (q, combinators) => {
@@ -2279,15 +2593,15 @@ export const bind = (entity) => Effect.gen(function* () {
         return new BoundQueryImpl(q, bqConfig);
     };
     return {
-        // CRUD — all ops return Effect (auto-wrapped)
+        // CRUD — fluent bound builders (yieldable, no .run() terminal)
         get: (key) => provide(entity.get(key)._run("record")),
-        put: (input, ...combinators) => applyPut(entity.put(input), combinators),
-        create: (input, ...combinators) => applyPut(entity.create(input), combinators),
-        update: (key, ...combinators) => applyUpdate(entity.update(key), combinators),
-        delete: (key, ...combinators) => applyDelete(entity.delete(key), combinators),
-        upsert: (input, ...combinators) => applyPut(entity.upsert(input), combinators),
-        patch: (key, ...combinators) => applyUpdate(entity.patch(key), combinators),
-        deleteIfExists: (key, ...combinators) => applyDelete(entity.deleteIfExists(key), combinators),
+        put: (input) => makeBoundPut(entity.put(input), boundCrudConfig),
+        create: (input) => makeBoundPut(entity.create(input), boundCrudConfig),
+        update: (key) => makeBoundUpdate(entity.update(key), boundCrudConfig),
+        delete: (key) => makeBoundDelete(entity.delete(key), boundCrudConfig),
+        upsert: (input) => makeBoundPut(entity.upsert(input), boundCrudConfig),
+        patch: (key) => makeBoundUpdate(entity.patch(key), boundCrudConfig),
+        deleteIfExists: (key) => makeBoundDelete(entity.deleteIfExists(key), boundCrudConfig),
         // Lifecycle
         getVersion: (key, version) => provide(entity.getVersion(key, version)._run("record")),
         versions: (key) => wrapAsBoundQuery(entity.versions(key)),
@@ -2297,6 +2611,53 @@ export const bind = (entity) => Effect.gen(function* () {
             get: (key) => provide(entity.deleted.get(key)._run("record")),
             list: (key) => wrapAsBoundQuery(entity.deleted.list(key)),
         },
+        // Time-series (no-ops when entity is not configured; runtime check in
+        // the entity-level `append` returns a ValidationError).
+        append: (input, condition) => provide(entity.append(input, condition)),
+        history: (key) => {
+            const q = entity.history(key);
+            const pathBuilder = createPathBuilder();
+            const conditionOps = createConditionOps();
+            const ts = entity.timeSeries;
+            const orderBy = ts?.orderBy;
+            const entityInternals = entity;
+            const schemaRef = entityInternals._schema;
+            const entityTypeRef = entityInternals.entityType;
+            // composeSkCondition: rewrite user's .where() values by prefixing
+            // with `<currentSk>#e#` and applying serialisation + casing to the
+            // user-supplied orderBy value.
+            const primary = entity.indexes.primary;
+            const composeSkCondition = (cond) => {
+                // We need the `currentSk` + prefix. The user's `key` lets us derive
+                // `currentSk` via the same primary SK composer used by `history()`.
+                const currentSk = KeyComposer.composeSk(schemaRef, entityTypeRef, 1, primary, key);
+                const prefix = KeyComposer.composeEventSkPrefix(currentSk, schemaRef.casing);
+                const rewrite = (v) => `${prefix}${DynamoSchema.applyCasing(KeyComposer.serializeValue(v), schemaRef.casing)}`;
+                if ("eq" in cond)
+                    return { eq: rewrite(cond.eq) };
+                if ("lt" in cond)
+                    return { lt: rewrite(cond.lt) };
+                if ("lte" in cond)
+                    return { lte: rewrite(cond.lte) };
+                if ("gt" in cond)
+                    return { gt: rewrite(cond.gt) };
+                if ("gte" in cond)
+                    return { gte: rewrite(cond.gte) };
+                if ("between" in cond)
+                    return { between: [rewrite(cond.between[0]), rewrite(cond.between[1])] };
+                if ("beginsWith" in cond)
+                    return { beginsWith: rewrite(cond.beginsWith) };
+                return cond;
+            };
+            const bqConfig = {
+                pathBuilder,
+                conditionOps,
+                provide,
+                skFields: orderBy ? [orderBy] : [],
+                composeSkCondition,
+            };
+            return new BoundQueryImpl(q, bqConfig);
+        },
         // Query execution
         paginate: (q, ...combinators) => {
             const final = applyQuery(q, combinators);