@intentius/chant 0.46.0 → 0.50.0

package/dist/op/local-executor.d.ts

@@ -42,7 +42,8 @@ export declare class OpRunFailure extends Error {
 }
 /** Parse a Temporal duration string ("5m", "30s", "1h30m", "100ms") to ms. */
 export declare function parseDuration(s: string): number;
-/** Find the first gate step anywhere in the Op (phases + onFailure), if any. */
+/** Find the first gate step anywhere in the Op (phases + onFailure, including
+ * gates nested inside effect steps), if any. */
 export declare function findGate(config: OpConfig): GateStep | undefined;
 /**
  * Execute an Op locally. Resolves with the run result on success; rejects with

package/dist/op/local-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-executor.d.ts","sourceRoot":"","sources":["../../src/op/local-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAiC,QAAQ,EAAkB,MAAM,SAAS,CAAC;AACjG,OAAO,EAAmB,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAI7F,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,MAAM,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,OAAO,CAAC;CACb;AAID,kFAAkF;AAClF,qBAAa,yBAA0B,SAAQ,KAAK;aACtB,UAAU,EAAE,MAAM;gBAAlB,UAAU,EAAE,MAAM;CAO/C;AAED,mFAAmF;AACnF,qBAAa,YAAa,SAAQ,KAAK;aACT,MAAM,EAAE,WAAW;gBAAnB,MAAM,EAAE,WAAW;CAIhD;AAkBD,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAU/C;AAWD,gFAAgF;AAChF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAO/D;AAuJD;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,QAAQ,EAChB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EACnC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACzC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,WAAW,CAAC,CA+BtB"}
+{"version":3,"file":"local-executor.d.ts","sourceRoot":"","sources":["../../src/op/local-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAiC,QAAQ,EAA8B,MAAM,SAAS,CAAC;AAC7G,OAAO,EAAmB,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAM7F,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,MAAM,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,OAAO,CAAC;CACb;AAID,kFAAkF;AAClF,qBAAa,yBAA0B,SAAQ,KAAK;aACtB,UAAU,EAAE,MAAM;gBAAlB,UAAU,EAAE,MAAM;CAO/C;AAED,mFAAmF;AACnF,qBAAa,YAAa,SAAQ,KAAK;aACT,MAAM,EAAE,WAAW;gBAAnB,MAAM,EAAE,WAAW;CAIhD;AAmBD,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAU/C;AA8BD;gDACgD;AAChD,wBAAgB,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAY/D;AAiSD;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,QAAQ,EAChB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EACnC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACzC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,WAAW,CAAC,CAgDtB"}

package/dist/op/op-verb-class.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Op verb classification (#1484) — generalizes `delete: "never" | "owned-only"
+ * | "gated"` (`../lifecycle` teardown/apply's `DeleteMode`) up one level, to
+ * the whole Op: read-only, mutating, or destructive. `ConvergeOp`'s
+ * dial × verb-class matrix (the issue's "Autonomy" table) needs to answer
+ * "what kind of thing is this dispatched Op, from the outside" for an
+ * arbitrary declared Op — including one this project's authors wrote, not
+ * just the pre-built composites — so classification walks `OpConfig`'s
+ * steps rather than trusting a self-reported tag.
+ *
+ * There is no existing per-Op verb-class field (`searchAttributes` is a free
+ * `Record<string,string>` an author may or may not set — `ApplyOp` tags
+ * `{ Apply: "true" }` but nothing requires it, and it carries no verb-class
+ * semantics on its own) and no existing "which activity names are
+ * destructive" registry (`../lint/pipeline-change-gate.ts`'s classifier is
+ * shaped for a `Component` composition's capability-verb steps, not an
+ * `OpConfig`'s activity steps — a genuinely different graph). This module is
+ * that registry's Op-shaped sibling: a small, explicit set of known
+ * mutating/destructive activity function names, plus the one piece of
+ * structured signal that already exists (`nativeApply`'s `deleteMode` arg).
+ *
+ * Fail-closed by construction: an activity `fn` this module doesn't
+ * recognize is classified `mutating`, never `read-only` — an unknown step
+ * might do anything, and "unknown never remediates" (the issue's own honesty
+ * requirement for symptoms) applies here too: this module never silently
+ * clears an Op to free-run just because its steps aren't in the known-safe
+ * list.
+ */
+import type { OpConfig } from "./types.js";
+export type OpVerbClass = "read-only" | "mutating" | "destructive";
+/**
+ * Classify an Op's own composition. Pure — reads only the passed config, no
+ * I/O. `nativeApply`'s `deleteMode` (`"never" | "owned-only" | "gated"`) is
+ * read straight off the step's `args` — `"owned-only"`/`"gated"` are
+ * destructive (both can delete a live resource), `"never"`/absent is merely
+ * mutating (creates/updates only). A step whose `fn` matches neither the
+ * read-only nor the destructive set is `mutating` by default (fail-closed).
+ */
+export declare function classifyOpVerbClass(config: Pick<OpConfig, "phases" | "onFailure">): OpVerbClass;
+/** Does this Op have its own approval gate anywhere in its phases (main or `onFailure`)? Thin re-export of `findGate` under the name this module's callers reach for. */
+export declare function isGated(config: Pick<OpConfig, "phases" | "onFailure">): boolean;
+//# sourceMappingURL=op-verb-class.d.ts.map

package/dist/op/op-verb-class.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"op-verb-class.d.ts","sourceRoot":"","sources":["../../src/op/op-verb-class.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,KAAK,EAA4B,QAAQ,EAAkB,MAAM,SAAS,CAAC;AAElF,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,aAAa,CAAC;AA0CnE;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,WAAW,CAAC,GAAG,WAAW,CA2B/F;AAED,yKAAyK;AACzK,wBAAgB,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,WAAW,CAAC,GAAG,OAAO,CAE/E"}

package/dist/op/operator.d.ts

@@ -0,0 +1,128 @@
+/**
+ * `chant operator` (#1485, epic #1487) — native durable ticks without
+ * Temporal. A deliberately small daemon: a timer, a lease
+ * (../lifecycle/lease.ts), and the existing local executor
+ * (./local-executor.ts) in a loop. No new service, no new state store — the
+ * lease lives on a git ref, tick state lives on the `chant/lifecycle`
+ * orphan branch via the same `convergeTick` activity `chant run <op>`
+ * already calls for a single one-shot tick.
+ *
+ * One round: discover every `ConvergeOp` (searchAttributes `Converge:
+ * "true"`, optionally filtered to one env), and for each one, try to
+ * acquire (or renew) its lease. Win it — run one tick via `runOpLocally` on
+ * the Op's own Observe → Converge phases, the identical path `chant run
+ * <name>` takes for a single tick (issue: "chant run fountain-converge —
+ * one tick, by hand — unchanged, and also the test story"). Lose it — skip
+ * and report, never queue (issue: "a tick that finds the lease held skips
+ * and reports ... never queues").
+ *
+ * Crash recovery needs no special code: a killed operator simply stops
+ * renewing its lease, which expires on its own TTL; the next round (from
+ * this process restarted, a different machine's operator, or a bare `chant
+ * run <name>` invoked by cron) re-acquires and re-ticks. A converge tick
+ * re-observes and re-derives everything every time (ConvergeOp's own
+ * design, #1484) — re-ticking after a crash and ticking on a normal
+ * schedule are the same act, not two different code paths.
+ *
+ * One crash *does* need a distinct report, though (#1959 finding 2): if the
+ * killed operator's own `git update-ref` was interrupted mid-write, it can
+ * leave a stale `.lock` file behind that blocks every future acquire
+ * attempt for that op's lease until someone removes it — TTL expiry doesn't
+ * help, since the ref update itself can't land. `acquireLease` surfaces
+ * that case as a `StaleLockError` rather than ordinary "lease held by
+ * someone else" contention, and a round reports it per-op as
+ * `{ kind: "lease-error" }` (never aborting the whole round) so `chant
+ * operator`'s log names the fix instead of quietly skipping that op
+ * forever.
+ */
+import type { ActivityFn, ActivityProfile } from "./activity-registry.js";
+import { type DiscoveredOp } from "./discover.js";
+import { type OpRunResult } from "./local-executor.js";
+/** Poll interval between rounds — the operator's own cadence, distinct from a `ConvergeOp`'s Temporal `schedule` cron (that field drives the durable path's `TemporalSchedule`, not anything the local executor can read back at discovery time; see this module's doc). Chosen short enough to converge promptly, long enough not to hammer `chant lifecycle plan --live` every few seconds. */
+export declare const DEFAULT_OPERATOR_INTERVAL_MS = 60000;
+/** Discover every `ConvergeOp` in the project (`searchAttributes.Converge === "true"`), optionally filtered to one environment. Ops that don't declare an `Env` search attribute are excluded from an `--env`-filtered discovery (there's nothing to match), but included when no `env` filter is given. */
+export declare function discoverConvergeOps(opts?: {
+    cwd?: string;
+    env?: string;
+}): Promise<{
+    ops: DiscoveredOp[];
+    errors: string[];
+}>;
+/** One discovered ConvergeOp's outcome for one round — what `chant operator`'s one-line-per-tick log (and its tests) key off of. */
+export type OperatorTickEvent = {
+    kind: "ticked";
+    op: string;
+    env: string;
+    result: OpRunResult;
+} | {
+    kind: "skipped-lease-held";
+    op: string;
+    env: string;
+    heldBy?: string;
+} | {
+    kind: "tick-failed";
+    op: string;
+    env: string;
+    error: string;
+}
+/** The lease was lost between acquiring it and the tick finishing (e.g. this process stalled past its TTL and another operator reclaimed it) — the tick's own ledger record (written inside `convergeTick`) still landed, since a converge tick is idempotent by design; this event exists purely so `chant operator`'s log and the ledger-independent test surface can see the fencing violation happened. Never a hard failure. */
+ | {
+    kind: "fenced";
+    op: string;
+    env: string;
+}
+/**
+ * `acquireLease` itself threw — a `StaleLockError` (#1959 finding 2: a
+ * previous `chant operator` was killed mid-write and left a `.lock` file
+ * behind, so this op's lease can no longer be acquired or renewed by
+ * anyone until the file is removed) or any other unexpected failure. A
+ * distinct outcome from `skipped-lease-held` on purpose — this is not
+ * ordinary contention with a live holder, it's wreckage that needs a
+ * human, and reading it as "someone else has it" would make the operator
+ * back off silently forever instead of surfacing the fix. One op's lease
+ * error never aborts the round for every other op.
+ */
+ | {
+    kind: "lease-error";
+    op: string;
+    env: string;
+    error: string;
+};
+export interface OperatorRoundOptions {
+    cwd?: string;
+    /** Restrict ticking to ConvergeOps for this environment. Omit to tick every discovered ConvergeOp. */
+    env?: string;
+    /** @default DEFAULT_LEASE_TTL_MS */
+    leaseTtlMs?: number;
+    /** This process's lease identity. @default currentHolderId() — a fresh identity per process, deliberately: two ticks from what could plausibly be two different processes should behave like two different holders even in a test that reuses one process, unless the caller wants to simulate "same process, later round" by passing a stable value. */
+    holder?: string;
+    /** Injected activity implementations — the CLI loads the real ones the same way `chant run` does (`loadActivities`); tests inject fakes so a round never shells out. */
+    activities: Map<string, ActivityFn>;
+    profiles: Record<string, ActivityProfile>;
+    now?: () => Date;
+    signal?: AbortSignal;
+}
+/**
+ * Run exactly one round: for every discovered ConvergeOp (filtered per
+ * `opts.env`), try its lease; tick the ones this holder wins. Returns one
+ * event per discovered op, in discovery order — deterministic, so tests can
+ * assert on it directly without depending on log output.
+ */
+export declare function runOperatorRound(opts: OperatorRoundOptions): Promise<OperatorTickEvent[]>;
+export interface OperatorLoopOptions extends OperatorRoundOptions {
+    /** @default DEFAULT_OPERATOR_INTERVAL_MS */
+    intervalMs?: number;
+    /** Called after every round completes — the CLI's one-line-per-tick log lives here, not inside the loop itself, so a test can drive rounds without capturing stdout. */
+    onRound?: (events: OperatorTickEvent[]) => void;
+}
+/**
+ * Run rounds forever, sleeping `intervalMs` between them, until
+ * `opts.signal` aborts. The daemon is a convenience, never a requirement
+ * (issue: "if it dies, nothing breaks and nothing is lost") — this function
+ * is exactly `while (!aborted) { round(); sleep(); }`, nothing durable lives
+ * in its own memory that a restart would need to recover.
+ */
+export declare function runOperatorForever(opts: OperatorLoopOptions): Promise<void>;
+/** Render one round's events as `chant operator`'s log line shape — one line per ticked/skipped/failed op, reusing each ticked op's own `convergeTick` log line (`OpRunResult`'s outcome attribute doesn't carry it, so this reads the tick's step record's `Remediated`... actually the human-readable summary comes from the ledger, not the run result — see `../cli/handlers/operator.ts` for where `chant operator status` reads it back). This formats what's available from the round itself: which op, which env, and whether it ticked, skipped, or failed. */
+export declare function formatRoundLine(event: OperatorTickEvent): string;
+//# sourceMappingURL=operator.d.ts.map

package/dist/op/operator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator.d.ts","sourceRoot":"","sources":["../../src/op/operator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAyD,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAI3G,iYAAiY;AACjY,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAWnD,4SAA4S;AAC5S,wBAAsB,mBAAmB,CACvC,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACpC,OAAO,CAAC;IAAE,GAAG,EAAE,YAAY,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAKpD;AAED,oIAAoI;AACpI,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACxE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AACjE,qaAAqa;GACna;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE;AAC7C;;;;;;;;;;GAUG;GACD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE,MAAM,WAAW,oBAAoB;IACnC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sGAAsG;IACtG,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yVAAyV;IACzV,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wKAAwK;IACxK,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACpC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC1C,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAkD/F;AAkBD,MAAM,WAAW,mBAAoB,SAAQ,oBAAoB;IAC/D,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wKAAwK;IACxK,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,EAAE,KAAK,IAAI,CAAC;CACjD;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQjF;AAED,wiBAAwiB;AACxiB,wBAAgB,eAAe,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAahE"}

package/dist/op/receipt-store.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Receipt store seam (#1834, epic #1703) — how the `effect()` step and the
+ * receipt-reading Ops reach a materialized receipt without knowing which
+ * lexicon materializes it.
+ *
+ * The store is injectable: core defines the {@link ReceiptStore} interface and
+ * the activity contracts; the receipt row's lexicon implements the store over
+ * its own resource (#1835's aws row over `AWS::SSM::Parameter`) and exports
+ * the bound activities (`receiptRead`, `receiptWrite`, `receiptStaleness`)
+ * from its `op/activities` module via {@link receiptActivities}. The activity
+ * registry then resolves them by name, exactly like `ensureSecret`
+ * (#1829/#1830, provided by the k8s lexicon). Tests bind a mock store the
+ * same way.
+ *
+ * Write discipline (epic #1703 decision log, item 3): the `effect()` step is
+ * the SOLE writer of a receipt — on success of its nested steps, last. The
+ * store interface carries a `write`, but only the effect step's emitted
+ * read-compare-run-write (and its local-executor twin) reaches it.
+ * `receiptStaleness` — the WatchOp phase (#1834) — is read-only by
+ * construction: it never touches `write` and runs nothing.
+ *
+ * Expectation resolution follows the resolution split (decision 5): a fully
+ * static receipt's expectation is stamped at synthesis and rides the step
+ * data ({@link receiptCheckInput}); a hash-flavor receipt with reference
+ * inputs resolves at run, through the store lexicon's
+ * {@link ReceiptActivityOptions.resolveExpectation} hook — never by hashing
+ * placeholders.
+ */
+import { type EffectReceiptDeclaration, type EffectReceiptFlavor } from "../effect-receipt.js";
+/**
+ * The serializable identity + declaration data of an effect receipt — what an
+ * `effect()` step and a `receiptStaleness` check carry through codegen. Built
+ * from the typed {@link EffectReceiptDeclaration} only ({@link receiptCheckInput});
+ * there is no string form. Reference inputs stay in placeholder form.
+ */
+export interface EffectReceiptRef {
+    /** The receipt's own name (the export-level identity of the witness). */
+    name: string;
+    /** The effect this receipt witnesses. */
+    effect: string;
+    /** How the receipt is compared: mere presence, or a digest of the inputs. */
+    flavor: EffectReceiptFlavor;
+    /** The effect's inputs as recorded at synthesis (references as placeholders). */
+    inputs: Record<string, unknown>;
+}
+/**
+ * The injectable seam over the materialized receipt (#1835 implements it for
+ * SSM; tests implement it with a map). `read` returns the receipt's current
+ * stored value, or `undefined` when the receipt is absent. `write` stores the
+ * expectation as the new value — called only by the effect step, on success,
+ * last.
+ */
+export interface ReceiptStore {
+    read(receipt: EffectReceiptRef): Promise<string | undefined>;
+    write(receipt: EffectReceiptRef, expectation: string): Promise<void>;
+}
+/** One receipt to check: its identity plus, when the receipt is fully static,
+ * the expectation stamped at synthesis. */
+export interface ReceiptCheckInput {
+    receipt: EffectReceiptRef;
+    /** Present when the expectation was computable at synthesis; absent when
+     * reference inputs resolve at run (decision 5). */
+    expectation?: string;
+}
+/**
+ * Snapshot a typed receipt declaration into check-input data: the
+ * {@link EffectReceiptRef} plus the synthesis-time expectation when the
+ * receipt is fully static. Used by the `effect()` builder and by WatchOp's
+ * staleness phase — the single place "static enough to hash now" is decided.
+ */
+export declare function receiptCheckInput(receipt: EffectReceiptDeclaration): ReceiptCheckInput;
+/** Args of the `receiptRead` activity, as the effect step's codegen emits them. */
+export interface ReceiptReadArgs extends ReceiptCheckInput {
+}
+/** Result of the `receiptRead` activity. `current` is `null` (not `undefined`)
+ * for an absent receipt so the value survives JSON transport. */
+export interface ReceiptReadResult {
+    /** The receipt's live stored value, or null when absent. */
+    current: string | null;
+    /** The resolved expectation the workflow compares and later writes. */
+    expectation: string;
+    /** Convenience: `current === expectation`. */
+    applied: boolean;
+}
+/** Args of the `receiptWrite` activity — the receipt and the resolved
+ * expectation returned by the preceding `receiptRead`. */
+export interface ReceiptWriteArgs {
+    receipt: EffectReceiptRef;
+    expectation: string;
+}
+/** Args of the read-only `receiptStaleness` activity (WatchOp). */
+export interface ReceiptStalenessArgs {
+    receipts: ReceiptCheckInput[];
+}
+/** One stale receipt, reported as a finding — never acted on. */
+export interface ReceiptStaleFinding {
+    /** The receipt's name. */
+    receipt: string;
+    /** The effect the receipt witnesses. */
+    effect: string;
+    /** `absent` — no receipt stored; `differs` — stored value is not the expectation. */
+    kind: "absent" | "differs";
+    /** The resolved expectation. */
+    expected: string;
+    /** The live stored value (present only for `differs`). */
+    current?: string;
+}
+/** Result of the `receiptStaleness` activity. */
+export interface ReceiptStalenessResult {
+    stale: boolean;
+    findings: ReceiptStaleFinding[];
+}
+/** Options for {@link receiptActivities}. */
+export interface ReceiptActivityOptions {
+    /**
+     * Resolve a reference-carrying receipt's expectation at run (decision 5) —
+     * the store lexicon's hook to deploy-time values, typically wrapping core's
+     * `resolveReceiptExpectation`. Without it, a check input that carries no
+     * synthesis-time expectation fails loudly rather than hashing placeholders.
+     */
+    resolveExpectation?: (receipt: EffectReceiptRef) => Promise<string> | string;
+}
+/** The three receipt activities, bound to one store. */
+export interface ReceiptActivities {
+    receiptRead: (args: ReceiptReadArgs, signal?: AbortSignal) => Promise<ReceiptReadResult>;
+    receiptWrite: (args: ReceiptWriteArgs, signal?: AbortSignal) => Promise<{
+        written: true;
+        receipt: string;
+    }>;
+    receiptStaleness: (args: ReceiptStalenessArgs, signal?: AbortSignal) => Promise<ReceiptStalenessResult>;
+}
+/**
+ * Bind the receipt activities to a store. The store's lexicon calls this once
+ * and re-exports the result from its `op/activities` module; the activity
+ * registry picks the functions up by name for both executors.
+ */
+export declare function receiptActivities(store: ReceiptStore, opts?: ReceiptActivityOptions): ReceiptActivities;
+//# sourceMappingURL=receipt-store.d.ts.map

package/dist/op/receipt-store.d.ts.map

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

package/dist/op/step-output-ref.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Step-output references — chant #1290 ("A step cannot reference a prior
+ * step's output, so values leave an Op only as search attributes").
+ *
+ * An Op's steps run in a fixed sequence chant already knows: phases in
+ * order, and (within a non-parallel phase) steps in order. Today the only
+ * way a value escapes a step is `outcomeAttribute`, which stringifies it
+ * into a Temporal search attribute — a UI filter, not something a later
+ * step can consume. `StepOutputRef` is the mechanism that lets a later
+ * step's `args` hold a *reference* to an earlier step's declared return
+ * value instead.
+ *
+ * Deliberately a reference, not an expression: `diff.out.driftedStacks` is
+ * a value placeholder the build resolves and the serializer compiles into a
+ * real local variable in the generated workflow — never `diff.out.count >
+ * 0` or a `.map()` over a reference. That property (an Op is data you can
+ * read and know what it does, not a program) is exactly what makes it safe
+ * to add this without Ops becoming programs; see the issue's "line not to
+ * cross".
+ *
+ * Scope, kept deliberately tight (see the issue's "Open questions"):
+ *  - same-Op only — no cross-Op plumbing (that needs a durable place to put
+ *    the value, which #1290 explicitly defers).
+ *  - main `phases` only — a step inside `onFailure` or nested inside an
+ *    `EffectStep` can neither produce nor consume a step-output reference.
+ *    `onFailure` compensation runs only when something upstream already
+ *    failed, so a main-phase step's captured result isn't reliably
+ *    available there; an effect step's nested steps run only when the
+ *    receipt comparison mismatches, so a value it produces isn't reliably
+ *    available to anything outside it either. Both are conditional
+ *    execution paths, which is exactly the class of thing #1290 keeps out
+ *    of an Op's inert-data model.
+ *  - producer must run to completion before the consumer starts: an earlier
+ *    phase, or an earlier step within the same non-parallel phase. Two
+ *    steps in the same parallel phase run concurrently (`Promise.all`) with
+ *    no ordering guarantee, so neither may reference the other.
+ *  - the producer needs a registered `ActivityContract` with a `returns`
+ *    schema — without one there is nothing to validate the reference
+ *    against, and it degrades into the same stringly path `outcomeAttribute`
+ *    already had (chant #1288 comment on this issue).
+ *
+ * Cross-contract type compatibility (chant #1950 pre-merge review, finding
+ * 3): `validateStepOutputRefs` checks the producer side (a registered
+ * contract with a `returns` schema, and — when `path` is set — that the path
+ * resolves on it) and, separately, `validateActivitySteps`/TMP012 checks a
+ * step's `args` against its own contract's `args` schema — but a
+ * {@link StepOutputRef} sitting in `args` is a placeholder object at build
+ * time, not the value it resolves to, so TMP012 skips it (see
+ * `activity-contract.ts`'s `isStepOutputRefValue` guard) rather than
+ * false-positive on it. Nothing before this compared the *consumer's*
+ * declared type at that position against the *producer's* declared type at
+ * `path` — a string-returning path could feed a number-typed arg and both
+ * checks would pass. `validateStepOutputRefs` now adds one more check for
+ * exactly this: when `path` is set, and both the producer's and the
+ * consumer's contracts are registered, it compares the zod schema at the
+ * producer's `path` against the zod schema at the consumer's arg position by
+ * primitive shape (`string`/`number`/`boolean`/`object`/`array` — see
+ * `activity-contract.ts`'s `primitiveKindOf`) and flags a mismatch. This is
+ * deliberately shallow, the same "hard stop rather than guess" posture
+ * `pathExistsInSchema`'s doc above takes for a record/array root: a union, an
+ * enum, a literal, `z.any()`/`z.unknown()`, a transform, or a ref sitting
+ * inside an array in `args` (no stable position to look up an arg schema
+ * against) all bail silently — no issue raised, not a false negative
+ * reported as clean, just genuinely out of this check's reach. A more
+ * complete version (real zod-schema subtyping/union-aware comparison) is
+ * exactly the kind of thing #1288 Stage 2 (typed step builders, deriving
+ * from contracts instead of restating them) would need anyway; deferred
+ * there rather than grown ad hoc here. A whole-value reference (no `path`)
+ * is skipped by this check for the same reason it's skipped by the
+ * path-existence check: there's no single field to compare.
+ *
+ * References only, no expressions: the issue asks for this to be "enforced
+ * by a lint rule rather than left as a convention." What's here instead is
+ * a runtime-on-load guard — `diff.out.count > 0` or a template literal over
+ * a reference coerces it to a primitive, and the reference throws when that
+ * happens, at the moment chant loads the `.op.ts` module to build the
+ * entity graph (i.e. still before anything runs). A real static lint rule
+ * would need to parse-inspect the author's TypeScript for expression syntax
+ * around a reference — a genuine ESLint-rule-shaped feature, and a bigger
+ * one than this issue's scope. The coercion guard catches the same misuse
+ * (arithmetic, comparisons, template literals, `String(...)`) without it;
+ * a `.map()`-style structural misuse already throws on its own (`StepOutputRef`
+ * has no array methods).
+ */
+import type { ActivityStep, OpConfig } from "./types.js";
+import { type ActivityContract, type ActivityContractIssue } from "./activity-contract.js";
+declare const STEP_OUTPUT_REF_BRAND: unique symbol;
+/**
+ * A typed reference to a prior step's declared return value. Inert by
+ * construction — it carries a producer step id and an optional dot-path
+ * into that producer's return schema, resolved by `chant build`
+ * (`validateStepOutputRefs`) and compiled by the temporal serializer into a
+ * local variable holding the awaited activity result.
+ */
+export interface StepOutputRef {
+    readonly [STEP_OUTPUT_REF_BRAND]: true;
+    readonly kind: "step-output-ref";
+    /** `ActivityStep.id` of the producing step. */
+    readonly step: string;
+    /**
+     * Dot-path into the producer's declared return value (e.g.
+     * `"driftedStacks"`, `"result.healthy"`). Omitted references the whole
+     * return value.
+     */
+    readonly path?: string;
+}
+/**
+ * `T` with every own property additionally accepting a {@link StepOutputRef}
+ * in its place (chant #1288 Stage 2) — the authoring-time counterpart of
+ * `args` accepting a reference anywhere in the structure (#1290): a typed
+ * step-builder wrapper whose opts type is `WithStepRefs<SomeActivityArgs>`
+ * lets an author pass `diff.out.driftedStacks` for any field without an
+ * `as` cast, while runtime validation of the reference itself is still
+ * `validateStepOutputRefs`' job, not this type's.
+ */
+export type WithStepRefs<T> = {
+    [K in keyof T]: T[K] | StepOutputRef;
+};
+/** Structural guard for a value produced by {@link stepOutput} (or `activity()`'s `.out`). */
+export declare function isStepOutputRef(value: unknown): value is StepOutputRef;
+/**
+ * Reference a named step's output from a later step's `args`. Works with
+ * any step that has an `id` — an `activity()` builder result (which also
+ * gets the `.out` proxy sugar below) or a plain `{ kind: "activity", ...,
+ * id: "..." }` object literal, the shape composites author directly.
+ *
+ * `stepOutput(diff, "driftedStacks")` and `diff.out.driftedStacks` produce
+ * an identical reference; `stepOutput` is the explicit form for authors who
+ * build steps as object literals, or whose return schema has a top-level
+ * field literally named `step`, `path`, or `kind` (the `.out` proxy
+ * reserves those three property names for its own introspection).
+ */
+export declare function stepOutput(step: string | Pick<ActivityStep, "id">, path?: string): StepOutputRef;
+/**
+ * `.out` proxy attached to `activity()`'s result: `diff.out.driftedStacks`
+ * builds a {@link StepOutputRef} without the explicit `stepOutput()` call.
+ *
+ * A single property-access level, matching `outcomeAttribute.from`'s
+ * existing convention — the property name IS the dot-path, so a nested
+ * field is `diff.out["result.healthy"]`, not `diff.out.result.healthy`.
+ * `kind`, `step`, and `path` are reserved (the ref's own introspection
+ * fields); a return schema with a top-level field by one of those names
+ * needs `stepOutput(diff, "step")` instead.
+ */
+export declare function makeOutProxy(stepId: string): Record<string, StepOutputRef>;
+/** Every {@link StepOutputRef} found anywhere inside `value` (recursing through plain objects and arrays). */
+export declare function collectStepOutputRefs(value: unknown): StepOutputRef[];
+/**
+ * Validate every step-output reference in an Op against scope and ordering
+ * alone — no contract needed. This is the subset of {@link
+ * validateStepOutputRefs}'s checks that don't depend on a contract map, kept
+ * as its own export so a caller with no contracts on hand (or that wants to
+ * defend against exactly this class of bug regardless of what contracts are
+ * registered) can still refuse a scope-invalid reference. The temporal
+ * lexicon's serializer (`serializeOps`) is exactly this caller: TMP013 (which
+ * calls the fuller {@link validateStepOutputRefs}) protects `chant build`,
+ * but `serializeOps` is a public export a caller can invoke directly,
+ * bypassing that lint pass — this is its own defense-in-depth.
+ *
+ * Flags:
+ *  - a reference authored inside `onFailure`, or inside an `EffectStep`'s
+ *    nested steps — out of scope by design (see the module doc); flagged
+ *    explicitly here rather than left to fall through as "unknown producer",
+ *  - a reference to an unregistered step id (no step in scope declares it),
+ *  - a duplicate step id (ambiguous producer),
+ *  - a reference to a step that does not precede the referencing step
+ *    (a later phase, a later step in the same phase, itself, or a step in
+ *    the same parallel phase).
+ */
+export declare function validateStepOutputRefScope(config: Pick<OpConfig, "name" | "phases" | "onFailure">): ActivityContractIssue[];
+/**
+ * Validate every step-output reference in an Op's main phases against a
+ * contract map and the Op's own step ordering. Scope: `config.phases` only
+ * (never `onFailure`, never a step nested inside an `EffectStep` — see the
+ * module doc). Layers contract-based checks on top of {@link
+ * validateStepOutputRefScope}'s scope/ordering checks.
+ *
+ * Flags everything {@link validateStepOutputRefScope} does, plus:
+ *  - a reference into a step whose `fn` has no registered
+ *    {@link ActivityContract}, or whose contract declares no `returns`
+ *    schema — nothing to validate the reference against,
+ *  - a `path` that does not resolve on the producer's declared return
+ *    schema (an empty `path` — the whole return value — is always valid).
+ */
+export declare function validateStepOutputRefs(config: Pick<OpConfig, "name" | "phases" | "onFailure">, contracts: ReadonlyMap<string, ActivityContract>): ActivityContractIssue[];
+export {};
+//# sourceMappingURL=step-output-ref.d.ts.map

package/dist/op/step-output-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-output-ref.d.ts","sourceRoot":"","sources":["../../src/op/step-output-ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAmB,MAAM,SAAS,CAAC;AACvE,OAAO,EAAqD,KAAK,gBAAgB,EAAE,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE3I,QAAA,MAAM,qBAAqB,eAAuC,CAAC;AAEnE;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,CAAC,qBAAqB,CAAC,EAAE,IAAI,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,aAAa;CAAE,CAAC;AAEvE,8FAA8F;AAC9F,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEtE;AAqBD;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,aAAa,CAQhG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAU1E;AAED,8GAA8G;AAC9G,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,EAAE,CAKrE;AAmED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,WAAW,CAAC,GACtD,qBAAqB,EAAE,CAqEzB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,WAAW,CAAC,EACvD,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAC/C,qBAAqB,EAAE,CA4EzB"}

package/dist/op/types.d.ts

@@ -4,6 +4,7 @@
  * These types are intentionally free of Temporal SDK imports so they can live
  * in core without pulling in @temporalio/* as a dependency.
  */
+import type { EffectReceiptRef } from "./receipt-store.js";
 export interface OpConfig {
     /** Kebab-case identifier. Used as the workflow function name (camelCase) and output directory name. */
     name: string;
@@ -30,12 +31,29 @@ export interface PhaseDefinition {
     /** Run all steps concurrently via Promise.all. Default: false. */
     parallel?: boolean;
 }
-export type StepDefinition = ActivityStep | GateStep;
+export type StepDefinition = ActivityStep | GateStep | EffectStep;
 export interface ActivityStep {
     kind: "activity";
+    /**
+     * Identifies this step so a later step can reference its output (#1290)
+     * via `stepOutput(id, path?)` or, when built with `activity()`, the
+     * `.out` proxy sugar. Only steps in an Op's main `phases` — not
+     * `onFailure`, not one nested inside an `EffectStep` — can be referenced.
+     */
+    id?: string;
     /** Name of the exported activity function in the pre-built activity library. */
     fn: string;
-    /** Arguments passed to the activity function. */
+    /**
+     * Arguments passed to the activity function. A value may be a
+     * {@link StepOutputRef} (anywhere in the structure, including nested
+     * inside a plain object or array) — a reference to an earlier step's
+     * declared return value, resolved at build time and compiled by the
+     * serializer into a local variable holding that step's result. Never an
+     * expression over one: `diff.out.count > 0` or a template literal
+     * coerces the reference to a primitive, which throws (see
+     * `step-output-ref.ts`'s module doc for why this is a runtime-on-load
+     * guard, not a static lint rule).
+     */
     args?: Record<string, unknown>;
     /**
      * Key from TEMPORAL_ACTIVITY_PROFILES controlling timeout + retry.
@@ -59,6 +77,35 @@ export interface ActivityStep {
         from?: string;
     };
 }
+/**
+ * Read-compare-run-write over an effect receipt (#1834, epic #1703). The
+ * runtime reads the live receipt through the receipt store, compares it
+ * against the resolved expectation, skips the nested steps on a match, and
+ * otherwise runs them — writing the receipt only when every nested step
+ * succeeded, last. A nested-step failure leaves the receipt untouched
+ * (stale), so the next run re-proposes the effect.
+ *
+ * Authored via the `effect()` builder, which takes the typed EffectReceipt
+ * declaration only — there is no string form.
+ */
+export interface EffectStep {
+    kind: "effect";
+    /** Receipt identity + declaration data (references in placeholder form). */
+    receipt: EffectReceiptRef;
+    /**
+     * The expectation stamped at synthesis when the receipt is fully static;
+     * absent when reference inputs resolve at run (#1703 decision 5).
+     */
+    expectation?: string;
+    /**
+     * Steps run when the live receipt does not match, in authored order. A gate
+     * authored here pauses only when the effect will fire. Effect steps do not
+     * nest.
+     */
+    steps: Array<ActivityStep | GateStep>;
+    /** Annotation carried into the generated workflow as a comment. */
+    description?: string;
+}
 export interface GateStep {
     kind: "gate";
     /** Signal name. The generated workflow waits for this signal before continuing. */

package/dist/op/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/op/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,QAAQ;IACvB,uGAAuG;IACvG,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;IAC9B,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,QAAQ,CAAC;AAErD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,gFAAgF;IAChF,EAAE,EAAE,MAAM,CAAC;IACX,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B;;;OAGG;IACH,OAAO,CAAC,EAAE,gBAAgB,GAAG,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,aAAa,CAAC;IAChG;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACpD;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/op/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,MAAM,WAAW,QAAQ;IACvB,uGAAuG;IACvG,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;IAC9B,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,QAAQ,GAAG,UAAU,CAAC;AAElE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB;;;;;OAKG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,EAAE,EAAE,MAAM,CAAC;IACX;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B;;;OAGG;IACH,OAAO,CAAC,EAAE,gBAAgB,GAAG,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,aAAa,CAAC;IAChG;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACpD;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,QAAQ,CAAC;IACf,4EAA4E;IAC5E,OAAO,EAAE,gBAAgB,CAAC;IAC1B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,KAAK,EAAE,KAAK,CAAC,YAAY,GAAG,QAAQ,CAAC,CAAC;IACtC,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}