@arnilo/prism-server 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [0.2.2] - 2026-08-13
+
+### Changed
+- Conversation create/branch/archive now route through the session-store appendSession version/CAS: concurrent writes surface as metadata_conflict mapped to HTTP 409 (carrying versions only, never metadata content); branch caps are enforced inside the CAS write. See docs/conversations.md.
+
 ## [0.1.0] - 2026-08-09
 
 ### Changed

package/dist/conversations.d.ts

@@ -49,8 +49,14 @@ export declare function resolveConversationLimits(input?: ConversationLimits): R
 export interface ConversationServiceStore {
     querySessions(query: import("@arnilo/prism").SessionQuery): Promise<PersistencePage<SessionRecord>>;
     queryEvents(query: import("@arnilo/prism").AgentEventQuery): Promise<PersistencePage<AgentEventRecord>>;
-    /** Required at factory time; optional in the type so persistence unions stay assignable. */
-    appendSession?(record: SessionRecord): Promise<void>;
+    /** Required at factory time; optional in the type so persistence unions stay assignable.
+     *  Additive CAS: `expectedVersion` requires the stored version to match (0 = create-only);
+     *  the returned `version` is the new write version. Throws `SessionMetadataConflictError`. */
+    appendSession?(record: SessionRecord & {
+        readonly expectedVersion?: number;
+    }): Promise<{
+        readonly version: number;
+    } | void>;
     readonly lifecycle?: Pick<PersistenceLifecycleStore, "applyRetention">;
 }
 export interface ConversationSessionFactoryInput {

package/dist/conversations.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { assertIdentityActive, assertIdentityMatchesOwnership, CONVERSATION_METADATA_KEY, ConversationError, conversationMarkerMetadata, conversationThreadFromRecord, decodeConversationReplayCursor, encodeConversationReplayCursor, } from "@arnilo/prism";
+import { assertIdentityActive, assertIdentityMatchesOwnership, CONVERSATION_METADATA_KEY, ConversationError, conversationMarkerMetadata, conversationThreadFromRecord, decodeConversationReplayCursor, encodeConversationReplayCursor, isSessionMetadataConflict, } from "@arnilo/prism";
 import { PrismServerError } from "./types.js";
 /** Phase 9 freeze: thread page 50/200; replay page 100/500; cursor 4/16 KiB; title 256 B/2 KiB;
  *  request id 256 B/2 KiB; active branches 16/64; export 8/32 MiB and 100/500 pages; body 64 KiB/1 MiB. */
@@ -58,7 +58,7 @@ export function createConversationService(store, options) {
     }
     async function writeMarker(thread, marker) {
         const now = new Date().toISOString();
-        await appendSession({
+        const result = await appendSession({
             id: thread.id,
             ...(thread.tenantId !== undefined ? { tenantId: thread.tenantId } : {}),
             ...(thread.accountId !== undefined ? { accountId: thread.accountId } : {}),
@@ -66,7 +66,13 @@ export function createConversationService(store, options) {
             createdAt: thread.createdAt,
             updatedAt: now,
             metadata: conversationMarkerMetadata(marker),
+            expectedVersion: thread.version ?? 0,
         });
+        return result?.version ?? (thread.version ?? 0) + 1;
+    }
+    /** CAS conflict on create is a race between two get-or-create callers: the winner wins. */
+    function throwMetadataConflict() {
+        throw new ConversationError("Conversation thread changed concurrently", "metadata_conflict");
     }
     return {
         async create(input) {
@@ -80,8 +86,8 @@ export function createConversationService(store, options) {
             if (input.requestId !== undefined)
                 assertBytes(input.requestId, limits.requestIdBytes, "request_id_too_large");
             if (input.id !== undefined) {
-                // Idempotent get-or-create for explicit ids. ponytail: concurrent creates race to the
-                // last metadata write; both callers receive a thread and ownership is enforced on read.
+                // Idempotent get-or-create for explicit ids; the create-only CAS below is the
+                // race backstop, so a concurrent create returns the winner's thread untouched.
                 const existing = await this.get({ ...input, threadId: id }).catch((error) => {
                     if (error instanceof ConversationError && error.reason === "not_found")
                         return undefined;
@@ -91,18 +97,26 @@ export function createConversationService(store, options) {
                     return existing;
             }
             const now = new Date().toISOString();
-            await appendSession({
-                id,
-                ...input.ownership,
-                createdAt: now,
-                updatedAt: now,
-                metadata: conversationMarkerMetadata({
-                    ...(input.title === undefined ? {} : { title: input.title }),
-                    state: "active",
-                    ...(input.requestId === undefined ? {} : { requestId: input.requestId }),
-                    ...(input.metadata === undefined ? {} : { metadata: input.metadata }),
-                }),
-            });
+            try {
+                await appendSession({
+                    id,
+                    ...input.ownership,
+                    createdAt: now,
+                    updatedAt: now,
+                    metadata: conversationMarkerMetadata({
+                        ...(input.title === undefined ? {} : { title: input.title }),
+                        state: "active",
+                        ...(input.requestId === undefined ? {} : { requestId: input.requestId }),
+                        ...(input.metadata === undefined ? {} : { metadata: input.metadata }),
+                    }),
+                    expectedVersion: 0,
+                });
+            }
+            catch (error) {
+                if (isSessionMetadataConflict(error))
+                    return this.get({ ...input, threadId: id });
+                throw error;
+            }
             return this.get({ ...input, threadId: id });
         },
         async list(input) {
@@ -169,26 +183,40 @@ export function createConversationService(store, options) {
             if (thread.branches.length >= limits.maxActiveBranches) {
                 throw new ConversationError("Too many active branches for this thread", "too_many_branches");
             }
-            // ponytail: read-modify-write of branch refs; concurrent branch calls can lose a ref, so
-            // the cap is approximate and the entry tree remains the content source of truth.
-            await writeMarker(thread, {
-                ...(thread.title === undefined ? {} : { title: thread.title }),
-                state: thread.state,
-                branches: [...thread.branches, { leafId, createdAt: new Date().toISOString() }],
-                ...(thread.metadata === undefined ? {} : { metadata: thread.metadata }),
-            });
+            // Branch refs are append-only within the marker; the CAS version guard makes the
+            // read-modify-write atomic, so concurrent branches cannot lose a ref or exceed the cap.
+            try {
+                await writeMarker(thread, {
+                    ...(thread.title === undefined ? {} : { title: thread.title }),
+                    state: thread.state,
+                    branches: [...thread.branches, { leafId, createdAt: new Date().toISOString() }],
+                    ...(thread.metadata === undefined ? {} : { metadata: thread.metadata }),
+                });
+            }
+            catch (error) {
+                if (isSessionMetadataConflict(error))
+                    throwMetadataConflict();
+                throw error;
+            }
             return loadThread(input, thread.id);
         },
         async archive(input) {
             const thread = await loadThread(input, input.threadId);
             if (thread.state === "archived")
                 return thread;
-            await writeMarker(thread, {
-                ...(thread.title === undefined ? {} : { title: thread.title }),
-                state: "archived",
-                ...(thread.branches.length === 0 ? {} : { branches: thread.branches }),
-                ...(thread.metadata === undefined ? {} : { metadata: thread.metadata }),
-            });
+            try {
+                await writeMarker(thread, {
+                    ...(thread.title === undefined ? {} : { title: thread.title }),
+                    state: "archived",
+                    ...(thread.branches.length === 0 ? {} : { branches: thread.branches }),
+                    ...(thread.metadata === undefined ? {} : { metadata: thread.metadata }),
+                });
+            }
+            catch (error) {
+                if (isSessionMetadataConflict(error))
+                    throwMetadataConflict();
+                throw error;
+            }
             return loadThread(input, thread.id);
         },
         async export(input) {
@@ -452,13 +480,15 @@ function conversationErrorResponse(error) {
                 ? 404
                 : error.reason === "thread_archived"
                     ? 409
-                    : error.reason === "ownership"
-                        ? 403
-                        : error.reason === "unsupported"
-                            ? 501
-                            : error.reason === "not_redacted" || error.reason === "limit_exceeded"
-                                ? 500
-                                : 400;
+                    : error.reason === "metadata_conflict"
+                        ? 409
+                        : error.reason === "ownership"
+                            ? 403
+                            : error.reason === "unsupported"
+                                ? 501
+                                : error.reason === "not_redacted" || error.reason === "limit_exceeded"
+                                    ? 500
+                                    : 400;
     }
     else if (error instanceof RangeError) {
         status = 400;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnilo/prism-server",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Optional framework-free Web Request-to-Response handler for explicitly selected Prism agents and workflows.",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,8 +29,8 @@
     "pack:dry-run": "npm pack --dry-run"
   },
   "peerDependencies": {
-    "@arnilo/prism": "0.2.1",
-    "@arnilo/prism-workflows": "0.2.1"
+    "@arnilo/prism": "0.2.2",
+    "@arnilo/prism-workflows": "0.2.2"
   },
   "devDependencies": {
     "@arnilo/prism": "file:../..",