spexcode 0.6.5 → 0.6.7

package/node_modules/@spexcode/{spec-cli → session-core}/dist/delivery-queue.d.ts

@@ -2,8 +2,9 @@ export type PendingMessage = {
     mid: string;
     text: string;
     from: string | null;
+    attributes?: Record<string, string>;
     dispatch?: {
-        operation: 'merge';
+        operation: string;
         requestDigest: string;
     };
 };

package/node_modules/@spexcode/{spec-cli → session-core}/dist/delivery-queue.js

@@ -1,6 +1,7 @@
 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);
@@ -62,14 +63,24 @@ function read(id) {
         return raw.filter((m) => !!m && typeof m === 'object'
             && typeof m.mid === 'string'
             && typeof m.text === 'string'
+            && (m.attributes === undefined
+                || (!!m.attributes
+                    && typeof m.attributes === 'object'
+                    && !Array.isArray(m.attributes)
+                    && Object.values(m.attributes).every((value) => typeof value === 'string')))
             && (m.dispatch === undefined
-                || (m.dispatch?.operation === 'merge'
+                || (typeof m.dispatch?.operation === 'string'
                     && typeof m.dispatch?.requestDigest === 'string')));
     }
     catch {
         return [];
     } // absent, empty, or unparseable all mean the honest thing: nothing owed
 }
+function sameAttributes(left, right) {
+    const leftEntries = Object.entries(left ?? {}).sort(([a], [b]) => a.localeCompare(b));
+    const rightEntries = Object.entries(right ?? {}).sort(([a], [b]) => a.localeCompare(b));
+    return JSON.stringify(leftEntries) === JSON.stringify(rightEntries);
+}
 // 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) {
@@ -160,7 +171,23 @@ export async function drain(id, insert, timeoutMs = 5_000) {
             }
             let ok = false;
             try {
-                ok = await insert(queued[0]);
+                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
+                        || !sameAttributes(receipt.delivery.attributes, head.attributes))
+                        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;

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

@@ -0,0 +1,5 @@
+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, runtimeSessionNotification, runtimeSessionChildren, RuntimeSessionConflict, type RuntimeSessionRecord, type RuntimeSessionNotification, 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

@@ -0,0 +1,5 @@
+export { acceptMessage, MessageKeyConflict } from './message.js';
+export { drain, owesDelivery, pendingMessages } from './delivery-queue.js';
+export { publishRuntimeSessionState, readRuntimeSession, registerRuntimeSession, runtimeSessionNotification, 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

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,22 @@
+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

@@ -0,0 +1,53 @@
+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,
+    ...(delivery.attributes ? { attributes: delivery.attributes } : {}),
+    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.d.ts

@@ -0,0 +1,7 @@
+export declare class SessionRecordLockTimeout extends Error {
+    constructor(id: string);
+}
+export declare function withSessionRecordLock<T>(id: string, body: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+export declare function withSessionRecordLockSync<T>(id: string, body: () => T): T;
+export declare function trySessionRecordLockSync(id: string): (() => void) | null;
+export declare function withSessionRecordLocks<T>(rawIds: string[], body: () => Promise<T>, index?: number, ids?: string[]): Promise<T>;

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

@@ -0,0 +1,152 @@
+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

@@ -0,0 +1,62 @@
+import { type SessionLifecycle, type SessionProposal } from '@spexcode/spec-core';
+import { type PendingMessage } from './delivery-queue.js';
+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 type RuntimeSessionNotification = {
+    childSessionId: string;
+    runtimeOwner: string;
+    runtimeState: string;
+    revision: string;
+    lifecycle: SessionLifecycle;
+    proposal: SessionProposal | null;
+    note: string | null;
+    runtimeMetadata: Record<string, string>;
+};
+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 runtimeSessionNotification(parentSessionId: string, message: PendingMessage): RuntimeSessionNotification | null;
+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[];