@xandreed/core 0.3.0 → 0.8.0-next.0

package/dist/session/session-event.entity.functions.js

@@ -0,0 +1,42 @@
+import { Effect, Option, Schema } from "effect";
+import { canonicalJson } from "../memory/memory-log.entity.functions.js";
+import { LogEntry } from "../memory/memory-log.entity.js";
+import { TransientTurnEvents, TurnEvent } from "../turn/turn-event.entity.js";
+import { MemoryKindOf, TurnEndedData, TurnStartedData } from "./session-event.entity.js";
+const encodeEntry = Schema.encodeEffect(LogEntry), decodeEntry = Schema.decodeUnknownEffect(LogEntry), encodeTurnEvent = Schema.encodeSync(TurnEvent), tagOfKind = new Map(Object.entries(MemoryKindOf).map(([tag, kind]) => [kind, tag])), canonical = (data) => JSON.parse(canonicalJson(data)), turnOf = (event) => Option.getOrElse(event.turn, () => 0);
+export const draftOfEntry = (entry) => entry.body._tag === "TurnStarted" ? Effect.succeed(Option.none()) : encodeEntry(entry).pipe(Effect.map((encoded) => {
+  const { _tag, ...body } = encoded.body, kind = MemoryKindOf[_tag];
+  return Option.some({
+    kind,
+    turn: Option.some(entry.turn),
+    data: { entry: encoded.id, runId: encoded.runId, step: encoded.step, at: encoded.at, body }
+  });
+})), draftsOfEntries = (entries) => Effect.forEach(entries, draftOfEntry).pipe(Effect.map((drafts) => drafts.flatMap(Option.toArray))), turnStartedDraft = (turn, data) => Schema.encodeEffect(TurnStartedData)(data).pipe(Effect.map((encoded) => ({ kind: "turn.started", turn: Option.some(turn), data: { ...encoded } }))), turnEndedDraft = (turn, data) => Schema.encodeEffect(TurnEndedData)(data).pipe(Effect.map((encoded) => ({ kind: "turn.ended", turn: Option.some(turn), data: { ...encoded } }))), turnStartedOf = (event) => Schema.decodeUnknownEffect(TurnStartedData)(canonical(event.data)), turnEndedOf = (event) => Schema.decodeUnknownEffect(TurnEndedData)(canonical(event.data)), entryOfEvent = (event) => {
+  if (event.kind === "turn.started")
+    return turnStartedOf(event).pipe(Effect.flatMap((started) => decodeEntry({
+      id: started.entry,
+      runId: started.runId,
+      turn: turnOf(event),
+      step: 0,
+      at: started.at,
+      body: { _tag: "TurnStarted", prompt: started.userMessage.text }
+    })), Effect.map(Option.some));
+  const tag = tagOfKind.get(event.kind);
+  if (tag === void 0)
+    return Effect.succeed(Option.none());
+  const data = canonical(event.data), body = typeof data.body === "object" && data.body !== null ? data.body : {};
+  return decodeEntry({ id: data.entry, runId: data.runId, turn: turnOf(event), step: data.step, at: data.at, body: { ...body, _tag: tag } }).pipe(Effect.map(Option.some));
+}, entriesOfEvents = (events) => Effect.forEach(events, entryOfEvent).pipe(Effect.map((entries) => entries.flatMap(Option.toArray)));
+const recordedElsewhere = new Set(["turn.started", "turn.ended", "skills.activated"]), withoutPayload = (data) => Object.fromEntries(Object.entries(data).filter(([key]) => key !== "result" && key !== "encoded" && key !== "input"));
+export const draftOfTurnEvent = (turn, event) => {
+  if (TransientTurnEvents.includes(event._tag) || recordedElsewhere.has(event._tag))
+    return Option.none();
+  if (event._tag === "host")
+    return Option.some({ kind: event.name, turn: Option.some(turn), data: event.data });
+  const { _tag, ...data } = encodeTurnEvent(event);
+  if (_tag === "assistant.message") {
+    const { step, model, usage } = data;
+    return Option.some({ kind: "step.usage", turn: Option.some(turn), data: { step, model, usage } });
+  }
+  return Option.some({ kind: _tag, turn: Option.some(turn), data: _tag === "tool.completed" ? withoutPayload(data) : data });
+};

package/dist/session/session-event.entity.js

@@ -0,0 +1,37 @@
+import { Schema } from "effect";
+import { EntryId } from "../memory/memory-log.entity.js";
+import { UserMessage } from "../turn/user-message.entity.js";
+import { JsonObject } from "./session-log.entity.js";
+export const TurnStartedData = Schema.Struct({
+  runId: Schema.String,
+  key: Schema.String,
+  origin: Schema.Literals(["user", "inbox"]),
+  userMessage: UserMessage,
+  command: JsonObject,
+  claimed: Schema.Array(Schema.String),
+  entry: EntryId,
+  at: Schema.Number
+}), TurnEndReason = Schema.Literals(["completed", "partial", "failed", "cancelled", "interrupted"]), TurnEndedData = Schema.Struct({
+  reason: TurnEndReason,
+  failure: Schema.OptionFromNullOr(Schema.Struct({ code: Schema.String, message: Schema.String }))
+}), MemoryKindOf = {
+  SystemPrepared: "memory.system",
+  TurnContext: "memory.section",
+  StepContext: "memory.step",
+  Message: "memory.message",
+  ToolResult: "memory.tool-result",
+  ToolDigest: "memory.digest",
+  ToolsActivated: "memory.skills",
+  Compaction: "memory.compaction",
+  TurnEnded: "turn.reply"
+}, MEMORY_KINDS = ["turn.started", ...Object.values(MemoryKindOf)], TURN_EVENT_KINDS = [
+  "step.started",
+  "step.ended",
+  "step.usage",
+  "tool.started",
+  "tool.completed",
+  "completion.evaluated",
+  "context.built",
+  "decision.recorded",
+  "request.prepared"
+], SESSION_KINDS = ["turn.ended", "inbox.queued", "inbox.dropped"], RESERVED_KINDS = [...MEMORY_KINDS, ...TURN_EVENT_KINDS, ...SESSION_KINDS];

package/dist/session/session-event.entity.test.d.ts

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

package/dist/session/session-log.conformance.d.ts

@@ -0,0 +1,13 @@
+import type { Context } from "effect";
+import type { ConformanceCheck } from "../conformance.entity.js";
+import type { SessionLog } from "../ports/session-log.port.js";
+type Log = Context.Service.Shape<typeof SessionLog>;
+/**
+ * The SessionLog contract, as checks any backend must pass: dense sequence
+ * numbers, one revision per commit, compare-and-swap, the `notAfter` clock
+ * check, JSON kept by value, reads by position and kind, listing order,
+ * children and their removal. Every check uses fresh ids and a fresh owner,
+ * so the kit is safe on a shared database.
+ */
+export declare const sessionLogConformance: (log: Log) => ReadonlyArray<ConformanceCheck>;
+export {};

package/dist/session/session-log.conformance.js

@@ -0,0 +1,167 @@
+import { Effect, Option } from "effect";
+import { ConformanceFailure } from "../conformance.entity.js";
+import { ConversationId } from "../domain/message.entity.js";
+import { canonicalJson } from "../memory/memory-log.entity.functions.js";
+const fail = (check, message) => Effect.fail(new ConformanceFailure({ check, message })), expect = (check, holds, message) => holds ? Effect.void : fail(check, message), freshId = Effect.sync(() => ConversationId.make(crypto.randomUUID())), headerOf = (id, owner, parent = Option.none()) => ({
+  id,
+  owner,
+  origin: "user",
+  createdAt: 1767225600000,
+  meta: { title: "conformance", nested: { list: [1, "two", null] } },
+  parent
+}), draft = (kind, data, turn = Option.none()) => ({ kind, turn, data }), noEvents = { notAfter: Option.none(), state: Option.none() }, rich = { zeta: 1, alpha: { b: [!0, !1, { y: "\xFC", x: 0.5 }], a: "text \u2713" }, empty: {}, list: [] };
+export const sessionLogConformance = (log) => {
+  const check = (name, id, body) => ({
+    name,
+    run: freshId.pipe(Effect.flatMap((owner) => body(`owner-${owner}`)), Effect.catch((error) => error instanceof ConformanceFailure ? Effect.fail(error) : fail(id, `unexpected ${typeof error === "object" && error !== null && "_tag" in error ? String(error._tag) : "error"}: ${JSON.stringify(error)}`)))
+  });
+  return [
+    check("a new session is empty: seq 0, revision 0, the header as given", "create", (owner) => Effect.gen(function* () {
+      const id = yield* freshId, created = yield* log.create(headerOf(id, owner)), head = yield* log.head(id);
+      yield* expect("create", created.seq === 0 && created.revision === 0 && head.seq === 0 && head.revision === 0, `seq ${head.seq}, revision ${head.revision}`);
+      yield* expect("create", head.header.owner === owner && head.header.origin === "user" && Option.isNone(head.header.parent), "the header changed");
+      yield* expect("create", canonicalJson(head.header.meta) === canonicalJson(headerOf(id, owner).meta), "meta changed");
+      yield* expect("create", canonicalJson(head.state) === "{}", "a new session has state");
+      const again = yield* Effect.flip(log.create(headerOf(id, owner)));
+      yield* expect("create", again._tag === "SessionExists", `creating twice gave ${again._tag}`);
+    })),
+    check("commits number events densely from 1, in order, and bump the revision once", "append", (owner) => Effect.gen(function* () {
+      const id = yield* freshId;
+      yield* log.create(headerOf(id, owner));
+      const first = yield* log.commit(id, { expect: 0, ...noEvents, events: [draft("a", { n: 1 }, Option.some(1)), draft("b", { n: 2 }, Option.some(1))] }), second = yield* log.commit(id, { expect: 1, ...noEvents, events: [draft("c", { n: 3 })] });
+      yield* expect("append", first.revision === 1 && second.revision === 2 && second.seq === 3, `revisions ${first.revision}, ${second.revision}; seq ${second.seq}`);
+      yield* expect("append", first.events.map((event) => event.seq).join() === "1,2" && second.events.map((event) => event.seq).join() === "3", "sequence numbers are not dense");
+      const stored = yield* log.read(id, { after: 0, limit: Option.none(), kinds: [] });
+      yield* expect("append", stored.map((event) => `${event.seq}:${event.kind}:${Option.getOrElse(event.turn, () => 0)}`).join() === "1:a:1,2:b:1,3:c:0", "the log differs");
+      yield* expect("append", stored.every((event) => event.session === id && event.at === (event.seq < 3 ? first.at : second.at)), "event times are not the commit's time");
+      const head = yield* log.head(id);
+      yield* expect("append", head.seq === 3 && head.revision === 2 && head.updatedAt === second.at, `head seq ${head.seq}, revision ${head.revision}`);
+    })),
+    check("a state-only commit bumps the revision and appends nothing", "state", (owner) => Effect.gen(function* () {
+      const id = yield* freshId;
+      yield* log.create(headerOf(id, owner));
+      const committed = yield* log.commit(id, { expect: 0, notAfter: Option.none(), events: [], state: Option.some({ open: { turn: 1 } }) }), head = yield* log.head(id);
+      yield* expect("state", committed.revision === 1 && committed.events.length === 0 && head.seq === 0 && head.revision === 1, `revision ${head.revision}, seq ${head.seq}`);
+      yield* expect("state", canonicalJson(head.state) === canonicalJson({ open: { turn: 1 } }), "the state was not replaced");
+      yield* log.commit(id, { expect: 1, ...noEvents, events: [draft("a", {})] });
+      yield* expect("state", canonicalJson((yield* log.head(id)).state) === canonicalJson({ open: { turn: 1 } }), "a commit without state changed it");
+    })),
+    check("a commit against a stale revision is refused and writes nothing", "conflict", (owner) => Effect.gen(function* () {
+      const id = yield* freshId;
+      yield* log.create(headerOf(id, owner));
+      yield* log.commit(id, { expect: 0, ...noEvents, events: [draft("a", {})] });
+      const refused = yield* Effect.flip(log.commit(id, { expect: 0, notAfter: Option.none(), events: [draft("b", {})], state: Option.some({ lost: !0 }) }));
+      yield* expect("conflict", refused._tag === "RevisionConflict" && refused.expected === 0 && refused.actual === 1, `refused with ${JSON.stringify(refused)}`);
+      const head = yield* log.head(id);
+      yield* expect("conflict", head.seq === 1 && head.revision === 1 && canonicalJson(head.state) === "{}", "a refused commit wrote something");
+    })),
+    check("a commit after its notAfter is refused by the storage clock and writes nothing", "expiry", (owner) => Effect.gen(function* () {
+      const id = yield* freshId;
+      yield* log.create(headerOf(id, owner));
+      const head = yield* log.head(id), refused = yield* Effect.flip(log.commit(id, { expect: 0, notAfter: Option.some(head.now - 60000), events: [draft("late", {})], state: Option.none() }));
+      yield* expect("expiry", refused._tag === "LeaseExpired", `refused with ${refused._tag}`);
+      const inTime = yield* log.commit(id, { expect: 0, notAfter: Option.some(head.now + 600000), events: [draft("on-time", {})], state: Option.none() });
+      yield* expect("expiry", inTime.revision === 1 && (yield* log.head(id)).seq === 1, "a commit in time was refused or the late one was written");
+    })),
+    check("of concurrent commits against one revision, exactly one wins", "race", (owner) => Effect.gen(function* () {
+      const id = yield* freshId;
+      yield* log.create(headerOf(id, owner));
+      const attempts = yield* Effect.forEach([0, 1, 2, 3, 4, 5, 6, 7], (n) => Effect.result(log.commit(id, { expect: 0, notAfter: Option.none(), events: [draft("attempt", { n })], state: Option.some({ winner: n }) })), { concurrency: "unbounded" }), won = attempts.filter((attempt) => attempt._tag === "Success"), refused = attempts.filter((attempt) => attempt._tag === "Failure" && attempt.failure._tag === "RevisionConflict");
+      yield* expect("race", won.length === 1 && refused.length === 7, `${won.length} won, ${refused.length} refused`);
+      const head = yield* log.head(id), events = yield* log.read(id, { after: 0, limit: Option.none(), kinds: [] });
+      yield* expect("race", head.revision === 1 && events.length === 1 && canonicalJson(head.state) === canonicalJson({ winner: events[0]?.data.n }), "the winner's state and event disagree");
+    })),
+    check("event data and state come back equal, whatever key order the store keeps", "json", (owner) => Effect.gen(function* () {
+      const id = yield* freshId;
+      yield* log.create(headerOf(id, owner));
+      yield* log.commit(id, { expect: 0, notAfter: Option.none(), events: [draft("rich", rich)], state: Option.some(rich) });
+      const [event] = yield* log.read(id, { after: 0, limit: Option.none(), kinds: [] });
+      yield* expect("json", event !== void 0 && canonicalJson(event.data) === canonicalJson(rich), `data came back as ${JSON.stringify(event?.data)}`);
+      yield* expect("json", canonicalJson((yield* log.head(id)).state) === canonicalJson(rich), "the state came back different");
+    })),
+    check("input and returned JSON are detached from stored heads and events", "json-isolation", (owner) => Effect.gen(function* () {
+      const id = yield* freshId, header = headerOf(id, owner), expectedMeta = canonicalJson(header.meta), created = yield* log.create(header), change = (json, by) => {
+        Reflect.set(json, "changed", by);
+        if (typeof json.nested === "object" && json.nested !== null) {
+          Reflect.set(json.nested, "text", by);
+          if ("list" in json.nested && typeof json.nested.list === "object" && json.nested.list !== null)
+            Reflect.set(json.nested.list, "0", by);
+        }
+        if (typeof json.list === "object" && json.list !== null)
+          Reflect.set(json.list, "0", by);
+      };
+      change(header.meta, "input");
+      change(created.header.meta, "create");
+      Reflect.set(created.state, "changed", "create");
+      yield* expect("json-isolation", canonicalJson((yield* log.head(id)).state) === "{}", "a returned create state changed the new session");
+      const value = { nested: { text: "original" }, list: ["original"] }, expected = canonicalJson(value), committed = yield* log.commit(id, { expect: 0, notAfter: Option.none(), events: [draft("fact", value)], state: Option.some(value) });
+      value.nested.text = "input";
+      value.list[0] = "input";
+      const head = yield* log.head(id), listed = yield* log.list({ owner, limit: 10, before: Option.none(), parent: Option.none() }), events = yield* log.read(id, { after: 0, limit: Option.none(), kinds: [] });
+      change(head.header.meta, "output");
+      change(head.state, "output");
+      listed.forEach((entry) => {
+        change(entry.header.meta, "output");
+        change(entry.state, "output");
+      });
+      committed.events.forEach((event) => change(event.data, "output"));
+      events.forEach((event) => change(event.data, "output"));
+      const again = yield* log.head(id), reread = yield* log.read(id, { after: 0, limit: Option.none(), kinds: [] });
+      yield* expect("json-isolation", again.revision === 1 && again.seq === 1, "mutating a returned value moved the head");
+      yield* expect("json-isolation", canonicalJson(again.header.meta) === expectedMeta, "input, create, head or list metadata changed the stored header");
+      yield* expect("json-isolation", canonicalJson(again.state) === expected, "input, head or list state changed the stored state");
+      yield* expect("json-isolation", reread.length === 1 && canonicalJson(reread[0].data) === expected, "input, commit or read data changed the stored event");
+    })),
+    check("reads return events after a position, ascending, filtered by kind and limited", "read", (owner) => Effect.gen(function* () {
+      const id = yield* freshId;
+      yield* log.create(headerOf(id, owner));
+      yield* log.commit(id, { expect: 0, ...noEvents, events: ["a", "b", "a", "c", "a"].map((kind, n) => draft(kind, { n })) });
+      const seqs = (events) => events.map((event) => event.seq).join();
+      yield* expect("read", seqs(yield* log.read(id, { after: 2, limit: Option.none(), kinds: [] })) === "3,4,5", "after is not exclusive");
+      yield* expect("read", seqs(yield* log.read(id, { after: 0, limit: Option.none(), kinds: ["a"] })) === "1,3,5", "kinds do not filter");
+      yield* expect("read", seqs(yield* log.read(id, { after: 1, limit: Option.some(2), kinds: ["a", "c"] })) === "3,4", "limit does not apply after the filter");
+      yield* expect("read", (yield* log.read(id, { after: 5, limit: Option.none(), kinds: [] })).length === 0, "reading past the end returned events");
+    })),
+    check("a listing holds the owner's top-level sessions, newest first, before the cursor", "list", (owner) => Effect.gen(function* () {
+      const [first, second, third] = [yield* freshId, yield* freshId, yield* freshId];
+      yield* log.create(headerOf(first, owner));
+      yield* log.create(headerOf(second, owner));
+      yield* log.create(headerOf(third, owner));
+      yield* log.create(headerOf(yield* freshId, `${owner}-other`));
+      yield* log.create(headerOf(yield* freshId, owner, Option.some({ id: first, through: 0, turnAtFork: 0 })));
+      yield* Effect.sleep("5 millis");
+      yield* log.commit(second, { expect: 0, ...noEvents, events: [draft("touch", {})] });
+      const listed = yield* log.list({ owner, limit: 10, before: Option.none(), parent: Option.none() });
+      yield* expect("list", listed.length === 3 && listed[0]?.header.id === second, `listed ${listed.map((head) => head.header.id).join()}`);
+      yield* expect("list", listed.every((head, index) => index === 0 || (listed[index - 1].updatedAt > head.updatedAt || listed[index - 1].updatedAt === head.updatedAt && listed[index - 1].header.id > head.header.id)), "the listing is not newest first, then by id");
+      const cursor = listed[0], rest = yield* log.list({ owner, limit: 10, before: Option.some({ updatedAt: cursor.updatedAt, id: cursor.header.id }), parent: Option.none() });
+      yield* expect("list", rest.length === 2 && rest.every((head) => head.header.id !== second), "the cursor is not exclusive");
+      yield* expect("list", (yield* log.list({ owner, limit: 1, before: Option.none(), parent: Option.none() })).length === 1, "the limit is ignored");
+      const children = yield* log.list({ owner, limit: 10, before: Option.none(), parent: Option.some(first) });
+      yield* expect("list", children.length === 1 && Option.exists(children[0].header.parent, (parent) => parent.id === first), "children are not listed under their parent");
+    })),
+    check("a child needs its parent, and removing a session removes its events and children", "lineage", (owner) => Effect.gen(function* () {
+      const [parent, child, grandchild, orphan] = [yield* freshId, yield* freshId, yield* freshId, yield* freshId], lost = yield* Effect.flip(log.create(headerOf(orphan, owner, Option.some({ id: yield* freshId, through: 0, turnAtFork: 0 }))));
+      yield* expect("lineage", lost._tag === "SessionMissing", `a child of a missing parent gave ${lost._tag}`);
+      yield* log.create(headerOf(parent, owner));
+      yield* log.commit(parent, { expect: 0, ...noEvents, events: [draft("a", {})] });
+      const forked = yield* log.create(headerOf(child, owner, Option.some({ id: parent, through: 1, turnAtFork: 1 })));
+      yield* expect("lineage", Option.exists(forked.header.parent, (lineage) => lineage.id === parent && lineage.through === 1 && lineage.turnAtFork === 1), "the lineage changed");
+      yield* log.create(headerOf(grandchild, owner, Option.some({ id: child, through: 0, turnAtFork: 1 })));
+      yield* log.remove(parent);
+      const gone = yield* Effect.forEach([parent, child, grandchild], (id) => Effect.flip(log.head(id)));
+      yield* expect("lineage", gone.every((error) => error._tag === "SessionMissing"), "a removed session or child is still there");
+      const read = yield* Effect.flip(log.read(parent, { after: 0, limit: Option.none(), kinds: [] }));
+      yield* expect("lineage", read._tag === "SessionMissing", "a removed session still reads");
+      yield* log.remove(parent);
+    })),
+    check("a missing session is SessionMissing to every operation", "missing", () => Effect.gen(function* () {
+      const id = yield* freshId, errors = [
+        yield* Effect.flip(log.head(id)),
+        yield* Effect.flip(log.read(id, { after: 0, limit: Option.none(), kinds: [] })),
+        yield* Effect.flip(log.commit(id, { expect: 0, ...noEvents, events: [draft("a", {})] }))
+      ];
+      yield* expect("missing", errors.every((error) => error._tag === "SessionMissing"), `got ${errors.map((error) => error._tag).join()}`);
+    }))
+  ];
+};

package/dist/session/session-log.entity.d.ts

@@ -0,0 +1,164 @@
+import { Schema } from "effect";
+/** A JSON object as stored: compared by value, key order is not kept. */
+export declare const JsonObject: Schema.$Record<Schema.String, Schema.Unknown>;
+export type JsonObject = typeof JsonObject.Type;
+/** Where a forked session starts: the parent, the last parent event it inherits, and the parent's turns at that point. */
+export declare const SessionLineage: Schema.Struct<{
+    readonly id: Schema.brand<Schema.String, "ConversationId">;
+    readonly through: Schema.Int;
+    readonly turnAtFork: Schema.Int;
+}>;
+export type SessionLineage = typeof SessionLineage.Type;
+/** What a session is, fixed when it is created. */
+export declare const SessionHeader: Schema.Struct<{
+    readonly id: Schema.brand<Schema.String, "ConversationId">;
+    /** Every read and write names the owner; another owner sees no session. */
+    readonly owner: Schema.Trimmed;
+    /** Who opened it: `user` for a conversation, `task` for a background task, or a host's own kind. */
+    readonly origin: Schema.Trimmed;
+    readonly createdAt: Schema.Number;
+    readonly meta: Schema.$Record<Schema.String, Schema.Unknown>;
+    readonly parent: Schema.OptionFromNullOr<Schema.Struct<{
+        readonly id: Schema.brand<Schema.String, "ConversationId">;
+        readonly through: Schema.Int;
+        readonly turnAtFork: Schema.Int;
+    }>>;
+}>;
+export type SessionHeader = typeof SessionHeader.Type;
+/** A session's head: the header, the last sequence number, the revision and the plugin's state. */
+export declare const SessionHead: Schema.Struct<{
+    readonly header: Schema.Struct<{
+        readonly id: Schema.brand<Schema.String, "ConversationId">;
+        /** Every read and write names the owner; another owner sees no session. */
+        readonly owner: Schema.Trimmed;
+        /** Who opened it: `user` for a conversation, `task` for a background task, or a host's own kind. */
+        readonly origin: Schema.Trimmed;
+        readonly createdAt: Schema.Number;
+        readonly meta: Schema.$Record<Schema.String, Schema.Unknown>;
+        readonly parent: Schema.OptionFromNullOr<Schema.Struct<{
+            readonly id: Schema.brand<Schema.String, "ConversationId">;
+            readonly through: Schema.Int;
+            readonly turnAtFork: Schema.Int;
+        }>>;
+    }>;
+    /** The last event's sequence number; 0 before any event. */
+    readonly seq: Schema.Int;
+    /** Bumped by exactly one on every commit, events or not. */
+    readonly revision: Schema.Int;
+    readonly state: Schema.$Record<Schema.String, Schema.Unknown>;
+    readonly updatedAt: Schema.Number;
+    /** The storage clock when the head was read. */
+    readonly now: Schema.Number;
+}>;
+export type SessionHead = typeof SessionHead.Type;
+/** An event to append; the log assigns its sequence number and time. */
+export declare const SessionDraft: Schema.Struct<{
+    readonly kind: Schema.Trimmed;
+    readonly turn: Schema.OptionFromNullOr<Schema.Int>;
+    readonly data: Schema.$Record<Schema.String, Schema.Unknown>;
+}>;
+export type SessionDraft = typeof SessionDraft.Type;
+/** One stored event. */
+export declare const SessionLogEvent: Schema.Struct<{
+    readonly session: Schema.brand<Schema.String, "ConversationId">;
+    /** Dense from 1 within the session. */
+    readonly seq: Schema.Int;
+    readonly turn: Schema.OptionFromNullOr<Schema.Int>;
+    readonly kind: Schema.Trimmed;
+    readonly at: Schema.Number;
+    readonly data: Schema.$Record<Schema.String, Schema.Unknown>;
+}>;
+export type SessionLogEvent = typeof SessionLogEvent.Type;
+/**
+ * One atomic commit: accepted only while the head's revision is `expect`
+ * and the storage clock is at most `notAfter` (when given). `state`, when
+ * given, replaces the head's state; `events` may be empty.
+ */
+export declare const SessionCommit: Schema.Struct<{
+    readonly expect: Schema.Int;
+    readonly notAfter: Schema.OptionFromNullOr<Schema.Number>;
+    readonly events: Schema.$Array<Schema.Struct<{
+        readonly kind: Schema.Trimmed;
+        readonly turn: Schema.OptionFromNullOr<Schema.Int>;
+        readonly data: Schema.$Record<Schema.String, Schema.Unknown>;
+    }>>;
+    readonly state: Schema.OptionFromNullOr<Schema.$Record<Schema.String, Schema.Unknown>>;
+}>;
+export type SessionCommit = typeof SessionCommit.Type;
+/** What a commit stored: the new revision, the events as stored, and the storage time. */
+export declare const SessionCommitted: Schema.Struct<{
+    readonly revision: Schema.Int;
+    readonly seq: Schema.Int;
+    readonly events: Schema.$Array<Schema.Struct<{
+        readonly session: Schema.brand<Schema.String, "ConversationId">;
+        /** Dense from 1 within the session. */
+        readonly seq: Schema.Int;
+        readonly turn: Schema.OptionFromNullOr<Schema.Int>;
+        readonly kind: Schema.Trimmed;
+        readonly at: Schema.Number;
+        readonly data: Schema.$Record<Schema.String, Schema.Unknown>;
+    }>>;
+    readonly at: Schema.Number;
+}>;
+export type SessionCommitted = typeof SessionCommitted.Type;
+/** Events after `after`, ascending; only the given kinds when any are named. */
+export declare const SessionReadQuery: Schema.Struct<{
+    readonly after: Schema.Int;
+    readonly limit: Schema.OptionFromNullOr<Schema.Int>;
+    readonly kinds: Schema.$Array<Schema.Trimmed>;
+}>;
+export type SessionReadQuery = typeof SessionReadQuery.Type;
+/** A position in a listing: strictly older sessions come after it. */
+export declare const SessionListCursor: Schema.Struct<{
+    readonly updatedAt: Schema.Number;
+    readonly id: Schema.brand<Schema.String, "ConversationId">;
+}>;
+export type SessionListCursor = typeof SessionListCursor.Type;
+/**
+ * An owner's sessions, most recently updated first (then by id, descending).
+ * With `parent`, that session's children; without, only top-level sessions.
+ */
+export declare const SessionListQuery: Schema.Struct<{
+    readonly owner: Schema.Trimmed;
+    readonly limit: Schema.Int;
+    readonly before: Schema.OptionFromNullOr<Schema.Struct<{
+        readonly updatedAt: Schema.Number;
+        readonly id: Schema.brand<Schema.String, "ConversationId">;
+    }>>;
+    readonly parent: Schema.OptionFromNullOr<Schema.brand<Schema.String, "ConversationId">>;
+}>;
+export type SessionListQuery = typeof SessionListQuery.Type;
+declare const SessionMissing_base: Schema.Class<SessionMissing, Schema.TaggedStruct<"SessionMissing", {
+    readonly session: Schema.brand<Schema.String, "ConversationId">;
+}>, import("effect/Cause").YieldableError>;
+export declare class SessionMissing extends SessionMissing_base {
+}
+declare const SessionExists_base: Schema.Class<SessionExists, Schema.TaggedStruct<"SessionExists", {
+    readonly session: Schema.brand<Schema.String, "ConversationId">;
+}>, import("effect/Cause").YieldableError>;
+export declare class SessionExists extends SessionExists_base {
+}
+declare const RevisionConflict_base: Schema.Class<RevisionConflict, Schema.TaggedStruct<"RevisionConflict", {
+    readonly session: Schema.brand<Schema.String, "ConversationId">;
+    readonly expected: Schema.Int;
+    readonly actual: Schema.Int;
+}>, import("effect/Cause").YieldableError>;
+/** The head moved on since the writer read it; nothing was written. */
+export declare class RevisionConflict extends RevisionConflict_base {
+}
+declare const LeaseExpired_base: Schema.Class<LeaseExpired, Schema.TaggedStruct<"LeaseExpired", {
+    readonly session: Schema.brand<Schema.String, "ConversationId">;
+    readonly notAfter: Schema.Number;
+    readonly now: Schema.Number;
+}>, import("effect/Cause").YieldableError>;
+/** The storage clock passed the commit's `notAfter`; nothing was written. */
+export declare class LeaseExpired extends LeaseExpired_base {
+}
+declare const SessionLogError_base: Schema.Class<SessionLogError, Schema.TaggedStruct<"SessionLogError", {
+    readonly code: Schema.String;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The store itself failed (unreachable, undecodable). */
+export declare class SessionLogError extends SessionLogError_base {
+}
+export {};

package/dist/session/session-log.entity.js

@@ -0,0 +1,82 @@
+import { Schema } from "effect";
+import { ConversationId } from "../domain/message.entity.js";
+const Name = Schema.Trimmed.check(Schema.isNonEmpty());
+export const JsonObject = Schema.Record(Schema.String, Schema.Unknown), SessionLineage = Schema.Struct({
+  id: ConversationId,
+  through: Schema.Int,
+  turnAtFork: Schema.Int
+}), SessionHeader = Schema.Struct({
+  id: ConversationId,
+  owner: Name,
+  origin: Name,
+  createdAt: Schema.Number,
+  meta: JsonObject,
+  parent: Schema.OptionFromNullOr(SessionLineage)
+}), SessionHead = Schema.Struct({
+  header: SessionHeader,
+  seq: Schema.Int,
+  revision: Schema.Int,
+  state: JsonObject,
+  updatedAt: Schema.Number,
+  now: Schema.Number
+}), SessionDraft = Schema.Struct({
+  kind: Name,
+  turn: Schema.OptionFromNullOr(Schema.Int),
+  data: JsonObject
+}), SessionLogEvent = Schema.Struct({
+  session: ConversationId,
+  seq: Schema.Int,
+  turn: Schema.OptionFromNullOr(Schema.Int),
+  kind: Name,
+  at: Schema.Number,
+  data: JsonObject
+}), SessionCommit = Schema.Struct({
+  expect: Schema.Int,
+  notAfter: Schema.OptionFromNullOr(Schema.Number),
+  events: Schema.Array(SessionDraft),
+  state: Schema.OptionFromNullOr(JsonObject)
+}), SessionCommitted = Schema.Struct({
+  revision: Schema.Int,
+  seq: Schema.Int,
+  events: Schema.Array(SessionLogEvent),
+  at: Schema.Number
+}), SessionReadQuery = Schema.Struct({
+  after: Schema.Int,
+  limit: Schema.OptionFromNullOr(Schema.Int),
+  kinds: Schema.Array(Name)
+}), SessionListCursor = Schema.Struct({ updatedAt: Schema.Number, id: ConversationId }), SessionListQuery = Schema.Struct({
+  owner: Name,
+  limit: Schema.Int,
+  before: Schema.OptionFromNullOr(SessionListCursor),
+  parent: Schema.OptionFromNullOr(ConversationId)
+});
+
+export class SessionMissing extends Schema.TaggedError()("SessionMissing", {
+  session: ConversationId
+}) {
+}
+
+export class SessionExists extends Schema.TaggedError()("SessionExists", {
+  session: ConversationId
+}) {
+}
+
+export class RevisionConflict extends Schema.TaggedError()("RevisionConflict", {
+  session: ConversationId,
+  expected: Schema.Int,
+  actual: Schema.Int
+}) {
+}
+
+export class LeaseExpired extends Schema.TaggedError()("LeaseExpired", {
+  session: ConversationId,
+  notAfter: Schema.Number,
+  now: Schema.Number
+}) {
+}
+
+export class SessionLogError extends Schema.TaggedError()("SessionLogError", {
+  code: Schema.String,
+  message: Schema.String
+}) {
+}

package/dist/session/session-log.memory.adapter.d.ts

@@ -0,0 +1,7 @@
+import { Layer } from "effect";
+import { SessionLog } from "../ports/session-log.port.js";
+/**
+ * The session log held in memory, for tests and single-process hosts. Its
+ * clock is the Effect clock, so a TestClock drives leases.
+ */
+export declare const SessionLogMemoryLive: Layer.Layer<SessionLog>;

package/dist/session/session-log.memory.adapter.js

@@ -0,0 +1,82 @@
+import { Clock, Effect, Layer, Option, Ref } from "effect";
+import { SessionLog } from "../ports/session-log.port.js";
+import { LeaseExpired, RevisionConflict, SessionExists, SessionMissing } from "./session-log.entity.js";
+const stored = (value) => JSON.parse(JSON.stringify(value)), copyHeader = (header) => ({
+  ...header,
+  meta: stored(header.meta),
+  parent: Option.map(header.parent, (parent) => ({ ...parent }))
+}), copyHead = (head, now) => ({
+  ...head,
+  header: copyHeader(head.header),
+  state: stored(head.state),
+  now
+}), copyEvent = (event) => ({
+  ...event,
+  turn: Option.map(event.turn, (turn) => turn),
+  data: stored(event.data)
+}), withDescendants = (all, ids) => {
+  const next = new Set([...ids, ...[...all.entries()].flatMap(([id, session]) => Option.match(session.head.header.parent, { onNone: () => [], onSome: (parent) => ids.has(parent.id) ? [id] : [] }))]);
+  return next.size === ids.size ? ids : withDescendants(all, next);
+}, olderThan = (cursor) => (head) => head.updatedAt < cursor.updatedAt || head.updatedAt === cursor.updatedAt && head.header.id < cursor.id;
+export const SessionLogMemoryLive = Layer.effect(SessionLog, Effect.gen(function* () {
+  const store = yield* Ref.make(new Map), now = Clock.currentTimeMillis, missing = (id) => new SessionMissing({ session: id });
+  return SessionLog.of({
+    create: (header) => now.pipe(Effect.flatMap((at) => Ref.modify(store, (all) => {
+      if (all.has(header.id))
+        return [Effect.fail(new SessionExists({ session: header.id })), all];
+      if (Option.isSome(header.parent) && !all.has(header.parent.value.id))
+        return [Effect.fail(missing(header.parent.value.id)), all];
+      const head = { header: copyHeader(header), seq: 0, revision: 0, state: {}, updatedAt: at };
+      return [Effect.succeed(copyHead(head, at)), new Map([...all, [header.id, { head, events: [] }]])];
+    })), Effect.flatten),
+    head: (id) => Effect.gen(function* () {
+      const at = yield* now, session = (yield* Ref.get(store)).get(id);
+      return session === void 0 ? yield* Effect.fail(missing(id)) : copyHead(session.head, at);
+    }),
+    list: (query) => Effect.gen(function* () {
+      const at = yield* now;
+      return [...(yield* Ref.get(store)).values()].map((session) => session.head).filter((head) => head.header.owner === query.owner).filter((head) => Option.match(query.parent, {
+        onNone: () => Option.isNone(head.header.parent),
+        onSome: (parent) => Option.exists(head.header.parent, (lineage) => lineage.id === parent)
+      })).filter(Option.match(query.before, { onNone: () => () => !0, onSome: olderThan })).sort((left, right) => right.updatedAt - left.updatedAt || (right.header.id < left.header.id ? -1 : right.header.id > left.header.id ? 1 : 0)).slice(0, Math.max(0, query.limit)).map((head) => copyHead(head, at));
+    }),
+    read: (id, query) => Ref.get(store).pipe(Effect.flatMap((all) => {
+      const session = all.get(id);
+      if (session === void 0)
+        return Effect.fail(missing(id));
+      const events = session.events.filter((event) => event.seq > query.after && (query.kinds.length === 0 || query.kinds.includes(event.kind)));
+      return Effect.succeed(Option.match(query.limit, { onNone: () => events, onSome: (limit) => events.slice(0, Math.max(0, limit)) }).map(copyEvent));
+    })),
+    commit: (id, commit) => now.pipe(Effect.flatMap((at) => Ref.modify(store, (all) => {
+      const session = all.get(id);
+      if (session === void 0)
+        return [Effect.fail(missing(id)), all];
+      if (session.head.revision !== commit.expect)
+        return [Effect.fail(new RevisionConflict({ session: id, expected: commit.expect, actual: session.head.revision })), all];
+      if (Option.isSome(commit.notAfter) && at > commit.notAfter.value)
+        return [Effect.fail(new LeaseExpired({ session: id, notAfter: commit.notAfter.value, now: at })), all];
+      const events = commit.events.map((draft, index) => ({
+        session: id,
+        seq: session.head.seq + index + 1,
+        turn: Option.map(draft.turn, (turn) => turn),
+        kind: draft.kind,
+        at,
+        data: stored(draft.data)
+      })), head = {
+        ...session.head,
+        seq: session.head.seq + events.length,
+        revision: session.head.revision + 1,
+        state: Option.match(commit.state, { onNone: () => session.head.state, onSome: stored }),
+        updatedAt: at
+      };
+      return [
+        Effect.succeed({ revision: head.revision, seq: head.seq, events: events.map(copyEvent), at }),
+        new Map([...all, [id, { head, events: [...session.events, ...events] }]])
+      ];
+    })), Effect.flatten),
+    remove: (id) => Ref.update(store, (all) => {
+      const removed = withDescendants(all, new Set([id]));
+      return new Map([...all].filter(([key]) => !removed.has(key)));
+    })
+  });
+}));

package/dist/session/session-log.memory.adapter.test.d.ts

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