@metaharness/kernel 0.1.2 → 0.1.4

package/README.md

@@ -9,7 +9,7 @@ A Rust kernel compiled to two npm-shippable targets:
 - **WebAssembly** (primary distribution — runs on Node, browser, Cloudflare Workers, Deno, Bun, edge)
 - **NAPI-RS native** (per-platform `.node` binaries — escape hatch for Node hot paths)
 
-At load time, `loadKernel()` prefers the per-platform native package; falls back to wasm.
+At load time, `loadKernel()` prefers an installed per-platform native package, then wasm, then the dependency-free JavaScript backend.
 
 ## Install
 
@@ -17,7 +17,7 @@ At load time, `loadKernel()` prefers the per-platform native package; falls back
 npm install @metaharness/kernel
 ```
 
-The native packages (`@metaharness/kernel-darwin-arm64`, `-linux-x64-gnu`, etc.) are declared as `optionalDependencies` — npm installs only the one for your platform.
+The native packages (`@metaharness/kernel-darwin-arm64`, `-linux-x64-gnu`, etc.) are optional peers. They are not yet available from the public npm registry (checked 2026-10-27), so they are not installed automatically. The native loader still discovers a compatible package when explicitly installed; otherwise wasm or JavaScript is used. Restore automatic native installation only after the platform packages are published and clean npm 10/11 installs are verified. This source change does not alter already-published kernel versions.
 
 ## Usage
 

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export type { McpServerSpec, ToolSpec, AgentSpec, HookSpec, HarnessSpec, HostAdapter } from './types.js';
+export { SessionLog } from './session.js';
+export type { SessionEvent } from './session.js';
 export interface KernelInfo {
     version: string;
     git_sha: string;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzG,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,aAAa;IACrB,UAAU,IAAI,UAAU,CAAC;IACzB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC7C,OAAO,IAAI,MAAM,CAAC;IAClB,OAAO,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAAC;CACnC;AAuHD;;;GAGG;AACH;gFACgF;AAChF,wBAAgB,yBAAyB,IAAI,IAAI,CAIhD;AAED,wBAAsB,UAAU,IAAI,OAAO,CAAC,aAAa,CAAC,CAwCzD;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAAC;IACnC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAIpE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGzG,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,aAAa;IACrB,UAAU,IAAI,UAAU,CAAC;IACzB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC7C,OAAO,IAAI,MAAM,CAAC;IAClB,OAAO,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAAC;CACnC;AAuHD;;;GAGG;AACH;gFACgF;AAChF,wBAAgB,yBAAyB,IAAI,IAAI,CAIhD;AAED,wBAAsB,UAAU,IAAI,OAAO,CAAC,aAAa,CAAC,CAwCzD;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAAC;IACnC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAIpE"}

package/dist/index.js

@@ -9,6 +9,8 @@
 // third backend: a dependency-free pure-JS implementation. native > wasm > js,
 // but js is the floor — the kernel is always loadable. (ADR-002a §fallback.)
 import { createRequire } from 'node:module';
+// ADR-246 §2.3: recoverable, forkable session log primitive.
+export { SessionLog } from './session.js';
 let _cached = null;
 // GH #20/#22: remember WHY a higher-tier backend was unavailable so `doctor`
 // and a requested-but-missing backend can report the actual reason instead of

package/dist/index.js.map

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

package/dist/session.d.ts

@@ -0,0 +1,87 @@
+export interface SessionEvent {
+    /** Per-branch 0-based monotonic index. */
+    index: number;
+    /** Branch ID this event belongs to. */
+    branch: string;
+    /** Fork point — present only on the first event of a non-root branch. */
+    parent?: {
+        branch: string;
+        index: number;
+    };
+    /** Event kind (free-form discriminator, e.g. "turn", "tool", "note"). */
+    kind: string;
+    /** Free-form event payload. */
+    payload: unknown;
+}
+/** Canonical JSON: recursively key-sorted objects, arrays in order, no
+ * whitespace. `undefined` object values are dropped (matching
+ * JSON.stringify). This is the byte input to the state-hash fold.
+ *
+ * Keys sort by UTF-8 BYTE order (not UTF-16 code-unit order, which the
+ * default `.sort()` would use) to match the Rust mirror, whose `&str`
+ * ordering is byte-wise. The two orders diverge for keys mixing BMP-high
+ * characters (>= U+E000) with astral characters. */
+export declare function canonicalJson(v: unknown): string;
+/**
+ * Crash-recoverable, forkable session log (ADR-246 §2.3). One JSONL file may
+ * carry many branches; each SessionLog instance appends to ONE active branch.
+ * `fork()` returns a sibling over the same file/state on a new branch.
+ */
+export declare class SessionLog {
+    private state;
+    /** Active branch this instance appends to. */
+    readonly branch: string;
+    constructor(path: string, branch?: string);
+    /** Internal: build an instance over existing shared state (open/fork). */
+    private static over;
+    get path(): string;
+    /**
+     * Resume a session: read the JSONL log, validate it, and reconstruct state.
+     * Throws with the first 'session: '-prefixed error on an invalid log.
+     * `branch` selects the active branch (default 'main').
+     */
+    static open(path: string, branch?: string): Promise<SessionLog>;
+    /** Append an event on the active branch, assigning the next monotonic
+     * index. The first event of a forked branch carries the fork's parent ref.
+     * Safe to call without awaiting the previous call: concurrent appends on
+     * this instance (or a fork() sibling sharing this state) are serialized
+     * via `enqueue` and assigned distinct, monotonic indices in call order. */
+    append(kind: string, payload: unknown, opts?: {
+        parent?: {
+            branch: string;
+            index: number;
+        };
+    }): Promise<SessionEvent>;
+    /** The unserialized body of `append()` — only ever runs for one caller at
+     * a time per `LogState`, via `enqueue`. Not called directly outside this
+     * file; `fork()` also runs its own synthetic first event through this. */
+    private appendLocked;
+    /**
+     * Fork at `atIndex` on THIS instance's active branch: returns a SessionLog
+     * over the same file (and shared state) whose active branch is `newBranch`.
+     * Immediately appends the new branch's synthetic first event (matching the
+     * Rust mirror's `fork`): index 0, parent {branch: this.branch, index:
+     * atIndex}, kind 'fork', payload null.
+     */
+    fork(atIndex: number, newBranch: string): Promise<SessionLog>;
+    /** The lineage of a branch, root → tip: the branch's own events preceded by
+     * its parent lineage truncated at the fork point, recursively. */
+    private lineage;
+    /**
+     * State hash over the branch lineage (root → tip). Exact fold (mirrored in
+     * the file-header comment; a Rust mirror must reproduce it):
+     *     hexPrev = ''; for each event: hexPrev = hex(sha256(utf8(hexPrev + canonicalJson(event))))
+     * Returns lowercase hex; the hash of an empty lineage is ''.
+     */
+    stateHash(branch?: string): string;
+    /** Deterministic replay of a branch lineage: event count + state hash. */
+    replay(branch?: string): {
+        eventCount: number;
+        stateHash: string;
+    };
+    /** Re-read the file from disk and report every validation error
+     * ('session: '-prefixed, corrupted lines cited by 1-based line number).
+     * An empty array means the on-disk log is valid. */
+    validate(): Promise<string[]>;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAmCA,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,MAAM,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;oDAOoD;AACpD,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAQhD;AAkLD;;;;GAIG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAW;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,IAAI,EAAE,MAAM,EAAE,MAAM,SAAS;IAYzC,0EAA0E;IAC1E,OAAO,CAAC,MAAM,CAAC,IAAI;IAMnB,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;OAIG;WACU,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;IASrE;;;;+EAI2E;IACrE,MAAM,CACV,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GACpD,OAAO,CAAC,YAAY,CAAC;IAIxB;;8EAE0E;YAC5D,YAAY;IAkC1B;;;;;;OAMG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAsBnE;sEACkE;IAClE,OAAO,CAAC,OAAO;IAYf;;;;;OAKG;IACH,SAAS,CAAC,MAAM,GAAE,MAAoB,GAAG,MAAM;IAU/C,0EAA0E;IAC1E,MAAM,CAAC,MAAM,GAAE,MAAoB,GAAG;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;IAI/E;;wDAEoD;IAC9C,QAAQ,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;CAKpC"}

package/dist/session.js

@@ -0,0 +1,345 @@
+// SPDX-License-Identifier: MIT
+//
+// Recoverable session log — ADR-246 §2.3.
+//
+// Append-only JSONL event log per session: every event carries a per-branch
+// monotonic index and (for the first event of a forked branch) a parent
+// reference {branch, index}. Replaying the log reconstructs session state
+// deterministically; a state hash over the replayed lineage verifies
+// integrity. Fork creates a new branch ID referencing a parent event index;
+// branches replay independently (Prime Agent's /tree capability, minus the
+// daemon — daemons, socket attach/detach, and kernel snapshots are
+// deliberately out of scope per the ADR).
+//
+// Serialization contract (a Rust mirror must reproduce it byte-for-byte):
+// each event is one line, JSON.stringify of an object literal built in
+// EXACT key order
+//     index, branch, parent, kind, payload
+// with `parent` (itself in key order branch, index) omitted entirely when
+// absent.
+//
+// State-hash fold (a Rust mirror must reproduce it byte-for-byte):
+//     hexPrev := ''                                  // empty string seed, NOT a digest
+//     for each event e in lineage order (root → tip):
+//         canonical := canonicalJson(e)              // recursively key-sorted JSON of the event
+//         hexPrev   := lowercaseHex(sha256(utf8(hexPrev + canonical)))
+//     stateHash := hexPrev
+// i.e. digest_i = sha256(hex(digest_{i-1}) + canonicalJson(event_i)) as UTF-8,
+// where hex(digest_0) is the empty string for the first event, and every
+// digest is rendered as lowercase hex before being folded into the next step.
+import { appendFile, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { Buffer } from 'node:buffer';
+/** Canonical JSON: recursively key-sorted objects, arrays in order, no
+ * whitespace. `undefined` object values are dropped (matching
+ * JSON.stringify). This is the byte input to the state-hash fold.
+ *
+ * Keys sort by UTF-8 BYTE order (not UTF-16 code-unit order, which the
+ * default `.sort()` would use) to match the Rust mirror, whose `&str`
+ * ordering is byte-wise. The two orders diverge for keys mixing BMP-high
+ * characters (>= U+E000) with astral characters. */
+export function canonicalJson(v) {
+    if (v === null || typeof v !== 'object')
+        return JSON.stringify(v) ?? 'null';
+    if (Array.isArray(v))
+        return '[' + v.map(x => canonicalJson(x)).join(',') + ']';
+    const rec = v;
+    const keys = Object.keys(rec)
+        .filter(k => rec[k] !== undefined)
+        .sort((a, b) => Buffer.compare(Buffer.from(a, 'utf8'), Buffer.from(b, 'utf8')));
+    return '{' + keys.map(k => JSON.stringify(k) + ':' + canonicalJson(rec[k])).join(',') + '}';
+}
+/** A raw unpaired surrogate: a lead surrogate not followed by a trail, or
+ * a trail surrogate not preceded by a lead. Rust (serde_json) cannot parse
+ * these — they are not valid UTF-8. */
+const LONE_SURROGATE = /(?:[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF])/;
+/** Well-formed JSON.stringify (ES2019) never emits a raw lone surrogate:
+ * it renders one as a `\udXXX` escape (paired surrogates pass through as
+ * raw astral characters, so any surrogate escape in stringify output IS a
+ * lone surrogate). A genuine escape is preceded by an even number of
+ * backslashes; an odd run means the backslash itself is escaped text. */
+const LONE_SURROGATE_ESCAPE = /(?<=(?:^|[^\\])(?:\\\\)*)\\u[dD][89abAB]/;
+/** Recursively test decoded JSON data (string values AND object keys) for a
+ * raw unpaired surrogate. Used on the READ path, where the raw line may
+ * legitimately contain paired `\udXXX` escapes (valid JSON that serde_json
+ * accepts), so the append-path escape regex cannot be reused: after
+ * JSON.parse, a valid pair decodes to an astral character while a lone
+ * surrogate stays lone — exactly what serde_json rejects as not-UTF-8. */
+function containsLoneSurrogate(v) {
+    if (typeof v === 'string')
+        return LONE_SURROGATE.test(v);
+    if (v === null || typeof v !== 'object')
+        return false;
+    if (Array.isArray(v))
+        return v.some(containsLoneSurrogate);
+    return Object.entries(v).some(([k, val]) => LONE_SURROGATE.test(k) || containsLoneSurrogate(val));
+}
+/** Serialize one event as a JSONL line in the EXACT wire key order
+ * (index, branch, parent, kind, payload; parent omitted when absent). */
+function serializeEvent(e) {
+    return JSON.stringify(e.parent === undefined
+        ? { index: e.index, branch: e.branch, kind: e.kind, payload: e.payload }
+        : {
+            index: e.index,
+            branch: e.branch,
+            parent: { branch: e.parent.branch, index: e.parent.index },
+            kind: e.kind,
+            payload: e.payload,
+        });
+}
+/** Run `op` after every previously enqueued operation on `state` has
+ * settled (success or failure), and chain the queue forward the same way —
+ * this is the TOCTOU fix: the read-index→serialize→write→state-mutate
+ * sequence in `appendLocked` only ever runs for one caller at a time per
+ * `LogState`, in call order, closing the race `append()`/`fork()` had when
+ * two unawaited calls both read the same pre-increment index. */
+function enqueue(state, op) {
+    const result = state.queue.then(op, op);
+    state.queue = result.then(() => undefined, () => undefined);
+    return result;
+}
+/** Parse + validate a JSONL log; returns either the reconstructed state or
+ * the list of 'session: '-prefixed errors (with 1-based line numbers).
+ *
+ * NOTE: the ADR-246 lockstep contract with the Rust mirror is the state
+ * hash plus the accept/reject decision; validation MESSAGES are
+ * per-language diagnostics (TS cites 1-based line numbers, Rust does not)
+ * and are not required to match byte-for-byte. */
+function parseLog(path, raw) {
+    const state = {
+        path,
+        events: [],
+        nextIndex: new Map(),
+        branchParent: new Map(),
+        rootBranch: '',
+        queue: Promise.resolve(),
+    };
+    const errors = [];
+    const seen = new Set();
+    const lines = raw.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim() === '')
+            continue; // blank / whitespace-only separators (still counted for line numbers)
+        const lineNo = i + 1;
+        let obj;
+        try {
+            obj = JSON.parse(line);
+        }
+        catch {
+            errors.push(`session: line ${lineNo}: corrupted line (invalid JSON)`);
+            continue;
+        }
+        // Mirror serde_json's accept/reject decision: a lone surrogate (decoded
+        // from a `\udXXX` escape — JSON.parse tolerates it, serde_json does not)
+        // is not representable as UTF-8, so the Rust mirror rejects the line.
+        if (containsLoneSurrogate(obj)) {
+            errors.push(`session: line ${lineNo}: corrupted line (contains an unpaired surrogate, not valid UTF-8)`);
+            continue;
+        }
+        const e = obj;
+        if (typeof e !== 'object' || e === null ||
+            typeof e.index !== 'number' || typeof e.branch !== 'string' ||
+            typeof e.kind !== 'string' || !('payload' in e) ||
+            (e.parent !== undefined &&
+                (typeof e.parent !== 'object' || e.parent === null ||
+                    typeof e.parent.branch !== 'string' || typeof e.parent.index !== 'number'))) {
+            errors.push(`session: line ${lineNo}: corrupted line (not a valid session event)`);
+            continue;
+        }
+        const ev = e;
+        const key = `${ev.branch}\u0000${ev.index}`;
+        if (seen.has(key)) {
+            errors.push(`session: line ${lineNo}: duplicate event (${ev.branch}, ${ev.index})`);
+            continue;
+        }
+        const expected = state.nextIndex.get(ev.branch) ?? 0;
+        if (ev.index !== expected) {
+            errors.push(`session: line ${lineNo}: branch "${ev.branch}" index ${ev.index} is not monotonic (expected ${expected})`);
+            // Resync like the Rust mirror: after reporting index X, expect X+1
+            // next, so a single gap yields exactly ONE error, not a cascade.
+            seen.add(key);
+            state.nextIndex.set(ev.branch, ev.index + 1);
+            continue;
+        }
+        if (expected === 0) {
+            // First event of a branch: the root branch (first branch in the file)
+            // carries no parent; every other branch MUST reference an existing
+            // (branch, index) already present in the log.
+            if (state.events.length === 0) {
+                state.rootBranch = ev.branch;
+                if (ev.parent !== undefined) {
+                    errors.push(`session: line ${lineNo}: root branch '${ev.branch}' must not carry a parent`);
+                    continue;
+                }
+            }
+            else {
+                if (ev.parent === undefined) {
+                    errors.push(`session: line ${lineNo}: first event of branch "${ev.branch}" must carry a parent reference`);
+                    continue;
+                }
+                if (!seen.has(`${ev.parent.branch}\u0000${ev.parent.index}`)) {
+                    errors.push(`session: line ${lineNo}: parent (${ev.parent.branch}, ${ev.parent.index}) does not exist`);
+                    continue;
+                }
+                state.branchParent.set(ev.branch, { branch: ev.parent.branch, index: ev.parent.index });
+            }
+        }
+        seen.add(key);
+        state.events.push(ev);
+        state.nextIndex.set(ev.branch, expected + 1);
+    }
+    return { state, errors };
+}
+/**
+ * Crash-recoverable, forkable session log (ADR-246 §2.3). One JSONL file may
+ * carry many branches; each SessionLog instance appends to ONE active branch.
+ * `fork()` returns a sibling over the same file/state on a new branch.
+ */
+export class SessionLog {
+    state;
+    /** Active branch this instance appends to. */
+    branch;
+    constructor(path, branch = 'main') {
+        this.state = {
+            path,
+            events: [],
+            nextIndex: new Map(),
+            branchParent: new Map(),
+            rootBranch: branch,
+            queue: Promise.resolve(),
+        };
+        this.branch = branch;
+    }
+    /** Internal: build an instance over existing shared state (open/fork). */
+    static over(state, branch) {
+        const log = new SessionLog(state.path, branch);
+        log.state = state;
+        return log;
+    }
+    get path() {
+        return this.state.path;
+    }
+    /**
+     * Resume a session: read the JSONL log, validate it, and reconstruct state.
+     * Throws with the first 'session: '-prefixed error on an invalid log.
+     * `branch` selects the active branch (default 'main').
+     */
+    static async open(path, branch = 'main') {
+        if (!existsSync(path))
+            return new SessionLog(path, branch);
+        const raw = await readFile(path, 'utf-8');
+        const { state, errors } = parseLog(path, raw);
+        if (errors.length > 0)
+            throw new Error(errors[0]);
+        if (state.events.length === 0)
+            return new SessionLog(path, branch);
+        return SessionLog.over(state, branch);
+    }
+    /** Append an event on the active branch, assigning the next monotonic
+     * index. The first event of a forked branch carries the fork's parent ref.
+     * Safe to call without awaiting the previous call: concurrent appends on
+     * this instance (or a fork() sibling sharing this state) are serialized
+     * via `enqueue` and assigned distinct, monotonic indices in call order. */
+    async append(kind, payload, opts) {
+        return enqueue(this.state, () => this.appendLocked(kind, payload, opts));
+    }
+    /** The unserialized body of `append()` — only ever runs for one caller at
+     * a time per `LogState`, via `enqueue`. Not called directly outside this
+     * file; `fork()` also runs its own synthetic first event through this. */
+    async appendLocked(kind, payload, opts) {
+        const index = this.state.nextIndex.get(this.branch) ?? 0;
+        const parent = opts?.parent;
+        const isRoot = this.state.events.length === 0 || this.branch === this.state.rootBranch;
+        if (index === 0 && !isRoot && parent === undefined) {
+            throw new Error(`session: first event of branch "${this.branch}" must carry a parent reference`);
+        }
+        const event = parent === undefined
+            ? { index, branch: this.branch, kind, payload }
+            : { index, branch: this.branch, parent, kind, payload };
+        const line = serializeEvent(event);
+        // Reject events the Rust mirror cannot parse: a lone surrogate is not
+        // valid UTF-8 (raw form), and serde_json also rejects its `\udXXX`
+        // escaped form, which well-formed JSON.stringify emits for it.
+        if (LONE_SURROGATE.test(line) || LONE_SURROGATE_ESCAPE.test(line)) {
+            throw new Error('session: event contains an unpaired surrogate (not valid UTF-8)');
+        }
+        await appendFile(this.state.path, line + '\n', 'utf-8');
+        if (this.state.events.length === 0)
+            this.state.rootBranch = this.branch;
+        if (index === 0 && parent !== undefined) {
+            this.state.branchParent.set(this.branch, parent);
+        }
+        this.state.events.push(event);
+        this.state.nextIndex.set(this.branch, index + 1);
+        return event;
+    }
+    /**
+     * Fork at `atIndex` on THIS instance's active branch: returns a SessionLog
+     * over the same file (and shared state) whose active branch is `newBranch`.
+     * Immediately appends the new branch's synthetic first event (matching the
+     * Rust mirror's `fork`): index 0, parent {branch: this.branch, index:
+     * atIndex}, kind 'fork', payload null.
+     */
+    async fork(atIndex, newBranch) {
+        // Both the "does newBranch already exist" check and the synthetic first
+        // event run inside ONE enqueue()'d operation: otherwise two concurrent
+        // fork() calls for the same new branch name could both pass the check
+        // before either's append() lands (the same TOCTOU shape as append()
+        // itself, one level up).
+        return enqueue(this.state, async () => {
+            const count = this.state.nextIndex.get(this.branch) ?? 0;
+            if (atIndex < 0 || atIndex >= count) {
+                throw new Error(`session: cannot fork branch "${this.branch}" at index ${atIndex} (has ${count} events)`);
+            }
+            if ((this.state.nextIndex.get(newBranch) ?? 0) > 0 || newBranch === this.branch) {
+                throw new Error(`session: branch "${newBranch}" already exists`);
+            }
+            const forked = SessionLog.over(this.state, newBranch);
+            await forked.appendLocked('fork', null, { parent: { branch: this.branch, index: atIndex } });
+            return forked;
+        });
+    }
+    /** The lineage of a branch, root → tip: the branch's own events preceded by
+     * its parent lineage truncated at the fork point, recursively. */
+    lineage(branch) {
+        const own = this.state.events
+            .filter(e => e.branch === branch)
+            .sort((a, b) => a.index - b.index);
+        const parent = this.state.branchParent.get(branch);
+        if (!parent)
+            return own;
+        const upstream = this.lineage(parent.branch).filter(e => e.branch !== parent.branch || e.index <= parent.index);
+        return [...upstream, ...own];
+    }
+    /**
+     * State hash over the branch lineage (root → tip). Exact fold (mirrored in
+     * the file-header comment; a Rust mirror must reproduce it):
+     *     hexPrev = ''; for each event: hexPrev = hex(sha256(utf8(hexPrev + canonicalJson(event))))
+     * Returns lowercase hex; the hash of an empty lineage is ''.
+     */
+    stateHash(branch = this.branch) {
+        let hexPrev = '';
+        for (const e of this.lineage(branch)) {
+            hexPrev = createHash('sha256')
+                .update(hexPrev + canonicalJson(e), 'utf-8')
+                .digest('hex');
+        }
+        return hexPrev;
+    }
+    /** Deterministic replay of a branch lineage: event count + state hash. */
+    replay(branch = this.branch) {
+        return { eventCount: this.lineage(branch).length, stateHash: this.stateHash(branch) };
+    }
+    /** Re-read the file from disk and report every validation error
+     * ('session: '-prefixed, corrupted lines cited by 1-based line number).
+     * An empty array means the on-disk log is valid. */
+    async validate() {
+        if (!existsSync(this.state.path))
+            return [];
+        const raw = await readFile(this.state.path, 'utf-8');
+        return parseLog(this.state.path, raw).errors;
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

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

package/dist/types.d.ts

@@ -31,6 +31,22 @@ export interface HarnessSpec {
         deny?: string[];
     };
     statusLine?: string;
+    /**
+     * Autonomous-mode fields (ADR-246 §2.2). Host adapters must project this
+     * block per host or emit an explicit documented no-op — never silently drop.
+     */
+    autonomous?: {
+        goal?: {
+            text: string;
+            tokenBudget?: number;
+        };
+        heartbeat?: {
+            cadence: string;
+            instruction: string;
+        };
+        gateCommand?: string;
+        maxTurns?: number;
+    };
 }
 export interface HostAdapter {
     name: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,WAAW,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3D"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,WAAW,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE;QACX,IAAI,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAC9C,SAAS,CAAC,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,WAAW,EAAE,MAAM,CAAA;SAAE,CAAC;QACrD,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3D"}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@metaharness/kernel",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Cross-platform kernel for the agent-harness-generator — wasm primary, NAPI-RS native fallback",
-  "homepage": "https://github.com/ruvnet/agent-harness-generator",
+  "homepage": "https://github.com/ruvnet/metaharness",
   "repository": {
     "type": "git",
-    "url": "https://github.com/ruvnet/agent-harness-generator.git",
+    "url": "https://github.com/ruvnet/metaharness.git",
     "directory": "packages/kernel-js"
   },
   "license": "MIT",
@@ -57,20 +57,33 @@
     "@ruvector/emergent-time": "^0.1.0"
   },
   "peerDependencies": {
-    "@ruvector/rvf": "^0.2.0"
-  },
-  "peerDependenciesMeta": {
-    "@ruvector/rvf": {
-      "optional": true
-    }
-  },
-  "optionalDependencies": {
+    "@ruvector/rvf": "^0.2.0 || ^0.3.0 || ^0.4.0",
     "@metaharness/kernel-darwin-arm64": "0.1.0",
     "@metaharness/kernel-darwin-x64": "0.1.0",
     "@metaharness/kernel-linux-x64-gnu": "0.1.0",
     "@metaharness/kernel-linux-arm64-gnu": "0.1.0",
     "@metaharness/kernel-win32-x64-msvc": "0.1.0"
   },
+  "peerDependenciesMeta": {
+    "@ruvector/rvf": {
+      "optional": true
+    },
+    "@metaharness/kernel-darwin-arm64": {
+      "optional": true
+    },
+    "@metaharness/kernel-darwin-x64": {
+      "optional": true
+    },
+    "@metaharness/kernel-linux-x64-gnu": {
+      "optional": true
+    },
+    "@metaharness/kernel-linux-arm64-gnu": {
+      "optional": true
+    },
+    "@metaharness/kernel-win32-x64-msvc": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=20.0.0"
   }

package/pkg/package.json

@@ -1,21 +0,0 @@
-{
-  "name": "ruflo-kernel-wasm",
-  "collaborators": [
-    "rUv <ruv@ruv.net>"
-  ],
-  "description": "WebAssembly bindings for ruflo-kernel",
-  "version": "0.1.0",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/ruvnet/agent-harness-generator"
-  },
-  "files": [
-    "ruflo_kernel_wasm_bg.wasm",
-    "ruflo_kernel_wasm.js",
-    "ruflo_kernel_wasm.d.ts"
-  ],
-  "main": "ruflo_kernel_wasm.js",
-  "types": "ruflo_kernel_wasm.d.ts",
-  "type": "commonjs"
-}

package/pkg/ruflo_kernel_wasm.d.ts

@@ -1,17 +0,0 @@
-/* tslint:disable */
-/* eslint-disable */
-
-/**
- * Return kernel build metadata as a JS object.
- */
-export function kernelInfo(): any;
-
-/**
- * Validate an MCP server spec (returns `null` on success, error string otherwise).
- */
-export function mcpValidate(spec_json: string): any;
-
-/**
- * Returns the package version.
- */
-export function version(): string;

package/pkg/ruflo_kernel_wasm.js

@@ -1,218 +0,0 @@
-/* @ts-self-types="./ruflo_kernel_wasm.d.ts" */
-
-/**
- * Return kernel build metadata as a JS object.
- * @returns {any}
- */
-function kernelInfo() {
-    try {
-        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-        wasm.kernelInfo(retptr);
-        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
-        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
-        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
-        if (r2) {
-            throw takeObject(r1);
-        }
-        return takeObject(r0);
-    } finally {
-        wasm.__wbindgen_add_to_stack_pointer(16);
-    }
-}
-exports.kernelInfo = kernelInfo;
-
-/**
- * Validate an MCP server spec (returns `null` on success, error string otherwise).
- * @param {string} spec_json
- * @returns {any}
- */
-function mcpValidate(spec_json) {
-    try {
-        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-        const ptr0 = passStringToWasm0(spec_json, wasm.__wbindgen_export, wasm.__wbindgen_export2);
-        const len0 = WASM_VECTOR_LEN;
-        wasm.mcpValidate(retptr, ptr0, len0);
-        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
-        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
-        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
-        if (r2) {
-            throw takeObject(r1);
-        }
-        return takeObject(r0);
-    } finally {
-        wasm.__wbindgen_add_to_stack_pointer(16);
-    }
-}
-exports.mcpValidate = mcpValidate;
-
-/**
- * Returns the package version.
- * @returns {string}
- */
-function version() {
-    let deferred1_0;
-    let deferred1_1;
-    try {
-        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-        wasm.version(retptr);
-        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
-        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
-        deferred1_0 = r0;
-        deferred1_1 = r1;
-        return getStringFromWasm0(r0, r1);
-    } finally {
-        wasm.__wbindgen_add_to_stack_pointer(16);
-        wasm.__wbindgen_export3(deferred1_0, deferred1_1, 1);
-    }
-}
-exports.version = version;
-function __wbg_get_imports() {
-    const import0 = {
-        __proto__: null,
-        __wbg_String_8564e559799eccda: function(arg0, arg1) {
-            const ret = String(getObject(arg1));
-            const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_export, wasm.__wbindgen_export2);
-            const len1 = WASM_VECTOR_LEN;
-            getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
-            getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
-        },
-        __wbg___wbindgen_throw_ea4887a5f8f9a9db: function(arg0, arg1) {
-            throw new Error(getStringFromWasm0(arg0, arg1));
-        },
-        __wbg_new_2e117a478906f062: function() {
-            const ret = new Object();
-            return addHeapObject(ret);
-        },
-        __wbg_set_6be42768c690e380: function(arg0, arg1, arg2) {
-            getObject(arg0)[takeObject(arg1)] = takeObject(arg2);
-        },
-        __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Ref(String) -> Externref`.
-            const ret = getStringFromWasm0(arg0, arg1);
-            return addHeapObject(ret);
-        },
-        __wbindgen_object_clone_ref: function(arg0) {
-            const ret = getObject(arg0);
-            return addHeapObject(ret);
-        },
-        __wbindgen_object_drop_ref: function(arg0) {
-            takeObject(arg0);
-        },
-    };
-    return {
-        __proto__: null,
-        "./ruflo_kernel_wasm_bg.js": import0,
-    };
-}
-
-function addHeapObject(obj) {
-    if (heap_next === heap.length) heap.push(heap.length + 1);
-    const idx = heap_next;
-    heap_next = heap[idx];
-
-    heap[idx] = obj;
-    return idx;
-}
-
-function dropObject(idx) {
-    if (idx < 1028) return;
-    heap[idx] = heap_next;
-    heap_next = idx;
-}
-
-let cachedDataViewMemory0 = null;
-function getDataViewMemory0() {
-    if (cachedDataViewMemory0 === null || cachedDataViewMemory0.buffer.detached === true || (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) {
-        cachedDataViewMemory0 = new DataView(wasm.memory.buffer);
-    }
-    return cachedDataViewMemory0;
-}
-
-function getStringFromWasm0(ptr, len) {
-    return decodeText(ptr >>> 0, len);
-}
-
-let cachedUint8ArrayMemory0 = null;
-function getUint8ArrayMemory0() {
-    if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
-        cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
-    }
-    return cachedUint8ArrayMemory0;
-}
-
-function getObject(idx) { return heap[idx]; }
-
-let heap = new Array(1024).fill(undefined);
-heap.push(undefined, null, true, false);
-
-let heap_next = heap.length;
-
-function passStringToWasm0(arg, malloc, realloc) {
-    if (realloc === undefined) {
-        const buf = cachedTextEncoder.encode(arg);
-        const ptr = malloc(buf.length, 1) >>> 0;
-        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
-        WASM_VECTOR_LEN = buf.length;
-        return ptr;
-    }
-
-    let len = arg.length;
-    let ptr = malloc(len, 1) >>> 0;
-
-    const mem = getUint8ArrayMemory0();
-
-    let offset = 0;
-
-    for (; offset < len; offset++) {
-        const code = arg.charCodeAt(offset);
-        if (code > 0x7F) break;
-        mem[ptr + offset] = code;
-    }
-    if (offset !== len) {
-        if (offset !== 0) {
-            arg = arg.slice(offset);
-        }
-        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
-        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
-        const ret = cachedTextEncoder.encodeInto(arg, view);
-
-        offset += ret.written;
-        ptr = realloc(ptr, len, offset, 1) >>> 0;
-    }
-
-    WASM_VECTOR_LEN = offset;
-    return ptr;
-}
-
-function takeObject(idx) {
-    const ret = getObject(idx);
-    dropObject(idx);
-    return ret;
-}
-
-let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
-cachedTextDecoder.decode();
-function decodeText(ptr, len) {
-    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
-}
-
-const cachedTextEncoder = new TextEncoder();
-
-if (!('encodeInto' in cachedTextEncoder)) {
-    cachedTextEncoder.encodeInto = function (arg, view) {
-        const buf = cachedTextEncoder.encode(arg);
-        view.set(buf);
-        return {
-            read: arg.length,
-            written: buf.length
-        };
-    };
-}
-
-let WASM_VECTOR_LEN = 0;
-
-const wasmPath = `${__dirname}/ruflo_kernel_wasm_bg.wasm`;
-const wasmBytes = require('fs').readFileSync(wasmPath);
-const wasmModule = new WebAssembly.Module(wasmBytes);
-let wasmInstance = new WebAssembly.Instance(wasmModule, __wbg_get_imports());
-let wasm = wasmInstance.exports;

package/pkg/ruflo_kernel_wasm_bg.wasm.d.ts

@@ -1,10 +0,0 @@
-/* tslint:disable */
-/* eslint-disable */
-export const memory: WebAssembly.Memory;
-export const kernelInfo: (a: number) => void;
-export const mcpValidate: (a: number, b: number, c: number) => void;
-export const version: (a: number) => void;
-export const __wbindgen_export: (a: number, b: number) => number;
-export const __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
-export const __wbindgen_add_to_stack_pointer: (a: number) => number;
-export const __wbindgen_export3: (a: number, b: number, c: number) => void;