@intentius/chant 0.49.0 → 0.51.0

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

@@ -34,9 +34,26 @@ export interface PhaseDefinition {
 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.

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,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,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;;;;;;;;;;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"}
+{"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"}

package/dist/provenance.d.ts

@@ -5,9 +5,11 @@
  * entity object, so it never serializes into the emitted YAML/JSON — it is build
  * metadata, not declared configuration. Read it back with {@link getProvenance}.
  *
- * This is entity-level provenance (which file declared it, and which composite
- * expanded it), not a YAML-line source map. It answers "where did this resource
- * come from?", which is the question an agent asks before changing it.
+ * Entity-level provenance (which file declared it, and which composite expanded
+ * it) answers "where did this resource come from?", which is the question an
+ * agent asks before changing it. {@link PathOrigin} (chant #1443) answers the
+ * follow-up — "what set THIS field" — for the paths a build can attribute
+ * without guessing. Neither is a YAML-line source map.
  *
  * {@link BuildParamProvenance} (chant #1064) is the other half: not "where did
  * this ENTITY come from" but "what INPUTS was this whole BUILD invoked with" —
@@ -27,7 +29,55 @@ export interface EntityProvenance {
      * collapse a composite to a single node at coarse diagram detail levels (#494).
      */
     compositeInstance?: string;
+    /**
+     * Per-path origins within the entity's `props` (chant #1443). Read with
+     * {@link originOfPath}, which does the prefix resolution these keys are
+     * written for.
+     *
+     * Keys are dotted property paths only — `spec.template.spec.containers` —
+     * with `""` for the whole entity. They never carry an array segment, because
+     * a producing mechanism attributes a whole array at once: the coarsest path
+     * it actually determines is the honest one to record, and a positional key
+     * would go stale the moment an element moved.
+     *
+     * Query paths come from #1441's diff addressing and may carry `[#key]` for an
+     * element of an associative list or `[n]` for a positional one. Resolution is
+     * longest segment-boundary prefix, so `spec.containers[#app].image` finds a
+     * key recorded at `spec.containers`, and a key recorded at
+     * `spec.containers.image` never matches it. The two grammars agree without
+     * the recorder needing the lexicon's ordering hook, which it has no access to.
+     *
+     * Absent means this build could not record path origins, not that nothing
+     * governs the entity's fields — the run path executes modules and has no
+     * expression to inspect, and a sandboxed child's provenance does not survive
+     * the wire (`discovery/entity-wire-codec.ts` drops build metadata).
+     */
+    paths?: Record<string, PathOrigin>;
 }
+/**
+ * What produced one path inside an entity's props.
+ *
+ * - `authored` — written in the source file that declared the entity.
+ * - `composite` — the entity was expanded by a composite, or the path was
+ *   supplied by `propagate()`'s shared props at the instance.
+ * - `build-param` — the build parameters the authored expression for this path
+ *   *reads*, which is a syntactic dependency, not a value taint. For
+ *   `replicas: params.tier === "prod" ? 5 : 1` a taint says the value came from
+ *   the literal `5`, which is true and useless; the dependency says the field
+ *   is governed by `tier`, which is what an editor needs to know. Under-reports
+ *   (a shape the collector does not follow drops a dependency) and never
+ *   over-reports a parameter the expression does not mention.
+ */
+export type PathOrigin = {
+    kind: "authored";
+} | {
+    kind: "composite";
+    composite: string;
+    instance: string;
+} | {
+    kind: "build-param";
+    params: string[];
+};
 /**
  * Merge provenance onto an entity. Non-enumerable so it is invisible to
  * serializers and spreads. Existing fields win (`??=`), so the first/most
@@ -36,6 +86,26 @@ export interface EntityProvenance {
 export declare function setProvenance(entity: object, prov: EntityProvenance): void;
 /** Read an entity's build provenance, if any was stamped. */
 export declare function getProvenance(entity: object): EntityProvenance | undefined;
+/**
+ * Record one path's origin, first writer wins — the same rule
+ * {@link setProvenance} applies to entity-level fields, and for the same
+ * reason: expansion runs innermost-composite-first, so the earliest writer is
+ * the most specific one.
+ */
+export declare function setPathProvenance(entity: object, path: string, origin: PathOrigin): void;
+/**
+ * An entity's recorded path origins in sorted key order, or `undefined` when
+ * none were recorded. Sorted because a build's outputs are compared byte for
+ * byte and object key order is not something insertion should decide.
+ */
+export declare function getPathProvenance(entity: object): Record<string, PathOrigin> | undefined;
+/**
+ * The origin governing `path` — the longest recorded key that addresses it or
+ * one of its ancestors. See {@link PROVENANCE_PATH_GRAMMAR}.
+ */
+export declare function originOfPath(paths: Readonly<Record<string, PathOrigin>> | undefined, path: string): PathOrigin | undefined;
+/** One-line rendering of an origin, for diff output. */
+export declare function describePathOrigin(origin: PathOrigin): string;
 /**
  * One resolved build-time parameter (chant #1064, see ../build-params.ts): its
  * final value and which source won it, so a build's parameter inputs are

package/dist/provenance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAe1E;AAED,6DAA6D;AAC7D,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAE1E;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACjC,sCAAsC;IACtC,MAAM,EAAE,KAAK,GAAG,aAAa,GAAG,KAAK,GAAG,SAAS,CAAC;CACnD"}
+{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CACpC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAW9C;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAqB1E;AAED,6DAA6D;AAC7D,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAE1E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAExF;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,SAAS,CAQxF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,GAAG,SAAS,EACvD,IAAI,EAAE,MAAM,GACX,UAAU,GAAG,SAAS,CAQxB;AAED,wDAAwD;AACxD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAS7D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACjC,sCAAsC;IACtC,MAAM,EAAE,KAAK,GAAG,aAAa,GAAG,KAAK,GAAG,SAAS,CAAC;CACnD"}

package/dist/runtime-adapter.d.ts

@@ -19,9 +19,15 @@ export interface RuntimeAdapter {
     readonly hashAlgorithm: string;
     /** Test whether filePath matches a glob pattern */
     globMatch(pattern: string, filePath: string): boolean;
-    /** Spawn a child process and collect output */
+    /**
+     * Spawn a child process and collect output. When `opts.stdin` is set, it is
+     * written to the child's stdin and the stream is closed — the caller never
+     * needs to round-trip content through a shell (`sh -c "echo … | cmd"`) just
+     * to feed a command that reads from stdin (e.g. `git hash-object --stdin`).
+     */
     spawn(cmd: string[], opts?: {
         cwd?: string;
+        stdin?: string;
     }): Promise<SpawnResult>;
     /** Commands to use when spawning package manager / executor */
     readonly commands: RuntimeCommands;

package/dist/runtime-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-adapter.d.ts","sourceRoot":"","sources":["../src/runtime-adapter.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,gDAAgD;IAChD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,mDAAmD;IACnD,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACtD,+CAA+C;IAC/C,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACpE,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;CACpC;AAuCD;;GAEG;AACH,wBAAgB,WAAW,IAAI,cAAc,CAG5C;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,cAAc,CAK3C;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAEvD"}
+{"version":3,"file":"runtime-adapter.d.ts","sourceRoot":"","sources":["../src/runtime-adapter.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,gDAAgD;IAChD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,mDAAmD;IACnD,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACtD;;;;;OAKG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACpF,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;CACpC;AAuDD;;GAEG;AACH,wBAAgB,WAAW,IAAI,cAAc,CAG5C;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,cAAc,CAK3C;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAEvD"}

package/dist/serializer.d.ts

@@ -38,6 +38,24 @@ export interface SerializerResult {
     primary: string;
     /** Additional files keyed by filename (e.g. "network.template.json" → content) */
     files?: Record<string, string>;
+    /**
+     * Basenames from `files` that must reach disk byte-for-byte — never
+     * `JSON.parse`d, key-sorted, or reformatted to YAML by the build's
+     * additional-file writer (chant#1937).
+     *
+     * A separate field rather than a per-file flag on `files` (e.g. widening
+     * its value to `string | { content: string; verbatim: boolean }`) so every
+     * existing lexicon serializer that returns `files: Record<string, string>`
+     * keeps compiling and behaving unchanged: this list defaults to empty, and
+     * only a serializer that actually carries opaque/pre-formatted bytes
+     * (committed ciphertext, a vendored file) needs to populate it.
+     *
+     * Before this field existed, "JSON.parse fails on this content" was the
+     * only way to opt out of round-tripping — true for YAML that happens not to
+     * parse as JSON, but never a structural guarantee (YAML is a JSON
+     * superset).
+     */
+    verbatimFiles?: string[];
     /**
      * Non-fatal diagnostics produced during serialization (e.g. a dialect
      * dropping keys the target platform ignores). The build pipeline collects

package/dist/serializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAE5B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEjC;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;;;;;;;;;;OAaG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEtC;;;;;OAKG;IACH,SAAS,CACP,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EACjC,OAAO,CAAC,EAAE,aAAa,EAAE,EACzB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,gBAAgB,CAAC;IAE7B;;;;;OAKG;IACH,iBAAiB,CAAC,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC;CACpD"}
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAE5B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEjC;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;;;;;;;;;;OAaG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEtC;;;;;OAKG;IACH,SAAS,CACP,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EACjC,OAAO,CAAC,EAAE,aAAa,EAAE,EACzB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,gBAAgB,CAAC;IAE7B;;;;;OAKG;IACH,iBAAiB,CAAC,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC;CACpD"}

package/dist/testing.d.ts

@@ -15,6 +15,12 @@
  *   in-process for exactly this suite's environment. Stateless by design:
  *   a crashed suite's environment is recovered by calling destroy again (or
  *   `chant lifecycle teardown <env> --yes`).
+ * - **assertLive** (#1857) — `describeResources()` against exactly one
+ *   declared entity, turned into a pass or a thrown failure. Preserves
+ *   #1089's tri-state rather than collapsing it: NOT-OBSERVED throws {@link
+ *   UnobservedAssertionError}, never a silent pass and never an ordinary
+ *   failure, because chant could not read the entity is not the same claim
+ *   as chant read it and it is gone.
  *
  * ## Isolation
  *
@@ -39,12 +45,14 @@
  * exported, and a CI job pointing the identical suite at a real account just
  * leaves both unset.
  */
-import type { Declarable } from "./declarable.js";
+import { type Declarable } from "./declarable.js";
 import type { SerializerResult } from "./serializer.js";
 import { type BuildParamValue } from "./build-params.js";
-import type { LexiconPlugin } from "./lexicon.js";
+import type { LexiconPlugin, ResourceMetadata } from "./lexicon.js";
 import { type ActivityFn, type ActivityProfile } from "./op/activity-registry.js";
 import { type TeardownReport } from "./lifecycle/teardown.js";
+import { LiveAssertionError, UnobservedAssertionError, type AssertLiveOptions } from "./lifecycle/assert-live.js";
+export { LiveAssertionError, UnobservedAssertionError, type AssertLiveOptions };
 export interface DeployStackOptions {
     /** The chant project directory (where the infra source lives). */
     dir: string;
@@ -86,6 +94,19 @@ export interface DeployedStack {
     entities: Map<string, Declarable>;
     /** The environment this deploy targeted — the teardown key. */
     env: string;
+    /**
+     * Assert that a declared entity is live: observed present in this
+     * deploy's environment, not confirmed as another stack/env's resource,
+     * and — when `status` is given — reporting that status.
+     *
+     * Rides the observation contract (#1089): an entity `describeResources`
+     * could not cover throws {@link UnobservedAssertionError}, never a pass
+     * and never a plain failure — NOT-OBSERVED is not the same claim as
+     * absent. Observed-absent, a confirmed-foreign identity, or a status
+     * mismatch throws {@link LiveAssertionError}. Resolves to the entity's
+     * `ResourceMetadata` on success.
+     */
+    assertLive(name: string, options?: AssertLiveOptions): Promise<ResourceMetadata>;
     /**
      * Tear down everything carrying this suite's marker `{ stack, env }`.
      * Throws {@link TeardownIncompleteError} when any candidate failed to

package/dist/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMrD,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAI1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG/C,OAAO,EAAgC,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE7G,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAgB5E,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACzC;;;OAGG;IACH,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B,6EAA6E;IAC7E,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC3C;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAED,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAAC,CAAC;IAChD,8CAA8C;IAC9C,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClC,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;OAOG;IACH,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC,CAAC;CACpC;AAED;;;;;;GAMG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;aACpB,MAAM,EAAE,cAAc;gBAAtB,MAAM,EAAE,cAAc;CAkBnD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUjD;AA8BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAkHrF"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAMH,OAAO,EAAwB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMrD,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAI1E,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAGjE,OAAO,EAAgC,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE7G,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC5E,OAAO,EAEL,kBAAkB,EAClB,wBAAwB,EACxB,KAAK,iBAAiB,EACvB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,KAAK,iBAAiB,EAAE,CAAC;AAgBhF,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACzC;;;OAGG;IACH,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B,6EAA6E;IAC7E,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC3C;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAED,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAAC,CAAC;IAChD,8CAA8C;IAC9C,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClC,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACjF;;;;;;;OAOG;IACH,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC,CAAC;CACpC;AAED;;;;;;GAMG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;aACpB,MAAM,EAAE,cAAc;gBAAtB,MAAM,EAAE,cAAc;CAkBnD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUjD;AA8BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAmJrF"}