@namzu/sdk 42.0.2 → 44.0.0

package/dist/store/session-log/chain.d.ts

@@ -0,0 +1,111 @@
+import type { SessionId } from '../../types/ids/index.js';
+import { type RecordPointer, type SessionRecord } from '../../types/session/records.js';
+/**
+ * The hash chain of one session log.
+ *
+ * Every record names its predecessor by `prev`: seq, byte offset, byte length
+ * (newline included) and the SHA-256 of exactly those bytes. Verifying a log
+ * is walking it line by line and checking that each `prev` is the pointer of
+ * the line before it. Moved here from `store/evidence/record-chain.ts`, whose
+ * predecessor and text-link rules it keeps, under the session envelope's
+ * names (`prev`, `prevText`).
+ *
+ * The rules:
+ *
+ * - Seq 1 is `session_started`, at offset 0, with `prev: null`.
+ * - Every later record has `seq = previous seq + 1` and a `prev` equal, field
+ *   by field, to the previous line's pointer. A flipped byte in any line
+ *   changes that line's hash, so the NEXT record's `prev` no longer matches.
+ * - Every record names the same session as the first.
+ * - `gen` never decreases: a record written under an older lease after one
+ *   written under a newer lease is a split writer, not a log.
+ * - `prevText`, when present, is a skip link to an earlier text-bearing
+ *   record: `null` only where `prev` is `null`, otherwise strictly before the
+ *   record, and equal to `prev` when it names the same seq.
+ *
+ * The last record has no successor to vouch for it. A reader that needs the
+ * tail anchored passes the head it expects (an index row, a checkpoint's
+ * `throughSha256`) and the read refuses a log that does not hold it.
+ */
+/** One record of a log, with the pointer to its own bytes. */
+export interface SessionLogEntry {
+    readonly record: SessionRecord;
+    readonly pointer: RecordPointer;
+}
+export type SessionLogBreakReason = 'not-a-record' | 'bad-start' | 'seq-gap' | 'prev-mismatch' | 'session-mismatch' | 'gen-regressed' | 'bad-text-link' | 'anchor-mismatch';
+/** A log that is not an unbroken chain. `seq` and `offset` name where the break is. */
+export declare class SessionLogIntegrityError extends Error {
+    readonly reason: SessionLogBreakReason;
+    /** The seq the reader expected at the break. */
+    readonly seq: number;
+    /** Byte offset of the line that broke the chain. */
+    readonly offset: number;
+    readonly name = "SessionLogIntegrityError";
+    constructor(reason: SessionLogBreakReason, 
+    /** The seq the reader expected at the break. */
+    seq: number, 
+    /** Byte offset of the line that broke the chain. */
+    offset: number, message: string, options?: ErrorOptions);
+}
+/** Where a chain walk starts: the beginning of the log, or just after a known record. */
+export interface ChainStart {
+    /** The last verified record; `null` (the default) starts at offset 0. */
+    readonly head: RecordPointer | null;
+    /** The session every record must name; learnt from seq 1 when omitted. */
+    readonly sessionId?: SessionId;
+    /** The `gen` of the record at `head`. */
+    readonly gen?: number;
+}
+/**
+ * Verifies a log one line at a time. Throws {@link SessionLogIntegrityError}
+ * at the first line that breaks the chain; the state is then unchanged, so a
+ * tolerant reader can stop there with everything before it intact.
+ */
+export declare class SessionLogChain {
+    #private;
+    constructor(start?: ChainStart);
+    get head(): RecordPointer | null;
+    get sessionId(): SessionId | undefined;
+    get gen(): number;
+    /** The byte offset the next line must start at. */
+    get end(): number;
+    /** Verify one complete line (newline included) found at `offset`. */
+    accept(line: Uint8Array, offset: number): SessionLogEntry;
+}
+/**
+ * Splits a byte stream into complete lines, carrying a partial line across
+ * chunks. Whatever is left at the end with no newline is the torn tail.
+ */
+export declare class LineSplitter {
+    #private;
+    constructor(startOffset?: number);
+    /** Bytes held after the last complete line. */
+    get pendingBytes(): number;
+    push(chunk: Uint8Array): Generator<{
+        line: Uint8Array;
+        offset: number;
+    }>;
+}
+/** Random access to a log's bytes, as both backends provide it. */
+export interface LogBytes {
+    size(): Promise<number>;
+    read(offset: number, length: number): Promise<Uint8Array>;
+}
+/**
+ * The last complete record of a log, read from its tail only: never the whole
+ * log. Salvaged from `transcriptTail`. Returns `undefined` for an empty log,
+ * or when the tail is torn or does not parse — the caller then scans.
+ *
+ * Unverified: the record's own `prev` is not checked against the line before
+ * it. It bootstraps a head cheaply; a writer re-verifies before appending.
+ */
+export declare function readSessionLogTail(bytes: LogBytes): Promise<{
+    entry: SessionLogEntry;
+    size: number;
+} | undefined>;
+/**
+ * Check that the bytes at `pointer` are exactly the record it names. Used to
+ * resume a walk from a cursor, and to anchor a tail.
+ */
+export declare function verifyPointer(bytes: LogBytes, pointer: RecordPointer): Promise<boolean>;
+//# sourceMappingURL=chain.d.ts.map

package/dist/store/session-log/chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.d.ts","sourceRoot":"","sources":["../../../src/store/session-log/chain.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AACzD,OAAO,EACN,KAAK,aAAa,EAElB,KAAK,aAAa,EAClB,MAAM,gCAAgC,CAAA;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,8DAA8D;AAC9D,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;CAC/B;AAED,MAAM,MAAM,qBAAqB,GAC9B,cAAc,GACd,WAAW,GACX,SAAS,GACT,eAAe,GACf,kBAAkB,GAClB,eAAe,GACf,eAAe,GACf,iBAAiB,CAAA;AAEpB,uFAAuF;AACvF,qBAAa,wBAAyB,SAAQ,KAAK;IAGjD,QAAQ,CAAC,MAAM,EAAE,qBAAqB;IACtC,gDAAgD;IAChD,QAAQ,CAAC,GAAG,EAAE,MAAM;IACpB,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM;IANxB,SAAkB,IAAI,8BAA6B;gBAEzC,MAAM,EAAE,qBAAqB;IACtC,gDAAgD;IACvC,GAAG,EAAE,MAAM;IACpB,oDAAoD;IAC3C,MAAM,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY;CAIvB;AAOD,yFAAyF;AACzF,MAAM,WAAW,UAAU;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAAA;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAA;IAC9B,yCAAyC;IACzC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;GAIG;AACH,qBAAa,eAAe;;gBAKf,KAAK,GAAE,UAA2B;IAM9C,IAAI,IAAI,IAAI,aAAa,GAAG,IAAI,CAE/B;IAED,IAAI,SAAS,IAAI,SAAS,GAAG,SAAS,CAErC;IAED,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED,mDAAmD;IACnD,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED,qEAAqE;IACrE,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,eAAe;CAiEzD;AA2BD;;;GAGG;AACH,qBAAa,YAAY;;gBAKZ,WAAW,SAAI;IAI3B,+CAA+C;IAC/C,IAAI,YAAY,IAAI,MAAM,CAEzB;IAEA,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CAAC;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CA+BzE;AAED,mEAAmE;AACnE,MAAM,WAAW,QAAQ;IACxB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;IACvB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;CACzD;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACvC,KAAK,EAAE,QAAQ,GACb,OAAO,CAAC;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC,CA0B/D;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CAK7F"}

package/dist/store/session-log/chain.js

@@ -0,0 +1,212 @@
+import { SessionLogLineError, parseSessionLogLine, recordSha256 } from '../../session/log-hash.js';
+import { SESSION_RECORD_MAX_BYTES, } from '../../types/session/records.js';
+/** A log that is not an unbroken chain. `seq` and `offset` name where the break is. */
+export class SessionLogIntegrityError extends Error {
+    reason;
+    seq;
+    offset;
+    name = 'SessionLogIntegrityError';
+    constructor(reason, 
+    /** The seq the reader expected at the break. */
+    seq, 
+    /** Byte offset of the line that broke the chain. */
+    offset, message, options) {
+        super(message, options);
+        this.reason = reason;
+        this.seq = seq;
+        this.offset = offset;
+    }
+}
+function samePointer(a, b) {
+    if (a === null || a === undefined || b === null)
+        return a === b;
+    return a.seq === b.seq && a.offset === b.offset && a.length === b.length && a.sha256 === b.sha256;
+}
+/**
+ * Verifies a log one line at a time. Throws {@link SessionLogIntegrityError}
+ * at the first line that breaks the chain; the state is then unchanged, so a
+ * tolerant reader can stop there with everything before it intact.
+ */
+export class SessionLogChain {
+    #head;
+    #sessionId;
+    #gen;
+    constructor(start = { head: null }) {
+        this.#head = start.head;
+        this.#sessionId = start.sessionId;
+        this.#gen = start.gen ?? 0;
+    }
+    get head() {
+        return this.#head;
+    }
+    get sessionId() {
+        return this.#sessionId;
+    }
+    get gen() {
+        return this.#gen;
+    }
+    /** The byte offset the next line must start at. */
+    get end() {
+        return this.#head === null ? 0 : this.#head.offset + this.#head.length;
+    }
+    /** Verify one complete line (newline included) found at `offset`. */
+    accept(line, offset) {
+        const expectedSeq = (this.#head?.seq ?? 0) + 1;
+        const fail = (reason, message, cause) => {
+            throw new SessionLogIntegrityError(reason, expectedSeq, offset, `Session log breaks at seq ${expectedSeq} (byte ${offset}): ${message}`, cause === undefined ? undefined : { cause });
+        };
+        if (offset !== this.end) {
+            fail('seq-gap', `the line starts at byte ${offset}, not at ${this.end} where the last one ended`);
+        }
+        let parsed;
+        try {
+            parsed = parseSessionLogLine(line);
+        }
+        catch (error) {
+            return fail('not-a-record', error instanceof SessionLogLineError ? error.message : String(error), error);
+        }
+        const { record } = parsed;
+        const pointer = {
+            seq: record.seq,
+            offset,
+            length: parsed.length,
+            sha256: parsed.sha256,
+        };
+        if (this.#head === null) {
+            if (offset !== 0 || record.seq !== 1 || record.type !== 'session_started') {
+                fail('bad-start', 'a session log starts with session_started at seq 1, offset 0');
+            }
+        }
+        else {
+            if (record.seq !== expectedSeq)
+                fail('seq-gap', `the record says seq ${record.seq}`);
+            if (!samePointer(record.prev, this.#head)) {
+                fail('prev-mismatch', 'its prev pointer does not name the bytes of the record before it (that record, or this pointer, was altered)');
+            }
+        }
+        if (this.#sessionId !== undefined && record.sessionId !== this.#sessionId) {
+            fail('session-mismatch', `the record names session ${record.sessionId}, not ${this.#sessionId}`);
+        }
+        if (record.gen < this.#gen) {
+            fail('gen-regressed', `gen ${record.gen} follows gen ${this.#gen}: a writer whose lease had been superseded appended after its successor`);
+        }
+        checkTextLink(record, pointer, fail);
+        this.#head = pointer;
+        this.#sessionId ??= record.sessionId;
+        this.#gen = record.gen;
+        return { record, pointer };
+    }
+}
+/**
+ * The text-link rules, salvaged from `recordPredecessors`: a skip link may
+ * pass over operational records, but never past the start of the log and
+ * never forward.
+ */
+function checkTextLink(record, pointer, fail) {
+    if (!Object.hasOwn(record, 'prevText'))
+        return;
+    const next = record.prevText ?? null;
+    const previous = record.prev;
+    if ((next === null && previous !== null) ||
+        (next !== null &&
+            (previous === null ||
+                next.seq >= pointer.seq ||
+                next.offset + next.length > pointer.offset ||
+                (next.seq === previous.seq && !samePointer(next, previous))))) {
+        fail('bad-text-link', 'its prevText skip link does not name an earlier record');
+    }
+}
+/**
+ * Splits a byte stream into complete lines, carrying a partial line across
+ * chunks. Whatever is left at the end with no newline is the torn tail.
+ */
+export class LineSplitter {
+    #pending = [];
+    #pendingBytes = 0;
+    #offset = 0;
+    constructor(startOffset = 0) {
+        this.#offset = startOffset;
+    }
+    /** Bytes held after the last complete line. */
+    get pendingBytes() {
+        return this.#pendingBytes;
+    }
+    *push(chunk) {
+        let start = 0;
+        for (;;) {
+            const newline = chunk.indexOf(0x0a, start);
+            if (newline === -1)
+                break;
+            let line = chunk.subarray(start, newline + 1);
+            if (this.#pendingBytes > 0) {
+                line = Buffer.concat([...this.#pending, line]);
+                this.#pending = [];
+                this.#pendingBytes = 0;
+            }
+            yield { line, offset: this.#offset };
+            this.#offset += line.byteLength;
+            start = newline + 1;
+        }
+        if (start < chunk.byteLength) {
+            // Copied: the caller may reuse the chunk's buffer for its next read.
+            const rest = Uint8Array.prototype.slice.call(chunk, start);
+            this.#pending.push(rest);
+            this.#pendingBytes += rest.byteLength;
+            if (this.#pendingBytes > SESSION_RECORD_MAX_BYTES) {
+                // A fragment longer than any record can be is not a line in progress.
+                throw new SessionLogIntegrityError('not-a-record', 0, this.#offset, `Session log holds ${this.#pendingBytes} bytes at byte ${this.#offset} without a newline; no record is that long.`);
+            }
+        }
+    }
+}
+/**
+ * The last complete record of a log, read from its tail only: never the whole
+ * log. Salvaged from `transcriptTail`. Returns `undefined` for an empty log,
+ * or when the tail is torn or does not parse — the caller then scans.
+ *
+ * Unverified: the record's own `prev` is not checked against the line before
+ * it. It bootstraps a head cheaply; a writer re-verifies before appending.
+ */
+export async function readSessionLogTail(bytes) {
+    const size = await bytes.size();
+    if (size === 0)
+        return undefined;
+    const offset = Math.max(0, size - SESSION_RECORD_MAX_BYTES - 1);
+    const tail = await bytes.read(offset, size - offset);
+    if (tail.at(-1) !== 0x0a)
+        return undefined;
+    const start = tail.lastIndexOf(0x0a, tail.byteLength - 2) + 1;
+    if (start === 0 && offset !== 0)
+        return undefined;
+    const raw = tail.subarray(start);
+    try {
+        const parsed = parseSessionLogLine(raw);
+        return {
+            entry: {
+                record: parsed.record,
+                pointer: {
+                    seq: parsed.record.seq,
+                    offset: offset + start,
+                    length: parsed.length,
+                    sha256: parsed.sha256,
+                },
+            },
+            size,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Check that the bytes at `pointer` are exactly the record it names. Used to
+ * resume a walk from a cursor, and to anchor a tail.
+ */
+export async function verifyPointer(bytes, pointer) {
+    const size = await bytes.size();
+    if (pointer.offset + pointer.length > size)
+        return false;
+    const raw = await bytes.read(pointer.offset, pointer.length);
+    return raw.byteLength === pointer.length && recordSha256(raw) === pointer.sha256;
+}
+//# sourceMappingURL=chain.js.map

package/dist/store/session-log/chain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.js","sourceRoot":"","sources":["../../../src/store/session-log/chain.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,61 @@
+/**
+ * The session-log contract, as a suite a host runs against its own backend.
+ *
+ * A custom log (a database, an object store) is re-implemented against the
+ * `SessionLog` interface and proved against this file. It holds the rules no
+ * type can state: the chain verifies, a superseded lease cannot write, a
+ * live lease is renewed only by the instance holding it (late or not), one
+ * turn is active at a time and its state is `running`, `paused` or
+ * `interrupted`, the fold applies compactions and replacements, a large body
+ * spills and reads back, a torn tail is repaired on the record, and a flipped
+ * byte is refused.
+ *
+ * Like `store/run/conformance.ts`, which it replaces, it takes `describe`,
+ * `it` and `expect` as arguments: the SDK gains no test dependency, and a
+ * caller can pass recording functions to run the suite as ordinary code
+ * (which is how `conformance-fails-a-wrong-log.test.ts` shows a broken log
+ * fails it).
+ *
+ * The assertions are public API: adding or tightening one raises
+ * {@link SESSION_LOG_CONTRACT_VERSION} and ships in a major.
+ */
+import type { SessionId } from '../../types/ids/index.js';
+import type { SessionLog } from './core.js';
+/** The contract revision these assertions express. A host declares the one it wrote against, as a literal. */
+export declare const SESSION_LOG_CONTRACT_VERSION = 1;
+/** Raw access to a backend's bytes, for the integrity cases. Omit it and those cases are skipped. */
+export interface SessionLogTamper {
+    /** The log's bytes as stored. */
+    bytes(): Promise<Uint8Array>;
+    /** Replace the stored bytes wholesale. */
+    overwrite(bytes: Uint8Array): Promise<void>;
+}
+/** A log to test, over fresh storage. */
+export interface SessionLogHandle {
+    readonly log: SessionLog;
+    /** A second instance over the same storage, as another process would open it. */
+    reopen(): SessionLog;
+    readonly tamper?: SessionLogTamper;
+    dispose?(): void | Promise<void>;
+}
+export type MakeSessionLog = (sessionId: SessionId) => SessionLogHandle | Promise<SessionLogHandle>;
+/** The assertions the suite uses, and nothing more. */
+export interface SessionLogAssertion {
+    toBe(expected: unknown): void;
+    toEqual(expected: unknown): void;
+    toBeGreaterThan(expected: number): void;
+    toMatch(expected: RegExp): void;
+}
+export interface SessionLogConformanceOptions {
+    readonly describe: (name: string, body: () => void) => unknown;
+    readonly it: (name: string, body: () => Promise<void>) => unknown;
+    readonly expect: (actual: unknown) => SessionLogAssertion;
+    /** The contract revision the backend was written against, as a literal. */
+    readonly contractVersion: number;
+    readonly makeLog: MakeSessionLog;
+    /** Names the backend in test output. */
+    readonly label?: string;
+}
+/** Register the session-log contract against `options.makeLog`. */
+export declare function defineSessionLogConformance(options: SessionLogConformanceOptions): void;
+//# sourceMappingURL=conformance.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../../../src/store/session-log/conformance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAa,SAAS,EAAU,MAAM,0BAA0B,CAAA;AAS5E,OAAO,KAAK,EAAE,UAAU,EAAsB,MAAM,WAAW,CAAA;AAG/D,8GAA8G;AAC9G,eAAO,MAAM,4BAA4B,IAAI,CAAA;AAE7C,qGAAqG;AACrG,MAAM,WAAW,gBAAgB;IAChC,iCAAiC;IACjC,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAAA;IAC5B,0CAA0C;IAC1C,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3C;AAED,yCAAyC;AACzC,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAA;IACxB,iFAAiF;IACjF,MAAM,IAAI,UAAU,CAAA;IACpB,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAA;IAClC,OAAO,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAChC;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,SAAS,EAAE,SAAS,KAAK,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;AAEnG,uDAAuD;AACvD,MAAM,WAAW,mBAAmB;IACnC,IAAI,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAA;IAC7B,OAAO,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAA;IAChC,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvC,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AAED,MAAM,WAAW,4BAA4B;IAC5C,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,KAAK,OAAO,CAAA;IAC9D,QAAQ,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,OAAO,CAAA;IACjE,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,mBAAmB,CAAA;IACzD,2EAA2E;IAC3E,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;IAChC,wCAAwC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACvB;AAiFD,mEAAmE;AACnE,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,4BAA4B,GAAG,IAAI,CA2UvF"}