@paths.design/caws-cli 11.1.7 → 11.1.8

package/dist/store/events-migration.js

@@ -0,0 +1,358 @@
+"use strict";
+// Pure migration module for v10→v11 events.jsonl rotation
+// (CAWS-MIGRATE-V10-EVENTS-001 A9).
+//
+// This module contains zero filesystem I/O and zero shell parsing. It
+// classifies a raw events.jsonl payload, gathers actor-shape stats and
+// tail metadata, and produces a deterministic rotation plan. The shell
+// reads files, calls into this module, prints the plan, and (on --apply)
+// invokes rotateEvents in events-store.ts. The shell is the only layer
+// that touches `.caws/`.
+//
+// This mirrors the worktrees-migration.ts precedent: pure detector +
+// pure planner + shell-does-IO. Refer to worktrees-migration.ts for the
+// canonical pattern.
+//
+// Note on validation: detectEventsLogShape NEVER calls validateChainedEvent.
+// Calling the strict validator on a v10 line is the exact failure mode
+// this slice exists to repair (the v11 envelope shape rejects every line
+// where actor is a string). The detector parses each line with JSON.parse
+// defensively and classifies actor shape by direct type inspection. See
+// docs/architecture/caws-vnext-command-surface.md invariant 14 and the
+// rotateEvents tolerant-scan helper in events-store.ts.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIGRATION_RULES = void 0;
+exports.detectEventsLogShape = detectEventsLogShape;
+exports.detectV10SpecsPresent = detectV10SpecsPresent;
+exports.planEventsRotation = planEventsRotation;
+const caws_kernel_1 = require("@paths.design/caws-kernel");
+const caws_kernel_2 = require("@paths.design/caws-kernel");
+// ---------------------------------------------------------------------------
+// Migration-local rule constants
+//
+// These rules are local to the migration surface and named with the
+// `store.events.migration.*` prefix. They are emitted only by this
+// module and by the shell command that invokes it (A10).
+// ---------------------------------------------------------------------------
+exports.MIGRATION_RULES = {
+    /** events.jsonl could not be JSON-parsed at all; every line failed. */
+    UNPARSEABLE_INPUT: 'store.events.migration.unparseable_input',
+    /** events.jsonl is empty; there is nothing to migrate or rotate. */
+    EMPTY_INPUT: 'store.events.migration.empty_input',
+    /** A v10-shape spec YAML was detected during half-upgrade scan. */
+    V10_SPEC_DETECTED: 'store.events.migration.v10_spec_detected',
+    /** events.jsonl has SOME unparseable lines alongside parseable ones.
+     *  The chain_rotated payload's prior_chain_status enum has no honest
+     *  label for this case (parseable_unverified implies every line
+     *  parsed; unparseable implies none did), so the planner refuses.
+     *  Mirrors STORE_RULES.EVENTS_ROTATE_PARTIAL_CORRUPTION in rotateEvents
+     *  so dry-run and apply paths agree. */
+    PARTIAL_CORRUPTION_REFUSED: 'store.events.migration.partial_corruption_refused',
+    /** The shell could not scan .caws/specs/ for v10-shape YAMLs (directory
+     *  missing, unreadable, or sparse-checkout-excluded). The half-upgrade
+     *  refusal CANNOT be enforced without a complete scan, so the migration
+     *  command refuses by default rather than silently bypass the guard.
+     *  No friction-flag escape in v11.2 scope. */
+    SPEC_SCAN_UNAVAILABLE: 'store.events.migration.spec_scan_unavailable',
+    /** Bug-class assertion: dry-run reported an archive name X and the
+     *  apply path (rotateEvents) returned a different archive name Y.
+     *  This indicates the dry-run's now-clock and the apply's now-clock
+     *  drifted, or windowsSafeIso diverged between events-migration.ts
+     *  and events-store.ts. Either way it is a programmer error, not an
+     *  operator error; the shell surfaces it as an internal failure. */
+    INTERNAL_DRYRUN_APPLY_MISMATCH: 'store.events.migration.internal_dryrun_apply_mismatch',
+    /** events migrate refused because the underlying log is fully
+     *  unparseable. Migration cannot claim it found a v10 chain. The
+     *  lower-level `caws events rotate` may still archive a fully
+     *  unparseable log under the honest 'unparseable' status as evidence
+     *  quarantine — that semantic is intentional and distinct from
+     *  migration. */
+    MIGRATE_UNPARSEABLE_REFUSED: 'store.events.migration.unparseable_refused',
+    /** verify-archive: events.jsonl exists but contains no chain_rotated
+     *  event. There is nothing to verify against. */
+    VERIFY_NO_ROTATION_EVENT: 'store.events.verify_archive.no_rotation_event',
+    /** verify-archive: the archive file named by the most recent
+     *  chain_rotated event does not exist on disk. */
+    VERIFY_ARCHIVE_MISSING: 'store.events.verify_archive.archive_missing',
+    /** verify-archive: the current events.jsonl could not be loaded
+     *  (e.g., malformed JSON line, invalid chain). The shell cannot
+     *  determine the most recent chain_rotated event. */
+    VERIFY_CURRENT_CHAIN_INVALID: 'store.events.verify_archive.current_chain_invalid',
+};
+/**
+ * Classify the actor-shape of every non-empty line in a raw events.jsonl
+ * payload. Pure: takes the file contents as a string, returns the
+ * detection result. No filesystem access.
+ *
+ * Errors:
+ *   - returns Err for an empty input. The shell treats this as "nothing
+ *     to do" rather than a hard error — the same condition rotateEvents
+ *     refuses on, so the migration command can short-circuit before
+ *     calling into the store.
+ *
+ * The detector deliberately does NOT call validateChainedEvent: the
+ * whole point of this slice is to handle v10-shape lines that the
+ * strict validator rejects. JSON.parse + direct actor-shape inspection
+ * is the entire contract.
+ */
+function detectEventsLogShape(raw) {
+    const trailingNewline = raw.endsWith('\n');
+    const parts = raw.split('\n');
+    const lines = trailingNewline ? parts.slice(0, -1) : parts;
+    const nonEmpty = lines.filter((l) => l.length > 0);
+    if (nonEmpty.length === 0) {
+        return (0, caws_kernel_2.err)((0, caws_kernel_1.diagnostic)({
+            rule: exports.MIGRATION_RULES.EMPTY_INPUT,
+            authority: 'kernel/diagnostics',
+            message: 'events.jsonl is empty; nothing to migrate. rotateEvents refuses on the same condition (EVENTS_ROTATE_NOTHING_TO_ROTATE).',
+        }));
+    }
+    let v10 = 0;
+    let v11 = 0;
+    let bad = 0;
+    let tailHash = null;
+    let tailSeq = null;
+    for (let i = 0; i < nonEmpty.length; i++) {
+        const line = nonEmpty[i];
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            bad += 1;
+            continue;
+        }
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            bad += 1;
+            continue;
+        }
+        const obj = parsed;
+        const actor = obj['actor'];
+        if (typeof actor === 'string') {
+            v10 += 1;
+        }
+        else if (actor !== null &&
+            typeof actor === 'object' &&
+            !Array.isArray(actor) &&
+            typeof actor['kind'] === 'string') {
+            v11 += 1;
+        }
+        else {
+            bad += 1;
+        }
+        if (i === nonEmpty.length - 1) {
+            const eh = obj['event_hash'];
+            if (typeof eh === 'string' && /^sha256:[0-9a-f]{64}$/.test(eh)) {
+                tailHash = eh;
+            }
+            const sq = obj['seq'];
+            if (typeof sq === 'number' && Number.isInteger(sq) && sq >= 1) {
+                tailSeq = sq;
+            }
+        }
+    }
+    const kind = classifyKind(v10, v11, bad);
+    return (0, caws_kernel_2.ok)({
+        kind,
+        stats: { v10_string_actor: v10, v11_object_actor: v11, unparseable: bad },
+        lineCount: nonEmpty.length,
+        tailHash,
+        tailSeq,
+    });
+}
+function classifyKind(v10, v11, bad) {
+    const totalParseable = v10 + v11;
+    if (totalParseable === 0 && bad > 0)
+        return 'unparseable_only';
+    if (v10 > 0 && v11 > 0)
+        return 'mixed_v10_v11';
+    if (v10 > 0)
+        return 'all_v10';
+    // v11 > 0 with no v10. We allow unparseable to coexist (rare crash
+    // recovery line) and still report 'all_v11' — the planner's clean-chain
+    // check explicitly excludes unparseable > 0 from triggering the friction
+    // flag, mirroring rotateEvents's isCleanV11 condition in events-store.ts.
+    if (v11 > 0)
+        return 'all_v11';
+    // No parseable lines and no unparseable lines reaches here only if the
+    // input was empty, which the caller handled before classifyKind ran.
+    return 'unparseable_only';
+}
+/**
+ * Minimal v10-vs-v11 spec YAML scanner. Used by the events migrate
+ * command to enforce the half-upgrade refusal (A10): if v10-shape spec
+ * YAMLs exist alongside v10 events, the operator must either run the
+ * specs migration first or explicitly pass --allow-partial-upgrade.
+ *
+ * Classification heuristic (per the spec's A10 invariant — "the check
+ * is mechanical: scan .caws/specs/*.yaml for v10 top-level keys (type,
+ * status, acceptance_criteria) and refuse if any are found"):
+ *
+ *   - v10: file contains any of the top-level keys `type:`, `status:`,
+ *     or `acceptance_criteria:` at column 0.
+ *   - v11: file contains any of the top-level keys `mode:`,
+ *     `lifecycle_state:`, or `acceptance:` at column 0, AND none of
+ *     the v10 keys.
+ *   - unclassified: no signal in either direction (e.g., empty file,
+ *     comment-only file, malformed YAML).
+ *
+ * This is a regex-level scan, not a full YAML parse. Deliverable 2
+ * (CAWS-MIGRATE-V10-SPECS-001) may replace it with detectSpecVersion
+ * from packages/caws-kernel/src/spec/migrate-v10.ts when that ships,
+ * but the refusal contract owned by this slice (A10) is named here.
+ */
+function detectV10SpecsPresent(files) {
+    const v10Paths = [];
+    const v11Paths = [];
+    const unclassifiedPaths = [];
+    const V10_KEY = /^(?:type|status|acceptance_criteria):/m;
+    const V11_KEY = /^(?:mode|lifecycle_state|acceptance):/m;
+    for (const file of files) {
+        const hasV10 = V10_KEY.test(file.raw);
+        const hasV11 = V11_KEY.test(file.raw);
+        if (hasV10) {
+            // Any v10 signal wins, even if v11 keys also appear (mixed-shape
+            // spec is itself a problem the specs migration owns).
+            v10Paths.push(file.path);
+        }
+        else if (hasV11) {
+            v11Paths.push(file.path);
+        }
+        else {
+            unclassifiedPaths.push(file.path);
+        }
+    }
+    return {
+        detected: v10Paths.length > 0,
+        v10Paths,
+        v11Paths,
+        unclassifiedPaths,
+    };
+}
+const ARCHIVE_PREFIX = 'events.jsonl.archive-';
+/**
+ * Compose a deterministic rotation plan from a previously-detected
+ * events-log shape plus operator policy. Pure: no I/O, no clock access
+ * (the caller supplies opts.now).
+ *
+ * The planner is structurally consistent with rotateEvents's refusal
+ * logic in events-store.ts — same conditions, same diagnostic rules
+ * (sourced from STORE_RULES not from MIGRATION_RULES, so a `rotate
+ * --apply` later that goes through rotateEvents will emit the same
+ * rule ids). The migration command can therefore present a dry-run
+ * plan that exactly mirrors what would happen at apply time.
+ *
+ * Order of refusal checks (highest precedence first):
+ *   1. unparseable_only        — nothing to rotate; the log is corrupt
+ *      and the operator must inspect before any archiving.
+ *   2. partial_corruption      — some unparseable lines alongside
+ *      parseable ones; chain_rotated payload cannot honestly label
+ *      this case. Mirrors STORE_RULES.EVENTS_ROTATE_PARTIAL_CORRUPTION
+ *      in rotateEvents. No friction-flag escape in v11.2 scope.
+ *   3. v10_specs_present       — half-upgrade refusal; requires
+ *      allowPartialUpgrade.
+ *   4. clean_chain (all_v11)   — friction flag; requires allowClean.
+ *
+ * If all checks pass, returns RotatePlan with the proposed archive
+ * name and the inputs the shell will pass to rotateEvents.
+ */
+function planEventsRotation(detection, opts) {
+    // 1. unparseable_only — refuse outright; rotation here would archive
+    //    a corrupt chain without operator inspection. The shell points
+    //    at the file and asks the operator what to do.
+    if (detection.kind === 'unparseable_only') {
+        return {
+            kind: 'refuse',
+            cause: 'unparseable_only',
+            diagnostic: (0, caws_kernel_1.diagnostic)({
+                rule: exports.MIGRATION_RULES.UNPARSEABLE_INPUT,
+                authority: 'kernel/diagnostics',
+                message: `events.jsonl has no JSON-parseable lines (${detection.stats.unparseable} unparseable, ${detection.lineCount} total). Inspect the file before rotation; manual recovery may be required.`,
+            }),
+            detection,
+        };
+    }
+    // 2. partial_corruption — some unparseable lines exist alongside
+    //    parseable ones. The chain_rotated payload's prior_chain_status
+    //    enum has no honest label for this case ('parseable_unverified'
+    //    implies every line parsed; 'unparseable' implies none did).
+    //    Refuse rather than archive a partially-corrupt log under a
+    //    misleading status. Mirrors rotateEvents's same-named refusal
+    //    so dry-run and apply paths agree exactly. No friction-flag
+    //    escape in v11.2 scope; a future opt-in path may be added
+    //    alongside a new 'partially_unparseable' enum value in a
+    //    later slice.
+    if (detection.stats.unparseable > 0 &&
+        detection.stats.unparseable < detection.lineCount) {
+        const parseable = detection.stats.v10_string_actor + detection.stats.v11_object_actor;
+        return {
+            kind: 'refuse',
+            cause: 'partial_corruption',
+            diagnostic: (0, caws_kernel_1.diagnostic)({
+                rule: exports.MIGRATION_RULES.PARTIAL_CORRUPTION_REFUSED,
+                authority: 'kernel/diagnostics',
+                message: `events.jsonl has ${detection.stats.unparseable} unparseable line(s) alongside ${parseable} parseable line(s) (${detection.lineCount} total). Mixed parseable + unparseable cannot be honestly labeled by the chain_rotated payload. Inspect the file and recover manually, or remove the corrupt lines before retrying.`,
+                narrowRepair: 'Open events.jsonl, identify the unparseable line(s) (often a truncated/crash-recovery tail), and either restore them or remove them. Re-run after the file has only parseable JSON lines.',
+            }),
+            detection,
+        };
+    }
+    // 3. Half-upgrade refusal. The planner only fires this when the
+    //    caller has supplied a v10Specs scan AND detected: true. The
+    //    contract is "if you scanned and found v10 specs, the planner
+    //    enforces; if you didn't scan, the planner trusts you."
+    if (opts.v10Specs?.detected === true &&
+        opts.allowPartialUpgrade !== true) {
+        return {
+            kind: 'refuse',
+            cause: 'v10_specs_require_allow_partial_upgrade',
+            diagnostic: (0, caws_kernel_1.diagnostic)({
+                rule: exports.MIGRATION_RULES.V10_SPEC_DETECTED,
+                authority: 'kernel/diagnostics',
+                message: `events migrate --apply refuses: ${opts.v10Specs.v10Paths.length} v10-shape spec(s) detected (${opts.v10Specs.v10Paths.join(', ')}). Run 'caws specs migrate --from v10 --dry-run' first or pass --allow-partial-upgrade.`,
+                narrowRepair: "Run 'caws specs migrate --from v10' to migrate specs first, then re-run 'caws events migrate --apply'. If you intentionally want the events log to migrate ahead of specs, pass --allow-partial-upgrade.",
+            }),
+            detection,
+            v10Specs: opts.v10Specs,
+        };
+    }
+    // 4. Clean v11 chain friction flag. Mirrors rotateEvents's isCleanV11
+    //    check in events-store.ts so dry-run and apply agree.
+    const isCleanV11 = detection.kind === 'all_v11' &&
+        detection.stats.v10_string_actor === 0 &&
+        detection.stats.unparseable === 0 &&
+        detection.stats.v11_object_actor > 0;
+    if (isCleanV11 && opts.allowClean !== true) {
+        return {
+            kind: 'refuse',
+            cause: 'clean_chain_requires_allow_clean',
+            diagnostic: (0, caws_kernel_1.diagnostic)({
+                rule: 'store.events.rotate.clean_chain_requires_allow_clean',
+                authority: 'kernel/diagnostics',
+                message: `rotateEvents would refuse: prior chain is a clean v11 chain (${detection.stats.v11_object_actor} structured actors); pass allowClean: true (CLI: --allow-clean) to rotate it anyway.`,
+                narrowRepair: 'If you intend to rotate a healthy v11 chain (e.g., for operational reasons unrelated to migration), pass --allow-clean. Otherwise, no rotation is needed.',
+            }),
+            detection,
+        };
+    }
+    // All checks passed. Compose the rotate plan.
+    return {
+        kind: 'rotate',
+        reason: opts.reason,
+        allowClean: opts.allowClean === true,
+        now: opts.now,
+        proposedArchiveName: `${ARCHIVE_PREFIX}${windowsSafeIso(opts.now)}`,
+        detection,
+        ...(opts.v10Specs !== undefined ? { v10Specs: opts.v10Specs } : {}),
+    };
+}
+/**
+ * Windows-safe ISO timestamp for archive filenames. Replaces both ':'
+ * and '.' with '-' so the archive name is filesystem-safe everywhere.
+ * Must match events-store.ts windowsSafeIso exactly so the planner's
+ * proposedArchiveName matches what rotateEvents will actually use.
+ */
+function windowsSafeIso(d) {
+    return d.toISOString().replace(/:/g, '-').replace(/\./g, '-');
+}
+//# sourceMappingURL=events-migration.js.map

package/dist/store/events-migration.js.map

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

package/dist/store/events-store.d.ts

@@ -1,4 +1,4 @@
-import { type ChainedEvent, type EventBody, type Result } from '@paths.design/caws-kernel';
+import { type Actor, type ChainedEvent, type EventBody, type Result } from '@paths.design/caws-kernel';
 import type { EventsLoadResult } from './types';
 /**
  * Load events from `.caws/events.jsonl`.
@@ -30,4 +30,50 @@ export declare function loadEvents(cawsDir: string): Result<EventsLoadResult>;
  * authority.
  */
 export declare function appendEvent(cawsDir: string, body: EventBody): Result<ChainedEvent>;
+export interface RotateEventsOptions {
+    /**
+     * Operator-supplied reason recorded verbatim into chain_rotated.data.
+     * migration_reason. Required for every rotate invocation regardless of
+     * chain shape; see CAWS-MIGRATE-V10-EVENTS-001 A6/A8.
+     */
+    readonly reason: string;
+    /**
+     * Actor to attribute the chain_rotated event to. The kernel envelope
+     * requires a structured Actor; the shell command's buildActor() helper
+     * is the conventional source.
+     */
+    readonly actor: Actor;
+    /**
+     * Friction flag. When the prior chain has only structured (v11) actors,
+     * rotation is refused unless allowClean === true. Default false means
+     * rotation against a clean chain is treated as an operator slip; the
+     * caller must explicitly opt in to log rotation as a non-migration
+     * maintenance operation. See A8.
+     */
+    readonly allowClean?: boolean;
+    /**
+     * Override the wall-clock used for the archive timestamp. Tests inject
+     * a fixed Date; production omits this and the function uses new Date().
+     */
+    readonly now?: Date;
+}
+/**
+ * Rotate the events.jsonl chain: archive the existing file under a
+ * timestamped name and write a fresh chain whose genesis event is
+ * chain_rotated, cryptographically tying the archive to the new chain
+ * via prior_file_digest.
+ *
+ * Refusals (typed Diagnostic, no file mutations on any refusal path):
+ *   - EVENTS_ROTATE_NOTHING_TO_ROTATE: file missing or zero-length.
+ *   - EVENTS_ROTATE_CLEAN_CHAIN_REQUIRES_ALLOW_CLEAN: all entries are
+ *     structured (v11) actors and allowClean !== true.
+ *   - EVENTS_PREPARE_APPEND_REJECTED: the constructed chain_rotated body
+ *     failed kernel validation (programmer error in this function or a
+ *     schema change drift). Carries kernel diagnostics in data.source_rule.
+ *   - WRITE_IO_FAILED: rename or genesis-write failed at the FS layer.
+ *
+ * On success returns the new ChainedEvent (the chain_rotated genesis event
+ * that is now the entirety of the new events.jsonl).
+ */
+export declare function rotateEvents(cawsDir: string, opts: RotateEventsOptions): Result<ChainedEvent>;
 //# sourceMappingURL=events-store.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"events-store.d.ts","sourceRoot":"","sources":["../../src/store/events-store.ts"],"names":[],"mappings":"AAsBA,OAAO,EAML,KAAK,YAAY,EAEjB,KAAK,SAAS,EACd,KAAK,MAAM,EACZ,MAAM,2BAA2B,CAAC;AAGnC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAUhD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAoBpE;AAoFD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,GACd,MAAM,CAAC,YAAY,CAAC,CAgEtB"}
+{"version":3,"file":"events-store.d.ts","sourceRoot":"","sources":["../../src/store/events-store.ts"],"names":[],"mappings":"AAuBA,OAAO,EAML,KAAK,KAAK,EACV,KAAK,YAAY,EAEjB,KAAK,SAAS,EACd,KAAK,MAAM,EACZ,MAAM,2BAA2B,CAAC;AAGnC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAUhD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAoBpE;AAoFD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,GACd,MAAM,CAAC,YAAY,CAAC,CAgEtB;AAoCD,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,mBAAmB,GACxB,MAAM,CAAC,YAAY,CAAC,CA0MtB"}