@spexcode/spec-cli 0.6.5 → 0.6.6

package/dist/supervise.js

@@ -42,7 +42,7 @@ const childApiBase = `http://127.0.0.1:${proxyPort}`;
 // observe the source closure, compile it, then make the supervisor's normal zero-downtime swap. A source edit
 // must never cause a restart that still runs the old dist.
 const watchRoots = workspaceRoot
-    ? [sourceRoot, join(workspaceRoot, 'spec-forge', 'src'), join(workspaceRoot, 'spec-eval', 'src'), join(workspaceRoot, 'packages', 'spec-core', 'src')]
+    ? [sourceRoot, join(workspaceRoot, 'spec-forge', 'src'), join(workspaceRoot, 'spec-eval', 'src'), join(workspaceRoot, 'packages', 'spec-core', 'src'), join(workspaceRoot, 'packages', 'session-core', 'src')]
     : [here];
 function buildWorkspace() {
     if (!workspaceRoot)
@@ -246,11 +246,11 @@ catch { /* already gone */ } };
 if (publicCfg) {
     // public mode: the raw proxy stays on loopback; the password-gated gateway owns the public port.
     const distDir = resolveDistDir();
-    listenOrExit(proxy, proxyPort, { host: '127.0.0.1', label: 'supervisor (loopback proxy)', cleanup: reapChild, onListen: () => { recordEndpoint(childApiBase); console.log(`spec-cli supervisor on loopback :${proxyPort} (zero-downtime reloads, backend :${first.port})`); } });
+    listenOrExit(proxy, proxyPort, { host: '127.0.0.1', label: 'supervisor (loopback proxy)', cleanup: reapChild, onListen: () => recordEndpoint(childApiBase), ready: `spec-cli supervisor on loopback :${proxyPort} (zero-downtime reloads, backend :${first.port})` });
     startGateway({ publicPort, upstreamPort: proxyPort, password: publicCfg.password, tls: publicCfg.tls, distDir, onBindFail: reapChild });
 }
 else {
-    listenOrExit(proxy, publicPort, { label: 'supervisor', cleanup: reapChild, onListen: () => { recordEndpoint(childApiBase); console.log(`spec-cli supervisor serving on http://localhost:${publicPort} (zero-downtime reloads, backend :${first.port})`); } });
+    listenOrExit(proxy, publicPort, { label: 'supervisor', cleanup: reapChild, onListen: () => recordEndpoint(childApiBase), ready: `spec-cli supervisor serving on http://localhost:${publicPort} (zero-downtime reloads, backend :${first.port})` });
 }
 startResourceMonitor();
 // Watch the source closure in a workspace and the emitted directory in an installed package. Debounce a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spexcode/spec-cli",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "type": "module",
   "description": "SpexCode CLI + server. The root spexcode package delegates to this compiled package; dashboard assets live in @spexcode/spec-dashboard.",
   "bin": {
@@ -21,6 +21,7 @@
   ],
   "bundledDependencies": [
     "@spexcode/spec-core",
+    "@spexcode/session-core",
     "@spexcode/spec-eval",
     "@spexcode/spec-forge"
   ],
@@ -35,9 +36,10 @@
     "test": "tsx --import ../scripts/test-home.mjs --test src/*.test.ts"
   },
   "dependencies": {
-    "@spexcode/spec-core": "0.6.5",
-    "@spexcode/spec-eval": "0.6.5",
-    "@spexcode/spec-forge": "0.6.5"
+    "@spexcode/session-core": "0.6.6",
+    "@spexcode/spec-core": "0.6.6",
+    "@spexcode/spec-eval": "0.6.6",
+    "@spexcode/spec-forge": "0.6.6"
   },
   "devDependencies": {
     "@types/node": "^20.16.0",

package/dist/delivery-queue.d.ts

@@ -1,23 +0,0 @@
-export type PendingMessage = {
-    mid: string;
-    text: string;
-    from: string | null;
-    dispatch?: {
-        operation: 'merge';
-        requestDigest: string;
-    };
-};
-export declare function revokeSenderDelivery(id: string): void;
-export declare const senderDeliveryRevoked: (id: string) => boolean;
-export declare function pendingSnapshot(id: string): PendingMessage[];
-export declare function replacePendingWhileLocked(id: string, msgs: PendingMessage[]): void;
-export declare function revokePendingFromWhileLocked(id: string, sender: string): number;
-export declare function enqueue(id: string, msg: PendingMessage): void;
-export declare function ensurePendingWhileLocked(id: string, msg: PendingMessage): boolean;
-export declare const pendingMessages: (id: string) => PendingMessage[];
-export declare const owesDelivery: (id: string) => boolean;
-export declare function withDeliveryLocks<T>(rawIds: string[], body: () => Promise<T>, index?: number, ids?: string[]): Promise<T>;
-export declare function drain(id: string, insert: (msg: PendingMessage) => Promise<boolean>, timeoutMs?: number): Promise<{
-    delivered: number;
-    remaining: number;
-}>;

package/dist/delivery-queue.js

@@ -1,179 +0,0 @@
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, writeSync } from 'node:fs';
-import { join } from 'node:path';
-import { runtimeRoot, sessionArtifactPath, sessionStoreDir } from '@spexcode/spec-core';
-const queuePath = (id) => sessionArtifactPath(id, 'pending.json');
-const revokedSenderRoot = () => join(runtimeRoot(), '.revoked-senders');
-const revokedSenderPath = (id) => join(revokedSenderRoot(), id);
-// @@@ its own lock, deliberately NOT the record lock - the drain holds this across the adapter insert, which
-// is what makes "claim" real: two processes draining the same session cannot both hand over one message. The
-// record lock could never span that call — a native turn runs lifecycle hooks that re-enter the record writer,
-// and holding it there deadlocks the adapter's own confirmation. Nothing in the delivery path takes this one,
-// so spanning the insert costs no contention. PID liveness reclaims a lock whose holder died mid-insert.
-const lockRoot = () => join(runtimeRoot(), '.delivery-locks');
-const lockPath = (id) => join(lockRoot(), `${id}.lock`);
-const pause = (ms) => new Promise((r) => setTimeout(r, ms));
-async function acquire(id, timeoutMs) {
-    mkdirSync(lockRoot(), { recursive: true });
-    const path = lockPath(id), deadline = Date.now() + timeoutMs;
-    for (;;) {
-        try {
-            const fd = openSync(path, 'wx');
-            writeSync(fd, String(process.pid));
-            closeSync(fd);
-            return () => { try {
-                unlinkSync(path);
-            }
-            catch { /* a liveness reclaim already removed it */ } };
-        }
-        catch (e) {
-            if (e.code !== 'EEXIST')
-                throw e;
-            let owner = 0;
-            try {
-                owner = Number(readFileSync(path, 'utf8').trim()) || 0;
-            }
-            catch { /* race with creator/releaser */ }
-            if (owner && owner !== process.pid) {
-                try {
-                    process.kill(owner, 0);
-                }
-                catch {
-                    try {
-                        unlinkSync(path);
-                    }
-                    catch { /* race */ }
-                    ;
-                    continue;
-                }
-            }
-            // A drain is never urgent enough to fight for: whoever holds the lock is delivering these same messages,
-            // and the retry sweep will come back. Declining is not a lost message.
-            if (Date.now() >= deadline)
-                return null;
-            await pause(25);
-        }
-    }
-}
-function read(id) {
-    try {
-        const raw = JSON.parse(readFileSync(queuePath(id), 'utf8'));
-        if (!Array.isArray(raw))
-            return [];
-        return raw.filter((m) => !!m && typeof m === 'object'
-            && typeof m.mid === 'string'
-            && typeof m.text === 'string'
-            && (m.dispatch === undefined
-                || (m.dispatch?.operation === 'merge'
-                    && typeof m.dispatch?.requestDigest === 'string')));
-    }
-    catch {
-        return [];
-    } // absent, empty, or unparseable all mean the honest thing: nothing owed
-}
-// Written whole and atomically; an empty queue is REMOVED rather than left as `[]`, so "is anything owed?" is
-// one existsSync on the sweep's hot path.
-function write(id, msgs) {
-    const path = queuePath(id);
-    if (!msgs.length) {
-        try {
-            unlinkSync(path);
-        }
-        catch { /* already gone */ }
-        ;
-        return;
-    }
-    mkdirSync(sessionStoreDir(id), { recursive: true });
-    const tmp = `${path}.${process.pid}.tmp`;
-    writeFileSync(tmp, JSON.stringify(msgs, null, 2) + '\n');
-    renameSync(tmp, path);
-}
-// A closed sender may have left debt in many other sessions' queues. The marker is deliberately outside its
-// own store (which close removes) and is checked under the sender's record lock by dispatch: a close cannot
-// return while an old process can still append, and a later sweep cannot hand over what it sees here.
-export function revokeSenderDelivery(id) {
-    mkdirSync(revokedSenderRoot(), { recursive: true });
-    writeFileSync(revokedSenderPath(id), `${id}\n`);
-}
-export const senderDeliveryRevoked = (id) => existsSync(revokedSenderPath(id));
-export function pendingSnapshot(id) { return read(id); }
-// These two writes require the target's delivery lock. They are the queue half of a larger transaction
-// (currently reparent), which must be able to restore the exact previous debt if a later record write fails.
-export function replacePendingWhileLocked(id, msgs) { write(id, msgs); }
-export function revokePendingFromWhileLocked(id, sender) {
-    const current = read(id);
-    const next = current.filter((msg) => msg.from !== sender);
-    write(id, next);
-    return current.length - next.length;
-}
-// The enqueue rides the timeline append ([[dispatch]]): the caller holds the session's RECORD lock across
-// both, and the record is written first, so delivery is never unrecorded. A keyed dispatch also carries its
-// exact delivery bytes in the timeline receipt, letting its retry restore a queue write lost to a crash.
-export function enqueue(id, msg) {
-    write(id, [...read(id), msg]);
-}
-// Caller holds this target's delivery lock. A retry may reach this after either side of the receipt->queue
-// crash boundary; exact mid identity makes reconstruction idempotent without inspecting message text.
-export function ensurePendingWhileLocked(id, msg) {
-    const current = read(id);
-    if (current.some((pending) => pending.mid === msg.mid))
-        return false;
-    write(id, [...current, msg]);
-    return true;
-}
-export const pendingMessages = (id) => read(id);
-export const owesDelivery = (id) => existsSync(queuePath(id));
-// Record transitions and queue mutations take locks in the same direction: record locks first, then these
-// target queue locks. A batch reparent needs all child queues held at once so its pointer/watch/debt change
-// either commits together or restores together.
-export async function withDeliveryLocks(rawIds, body, index = 0, ids = [...new Set(rawIds)].sort()) {
-    if (index >= ids.length)
-        return body();
-    const release = await acquire(ids[index], 30_000);
-    if (!release)
-        throw new Error(`delivery queue ${ids[index]}: timed out waiting for transaction lock`);
-    try {
-        return await withDeliveryLocks(ids, body, index + 1, ids);
-    }
-    finally {
-        release();
-    }
-}
-// Hand over what is owed, in order, exactly once. `insert` reports whether the adapter took the message: only
-// then is the entry dropped. A refusal ENDS the pass with that entry still queued and everything behind it
-// still behind it — order is a property of a conversation, so a message is never skipped to deliver a later
-// one. Returns how many were handed over and how many are still owed.
-export async function drain(id, insert, timeoutMs = 5_000) {
-    const release = await acquire(id, timeoutMs);
-    if (!release)
-        return { delivered: 0, remaining: read(id).length };
-    let delivered = 0;
-    try {
-        for (;;) {
-            const queued = read(id);
-            if (!queued.length)
-                return { delivered, remaining: 0 };
-            if (queued[0].from && senderDeliveryRevoked(queued[0].from)) {
-                // Closing a sender voids its undelivered output, not the recipient's immutable conversation history.
-                // Drop a revoked head and continue so it cannot permanently block the messages behind it.
-                write(id, read(id).filter((m) => m.mid !== queued[0].mid));
-                continue;
-            }
-            let ok = false;
-            try {
-                ok = await insert(queued[0]);
-            }
-            catch {
-                ok = false;
-            }
-            if (!ok)
-                return { delivered, remaining: queued.length };
-            // Re-read before removing: a send that landed while this pass ran appended to the tail, and rewriting a
-            // stale snapshot minus the head would silently drop it.
-            write(id, read(id).filter((m) => m.mid !== queued[0].mid));
-            delivered++;
-        }
-    }
-    finally {
-        release();
-    }
-}

package/dist/session-cursors.d.ts

@@ -1,14 +0,0 @@
-import type { TimelineEvent } from './session-timeline.js';
-export type Cursors = {
-    version: 1;
-    follows: Record<string, number>;
-};
-export declare function readCursors(id: string): Cursors;
-export declare const followCursor: (id: string, target: string) => number | null;
-export declare function advanceFollow(id: string, target: string, to: number): void;
-export declare const followedSessions: (id: string) => string[];
-export declare function unreadSince(events: TimelineEvent[], from: number): {
-    events: TimelineEvent[];
-    at: number[];
-    next: number;
-};

package/dist/session-cursors.js

@@ -1,82 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { sessionArtifactPath, sessionStoreDir } from '@spexcode/spec-core';
-const cursorsPath = (id) => sessionArtifactPath(id, 'cursors.json');
-const at = (v) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? Math.floor(v) : 0);
-// Never throws: a missing, empty, or unparseable file reads as "nothing consumed", because re-showing a
-// message is the honest recovery for a lost position and skipping one is not. Followed entries whose target
-// store dir is gone are dropped here — expiry is this read, and the next write persists it.
-export function readCursors(id) {
-    let raw = null;
-    try {
-        raw = JSON.parse(readFileSync(cursorsPath(id), 'utf8'));
-    }
-    catch { /* no cursors yet */ }
-    const follows = {};
-    const stored = raw?.follows;
-    if (stored && typeof stored === 'object') {
-        for (const [target, pos] of Object.entries(stored)) {
-            if (!target || !existsSync(sessionStoreDir(target)))
-                continue;
-            follows[target] = at(pos);
-        }
-    }
-    return { version: 1, follows };
-}
-// Written whole and atomically, one field per line — the same shape as the session record, so a position stays
-// readable by an exact whole-line match where a value regex would not be.
-function writeCursors(id, cursors) {
-    const dir = sessionStoreDir(id);
-    mkdirSync(dir, { recursive: true });
-    const tmp = join(dir, `.cursors.json.${process.pid}.tmp`);
-    writeFileSync(tmp, JSON.stringify(cursors, null, 2) + '\n');
-    renameSync(tmp, cursorsPath(id));
-}
-export const followCursor = (id, target) => {
-    const stored = readCursors(id).follows[target];
-    return stored === undefined ? null : stored;
-};
-// Start or advance a follow. Following IS this entry existing, so the first call registers the relationship.
-// Monotonic: a stale read can leave a position too low (an event read twice), never too high (one lost).
-export function advanceFollow(id, target, to) {
-    const cursors = readCursors(id);
-    const stored = cursors.follows[target];
-    if (stored !== undefined && to <= stored)
-        return;
-    writeCursors(id, { ...cursors, follows: { ...cursors.follows, [target]: Math.max(0, Math.floor(to)) } });
-}
-export const followedSessions = (id) => Object.keys(readCursors(id).follows);
-const sameStatus = (a, b) => a.kind === 'status' && b.kind === 'status' && a.status === b.status
-    && (a.proposal ?? null) === (b.proposal ?? null) && (a.note ?? null) === (b.note ?? null);
-// @@@ edges, not lines - what a reader has not yet seen, with repeated status lines dropped. X→X IS NOT A
-// TRANSITION: the log is append-only and already holds runs of identical status lines from before the
-// timeline observer was deleted (every stray `spex serve` process ran an fs.watch over the same store and
-// re-recorded each real move, so ONE transition landed as up to 6 lines within ~200ms). Those bytes are
-// history and stay. Any consumer that decides "did it move?" must therefore compare VALUES, never adjacency,
-// and must compare against the last status the reader ALREADY saw — otherwise a duplicate straddling the
-// cursor boundary reads as a fresh move on the very next tick. `next` is where the cursor goes after consuming
-// the WHOLE slice: the full length, because a dropped duplicate is still consumed. `at[i]` is the absolute
-// index of `events[i]`, which is what lets a reader that STOPS on one event ([[session-follow]]'s take-one
-// wait) advance to exactly `at[i] + 1` and leave the lines behind it unread for the next reader.
-export function unreadSince(events, from) {
-    const start = Math.min(Math.max(0, Math.floor(from)), events.length);
-    let prev = null;
-    for (let i = start - 1; i >= 0; i--)
-        if (events[i].kind === 'status') {
-            prev = events[i];
-            break;
-        }
-    const out = [];
-    const at = [];
-    for (let i = start; i < events.length; i++) {
-        const e = events[i];
-        if (e.kind === 'status') {
-            if (prev && sameStatus(prev, e))
-                continue;
-            prev = e;
-        }
-        out.push(e);
-        at.push(i);
-    }
-    return { events: out, at, next: events.length };
-}