@exaudeus/workrail 3.12.0 → 3.14.0

package/dist/v2/infra/local/managed-source-store/index.js

@@ -0,0 +1,164 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalManagedSourceStoreV2 = void 0;
+const path_1 = __importDefault(require("path"));
+const zod_1 = require("zod");
+const neverthrow_1 = require("neverthrow");
+const MANAGED_SOURCE_LOCK_RETRY_MS = 250;
+const jcs_js_1 = require("../../../durable-core/canonical/jcs.js");
+const ManagedSourceRecordSchema = zod_1.z.object({
+    path: zod_1.z.string(),
+    addedAtMs: zod_1.z.number().int().nonnegative(),
+});
+const ManagedSourcesFileSchema = zod_1.z.object({
+    v: zod_1.z.literal(1),
+    sources: zod_1.z.array(ManagedSourceRecordSchema),
+});
+function mapFsToManagedSourceError(e) {
+    if (e.code === 'FS_ALREADY_EXISTS') {
+        return {
+            code: 'MANAGED_SOURCE_BUSY',
+            message: 'Managed sources are being updated by another WorkRail process.',
+            retry: { kind: 'retryable_after_ms', afterMs: MANAGED_SOURCE_LOCK_RETRY_MS },
+            lockPath: 'managed-sources.lock',
+        };
+    }
+    return { code: 'MANAGED_SOURCE_IO_ERROR', message: e.message };
+}
+function normalizeRecords(sources) {
+    const seen = new Set();
+    const normalized = [];
+    for (const source of sources) {
+        const normalizedPath = path_1.default.resolve(source.path);
+        if (seen.has(normalizedPath))
+            continue;
+        seen.add(normalizedPath);
+        normalized.push({ path: normalizedPath, addedAtMs: source.addedAtMs });
+    }
+    return normalized;
+}
+class LocalManagedSourceStoreV2 {
+    constructor(dataDir, fs) {
+        this.dataDir = dataDir;
+        this.fs = fs;
+    }
+    list() {
+        return this.readSources();
+    }
+    attach(sourcePath) {
+        const normalizedPath = path_1.default.resolve(sourcePath);
+        const nowMs = Date.now();
+        return this.withLock(() => this.readSources().andThen((sources) => {
+            const alreadyPresent = sources.some((s) => s.path === normalizedPath);
+            if (alreadyPresent)
+                return (0, neverthrow_1.okAsync)(undefined);
+            const next = [...sources, { path: normalizedPath, addedAtMs: nowMs }];
+            return this.persist(next);
+        }));
+    }
+    detach(sourcePath) {
+        const normalizedPath = path_1.default.resolve(sourcePath);
+        return this.withLock(() => this.readSources().andThen((sources) => {
+            const next = sources.filter((s) => s.path !== normalizedPath);
+            if (next.length === sources.length)
+                return (0, neverthrow_1.okAsync)(undefined);
+            return this.persist(next);
+        }));
+    }
+    readSources() {
+        const filePath = this.dataDir.managedSourcesPath();
+        return this.fs.readFileUtf8(filePath)
+            .orElse((e) => {
+            if (e.code === 'FS_NOT_FOUND')
+                return (0, neverthrow_1.okAsync)('');
+            return (0, neverthrow_1.errAsync)(mapFsToManagedSourceError(e));
+        })
+            .andThen((raw) => {
+            if (raw === '')
+                return (0, neverthrow_1.okAsync)([]);
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                return (0, neverthrow_1.errAsync)({
+                    code: 'MANAGED_SOURCE_CORRUPTION',
+                    message: `Invalid JSON in managed sources file: ${filePath}`,
+                });
+            }
+            const validated = ManagedSourcesFileSchema.safeParse(parsed);
+            if (!validated.success) {
+                return (0, neverthrow_1.errAsync)({
+                    code: 'MANAGED_SOURCE_CORRUPTION',
+                    message: `Managed sources file has invalid shape: ${filePath}`,
+                });
+            }
+            return (0, neverthrow_1.okAsync)(normalizeRecords(validated.data.sources));
+        });
+    }
+    persist(sources) {
+        const filePath = this.dataDir.managedSourcesPath();
+        const dir = path_1.default.dirname(filePath);
+        const tmpPath = `${filePath}.tmp`;
+        const fileValue = {
+            v: 1,
+            sources: [...normalizeRecords(sources)],
+        };
+        const canonical = (0, jcs_js_1.toCanonicalBytes)(fileValue).mapErr((e) => ({
+            code: 'MANAGED_SOURCE_IO_ERROR',
+            message: `Failed to canonicalize managed sources state: ${e.message}`,
+        }));
+        if (canonical.isErr())
+            return (0, neverthrow_1.errAsync)(canonical.error);
+        const bytes = canonical.value;
+        return this.fs.mkdirp(dir)
+            .mapErr(mapFsToManagedSourceError)
+            .andThen(() => this.fs.openWriteTruncate(tmpPath).mapErr(mapFsToManagedSourceError))
+            .andThen(({ fd }) => this.fs.writeAll(fd, bytes)
+            .mapErr(mapFsToManagedSourceError)
+            .andThen(() => this.fs.fsyncFile(fd).mapErr(mapFsToManagedSourceError))
+            .andThen(() => this.fs.closeFile(fd).mapErr(mapFsToManagedSourceError))
+            .orElse((e) => this.fs.closeFile(fd)
+            .mapErr(() => e)
+            .andThen(() => (0, neverthrow_1.errAsync)(e))))
+            .andThen(() => this.fs.rename(tmpPath, filePath).mapErr(mapFsToManagedSourceError))
+            .andThen(() => this.fs.fsyncDir(dir).mapErr(mapFsToManagedSourceError));
+    }
+    withLock(run) {
+        const lockPath = this.dataDir.managedSourcesLockPath();
+        const dir = path_1.default.dirname(lockPath);
+        const lockBytes = new TextEncoder().encode(JSON.stringify({ v: 1, pid: process.pid }));
+        return this.fs.mkdirp(dir)
+            .mapErr(mapFsToManagedSourceError)
+            .andThen(() => this.fs.openExclusive(lockPath, lockBytes)
+            .mapErr((e) => {
+            const mapped = mapFsToManagedSourceError(e);
+            if (mapped.code === 'MANAGED_SOURCE_BUSY') {
+                return { ...mapped, lockPath };
+            }
+            return mapped;
+        }))
+            .andThen(({ fd }) => this.fs.fsyncFile(fd)
+            .mapErr(mapFsToManagedSourceError)
+            .andThen(() => this.fs.closeFile(fd).mapErr(mapFsToManagedSourceError))
+            .andThen(() => run())
+            .andThen((value) => this.fs.unlink(lockPath)
+            .orElse((e) => {
+            if (e.code === 'FS_NOT_FOUND')
+                return (0, neverthrow_1.okAsync)(undefined);
+            return (0, neverthrow_1.errAsync)(mapFsToManagedSourceError(e));
+        })
+            .map(() => value))
+            .orElse((error) => this.fs.unlink(lockPath)
+            .orElse((e) => {
+            if (e.code === 'FS_NOT_FOUND')
+                return (0, neverthrow_1.okAsync)(undefined);
+            return (0, neverthrow_1.errAsync)(mapFsToManagedSourceError(e));
+        })
+            .andThen(() => (0, neverthrow_1.errAsync)(error))));
+    }
+}
+exports.LocalManagedSourceStoreV2 = LocalManagedSourceStoreV2;

package/dist/v2/ports/data-dir.port.d.ts

@@ -14,4 +14,6 @@ export interface DataDirPortV2 {
     sessionManifestPath(sessionId: SessionId): string;
     sessionLockPath(sessionId: SessionId): string;
     tokenIndexPath(): string;
+    managedSourcesPath(): string;
+    managedSourcesLockPath(): string;
 }

package/dist/v2/ports/managed-source-store.port.d.ts

@@ -0,0 +1,25 @@
+import type { ResultAsync } from 'neverthrow';
+export type ManagedSourceStoreError = {
+    readonly code: 'MANAGED_SOURCE_BUSY';
+    readonly message: string;
+    readonly retry: {
+        readonly kind: 'retryable_after_ms';
+        readonly afterMs: number;
+    };
+    readonly lockPath: string;
+} | {
+    readonly code: 'MANAGED_SOURCE_IO_ERROR';
+    readonly message: string;
+} | {
+    readonly code: 'MANAGED_SOURCE_CORRUPTION';
+    readonly message: string;
+};
+export interface ManagedSourceRecordV2 {
+    readonly path: string;
+    readonly addedAtMs: number;
+}
+export interface ManagedSourceStorePortV2 {
+    list(): ResultAsync<readonly ManagedSourceRecordV2[], ManagedSourceStoreError>;
+    attach(path: string): ResultAsync<void, ManagedSourceStoreError>;
+    detach(path: string): ResultAsync<void, ManagedSourceStoreError>;
+}

package/dist/v2/ports/managed-source-store.port.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "3.12.0",
+  "version": "3.14.0",
   "description": "Step-by-step workflow enforcement for AI agents via MCP",
   "license": "MIT",
   "repository": {
@@ -40,6 +40,7 @@
     "watch": "tsc --watch",
     "validate:workflows": "bash scripts/validate-workflows.sh",
     "validate:registry": "node scripts/validate-workflows-registry.ts",
+    "stamp-workflow": "node scripts/stamp-workflow.ts",
     "validate:authoring-spec": "node scripts/validate-authoring-spec.js",
     "validate:authoring-docs": "node scripts/generate-authoring-docs.js --check",
     "validate:workflow-discovery": "node scripts/validate-workflow-discovery.js",

package/spec/authoring-spec.json

@@ -20,7 +20,8 @@
     "When a workflow feature lands or changes, update the schema and runtime first.",
     "Then update this authoring spec so guidance matches the shipped behavior.",
     "Then regenerate or update human-facing docs and examples derived from this spec.",
-    "Do not leave authoring guidance behind the runtime."
+    "Do not leave authoring guidance behind the runtime.",
+    "Increment `version` when any required-level rule is added, removed, or materially changed. Add a `changelog` entry for the new version."
   ],
   "ruleModel": {
     "levels": [
@@ -1402,6 +1403,12 @@
       ]
     }
   ],
-  "plannedRules": [
+  "plannedRules": [],
+  "changelog": [
+    {
+      "version": 3,
+      "date": "2026-03-21",
+      "summary": "Baseline version at staleness feature introduction."
+    }
   ]
 }