@guuey/threads 0.31.0 → 0.32.0

package/dist/testing/contract-suite.js

@@ -6,6 +6,8 @@
  * contract-suite pattern (guuey#107).
  */
 import { describe, expect, it } from "vitest";
+import { ThreadClosedError, threadClosure } from "../closed.js";
+import { DYNAMODB_ITEM_LIMIT_BYTES, DYNAMODB_ROW_BUDGET, dynamoItemBytes, dynamoNumberFits } from "../item-size.js";
 function threadRow(id) {
     const now = "2026-08-07T00:00:00.000Z";
     return {
@@ -37,8 +39,47 @@ async function withHarness(make, fn) {
  * Run the port contract against a binding. `make` must yield a FRESH,
  * empty store per call.
  */
-export function runThreadPersistenceContractSuite(name, make) {
+export function runThreadPersistenceContractSuite(name, make, options = {}) {
     describe(`ThreadPersistencePort contract — ${name}`, () => {
+        if (options.canClose === true) {
+            const closure = { code: "app:CHAT_FULL", message: "This chat is full.", at: "2026-08-07T00:00:05.000Z" };
+            it("closeThread records the closure once; a second close is already_closed; a missing thread rejects", async () => {
+                await withHarness(make, async (port) => {
+                    expect(port.closeThread).toBeTypeOf("function");
+                    if (port.closeThread === undefined)
+                        return;
+                    await port.createThread(threadRow("t1"));
+                    expect(await port.closeThread("t1", closure)).toBe("closed");
+                    expect(await port.closeThread("t1", { ...closure, code: "app:OTHER" })).toBe("already_closed");
+                    const t = await port.getThread("t1");
+                    expect(t && threadClosure(t)).toEqual(closure);
+                    // Closing is not archiving: the status the thread had is kept.
+                    expect(t?.status).toBe("active");
+                    await expect(port.closeThread("t-missing", closure)).rejects.toThrow();
+                });
+            });
+            it("incrementSeq on a closed thread rejects with ThreadClosedError and allocates no seq", async () => {
+                await withHarness(make, async (port) => {
+                    if (port.closeThread === undefined)
+                        throw new Error("canClose binding has no closeThread");
+                    await port.createThread(threadRow("t1"));
+                    expect(await port.incrementSeq("t1", "before", "2026-08-07T00:00:01.000Z")).toBe(1);
+                    await port.closeThread("t1", closure);
+                    await expect(port.incrementSeq("t1", "after", "2026-08-07T00:00:06.000Z")).rejects.toBeInstanceOf(ThreadClosedError);
+                    await expect(port.incrementSeq("t1", null, "2026-08-07T00:00:06.000Z")).rejects.toBeInstanceOf(ThreadClosedError);
+                    const t = await port.getThread("t1");
+                    expect(t?.lastSeq).toBe(1);
+                    expect(t?.lastMessagePreview).toBe("before");
+                });
+            });
+            it("incrementSeq on a missing thread still rejects with something other than ThreadClosedError", async () => {
+                await withHarness(make, async (port) => {
+                    const err = await port.incrementSeq("t-missing", "p", "2026-08-07T00:00:01.000Z").catch((e) => e);
+                    expect(err).toBeInstanceOf(Error);
+                    expect(err).not.toBeInstanceOf(ThreadClosedError);
+                });
+            });
+        }
         it("creates and point-reads a thread; unknown ids read undefined", async () => {
             await withHarness(make, async (port) => {
                 await port.createThread(threadRow("t1"));
@@ -198,3 +239,83 @@ export function runThreadPersistenceContractSuite(name, make) {
         });
     });
 }
+/**
+ * The error {@link withItemSizeLimit} rejects an oversized row with: the shape
+ * DynamoDB answers a too-large `PutItem` with.
+ */
+export class ItemSizeExceededError extends Error {
+    bytes;
+    name = "ValidationException";
+    constructor(bytes) {
+        super("Item size has exceeded the maximum allowed size");
+        this.bytes = bytes;
+    }
+}
+/**
+ * The error {@link withItemSizeLimit} rejects a row carrying a number DynamoDB
+ * cannot hold with: like the DocumentClient's own, its message names the number.
+ */
+export class UnstorableNumberError extends Error {
+    value;
+    constructor(value) {
+        super(`Number ${String(value)} cannot be stored as written`);
+        this.value = value;
+    }
+}
+function firstUnfitNumber(value) {
+    if (typeof value === "number")
+        return dynamoNumberFits(value) ? undefined : value;
+    if (value === null || typeof value !== "object")
+        return undefined;
+    for (const child of Array.isArray(value) ? value : Object.values(value)) {
+        const found = firstUnfitNumber(child);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+/**
+ * Wrap a port so it behaves like a DynamoDB-backed binding on what a row may
+ * hold (guuey#1794): it declares the DynamoDB row budget, and its
+ * `putMessage` (and, guuey#2120, its `putSnapshot`) rejects a row over DynamoDB's 400 KB item limit (measured by
+ * `dynamoItemBytes`) with {@link ItemSizeExceededError}, and a row carrying a
+ * number DynamoDB cannot hold with {@link UnstorableNumberError}, instead of
+ * storing it. Run a `ThreadStore` over it to test what happens at those
+ * limits without a real table.
+ */
+export function withItemSizeLimit(port) {
+    return {
+        rowBudget: DYNAMODB_ROW_BUDGET,
+        getThread: (threadId) => port.getThread(threadId),
+        createThread: (row) => port.createThread(row),
+        incrementSeq: (threadId, preview, atIso) => port.incrementSeq(threadId, preview, atIso),
+        ...closeThreadOf(port),
+        async putMessage(row) {
+            const unfit = firstUnfitNumber(row);
+            if (unfit !== undefined)
+                throw new UnstorableNumberError(unfit);
+            const bytes = dynamoItemBytes(row);
+            if (bytes > DYNAMODB_ITEM_LIMIT_BYTES)
+                throw new ItemSizeExceededError(bytes);
+            await port.putMessage(row);
+        },
+        listRecentMessages: (threadId, limit) => port.listRecentMessages(threadId, limit),
+        findByClientMessageId: (threadId, clientMessageId) => port.findByClientMessageId(threadId, clientMessageId),
+        getSnapshot: (threadId) => port.getSnapshot(threadId),
+        // guuey#2120: the snapshot row is an item of the same store, refused the same way.
+        async putSnapshot(row) {
+            const unfit = firstUnfitNumber(row);
+            if (unfit !== undefined)
+                throw new UnstorableNumberError(unfit);
+            const bytes = dynamoItemBytes(row);
+            if (bytes > DYNAMODB_ITEM_LIMIT_BYTES)
+                throw new ItemSizeExceededError(bytes);
+            await port.putSnapshot(row);
+        },
+    };
+}
+/** `port`'s `closeThread`, forwarded, or nothing when it has none. */
+function closeThreadOf(port) {
+    const close = port.closeThread;
+    return close === undefined ? {} : { closeThread: (threadId, closure) => close.call(port, threadId, closure) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/threads",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Universal session/thread persistence for AgJSON agents — the ThreadStore contract (append-fold, history, snapshots), the fold↔row mapping, and an in-memory binding. Guuey's hosted runtime is one binding; implement the port against your own store and run the exported contract suite for the same guarantees.",
   "license": "MIT",
   "type": "module",
@@ -25,8 +25,8 @@
     }
   },
   "dependencies": {
-    "@silverprotocol/core": "0.12.1",
-    "@guuey/mcp-apps-host": "0.31.0"
+    "@silverprotocol/core": "0.12.7",
+    "@guuey/mcp-apps-host": "0.32.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",