@guuey/threads 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Loqu, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# @guuey/threads
+
+Universal session/thread persistence for AgJSON agents.
+
+Hosted guuey agents get thread rehydration ("my agent remembers this
+conversation") from the platform. This package is that same session model as
+a public contract, so ejected and self-hosted agents — and integration
+harnesses — share it:
+
+- **`ThreadStore`** — the storage-agnostic logic: thread resolution and
+  ownership, atomic gap-free sequencing, `clientMessageId` idempotency,
+  turn-level fold persistence (messages + generative-UI card rows + the
+  latest-replace snapshot), and the prompt-lane history projection.
+- **`ThreadPersistencePort`** — the narrow surface a binding implements.
+  `InMemoryThreadPersistence` ships in the box (dev, tests, CI); guuey's
+  hosted runtime binds DynamoDB; implement the port against your own store
+  for ejected deployments.
+- **fold ↔ row mapping** — `agMessageToRow`, `reassembleFold`,
+  `uiCardArtifactsFromMessages` and friends: byte-identity persistence of an
+  `@silverprotocol/core` `AgReduceResult`, including the projection that
+  persists MCP-App cards carried on tool-result blocks.
+- **`@guuey/threads/testing`** — the port contract suite. Run it against
+  your binding and "works in-memory" and "works on the real thing" mean the
+  same set of guarantees.
+
+```ts
+import { InMemoryThreadPersistence, ThreadStore } from "@guuey/threads";
+
+const store = new ThreadStore(new InMemoryThreadPersistence());
+const threadId = await store.ensureThread({
+  userId: "g_dev",
+  appId: "my-agent",
+  region: "local",
+});
+await store.appendMessage({
+  threadId,
+  userId: "g_dev",
+  role: "user",
+  content: "hello",
+  text: "hello",
+  clientMessageId: "m1",
+});
+const history = await store.loadHistory(threadId);
+```
+
+```ts
+// your-binding.test.ts
+import { runThreadPersistenceContractSuite } from "@guuey/threads/testing";
+runThreadPersistenceContractSuite("MyBinding", async () => ({ port: makeMyPort() }));
+```

package/dist/fold-rows.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Pure mappers between the AgJSON fold (`AgReduceResult` components) and
+ * `ThreadMessage` rows / `ThreadSnapshot`. No AWS, no I/O — the byte-identity
+ * round-trip lives here and is unit-tested table-free. See
+ * docs/superpowers/specs/2026-06-23-agjson-persistence-fold-design.md §6–§9.
+ */
+import type { AgMessage, AgArtifact, AgTurnRecord, AgReduceResult, AgEvent, AgMemoryRecord, JsonValue } from "@silverprotocol/core";
+import type { ThreadMessageRow, ThreadSnapshotRow } from "./rows.js";
+export interface RowCtx {
+    threadId: string;
+    userId: string;
+    seq: number;
+    at: string;
+    clientMessageId: string;
+}
+/** Plain-text projection of an AgMessage — concatenated text blocks. */
+export declare function messageText(msg: AgMessage): string;
+export declare function agMessageToRow(msg: AgMessage, ctx: RowCtx & {
+    turnRecord?: AgTurnRecord;
+}): ThreadMessageRow;
+export declare function uiCardArtifactsFromMessages(messages: AgMessage[]): AgArtifact[];
+export declare function agArtifactToCardRow(art: AgArtifact, ctx: RowCtx): ThreadMessageRow;
+/**
+ * Reconstruct an AgMessage from a row. Agent-fold rows store the verbatim
+ * AgMessage in `content`; user/system rows (persisted up-front) store plain
+ * `{ kind, text }` — synthesize a single-text-block AgMessage for those so
+ * the reassembled transcript is uniform.
+ */
+export declare function rowToAgMessage(row: ThreadMessageRow): AgMessage;
+/** Extract the AgArtifact from a kind='card' row, or undefined if malformed. */
+export declare function cardRowToAgArtifact(row: ThreadMessageRow): AgArtifact | undefined;
+/**
+ * Reassemble an AgReduceResult from persisted rows + the thread snapshot.
+ * Inverse of the per-turn write (design §9). Append components come from
+ * rows in seq order; latest-replace components from the snapshot. Byte-
+ * identical to reduce() over the agent-folded portion — EXCEPT that
+ * `artifacts` additionally carries the UI-card projections
+ * ({@link uiCardArtifactsFromMessages}) the live reduce() never produced.
+ * Re-persisting a reassembled fold through `appendFold` stays single-write:
+ * the projection is deduped by its deterministic `<msgId>#ui#<idx>`
+ * artifactIds there.
+ */
+export declare function reassembleFold(rows: ThreadMessageRow[], snapshot: ThreadSnapshotRow | undefined): AgReduceResult;
+/**
+ * Synthetic events that seed a reducer with prior latest-replace state before
+ * folding a turn (design §8.1). Seeds state + thread-memory ONLY — never
+ * messages/artifacts/turns — so result() yields this turn's append-delta while
+ * carrying cumulative state/memory. Contiguous seqs 0..K (no internal gap); the
+ * live stream that follows uses its own per-message 0-based seqs (backward
+ * jumps, which the reducer tolerates). Push these into the reducer but never
+ * emit them to the client.
+ *
+ * Each synthetic `memory.write` carries `turnId` so the reducer's SET handler
+ * lands it back onto the AgMemoryRecord — without it, a re-seeded thread-memory
+ * record loses its turnId and memory byte-identity breaks from turn 2 on.
+ * (`threadId` is NOT carried: `memory.write` has no threadId on its event arm,
+ * so it cannot round-trip through a live write — that is expected.)
+ */
+export declare function seedEventsForReducer(priorState: JsonValue | undefined, priorThreadMemory: AgMemoryRecord[]): AgEvent[];
+//# sourceMappingURL=fold-rows.d.ts.map

package/dist/fold-rows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fold-rows.d.ts","sourceRoot":"","sources":["../src/fold-rows.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EACV,SAAS,EACT,UAAU,EACV,YAAY,EAEZ,cAAc,EACd,OAAO,EACP,cAAc,EACd,SAAS,EACV,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,gBAAgB,EAAwC,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE3G,MAAM,WAAW,MAAM;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,eAAe,EAAE,MAAM,CAAC;CACzB;AASD,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,CAMlD;AAED,wBAAgB,cAAc,CAC5B,GAAG,EAAE,SAAS,EACd,GAAG,EAAE,MAAM,GAAG;IAAE,UAAU,CAAC,EAAE,YAAY,CAAA;CAAE,GAC1C,gBAAgB,CAelB;AAgDD,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,SAAS,EAAE,GAAG,UAAU,EAAE,CAqB/E;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAYlF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,gBAAgB,GAAG,SAAS,CAY/D;AAED,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,gBAAgB,GAAG,UAAU,GAAG,SAAS,CAMjF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,gBAAgB,EAAE,EACxB,QAAQ,EAAE,iBAAiB,GAAG,SAAS,GACtC,cAAc,CA2BhB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,SAAS,GAAG,SAAS,EACjC,iBAAiB,EAAE,cAAc,EAAE,GAClC,OAAO,EAAE,CAmBX"}

package/dist/fold-rows.js

@@ -0,0 +1,216 @@
+import { AgMessage as AgMessageSchema } from "@silverprotocol/core";
+/** AgRole → the row's coarse authorRole projection (secondary; role of record lives in content). */
+function roleToAuthor(role) {
+    if (role === "user")
+        return "user";
+    if (role === "system")
+        return "system";
+    return "agent"; // assistant | tool
+}
+/** Plain-text projection of an AgMessage — concatenated text blocks. */
+export function messageText(msg) {
+    let out = "";
+    for (const block of msg.content) {
+        if (block.type === "text")
+            out += block.text;
+    }
+    return out;
+}
+export function agMessageToRow(msg, ctx) {
+    const text = messageText(msg);
+    const kind = "text";
+    return {
+        threadId: ctx.threadId,
+        seq: ctx.seq,
+        userId: ctx.userId,
+        clientMessageId: ctx.clientMessageId,
+        at: ctx.at,
+        kind,
+        authorRole: roleToAuthor(msg.role),
+        ...(text ? { text } : {}),
+        content: msg,
+        ...(ctx.turnRecord ? { aiContext: ctx.turnRecord } : {}),
+    };
+}
+/**
+ * MCP-App cards ride `tool-result` blocks' UI channels inside AgMessages —
+ * the Claude facet emits NO `artifact.*` events, so `fold.artifacts` alone
+ * misses every generative-UI card and nothing ever wrote a `kind:'card'`
+ * row for them (guuey#86: cards never rehydrated after a reload). Project
+ * UI-carrying tool-result blocks into synthetic AgArtifacts so the
+ * EXISTING card-row lane persists them; the client's `cardCardMount`
+ * mounts `{ parts: [block] }` through its inline arm unchanged. Facets
+ * that DO emit artifact events don't stamp `uiData` on tool-results, so
+ * the two sources don't double-write for one card.
+ *
+ * The narrowing MIRRORS `@guuey/agent-client`'s `toolResultUiResource`
+ * (@guuey/agent-client's block-ui.ts — keep the two in sync):
+ *   1. `uiData` carrying an MCP resource payload (`{uri, text|blob}`,
+ *      inlined directly or wrapped as `{ resource: {...} }`) — the explicit
+ *      surface channel, no `ui://` gate on purpose;
+ *   2. a `ui://` resource degraded into a `provider-raw` content part —
+ *      gated on the scheme, because provider-raw is a lossy catch-all.
+ */
+function isJsonObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isResourcePayload(v) {
+    if (!isJsonObject(v))
+        return false;
+    if (typeof v.uri !== "string")
+        return false;
+    return typeof v.text === "string" || typeof v.blob === "string";
+}
+function resourceUri(v) {
+    if (!isJsonObject(v))
+        return undefined;
+    return typeof v.uri === "string" ? v.uri : undefined;
+}
+function uiDataCarriesResource(uiData) {
+    if (!isJsonObject(uiData))
+        return false;
+    return isResourcePayload(uiData) || isResourcePayload(uiData.resource);
+}
+function providerRawCarriesUiResource(raw) {
+    if (!isJsonObject(raw))
+        return false;
+    const candidate = raw.resource !== undefined ? raw.resource : raw;
+    if (!isResourcePayload(candidate))
+        return false;
+    return resourceUri(candidate)?.startsWith("ui://") === true;
+}
+export function uiCardArtifactsFromMessages(messages) {
+    const artifacts = [];
+    for (const msg of messages) {
+        for (let i = 0; i < msg.content.length; i++) {
+            const block = msg.content[i];
+            if (block.type !== "tool-result")
+                continue;
+            const carriesUi = uiDataCarriesResource(block.uiData) ||
+                block.content.some((part) => part.type === "provider-raw" && providerRawCarriesUiResource(part.raw));
+            if (!carriesUi)
+                continue;
+            artifacts.push({
+                artifactId: `${msg.id}#ui#${i}`,
+                turnId: msg.turnId ?? "",
+                threadId: msg.threadId ?? "",
+                parts: [block],
+            });
+        }
+    }
+    return artifacts;
+}
+export function agArtifactToCardRow(art, ctx) {
+    return {
+        threadId: ctx.threadId,
+        seq: ctx.seq,
+        userId: ctx.userId,
+        clientMessageId: ctx.clientMessageId,
+        at: ctx.at,
+        kind: "card",
+        authorRole: "agent",
+        content: { producedInTurnId: art.turnId },
+        cardSnapshot: art,
+    };
+}
+/**
+ * Reconstruct an AgMessage from a row. Agent-fold rows store the verbatim
+ * AgMessage in `content`; user/system rows (persisted up-front) store plain
+ * `{ kind, text }` — synthesize a single-text-block AgMessage for those so
+ * the reassembled transcript is uniform.
+ */
+export function rowToAgMessage(row) {
+    const parsed = AgMessageSchema.safeParse(row.content);
+    if (parsed.success)
+        return parsed.data;
+    const role = row.authorRole === "user" ? "user" : row.authorRole === "system" ? "system" : "assistant";
+    const text = row.text ?? "";
+    return {
+        id: `${row.threadId}#${row.seq}`,
+        role,
+        content: text ? [{ type: "text", text }] : [],
+        threadId: row.threadId,
+    };
+}
+/** Extract the AgArtifact from a kind='card' row, or undefined if malformed. */
+export function cardRowToAgArtifact(row) {
+    const snap = row.cardSnapshot;
+    if (snap && typeof snap === "object" && "artifactId" in snap) {
+        return snap;
+    }
+    return undefined;
+}
+/**
+ * Reassemble an AgReduceResult from persisted rows + the thread snapshot.
+ * Inverse of the per-turn write (design §9). Append components come from
+ * rows in seq order; latest-replace components from the snapshot. Byte-
+ * identical to reduce() over the agent-folded portion — EXCEPT that
+ * `artifacts` additionally carries the UI-card projections
+ * ({@link uiCardArtifactsFromMessages}) the live reduce() never produced.
+ * Re-persisting a reassembled fold through `appendFold` stays single-write:
+ * the projection is deduped by its deterministic `<msgId>#ui#<idx>`
+ * artifactIds there.
+ */
+export function reassembleFold(rows, snapshot) {
+    const ordered = rows.slice().sort((a, b) => a.seq - b.seq);
+    const messages = [];
+    const artifacts = [];
+    const turnsById = new Map();
+    for (const row of ordered) {
+        if (row.kind === "card") {
+            const art = cardRowToAgArtifact(row);
+            if (art)
+                artifacts.push(art);
+            continue;
+        }
+        messages.push(rowToAgMessage(row));
+        const tr = row.aiContext;
+        if (tr && typeof tr === "object" && "turnId" in tr) {
+            const rec = tr;
+            if (!turnsById.has(rec.turnId))
+                turnsById.set(rec.turnId, rec);
+        }
+    }
+    return {
+        messages,
+        artifacts,
+        memory: snapshot?.threadMemory ?? [],
+        turns: [...turnsById.values()],
+        ...(snapshot?.workingState !== undefined ? { state: snapshot.workingState } : {}),
+    };
+}
+/**
+ * Synthetic events that seed a reducer with prior latest-replace state before
+ * folding a turn (design §8.1). Seeds state + thread-memory ONLY — never
+ * messages/artifacts/turns — so result() yields this turn's append-delta while
+ * carrying cumulative state/memory. Contiguous seqs 0..K (no internal gap); the
+ * live stream that follows uses its own per-message 0-based seqs (backward
+ * jumps, which the reducer tolerates). Push these into the reducer but never
+ * emit them to the client.
+ *
+ * Each synthetic `memory.write` carries `turnId` so the reducer's SET handler
+ * lands it back onto the AgMemoryRecord — without it, a re-seeded thread-memory
+ * record loses its turnId and memory byte-identity breaks from turn 2 on.
+ * (`threadId` is NOT carried: `memory.write` has no threadId on its event arm,
+ * so it cannot round-trip through a live write — that is expected.)
+ */
+export function seedEventsForReducer(priorState, priorThreadMemory) {
+    const events = [];
+    let seq = 0;
+    if (priorState !== undefined) {
+        events.push({ seq: seq++, type: "state.snapshot", snapshot: priorState });
+    }
+    for (const rec of priorThreadMemory) {
+        events.push({
+            seq: seq++,
+            type: "memory.write",
+            scope: "thread",
+            ...(rec.key !== undefined ? { key: rec.key } : {}),
+            value: rec.value,
+            ...(rec.reason !== undefined ? { reason: rec.reason } : {}),
+            ...(rec.durable !== undefined ? { durable: rec.durable } : {}),
+            ...(rec.turnId !== undefined ? { turnId: rec.turnId } : {}),
+        });
+    }
+    return events;
+}

package/dist/in-memory.d.ts

@@ -0,0 +1,21 @@
+/**
+ * InMemoryThreadPersistence — the dev/test binding of
+ * {@link ThreadPersistencePort}. Same contract as any real binding (run
+ * the suite in `@guuey/threads/testing` to prove yours), including the
+ * two conditional-write guards and the null-preview no-touch semantics.
+ */
+import type { ThreadMessageRow, ThreadPersistencePort, ThreadRow, ThreadSnapshotRow } from "./rows.js";
+export declare class InMemoryThreadPersistence implements ThreadPersistencePort {
+    readonly threads: Map<string, ThreadRow>;
+    readonly messages: ThreadMessageRow[];
+    readonly snapshots: Map<string, ThreadSnapshotRow>;
+    getThread(threadId: string): Promise<ThreadRow | undefined>;
+    createThread(row: ThreadRow): Promise<void>;
+    incrementSeq(threadId: string, preview: string | null, atIso: string): Promise<number>;
+    putMessage(row: ThreadMessageRow): Promise<void>;
+    listRecentMessages(threadId: string, limit: number): Promise<ThreadMessageRow[]>;
+    findByClientMessageId(threadId: string, clientMessageId: string): Promise<ThreadMessageRow | undefined>;
+    getSnapshot(threadId: string): Promise<ThreadSnapshotRow | undefined>;
+    putSnapshot(row: ThreadSnapshotRow): Promise<void>;
+}
+//# sourceMappingURL=in-memory.d.ts.map

package/dist/in-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory.d.ts","sourceRoot":"","sources":["../src/in-memory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EACV,gBAAgB,EAChB,qBAAqB,EACrB,SAAS,EACT,iBAAiB,EAClB,MAAM,WAAW,CAAC;AAEnB,qBAAa,yBAA0B,YAAW,qBAAqB;IACrE,QAAQ,CAAC,OAAO,yBAAgC;IAChD,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,EAAE,CAAM;IAC3C,QAAQ,CAAC,SAAS,iCAAwC;IAEpD,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAI3D,YAAY,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAO3C,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAYtF,UAAU,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOhD,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAQhF,qBAAqB,CACzB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAMlC,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC;IAIrE,WAAW,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;CAGzD"}

package/dist/in-memory.js

@@ -0,0 +1,49 @@
+export class InMemoryThreadPersistence {
+    threads = new Map();
+    messages = [];
+    snapshots = new Map();
+    async getThread(threadId) {
+        return this.threads.get(threadId);
+    }
+    async createThread(row) {
+        if (this.threads.has(row.id)) {
+            throw new Error(`createThread: thread ${row.id} already exists`);
+        }
+        this.threads.set(row.id, { ...row });
+    }
+    async incrementSeq(threadId, preview, atIso) {
+        const t = this.threads.get(threadId);
+        if (!t)
+            throw new Error(`incrementSeq: thread ${threadId} does not exist`);
+        t.lastSeq += 1;
+        t.lastMessageAt = atIso;
+        t.updatedAt = atIso;
+        // null = allocate the seq WITHOUT touching the preview (card rows,
+        // text-less agent turns) — mirror of the hosted binding's branch.
+        if (preview !== null)
+            t.lastMessagePreview = preview;
+        return t.lastSeq;
+    }
+    async putMessage(row) {
+        if (this.messages.some((m) => m.threadId === row.threadId && m.seq === row.seq)) {
+            throw new Error(`putMessage: seq ${row.seq} already exists on ${row.threadId}`);
+        }
+        this.messages.push({ ...row });
+    }
+    async listRecentMessages(threadId, limit) {
+        return this.messages
+            .filter((m) => m.threadId === threadId)
+            .sort((a, b) => b.seq - a.seq)
+            .slice(0, limit)
+            .reverse();
+    }
+    async findByClientMessageId(threadId, clientMessageId) {
+        return this.messages.find((m) => m.threadId === threadId && m.clientMessageId === clientMessageId);
+    }
+    async getSnapshot(threadId) {
+        return this.snapshots.get(threadId);
+    }
+    async putSnapshot(row) {
+        this.snapshots.set(row.threadId, { ...row });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @guuey/threads — universal session/thread persistence for AgJSON agents
+ * (guuey#107).
+ *
+ * The pieces:
+ *   - {@link ThreadStore} — the storage-agnostic logic: thread resolution,
+ *     atomic sequencing, idempotency, turn-level fold persistence
+ *     (messages + card rows + snapshot), prompt-lane history.
+ *   - {@link ThreadPersistencePort} — the narrow surface a binding
+ *     implements. `InMemoryThreadPersistence` ships here; guuey's hosted
+ *     runtime binds DynamoDB; bring your own store for ejected agents.
+ *   - fold↔row mapping — `agMessageToRow`/`reassembleFold`/friends, the
+ *     byte-identity persistence of an `AgReduceResult`, including the
+ *     UI-card projection (`uiCardArtifactsFromMessages`, guuey#86).
+ *   - `@guuey/threads/testing` — the port contract suite: run it against
+ *     your binding for the same guarantees the hosted one carries.
+ */
+export type { StoredHistoryMessage, ThreadMessageKind, ThreadMessageRole, ThreadMessageRow, ThreadPersistencePort, ThreadRow, ThreadSnapshotRow, } from "./rows.js";
+export { ThreadStore, type AppendFoldInput, type AppendFoldResult, type AppendMessageInput, type AppendMessageResult, type EnsureThreadInput, } from "./store.js";
+export { InMemoryThreadPersistence } from "./in-memory.js";
+export { agArtifactToCardRow, agMessageToRow, cardRowToAgArtifact, messageText, reassembleFold, rowToAgMessage, seedEventsForReducer, uiCardArtifactsFromMessages, type RowCtx, } from "./fold-rows.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,SAAS,EACT,iBAAiB,GAClB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,WAAW,EACX,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,2BAA2B,EAC3B,KAAK,MAAM,GACZ,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { ThreadStore, } from "./store.js";
+export { InMemoryThreadPersistence } from "./in-memory.js";
+export { agArtifactToCardRow, agMessageToRow, cardRowToAgArtifact, messageText, reassembleFold, rowToAgMessage, seedEventsForReducer, uiCardArtifactsFromMessages, } from "./fold-rows.js";

package/dist/rows.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Row shapes + the persistence port — the storage-agnostic half of the
+ * thread contract (guuey#107, extracted from the hosted runtime's
+ * thread-store so ejected/self-hosted agents share ONE session model).
+ *
+ * A binding implements {@link ThreadPersistencePort} against its store
+ * (guuey's hosted runtime binds DynamoDB; `InMemoryThreadPersistence`
+ * ships here for dev/tests) and runs the exported contract suite
+ * (`@guuey/threads/testing`) so "works in-memory" and "works on the real
+ * thing" are the same mechanical guarantee — the `@guuey/state` pattern.
+ */
+import type { AgMemoryRecord, JsonValue } from "@silverprotocol/core";
+export type ThreadMessageRole = "user" | "agent" | "system";
+export type ThreadMessageKind = "text" | "card" | "event";
+export interface ThreadRow {
+    id: string;
+    userId: string;
+    appId: string;
+    servingRegion: string;
+    title: string;
+    status: string;
+    pinned: boolean;
+    /** Monotonic seq counter — bumped atomically on each append. */
+    lastSeq: number;
+    lastMessageAt: string;
+    lastMessagePreview: string;
+    threadMode: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ThreadMessageRow {
+    threadId: string;
+    seq: number;
+    userId: string;
+    clientMessageId: string;
+    at: string;
+    kind: ThreadMessageKind;
+    authorRole: ThreadMessageRole;
+    text?: string;
+    content?: unknown;
+    /** Verbatim `AgArtifact` stored on kind='card' rows. */
+    cardSnapshot?: unknown;
+    /** `AgTurnRecord` stored on agent-fold rows for context recovery. */
+    aiContext?: unknown;
+}
+/** Latest-replace fold snapshot for a thread. */
+export interface ThreadSnapshotRow {
+    threadId: string;
+    userId: string;
+    /** AgReduceResult.state — opaque working blob. */
+    workingState?: JsonValue;
+    /** AgReduceResult.memory filtered to scope='thread'. */
+    threadMemory: AgMemoryRecord[];
+    lastTurnId?: string;
+    updatedAt: string;
+}
+/** A prior message loaded for context injection — narrow projection. */
+export interface StoredHistoryMessage {
+    seq: number;
+    authorRole: ThreadMessageRole;
+    kind: ThreadMessageKind;
+    text: string | null;
+    content: unknown;
+    at: string;
+}
+/**
+ * The only surface {@link ThreadStore} needs from a backing store. Keep
+ * implementations honest with the contract suite in
+ * `@guuey/threads/testing`.
+ */
+export interface ThreadPersistencePort {
+    /** Point-read a Thread by id; `undefined` when the row does not exist. */
+    getThread(threadId: string): Promise<ThreadRow | undefined>;
+    /** Put a new Thread row (conditional create — must reject an existing id). */
+    createThread(row: ThreadRow): Promise<void>;
+    /**
+     * Atomically bump `lastSeq` (+ set `lastMessageAt`/`updatedAt`) on an
+     * EXISTING Thread and return the NEW `lastSeq`. `preview: null`
+     * allocates the seq WITHOUT touching `lastMessagePreview` (card rows and
+     * text-less agent turns must not clobber the last real preview);
+     * a string preview replaces it.
+     */
+    incrementSeq(threadId: string, preview: string | null, atIso: string): Promise<number>;
+    /** Put a ThreadMessage row (conditional — must reject a duplicate seq). */
+    putMessage(row: ThreadMessageRow): Promise<void>;
+    /** Up to `limit` most-recent messages for a thread, returned seq-ASCending. */
+    listRecentMessages(threadId: string, limit: number): Promise<ThreadMessageRow[]>;
+    /** Existing message by (clientMessageId, threadId) for idempotency dedup. */
+    findByClientMessageId(threadId: string, clientMessageId: string): Promise<ThreadMessageRow | undefined>;
+    /** Point-read the thread's snapshot; undefined when none yet. */
+    getSnapshot(threadId: string): Promise<ThreadSnapshotRow | undefined>;
+    /** Upsert (full replace) the thread's snapshot row. */
+    putSnapshot(row: ThreadSnapshotRow): Promise<void>;
+}
+//# sourceMappingURL=rows.d.ts.map

package/dist/rows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rows.d.ts","sourceRoot":"","sources":["../src/rows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAC5D,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE1D,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,iBAAiB,CAAC;IACxB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wDAAwD;IACxD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,qEAAqE;IACrE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,iDAAiD;AACjD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,wDAAwD;IACxD,YAAY,EAAE,cAAc,EAAE,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wEAAwE;AACxE,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,iBAAiB,CAAC;IAC9B,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC;IAC5D,8EAA8E;IAC9E,YAAY,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C;;;;;;OAMG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvF,2EAA2E;IAC3E,UAAU,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,+EAA+E;IAC/E,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;IACjF,6EAA6E;IAC7E,qBAAqB,CACnB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAAC;IACzC,iEAAiE;IACjE,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAAC;IACtE,uDAAuD;IACvD,WAAW,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD"}

package/dist/rows.js

@@ -0,0 +1 @@
+export {};

package/dist/store.d.ts

@@ -0,0 +1,102 @@
+import type { AgReduceResult } from "@silverprotocol/core";
+import type { StoredHistoryMessage, ThreadMessageKind, ThreadMessageRole, ThreadPersistencePort, ThreadSnapshotRow } from "./rows.js";
+export interface EnsureThreadInput {
+    /** Client-supplied thread id (localStorage). Absent on first contact. */
+    threadId?: string;
+    /** Resolved end-user id (`g_<hash>`). */
+    userId: string;
+    appId: string;
+    /** Region pin for a freshly-created Thread (the pod's `AWS_REGION`). */
+    region: string;
+}
+export interface AppendMessageInput {
+    threadId: string;
+    userId: string;
+    role: ThreadMessageRole;
+    /** Arbitrary JSON persisted on the row (string for plain text turns). */
+    content: unknown;
+    /** Plain-text projection for the preview + transcript render. */
+    text?: string;
+    /** Idempotency key — a retried invoke with the same key won't double-write. */
+    clientMessageId: string;
+    kind?: ThreadMessageKind;
+}
+export interface AppendMessageResult {
+    seq: number;
+    /** True when an existing row matched `clientMessageId` (no new write). */
+    deduped: boolean;
+}
+export interface AppendFoldInput {
+    threadId: string;
+    userId: string;
+    fold: AgReduceResult;
+    /** Base for the turn-level idempotency sentinel + per-row derived keys. */
+    clientMessageIdBase: string;
+    /**
+     * Suppress the `putSnapshot` upsert (rows still write). Set by the caller
+     * when the prior snapshot read failed OR the reducer parked
+     * (`needsResync`), so a degraded/partial fold never clobbers a good
+     * snapshot. Default: write the snapshot.
+     */
+    skipSnapshot?: boolean;
+}
+export interface AppendFoldResult {
+    messageSeqs: number[];
+    artifactSeqs: number[];
+    /** Count of non-thread (durable) memory records dropped in v1. */
+    droppedDurableMemory: number;
+    /**
+     * True when the turn-level sentinel matched a committed prior turn and the
+     * WHOLE fold-persist was short-circuited (no rows written this call).
+     */
+    deduped: boolean;
+}
+export declare class ThreadStore {
+    private readonly db;
+    constructor(db: ThreadPersistencePort);
+    /**
+     * Resolve the thread for this invoke:
+     * - `threadId` found AND owned by `userId` → return it (the happy path);
+     * - otherwise (no `threadId`, stale/unknown id, OR owned by a different
+     *   identity) → mint a fresh Thread with a server-assigned id and return it.
+     *
+     * Minting-fresh on an owner mismatch (rather than erroring) is deliberate:
+     * the caller's anon `guuey_guest` cookie can rotate (cleared, or a cross-site
+     * request where it isn't sent), which would otherwise orphan a stored
+     * `threadId` behind a permanent 403. Minting fresh is both resilient (chat
+     * continues on a new conversation) AND safe — the caller never sees another
+     * user's thread, and there's no existence oracle. The pod never honours a
+     * client-chosen id, so squatting is impossible.
+     */
+    ensureThread(input: EnsureThreadInput): Promise<string>;
+    /** Prior messages for the thread (seq-ASC, capped to the most recent N). */
+    loadHistory(threadId: string, limit?: number): Promise<StoredHistoryMessage[]>;
+    /**
+     * Append one message with an atomic, gap-free seq. Idempotent on
+     * `clientMessageId`: a prior row with the same key returns its seq without
+     * a second write. Mirrors `ops/append-message.ts` steps 2–4.
+     */
+    appendMessage(input: AppendMessageInput): Promise<AppendMessageResult>;
+    /** The thread's latest fold snapshot, or undefined when none persisted yet. */
+    getSnapshot(threadId: string): Promise<ThreadSnapshotRow | undefined>;
+    /**
+     * Persist a turn's fold delta: one row per message, one card row per
+     * artifact (each via an atomic gap-free seq), turn records inlined on the
+     * message rows, and an upserted snapshot for working state + thread-memory.
+     *
+     * Idempotency is TURN-LEVEL, not per-row. A retried invoke re-runs the LLM
+     * and can yield a *different* fold (different message count / content);
+     * per-index dedup would keep some prior rows and append new ones for the
+     * rest → a Frankenstein/orphan thread + clobbered snapshot. Instead, the
+     * FIRST row written (the first message, or — if there are no messages — the
+     * first card) claims a single `${base}#agentTurn` sentinel key. On any later
+     * call with the same base, the sentinel matches and the WHOLE persist is
+     * short-circuited (a committed agent turn is never re-merged).
+     *
+     * Durable (non-thread) memory is logged-and-dropped in v1. `skipSnapshot`
+     * suppresses the snapshot upsert so a degraded/parked fold never overwrites
+     * a good snapshot.
+     */
+    appendFold(input: AppendFoldInput): Promise<AppendFoldResult>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,KAAK,EACV,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EAEjB,qBAAqB,EAErB,iBAAiB,EAClB,MAAM,WAAW,CAAC;AAOnB,MAAM,WAAW,iBAAiB;IAChC,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,iBAAiB,CAAC;IACxB,yEAAyE;IACzE,OAAO,EAAE,OAAO,CAAC;IACjB,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,EAAE,iBAAiB,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,cAAc,CAAC;IACrB,2EAA2E;IAC3E,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,kEAAkE;IAClE,oBAAoB,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB;AAMD,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,qBAAqB;IAEtD;;;;;;;;;;;;;OAaG;IACG,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IA4B7D,4EAA4E;IACtE,WAAW,CACf,QAAQ,EAAE,MAAM,EAChB,KAAK,GAAE,MAA8B,GACpC,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAqBlC;;;;OAIG;IACG,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IA4B5E,+EAA+E;IACzE,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC;IAI3E;;;;;;;;;;;;;;;;;OAiBG;IACG,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;CA8EpE"}

package/dist/store.js

@@ -0,0 +1,201 @@
+/**
+ * ThreadStore — the storage-agnostic session logic: thread resolution +
+ * ownership, atomic gap-free sequencing, clientMessageId idempotency,
+ * turn-level fold persistence (messages + card rows + snapshot), and the
+ * prompt-lane history projection. Depends only on
+ * {@link ThreadPersistencePort}; bindings supply the storage
+ * (`InMemoryThreadPersistence` here; guuey's hosted runtime binds
+ * DynamoDB).
+ */
+import { randomUUID } from "node:crypto";
+import { agMessageToRow, agArtifactToCardRow, uiCardArtifactsFromMessages } from "./fold-rows.js";
+/** Max history messages fed back as context — bounds latency on long threads. */
+const DEFAULT_HISTORY_LIMIT = 40;
+const PREVIEW_MAX_LEN = 240;
+// ───────────────────────────────────────────────────────────────────────
+// ThreadStore — the logic.
+// ───────────────────────────────────────────────────────────────────────
+export class ThreadStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Resolve the thread for this invoke:
+     * - `threadId` found AND owned by `userId` → return it (the happy path);
+     * - otherwise (no `threadId`, stale/unknown id, OR owned by a different
+     *   identity) → mint a fresh Thread with a server-assigned id and return it.
+     *
+     * Minting-fresh on an owner mismatch (rather than erroring) is deliberate:
+     * the caller's anon `guuey_guest` cookie can rotate (cleared, or a cross-site
+     * request where it isn't sent), which would otherwise orphan a stored
+     * `threadId` behind a permanent 403. Minting fresh is both resilient (chat
+     * continues on a new conversation) AND safe — the caller never sees another
+     * user's thread, and there's no existence oracle. The pod never honours a
+     * client-chosen id, so squatting is impossible.
+     */
+    async ensureThread(input) {
+        if (input.threadId) {
+            const existing = await this.db.getThread(input.threadId);
+            if (existing && existing.userId === input.userId) {
+                return existing.id;
+            }
+            // Not found OR owned by a different identity → fall through, mint fresh.
+        }
+        const now = new Date().toISOString();
+        const row = {
+            id: randomUUID(),
+            userId: input.userId,
+            appId: input.appId,
+            servingRegion: input.region,
+            title: 'New thread',
+            status: 'active',
+            pinned: false,
+            lastSeq: 0,
+            lastMessageAt: now,
+            lastMessagePreview: '',
+            threadMode: 'single',
+            createdAt: now,
+            updatedAt: now,
+        };
+        await this.db.createThread(row);
+        return row.id;
+    }
+    /** Prior messages for the thread (seq-ASC, capped to the most recent N). */
+    async loadHistory(threadId, limit = DEFAULT_HISTORY_LIMIT) {
+        const rows = await this.db.listRecentMessages(threadId, limit);
+        // This lane feeds the LLM prompt (sse-server → priorMessages →
+        // worker <conversation_history>, which serializes {role, text} ONLY —
+        // row `content` never reaches the model). Card rows are UI
+        // persistence, not conversation: mapped naively they render as empty
+        // "Agent:" lines and evict real messages from the history window, so
+        // they are dropped here and the model deliberately sees no card HTML.
+        // Known trade-off: cards still consume the DynamoDB Limit before this
+        // filter, so card-heavy threads under-fill the window (bounded, most-
+        // recent-first; revisit with an over-fetch if it bites).
+        return rows.filter((r) => r.kind !== 'card').map((r) => ({
+            seq: r.seq,
+            authorRole: r.authorRole,
+            kind: r.kind,
+            text: r.text ?? null,
+            content: r.content ?? null,
+            at: r.at,
+        }));
+    }
+    /**
+     * Append one message with an atomic, gap-free seq. Idempotent on
+     * `clientMessageId`: a prior row with the same key returns its seq without
+     * a second write. Mirrors `ops/append-message.ts` steps 2–4.
+     */
+    async appendMessage(input) {
+        const prior = await this.db.findByClientMessageId(input.threadId, input.clientMessageId);
+        if (prior) {
+            return { seq: prior.seq, deduped: true };
+        }
+        const now = new Date().toISOString();
+        const preview = input.text ? input.text.slice(0, PREVIEW_MAX_LEN) : '';
+        const seq = await this.db.incrementSeq(input.threadId, preview, now);
+        const row = {
+            threadId: input.threadId,
+            seq,
+            userId: input.userId,
+            clientMessageId: input.clientMessageId,
+            at: now,
+            kind: input.kind ?? 'text',
+            authorRole: input.role,
+            ...(input.text !== undefined ? { text: input.text } : {}),
+            content: input.content,
+        };
+        await this.db.putMessage(row);
+        return { seq, deduped: false };
+    }
+    /** The thread's latest fold snapshot, or undefined when none persisted yet. */
+    async getSnapshot(threadId) {
+        return this.db.getSnapshot(threadId);
+    }
+    /**
+     * Persist a turn's fold delta: one row per message, one card row per
+     * artifact (each via an atomic gap-free seq), turn records inlined on the
+     * message rows, and an upserted snapshot for working state + thread-memory.
+     *
+     * Idempotency is TURN-LEVEL, not per-row. A retried invoke re-runs the LLM
+     * and can yield a *different* fold (different message count / content);
+     * per-index dedup would keep some prior rows and append new ones for the
+     * rest → a Frankenstein/orphan thread + clobbered snapshot. Instead, the
+     * FIRST row written (the first message, or — if there are no messages — the
+     * first card) claims a single `${base}#agentTurn` sentinel key. On any later
+     * call with the same base, the sentinel matches and the WHOLE persist is
+     * short-circuited (a committed agent turn is never re-merged).
+     *
+     * Durable (non-thread) memory is logged-and-dropped in v1. `skipSnapshot`
+     * suppresses the snapshot upsert so a degraded/parked fold never overwrites
+     * a good snapshot.
+     */
+    async appendFold(input) {
+        const { threadId, userId, fold, clientMessageIdBase, skipSnapshot } = input;
+        // Turn-level idempotency gate: a committed agent turn is never re-merged.
+        const sentinelKey = `${clientMessageIdBase}#agentTurn`;
+        const existing = await this.db.findByClientMessageId(threadId, sentinelKey);
+        if (existing) {
+            return { messageSeqs: [existing.seq], artifactSeqs: [], droppedDurableMemory: 0, deduped: true };
+        }
+        const messageSeqs = [];
+        const artifactSeqs = [];
+        // Whichever row is written first claims the sentinel key.
+        let sentinelClaimed = false;
+        for (let i = 0; i < fold.messages.length; i++) {
+            const msg = fold.messages[i];
+            const clientMessageId = sentinelClaimed ? `${clientMessageIdBase}#agent#${i}` : sentinelKey;
+            sentinelClaimed = true;
+            const text = msg.content.reduce((acc, b) => (b.type === 'text' ? acc + b.text : acc), '');
+            const now = new Date().toISOString();
+            // Text-less agent messages (tool-call + tool-result only — the canonical
+            // card-producing turn) must not blank the preview: '' takes the SET
+            // branch, null leaves the prior preview standing.
+            const seq = await this.db.incrementSeq(threadId, text ? text.slice(0, PREVIEW_MAX_LEN) : null, now);
+            const turnRecord = fold.turns.find((t) => t.turnId === msg.turnId);
+            await this.db.putMessage(agMessageToRow(msg, {
+                threadId,
+                userId,
+                seq,
+                at: now,
+                clientMessageId,
+                ...(turnRecord ? { turnRecord } : {}),
+            }));
+            messageSeqs.push(seq);
+        }
+        // Cards can arrive two ways: first-class artifact events (fold.artifacts)
+        // or UI-carrying tool-result blocks inside messages (the Claude facet's
+        // only channel — see uiCardArtifactsFromMessages). Persist both through
+        // the same card-row lane so history rehydrates them (guuey#86). The
+        // artifactId dedupe makes re-persisting a reassembled fold (whose
+        // artifacts already CONTAIN prior projections, deterministic
+        // `<msgId>#ui#<idx>` ids) a no-op instead of a double-write.
+        const knownArtifactIds = new Set(fold.artifacts.map((a) => a.artifactId));
+        const projected = uiCardArtifactsFromMessages(fold.messages).filter((a) => !knownArtifactIds.has(a.artifactId));
+        const cardArtifacts = [...fold.artifacts, ...projected];
+        for (let i = 0; i < cardArtifacts.length; i++) {
+            const art = cardArtifacts[i];
+            const clientMessageId = sentinelClaimed ? `${clientMessageIdBase}#card#${i}` : sentinelKey;
+            sentinelClaimed = true;
+            const now = new Date().toISOString();
+            const seq = await this.db.incrementSeq(threadId, art.name ?? null, now);
+            await this.db.putMessage(agArtifactToCardRow(art, { threadId, userId, seq, at: now, clientMessageId }));
+            artifactSeqs.push(seq);
+        }
+        const threadMemory = fold.memory.filter((m) => m.scope === 'thread');
+        const droppedDurableMemory = fold.memory.length - threadMemory.length;
+        if (skipSnapshot !== true) {
+            const lastTurnId = fold.turns.length ? fold.turns[fold.turns.length - 1].turnId : undefined;
+            await this.db.putSnapshot({
+                threadId,
+                userId,
+                threadMemory,
+                updatedAt: new Date().toISOString(),
+                ...(fold.state !== undefined ? { workingState: fold.state } : {}),
+                ...(lastTurnId ? { lastTurnId } : {}),
+            });
+        }
+        return { messageSeqs, artifactSeqs, droppedDurableMemory, deduped: false };
+    }
+}

package/dist/testing/contract-suite.d.ts

@@ -0,0 +1,11 @@
+import type { ThreadPersistencePort } from "../rows.js";
+export interface ThreadPersistenceHarness {
+    port: ThreadPersistencePort;
+    cleanup?: () => void | Promise<void>;
+}
+/**
+ * Run the port contract against a binding. `make` must yield a FRESH,
+ * empty store per call.
+ */
+export declare function runThreadPersistenceContractSuite(name: string, make: () => Promise<ThreadPersistenceHarness>): void;
+//# sourceMappingURL=contract-suite.d.ts.map

package/dist/testing/contract-suite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-suite.d.ts","sourceRoot":"","sources":["../../src/testing/contract-suite.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,qBAAqB,EAAa,MAAM,YAAY,CAAC;AAEnE,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAiCD;;;GAGG;AACH,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,OAAO,CAAC,wBAAwB,CAAC,GAC5C,IAAI,CA8HN"}

package/dist/testing/contract-suite.js

@@ -0,0 +1,158 @@
+/**
+ * Binding-agnostic behavioral contract for {@link ThreadPersistencePort}.
+ * Every binding (in-memory here, guuey's hosted DynamoDB binding, your
+ * own store) runs this SAME suite so "works in-memory" and "works on the
+ * real thing" mean the same set of guarantees — the `@guuey/state`
+ * contract-suite pattern (guuey#107).
+ */
+import { describe, expect, it } from "vitest";
+function threadRow(id) {
+    const now = "2026-08-07T00:00:00.000Z";
+    return {
+        id,
+        userId: "g_contract",
+        appId: "app_contract",
+        servingRegion: "test-region",
+        title: "New thread",
+        status: "active",
+        pinned: false,
+        lastSeq: 0,
+        lastMessageAt: now,
+        lastMessagePreview: "",
+        threadMode: "single",
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+async function withHarness(make, fn) {
+    const h = await make();
+    try {
+        await fn(h.port);
+    }
+    finally {
+        await h.cleanup?.();
+    }
+}
+/**
+ * Run the port contract against a binding. `make` must yield a FRESH,
+ * empty store per call.
+ */
+export function runThreadPersistenceContractSuite(name, make) {
+    describe(`ThreadPersistencePort contract — ${name}`, () => {
+        it("creates and point-reads a thread; unknown ids read undefined", async () => {
+            await withHarness(make, async (port) => {
+                await port.createThread(threadRow("t1"));
+                expect((await port.getThread("t1"))?.id).toBe("t1");
+                expect(await port.getThread("t-missing")).toBeUndefined();
+            });
+        });
+        it("rejects creating a thread id twice (conditional create)", async () => {
+            await withHarness(make, async (port) => {
+                await port.createThread(threadRow("t1"));
+                await expect(port.createThread(threadRow("t1"))).rejects.toThrow();
+            });
+        });
+        it("incrementSeq is monotonic from 1 and echoes the new value", async () => {
+            await withHarness(make, async (port) => {
+                await port.createThread(threadRow("t1"));
+                expect(await port.incrementSeq("t1", "one", "2026-08-07T00:00:01.000Z")).toBe(1);
+                expect(await port.incrementSeq("t1", "two", "2026-08-07T00:00:02.000Z")).toBe(2);
+                const t = await port.getThread("t1");
+                expect(t?.lastSeq).toBe(2);
+                expect(t?.lastMessagePreview).toBe("two");
+            });
+        });
+        it("incrementSeq(null) allocates the seq WITHOUT touching the preview", async () => {
+            await withHarness(make, async (port) => {
+                await port.createThread(threadRow("t1"));
+                await port.incrementSeq("t1", "kept preview", "2026-08-07T00:00:01.000Z");
+                expect(await port.incrementSeq("t1", null, "2026-08-07T00:00:02.000Z")).toBe(2);
+                const t = await port.getThread("t1");
+                expect(t?.lastMessagePreview).toBe("kept preview");
+                expect(t?.lastMessageAt).toBe("2026-08-07T00:00:02.000Z");
+            });
+        });
+        it("incrementSeq on a missing thread rejects (conditional update)", async () => {
+            await withHarness(make, async (port) => {
+                await expect(port.incrementSeq("t-missing", "p", "2026-08-07T00:00:01.000Z")).rejects.toThrow();
+            });
+        });
+        it("putMessage rejects a duplicate (threadId, seq)", async () => {
+            await withHarness(make, async (port) => {
+                await port.createThread(threadRow("t1"));
+                const row = {
+                    threadId: "t1",
+                    seq: 1,
+                    userId: "g_contract",
+                    clientMessageId: "c1",
+                    at: "2026-08-07T00:00:01.000Z",
+                    kind: "text",
+                    authorRole: "user",
+                    text: "hello",
+                };
+                await port.putMessage(row);
+                await expect(port.putMessage({ ...row, clientMessageId: "c2" })).rejects.toThrow();
+            });
+        });
+        it("listRecentMessages returns the most-recent `limit` rows in seq-ASC order", async () => {
+            await withHarness(make, async (port) => {
+                await port.createThread(threadRow("t1"));
+                for (let seq = 1; seq <= 5; seq++) {
+                    await port.putMessage({
+                        threadId: "t1",
+                        seq,
+                        userId: "g_contract",
+                        clientMessageId: `c${seq}`,
+                        at: `2026-08-07T00:00:0${seq}.000Z`,
+                        kind: "text",
+                        authorRole: seq % 2 ? "user" : "agent",
+                        text: `m${seq}`,
+                    });
+                }
+                const rows = await port.listRecentMessages("t1", 3);
+                expect(rows.map((r) => r.seq)).toEqual([3, 4, 5]);
+            });
+        });
+        it("findByClientMessageId resolves the idempotency key within its thread only", async () => {
+            await withHarness(make, async (port) => {
+                await port.createThread(threadRow("t1"));
+                await port.createThread(threadRow("t2"));
+                await port.putMessage({
+                    threadId: "t1",
+                    seq: 1,
+                    userId: "g_contract",
+                    clientMessageId: "shared-key",
+                    at: "2026-08-07T00:00:01.000Z",
+                    kind: "text",
+                    authorRole: "user",
+                    text: "hello",
+                });
+                expect((await port.findByClientMessageId("t1", "shared-key"))?.seq).toBe(1);
+                expect(await port.findByClientMessageId("t2", "shared-key")).toBeUndefined();
+                expect(await port.findByClientMessageId("t1", "unknown")).toBeUndefined();
+            });
+        });
+        it("snapshot upsert is full-replace and point-readable", async () => {
+            await withHarness(make, async (port) => {
+                await port.createThread(threadRow("t1"));
+                expect(await port.getSnapshot("t1")).toBeUndefined();
+                await port.putSnapshot({
+                    threadId: "t1",
+                    userId: "g_contract",
+                    threadMemory: [{ scope: "thread", key: "k", value: "v1" }],
+                    workingState: { step: 1 },
+                    updatedAt: "2026-08-07T00:00:01.000Z",
+                });
+                await port.putSnapshot({
+                    threadId: "t1",
+                    userId: "g_contract",
+                    threadMemory: [],
+                    updatedAt: "2026-08-07T00:00:02.000Z",
+                });
+                const snap = await port.getSnapshot("t1");
+                expect(snap?.threadMemory).toEqual([]);
+                expect(snap?.workingState).toBeUndefined();
+            });
+        });
+    });
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@guuey/threads",
+  "version": "0.2.2",
+  "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",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/contract-suite.d.ts",
+      "import": "./dist/testing/contract-suite.js"
+    }
+  },
+  "dependencies": {
+    "@silverprotocol/core": "0.4.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "guuey",
+    "threads",
+    "sessions",
+    "persistence",
+    "rehydration",
+    "agjson",
+    "agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/withguuey/guuey-sdks.git",
+    "directory": "packages/threads"
+  },
+  "homepage": "https://guuey.com",
+  "bugs": {
+    "url": "https://github.com/loqu-co/guuey/issues"
+  },
+  "peerDependencies": {
+    "vitest": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}