spexcode 0.6.6 → 0.6.8

package/node_modules/@spexcode/session-application/dist/production.d.ts

@@ -0,0 +1,109 @@
+import { type Message, type MessageInput, type SessionProtocol } from '@spexcode/session-protocol';
+import { type SessionEvent, type SessionEventStore } from '@spexcode/session-events';
+import { type RuntimeBinding, type SessionRuntimeBindings } from '@spexcode/session-runtime';
+import { type SessionTopology, type TopologyEdge } from '@spexcode/session-topology';
+export interface LocalityPrecondition {
+    (databasePath: string): void;
+}
+export interface SessionState {
+    sessionId: string;
+    status: string;
+    proposal: string | null;
+    note: string | null;
+    parentSessionId: string | null;
+    updatedAtMs: number;
+}
+export interface SessionStateChange {
+    sessionId: string;
+    status: string;
+    proposal: string | null;
+    note: string | null;
+    previousProposal: string | null;
+    previousNote: string | null;
+    parentSessionId: string | null;
+    previousStatus: string | null;
+    previousParentSessionId: string | null;
+    reason: string | null;
+}
+export interface NativeRuntimeIdentity {
+    namespace: string;
+    runtimeKind: string;
+    nativeSessionId: string;
+    nativeStartToken: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ProjectSessionApplicationOptions {
+    databasePath: string;
+    locality: LocalityPrecondition;
+    now?: () => number;
+    onCommitted?: (result: Pick<CommittedSessionChange, 'recipients'>) => void;
+    /** Runtime binding is the event that makes an existing canonical delivery debt drainable. */
+    onRuntimeBound?: (sessionId: string) => void;
+}
+export interface CreateSessionInput {
+    sessionId: string;
+    status?: string;
+    parentSessionId?: string | null;
+    runtime?: NativeRuntimeIdentity;
+    eventId?: string;
+    updatedAtMs?: number;
+    proposal?: string | null;
+    note?: string | null;
+}
+export interface TransitionSessionInput {
+    status?: string;
+    proposal?: string | null;
+    note?: string | null;
+    parentSessionId?: string | null;
+    reason?: string | null;
+    /** An upstream policy may resolve recipients before this neutral transition. */
+    recipientSessionIds?: readonly string[];
+}
+export interface CommittedSessionChange {
+    state: SessionState;
+    event: SessionEvent;
+    edge: TopologyEdge | null;
+    recipients: string[];
+    messages: Message[];
+}
+export interface ConversationMessageInput {
+    text: string;
+    from: string | null;
+    replyVia?: 'note';
+}
+export interface ProductionSessionApplication extends SessionApplication {
+    readonly databasePath: string;
+    readonly protocol: SessionProtocol;
+    readonly topology: SessionTopology;
+    readonly events: SessionEventStore;
+    readonly runtimeBindings: SessionRuntimeBindings;
+    createSession(input: CreateSessionInput): SessionState;
+    transitionSession(sessionId: string, input: TransitionSessionInput): CommittedSessionChange;
+    enqueueMessage(sessionId: string, message: MessageInput): Message;
+    enqueueConversationMessage(sessionId: string, message: MessageInput, conversation: ConversationMessageInput): Message;
+    attachWatcher(watcherSessionId: string, subjectSessionId: string, channel?: string): TopologyEdge;
+    detachWatcher(watcherSessionId: string, subjectSessionId: string, channel?: string): TopologyEdge;
+    listWatchers(watcherSessionId: string, channel?: string): TopologyEdge[];
+    bindRuntime(sessionId: string, identity: NativeRuntimeIdentity, expectedGeneration?: number): RuntimeBinding;
+    resolveRuntime(sessionId: string, namespace: string): RuntimeBinding | null;
+    dequeueForRuntime(sessionId: string, namespace: string, expectedGeneration?: number, expectedMessageId?: string): Message | null;
+    readPendingMessages(sessionId: string): readonly Message[];
+    readMessageHistory(sessionId: string): readonly Message[];
+    dequeuePendingMessage(sessionId: string, expectedMessageId: string): Message | null;
+    readState(sessionId: string): SessionState | null;
+    readEvents(sessionId: string, afterSequence?: number): readonly SessionEvent[];
+    readFollowCursor(watcherSessionId: string, subjectSessionId: string): number | null;
+    advanceFollowCursor(watcherSessionId: string, subjectSessionId: string, eventSequence: number): void;
+    replayState(sessionId: string): SessionState | null;
+    close(): void;
+}
+export interface SessionApplication {
+    notifyRecipients(subjectSessionId: string, message: MessageInput): NotificationResult;
+    attachAndNotify(fromSessionId: string, subjectSessionId: string, relationType: string, message: MessageInput): NotificationResult;
+}
+export interface NotificationResult {
+    edge: TopologyEdge | null;
+    recipients: string[];
+    messages: Message[];
+}
+export declare function openProjectSessionApplication(options: ProjectSessionApplicationOptions): ProductionSessionApplication;

package/node_modules/@spexcode/session-application/dist/production.js

@@ -0,0 +1,438 @@
+import { randomBytes } from 'node:crypto';
+import { isAbsolute } from 'node:path';
+import { applyComponentMigrations, openProtocol, } from '@spexcode/session-protocol';
+import { encodeEventJson, openSessionEvents, } from '@spexcode/session-events';
+import { openRuntimeBindings, } from '@spexcode/session-runtime';
+import { openTopology } from '@spexcode/session-topology';
+import { SESSION_APPLICATION_MIGRATIONS } from './schema.js';
+const SESSION_ID = /^(?!-)[0-9A-Za-z_-]{1,256}$/;
+const STATUS = /^[0-9A-Za-z._:-]{1,64}$/;
+const STATE_EVENT = 'session.state.changed.v1';
+const MESSAGE_EVENT = 'session.message.sent.v1';
+const PARENT_RELATION = 'parent';
+const WATCH_RELATION = 'watch';
+const PARENT_WATCH_RELATION = 'watch:parent';
+const MANUAL_WATCH_RELATION = 'watch:manual';
+const compositions = new Map();
+const requirePath = (databasePath) => {
+    if (typeof databasePath !== 'string' || !isAbsolute(databasePath) || databasePath.startsWith('file:') || databasePath.includes('\0') || databasePath.endsWith('/')) {
+        throw new TypeError('session application requires an explicit absolute databasePath naming a file');
+    }
+};
+const requireId = (value, field) => {
+    if (typeof value !== 'string' || !SESSION_ID.test(value))
+        throw new TypeError(`${field} must be a valid protocol session id`);
+};
+const requireStatus = (value) => {
+    if (typeof value !== 'string' || !STATUS.test(value))
+        throw new TypeError('session status has an invalid grammar');
+};
+const eventId = () => randomBytes(16).toString('hex');
+const readStateInTransaction = (tx, sessionId) => {
+    const row = tx.query('SELECT session_id, status, proposal, note, parent_session_id, updated_at_ms FROM session_application_state WHERE session_id=?', sessionId)[0];
+    return row
+        ? {
+            sessionId: String(row.session_id),
+            status: String(row.status),
+            proposal: row.proposal === null ? null : String(row.proposal),
+            note: row.note === null ? null : String(row.note),
+            parentSessionId: row.parent_session_id === null ? null : String(row.parent_session_id),
+            updatedAtMs: Number(row.updated_at_ms),
+        }
+        : null;
+};
+const messageForEvent = (state, id) => ({
+    kind: STATE_EVENT,
+    body: encodeEventJson({
+        eventId: id,
+        sessionId: state.sessionId,
+        status: state.status,
+        proposal: state.proposal,
+        note: state.note,
+        previousProposal: state.previousProposal,
+        previousNote: state.previousNote,
+        parentSessionId: state.parentSessionId,
+        previousStatus: state.previousStatus,
+        previousParentSessionId: state.previousParentSessionId,
+        reason: state.reason,
+    }),
+    senderSessionId: state.sessionId,
+    idempotencyKey: id,
+});
+export function openProjectSessionApplication(options) {
+    requirePath(options.databasePath);
+    if (typeof options.locality !== 'function')
+        throw new TypeError('session application requires a locality precondition');
+    options.locality(options.databasePath);
+    const existing = compositions.get(options.databasePath);
+    if (existing)
+        return existing;
+    const protocol = openProtocolOnce(options.databasePath, options.now);
+    applyComponentMigrations(protocol, 'session-application', SESSION_APPLICATION_MIGRATIONS);
+    const topology = openTopology(protocol);
+    const events = openSessionEvents(protocol);
+    const runtimeBindings = openRuntimeBindings(protocol);
+    const now = options.now ?? (() => Date.now());
+    const initialized = new Set();
+    const initialize = (sessionId) => {
+        requireId(sessionId, 'sessionId');
+        if (!initialized.has(sessionId)) {
+            protocol.initialize(sessionId);
+            initialized.add(sessionId);
+        }
+    };
+    const notifyCommitted = (result) => {
+        options.onCommitted?.(result);
+    };
+    // Parent supervision is intentionally quiet for routine active/working transitions. A manual watch
+    // opts into the complete feed; when both sources exist, the union keeps that manual choice without
+    // enqueueing the same watcher twice. Creation still publishes its initial snapshot through the normal
+    // relation recipients; this filter governs later lifecycle transitions only. A queued creation snapshot is
+    // corrected once by the first ready active publication, otherwise parent-only supervision would retain the
+    // stale queued face forever.
+    const lifecycleRecipients = (subjectSessionId, previousStatus, status, tx) => {
+        const recipients = new Set();
+        for (const edge of topology.parents(subjectSessionId, undefined, tx)) {
+            const parentOnly = edge.relationType === PARENT_WATCH_RELATION;
+            const manual = edge.relationType === MANUAL_WATCH_RELATION || edge.relationType === WATCH_RELATION;
+            if (manual || (parentOnly && (status !== 'active' || previousStatus === 'queued')))
+                recipients.add(edge.fromSessionId);
+        }
+        return [...recipients].sort();
+    };
+    const app = {
+        databasePath: options.databasePath,
+        protocol,
+        topology,
+        events,
+        runtimeBindings,
+        notifyRecipients(subjectSessionId, message) {
+            const result = protocol.withTransaction(tx => {
+                const recipients = topology.recipients(subjectSessionId, tx);
+                const messages = recipients.map(recipient => tx.enqueue(recipient, {
+                    ...message,
+                    senderSessionId: message.senderSessionId === undefined ? subjectSessionId : message.senderSessionId,
+                }));
+                return { edge: null, recipients, messages };
+            });
+            notifyCommitted(result);
+            return result;
+        },
+        attachAndNotify(fromSessionId, subjectSessionId, relationType, message) {
+            const result = protocol.withTransaction(tx => {
+                const edge = topology.attach(tx, fromSessionId, subjectSessionId, relationType);
+                const recipients = topology.recipients(subjectSessionId, tx);
+                const messages = recipients.map(recipient => tx.enqueue(recipient, {
+                    ...message,
+                    senderSessionId: message.senderSessionId === undefined ? subjectSessionId : message.senderSessionId,
+                }));
+                return { edge, recipients, messages };
+            });
+            notifyCommitted(result);
+            return result;
+        },
+        createSession(input) {
+            requireId(input.sessionId, 'sessionId');
+            const status = input.status ?? 'created';
+            requireStatus(status);
+            const proposal = input.proposal ?? null;
+            const note = input.note ?? null;
+            const parentSessionId = input.parentSessionId ?? null;
+            if (parentSessionId !== null)
+                requireId(parentSessionId, 'parentSessionId');
+            initialize(input.sessionId);
+            if (parentSessionId)
+                initialize(parentSessionId);
+            const created = protocol.withTransaction(tx => {
+                if (readStateInTransaction(tx, input.sessionId)) {
+                    throw new Error(`session application state already exists: ${input.sessionId}`);
+                }
+                let edge = null;
+                if (parentSessionId)
+                    edge = topology.attach(tx, parentSessionId, input.sessionId, PARENT_RELATION);
+                const updatedAtMs = input.updatedAtMs ?? now();
+                tx.exec('INSERT INTO session_application_state(session_id,status,proposal,note,parent_session_id,updated_at_ms) VALUES(?,?,?,?,?,?)', input.sessionId, status, proposal, note, parentSessionId, updatedAtMs);
+                const id = input.eventId ?? eventId();
+                const change = {
+                    sessionId: input.sessionId,
+                    status,
+                    proposal,
+                    note,
+                    previousProposal: null,
+                    previousNote: null,
+                    parentSessionId,
+                    previousStatus: null,
+                    previousParentSessionId: null,
+                    reason: 'create',
+                };
+                const event = events.append(tx, {
+                    eventId: id,
+                    type: STATE_EVENT,
+                    schemaVersion: 1,
+                    subjectSessionId: input.sessionId,
+                    payload: encodeEventJson(change),
+                    occurredAtMs: updatedAtMs,
+                });
+                const recipients = topology.recipients(input.sessionId, tx);
+                const messages = recipients.map(recipient => tx.enqueue(recipient, messageForEvent(change, id)));
+                let runtime = null;
+                if (input.runtime) {
+                    runtime = runtimeBindings.bind(tx, input.sessionId, input.runtime);
+                }
+                return {
+                    state: { sessionId: input.sessionId, status, proposal, note, parentSessionId, updatedAtMs },
+                    event,
+                    edge,
+                    recipients,
+                    messages,
+                    runtime,
+                };
+            });
+            const result = {
+                state: created.state,
+                event: created.event,
+                edge: created.edge,
+                recipients: created.recipients,
+                messages: created.messages,
+            };
+            notifyCommitted(result);
+            return created.state;
+        },
+        transitionSession(sessionId, input) {
+            requireId(sessionId, 'sessionId');
+            const nextStatus = input.status;
+            if (nextStatus !== undefined)
+                requireStatus(nextStatus);
+            if (input.parentSessionId !== undefined && input.parentSessionId !== null)
+                requireId(input.parentSessionId, 'parentSessionId');
+            if (input.parentSessionId === sessionId)
+                throw new TypeError('a session cannot be its own parent');
+            if (input.parentSessionId)
+                initialize(input.parentSessionId);
+            const result = protocol.withTransaction(tx => {
+                const current = readStateInTransaction(tx, sessionId);
+                if (!current) {
+                    throw new Error(`session application state is missing: ${sessionId}`);
+                }
+                const status = nextStatus ?? current.status;
+                const proposal = input.proposal === undefined ? current.proposal : input.proposal;
+                const note = input.note === undefined ? current.note : input.note;
+                const parentSessionId = input.parentSessionId === undefined ? current.parentSessionId : input.parentSessionId;
+                let edge = null;
+                if (parentSessionId !== current.parentSessionId) {
+                    if (parentSessionId && current.parentSessionId)
+                        edge = topology.reparent(tx, sessionId, parentSessionId, PARENT_RELATION);
+                    else if (parentSessionId)
+                        edge = topology.attach(tx, parentSessionId, sessionId, PARENT_RELATION);
+                    else if (current.parentSessionId) {
+                        const former = topology.parents(sessionId, PARENT_RELATION, tx)[0];
+                        if (former)
+                            topology.detach(tx, former.edgeId);
+                    }
+                }
+                const updatedAtMs = now();
+                tx.exec('UPDATE session_application_state SET status=?, proposal=?, note=?, parent_session_id=?, updated_at_ms=? WHERE session_id=?', status, proposal, note, parentSessionId, updatedAtMs, sessionId);
+                const id = eventId();
+                const change = {
+                    sessionId,
+                    status,
+                    proposal,
+                    note,
+                    previousProposal: current.proposal,
+                    previousNote: current.note,
+                    parentSessionId,
+                    previousStatus: current.status,
+                    previousParentSessionId: current.parentSessionId,
+                    reason: input.reason ?? null,
+                };
+                const event = events.append(tx, {
+                    eventId: id,
+                    type: STATE_EVENT,
+                    schemaVersion: 1,
+                    subjectSessionId: sessionId,
+                    payload: encodeEventJson(change),
+                    occurredAtMs: updatedAtMs,
+                });
+                const recipients = input.recipientSessionIds === undefined
+                    ? lifecycleRecipients(sessionId, current.status, status, tx)
+                    : [...new Set(input.recipientSessionIds.map(recipient => {
+                            requireId(recipient, 'recipientSessionId');
+                            return recipient;
+                        }))];
+                const messages = recipients.map(recipient => tx.enqueue(recipient, messageForEvent(change, id)));
+                return {
+                    state: { sessionId, status, proposal, note, parentSessionId, updatedAtMs },
+                    event,
+                    edge,
+                    recipients,
+                    messages,
+                };
+            });
+            notifyCommitted(result);
+            return result;
+        },
+        enqueueMessage(sessionId, message) {
+            requireId(sessionId, 'sessionId');
+            initialize(sessionId);
+            return protocol.withTransaction(tx => tx.enqueue(sessionId, message));
+        },
+        enqueueConversationMessage(sessionId, message, conversation) {
+            requireId(sessionId, 'sessionId');
+            if (!conversation || typeof conversation.text !== 'string' || conversation.text.length === 0) {
+                throw new TypeError('conversation message requires non-empty text');
+            }
+            if (conversation.from !== null && typeof conversation.from !== 'string') {
+                throw new TypeError('conversation message from must be a session id or null');
+            }
+            initialize(sessionId);
+            return protocol.withTransaction(tx => {
+                const queued = tx.enqueue(sessionId, message);
+                const recorded = events.hasMessageEvent(tx, sessionId, queued.messageId);
+                if (!recorded) {
+                    events.append(tx, {
+                        eventId: eventId(),
+                        type: MESSAGE_EVENT,
+                        schemaVersion: 1,
+                        subjectSessionId: sessionId,
+                        payload: encodeEventJson({
+                            messageId: queued.messageId,
+                            text: conversation.text,
+                            from: conversation.from,
+                            ...(conversation.replyVia ? { replyVia: conversation.replyVia } : {}),
+                        }),
+                        occurredAtMs: queued.enqueuedAtMs,
+                    });
+                }
+                return queued;
+            });
+        },
+        attachWatcher(watcherSessionId, subjectSessionId, channel = WATCH_RELATION) {
+            requireId(watcherSessionId, 'watcherSessionId');
+            requireId(subjectSessionId, 'subjectSessionId');
+            initialize(watcherSessionId);
+            initialize(subjectSessionId);
+            return protocol.withTransaction(tx => topology.subscribe(tx, watcherSessionId, subjectSessionId, channel));
+        },
+        detachWatcher(watcherSessionId, subjectSessionId, channel = WATCH_RELATION) {
+            requireId(watcherSessionId, 'watcherSessionId');
+            requireId(subjectSessionId, 'subjectSessionId');
+            return protocol.withTransaction(tx => topology.unsubscribe(tx, watcherSessionId, subjectSessionId, channel));
+        },
+        listWatchers(watcherSessionId, channel = WATCH_RELATION) {
+            requireId(watcherSessionId, 'watcherSessionId');
+            return topology.subscriptions(watcherSessionId).filter(edge => edge.relationType === channel);
+        },
+        bindRuntime(sessionId, identity, expectedGeneration) {
+            requireId(sessionId, 'sessionId');
+            initialize(sessionId);
+            const binding = protocol.withTransaction(tx => runtimeBindings.bind(tx, sessionId, identity, { expectedGeneration }));
+            options.onRuntimeBound?.(sessionId);
+            return binding;
+        },
+        resolveRuntime(sessionId, namespace) {
+            requireId(sessionId, 'sessionId');
+            return runtimeBindings.resolve(namespace, sessionId);
+        },
+        dequeueForRuntime(sessionId, namespace, expectedGeneration, expectedMessageId) {
+            requireId(sessionId, 'sessionId');
+            const binding = runtimeBindings.resolve(namespace, sessionId);
+            if (!binding || binding.status !== 'bound')
+                throw new Error(`runtime binding is not active for ${sessionId}`);
+            if (expectedGeneration !== undefined && binding.bindingGeneration !== expectedGeneration) {
+                throw new Error(`runtime binding generation is stale for ${sessionId}`);
+            }
+            if (expectedMessageId !== undefined && protocol.listPending(sessionId)[0]?.messageId !== expectedMessageId)
+                return null;
+            return protocol.dequeue(sessionId);
+        },
+        readPendingMessages(sessionId) {
+            requireId(sessionId, 'sessionId');
+            return protocol.listPending(sessionId);
+        },
+        readMessageHistory(sessionId) {
+            requireId(sessionId, 'sessionId');
+            return protocol.readMessages(sessionId);
+        },
+        dequeuePendingMessage(sessionId, expectedMessageId) {
+            requireId(sessionId, 'sessionId');
+            requireId(expectedMessageId, 'expectedMessageId');
+            const head = protocol.listPending(sessionId)[0];
+            if (!head || head.messageId !== expectedMessageId)
+                return null;
+            return protocol.dequeue(sessionId);
+        },
+        readState(sessionId) {
+            requireId(sessionId, 'sessionId');
+            const state = protocol.withTransaction(tx => readStateInTransaction(tx, sessionId));
+            return state;
+        },
+        readEvents(sessionId, afterSequence) {
+            requireId(sessionId, 'sessionId');
+            return events.read(sessionId, afterSequence === undefined ? undefined : { afterSequence });
+        },
+        readFollowCursor(watcherSessionId, subjectSessionId) {
+            requireId(watcherSessionId, 'watcherSessionId');
+            requireId(subjectSessionId, 'subjectSessionId');
+            const rows = protocol.withTransaction(tx => tx.query('SELECT event_seq FROM session_follow_cursors WHERE watcher_session_id=? AND subject_session_id=?', watcherSessionId, subjectSessionId));
+            const value = rows[0]?.event_seq;
+            return value === undefined ? null : Number(value);
+        },
+        advanceFollowCursor(watcherSessionId, subjectSessionId, eventSequence) {
+            requireId(watcherSessionId, 'watcherSessionId');
+            requireId(subjectSessionId, 'subjectSessionId');
+            if (!Number.isSafeInteger(eventSequence) || eventSequence < 0)
+                throw new TypeError('eventSequence must be a non-negative safe integer');
+            protocol.withTransaction(tx => {
+                const prior = tx.query('SELECT event_seq FROM session_follow_cursors WHERE watcher_session_id=? AND subject_session_id=?', watcherSessionId, subjectSessionId)[0]?.event_seq;
+                if (prior !== undefined && Number(prior) >= eventSequence)
+                    return;
+                tx.exec(`INSERT INTO session_follow_cursors (watcher_session_id, subject_session_id, event_seq)
+           VALUES (?, ?, ?)
+           ON CONFLICT(watcher_session_id, subject_session_id) DO UPDATE SET event_seq=excluded.event_seq`, watcherSessionId, subjectSessionId, eventSequence);
+            });
+        },
+        replayState(sessionId) {
+            requireId(sessionId, 'sessionId');
+            initialize(sessionId);
+            return events.replay(sessionId, {
+                initialState: null,
+                reducers: {
+                    // A conversation message is a public fact beside the state fold, not a state transition.
+                    [MESSAGE_EVENT]: state => state,
+                    [STATE_EVENT]: (_state, event) => {
+                        const decoded = JSON.parse(new TextDecoder().decode(event.payload));
+                        return {
+                            sessionId: decoded.sessionId,
+                            status: decoded.status,
+                            proposal: decoded.proposal ?? null,
+                            note: decoded.note ?? null,
+                            parentSessionId: decoded.parentSessionId,
+                            updatedAtMs: event.occurredAtMs,
+                        };
+                    },
+                },
+            });
+        },
+        close() {
+            compositions.delete(options.databasePath);
+            closeProtocol(options.databasePath, protocol);
+        },
+    };
+    compositions.set(options.databasePath, app);
+    return app;
+}
+const protocols = new Map();
+function openProtocolOnce(databasePath, now) {
+    const existing = protocols.get(databasePath);
+    if (existing)
+        return existing;
+    const protocol = openProtocol(databasePath, now ? { now } : undefined);
+    protocols.set(databasePath, protocol);
+    return protocol;
+}
+function closeProtocol(databasePath, protocol) {
+    if (protocols.get(databasePath) !== protocol)
+        return;
+    protocols.delete(databasePath);
+    protocol.close();
+}

package/node_modules/@spexcode/session-application/dist/schema.d.ts

@@ -0,0 +1,2 @@
+import type { ComponentMigration } from '@spexcode/session-protocol';
+export declare const SESSION_APPLICATION_MIGRATIONS: readonly ComponentMigration[];

package/node_modules/@spexcode/session-application/dist/schema.js

@@ -0,0 +1,39 @@
+export const SESSION_APPLICATION_MIGRATIONS = [
+    {
+        version: 1,
+        sql: `
+CREATE TABLE session_application_state (
+  session_id         TEXT    NOT NULL PRIMARY KEY REFERENCES protocol_sessions(session_id),
+  status             TEXT    NOT NULL,
+  parent_session_id  TEXT    REFERENCES protocol_sessions(session_id),
+  updated_at_ms      INTEGER NOT NULL,
+  CHECK (length(status) BETWEEN 1 AND 64),
+  CHECK (status NOT GLOB '*[^0-9A-Za-z._:-]*'),
+  CHECK (updated_at_ms >= 0),
+  CHECK (parent_session_id IS NULL OR parent_session_id <> session_id)
+) STRICT;
+
+CREATE INDEX session_application_state_parent
+  ON session_application_state (parent_session_id, session_id);
+`,
+    },
+    {
+        version: 2,
+        sql: `
+ALTER TABLE session_application_state ADD COLUMN proposal TEXT;
+ALTER TABLE session_application_state ADD COLUMN note TEXT;
+`,
+    },
+    {
+        version: 3,
+        sql: `
+CREATE TABLE session_follow_cursors (
+  watcher_session_id TEXT NOT NULL REFERENCES protocol_sessions(session_id),
+  subject_session_id TEXT NOT NULL REFERENCES protocol_sessions(session_id),
+  event_seq         INTEGER NOT NULL,
+  PRIMARY KEY (watcher_session_id, subject_session_id),
+  CHECK (event_seq >= 0)
+) STRICT;
+`,
+    },
+];

package/node_modules/@spexcode/session-application/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@spexcode/session-application",
+  "version": "0.6.8",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "description": "Adopter-owned composition of session protocol and topology transactions.",
+  "files": ["dist"],
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "engines": { "node": ">=22" },
+  "scripts": {
+    "build": "node ../../scripts/build-dist.mjs",
+    "prepublishOnly": "node ../../scripts/release-publish.mjs --from-package-publish",
+    "test": "npm run build && tsx --import ../../scripts/test-home.mjs --test src/*.test.ts"
+  },
+  "dependencies": {
+    "@spexcode/session-events": "0.6.8",
+    "@spexcode/session-protocol": "0.6.8",
+    "@spexcode/session-runtime": "0.6.8",
+    "@spexcode/session-topology": "0.6.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.16.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}

package/node_modules/@spexcode/session-events/dist/errors.d.ts

@@ -0,0 +1,6 @@
+export type SessionEventErrorCode = 'EVENT_TRANSACTION_INVALID' | 'EVENT_SESSION_ID_INVALID' | 'EVENT_SESSION_UNKNOWN' | 'EVENT_ID_INVALID' | 'EVENT_ID_EXISTS' | 'EVENT_TYPE_INVALID' | 'EVENT_SCHEMA_VERSION_INVALID' | 'EVENT_PAYLOAD_INVALID' | 'EVENT_TIMESTAMP_INVALID' | 'EVENT_SEQUENCE_INVALID' | 'EVENT_TYPE_UNKNOWN' | 'EVENT_JSON_INVALID' | 'EVENT_STORAGE';
+export declare class SessionEventError extends Error {
+    readonly code: SessionEventErrorCode;
+    constructor(code: SessionEventErrorCode, message: string, cause?: unknown);
+}
+export declare function failSessionEvent(code: SessionEventErrorCode, message: string, cause?: unknown): never;

package/node_modules/@spexcode/session-events/dist/errors.js

@@ -0,0 +1,11 @@
+export class SessionEventError extends Error {
+    code;
+    constructor(code, message, cause) {
+        super(message, { cause });
+        this.name = 'SessionEventError';
+        this.code = code;
+    }
+}
+export function failSessionEvent(code, message, cause) {
+    throw new SessionEventError(code, message, cause);
+}