@pellux/goodvibes-sdk 0.18.3 → 0.18.11

package/dist/platform/sessions/orchestration/registry.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Multi-session Orchestration — Cross-Session Task Registry
+ *
+ * Wraps SessionTaskGraph with persistence to
+ * `.goodvibes/sdk/sessions/task-graph.json` and reconnect/resume hydration.
+ *
+ * The registry is the single authoritative source for the cross-session task
+ * graph within a process. Command handlers and sync integrations receive an
+ * owned instance from the runtime service graph.
+ */
+import type { CrossSessionTaskRef, TaskHandoffRecord, CancellationRequest, CancellationResult, SessionTaskGraphSnapshot } from './types.js';
+import type { TaskLifecycleState } from '../../runtime/store/domains/tasks.js';
+/**
+ * CrossSessionTaskRegistry — persistent wrapper around `SessionTaskGraph`.
+ *
+ * Responsibilities:
+ * - Load the graph from disk on construction (reconnect/resume hydration).
+ * - Flush the graph to disk after every mutation.
+ * - Expose a stable interface for command handlers and sync adapters.
+ * - Generate unique handoff IDs.
+ */
+export declare class CrossSessionTaskRegistry {
+    private readonly _graph;
+    private readonly _graphPath;
+    private readonly _dir;
+    private _dirEnsured;
+    private _flushTimer;
+    _exitHandler: (() => void) | null;
+    /**
+     * @param baseDir - Project base directory.
+     *   The graph is persisted at `<baseDir>/.goodvibes/sdk/sessions/task-graph.json`.
+     */
+    constructor(baseDir: string);
+    /**
+     * Link a task into the global graph — registers the task as a
+     * cross-session ref and optionally adds a dependency edge.
+     *
+     * @param ref - The task ref to link.
+     * @param dependsOn - Optional ref this task depends on.
+     * @param reason - Optional reason for the dependency edge.
+     * @returns Result of the link operation.
+     */
+    linkTask(ref: CrossSessionTaskRef, dependsOn?: {
+        sessionId: string;
+        taskId: string;
+    }, reason?: string): {
+        ok: boolean;
+        error?: string;
+    };
+    /**
+     * Update the status of a task ref.
+     *
+     * @param sessionId - Owning session.
+     * @param taskId - Target task.
+     * @param status - New lifecycle status.
+     * @returns `true` if the status changed and was flushed.
+     */
+    propagateStatus(sessionId: string, taskId: string, status: TaskLifecycleState): boolean;
+    /**
+     * Look up a ref by session + task ID.
+     */
+    getRef(sessionId: string, taskId: string): CrossSessionTaskRef | undefined;
+    /**
+     * Return all refs in the graph.
+     */
+    getAllRefs(): CrossSessionTaskRef[];
+    /**
+     * Return all refs for a given session.
+     */
+    getRefsBySession(sessionId: string): CrossSessionTaskRef[];
+    /**
+     * Return all direct dependencies of a task.
+     */
+    getDependencies(sessionId: string, taskId: string): CrossSessionTaskRef[];
+    /**
+     * Return all direct dependents of a task.
+     */
+    getDependents(sessionId: string, taskId: string): CrossSessionTaskRef[];
+    /**
+     * Initiate a task handoff from one session to another.
+     *
+     * Both sessions must have their task refs registered before calling this.
+     * The originating task ref status is updated to 'blocked' (awaiting handoff).
+     *
+     * @param taskRef - The task being handed off.
+     * @param fromSessionId - Source session.
+     * @param toSessionId - Destination session.
+     * @param reason - Optional human-readable reason.
+     * @returns Result of the handoff operation.
+     */
+    initiateHandoff(taskRef: {
+        sessionId: string;
+        taskId: string;
+    }, fromSessionId: string, toSessionId: string, reason?: string): {
+        ok: boolean;
+        handoffId?: string;
+        error?: string;
+    };
+    /**
+     * Acknowledge a handoff from the destination session.
+     *
+     * @param handoffId - The handoff to acknowledge.
+     * @returns `true` if the handoff was found and acknowledged.
+     */
+    acknowledgeHandoff(handoffId: string): boolean;
+    /**
+     * Return all handoff records.
+     */
+    getHandoffs(): TaskHandoffRecord[];
+    /**
+     * Apply a scoped cancellation to the graph.
+     *
+     * @param request - The cancellation request.
+     * @returns Result describing what was cancelled and what was skipped.
+     */
+    cancel(request: CancellationRequest): CancellationResult;
+    /**
+     * Take a snapshot of the current graph state.
+     * Suitable for display (e.g. `/session graph`).
+     */
+    snapshot(): SessionTaskGraphSnapshot;
+    /**
+     * Force a synchronous flush to disk.
+     * Use on shutdown/dispose to ensure all pending data is written.
+     */
+    flush(): void;
+    /**
+     * Release process-level resources held by the registry.
+     *
+     * Safe to call multiple times. Flushes pending state before detaching the
+     * process exit handler.
+     */
+    dispose(): void;
+    /**
+     * Load the persisted graph from disk and hydrate the in-memory graph.
+     * Non-fatal: if the file is missing or malformed, the graph starts empty.
+     */
+    private _load;
+    /**
+     * Flush the current graph snapshot to disk.
+     * Non-fatal: if the write fails, logs a debug message and continues.
+     */
+    private _flush;
+    /** Schedule a debounced async write (coalesces rapid successive mutations). */
+    private _scheduledFlush;
+    /** Perform a synchronous write — used by shutdown/dispose and flush(). */
+    private _flushSync;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/platform/sessions/orchestration/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../../src/platform/sessions/orchestration/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAQ/E;;;;;;;;GAQG;AACH,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,WAAW,CAA8C;IACjE,YAAY,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAQ;IAEzC;;;OAGG;gBACgB,OAAO,EAAE,MAAM;IAiBlC;;;;;;;;OAQG;IACI,QAAQ,CACb,GAAG,EAAE,mBAAmB,EACxB,SAAS,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EACjD,MAAM,CAAC,EAAE,MAAM,GACd;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IAmBlC;;;;;;;OAOG;IACI,eAAe,CACpB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,kBAAkB,GACzB,OAAO;IAMV;;OAEG;IACI,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS;IAIjF;;OAEG;IACI,UAAU,IAAI,mBAAmB,EAAE;IAI1C;;OAEG;IACI,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,EAAE;IAIjE;;OAEG;IACI,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,mBAAmB,EAAE;IAIhF;;OAEG;IACI,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,mBAAmB,EAAE;IAM9E;;;;;;;;;;;OAWG;IACI,eAAe,CACpB,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAC9C,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,MAAM,GACd;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IA8BtD;;;;;OAKG;IACI,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAMrD;;OAEG;IACI,WAAW,IAAI,iBAAiB,EAAE;IAMzC;;;;;OAKG;IACI,MAAM,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB;IAQ/D;;;OAGG;IACI,QAAQ,IAAI,wBAAwB;IAI3C;;;OAGG;IACI,KAAK,IAAI,IAAI;IAQpB;;;;;OAKG;IACI,OAAO,IAAI,IAAI;IAUtB;;;OAGG;IACH,OAAO,CAAC,KAAK;IA4Bb;;;OAGG;IACH,OAAO,CAAC,MAAM;IAId,+EAA+E;IAC/E,OAAO,CAAC,eAAe;IAmBvB,0EAA0E;IAC1E,OAAO,CAAC,UAAU;CAgBnB"}

package/dist/platform/sessions/orchestration/registry.js

@@ -0,0 +1,299 @@
+/**
+ * Multi-session Orchestration — Cross-Session Task Registry
+ *
+ * Wraps SessionTaskGraph with persistence to
+ * `.goodvibes/sdk/sessions/task-graph.json` and reconnect/resume hydration.
+ *
+ * The registry is the single authoritative source for the cross-session task
+ * graph within a process. Command handlers and sync integrations receive an
+ * owned instance from the runtime service graph.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { writeFile } from 'node:fs/promises';
+import { join } from 'path';
+import { logger } from '../../utils/logger.js';
+import { SessionTaskGraph } from './graph.js';
+import { makeRefKey } from './types.js';
+import { summarizeError } from '../../utils/error-display.js';
+/** Current schema version for the persisted graph file. */
+const GRAPH_SCHEMA_VERSION = 1;
+// ── CrossSessionTaskRegistry ──────────────────────────────────────────────────
+/**
+ * CrossSessionTaskRegistry — persistent wrapper around `SessionTaskGraph`.
+ *
+ * Responsibilities:
+ * - Load the graph from disk on construction (reconnect/resume hydration).
+ * - Flush the graph to disk after every mutation.
+ * - Expose a stable interface for command handlers and sync adapters.
+ * - Generate unique handoff IDs.
+ */
+export class CrossSessionTaskRegistry {
+    _graph;
+    _graphPath;
+    _dir;
+    _dirEnsured = false;
+    _flushTimer = null;
+    _exitHandler = null;
+    /**
+     * @param baseDir - Project base directory.
+     *   The graph is persisted at `<baseDir>/.goodvibes/sdk/sessions/task-graph.json`.
+     */
+    constructor(baseDir) {
+        this._dir = join(baseDir, '.goodvibes', 'sdk', 'sessions');
+        this._graphPath = join(this._dir, 'task-graph.json');
+        this._graph = new SessionTaskGraph();
+        this._load();
+        this._exitHandler = () => {
+            if (this._flushTimer) {
+                clearTimeout(this._flushTimer);
+                this._flushTimer = null;
+                this._flushSync();
+            }
+        };
+        process.on('exit', this._exitHandler);
+    }
+    // ── Task ref operations ───────────────────────────────────────────────────────
+    /**
+     * Link a task into the global graph — registers the task as a
+     * cross-session ref and optionally adds a dependency edge.
+     *
+     * @param ref - The task ref to link.
+     * @param dependsOn - Optional ref this task depends on.
+     * @param reason - Optional reason for the dependency edge.
+     * @returns Result of the link operation.
+     */
+    linkTask(ref, dependsOn, reason) {
+        this._graph.upsertRef(ref);
+        if (dependsOn) {
+            const edgeResult = this._graph.addEdge({ sessionId: ref.sessionId, taskId: ref.taskId }, dependsOn, reason);
+            if (!edgeResult.ok) {
+                this._flush();
+                return { ok: false, error: edgeResult.error };
+            }
+        }
+        this._flush();
+        return { ok: true };
+    }
+    /**
+     * Update the status of a task ref.
+     *
+     * @param sessionId - Owning session.
+     * @param taskId - Target task.
+     * @param status - New lifecycle status.
+     * @returns `true` if the status changed and was flushed.
+     */
+    propagateStatus(sessionId, taskId, status) {
+        const changed = this._graph.propagateStatus(sessionId, taskId, status);
+        if (changed)
+            this._flush();
+        return changed;
+    }
+    /**
+     * Look up a ref by session + task ID.
+     */
+    getRef(sessionId, taskId) {
+        return this._graph.getRef(sessionId, taskId);
+    }
+    /**
+     * Return all refs in the graph.
+     */
+    getAllRefs() {
+        return this._graph.getAllRefs();
+    }
+    /**
+     * Return all refs for a given session.
+     */
+    getRefsBySession(sessionId) {
+        return this._graph.getRefsBySession(sessionId);
+    }
+    /**
+     * Return all direct dependencies of a task.
+     */
+    getDependencies(sessionId, taskId) {
+        return this._graph.getDependencies(sessionId, taskId);
+    }
+    /**
+     * Return all direct dependents of a task.
+     */
+    getDependents(sessionId, taskId) {
+        return this._graph.getDependents(sessionId, taskId);
+    }
+    // ── Handoff operations ────────────────────────────────────────────────────────
+    /**
+     * Initiate a task handoff from one session to another.
+     *
+     * Both sessions must have their task refs registered before calling this.
+     * The originating task ref status is updated to 'blocked' (awaiting handoff).
+     *
+     * @param taskRef - The task being handed off.
+     * @param fromSessionId - Source session.
+     * @param toSessionId - Destination session.
+     * @param reason - Optional human-readable reason.
+     * @returns Result of the handoff operation.
+     */
+    initiateHandoff(taskRef, fromSessionId, toSessionId, reason) {
+        const ref = this._graph.getRef(taskRef.sessionId, taskRef.taskId);
+        if (!ref) {
+            return {
+                ok: false,
+                error: `Task ref not found: ${makeRefKey(taskRef.sessionId, taskRef.taskId)}. ` +
+                    'Register the task with /session link-task first.',
+            };
+        }
+        const handoffId = crypto.randomUUID();
+        const record = {
+            handoffId,
+            taskRef: { sessionId: taskRef.sessionId, taskId: taskRef.taskId },
+            fromSessionId,
+            toSessionId,
+            reason,
+            initiatedAt: Date.now(),
+            acknowledged: false,
+        };
+        this._graph.recordHandoff(record);
+        // Mark the task as blocked while awaiting handoff acknowledgement
+        this._graph.propagateStatus(taskRef.sessionId, taskRef.taskId, 'blocked');
+        this._flush();
+        return { ok: true, handoffId };
+    }
+    /**
+     * Acknowledge a handoff from the destination session.
+     *
+     * @param handoffId - The handoff to acknowledge.
+     * @returns `true` if the handoff was found and acknowledged.
+     */
+    acknowledgeHandoff(handoffId) {
+        const ok = this._graph.acknowledgeHandoff(handoffId);
+        if (ok)
+            this._flush();
+        return ok;
+    }
+    /**
+     * Return all handoff records.
+     */
+    getHandoffs() {
+        return this._graph.getHandoffs();
+    }
+    // ── Scoped cancellation ───────────────────────────────────────────────────────
+    /**
+     * Apply a scoped cancellation to the graph.
+     *
+     * @param request - The cancellation request.
+     * @returns Result describing what was cancelled and what was skipped.
+     */
+    cancel(request) {
+        const result = this._graph.applyCancellation(request);
+        if (result.ok && result.cancelled.length > 0)
+            this._flush();
+        return result;
+    }
+    // ── Snapshot / persistence ────────────────────────────────────────────────────
+    /**
+     * Take a snapshot of the current graph state.
+     * Suitable for display (e.g. `/session graph`).
+     */
+    snapshot() {
+        return this._graph.snapshot();
+    }
+    /**
+     * Force a synchronous flush to disk.
+     * Use on shutdown/dispose to ensure all pending data is written.
+     */
+    flush() {
+        if (this._flushTimer !== null) {
+            clearTimeout(this._flushTimer);
+            this._flushTimer = null;
+        }
+        this._flushSync();
+    }
+    /**
+     * Release process-level resources held by the registry.
+     *
+     * Safe to call multiple times. Flushes pending state before detaching the
+     * process exit handler.
+     */
+    dispose() {
+        this.flush();
+        if (this._exitHandler) {
+            process.removeListener('exit', this._exitHandler);
+            this._exitHandler = null;
+        }
+    }
+    // ── Private ───────────────────────────────────────────────────────────────────
+    /**
+     * Load the persisted graph from disk and hydrate the in-memory graph.
+     * Non-fatal: if the file is missing or malformed, the graph starts empty.
+     */
+    _load() {
+        if (!existsSync(this._graphPath))
+            return;
+        try {
+            const raw = readFileSync(this._graphPath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            if (parsed.version !== GRAPH_SCHEMA_VERSION) {
+                logger.debug('CrossSessionTaskRegistry: snapshot version mismatch, starting fresh', {
+                    expected: GRAPH_SCHEMA_VERSION,
+                    got: parsed.version,
+                });
+                return;
+            }
+            this._graph.hydrate(parsed);
+            logger.debug('CrossSessionTaskRegistry: hydrated graph from disk', {
+                path: this._graphPath,
+            });
+        }
+        catch (e) {
+            // Non-fatal: malformed or missing graph file — start with empty graph
+            logger.debug('CrossSessionTaskRegistry: could not load task graph', {
+                path: this._graphPath,
+                error: summarizeError(e),
+            });
+        }
+    }
+    /**
+     * Flush the current graph snapshot to disk.
+     * Non-fatal: if the write fails, logs a debug message and continues.
+     */
+    _flush() {
+        this._scheduledFlush();
+    }
+    /** Schedule a debounced async write (coalesces rapid successive mutations). */
+    _scheduledFlush() {
+        if (this._flushTimer !== null)
+            return;
+        this._flushTimer = setTimeout(async () => {
+            this._flushTimer = null;
+            try {
+                if (!this._dirEnsured) {
+                    mkdirSync(this._dir, { recursive: true });
+                    this._dirEnsured = true;
+                }
+                await writeFile(this._graphPath, JSON.stringify(this._graph.snapshot(), null, 2), 'utf-8');
+            }
+            catch (e) {
+                logger.warn('CrossSessionTaskRegistry: failed to flush task graph', {
+                    path: this._graphPath,
+                    error: summarizeError(e),
+                });
+            }
+        }, 100);
+    }
+    /** Perform a synchronous write — used by shutdown/dispose and flush(). */
+    _flushSync() {
+        try {
+            if (!this._dirEnsured) {
+                mkdirSync(this._dir, { recursive: true });
+                this._dirEnsured = true;
+            }
+            const snap = this._graph.snapshot();
+            writeFileSync(this._graphPath, JSON.stringify(snap, null, 2), 'utf-8');
+        }
+        catch (e) {
+            // Non-fatal: failed to persist graph — in-memory graph remains authoritative
+            logger.debug('CrossSessionTaskRegistry: failed to flush task graph', {
+                path: this._graphPath,
+                error: summarizeError(e),
+            });
+        }
+    }
+}

package/dist/platform/sessions/orchestration/types.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Multi-session Orchestration — Core Types
+ *
+ * Global task references across sessions,
+ * status/dependency propagation, and scoped cancellation semantics.
+ */
+import type { TaskLifecycleState } from '../../runtime/store/domains/tasks.js';
+/**
+ * A globally addressable reference to a task that may live in any session.
+ *
+ * The combination of sessionId + taskId is universally unique within a
+ * goodvibes-sdk process. Refs survive session reconnect/resume because
+ * sessionId is stable (matches the durable identity in the remote substrate).
+ */
+export interface CrossSessionTaskRef {
+    /** Stable session ID that owns this task (matches DurableIdentity.sessionId). */
+    readonly sessionId: string;
+    /** Task ID within that session. */
+    readonly taskId: string;
+    /** Human-readable title for display in the graph view. */
+    readonly title: string;
+    /** Current lifecycle status — propagated on update. */
+    status: TaskLifecycleState;
+    /** Epoch ms when this ref was created. */
+    readonly createdAt: number;
+    /** Epoch ms of last status update. */
+    updatedAt: number;
+    /** Optional label applied at link time. */
+    label?: string;
+}
+/**
+ * A directed dependency edge between two cross-session task refs.
+ *
+ * Semantics: `from` depends on `to` (i.e., `from` should not start until
+ * `to` is completed or cancelled).
+ */
+export interface TaskDependencyEdge {
+    /** The task that depends on another. */
+    readonly fromRef: Pick<CrossSessionTaskRef, 'sessionId' | 'taskId'>;
+    /** The task being depended upon. */
+    readonly toRef: Pick<CrossSessionTaskRef, 'sessionId' | 'taskId'>;
+    /** Epoch ms when the dependency was established. */
+    readonly linkedAt: number;
+    /** Optional human-readable reason for the dependency. */
+    readonly reason?: string;
+}
+/**
+ * Records a task handoff — when a task's continuation is transferred from
+ * one session to another. Handoffs preserve causal context across reconnects.
+ */
+export interface TaskHandoffRecord {
+    /** Unique handoff ID. */
+    readonly handoffId: string;
+    /** The task being handed off. */
+    readonly taskRef: Pick<CrossSessionTaskRef, 'sessionId' | 'taskId'>;
+    /** Session ID handing off the task (source). */
+    readonly fromSessionId: string;
+    /** Session ID receiving the task (destination). */
+    readonly toSessionId: string;
+    /** Human-readable reason for the handoff. */
+    readonly reason?: string;
+    /** Epoch ms when the handoff was initiated. */
+    readonly initiatedAt: number;
+    /** Whether the handoff completed (destination session acknowledged it). */
+    acknowledged: boolean;
+    /** Epoch ms when the destination acknowledged. */
+    acknowledgedAt?: number;
+}
+/**
+ * Defines the scope of a cross-session cancellation operation.
+ *
+ * - `task`   — Cancel only the specific task.
+ * - `subtree` — Cancel the task and all transitive dependents (tasks that
+ *               depend on this one directly or indirectly).
+ * - `session` — Cancel all tasks owned by the given session.
+ */
+export type CancellationScope = 'task' | 'subtree' | 'session';
+/**
+ * The set of valid cancellation scope values — exported for use in command
+ * handlers to avoid duplication.
+ */
+export declare const VALID_SCOPES: ReadonlyArray<CancellationScope>;
+/**
+ * Parameters for a scoped cancellation request.
+ */
+export interface CancellationRequest {
+    /** Session ID of the task to cancel (required for task/subtree scope). */
+    sessionId: string;
+    /** Task ID to cancel (required for task/subtree scope; ignored for session scope). */
+    taskId?: string;
+    /** Cancellation scope — defaults to 'task'. */
+    scope: CancellationScope;
+    /** Human-readable reason surfaced to the task owner. */
+    reason?: string;
+    /** Epoch ms when the cancellation was requested. */
+    readonly requestedAt: number;
+}
+/**
+ * Result of a scoped cancellation operation.
+ */
+export interface CancellationResult {
+    /** Whether the cancellation was fully applied. */
+    ok: boolean;
+    /** Task refs that were cancelled as part of this operation. */
+    cancelled: Array<Pick<CrossSessionTaskRef, 'sessionId' | 'taskId' | 'title'>>;
+    /** Task refs that could not be cancelled (e.g. already terminal). */
+    skipped: Array<Pick<CrossSessionTaskRef, 'sessionId' | 'taskId' | 'title'> & {
+        reason: string;
+    }>;
+    /** Error message if the operation failed entirely. */
+    error?: string;
+}
+/**
+ * A point-in-time snapshot of the full cross-session task graph.
+ *
+ * Used for persistence, reconnect hydration, and the `/session graph` display.
+ */
+export interface SessionTaskGraphSnapshot {
+    /** Schema version — increment on breaking changes. */
+    readonly version: 1;
+    /** Epoch ms when this snapshot was taken. */
+    readonly snapshotAt: number;
+    /** All tracked cross-session task refs, keyed by `${sessionId}:${taskId}`. */
+    readonly refs: Record<string, CrossSessionTaskRef>;
+    /** All dependency edges. */
+    readonly edges: TaskDependencyEdge[];
+    /** All handoff records. */
+    readonly handoffs: TaskHandoffRecord[];
+}
+/**
+ * Build a stable composite key for a cross-session task ref.
+ *
+ * @param sessionId - The owning session ID.
+ * @param taskId - The task ID within that session.
+ * @returns A colon-delimited composite key suitable for Map/Record keying.
+ */
+export declare function makeRefKey(sessionId: string, taskId: string): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/platform/sessions/orchestration/types.d.ts.map

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

package/dist/platform/sessions/orchestration/types.js

@@ -0,0 +1,22 @@
+/**
+ * Multi-session Orchestration — Core Types
+ *
+ * Global task references across sessions,
+ * status/dependency propagation, and scoped cancellation semantics.
+ */
+/**
+ * The set of valid cancellation scope values — exported for use in command
+ * handlers to avoid duplication.
+ */
+export const VALID_SCOPES = ['task', 'subtree', 'session'];
+// ── Graph key helper ──────────────────────────────────────────────────────────
+/**
+ * Build a stable composite key for a cross-session task ref.
+ *
+ * @param sessionId - The owning session ID.
+ * @param taskId - The task ID within that session.
+ * @returns A colon-delimited composite key suitable for Map/Record keying.
+ */
+export function makeRefKey(sessionId, taskId) {
+    return `${sessionId}:${taskId}`;
+}