@xandreed/plugin-session-files 0.0.0-stage → 0.15.1

package/LICENSE

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

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @xandreed/plugin-session-files
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Efferent composable agent framework, 0.15.1. Node 24 or Bun.
+
+Documentation: https://github.com/xandreeddev/efferent

package/dist/bounded-call.adapter.d.ts

@@ -0,0 +1,14 @@
+import { Effect } from "effect";
+import { FileStoreIo, FileStoreStalled } from "./session-files.entity.js";
+type Failed = FileStoreIo | FileStoreStalled;
+/**
+ * Two native operations per handle. A call holds a slot from its admission
+ * until its native operation settles: one whose caller stopped waiting (a
+ * timeout, an interrupt) keeps its slot until it settles, the handle's
+ * capacity lowered by one meanwhile. While healthy, a call queues for a free
+ * slot within the admission deadline, so a hung operation slows the others
+ * and never fails them; a cooldown probe never waits (a full slot set fails
+ * it at once).
+ */
+export declare const makeBoundedFilesCall: (stallMs: number) => Effect.Effect<(<A>(op: string, path: string, run: () => Promise<A>) => Effect.Effect<A, Failed>), never, never>;
+export {};

package/dist/bounded-call.adapter.js

@@ -0,0 +1,67 @@
+import { Cause, Clock, Deferred, Effect, Exit, Option, Ref, Result, Semaphore } from "effect";
+import { FileStoreIo, FileStoreStalled } from "./session-files.entity.js";
+import { abandonCall, admitCall, afterCall } from "./session-files.entity.functions.js";
+const withinDeadline = (promise, ms, stalled) => new Promise((resolve, reject) => {
+  const timer = setTimeout(() => reject(stalled), ms);
+  promise.then((value) => {
+    clearTimeout(timer);
+    resolve(value);
+  }, (error) => {
+    clearTimeout(timer);
+    reject(error);
+  });
+}), NATIVE_SLOTS = 2;
+export const makeBoundedFilesCall = Effect.fnUntraced(function* (stallMs) {
+  const slots = yield* Semaphore.make(NATIVE_SLOTS), health = yield* Ref.make({ _tag: "Healthy" }), orphans = { count: 0 }, capacity = (change) => Effect.suspend(() => {
+    orphans.count += change;
+    return slots.resize(NATIVE_SLOTS - orphans.count);
+  }), settle = (answered) => Clock.currentTimeMillis.pipe(Effect.flatMap((now) => Ref.update(health, (current) => afterCall(current, answered, now))));
+  return (op, path, run) => Effect.gen(function* () {
+    const stalled = new FileStoreStalled({ op, path, ms: stallMs }), now = yield* Clock.currentTimeMillis, before = yield* Ref.get(health);
+    if (!admitCall(before, now, stallMs)[0])
+      return yield* Effect.fail(stalled);
+    const admission = yield* Deferred.make(), execute = Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
+      const claimed = yield* Clock.currentTimeMillis.pipe(Effect.flatMap((at) => Ref.modify(health, (current) => {
+        const [allowed, next] = admitCall(current, at, stallMs);
+        return [{ allowed, probe: allowed && current._tag === "Stalled" ? Option.some(next) : Option.none() }, next];
+      })));
+      if (!claimed.allowed)
+        return yield* Effect.fail(stalled);
+      const native = { settled: !1, orphaned: !1 }, outcome = yield* Effect.sync(() => Promise.resolve().then(run).then((value) => Result.succeed(value), (cause) => Result.fail(cause)).finally(() => {
+        native.settled = !0;
+        if (native.orphaned)
+          Effect.runSync(capacity(-1));
+      })), handOver = Effect.suspend(() => {
+        if (native.settled)
+          return Effect.void;
+        native.orphaned = !0;
+        return capacity(1);
+      });
+      return yield* restore(Effect.tryPromise({
+        try: () => withinDeadline(outcome, stallMs, stalled),
+        catch: (cause) => cause === stalled ? stalled : new FileStoreIo({ op, path, cause })
+      }).pipe(Effect.flatMap(Result.match({
+        onSuccess: Effect.succeed,
+        onFailure: (cause) => Effect.fail(new FileStoreIo({ op, path, cause }))
+      })))).pipe(Effect.onExit((exit) => handOver.pipe(Effect.andThen(() => {
+        if (Exit.isSuccess(exit))
+          return settle(!0);
+        const failed = exit.cause.reasons.find(Cause.isFailReason);
+        return failed === void 0 ? Option.match(claimed.probe, {
+          onNone: () => Effect.void,
+          onSome: (probe) => Ref.update(health, (current) => abandonCall(current, probe))
+        }) : settle(failed.error._tag === "FileStoreIo");
+      }))));
+    }));
+    if (before._tag === "Stalled")
+      return yield* slots.withPermitsIfAvailable(1)(execute).pipe(Effect.flatMap(Option.match({
+        onNone: () => Effect.fail(stalled),
+        onSome: Effect.succeed
+      })));
+    return yield* Effect.uninterruptibleMask((restore) => restore(Effect.raceFirst(slots.withPermits(1)(Effect.gen(function* () {
+      if (!(yield* Deferred.succeed(admission, void 0)))
+        return yield* Effect.fail(stalled);
+      return yield* restore(execute);
+    })).pipe(Effect.interruptible), Effect.sleep(stallMs).pipe(Effect.andThen(Deferred.fail(admission, stalled)), Effect.flatMap((expired) => expired ? Effect.fail(stalled) : Effect.never), Effect.interruptible))));
+  });
+});

package/dist/files-io.adapter.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The file system calls the store makes, each one promise: a seam a test
+ * replaces to make a call hang, fail or pause at a named point. Not a
+ * service: a constructor option of the store, like `SessionsLive`'s
+ * `liveness`.
+ *
+ * @public
+ */
+export interface FilesIo {
+    /** Create a directory and its parents (owner only); one that exists is fine. */
+    readonly mkdir: (path: string) => Promise<void>;
+    /** Create a new file with `bytes` (owner only), flushed to the disk before it answers; one that exists fails `EEXIST`. */
+    readonly create: (path: string, bytes: Uint8Array) => Promise<void>;
+    readonly link: (from: string, to: string) => Promise<void>;
+    readonly rename: (from: string, to: string) => Promise<void>;
+    readonly read: (path: string) => Promise<Uint8Array>;
+    /** The file's first bytes, up to `length` (all of them when the file is that long, however many reads it takes). */
+    readonly readStart: (path: string, length: number) => Promise<Uint8Array>;
+    readonly list: (path: string) => Promise<ReadonlyArray<string>>;
+    /** Whether the path exists; a missing one answers false, any other failure rejects. */
+    readonly exists: (path: string) => Promise<boolean>;
+    readonly unlink: (path: string) => Promise<void>;
+    /** Remove a directory and everything in it. */
+    readonly removeTree: (path: string) => Promise<void>;
+    /** Flush a directory's entries to the disk; a file system that cannot answers an error the store ignores. */
+    readonly syncDirectory: (path: string) => Promise<void>;
+}
+/** One positioned read: it may answer fewer bytes than asked (an interrupted call, a network or FUSE mount). */
+export type ReadAt = (buffer: Uint8Array, offset: number, length: number, position: number) => Promise<{
+    readonly bytesRead: number;
+}>;
+/** The first `length` bytes of a file, reading again after a short answer until the buffer is full or the file ends. */
+export declare const readFully: (read: ReadAt, length: number) => Promise<Uint8Array>;
+/**
+ * The store's calls on the local machine's file system (`node:fs/promises`), on Node and Bun.
+ *
+ * @public
+ */
+export declare const nodeFilesIo: FilesIo;

package/dist/files-io.adapter.js

@@ -0,0 +1,22 @@
+import { link, mkdir, open, readdir, readFile, rename, rm, stat, unlink } from "node:fs/promises";
+import { Option } from "effect";
+import { errorCodeOf } from "@xandreed/core";
+const missing = (error) => Option.contains(errorCodeOf(error), "ENOENT");
+export const readFully = (read, length) => {
+  const buffer = new Uint8Array(length), from = (offset) => offset >= length ? Promise.resolve(offset) : read(buffer, offset, length - offset, offset).then(({ bytesRead }) => bytesRead === 0 ? offset : from(offset + bytesRead));
+  return from(0).then((filled) => buffer.subarray(0, filled));
+}, nodeFilesIo = {
+  mkdir: (path) => mkdir(path, { recursive: !0, mode: 448 }).then(() => {
+    return;
+  }),
+  create: (path, bytes) => open(path, "wx", 384).then((handle) => handle.writeFile(bytes).then(() => handle.sync()).then(() => handle.close(), (error) => handle.close().then(() => Promise.reject(error), () => Promise.reject(error)))),
+  link: (from, to) => link(from, to),
+  rename: (from, to) => rename(from, to),
+  read: (path) => readFile(path),
+  readStart: (path, length) => open(path, "r").then((handle) => readFully((buffer, offset, size, position) => handle.read(buffer, offset, size, position), length).then((bytes) => handle.close().then(() => bytes), (error) => handle.close().then(() => Promise.reject(error), () => Promise.reject(error)))),
+  list: (path) => readdir(path),
+  exists: (path) => stat(path).then(() => !0, (error) => missing(error) ? !1 : Promise.reject(error)),
+  unlink: (path) => unlink(path),
+  removeTree: (path) => rm(path, { recursive: !0, force: !0 }),
+  syncDirectory: (path) => open(path, "r").then((handle) => handle.sync().then(() => handle.close(), (error) => handle.close().then(() => Promise.reject(error), () => Promise.reject(error))))
+};

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import { sessionFilesPlugin } from "./plugin.adapter.js";
+export { makeSessionLogFiles, SessionLogFilesLive } from "./session-log.adapter.js";
+export type { SessionLogFilesOptions } from "./session-log.adapter.js";
+export type { FilesIo } from "./files-io.adapter.js";
+export { nodeFilesIo } from "./files-io.adapter.js";
+export { MediaStoreDirectoryLive } from "./media-store-directory.adapter.js";
+export type { MediaStoreDirectoryOptions } from "./media-store-directory.adapter.js";
+export { sessionFilesPlugin, sessionLogFilesPlugin } from "./plugin.adapter.js";
+export { SessionFilesConfig, sessionFilesDefaults } from "./session-files.entity.js";
+/** @public */
+export default sessionFilesPlugin;

package/dist/index.js

@@ -0,0 +1,7 @@
+import { sessionFilesPlugin } from "./plugin.adapter.js";
+export { makeSessionLogFiles, SessionLogFilesLive } from "./session-log.adapter.js";
+export { nodeFilesIo } from "./files-io.adapter.js";
+export { MediaStoreDirectoryLive } from "./media-store-directory.adapter.js";
+export { sessionFilesPlugin, sessionLogFilesPlugin } from "./plugin.adapter.js";
+export { SessionFilesConfig, sessionFilesDefaults } from "./session-files.entity.js";
+export default sessionFilesPlugin;

package/dist/media-store-directory.adapter.d.ts

@@ -0,0 +1,16 @@
+import { Layer } from "effect";
+import { MediaStore, MediaStoreError } from "@xandreed/core";
+import type { FilesIo } from "./files-io.adapter.js";
+/** The directory adapter's bounded IO and fault-injection seam. @public */
+export interface MediaStoreDirectoryOptions {
+    readonly io?: FilesIo;
+    readonly stallMs?: number;
+}
+/**
+ * Immutable SHA-256 media blobs, published by exclusive hard link after file sync.
+ * The independent root retains orphans; session removal never deletes blobs.
+ * Opening sweeps temporary files older than an hour; a put of bytes whose final
+ * file is damaged keeps that file in `quarantine/` and replaces it.
+ * @public
+ */
+export declare const MediaStoreDirectoryLive: (root: string, options?: MediaStoreDirectoryOptions) => Layer.Layer<MediaStore, MediaStoreError, never>;

package/dist/media-store-directory.adapter.js

@@ -0,0 +1,77 @@
+import { createHash, randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { Clock, Effect, Layer, Match, Option, Result, Schema } from "effect";
+import { errorCodeOf, MEDIA_LIMITS, MediaHash, MediaStore, MediaStoreBytes, MediaStoreError } from "@xandreed/core";
+import { nodeFilesIo } from "./files-io.adapter.js";
+import { makeBoundedFilesCall } from "./bounded-call.adapter.js";
+import { MEDIA_DIRECTORY_LAYOUT, MediaDirectoryMarker } from "./media-store-directory.entity.js";
+import { sessionFilesDefaults } from "./session-files.entity.js";
+const missing = (error) => error._tag === "FileStoreIo" && Option.contains(errorCodeOf(error.cause), "ENOENT"), unavailable = (error) => Match.valueTags(error, {
+  FileStoreIo: ({ cause }) => new MediaStoreError({ reason: "Unavailable", message: "The media directory is unavailable.", cause }),
+  FileStoreStalled: (cause) => new MediaStoreError({ reason: "Unavailable", message: "The media directory did not answer within its deadline.", cause })
+}), corrupt = () => new MediaStoreError({ reason: "Corrupt", message: "The stored media does not match its content key." }), equal = (left, right) => left.length === right.length && left.every((byte, index) => byte === right[index]), stallBound = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 2147483647 })), sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex"), TEMPORARY_GRACE_MS = 3600000, createdAt = (name) => Option.map(Option.fromNullishOr(/^(?:[0-9a-f]{64}|marker)\.(\d{1,16})\.[0-9a-f-]{36}(?:\.tmp)?$/.exec(name)?.[1]), Number), makeDirectory = Effect.fnUntraced(function* (root, options) {
+  const io = options?.io ?? nodeFilesIo, stallMs = yield* Schema.decodeUnknownEffect(stallBound)(options?.stallMs ?? sessionFilesDefaults.stallMs).pipe(Effect.mapError((cause) => new MediaStoreError({ reason: "Invalid", message: "The media directory deadline is invalid.", cause }))), call = yield* makeBoundedFilesCall(stallMs), blobs = join(root, "blobs"), temporary = join(root, "tmp"), quarantine = join(root, "quarantine"), marker = join(root, "media-store.json"), encoder = new TextEncoder, decoder = new TextDecoder, clean = (path) => call("unlink", path, () => io.unlink(path)).pipe(Effect.ignore({ log: "Debug", message: "A temporary media file was left for later cleanup." })), sync = (path) => call("sync", path, () => io.syncDirectory(path)).pipe(Effect.ignore({ log: "Debug", message: "The media directory could not synchronize its directory entries." })), read = (path, max) => call("read", path, () => io.readStart(path, max + 1)).pipe(Effect.map(Option.some), Effect.catchIf(missing, () => Effect.succeed(Option.none())), Effect.mapError(unavailable)), markerAt = Effect.gen(function* () {
+    const found = yield* read(marker, 1024);
+    return yield* Option.match(found, {
+      onNone: () => Effect.succeed(!1),
+      onSome: (bytes) => Effect.gen(function* () {
+        if (bytes.length > 1024)
+          return yield* Effect.fail(new MediaStoreError({ reason: "Corrupt", message: "The media directory marker is invalid." }));
+        if ((yield* Schema.decodeUnknownEffect(Schema.fromJsonString(MediaDirectoryMarker))(decoder.decode(bytes)).pipe(Effect.mapError((cause) => new MediaStoreError({ reason: "Corrupt", message: "The media directory marker is invalid.", cause })))).layout !== MEDIA_DIRECTORY_LAYOUT)
+          return yield* Effect.fail(new MediaStoreError({ reason: "Unavailable", message: "The media directory layout is not supported." }));
+        return !0;
+      })
+    });
+  });
+  yield* Effect.forEach([root, blobs, temporary, quarantine], (path) => call("mkdir", path, () => io.mkdir(path)), { concurrency: 1, discard: !0 }).pipe(Effect.mapError(unavailable));
+  const temporaryPath = (prefix, suffix) => Clock.currentTimeMillis.pipe(Effect.map((now) => join(temporary, `${prefix}.${now}.${randomUUID()}${suffix}`)));
+  yield* Effect.gen(function* () {
+    const now = yield* Clock.currentTimeMillis, names = yield* call("list", temporary, () => io.list(temporary));
+    yield* Effect.forEach(names.filter((name) => Option.exists(createdAt(name), (at) => now - at > TEMPORARY_GRACE_MS)), (name) => clean(join(temporary, name)), { concurrency: 1, discard: !0 });
+  }).pipe(Effect.ignore({ log: "Debug", message: "The media directory's abandoned temporary files were not swept." }));
+  if (!(yield* markerAt)) {
+    const path = yield* temporaryPath("marker", "");
+    yield* Effect.gen(function* () {
+      yield* call("create", path, () => io.create(path, encoder.encode(`${JSON.stringify({ layout: MEDIA_DIRECTORY_LAYOUT, algorithm: "sha256" })}
+`))).pipe(Effect.mapError(unavailable));
+      yield* call("link", marker, () => io.link(path, marker)).pipe(Effect.catch((error) => markerAt.pipe(Effect.catchIf((failure) => failure.reason === "Unavailable", () => Effect.fail(unavailable(error))), Effect.flatMap((exists) => exists ? Effect.void : Effect.fail(unavailable(error))))), Effect.ensuring(clean(path).pipe(Effect.interruptible)));
+      yield* sync(root);
+    });
+  }
+  const blobAt = (hash) => read(join(blobs, `${hash}.bin`), MEDIA_LIMITS.imageBytes).pipe(Effect.flatMap((found) => Option.match(found, {
+    onNone: () => Effect.succeed(Option.none()),
+    onSome: (raw) => {
+      const bytes = new Uint8Array(raw);
+      return bytes.length > 0 && bytes.length <= MEDIA_LIMITS.imageBytes && sha256(bytes) === hash ? Effect.succeed(Option.some(bytes)) : Effect.fail(corrupt());
+    }
+  }))), checkHash = (hash) => Schema.decodeUnknownEffect(MediaHash)(hash).pipe(Effect.mapError((cause) => new MediaStoreError({ reason: "Invalid", message: "The media content key is invalid.", cause })));
+  return MediaStore.of({
+    get: Effect.fn("media_store.get")(function* (key) {
+      return yield* blobAt(yield* checkHash(key));
+    }),
+    put: Effect.fn("media_store.put")(function* (input) {
+      const decoded = Schema.decodeUnknownResult(MediaStoreBytes)(input);
+      if (Result.isFailure(decoded))
+        return yield* Effect.fail(new MediaStoreError({ reason: "Invalid", message: "The media bytes are outside the store's bounds.", cause: decoded.failure }));
+      const bytes = new Uint8Array(decoded.success), checked = Schema.decodeUnknownResult(MediaStoreBytes)(bytes);
+      if (Result.isFailure(checked))
+        return yield* Effect.fail(new MediaStoreError({ reason: "Invalid", message: "The media bytes are outside the store's bounds.", cause: checked.failure }));
+      const hash = MediaHash.make(sha256(bytes)), final = join(blobs, `${hash}.bin`), presence = blobAt(hash).pipe(Effect.map((found) => Option.match(found, { onNone: () => "absent", onSome: (stored) => equal(stored, bytes) ? "present" : "corrupt" })), Effect.catchIf((failure) => failure.reason === "Corrupt", () => Effect.succeed("corrupt"))), repair = (path) => Effect.gen(function* () {
+        const kept = join(quarantine, `${hash}.${yield* Clock.currentTimeMillis}.${randomUUID()}.bin`);
+        yield* call("link", kept, () => io.link(final, kept)).pipe(Effect.catchIf(missing, () => Effect.void), Effect.mapError(unavailable));
+        yield* call("rename", final, () => io.rename(path, final)).pipe(Effect.mapError(unavailable));
+        yield* Effect.logWarning("A damaged media blob was replaced by the bytes put again; the damaged copy is in quarantine.").pipe(Effect.annotateLogs({ "efferent.media.hash": hash }));
+      }), found = yield* presence;
+      if (found === "present")
+        return hash;
+      const path = yield* temporaryPath(hash, ".tmp");
+      yield* Effect.gen(function* () {
+        yield* call("create", path, () => io.create(path, bytes)).pipe(Effect.mapError(unavailable));
+        yield* (found === "corrupt" ? repair(path) : call("link", final, () => io.link(path, final)).pipe(Effect.catch((error) => presence.pipe(Effect.catchIf((failure) => failure.reason === "Unavailable", () => Effect.fail(unavailable(error))), Effect.flatMap((now) => now === "present" ? Effect.void : now === "corrupt" ? repair(path) : Effect.fail(unavailable(error))))))).pipe(Effect.ensuring(clean(path).pipe(Effect.interruptible)));
+        yield* sync(blobs);
+      });
+      return hash;
+    })
+  });
+});
+export const MediaStoreDirectoryLive = (root, options) => Layer.effect(MediaStore, makeDirectory(root, options));

package/dist/media-store-directory.entity.d.ts

@@ -0,0 +1,7 @@
+import { Schema } from "effect";
+/** Independent of the session log's store.json and FILES_LAYOUT. */
+export declare const MEDIA_DIRECTORY_LAYOUT = 1;
+export declare const MediaDirectoryMarker: Schema.Struct<{
+    readonly layout: Schema.Int;
+    readonly algorithm: Schema.Literal<"sha256">;
+}>;

package/dist/media-store-directory.entity.js

@@ -0,0 +1,2 @@
+import { Schema } from "effect";
+export const MEDIA_DIRECTORY_LAYOUT = 1, MediaDirectoryMarker = Schema.Struct({ layout: Schema.Int, algorithm: Schema.Literal("sha256") });

package/dist/plugin.adapter.d.ts

@@ -0,0 +1,26 @@
+import { SessionLog, TurnAdmission } from "@xandreed/core";
+/**
+ * The session log in a directory, as a plugin: provides `SessionLog`.
+ *
+ * @public
+ */
+export declare const sessionLogFilesPlugin: import("@xandreed/core").TypedPlugin<{
+    readonly path: string;
+    readonly stallMs: number;
+}, {
+    readonly path: string;
+    readonly stallMs: number;
+}, SessionLog, import("@xandreed/core").SessionLogError, never>;
+/**
+ * The session log in a directory and the open admission policy; compose
+ * `sessionsPlugin` beside it in the host's graph.
+ *
+ * @public
+ */
+export declare const sessionFilesPlugin: import("@xandreed/core").TypedPlugin<{
+    readonly path: string;
+    readonly stallMs: number;
+}, {
+    readonly path: string;
+    readonly stallMs: number;
+}, SessionLog | TurnAdmission, import("@xandreed/core").SessionLogError, never>;

package/dist/plugin.adapter.js

@@ -0,0 +1,21 @@
+import { Layer } from "effect";
+import { definePlugin, SessionLog, TurnAdmission, TurnAdmissionOpen } from "@xandreed/core";
+import { SessionLogFilesLive } from "./session-log.adapter.js";
+import { SessionFilesConfig, sessionFilesDefaults } from "./session-files.entity.js";
+export const sessionLogFilesPlugin = definePlugin({
+  id: "@xandreed/plugin-session-files/log",
+  version: "0.15.1",
+  scope: "runtime",
+  config: SessionFilesConfig,
+  defaults: sessionFilesDefaults,
+  provides: [SessionLog],
+  layer: ({ path, stallMs }) => SessionLogFilesLive(path, { stallMs })
+}), sessionFilesPlugin = definePlugin({
+  id: "@xandreed/plugin-session-files",
+  version: "0.15.1",
+  scope: "runtime",
+  config: SessionFilesConfig,
+  defaults: sessionFilesDefaults,
+  provides: [SessionLog, TurnAdmission],
+  layer: ({ path, stallMs }) => Layer.merge(SessionLogFilesLive(path, { stallMs }), TurnAdmissionOpen)
+});

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

@@ -0,0 +1,135 @@
+import { Schema } from "effect";
+import { JsonObject } from "@xandreed/core";
+/** The version of the directory's layout; a later one is refused (`store.version`). Shipped: change it only with a migration. */
+export declare const FILES_LAYOUT = 1;
+/**
+ * How long something stays in `staging/` before an open sweeps it as left
+ * by a create, an open or a link probe that stopped half way: an hour, and
+ * never less than 16 stall bounds (more than the longest staging takes).
+ */
+export declare const STAGING_SWEEP_MS = 3600000;
+/** `store.json`: the layout the directory holds. */
+export declare const StoreMarker: Schema.Struct<{
+    readonly layout: Schema.Int;
+}>;
+export type StoreMarker = typeof StoreMarker.Type;
+/** A writer's mark on what it published: told apart from another writer's after an answer that may be wrong (a retransmitted link). */
+export declare const PublishNonce: Schema.brand<Schema.String, "PublishNonce">;
+export type PublishNonce = typeof PublishNonce.Type;
+/** `header.json`: the header, the storage time it was created at, and its creator's nonce. */
+export declare const HeaderRecord: Schema.Struct<{
+    readonly header: Schema.Struct<{
+        readonly id: Schema.brand<Schema.String, "ConversationId">;
+        readonly owner: Schema.Trimmed;
+        readonly origin: Schema.Trimmed;
+        readonly createdAt: Schema.Number;
+        readonly meta: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        readonly parent: Schema.OptionFromNullOr<Schema.Struct<{
+            readonly id: Schema.brand<Schema.String, "ConversationId">;
+            readonly through: Schema.Int;
+            readonly turnAtFork: Schema.Int;
+        }>>;
+    }>;
+    readonly createdNow: Schema.Number;
+    readonly nonce: Schema.brand<Schema.String, "PublishNonce">;
+}>;
+export type HeaderRecord = typeof HeaderRecord.Type;
+/** A commit file's first line: what it holds, read alone to skip a commit a read does not need. */
+export declare const CommitMeta: Schema.Struct<{
+    readonly layout: Schema.Int;
+    readonly session: Schema.brand<Schema.String, "ConversationId">;
+    /** The revision this commit made: its file's name. */
+    readonly revision: Schema.Int;
+    /** The first event's sequence number, and the session's last after the commit. */
+    readonly first: Schema.Int;
+    readonly last: Schema.Int;
+    /** The storage time: every event's, and the head's `updatedAt`. */
+    readonly at: Schema.Number;
+    /** The kinds of its events, each once. */
+    readonly kinds: Schema.$Array<Schema.String>;
+    readonly nonce: Schema.brand<Schema.String, "PublishNonce">;
+}>;
+export type CommitMeta = typeof CommitMeta.Type;
+/** A commit file's second line: the head's whole state after the commit (a commit without one carries the state before it). */
+export declare const CommitState: Schema.Struct<{
+    readonly state: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>;
+export type CommitState = typeof CommitState.Type;
+/** One event of a commit. */
+export declare const CommitEvent: Schema.Struct<{
+    readonly seq: Schema.Int;
+    readonly turn: Schema.NullOr<Schema.Int>;
+    readonly kind: Schema.String;
+    readonly data: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>;
+export type CommitEvent = typeof CommitEvent.Type;
+/** A commit file's last line: the bytes before it and their CRC-32, so a file cut short or changed is told apart from a whole one. */
+export declare const CommitTrailer: Schema.Struct<{
+    readonly bytes: Schema.Int;
+    readonly crc32: Schema.String;
+}>;
+export type CommitTrailer = typeof CommitTrailer.Type;
+/** A commit file, read whole and checked. */
+export interface CommitRecord {
+    readonly meta: CommitMeta;
+    readonly state: JsonObject;
+    readonly events: ReadonlyArray<CommitEvent>;
+}
+/** Why a commit file is not a whole commit. */
+export declare const CommitDamage: Schema.Literals<readonly ["short", "checksum", "decode"]>;
+export type CommitDamage = typeof CommitDamage.Type;
+/**
+ * What to do with a commit file that is not whole: at the session's tail it
+ * is a torn tail, set aside (`quarantine`), and the commit before it is the
+ * head; anywhere else the session is damaged (`store.decode`), and nothing
+ * is moved.
+ */
+export type TailVerdict = {
+    readonly _tag: "Intact";
+} | {
+    readonly _tag: "Quarantine";
+    readonly damage: CommitDamage;
+} | {
+    readonly _tag: "Corrupt";
+    readonly damage: CommitDamage;
+};
+/** How the store answers while its directory stalls: every call fails at once until one goes through again. */
+export type StoreHealth = {
+    readonly _tag: "Healthy";
+} | {
+    readonly _tag: "Stalled";
+    readonly since: number;
+    readonly probing: boolean;
+};
+/**
+ * The file store's options: the directory, and how long one file system
+ * call may take before the store fails it with `store.stalled` (a hung
+ * network mount never answers; the store then fails every call at once
+ * until one, let through a `stallMs` later, answers again).
+ *
+ * @public
+ */
+export declare const SessionFilesConfig: Schema.Struct<{
+    readonly path: Schema.String;
+    readonly stallMs: Schema.Int;
+}>;
+export type SessionFilesConfig = typeof SessionFilesConfig.Type;
+/** @public */
+export declare const sessionFilesDefaults: SessionFilesConfig;
+declare const FileStoreIo_base: Schema.Class<FileStoreIo, Schema.TaggedStruct<"FileStoreIo", {
+    readonly op: Schema.String;
+    readonly path: Schema.String;
+    readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/** A file system call failed: its operation, its path, and the file system's own error. */
+export declare class FileStoreIo extends FileStoreIo_base {
+}
+declare const FileStoreStalled_base: Schema.Class<FileStoreStalled, Schema.TaggedStruct<"FileStoreStalled", {
+    readonly op: Schema.String;
+    readonly path: Schema.String;
+    readonly ms: Schema.Int;
+}>, import("effect/Cause").YieldableError>;
+/** A file system call did not answer within `stallMs`. */
+export declare class FileStoreStalled extends FileStoreStalled_base {
+}
+export {};

package/dist/session-files.entity.functions.d.ts

@@ -0,0 +1,76 @@
+import { Option, Order, Result, Schema } from "effect";
+import type { SessionHead, SessionListQuery } from "@xandreed/core";
+import { CommitMeta, HeaderRecord, StoreMarker } from "./session-files.entity.js";
+import type { CommitDamage, CommitRecord, StoreHealth, TailVerdict } from "./session-files.entity.js";
+/** The CRC-32 of `bytes`, as eight lowercase hex digits. */
+export declare const crc32Of: (bytes: Uint8Array) => string;
+/** A commit file's name: its revision, padded so names sort as numbers do. */
+export declare const revisionFile: (revision: number) => string;
+/** The revision a commit file's name holds; none for any other name (a temporary file, a stray one). */
+export declare const revisionOfFile: (name: string) => Option.Option<number>;
+/** The revision a temporary commit file was written for (`<revision>.jsonl.<nonce>`); none for any other name. */
+export declare const revisionOfTemporary: (name: string) => Option.Option<number>;
+/** Whether a name under `sessions/` is a session's directory: its id. Anything else (an editor's file, a network file system's `.nfs…`) is not read. */
+export declare const isSessionDirectory: (name: string) => boolean;
+/** A name in `staging/` for what `prefix` names, staged at storage time `now` (`<prefix>.<now>.<unique>`), so a later open can tell its age. */
+export declare const stagingName: (prefix: string, now: number, unique: string) => string;
+/** The storage time a name in `staging/` was staged at; none for a name that does not carry one (an earlier release's). */
+export declare const stagedAtOf: (name: string) => Option.Option<number>;
+/**
+ * Whether a name in `staging/` was left by a create, an open or a probe that
+ * stopped half way: it was staged more than `ageMs` before `now`. A name
+ * without its time is never judged abandoned.
+ */
+export declare const isAbandonedStaging: (name: string, now: number, ageMs: number) => boolean;
+/** Whether two files hold the same bytes. */
+export declare const sameBytes: (left: Uint8Array, right: Uint8Array) => boolean;
+/**
+ * A handle's cache bounds: how many sessions it remembers, and how many
+ * commit first lines (`CommitMeta`) it keeps across them.
+ */
+export declare const CACHE_BOUNDS: {
+    readonly sessions: 1024;
+    readonly metas: 65536;
+};
+/**
+ * The cache within its bounds: entries in order of use (the least recently
+ * used first), the oldest dropped past `bounds.sessions`; then the oldest
+ * entries' metas dropped (`shrink(entry, kept)`, `size` counting them) until
+ * at most `bounds.metas` are kept, the newest entry keeping its highest
+ * revisions when it alone is over.
+ */
+export declare const trimCache: <K, V>(entries: ReadonlyMap<K, V>, size: (entry: V) => number, shrink: (entry: V, kept: number) => V, bounds: {
+    readonly sessions: number;
+    readonly metas: number;
+}) => ReadonlyMap<K, V>;
+/** The lines of a commit file, as its bytes: meta, state, one line per event, then the trailer over the bytes before it. */
+export declare const encodeCommit: (record: CommitRecord) => Uint8Array;
+/**
+ * A commit file's bytes as the commit: whole (its trailer's length and
+ * CRC-32 match the bytes before it) and decoded line by line, or what is
+ * wrong with it: cut short (no trailer, or one that counts other bytes),
+ * changed (the checksum), or lines that do not decode.
+ */
+export declare const decodeCommit: (bytes: Uint8Array) => Result.Result<CommitRecord, CommitDamage>;
+/** A commit file's first line, read alone (a read that skips the commit needs nothing else); none when it is not one. */
+export declare const metaOfLine: (line: string) => Option.Option<CommitMeta>;
+/** What to do with a commit file that is not whole: a tail is set aside; anything before the tail is damage the store does not repair. */
+export declare const tailVerdict: (decoded: Result.Result<CommitRecord, CommitDamage>, isTail: boolean) => TailVerdict;
+/** `header.json` as text. */
+export declare const headerText: (record: HeaderRecord) => Result.Result<string, Schema.SchemaError>;
+/** `header.json`'s text as its record. */
+export declare const headerOfText: (text: string) => Result.Result<HeaderRecord, Schema.SchemaError>;
+/** `store.json`'s text as its marker. */
+export declare const markerOfText: (text: string) => Result.Result<StoreMarker, Schema.SchemaError>;
+/** Most recently updated first, then by id, descending: the listing's order. */
+export declare const newestFirst: Order.Order<SessionHead>;
+/** Whether a session's header puts it in a listing: the owner's, top-level or the named parent's child. */
+export declare const inListing: (record: HeaderRecord, query: SessionListQuery) => boolean;
+/** The heads strictly older than the listing's cursor, in order, at most its limit. */
+export declare const page: (heads: ReadonlyArray<SessionHead>, query: SessionListQuery) => ReadonlyArray<SessionHead>;
+/** Whether a call goes through: always while healthy; while stalled, one call at a time once `stallMs` passed since the stall (the probe). */
+export declare const admitCall: (health: StoreHealth, now: number, stallMs: number) => readonly [boolean, StoreHealth];
+/** A call's outcome on the store's health: one that answered heals it; one that stalled marks it stalled from now. */
+export declare const afterCall: (health: StoreHealth, answered: boolean, now: number) => StoreHealth;
+/** Cancellation abandons a probe without turning an answered healthy mount into a stalled one. */
+export declare const abandonCall: (health: StoreHealth, claimed: StoreHealth) => StoreHealth;

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

@@ -0,0 +1,65 @@
+import { Option, Order, Result, Schema } from "effect";
+import { CommitEvent, CommitMeta, CommitState, CommitTrailer, HeaderRecord, StoreMarker } from "./session-files.entity.js";
+const CRC_TABLE = Array.from({ length: 256 }, (_, n) => Array.from({ length: 8 }).reduce((c) => (c & 1) === 1 ? 3988292384 ^ c >>> 1 : c >>> 1, n));
+export const crc32Of = (bytes) => ((bytes.reduce((crc, byte) => (CRC_TABLE[(crc ^ byte) & 255] ?? 0) ^ crc >>> 8, 4294967295) ^ 4294967295) >>> 0).toString(16).padStart(8, "0");
+const REVISION_DIGITS = 12;
+export const revisionFile = (revision) => `${String(revision).padStart(REVISION_DIGITS, "0")}.jsonl`, revisionOfFile = (name) => {
+  const match = /^(\d{12})\.jsonl$/.exec(name);
+  return match === null ? Option.none() : Option.some(Number(match[1]));
+}, revisionOfTemporary = (name) => {
+  const match = /^(\d{12})\.jsonl\./.exec(name);
+  return match === null ? Option.none() : Option.some(Number(match[1]));
+};
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const isSessionDirectory = (name) => UUID.test(name), stagingName = (prefix, now, unique) => `${prefix}.${now}.${unique}`, stagedAtOf = (name) => {
+  const match = /\.(\d+)\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(?:\.linked)?$/i.exec(name);
+  return match === null ? Option.none() : Option.some(Number(match[1]));
+}, isAbandonedStaging = (name, now, ageMs) => Option.exists(stagedAtOf(name), (at) => now - at > ageMs), sameBytes = (left, right) => left.length === right.length && left.every((byte, index) => byte === right[index]), CACHE_BOUNDS = { sessions: 1024, metas: 65536 }, trimCache = (entries, size, shrink, bounds) => {
+  const kept = [...entries].slice(Math.max(0, entries.size - bounds.sessions)), total = kept.reduce((sum, [, entry]) => sum + size(entry), 0);
+  return new Map(kept.reduce((acc, [key, entry]) => {
+    const own = size(entry), drop = Math.min(own, acc.over);
+    acc.out.push([key, drop === 0 ? entry : shrink(entry, own - drop)]);
+    return { over: acc.over - drop, out: acc.out };
+  }, { over: Math.max(0, total - bounds.metas), out: [] }).out);
+};
+const encoder = new TextEncoder, decoder = new TextDecoder;
+export const encodeCommit = (record) => {
+  const body = encoder.encode([
+    JSON.stringify(record.meta),
+    JSON.stringify({ state: record.state }),
+    ...record.events.map((event) => JSON.stringify(event))
+  ].map((line) => `${line}
+`).join("")), trailer = encoder.encode(`${JSON.stringify({ bytes: body.length, crc32: crc32Of(body) })}
+`), file = new Uint8Array(body.length + trailer.length);
+  file.set(body);
+  file.set(trailer, body.length);
+  return file;
+};
+const decodeMetaLine = Schema.decodeUnknownResult(Schema.fromJsonString(CommitMeta)), decodeStateLine = Schema.decodeUnknownResult(Schema.fromJsonString(CommitState)), decodeEventLine = Schema.decodeUnknownResult(Schema.fromJsonString(CommitEvent)), decodeTrailerLine = Schema.decodeUnknownResult(Schema.fromJsonString(CommitTrailer));
+export const decodeCommit = (bytes) => {
+  const end = bytes.length > 0 && bytes[bytes.length - 1] === 10 ? bytes.length - 1 : -1;
+  if (end < 0)
+    return Result.fail("short");
+  const trailerStart = bytes.lastIndexOf(10, end - 1) + 1, trailer = decodeTrailerLine(decoder.decode(bytes.subarray(trailerStart, end)));
+  if (Result.isFailure(trailer) || trailer.success.bytes !== trailerStart)
+    return Result.fail("short");
+  const body = bytes.subarray(0, trailerStart);
+  if (crc32Of(body) !== trailer.success.crc32)
+    return Result.fail("checksum");
+  const [metaLine = "", stateLine = "", ...eventLines] = decoder.decode(body).split(`
+`).slice(0, -1), meta = decodeMetaLine(metaLine), state = decodeStateLine(stateLine), events = eventLines.map((line) => decodeEventLine(line));
+  if (Result.isFailure(meta) || Result.isFailure(state) || events.some(Result.isFailure))
+    return Result.fail("decode");
+  return Result.succeed({ meta: meta.success, state: state.success.state, events: events.flatMap((event) => Result.isSuccess(event) ? [event.success] : []) });
+}, metaOfLine = (line) => Result.getSuccess(decodeMetaLine(line)), tailVerdict = (decoded, isTail) => Result.match(decoded, {
+  onSuccess: () => ({ _tag: "Intact" }),
+  onFailure: (damage) => isTail ? { _tag: "Quarantine", damage } : { _tag: "Corrupt", damage }
+});
+const encodeHeader = Schema.encodeUnknownResult(Schema.fromJsonString(HeaderRecord)), decodeHeaderText = Schema.decodeUnknownResult(Schema.fromJsonString(HeaderRecord)), decodeMarkerText = Schema.decodeUnknownResult(Schema.fromJsonString(StoreMarker));
+export const headerText = (record) => encodeHeader(record), headerOfText = (text) => decodeHeaderText(text), markerOfText = (text) => decodeMarkerText(text), newestFirst = Order.combine(Order.flip(Order.mapInput(Order.Number, (head) => head.updatedAt)), Order.flip(Order.mapInput(Order.String, (head) => head.header.id))), inListing = (record, query) => record.header.owner === query.owner && Option.match(query.parent, {
+  onNone: () => Option.isNone(record.header.parent),
+  onSome: (parent) => Option.exists(record.header.parent, (lineage) => lineage.id === parent)
+}), page = (heads, query) => [...heads].sort(newestFirst).filter((head) => Option.match(query.before, {
+  onNone: () => !0,
+  onSome: (cursor) => head.updatedAt < cursor.updatedAt || head.updatedAt === cursor.updatedAt && head.header.id < cursor.id
+})).slice(0, Math.max(0, query.limit)), admitCall = (health, now, stallMs) => health._tag === "Healthy" ? [!0, health] : !health.probing && now - health.since >= stallMs ? [!0, { ...health, probing: !0 }] : [!1, health], afterCall = (health, answered, now) => answered ? { _tag: "Healthy" } : { _tag: "Stalled", since: now, probing: !1 }, abandonCall = (health, claimed) => health !== claimed || health._tag === "Healthy" ? health : { ...health, probing: !1 };

package/dist/session-files.entity.js

@@ -0,0 +1,38 @@
+import { Schema } from "effect";
+import { ConversationId, JsonObject, SessionHeader } from "@xandreed/core";
+export const FILES_LAYOUT = 1, STAGING_SWEEP_MS = 3600000, StoreMarker = Schema.Struct({ layout: Schema.Int }), PublishNonce = Schema.String.pipe(Schema.brand("PublishNonce")), HeaderRecord = Schema.Struct({
+  header: SessionHeader,
+  createdNow: Schema.Number,
+  nonce: PublishNonce
+}), CommitMeta = Schema.Struct({
+  layout: Schema.Int,
+  session: ConversationId,
+  revision: Schema.Int,
+  first: Schema.Int,
+  last: Schema.Int,
+  at: Schema.Number,
+  kinds: Schema.Array(Schema.String),
+  nonce: PublishNonce
+}), CommitState = Schema.Struct({ state: JsonObject }), CommitEvent = Schema.Struct({
+  seq: Schema.Int,
+  turn: Schema.NullOr(Schema.Int),
+  kind: Schema.String,
+  data: JsonObject
+}), CommitTrailer = Schema.Struct({ bytes: Schema.Int, crc32: Schema.String }), CommitDamage = Schema.Literals(["short", "checksum", "decode"]), SessionFilesConfig = Schema.Struct({
+  path: Schema.String,
+  stallMs: Schema.Int.check(Schema.isGreaterThanOrEqualTo(100))
+}), sessionFilesDefaults = { path: ".efferent/runtime/sessions", stallMs: 1e4 };
+
+export class FileStoreIo extends Schema.TaggedError()("FileStoreIo", {
+  op: Schema.String,
+  path: Schema.String,
+  cause: Schema.Defect()
+}) {
+}
+
+export class FileStoreStalled extends Schema.TaggedError()("FileStoreStalled", {
+  op: Schema.String,
+  path: Schema.String,
+  ms: Schema.Int
+}) {
+}

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

@@ -0,0 +1,60 @@
+import { Effect, Layer } from "effect";
+import type { Scope } from "effect";
+import { ConversationId, LeaseExpired, RevisionConflict, SessionExists, SessionLog, SessionLogError, SessionMissing } from "@xandreed/core";
+import type { SessionCommit, SessionCommitted, SessionHead, SessionHeader, SessionListQuery, SessionLogEvent, SessionReadQuery } from "@xandreed/core";
+import type { FilesIo } from "./files-io.adapter.js";
+/**
+ * The store's options beyond its directory: the stall bound, and the file system calls (a test's seam).
+ *
+ * @public
+ */
+export interface SessionLogFilesOptions {
+    readonly stallMs?: number;
+    readonly io?: FilesIo;
+}
+/**
+ * The session log as files in a directory, local or on a network mount
+ * (NFS), on Node 24 and Bun: one immutable file per commit, written to a
+ * temporary file, flushed, then published by an exclusive hard link to its
+ * revision's name. Exactly one writer wins each revision, so a commit is a
+ * compare-and-swap without a lock: no handle waits on another, and a handle
+ * whose process stopped blocks nobody. A publish whose answer may be wrong
+ * (a network file system's retransmitted link) is settled by reading the
+ * published file's nonce. A commit's `notAfter` is checked again once its
+ * file is written, right before the link. Creating a session publishes its
+ * directory by a rename; removing one renames it away first, never emptying
+ * it in place, then removes the children that name it as their parent.
+ *
+ * A commit file holds its trailer's length and CRC-32: one at a session's
+ * tail that is not whole (the disk dropped what was flushed) is moved to
+ * `quarantine/` and the commit before it is the head, a warning logged; one
+ * before the tail fails with `store.decode`, nothing moved. A move that took
+ * another writer's whole commit (published after another handle set the
+ * torn one aside) puts it back. A directory whose layout a newer release
+ * wrote fails to open with `store.version`; one without hard links, with
+ * `store.open`. An open sweeps what stopped creates, opens and removals left
+ * in `staging/` and `trash/`.
+ *
+ * At most two file system calls are in flight per handle, and each must
+ * answer within `stallMs` (default 10 s), or the call fails with
+ * `store.stalled`; then every call fails at once, until one let through a
+ * `stallMs` later answers again. A call that did not answer keeps its slot
+ * until it does, so a hung mount holds two of the runtime's worker threads,
+ * not all of them, and healthy calls queue for what is left. The time is
+ * the caller's Effect `Clock`: commits and heads are stamped with it, so
+ * instances sharing the directory need clocks in step. A handle caches at
+ * most `CACHE_BOUNDS` (sessions, commit first lines). Each call is a
+ * `session_log.<op>` span, with `efferent.session.id` when it names one.
+ *
+ * @public
+ */
+export declare const makeSessionLogFiles: (root: string, options?: SessionLogFilesOptions | undefined) => Effect.Effect<{
+    readonly create: (header: SessionHeader) => Effect.Effect<SessionHead, SessionExists | SessionMissing | SessionLogError>;
+    readonly head: (id: ConversationId) => Effect.Effect<SessionHead, SessionMissing | SessionLogError>;
+    readonly list: (query: SessionListQuery) => Effect.Effect<ReadonlyArray<SessionHead>, SessionLogError>;
+    readonly read: (id: ConversationId, query: SessionReadQuery) => Effect.Effect<ReadonlyArray<SessionLogEvent>, SessionMissing | SessionLogError>;
+    readonly commit: (id: ConversationId, commit: SessionCommit) => Effect.Effect<SessionCommitted, RevisionConflict | LeaseExpired | SessionMissing | SessionLogError>;
+    readonly remove: (id: ConversationId) => Effect.Effect<void, SessionLogError>;
+}, SessionLogError, Scope.Scope>;
+/** The session log in a directory (see `makeSessionLogFiles`). @public */
+export declare const SessionLogFilesLive: (root: string, options?: SessionLogFilesOptions) => Layer.Layer<SessionLog, SessionLogError>;

package/dist/session-log.adapter.js

@@ -0,0 +1,287 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { Cause, Clock, Effect, Layer, Match, Option, Ref, Result, Schema } from "effect";
+import {
+  ConversationId,
+  errorCodeOf,
+  LeaseExpired,
+  reasonOf,
+  RevisionConflict,
+  SessionExists,
+  SessionIncarnation,
+  SessionLog,
+  SessionLogError,
+  SessionMissing,
+  storedJson
+} from "@xandreed/core";
+import { nodeFilesIo } from "./files-io.adapter.js";
+import { makeBoundedFilesCall } from "./bounded-call.adapter.js";
+import { FILES_LAYOUT, PublishNonce, sessionFilesDefaults, STAGING_SWEEP_MS } from "./session-files.entity.js";
+import {
+  CACHE_BOUNDS,
+  decodeCommit,
+  encodeCommit,
+  headerOfText,
+  headerText,
+  inListing,
+  isAbandonedStaging,
+  isSessionDirectory,
+  markerOfText,
+  metaOfLine,
+  page,
+  revisionFile,
+  revisionOfFile,
+  revisionOfTemporary,
+  sameBytes,
+  stagingName,
+  tailVerdict,
+  trimCache
+} from "./session-files.entity.functions.js";
+const META_PREFIX = 65536, sessionIdOf = (name) => isSessionDirectory(name) ? Schema.decodeUnknownOption(ConversationId)(name) : Option.none(), encoder = new TextEncoder, decoder = new TextDecoder, isCode = (error, ...codes) => error._tag === "FileStoreIo" && Option.exists(errorCodeOf(error.cause), (code) => codes.includes(code)), vanished = (error) => error._tag === "SessionLogError" && Option.exists(errorCodeOf(error.cause), (code) => code === "ENOENT" || code === "ENOTDIR"), onSession = (effect, id) => Effect.annotateCurrentSpan("efferent.session.id", id).pipe(Effect.andThen(effect)), storeError = (code, what) => (error) => Match.valueTags(error, {
+  FileStoreStalled: (stalled) => new SessionLogError({
+    code: "store.stalled",
+    message: `the session directory did not answer ${stalled.op} of ${stalled.path} within ${stalled.ms} ms; a write it held may still land`
+  }),
+  FileStoreIo: (failed) => new SessionLogError({ code, message: `the session directory failed to ${what}: ${reasonOf(Cause.die(failed.cause))}`, cause: failed.cause })
+}), decodeError = (what, detail) => new SessionLogError({ code: "store.decode", message: `${what} does not decode: ${detail}` }), incarnationOf = (header) => SessionIncarnation.make(header.nonce), cacheWith = (all, id, entry) => trimCache(new Map([...all].filter(([key]) => key !== id)).set(id, entry), (known) => known.metas.size, (known, kept) => ({
+  ...known,
+  metas: new Map([...known.metas].toSorted(([left], [right]) => left - right).slice(known.metas.size - kept))
+}), CACHE_BOUNDS);
+export const makeSessionLogFiles = Effect.fnUntraced(function* (root, options) {
+  const io = options?.io ?? nodeFilesIo, stallMs = options?.stallMs ?? sessionFilesDefaults.stallMs, known = yield* Ref.make(new Map), swept = yield* Ref.make(new Set), sessionsDir = join(root, "sessions"), stagingDir = join(root, "staging"), dirOf = (id) => join(sessionsDir, id), headerPath = (id) => join(dirOf(id), "header.json"), commitsDir = (id) => join(dirOf(id), "commits"), commitPath = (id, revision) => join(commitsDir(id), revisionFile(revision)), nonce = () => PublishNonce.make(randomUUID()), staged = (prefix, now) => join(stagingDir, stagingName(prefix, now, randomUUID())), call = yield* makeBoundedFilesCall(stallMs), bestEffort = (op, path, run) => call(op, path, run).pipe(Effect.ignore({ log: "Debug", message: `the session directory could not ${op} ${path}; it is left as it is` })), openedAt = yield* Clock.currentTimeMillis;
+  yield* Effect.forEach([root, sessionsDir, stagingDir, join(root, "trash"), join(root, "quarantine")], (path) => call("mkdir", path, () => io.mkdir(path)), { concurrency: 1, discard: !0 }).pipe(Effect.mapError(storeError("store.open", "create its folders")));
+  const probe = staged("link-probe", openedAt);
+  yield* call("create", probe, () => io.create(probe, encoder.encode(`probe
+`))).pipe(Effect.mapError(storeError("store.open", "write a file")));
+  yield* call("link", probe, () => io.link(probe, `${probe}.linked`)).pipe(Effect.mapError((error) => isCode(error, "EPERM", "EOPNOTSUPP", "ENOTSUP", "ENOSYS", "EXDEV") ? new SessionLogError({ code: "store.open", message: `the session directory ${root} does not support hard links, which this store needs to publish a commit exclusively` }) : storeError("store.open", "link a file")(error)));
+  yield* bestEffort("unlink", probe, () => io.unlink(probe));
+  yield* bestEffort("unlink", `${probe}.linked`, () => io.unlink(`${probe}.linked`));
+  const markerPath = join(root, "store.json"), readMarker = call("read", markerPath, () => io.read(markerPath)).pipe(Effect.mapError(storeError("store.open", "read store.json")), Effect.flatMap((bytes) => Result.match(markerOfText(decoder.decode(bytes)), {
+    onFailure: (error) => Effect.fail(decodeError("store.json", error.message)),
+    onSuccess: Effect.succeed
+  }))), markerTemp = staged("store.json", openedAt);
+  yield* call("create", markerTemp, () => io.create(markerTemp, encoder.encode(`${JSON.stringify({ layout: FILES_LAYOUT })}
+`))).pipe(Effect.andThen(call("link", markerPath, () => io.link(markerTemp, markerPath)).pipe(Effect.catchIf((error) => isCode(error, "EEXIST"), () => Effect.void))), Effect.mapError(storeError("store.open", "write store.json")));
+  yield* bestEffort("unlink", markerTemp, () => io.unlink(markerTemp));
+  const marker = yield* readMarker;
+  if (marker.layout > FILES_LAYOUT)
+    return yield* Effect.fail(new SessionLogError({
+      code: "store.version",
+      message: `the session directory is at layout ${marker.layout}, written by a newer release; this release reads up to layout ${FILES_LAYOUT}`
+    }));
+  const leftIn = (folder) => call("list", join(root, folder), () => io.list(join(root, folder))).pipe(Effect.tapError((error) => Effect.logDebug(`the session directory's ${folder} could not be listed (${error._tag}); it is swept at the next open`)), Effect.orElseSucceed(() => [])), trashed = yield* leftIn("trash");
+  yield* Effect.forEach(trashed, (name) => bestEffort("remove", join(root, "trash", name), () => io.removeTree(join(root, "trash", name))), { concurrency: 1, discard: !0 });
+  const abandoned = (yield* leftIn("staging")).filter((name) => isAbandonedStaging(name, openedAt, Math.max(STAGING_SWEEP_MS, 16 * stallMs)));
+  yield* Effect.forEach(abandoned, (name) => bestEffort("remove", join(stagingDir, name), () => io.removeTree(join(stagingDir, name))), { concurrency: 1, discard: !0 });
+  const headerOf = (id) => call("read", headerPath(id), () => io.read(headerPath(id))).pipe(Effect.catchIf((error) => isCode(error, "ENOENT", "ENOTDIR"), () => Effect.fail(new SessionMissing({ session: id }))), Effect.mapError((error) => error._tag === "SessionMissing" ? error : storeError("store.io", "read a session's header")(error)), Effect.flatMap((bytes) => Result.match(headerOfText(decoder.decode(bytes)), {
+    onFailure: (error) => Effect.fail(decodeError(`the header of session ${id}`, error.message)),
+    onSuccess: Effect.succeed
+  }))), exists = (path) => call("stat", path, () => io.exists(path)).pipe(Effect.mapError(storeError("store.io", "look a file up"))), goneOr = (id, what) => (error) => isCode(error, "ENOENT", "ENOTDIR") ? exists(headerPath(id)).pipe(Effect.flatMap((there) => Effect.fail(there ? storeError("store.io", what)(error) : new SessionMissing({ session: id })))) : Effect.fail(storeError("store.io", what)(error)), probeForward = (id, from) => exists(commitPath(id, from + 1)).pipe(Effect.flatMap((found) => found ? probeForward(id, from + 1) : Effect.succeed(from))), listedRevision = (id) => call("list", commitsDir(id), () => io.list(commitsDir(id))).pipe(Effect.catch(goneOr(id, "list a session's commits")), Effect.map((names) => names.reduce((highest, name) => Option.match(revisionOfFile(name), { onNone: () => highest, onSome: (revision) => Math.max(highest, revision) }), 0))), commitBytes = (id, revision) => call("read", commitPath(id, revision), () => io.read(commitPath(id, revision))).pipe(Effect.catch(goneOr(id, "read a commit"))), wholeCommit = (id, revision) => commitBytes(id, revision).pipe(Effect.flatMap((bytes) => Result.match(decodeCommit(bytes), {
+    onFailure: (damage) => Effect.fail(decodeError(`commit ${revision} of session ${id}`, `${damage}; it is not the session's last, so it is not repaired`)),
+    onSuccess: Effect.succeed
+  }))), quarantine = (id, revision, torn, damage) => Effect.gen(function* () {
+    const folder = join(root, "quarantine", id);
+    yield* call("mkdir", folder, () => io.mkdir(folder)).pipe(Effect.mapError(storeError("store.io", "create the quarantine")));
+    const aside = join(folder, `${revisionFile(revision)}.${randomUUID()}`);
+    if (!(yield* call("rename", commitPath(id, revision), () => io.rename(commitPath(id, revision), aside)).pipe(Effect.as(!0), Effect.catchIf((error) => isCode(error, "ENOENT"), () => Effect.succeed(!1)), Effect.mapError(storeError("store.io", "set a torn commit aside")))))
+      return "aside";
+    const taken = yield* call("read", aside, () => io.read(aside)).pipe(Effect.mapError(storeError("store.io", "read a commit set aside"))), annotated = Effect.annotateLogs({ "efferent.session.id": id });
+    if (sameBytes(taken, torn)) {
+      yield* Effect.logWarning(`a torn commit at the tail of the session (revision ${revision}, ${damage}) was moved to ${aside}; the commit before it is the session's head`).pipe(annotated);
+      return "aside";
+    }
+    if (yield* call("link", commitPath(id, revision), () => io.link(aside, commitPath(id, revision))).pipe(Effect.as(!0), Effect.catchIf((error) => isCode(error, "EEXIST"), () => Effect.succeed(!1)), Effect.mapError(storeError("store.io", "put a commit back")))) {
+      yield* bestEffort("unlink", aside, () => io.unlink(aside));
+      return "restored";
+    }
+    yield* Effect.logError(`revision ${revision} of the session, published again after a torn one was set aside, was moved to ${aside} and could not be put back: a third writer took the revision; its bytes are kept there`).pipe(annotated);
+    return "restored";
+  }), tailOfRecord = (record) => ({ revision: record.meta.revision, seq: record.meta.last, at: record.meta.at, state: record.state }), tailAt = (id, header, revision, repaired) => {
+    if (revision === 0)
+      return Effect.succeed({ tail: { revision: 0, seq: 0, at: header.createdNow, state: {} }, meta: Option.none() });
+    return commitBytes(id, revision).pipe(Effect.flatMap((bytes) => {
+      const decoded = decodeCommit(bytes);
+      return Match.valueTags(tailVerdict(decoded, !repaired), {
+        Intact: () => Result.match(decoded, {
+          onFailure: () => Effect.fail(decodeError(`commit ${revision} of session ${id}`, "unreadable")),
+          onSuccess: (record) => Effect.succeed({ tail: tailOfRecord(record), meta: Option.some(record.meta) })
+        }),
+        Quarantine: ({ damage }) => quarantine(id, revision, bytes, damage).pipe(Effect.flatMap((outcome) => outcome === "aside" ? tailAt(id, header, revision - 1, !0) : tailAt(id, header, revision, repaired))),
+        Corrupt: ({ damage }) => Effect.fail(decodeError(`commit ${revision} of session ${id}`, `${damage}, below a torn tail`))
+      });
+    }));
+  }, remember = (id, headerNonce, tail, metas) => Ref.update(known, (all) => {
+    const before = Option.filter(Option.fromNullishOr(all.get(id)), (entry) => entry.nonce === headerNonce), kept = Option.match(before, { onNone: () => new Map, onSome: (entry) => new Map(entry.metas) });
+    Array.from(metas).forEach((meta) => kept.set(meta.revision, meta));
+    return cacheWith(all, id, { nonce: headerNonce, tail, metas: kept });
+  }), currentOnce = (id) => Effect.gen(function* () {
+    const header = yield* headerOf(id), before = Option.filter(Option.fromNullishOr((yield* Ref.get(known)).get(id)), (entry) => entry.nonce === header.nonce), start = yield* Option.match(before, {
+      onNone: () => listedRevision(id),
+      onSome: (entry) => entry.tail.revision === 0 ? Effect.succeed(0) : exists(commitPath(id, entry.tail.revision)).pipe(Effect.flatMap((still) => still ? Effect.succeed(entry.tail.revision) : listedRevision(id)))
+    }), revision = yield* probeForward(id, start), same = Option.filter(before, (entry) => entry.tail.revision === revision);
+    if (Option.isSome(same)) {
+      yield* Ref.update(known, (all) => cacheWith(all, id, same.value));
+      return { header, tail: same.value.tail };
+    }
+    const found = yield* tailAt(id, header, revision, !1);
+    yield* remember(id, header.nonce, found.tail, Option.toArray(found.meta));
+    return { header, tail: found.tail };
+  }), current = (id) => currentOnce(id).pipe(Effect.catchIf(vanished, () => currentOnce(id))), headOf = (header, tail, now) => ({
+    header: { ...header.header, meta: structuredClone(header.header.meta) },
+    incarnation: incarnationOf(header),
+    seq: tail.seq,
+    revision: tail.revision,
+    state: structuredClone(tail.state),
+    updatedAt: tail.at,
+    now
+  }), metaOfFile = (id, revision) => Effect.gen(function* () {
+    const start = yield* call("read", commitPath(id, revision), () => io.readStart(commitPath(id, revision), META_PREFIX)).pipe(Effect.catch(goneOr(id, "read a commit"))), text = decoder.decode(start), line = text.slice(0, Math.max(0, text.indexOf(`
+`)));
+    return yield* Option.match(metaOfLine(line), {
+      onSome: Effect.succeed,
+      onNone: () => wholeCommit(id, revision).pipe(Effect.map((record) => record.meta))
+    });
+  }), eventOf = (id, at) => (event) => ({
+    session: id,
+    seq: event.seq,
+    turn: Option.fromNullishOr(event.turn),
+    kind: event.kind,
+    at,
+    data: event.data
+  }), publish = (id, temporary, revision, ours) => call("link", commitPath(id, revision), () => io.link(temporary, commitPath(id, revision))).pipe(Effect.as({ _tag: "Published" }), Effect.catch((linkError) => call("read", commitPath(id, revision), () => io.read(commitPath(id, revision))).pipe(Effect.map((bytes) => Result.match(decodeCommit(bytes), {
+    onSuccess: (record) => record.meta.nonce === ours ? { _tag: "Published" } : { _tag: "Taken" },
+    onFailure: () => ({ _tag: "Taken" })
+  })), Effect.catchIf((error) => isCode(error, "ENOENT", "ENOTDIR"), () => exists(dirOf(id)).pipe(Effect.flatMap((there) => there ? Effect.fail(storeError("store.io", "publish a commit")(linkError)) : Effect.succeed({ _tag: "Missing" })))), Effect.mapError((error) => error._tag === "SessionLogError" ? error : storeError("store.io", "read a commit back")(error))))), sweepTemporaries = (id, revision) => Effect.gen(function* () {
+    if (!(yield* Ref.modify(swept, (done) => done.has(id) ? [!1, done] : [!0, done.size >= CACHE_BOUNDS.sessions ? new Set([id]) : new Set(done).add(id)])))
+      return;
+    const folder = join(dirOf(id), "tmp"), dead = (yield* call("list", folder, () => io.list(folder)).pipe(Effect.tapError((error) => Effect.logDebug(`the temporary files of a session could not be listed (${error._tag}); they are swept at a later commit`)), Effect.orElseSucceed(() => []))).filter((name) => Option.exists(revisionOfTemporary(name), (written) => written <= revision));
+    yield* Effect.forEach(dead, (name) => bestEffort("unlink", join(folder, name), () => io.unlink(join(folder, name))), { concurrency: 1, discard: !0 });
+  }), discard = (id) => Effect.gen(function* () {
+    const aside = join(root, "trash", `${id}.${randomUUID()}`), moved = yield* call("rename", dirOf(id), () => io.rename(dirOf(id), aside)).pipe(Effect.as(!0), Effect.catchIf((error) => isCode(error, "ENOENT"), () => Effect.succeed(!1)), Effect.mapError(storeError("store.io", "remove a session")));
+    yield* Ref.update(known, (all) => {
+      const rest = new Map(all);
+      rest.delete(id);
+      return rest;
+    });
+    if (moved)
+      yield* bestEffort("remove", aside, () => io.removeTree(aside));
+  }), childrenOf = (parent) => Effect.gen(function* () {
+    const names = yield* call("list", sessionsDir, () => io.list(sessionsDir)).pipe(Effect.mapError(storeError("store.io", "list the sessions")));
+    return (yield* Effect.forEach(names.flatMap((name) => Option.toArray(sessionIdOf(name))), (name) => headerOf(name).pipe(Effect.map(Option.some), Effect.catchTag("SessionMissing", () => Effect.succeedNone)), { concurrency: 2 })).flatMap((found) => Option.match(found, {
+      onNone: () => [],
+      onSome: (record) => Option.exists(record.header.parent, (lineage) => lineage.id === parent) ? [record.header.id] : []
+    }));
+  }), removeTree = (id) => Effect.gen(function* () {
+    yield* discard(id);
+    const children = yield* childrenOf(id);
+    yield* Effect.forEach(children, removeTree, { concurrency: 1, discard: !0 });
+  });
+  return SessionLog.of({
+    create: Effect.fn("session_log.create")(function* (header) {
+      const meta = yield* storedJson(header.meta).pipe(Effect.mapError((error) => new SessionLogError({ code: "store.encode", message: `the meta is not JSON: ${error.message}`, cause: error }))), parent = header.parent;
+      if (Option.isSome(parent) && !(yield* exists(headerPath(parent.value.id))))
+        return yield* Effect.fail(new SessionMissing({ session: parent.value.id }));
+      const now = yield* Clock.currentTimeMillis, record = { header: { ...header, meta }, createdNow: now, nonce: nonce() }, text = yield* Result.match(headerText(record), {
+        onFailure: (error) => Effect.fail(new SessionLogError({ code: "store.encode", message: `the header does not encode: ${error.message}`, cause: error })),
+        onSuccess: Effect.succeed
+      }), stagedDir = staged(header.id, now);
+      yield* Effect.forEach([join(stagedDir, "commits"), join(stagedDir, "tmp")], (path) => call("mkdir", path, () => io.mkdir(path)), { concurrency: 1, discard: !0 }).pipe(Effect.andThen(call("create", join(stagedDir, "header.json"), () => io.create(join(stagedDir, "header.json"), encoder.encode(text)))), Effect.mapError(storeError("store.io", "stage a new session")));
+      if ((yield* call("rename", dirOf(header.id), () => io.rename(stagedDir, dirOf(header.id))).pipe(Effect.as("created"), Effect.catch((renameError) => headerOf(header.id).pipe(Effect.map((found) => found.nonce === record.nonce ? "created" : "exists"), Effect.catchTag("SessionMissing", () => Effect.fail(storeError("store.io", "publish a new session")(renameError))))))) === "exists") {
+        yield* bestEffort("remove", stagedDir, () => io.removeTree(stagedDir));
+        return yield* Effect.fail(new SessionExists({ session: header.id }));
+      }
+      if (Option.isSome(parent) && !(yield* exists(headerPath(parent.value.id)))) {
+        yield* discard(header.id);
+        return yield* Effect.fail(new SessionMissing({ session: parent.value.id }));
+      }
+      const tail = { revision: 0, seq: 0, at: now, state: {} };
+      yield* remember(header.id, record.nonce, tail, []);
+      return headOf(record, tail, now);
+    }, (effect, header) => onSession(effect, header.id)),
+    head: Effect.fn("session_log.head")(function* (id) {
+      const { header, tail } = yield* current(id);
+      return headOf(header, tail, yield* Clock.currentTimeMillis);
+    }, onSession),
+    list: Effect.fn("session_log.list")(function* (query) {
+      const now = yield* Clock.currentTimeMillis, names = yield* call("list", sessionsDir, () => io.list(sessionsDir)).pipe(Effect.mapError(storeError("store.io", "list the sessions"))), heads = yield* Effect.forEach(names.flatMap((name) => Option.toArray(sessionIdOf(name))), (name) => headerOf(name).pipe(Effect.flatMap((record) => inListing(record, query) ? current(record.header.id).pipe(Effect.map(({ header, tail }) => Option.some(headOf(header, tail, now)))) : Effect.succeedNone), Effect.catchTag("SessionMissing", () => Effect.succeedNone)), { concurrency: 2 });
+      return page(heads.flatMap(Option.toArray), query);
+    }),
+    read: Effect.fn("session_log.read")(function* (id, query) {
+      const { header, tail } = yield* current(id), limit = Option.match(query.limit, { onNone: () => Number.POSITIVE_INFINITY, onSome: (value) => Math.max(0, value) }), wanted = (kind) => query.kinds.length === 0 || query.kinds.includes(kind), revisions = Array.from({ length: tail.revision }, (_, index) => index + 1), cached = Option.match(Option.filter(Option.fromNullishOr((yield* Ref.get(known)).get(id)), (entry) => entry.nonce === header.nonce), {
+        onNone: () => new Map,
+        onSome: (entry) => entry.metas
+      }), fresh = new Map, metaAt = (revision) => Option.match(Option.fromNullishOr(cached.get(revision)), {
+        onSome: (meta) => Effect.succeed(meta),
+        onNone: () => metaOfFile(id, revision).pipe(Effect.tap((meta) => Effect.sync(() => fresh.set(revision, meta))))
+      }), events = yield* Effect.reduce(revisions, () => [], (events, revision) => {
+        if (events.length >= limit)
+          return Effect.succeed(events);
+        return metaAt(revision).pipe(Effect.flatMap((meta) => meta.last <= query.after || query.through !== void 0 && meta.first > query.through || meta.first > meta.last || !meta.kinds.some(wanted) ? Effect.succeed(events) : wholeCommit(id, revision).pipe(Effect.map((record) => [
+          ...events,
+          ...record.events.filter((event) => event.seq > query.after && (query.through === void 0 || event.seq <= query.through) && wanted(event.kind)).map(eventOf(id, record.meta.at))
+        ].slice(0, limit)))));
+      });
+      if (fresh.size > 0)
+        yield* Ref.update(known, (all) => Option.match(Option.filter(Option.fromNullishOr(all.get(id)), (entry) => entry.nonce === header.nonce), {
+          onNone: () => all,
+          onSome: (entry) => cacheWith(all, id, { ...entry, metas: new Map([...entry.metas, ...fresh]) })
+        }));
+      return events;
+    }, onSession),
+    commit: Effect.fn("session_log.commit")(function* (id, commit) {
+      const data = yield* Effect.forEach(commit.events, (draft) => storedJson(draft.data).pipe(Effect.mapError((error) => new SessionLogError({ code: "store.encode", message: `the data is not JSON: ${error.message}`, cause: error }))), { concurrency: 1 }), { header, tail } = yield* current(id);
+      if (commit.incarnation !== void 0 && commit.incarnation !== incarnationOf(header))
+        return yield* Effect.fail(new SessionMissing({ session: id }));
+      if (tail.revision !== commit.expect)
+        return yield* Effect.fail(new RevisionConflict({ session: id, expected: commit.expect, actual: tail.revision }));
+      const at = yield* Clock.currentTimeMillis;
+      if (Option.isSome(commit.notAfter) && at > commit.notAfter.value)
+        return yield* Effect.fail(new LeaseExpired({ session: id, notAfter: commit.notAfter.value, now: at }));
+      const revision = tail.revision + 1, events = commit.events.map((draft, index) => ({
+        seq: tail.seq + index + 1,
+        turn: Option.getOrNull(draft.turn),
+        kind: draft.kind,
+        data: data[index] ?? {}
+      })), ours = nonce(), meta = {
+        layout: FILES_LAYOUT,
+        session: id,
+        revision,
+        first: tail.seq + 1,
+        last: tail.seq + events.length,
+        at,
+        kinds: [...new Set(events.map((event) => event.kind))],
+        nonce: ours
+      }, state = yield* Option.match(commit.state, {
+        onNone: () => Effect.succeed(tail.state),
+        onSome: (next) => storedJson(next).pipe(Effect.mapError((error) => new SessionLogError({ code: "store.encode", message: `the state is not JSON: ${error.message}`, cause: error })))
+      }), temporary = join(dirOf(id), "tmp", `${revisionFile(revision)}.${ours}`), published = yield* Effect.uninterruptible(Effect.gen(function* () {
+        if (!(yield* call("create", temporary, () => io.create(temporary, encodeCommit({ meta, state, events }))).pipe(Effect.as(!0), Effect.catchIf((error) => isCode(error, "ENOENT", "ENOTDIR"), () => Effect.succeed(!1)), Effect.mapError(storeError("store.io", "write a commit")))))
+          return { _tag: "Missing" };
+        if (!(yield* headerOf(id).pipe(Effect.map((found) => found.nonce === header.nonce), Effect.catchTag("SessionMissing", () => Effect.succeed(!1))))) {
+          yield* bestEffort("unlink", temporary, () => io.unlink(temporary));
+          return { _tag: "Replaced" };
+        }
+        const linking = yield* Clock.currentTimeMillis;
+        if (Option.isSome(commit.notAfter) && linking > commit.notAfter.value) {
+          yield* bestEffort("unlink", temporary, () => io.unlink(temporary));
+          return { _tag: "Expired", notAfter: commit.notAfter.value, now: linking };
+        }
+        const outcome = yield* publish(id, temporary, revision, ours);
+        yield* bestEffort("unlink", temporary, () => io.unlink(temporary));
+        if (outcome._tag === "Published")
+          yield* bestEffort("sync", commitsDir(id), () => io.syncDirectory(commitsDir(id)));
+        return outcome;
+      }));
+      return yield* Match.valueTags(published, {
+        Published: () => remember(id, header.nonce, { revision, seq: meta.last, at, state }, [meta]).pipe(Effect.andThen(sweepTemporaries(id, revision)), Effect.as({ revision, seq: meta.last, events: events.map(eventOf(id, at)), at })),
+        Taken: () => current(id).pipe(Effect.flatMap((after) => Effect.fail(new RevisionConflict({ session: id, expected: commit.expect, actual: after.tail.revision })))),
+        Missing: () => Effect.fail(new SessionMissing({ session: id })),
+        Expired: (expired) => Effect.fail(new LeaseExpired({ session: id, notAfter: expired.notAfter, now: expired.now })),
+        Replaced: () => commit.incarnation !== void 0 ? Effect.fail(new SessionMissing({ session: id })) : current(id).pipe(Effect.flatMap((after) => Effect.fail(new RevisionConflict({ session: id, expected: commit.expect, actual: after.tail.revision }))))
+      });
+    }, onSession),
+    remove: Effect.fn("session_log.remove")(function* (id) {
+      yield* removeTree(id);
+    }, onSession)
+  });
+}), SessionLogFilesLive = (root, options) => Layer.effect(SessionLog, makeSessionLogFiles(root, options));

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@xandreed/plugin-session-files",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.15.1",
+  "engines": {
+    "node": ">=24",
+    "bun": ">=1.3.0"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {},
+  "private": false,
+  "types": "./dist/index.d.ts",
+  "peerDependencies": {
+    "@xandreed/core": "^0.15.1",
+    "effect": "^4.0.7"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "profiles",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT"
+}