@aperant/framework 0.17.0 → 0.19.0

package/dist/cli/produce/projection.d.mts

@@ -0,0 +1,55 @@
+/**
+ * Recompute the roadmap projection for a run by folding its append-only
+ * `produce.roadmap.*` events. `milestone_added` seeds a planned milestone (in
+ * first-seen order); `milestone_status_changed` advances its status. Idempotent
+ * re-adds keep the first seed (never clobber an advanced status). `updated_at`
+ * is derived from the last folded event's timestamp so the projection is
+ * DETERMINISTIC — two folds of the same log yield the identical roadmap.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {{ run_id: string, milestones: Array<{ id: string, title: string, status: string }>, updated_at: string | null }}
+ */
+export function projectRoadmap(projectDir: string, runId: string): {
+    run_id: string;
+    milestones: Array<{
+        id: string;
+        title: string;
+        status: string;
+    }>;
+    updated_at: string | null;
+};
+/**
+ * The derived roadmap.json cache path for a run.
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {string}
+ */
+export function roadmapCachePath(projectDir: string, runId: string): string;
+/**
+ * Refresh the derived roadmap.json cache single-writer under withFileLock, and
+ * return the freshly-folded roadmap. Convenience only — the log is the
+ * authority; a corrupt cache is repaired by re-folding (ID-01).
+ *
+ * The fold happens INSIDE the lock (not precomputed then written): the write is
+ * a full idempotent regenerate from the authoritative log, never a
+ * read-modify-write of a shared blob. This guarantees the last writer to
+ * acquire the lock persists the COMPLETE set — a precompute-then-write pattern
+ * could persist a STALE fold if a concurrent O_APPEND landed between the
+ * precompute and the write, silently dropping that milestone from the cache
+ * (parent TD-06 / subtask 4). The event log stays lossless regardless.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {{ run_id: string, milestones: Array<{ id: string, title: string, status: string }>, updated_at: string | null }}
+ */
+export function writeProjectionCache(projectDir: string, runId: string): {
+    run_id: string;
+    milestones: Array<{
+        id: string;
+        title: string;
+        status: string;
+    }>;
+    updated_at: string | null;
+};
+//# sourceMappingURL=projection.d.mts.map

package/dist/cli/produce/projection.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.mts","sourceRoot":"","sources":["../../../src/cli/produce/projection.mjs"],"names":[],"mappings":"AAyBA;;;;;;;;;;;GAWG;AACH,2CAJW,MAAM,SACN,MAAM,GACJ;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CA6B3H;AAED;;;;;GAKG;AACH,6CAJW,MAAM,SACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,iDAJW,MAAM,SACN,MAAM,GACJ;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAa3H"}

package/dist/cli/produce/projection.mjs

@@ -0,0 +1,97 @@
+/**
+ * @internal
+ * produce/projection.mjs — event-sourced roadmap projection (M1, ID-01).
+ *
+ * The roadmap is DERIVED: `projectRoadmap` folds the run's `produce.roadmap.*`
+ * events into `{ run_id, milestones:[{id,title,status}], updated_at }` on every
+ * call. It is NEVER read as the source of truth — a persisted `roadmap.json`
+ * cache MAY be written for convenience but is always regenerable from the log,
+ * so the shared-mutable-blob lost-update bug is structurally impossible.
+ *
+ * `writeProjectionCache` is a SINGLE-WRITER-PER-RECORD write under withFileLock
+ * (a torn cache is recoverable by re-folding). The event log is the authority;
+ * the cache is disposable.
+ */
+import { join } from 'node:path';
+import { withFileLock } from '../util/fs-lock.mjs';
+import { atomicWriteJson } from '../util/io.mjs';
+import { resolveMainRepoRoot } from '../util/state-paths.mjs';
+import { readProduceEventsForRun } from './events.mjs';
+import { resolveRunDir } from './run-id.mjs';
+/** M1 milestone lifecycle — `done` is external-oracle-gated (M2, ID-03). */
+const SEED_STATUS = 'planned';
+/**
+ * Recompute the roadmap projection for a run by folding its append-only
+ * `produce.roadmap.*` events. `milestone_added` seeds a planned milestone (in
+ * first-seen order); `milestone_status_changed` advances its status. Idempotent
+ * re-adds keep the first seed (never clobber an advanced status). `updated_at`
+ * is derived from the last folded event's timestamp so the projection is
+ * DETERMINISTIC — two folds of the same log yield the identical roadmap.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {{ run_id: string, milestones: Array<{ id: string, title: string, status: string }>, updated_at: string | null }}
+ */
+export function projectRoadmap(projectDir, runId) {
+    const events = readProduceEventsForRun(projectDir, runId);
+    const byId = new Map();
+    const order = [];
+    let updatedAt = null;
+    for (const e of events) {
+        const d = e.data || {};
+        const id = typeof d.milestone_id === 'string' ? d.milestone_id : null;
+        if (e.op === 'produce.roadmap.milestone_added') {
+            if (id && !byId.has(id)) {
+                byId.set(id, { id, title: typeof d.title === 'string' ? d.title : id, status: SEED_STATUS });
+                order.push(id);
+            }
+        }
+        else if (e.op === 'produce.roadmap.milestone_status_changed') {
+            if (id && byId.has(id) && typeof d.status === 'string') {
+                byId.get(id).status = d.status;
+            }
+        }
+        if (typeof e.t === 'string')
+            updatedAt = e.t;
+    }
+    return {
+        run_id: runId,
+        milestones: order.map((id) => byId.get(id)),
+        updated_at: updatedAt,
+    };
+}
+/**
+ * The derived roadmap.json cache path for a run.
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {string}
+ */
+export function roadmapCachePath(projectDir, runId) {
+    return join(resolveRunDir(projectDir, runId), 'roadmap.json');
+}
+/**
+ * Refresh the derived roadmap.json cache single-writer under withFileLock, and
+ * return the freshly-folded roadmap. Convenience only — the log is the
+ * authority; a corrupt cache is repaired by re-folding (ID-01).
+ *
+ * The fold happens INSIDE the lock (not precomputed then written): the write is
+ * a full idempotent regenerate from the authoritative log, never a
+ * read-modify-write of a shared blob. This guarantees the last writer to
+ * acquire the lock persists the COMPLETE set — a precompute-then-write pattern
+ * could persist a STALE fold if a concurrent O_APPEND landed between the
+ * precompute and the write, silently dropping that milestone from the cache
+ * (parent TD-06 / subtask 4). The event log stays lossless regardless.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {{ run_id: string, milestones: Array<{ id: string, title: string, status: string }>, updated_at: string | null }}
+ */
+export function writeProjectionCache(projectDir, runId) {
+    const path = roadmapCachePath(projectDir, runId);
+    return withFileLock(path, () => {
+        const roadmap = projectRoadmap(projectDir, runId);
+        atomicWriteJson(path, roadmap);
+        return roadmap;
+    }, { projectRoot: resolveMainRepoRoot(projectDir) });
+}
+//# sourceMappingURL=projection.mjs.map

package/dist/cli/produce/projection.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.mjs","sourceRoot":"","sources":["../../../src/cli/produce/projection.mjs"],"names":[],"mappings":"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"}

package/dist/cli/produce/run-id.d.mts

@@ -0,0 +1,42 @@
+/**
+ * Slugify an outcome string into a short kebab identifier. Strips punctuation,
+ * lowercases, keeps the first `maxWords` words. Falls back to 'run' when empty.
+ *
+ * @param {string} outcome
+ * @param {number} [maxWords=6]
+ * @returns {string}
+ */
+export function slugFromOutcome(outcome: string, maxWords?: number): string;
+/**
+ * Mint a fresh run-id: `<slug>-<YYYYMMDD-HHMMSS>-<rand>`. The random suffix
+ * guarantees uniqueness even for identical outcomes minted in the same second.
+ *
+ * @param {string} outcome
+ * @param {Date} [now]
+ * @returns {string}
+ */
+export function mintRunId(outcome: string, now?: Date): string;
+/**
+ * The `.aperant/produce/` root, resolved to the shared main repo from any cwd.
+ *
+ * @param {string} projectDir
+ * @returns {string}
+ */
+export function resolveProduceRoot(projectDir: string): string;
+/**
+ * The run dir `.aperant/produce/<run-id>/`, resolved to the shared main repo.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {string}
+ */
+export function resolveRunDir(projectDir: string, runId: string): string;
+/**
+ * Repo-relative setpoint path for a run — used as the `setpoint_path` event
+ * field. Forward-slash separated for portability across the event log.
+ *
+ * @param {string} runId
+ * @returns {string}
+ */
+export function relativeSetpointPath(runId: string): string;
+//# sourceMappingURL=run-id.d.mts.map

package/dist/cli/produce/run-id.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-id.d.mts","sourceRoot":"","sources":["../../../src/cli/produce/run-id.mjs"],"names":[],"mappings":"AAeA;;;;;;;GAOG;AACH,yCAJW,MAAM,aACN,MAAM,GACJ,MAAM,CAYlB;AAED;;;;;;;GAOG;AACH,mCAJW,MAAM,QACN,IAAI,GACF,MAAM,CAUlB;AAED;;;;;GAKG;AACH,+CAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;GAMG;AACH,0CAJW,MAAM,SACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;GAMG;AACH,4CAHW,MAAM,GACJ,MAAM,CAIlB"}

package/dist/cli/produce/run-id.mjs

@@ -0,0 +1,79 @@
+/**
+ * @internal
+ * produce/run-id.mjs — mint + resolve produce run identifiers and run dirs (M1).
+ *
+ * A produce run is scoped to one frozen acceptance setpoint. Its run-id is a
+ * human-readable slug derived from the outcome plus a short timestamp and a
+ * random suffix (so two `start`s in the same second never collide). The run
+ * dir lives under the SHARED main-repo root at `.aperant/produce/<run-id>/`
+ * (resolveMainRepoRoot) so every worktree agent reads/writes one board
+ * (parent AC8 path / ID-06).
+ */
+import { join } from 'node:path';
+import { resolveMainRepoRoot } from '../util/state-paths.mjs';
+/**
+ * Slugify an outcome string into a short kebab identifier. Strips punctuation,
+ * lowercases, keeps the first `maxWords` words. Falls back to 'run' when empty.
+ *
+ * @param {string} outcome
+ * @param {number} [maxWords=6]
+ * @returns {string}
+ */
+export function slugFromOutcome(outcome, maxWords = 6) {
+    const words = String(outcome || '')
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, ' ')
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean)
+        .slice(0, maxWords);
+    const slug = words.join('-').replace(/-+/g, '-');
+    return slug || 'run';
+}
+/**
+ * Mint a fresh run-id: `<slug>-<YYYYMMDD-HHMMSS>-<rand>`. The random suffix
+ * guarantees uniqueness even for identical outcomes minted in the same second.
+ *
+ * @param {string} outcome
+ * @param {Date} [now]
+ * @returns {string}
+ */
+export function mintRunId(outcome, now = new Date()) {
+    const stamp = now
+        .toISOString()
+        .replace(/\.\d+Z$/, '')
+        .replace(/[-:]/g, '')
+        .replace('T', '-');
+    const rand = Math.random().toString(36).slice(2, 6);
+    return `${slugFromOutcome(outcome)}-${stamp}-${rand}`;
+}
+/**
+ * The `.aperant/produce/` root, resolved to the shared main repo from any cwd.
+ *
+ * @param {string} projectDir
+ * @returns {string}
+ */
+export function resolveProduceRoot(projectDir) {
+    return join(resolveMainRepoRoot(projectDir), '.aperant', 'produce');
+}
+/**
+ * The run dir `.aperant/produce/<run-id>/`, resolved to the shared main repo.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {string}
+ */
+export function resolveRunDir(projectDir, runId) {
+    return join(resolveProduceRoot(projectDir), runId);
+}
+/**
+ * Repo-relative setpoint path for a run — used as the `setpoint_path` event
+ * field. Forward-slash separated for portability across the event log.
+ *
+ * @param {string} runId
+ * @returns {string}
+ */
+export function relativeSetpointPath(runId) {
+    return ['.aperant', 'produce', runId, 'setpoint.json'].join('/');
+}
+//# sourceMappingURL=run-id.mjs.map

package/dist/cli/produce/run-id.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-id.mjs","sourceRoot":"","sources":["../../../src/cli/produce/run-id.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAE7D;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,OAAO,EAAE,QAAQ,GAAG,CAAC;IACpD,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC;SACjC,WAAW,EAAE;SACb,OAAO,CAAC,eAAe,EAAE,GAAG,CAAC;SAC7B,IAAI,EAAE;SACN,KAAK,CAAC,KAAK,CAAC;SACZ,MAAM,CAAC,OAAO,CAAC;SACf,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAA;IACpB,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;IAChD,OAAO,IAAI,IAAI,KAAK,CAAA;AACrB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI,IAAI,EAAE;IAClD,MAAM,KAAK,GAAG,GAAG;SACf,WAAW,EAAE;SACb,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC;SACtB,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;SACpB,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IACnB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IACnD,OAAO,GAAG,eAAe,CAAC,OAAO,CAAC,IAAI,KAAK,IAAI,IAAI,EAAE,CAAA;AACtD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAAU;IAC5C,OAAO,IAAI,CAAC,mBAAmB,CAAC,UAAU,CAAC,EAAE,UAAU,EAAE,SAAS,CAAC,CAAA;AACpE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,UAAU,EAAE,KAAK;IAC9C,OAAO,IAAI,CAAC,kBAAkB,CAAC,UAAU,CAAC,EAAE,KAAK,CAAC,CAAA;AACnD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAK;IACzC,OAAO,CAAC,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AACjE,CAAC"}

package/dist/cli/produce/saga.d.mts

@@ -0,0 +1,180 @@
+/**
+ * Resolve the declared FORWARD compensator for a saga phase. Returns a fresh
+ * copy (the table is never handed out mutable) or null for an out-of-vocabulary
+ * phase (fail-closed). The returned descriptor ALWAYS has
+ * `rolls_back_merged_pr: false` (ID-M4-02).
+ *
+ * @param {string} phase
+ * @returns {{ kind: string, reopens_task: boolean, ships_revert: boolean, rolls_back_merged_pr: boolean } | null}
+ */
+export function resolveCompensator(phase: string): {
+    kind: string;
+    reopens_task: boolean;
+    ships_revert: boolean;
+    rolls_back_merged_pr: boolean;
+} | null;
+/**
+ * Append `produce.saga.phase_entered` for a milestone's saga phase. Validates
+ * the phase against SAGA_PHASES fail-closed (an out-of-vocabulary phase appends
+ * nothing).
+ *
+ * @param {string} projectDir
+ * @param {{ runId: string, milestoneId: string, phase: string }} args
+ * @returns {{ ok: true, phase: string } | { ok: false, reason: string }}
+ */
+export function enterPhase(projectDir: string, { runId, milestoneId, phase }: {
+    runId: string;
+    milestoneId: string;
+    phase: string;
+}): {
+    ok: true;
+    phase: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Append `produce.saga.phase_completed` for a milestone's saga phase. Validates
+ * the phase against SAGA_PHASES fail-closed.
+ *
+ * @param {string} projectDir
+ * @param {{ runId: string, milestoneId: string, phase: string }} args
+ * @returns {{ ok: true, phase: string } | { ok: false, reason: string }}
+ */
+export function completePhase(projectDir: string, { runId, milestoneId, phase }: {
+    runId: string;
+    milestoneId: string;
+    phase: string;
+}): {
+    ok: true;
+    phase: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Fire the FORWARD compensator for a failed saga phase (ID-M4-02). Resolves the
+ * declared compensator, then appends `produce.saga.compensated {run_id,
+ * milestone_id, phase, compensator: <descriptor.kind>, reason}` — carrying the
+ * descriptor KIND, never a rollback instruction. Validates the phase fail-closed.
+ * The CLI records the forward compensator; it does NOT execute the revert/reopen/
+ * re-plan (OOS dispatch) and NEVER mutates the roadmap milestone status.
+ *
+ * @param {string} projectDir
+ * @param {{ runId: string, milestoneId: string, phase: string, reason?: string }} args
+ * @returns {{ ok: true, phase: string, compensator: object } | { ok: false, reason: string }}
+ */
+export function compensatePhase(projectDir: string, { runId, milestoneId, phase, reason }: {
+    runId: string;
+    milestoneId: string;
+    phase: string;
+    reason?: string;
+}): {
+    ok: true;
+    phase: string;
+    compensator: object;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Record a provider-diverse review verdict (ID-M4-04 / ID-08). The review-path
+ * analog of evidence-oracle.mjs::recordOracleVerdict. REFUSES fail-closed when
+ * the reviewer family equals the recorded implementer family (a same-family
+ * reviewer rubber-stamps its own family's work) or when no implementer family is
+ * recorded (ID-M2-02). On acceptance appends `produce.saga.reviewed {run_id,
+ * milestone_id, reviewer_family, verdict}`.
+ *
+ * @param {string} projectDir
+ * @param {{ runId: string, milestoneId: string, verdict: string, reviewerFamily: string }} args
+ * @returns {{ ok: true, verdict: string, reviewer_family: string, implementer_family: string }
+ *   | { ok: false, reason: string, implementer_family?: string | null }}
+ */
+export function recordReview(projectDir: string, { runId, milestoneId, verdict, reviewerFamily }: {
+    runId: string;
+    milestoneId: string;
+    verdict: string;
+    reviewerFamily: string;
+}): {
+    ok: true;
+    verdict: string;
+    reviewer_family: string;
+    implementer_family: string;
+} | {
+    ok: false;
+    reason: string;
+    implementer_family?: string | null;
+};
+/**
+ * Resolve a REVIEW-phase reviewer family DISJOINT from the recorded implementer
+ * (ID-M4-04 / ID-08), a THIN wrapper over the M2 `resolveProbeFamily` — NO
+ * duplicated cross-family / partner-map / model-resolution logic. Reads the
+ * implementer family from the recorded `produce.milestone.implemented` trail
+ * (fail-closed when absent). Returns the resolution with `probe_family` surfaced
+ * as `reviewer_family`. Provider is an OUTPUT; the model is resolved LIVE (null
+ * for self-resolving families) — never a hardcoded id.
+ *
+ * @param {string} projectDir
+ * @param {{ runId: string, milestoneId: string, hostFamily?: string | null, availableFamilies?: string[] }} args
+ * @returns {{ available: boolean, reviewer_family: string | null, implementer_family: string | null,
+ *   transport_hint: object | null, model: string | null, source: string | null, reason: string | null }}
+ */
+export function resolveReviewer(projectDir: string, { runId, milestoneId, hostFamily, availableFamilies }: {
+    runId: string;
+    milestoneId: string;
+    hostFamily?: string | null;
+    availableFamilies?: string[];
+}): {
+    available: boolean;
+    reviewer_family: string | null;
+    implementer_family: string | null;
+    transport_hint: object | null;
+    model: string | null;
+    source: string | null;
+    reason: string | null;
+};
+/**
+ * Fold the run's `produce.saga.*` events into per-milestone saga state — a
+ * SEPARATE fold parallel to the roadmap projection (the roadmap projection folds
+ * `produce.roadmap.*` ONLY, so saga events never enter the roadmap the Showrunner
+ * re-reads each tick — blindness preserved, ID-M4-01). Deterministic: two folds
+ * of the same log yield the identical saga state; `updated_at` is the last folded
+ * event's timestamp.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {{
+ *   run_id: string,
+ *   milestones: Array<{
+ *     milestone_id: string,
+ *     current_phase: string | null,
+ *     phase_status: 'entered' | 'completed' | null,
+ *     phases: Record<string, 'entered' | 'completed'>,
+ *     last_compensated: { phase: string | null, compensator: string | null, reason: string | null } | null,
+ *     reviewed: { reviewer_family: string | null, verdict: string | null } | null,
+ *   }>,
+ *   updated_at: string | null,
+ * }}
+ */
+export function projectSaga(projectDir: string, runId: string): {
+    run_id: string;
+    milestones: Array<{
+        milestone_id: string;
+        current_phase: string | null;
+        phase_status: "entered" | "completed" | null;
+        phases: Record<string, "entered" | "completed">;
+        last_compensated: {
+            phase: string | null;
+            compensator: string | null;
+            reason: string | null;
+        } | null;
+        reviewed: {
+            reviewer_family: string | null;
+            verdict: string | null;
+        } | null;
+    }>;
+    updated_at: string | null;
+};
+/** The ordered saga phases (ID-M4-01). Mirrors ALLOWED_SAGA_PHASES in event-schema.mjs. */
+export const SAGA_PHASES: string[];
+//# sourceMappingURL=saga.d.mts.map

package/dist/cli/produce/saga.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saga.d.mts","sourceRoot":"","sources":["../../../src/cli/produce/saga.mjs"],"names":[],"mappings":"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"}