@reactive-skills/runtime 0.1.1 → 0.3.0

package/README.md

@@ -22,6 +22,7 @@ import { FSMEngine, EventStore, LegacySkillAdapter, ProjectionEngine } from '@re
 - `ProjectionEngine` - Handlebars deliverable generator for read-model projections
 - `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
 
 ## Skill Manifest Schema
 

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}`);
                 }
             }