@paths.design/caws-cli 11.0.0 → 11.1.1

package/dist/store/lifecycle-transaction.js

@@ -0,0 +1,319 @@
+"use strict";
+// Lifecycle mutation transaction wrapper.
+//
+// LIFECYCLE-MUTATION-001 substrate: multi-file lifecycle mutations
+// serialize through .caws/state.lock and produce a typed outcome that
+// names partial-failure explicitly. The transaction is NOT a database
+// transaction — filesystem rollback is best-effort, and the useful
+// invariant is "partial failure is detected, named, and recoverable,"
+// not "rollback always succeeds."
+//
+// Operation order (within the critical section):
+//   1. acquire lifecycle lock (already done by withLifecycleLock or
+//      directly by the caller)
+//   2. read all affected files; capture original bytes for rollback
+//   3. compute planned writes (caller-provided)
+//   4. validate planned state via kernel hooks (caller-provided)
+//   5. write files in deterministic order using writeFileAtomic
+//      with preserveMode: true (per A2)
+//   6. append the transaction's event(s) through appendEvent (the SOLE
+//      v11 writer of events.jsonl)
+//   7. if event append fails, attempt rollback of all written files
+//      from captured original bytes; produce LIFECYCLE_PARTIAL_FAILURE_*
+//   8. release lock (caller's `finally`)
+//
+// fsyncDir posture (A3):
+//   This module does NOT call fsyncDir by default. Rationale: v11.1
+//   accepts rename durability without parent-directory fsync for two
+//   reasons. (a) writeFileAtomic already does file-content fsync before
+//   rename, which is the durability primitive that survives kernel
+//   crashes; only power loss between rename and dirent flush is at risk.
+//   (b) The lock + event-append step provides a recovery anchor: if a
+//   crash leaves the filesystem in a partially-renamed state, the next
+//   transaction's read step will see whichever state the filesystem
+//   committed, and the event log's last entry tells the operator the
+//   last fully-acknowledged transition. Power-loss safety is therefore
+//   bounded by the audit log, not by directory fsync. Callers needing
+//   stronger durability may pass an `fsyncAfter: true` option.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runLifecycleTransaction = runLifecycleTransaction;
+const fs = __importStar(require("fs"));
+const caws_kernel_1 = require("@paths.design/caws-kernel");
+const atomic_write_1 = require("./atomic-write");
+const events_store_1 = require("./events-store");
+const repo_root_1 = require("./repo-root");
+const rules_1 = require("./rules");
+// ─── Implementation ──────────────────────────────────────────────────────
+function captureSnapshot(filePath) {
+    try {
+        const stat = fs.statSync(filePath);
+        const originalContents = fs.readFileSync(filePath);
+        return {
+            path: filePath,
+            originalContents,
+            originalMode: stat.mode & 0o7777,
+        };
+    }
+    catch (e) {
+        const cause = e;
+        if (cause.code === 'ENOENT') {
+            return { path: filePath, originalContents: null, originalMode: undefined };
+        }
+        // Any other read failure: surface as a snapshot we don't trust.
+        // Treat as "file did not exist" for rollback purposes; the
+        // transaction's write step will hit the same error and abort.
+        return { path: filePath, originalContents: null, originalMode: undefined };
+    }
+}
+function rollbackOne(snapshot) {
+    try {
+        if (snapshot.originalContents === null) {
+            // File didn't exist before; rollback is to delete it.
+            try {
+                fs.unlinkSync(snapshot.path);
+            }
+            catch (e) {
+                const cause = e;
+                // Already gone — treat as success.
+                if (cause.code === 'ENOENT')
+                    return { ok: true };
+                return { ok: false, reason: `failed to remove ${snapshot.path}: ${cause.code ?? 'unknown'}` };
+            }
+            return { ok: true };
+        }
+        // Restore prior contents. Use writeFileAtomic with the captured
+        // mode so the rollback itself is atomic at the file level.
+        const opts = snapshot.originalMode !== undefined ? { preserveMode: true } : {};
+        // Pre-stage the target file with original mode by chmod-then-write
+        // is overkill; writeFileAtomic with preserveMode will stat the
+        // target (which currently has the failed-transaction bytes and
+        // possibly a different mode). Safer: write first with default
+        // mode, then chmod explicitly.
+        const writeResult = (0, atomic_write_1.writeFileAtomic)(snapshot.path, snapshot.originalContents, opts);
+        if (!writeResult.ok) {
+            return { ok: false, reason: `writeFileAtomic failed during rollback: ${snapshot.path}` };
+        }
+        if (snapshot.originalMode !== undefined) {
+            try {
+                fs.chmodSync(snapshot.path, snapshot.originalMode);
+            }
+            catch {
+                // Mode-restore failure during rollback: contents are restored
+                // but mode may be wrong. We do NOT escalate to unrecovered for
+                // a mode-only failure; the file content is correct.
+            }
+        }
+        return { ok: true };
+    }
+    catch (e) {
+        const cause = e;
+        return { ok: false, reason: cause.message ?? 'unknown rollback error' };
+    }
+}
+function buildRecoveryInstruction(plannedEvents, writesCompleted, rolledBack, rollbackFailed) {
+    const lines = [
+        'Lifecycle transaction left the repository in a partial state.',
+        `  ${writesCompleted.length} file write(s) completed before failure.`,
+        `  ${rolledBack.length} successfully rolled back; ${rollbackFailed.length} rollback failure(s).`,
+        '',
+        `Files that may need manual inspection:`,
+    ];
+    for (const f of rollbackFailed) {
+        lines.push(`  ${f.path} (rollback failed)`);
+    }
+    lines.push('');
+    lines.push(`Events that were NOT appended (${plannedEvents.length}):`);
+    for (const ev of plannedEvents) {
+        lines.push(`  ${ev.event} (spec_id=${ev.spec_id ?? 'n/a'})`);
+    }
+    lines.push('');
+    lines.push('Required action: review each listed file against the planned event payload above to');
+    lines.push('determine whether to redo the lifecycle transition or to manually restore prior state.');
+    lines.push('Do NOT hand-author entries into events.jsonl.');
+    return lines.join('\n');
+}
+/**
+ * Run a lifecycle transaction.
+ *
+ * The caller MUST hold the lifecycle lock (via withLifecycleLock or
+ * acquireLifecycleLock). This function does not acquire the lock
+ * itself; that responsibility lives in the caller so a higher-level
+ * orchestrator (CLI-SPECS-001, CLI-WORKTREE-001) can group multiple
+ * conceptual mutations inside one lock if needed.
+ *
+ * Returns:
+ *   Ok({ kind: 'success', ... })                    — everything worked
+ *   Ok({ kind: 'partial_failure_recovered', ... })  — rolled back cleanly
+ *   Err([LIFECYCLE_PARTIAL_FAILURE_UNRECOVERED]) — partial state remains
+ *   Err([LIFECYCLE_PLAN_REJECTED])               — validate() rejected
+ *   Err([LIFECYCLE_WRITE_FAILED])                — a write failed before events
+ */
+function runLifecycleTransaction(plan) {
+    // Step 1: validate plan (pre-write).
+    if (plan.validate) {
+        const validation = plan.validate();
+        if (!validation.ok) {
+            const diagnostics = validation.errors.map((d) => {
+                const extra = {
+                    data: { source_rule: d.rule },
+                };
+                if (d.subject !== undefined)
+                    extra.subject = d.subject;
+                return (0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, d.message, extra);
+            });
+            return (0, caws_kernel_1.err)(diagnostics);
+        }
+    }
+    // Step 2: snapshot every planned file BEFORE any write.
+    const snapshots = plan.plannedWrites.map((w) => captureSnapshot(w.path));
+    // Step 3: apply writes in deterministic order.
+    const writesCompleted = [];
+    for (let i = 0; i < plan.plannedWrites.length; i++) {
+        const w = plan.plannedWrites[i];
+        if (!w)
+            continue;
+        const opts = w.preserveMode === true ? { preserveMode: true } : {};
+        const result = (0, atomic_write_1.writeFileAtomic)(w.path, w.contents, opts);
+        if (!result.ok) {
+            // Write failed; the transaction has not yet appended any events.
+            // Roll back the writes that already succeeded.
+            const rolledBack = [];
+            const rollbackFailed = [];
+            for (let j = i - 1; j >= 0; j--) {
+                const snap = snapshots[j];
+                if (!snap)
+                    continue;
+                const r = rollbackOne(snap);
+                if (r.ok)
+                    rolledBack.push(snap.path);
+                else
+                    rollbackFailed.push({ path: snap.path, reason: r.reason });
+            }
+            if (rollbackFailed.length === 0) {
+                const diagnostics = result.errors.map((d) => {
+                    const extra = {
+                        data: { source_rule: d.rule, rolled_back: rolledBack.length },
+                    };
+                    if (d.subject !== undefined)
+                        extra.subject = d.subject;
+                    return (0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_WRITE_FAILED, d.message, extra);
+                });
+                return (0, caws_kernel_1.err)(diagnostics);
+            }
+            // Rollback during pre-event-write failure is itself unrecovered.
+            const recoveryInstruction = buildRecoveryInstruction(plan.events, writesCompleted, rolledBack, rollbackFailed);
+            return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PARTIAL_FAILURE_UNRECOVERED, `Lifecycle write failed and rollback could not fully restore prior state.`, {
+                subject: w.path,
+                data: {
+                    writes_completed: writesCompleted,
+                    rolled_back: rolledBack,
+                    rollback_failed: rollbackFailed,
+                    recovery_instruction: recoveryInstruction,
+                },
+            }));
+        }
+        writesCompleted.push(w.path);
+    }
+    // Step 3b (optional): fsync affected directories.
+    if (plan.fsyncAfter === true) {
+        const dirs = new Set();
+        for (const w of plan.plannedWrites) {
+            const lastSlash = w.path.lastIndexOf('/');
+            if (lastSlash > 0)
+                dirs.add(w.path.slice(0, lastSlash));
+        }
+        for (const d of dirs) {
+            (0, atomic_write_1.fsyncDir)(d);
+        }
+    }
+    // Step 4: append events through appendEvent (the SOLE v11 events
+    // writer). On any failure, attempt rollback.
+    const appendedEvents = [];
+    for (let i = 0; i < plan.events.length; i++) {
+        const body = plan.events[i];
+        if (!body)
+            continue;
+        const result = (0, events_store_1.appendEvent)(plan.cawsDir, body);
+        if (!result.ok) {
+            // Roll back all writes. Reverse order so latest writes are
+            // restored to their pre-transaction state first.
+            const rolledBack = [];
+            const rollbackFailed = [];
+            for (let j = snapshots.length - 1; j >= 0; j--) {
+                const snap = snapshots[j];
+                if (!snap)
+                    continue;
+                const r = rollbackOne(snap);
+                if (r.ok)
+                    rolledBack.push(snap.path);
+                else
+                    rollbackFailed.push({ path: snap.path, reason: r.reason });
+            }
+            // Also, previously-appended events in this transaction are
+            // already in the log. We CANNOT un-append from a hash-chained
+            // log without breaking the chain. Surface this in the recovery
+            // instruction.
+            if (rollbackFailed.length === 0 && appendedEvents.length === 0) {
+                return (0, caws_kernel_1.ok)({
+                    kind: 'partial_failure_recovered',
+                    cause: result.errors,
+                    rolledBack,
+                });
+            }
+            const recoveryInstruction = buildRecoveryInstruction(plan.events, writesCompleted, rolledBack, rollbackFailed);
+            return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PARTIAL_FAILURE_UNRECOVERED, `Lifecycle event append failed. ${appendedEvents.length} event(s) were already appended before the failure; ${rollbackFailed.length} file(s) could not be rolled back.`, {
+                subject: body.event,
+                data: {
+                    writes_completed: writesCompleted,
+                    rolled_back: rolledBack,
+                    rollback_failed: rollbackFailed,
+                    already_appended: appendedEvents.map((e) => ({
+                        seq: e.seq,
+                        event_hash: e.event_hash,
+                    })),
+                    recovery_instruction: recoveryInstruction,
+                },
+            }));
+        }
+        appendedEvents.push(result.value);
+    }
+    return (0, caws_kernel_1.ok)({
+        kind: 'success',
+        writes: writesCompleted.map((path) => ({ path })),
+        appendedEvents,
+    });
+}
+//# sourceMappingURL=lifecycle-transaction.js.map

package/dist/store/lifecycle-transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-transaction.js","sourceRoot":"","sources":["../../src/store/lifecycle-transaction.ts"],"names":[],"mappings":"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"}

package/dist/store/rules.d.ts

@@ -47,6 +47,22 @@ export declare const STORE_RULES: {
     readonly INIT_LEGACY_RESIDUE: "store.init.legacy_residue";
     /** init seeded a default policy that did not pass kernel validation. */
     readonly INIT_DEFAULT_POLICY_INVALID: "store.init.default_policy_invalid";
+    /** Failed to acquire the global .caws/state.lock after bounded retry. */
+    readonly LIFECYCLE_LOCK_CONTENTION: "store.lifecycle.lock_contention";
+    /** Plan validation rejected the proposed transaction before any write. */
+    readonly LIFECYCLE_PLAN_REJECTED: "store.lifecycle.plan_rejected";
+    /** A planned file write failed; the transaction aborted before event append. */
+    readonly LIFECYCLE_WRITE_FAILED: "store.lifecycle.write_failed";
+    /** State writes succeeded but event append failed; rollback succeeded. */
+    readonly LIFECYCLE_PARTIAL_FAILURE_RECOVERED: "store.lifecycle.partial_failure_recovered";
+    /** State writes succeeded, event append failed, AND rollback also failed.
+     *  Caller MUST handle the recovery instruction in the diagnostic data. */
+    readonly LIFECYCLE_PARTIAL_FAILURE_UNRECOVERED: "store.lifecycle.partial_failure_unrecovered";
+    /** yaml-patch refused an ambiguous mutation (e.g., duplicate top-level key,
+     *  or a flow-style mapping at the target location). */
+    readonly YAML_PATCH_AMBIGUOUS: "store.yaml_patch.ambiguous";
+    /** yaml-patch refused because the target key was not found in the document. */
+    readonly YAML_PATCH_KEY_NOT_FOUND: "store.yaml_patch.key_not_found";
 };
 export type StoreRule = (typeof STORE_RULES)[keyof typeof STORE_RULES];
 export declare const STORE_RULE_PREFIXES: readonly ["store.repo_root.", "store.read.", "store.write.", "store.specs.", "store.waivers.", "store.registry.", "store.events.", "store.init."];

package/dist/store/rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/store/rules.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,WAAW;;;;IAOtB,+EAA+E;;;;IAI/E,0BAA0B;;IAE1B,0BAA0B;;;IAK1B,+EAA+E;;IAI/E,4EAA4E;;IAE5E,2EAA2E;;IAE3E,gDAAgD;;IAIhD,sEAAsE;;IAItE,8EAA8E;;IAE9E,kDAAkD;;IAElD,oDAAoD;;IAEpD,4CAA4C;;IAE5C,sEAAsE;;IAEtE,2DAA2D;;IAI3D,mEAAmE;;IAEnE,6EAA6E;;IAE7E,uEAAuE;;IAEvE,uEAAuE;;IAEvE,uEAAuE;;IAIvE,iEAAiE;;IAEjE,wEAAwE;;CAEhE,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAEvE,eAAO,MAAM,mBAAmB,mJAStB,CAAC"}
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/store/rules.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,WAAW;;;;IAOtB,+EAA+E;;;;IAI/E,0BAA0B;;IAE1B,0BAA0B;;;IAK1B,+EAA+E;;IAI/E,4EAA4E;;IAE5E,2EAA2E;;IAE3E,gDAAgD;;IAIhD,sEAAsE;;IAItE,8EAA8E;;IAE9E,kDAAkD;;IAElD,oDAAoD;;IAEpD,4CAA4C;;IAE5C,sEAAsE;;IAEtE,2DAA2D;;IAI3D,mEAAmE;;IAEnE,6EAA6E;;IAE7E,uEAAuE;;IAEvE,uEAAuE;;IAEvE,uEAAuE;;IAIvE,iEAAiE;;IAEjE,wEAAwE;;IAIxE,yEAAyE;;IAEzE,0EAA0E;;IAE1E,gFAAgF;;IAEhF,0EAA0E;;IAG1E;8EAC0E;;IAG1E;2DACuD;;IAEvD,+EAA+E;;CAEvE,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAEvE,eAAO,MAAM,mBAAmB,mJAStB,CAAC"}

package/dist/store/rules.js

@@ -64,6 +64,23 @@ exports.STORE_RULES = {
     INIT_LEGACY_RESIDUE: 'store.init.legacy_residue',
     /** init seeded a default policy that did not pass kernel validation. */
     INIT_DEFAULT_POLICY_INVALID: 'store.init.default_policy_invalid',
+    // ---- lifecycle mutation substrate (LIFECYCLE-MUTATION-001) -------------
+    /** Failed to acquire the global .caws/state.lock after bounded retry. */
+    LIFECYCLE_LOCK_CONTENTION: 'store.lifecycle.lock_contention',
+    /** Plan validation rejected the proposed transaction before any write. */
+    LIFECYCLE_PLAN_REJECTED: 'store.lifecycle.plan_rejected',
+    /** A planned file write failed; the transaction aborted before event append. */
+    LIFECYCLE_WRITE_FAILED: 'store.lifecycle.write_failed',
+    /** State writes succeeded but event append failed; rollback succeeded. */
+    LIFECYCLE_PARTIAL_FAILURE_RECOVERED: 'store.lifecycle.partial_failure_recovered',
+    /** State writes succeeded, event append failed, AND rollback also failed.
+     *  Caller MUST handle the recovery instruction in the diagnostic data. */
+    LIFECYCLE_PARTIAL_FAILURE_UNRECOVERED: 'store.lifecycle.partial_failure_unrecovered',
+    /** yaml-patch refused an ambiguous mutation (e.g., duplicate top-level key,
+     *  or a flow-style mapping at the target location). */
+    YAML_PATCH_AMBIGUOUS: 'store.yaml_patch.ambiguous',
+    /** yaml-patch refused because the target key was not found in the document. */
+    YAML_PATCH_KEY_NOT_FOUND: 'store.yaml_patch.key_not_found',
 };
 exports.STORE_RULE_PREFIXES = [
     'store.repo_root.',

package/dist/store/rules.js.map

@@ -1 +1 @@
-{"version":3,"file":"rules.js","sourceRoot":"","sources":["../../src/store/rules.ts"],"names":[],"mappings":";AAAA,yDAAyD;AACzD,EAAE;AACF,yEAAyE;AACzE,qEAAqE;AACrE,wEAAwE;AACxE,wEAAwE;;;AAE3D,QAAA,WAAW,GAAG;IACzB,4EAA4E;IAC5E,wBAAwB,EAAE,gCAAgC;IAC1D,+BAA+B,EAAE,uCAAuC;IACxE,0BAA0B,EAAE,kCAAkC;IAE9D,6EAA6E;IAC7E,+EAA+E;IAC/E,iBAAiB,EAAE,yBAAyB;IAC5C,eAAe,EAAE,uBAAuB;IACxC,cAAc,EAAE,sBAAsB;IACtC,0BAA0B;IAC1B,iBAAiB,EAAE,yBAAyB;IAC5C,0BAA0B;IAC1B,iBAAiB,EAAE,yBAAyB;IAE5C,6EAA6E;IAC7E,eAAe,EAAE,uBAAuB;IACxC,+EAA+E;IAC/E,0BAA0B,EAAE,kCAAkC;IAE9D,6EAA6E;IAC7E,4EAA4E;IAC5E,kBAAkB,EAAE,0BAA0B;IAC9C,2EAA2E;IAC3E,sBAAsB,EAAE,8BAA8B;IACtD,gDAAgD;IAChD,kBAAkB,EAAE,0BAA0B;IAE9C,4EAA4E;IAC5E,sEAAsE;IACtE,mBAAmB,EAAE,2BAA2B;IAEhD,4EAA4E;IAC5E,8EAA8E;IAC9E,oBAAoB,EAAE,4BAA4B;IAClD,kDAAkD;IAClD,wBAAwB,EAAE,gCAAgC;IAC1D,oDAAoD;IACpD,oBAAoB,EAAE,4BAA4B;IAClD,4CAA4C;IAC5C,yBAAyB,EAAE,iCAAiC;IAC5D,sEAAsE;IACtE,sBAAsB,EAAE,8BAA8B;IACtD,2DAA2D;IAC3D,iBAAiB,EAAE,yBAAyB;IAE5C,4EAA4E;IAC5E,mEAAmE;IACnE,8BAA8B,EAAE,sCAAsC;IACtE,6EAA6E;IAC7E,4BAA4B,EAAE,oCAAoC;IAClE,uEAAuE;IACvE,0BAA0B,EAAE,kCAAkC;IAC9D,uEAAuE;IACvE,sBAAsB,EAAE,8BAA8B;IACtD,uEAAuE;IACvE,8BAA8B,EAAE,sCAAsC;IAEtE,4EAA4E;IAC5E,iEAAiE;IACjE,mBAAmB,EAAE,2BAA2B;IAChD,wEAAwE;IACxE,2BAA2B,EAAE,mCAAmC;CACxD,CAAC;AAIE,QAAA,mBAAmB,GAAG;IACjC,kBAAkB;IAClB,aAAa;IACb,cAAc;IACd,cAAc;IACd,gBAAgB;IAChB,iBAAiB;IACjB,eAAe;IACf,aAAa;CACL,CAAC"}
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../../src/store/rules.ts"],"names":[],"mappings":";AAAA,yDAAyD;AACzD,EAAE;AACF,yEAAyE;AACzE,qEAAqE;AACrE,wEAAwE;AACxE,wEAAwE;;;AAE3D,QAAA,WAAW,GAAG;IACzB,4EAA4E;IAC5E,wBAAwB,EAAE,gCAAgC;IAC1D,+BAA+B,EAAE,uCAAuC;IACxE,0BAA0B,EAAE,kCAAkC;IAE9D,6EAA6E;IAC7E,+EAA+E;IAC/E,iBAAiB,EAAE,yBAAyB;IAC5C,eAAe,EAAE,uBAAuB;IACxC,cAAc,EAAE,sBAAsB;IACtC,0BAA0B;IAC1B,iBAAiB,EAAE,yBAAyB;IAC5C,0BAA0B;IAC1B,iBAAiB,EAAE,yBAAyB;IAE5C,6EAA6E;IAC7E,eAAe,EAAE,uBAAuB;IACxC,+EAA+E;IAC/E,0BAA0B,EAAE,kCAAkC;IAE9D,6EAA6E;IAC7E,4EAA4E;IAC5E,kBAAkB,EAAE,0BAA0B;IAC9C,2EAA2E;IAC3E,sBAAsB,EAAE,8BAA8B;IACtD,gDAAgD;IAChD,kBAAkB,EAAE,0BAA0B;IAE9C,4EAA4E;IAC5E,sEAAsE;IACtE,mBAAmB,EAAE,2BAA2B;IAEhD,4EAA4E;IAC5E,8EAA8E;IAC9E,oBAAoB,EAAE,4BAA4B;IAClD,kDAAkD;IAClD,wBAAwB,EAAE,gCAAgC;IAC1D,oDAAoD;IACpD,oBAAoB,EAAE,4BAA4B;IAClD,4CAA4C;IAC5C,yBAAyB,EAAE,iCAAiC;IAC5D,sEAAsE;IACtE,sBAAsB,EAAE,8BAA8B;IACtD,2DAA2D;IAC3D,iBAAiB,EAAE,yBAAyB;IAE5C,4EAA4E;IAC5E,mEAAmE;IACnE,8BAA8B,EAAE,sCAAsC;IACtE,6EAA6E;IAC7E,4BAA4B,EAAE,oCAAoC;IAClE,uEAAuE;IACvE,0BAA0B,EAAE,kCAAkC;IAC9D,uEAAuE;IACvE,sBAAsB,EAAE,8BAA8B;IACtD,uEAAuE;IACvE,8BAA8B,EAAE,sCAAsC;IAEtE,4EAA4E;IAC5E,iEAAiE;IACjE,mBAAmB,EAAE,2BAA2B;IAChD,wEAAwE;IACxE,2BAA2B,EAAE,mCAAmC;IAEhE,2EAA2E;IAC3E,yEAAyE;IACzE,yBAAyB,EAAE,iCAAiC;IAC5D,0EAA0E;IAC1E,uBAAuB,EAAE,+BAA+B;IACxD,gFAAgF;IAChF,sBAAsB,EAAE,8BAA8B;IACtD,0EAA0E;IAC1E,mCAAmC,EACjC,2CAA2C;IAC7C;8EAC0E;IAC1E,qCAAqC,EACnC,6CAA6C;IAC/C;2DACuD;IACvD,oBAAoB,EAAE,4BAA4B;IAClD,+EAA+E;IAC/E,wBAAwB,EAAE,gCAAgC;CAClD,CAAC;AAIE,QAAA,mBAAmB,GAAG;IACjC,kBAAkB;IAClB,aAAa;IACb,cAAc;IACd,cAAc;IACd,gBAAgB;IAChB,iBAAiB;IACjB,eAAe;IACf,aAAa;CACL,CAAC"}

package/dist/store/specs-writer.d.ts

@@ -0,0 +1,61 @@
+import { type EventBody, type Result, type Spec, type Diagnostic } from '@paths.design/caws-kernel';
+export interface CreateSpecInput {
+    readonly id: string;
+    readonly title: string;
+    readonly mode: 'feature' | 'refactor' | 'fix' | 'doc' | 'chore';
+    readonly riskTier: 1 | 2 | 3;
+    /** Initial state. v11.1 defaults to active. */
+    readonly initialState?: 'active' | 'draft';
+    /** Override the timestamp used for created_at + the event ts. Tests inject. */
+    readonly now?: () => Date;
+    /** The EventBody actor envelope (built by the shell layer). */
+    readonly actor: EventBody['actor'];
+}
+export interface CloseSpecInput {
+    readonly id: string;
+    readonly resolution: 'completed' | 'superseded' | 'abandoned';
+    readonly reason?: string;
+    readonly mergeCommit?: string;
+    readonly supersededBy?: string;
+    readonly now?: () => Date;
+    readonly actor: EventBody['actor'];
+}
+export interface ArchiveSpecInput {
+    readonly id: string;
+    readonly reason?: string;
+    readonly now?: () => Date;
+    readonly actor: EventBody['actor'];
+}
+export type SpecWriterOutcome = {
+    readonly kind: 'success';
+    readonly id: string;
+    readonly path: string;
+} | {
+    readonly kind: 'partial_failure_recovered';
+    readonly cause: readonly Diagnostic[];
+};
+export declare function createSpec(cawsDir: string, input: CreateSpecInput): Result<SpecWriterOutcome>;
+export declare function closeSpec(cawsDir: string, input: CloseSpecInput): Result<SpecWriterOutcome>;
+export declare function archiveSpec(cawsDir: string, input: ArchiveSpecInput): Result<SpecWriterOutcome>;
+export interface SpecsListEntry {
+    readonly id: string;
+    readonly title: string;
+    readonly lifecycle_state: string;
+    readonly path: string;
+}
+export interface SpecsListResult {
+    readonly active: readonly SpecsListEntry[];
+    readonly archived: readonly SpecsListEntry[];
+}
+/** List specs by lifecycle state, optionally including archived ones. */
+export declare function listSpecs(cawsDir: string, options?: {
+    readonly includeArchived?: boolean;
+}): Result<SpecsListResult>;
+/** Find a spec by id under active or archive locations. */
+export declare function showSpec(cawsDir: string, id: string): Result<{
+    readonly spec: Spec;
+    readonly path: string;
+    readonly source: string;
+}>;
+export type { EventBody };
+//# sourceMappingURL=specs-writer.d.ts.map

package/dist/store/specs-writer.d.ts.map

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