@reactive-skills/runtime 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+
+## [0.4.0] - 2026-09-14
+
+- feat(axi): implement native validate command for skill manifest and statechart verification (3b75a21)
+- docs: add v0.3.0 release highlights to READMEs and bundle changelog in package files (732f72b)
+- chore: release v0.3.0 (ae379ca)
+- feat(core): implement job management, isolated run storage, dual-write projections, and AXI jobs suite (c76c6cb)
+- chore: release v0.2.0 (bb33cfc)
+
+## [0.3.0] - 2026-09-13
+
+- feat(core): implement job management, isolated run storage, dual-write projections, and AXI jobs suite (c76c6cb)
+
+## [2.0.0] - 2026-09-01
+
+- feat: implement SQLite event store engine, state snapshotting, and JSONL log rotation with supporting documentation (6912493)
+- feat: implement skill-scoped SQLite event storage and migration infrastructure (b28fb19)
+- feat: implement core event-store with SQLite persistence, FSM engine, and projection tracking. (5926118)
+- feat: implement reactive skill core with FSM engine, event-sourced SQLite storage, and Zod-validated manifest schemas (b542c0a)
+- feat: add CLI tool for reactive skill management, project documentation, and state inspection workflows (39830d0)
+
+## [1.0.3] - 2026-08-31
+
+- refactor(core): migrate to clean semantic state filenames and convention-over-configuration resolution (8180b1b)
+- feat(hitl): add pre-implementation collaboration gate with 3 interaction modes (direct build, brainstorm, plan review) (0cd22b7)
+- fix(core): resolve P2 memory leak - add bounded in-memory sliding buffer with SQLite backing (7fefae5)
+- fix(core): resolve all Principal Engineer review findings - state rehydration, lifecycle signal queue, VM sandbox, and dual-write durability (791753e)
+- feat(mcp): add reactive_migrate tool to MCP server suite (e35779c)
+
+## [1.0.2] - 2026-08-31
+
+- chore(release): add automated multi-file semver bumping script and changelog generator (d0f9abd)
+- feat(docs): add automated doc invariant checker script and synchronize all project docs (280a95d)
+- feat(core): upgrade to v2 with Event Modeling 4-slice CQRS, statechart topology validation, and retroactive migration (c9801ed)
+- docs: clarify workspace layout, file destination paths, and greenfield/brownfield execution (1c79455)
+- docs: add Model Context Protocol (MCP) server documentation to README, architecture, and AGENTS (f2e638b)
+# Changelog
+
+## [1.0.1] - 2026-08-31
+
+- feat(docs): add automated doc invariant checker script and synchronize all project docs (280a95d)
+- feat(core): upgrade to v2 with Event Modeling 4-slice CQRS, statechart topology validation, and retroactive migration (c9801ed)
+- docs: clarify workspace layout, file destination paths, and greenfield/brownfield execution (1c79455)
+- docs: add Model Context Protocol (MCP) server documentation to README, architecture, and AGENTS (f2e638b)
+- feat(mcp): build universal reactive-mcp-server with 6 tools and live resources (9a01807)

package/README.md

@@ -1,6 +1,8 @@
 # @reactive-skills/runtime
 
-Reactive Skills Architecture (RSA) core runtime - FSM engine, event store, guard evaluator, projection engine, and MCP server.
+Reactive Skills Architecture (RSA) core runtime — FSM engine, event store, guard evaluator, projection engine, job manager, and MCP server.
+
+> 🚀 **What's New in v0.4.0:** Native `validate` command in AXI, first-class Job & Run Management, isolated event logs, and dual-write deliverable mirroring. [Read Full Release Notes →](https://github.com/Reactive-Skills/reactive-skills/releases/tag/v0.4.0) · [View Changelog](https://github.com/Reactive-Skills/reactive-skills/blob/main/CHANGELOG.md)
 
 ## Installation
 
@@ -11,15 +13,16 @@ npm install @reactive-skills/runtime
 ## Usage
 
 ```ts
-import { FSMEngine, EventStore, LegacySkillAdapter, ProjectionEngine } from '@reactive-skills/runtime';
+import { FSMEngine, EventStore, JobManager, LegacySkillAdapter, ProjectionEngine } from '@reactive-skills/runtime';
 ```
 
 ## Core Modules
 
 - `FSMEngine` - Hierarchical State Machine loader, state path resolver, and signal-driven transition engine
+- `JobManager` - Run isolation, active pointer resolution, metadata management, and safe directory pathing
 - `EventStore` - Immutable append-only event ledger (JSONL + SQLite)
 - `GuardEvaluator` - Sandbox evaluator for transition guard expressions
-- `ProjectionEngine` - Handlebars deliverable generator for read-model projections
+- `ProjectionEngine` - Handlebars deliverable generator for read-model projections with dual-write archiving
 - `LegacySkillAdapter` - Backward compatibility wrapper and converter for SKILL.md
 - `McpServer` - Stdio Model Context Protocol (MCP) server integration
 - `TelemetryServer` - Real-time Server-Sent Events (SSE) broadcaster and Private Network Access (PNA) HTTP bridge

package/dist/core/event-store.d.ts

@@ -7,6 +7,7 @@ export interface EventStoreOptions {
     sqlitePath?: string;
     workspaceDir?: string;
     skillId?: string;
+    jobId?: string;
     runId?: string;
     run_id?: string;
     correlationId?: string;
@@ -23,6 +24,7 @@ export interface EventStoreOptions {
     enableSqlite?: boolean;
     maxInMemoryEvents?: number;
     maxJsonlBytes?: number;
+    acquireLock?: boolean;
 }
 export interface EventQueryOptions {
     type?: string;
@@ -36,6 +38,7 @@ export interface EventQueryOptions {
  */
 export declare class SQLiteStorageDriver {
     private db;
+    private isClosed;
     constructor(dbPath: string);
     private initTables;
     private ensureSchemaVersion;
@@ -93,7 +96,11 @@ export declare class EventStore {
     private projectionWatermarks;
     private latestSnapshot;
     private maxJsonlBytes;
+    private lockFd;
+    private lockPath;
     constructor(options?: EventStoreOptions);
+    private acquireJobLock;
+    private releaseJobLock;
     private initializeStorage;
     /**
      * Scan all JSONL files for the authoritative max seq and event count.
@@ -168,7 +175,7 @@ export declare class EventStore {
      */
     query(filter?: EventQueryOptions): SignalEvent[];
     /**
-     * Close storage drivers and release file handles
+     * Close storage drivers and release file handles and locks
      */
     close(): void;
     /**

package/dist/core/event-store.js

@@ -20,6 +20,7 @@ export function createSortableId() {
  */
 export class SQLiteStorageDriver {
     db;
+    isClosed = false;
     constructor(dbPath) {
         if (dbPath !== ':memory:') {
             const dir = path.dirname(dbPath);
@@ -237,7 +238,17 @@ export class SQLiteStorageDriver {
         return row ? row.content : null;
     }
     close() {
-        this.db.close();
+        if (this.isClosed)
+            return;
+        try {
+            this.db.close();
+        }
+        catch {
+            // already closed
+        }
+        finally {
+            this.isClosed = true;
+        }
     }
     static getSchemaVersion(dbPath) {
         const db = new DatabaseSync(dbPath);
@@ -334,12 +345,15 @@ export class EventStore {
     projectionWatermarks = new Map();
     latestSnapshot = null;
     maxJsonlBytes;
+    lockFd = null;
+    lockPath = null;
     constructor(options = {}) {
         this.maxInMemoryEvents = options.maxInMemoryEvents || 1000;
         this.maxJsonlBytes = options.maxJsonlBytes || 10 * 1024 * 1024;
+        const effectiveJobId = options.jobId || options.runId || options.run_id;
         this.eventContext = {
             skill_id: options.skillId,
-            run_id: options.runId || options.run_id || createSortableId(),
+            run_id: effectiveJobId || createSortableId(),
             correlation_id: options.correlationId || createSortableId(),
             request_id: options.requestId,
             trace_parent: options.traceParent,
@@ -351,9 +365,21 @@ export class EventStore {
             const scopeDir = options.skillId
                 ? path.join(workspaceDir, '.reactive', 'skills', options.skillId)
                 : path.join(workspaceDir, '.reactive');
-            const runScopedDir = options.runId
-                ? path.join(scopeDir, options.runId)
-                : scopeDir;
+            let runScopedDir = scopeDir;
+            if (options.skillId && effectiveJobId) {
+                const isLegacyFallback = effectiveJobId === 'default' &&
+                    !fs.existsSync(path.join(scopeDir, 'jobs', effectiveJobId)) &&
+                    fs.existsSync(path.join(scopeDir, 'events.jsonl'));
+                if (!isLegacyFallback) {
+                    runScopedDir = path.join(scopeDir, 'jobs', effectiveJobId);
+                }
+            }
+            else if (effectiveJobId) {
+                runScopedDir = path.join(scopeDir, effectiveJobId);
+            }
+            if (options.acquireLock && runScopedDir) {
+                this.acquireJobLock(runScopedDir);
+            }
             this.storagePath = options.storagePath || path.join(runScopedDir, 'events.jsonl');
             if (options.enableSqlite || options.sqlitePath) {
                 const dbPath = options.sqlitePath || path.join(runScopedDir, 'events.db');
@@ -366,6 +392,69 @@ export class EventStore {
             this.sqliteDriver = new SQLiteStorageDriver(':memory:');
         }
     }
+    acquireJobLock(dir) {
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        this.lockPath = path.join(dir, '.lock');
+        try {
+            this.lockFd = fs.openSync(this.lockPath, 'wx');
+            fs.writeSync(this.lockFd, JSON.stringify({ pid: process.pid, time: new Date().toISOString() }));
+        }
+        catch (err) {
+            if (err.code === 'EEXIST') {
+                try {
+                    const content = fs.readFileSync(this.lockPath, 'utf8');
+                    const data = JSON.parse(content);
+                    if (data.pid) {
+                        try {
+                            process.kill(data.pid, 0);
+                            const lockError = new Error(`JOB_LOCKED: Job directory is currently locked by PID ${data.pid}`);
+                            lockError.code = 'JOB_LOCKED';
+                            throw lockError;
+                        }
+                        catch (killErr) {
+                            if (killErr.code === 'ESRCH') {
+                                fs.unlinkSync(this.lockPath);
+                                this.lockFd = fs.openSync(this.lockPath, 'wx');
+                                fs.writeSync(this.lockFd, JSON.stringify({ pid: process.pid, time: new Date().toISOString() }));
+                                return;
+                            }
+                            throw killErr;
+                        }
+                    }
+                }
+                catch (readErr) {
+                    if (readErr.code === 'JOB_LOCKED')
+                        throw readErr;
+                }
+                const lockError = new Error(`JOB_LOCKED: Job directory is currently locked`);
+                lockError.code = 'JOB_LOCKED';
+                throw lockError;
+            }
+            throw err;
+        }
+    }
+    releaseJobLock() {
+        if (this.lockFd !== null) {
+            try {
+                fs.closeSync(this.lockFd);
+            }
+            catch {
+                // ignore
+            }
+            this.lockFd = null;
+        }
+        if (this.lockPath && fs.existsSync(this.lockPath)) {
+            try {
+                fs.unlinkSync(this.lockPath);
+            }
+            catch {
+                // ignore
+            }
+            this.lockPath = null;
+        }
+    }
     initializeStorage() {
         // SQLite is authoritative. If it already has events, load the recent
         // sliding window and check JSONL for divergence before returning.
@@ -727,9 +816,10 @@ export class EventStore {
         return filter.limit ? filtered.slice(0, filter.limit) : filtered;
     }
     /**
-     * Close storage drivers and release file handles
+     * Close storage drivers and release file handles and locks
      */
     close() {
+        this.releaseJobLock();
         if (this.sqliteDriver) {
             this.sqliteDriver.close();
         }
@@ -748,6 +838,7 @@ export class EventStore {
         this.seqCounter = 0;
         this.projectionWatermarks.clear();
         this.latestSnapshot = null;
+        this.releaseJobLock();
         if (this.sqliteDriver) {
             this.sqliteDriver.clear();
         }

package/dist/core/fsm-engine.d.ts

@@ -1,10 +1,12 @@
 import { SkillManifest, StateDefinition, SignalEvent, PromptSlice, EventContext, ChildRunSummary, DecisionRecord } from './types.js';
 import { EventStore } from './event-store.js';
+import { JobManager } from './job-manager.js';
 export interface FSMEngineOptions {
     skillDir: string;
     workspaceDir?: string;
     eventStore?: EventStore;
     eventContext?: EventContext;
+    jobId?: string;
     runId?: string;
     initialContext?: Record<string, any>;
     autoRehydrate?: boolean;
@@ -23,6 +25,9 @@ export declare class FSMEngine {
     private turnsSinceLastSignal;
     private inBypassState;
     private readonly strictExecution;
+    private jobId?;
+    private isActiveJob;
+    private jobManager;
     constructor(options: FSMEngineOptions);
     /**
      * Rehydrate state machine state and context from immutable event history,
@@ -92,4 +97,8 @@ export declare class FSMEngine {
     private enterPath;
     private executeEntryHook;
     private executeExitHook;
+    getJobId(): string | undefined;
+    isJobActive(): boolean;
+    getJobManager(): JobManager;
+    close(): void;
 }

package/dist/core/fsm-engine.js

@@ -7,6 +7,7 @@ import { EventStore, createSortableId } from './event-store.js';
 import { GuardEvaluator } from './guard-evaluator.js';
 import { LegacySkillAdapter } from './legacy-adapter.js';
 import { ProjectionEngine } from './projection-engine.js';
+import { JobManager } from './job-manager.js';
 /** Maximum lifecycle-signal drain steps per top-level handleSignal call.
  *  Prevents cyclic on_enter/on_exit emissions from overflowing the call stack (REL-02). */
 const MAX_QUEUE_DRAIN_DEPTH = 50;
@@ -24,6 +25,9 @@ export class FSMEngine {
     turnsSinceLastSignal;
     inBypassState;
     strictExecution;
+    jobId;
+    isActiveJob;
+    jobManager;
     constructor(options) {
         this.skillDir = path.resolve(options.skillDir);
         this.workspaceDir = options.workspaceDir || process.cwd();
@@ -31,10 +35,29 @@ export class FSMEngine {
         this.strictExecution = this.manifest.strict_execution === true;
         this.turnsSinceLastSignal = 0;
         this.inBypassState = false;
+        const effectiveJobId = options.jobId || options.runId;
+        this.jobManager = new JobManager(this.workspaceDir);
+        const activeJobId = this.jobManager.getActiveJobId(this.manifest.name);
+        const resolvedJobId = effectiveJobId || activeJobId;
+        const isActiveJob = (resolvedJobId === activeJobId);
+        this.jobId = resolvedJobId;
+        this.isActiveJob = isActiveJob;
+        if (this.jobId) {
+            const existingJob = this.jobManager.getJob(this.manifest.name, this.jobId);
+            if (!existingJob) {
+                this.jobManager.createJob(this.manifest.name, {
+                    id: this.jobId,
+                    name: this.jobId,
+                    initialState: this.manifest.initial_state,
+                    setActive: this.isActiveJob,
+                });
+            }
+        }
         this.eventStore = options.eventStore || new EventStore({
             skillId: this.manifest.name,
             workspaceDir: this.workspaceDir,
-            runId: options.runId,
+            jobId: this.jobId,
+            runId: this.jobId,
             enableSqlite: true,
             ...options.eventContext,
         });
@@ -42,7 +65,7 @@ export class FSMEngine {
             ...(this.manifest.default_context || {}),
             ...(options.initialContext || {}),
         };
-        this.projectionEngine = new ProjectionEngine(this.skillDir, this.manifest.deliverable_projections || [], options.workspaceDir || process.cwd());
+        this.projectionEngine = new ProjectionEngine(this.skillDir, this.manifest.deliverable_projections || [], options.workspaceDir || process.cwd(), this.jobId, this.isActiveJob);
         const autoRehydrate = options.autoRehydrate !== false;
         const latestSnapshot = autoRehydrate ? this.eventStore.getLatestSnapshot() : null;
         const history = autoRehydrate
@@ -50,6 +73,11 @@ export class FSMEngine {
             : [];
         if (autoRehydrate && (latestSnapshot || history.length > 0)) {
             this.rehydrate(history, latestSnapshot);
+            if (this.jobId) {
+                this.jobManager.updateJob(this.manifest.name, this.jobId, {
+                    currentState: this.getCurrentState(),
+                });
+            }
         }
         else {
             const initialPath = this.resolveInitialPath([this.manifest.initial_state]);
@@ -62,6 +90,11 @@ export class FSMEngine {
             }, { state: initialPath.join('.') });
             this.enterPath(initialPath, [], 'INITIAL_BOOT');
             this.eventStore.saveSnapshot(this.eventStore.getLatestSequence(), this.getCurrentState(), this.context);
+            if (this.jobId) {
+                this.jobManager.updateJob(this.manifest.name, this.jobId, {
+                    currentState: this.getCurrentState(),
+                });
+            }
         }
     }
     /**
@@ -531,6 +564,11 @@ export class FSMEngine {
                             this.signalQueueDepth = 0;
                         }
                     }
+                    if (this.jobId) {
+                        this.jobManager.updateJob(this.manifest.name, this.jobId, {
+                            currentState: this.getCurrentState(),
+                        });
+                    }
                     return {
                         transitioned: true,
                         previousState,
@@ -648,4 +686,16 @@ export class FSMEngine {
             }
         }
     }
+    getJobId() {
+        return this.jobId;
+    }
+    isJobActive() {
+        return this.isActiveJob;
+    }
+    getJobManager() {
+        return this.jobManager;
+    }
+    close() {
+        this.eventStore.close();
+    }
 }

package/dist/core/job-manager.d.ts

@@ -0,0 +1,50 @@
+import { JobMetadata } from './types.js';
+export declare const DEFAULT_JOB_ID = "default";
+/**
+ * Converts arbitrary human strings (e.g. 'Auth Slice v1.0') into safe filesystem slugs.
+ */
+export declare function normalizeJobSlug(name: string): string;
+export interface CreateJobOptions {
+    id?: string;
+    name?: string;
+    initialState?: string;
+    parentRunId?: string;
+    setActive?: boolean;
+}
+/**
+ * JobManager handles execution run isolation, active job pointer resolution,
+ * and job metadata persistence.
+ */
+export declare class JobManager {
+    private workspaceDir;
+    constructor(workspaceDir?: string);
+    getSkillDir(skillId: string): string;
+    getActivePointerPath(skillId: string): string;
+    getJobsDir(skillId: string): string;
+    getJobDir(skillId: string, jobId: string): string;
+    /**
+     * Resolves the current active job ID for a skill.
+     * Falls back to DEFAULT_JOB_ID ('default') if no pointer exists.
+     */
+    getActiveJobId(skillId: string): string;
+    /**
+     * Sets the active job pointer for a skill.
+     */
+    setActiveJobId(skillId: string, jobId: string): void;
+    /**
+     * Creates a new isolated job and persists its job.json metadata.
+     */
+    createJob(skillId: string, options?: CreateJobOptions): JobMetadata;
+    /**
+     * Retrieves a job's metadata by ID.
+     */
+    getJob(skillId: string, jobId: string): JobMetadata | null;
+    /**
+     * Updates a job's metadata (e.g. status, currentState, completedAt).
+     */
+    updateJob(skillId: string, jobId: string, updates: Partial<JobMetadata>): JobMetadata;
+    /**
+     * Lists all jobs for a skill.
+     */
+    listJobs(skillId: string): JobMetadata[];
+}

package/dist/core/job-manager.js

@@ -0,0 +1,213 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createSortableId } from './event-store.js';
+import { JobMetadataSchema } from './types.js';
+export const DEFAULT_JOB_ID = 'default';
+/**
+ * Converts arbitrary human strings (e.g. 'Auth Slice v1.0') into safe filesystem slugs.
+ */
+export function normalizeJobSlug(name) {
+    const cleaned = name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    if (!cleaned) {
+        return `job-${createSortableId().slice(0, 8)}`;
+    }
+    return cleaned;
+}
+/**
+ * JobManager handles execution run isolation, active job pointer resolution,
+ * and job metadata persistence.
+ */
+export class JobManager {
+    workspaceDir;
+    constructor(workspaceDir = process.cwd()) {
+        this.workspaceDir = path.resolve(workspaceDir);
+    }
+    getSkillDir(skillId) {
+        return path.join(this.workspaceDir, '.reactive', 'skills', skillId);
+    }
+    getActivePointerPath(skillId) {
+        return path.join(this.getSkillDir(skillId), 'active_job');
+    }
+    getJobsDir(skillId) {
+        return path.join(this.getSkillDir(skillId), 'jobs');
+    }
+    getJobDir(skillId, jobId) {
+        return path.join(this.getJobsDir(skillId), jobId);
+    }
+    /**
+     * Resolves the current active job ID for a skill.
+     * Falls back to DEFAULT_JOB_ID ('default') if no pointer exists.
+     */
+    getActiveJobId(skillId) {
+        const pointerFile = this.getActivePointerPath(skillId);
+        if (fs.existsSync(pointerFile)) {
+            try {
+                const id = fs.readFileSync(pointerFile, 'utf8').trim();
+                if (id)
+                    return id;
+            }
+            catch {
+                // Fall back to default
+            }
+        }
+        return DEFAULT_JOB_ID;
+    }
+    /**
+     * Sets the active job pointer for a skill.
+     */
+    setActiveJobId(skillId, jobId) {
+        const targetDir = this.getSkillDir(skillId);
+        if (!fs.existsSync(targetDir)) {
+            fs.mkdirSync(targetDir, { recursive: true });
+        }
+        const pointerFile = this.getActivePointerPath(skillId);
+        fs.writeFileSync(pointerFile, jobId.trim(), 'utf8');
+    }
+    /**
+     * Creates a new isolated job and persists its job.json metadata.
+     */
+    createJob(skillId, options = {}) {
+        const id = options.id || createSortableId();
+        const name = options.name ? normalizeJobSlug(options.name) : (options.id ? normalizeJobSlug(options.id) : DEFAULT_JOB_ID);
+        const now = new Date().toISOString();
+        const metadata = {
+            id,
+            name,
+            skillId,
+            status: 'active',
+            currentState: options.initialState || 'INIT',
+            parentRunId: options.parentRunId,
+            createdAt: now,
+            updatedAt: now,
+        };
+        const jobDir = this.getJobDir(skillId, id);
+        if (!fs.existsSync(jobDir)) {
+            fs.mkdirSync(jobDir, { recursive: true });
+        }
+        const metadataPath = path.join(jobDir, 'job.json');
+        fs.writeFileSync(metadataPath, JSON.stringify(metadata, null, 2), 'utf8');
+        if (options.setActive) {
+            this.setActiveJobId(skillId, id);
+        }
+        return metadata;
+    }
+    /**
+     * Retrieves a job's metadata by ID.
+     */
+    getJob(skillId, jobId) {
+        const jobDir = this.getJobDir(skillId, jobId);
+        const metadataPath = path.join(jobDir, 'job.json');
+        if (fs.existsSync(metadataPath)) {
+            try {
+                const raw = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+                return JobMetadataSchema.parse(raw);
+            }
+            catch {
+                return null;
+            }
+        }
+        // Fallback: if jobDir exists (e.g. created by EventStore), synthesize metadata
+        if (fs.existsSync(jobDir)) {
+            const stat = fs.statSync(jobDir);
+            return {
+                id: jobId,
+                name: normalizeJobSlug(jobId),
+                skillId,
+                status: 'active',
+                currentState: 'INIT',
+                createdAt: stat.birthtime && !isNaN(stat.birthtime.getTime()) ? stat.birthtime.toISOString() : new Date().toISOString(),
+                updatedAt: stat.mtime && !isNaN(stat.mtime.getTime()) ? stat.mtime.toISOString() : new Date().toISOString(),
+            };
+        }
+        // Check if it's the active job pointer
+        if (jobId === this.getActiveJobId(skillId)) {
+            const pointerFile = this.getActivePointerPath(skillId);
+            if (fs.existsSync(pointerFile)) {
+                const stat = fs.statSync(pointerFile);
+                return {
+                    id: jobId,
+                    name: normalizeJobSlug(jobId),
+                    skillId,
+                    status: 'active',
+                    currentState: 'INIT',
+                    createdAt: stat.birthtime && !isNaN(stat.birthtime.getTime()) ? stat.birthtime.toISOString() : new Date().toISOString(),
+                    updatedAt: stat.mtime && !isNaN(stat.mtime.getTime()) ? stat.mtime.toISOString() : new Date().toISOString(),
+                };
+            }
+        }
+        // Legacy fallback: if requesting 'default' and legacy events.jsonl exists at skill root
+        if (jobId === DEFAULT_JOB_ID) {
+            const legacyEventStore = path.join(this.getSkillDir(skillId), 'events.jsonl');
+            if (fs.existsSync(legacyEventStore)) {
+                return {
+                    id: DEFAULT_JOB_ID,
+                    name: DEFAULT_JOB_ID,
+                    skillId,
+                    status: 'active',
+                    currentState: 'ACTIVE',
+                    createdAt: new Date().toISOString(),
+                    updatedAt: new Date().toISOString(),
+                };
+            }
+        }
+        return null;
+    }
+    /**
+     * Updates a job's metadata (e.g. status, currentState, completedAt).
+     */
+    updateJob(skillId, jobId, updates) {
+        const existing = this.getJob(skillId, jobId) || this.createJob(skillId, { id: jobId, name: jobId });
+        const updated = {
+            ...existing,
+            ...updates,
+            updatedAt: new Date().toISOString(),
+        };
+        const validated = JobMetadataSchema.parse(updated);
+        const jobDir = this.getJobDir(skillId, jobId);
+        if (!fs.existsSync(jobDir)) {
+            fs.mkdirSync(jobDir, { recursive: true });
+        }
+        const metadataPath = path.join(jobDir, 'job.json');
+        fs.writeFileSync(metadataPath, JSON.stringify(validated, null, 2), 'utf8');
+        return validated;
+    }
+    /**
+     * Lists all jobs for a skill.
+     */
+    listJobs(skillId) {
+        const jobs = [];
+        const jobsDir = this.getJobsDir(skillId);
+        if (fs.existsSync(jobsDir)) {
+            const entries = fs.readdirSync(jobsDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    const job = this.getJob(skillId, entry.name);
+                    if (job) {
+                        jobs.push(job);
+                    }
+                }
+            }
+        }
+        const activeJobId = this.getActiveJobId(skillId);
+        if (!jobs.some(j => j.id === activeJobId)) {
+            const activeJob = this.getJob(skillId, activeJobId);
+            if (activeJob) {
+                jobs.push(activeJob);
+            }
+        }
+        // Check for legacy root event store if no jobs found
+        if (jobs.length === 0) {
+            const legacyEventStore = path.join(this.getSkillDir(skillId), 'events.jsonl');
+            if (fs.existsSync(legacyEventStore)) {
+                const defaultJob = this.getJob(skillId, DEFAULT_JOB_ID);
+                if (defaultJob)
+                    jobs.push(defaultJob);
+            }
+        }
+        return jobs.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    }
+}

package/dist/core/projection-engine.d.ts

@@ -30,7 +30,10 @@ export declare class ProjectionEngine {
     private projections;
     private compiledTemplates;
     private eventCaches;
-    constructor(skillDir: string, projections?: DeliverableProjection[], workspaceDir?: string);
+    private jobId?;
+    private isActiveJob;
+    constructor(skillDir: string, projections?: DeliverableProjection[], workspaceDir?: string, jobId?: string, isActiveJob?: boolean);
+    setJob(jobId?: string, isActiveJob?: boolean): void;
     private resolveOutputPath;
     private getProjectionEvents;
     private matchesTrigger;

package/dist/core/projection-engine.js

@@ -11,13 +11,21 @@ export class ProjectionEngine {
     projections;
     compiledTemplates = new Map();
     eventCaches = new WeakMap();
-    constructor(skillDir, projections = [], workspaceDir = process.cwd()) {
+    jobId;
+    isActiveJob;
+    constructor(skillDir, projections = [], workspaceDir = process.cwd(), jobId, isActiveJob = true) {
         this.skillDir = skillDir;
         this.workspaceDir = path.resolve(workspaceDir);
         this.projections = projections;
+        this.jobId = jobId;
+        this.isActiveJob = isActiveJob;
         this.registerHelpers();
         this.compileTemplates();
     }
+    setJob(jobId, isActiveJob = true) {
+        this.jobId = jobId;
+        this.isActiveJob = isActiveJob;
+    }
     resolveOutputPath(output) {
         if (path.isAbsolute(output)) {
             throw new Error('Projection output must be relative to the workspace.');
@@ -138,13 +146,27 @@ export class ProjectionEngine {
                 }
                 if (templateFn) {
                     const outputContent = templateFn(projContext);
-                    const outputPath = this.resolveOutputPath(proj.output);
-                    const outputDir = path.dirname(outputPath);
-                    if (!fs.existsSync(outputDir)) {
-                        fs.mkdirSync(outputDir, { recursive: true });
+                    const canonicalOutputPath = this.resolveOutputPath(proj.output);
+                    const canonicalDir = path.dirname(canonicalOutputPath);
+                    const fileName = path.basename(canonicalOutputPath);
+                    // 1. If jobId is present, write to historical job archive:
+                    if (this.jobId) {
+                        const archiveDir = path.join(canonicalDir, 'jobs', this.jobId);
+                        if (!fs.existsSync(archiveDir)) {
+                            fs.mkdirSync(archiveDir, { recursive: true });
+                        }
+                        const archivePath = path.join(archiveDir, fileName);
+                        fs.writeFileSync(archivePath, outputContent, 'utf8');
+                        writtenFiles.push(archivePath);
+                    }
+                    // 2. If active job or no jobId (legacy mode), mirror to canonical root:
+                    if (this.isActiveJob || !this.jobId) {
+                        if (!fs.existsSync(canonicalDir)) {
+                            fs.mkdirSync(canonicalDir, { recursive: true });
+                        }
+                        fs.writeFileSync(canonicalOutputPath, outputContent, 'utf8');
+                        writtenFiles.push(canonicalOutputPath);
                     }
-                    fs.writeFileSync(outputPath, outputContent, 'utf8');
-                    writtenFiles.push(outputPath);
                     eventStore.saveProjectionWatermark(proj.template, eventStore.getLatestSequence(), `${this.skillDir}:${proj.template}`);
                 }
             }

package/dist/core/types.d.ts

@@ -236,3 +236,37 @@ export declare const SkillManifestSchema: z.ZodObject<{
         trigger_on?: string[] | undefined;
     }[] | undefined;
 }>;
+export declare const JobStatusSchema: z.ZodEnum<["active", "completed", "failed", "archived"]>;
+export type JobStatus = z.infer<typeof JobStatusSchema>;
+export declare const JobMetadataSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    skillId: z.ZodString;
+    status: z.ZodEnum<["active", "completed", "failed", "archived"]>;
+    currentState: z.ZodString;
+    parentRunId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    completedAt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "completed" | "failed" | "active" | "archived";
+    name: string;
+    id: string;
+    skillId: string;
+    currentState: string;
+    createdAt: string;
+    updatedAt: string;
+    parentRunId?: string | undefined;
+    completedAt?: string | undefined;
+}, {
+    status: "completed" | "failed" | "active" | "archived";
+    name: string;
+    id: string;
+    skillId: string;
+    currentState: string;
+    createdAt: string;
+    updatedAt: string;
+    parentRunId?: string | undefined;
+    completedAt?: string | undefined;
+}>;
+export type JobMetadata = z.infer<typeof JobMetadataSchema>;

package/dist/core/types.js

@@ -53,3 +53,15 @@ export const SkillManifestSchema = z.object({
         trigger_on: z.array(z.string()).optional(),
     })).optional(),
 });
+export const JobStatusSchema = z.enum(['active', 'completed', 'failed', 'archived']);
+export const JobMetadataSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    skillId: z.string(),
+    status: JobStatusSchema,
+    currentState: z.string(),
+    parentRunId: z.string().optional(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    completedAt: z.string().optional(),
+});

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export * from './core/fsm-engine.js';
 export * from './core/runtime-hooks.js';
 export * from './core/legacy-adapter.js';
 export * from './core/migration.js';
+export * from './core/job-manager.js';
 export * from './mcp/server.js';
 export * from './sync/types.js';
 export { runSync } from './sync/engine.js';

package/dist/index.js

@@ -6,6 +6,7 @@ export * from './core/fsm-engine.js';
 export * from './core/runtime-hooks.js';
 export * from './core/legacy-adapter.js';
 export * from './core/migration.js';
+export * from './core/job-manager.js';
 export * from './mcp/server.js';
 export * from './sync/types.js';
 export { runSync } from './sync/engine.js';

package/dist/mcp/server.js

@@ -7,6 +7,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 import { FSMEngine } from '../core/fsm-engine.js';
 import { EventStore } from '../core/event-store.js';
+import { JobManager } from '../core/job-manager.js';
 import { SkillManifestSchema } from '../core/types.js';
 export function createReactiveMcpServer(options = {}) {
     const workspaceDir = options.workspaceDir || process.cwd();
@@ -15,7 +16,7 @@ export function createReactiveMcpServer(options = {}) {
         name: 'reactive-skills-server',
         version: '1.0.0',
     });
-    // Cached active engine instance per skill
+    // Cached active engine instance per skill and job
     const engines = new Map();
     function normalizeDeliverableName(name) {
         const trimmed = String(name || '').trim();
@@ -27,13 +28,16 @@ export function createReactiveMcpServer(options = {}) {
         }
         return trimmed;
     }
-    function getEngine(skillName = defaultSkill) {
-        if (engines.has(skillName)) {
-            const cached = engines.get(skillName);
+    function getEngine(skillName = defaultSkill, jobId) {
+        const jobManager = new JobManager(workspaceDir);
+        const resolvedJobId = jobId || jobManager.getActiveJobId(skillName);
+        const cacheKey = `${skillName}::${resolvedJobId}`;
+        if (engines.has(cacheKey)) {
+            const cached = engines.get(cacheKey);
             if (fs.existsSync(cached.getSkillDir())) {
                 return cached;
             }
-            engines.delete(skillName);
+            engines.delete(cacheKey);
         }
         const candidatePaths = [
             path.resolve(workspaceDir, 'skills', skillName),
@@ -74,18 +78,26 @@ export function createReactiveMcpServer(options = {}) {
         const eventStore = new EventStore({
             workspaceDir,
             skillId: skillName,
+            jobId: resolvedJobId,
+            runId: resolvedJobId,
             enableSqlite: true,
         });
-        const engine = new FSMEngine({ skillDir, workspaceDir, eventStore });
-        engines.set(skillName, engine);
+        const engine = new FSMEngine({
+            skillDir,
+            workspaceDir,
+            eventStore,
+            jobId: resolvedJobId,
+        });
+        engines.set(cacheKey, engine);
         return engine;
     }
     // 1. TOOL: reactive_state
     server.tool('reactive_state', 'Get current state, prompt slice, and allowed tools for the active reactive skill', {
         skill: z.string().optional().describe('Skill name (defaults to active skill)'),
-    }, async ({ skill }) => {
+        job_id: z.string().optional().describe('Optional job/run ID (defaults to active job)'),
+    }, async ({ skill, job_id }) => {
         try {
-            const engine = getEngine(skill || defaultSkill);
+            const engine = getEngine(skill || defaultSkill, job_id);
             if (engine.isBypassDetected()) {
                 return {
                     content: [
@@ -114,6 +126,7 @@ export function createReactiveMcpServer(options = {}) {
                         type: 'text',
                         text: JSON.stringify({
                             skill: engine.getManifest().name,
+                            job_id: engine.getJobId(),
                             activeState,
                             isWaitingForHuman: isWaiting,
                             allowedTools: slice.allowedTools,
@@ -145,15 +158,18 @@ export function createReactiveMcpServer(options = {}) {
         signal: z.string().describe('Signal name (e.g. CHECK_PASSED, CHARTER_DRAFTED)'),
         payload: z.record(z.any()).optional().describe('Signal payload data (e.g. exit_code, file_path)'),
         skill: z.string().optional().describe('Target skill name'),
-    }, async ({ signal, payload = {}, skill }) => {
+        job_id: z.string().optional().describe('Optional job/run ID (defaults to active job)'),
+    }, async ({ signal, payload = {}, skill, job_id }) => {
         try {
-            const engine = getEngine(skill || defaultSkill);
+            const engine = getEngine(skill || defaultSkill, job_id);
             const result = await engine.handleSignal(signal, payload);
             return {
                 content: [
                     {
                         type: 'text',
                         text: JSON.stringify({
+                            skill: engine.getManifest().name,
+                            job_id: engine.getJobId(),
                             transitioned: result.transitioned,
                             previousState: result.previousState,
                             newState: result.newState,
@@ -175,9 +191,10 @@ export function createReactiveMcpServer(options = {}) {
     server.tool('reactive_query', 'Execute a read-only SQL query against the SQLite event store (.reactive/events.db)', {
         sql: z.string().describe('SQL query string (e.g. SELECT * FROM events ORDER BY seq DESC LIMIT 10)'),
         skill: z.string().optional().describe('Skill context for event store'),
-    }, async ({ sql, skill }) => {
+        job_id: z.string().optional().describe('Optional job/run ID (defaults to active job)'),
+    }, async ({ sql, skill, job_id }) => {
         try {
-            const engine = getEngine(skill || defaultSkill);
+            const engine = getEngine(skill || defaultSkill, job_id);
             const driver = engine.getEventStore().getSqliteDriver();
             if (!driver) {
                 throw new Error('SQLite storage driver is not active.');
@@ -206,9 +223,10 @@ export function createReactiveMcpServer(options = {}) {
         sinceSeq: z.number().int().nonnegative().optional().describe('Return events after this sequence'),
         limit: z.number().int().positive().max(1000).optional().describe('Maximum number of events'),
         skill: z.string().optional().describe('Skill context for event store'),
-    }, async ({ type, state, sinceSeq, limit, skill }) => {
+        job_id: z.string().optional().describe('Optional job/run ID (defaults to active job)'),
+    }, async ({ type, state, sinceSeq, limit, skill, job_id }) => {
         try {
-            const engine = getEngine(skill || defaultSkill);
+            const engine = getEngine(skill || defaultSkill, job_id);
             const rows = engine.getEventStore().query({ type, state, sinceSeq, limit });
             return {
                 content: [{ type: 'text', text: JSON.stringify(rows, null, 2) }],
@@ -268,9 +286,10 @@ export function createReactiveMcpServer(options = {}) {
     // 5. TOOL: reactive_inspect
     server.tool('reactive_inspect', 'Inspect the full statechart, transitions, and guard criteria of a reactive skill', {
         skill: z.string().optional().describe('Skill name to inspect'),
-    }, async ({ skill }) => {
+        job_id: z.string().optional().describe('Optional job/run ID (defaults to active job)'),
+    }, async ({ skill, job_id }) => {
         try {
-            const engine = getEngine(skill || defaultSkill);
+            const engine = getEngine(skill || defaultSkill, job_id);
             const manifest = engine.getManifest();
             return {
                 content: [
@@ -319,15 +338,16 @@ export function createReactiveMcpServer(options = {}) {
             };
         }
     });
-    // 6. TOOL: reactive_respond_human
+    // 7. TOOL: reactive_respond_human
     server.tool('reactive_respond_human', 'Submit user approval or feedback to unpause a Human-in-the-Loop (HITL) gate', {
         choice: z.string().describe('User selected choice (e.g. Approve Plan)'),
         approved: z.boolean().optional().describe('Explicit approval boolean flag'),
         feedback: z.string().optional().describe('Optional feedback text'),
         skill: z.string().optional().describe('Target skill name'),
-    }, async ({ choice, approved = true, feedback, skill }) => {
+        job_id: z.string().optional().describe('Optional job/run ID (defaults to active job)'),
+    }, async ({ choice, approved = true, feedback, skill, job_id }) => {
         try {
-            const engine = getEngine(skill || defaultSkill);
+            const engine = getEngine(skill || defaultSkill, job_id);
             const signalsEmitted = [];
             let transitioned = false;
             let deliverablesWritten = [];
@@ -427,6 +447,35 @@ export function createReactiveMcpServer(options = {}) {
             };
         }
     });
+    // 9. TOOL: reactive_list_jobs
+    server.tool('reactive_list_jobs', 'List all historical and active execution jobs for a skill with status metadata', {
+        skill: z.string().optional().describe('Skill name (defaults to active skill)'),
+    }, async ({ skill }) => {
+        try {
+            const targetSkill = skill || defaultSkill;
+            const jobManager = new JobManager(workspaceDir);
+            const activeJobId = jobManager.getActiveJobId(targetSkill);
+            const jobs = jobManager.listJobs(targetSkill);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            skill: targetSkill,
+                            activeJobId,
+                            jobs,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ error: err.message }) }],
+                isError: true,
+            };
+        }
+    });
     // RESOURCE 1: reactive://events
     server.resource('reactive-events', 'reactive://events', async (uri) => {
         const store = new EventStore({ enableSqlite: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reactive-skills/runtime",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Reactive Skills Architecture (RSA) core runtime — FSM engine, event store, guard evaluator, projection engine, MCP server",
   "type": "module",
   "main": "dist/index.js",
@@ -14,7 +14,8 @@
     "reactive-skills-mcp": "./dist/mcp/server.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "ai",