@intentius/chant 0.57.0 → 0.59.0

package/src/fold-provenance.ts

@@ -0,0 +1,441 @@
+/**
+ * Fold provenance (#2161) — which composite parameter produced which emitted field.
+ *
+ * A composite is the one lossy thing chant emits. It takes a few typed
+ * arguments and expands to several resources, so a return leg that regenerates
+ * source from live produces flat typed resources and the composite is gone. The
+ * projection is not invertible from its output alone, which is the view-update
+ * problem landing on chant's record.
+ *
+ * chant can answer it where a general generator cannot, and for one reason: the
+ * evaluated subset is restricted on purpose. `discovery/fold-import.ts` already
+ * interprets an admissible factory body rather than calling it, so the
+ * expression each member property was WRITTEN as is in hand at build time. The
+ * same pass records where the field came from, in `discovery/param-deps.ts`'s
+ * {@link import("./discovery/param-deps").collectCompositeOrigins}.
+ *
+ * ## Four answers, and the fourth is a real one
+ *
+ * Every emitted path gets one of {@link FoldFieldOrigin}'s four kinds. Three of
+ * them are findings; `unknown` is the fourth, and it is a legal answer rather
+ * than a gap. A build that expanded a composite without interpreting its body
+ * (the run path, a factory outside the admissible subset, a sandboxed child
+ * whose provenance did not survive the wire) knows the field came from a
+ * composite and cannot say which parameter. Recording that is the whole point:
+ * an unknown must never fall through to `direct`, because `direct` licenses
+ * editing the field in the user's source and an unattributed composite field is
+ * exactly the case where that produces a flattened resource.
+ *
+ * `direct` is claimed only where the build has a provenance record AND that
+ * record says no composite expanded the entity. Absence of a record is
+ * `unknown`, never `direct`.
+ *
+ * ## Beside the output, never in it
+ *
+ * The record is build metadata, not declared configuration, and it must not
+ * reach the document an applier writes. It rides two channels, both outside the
+ * apply-bound document, and neither is a new mechanism:
+ *
+ *  - per entity, the non-enumerable symbol-keyed side channel `./provenance.ts`
+ *    already owns, invisible to every serializer and to every spread;
+ *  - per build, {@link import("./build").BuildResult.foldProvenance}, a sibling
+ *    of `buildParams` and `lexiconVersions`.
+ *
+ * Nothing is added to `SerializeContext`. That is the same posture
+ * `./effect-receipt.ts` takes at the same seam, one notch stricter: a receipt
+ * rides `SerializeContext.receipts` so a lexicon MAY render it outside
+ * `Resources`, whereas provenance has no rendering and is simply never handed
+ * to a serializer at all. `fold-provenance-exclusion.test.ts` drives a real
+ * build through a spy serializer and a mock applier to hold that line.
+ *
+ * ## The return leg
+ *
+ * {@link resolveDriftedField} is the consumer. #2160 has already ruled out the
+ * fields nobody declared, so a drifted field reaching it is one source actually
+ * declared, and the origin decides what may be proposed:
+ *
+ *  - a composite parameter: propose changing that parameter, naming the file,
+ *    the composite call and the parameter path. One line, composite intact.
+ *  - a literal the composite fixes: refuse by name. The choice is to
+ *    parameterize the field or stop using the composite there, and neither is
+ *    something chant may pick.
+ *  - a direct declaration: today's behaviour, unchanged.
+ *  - unknown: today's behaviour, and say that is what happened.
+ *
+ * Proposing is as far as this goes. Rewriting a parameter in the user's source
+ * is a source-edit problem (the generator half of `chant import` emits whole
+ * files and nothing maps a property path back to a location in a `.ts` file),
+ * so a proposal here is a described action: it names the file, the composite
+ * call and the parameter path, and performs no edit.
+ */
+
+import { isResourceDeclarable, type Declarable } from "./declarable";
+import { originOfPath, type EntityProvenance, type PathOrigin } from "./provenance";
+import type { DeepEntityDrift, PropertyDrift } from "./lifecycle/deep-diff";
+
+/** Why a field's origin could not be determined. Both are facts about the BUILD, not about the field. */
+export type UnknownOriginReason =
+  /**
+   * A composite expanded the entity and this build did not interpret its body,
+   * so parameter and fixed literal are indistinguishable. The run path, a
+   * factory outside `fold-import.ts`'s admissible subset, and a `propagate()`
+   * key both sides wrote all land here.
+   */
+  | "composite-not-interpreted"
+  /**
+   * The build recorded no provenance for this entity at all, so not even "did a
+   * composite make it" is answerable. A sandboxed child's entities arrive this
+   * way: `discovery/entity-wire-codec.ts` drops build metadata over the wire.
+   */
+  | "no-provenance";
+
+/**
+ * What produced one emitted property path.
+ *
+ * The composite kinds carry `instance` — the export name every member of one
+ * composite call shares — because "the `AutoscaledService` composite" is not an
+ * address and "the `api` call of `AutoscaledService`" is.
+ */
+export type FoldFieldOrigin =
+  | { kind: "composite-parameter"; composite: string; instance?: string; parameters: string[] }
+  | { kind: "composite-literal"; composite: string; instance?: string }
+  | { kind: "direct" }
+  | { kind: "unknown"; reason: UnknownOriginReason };
+
+/** One entity's fold provenance: where it was declared, and an origin for every field it emits. */
+export interface EntityFoldProvenance {
+  /** The source file that declared the entity, when the build recorded one. */
+  sourceFile?: string;
+  /** The composite type that expanded it, when one did. */
+  composite?: string;
+  /** The composite call (export name) it belongs to, when one expanded it. */
+  instance?: string;
+  /**
+   * Emitted property path to origin, in sorted key order. Every path the entity
+   * emits is present: a path with no attribution carries an `unknown` origin
+   * rather than being left out, so a consumer iterating fields never has to
+   * decide what a missing key meant.
+   */
+  fields: Record<string, FoldFieldOrigin>;
+}
+
+/** A whole build's fold provenance, keyed by chant entity name. */
+export type FoldProvenance = Record<string, EntityFoldProvenance>;
+
+/** True for an ordinary `{}`, false for an array, a class instance, an `AttrRef`. */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value) as unknown;
+  return proto === Object.prototype || proto === null;
+}
+
+/**
+ * Every property path an entity's `props` emits, in `EntityProvenance.paths`'
+ * grammar: dotted names only, plain objects descended into, everything else
+ * attributed whole at its own path.
+ *
+ * Arrays are deliberately not indexed. An index-shaped key would not survive an
+ * element moving, and the recorder that produces origins cannot index either,
+ * so indexing here would manufacture paths nothing can ever attribute. The diff
+ * addresses array elements with `[#key]`/`[n]` and `originOfPath` resolves
+ * those against the dotted key that covers them, which is the join between the
+ * two grammars.
+ *
+ * An empty object is a value, and a leaf. An `undefined` value is not emitted
+ * and yields no path.
+ */
+export function emittedFieldPaths(props: unknown): string[] {
+  const out: string[] = [];
+
+  const walk = (value: unknown, prefix: string): void => {
+    if (value === undefined) return;
+    if (isPlainObject(value)) {
+      const keys = Object.keys(value).sort();
+      if (keys.length === 0) {
+        if (prefix) out.push(prefix);
+        return;
+      }
+      for (const key of keys) walk(value[key], prefix ? `${prefix}.${key}` : key);
+      return;
+    }
+    if (prefix) out.push(prefix);
+  };
+
+  walk(props, "");
+  return out;
+}
+
+/**
+ * The four-way answer for one path, from the recorded {@link PathOrigin} and
+ * the entity's own provenance.
+ *
+ * `origin` is what {@link originOfPath} resolved for the path, so a coarse key
+ * recorded at an ancestor governs a leaf, exactly as it does everywhere else.
+ */
+export function classifyFieldOrigin(
+  origin: PathOrigin | undefined,
+  provenance: EntityProvenance | undefined,
+): FoldFieldOrigin {
+  if (!provenance) return { kind: "unknown", reason: "no-provenance" };
+  const instance = provenance.compositeInstance;
+
+  switch (origin?.kind) {
+    case "composite-parameter":
+      return {
+        kind: "composite-parameter",
+        composite: origin.composite,
+        ...(instance ? { instance } : {}),
+        parameters: [...origin.parameters],
+      };
+    case "composite-literal":
+      return { kind: "composite-literal", composite: origin.composite, ...(instance ? { instance } : {}) };
+    case "composite":
+      // The coarse kind: a composite expanded this, and nothing said which
+      // parameter. Not a parameter, not a fixed literal, and above all not a
+      // direct declaration.
+      return { kind: "unknown", reason: "composite-not-interpreted" };
+    case "authored":
+    case "build-param":
+      // A build parameter governs the expression the AUTHOR wrote in their own
+      // source, so the declaration is still theirs to edit.
+      return { kind: "direct" };
+    case undefined:
+      return provenance.composite
+        ? { kind: "unknown", reason: "composite-not-interpreted" }
+        : { kind: "direct" };
+  }
+}
+
+/** One entity's fold provenance, or `undefined` when it emits no properties at all. */
+export function foldProvenanceOfEntity(
+  entity: Declarable,
+  provenance: EntityProvenance | undefined,
+): EntityFoldProvenance | undefined {
+  if (!isResourceDeclarable(entity)) return undefined;
+  const paths = emittedFieldPaths(entity.props);
+  if (paths.length === 0) return undefined;
+
+  const fields: Record<string, FoldFieldOrigin> = {};
+  for (const path of paths) {
+    fields[path] = classifyFieldOrigin(originOfPath(provenance?.paths, path), provenance);
+  }
+
+  return {
+    ...(provenance?.sourceFile ? { sourceFile: provenance.sourceFile } : {}),
+    ...(provenance?.composite ? { composite: provenance.composite } : {}),
+    ...(provenance?.compositeInstance ? { instance: provenance.compositeInstance } : {}),
+    fields,
+  };
+}
+
+/**
+ * A whole build's fold provenance.
+ *
+ * `provenanceOf` is injected rather than read off the entity here so the same
+ * function serves a build (where it is `getProvenance`) and a test with a
+ * hand-written record. Entities with no properties are absent; sorted, because
+ * a build's outputs are compared byte for byte.
+ */
+export function foldProvenanceOfEntities(
+  entities: ReadonlyMap<string, Declarable>,
+  provenanceOf: (entity: Declarable) => EntityProvenance | undefined,
+): FoldProvenance {
+  const out: FoldProvenance = {};
+  for (const name of [...entities.keys()].sort()) {
+    const entity = entities.get(name) as Declarable;
+    const record = foldProvenanceOfEntity(entity, provenanceOf(entity));
+    if (record) out[name] = record;
+  }
+  return out;
+}
+
+/** One-line rendering of a field origin, for a report. */
+export function describeFoldFieldOrigin(origin: FoldFieldOrigin): string {
+  switch (origin.kind) {
+    case "composite-parameter":
+      return `parameter ${origin.parameters.join(", ")} of ${compositeCall(origin.composite, origin.instance)}`;
+    case "composite-literal":
+      return `fixed by ${compositeCall(origin.composite, origin.instance)}`;
+    case "direct":
+      return "declared directly";
+    case "unknown":
+      return `origin unknown (${unknownOriginText(origin.reason)})`;
+  }
+}
+
+/** Why an origin could not be determined, in words a report can print. */
+export function unknownOriginText(reason: UnknownOriginReason): string {
+  switch (reason) {
+    case "composite-not-interpreted":
+      return "expanded by a composite whose factory this build did not interpret";
+    case "no-provenance":
+      return "this build recorded no provenance for the entity";
+  }
+}
+
+/** `AutoscaledService composite call \`api\``, or just the composite when the call has no name. */
+function compositeCall(composite: string, instance: string | undefined): string {
+  return instance ? `the \`${instance}\` call of composite ${composite}` : `composite ${composite}`;
+}
+
+/** `in src/app.infra.ts`, or nothing when the build recorded no file. */
+function inFile(sourceFile: string | undefined): string {
+  return sourceFile ? ` in ${sourceFile}` : "";
+}
+
+/** A value as a report prints it. */
+function renderValue(value: unknown): string {
+  if (value === undefined) return "unset";
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
+/**
+ * What the return leg may do about one drifted field.
+ *
+ * Every arm is a DESCRIBED action. Nothing here edits a file, and
+ * `propose-parameter` deliberately stops at naming the edit: the source-edit
+ * half is the generator side of `chant import` and does not exist yet.
+ */
+export type DriftResolution =
+  | {
+      kind: "propose-parameter";
+      composite: string;
+      instance?: string;
+      sourceFile?: string;
+      /** The factory parameter paths that govern the field. */
+      parameters: string[];
+      description: string;
+    }
+  | {
+      kind: "refuse-fixed";
+      composite: string;
+      instance?: string;
+      sourceFile?: string;
+      description: string;
+    }
+  | { kind: "edit-declaration"; sourceFile?: string; description: string }
+  | { kind: "fall-back"; reason: UnknownOriginReason; sourceFile?: string; description: string };
+
+/** One drifted field and what may be done about it. */
+export interface FieldReconcile {
+  entity: string;
+  path: string;
+  declared?: unknown;
+  live?: unknown;
+  origin: FoldFieldOrigin;
+  resolution: DriftResolution;
+}
+
+/**
+ * Classify one drifted field by its origin.
+ *
+ * The caller has already established this is drift in #2160's sense: a path
+ * source declared, whose live value moved. Undeclared fields are held
+ * elsewhere and never reach here, so the only question left is which of the
+ * four origins produced the field.
+ */
+export function resolveDriftedField(input: {
+  entity: string;
+  path: string;
+  declared?: unknown;
+  live?: unknown;
+  origin?: PathOrigin;
+  provenance?: EntityProvenance;
+}): FieldReconcile {
+  const origin = classifyFieldOrigin(input.origin, input.provenance);
+  const sourceFile = input.provenance?.sourceFile;
+  const move = `${renderValue(input.declared)} to ${renderValue(input.live)}`;
+
+  const resolution: DriftResolution = ((): DriftResolution => {
+    switch (origin.kind) {
+      case "composite-parameter": {
+        const parameters = origin.parameters;
+        return {
+          kind: "propose-parameter",
+          composite: origin.composite,
+          ...(origin.instance ? { instance: origin.instance } : {}),
+          ...(sourceFile ? { sourceFile } : {}),
+          parameters: [...parameters],
+          description:
+            `change ${parameters.length === 1 ? "parameter" : "parameters"} ` +
+            `${parameters.map((p) => `\`${p}\``).join(", ")} of ` +
+            `${compositeCall(origin.composite, origin.instance)}${inFile(sourceFile)} ` +
+            `so \`${input.path}\` moves from ${move}. The composite stays.`,
+        };
+      }
+      case "composite-literal":
+        return {
+          kind: "refuse-fixed",
+          composite: origin.composite,
+          ...(origin.instance ? { instance: origin.instance } : {}),
+          ...(sourceFile ? { sourceFile } : {}),
+          description:
+            `refused: \`${input.path}\` is fixed by ${compositeCall(origin.composite, origin.instance)}` +
+            `${inFile(sourceFile)}, so no argument at the call site moves it. ` +
+            `Parameterize the field in composite ${origin.composite}, or stop using the composite here.`,
+        };
+      case "direct":
+        return {
+          kind: "edit-declaration",
+          ...(sourceFile ? { sourceFile } : {}),
+          description: `change the declared value of \`${input.path}\`${inFile(sourceFile)} from ${move}.`,
+        };
+      case "unknown":
+        return {
+          kind: "fall-back",
+          reason: origin.reason,
+          ...(sourceFile ? { sourceFile } : {}),
+          description:
+            `origin unknown (${unknownOriginText(origin.reason)}), so falling back to changing the ` +
+            `declared value of \`${input.path}\`${inFile(sourceFile)} from ${move}.`,
+        };
+    }
+  })();
+
+  return {
+    entity: input.entity,
+    path: input.path,
+    ...("declared" in input ? { declared: input.declared } : {}),
+    ...("live" in input ? { live: input.live } : {}),
+    origin,
+    resolution,
+  };
+}
+
+/**
+ * Every drifted field in a deep diff, classified.
+ *
+ * Reads `drifted` only. `unclaimed` is somebody else's field and
+ * `accepted` is a difference the baseline holds back, and neither may become an
+ * update, so neither is offered a resolution.
+ *
+ * A drift row of kind `absent` has no live value: the field is declared and the
+ * cloud does not have it. That is still drift on a declared path, and the same
+ * four origins decide what may be proposed about it.
+ */
+export function resolveDeepDrift(
+  drifted: readonly DeepEntityDrift[],
+  provenanceOf: (entity: string) => EntityProvenance | undefined,
+): FieldReconcile[] {
+  const out: FieldReconcile[] = [];
+  for (const entity of drifted) {
+    const provenance = provenanceOf(entity.name);
+    for (const change of entity.changes as readonly PropertyDrift[]) {
+      out.push(
+        resolveDriftedField({
+          entity: entity.name,
+          path: change.path,
+          ...("declared" in change ? { declared: change.declared } : {}),
+          ...("live" in change ? { live: change.live } : {}),
+          ...(change.origin ? { origin: change.origin } : {}),
+          ...(provenance ? { provenance } : {}),
+        }),
+      );
+    }
+  }
+  return out;
+}

package/src/graph-ops.test.ts

@@ -50,14 +50,14 @@ describe("mergeProjectOps (#1675)", () => {
 
     const ir = buildGraphIr(result.entities, root);
     const node = ir.nodes.find((n) => n.id === "deploy");
-    expect(node).toMatchObject({ kind: "Temporal::Op", lexicon: "temporal", sourceLoc: { file: "deploy.op.ts" } });
+    expect(node).toMatchObject({ kind: "Chant::Op", lexicon: "chant", sourceLoc: { file: "deploy.op.ts" } });
     expect(node?.attrs.name).toBe("deploy");
     expect(node?.attrs.depends).toEqual(["inner"]);
     expect(node?.attrs.phases).toEqual([
-      { name: "Apply", steps: [{ kind: "activity", fn: "build" }, { kind: "gate", signalName: "approve" }] },
+      { name: "Apply", steps: [{ kind: "activity", fn: "build" }, { kind: "gate", gate: "approve" }] },
     ]);
     // The sourceDir op discovery already loaded is untouched, not duplicated.
-    expect(ir.nodes.filter((n) => n.kind === "Temporal::Op")).toHaveLength(2);
+    expect(ir.nodes.filter((n) => n.kind === "Chant::Op")).toHaveLength(2);
   });
 
   test("is idempotent — a second merge adds nothing", async () => {

package/src/graph-ops.ts

@@ -10,7 +10,7 @@ import { setProvenance } from "./provenance";
  * root beside `sourceDir: "src"`), and `chant op` / `chant graph` find them via
  * {@link discoverOps}, which scans from the git root. Join the two scopes: every
  * Op `discoverOps` finds that discovery did not already load becomes a
- * `Temporal::Op` entity in the map, keyed the way discovery keys a default
+ * `Chant::Op` entity in the map, keyed the way discovery keys a default
  * export (the file's basename sans `.op.ts`), so the IR carries the declared
  * DAG whatever the layout. Ops discovery already loaded (same file) are left
  * alone. Returns the op-discovery errors for the caller to surface.

package/src/held-elsewhere.test.ts

@@ -0,0 +1,102 @@
+/**
+ * `heldElsewhere()` (#2162) — the runtime marker itself, its JSON-safe
+ * normalized form, and the type-checking contract the compile-time-only
+ * section proves against a real generated-style property interface.
+ */
+
+import { describe, test, expect } from "vitest";
+import {
+  HELD_ELSEWHERE_MARKER,
+  HELD_ELSEWHERE_TAG,
+  heldElsewhere,
+  isHeldElsewhere,
+  isNormalizedHeldElsewhere,
+  normalizeHeldElsewhere,
+} from "./held-elsewhere";
+
+describe("heldElsewhere()", () => {
+  test("returns a marker carrying by/reason, symbol-tagged", () => {
+    const marker = heldElsewhere<number>({ by: "hpa", reason: "the autoscaler owns replicas after the first apply" });
+    expect(isHeldElsewhere(marker)).toBe(true);
+    expect((marker as unknown as { by: string }).by).toBe("hpa");
+    expect((marker as unknown as { reason: string }).reason).toBe("the autoscaler owns replicas after the first apply");
+  });
+
+  test("isHeldElsewhere is false for an ordinary value and for a lookalike object missing the symbol", () => {
+    expect(isHeldElsewhere(3)).toBe(false);
+    expect(isHeldElsewhere(undefined)).toBe(false);
+    expect(isHeldElsewhere(null)).toBe(false);
+    // Same shape, no marker: a plain object an author happened to write with
+    // `by`/`reason` keys must never be mistaken for the real thing.
+    expect(isHeldElsewhere({ by: "hpa", reason: "not actually held" })).toBe(false);
+  });
+
+  test("the marker's own symbol key never enumerates through Object.entries/JSON.stringify", () => {
+    const marker = heldElsewhere<number>({ by: "hpa", reason: "x" });
+    expect(Object.entries(marker as unknown as object)).toEqual([
+      ["by", "hpa"],
+      ["reason", "x"],
+    ]);
+    // The marker key is invisible to a JSON round-trip — this is exactly why
+    // `deep-observation.ts` normalizes it to a JSON-safe tagged form instead
+    // of relying on the symbol surviving a `--json` snapshot.
+    expect(JSON.parse(JSON.stringify(marker))).toEqual({ by: "hpa", reason: "x" });
+  });
+
+  test("HELD_ELSEWHERE_MARKER is the well-known chant symbol, stable across module instances", () => {
+    expect(HELD_ELSEWHERE_MARKER).toBe(Symbol.for("chant.heldElsewhere"));
+  });
+});
+
+describe("normalizeHeldElsewhere() / isNormalizedHeldElsewhere()", () => {
+  test("normalizes to a JSON-safe tagged object", () => {
+    const marker = heldElsewhere<number>({ by: "hpa", reason: "x" });
+    const normalized = normalizeHeldElsewhere(marker as never);
+    expect(normalized).toEqual({ heldElsewhere: HELD_ELSEWHERE_TAG, by: "hpa", reason: "x" });
+    expect(isNormalizedHeldElsewhere(normalized)).toBe(true);
+    // Round-trips through JSON — this is the shape that actually rides in
+    // `--json` output, unlike the symbol-tagged runtime marker above.
+    expect(isNormalizedHeldElsewhere(JSON.parse(JSON.stringify(normalized)))).toBe(true);
+  });
+
+  test("isNormalizedHeldElsewhere rejects an ordinary object and the un-normalized runtime marker", () => {
+    expect(isNormalizedHeldElsewhere({ by: "hpa", reason: "x" })).toBe(false);
+    expect(isNormalizedHeldElsewhere(heldElsewhere<number>({ by: "hpa", reason: "x" }))).toBe(false);
+  });
+});
+
+// ── Compile-time-only: authoring-time type errors (never executed) ──────────
+//
+// A generated resource's props interface, shaped like a real lexicon's
+// generated constructor argument (chant #2162's whole point: `heldElsewhere`
+// must typecheck in exactly the position the property's own value would go,
+// and nowhere else).
+interface DeploymentSpecProps {
+  replicas?: number;
+  image: string;
+}
+
+function _typeChecksOnly(): void {
+  // The success case: assignable where the property's own value goes,
+  // exactly like a literal `replicas: 3` would be.
+  const ok: DeploymentSpecProps = {
+    image: "my-app:latest",
+    replicas: heldElsewhere({ by: "hpa", reason: "the autoscaler owns replicas after the first apply" }),
+  };
+  void ok;
+
+  const badType: DeploymentSpecProps = {
+    image: "my-app:latest",
+    // @ts-expect-error — replicas is a number; heldElsewhere<string>() does not typecheck against it.
+    replicas: heldElsewhere<string>({ by: "hpa", reason: "x" }),
+  };
+  void badType;
+
+  const badProperty: DeploymentSpecProps = {
+    image: "my-app:latest",
+    // @ts-expect-error — "nope" is not a key of DeploymentSpecProps at all.
+    nope: heldElsewhere({ by: "hpa", reason: "x" }),
+  };
+  void badProperty;
+}
+void _typeChecksOnly;

package/src/held-elsewhere.ts

@@ -0,0 +1,114 @@
+/**
+ * `heldElsewhere` — a typed, per-property declaration that a field belongs to
+ * something else once the first apply happens (chant #2162).
+ *
+ * An autoscaler owns a Deployment's `replicas` after the first apply. A
+ * controller writes an annotation on every sync. An operator was granted one
+ * knob deliberately. None of these are drift, and reconciling them back to
+ * whatever chant last declared would fight the thing that is actually
+ * supposed to own the field.
+ *
+ * Terraform's answer is `lifecycle { ignore_changes = [...] }`: a list of
+ * strings, carrying no reason, invisible once written. This is the typed
+ * alternative — a marker written where the property's value would go, so a
+ * lexicon's generated types check it the same way they check any other value,
+ * and it cannot be attached to a property that does not exist.
+ *
+ * This is not a suppression comment. `chant-ignore` (#2111) hides a *lint*
+ * finding about source; a `heldElsewhere` marker is a fact about who operates
+ * a field at *runtime*, so it lives in the typed declaration, where
+ * `chant lifecycle plan` and `chant lifecycle diff --live` can render it,
+ * rather than in a comment only a linter reads.
+ */
+
+/**
+ * Runtime-only marker, symbol-keyed so it never collides with a real
+ * property actually named `by` or `reason` and never serializes by accident
+ * through `JSON.stringify` or `Object.entries` (which do not visit symbol
+ * keys) — the two places a stray plain-object marker would otherwise leak
+ * into a snapshot or a wire payload unnoticed.
+ */
+export const HELD_ELSEWHERE_MARKER = Symbol.for("chant.heldElsewhere");
+
+export interface HeldElsewhereOptions {
+  /** Who holds the field at runtime — the autoscaler, the controller, the operator. Free text: whatever names the holder on this substrate ("hpa", "cluster-autoscaler", "the on-call operator who set this by hand"). */
+  by: string;
+  /** Why chant does not reconcile this field after the first apply. */
+  reason: string;
+}
+
+/** The runtime shape a `heldElsewhere()` call actually produces. */
+export interface HeldElsewhereMarker extends HeldElsewhereOptions {
+  readonly [HELD_ELSEWHERE_MARKER]: true;
+}
+
+/**
+ * Declare a property held by something else after the first apply.
+ *
+ * Typed `T` — the property's own declared type — rather than
+ * `HeldElsewhereMarker`, so it type-checks in exactly the position the
+ * property's real value would go: `replicas: heldElsewhere({ by: "hpa",
+ * reason: "the autoscaler owns replicas after the first apply" })` against a
+ * generated `replicas?: number` typechecks the same way `replicas: 3` does,
+ * and writing it against a property that does not exist on the resource's
+ * props is an excess-property error like any other.
+ *
+ * The runtime value is the marker object, not a `T` — this function tells
+ * TypeScript otherwise on purpose. Every consumer that must tell the two
+ * apart checks {@link isHeldElsewhere} before trusting a declared value's
+ * real shape: the synth-time serializer (`serializer-walker.ts`, which omits
+ * the field from the applied payload so the property is never sent — the
+ * provider defaults it once at creation, and the holder owns it from there)
+ * and the deep-diff declared side (`deep-observation.ts`/`deep-diff.ts`,
+ * which reports a live difference as held rather than as drift).
+ */
+export function heldElsewhere<T>(opts: HeldElsewhereOptions): T {
+  const marker: HeldElsewhereMarker = {
+    [HELD_ELSEWHERE_MARKER]: true,
+    by: opts.by,
+    reason: opts.reason,
+  };
+  return marker as unknown as T;
+}
+
+/**
+ * True when `value` is a {@link HeldElsewhereMarker} — the runtime shape a
+ * `heldElsewhere()` call produces, wherever it ends up (a resource's own
+ * prop, nested inside a property-kind Declarable's props).
+ */
+export function isHeldElsewhere(value: unknown): value is HeldElsewhereMarker {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Record<symbol, unknown>)[HELD_ELSEWHERE_MARKER] === true
+  );
+}
+
+/**
+ * JSON-safe tag a held marker normalizes to (see `deep-observation.ts`) so
+ * its identity survives normalization, `flattenDeepProperties`, and a
+ * `--json` round-trip. The symbol marker above does not serialize and
+ * `Object.entries` does not enumerate it, so without a JSON-safe stand-in the
+ * normalization pass would flatten `{ by, reason }` into two ordinary leaf
+ * paths instead of keeping the marker recognizable as one value.
+ */
+export const HELD_ELSEWHERE_TAG = "chant:heldElsewhere" as const;
+
+/** The normalized, JSON-safe form of a {@link HeldElsewhereMarker}. */
+export interface NormalizedHeldElsewhere extends HeldElsewhereOptions {
+  readonly heldElsewhere: typeof HELD_ELSEWHERE_TAG;
+}
+
+/** Normalize a runtime marker to its JSON-safe tagged form. */
+export function normalizeHeldElsewhere(marker: HeldElsewhereMarker): NormalizedHeldElsewhere {
+  return { heldElsewhere: HELD_ELSEWHERE_TAG, by: marker.by, reason: marker.reason };
+}
+
+/** True when `value` is the normalized, JSON-safe tagged form of a held marker. */
+export function isNormalizedHeldElsewhere(value: unknown): value is NormalizedHeldElsewhere {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { heldElsewhere?: unknown }).heldElsewhere === HELD_ELSEWHERE_TAG
+  );
+}