@intentius/chant 0.49.0 → 0.50.0

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

@@ -1,9 +1,44 @@
 /**
- * TOML emitter and parser — re-exports from split modules.
+ * Lightweight TOML parser (#446).
  *
- * Import from here for the public API:
- *   import { emitTOML, parseTOML } from "@intentius/chant/toml";
+ * Written for the audit engine's spike: is there a pure, dependency-free way
+ * to parse a config format the engine can't read today? TOML fits — it is a
+ * fully-specified, static (no macros/interpolation/imports) grammar, so a
+ * hand-rolled tokenizer + recursive-descent parser covers it without any
+ * runtime surface a Workers sandbox would reject (no `eval`, no native
+ * modules, no filesystem/network).
+ *
+ * Covers the subset of TOML v1.0 that real-world deploy configs
+ * (`wrangler.toml`, `Cargo.toml`, `pyproject.toml`, `netlify.toml`) actually
+ * use: basic/literal strings (single-line), integers, floats, booleans,
+ * arrays (including multi-line), inline tables, dotted keys, standard tables
+ * (`[a.b]`), and arrays of tables (`[[a.b]]`).
+ *
+ * Deliberately NOT a full spec implementation:
+ *  - Multi-line strings (`"""..."""`, `'''...'''`) are read as a single
+ *    opaque string body (no line-ending backslash trimming); good enough to
+ *    not crash, not spec-perfect for continuation whitespace.
+ *  - Dates/times are returned as their raw source text (a string), not a
+ *    `Date` — none of the checks built on this parser need calendar math.
+ *  - A dotted-key path element must be a bare word or a plain quoted string;
+ *    mixing exotic key shapes mid-path is not supported.
+ * These gaps only matter for exotic TOML; they don't affect the shapes the
+ * audit checks read (`[vars]`, `[[kv_namespaces]]`, `[env.NAME]`, …).
+ */
+export declare class TomlParseError extends Error {
+}
+type TomlValue = string | number | boolean | TomlValue[] | {
+    [k: string]: TomlValue;
+};
+type TomlTable = {
+    [k: string]: TomlValue;
+};
+/**
+ * Parse a TOML document into a plain nested object. Throws {@link TomlParseError}
+ * on malformed input — callers that scan arbitrary repo files should wrap the
+ * call in a try/catch (matching the rest of the audit engine's tolerance for
+ * unparseable content).
  */
-export { emitTOML, type EmitTOMLOptions } from "./toml-emit.js";
-export { parseTOML } from "./toml-parse.js";
+export declare function parseTOML(input: string): TomlTable;
+export {};
 //# sourceMappingURL=toml.d.ts.map

package/dist/toml.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toml.d.ts","sourceRoot":"","sources":["../src/toml.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"toml.d.ts","sourceRoot":"","sources":["../src/toml.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,qBAAa,cAAe,SAAQ,KAAK;CAAG;AAqK5C,KAAK,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,EAAE,GAAG;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AACtF,KAAK,SAAS,GAAG;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAgJ5C;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CA8BlD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.49.0",
+  "version": "0.50.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/audit/catalog.test.ts

@@ -91,7 +91,7 @@ describe("RULE_CATALOG (aggregated: core static + lexicon-contributed, #687)", (
       expect(m.remediation.length, `${id} has remediation`).toBeGreaterThan(0);
       expect(["merge-worthy", "report-only"]).toContain(m.tier);
       expect(["deterministic", "guidance"]).toContain(m.fixKind);
-      expect(["security", "correctness", "best-practice"], `${id} has a valid category`).toContain(m.category);
+      expect(["security", "correctness", "best-practice", "efficiency"], `${id} has a valid category`).toContain(m.category);
     }
   });
 

package/src/audit/catalog.ts

@@ -26,10 +26,13 @@ export type FixKind = "deterministic" | "guidance";
  * What kind of finding this is — orthogonal to `tier` (fix confidence). Lets the
  * report say "N security, M best-practice, K correctness" instead of branding
  * everything "security." `security` = exposure/vuln/supply-chain; `correctness`
- * = a structural bug (broken reference, invalid schema, never-runs); everything
- * else is `best-practice` (hygiene/style/deprecation/reliability).
+ * = a structural bug (broken reference, invalid schema, never-runs); `efficiency`
+ * (#444) = waste — redundant work, an oversized execution environment,
+ * unintended fan-out, unbounded retention — never a safety/correctness issue,
+ * so it is excluded from the security and correctness tallies; everything else
+ * is `best-practice` (hygiene/style/deprecation/reliability).
  */
-export type Category = "security" | "correctness" | "best-practice";
+export type Category = "security" | "correctness" | "best-practice" | "efficiency";
 
 export interface Authority {
   name: string;
@@ -96,6 +99,34 @@ export const K8S_SECRETS: Authority = {
   name: "Kubernetes — Good practices for Secrets",
   url: "https://kubernetes.io/docs/concepts/security/secrets-good-practices/",
 };
+export const GH_SECRET_SCANNING: Authority = {
+  name: "GitHub — About secret scanning",
+  url: "https://docs.github.com/en/code-security/secret-scanning/introduction/about-secret-scanning",
+};
+export const SCORECARD_VULN: Authority = {
+  name: "OSSF Scorecard — Vulnerabilities",
+  url: "https://github.com/ossf/scorecard/blob/main/docs/checks.md#vulnerabilities",
+};
+export const CF_WORKERS_DEV: Authority = {
+  name: "Cloudflare Workers — workers.dev",
+  url: "https://developers.cloudflare.com/workers/configuration/routing/workers-dev/",
+};
+export const CF_SECRETS: Authority = {
+  name: "Cloudflare Workers — Secrets",
+  url: "https://developers.cloudflare.com/workers/configuration/secrets/",
+};
+export const CF_ROUTES: Authority = {
+  name: "Cloudflare Workers — Routes",
+  url: "https://developers.cloudflare.com/workers/configuration/routing/routes/",
+};
+export const CF_ENVIRONMENTS: Authority = {
+  name: "Cloudflare Workers — Wrangler environments",
+  url: "https://developers.cloudflare.com/workers/wrangler/configuration/#environments",
+};
+export const CF_STATIC_ASSETS: Authority = {
+  name: "Cloudflare Workers — Static assets",
+  url: "https://developers.cloudflare.com/workers/static-assets/",
+};
 
 function meta(
   id: string,
@@ -127,6 +158,22 @@ const G = "guidance" as const;
 export const RULE_CATEGORY: Record<string, Category> = {
   COR020: "correctness",
   EXT001: "correctness",
+  SEC001: "security",
+  SEC002: "security",
+  SEC003: "security",
+  SEC004: "security",
+  SEC005: "security",
+  SEC006: "security",
+  SEC007: "security",
+  SEC008: "security",
+  SEC009: "security",
+  SEC010: "security",
+  WRG001: "security",
+  WRG002: "security",
+  WRG003: "best-practice",
+  WRG004: "security",
+  WRG005: "security",
+  WRG006: "security",
 };
 
 /**
@@ -139,6 +186,31 @@ export const RULE_CATEGORY: Record<string, Category> = {
 export const RULE_CATALOG: Record<string, RuleMeta> = {
   COR020: meta("COR020", M, G, "Circular resource dependency", "Break the dependency cycle between resources."),
   EXT001: meta("EXT001", M, G, "Extension constraint violation", "Fix the cross-property constraint flagged by the cfn-lint extension schema."),
+
+  // Secrets & credentials (#443) — lexicon-independent: `secrets.ts` scans the
+  // raw text of every candidate file, so these ids apply regardless of which
+  // (if any) audit lexicons are installed. `fixKind` is `guidance`: removing
+  // a hardcoded credential and rotating it needs a human, never an auto-fix.
+  SEC001: meta("SEC001", M, G, "AWS access key ID found", "Remove the key from source, rotate it in IAM, and load it from a secret store or environment variable instead.", [GH_SECRET_SCANNING]),
+  SEC002: meta("SEC002", M, G, "AWS secret access key found", "Remove the key from source, rotate it in IAM, and load it from a secret store or environment variable instead.", [GH_SECRET_SCANNING]),
+  SEC003: meta("SEC003", M, G, "GitHub token found", "Remove the token from source and revoke it at github.com/settings/tokens; use a GitHub Actions secret instead.", [GH_SECRET_SCANNING]),
+  SEC004: meta("SEC004", M, G, "Slack token found", "Remove the token from source and revoke it in the Slack app's OAuth settings.", [GH_SECRET_SCANNING]),
+  SEC005: meta("SEC005", M, G, "Google API key found", "Remove the key from source and regenerate it in the Google Cloud Console credentials page.", [GH_SECRET_SCANNING]),
+  SEC006: meta("SEC006", M, G, "Stripe live secret key found", "Remove the key from source and roll it in the Stripe dashboard immediately — this is a live-mode key.", [GH_SECRET_SCANNING]),
+  SEC007: meta("SEC007", M, G, "Private key block found", "Remove the private key from source, rotate the keypair, and load the key from a secret store instead.", [GH_SECRET_SCANNING]),
+  SEC008: meta("SEC008", M, G, "Bearer/authorization token found", "Remove the token from source; if it's long-lived, revoke and reissue it via the issuing service.", [GH_SECRET_SCANNING]),
+  SEC009: meta("SEC009", M, G, "Credentials embedded in a connection string", "Move the username/password out of the URI into a secret store, and rotate the credential.", [GH_SECRET_SCANNING]),
+  SEC010: meta("SEC010", M, G, "High-entropy string — possible secret", "Confirm whether this is a live credential; if so, remove it from source and rotate it. If it's a false positive, suppress with a `chant-audit-ignore` comment or an allowlist entry.", [GH_SECRET_SCANNING]),
+
+  // Wrangler config audit (#446) — lexicon-independent, same shape as the SEC
+  // family above: `wrangler.ts` scans every `wrangler.toml` it finds
+  // regardless of which (if any) audit lexicons are installed.
+  WRG001: meta("WRG001", M, G, "Production environment exposed on *.workers.dev", "Remove workers_dev (or set it to false) for this environment and rely on its custom domain/route instead of the shared public subdomain.", [CF_WORKERS_DEV]),
+  WRG002: meta("WRG002", M, G, "Credential-shaped key stored in [vars]", "Move the value out of [vars] and into `wrangler secret put <name>` so it isn't committed to source or visible in `wrangler dev`/the dashboard.", [CF_SECRETS]),
+  WRG003: meta("WRG003", R, G, "Observability explicitly disabled", "Set observability.enabled = true (or remove the override) so Workers Logs are recorded for this deployment."),
+  WRG004: meta("WRG004", M, G, "Unscoped wildcard route", "Scope the route pattern to the intended zone (e.g. \"example.com/*\") instead of a bare \"*\" or \"*/*\" that matches every zone on the account.", [CF_ROUTES]),
+  WRG005: meta("WRG005", M, G, "Non-production environment shares a data store with production", "Give the non-production environment its own KV namespace/R2 bucket/D1 database id instead of reusing production's.", [CF_ENVIRONMENTS]),
+  WRG006: meta("WRG006", M, G, "Static assets served from the project root", "Point [site].bucket / [assets].directory at a dedicated public output folder, not the project root, so non-public files (config, source maps, .git) aren't served.", [CF_STATIC_ASSETS]),
 };
 
 /**

package/src/audit/core.ts

@@ -73,6 +73,15 @@ export interface AuditFinding {
   lexicon: string;
   /** Optional entity (e.g. job name) the check attached. */
   entity?: string;
+  /** 1-based line number within `file`, when the check can pin one (e.g. secrets detection, #443). */
+  line?: number;
+  /**
+   * A redaction-safe fingerprint of the flagged value (see
+   * `secrets.ts`'s `fingerprintSecret`), so a finding can be referenced —
+   * for an allowlist entry, for dedup — without ever carrying the value
+   * itself.
+   */
+  fingerprint?: string;
 }
 
 /**