@intentius/chant 0.49.0 → 0.51.0

package/dist/lifecycle/assert-live.d.ts

@@ -0,0 +1,77 @@
+/**
+ * assertLive (#1857) — the read half of the test harness (#1224):
+ * observation-backed assertions against a live deploy, for exactly one
+ * declared entity at a time. Same primitive teardown.ts's fallback path
+ * uses — `describeResources` — turned into a pass/throw instead of a
+ * would-delete set.
+ *
+ * The observation contract (#1089) draws a hard line between OBSERVED-ABSENT
+ * and NOT-OBSERVED: a declared entity the read could not cover is never the
+ * same as one confirmed missing. `assertLiveEntity` preserves that line by
+ * construction — NOT-OBSERVED throws {@link UnobservedAssertionError}, a type
+ * distinct from the {@link LiveAssertionError} an observed-absent, foreign,
+ * or status-mismatched verdict throws, so a caller can tell "could not tell"
+ * from "confirmed wrong" without parsing a message.
+ *
+ * Marker verification is best-effort by the same logic {@link
+ * ResourceMetadata.marker}'s own contract states: a lexicon with no marker
+ * channel on this read path (aws's thin `describeResources`, `ownership:
+ * "unknown"`) reports no marker at all, which is not the same claim as
+ * "foreign". Enforcing a match whenever the channel exists — a present
+ * mismatch, or `ownership: "foreign"` with no marker to show — catches the
+ * case the harness cares about (a same-named leftover from another env);
+ * an absent channel is passed through unverified rather than making every
+ * lexicon without one unusable.
+ */
+import { type UnobservedReason } from "../observation.js";
+import type { ObservationLexicon, ResourceMetadata } from "../lexicon.js";
+import type { OwnershipMarker } from "../ownership.js";
+/**
+ * Thrown by {@link assertLiveEntity} for a confirmed failure: observed
+ * absent, a marker that names another stack/env, a resource confirmed
+ * foreign, or a status mismatch. Never thrown for NOT-OBSERVED — see {@link
+ * UnobservedAssertionError}.
+ */
+export declare class LiveAssertionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when the entity is NOT-OBSERVED (#1089) rather than confirmed
+ * present or absent. Kept as its own type, not a flag on {@link
+ * LiveAssertionError}: a suite (or a CI policy) that wants to fail loudly on
+ * "could not tell" but treat it differently from a confirmed miss can catch
+ * this one specifically.
+ */
+export declare class UnobservedAssertionError extends Error {
+    readonly entity: string;
+    readonly reason: UnobservedReason;
+    readonly detail?: string | undefined;
+    constructor(entity: string, reason: UnobservedReason, detail?: string | undefined);
+}
+export interface AssertLiveOptions {
+    /** Expected `ResourceMetadata.status`, where the lexicon reports one. Skipped when omitted. */
+    status?: string;
+}
+export interface AssertLiveEntityOptions extends AssertLiveOptions {
+    plugin: ObservationLexicon;
+    /** chant entity name — the key to assert on. */
+    name: string;
+    entityType: string;
+    props: Record<string, unknown>;
+    /** This lexicon's own built output for the deploy, or `""` when none was built. */
+    buildOutput: string;
+    environment: string;
+    /** This deploy's identity — the marker an observed resource is checked against. */
+    marker: OwnershipMarker;
+}
+/**
+ * Assert one declared entity is live: observed present in `environment`, not
+ * a confirmed-foreign resource, and — when `status` is given — reporting
+ * that status. Resolves to the entity's {@link ResourceMetadata} on success.
+ *
+ * Throws {@link UnobservedAssertionError} for NOT-OBSERVED. Throws {@link
+ * LiveAssertionError} for observed-absent, a confirmed-foreign identity, or a
+ * status mismatch.
+ */
+export declare function assertLiveEntity(opts: AssertLiveEntityOptions): Promise<ResourceMetadata>;
+//# sourceMappingURL=assert-live.d.ts.map

package/dist/lifecycle/assert-live.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-live.d.ts","sourceRoot":"","sources":["../../src/lifecycle/assert-live.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAA6D,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClH,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;GAMG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;aAE/B,MAAM,EAAE,MAAM;aACd,MAAM,EAAE,gBAAgB;aACxB,MAAM,CAAC,EAAE,MAAM;gBAFf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,gBAAgB,EACxB,MAAM,CAAC,EAAE,MAAM,YAAA;CAQlC;AAED,MAAM,WAAW,iBAAiB;IAChC,+FAA+F;IAC/F,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,uBAAwB,SAAQ,iBAAiB;IAChE,MAAM,EAAE,kBAAkB,CAAC;IAC3B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,mFAAmF;IACnF,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,MAAM,EAAE,eAAe,CAAC;CACzB;AAQD;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAwD/F"}

package/dist/lifecycle/change-set.d.ts

@@ -14,6 +14,7 @@
  */
 import { type AttributeChange, type DiffLiveInput } from "./live-diff.js";
 import { type UnobservedReason } from "../observation.js";
+import { type Disruption } from "./disruption.js";
 /**
  * What the projection proposes for a single resource.
  *
@@ -125,6 +126,22 @@ export interface ChangeSetEntry {
     effectReason?: EffectFireReason;
     /** Human-readable backing for `effectReason` (the digests that differ, the unresolved path). */
     effectDetail?: string;
+    /**
+     * How much applying this change hurts (#1665) — in-place / rolling / replace
+     * / destroy / unknown. Set on `update` entries only: every other action
+     * carries its blast radius in the action itself.
+     *
+     * The verdict comes from the lexicon that owns the spec
+     * ({@link LexiconPlugin.classifyDisruption}), never from core, which has no
+     * per-provider replacement rules and must not grow any. `unknown` is the
+     * default and the only fallback — read it as "nobody could say", never as
+     * "probably in place".
+     */
+    disruption?: Disruption;
+    /** The attribute paths that forced `disruption` (#1665). */
+    disruptionBecause?: string[];
+    /** Human-readable backing for `disruption` — the spec knowledge behind the call, or why there is none. */
+    disruptionDetail?: string;
 }
 export interface ChangeSet {
     env: string;

package/dist/lifecycle/change-set.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"change-set.d.ts","sourceRoot":"","sources":["../../src/lifecycle/change-set.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAY,KAAK,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EAAwB,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,YAAY,CAAC;AAEnH;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG,eAAe,GAAG,kBAAkB,CAAC;AAEvF;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;AAExD,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,YAAY,CAAC;IACrB,kEAAkE;IAClE,QAAQ,EAAE;QACR,oCAAoC;QACpC,QAAQ,EAAE,OAAO,CAAC;QAClB,oCAAoC;QACpC,UAAU,EAAE,OAAO,CAAC;QACpB,qDAAqD;QACrD,IAAI,EAAE,OAAO,CAAC;QACd;;;;;WAKG;QACH,QAAQ,EAAE,OAAO,CAAC;KACnB,CAAC;IACF,6CAA6C;IAC7C,MAAM,CAAC,EAAE,eAAe,EAAE,CAAC;IAC3B,oDAAoD;IACpD,SAAS,EAAE,SAAS,CAAC;IACrB,gFAAgF;IAChF,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,gGAAgG;IAChG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oGAAoG;IACpG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC,gGAAgG;IAChG,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,CA6GvG;AAID,gCAAgC;AAChC,wBAAgB,SAAS,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAarE;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,EAAE,EAAE,SAAS,GAAG,cAAc,CAG5D;AAED,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,CAsCrD"}
+{"version":3,"file":"change-set.d.ts","sourceRoot":"","sources":["../../src/lifecycle/change-set.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,90 @@
+/** One rule's outcome within a tick. */
+export interface ConvergeRuleOutcome {
+    ruleId: string;
+    /**
+     * What actually happened for this fired rule this tick. `"gated"` (#1485)
+     * is gate-as-fact: the dispatched op's own run hit a gate it can't clear
+     * on the local executor, and the tick records that as a terminal, durable
+     * fact — `gateName` names the gate — rather than treating it as a
+     * dispatch failure. Resolution is out-of-band (`chant approve <op>
+     * <gate>`, ./gate-ledger.ts, or a merged PR); the tick itself never
+     * blocks waiting for it.
+     */
+    action: "ran" | "reported" | "skipped-budget" | "skipped-flap" | "gated";
+    /** The dispatched Op name, for `action: "ran"` or `"gated"`. */
+    op?: string;
+    /** The gate's signal name, for `action: "gated"`. */
+    gateName?: string;
+    /** The report reason, for `action: "reported"` (including a flap-damped rule's forced report) — and the human-readable explanation for `action: "gated"`. */
+    reason?: string;
+}
+/** One immutable converge-tick record. */
+export interface ConvergeTickRecord {
+    /** Schema version, so an incompatible future shape is detected before being misread. */
+    version: 1;
+    /** The ConvergeOp's name (`OpConfig.name`). */
+    op: string;
+    env: string;
+    /** ISO-8601 timestamp, caller-supplied (same convention as `ReleaseRecord.timestamp` — library code never calls `Date.now()` internally). */
+    timestamp: string;
+    /** Every rule id whose predicate matched this tick, regardless of what action followed — the flap-damping input. */
+    firedRuleIds: string[];
+    /** Per-rule outcome, for every fired rule. */
+    outcomes: ConvergeRuleOutcome[];
+    /** Aggregate counts backing the tick's one log line. */
+    summary: {
+        drifted: number;
+        remediated: number;
+        reported: number;
+        skippedBudget: number;
+        skippedFlap: number;
+        unobserved: number;
+        adopted: number;
+        /** Rules whose dispatch hit a gate this tick (#1485) — a terminal, non-blocking fact; see `ConvergeRuleOutcome.action`'s doc. @default 0, so an older record without this field still reads as zero, not undefined. */
+        gated?: number;
+    };
+    /** The one human-readable log line this tick produced (issue: "one log line and one ledger record per tick"). */
+    log: string;
+}
+export type ConvergeTickRecordInput = Omit<ConvergeTickRecord, "version">;
+/**
+ * Append one immutable tick record. Does not push to the remote — call
+ * `pushLifecycle` (./git.ts) afterward, same two-step shape every other
+ * ledger write here uses.
+ *
+ * Retries the whole read-modify-write cycle (#1485) on `RefCASConflictError`
+ * — `writeBlobToPath`'s ref write is CAS-guarded, so a concurrent writer to
+ * a *different* env's file on the same orphan branch (two operators ticking
+ * two environments at once is the ordinary case, not an edge case) can lose
+ * the race and needs to re-read the branch tip and retry, not fail the
+ * tick. Each retry re-reads `existing` fresh, so it always appends onto
+ * whatever the other writer just committed rather than reintroducing a stale
+ * read. Exhausting the budget re-throws the conflict — a real, sustained
+ * pile-up of writers is a signal worth surfacing, not silently swallowing.
+ *
+ * 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 appendConvergeRecord(input: ConvergeTickRecordInput, opts?: {
+    cwd?: string;
+}): Promise<{
+    commit: string;
+    record: ConvergeTickRecord;
+}>;
+/** Read every tick record for `environment`, oldest first. Malformed lines are skipped, not thrown on — a corrupted or hand-edited ledger degrades gracefully, the same stance `readReleaseLedger` takes. */
+export declare function readConvergeLedger(environment: string, opts?: {
+    cwd?: string;
+}): Promise<{
+    records: ConvergeTickRecord[];
+    malformed: number;
+}>;
+/**
+ * How many consecutive most-recent ticks (newest first) fired `ruleId`,
+ * stopping at the first tick where it did not — the count a rule's
+ * `flapThreshold` is compared against. `0` when the newest tick didn't fire
+ * it (including an empty ledger).
+ */
+export declare function consecutiveRuleFires(records: ConvergeTickRecord[], ruleId: string): number;
+//# sourceMappingURL=converge-ledger.d.ts.map

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

@@ -0,0 +1,96 @@
+/**
+ * Per-change disruption classification (#1665).
+ *
+ * The change set says WHAT a pending change is (`create`/`update`/`delete`/…).
+ * It says nothing about what applying it costs. An `update` that flips a tag
+ * and an `update` that rebuilds a database read identically, and the second one
+ * is the one that wakes somebody up.
+ *
+ * The knowledge that separates them is spec knowledge. CloudFormation's
+ * registry schema declares `createOnlyProperties` per type; Kubernetes' SSA
+ * schema knows which field changes roll a workload. Core owns neither, and
+ * hardcoding either here would put per-provider replacement rules in the tool
+ * — the same mistake `postSynthChecks` exists to avoid. So core defines the
+ * contract and the reporting, and the lexicon that compiled the spec supplies
+ * the answer, via {@link LexiconPlugin.classifyDisruption}.
+ *
+ * The invariant that makes the field trustworthy is that `unknown` is the
+ * default and the only fallback. No classifier, a classifier that says nothing
+ * about an entry, a classifier that throws, a classifier that returns a level
+ * outside the vocabulary — all of them land on `unknown`, never on `in-place`.
+ * A confident "this mutates in place" is only ever a lexicon's own claim.
+ */
+import type { AttributeChange } from "./live-diff.js";
+import type { ChangeSet, ChangeSetEntry } from "./change-set.js";
+/**
+ * How much applying one pending change hurts.
+ *
+ * - `in-place` — the provider mutates the existing resource. No new identity,
+ *   no window where it is absent.
+ * - `rolling` — the resource survives, but its workload is replaced
+ *   incrementally (a Deployment's pod template changing). Disruptive to what
+ *   is running, not to the resource.
+ * - `replace` — a new resource is created and the old one removed. The
+ *   physical id changes; anything holding the old one has to be updated.
+ * - `destroy` — replacement that removes the old resource FIRST. There is a
+ *   window with nothing there, and whatever the old one held is gone.
+ * - `unknown` — nobody could say. The honest value, and the default: it is
+ *   what a change gets when no lexicon classifies it, and it must never be
+ *   read as "probably fine".
+ */
+export type Disruption = "in-place" | "rolling" | "replace" | "destroy" | "unknown";
+/** Every level, most disruptive last — also the guard core validates a lexicon's answer against. */
+export declare const DISRUPTION_LEVELS: readonly Disruption[];
+/** One pending change put to a lexicon for classification. */
+export interface DisruptionQuery {
+    /** The change set entry's `name` — the key a verdict comes back under. */
+    name: string;
+    /** Resource type, when the observation reported one. */
+    type?: string;
+    /** The attribute-level changes the entry carries. */
+    deltas: AttributeChange[];
+}
+/** A lexicon's answer for one query. */
+export interface DisruptionVerdict {
+    disruption: Disruption;
+    /** The attribute paths that forced the verdict — empty or absent when none did. */
+    because?: string[];
+    /** One line of human-readable backing, naming the spec knowledge behind the call. */
+    detail?: string;
+}
+/**
+ * The shape of {@link LexiconPlugin.classifyDisruption}. Keyed by query `name`;
+ * a name the lexicon says nothing about degrades to `unknown`, so a partial
+ * answer is a valid answer.
+ */
+export type DisruptionClassifier = (options: {
+    environment: string;
+    changes: DisruptionQuery[];
+}) => Record<string, DisruptionVerdict> | Promise<Record<string, DisruptionVerdict>>;
+/** The verdict every fallback path produces. */
+export declare function unknownDisruption(detail: string): DisruptionVerdict;
+/**
+ * Annotate one lexicon's change set with a disruption verdict per `update`.
+ *
+ * Only `update` entries are asked about: every other action already carries its
+ * blast radius in the action itself. Called once per lexicon, before the plan
+ * merges the change sets, so `classify` is always the lexicon that produced the
+ * entries — the only party that can map its own observation's attribute paths
+ * back onto spec properties.
+ *
+ * Returns a new change set; the input is not mutated.
+ */
+export declare function annotateDisruption(cs: ChangeSet, environment: string, classify?: DisruptionClassifier): Promise<ChangeSet>;
+/** Count `update` entries per level. Entries with no verdict at all are not counted. */
+export declare function summarizeDisruption(cs: ChangeSet): Record<Disruption, number>;
+/** The most disruptive verdict in the set, or undefined when nothing was classified. */
+export declare function worstDisruption(cs: ChangeSet): Disruption | undefined;
+/**
+ * Warnings a plan should print on stderr — so a `--json` or `--report gitlab-mr`
+ * consumer, whose shape has no column for disruption, still hears about the
+ * expensive rows. Same discipline as the unobserved warning (#1089).
+ */
+export declare function disruptionNotices(cs: ChangeSet): string[];
+/** Render one entry's verdict for the human plan, or "" when there is none. */
+export declare function renderDisruption(entry: ChangeSetEntry): string;
+//# sourceMappingURL=disruption.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"disruption.d.ts","sourceRoot":"","sources":["../../src/lifecycle/disruption.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAEpF,oGAAoG;AACpG,eAAO,MAAM,iBAAiB,EAAE,SAAS,UAAU,EAMlD,CAAC;AAWF,8DAA8D;AAC9D,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED,wCAAwC;AACxC,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,UAAU,CAAC;IACvB,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,EAAE;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B,KAAK,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC;AAErF,gDAAgD;AAChD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAEnE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,SAAS,EACb,WAAW,EAAE,MAAM,EACnB,QAAQ,CAAC,EAAE,oBAAoB,GAC9B,OAAO,CAAC,SAAS,CAAC,CA0CpB;AAiBD,wFAAwF;AACxF,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAY7E;AAED,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,EAAE,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,CAOrE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,EAAE,CAkBzD;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAG9D"}

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.
  */