@intentius/chant 0.49.0 → 0.50.0

package/dist/lifecycle/scenario.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Plan scenarios (chant #1292): a declared expectation about what a change
+ * SHOULD do, checkable offline against a fixture snapshot.
+ *
+ * Everything else chant validates is about shape — is this declaration
+ * well-formed, does this reference resolve. Nothing answers "what will this
+ * change do" as something source can assert about itself, until now. A
+ * `Scenario` pairs a `given` (a stand-in for live observation) with an
+ * `expect` (a claim about the resulting change set) — `chant scenario check`
+ * (../cli/handlers/scenario.ts) builds the project, replays `given` in place
+ * of a live read, and evaluates `expect` against the resulting `ChangeSet`
+ * (./change-set.ts) via `evaluateScenario` (./scenario-eval.ts).
+ *
+ * Modeled precisely on the other non-resource Declarables (../effect-receipt.ts,
+ * ../secret-provenance.ts): discovery collects a `Scenario` like any entity
+ * (it is a Declarable), but it carries no resource payload and no serializer
+ * ever emits it — `partitionByLexicon` (../build.ts) excludes it from every
+ * lexicon's partition, the same way it excludes a secret declaration.
+ *
+ * This module is pure and does no I/O: `snapshot()` records where the fixture
+ * comes from without reading it, and the factory validates and freezes. The
+ * CLI handler is where the fixture is actually read, replayed, and compared —
+ * the same synthesis/plan split every other lifecycle primitive here follows.
+ */
+import { type Declarable } from "../declarable.js";
+import type { Ownership } from "./change-set.js";
+/** Marker symbol identifying a scenario declaration. `Symbol.for` so it
+ * survives the entity-wire codec, the same reason ../effect-receipt.ts and
+ * ../secret-provenance.ts use `Symbol.for` for their markers. */
+export declare const SCENARIO_MARKER: unique symbol;
+/** The `entityType` every scenario declaration carries. */
+export declare const SCENARIO_ENTITY_TYPE = "Chant::Scenario";
+/**
+ * `given: snapshot("fixtures/prod-baseline.json")` — a checked-in fixture, in
+ * the same {@link LifecycleSnapshot} JSON shape `chant lifecycle snapshot`
+ * writes (a single lexicon's recorded resources). Path-relative to the
+ * project root, read at check time — never here.
+ */
+export interface ScenarioGivenFile {
+    readonly kind: "file";
+    /** Repo-relative path to the fixture JSON file. */
+    readonly path: string;
+}
+/**
+ * `given: snapshot("prod")` — the last snapshot recorded for that environment
+ * on the `chant/lifecycle` orphan branch (one file per lexicon, read via
+ * `readSnapshot`/`readEnvironmentSnapshots`, ../lifecycle/git.ts), replayed
+ * exactly as `chant lifecycle plan` reads its own prior snapshot.
+ */
+export interface ScenarioGivenEnv {
+    readonly kind: "env";
+    /** Environment name, matching a `chant.config.ts` `environments` entry. */
+    readonly env: string;
+}
+/** What a scenario's `given` stands in for — a fixture file or a recorded environment. */
+export type ScenarioGiven = ScenarioGivenFile | ScenarioGivenEnv;
+/**
+ * Declare `given` from a single string. Pure and offline: no filesystem
+ * access, no git — the factory only classifies the string's SHAPE, never
+ * checks whether it exists. That is what keeps `Scenario` foldable under
+ * `--sandbox`, the same discipline `declareSecret`'s committed-encrypted path
+ * validation follows (../secret-provenance.ts).
+ *
+ * The classification is structural: a string containing a path separator or
+ * ending in `.json` is a fixture file; anything else (a bare token like
+ * `"prod"`) is an environment name. A `chant.config.ts` environment name that
+ * happens to contain a slash or end in `.json` is not supported by this
+ * heuristic — pass `{ kind: "env", env }` directly in that unlikely case.
+ */
+export declare function snapshot(source: string): ScenarioGiven;
+/** One named delete an `expect.deletes` clause requires — the resource must
+ * be proposed for deletion, and with exactly this ownership verdict. */
+export interface ScenarioDeleteExpectation {
+    /** The change-set entry name (ChangeSetEntry.name) expected to delete. */
+    readonly name: string;
+    /** The ownership verdict (./change-set.ts's `Ownership`) the delete must carry. */
+    readonly ownership: Ownership;
+}
+/**
+ * How a scenario treats the change set's `unobserved` rows (#1089):
+ *
+ * - `"refuse"` — any unobserved entry fails the scenario. The plan admitting
+ *   a hole is never a pass, the same fail-closed instinct
+ *   `evaluateUnobservedGate`'s default takes (./unobserved-gate.ts).
+ * - `{ allow: [names] }` — the named entities may be unobserved without
+ *   failing the scenario; any unobserved entity NOT in the list still fails
+ *   it. Unlike `evaluateUnobservedGate`'s policy (which allows by *reason*),
+ *   this allows by entity *name* — the natural unit for a scenario written
+ *   against one fixture, where "this specific resource has no binding in the
+ *   fixture" is a known, accepted gap rather than a class of reason to trust
+ *   everywhere.
+ */
+export type ScenarioUnobservedPolicy = "refuse" | {
+    readonly allow: readonly string[];
+};
+/**
+ * The assertion vocabulary (#1292 research, settled shape). Every clause is
+ * independently optional and clauses compose within one `expect` object — a
+ * scenario can assert `noop`, exact counts, specific named deletes, and an
+ * unobserved policy together. At least one clause must be present; an empty
+ * `expect` asserts nothing and is refused as a likely mistake.
+ */
+export interface ScenarioExpect {
+    /** The plan proposes no create, update, or delete, and no declared effect
+     * receipt (#1832) fires — the majority-value case (refactors, upgrades,
+     * no-op deploys). Equivalent to `{ create: 0, update: 0, delete: 0 }` plus
+     * "no receipt classifies as `effect`", but reads as the specific claim it
+     * is: a pending effect fire is a real proposed action even though it never
+     * joins the create/update/delete triad. */
+    readonly noop?: true;
+    /** Exact count of `create` rows the plan must propose. Omitted = unconstrained. */
+    readonly create?: number;
+    /** Exact count of `update` rows the plan must propose. Omitted = unconstrained. */
+    readonly update?: number;
+    /** Exact count of `delete` rows the plan must propose. Omitted = unconstrained. */
+    readonly delete?: number;
+    /** Exactly these resources must delete, each with the stated ownership —
+     * and no OTHER delete may be proposed. The highest-value assertion in the
+     * vocabulary: "this plan deletes nothing foreign", made precise per-name. */
+    readonly deletes?: readonly ScenarioDeleteExpectation[];
+    /** How the scenario treats unobserved rows. Omitted = unconstrained (an
+     * unobserved entity neither passes nor fails the scenario on its own). */
+    readonly unobserved?: ScenarioUnobservedPolicy;
+}
+/**
+ * A scenario declaration — a Declarable, so discovery collects it and `chant
+ * list` shows it, but it carries no resource payload: `partitionByLexicon`
+ * (../build.ts) excludes it from every serializer partition, so no lexicon
+ * ever emits it and no apply-bound document ever contains one.
+ */
+export interface ScenarioDeclaration extends Declarable {
+    readonly [SCENARIO_MARKER]: true;
+    readonly lexicon: "chant";
+    readonly entityType: typeof SCENARIO_ENTITY_TYPE;
+    /** The scenario's own name — what `chant scenario check` reports pass/fail against. */
+    readonly name: string;
+    readonly given: ScenarioGiven;
+    readonly expect: ScenarioExpect;
+}
+/** Factory options for {@link Scenario}. */
+export interface ScenarioOptions {
+    /** What stands in for live observation — a fixture file or a recorded environment. */
+    readonly given: ScenarioGiven;
+    /** The claim about the resulting change set. At least one clause required. */
+    readonly expect: ScenarioExpect;
+}
+/**
+ * Declare a plan scenario. The returned object is a locked Declarable:
+ * declared fields are immutable and nested structures are frozen, the same
+ * shape ../effect-receipt.ts and ../secret-provenance.ts lock down; the
+ * top-level object stays extensible so discovery can still stamp its own
+ * symbol-keyed metadata.
+ */
+export declare function Scenario(name: string, options: ScenarioOptions): ScenarioDeclaration;
+/** Type guard for a scenario declaration. */
+export declare function isScenario(value: unknown): value is ScenarioDeclaration;
+/**
+ * Extract the scenario declarations from a discovered entity map — the read
+ * surface `chant scenario check` (../cli/handlers/scenario.ts) uses. Keyed by
+ * entity name (export name), the same key `DiscoveryResult.entities` uses.
+ */
+export declare function collectScenarios(entities: ReadonlyMap<string, Declarable>): Map<string, ScenarioDeclaration>;
+//# sourceMappingURL=scenario.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scenario.d.ts","sourceRoot":"","sources":["../../src/lifecycle/scenario.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C;;iEAEiE;AACjE,eAAO,MAAM,eAAe,eAA+B,CAAC;AAE5D,2DAA2D;AAC3D,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,0FAA0F;AAC1F,MAAM,MAAM,aAAa,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;AAEjE;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAMtD;AAED;wEACwE;AACxE,MAAM,WAAW,yBAAyB;IACxC,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mFAAmF;IACnF,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,wBAAwB,GAAG,QAAQ,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAExF;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;+CAK2C;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACrB,mFAAmF;IACnF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;iFAE6E;IAC7E,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,yBAAyB,EAAE,CAAC;IACxD;8EAC0E;IAC1E,QAAQ,CAAC,UAAU,CAAC,EAAE,wBAAwB,CAAC;CAChD;AAQD;;;;;GAKG;AACH,MAAM,WAAW,mBAAoB,SAAQ,UAAU;IACrD,QAAQ,CAAC,CAAC,eAAe,CAAC,EAAE,IAAI,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,OAAO,oBAAoB,CAAC;IACjD,uFAAuF;IACvF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;CACjC;AAED,4CAA4C;AAC5C,MAAM,WAAW,eAAe;IAC9B,sFAAsF;IACtF,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,mBAAmB,CAoBpF;AAuGD,6CAA6C;AAC7C,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAOvE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAM5G"}

package/dist/lifecycle/symptoms.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Symptom derivation (#1484, epic #1487 feature 5) — one typed record joining
+ * the status join (./status.ts), change-set summaries (./change-set.ts), and
+ * unobserved evidence (../observation.ts) into the shape `ConvergeOp`'s rule
+ * table evaluates against.
+ *
+ * Derive-only, per the issue's leaning on its own open question 4: no new
+ * `LexiconPlugin.symptoms?()` interface in v1 — everything here is a pure
+ * projection of structures chant already computes (`ChangeSet`,
+ * `ComponentStatusRow[]`). No I/O in this module; a caller (the `convergeTick`
+ * activity, lexicons/temporal/src/op/activities/converge.ts) gathers those
+ * inputs and hands them here.
+ *
+ * One record per tick, not per component: the issue's own rule sketch reads
+ * `s.status`/`s.backupVerifiedAge` as a single symptom `s` a rule closes
+ * over, and epic feature 5 calls it "one typed record" (singular). A
+ * multi-component environment still resolves to one record per tick —
+ * `components` carries the per-component detail behind the aggregate for
+ * reporting, and `status` is the worst verdict across all of them (see
+ * {@link worstStatus}), so "any component is unknown" is enough to trip
+ * `unknown never remediates` for the whole tick.
+ */
+import type { ChangeSet } from "./change-set.js";
+import type { ComponentStatusRow } from "./status.js";
+import { type UnobservedReason } from "../observation.js";
+/** The worst (most-cautious) reconciliation verdict across a set of component rows. `"reconciled"` for an empty set — nothing to converge is a quiet environment. */
+export declare function worstStatus(rows: ComponentStatusRow[]): ComponentStatusRow["reconciliation"];
+/**
+ * One tick's typed symptom record. Every field a `ConvergeOp` rule may
+ * reference — see `../op/converge-rule.ts`'s `SymptomPredicate<S>`, where
+ * `S` is this interface, so a rule whose predicate names a field outside
+ * this shape fails TypeScript at the author's call site (the "symptom field
+ * nothing produces" build-time refusal).
+ */
+export interface ConvergeSymptom {
+    env: string;
+    /** The worst reconciliation verdict across every component row this tick observed (see {@link worstStatus}). */
+    status: ComponentStatusRow["reconciliation"];
+    /** Per-component detail behind `status`, for reporting — never read by a rule predicate directly (rules read the flat counts below). */
+    components: ComponentStatusRow[];
+    /** Change-set action counts for the tick (./change-set.ts's `summarize`). */
+    createCount: number;
+    updateCount: number;
+    deleteCount: number;
+    /** Live but undeclared, ownership unestablished — a candidate to adopt into source. Never auto-claimed; see the issue's "adopt is reported, never auto-claimed" honesty requirement. */
+    adoptCount: number;
+    runtimeCount: number;
+    effectCount: number;
+    /** Declared, but the lexicon could not observe it (#1089) — the count backing `status: "unknown"`. */
+    unobservedCount: number;
+    /** Every distinct reason behind `unobservedCount`, for a report action's detail. */
+    unobservedReasons: UnobservedReason[];
+    /** Total resource count under change-set evidence for this tick (sum of the six counts above). */
+    totalCount: number;
+}
+/**
+ * Join a `ChangeSet` and `ComponentStatusRow[]` for one tick into a
+ * `ConvergeSymptom`. Pure — no I/O.
+ */
+export declare function deriveSymptoms(env: string, cs: ChangeSet, statusRows: ComponentStatusRow[]): ConvergeSymptom;
+/** Every field name a `ConvergeSymptom` produces — the runtime whitelist `TMP014` (lexicons/temporal) re-validates a serialized rule table's predicates against. Kept in sync with {@link ConvergeSymptom} by hand (deliberately small, changes rarely). */
+export declare const CONVERGE_SYMPTOM_FIELDS: ReadonlySet<string>;
+//# sourceMappingURL=symptoms.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"symptoms.d.ts","sourceRoot":"","sources":["../../src/lifecycle/symptoms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAgB,SAAS,EAAE,MAAM,cAAc,CAAC;AAE5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,EAAwB,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAkB7E,qKAAqK;AACrK,wBAAgB,WAAW,CAAC,IAAI,EAAE,kBAAkB,EAAE,GAAG,kBAAkB,CAAC,gBAAgB,CAAC,CAM5F;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,gHAAgH;IAChH,MAAM,EAAE,kBAAkB,CAAC,gBAAgB,CAAC,CAAC;IAC7C,wIAAwI;IACxI,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,wLAAwL;IACxL,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,sGAAsG;IACtG,eAAe,EAAE,MAAM,CAAC;IACxB,oFAAoF;IACpF,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;IACtC,kGAAkG;IAClG,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE,kBAAkB,EAAE,GAAG,eAAe,CAwB5G;AAED,4PAA4P;AAC5P,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAatD,CAAC"}

package/dist/lint/output-docs.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Parsed-output view for post-synth checks (chant #975).
+ *
+ * `PostSynthContext.outputs` carries raw serialized strings — a `chant build`
+ * consumer has to parse YAML/JSON itself before it can reason about
+ * structure. Every lexicon that needs this today rolls its own splitter
+ * (`parseK8sManifests` in k8s, hand-rolled `JSON.parse` in aws's
+ * `cf-refs.ts`), and each of the ~30 k8s post-synth checks reparses the same
+ * output independently. This module is the shared, parse-once primitive:
+ * `parseOutputDocs` turns `ctx.outputs` into a flat list of `OutputDoc`s,
+ * and `PostSynthContext.docs` (see `./post-synth.ts`) memoizes one call to it
+ * per build so every check — lexicon-shipped or project-authored policy —
+ * shares the same parse.
+ *
+ * `pick`/`get` are the "look at only the fields you care about" ergonomic
+ * from the issue's `,remain`-style framing — a partial, unvalidated view of
+ * an already-parsed tree, not a query DSL. Selector languages over the
+ * *source* AST stay in `./declarative.ts`; this module is output-side only.
+ */
+import type { SerializerResult } from "../serializer.js";
+/**
+ * One parsed document from a build's serialized output.
+ *
+ * A single `ctx.outputs` entry can yield more than one `OutputDoc`: a
+ * multi-document YAML stream (`---`-separated) yields one per document, and
+ * a `SerializerResult` with `files` yields further docs for each nested
+ * file (a CloudFormation nested stack template, a sidecar manifest).
+ */
+export interface OutputDoc {
+    /** The `ctx.outputs` map key this document came from. */
+    lexicon: string;
+    /** Position of this document within its source (primary output or one
+     *  `files` entry) — 0 for a single-document source, 0..n-1 for a
+     *  multi-document YAML stream. */
+    index: number;
+    /** Whether this document was decoded as YAML or as whole-content JSON. */
+    format: "yaml" | "json";
+    /** The parsed tree. `undefined` when parsing failed — see `error`. */
+    value: unknown;
+    /**
+     * Set when this document came from a `SerializerResult.files` entry rather
+     * than the primary output — the file's key in that map (e.g. a nested
+     * stack template's filename).
+     */
+    file?: string;
+    /**
+     * Set when this document could not be parsed into a usable tree. The
+     * document is still returned (a marker, not a throw) so a caller can see
+     * that something in the build output failed to parse, rather than the
+     * failure disappearing silently the way `parseK8sManifests` has always
+     * swallowed it. `value` is `undefined` on an errored document. Filter with
+     * `ctx.docs.filter((d) => !d.error)` to get only usable documents.
+     */
+    error?: string;
+}
+/**
+ * Parse every output in `outputs` into a flat list of `OutputDoc`s: one call,
+ * shared by every post-synth check via `PostSynthContext.docs`.
+ *
+ * Format detection is whole-source, not per-document: if the entire source
+ * parses as JSON, it is one `"json"` document (CloudFormation, most non-k8s
+ * serializers). Otherwise the source is treated as a YAML stream — split on
+ * `---` document separators — and each resulting document is parsed as YAML
+ * (`format: "yaml"`), even one that happens to also be valid JSON, since
+ * JSON is a YAML subset. `SerializerResult.files` entries (nested templates,
+ * sidecar manifests) are parsed the same way, tagged with `file`.
+ *
+ * A document that fails to parse into a non-null object/array — malformed
+ * input, or a bare scalar where a manifest was expected — is not thrown:
+ * it is included with `error` set and `value: undefined`. See `OutputDoc`.
+ */
+export declare function parseOutputDocs(outputs: Map<string, string | SerializerResult>): OutputDoc[];
+/**
+ * Partial typed decode — the `,remain`-style ergonomic from `ma91n/tfpolicy`:
+ * decode the fields you care about, leave everything else in place,
+ * unvalidated. Returns a shallow, top-level view of `value` narrowed to the
+ * keys named in `shape`. A key absent from `value` (or `value` not being a
+ * plain object) is simply absent from the result — no default is invented.
+ *
+ * This is NOT runtime validation: a key that IS present is copied as-is,
+ * whatever its actual shape, and cast to `T`'s declared type for that key.
+ * Use `get` for a deeper walk into one of the picked values.
+ */
+export declare function pick<T extends object>(value: unknown, shape: (keyof T)[]): Partial<T>;
+/**
+ * Dotted-path getter for the common walk over a parsed doc, e.g.
+ * `get(doc.value, "spec.template.spec")`. Not a query DSL — no wildcards,
+ * no predicates, no array-flattening. An array index is just a numeric path
+ * segment (`get(value, "items.0.name")`), since JS indexes arrays by string
+ * key underneath. Returns `undefined` as soon as any segment is missing or
+ * the value at that point isn't indexable — it never throws on a bad path.
+ */
+export declare function get(value: unknown, path: string): unknown;
+//# sourceMappingURL=output-docs.d.ts.map

package/dist/lint/output-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-docs.d.ts","sourceRoot":"","sources":["../../src/lint/output-docs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGtD;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB;;sCAEkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,sEAAsE;IACtE,KAAK,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAAC,GAAG,SAAS,EAAE,CAY5F;AA4ED;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAWrF;AAED;;;;;;;GAOG;AACH,wBAAgB,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAQzD"}

package/dist/lint/post-synth.d.ts

@@ -1,6 +1,8 @@
 import type { Declarable } from "../declarable.js";
 import type { SerializerResult } from "../serializer.js";
 import type { Severity } from "./rule.js";
+import { type OutputDoc } from "./output-docs.js";
+export { parseOutputDocs, pick, get, type OutputDoc } from "./output-docs.js";
 /**
  * Context provided to post-synthesis checks.
  */
@@ -15,6 +17,25 @@ export interface PostSynthContext {
      * e.g. "no public buckets in prod". Undefined when no environment is set.
      */
     env?: string;
+    /**
+     * Parsed output documents (chant #975) — `ctx.outputs` run through
+     * `parseOutputDocs` once and cached. A lazy `readonly` getter, not a plain
+     * field: computed on first access and shared across every check in the
+     * run, so a check that only reads `entities` pays nothing, and no two
+     * checks re-parse the same YAML/JSON. See `./output-docs.ts`.
+     *
+     * Optional at the type level — NOT because it can be absent from a real
+     * build. Every context chant itself constructs (`runPostSynthChecks`
+     * below, `@intentius/chant-test-utils`'s `createPostSynthContext` and
+     * `makePostSynthCtx*`) wires it up via `createDocsAccessor` and it is
+     * always present there. It is typed optional only so the many lexicon
+     * tests that build a `PostSynthContext` object literal by hand (predating
+     * this field) keep compiling unchanged, per this issue's own "existing
+     * checks compile unchanged" constraint — a new check that wants `ctx.docs`
+     * should still get a real array from every context chant builds; guard
+     * with `ctx.docs ?? []` only when a context's provenance is unknown.
+     */
+    readonly docs?: OutputDoc[];
     /** Raw build result object */
     buildResult: {
         outputs: Map<string, string | SerializerResult>;
@@ -27,6 +48,14 @@ export interface PostSynthContext {
         sourceFileCount: number;
     };
 }
+/**
+ * Build the lazy, memoized `docs` accessor shared by `runPostSynthChecks`
+ * (below) and `@intentius/chant-test-utils`'s `createPostSynthContext` — the
+ * two places a `PostSynthContext` gets constructed. Returns a zero-arg
+ * function suitable for a `get docs()` object-literal accessor; the first
+ * call parses, every later call returns the same cached array.
+ */
+export declare function createDocsAccessor(outputs: Map<string, string | SerializerResult>): () => OutputDoc[];
 /**
  * Extract the primary content string from a serializer output.
  */

package/dist/lint/post-synth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"post-synth.d.ts","sourceRoot":"","sources":["../../src/lint/post-synth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAEvC;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAAC,CAAC;IAChD,8CAA8C;IAC9C,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClC;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,WAAW,EAAE;QACX,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAAC,CAAC;QAChD,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;QAClC,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,MAAM,EAAE,KAAK,CAAC;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACjD,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,GAAG,MAAM,CAE1E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE5F;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,QAAQ,EAAE,QAAQ,CAAC;IACnB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,KAAK,CAAC,GAAG,EAAE,gBAAgB,GAAG,mBAAmB,EAAE,CAAC;CACrD;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAQxE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,cAAc,EAAE,EACxB,WAAW,EAAE,gBAAgB,CAAC,aAAa,CAAC,EAC5C,GAAG,CAAC,EAAE,MAAM,GACX,mBAAmB,EAAE,CAavB"}
+{"version":3,"file":"post-synth.d.ts","sourceRoot":"","sources":["../../src/lint/post-synth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAEhE,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAE3E;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAAC,CAAC;IAChD,8CAA8C;IAC9C,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClC;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,CAAC;IAC5B,8BAA8B;IAC9B,WAAW,EAAE;QACX,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAAC,CAAC;QAChD,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;QAClC,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,MAAM,EAAE,KAAK,CAAC;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACjD,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAAC,GAC9C,MAAM,SAAS,EAAE,CAQnB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,GAAG,MAAM,CAE1E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE5F;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,QAAQ,EAAE,QAAQ,CAAC;IACnB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,KAAK,CAAC,GAAG,EAAE,gBAAgB,GAAG,mBAAmB,EAAE,CAAC;CACrD;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAQxE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,cAAc,EAAE,EACxB,WAAW,EAAE,gBAAgB,CAAC,aAAa,CAAC,EAC5C,GAAG,CAAC,EAAE,MAAM,GACX,mBAAmB,EAAE,CAiBvB"}

package/dist/lint/rules/__fixtures__/comp/comp003/pass/agent-turn.component.d.ts

@@ -0,0 +1,11 @@
+import type { Component } from "../../../../../../components/component.js";
+/**
+ * COMP003 pass case (#1944): a bare "run-agent" step with no "noRollback"
+ * opt-out and no component-level "rollback" — must pass COMP003 because
+ * "run-agent"'s rollbackPolicy is "native" (#1941), not "needs-opt-out". This
+ * is the regression test proving the registry's declared rollbackPolicy for
+ * "run-agent" is wired correctly into ctx.rollbackPolicies, the same seam
+ * COMP005 uses for ctx.knownKinds — see comp.test.ts's FIXTURE_ROLLBACK_POLICIES.
+ */
+export declare const agentTurn: Component;
+//# sourceMappingURL=agent-turn.component.d.ts.map

package/dist/lint/rules/__fixtures__/comp/comp003/pass/agent-turn.component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-turn.component.d.ts","sourceRoot":"","sources":["../../../../../../../src/lint/rules/__fixtures__/comp/comp003/pass/agent-turn.component.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wCAAwC,CAAC;AAGxE;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,EAAE,SAcvB,CAAC"}

package/dist/lsp/lexicon-providers.d.ts

@@ -16,6 +16,13 @@ export interface LexiconEntry {
     writeOnly?: string[];
     primaryIdentifier?: string[];
     deprecatedProperties?: string[];
+    /**
+     * Subset of `deprecatedProperties` that only prose supports — a lexicon
+     * generator matched the property description against a deprecation regex
+     * rather than reading an upstream declaration (#1701). Editors do not strike
+     * these through; the basis is too weak to mark a property dead.
+     */
+    inferredDeprecations?: string[];
     conditionalCreateOnly?: string[];
     replacementStrategy?: "delete_then_create" | "create_then_delete";
     tagging?: {

package/dist/lsp/lexicon-providers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lexicon-providers.d.ts","sourceRoot":"","sources":["../../src/lsp/lexicon-providers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAI1F,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,UAAU,GAAG,UAAU,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,mBAAmB,CAAC,EAAE,oBAAoB,GAAG,oBAAoB,CAAC;IAClE,OAAO,CAAC,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,OAAO,CAAC;QAAC,YAAY,EAAE,OAAO,CAAA;KAAE,CAAC;CAC9E;AAID;;GAEG;AACH,qBAAa,YAAY;IACX,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC;IAEzD,8DAA8D;IAC9D,gBAAgB,IAAI,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IAUtE,0DAA0D;IAC1D,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE;IAqB7C,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;CAGjD;AAID;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,iBAAiB,EACtB,KAAK,EAAE,YAAY,EACnB,YAAY,EAAE,MAAM,GACnB,cAAc,EAAE,CAsDlB;AAID;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,YAAY,EACjB,KAAK,EAAE,YAAY,EACnB,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,KAAK,SAAS,GAAG,SAAS,GAC9E,SAAS,GAAG,SAAS,CAiBvB"}
+{"version":3,"file":"lexicon-providers.d.ts","sourceRoot":"","sources":["../../src/lsp/lexicon-providers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAI1F,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,UAAU,GAAG,UAAU,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,mBAAmB,CAAC,EAAE,oBAAoB,GAAG,oBAAoB,CAAC;IAClE,OAAO,CAAC,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,OAAO,CAAC;QAAC,YAAY,EAAE,OAAO,CAAA;KAAE,CAAC;CAC9E;AAID;;GAEG;AACH,qBAAa,YAAY;IACX,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC;IAEzD,8DAA8D;IAC9D,gBAAgB,IAAI,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IAUtE,0DAA0D;IAC1D,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE;IAqB7C,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;CAGjD;AAID;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,iBAAiB,EACtB,KAAK,EAAE,YAAY,EACnB,YAAY,EAAE,MAAM,GACnB,cAAc,EAAE,CAyDlB;AAID;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,YAAY,EACjB,KAAK,EAAE,YAAY,EACnB,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,KAAK,SAAS,GAAG,SAAS,GAC9E,SAAS,GAAG,SAAS,CAiBvB"}

package/dist/op/activity-contract.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Activity contracts — the Stage 1 fix for chant #1288 ("Ops are the one
+ * place chant accepts untyped arguments and resolves names at runtime").
+ *
+ * Maintainer decision (#1288, 2026-08-25): a staged approach. Stage 1 (this
+ * module) is registered args/return schemas per activity, validated by
+ * `chant build` against every step — non-breaking, no change to
+ * {@link ActivityStep.args}'s `Record<string, unknown>` shape or the step
+ * builders. Stage 2 (a separate PR) regenerates the step builders as fully
+ * typed wrappers for editor completion and go-to-definition. #1289 (op.json
+ * IR) and #1290 (step-output references) build on these contracts — #1290
+ * specifically needs a declared `returns` schema to validate a later step's
+ * reference into an earlier one's output against, which is why `returns` is
+ * part of the shape here even though nothing in Stage 1 reads it for that.
+ *
+ * An activity declares a contract alongside its implementation — the same
+ * "registration surface" the issue asked for (`activity-registry.ts`'s
+ * `collectActivities` already does this for implementations; this is the
+ * schema-shaped sibling). `chant build` — via a lexicon's own post-synth
+ * check, e.g. the temporal lexicon's TMP012 — resolves each step's `fn`
+ * against a contract map built the same way and validates `args` and
+ * `outcomeAttribute.from`. A step whose `fn` has no registered contract is
+ * skipped (not an error): this is deliberately incremental — a lexicon opts
+ * an activity in by declaring a contract for it, and the k8s/aws/azure/gcp/
+ * fly activity sets are expected to pick this up lexicon by lexicon rather
+ * than all at once (see the issue's "worth checking this lands cleanly"
+ * note).
+ *
+ * Ownership is decentralized on purpose: each lexicon declares contracts for
+ * the activities it implements and validates them with its own post-synth
+ * check (the same `rulePrefix`-per-lexicon pattern every other check in
+ * chant already uses), rather than a shared cross-lexicon registry. A
+ * `Temporal::Op` step can call an activity contributed by any lexicon, and
+ * `PostSynthContext.entities` already carries the whole resolved graph to
+ * every lexicon's checks, so no new plumbing is needed for that to work.
+ */
+import { z } from "zod";
+import type { OpConfig } from "./types.js";
+/** Every literal value {@link ActivityStep.profile} may hold. Kept in sync with `types.ts`'s `ActivityStep["profile"]`. */
+export declare const KNOWN_ACTIVITY_PROFILES: readonly ["fastIdempotent", "longInfra", "k8sWait", "humanGate", "argoSync", "policyCheck"];
+declare const CONTRACT_BRAND: unique symbol;
+/**
+ * A registered activity's args/return schemas — the declaration that lets
+ * `chant build` catch a typo'd or mistyped step before it ever reaches a
+ * cluster.
+ *
+ * Author `args` with `z.strictObject(...)` (or an equivalent that rejects
+ * unrecognized keys), not `z.object(...)`. Zod's default `.object()` silently
+ * drops a key it doesn't recognize instead of failing — exactly the
+ * `helmInstall("api", "./chart", { nameSpace: "prod" })` failure class the
+ * issue names, where the misspelled key vanishes instead of erroring. A
+ * strict schema turns that into a build error.
+ */
+export interface ActivityContract<Args = unknown, Return = unknown> {
+    readonly [CONTRACT_BRAND]: true;
+    /** The activity's registered name — must match a step's `fn`. */
+    name: string;
+    /** Schema every step's `args` (defaulted to `{}` when omitted) must satisfy. */
+    args: z.ZodType<Args>;
+    /**
+     * Schema the activity resolves to. Optional: an activity that returns
+     * nothing meaningful (or hasn't had its return type written down yet) can
+     * omit it. Needed to validate a step's `outcomeAttribute.from` path, and —
+     * per #1290 — a later step's reference into this one's output.
+     */
+    returns?: z.ZodType<Return>;
+}
+/** Declare an activity contract. */
+export declare function activityContract<ArgsSchema extends z.ZodTypeAny, ReturnSchema extends z.ZodTypeAny = never>(name: string, args: ArgsSchema, returns?: ReturnSchema): ActivityContract<z.infer<ArgsSchema>, ReturnSchema extends z.ZodTypeAny ? z.infer<ReturnSchema> : unknown>;
+/** Structural guard for a value produced by {@link activityContract}. */
+export declare function isActivityContract(value: unknown): value is ActivityContract;
+/**
+ * Add every {@link ActivityContract} exported from an activity-contracts
+ * module to `into`, keyed by its declared `name` — the schema-shaped sibling
+ * of `activity-registry.ts`'s `collectActivities`.
+ */
+export declare function collectActivityContracts(mod: Record<string, unknown>, into: Map<string, ActivityContract>): void;
+export interface ActivityContractIssue {
+    /** The Op the offending step belongs to. */
+    opName: string;
+    /** The phase the offending step belongs to. */
+    phase: string;
+    /** The activity name the offending step calls. */
+    fn: string;
+    /** Human-readable description of the mismatch. */
+    message: string;
+}
+/**
+ * Does dot-path `path` resolve to a field that exists on `schema`? Object
+ * shapes only — a return schema whose root (or an intermediate segment) is
+ * a `z.record(...)`/`z.array(...)` rather than a `z.object(...)` hard-errors
+ * (returns `false`) instead of skipping, deliberately (chant #1290 comment
+ * on #1288's pre-merge review): a record's keys are dynamic and an array's
+ * elements are index-addressed, neither of which a dot-path segment can
+ * check against in any way that's more meaningful than "the author probably
+ * meant something else." No declared `returns` schema needs this today, so
+ * there's no live case to design against yet. The escape hatch is an empty
+ * path — `outcomeAttribute.from` omitted, or a {@link StepOutputRef}'s
+ * `path` omitted — which references the whole return value and never calls
+ * this function; a record/array-returning activity's whole value is always
+ * a valid reference target.
+ */
+export declare function pathExistsInSchema(schema: z.ZodTypeAny, path: string): boolean;
+/**
+ * The zod schema at property-key path `path` inside `schema`, walking
+ * through `z.ZodObject` shapes only (unwrapping optional/nullable/default at
+ * each level, same as {@link pathExistsInSchema}). `undefined` when a
+ * segment doesn't resolve, or an intermediate schema isn't a `z.ZodObject` —
+ * same record/array hard-stop {@link pathExistsInSchema} documents. An empty
+ * `path` returns `schema` itself (unwrapped).
+ */
+export declare function schemaAtPath(schema: z.ZodTypeAny, path: ReadonlyArray<string>): z.ZodTypeAny | undefined;
+/**
+ * A primitive-shape classification of a zod schema — `string`/`number`/
+ * `boolean`/`object`/`array`, or `undefined` for anything else (a union,
+ * enum, literal, `z.any()`/`z.unknown()`, a transform, …). Used by the
+ * step-output-ref cross-contract type check (chant #1950-3) to compare a
+ * producer's declared return type against a consumer's declared arg type at
+ * the same structural position — deliberately shallow: it bails (returns
+ * `undefined`) on anything fancier than these five kinds rather than trying
+ * to reason about it, per that check's "bail out silently" design.
+ */
+export type PrimitiveSchemaKind = "string" | "number" | "boolean" | "object" | "array";
+export declare function primitiveKindOf(schema: z.ZodTypeAny): PrimitiveSchemaKind | undefined;
+/**
+ * Validate every activity step in an Op's phases (main and `onFailure`)
+ * against a contract map. A step whose `fn` has no entry in `contracts` is
+ * skipped — Stage 1 is opt-in per activity, not a hard requirement that
+ * every activity have a declared contract.
+ *
+ * Catches the four failure classes chant #1288 names:
+ *  - an unrecognized `profile` (checked against {@link KNOWN_ACTIVITY_PROFILES}, independent of whether `fn` has a contract),
+ *  - an args key the declared schema doesn't recognize,
+ *  - an args value of the wrong type (including a required key that's missing),
+ *  - an `outcomeAttribute.from` path that can't exist on the declared return type.
+ */
+export declare function validateActivitySteps(config: Pick<OpConfig, "name" | "phases" | "onFailure">, contracts: ReadonlyMap<string, ActivityContract>): ActivityContractIssue[];
+export {};
+//# sourceMappingURL=activity-contract.d.ts.map

package/dist/op/activity-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-contract.d.ts","sourceRoot":"","sources":["../../src/op/activity-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,QAAQ,EAAiD,MAAM,SAAS,CAAC;AAEvF,2HAA2H;AAC3H,eAAO,MAAM,uBAAuB,6FAO1B,CAAC;AAEX,QAAA,MAAM,cAAc,eAA0C,CAAC;AAE/D;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB,CAAC,IAAI,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO;IAChE,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,IAAI,CAAC;IAChC,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED,oCAAoC;AACpC,wBAAgB,gBAAgB,CAAC,UAAU,SAAS,CAAC,CAAC,UAAU,EAAE,YAAY,SAAS,CAAC,CAAC,UAAU,GAAG,KAAK,EACzG,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,UAAU,EAChB,OAAO,CAAC,EAAE,YAAY,GACrB,gBAAgB,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,YAAY,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC,CAO5G;AAED,yEAAyE;AACzE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAE5E;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,IAAI,CAIhH;AAID,MAAM,WAAW,qBAAqB;IACpC,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;CACjB;AAmCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE9E;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,UAAU,GAAG,SAAS,CASxG;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEvF,wBAAgB,eAAe,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,mBAAmB,GAAG,SAAS,CAQrF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,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,CA+CzB"}