@intentius/chant 0.57.0 → 0.59.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,24 +486,133 @@ 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
- * `issue`/`pull-request`/`merge-request`, none for `report`.
+ * `issue`/`comment`/`pull-request`/`merge-request`, none for `report`.
+ *
+ * `comment` posts the finding on the pull request that triggered the run
+ * (#2231), so unlike every other mode it constrains the trigger: the github
+ * generator refuses it by name on anything but `pull_request`, and the gitlab
+ * and forgejo generators refuse it outright.
+ */
+export type OpFindingMode = "report" | "issue" | "comment" | "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 step a generated Op job runs between the checkout and the
+ * `beforeScript` lines (#2242). Two shapes, matching what a GitHub Actions
+ * step can be: a marketplace action (`uses`, with its `with:` inputs and
+ * `env:`), or a shell line (`run`). The `uses` shape is the reason this
+ * exists at all: `beforeScript` covers everything a shell line can install,
+ * but an action like `aws-actions/configure-aws-credentials` is not a shell
+ * line, and OIDC has no shell equivalent.
+ *
+ * A CI provider with no action concept degrades by name rather than
+ * silently: the gitlab generator refuses a `uses` entry at build time and
+ * emits a `run` entry as an ordinary script line.
  */
-export type OpFindingMode = "report" | "issue" | "pull-request" | "merge-request";
+export type OpSetupStep = OpSetupUsesStep | OpSetupRunStep;
+
+/** A marketplace-action setup step (`uses:` with its inputs). */
+export interface OpSetupUsesStep {
+  /**
+   * `owner/repo[/subpath]@ref`. The ref is required and must not be the
+   * action repository's own default branch — see the github generator's
+   * `assertSetupSteps`, which refuses both at build time.
+   */
+  uses: string;
+  /** The action's inputs, emitted as the step's `with:` mapping. */
+  with?: Record<string, string | number | boolean>;
+  /** Environment for this step alone, emitted as the step's `env:` mapping. */
+  env?: Record<string, string>;
+}
+
+/** A shell setup step, the same shape a `beforeScript` line emits as. */
+export interface OpSetupRunStep {
+  /** The shell line, emitted as the step's `run:`. */
+  run: string;
+  /** Environment for this step alone, emitted as the step's `env:` mapping. */
+  env?: Record<string, 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;
+  /**
+   * Steps this Op's generated job runs between the checkout and the
+   * `beforeScript` lines (#2242), in the order given. Per-Op rather than a
+   * `ComponentPipelineOptions` knob because the setup an Op needs is a
+   * property of that Op: a plan job assumes a read-only role, an apply job
+   * assumes the one that can write.
+   */
+  setup?: OpSetupStep[];
+  /**
+   * Scopes added to the ones this Op's finding-mode already grants (#2242).
+   * Strictly additive: the generator refuses a scope the mode's own set
+   * already names, at any value, so this can neither downgrade nor restate
+   * least privilege, and it refuses `write-all`/`read-all` outright. The
+   * motivating value is `{ "id-token": "write" }`, which no finding-mode
+   * grants and OIDC cannot work without.
+   */
+  permissions?: Record<string, "read" | "write">;
+}
+
+/**
+ * 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. */
@@ -498,8 +621,8 @@ export interface OpPipelineJob {
   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;
 }
@@ -599,6 +722,29 @@ export type BuildRootContributor = (
   ctx: Pick<BuildRootContext, "entities">,
 ) => Promise<BuildRootContribution>;
 
+/**
+ * Where the content handed to `auditEntities` came from (#2217).
+ *
+ * The hook's first argument is the text audit discovery classified for a
+ * lexicon. For most lexicons that is the whole unit of parsing. For terraform
+ * it is not: a root module's `module` blocks name sibling directories, and a
+ * rule about what a CHILD module may contain cannot be answered from one
+ * directory's text. So the discovery facts a lexicon may need to read further
+ * travel with the content.
+ *
+ * `dir` and `baseDir` are set only when discovery walked a local filesystem.
+ * A remote tree fetch leaves both undefined, and a lexicon that finds them
+ * undefined parses the content it was given and nothing else.
+ */
+export interface AuditEntitiesInput {
+  /** The input's path as discovery recorded it, relative to the audited root. `"."` for the root itself. */
+  path: string;
+  /** Absolute path of the directory this input's files were read from. */
+  dir?: string;
+  /** Absolute path of the audited root: the boundary a lexicon may read within. */
+  baseDir?: string;
+}
+
 export interface LexiconPlugin {
   // ── Required ──────────────────────────────────────────────
   /** Human-readable name (e.g. "aws", "gcp") */
@@ -623,8 +769,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 +826,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 +851,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 +869,21 @@ 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`.
+   *
+   * `input` says where the content came from (#2217). It is optional so a
+   * caller can still parse a bare string, and a lexicon that only needs the
+   * text ignores it. A lexicon whose unit of parsing is a directory rather
+   * than a file (terraform: a root module and the local modules it calls)
+   * reads `dir` to descend, and stays inside `baseDir` while doing it.
    */
-  auditEntities?(content: string): Map<string, Declarable>;
+  auditEntities?(
+    content: string,
+    input?: AuditEntitiesInput,
+  ): Map<string, Declarable> | Promise<Map<string, Declarable>>;
 
   /**
    * Machine-readable spec-coverage accounting for `check-lexicon` (#1330).
@@ -785,6 +970,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 +1039,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 +1072,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.
    *
@@ -1040,6 +1237,39 @@ export interface LexiconPlugin {
     region?: string;
   }): Promise<Record<string, ResourceMetadata>>;
 
+  /**
+   * Subscribe to this substrate's own change notifications (#1981), so an
+   * operator tick can run when something moved instead of only when the timer
+   * came round. Optional, and consumed by exactly one caller: `chant
+   * operator`'s loop (`./op/operator.ts`). A lexicon that does not implement
+   * it behaves exactly as it did: the loop keeps its timer and never asks.
+   *
+   * Three rules make the seam honest, and the types are shaped to enforce the
+   * first one rather than describe it.
+   *
+   * - **The signal is a trigger, never a fact.** {@link
+   *   SubscribeChangesOptions.onChange} takes no arguments and returns
+   *   nothing, so there is no channel through which a watch event could reach
+   *   a change set, a snapshot row or a diff line. The tick that follows an
+   *   early wake re-observes and re-derives from scratch, exactly as a
+   *   timer-driven tick does; waking early changes *when* a tick runs and
+   *   nothing about what it concludes.
+   * - **A dropped subscription degrades to the timer and says so.** Report it
+   *   through {@link SubscribeChangesOptions.onError} and stop; the operator
+   *   logs one line and re-subscribes on its next round. Losing the stream
+   *   slows detection back to the interval. It must never stop the loop, and
+   *   must never read as a clean estate.
+   * - **The timer stays.** A signal shortens the sleep, it does not replace
+   *   it, so a substrate that silently stops sending still converges on the
+   *   interval.
+   *
+   * Only implement it where the substrate has a change stream that needs
+   * nothing deployed into the account being observed. See the per-lexicon
+   * verdict table in the operator guide for where that holds and where it does
+   * not.
+   */
+  subscribeChanges?(options: SubscribeChangesOptions): Promise<ChangeSubscription>;
+
   /**
    * Read the full live *property tree* for each declared entity (#1014). Opt-in,
    * and strictly deeper than {@link describeResources}, which reports existence
@@ -1462,6 +1692,56 @@ export interface DependencyObservation {
   edges?: IREdge[];
 }
 
+/**
+ * What {@link LexiconPlugin.subscribeChanges} is handed (#1981).
+ *
+ * `onChange` is the whole payload channel, and it has no payload. That is the
+ * point: a substrate's change notification is a reason to look again, never
+ * evidence of what is there. An implementation that wanted to pass the watch
+ * event through would have nowhere to put it.
+ */
+export interface SubscribeChangesOptions {
+  /** chant environment being watched. Resolves the same binding a read does. */
+  environment: string;
+  /** Directory whose `chant.config.ts` carries the binding. Defaults to cwd. */
+  cwd?: string;
+  /**
+   * Declared entities for this lexicon, keyed by chant entity name. The same
+   * map {@link LexiconPlugin.describeResources} receives, and the bound on
+   * what a subscription may watch. An implementation scopes its streams to the
+   * kinds and namespaces these entities name; it must never subscribe to the
+   * whole substrate. Absent, or empty, means there is nothing in scope to
+   * watch and the implementation should say so through {@link onError} rather
+   * than widening.
+   */
+  entities?: Map<string, { entityType: string; props: Record<string, unknown> }>;
+  /**
+   * Something moved. No arguments, deliberately (see {@link
+   * LexiconPlugin.subscribeChanges}). The caller re-observes from scratch and
+   * nothing about the notification reaches what it reports.
+   */
+  onChange(): void;
+  /**
+   * The subscription died, or could not be established for part of its scope.
+   * Reported once per occurrence; the caller logs it and falls back to its
+   * timer. Never a throw once the subscription is live: a stream that ends is
+   * a degradation, not a crash.
+   */
+  onError?(message: string): void;
+  /** Aborts the subscription. Closing on abort is the implementation's job. */
+  signal: AbortSignal;
+}
+
+/**
+ * A live subscription handed back by {@link LexiconPlugin.subscribeChanges}
+ * (#1981). `close()` releases every stream the subscription holds and resolves
+ * once they are gone; it must be safe to call twice, and safe to call after
+ * the subscription has already died on its own.
+ */
+export interface ChangeSubscription {
+  close(): Promise<void>;
+}
+
 export interface ResourceMetadata {
   /** Entity type (e.g. AWS::S3::Bucket, K8s::Apps::Deployment) */
   type: string;

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";
 }