@intentius/chant 0.57.0 → 0.58.0

package/src/index.ts

@@ -5,6 +5,7 @@
  */
 
 export * from "./declarable";
+export * from "./held-elsewhere";
 export * from "./composite";
 export * from "./provenance";
 export * from "./secret-provenance";
@@ -56,6 +57,8 @@ export * from "./observation";
 export * from "./identity";
 export * from "./apply";
 export * from "./deep-observation";
+export * from "./claimed-fields";
+export * from "./fold-provenance";
 export * from "./owner-chain";
 export * from "./lexicon-integrity";
 export * from "./lexicon-manifest";

package/src/kubectl-context.ts

@@ -3,7 +3,7 @@
  *
  * Every cloud lexicon binds an environment to a scope: AWS resolves `<env>`
  * to a CloudFormation stack, Azure treats `<env>` as the resource group,
- * Temporal looks up `temporal.profiles.<env>` in `chant.config.ts`. K8s (and
+ * Fly resolves it to an app. K8s (and
  * GCP-via-Config-Connector, which observes through the same kubectl path)
  * bound nothing — `describeResources` shelled out to `kubectl get` with no
  * `--context`, so it read whatever cluster `kubectl config current-context`
@@ -111,8 +111,8 @@ export interface ResolveClusterTargetOptions {
  * Resolve the kubectl context an environment should be observed/applied
  * against, reading `k8s.profiles.<environment>.context` from `chant.config.ts`
  * (the `config` passed in is the passthrough `ChantConfig`, cast loosely since
- * the `k8s` key isn't declared on the core schema — same pattern as
- * `temporal.profiles`).
+ * the `k8s` key isn't declared on the core schema — the same pattern every
+ * lexicon namespace follows).
  *
  * - No binding declared: returns `{ source: "ambient" }` — unchanged
  *   behavior — but logs a visible warning identifying the caller and

package/src/lexicon-config.test.ts

@@ -67,15 +67,15 @@ describe("validateLexiconConfig (#1344)", () => {
   });
 
   test("validates each declaring lexicon independently", () => {
-    const temporal = {
-      name: "temporal",
+    const k8s = {
+      name: "k8s",
       configSchema: z.strictObject({ defaultProfile: z.string().optional() }),
     };
     const problems = validateLexiconConfig(
-      [forgejo, temporal],
-      cfg({ forgejo: { actionsRoot: "https://x" }, temporal: { defaultProfil: "local" } }),
+      [forgejo, k8s],
+      cfg({ forgejo: { actionsRoot: "https://x" }, k8s: { defaultProfil: "local" } }),
     );
-    expect(problems.map((p) => p.lexicon)).toEqual(["temporal"]);
+    expect(problems.map((p) => p.lexicon)).toEqual(["k8s"]);
   });
 
   test("no config at all is not a problem", () => {

package/src/lexicon-config.ts

@@ -2,7 +2,7 @@
  * The config namespace a lexicon owns (#1344).
  *
  * Three lexicons read a top-level `chant.config.ts` key named after themselves —
- * `k8s.profiles.<env>.context`, `temporal.profiles`, `forgejo.runnerLabels` and
+ * `k8s.profiles.<env>.context`, `forgejo.runnerLabels` and
  * `forgejo.actionsRoot` — all documented for users, none declared anywhere.
  * `ChantConfigSchema` is `.passthrough()`, so at runtime any key is accepted and
  * a typo is silently ignored: write `runnerLabel` and the Forgejo dialect just
@@ -12,9 +12,9 @@
  *     error TS2353: Object literal may only specify known properties,
  *     and 'forgejo' does not exist in type 'ChantConfig'.
  *
- * Three lexicons had arrived at three different workarounds: temporal exported
- * its own widened `TemporalChantConfig`, k8s's docs dropped `satisfies`, and
- * forgejo's kept it and were wrong.
+ * The lexicons had arrived at different workarounds: one exported its own
+ * widened config type, k8s's docs dropped `satisfies`, and forgejo's kept it
+ * and were wrong.
  *
  * A lexicon now declares the shape of its namespace. The declaration is both
  * halves of the fix at once: core validates against it at load, and the lexicon

package/src/lexicon-plugin-helpers.ts

@@ -1,7 +1,7 @@
 /**
  * Shared helpers for lexicon plugin implementations.
  *
- * Eliminates boilerplate across the 8 lexicon plugins by providing
+ * Eliminates boilerplate across the 15 lexicon plugins that use it by providing
  * factory functions for common plugin methods: skills loading,
  * MCP diff tool, and MCP catalog resource.
  */

package/src/lexicon.ts

@@ -12,6 +12,9 @@ import type { CompletionContext, CompletionItem, HoverContext, HoverInfo, CodeAc
 import type { McpToolContribution, McpResourceContribution } from "./mcp/types";
 import type { DriverComponent } from "./components/driver";
 import type { EmulatorDeclaration } from "./op/emulator-lifecycle";
+import type { OpRuntimeProvider } from "./op/runtime";
+import type { OpSchedule } from "./op/types";
+import type { ActivityContract } from "./op/activity-contract";
 import type { OwnershipChannel, OwnershipMarker } from "./ownership";
 import type { LexiconConfigSchema } from "./lexicon-config";
 import type { RuleMeta } from "./audit/catalog";
@@ -24,6 +27,17 @@ import type { DisruptionQuery, DisruptionVerdict } from "./lifecycle/disruption"
 import type { OwnerChainVerdict } from "./owner-chain";
 import type { CommandGroup } from "./cli/command-group";
 
+// Re-exported so a lexicon that hosts Op runs (#2121) can type its
+// `opRuntime` from the same entry it imports the plugin contract from.
+export type {
+  OpRuntimeProvider,
+  OpRunHandle,
+  OpRunRecord,
+  OpRunStartOptions,
+  OpRunState,
+  OpRunStatus,
+} from "./op/runtime";
+
 // Re-exported so a lexicon can author its command group (#1078) from the
 // same `@intentius/chant/lexicon` entry it imports the plugin contract from.
 export type { CommandGroup, CommandGroupCommand, CommandGroupContext } from "./cli/command-group";
@@ -472,9 +486,9 @@ export interface ComponentPipelineResult {
 }
 
 /**
- * Finding-mode a scheduled Op surfaces on drift — the vocabulary the
- * temporal-lexicon composites (`WorkflowAuditOp`/`PipelineAuditOp`/
- * `ReconcileOp`) already declare on the Op itself (#927). The mode is baked
+ * Finding-mode a scheduled Op surfaces on drift — the vocabulary the core
+ * composites (`WorkflowAuditOp`/`PipelineAuditOp`/`ReconcileOp`) already
+ * declare on the Op itself (#927). The mode is baked
  * into the Op's own activity args at build time and is never re-passed on the
  * generated CI invocation; here it decides only what token/permission wiring
  * the generated job needs to act on a finding — elevated write access for
@@ -482,24 +496,74 @@ export interface ComponentPipelineResult {
  */
 export type OpFindingMode = "report" | "issue" | "pull-request" | "merge-request";
 
+/**
+ * The CI-native trigger driving a scheduled Op's generated workflow. `cron`
+ * is the historical shape — the CI-only way to give an Op a cadence.
+ * `pull_request` and `push` are generic beyond cron: a
+ * Terraform CI shape needs `plan` on `pull_request` (posted as a PR comment)
+ * and `apply` on `push` to the default branch, each its own Op with its own
+ * trigger (#2081, #2084).
+ */
+export type OpTrigger =
+  | { kind: "cron"; schedule: string }
+  | { kind: "pull_request"; branches?: string[] }
+  | { kind: "push"; branches?: string[] };
+
 /** One scheduled Op to generate CI for — the cron-triggered counterpart to a component (generate mode). */
 export interface ScheduledOpSpec {
   /** Op name (`*.op.ts`'s `Op({ name })`) — what `chant run <name>` targets. */
   name: string;
-  /** Cron expression driving the CI-native trigger — the CI-only alternative to a Temporal `TemporalSchedule`. */
-  schedule: string;
+  /**
+   * Cron expression driving the CI-native trigger. Superseded by `trigger`; kept for
+   * backward compatibility, so an omitted `trigger` with `schedule` present
+   * still means `{ kind: "cron", schedule }` (see {@link resolveOpTrigger}).
+   */
+  schedule?: string;
+  /**
+   * The CI-native trigger driving this Op's generated workflow (#2084).
+   * Omit this and set only `schedule` for the pre-existing cron behavior;
+   * set explicitly for `pull_request`/`push`, or to spell cron the same way.
+   */
+  trigger?: OpTrigger;
+  /**
+   * The declaring Op's own cadence (#2120) — `OpConfig.schedule`, filled in
+   * by `generateOpsPipeline` from the discovered Op so a scheduled Op needs
+   * no second cron declaration on the CI side. The lowest-precedence source
+   * of a trigger: an explicit `trigger` first, then an explicit `schedule` on
+   * this spec, then this (see {@link resolveOpTrigger}).
+   */
+  opSchedule?: OpSchedule;
   /** This Op's finding-mode, for permission/token wiring only (see {@link OpFindingMode}). Default: "report" — no elevated permissions. */
   findingMode?: OpFindingMode;
 }
 
+/**
+ * Resolve a `ScheduledOpSpec`'s effective trigger, most specific first:
+ * `trigger` when given; else the backward-compatible `{ kind: "cron",
+ * schedule }` built from this spec's own `schedule` — every pre-#2084 caller
+ * (`WorkflowAuditOp`, `PipelineAuditOp`, `ReconcileOp`, …, and their tests)
+ * sets only that and keeps meaning cron unchanged; else the declaring Op's
+ * own `schedule.cron` (#2120), so an Op that already carries its cadence
+ * needs no second cron declaration on the CI side. Throws when none of the
+ * three is present — a `ScheduledOpSpec` needs exactly one trigger.
+ */
+export function resolveOpTrigger(spec: ScheduledOpSpec): OpTrigger {
+  if (spec.trigger) return spec.trigger;
+  if (spec.schedule) return { kind: "cron", schedule: spec.schedule };
+  if (spec.opSchedule) return { kind: "cron", schedule: spec.opSchedule.cron };
+  throw new Error(
+    `Scheduled Op "${spec.name}" has neither \`trigger\` nor \`schedule\`, and the Op itself declares no \`schedule\` — one is required.`,
+  );
+}
+
 /** One CI job generated for a scheduled Op. */
 export interface OpPipelineJob {
   /** CI job name (safe as a YAML key). */
   jobName: string;
   /** The Op this job runs. */
   op: string;
-  /** Cron expression this job's workflow is scheduled on. */
-  schedule: string;
+  /** The trigger driving this job's generated workflow (#2084) — lets a consumer tell cron/`pull_request`/`push` jobs apart. */
+  trigger: OpTrigger;
   /** The finding-mode wired for this job. */
   findingMode: OpFindingMode;
 }
@@ -623,8 +687,8 @@ export interface LexiconPlugin {
    * The shape of this lexicon's own `chant.config.ts` namespace — the top-level
    * key named after the lexicon (#1344).
    *
-   * k8s reads `k8s.profiles.<env>.context`, temporal `temporal.profiles`,
-   * forgejo `forgejo.runnerLabels` and `forgejo.actionsRoot`. All were
+   * k8s reads `k8s.profiles.<env>.context`, forgejo `forgejo.runnerLabels`
+   * and `forgejo.actionsRoot`. All were
    * documented for users and declared nowhere: the config schema is
    * `.passthrough()`, so a typo was accepted and silently ignored, and the
    * `ChantConfig` interface is closed, so the documented examples did not
@@ -680,6 +744,22 @@ export interface LexiconPlugin {
   /** Return post-synthesis checks for build validation */
   postSynthChecks?(): PostSynthCheck[];
 
+  /**
+   * Activity contracts (`ActivityContract`, `./op/activity-contract.ts`) for
+   * the activities this lexicon implements, so another lexicon's post-synth
+   * check can validate an Op step calling one of them (chant #2101).
+   *
+   * The ordinary way to contribute these is the same convention activities
+   * themselves use: export them from
+   * `@intentius/chant-lexicon-<name>/op/activity-contracts`, and
+   * `loadActivityContracts` (`./op/activity-contract-registry.ts`) finds them
+   * with no plugin member at all. This member is the escape hatch for a
+   * lexicon whose contracts are not reachable at that subpath — a bundled
+   * single-file plugin, a project-local one — and both sources are merged
+   * when both are present. Omit it in the common case.
+   */
+  activityContracts?(): ActivityContract[];
+
   /**
    * Audit catalog metadata (title/tier/fix/authority/category) for this
    * lexicon's `postSynthChecks`, keyed by check id — the per-provider half of
@@ -689,6 +769,17 @@ export interface LexiconPlugin {
    */
   auditCatalog?(): Record<string, RuleMeta>;
 
+  /**
+   * Preset name mapped to the post-synth check ids that preset enables
+   * (chant #2113), e.g. `{ recommended: ["TF001", ...], all: ["TF001", ..., "TF011"] }`.
+   * A project selects one via `lint.presets: { "<this lexicon's name>": "<preset>" }`
+   * (`./lint/config.ts`'s `LintConfig.presets`). `resolvePresetIds` and
+   * `applyConfiguredPreset` (same file) do the filtering. Omit for a lexicon
+   * that ships no presets. Its post-synth findings are unaffected by
+   * `lint.presets`, exactly as before this existed.
+   */
+  lintPresets?(): Record<string, string[]>;
+
   /**
    * Parse standalone template content (a file audit discovery classified for
    * this lexicon) into the lexicon's entity graph, keyed the way `ctx.entities`
@@ -696,9 +787,12 @@ export interface LexiconPlugin {
    * `chant audit` of hand-written manifests — parse-to-graph rather than
    * output-reading rule variants (#1567). Implementations must tolerate
    * arbitrary external content: a malformed document yields no entities, never
-   * a throw. Omit for lexicons whose audit checks read `ctx.outputs`.
+   * a throw. Omit for lexicons whose audit checks read `ctx.outputs`. May
+   * return a `Promise` for a lexicon whose parser is inherently async (e.g.
+   * terraform's HCL parser, a lazy-loaded wasm module). `auditLexicon` awaits
+   * it before reading `ctx.entities`.
    */
-  auditEntities?(content: string): Map<string, Declarable>;
+  auditEntities?(content: string): Map<string, Declarable> | Promise<Map<string, Declarable>>;
 
   /**
    * Machine-readable spec-coverage accounting for `check-lexicon` (#1330).
@@ -785,6 +879,18 @@ export interface LexiconPlugin {
     options?: ComponentPipelineOptions,
   ): OpPipelineResult;
 
+  /**
+   * Host Op runs — the seam `chant run <op> --on <this lexicon>` dispatches to
+   * (#2121, epic #2114). Core ships one provider of its own, `local`, and
+   * selects it when no `--on` is passed; a lexicon that can start, watch,
+   * cancel and wake runs somewhere else implements the same contract and
+   * every `chant run` subcommand goes through it unchanged.
+   *
+   * Core never imports a hosting lexicon, so this is the only direction the
+   * dependency runs. Omit for lexicons that host nothing.
+   */
+  readonly opRuntime?: OpRuntimeProvider;
+
   /**
    * Render this lexicon's config-declared build roots into entities (#1548
    * piece 3) — the seam for a build root that is NOT typed chant source. The
@@ -842,7 +948,7 @@ export interface LexiconPlugin {
    * Query deployed resources and return API metadata. Opt-in.
    *
    * Use this when each chant entity has a 1:1 cloud equivalent — e.g. an
-   * AWS CFN resource, a K8s object, an ARM resource, a Temporal namespace.
+   * AWS CFN resource, a K8s object, an ARM resource, a Fly app.
    *
    * **The observation contract (#1089).** Returning nothing for a declared
    * entity is a claim, and there are two different claims to make. Either the
@@ -875,8 +981,8 @@ export interface LexiconPlugin {
    * `entities` carries the chant-side entity declarations for this lexicon,
    * keyed by chant entity name (e.g. the export name from a `*.ts` file).
    * Implementations that need to map cloud-side names back to chant entity
-   * names (e.g. Temporal — server-side namespace `prod` ↔ chant entity `ns`
-   * declared with `name: "prod"`) read this; implementations that already
+   * names (server-side name `prod` ↔ chant entity `ns` declared with
+   * `name: "prod"`) read this; implementations that already
    * have name parity (e.g. AWS CloudFormation logical IDs == chant entity
    * names) can ignore it.
    *

package/src/lifecycle/change-set.test.ts

@@ -8,6 +8,7 @@ import {
   unobservedPlanNotice,
   type ChangeSet,
   type ChangeSetEntry,
+  type HeldEntitySet,
 } from "./change-set";
 import type { ResourceMetadata } from "../lexicon";
 
@@ -589,3 +590,51 @@ describe("renderChangeSetMarkdown (#1983)", () => {
     expect(few).not.toContain("<details>");
   });
 });
+
+// #2162 — a held property is never a `ChangeAction`: it rides beside
+// `entries` on the change set, in its own section, in both renders.
+describe("ChangeSet.held (#2162)", () => {
+  const heldEntities: HeldEntitySet[] = [
+    {
+      name: "web",
+      type: "K8s::Apps::Deployment",
+      lexicon: "k8s",
+      held: [
+        { path: "spec.replicas", by: "hpa", reason: "the autoscaler owns replicas after the first apply", live: 5, suspicious: false },
+      ],
+    },
+  ];
+
+  test("renderChangeSet: a HELD section, separate from every action group", () => {
+    const cs: ChangeSet = { ...set([entry({ action: "noop" })]), held: heldEntities };
+    const out = renderChangeSet(cs);
+    expect(out).toContain("HELD (declared heldElsewhere(); not drift, never proposed for update)");
+    expect(out).toContain("web (K8s::Apps::Deployment) k8s");
+    expect(out).toContain("spec.replicas: held by hpa — 5 (the autoscaler owns replicas after the first apply)");
+  });
+
+  test("renderChangeSetMarkdown: its own section, held entries never counted in the header", () => {
+    const cs: ChangeSet = { ...set([entry({ action: "noop" })]), held: heldEntities };
+    const out = renderChangeSetMarkdown(cs);
+    expect(out).toContain("### HELD (declared heldElsewhere(); not drift, never proposed for update)");
+    expect(out).toContain("`web` (K8s::Apps::Deployment) `k8s`");
+    expect(out).toContain("spec.replicas: held by hpa — 5");
+    // The counts header only ever tallies `ChangeAction`s.
+    expect(out).toContain("0 create, 0 update, 0 effect, 0 delete, 0 adopt, 0 runtime, 1 noop, 0 unobserved");
+  });
+
+  test("a suspicious held property is marked in both renders", () => {
+    const suspicious: HeldEntitySet[] = [
+      { name: "cfg", type: "T", held: [{ path: "A", by: "controller", reason: "x", suspicious: true }] },
+    ];
+    const cs: ChangeSet = { ...set([]), held: suspicious };
+    expect(renderChangeSet(cs)).toContain("[SUSPICIOUS: no live value ever showed up here]");
+    expect(renderChangeSetMarkdown(cs)).toContain("SUSPICIOUS: no live value ever showed up here");
+  });
+
+  test("omitted entirely when nothing is held — no empty section in either render", () => {
+    const cs = set([entry({ action: "noop" })]);
+    expect(renderChangeSet(cs)).not.toContain("HELD");
+    expect(renderChangeSetMarkdown(cs)).not.toContain("HELD");
+  });
+});

package/src/lifecycle/change-set.ts

@@ -15,6 +15,7 @@
 import { diffLive, type AttributeChange, type DiffLiveInput } from "./live-diff";
 import { unobservedReasonText, type UnobservedReason } from "../observation";
 import { renderDisruption, summarizeDisruption, type Disruption } from "./disruption";
+import type { DeepEntityHeld } from "./deep-diff";
 
 /**
  * What the projection proposes for a single resource.
@@ -148,9 +149,22 @@ export interface ChangeSetEntry {
   disruptionDetail?: string;
 }
 
+/** One entity's held properties (#2162), attributed to the lexicon that observed it — a plan merges every lexicon's, so the attribution has to survive the merge the same way {@link ChangeSetEntry.lexicon} does. */
+export interface HeldEntitySet extends DeepEntityHeld {
+  lexicon?: string;
+}
+
 export interface ChangeSet {
   env: string;
   entries: ChangeSetEntry[];
+  /**
+   * Properties declared `heldElsewhere()` (#2162), across every lexicon this
+   * plan checked. Not part of `entries`: a held property is never a proposal
+   * — it carries no `ChangeAction` — so it rides beside the actionable set
+   * rather than inside it, the same way `unobservedPlanNotice` rides beside
+   * rather than inside. Omitted when nothing declared one.
+   */
+  held?: HeldEntitySet[];
 }
 
 /**
@@ -407,9 +421,58 @@ export function renderChangeSet(cs: ChangeSet): string {
     }
   }
 
+  if (cs.held && cs.held.length > 0) {
+    lines.push(`\n${heldSectionLabel()}:`);
+    for (const line of heldLines(cs.held)) lines.push(line);
+  }
+
   return lines.join("\n");
 }
 
+/**
+ * Section heading for the held set (#2162) — shared between {@link renderChangeSet}
+ * and {@link renderChangeSetMarkdown}.
+ */
+function heldSectionLabel(): string {
+  return "HELD (declared heldElsewhere(); not drift, never proposed for update)";
+}
+
+/** One held property's plain-text line, indented under its entity. */
+function heldLines(held: readonly HeldEntitySet[]): string[] {
+  const lines: string[] = [];
+  for (const entity of held) {
+    const lexicon = entity.lexicon ? ` ${entity.lexicon}` : "";
+    lines.push(`  ${entity.name} (${entity.type})${lexicon}`);
+    for (const h of entity.held) {
+      const live = "live" in h ? fmt(h.live) : "<absent>";
+      const suspicious = h.suspicious
+        ? " [SUSPICIOUS: no live value ever showed up here]"
+        : "";
+      lines.push(`      ${h.path}: held by ${h.by} — ${live} (${h.reason})${suspicious}`);
+    }
+  }
+  return lines;
+}
+
+/** One held property's markdown line, mirroring {@link renderMarkdownEntry}'s formatting. */
+function heldLinesMarkdown(held: readonly HeldEntitySet[]): string[] {
+  const lines: string[] = [];
+  for (const entity of held) {
+    const lexicon = entity.lexicon ? ` \`${entity.lexicon}\`` : "";
+    lines.push(`- \`${entity.name}\` (${entity.type})${lexicon}`);
+    if (entity.held.length > 0) {
+      lines.push("  ```");
+      for (const h of entity.held) {
+        const live = "live" in h ? fmt(h.live) : "<absent>";
+        const suspicious = h.suspicious ? "  SUSPICIOUS: no live value ever showed up here" : "";
+        lines.push(`  ${h.path}: held by ${h.by} — ${live} (${h.reason})${suspicious}`);
+      }
+      lines.push("  ```");
+    }
+  }
+  return lines;
+}
+
 /**
  * Entries beyond this in one action group are collapsed into a `<details>`
  * block in {@link renderChangeSetMarkdown} — a group's worth of rows is fine
@@ -500,6 +563,10 @@ export function renderChangeSetMarkdown(cs: ChangeSet): string {
     }
   }
 
+  if (cs.held && cs.held.length > 0) {
+    lines.push("", `### ${heldSectionLabel()}`, "", ...heldLinesMarkdown(cs.held));
+  }
+
   return lines.join("\n").trimEnd() + "\n";
 }
 

package/src/lifecycle/converge-ledger.ts

@@ -28,7 +28,7 @@ const FILENAME = "converge.jsonl";
  * record. A record here is one line of JSON, so a multi-line or unbounded
  * string folded into any field would break the line the ledger is built out
  * of. Every free-text field a tick writes goes through this: a dispatch
- * failure's `stderr` (lexicons/temporal's `sanitizeOneLine`, which delegates
+ * failure's `stderr` (a hosting lexicon's own one-line sanitizer delegates
  * here) and a component verdict's lexicon-authored `detail`.
  */
 const MAX_LEDGER_TEXT_LEN = 300;