spexcode 0.6.6 → 0.6.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "type": "module",
   "description": "SpexCode — a spec-driven, self-developing dev tool. The `spex` CLI + spec server reads the .spec tree and its git history, and serves the dashboard.",
   "license": "MIT",
@@ -21,9 +21,15 @@
     "node": ">=22"
   },
   "scripts": {
-    "build": "npm run build --workspace=@spexcode/spec-core && npm run build --workspace=@spexcode/session-core && npm run build --workspace=@spexcode/spec-eval && npm run build --workspace=@spexcode/spec-forge && npm run build --workspace=@spexcode/spec-cli",
+    "build": "npm run build --workspace=@spexcode/session-protocol && npm run build --workspace=@spexcode/session-topology && npm run build --workspace=@spexcode/session-runtime && npm run build --workspace=@spexcode/session-events && npm run build --workspace=@spexcode/session-application && npm run build --workspace=@spexcode/session-selflaunch && npm run build --workspace=@spexcode/spec-core && npm run build --workspace=@spexcode/spec-eval && npm run build --workspace=@spexcode/spec-forge && npm run build --workspace=@spexcode/spec-cli",
+    "typecheck": "tsc --noEmit -p spec-cli/tsconfig.json",
+    "migrate:sessions": "npm run build && node scripts/migrate-session-json.mjs",
+    "test:session-cutover": "node --test scripts/session-live-cutover.test.mjs",
     "api": "npm run build && node bin/spex.mjs serve",
     "web": "cd spec-dashboard && npm run dev",
+    "desktop:install": "npm --prefix spec-desktop install",
+    "desktop:start": "npm --prefix spec-desktop start",
+    "desktop:check": "node --test scripts/desktop-contract.test.mjs",
     "build:public": "node scripts/public-graph-build.mjs",
     "test:public-graph": "npm run build:public && node spec-dashboard/test/public-graph-static.e2e.mjs",
     "lint": "node scripts/sync-init-plugins.mjs --check && cd spec-cli && npm run -s lint",
@@ -38,7 +44,7 @@
     "prepack": "node scripts/sync-init-plugins.mjs --check && node scripts/prepack.mjs"
   },
   "dependencies": {
-    "@spexcode/spec-cli": "0.6.6"
+    "@spexcode/spec-cli": "0.6.8"
   },
   "publishConfig": {
     "access": "public"

package/node_modules/@spexcode/session-core/dist/delivery-queue.d.ts

@@ -1,23 +0,0 @@
-export type PendingMessage = {
-    mid: string;
-    text: string;
-    from: string | null;
-    dispatch?: {
-        operation: string;
-        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/node_modules/@spexcode/session-core/dist/delivery-queue.js

@@ -1,195 +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';
-import { sentDispatchReceipt, settleSentDispatch } from './session-timeline.js';
-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
-                || (typeof m.dispatch?.operation === 'string'
-                    && 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 {
-                const head = queued[0];
-                if (head.dispatch) {
-                    const receipt = sentDispatchReceipt(id, head.dispatch.operation, head.dispatch.requestDigest);
-                    if (!receipt || receipt.mid !== head.mid || !receipt.delivery
-                        || receipt.delivery.text !== head.text || receipt.delivery.from !== head.from)
-                        return { delivered, remaining: queued.length };
-                    if (receipt.delivered)
-                        ok = true;
-                    else {
-                        ok = await insert(head);
-                        if (ok)
-                            settleSentDispatch(id, head.mid);
-                    }
-                }
-                else
-                    ok = await insert(head);
-            }
-            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/node_modules/@spexcode/session-core/dist/index.d.ts

@@ -1,5 +0,0 @@
-export { acceptMessage, MessageKeyConflict, type AcceptMessageOptions, type MessageIdempotency, type PreparedMessage } from './message.js';
-export { drain, owesDelivery, pendingMessages, type PendingMessage } from './delivery-queue.js';
-export { publishRuntimeSessionState, readRuntimeSession, registerRuntimeSession, runtimeSessionChildren, RuntimeSessionConflict, type RuntimeSessionRecord, type RuntimeSessionRegistration, type RuntimeSessionState, } from './runtime-session.js';
-export { advanceFollow, followedSessions, followCursor, readCursors, unreadSince, type Cursors } from './session-cursors.js';
-export { currentHumanTurn, lastHumanSendVia, recordStatus, timelineEvents, timelineStamp, timelineTail, type SessionTurn, type TimelineEvent, } from './session-timeline.js';

package/node_modules/@spexcode/session-core/dist/index.js

@@ -1,5 +0,0 @@
-export { acceptMessage, MessageKeyConflict } from './message.js';
-export { drain, owesDelivery, pendingMessages } from './delivery-queue.js';
-export { publishRuntimeSessionState, readRuntimeSession, registerRuntimeSession, runtimeSessionChildren, RuntimeSessionConflict, } from './runtime-session.js';
-export { advanceFollow, followedSessions, followCursor, readCursors, unreadSince } from './session-cursors.js';
-export { currentHumanTurn, lastHumanSendVia, recordStatus, timelineEvents, timelineStamp, timelineTail, } from './session-timeline.js';

package/node_modules/@spexcode/session-core/dist/internal.d.ts

@@ -1,3 +0,0 @@
-export { enqueue, ensurePendingWhileLocked, pendingSnapshot, replacePendingWhileLocked, revokePendingFromWhileLocked, revokeSenderDelivery, senderDeliveryRevoked, withDeliveryLocks, } from './delivery-queue.js';
-export { appendSent, sentDispatchReceipt, settleSentDispatch, type SentDispatchReceipt, type SentDispatchState, } from './session-timeline.js';
-export { trySessionRecordLockSync, withSessionRecordLock, withSessionRecordLocks, withSessionRecordLockSync, } from './record-lock.js';

package/node_modules/@spexcode/session-core/dist/internal.js

@@ -1,3 +0,0 @@
-export { enqueue, ensurePendingWhileLocked, pendingSnapshot, replacePendingWhileLocked, revokePendingFromWhileLocked, revokeSenderDelivery, senderDeliveryRevoked, withDeliveryLocks, } from './delivery-queue.js';
-export { appendSent, sentDispatchReceipt, settleSentDispatch, } from './session-timeline.js';
-export { trySessionRecordLockSync, withSessionRecordLock, withSessionRecordLocks, withSessionRecordLockSync, } from './record-lock.js';

package/node_modules/@spexcode/session-core/dist/message.d.ts

@@ -1,22 +0,0 @@
-import { type SentDispatchReceipt } from './session-timeline.js';
-export type MessageIdempotency = SentDispatchReceipt;
-export type PreparedMessage = {
-    text: string;
-    replyVia?: 'note';
-};
-export type AcceptMessageOptions = {
-    target: string;
-    text: string;
-    from?: string;
-    idempotency?: MessageIdempotency;
-    validate?: () => Promise<void>;
-    prepare: () => Promise<PreparedMessage>;
-};
-export declare class MessageKeyConflict extends Error {
-    readonly code = "dispatch_key_reused";
-    constructor(operation: string);
-}
-export declare function acceptMessage(options: AcceptMessageOptions): Promise<{
-    mid: string;
-    replayed: boolean;
-}>;

package/node_modules/@spexcode/session-core/dist/message.js

@@ -1,52 +0,0 @@
-import { ensurePendingWhileLocked, enqueue, senderDeliveryRevoked, withDeliveryLocks } from './delivery-queue.js';
-import { appendSent, sentDispatchReceipt } from './session-timeline.js';
-import { withSessionRecordLocks } from './record-lock.js';
-export class MessageKeyConflict extends Error {
-    code = 'dispatch_key_reused';
-    constructor(operation) {
-        super(`idempotency key is already bound to another ${operation} payload`);
-        this.name = 'MessageKeyConflict';
-    }
-}
-const keyedPending = (receipt, mid, delivery) => ({
-    mid,
-    text: delivery.text,
-    from: delivery.from,
-    dispatch: { operation: receipt.operation, requestDigest: receipt.requestDigest },
-});
-// The durable acceptance boundary. Product validation and prompt composition run while the record fence is
-// held, but the package alone owns append + debt publication and keyed crash recovery.
-export async function acceptMessage(options) {
-    const from = options.from ?? null;
-    let result = null;
-    await withSessionRecordLocks([options.target, ...(from ? [from] : [])], async () => {
-        if (from && senderDeliveryRevoked(from))
-            throw new Error(`sender session ${from} is closed; prompt NOT delivered`);
-        await options.validate?.();
-        const accept = async () => {
-            if (options.idempotency) {
-                const prior = sentDispatchReceipt(options.target, options.idempotency.operation, options.idempotency.requestDigest);
-                if (prior) {
-                    if (prior.payloadHash !== options.idempotency.payloadHash)
-                        throw new MessageKeyConflict(options.idempotency.operation);
-                    if (prior.delivery && !prior.delivered)
-                        ensurePendingWhileLocked(options.target, keyedPending(options.idempotency, prior.mid, prior.delivery));
-                    result = { mid: prior.mid, replayed: true };
-                    return;
-                }
-            }
-            const prepared = await options.prepare();
-            const receipt = options.idempotency
-                ? { ...options.idempotency, delivery: { text: prepared.text, from } }
-                : undefined;
-            const { mid } = appendSent(options.target, options.text, from, prepared.replyVia, receipt);
-            enqueue(options.target, receipt ? keyedPending(receipt, mid, receipt.delivery) : { mid, text: prepared.text, from });
-            result = { mid, replayed: false };
-        };
-        if (options.idempotency)
-            await withDeliveryLocks([options.target], accept);
-        else
-            await accept();
-    });
-    return result;
-}

package/node_modules/@spexcode/session-core/dist/record-lock.js

@@ -1,152 +0,0 @@
-import { closeSync, mkdirSync, openSync, readFileSync, unlinkSync, writeSync } from 'node:fs';
-import { join } from 'node:path';
-import { runtimeRoot } from '@spexcode/spec-core';
-const lockRoot = () => join(runtimeRoot(), '.session-locks');
-const lockPath = (id) => join(lockRoot(), `${id}.lock`);
-const syncPause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-export class SessionRecordLockTimeout extends Error {
-    constructor(id) {
-        super(`session ${id}: lifecycle transition lock timed out; refusing a stale write`);
-        this.name = 'SessionRecordLockTimeout';
-    }
-}
-function acquireSync(id, timeoutMs = 30_000) {
-    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 { /* another recovery already removed it */ } };
-        }
-        catch (error) {
-            if (error.code !== 'EEXIST')
-                throw error;
-            let owner = 0;
-            try {
-                owner = Number(readFileSync(path, 'utf8').trim()) || 0;
-            }
-            catch { /* race */ }
-            if (owner && owner !== process.pid) {
-                try {
-                    process.kill(owner, 0);
-                }
-                catch {
-                    try {
-                        unlinkSync(path);
-                    }
-                    catch { /* race */ }
-                    ;
-                    continue;
-                }
-            }
-            if (Date.now() >= deadline)
-                throw new SessionRecordLockTimeout(id);
-            syncPause(10);
-        }
-    }
-}
-const aborted = (signal) => signal.reason instanceof Error
-    ? signal.reason
-    : Object.assign(new Error('The operation was aborted'), { name: 'AbortError', code: 'ABORT_ERR' });
-async function pause(signal) {
-    if (!signal) {
-        await new Promise((resolve) => setTimeout(resolve, 10));
-        return;
-    }
-    if (signal.aborted)
-        throw aborted(signal);
-    await new Promise((resolve, reject) => {
-        const timer = setTimeout(done, 10);
-        const abort = () => { clearTimeout(timer); signal.removeEventListener('abort', abort); reject(aborted(signal)); };
-        function done() { signal.removeEventListener('abort', abort); resolve(); }
-        signal.addEventListener('abort', abort, { once: true });
-    });
-}
-async function acquire(id, timeoutMs = 30_000, signal) {
-    mkdirSync(lockRoot(), { recursive: true });
-    const path = lockPath(id), deadline = Date.now() + timeoutMs;
-    for (;;) {
-        if (signal?.aborted)
-            throw aborted(signal);
-        try {
-            const fd = openSync(path, 'wx');
-            writeSync(fd, String(process.pid));
-            closeSync(fd);
-            return () => { try {
-                unlinkSync(path);
-            }
-            catch { /* another recovery already removed it */ } };
-        }
-        catch (error) {
-            if (error.code !== 'EEXIST')
-                throw error;
-            let owner = 0;
-            try {
-                owner = Number(readFileSync(path, 'utf8').trim()) || 0;
-            }
-            catch { /* race */ }
-            if (owner && owner !== process.pid) {
-                try {
-                    process.kill(owner, 0);
-                }
-                catch {
-                    try {
-                        unlinkSync(path);
-                    }
-                    catch { /* race */ }
-                    ;
-                    continue;
-                }
-            }
-            if (Date.now() >= deadline)
-                throw new SessionRecordLockTimeout(id);
-            await pause(signal);
-        }
-    }
-}
-export async function withSessionRecordLock(id, body, signal) {
-    const release = await acquire(id, 30_000, signal);
-    try {
-        return await body();
-    }
-    finally {
-        release();
-    }
-}
-export function withSessionRecordLockSync(id, body) {
-    const release = acquireSync(id);
-    try {
-        return body();
-    }
-    finally {
-        release();
-    }
-}
-export function trySessionRecordLockSync(id) {
-    mkdirSync(lockRoot(), { recursive: true });
-    const path = lockPath(id);
-    try {
-        const fd = openSync(path, 'wx');
-        writeSync(fd, String(process.pid));
-        closeSync(fd);
-        return () => { try {
-            unlinkSync(path);
-        }
-        catch { /* another recovery already removed it */ } };
-    }
-    catch (error) {
-        if (error.code === 'EEXIST')
-            return null;
-        throw error;
-    }
-}
-export async function withSessionRecordLocks(rawIds, body, index = 0, ids = [...new Set(rawIds)].sort()) {
-    if (index >= ids.length)
-        return body();
-    return withSessionRecordLock(ids[index], () => withSessionRecordLocks(ids, body, index + 1, ids));
-}

package/node_modules/@spexcode/session-core/dist/runtime-session.d.ts

@@ -1,50 +0,0 @@
-import { type SessionLifecycle, type SessionProposal } from '@spexcode/spec-core';
-export type RuntimeSessionRegistration = {
-    sessionId: string;
-    runtimeOwner: string;
-    worktreePath: string;
-    branch: string | null;
-    parentSessionId?: string | null;
-    title?: string | null;
-    node?: string | null;
-    runtimeMetadata?: Record<string, string>;
-    createdAt?: number;
-};
-export type RuntimeSessionState = {
-    sessionId: string;
-    runtimeOwner: string;
-    revision: string;
-    runtimeState: string;
-    lifecycle: SessionLifecycle;
-    proposal?: SessionProposal | null;
-    note?: string | null;
-};
-export type RuntimeSessionRecord = {
-    sessionId: string;
-    runtimeOwner: string;
-    runtimeState: string | null;
-    revision: string | null;
-    worktreePath: string;
-    branch: string | null;
-    parentSessionId: string | null;
-    title: string | null;
-    node: string | null;
-    runtimeMetadata: Record<string, string>;
-    lifecycle: SessionLifecycle;
-    proposal: SessionProposal | null;
-    note: string | null;
-    createdAt: number;
-};
-export declare class RuntimeSessionConflict extends Error {
-    readonly code = "runtime_session_conflict";
-    constructor(message: string);
-}
-export declare function registerRuntimeSession(input: RuntimeSessionRegistration): Promise<{
-    replayed: boolean;
-}>;
-export declare function publishRuntimeSessionState(input: RuntimeSessionState): Promise<{
-    notified: string[];
-    replayed: boolean;
-}>;
-export declare function readRuntimeSession(sessionId: string): RuntimeSessionRecord | null;
-export declare function runtimeSessionChildren(parentSessionId: string, runtimeOwner?: string): RuntimeSessionRecord[];