@paths.design/caws-cli 10.2.0 → 11.1.0

package/dist/store/lifecycle-transaction.d.ts

@@ -0,0 +1,79 @@
+import { type ChainedEvent, type EventBody, type Result, type Diagnostic } from '@paths.design/caws-kernel';
+/** A single file write the transaction will perform. Order in
+ *  `plannedWrites` is the order writes are applied. */
+export interface LifecycleFileWrite {
+    /** Absolute path of the file to write. */
+    readonly path: string;
+    /** New contents for this file. */
+    readonly contents: string | Buffer;
+    /** When true, writeFileAtomic preserves the target's existing mode. */
+    readonly preserveMode?: boolean;
+}
+/** Inputs to a lifecycle transaction. */
+export interface LifecycleTransactionPlan {
+    /** Path to the .caws/ directory (passed through to appendEvent). */
+    readonly cawsDir: string;
+    /** Files to write in deterministic order. */
+    readonly plannedWrites: readonly LifecycleFileWrite[];
+    /** Event(s) to append after state writes succeed. Appended in array
+     *  order. The transaction supports multiple events per command (e.g.,
+     *  worktree create emits worktree_created then worktree_bound). */
+    readonly events: readonly EventBody[];
+    /** Optional pre-write validation. Runs AFTER the lock is held and
+     *  files are read, BEFORE any write. Returns Err to abort the
+     *  transaction with LIFECYCLE_PLAN_REJECTED. */
+    readonly validate?: () => Result<void>;
+    /** When true, call fsyncDir on each affected directory after writes.
+     *  Defaults to false; see module header for rationale. */
+    readonly fsyncAfter?: boolean;
+}
+/** Success outcome: all state writes + all event appends succeeded. */
+export interface LifecycleTransactionSuccess {
+    readonly kind: 'success';
+    readonly writes: readonly {
+        readonly path: string;
+    }[];
+    readonly appendedEvents: readonly ChainedEvent[];
+}
+/** Partial-failure-recovered: state writes succeeded, event append
+ *  failed, rollback succeeded. The repository is in its pre-transaction
+ *  state. */
+export interface LifecyclePartialRecovered {
+    readonly kind: 'partial_failure_recovered';
+    readonly cause: readonly Diagnostic[];
+    readonly rolledBack: readonly string[];
+}
+/** Partial-failure-unrecovered: state writes succeeded, event append
+ *  failed, AND rollback also failed. The repository may be in a
+ *  partial state. The caller MUST handle the recovery instruction. */
+export interface LifecyclePartialUnrecovered {
+    readonly kind: 'partial_failure_unrecovered';
+    readonly cause: readonly Diagnostic[];
+    readonly plannedEvents: readonly EventBody[];
+    readonly writesCompleted: readonly string[];
+    readonly rolledBack: readonly string[];
+    readonly rollbackFailed: readonly {
+        readonly path: string;
+        readonly reason: string;
+    }[];
+    readonly recoveryInstruction: string;
+}
+export type LifecycleTransactionResult = LifecycleTransactionSuccess | LifecyclePartialRecovered | LifecyclePartialUnrecovered;
+/**
+ * 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
+ */
+export declare function runLifecycleTransaction(plan: LifecycleTransactionPlan): Result<LifecycleTransactionResult>;
+//# sourceMappingURL=lifecycle-transaction.d.ts.map

package/dist/store/lifecycle-transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-transaction.d.ts","sourceRoot":"","sources":["../../src/store/lifecycle-transaction.ts"],"names":[],"mappings":"AAuCA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,SAAS,EAGd,KAAK,MAAM,EACX,KAAK,UAAU,EAChB,MAAM,2BAA2B,CAAC;AASnC;uDACuD;AACvD,MAAM,WAAW,kBAAkB;IACjC,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC,uEAAuE;IACvE,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,yCAAyC;AACzC,MAAM,WAAW,wBAAwB;IACvC,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,aAAa,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACtD;;uEAEmE;IACnE,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC;;oDAEgD;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;IACvC;8DAC0D;IAC1D,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAWD,uEAAuE;AACvE,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACtD,QAAQ,CAAC,cAAc,EAAE,SAAS,YAAY,EAAE,CAAC;CAClD;AAED;;aAEa;AACb,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED;;sEAEsE;AACtE,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,6BAA6B,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,QAAQ,CAAC,aAAa,EAAE,SAAS,SAAS,EAAE,CAAC;IAC7C,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,cAAc,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACvF,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACtC;AAED,MAAM,MAAM,0BAA0B,GAClC,2BAA2B,GAC3B,yBAAyB,GACzB,2BAA2B,CAAC;AAkGhC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,wBAAwB,GAC7B,MAAM,CAAC,0BAA0B,CAAC,CA+JpC"}

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/policy-store.d.ts

@@ -0,0 +1,3 @@
+import type { PolicyLoadResult } from './types';
+export declare function loadPolicy(cawsDir: string): PolicyLoadResult;
+//# sourceMappingURL=policy-store.d.ts.map

package/dist/store/policy-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-store.d.ts","sourceRoot":"","sources":["../../src/store/policy-store.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEhD,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAmB5D"}

package/dist/store/policy-store.js

@@ -0,0 +1,65 @@
+"use strict";
+// Policy loader.
+//
+// Loads `.caws/policy.yaml`, hands the source to the kernel's
+// `parseAndValidatePolicy`, and surfaces both the parsed value and any
+// non-fatal warnings the kernel emitted. Missing file is NOT an error
+// at the store level — doctor decides whether to emit `POLICY_MISSING`.
+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.loadPolicy = loadPolicy;
+const path = __importStar(require("path"));
+const caws_kernel_1 = require("@paths.design/caws-kernel");
+const rules_1 = require("./rules");
+const yaml_store_1 = require("./yaml-store");
+function loadPolicy(cawsDir) {
+    const policyPath = path.join(cawsDir, 'policy.yaml');
+    const source = (0, yaml_store_1.readYamlSource)(policyPath);
+    if (!(0, caws_kernel_1.isOk)(source)) {
+        // Distinguish missing file (Ok-shaped) from malformed file (Err).
+        const missing = source.errors.some((e) => e.rule === rules_1.STORE_RULES.READ_MISSING_FILE);
+        if (missing) {
+            return { warnings: [], errors: [] };
+        }
+        return { warnings: [], errors: [...source.errors] };
+    }
+    const result = (0, caws_kernel_1.parseAndValidatePolicy)(source.value);
+    if (!(0, caws_kernel_1.isOk)(result)) {
+        return { warnings: [], errors: [...result.errors] };
+    }
+    const warnings = result.warnings ?? [];
+    return { policy: result.value, warnings: [...warnings], errors: [] };
+}
+//# sourceMappingURL=policy-store.js.map

package/dist/store/policy-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-store.js","sourceRoot":"","sources":["../../src/store/policy-store.ts"],"names":[],"mappings":";AAAA,iBAAiB;AACjB,EAAE;AACF,8DAA8D;AAC9D,uEAAuE;AACvE,sEAAsE;AACtE,wEAAwE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAYxE,gCAmBC;AA7BD,2CAA6B;AAC7B,2DAImC;AACnC,mCAAsC;AACtC,6CAA8C;AAG9C,SAAgB,UAAU,CAAC,OAAe;IACxC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,IAAA,2BAAc,EAAC,UAAU,CAAC,CAAC;IAC1C,IAAI,CAAC,IAAA,kBAAI,EAAC,MAAM,CAAC,EAAE,CAAC;QAClB,kEAAkE;QAClE,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,mBAAW,CAAC,iBAAiB,CAAC,CAAC;QACpF,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;QACtC,CAAC;QACD,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;IACtD,CAAC;IAED,MAAM,MAAM,GAAG,IAAA,oCAAsB,EAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACpD,IAAI,CAAC,IAAA,kBAAI,EAAC,MAAM,CAAC,EAAE,CAAC;QAClB,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;IACtD,CAAC;IAED,MAAM,QAAQ,GAA0B,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC;IAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC,GAAG,QAAQ,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AACvE,CAAC"}

package/dist/store/repo-root.d.ts

@@ -0,0 +1,46 @@
+import { type Diagnostic, type Result } from '@paths.design/caws-kernel';
+export interface RepoRoot {
+    /** Absolute path to the main repository root (parent of .git common dir). */
+    readonly repoRoot: string;
+    /** Absolute path to the .caws/ directory under the repo root. */
+    readonly cawsDir: string;
+}
+/**
+ * Pluggable git invoker. Tests stub this; production uses execFileSync.
+ *
+ * Returns the trimmed stdout on success, or throws on non-zero exit. The
+ * caller distinguishes "not a git repo" by inspecting the thrown error's
+ * stderr / status, which production execFileSync surfaces.
+ */
+export type GitRunner = (args: readonly string[], options: {
+    cwd: string;
+}) => string;
+export declare const defaultGitRunner: GitRunner;
+export interface ResolveRepoRootOptions {
+    readonly git?: GitRunner;
+    /**
+     * If true, the .caws/ directory must already exist on disk. When false
+     * (default) the function only resolves where it WOULD be, leaving
+     * creation to a different layer (e.g., `caws init`).
+     */
+    readonly requireCawsDir?: boolean;
+}
+/**
+ * Resolve the main-repo root from `cwd`, even when cwd is inside a linked
+ * worktree.
+ *
+ * Returns Err when:
+ *  - cwd is not inside a git repository, OR
+ *  - git invocation fails for another reason, OR
+ *  - `requireCawsDir: true` and `.caws/` does not exist.
+ *
+ * Programmer errors (cwd not a string, git binary missing) throw.
+ */
+export declare function resolveRepoRoot(cwd: string, options?: ResolveRepoRootOptions): Result<RepoRoot>;
+/** Construct a structured Diagnostic with the canonical store authority. */
+export declare function storeDiagnostic(rule: string, message: string, extra?: {
+    subject?: string;
+    narrowRepair?: string;
+    data?: Record<string, unknown>;
+}): Diagnostic;
+//# sourceMappingURL=repo-root.d.ts.map

package/dist/store/repo-root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-root.d.ts","sourceRoot":"","sources":["../../src/store/repo-root.ts"],"names":[],"mappings":"AAoBA,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,MAAM,EACZ,MAAM,2BAA2B,CAAC;AAOnC,MAAM,WAAW,QAAQ;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,CACtB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,KACrB,MAAM,CAAC;AAEZ,eAAO,MAAM,gBAAgB,EAAE,SAO9B,CAAC;AAMF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,sBAA2B,GACnC,MAAM,CAAC,QAAQ,CAAC,CA6DlB;AAMD,4EAA4E;AAC5E,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAO,GACtF,UAAU,CASZ"}