@vincemakes/kiso-runtime 0.1.0

package/dist/store.d.ts

@@ -0,0 +1,111 @@
+/**
+ * SessionStore — append-only JSONL durability, identity-safe (A 组).
+ *
+ * One file per session: `<root>/<id>.jsonl`, lines of
+ * `{"runId": string, "ts": number, "event": Event}`. The single-writer
+ * lock (第四轮) is an EXCLUSIVE KERNEL flock on `<id>.lock`, held by a
+ * dedicated helper process:
+ *
+ * - the kernel arbitrates every race — a contender can never remove or
+ *   overwrite a live holder's lock, because there is nothing to remove;
+ *   the lock simply exists while the helper lives and vanishes with it;
+ * - the lock file ALSO carries `{"pid": number, "token": string}` written
+ *   by the holder, as a best-effort guard for OLD-format writers (whose
+ *   O_EXCL pidfile scheme does not honor flock). 第五轮(P1-4): this guard
+ *   is NOT a seamless rolling upgrade — an old writer that created an
+ *   empty lock file before writing its pid creates a split-brain window
+ *   that a pidfile read cannot close. The documented upgrade contract is
+ *   QUARANTINE: stop every old-format process, THEN start the new
+ *   version. A dead/empty/unreadable legacy lock is otherwise harmless —
+ *   flock ignores content, and the kernel lock is what matters;
+ * - `close()` releases only THIS instance's helper; `closeAll()` every
+ *   held helper — a foreign close can never release another writer's
+ *   kernel lock (flock is tied to the helper's open file description).
+ *
+ * Consistency contract (A 组):
+ * - every id is validated BEFORE any file side effect (append, close,
+ *   load, lock paths);
+ * - append runs an expected-last-seq CAS against the file's REAL last
+ *   committed seq: a stale preloaded handle writing a duplicate seq is
+ *   refused with StaleWriterError — and the run that fed it terminates,
+ *   so the in-memory EventLog never continues past a rejected write;
+ * - the torn tail is repaired before EVERY append, and committed records
+ *   (newline-terminated) are never truncated;
+ * - load is strict (A 组 round 1): a partial final line is the only
+ *   tolerated damage; everything else throws StoreCorruptionError.
+ */
+import { type Event } from "@vincemakes/kiso-core";
+/** History that does not parse as a contiguous kiso trajectory. */
+export declare class StoreCorruptionError extends Error {
+    constructor(message: string);
+}
+/** A write that would duplicate or skip a seq — the handle is stale. */
+export declare class StaleWriterError extends Error {
+    constructor(expected: number, got: number);
+}
+/** A durable record: the run that produced it, and the event itself. */
+export interface StoreRecord {
+    readonly runId: string;
+    readonly ts: number;
+    readonly event: Event;
+}
+export interface SessionMeta {
+    readonly id: string;
+    readonly title: string;
+    readonly events: number;
+    readonly runs: number;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+export declare class SessionStore {
+    #private;
+    readonly root: string;
+    constructor(root: string);
+    private pathFor;
+    private lockPathFor;
+    /**
+     * Take the single-writer lock (第四轮): an EXCLUSIVE kernel flock held
+     * by a dedicated helper process. The KERNEL arbitrates every race —
+     * there is no stale lock to delete and no takeover to race: a
+     * contender either gets the flock (the previous holder is gone) or it
+     * fails. The lock file also carries the holder's identity so an OLD-format
+     * writer (which does not honor flock) still sees a live owner and
+     * refuses to take over — a best-effort guard, NOT a seamless rolling
+     * upgrade (第五轮 P1-4): the documented upgrade contract is quarantine —
+     * stop every old-format process, then start the new version.
+     * No recursion, no deletion, no window between NEW-format writers.
+     */
+    private acquireLock;
+    /** 第五轮(P1-2): true only while the helper process is alive. */
+    private lockHeld;
+    /**
+     * Release OUR lock only: kill OUR helper. The kernel releases the
+     * flock with the helper's death; the identity file is CLEARED so a
+     * same-process successor is never mistaken for a live legacy owner —
+     * the flock is the authority, the file is advisory (第四轮).
+     */
+    private releaseLock;
+    /** Write-ahead: durable (written + fsynced) before returning. */
+    append(sessionId: string, runId: string, event: Event): Promise<void>;
+    /**
+     * Open (creating if needed) the session file. The torn tail is repaired
+     * here AND before every append — an in-process append failure cannot
+     * poison the next one. The parent directory is fsynced so the file's
+     * existence survives a crash.
+     */
+    private fd;
+    /**
+     * Replay a session's log. The ONLY tolerated damage is a partial final
+     * line (a crash mid-write): it is dropped and the contiguous prefix is
+     * returned. Anything else — mid-file garbage, valid JSON that is not a
+     * kiso record, a seq that is not 0..N — throws StoreCorruptionError.
+     */
+    load(sessionId: string): StoreRecord[];
+    has(sessionId: string): boolean;
+    list(): SessionMeta[];
+    /** Release a session's fd and OUR writer lock. Idempotent. */
+    close(sessionId: string): void;
+    /** Release every held fd and lock, including locks whose JSONL open failed. */
+    closeAll(): void;
+}
+export type { Event };