@intentius/chant 0.57.0 → 0.58.0

package/dist/op/types.d.ts

@@ -1,30 +1,62 @@
 /**
- * Op type definitions — the data model for a named, phased Temporal workflow.
+ * Op type definitions — the data model for a named, phased Op.
  *
- * These types are intentionally free of Temporal SDK imports so they can live
- * in core without pulling in @temporalio/* as a dependency.
+ * These types are intentionally free of any runtime SDK's imports, so they can
+ * live in core without core depending on a runtime.
  */
 import type { EffectReceiptRef } from "./receipt-store.js";
+import type { ActivityProfileName } from "./activity-profiles.js";
 export interface OpConfig {
-    /** Kebab-case identifier. Used as the workflow function name (camelCase) and output directory name. */
+    /** Kebab-case identifier. Names the Op's output directory (`dist/ops/<name>/`), and is the name `chant run <name>` and another Op's `depends` refer to. */
     name: string;
     /** Human-readable description shown in `chant run list` and deployment reports. */
     overview: string;
-    /** Temporal task queue. Defaults to `name`. */
-    taskQueue?: string;
-    /** Temporal namespace. Defaults to chant.config.ts defaultProfile's namespace. */
-    namespace?: string;
     /** Ordered list of execution phases. */
     phases: PhaseDefinition[];
     /** Other Op names that must be complete before this Op can run. */
     depends?: string[];
     /** Compensation phases executed on terminal failure (run in reverse order). */
     onFailure?: PhaseDefinition[];
-    /** Search attributes to upsert at workflow start. */
-    searchAttributes?: Record<string, string>;
+    /**
+     * Discovery keys for this Op — free-form `name: value` pairs a reader
+     * filters on. `ConvergeOp` sets `Converge: "true"` and `Env`, `WatchOp`
+     * sets `Watch`, and `discoverConvergeOps` (`./operator.ts`) reads both;
+     * `chant run list` prints whatever is here.
+     *
+     * These are the discovery half of what `searchAttributes` used to carry
+     * (#2118). The other half — a run's own outcome (`Phase`, `Drift`,
+     * `Approver`, `RollbackFailed`) — is not a property of the declaration at
+     * all and now lands on the run ledger as a fact
+     * (`../lifecycle/run-ledger.ts`), written per run rather than declared once.
+     */
+    labels?: Record<string, string>;
+    /**
+     * The cadence this Op runs on, when it has one (#2120). Runtime-neutral
+     * data, not a scheduler: the github/gitlab/forgejo lexicons render it as a
+     * CI cron ({@link ScheduledOpSpec}), `chant operator` reads it as this Op's
+     * tick cadence, a hosting lexicon hands it to its own scheduler, and the
+     * local one-shot executor ignores it.
+     */
+    schedule?: OpSchedule;
+}
+/**
+ * An Op's cadence (#2120). The cron is validated at `Op()` construction by
+ * the permissive 5-/6-field parser in `./cron.ts`, the same one a lexicon's
+ * own post-synth cron check imports.
+ */
+export interface OpSchedule {
+    /** 5- or 6-field cron expression, read in the running host's local time. */
+    cron: string;
+    /**
+     * What a fire does while the previous run is still going. `"skip"` is the
+     * only value — and the default — because that is what a level-triggered
+     * tick wants: the next fire re-observes everything anyway, so queueing a
+     * backlog buys nothing a single later tick does not.
+     */
+    overlap?: "skip";
 }
 export interface PhaseDefinition {
-    /** Display name shown in progress output and Temporal UI. */
+    /** Display name shown in progress output. */
     name: string;
     /** Ordered steps within the phase. */
     steps: StepDefinition[];
@@ -56,27 +88,47 @@ export interface ActivityStep {
      */
     args?: Record<string, unknown>;
     /**
-     * Key from TEMPORAL_ACTIVITY_PROFILES controlling timeout + retry.
+     * Key from {@link ACTIVITY_PROFILES} controlling timeout + retry.
      * Default: "fastIdempotent"
      */
-    profile?: "fastIdempotent" | "longInfra" | "k8sWait" | "humanGate" | "argoSync" | "policyCheck";
+    profile?: ActivityProfileName;
     /**
-     * Surface this activity's return value as a workflow search attribute.
+     * Surface this activity's return value as a named run outcome.
      *
-     * The serializer captures the awaited result into a temporary, then emits
-     * `upsertSearchAttributes({ <name>: [String(<from-path>)] })` immediately
-     * after. Useful for filtering runs by outcome (e.g. `Drift: "true"/"false"`
-     * from a lifecycleDiff activity).
+     * The local executor captures it into the step's record and folds it into
+     * the run ledger's `outcomes` (`../lifecycle/run-ledger.ts`); a hosting
+     * lexicon's serializer may additionally publish it to whatever index that
+     * runtime queries by. Useful for reading back a run by outcome (e.g. `Drift:
+     * "true"/"false"` from a lifecycleDiff activity).
+     *
+     * An array publishes several attributes off the same result in one upsert
+     * (#2105): one activity can answer more than one question about a run, and
+     * `choudoufuLivePlan`'s drift boolean plus its unowned and adoptable counts
+     * are three attributes over a single live read that nothing would be gained
+     * by splitting into three steps. A single object is the same thing with one
+     * entry, and stays the authored form everywhere one attribute is enough.
      *
      * `from` is a dot-path into the return value (e.g. `"drifted"` for
      * `{ drifted: boolean }`); when omitted, the whole return value is
-     * stringified.
+     * recorded.
      */
-    outcomeAttribute?: {
-        name: string;
-        from?: string;
-    };
+    outcomeAttribute?: OutcomeAttribute | OutcomeAttribute[];
 }
+/** One named run outcome published off a step's return value. */
+export interface OutcomeAttribute {
+    /** The outcome's name, as it appears in the run ledger's `outcomes`. */
+    name: string;
+    /** Dot-path into the activity's return value; the whole value when omitted. */
+    from?: string;
+}
+/**
+ * {@link ActivityStep.outcomeAttribute} as a list, whichever form it was
+ * authored in. `[]` when the step publishes none, so every consumer can
+ * iterate without first asking which of the two shapes it is holding.
+ */
+export declare function outcomeAttributesOf(step: {
+    outcomeAttribute?: OutcomeAttribute | OutcomeAttribute[];
+}): OutcomeAttribute[];
 /**
  * Read-compare-run-write over an effect receipt (#1834, epic #1703). The
  * runtime reads the live receipt through the receipt store, compares it
@@ -99,18 +151,18 @@ export interface EffectStep {
     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
+     * authored here is reached only when the effect will fire. Effect steps do not
      * nest.
      */
     steps: Array<ActivityStep | GateStep>;
-    /** Annotation carried into the generated workflow as a comment. */
+    /** Annotation carried into the Op's build output as a comment. */
     description?: string;
 }
 export interface GateStep {
     kind: "gate";
-    /** Signal name. The generated workflow waits for this signal before continuing. */
+    /** The gate's name — what `chant approve <op> <gate>` resolves. */
     signalName: string;
-    /** Temporal duration string. Default: "48h". */
+    /** How long a recorded pending gate stays valid, as a duration string. Default: "48h". */
     timeout?: string;
     /** Human-readable description of the action required to unblock this gate. */
     description?: string;

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;;;;;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"}
+{"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;AACxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D,MAAM,WAAW,QAAQ;IACvB,2JAA2J;IAC3J,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,QAAQ,EAAE,MAAM,CAAC;IACjB,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;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,UAAU,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,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,mBAAmB,CAAC;IAC9B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CAAC;CAC1D;AAED,iEAAiE;AACjE,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IAAE,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CAAA;CAAE,GAAG,gBAAgB,EAAE,CAI1H;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,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}

package/dist/ownership.d.ts

@@ -40,7 +40,7 @@ export interface ChannelKeys {
 /**
  * The label-based ownership convention (`app.kubernetes.io/managed-by` +
  * `chant.intentius.io/{stack,env}`) — the default, shared by every label-based
- * lexicon (k8s, gcp, helm, and the Temporal apply activity's `kubectl --prune`
+ * lexicon (k8s, gcp, helm, and the `k8sApply` activity's `kubectl --prune`
  * selector). AWS and Azure tag keys are defined in their own lexicons.
  */
 export declare const LABEL_OWNERSHIP_KEYS: ChannelKeys;

package/dist/provenance.d.ts

@@ -67,6 +67,20 @@ export interface EntityProvenance {
  *   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.
+ * - `composite-parameter` — the fold interpreted the composite's factory body,
+ *   and the expression for this path reads the named factory parameter paths
+ *   (chant #2161). Same syntactic-dependency discipline as `build-param`, and
+ *   for the same reason: a shape the collector does not follow drops a
+ *   parameter, it never invents one.
+ * - `composite-literal` — the fold interpreted the factory body and the
+ *   expression for this path reads no parameter at all. The composite fixes
+ *   this field, and no argument at the call site moves it.
+ *
+ * The coarse `composite` and the two fine kinds are not alternatives. A build
+ * records `composite` when it expanded a composite without interpreting its
+ * body (the run path, an inadmissible factory), and that is why
+ * ./fold-provenance.ts answers `unknown` there rather than falling through to a
+ * direct declaration.
  */
 export type PathOrigin = {
     kind: "authored";
@@ -77,6 +91,13 @@ export type PathOrigin = {
 } | {
     kind: "build-param";
     params: string[];
+} | {
+    kind: "composite-parameter";
+    composite: string;
+    parameters: string[];
+} | {
+    kind: "composite-literal";
+    composite: string;
 };
 /**
  * Merge provenance onto an entity. Non-enumerable so it is invisible to

package/dist/provenance.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;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,GACzC;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,GACxE;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAWrD;;;;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,CAa7D;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/serializer-walker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializer-walker.d.ts","sourceRoot":"","sources":["../src/serializer-walker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAM/C,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IACzD,mEAAmE;IACnE,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1C,+DAA+D;IAC/D,kBAAkB,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC;CAChF;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,OAAO,EACd,WAAW,EAAE,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,EACpC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAuET"}
+{"version":3,"file":"serializer-walker.d.ts","sourceRoot":"","sources":["../src/serializer-walker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAO/C,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IACzD,mEAAmE;IACnE,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1C,+DAA+D;IAC/D,kBAAkB,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC;CAChF;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,OAAO,EACd,WAAW,EAAE,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,EACpC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAyFT"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.57.0",
+  "version": "0.58.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -59,6 +59,11 @@
       "types": "./dist/op/index.d.ts",
       "default": "./src/op/index.ts"
     },
+    "./op/activities": {
+      "development": "./src/op/activities/index.ts",
+      "types": "./dist/op/activities/index.d.ts",
+      "default": "./src/op/activities/index.ts"
+    },
     "./components": {
       "development": "./src/components/index.ts",
       "types": "./dist/components/index.d.ts",

package/src/audit/catalog.test.ts

@@ -1,14 +1,14 @@
 import { describe, test, expect } from "vitest";
 import { readdirSync } from "fs";
 import { join } from "path";
-import { RULE_CATALOG, RULE_CATEGORY, auditRule, resolveAuditCatalog } from "./catalog";
+import { PRIOR_ART, RULE_CATALOG, RULE_CATEGORY, auditRule, resolveAuditCatalog, canonicalRuleId } from "./catalog";
 import { loadPlugins } from "../cli/plugins";
 
 /**
  * Every lexicon in the repo, enumerated rather than listed (#1346).
  *
  * This was nine hardcoded names. It missed fountain, which contributes a
- * catalog, and could not notice fly and temporal, which did not — so their six
+ * catalog, and could not notice fly, which did not — so their six
  * post-synth checks reached `chant audit` with no title, tier, fix kind, or
  * category, and the guard meant to catch exactly that was blind to them. A
  * thirteenth lexicon would have been invisible to it on arrival.
@@ -67,6 +67,11 @@ describe("RULE_CATALOG (aggregated: core static + lexicon-contributed, #687)", (
       .filter((id) => !shipped.has(id))
       // Core's own cross-cutting ids are not any one lexicon's to ship.
       .filter((id) => !(id in RULE_CATALOG))
+      // A deprecated rule is deliberately kept in the catalog after its check
+      // stops shipping (chant #2113). That's the whole point of `deprecated`
+      // over deleting the entry, so it's not "stale" the way an orphaned
+      // entry with no explanation is.
+      .filter((id) => !catalog[id]?.deprecated)
       .sort();
     expect(stale).toEqual([]);
   });
@@ -123,6 +128,33 @@ describe("RULE_CATALOG (aggregated: core static + lexicon-contributed, #687)", (
     }
   });
 
+  test("lineage entries key into PRIOR_ART, link over https, and use a known relation", async () => {
+    const relations = new Set(["equivalent", "overlaps", "extends"]);
+    for (const [id, m] of Object.entries(await aggregate())) {
+      for (const l of m.lineage ?? []) {
+        expect(l.tool in PRIOR_ART, `${id} credits unregistered tool "${l.tool}"`).toBe(true);
+        expect(l.url.startsWith("https://"), `${id} lineage url ${l.url}`).toBe(true);
+        expect(relations.has(l.relation), `${id} lineage relation ${l.relation}`).toBe(true);
+      }
+    }
+  });
+
+  test("lineage is credit, not authority: it never forces a category or tier", () => {
+    const m = auditRule("ZZZ001", "report-only", "guidance", "t", "r", {
+      lineage: [{ tool: Object.keys(PRIOR_ART)[0] as never, url: "https://example.invalid/x", relation: "overlaps" }],
+    });
+    expect(m.category).toBe("best-practice");
+    expect(m.tier).toBe("report-only");
+    expect(m.lineage?.length).toBe(1);
+  });
+
+  test("every registered prior-art tool is credited by at least one rule", async () => {
+    const used = new Set<string>();
+    for (const m of Object.values(await aggregate())) for (const l of m.lineage ?? []) used.add(l.tool);
+    const idle = Object.keys(PRIOR_ART).filter((k) => !used.has(k)).sort();
+    expect(idle, "PRIOR_ART entries no rule credits").toEqual([]);
+  });
+
   test("flagship security rules carry an authority citation", async () => {
     const catalog = await aggregate();
     const flagship = ["GHA017", "GHA021", "GHA029", "GHA033", "GHA034", "GHA036", "GHA037", "WGL016", "WGL029"];
@@ -134,13 +166,34 @@ describe("RULE_CATALOG (aggregated: core static + lexicon-contributed, #687)", (
     }
   });
 
+  test("a deprecated id must still resolve (chant #2113): the inverse of the every-check-has-metadata test above", async () => {
+    // A retired check ships no runtime PostSynthCheck any more, so it is
+    // absent from `realCheckIds()`/`shippedRuleIds()` — that's what makes it
+    // "deprecated" rather than merely renamed. The catalog entry, and its
+    // resolution, must survive that removal.
+    const catalog = {
+      ...RULE_CATALOG,
+      ZZZ900: auditRule("ZZZ900", "report-only", "guidance", "Retired check", "No longer applicable.", {
+        category: "best-practice",
+      }),
+    };
+    catalog.ZZZ900.deprecated = "superseded by ZZZ901";
+    expect(catalog.ZZZ900).toBeDefined();
+    expect(catalog.ZZZ900.deprecated).toBe("superseded by ZZZ901");
+    expect(canonicalRuleId("ZZZ900", catalog)).toBe("ZZZ900");
+  });
+
   test("deterministic fixes are limited to the safe mechanical set", async () => {
     const deterministic = Object.values(await aggregate())
       .filter((m) => m.fixKind === "deterministic")
       .map((m) => m.id)
       .sort();
+    // TF016 and TF019 (#2110) are the first report-only rules in the set: both
+    // unquote or delete exactly the flagged line, which is as mechanical as
+    // pinning an action, and `report-model.ts` renders them as quick wins for
+    // that reason. Every entry here needs a case in `proof.ts`'s `proveFix`.
     expect(deterministic).toEqual(
-      ["GHA017", "GHA021", "GHA029", "GHA030", "GHA033", "WGL031"].sort(),
+      ["GHA017", "GHA021", "GHA029", "GHA030", "GHA033", "TF016", "TF019", "WGL031"].sort(),
     );
   });
 });
@@ -164,6 +217,29 @@ describe("auditRule (lexicon-facing catalog constructor, #687)", () => {
   });
 });
 
+describe("canonicalRuleId (chant #2113, alias resolution)", () => {
+  const catalog: Record<string, ReturnType<typeof auditRule>> = {
+    NEW001: { ...auditRule("NEW001", "report-only", "guidance", "T", "r"), aliases: ["OLD001", "LEGACY_OLD"] },
+  };
+
+  test("a canonical id passes through unchanged", () => {
+    expect(canonicalRuleId("NEW001", catalog)).toBe("NEW001");
+  });
+
+  test("an alias resolves to the canonical id", () => {
+    expect(canonicalRuleId("OLD001", catalog)).toBe("NEW001");
+    expect(canonicalRuleId("LEGACY_OLD", catalog)).toBe("NEW001");
+  });
+
+  test("an id that is neither a key nor an alias passes through unchanged", () => {
+    expect(canonicalRuleId("NOBODY_KNOWS_THIS", catalog)).toBe("NOBODY_KNOWS_THIS");
+  });
+
+  test("defaults to the static core RULE_CATALOG when no catalog is given", () => {
+    expect(canonicalRuleId("SEC001")).toBe("SEC001");
+  });
+});
+
 describe("resolveAuditCatalog (#687 aggregation seam)", () => {
   test("with no lexicons, returns a copy of the static core catalog", async () => {
     const resolved = await resolveAuditCatalog([]);

package/src/audit/catalog.ts

@@ -17,6 +17,11 @@
  * test asserts the aggregate stays in sync with the lexicons' post-synth checks.
  */
 
+import type { Lineage } from "./prior-art";
+import { applyLineage as attachLineage } from "./prior-art";
+import { coreAuditLineage } from "./lineage";
+export { PRIOR_ART, applyLineage, lineageLabel, type Lineage, type LineageRelation, type PriorArtEntry, type PriorArtTool } from "./prior-art";
+
 export type Tier = "merge-worthy" | "report-only";
 
 /** deterministic = safe auto-fix/diff; guidance = report text only (needs judgment). */
@@ -48,14 +53,42 @@ export interface RuleMeta {
   title: string;
   /** External backing so a finding isn't just chant's opinion. */
   authority?: Authority[];
+  /**
+   * Prior art: the open-source tools whose rules check the same condition
+   * (./prior-art.ts). Credit, not authority — never affects tier or category.
+   */
+  lineage?: Lineage[];
   /** One-line fix guidance (always present). */
   remediation: string;
   /**
    * False if the check reads the chant model (`ctx.entities`) rather than the
    * emitted YAML (`ctx.outputs`) — such a check won't fire on audited YAML.
-   * All current post-synth checks are output-based, so this is true.
+   * Most post-synth checks are output-based, but cpln, fly, fountain, k3s
+   * and render all ship model-based checks with this false.
    */
   yamlBased: boolean;
+  /**
+   * Retired ids this rule used to ship under (chant #2113). A rule id is
+   * public the day it ships. trivy's checks carry `id`, `long_id` and
+   * `aliases` for exactly this reason, so a rename or a scheme migration
+   * doesn't strand every existing reference to the old id. An alias resolves
+   * to this entry wherever a rule id is looked up by a human or a config.
+   * `canonicalRuleId()` (below) is the shared resolver; a `lint.rules` key
+   * and #2111's HCL suppression both go through it (or will, since #2111
+   * lands separately and is not touched by this change).
+   */
+  aliases?: string[];
+  /**
+   * Set when this rule is retired: `true`, or a string explaining what
+   * replaced it / why it no longer fires. A deprecated rule stays in the
+   * catalog rather than being deleted. trivy's `deprecated: true` field lets
+   * a ruleset retire a check without breaking every existing suppression or
+   * dashboard that still names it, so its id keeps resolving (via `aliases`
+   * on whichever rule superseded it, when there is one) and the rules page
+   * still lists it, greyed out, instead of the id going dark with no
+   * explanation.
+   */
+  deprecated?: boolean | string;
 }
 
 // ── Authority references ─────────────────────────────────────────────
@@ -147,6 +180,10 @@ export const CWE_HARDCODED_CREDS: Authority = {
   name: "CWE-798 — Use of Hard-coded Credentials",
   url: "https://cwe.mitre.org/data/definitions/798.html",
 };
+export const HASHICORP_STYLE_GITIGNORE: Authority = {
+  name: "HashiCorp Terraform style guide — .gitignore",
+  url: "https://developer.hashicorp.com/terraform/language/style#gitignore",
+};
 export const CWE_CLEARTEXT: Authority = {
   name: "CWE-319 — Cleartext Transmission of Sensitive Information",
   url: "https://cwe.mitre.org/data/definitions/319.html",
@@ -159,13 +196,14 @@ function meta(
   title: string,
   remediation: string,
   authority?: Authority[],
+  lineage?: Lineage[],
 ): RuleMeta {
   // An authority citation is the strongest security signal, so it wins. Otherwise
   // the curated RULE_CATEGORY map (defined below, before RULE_CATALOG runs)
   // decides correctness vs best-practice vs security-without-authority; the drift
   // test guarantees every id is mapped, so the fallback is only a type belt.
   const category: Category = authority && authority.length > 0 ? "security" : RULE_CATEGORY[id] ?? "best-practice";
-  return { id, tier, fixKind, category, title, remediation, authority, yamlBased: true };
+  return { id, tier, fixKind, category, title, remediation, authority, ...(lineage?.length ? { lineage } : {}), yamlBased: true };
 }
 
 const M = "merge-worthy" as const;
@@ -221,6 +259,10 @@ export const RULE_CATEGORY: Record<string, Category> = {
   NGX005: "security",
   NGX006: "best-practice",
   NGX007: "best-practice",
+  // TF023 — Terraform state committed to the repository. Core-owned for the
+  // same reason SEC/WRG/NGX are: it reads the discovered file list, not a
+  // parsed root module. See ./terraform-state.ts.
+  TF023: "security",
   // AGT — agent configuration (`chant audit --agents`). Core-owned like COR/EXT:
   // these run against the machine's own agent config, not against any one
   // lexicon's emitted output, so no lexicon ships them.
@@ -282,6 +324,21 @@ export const RULE_CATALOG: Record<string, RuleMeta> = {
   NGX006: meta("NGX006", R, G, "Server version disclosure", "Add `server_tokens off;` in the http block so nginx stops advertising its exact version in the Server header and error pages."),
   NGX007: meta("NGX007", R, G, "Access logging disabled at server scope", "Re-enable access_log at http/server scope (silencing a single noisy location is fine) so requests are recorded for incident investigation."),
 
+  // TF023 (#2110) — Terraform state, or the `.terraform/` working directory,
+  // committed to the repository. The one TF rule core owns: every other TF id
+  // is a post-synth check over a parsed root module (the terraform lexicon's
+  // `auditCatalog()`), while this one reads the discovered file list and never
+  // runs during `chant build`. Same shape as SEC/WRG/NGX above, and the same
+  // reason it lives here: `terraform-state.ts` needs no lexicon installed.
+  TF023: meta(
+    "TF023",
+    M,
+    G,
+    "Terraform state committed to the repository",
+    "Delete the state file (or `.terraform/`) from version control, add it to .gitignore, move the state to a remote backend, and rotate every credential the file held.",
+    [HASHICORP_STYLE_GITIGNORE],
+  ),
+
   // ── Agent configuration (`chant audit --agents`) ──────────────────
   AGT001: agentMeta(
     "AGT001",
@@ -337,6 +394,9 @@ export const RULE_CATALOG: Record<string, RuleMeta> = {
   ),
 };
 
+// Prior art credits for the core static rules (SEC/WRG/NGX/AGT/EXT) — ./lineage.ts.
+attachLineage(RULE_CATALOG, coreAuditLineage);
+
 /**
  * Build one catalog entry — the lexicon-facing constructor for
  * `LexiconPlugin.auditCatalog()` (#687), so a lexicon can declare its own rules'
@@ -351,10 +411,20 @@ export function auditRule(
   fixKind: FixKind,
   title: string,
   remediation: string,
-  opts?: { authority?: Authority[]; category?: Category },
+  opts?: { authority?: Authority[]; category?: Category; lineage?: Lineage[] },
 ): RuleMeta {
   const category: Category = opts?.authority && opts.authority.length > 0 ? "security" : (opts?.category ?? "best-practice");
-  return { id, tier, fixKind, category, title, remediation, authority: opts?.authority, yamlBased: true };
+  return {
+    id,
+    tier,
+    fixKind,
+    category,
+    title,
+    remediation,
+    authority: opts?.authority,
+    ...(opts?.lineage?.length ? { lineage: opts.lineage } : {}),
+    yamlBased: true,
+  };
 }
 
 /**
@@ -374,15 +444,18 @@ export async function resolveAuditCatalog(lexicons: string[]): Promise<Record<st
     lexicons.includes("forgejo") && !lexicons.includes("github") ? [...lexicons, "github"] : lexicons;
   if (needed.length === 0) return catalog;
   // Lazy import so importing this module doesn't pull in the plugin/config graph
-  // (matches ./core.ts's `load` — see #408).
-  const { loadPlugins } = await import("../cli/plugins");
-  let plugins: Array<{ auditCatalog?(): Record<string, RuleMeta> }>;
-  try {
-    plugins = await loadPlugins(needed);
-  } catch {
-    return catalog; // a lexicon package isn't installed — fall back to the static core catalog.
-  }
-  for (const plugin of plugins) {
+  // (matches ./core.ts's `load` — see #408). Loaded one at a time (rather than
+  // the bulk `loadPlugins`, which aborts on the first failure) so one
+  // not-yet-installed lexicon (e.g. terraform, #2085) doesn't drop every other
+  // lexicon's contributed catalog back to the static core map.
+  const { loadPlugin } = await import("../cli/plugins");
+  for (const name of needed) {
+    let plugin: { auditCatalog?(): Record<string, RuleMeta> };
+    try {
+      plugin = await loadPlugin(name);
+    } catch {
+      continue; // a lexicon package isn't installed, its catalog just doesn't contribute.
+    }
     const contributed = plugin?.auditCatalog?.();
     if (contributed) Object.assign(catalog, contributed);
   }
@@ -394,6 +467,31 @@ export function ruleMeta(id: string): RuleMeta | undefined {
   return RULE_CATALOG[id];
 }
 
+/**
+ * Resolve a rule id to its canonical form against `catalog` (chant #2113). An
+ * id that is itself a key of `catalog` passes through unchanged (this covers
+ * the common case without scanning every entry's `aliases`); otherwise every
+ * entry's `aliases` is searched for a match, and the id it belongs to is
+ * returned. An id neither a key nor anyone's alias passes through unchanged
+ * too, since this is a best-effort resolver, not a validator, so an unknown
+ * id is a caller's problem, not this function's.
+ *
+ * Exported so a `lint.rules`/preset key that names an alias resolves to the
+ * rule that actually runs (see `resolveConfiguredSeverity`,
+ * `../lint/config.ts`), and so #2111's HCL suppression code can key an
+ * inline `# chant-ignore <id>` off the same resolution once it lands — that
+ * suppression mechanism does not exist yet in this worktree (#2111 is a
+ * separate, parallel issue), so this function is exported now for it to call
+ * later rather than being wired into it here.
+ */
+export function canonicalRuleId(id: string, catalog: Record<string, RuleMeta> = RULE_CATALOG): string {
+  if (id in catalog) return id;
+  for (const [canonicalId, meta] of Object.entries(catalog)) {
+    if (meta.aliases?.includes(id)) return canonicalId;
+  }
+  return id;
+}
+
 /** Docs path for the audit rules reference (one anchor per rule id). */
 export const RULES_DOC_PATH = "/chant/lint-rules/audit-rules/";
 

package/src/audit/core.test.ts

@@ -208,6 +208,32 @@ describe("auditFiles", () => {
     expect(findings.map((f) => `${f.file}:${f.entity}`).sort()).toEqual(["a.yaml:one", "b.yaml:two"]);
   });
 
+  test("parse-to-graph with an async entities parser: auditFiles awaits it into ctx.entities (#2082)", async () => {
+    const entityCheck: PostSynthCheck = {
+      id: "ENT003",
+      description: "reads ctx.entities, not ctx.outputs",
+      check: (ctx) =>
+        [...ctx.entities.keys()].map((name) => ({ checkId: "ENT003", severity: "warning" as const, message: `saw ${name}`, entity: name })),
+    };
+    const findings = await auditFiles(
+      [
+        { path: "a.tf", content: "one", lexicon: "terraform" },
+        { path: "b.tf", content: "two", lexicon: "terraform" },
+      ],
+      {
+        checksProvider: async () => [entityCheck],
+        // The lexicon's parser is inherently async (a lazy-loaded wasm HCL
+        // parser, per #1567's terraform follow-up). The returned Promise
+        // must be awaited before the check sees ctx.entities.
+        entitiesProvider: async () => async (content) => {
+          await Promise.resolve();
+          return new Map([[content, { entityType: "T::X" } as never]]);
+        },
+      },
+    );
+    expect(findings.map((f) => `${f.file}:${f.entity}`).sort()).toEqual(["a.tf:one", "b.tf:two"]);
+  });
+
   test("parse-to-graph merge: the same entity name in two files keeps both — a duplicate check sees the collision cross-file", async () => {
     const dupCheck: PostSynthCheck = {
       id: "DUP001",