@xandreed/core 0.13.0 → 0.14.0

package/dist/session/sessions.conformance.js

@@ -0,0 +1,355 @@
+import { Deferred, Effect, Exit, Fiber, Option, Ref, Scope } from "effect";
+import { check, expect, freshId, kindsOf, pixelPng, settles } from "../conformance.functions.js";
+import { mediaFromBase64 } from "../domain/media.entity.functions.js";
+import { canonicalJson } from "../memory/memory-log.entity.functions.js";
+import { TurnAdmission } from "../ports/turn-admission.port.js";
+import { UserMessage } from "../turn/user-message.entity.js";
+import { TurnRefused } from "./sessions.entity.js";
+const admitAll = TurnAdmission.of({ admit: (_turn, open) => open }), LONG = 600000, SHORT = 1000, say = (text, key = text, command = {}) => ({ _tag: "User", userMessage: new UserMessage({ text }), runId: `run-${key}`, key, command }), resume = (turn, key = `resume:${turn}`) => ({ _tag: "User", userMessage: new UserMessage({ text: "Continue." }), runId: `run-${key}`, key, command: {}, resumes: turn }), completed = { reason: "completed", failure: Option.none() }, item = (id) => ({ id, source: { kind: "conformance", id }, content: `the result of ${id}` }), turnOf = (event) => Option.getOrElse(event.turn, () => 0), codeOf = (event) => {
+  const failure = event.data.failure;
+  return typeof failure === "object" && failure !== null && "code" in failure && typeof failure.code === "string" ? failure.code : "none";
+}, endings = (events) => events.filter((event) => event.kind === "turn.ended").map((event) => `${turnOf(event)}:${String(event.data.reason)}:${codeOf(event)}`).join(), created = (sessions, owner) => sessions.create({ owner }).pipe(Effect.map((view) => ({ id: view.header.id, owner }))), openTurn = (sessions, address) => sessions.get(address).pipe(Effect.map((view) => Option.map(view.open, (open) => open.turn))), refusal = (sessions, address, input) => Effect.scoped(sessions.begin(address, input)).pipe(Effect.match({
+  onFailure: (error) => error._tag === "NotResumable" ? `NotResumable:${error.reason}` : error._tag,
+  onSuccess: (writer) => `opened turn ${writer.admitted.turn}`
+})), writeRefused = (writer) => writer.append([{ kind: "conformance.late", data: {} }]).pipe(Effect.andThen(writer.flush), Effect.match({ onFailure: (error) => error.code, onSuccess: () => "stored" })), scopeOfCheck = Effect.acquireRelease(Scope.make(), (scope) => Scope.close(scope, Exit.void));
+export const sessionsConformance = (subject) => {
+  const scoped = (name, id, body) => check(name, id, (owner) => Effect.scoped(body(owner))), leased = (ttlMs = LONG, admission = admitAll) => subject.leased({ ttlMs, admission });
+  return [
+    scoped("a session is created empty, read back by its owner only, and its id is created once", "create", (owner) => Effect.gen(function* () {
+      const { sessions } = yield* leased(), view = yield* sessions.create({ owner, origin: "conformance", meta: { purpose: "kit", nested: { list: [1, "two", null] } } }), address = { id: view.header.id, owner };
+      yield* expect("create", view.header.owner === owner && view.header.origin === "conformance" && Option.isNone(view.header.parent) && canonicalJson(view.header.meta) === canonicalJson({ purpose: "kit", nested: { list: [1, "two", null] } }), `the header was created as ${canonicalJson({ ...view.header, parent: null })}`);
+      yield* expect("create", view.turns === 0 && Option.isNone(view.open) && view.pending === 0, `a new session shows ${view.turns} turns, ${view.pending} waiting, ${Option.isSome(view.open) ? "one open" : "none open"}`);
+      const read = yield* sessions.get(address);
+      yield* expect("create", read.header.id === view.header.id && read.turns === 0, "get does not read the session as it was created");
+      const again = yield* Effect.flip(sessions.create({ owner, id: view.header.id }));
+      yield* expect("create", again._tag === "SessionExists", `creating an existing id gave ${again._tag}`);
+      const stranger = { ...address, owner: `${owner}-stranger` }, refused = [
+        yield* Effect.flip(sessions.get(stranger)),
+        yield* Effect.flip(sessions.read(stranger)),
+        yield* Effect.flip(sessions.cancel(stranger, 1)),
+        yield* Effect.flip(sessions.get({ id: yield* freshId, owner }))
+      ].map((error) => error._tag);
+      yield* expect("create", refused.every((tag) => tag === "SessionMissing"), `another owner's address and an unknown id gave ${refused.join()}`);
+      yield* expect("create", (yield* sessions.read(address)).length === 0, "a new session holds events");
+    })),
+    scoped("an owner's sessions are listed newest first in pages, and a session's children only under it", "list", (owner) => Effect.gen(function* () {
+      const { sessions } = yield* leased(), first = yield* created(sessions, owner);
+      yield* subject.advance(10);
+      const second = yield* created(sessions, owner);
+      yield* subject.advance(10);
+      const third = yield* created(sessions, owner), child = yield* sessions.fork(first, { origin: "conformance", inherit: !1 }), page = yield* sessions.list({ owner, limit: 2 });
+      yield* expect("list", page.sessions.map((view) => view.header.id).join() === [third.id, second.id].join() && Option.isSome(page.next), `the first page of two lists ${page.sessions.length} sessions${Option.isSome(page.next) ? "" : " and no next page"}`);
+      const rest = yield* sessions.list({ owner, limit: 2, ...Option.match(page.next, { onNone: () => ({}), onSome: (before) => ({ before }) }) });
+      yield* expect("list", rest.sessions.map((view) => view.header.id).join() === first.id && Option.isNone(rest.next), `the page after it lists ${rest.sessions.length} sessions${Option.isSome(rest.next) ? " and another page" : ""}`);
+      const children = yield* sessions.list({ owner, parent: first.id });
+      yield* expect("list", children.sessions.map((view) => view.header.id).join() === child.header.id, `the parent's children are ${children.sessions.length}`);
+      const others = yield* sessions.list({ owner: `${owner}-stranger` });
+      yield* expect("list", others.sessions.length === 0, "another owner lists these sessions");
+    })),
+    scoped("a fork's history is its parent's up to the last closed turn and its turns count on from there; a spawn starts empty", "fork", (owner) => Effect.gen(function* () {
+      const { sessions } = yield* leased(), parent = yield* created(sessions, owner);
+      yield* Effect.scoped(sessions.begin(parent, say("one")).pipe(Effect.tap((writer) => writer.append([{ kind: "conformance.answer", data: { n: 1 } }]).pipe(Effect.andThen(writer.end(completed))))));
+      const left = yield* scopeOfCheck, open = yield* sessions.begin(parent, say("two")).pipe(Scope.provide(left));
+      yield* open.append([{ kind: "conformance.answer", data: { n: 2 } }]);
+      yield* open.flush;
+      const fork = yield* sessions.fork(parent, { origin: "conformance", inherit: !0, meta: { task: "t1" } }), closing = (yield* sessions.read(parent, { kinds: ["turn.ended"] })).at(-1), lineage = fork.header.parent;
+      yield* expect("fork", Option.exists(lineage, (at) => at.id === parent.id && at.turnAtFork === 1 && at.through === (closing?.seq ?? -1)) && fork.turns === 1 && fork.header.owner === owner && fork.header.origin === "conformance" && canonicalJson(fork.header.meta) === canonicalJson({ task: "t1" }), `the fork's lineage is ${canonicalJson(Option.getOrNull(lineage))} with ${fork.turns} turns`);
+      const child = { id: fork.header.id, owner }, writer = yield* sessions.begin(child, say("in the fork"));
+      yield* expect("fork", writer.admitted.turn === 2, `the fork's first turn is ${writer.admitted.turn}, not 2`);
+      const history = kindsOf(yield* writer.history([]));
+      yield* expect("fork", history === "turn.started@1,conformance.answer@1,turn.ended@1", `the fork's history is ${history}`);
+      yield* writer.append([{ kind: "conformance.answer", data: { n: 3 } }]);
+      const snapshot = kindsOf(yield* writer.snapshot(["conformance.answer"]));
+      yield* expect("fork", snapshot === "conformance.answer@1,conformance.answer@2", `the fork's snapshot is ${snapshot}`);
+      const spawn = yield* sessions.fork(parent, { origin: "conformance", inherit: !1 }), fresh = yield* sessions.begin({ id: spawn.header.id, owner }, say("from nothing"));
+      yield* expect("fork", spawn.turns === 0 && fresh.admitted.turn === 1 && (yield* fresh.history([])).length === 0, `a spawn starts at ${spawn.turns} turns`);
+      const orphan = yield* Effect.flip(sessions.fork({ id: yield* freshId, owner }, { origin: "conformance", inherit: !0 }));
+      yield* expect("fork", orphan._tag === "SessionMissing", `forking a missing session gave ${orphan._tag}`);
+    })),
+    scoped("one turn is open per session: a second begin is SessionBusy on any instance, which also sees the turn open", "busy", (owner) => Effect.gen(function* () {
+      const [one, two] = [yield* leased(), yield* leased()], address = yield* created(one.sessions, owner), writer = yield* one.sessions.begin(address, say("first", "k1", { canvas: "c1" })), admitted = writer.admitted;
+      yield* expect("busy", admitted.turn === 1 && admitted.key === "k1" && admitted.runId === "run-k1" && admitted.origin === "user" && admitted.userMessage.text === "first" && canonicalJson(admitted.command) === canonicalJson({ canvas: "c1" }) && admitted.claimed.length === 0 && admitted.session.id === address.id && writer.started.kind === "turn.started" && Option.contains(writer.started.turn, 1), `the turn was admitted as ${canonicalJson({ ...admitted, userMessage: admitted.userMessage.text })}`);
+      const views = [yield* one.sessions.get(address), yield* two.sessions.get(address)];
+      yield* expect("busy", views.every((view) => Option.exists(view.open, (open) => open.turn === 1 && open.key === "k1" && open.origin === "user") && view.turns === 1), "an instance does not show the open turn");
+      const busy = [yield* Effect.flip(Effect.scoped(one.sessions.begin(address, say("second", "k2")))), yield* Effect.flip(Effect.scoped(two.sessions.begin(address, say("second", "k2"))))];
+      yield* expect("busy", busy.every((error) => error._tag === "SessionBusy" && error.turn === 1), `a second begin gave ${busy.map((error) => error._tag).join()}`);
+      yield* writer.end(completed);
+      const next = yield* two.sessions.begin(address, say("second", "k2"));
+      yield* expect("busy", next.admitted.turn === 2 && Option.contains(yield* openTurn(one.sessions, address), 2), `the begin after the end opened turn ${next.admitted.turn}`);
+      const started = kindsOf(yield* one.sessions.read(address, { kinds: ["turn.started"] }));
+      yield* expect("busy", started === "turn.started@1,turn.started@2", `the session stored ${started}`);
+    })),
+    scoped("of begins racing on one session from several instances, exactly one opens a turn", "race", (owner) => Effect.gen(function* () {
+      const instances = [yield* leased(), yield* leased(), yield* leased()], address = yield* created(instances[0].sessions, owner), attempts = yield* Effect.forEach(instances, (instance, n) => Effect.result(instance.sessions.begin(address, say(`racer ${n}`))), { concurrency: "unbounded" }), won = attempts.filter((attempt) => attempt._tag === "Success").length, busy = attempts.filter((attempt) => attempt._tag === "Failure" && attempt.failure._tag === "SessionBusy").length;
+      yield* expect("race", won === 1 && busy === 2, `of three racing begins ${won} opened a turn and ${busy} were busy`);
+      const started = (yield* instances[1].sessions.read(address, { kinds: ["turn.started"] })).length;
+      yield* expect("race", started === 1, `the race stored ${started} turns`);
+    })),
+    scoped("a key's retry is the same turn (TurnDuplicate, whatever its meta) and anything else under the key a KeyConflict", "duplicate", (owner) => Effect.gen(function* () {
+      const { sessions } = yield* leased(), address = yield* created(sessions, owner), asked = (text, canvas, meta) => meta === void 0 ? say(text, "k1", { canvas }) : { ...say(text, "k1", { canvas }), meta }, writer = yield* sessions.begin(address, asked("find alpha", "c1", { request: "r1" })), retries = [
+        yield* Effect.flip(Effect.scoped(sessions.begin(address, asked("find alpha", "c1", { request: "r2" })))),
+        yield* Effect.flip(Effect.scoped(sessions.begin(address, asked("find alpha", "c1"))))
+      ];
+      yield* expect("duplicate", retries.every((error) => error._tag === "TurnDuplicate" && error.turn === 1 && error.open), `a retry while the turn is open gave ${retries.map((error) => error._tag === "TurnDuplicate" ? `TurnDuplicate(${error.turn}, open ${error.open})` : error._tag).join()}`);
+      const conflicts = [
+        yield* Effect.flip(Effect.scoped(sessions.begin(address, asked("find beta", "c1")))),
+        yield* Effect.flip(Effect.scoped(sessions.begin(address, asked("find alpha", "c2"))))
+      ];
+      yield* expect("duplicate", conflicts.every((error) => error._tag === "KeyConflict" && error.key === "k1" && error.turn === 1), `another message or command under the key gave ${conflicts.map((error) => error._tag).join()}`);
+      yield* expect("duplicate", Option.contains(yield* sessions.lookup(address, "k1"), 1) && Option.isNone(yield* sessions.lookup(address, "k-unused")), "lookup does not find the key's turn");
+      yield* writer.end(completed);
+      const after = yield* Effect.flip(Effect.scoped(sessions.begin(address, asked("find alpha", "c1"))));
+      yield* expect("duplicate", after._tag === "TurnDuplicate" && !after.open, `a retry after the turn ended gave ${after._tag}${after._tag === "TurnDuplicate" ? `, open ${after.open}` : ""}`);
+      const started = kindsOf(yield* sessions.read(address, { kinds: ["turn.started"] }));
+      yield* expect("duplicate", started === "turn.started@1", `the retries stored ${started}`);
+    })),
+    scoped("a turn's meta is stored, admitted and shown to the host's admission, {} when none is given, and the inbox's from drain", "meta", (owner) => Effect.gen(function* () {
+      const seen = yield* Ref.make([]), recording = TurnAdmission.of({ admit: (turn, open) => Ref.update(seen, (all) => [...all, canonicalJson(turn.meta)]).pipe(Effect.andThen(open)) }), { sessions } = yield* leased(LONG, recording), address = yield* created(sessions, owner), shown = yield* Effect.scoped(sessions.begin(address, { ...say("one", "k1"), meta: { tenant: "acme", nested: { n: 1 } } }).pipe(Effect.tap((writer) => writer.end(completed)), Effect.map((writer) => [canonicalJson(writer.admitted.meta), canonicalJson(writer.started.data.meta ?? null)])));
+      yield* expect("meta", shown.every((json) => json === canonicalJson({ tenant: "acme", nested: { n: 1 } })), `the turn's meta was admitted and stored as ${shown.join(" and ")}`);
+      const plain = yield* Effect.scoped(sessions.begin(address, say("two", "k2")).pipe(Effect.tap((writer) => writer.end(completed)), Effect.map((writer) => [canonicalJson(writer.admitted.meta), canonicalJson(writer.started.data.meta ?? {})])));
+      yield* expect("meta", plain.every((json) => json === "{}"), `a turn without meta was admitted and stored with ${plain.join(" and ")}`);
+      yield* sessions.deliver(address, item("i1"));
+      const drained = yield* Ref.make([]);
+      yield* sessions.drain(address, (writer) => Ref.set(drained, [canonicalJson(writer.admitted.meta), canonicalJson(writer.started.data.meta ?? null)]), { maxTurns: 1, meta: { source: "drain" } });
+      yield* expect("meta", (yield* Ref.get(drained)).join() === [canonicalJson({ source: "drain" }), canonicalJson({ source: "drain" })].join(), `the inbox turn's meta was ${(yield* Ref.get(drained)).join(" and ")}`);
+      const admitted = (yield* Ref.get(seen)).join(" ");
+      yield* expect("meta", admitted === [canonicalJson({ tenant: "acme", nested: { n: 1 } }), "{}", canonicalJson({ source: "drain" })].join(" "), `the host's admission saw ${admitted}`);
+    })),
+    scoped("only the last user's turn, cancelled or interrupted, is resumed; every other is NotResumable with why, and nothing opens", "resume", (owner) => Effect.gen(function* () {
+      const { sessions } = yield* leased(), address = yield* created(sessions, owner);
+      yield* Effect.scoped(sessions.begin(address, say("one")).pipe(Effect.tap((writer) => writer.end(completed))));
+      const early = [yield* refusal(sessions, address, resume(1)), yield* refusal(sessions, address, resume(7)), yield* refusal(sessions, address, resume(1.5, "resume:half"))];
+      yield* expect("resume", early.join() === "NotResumable:finished,NotResumable:missing,NotResumable:missing", `resuming a completed, an unknown and a fractional turn gave ${early.join()}`);
+      yield* sessions.begin(address, say("two"));
+      yield* sessions.cancel(address, 2);
+      const resumed = yield* Effect.scoped(sessions.begin(address, resume(2)).pipe(Effect.tap((writer) => writer.end(completed)), Effect.map((writer) => [writer.admitted.turn, writer.admitted.resumes ?? null, writer.started.data.resumes ?? null].join())));
+      yield* expect("resume", resumed === "3,2,2", `resuming the cancelled turn 2 admitted turn, resumes and stored resumes ${resumed}`);
+      const after = [yield* refusal(sessions, address, resume(2)), yield* refusal(sessions, address, resume(2, "resume:2:again"))];
+      yield* expect("resume", after.join() === "TurnDuplicate,NotResumable:superseded", `retrying the resume, and resuming again under a new key, gave ${after.join()}`);
+      yield* sessions.deliver(address, item("i1"));
+      yield* sessions.drain(address, () => Effect.interrupt, { maxTurns: 1 });
+      const inbox = yield* refusal(sessions, address, resume(4));
+      yield* expect("resume", inbox === "NotResumable:inbox", `resuming an interrupted inbox turn gave ${inbox}`);
+      const before = yield* sessions.get(address), busyFirst = yield* Effect.scoped(Effect.gen(function* () {
+        yield* sessions.begin(address, say("open"));
+        return yield* refusal(sessions, address, resume(4));
+      }));
+      yield* expect("resume", busyFirst === "SessionBusy", `a resume while a turn is open gave ${busyFirst}`);
+      yield* expect("resume", before.turns === 4, `the refused resumes moved the session to ${before.turns} turns`);
+    })),
+    scoped("a message whose image its bytes do not support is refused with AttachmentRejected and opens nothing; a good one is stored", "attachments", (owner) => Effect.gen(function* () {
+      const { sessions } = yield* leased(), address = yield* created(sessions, owner), image = yield* mediaFromBase64(pixelPng, { name: "pixel.png" }), asked = (attachments, key) => ({ _tag: "User", userMessage: new UserMessage({ text: "what is this?", attachments }), runId: `run-${key}`, key, command: {} }), rejected = yield* refusal(sessions, address, asked([{ ...image, data: "aGVsbG8gd29ybGQ=" }], "k1"));
+      yield* expect("attachments", rejected === "AttachmentRejected", `an image that is text gave ${rejected}`);
+      const view = yield* sessions.get(address);
+      yield* expect("attachments", view.turns === 0 && Option.isNone(view.open) && (yield* sessions.read(address)).length === 0, "a refused image opened or stored something");
+      const writer = yield* sessions.begin(address, asked([image], "k2")), kept = writer.admitted.userMessage.attachments?.map((media) => media.fingerprint).join() ?? "";
+      yield* expect("attachments", writer.admitted.turn === 1 && kept === image.fingerprint && JSON.stringify(writer.started.data.userMessage ?? null).includes(image.fingerprint), `a good image was admitted as ${kept || "nothing"}`);
+    })),
+    scoped("an inbox turn with nothing waiting is NothingPending and opens nothing; a drain then runs none", "nothing-pending", (owner) => Effect.gen(function* () {
+      const { sessions } = yield* leased(), address = yield* created(sessions, owner), refused = yield* refusal(sessions, address, { _tag: "Inbox", runId: "run-inbox" });
+      yield* expect("nothing-pending", refused === "NothingPending", `an inbox turn with nothing waiting gave ${refused}`);
+      const ran = yield* Ref.make(0), drained = yield* sessions.drain(address, () => Ref.update(ran, (count) => count + 1));
+      yield* expect("nothing-pending", drained.turns === 0 && (yield* Ref.get(ran)) === 0, `a drain with nothing waiting ran ${yield* Ref.get(ran)} turns`);
+      const view = yield* sessions.get(address);
+      yield* expect("nothing-pending", view.turns === 0 && (yield* sessions.read(address)).length === 0, "nothing waiting still opened or stored something");
+    })),
+    scoped("a writer stores in order, stamped with its turn; its end stores how the turn ended, an unended scope failed and an interrupted one interrupted", "writer", (owner) => Effect.gen(function* () {
+      const { sessions } = yield* leased(), address = yield* created(sessions, owner), late = yield* Effect.scoped(Effect.gen(function* () {
+        const writer = yield* sessions.begin(address, say("one"));
+        yield* writer.append([{ kind: "conformance.a", data: { n: 1 } }, { kind: "conformance.b", data: { n: 2 } }]);
+        const written = yield* writer.write(Effect.succeed("in order"));
+        yield* expect("writer", written === "in order", "write did not return its operation's value");
+        yield* writer.append([{ kind: "conformance.c", data: { n: 3 } }]);
+        const snapshot = kindsOf(yield* writer.snapshot(["conformance.a", "conformance.b", "conformance.c"]));
+        yield* expect("writer", snapshot === "conformance.a@1,conformance.b@1,conformance.c@1", `the turn's snapshot is ${snapshot}`);
+        const ended = yield* writer.end(completed);
+        yield* expect("writer", ended.pending === 0, `the end reports ${ended.pending} items waiting`);
+        return yield* writeRefused(writer);
+      }));
+      yield* expect("writer", late === "turn.closed", `a write after the end gave ${late}`);
+      yield* Effect.scoped(sessions.begin(address, say("two")).pipe(Effect.tap((writer) => writer.end({ reason: "failed", failure: Option.some({ code: "conformance.failed", message: "the host failed" }) }))));
+      yield* Effect.scoped(sessions.begin(address, say("three")));
+      const begun = yield* Deferred.make(), held = yield* Effect.forkChild(Effect.scoped(sessions.begin(address, say("four")).pipe(Effect.andThen(Deferred.succeed(begun, void 0)), Effect.andThen(Effect.never))));
+      yield* Deferred.await(begun);
+      yield* Fiber.interrupt(held);
+      const all = yield* sessions.read(address), stored = endings(all);
+      yield* expect("writer", stored === "1:completed:none,2:failed:conformance.failed,3:failed:turn.unended,4:interrupted:turn.interrupted", `the turns ended ${stored}`);
+      const first = kindsOf(all.filter((event) => turnOf(event) === 1));
+      yield* expect("writer", first === "turn.started@1,conformance.a@1,conformance.b@1,conformance.c@1,turn.ended@1", `turn 1 stored ${first}`);
+      const view = yield* sessions.get(address);
+      yield* expect("writer", view.turns === 4 && Option.isNone(view.open), `after four ended turns the session shows ${view.turns} turns${Option.isSome(view.open) ? " and one open" : ""}`);
+    })),
+    scoped("transact records outside a turn, and the framework's kinds are refused as ReservedKind", "transact", (owner) => Effect.gen(function* () {
+      const { sessions } = yield* leased(), address = yield* created(sessions, owner), decided = yield* sessions.transact(address, (view) => Effect.succeed({ drafts: [{ kind: "conformance.note", data: { turns: view.turns } }], result: "noted" }));
+      yield* expect("transact", decided.result === "noted" && kindsOf(decided.events) === "conformance.note", `transact returned ${String(decided.result)} with ${kindsOf(decided.events)}`);
+      const reserved = yield* Effect.flip(sessions.transact(address, () => Effect.succeed({ drafts: [{ kind: "turn.ended", data: {} }], result: void 0 })));
+      yield* expect("transact", reserved._tag === "ReservedKind", `recording turn.ended gave ${reserved._tag}`);
+      const all = kindsOf(yield* sessions.read(address));
+      yield* expect("transact", all === "conformance.note", `the session holds ${all}`);
+    })),
+    scoped("a cancel ends exactly the open turn as cancelled and closes its writer, on its own instance at once and on another at its next write", "cancel", (owner) => Effect.gen(function* () {
+      const [holder, other] = [yield* leased(), yield* leased()], address = yield* created(holder.sessions, owner), local = yield* holder.sessions.begin(address, say("stop me")), cancelled = yield* holder.sessions.cancel(address, 1);
+      yield* expect("cancel", cancelled.cancelled && cancelled.pending === 0, `cancelling the open turn answered ${canonicalJson(cancelled)}`);
+      const closed = yield* local.closed;
+      yield* expect("cancel", closed.reason === "cancelled" && closed.turn === 1, `the holder's writer was closed as ${closed.reason}`);
+      yield* expect("cancel", (yield* writeRefused(local)) === "turn.closed", "the cancelled writer still writes");
+      const remote = yield* holder.sessions.begin(address, say("elsewhere"));
+      yield* expect("cancel", (yield* other.sessions.cancel(address, 2)).cancelled, "another instance could not cancel the open turn");
+      yield* expect("cancel", (yield* writeRefused(remote)) === "turn.closed", "a writer cancelled from another instance still writes");
+      const closedRemotely = yield* remote.closed;
+      yield* expect("cancel", closedRemotely.reason === "cancelled", `a writer cancelled from another instance was closed as ${closedRemotely.reason}`);
+      const third = yield* holder.sessions.begin(address, say("three")), wrong = [yield* other.sessions.cancel(address, 2), yield* other.sessions.cancel(address, 1)];
+      yield* expect("cancel", wrong.every((answer) => !answer.cancelled) && Option.contains(yield* openTurn(other.sessions, address), third.admitted.turn), "a cancel naming a turn that is not open closed something");
+      const stored = endings(yield* holder.sessions.read(address, { kinds: ["turn.ended"] }));
+      yield* expect("cancel", stored === "1:cancelled:none,2:cancelled:none", `the cancels stored ${stored}`);
+    })),
+    scoped("removing a session closes its open turn and removes its children", "remove", (owner) => Effect.gen(function* () {
+      const { sessions } = yield* leased(), address = yield* created(sessions, owner), child = yield* sessions.fork(address, { origin: "conformance", inherit: !1 }), writer = yield* sessions.begin(address, say("open"));
+      yield* sessions.remove(address);
+      const closed = yield* writer.closed;
+      yield* expect("remove", closed.reason === "removed", `the open turn's writer was closed as ${closed.reason}`);
+      const gone = [yield* Effect.flip(sessions.get(address)), yield* Effect.flip(sessions.get({ id: child.header.id, owner })), yield* Effect.flip(sessions.remove(address))];
+      yield* expect("remove", gone.every((error) => error._tag === "SessionMissing"), `after the removal the session, its child and a second removal gave ${gone.map((error) => error._tag).join()}`);
+    })),
+    scoped("the inbox: an item is delivered once per id, taken by one inbox turn, waits for the open turn, comes back when its turn is interrupted from outside, and is done when its turn is cancelled", "inbox", (owner) => Effect.gen(function* () {
+      const { sessions } = yield* leased(), address = yield* created(sessions, owner), delivered = [yield* sessions.deliver(address, item("i1")), yield* sessions.deliver(address, item("i1"))];
+      yield* expect("inbox", delivered.map((answer) => `${answer.delivered}:${answer.pending}`).join() === "true:1,false:1", `delivering one item twice answered ${canonicalJson(delivered)}`);
+      const taken = yield* Ref.make(Option.none()), drained = yield* sessions.drain(address, (writer) => Ref.set(taken, Option.some(writer.admitted))), turn = yield* Ref.get(taken);
+      yield* expect("inbox", drained.turns === 1 && Option.exists(turn, (admitted) => admitted.origin === "inbox" && admitted.claimed.map((claimed) => claimed.id).join() === "i1" && admitted.claimed[0]?.content === item("i1").content && admitted.userMessage.text.includes(item("i1").content)), `the drain ran ${drained.turns} turns, taking ${canonicalJson(Option.getOrNull(Option.map(turn, (admitted) => admitted.claimed)))}`);
+      yield* expect("inbox", (yield* sessions.get(address)).pending === 0 && endings(yield* sessions.read(address)) === "1:completed:none", "the inbox turn did not end completed with its item taken");
+      yield* expect("inbox", !(yield* sessions.deliver(address, item("i1"))).delivered, "an item delivered again after it was taken is stored again");
+      const writer = yield* sessions.begin(address, say("long answer"));
+      yield* expect("inbox", (yield* sessions.deliver(address, item("i2"))).pending === 1, "an item delivered during a turn does not wait");
+      yield* expect("inbox", (yield* sessions.drain(address, () => Effect.void)).turns === 0, "a drain ran an inbox turn while a turn was open");
+      yield* expect("inbox", (yield* writer.end(completed)).pending === 1, "the turn's end does not report the item that waits");
+      yield* expect("inbox", (yield* sessions.drain(address, () => Effect.void)).turns === 1, "the drain after the turn did not take the item");
+      yield* sessions.deliver(address, item("i3"));
+      const entered = yield* Deferred.make(), held = yield* Effect.forkChild(sessions.drain(address, () => Deferred.succeed(entered, void 0).pipe(Effect.andThen(Effect.never))));
+      yield* Deferred.await(entered);
+      yield* Fiber.interrupt(held);
+      const back = yield* sessions.get(address);
+      yield* expect("inbox", back.pending === 1 && Option.isNone(back.open), `after its inbox turn was interrupted from outside ${back.pending} items wait${Option.isSome(back.open) ? " and a turn is open" : ""}`);
+      yield* expect("inbox", (yield* sessions.drain(address, () => Effect.void)).turns === 1 && (yield* sessions.get(address)).pending === 0, "the item given back was not taken by the next drain");
+      const queued = (yield* sessions.read(address, { kinds: ["inbox.queued"] })).length;
+      yield* expect("inbox", queued === 3, `three items were stored as ${queued}`);
+      yield* sessions.deliver(address, item("i4"));
+      const claiming = yield* Deferred.make(), claim = yield* Effect.forkChild(sessions.drain(address, (writer) => Deferred.succeed(claiming, writer.admitted.turn).pipe(Effect.andThen(Effect.never)))), claimTurn = yield* Deferred.await(claiming), stopped = yield* sessions.cancel(address, claimTurn);
+      yield* Fiber.interrupt(claim);
+      const done = yield* sessions.get(address);
+      yield* expect("inbox", stopped.cancelled && stopped.pending === 0 && done.pending === 0 && Option.isNone(done.open), `after its inbox turn was cancelled ${done.pending} items wait${Option.isSome(done.open) ? " and a turn is open" : ""} (a cancelled turn's items are done)`);
+      const last = endings(yield* sessions.read(address, { kinds: ["turn.ended"] })).split(",").at(-1);
+      yield* expect("inbox", last === `${claimTurn}:cancelled:none`, `the cancelled inbox turn was closed as ${last ?? "nothing"}`);
+      yield* expect("inbox", (yield* sessions.drain(address, () => Effect.void)).turns === 0, "a drain took again an item whose turn was cancelled");
+    })),
+    scoped("a turn whose lease ran out is shown closed, left alone by a drain with nothing waiting, reaped as interrupted by the next begin, and its writer refused", "lease", (owner) => Effect.gen(function* () {
+      const [first, second] = [yield* leased(SHORT), yield* leased(SHORT)], address = yield* created(first.sessions, owner), writer = yield* first.sessions.begin(address, say("slow"));
+      yield* subject.advance(SHORT / 2);
+      yield* expect("lease", Option.contains(yield* openTurn(second.sessions, address), 1), "a turn within its lease is shown closed");
+      const early = yield* refusal(second.sessions, address, say("too early"));
+      yield* expect("lease", early === "SessionBusy", `a begin within the lease gave ${early}`);
+      yield* subject.advance(SHORT);
+      yield* expect("lease", Option.isNone(yield* openTurn(second.sessions, address)), "a turn past its lease is still shown open");
+      const idle = yield* second.sessions.drain(address, () => Effect.void), unreaped = endings(yield* second.sessions.read(address, { kinds: ["turn.ended"] }));
+      yield* expect("lease", idle.turns === 0 && unreaped === "", `a drain with nothing waiting ran ${idle.turns} turns and stored ${unreaped || "no ending"} (only a turn that opens reaps)`);
+      const next = yield* second.sessions.begin(address, say("next"));
+      yield* expect("lease", next.admitted.turn === 2, `the begin after the lease opened turn ${next.admitted.turn}`);
+      const reaped = endings(yield* second.sessions.read(address, { kinds: ["turn.ended"] }));
+      yield* expect("lease", reaped === "1:interrupted:turn.lease", `the expired turn was closed as ${reaped || "nothing"}`);
+      yield* expect("lease", (yield* writeRefused(writer)) === "turn.closed", "the old holder still writes");
+      const closed = yield* writer.closed;
+      yield* expect("lease", closed.reason === "interrupted", `the old holder's writer was closed as ${closed.reason}`);
+    })),
+    scoped("a write renews the lease: a turn written to within its lease is held for a lease from that write, then reaped", "lease-renewal", (owner) => Effect.gen(function* () {
+      const [holder, other] = [yield* leased(SHORT), yield* leased(SHORT)], address = yield* created(holder.sessions, owner), writer = yield* holder.sessions.begin(address, say("long turn")), step = SHORT * 0.6;
+      yield* subject.advance(step);
+      yield* writer.append([{ kind: "conformance.progress", data: { n: 1 } }]);
+      yield* writer.flush;
+      yield* subject.advance(step);
+      yield* expect("lease-renewal", Option.contains(yield* openTurn(other.sessions, address), 1), `a turn written to ${step} ms ago, ${step * 2} ms after its begin, is shown closed: its write did not renew its lease of ${SHORT} ms`);
+      const held = yield* refusal(other.sessions, address, say("too early"));
+      yield* expect("lease-renewal", held === "SessionBusy", `a begin within the renewed lease gave ${held}`);
+      yield* subject.advance(SHORT);
+      const next = yield* other.sessions.begin(address, say("next")), reaped = endings(yield* other.sessions.read(address, { kinds: ["turn.ended"] }));
+      yield* expect("lease-renewal", next.admitted.turn === 2 && reaped === "1:interrupted:turn.lease", `once the renewed lease ran out the begin opened turn ${next.admitted.turn} and the turn was closed as ${reaped || "nothing"}`);
+      const stored = kindsOf(yield* other.sessions.read(address, { kinds: ["conformance.progress"] }));
+      yield* expect("lease-renewal", stored === "conformance.progress@1", `the renewing write was stored as ${stored || "nothing"}`);
+    })),
+    ...Option.match(Option.fromNullishOr(subject.processOwned), {
+      onNone: () => [],
+      onSome: (processOwned) => [
+        scoped("under process ownership a turn whose process stopped is reaped by the next begin, and one whose process runs stays held", "process", (owner) => Effect.gen(function* () {
+          const named = (pid, startedAt, running) => processOwned({ self: { host: "conformance-host", pid, startedAt }, running, admission: admitAll }), crashed = yield* named(101, 1, [202]), restarted = yield* named(202, 2, [202]), address = yield* created(crashed.sessions, owner), writer = yield* crashed.sessions.begin(address, say("before the crash"));
+          yield* expect("process", Option.isNone(yield* openTurn(restarted.sessions, address)), "a turn whose process stopped is shown open");
+          const next = yield* restarted.sessions.begin(address, say("after the restart"));
+          yield* expect("process", next.admitted.turn === 2, `the begin after the crash opened turn ${next.admitted.turn}`);
+          yield* expect("process", (yield* writeRefused(writer)) === "turn.closed", "the stopped process's writer still writes");
+          const reborn = yield* named(202, 3, [202]), third = yield* reborn.sessions.begin(address, say("pid reused"));
+          yield* expect("process", third.admitted.turn === 3, `a process reusing the holder's pid opened turn ${third.admitted.turn}`);
+          const reaped = endings(yield* reborn.sessions.read(address, { kinds: ["turn.ended"] }));
+          yield* expect("process", reaped === "1:interrupted:turn.lease,2:interrupted:turn.lease", `the stopped holders' turns were closed as ${reaped}`);
+          const alive = yield* named(303, 3, [303, 404]), observer = yield* named(404, 4, [303, 404]), other = yield* created(alive.sessions, owner);
+          yield* alive.sessions.begin(other, say("still running"));
+          yield* expect("process", Option.contains(yield* openTurn(observer.sessions, other), 1), "a turn whose process runs is shown closed");
+          const busy = yield* refusal(observer.sessions, other, say("second"));
+          yield* expect("process", busy === "SessionBusy", `a begin while the holder's process runs gave ${busy}`);
+        }))
+      ]
+    }),
+    scoped("TurnActivity agrees with what is open: a begin counts from the moment it is asked for, then its turn per session and turn until its scope closes", "activity", (owner) => Effect.gen(function* () {
+      const gate = yield* Deferred.make(), queued = yield* Deferred.make(), refusing = yield* Ref.make(!1), admission = TurnAdmission.of({
+        admit: (turn, open) => Effect.gen(function* () {
+          if (yield* Ref.get(refusing))
+            return yield* Effect.fail(new TurnRefused({ session: turn.session.id, reason: "conformance", message: "the kit refuses it" }));
+          if (turn.key === "held at admission")
+            yield* Deferred.succeed(queued, void 0).pipe(Effect.andThen(Deferred.await(gate)));
+          return yield* open;
+        })
+      }), { sessions, activity: provided } = yield* leased(LONG, admission);
+      if (Option.isNone(provided))
+        return;
+      const activity = provided.value, other = yield* leased(), [a, b, c] = [yield* created(sessions, owner), yield* created(sessions, owner), yield* created(sessions, owner)], label = (address) => address.id === a.id ? "a" : address.id === b.id ? "b" : "other", current = activity.current.pipe(Effect.map((now) => ({
+        open: now.open.map((turn) => `${label({ id: turn.session, owner })}:${turn.turn}`).join(),
+        since: now.open.map((turn) => turn.since),
+        beginning: now.beginning
+      }))), shows = (open, beginning, when) => current.pipe(Effect.flatMap((now) => expect("activity", now.open === open && now.beginning === beginning, `${when}: open [${now.open}], beginning ${now.beginning}; expected open [${open}], beginning ${beginning}`)));
+      yield* shows("", 0, "before any begin");
+      yield* expect("activity", yield* settles(yield* Effect.forkChild(activity.idle)), "idle does not complete with nothing open");
+      const scopeA = yield* scopeOfCheck, beginning = yield* Effect.forkChild(sessions.begin(a, say("held at admission")).pipe(Scope.provide(scopeA)));
+      yield* Deferred.await(queued);
+      yield* shows("", 1, "a begin waiting for the host's admission");
+      const idle = yield* Effect.forkChild(activity.idle);
+      yield* expect("activity", !(yield* settles(idle)), "idle completed while a begin was waiting for its admission");
+      yield* Deferred.succeed(gate, void 0);
+      const first = yield* Fiber.join(beginning);
+      yield* shows("a:1", 0, "a turn handed over");
+      yield* subject.advance(10);
+      const scopeB = yield* scopeOfCheck;
+      yield* sessions.begin(b, say("two")).pipe(Scope.provide(scopeB));
+      yield* shows("a:1,b:1", 0, "two sessions with a turn open each");
+      yield* Effect.scoped(Effect.gen(function* () {
+        yield* other.sessions.begin(yield* created(other.sessions, owner), say("elsewhere"));
+        yield* shows("a:1,b:1", 0, "with another instance's turn open");
+      }));
+      yield* first.end(completed);
+      yield* shows("a:1,b:1", 0, "an ended turn whose scope is still open");
+      yield* subject.advance(10);
+      const scopeNext = yield* scopeOfCheck;
+      yield* sessions.begin(a, say("three")).pipe(Scope.provide(scopeNext));
+      yield* shows("a:1,b:1,a:2", 0, "the session's next turn begun while the ended one's scope is open");
+      const since = (yield* current).since;
+      yield* expect("activity", since.every((at, index) => index === 0 || at >= since[index - 1]), `the open turns are not oldest first: since ${since.join()}`);
+      yield* Scope.close(scopeA, Exit.void);
+      yield* shows("b:1,a:2", 0, "after the ended turn's scope closed");
+      yield* Ref.set(refusing, !0);
+      const refused = yield* refusal(sessions, c, say("refused"));
+      yield* expect("activity", refused === "TurnRefused", `a begin the host refuses gave ${refused}`);
+      yield* shows("b:1,a:2", 0, "after a begin the host refused");
+      yield* Ref.set(refusing, !1);
+      yield* expect("activity", !(yield* settles(idle)), "idle completed while turns were open");
+      yield* Scope.close(scopeB, Exit.void);
+      yield* Scope.close(scopeNext, Exit.void);
+      yield* shows("", 0, "after every scope closed");
+      yield* expect("activity", yield* settles(idle), "idle did not complete once nothing was open");
+    }))
+  ];
+};

package/dist/session/sessions.entity.d.ts

@@ -105,8 +105,12 @@ export declare const BeginTurn: Schema.Union<readonly [Schema.TaggedStruct<"User
     /** The host's idempotency key (e.g. the client's command id). */
     readonly key: Schema.String;
     readonly command: Schema.$Record<Schema.String, Schema.Unknown>;
+    readonly meta: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
+    /** The turn this one resumes (see `NotResumable` for which turns can be). */
+    readonly resumes: Schema.optionalKey<Schema.Int>;
 }>, Schema.TaggedStruct<"Inbox", {
     readonly runId: Schema.String;
+    readonly meta: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
 }>]>;
 export type BeginTurn = typeof BeginTurn.Type;
 /** An admitted turn, as the turn's code reads it. */
@@ -129,9 +133,20 @@ export declare const AdmittedTurn: Schema.Struct<{
         /** What the turn that takes it shows the model, framed by the sender. */
         readonly content: Schema.NonEmptyString;
     }>>;
+    /** The host's metadata the turn was begun with (`{}` when none was given). */
+    readonly meta: Schema.$Record<Schema.String, Schema.Unknown>;
+    /** The turn this one resumes, when it resumes one. */
+    readonly resumes: Schema.optionalKey<Schema.Int>;
 }>;
 export type AdmittedTurn = typeof AdmittedTurn.Type;
-/** How a turn ended, as its closer records it. */
+/**
+ * How a turn ended, as its closer records it (`turnEndingOf` gives the
+ * ending of a turn's exit). A failure's `code` is the error's own code when
+ * it has one; otherwise one of the framework's codes (`turn.failed`,
+ * `turn.defect`, `turn.interrupted`, `turn.unended`, `turn.lease`), or a
+ * code the closer passes to `writer.end` itself (plugin-tasks: `task.turn`,
+ * `task.deadline`; a host's own).
+ */
 export declare const TurnEnding: Schema.Struct<{
     readonly reason: Schema.Literals<readonly ["completed", "partial", "failed", "cancelled", "interrupted"]>;
     readonly failure: Schema.OptionFromNullOr<Schema.Struct<{
@@ -152,7 +167,7 @@ declare const TurnDuplicate_base: Schema.Class<TurnDuplicate, Schema.TaggedStruc
     readonly turn: Schema.Int;
     readonly open: Schema.Boolean;
 }>, import("effect/Cause").YieldableError>;
-/** The key was begun before, with the same message: that turn is the answer. */
+/** The key was begun before with the same message, command and `resumes`: that turn is the answer. */
 export declare class TurnDuplicate extends TurnDuplicate_base {
 }
 declare const KeyConflict_base: Schema.Class<KeyConflict, Schema.TaggedStruct<"KeyConflict", {
@@ -160,9 +175,27 @@ declare const KeyConflict_base: Schema.Class<KeyConflict, Schema.TaggedStruct<"K
     readonly key: Schema.String;
     readonly turn: Schema.Int;
 }>, import("effect/Cause").YieldableError>;
-/** The key was begun before with another message or command. */
+/** The key was begun before with another message, command or `resumes`. */
 export declare class KeyConflict extends KeyConflict_base {
 }
+declare const NotResumable_base: Schema.Class<NotResumable, Schema.TaggedStruct<"NotResumable", {
+    readonly session: Schema.brand<Schema.String, "ConversationId">;
+    readonly turn: Schema.Number;
+    readonly reason: Schema.Literals<readonly ["missing", "superseded", "finished", "inbox"]>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A user's turn asked to resume a turn that cannot be resumed: `missing`, no
+ * such turn in the session's own log (a fork's inherited turns are its
+ * parent's; a `resumes` that is not a whole number of at least 1 names no
+ * turn); `inbox`, an inbox turn; `superseded`, a user's turn was begun after
+ * it (other than a resume of it that failed, was cancelled or was
+ * interrupted); `finished`, it ended completed, partial or failed. Only the
+ * last user's turn, ended cancelled or interrupted (a turn reaped because
+ * its holder stopped is interrupted), can be resumed. Nothing was opened.
+ * `turn` is the `resumes` asked for, as given.
+ */
+export declare class NotResumable extends NotResumable_base {
+}
 declare const NothingPending_base: Schema.Class<NothingPending, Schema.TaggedStruct<"NothingPending", {
     readonly session: Schema.brand<Schema.String, "ConversationId">;
 }>, import("effect/Cause").YieldableError>;

package/dist/session/sessions.entity.functions.d.ts

@@ -0,0 +1,42 @@
+import { Exit, Option } from "effect";
+import type { TurnEndReason } from "./session-event.entity.js";
+import type { NotResumable, TurnEnding } from "./sessions.entity.js";
+/**
+ * How a turn ended, from its exit:
+ * - success: the outcome it returned, with no failure;
+ * - a typed error (it wins over an interruption in the same cause): failed,
+ *   with the error's own `code` and message when it has a string `code`, and
+ *   `turn.failed` with `<_tag>: <message>` (or the error as text) otherwise;
+ * - a defect: failed, `turn.defect` (a runner applies
+ *   `harnessDefectsAsFailures` before taking the exit, so a `HarnessError`
+ *   carried as a defect keeps its own code);
+ * - an interruption only: interrupted, `turn.interrupted`.
+ * Messages are cut to 500 characters. A runner whose exit has no outcome
+ * maps it first: `turnEndingOf(Exit.map(exit, () => ({ outcome: "completed" })))`.
+ */
+export declare const turnEndingOf: (exit: Exit.Exit<{
+    readonly outcome: "completed" | "partial" | "failed";
+}, unknown>) => TurnEnding;
+/**
+ * One turn of a session as a resume is checked against it: who began it, the
+ * turn it resumed (when it resumed one) and, once it ended, how.
+ */
+export interface ResumableTurn {
+    readonly turn: number;
+    readonly origin: "user" | "inbox";
+    readonly resumes: Option.Option<number>;
+    readonly ended: Option.Option<TurnEndReason>;
+}
+/**
+ * Why turn `target` cannot be resumed, or none when it can, from the
+ * session's own turns (each `turn.started`, with the turn it resumed and its
+ * `turn.ended`'s reason when it has them): `missing` when no turn has that
+ * number (a number that is not a whole number of at least 1 never does),
+ * `inbox` when an inbox turn has it, `superseded` when a user's turn was
+ * begun after it (only inbox turns, and resumes of it that failed, were
+ * cancelled or were interrupted, may follow), `finished` unless it ended
+ * cancelled or interrupted (a turn reaped because its holder stopped ended
+ * interrupted; one with no end yet is open, which `SessionBusy` answers
+ * first).
+ */
+export declare const resumeRefusal: (target: number, turns: ReadonlyArray<ResumableTurn>) => Option.Option<NotResumable["reason"]>;

package/dist/session/sessions.entity.functions.js

@@ -0,0 +1,26 @@
+import { Cause, Exit, Formatter, Option, Predicate, Result } from "effect";
+const MESSAGE_CHARS = 500, clipped = (text) => text.length <= MESSAGE_CHARS ? text : text.slice(0, MESSAGE_CHARS), stringField = (value, key) => Predicate.isObject(value) ? Option.filter(Option.some(value[key]), Predicate.isString) : Option.none(), fieldsOf = (error) => Predicate.isObject(error) ? Formatter.formatJson(Object.fromEntries(Object.entries(error).filter(([key]) => key !== "_tag"))) : "", failureOfError = (error) => Option.match(stringField(error, "code"), {
+  onSome: (code) => ({ code, message: Option.getOrElse(stringField(error, "message"), () => Formatter.format(error)) }),
+  onNone: () => ({
+    code: "turn.failed",
+    message: Option.match(stringField(error, "_tag"), {
+      onSome: (tag) => `${tag}: ${Option.getOrElse(Option.filter(stringField(error, "message"), (text) => text.length > 0), () => fieldsOf(error))}`,
+      onNone: () => typeof error === "string" ? error : Formatter.format(error)
+    })
+  })
+}), failed = (failure) => ({ reason: "failed", failure: Option.some({ code: failure.code, message: clipped(failure.message) }) });
+export const turnEndingOf = (exit) => Exit.match(exit, {
+  onSuccess: (value) => ({ reason: value.outcome, failure: Option.none() }),
+  onFailure: (cause) => Option.match(Cause.findErrorOption(cause), {
+    onSome: (error) => failed(failureOfError(error)),
+    onNone: () => Result.match(Cause.findDefect(cause), {
+      onSuccess: (defect) => failed({ code: "turn.defect", message: Formatter.format(defect) }),
+      onFailure: () => Cause.hasInterrupts(cause) ? { reason: "interrupted", failure: Option.some({ code: "turn.interrupted", message: "the turn was interrupted" }) } : failed({ code: "turn.failed", message: "the turn failed without an error" })
+    })
+  })
+});
+const stopped = (ended) => Option.exists(ended, (reason) => reason === "cancelled" || reason === "interrupted"), supersedes = (target) => (later) => later.turn > target && later.origin === "user" && !(Option.contains(later.resumes, target) && (stopped(later.ended) || Option.contains(later.ended, "failed")));
+export const resumeRefusal = (target, turns) => Option.match(Option.fromNullishOr(turns.find((candidate) => candidate.turn === target)), {
+  onNone: () => Option.some("missing"),
+  onSome: (found) => found.origin === "inbox" ? Option.some("inbox") : turns.some(supersedes(target)) ? Option.some("superseded") : stopped(found.ended) ? Option.none() : Option.some("finished")
+});

package/dist/session/sessions.entity.js

@@ -25,14 +25,18 @@ export const SessionAddress = Schema.Struct({ id: ConversationId, owner: Schema.
 }), SessionPage = Schema.Struct({
   sessions: Schema.Array(SessionView),
   next: Schema.OptionFromNullOr(SessionListCursor)
-}), BeginTurn = Schema.Union([
+});
+const TurnMeta = Schema.optionalKey(JsonObject), Resumes = Schema.optionalKey(Schema.Int);
+export const BeginTurn = Schema.Union([
   Schema.TaggedStruct("User", {
     userMessage: UserMessage,
     runId: Schema.String,
     key: Schema.String,
-    command: JsonObject
+    command: JsonObject,
+    meta: TurnMeta,
+    resumes: Resumes
   }),
-  Schema.TaggedStruct("Inbox", { runId: Schema.String })
+  Schema.TaggedStruct("Inbox", { runId: Schema.String, meta: TurnMeta })
 ]), AdmittedTurn = Schema.Struct({
   session: SessionAddress,
   turn: Schema.Int,
@@ -41,7 +45,9 @@ export const SessionAddress = Schema.Struct({ id: ConversationId, owner: Schema.
   origin: Schema.Literals(["user", "inbox"]),
   userMessage: UserMessage,
   command: JsonObject,
-  claimed: Schema.Array(InboxItem)
+  claimed: Schema.Array(InboxItem),
+  meta: JsonObject,
+  resumes: Resumes
 }), TurnEnding = Schema.Struct({
   reason: TurnEndReason,
   failure: Schema.OptionFromNullOr(Schema.Struct({ code: Schema.String, message: Schema.String }))
@@ -67,6 +73,13 @@ export class KeyConflict extends Schema.TaggedError()("KeyConflict", {
 }) {
 }
 
+export class NotResumable extends Schema.TaggedError()("NotResumable", {
+  session: ConversationId,
+  turn: Schema.Number,
+  reason: Schema.Literals(["missing", "superseded", "finished", "inbox"])
+}) {
+}
+
 export class NothingPending extends Schema.TaggedError()("NothingPending", {
   session: ConversationId
 }) {

package/dist/session/sessions.entity.test.d.ts

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