@intentius/chant 0.49.0 → 0.50.0

package/dist/lifecycle/converge-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"converge-ledger.d.ts","sourceRoot":"","sources":["../../src/lifecycle/converge-ledger.ts"],"names":[],"mappings":"AAmCA,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;;OAQG;IACH,MAAM,EAAE,KAAK,GAAG,UAAU,GAAG,gBAAgB,GAAG,cAAc,GAAG,OAAO,CAAC;IACzE,gEAAgE;IAChE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6JAA6J;IAC7J,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IACjC,wFAAwF;IACxF,OAAO,EAAE,CAAC,CAAC;IACX,+CAA+C;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,6IAA6I;IAC7I,SAAS,EAAE,MAAM,CAAC;IAClB,oHAAoH;IACpH,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,8CAA8C;IAC9C,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,wDAAwD;IACxD,OAAO,EAAE;QACP,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,aAAa,EAAE,MAAM,CAAC;QACtB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,uNAAuN;QACvN,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,iHAAiH;IACjH,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,kBAAkB,EAAE,SAAS,CAAC,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,uBAAuB,EAC9B,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAqBzD;AAED,6MAA6M;AAC7M,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC;IAAE,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CA0B/D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAO1F"}

package/dist/lifecycle/deep-diff.d.ts

@@ -22,6 +22,7 @@
  * interpolated property forever.
  */
 import { type DeepNormalizationHooks, type NormalizedDeepObservation } from "../deep-observation.js";
+import { type PathOrigin } from "../provenance.js";
 import type { UnobservedResource } from "./live-diff.js";
 import { type BaselineLexicon } from "./observation-baseline.js";
 /**
@@ -61,6 +62,18 @@ export interface PropertyDrift {
      * with no per-field ownership, which is every substrate but k8s.
      */
     owner?: string;
+    /**
+     * What produced this path on the DECLARED side (#1443) — the counterpart of
+     * {@link owner}, and the reason the two are reported together: "owned live by
+     * `hpa-controller`, governed in source by the `tier` parameter" says where
+     * each half of a disagreement has to be fixed, which neither half says alone.
+     *
+     * Resolved by longest prefix from the entity's recorded path origins, so a
+     * field inside a keyed list element inherits the origin recorded for the
+     * list. Absent when the build recorded none — the run path, and a sandboxed
+     * child, have no expression to attribute (see `EntityProvenance.paths`).
+     */
+    origin?: PathOrigin;
 }
 /** Property-level drift for one declared entity. */
 export interface DeepEntityDrift {
@@ -88,6 +101,11 @@ export interface DeepDiffResult {
 export interface DeclaredDeepEntity {
     type: string;
     properties: Record<string, unknown>;
+    /**
+     * The entity's recorded path origins (#1443), as `EntityProvenance.paths`.
+     * Omit for a build that recorded none.
+     */
+    pathOrigins?: Record<string, PathOrigin>;
 }
 export interface DiffDeepInput {
     /** Normalized declared property trees, keyed by chant entity name. */

package/dist/lifecycle/deep-diff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deep-diff.d.ts","sourceRoot":"","sources":["../../src/lifecycle/deep-diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAIL,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,EAC/B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEjF;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,YAAY,GAAG,QAAQ,CAAC;AAEpE,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,iBAAiB,CAAC;IACxB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,iFAAiF;IACjF,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,qDAAqD;IACrD,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,8EAA8E;IAC9E,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,0EAA0E;IAC1E,kBAAkB,EAAE,MAAM,EAAE,CAAC;CAC9B;AAED,sFAAsF;AACtF,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAC7C,4EAA4E;IAC5E,IAAI,EAAE,yBAAyB,CAAC;IAChC,yEAAyE;IACzE,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,sBAAsB,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,cAAc,CAmG7D;AAED,+DAA+D;AAC/D,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAEjE"}
+{"version":3,"file":"deep-diff.d.ts","sourceRoot":"","sources":["../../src/lifecycle/deep-diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAIL,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,EAC/B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEjF;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,YAAY,GAAG,QAAQ,CAAC;AAEpE,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,iBAAiB,CAAC;IACxB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,iFAAiF;IACjF,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,qDAAqD;IACrD,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,8EAA8E;IAC9E,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,0EAA0E;IAC1E,kBAAkB,EAAE,MAAM,EAAE,CAAC;CAC9B;AAED,sFAAsF;AACtF,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAC7C,4EAA4E;IAC5E,IAAI,EAAE,yBAAyB,CAAC;IAChC,yEAAyE;IACzE,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,sBAAsB,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,cAAc,CAwG7D;AAED,+DAA+D;AAC/D,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAEjE"}

package/dist/lifecycle/deep-observe.d.ts

@@ -18,12 +18,20 @@
  */
 import type { ObservationLexicon } from "../lexicon.js";
 import { type DeepNormalizationHooks, type NormalizedDeepObservation } from "../deep-observation.js";
+import type { PathOrigin } from "../provenance.js";
 import { type DeepDiffResult } from "./deep-diff.js";
 import type { BaselineLexicon } from "./observation-baseline.js";
-/** Declared entities for one lexicon, in the shape the observe paths pass around. */
+/**
+ * Declared entities for one lexicon, in the shape the observe paths pass around.
+ *
+ * `pathOrigins` (#1443) rides alongside `props` rather than being read off the
+ * entity, because callers rebuild this map as plain objects and the symbol-keyed
+ * provenance channel does not survive that copy.
+ */
 export type DeclaredEntities = Map<string, {
     entityType: string;
     props: Record<string, unknown>;
+    pathOrigins?: Record<string, PathOrigin>;
 }>;
 export interface DeepObserveOptions {
     environment: string;

package/dist/lifecycle/deep-observe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deep-observe.d.ts","sourceRoot":"","sources":["../../src/lifecycle/deep-observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAIL,KAAK,sBAAsB,EAE3B,KAAK,yBAAyB,EAC/B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAqC,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D,qFAAqF;AACrF,MAAM,MAAM,gBAAgB,GAAG,GAAG,CAAC,MAAM,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,CAAC;AAEnG,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;4CAEwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,QAAQ,CAAC,yBAAyB,CAAC,GACzC,yBAAyB,CAS3B;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,kBAAkB,EAC1B,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,yBAAyB,CAAC,CA+BpC;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,gBAAgB,EAC1B,IAAI,EAAE,yBAAyB,EAC/B,KAAK,CAAC,EAAE,sBAAsB,EAC9B,QAAQ,CAAC,EAAE,eAAe,GACzB,cAAc,CAmDhB;AAED,oFAAoF;AACpF,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,kBAAkB,EAC1B,IAAI,EAAE,kBAAkB,GAAG;IAAE,QAAQ,CAAC,EAAE,eAAe,CAAA;CAAE,GACxD,OAAO,CAAC,cAAc,CAAC,CAGzB"}
+{"version":3,"file":"deep-observe.d.ts","sourceRoot":"","sources":["../../src/lifecycle/deep-observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAIL,KAAK,sBAAsB,EAE3B,KAAK,yBAAyB,EAC/B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAqC,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,GAAG,CAChC,MAAM,EACN;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;CAAE,CACjG,CAAC;AAEF,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;4CAEwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,QAAQ,CAAC,yBAAyB,CAAC,GACzC,yBAAyB,CAS3B;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,kBAAkB,EAC1B,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,yBAAyB,CAAC,CA+BpC;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,gBAAgB,EAC1B,IAAI,EAAE,yBAAyB,EAC/B,KAAK,CAAC,EAAE,sBAAsB,EAC9B,QAAQ,CAAC,EAAE,eAAe,GACzB,cAAc,CAoDhB;AAED,oFAAoF;AACpF,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,kBAAkB,EAC1B,IAAI,EAAE,kBAAkB,GAAG;IAAE,QAAQ,CAAC,EAAE,eAAe,CAAA;CAAE,GACxD,OAAO,CAAC,cAAc,CAAC,CAGzB"}

package/dist/lifecycle/gate-ledger.d.ts

@@ -0,0 +1,33 @@
+/** One immutable gate-resolution record. */
+export interface GateResolutionRecord {
+    /** Schema version, so an incompatible future shape is detected before being misread. */
+    version: 1;
+    /** The dispatched op the gate belongs to. */
+    op: string;
+    /** The gate's signal name (matches `ConvergeRuleOutcome.gateName`). */
+    gate: string;
+    /** Who resolved it — an actor name, the same convention `components release --actor` and `run signal --approver` use. */
+    resolvedBy: string;
+    /** ISO-8601 timestamp, caller-supplied (library code never calls `Date.now()` internally). */
+    timestamp: string;
+    /** Optional free-text context (e.g. a PR URL — "or a merged PR" is the issue's other resolution path; recording its link here keeps both paths visible from one ledger). */
+    note?: string;
+}
+export type GateResolutionInput = Omit<GateResolutionRecord, "version">;
+/** Append one immutable gate-resolution record. Does not push to the remote — call `pushLifecycle` (./git.ts) afterward, same two-step shape every other ledger write here uses. Retries on `RefCASConflictError` the same way `appendConvergeRecord` does (./converge-ledger.ts) — a concurrent writer to a different op's/env's file on the same orphan branch is the ordinary case, not an edge case. The baseline read must be `readPathSha` + `readBlobBySha` rather than `readBlobFromPath`, so the exact sha `existing` came from can be passed as `expectPriorPathSha` — see `writeBlobToPath` (./git.ts) for the race that closes. */
+export declare function appendGateResolution(input: GateResolutionInput, opts?: {
+    cwd?: string;
+}): Promise<{
+    commit: string;
+    record: GateResolutionRecord;
+}>;
+/** Read every gate-resolution record for `op`, oldest first. Malformed lines are skipped, not thrown on, the same graceful-degradation stance `readConvergeLedger` takes. Returns `[]` (never throws) when `op` has no resolutions recorded yet. */
+export declare function readGateResolutions(op: string, opts?: {
+    cwd?: string;
+}): Promise<{
+    records: GateResolutionRecord[];
+    malformed: number;
+}>;
+/** The most recent resolution for `gate` recorded after `sinceIso` (a gated tick's own timestamp) — what `chant operator status` uses to tell a resolved gate from a still-pending one. `undefined` when no such resolution exists. */
+export declare function latestResolutionSince(records: GateResolutionRecord[], gate: string, sinceIso: string): GateResolutionRecord | undefined;
+//# sourceMappingURL=gate-ledger.d.ts.map

package/dist/lifecycle/gate-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate-ledger.d.ts","sourceRoot":"","sources":["../../src/lifecycle/gate-ledger.ts"],"names":[],"mappings":"AA4CA,4CAA4C;AAC5C,MAAM,WAAW,oBAAoB;IACnC,wFAAwF;IACxF,OAAO,EAAE,CAAC,CAAC;IACX,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAC;IACX,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,yHAAyH;IACzH,UAAU,EAAE,MAAM,CAAC;IACnB,8FAA8F;IAC9F,SAAS,EAAE,MAAM,CAAC;IAClB,4KAA4K;IAC5K,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,oBAAoB,EAAE,SAAS,CAAC,CAAC;AAMxE,+mBAA+mB;AAC/mB,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,mBAAmB,EAC1B,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE,CAAC,CAqB3D;AAED,oPAAoP;AACpP,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,MAAM,EACV,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC;IAAE,OAAO,EAAE,oBAAoB,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CA0BjE;AAED,uOAAuO;AACvO,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,oBAAoB,EAAE,EAC/B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,oBAAoB,GAAG,SAAS,CASlC"}

package/dist/lifecycle/git.d.ts

@@ -1,26 +1,6 @@
-/**
- * Write a blob to an arbitrary `<environment>/<filename>` path on the orphan
- * branch, preserving every other env/file entry already on the branch.
- *
- * Pipeline: hash-object → mktree → commit-tree → update-ref. Factored out of
- * `writeSnapshot` so the release ledger (#568, epic #551 "Build & deploy
- * observability") can reuse the identical git-plumbing path for a different
- * filename (`releases.jsonl`) under the same env directory, rather than a
- * parallel storage mechanism.
- *
- * Exported (not just used internally) so ./build-ledger-store.ts (#609) can
- * reuse this exact plumbing for a top-level directory that isn't really an
- * "environment" (`_builds`, keyed by manifest digest rather than env name) —
- * a build archive is promoted by digest across environments, never owned by
- * one, so it belongs in its own digest-keyed namespace on the same orphan
- * branch rather than duplicated per env. The parameter is still named
- * `environment` because it is literally the first path segment / root-tree
- * entry name this function's tree-building logic groups by; callers outside
- * this module that pass a non-env value (like `_builds`) are relying on that
- * generic behavior, not on any env-specific semantics.
- */
 export declare function writeBlobToPath(environment: string, filename: string, content: string, commitMessage: string, opts?: {
     cwd?: string;
+    expectPriorPathSha?: string | null;
 }): Promise<string>;
 /**
  * Read a blob from an arbitrary `<environment>/<filename>` path on the orphan
@@ -32,6 +12,16 @@ export declare function writeBlobToPath(environment: string, filename: string, c
 export declare function readBlobFromPath(environment: string, filename: string, opts?: {
     cwd?: string;
 }): Promise<string | null>;
+/**
+ * Read the blob SHA stored at `<environment>/<filename>` on the orphan branch,
+ * or `null` if absent. Sibling of `readBlobFromPath` returning the
+ * content-address rather than the content. A read-modify-write ledger append
+ * pairs this with {@link readBlobBySha} to pin its baseline read to an exact
+ * sha, then passes that sha as `writeBlobToPath`'s `expectPriorPathSha`.
+ */
+export declare function readPathSha(environment: string, filename: string, opts?: {
+    cwd?: string;
+}): Promise<string | null>;
 /**
  * Storage key for a snapshot on the orphan branch. Single-stack projects key by
  * lexicon (`<env>/<lexicon>.json`, unchanged). A multi-stack project (see
@@ -81,6 +71,20 @@ export declare function readSnapshotAt(environment: string, lexicon: string, ref
  * Returns the new orphan-branch commit SHA — the caller still owns pushing
  * via `pushLifecycle` under the same concurrent-write lease `writeSnapshot`
  * uses.
+ *
+ * Retries the whole read-modify-append cycle on `RefCASConflictError`
+ * (#1959 finding 1), the same shape `appendConvergeRecord`
+ * (./converge-ledger.ts) and `appendGateResolution` (./gate-ledger.ts) use
+ * for their own append-only ledgers: `writeBlobToPath`'s own retry only
+ * absorbs a conflict caused by some *other* env/file changing — a conflict
+ * on this exact `releases.jsonl` (e.g. two deploys to the same env racing)
+ * needs `existing` re-read fresh so the appended line list is rebuilt onto
+ * whatever the other writer just committed, not silently dropped by
+ * retrying with a blob computed from a stale read.
+ *
+ * The baseline read must be `readPathSha` + `readBlobBySha` rather than
+ * `readBlobFromPath`, so the exact sha `existing` came from can be passed as
+ * `expectPriorPathSha`. See `writeBlobToPath` for the race that closes.
  */
 export declare function appendReleaseRecordLine(environment: string, recordJson: string, opts?: {
     cwd?: string;
@@ -166,6 +170,126 @@ export declare function pushLifecycle(opts?: {
 export declare function fetchLifecycle(opts?: {
     cwd?: string;
 }): Promise<boolean>;
+/**
+ * Thrown by {@link updateRefCAS}/{@link deleteRefCAS} when `ref` no longer
+ * points at the `oldValue` the caller last observed — another writer moved
+ * it concurrently. Deliberately a distinct type from a generic git failure so
+ * callers (a lease acquire, a retried ledger append) can tell "I lost a race"
+ * from "git itself failed" and react differently to each.
+ */
+export declare class RefCASConflictError extends Error {
+    readonly ref: string;
+    readonly expected: string | null;
+    constructor(ref: string, expected: string | null, stderr: string);
+}
+/**
+ * Thrown by {@link updateRefCAS}/{@link deleteRefCAS} when the ref update
+ * failed because git found a stale `.lock` file already sitting next to the
+ * ref (#1959 finding 2) — what a `chant operator`/`chant approve`/etc.
+ * process leaves behind when it is killed (SIGKILL, OOM, `kill -9`) mid-write,
+ * *before* `git update-ref`'s own lockfile-then-rename completes. This is
+ * exactly the crash this feature must recover from, and it is NOT a CAS
+ * conflict: nobody else actually holds the ref (no other writer is racing,
+ * the previous one is simply dead), so it must never be misread as "someone
+ * else updated it first" — see `./lease.ts`'s `acquireLease`, which used to
+ * (before this fix) read this as "lease held by someone else" and quietly
+ * back off forever, since the dead process's lock file never goes away on
+ * its own.
+ */
+export declare class StaleLockError extends Error {
+    readonly ref: string;
+    readonly lockPath: string;
+    constructor(ref: string, lockPath: string, stderr: string);
+}
+/** Read the SHA `ref` currently points to, or `null` if it doesn't exist. Works for any ref, not just the lifecycle branch. */
+export declare function readRefSha(ref: string, opts?: {
+    cwd?: string;
+}): Promise<string | null>;
+/**
+ * Compare-and-swap update of an arbitrary ref. `oldValue` is the SHA the
+ * caller last observed the ref at, or `null` to assert the ref does not yet
+ * exist (git's own convention: an empty `<oldvalue>` argument to
+ * `update-ref` means "must not exist"). Throws {@link RefCASConflictError}
+ * when the ref genuinely moved since `oldValue` was read, {@link
+ * StaleLockError} when a leftover lock file from a killed process is
+ * blocking the write, or a plain `Error` for anything else — never silently
+ * overwrites, and never misclassifies one failure as another (#1959 finding
+ * 2; see {@link classifyRefFailure}).
+ */
+export declare function updateRefCAS(ref: string, newValue: string, oldValue: string | null, opts?: {
+    cwd?: string;
+}): Promise<void>;
+/**
+ * Compare-and-swap delete of an arbitrary ref — `oldValue` is required (no
+ * "delete unconditionally" escape hatch here) so releasing a lease you no
+ * longer hold can never delete someone else's newer one. Same failure
+ * classification as {@link updateRefCAS} (#1959 finding 2).
+ */
+export declare function deleteRefCAS(ref: string, oldValue: string, opts?: {
+    cwd?: string;
+}): Promise<void>;
+/**
+ * Write arbitrary content as a git blob object — no tree, no commit, no ref
+ * update. The building block a CAS ref's value can point at directly: a
+ * lease record (`./lease.ts`) has no meaningful "tree of files", so its ref
+ * targets a blob SHA rather than a commit the way `writeBlobToPath`'s tree-
+ * building pipeline does.
+ */
+export declare function writeBlob(content: string, opts?: {
+    cwd?: string;
+}): Promise<string>;
+/** Read a blob's raw content by its SHA (whatever object a ref points at directly). Returns `null` when the object doesn't exist locally. */
+export declare function readBlobBySha(sha: string, opts?: {
+    cwd?: string;
+}): Promise<string | null>;
+/**
+ * Push one arbitrary ref (e.g. a lease ref) to the remote, guarded the same
+ * way {@link pushLifecycle} guards the ledger branch: `--force-with-lease`
+ * keyed to the remote SHA last observed locally, so a concurrent push from a
+ * second machine is rejected rather than silently clobbered. Plain `--force`
+ * underneath that lease — a lease ref's value is a bare blob SHA, not a
+ * commit descending from the previous one, so there is no "fast-forward" to
+ * preserve, only the CAS the lease guard already provides.
+ *
+ * Returns `false` (never throws) when no remote is configured — a
+ * remote-less project's lease is local-only by construction (see
+ * `./lease.ts`'s module doc), or when the push itself is rejected (the
+ * caller re-reads and retries; see `acquireLease`).
+ */
+export declare function pushRef(ref: string, opts?: {
+    cwd?: string;
+}): Promise<boolean>;
+/**
+ * Fetch one arbitrary remote ref into a local ref of a possibly *different*
+ * name (#1959 finding 3). `+` forces the update even when it isn't a
+ * fast-forward (a lease ref's new value is rarely a descendant of its old
+ * one). Returns `false` (never throws) when no remote is configured.
+ *
+ * The `localRef !== remoteRef` shape exists so a read path can observe what
+ * the remote currently holds without ever touching a local ref another code
+ * path treats as CAS-authoritative — see {@link fetchRef}'s doc and
+ * `./lease.ts`'s `readLease`, which fetches into a side tracking ref
+ * (`refs/chant/lease-remote/<op>`) for exactly this reason.
+ */
+export declare function fetchRefInto(remoteRef: string, localRef: string, opts?: {
+    cwd?: string;
+}): Promise<boolean>;
+/**
+ * Fetch one arbitrary ref from remote into the same local ref name.
+ *
+ * **Caution for a read path (#1959 finding 3):** this force-overwrites
+ * `ref` locally (`+ref:ref`) — safe for a ref only a CAS write path ever
+ * mutates locally between fetches, but NOT safe to call from a plain read
+ * before every read if some other local writer (in the same clone) might be
+ * mid-write: fetching here would force the local ref back to whatever the
+ * remote last had, clobbering a just-written, not-yet-pushed local value out
+ * from under it. `./lease.ts`'s `readLease` used to do exactly that; it now
+ * uses {@link fetchRefInto} against a side tracking ref instead. Prefer
+ * `fetchRefInto` for any new read-before-decide path.
+ */
+export declare function fetchRef(ref: string, opts?: {
+    cwd?: string;
+}): Promise<boolean>;
 /**
  * Get the current HEAD commit SHA of the main working branch.
  */

package/dist/lifecycle/git.d.ts.map

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

package/dist/lifecycle/index.d.ts

@@ -16,4 +16,8 @@ export * from "./build-ledger-store.js";
 export * from "./oras-referrer-lookup.js";
 export * from "./status.js";
 export * from "./teardown.js";
+export * from "./symptoms.js";
+export * from "./converge-ledger.js";
+export * from "./scenario.js";
+export * from "./scenario-eval.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lifecycle/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lifecycle/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lifecycle/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC"}

package/dist/lifecycle/lease.d.ts

@@ -0,0 +1,113 @@
+export declare const LEASE_REF_PREFIX = "refs/chant/lease/";
+/**
+ * Side namespace `readLease` fetches remote lease state into (#1959 finding
+ * 3), rather than into `refs/chant/lease/<op>` itself. That ref is the CAS
+ * write path's alone (`acquireLease`/`releaseLease`, both via
+ * `updateRefCAS`/`deleteRefCAS`); a read path force-fetching directly into
+ * it would risk clobbering a just-acquired, not-yet-pushed local lease with
+ * the still-stale remote value — the exact race a concurrent `chant operator
+ * status` in the same clone could hit during the acquire→push window. See
+ * `readLease`'s doc for how the two are reconciled without that risk.
+ */
+export declare const LEASE_REMOTE_TRACKING_PREFIX = "refs/chant/lease-remote/";
+/**
+ * Default lease TTL — long enough that a normal tick (observe, classify,
+ * a budget-bounded number of dispatches) finishes well inside it; short
+ * enough that a crashed operator's environment resumes converging soon
+ * after, without a human intervening. The operator loop renews well before
+ * this elapses (every round it still owns the lease for), so under normal
+ * operation the TTL is never actually reached.
+ */
+export declare const DEFAULT_LEASE_TTL_MS: number;
+export declare function leaseRef(opName: string): string;
+/** One lease's live state — the entire durable record; there is no history, only the current holder (see this module's doc on why no separate ledger). */
+export interface LeaseRecord {
+    op: string;
+    /** `<hostname>:<pid>:<random>` — a diagnostic identity, not itself the fencing mechanism (`token` is). */
+    holder: string;
+    /** Fencing token — new only when the lease actually changes hands; see module doc. */
+    token: string;
+    acquiredAt: string;
+    expiresAt: string;
+}
+/** A stable-enough identity for "who holds this lease", for logs and `chant operator status` — hostname:pid, plus a short random suffix so two processes started in the same pid-reuse window never read as the same holder. */
+export declare function currentHolderId(): string;
+export interface ReadLeaseResult {
+    /** The ref's current SHA (the CAS anchor for the next write), or `null` if no lease has ever been written. */
+    sha: string | null;
+    record?: LeaseRecord;
+}
+/**
+ * Read the live lease for `opName`, fetching the remote ref first (best-
+ * effort) so a lease held by another machine is visible before deciding
+ * whether to acquire.
+ *
+ * The fetch lands in a side tracking ref (`refs/chant/lease-remote/<op>`),
+ * never directly into `refs/chant/lease/<op>` itself (#1959 finding 3) — the
+ * canonical local ref is written *only* by the CAS path
+ * (`acquireLease`/`releaseLease`), so a read (this function is called
+ * before every `acquireLease`, and directly by `chant operator status`) can
+ * never force it back to a stale remote value out from under a concurrent
+ * local acquirer. The returned `record` is whichever of the local/remote
+ * views is more current by `leaseFreshnessKey` (ties keep local): this
+ * still gives full cross-machine visibility — a genuinely newer remote
+ * holder wins — while a just-acquired, not-yet-pushed local lease (freshest
+ * by construction) always survives a same-clone concurrent read. `sha`
+ * — the CAS anchor a subsequent `acquireLease`/`releaseLease` writes
+ * against — is always the local ref's own actual value; only the local
+ * canonical ref is ever a valid basis for a `updateRefCAS`/`deleteRefCAS`
+ * call against it, regardless of what the comparison decided about `record`.
+ */
+export declare function readLease(opName: string, opts?: {
+    cwd?: string;
+}): Promise<ReadLeaseResult>;
+export interface AcquireLeaseResult {
+    acquired: boolean;
+    lease?: LeaseRecord;
+    /** Present when not acquired: the lease record currently held by someone else. */
+    heldBy?: LeaseRecord;
+}
+/**
+ * Acquire or renew the lease for `opName` as `holder`. Succeeds when the ref
+ * doesn't exist yet, is expired, or is already held by `holder` (a renewal:
+ * same token, pushed-out expiry). Fails — returns `acquired: false`, without
+ * throwing — when it's live-held by someone else, or when a concurrent CAS
+ * write is lost to a race that happened between this call's read and its
+ * write ({@link RefCASConflictError}); both read identically to a caller
+ * deciding whether to tick this round ("someone else has it right now,
+ * skip").
+ *
+ * Deliberately does NOT swallow a `StaleLockError` (./git.ts) into that same
+ * "someone else has it" outcome (#1959 finding 2): a leftover `.lock` file
+ * from a killed process is not contention, it's wreckage, and treating it as
+ * "held by someone else" would make `chant operator` back off forever
+ * against a lease nobody can ever actually acquire again without manual
+ * intervention. It propagates instead, so the caller (`../op/operator.ts`'s
+ * `runOperatorRound`) can surface it as its own distinct, diagnosable event
+ * rather than a silent, permanent skip.
+ */
+export declare function acquireLease(opName: string, holder: string, opts?: {
+    cwd?: string;
+    ttlMs?: number;
+    now?: () => Date;
+}): Promise<AcquireLeaseResult>;
+/**
+ * Release the lease, but only when `holder`/`token` still match the live
+ * value — releasing a lease this caller no longer actually holds would
+ * silently drop someone else's. Best-effort courtesy: a lease nobody
+ * releases is reclaimed anyway once its TTL passes, so a failed release
+ * (returns `false`, never throws) is not itself a correctness problem.
+ */
+export declare function releaseLease(opName: string, holder: string, token: string, opts?: {
+    cwd?: string;
+}): Promise<boolean>;
+/**
+ * Does `holder`/`token` still match the live lease? The fencing check a
+ * tick uses right before trusting its own work as authoritative (see
+ * `../op/operator.ts`). Fetches first, so a lease stolen by another machine
+ * is detected, not just a stale local read.
+ */
+export declare function stillHoldsLease(opName: string, holder: string, token: string, opts?: {
+    cwd?: string;
+}): Promise<boolean>;
+//# sourceMappingURL=lease.d.ts.map

package/dist/lifecycle/lease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease.d.ts","sourceRoot":"","sources":["../../src/lifecycle/lease.ts"],"names":[],"mappings":"AAqCA,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AAEpD;;;;;;;;;GASG;AACH,eAAO,MAAM,4BAA4B,6BAA6B,CAAC;AAEvE;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,QAAa,CAAC;AAE/C,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE/C;AAoBD,0JAA0J;AAC1J,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,0GAA0G;IAC1G,MAAM,EAAE,MAAM,CAAC;IACf,sFAAsF;IACtF,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,gOAAgO;AAChO,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAwBD,MAAM,WAAW,eAAe;IAC9B,8GAA8G;IAC9G,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,eAAe,CAAC,CAajG;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,kFAAkF;IAClF,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CAAE,GACxD,OAAO,CAAC,kBAAkB,CAAC,CAoC7B;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC,OAAO,CAAC,CAGlB"}

package/dist/lifecycle/scenario-eval.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure evaluation of a plan scenario's `expect` clause against a `ChangeSet`
+ * (#1292).
+ *
+ * `evaluateScenario` reads only what the caller hands it — a `ChangeSet` and
+ * a `ScenarioExpect` — and does no I/O. Building the change set (reading a
+ * fixture, replaying it in place of a live observation) is the CLI handler's
+ * job (../cli/handlers/scenario.ts); this module is the part that stays
+ * testable without a filesystem, a build, or a fixture.
+ *
+ * Built on the same primitives `chant lifecycle plan` already computes from:
+ * `summarize` for counts, a filter over `cs.entries` for named deletes and
+ * ownership, and `evaluateUnobservedGate` (./unobserved-gate.ts, #1568) for
+ * the unobserved clause.
+ */
+import { type ChangeSet } from "./change-set.js";
+import type { ScenarioExpect } from "./scenario.js";
+/**
+ * One clause's verdict — always present in {@link ScenarioVerdict.checks}, in
+ * declaration order, whether it passed or not. A scenario with no failing
+ * clauses is legible too: every check that ran, and that it held.
+ */
+export interface ScenarioCheckResult {
+    /** Which `expect` clause this is (`"noop"`, `"create"`, `"deletes"`, …). */
+    clause: string;
+    pass: boolean;
+    /** Present when `pass` is false — what was expected vs what the plan proposes, naming resources for delete/ownership failures. */
+    detail?: string;
+}
+/** The result of evaluating one scenario's `expect` against a change set. */
+export interface ScenarioVerdict {
+    pass: boolean;
+    /** Every clause `expect` declared, evaluated — see {@link ScenarioCheckResult}. */
+    checks: ScenarioCheckResult[];
+}
+/**
+ * Evaluate `expect` against `cs`. Pure: reads `cs` and `expect`, computes
+ * nothing else. Every clause present on `expect` is checked independently and
+ * every one contributes to `checks`; `pass` is true only when all of them are.
+ */
+export declare function evaluateScenario(cs: ChangeSet, expect: ScenarioExpect): ScenarioVerdict;
+//# sourceMappingURL=scenario-eval.d.ts.map

package/dist/lifecycle/scenario-eval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenario-eval.d.ts","sourceRoot":"","sources":["../../src/lifecycle/scenario-eval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAGzD,OAAO,KAAK,EAA6B,cAAc,EAA4B,MAAM,YAAY,CAAC;AAEtG;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,kIAAkI;IAClI,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,OAAO,CAAC;IACd,mFAAmF;IACnF,MAAM,EAAE,mBAAmB,EAAE,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,GAAG,eAAe,CAgDvF"}