@intentius/chant 0.44.14 → 0.46.0

package/src/graph-ops.ts

@@ -0,0 +1,42 @@
+import { basename, resolve } from "node:path";
+import type { Declarable } from "./declarable";
+import { discoverOps } from "./op/discover";
+import { Op } from "./op/builders";
+import { setProvenance } from "./provenance";
+
+/**
+ * #1675 — the graph IR is built from `discover(sourceDir)`, but the Op
+ * convention keeps `*.op.ts` files OUTSIDE `sourceDir` (`ops/` or the project
+ * 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
+ * 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.
+ */
+export async function mergeProjectOps(
+  entities: Map<string, Declarable>,
+  sourceFiles: readonly string[],
+  projectPath: string,
+): Promise<{ added: string[]; errors: string[] }> {
+  const added: string[] = [];
+  let found: Awaited<ReturnType<typeof discoverOps>>;
+  try {
+    found = await discoverOps({ cwd: projectPath });
+  } catch (err) {
+    // Not a git checkout — nothing beyond sourceDir to join.
+    return { added, errors: [err instanceof Error ? err.message : String(err)] };
+  }
+  const loaded = new Set(sourceFiles.map((f) => resolve(f)));
+  for (const { config, filePath } of found.ops.values()) {
+    if (loaded.has(resolve(filePath))) continue;
+    const key = basename(filePath).replace(/\.ts$/, "").replace(/\.op$/, "");
+    if (entities.has(key)) continue;
+    const entity = Op(config) as unknown as Declarable;
+    setProvenance(entity, { sourceFile: resolve(filePath) });
+    entities.set(key, entity);
+    added.push(key);
+  }
+  return { added, errors: found.errors };
+}

package/src/lexicon.ts

@@ -11,12 +11,12 @@ 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 { OwnershipChannel } from "./ownership";
+import type { OwnershipChannel, OwnershipMarker } from "./ownership";
 import type { LexiconConfigSchema } from "./lexicon-config";
 import type { RuleMeta } from "./audit/catalog";
 import type { ReferenceCatalog } from "./graph-refs";
 import type { IREdge } from "./graph-ir";
-import type { DescribeResourcesResult } from "./observation";
+import type { DescribeResourcesResult, UnobservedReason } from "./observation";
 import type { DeepNormalizationHooks, DeepObservationResult } from "./deep-observation";
 import type { OwnerChainVerdict } from "./owner-chain";
 import type { CommandGroup } from "./cli/command-group";
@@ -540,6 +540,23 @@ export interface LexiconPlugin {
    */
   auditCatalog?(): Record<string, RuleMeta>;
 
+  /**
+   * Machine-readable spec-coverage accounting for `check-lexicon` (#1330).
+   *
+   * `coverage()` prints a report for humans; this returns the one fact the
+   * completeness gate cares about: which upstream spec kinds are neither
+   * modeled as declarables nor on the lexicon's exclusion list. fountain held
+   * this line in a lexicon-local vitest assertion (`coverage.test.ts`), which
+   * is a convention rather than a contract — the same class of gap #1342
+   * closed for LSP providers.
+   *
+   * Implementations must work offline from committed snapshots (fountain
+   * reads `spec/fountain-openapi.snapshot.json` plus its surface baseline):
+   * `check-lexicon` runs on every PR, so no network I/O. Omit when the
+   * lexicon has no kind-level spec accounting; the check passes vacuously.
+   */
+  coverageReport?(): Promise<{ unaccountedKinds?: string[] }>;
+
   /** Return intrinsic function definitions */
   intrinsics?(): IntrinsicDef[];
 
@@ -862,6 +879,86 @@ export interface LexiconPlugin {
    */
   describeStackStatus?(options: { environment: string; stack: string }): Promise<StackStatusObservation | null>;
 
+  /**
+   * Enumerate the resources this lexicon would delete for one marker identity
+   * (#1222). Opt-in, and read-only here: this method names the would-delete
+   * set, it never deletes. `chant lifecycle teardown <env>` calls it to plan;
+   * the execution half ({@link executeTeardown}) deletes from the same
+   * enumeration.
+   *
+   * Selection is marker-scoped by construction. `marker` carries this
+   * project's ownership stack plus the requested environment, and every
+   * returned candidate must have been read carrying exactly that identity on
+   * this lexicon's marker channel — managed-by present, stack equal, env
+   * equal. A resource whose marker is absent, foreign-stack, or foreign-env is
+   * not a candidate, ever. Core re-checks each candidate's `marker` and drops
+   * mismatches, so a buggy implementation cannot widen the set.
+   *
+   * The #1089 discipline applies: a kind this lexicon stamps but cannot read
+   * back (no reader for the kind, the read errored, no credentials) is a
+   * `hole`, named with a total {@link UnobservedReason} — never silently
+   * absent, because "absent from the plan" reads as "safe", and an unreadable
+   * kind is unknown, not safe.
+   *
+   * A lexicon without this capability still takes part in teardown planning:
+   * core falls back to {@link describeResources} and filters on
+   * {@link ResourceMetadata.marker}. Implement this when that read is the
+   * wrong shape for deletion — aws, whose thin read carries no tags and whose
+   * teardown is stack-level, is the motivating case.
+   */
+  teardownOwned?(options: {
+    environment: string;
+    /** The identity to select on: this project's ownership stack + the env being torn down. */
+    marker: OwnershipMarker;
+    /** Deployed stack name, for a multi-stack project (see `stacks` in {@link ChantConfig}). */
+    stack?: string;
+    /** Region that stack is deployed in (#1261's contract). */
+    region?: string;
+    /**
+     * Every deployed stack a multi-stack project declares (see `stacks` in
+     * {@link ChantConfig}), for a lexicon whose enumeration is stack-shaped
+     * (aws). When absent or empty, the single-stack convention applies:
+     * `stack`, else the stack named after the environment.
+     */
+    stacks?: Array<{ name: string; region?: string }>;
+  }): Promise<TeardownEnumeration>;
+
+  /**
+   * Delete the teardown candidates core hands over — the execution half of
+   * `chant lifecycle teardown <env> --yes` (#1222). Opt-in, and the sibling of
+   * {@link teardownOwned}: that method names the would-delete set, this one
+   * deletes it. A lexicon that enumerates but does not implement this reports
+   * its candidates as skipped rather than pretending.
+   *
+   * `candidates` is the marker-verified set core computed from the plan — an
+   * implementation deletes those and only those, in whatever order its target
+   * requires (k8s deletes namespaces last; fly deletes apps last). It never
+   * re-widens the set: a live resource not in `candidates` is not this call's
+   * business, whatever its labels say.
+   *
+   * Every candidate gets exactly one outcome per call, keyed by `name`:
+   * `deleted` (including already-gone — deletion is idempotent), `failed`
+   * (the delete errored; core runs one bounded retry pass over these), or
+   * `not-prunable` with a reason (the live object no longer carries the
+   * requested identity, the kind cannot be addressed, the target refuses).
+   * A candidate the implementation says nothing about is reported as failed
+   * by core — silence is never success.
+   */
+  executeTeardown?(options: {
+    environment: string;
+    /** The identity everything was selected on: ownership stack + env. */
+    marker: OwnershipMarker;
+    /** The marker-verified candidates to delete — from {@link teardownOwned} / the plan. */
+    candidates: TeardownCandidate[];
+    /** Deployed stack name, for a multi-stack project (see `stacks` in {@link ChantConfig}). */
+    stack?: string;
+    /** Region that stack is deployed in (#1261's contract). */
+    region?: string;
+    /** Every declared deployed stack, mirroring {@link teardownOwned} — how a
+     * stack-shaped execution (aws) finds each candidate's region. */
+    stacks?: Array<{ name: string; region?: string }>;
+  }): Promise<TeardownExecution>;
+
   /**
    * Where this lexicon can stamp and read chant's ownership marker (#1348).
    * Data, not a method.
@@ -962,6 +1059,74 @@ export interface LexiconPlugin {
   }): Promise<ExportedTemplate>;
 }
 
+/**
+ * One resource {@link LexiconPlugin.teardownOwned} would delete (#1222).
+ * Identity only — no delete happens on this path.
+ */
+export interface TeardownCandidate {
+  /** chant entity name where a declared mapping exists, else the provider-side name. */
+  name: string;
+  /** Resource type (e.g. "AWS::S3::Bucket", "K8s::Apps::Deployment"). */
+  type: string;
+  /** Provider-side identifier, when the read surfaces one. */
+  physicalId?: string;
+  /**
+   * The stack/env identity read off the resource's own marker — read back,
+   * never inferred. Core verifies it equals the requested identity and drops
+   * the candidate otherwise.
+   */
+  marker: OwnershipMarker;
+}
+
+/**
+ * One kind or entity a teardown enumeration could not read (#1089). A hole is
+ * a claim of ignorance, not of absence: the plan must print it loudly, and the
+ * execution half must refuse to call the env clean while holes exist.
+ */
+export interface TeardownHole {
+  /** The unreadable kind or entity name. */
+  name: string;
+  /** Resource type, when known. */
+  type?: string;
+  /** Total verdict — the same vocabulary the observation envelope uses. */
+  reason: UnobservedReason;
+  /** Human-readable detail: the failing command, the unsupported kind. */
+  detail?: string;
+}
+
+/** What {@link LexiconPlugin.teardownOwned} returns: the would-delete set plus its holes. */
+export interface TeardownEnumeration {
+  candidates: TeardownCandidate[];
+  /** Omit or leave empty when every stamped kind was readable. */
+  holes?: TeardownHole[];
+}
+
+/**
+ * One candidate's fate after {@link LexiconPlugin.executeTeardown} (#1222).
+ * `name` keys it back to the candidate it answers for.
+ */
+export interface TeardownOutcome {
+  /** The candidate's `name`, verbatim. */
+  name: string;
+  /** Resource type, when the implementation carries it through. */
+  type?: string;
+  /** Provider-side identifier, when known. */
+  physicalId?: string;
+  /**
+   * - `deleted` — gone, including already-gone (deletion is idempotent);
+   * - `failed` — the delete errored (core retries these once);
+   * - `not-prunable` — deliberately not deleted; `detail` says why.
+   */
+  outcome: "deleted" | "failed" | "not-prunable";
+  /** The error for `failed`, the reason for `not-prunable`. */
+  detail?: string;
+}
+
+/** What {@link LexiconPlugin.executeTeardown} returns: one outcome per candidate. */
+export interface TeardownExecution {
+  outcomes: TeardownOutcome[];
+}
+
 /**
  * The observation view of a lexicon — every capability except live export.
  *
@@ -1047,6 +1212,21 @@ export interface ResourceMetadata {
    * a delete, and never escalates `unknown` to one.
    */
   ownership?: "owned" | "foreign" | "unknown";
+  /**
+   * The stack/env identity read off the resource's own ownership marker
+   * (#1222) — the tags/labels/metadata chant stamped at synthesis, read back
+   * verbatim on the same channel. This is what marker-scoped selection keys
+   * on: {@link ownership} says "chant's", `marker` says *which* stack and env.
+   *
+   * Set only when the live model actually carries the channel and the
+   * managed-by marker is present — an absent channel means an absent field,
+   * never a guess. In particular aws's thin read is sourced from
+   * `describe-stack-resources`, which returns no tags at all, so aws never
+   * populates this here; aws teardown is stack-level and reads the stack's own
+   * tags instead (later PR). A populated `marker` does not by itself imply an
+   * {@link ownership} verdict on paths that do not declare a marker channel.
+   */
+  marker?: OwnershipMarker;
   /**
    * Where this resource's owner-reference chain leads, for a live resource
    * that is not itself declared (#1077). A lexicon that maintains an

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

@@ -346,6 +346,47 @@ describe("buildChangeSet: not-observed is not absent (#1089)", () => {
     expect(e.queried).toBe("from-entry");
   });
 
+  // #1674 — lexicon attribution and the provider's physical id per entry.
+  test("stamps every entry with the lexicon it was built for, when given one", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["web", "api"]),
+      observedNow: { web: meta(), "sg-0abc123": meta({ ownership: "foreign" }) },
+      observedThen: undefined,
+    }, { lexicon: "aws" });
+    expect(cs.entries.map((e) => e.lexicon)).toEqual(["aws", "aws", "aws"]);
+    const without = buildChangeSet("prod", { declared: new Set(["web"]), observedNow: {}, observedThen: undefined });
+    expect(without.entries[0]).not.toHaveProperty("lexicon");
+  });
+
+  test("physicalId comes from the live observation — name stays the lexicon's key", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["web"]),
+      observedNow: {
+        web: meta({ physicalId: "arn:aws:elasticloadbalancing:us-east-1:123:loadbalancer/app/web/abc" }),
+        "sg-0abc123": meta({ physicalId: "sg-0abc123", ownership: "foreign" }),
+        "pod-xyz": meta({ physicalId: "default/pod-xyz", ownerChain: { root: "declared", entity: "web" } }),
+        owned: meta({ physicalId: "i-0deadbeef", ownership: "owned" }),
+      },
+      observedThen: undefined,
+    });
+    const byName = Object.fromEntries(cs.entries.map((e) => [e.name, e]));
+    expect(byName.web.physicalId).toBe("arn:aws:elasticloadbalancing:us-east-1:123:loadbalancer/app/web/abc");
+    expect(byName["sg-0abc123"]).toMatchObject({ action: "adopt", physicalId: "sg-0abc123", name: "sg-0abc123" });
+    expect(byName["pod-xyz"]).toMatchObject({ action: "runtime", physicalId: "default/pod-xyz" });
+    expect(byName.owned).toMatchObject({ action: "delete", physicalId: "i-0deadbeef" });
+  });
+
+  test("physicalId is absent when no side reported one, and falls back to the snapshot's when the resource is gone", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["web"]),
+      observedNow: {},
+      observedThen: { gone: meta({ physicalId: "i-gone" }) },
+    });
+    const byName = Object.fromEntries(cs.entries.map((e) => [e.name, e]));
+    expect(byName.web).not.toHaveProperty("physicalId");
+    expect(byName.gone).toMatchObject({ action: "noop", physicalId: "i-gone" });
+  });
+
   test("a returned resource wins over an unobserved claim for the same name", () => {
     const cs = buildChangeSet("prod", {
       declared: new Set(["queue"]),

package/src/lifecycle/change-set.ts

@@ -45,10 +45,27 @@ export type ChangeAction = "create" | "update" | "delete" | "adopt" | "runtime"
 export type Ownership = "owned" | "foreign" | "unknown";
 
 export interface ChangeSetEntry {
-  /** chant entity name. */
+  /**
+   * chant entity name for a declared entity. For an undeclared live resource
+   * (`adopt`, `delete`, `runtime`) this is the lexicon's live key — not an
+   * IR-joinable entity name; read `physicalId` for the provider id (#1674).
+   */
   name: string;
   /** Resource type, when known from either side. */
   type?: string;
+  /**
+   * The lexicon whose observation produced this entry (#1674). Set when the
+   * change set is built for one lexicon; `lifecycle plan` merges every
+   * lexicon's change set into one `entries[]`, and this is what keeps the
+   * attribution through the merge.
+   */
+  lexicon?: string;
+  /**
+   * Provider-assigned physical id (ARN, resource id, pod name) from the live
+   * observation's `ResourceMetadata.physicalId`, falling back to the snapshot's
+   * when the resource is gone (#1674). Absent when neither side reported one.
+   */
+  physicalId?: string;
   action: ChangeAction;
   /** The three-way evidence the classification was derived from. */
   evidence: {
@@ -101,7 +118,12 @@ export interface ChangeSet {
  * classifies as `unobserved` and nothing else: no `create` is ever synthesized
  * from a read that did not happen.
  */
-export function buildChangeSet(env: string, input: DiffLiveInput): ChangeSet {
+export interface ChangeSetOptions {
+  /** Stamp every entry with the lexicon it was observed by (#1674). */
+  lexicon?: string;
+}
+
+export function buildChangeSet(env: string, input: DiffLiveInput, options?: ChangeSetOptions): ChangeSet {
   const diff = diffLive(input);
   const { declared, observedNow } = input;
   const observedThen = input.observedThen ?? {};
@@ -184,9 +206,15 @@ export function buildChangeSet(env: string, input: DiffLiveInput): ChangeSet {
     // classification above never reads it.
     const queried = unobservedEntry?.queried ?? input.queried?.[name];
 
+    // The provider's id for the row (#1674). Live first; the snapshot's only
+    // when the resource is no longer live (a snapshot-only noop).
+    const physicalId = observedNow[name]?.physicalId ?? observedThen[name]?.physicalId;
+
     entries.push({
       name,
       type,
+      ...(options?.lexicon ? { lexicon: options.lexicon } : {}),
+      ...(physicalId ? { physicalId } : {}),
       action,
       evidence,
       deltas,

package/src/lifecycle/deep-observe.ts

@@ -143,6 +143,10 @@ export function diffDeepObservation(
       normalizedLive[name] = {
         type: liveEntity.type || entity.entityType,
         ...(liveEntity.physicalId ? { physicalId: liveEntity.physicalId } : {}),
+        // Per-path owners (#1189) ride through unchanged; the diff looks them
+        // up by the flattened path, so a keyed list element (`[#name]`) has
+        // no owner today — its raw index path is what the reader recorded.
+        ...(liveEntity.fieldOwners ? { fieldOwners: liveEntity.fieldOwners } : {}),
         properties: normalizeDeepProperties(liveRaw, {
           entityType: liveEntity.type || entity.entityType,
           side: "live",

package/src/lifecycle/index.ts

@@ -13,3 +13,4 @@ export * from "./build-ledger";
 export * from "./build-ledger-store";
 export * from "./oras-referrer-lookup";
 export * from "./status";
+export * from "./teardown";

package/src/lifecycle/observe.ts

@@ -31,6 +31,14 @@ export interface ObserveResult {
   observations: LiveObservation[];
   warnings: string[];
   errors: string[];
+  /**
+   * Run-level notices from the lexicons (#1265), each said once however many
+   * stacks or lexicons reported it — "ownership filter unavailable on this
+   * read path" is the canonical one. Kept apart from `warnings`, which are
+   * per-entity, so a caller can print them where a note belongs: after the
+   * answer, not ahead of it.
+   */
+  notes: string[];
 }
 
 /**
@@ -43,7 +51,14 @@ export interface ObserveResult {
 function qualifyObservation(obs: NormalizedObservation, stackName: string): NormalizedObservation {
   const q = <T>(m: Record<string, T>): Record<string, T> =>
     Object.fromEntries(Object.entries(m).map(([k, v]) => [`${stackName}::${k}`, v]));
-  return { resources: q(obs.resources), unobserved: q(obs.unobserved), queried: q(obs.queried) };
+  return {
+    resources: q(obs.resources),
+    unobserved: q(obs.unobserved),
+    queried: q(obs.queried),
+    notes: obs.notes,
+    // Exports are already keyed by stack (#1279); nothing to qualify.
+    ...(obs.stackExports ? { stackExports: obs.stackExports } : {}),
+  };
 }
 
 /**
@@ -110,6 +125,7 @@ export async function observeResources(
   const observations: LiveObservation[] = [];
   const warnings: string[] = [];
   const errors: string[] = [];
+  const notes: string[] = [];
 
   for (const plugin of plugins) {
     if (!plugin.describeResources) continue;
@@ -200,6 +216,13 @@ export async function observeResources(
           }),
         );
       }
+      // Run-level notices (#1265): one line per distinct note per run,
+      // whatever the stack count. `mergeObservations` already folded the
+      // per-stack copies; this folds across lexicons.
+      for (const note of observed.notes) {
+        const line = `[${plugin.name}] ${note}`;
+        if (!notes.includes(line)) notes.push(line);
+      }
       // What the estate depends on but does not declare (#1273). Read after the
       // managed resources, because the declared observation is the closure's
       // roots — there is nothing to reference out from until it exists.
@@ -260,6 +283,7 @@ export async function observeResources(
           resources: {},
           unobserved: unobservedAll(entityNames, "read-failed", message, entities),
           queried: {},
+          notes: [],
         },
         environment,
         entityNames.length,
@@ -267,7 +291,7 @@ export async function observeResources(
     }
   }
 
-  return { observations, warnings, errors };
+  return { observations, warnings, errors, notes };
 }
 
 /**
@@ -451,5 +475,8 @@ function pushObservation(
       : observed.resources,
     ...(unobservedNames.length > 0 ? { unobserved: observed.unobserved } : {}),
     ...(dependencies.edges.length > 0 ? { edges: dependencies.edges } : {}),
+    ...(observed.stackExports && Object.keys(observed.stackExports).length > 0
+      ? { stackExports: observed.stackExports }
+      : {}),
   });
 }

package/src/lifecycle/replay.ts

@@ -177,6 +177,9 @@ export async function replaySnapshots(
       lexicon,
       resources,
       ...(edges.length > 0 ? { edges } : {}),
+      ...(snapshot.stackExports && Object.keys(snapshot.stackExports).length > 0
+        ? { stackExports: snapshot.stackExports }
+        : {}),
     });
     commit ||= snapshot.commit ?? "";
     // Report the OLDEST timestamp across stacks: a caller asking how stale this

package/src/lifecycle/snapshot.ts

@@ -140,6 +140,7 @@ export async function takeSnapshot(
     let resources: Record<string, ResourceMetadata> = {};
     let artifacts: Record<string, ArtifactMetadata> = {};
     let unobserved: Record<string, UnobservedEntity> = {};
+    let stackExports: Record<string, Record<string, unknown>> | undefined;
 
     try {
       if (plugin.describeResources) {
@@ -163,6 +164,7 @@ export async function takeSnapshot(
         // entity nobody could read must not be recorded as "was not there",
         // because the next diff would then read it back as absent.
         unobserved = observed.unobserved;
+        stackExports = observed.stackExports;
         for (const [name, entry] of Object.entries(unobserved)) {
           warnings.push(`${plugin.name}: not observed — ${formatUnobserved(name, entry)}`);
         }
@@ -258,6 +260,7 @@ export async function takeSnapshot(
         timestamp,
         resources: withDependencies,
         ...(dependencies.edges.length > 0 ? { edges: dependencies.edges } : {}),
+        ...(stackExports && Object.keys(stackExports).length > 0 ? { stackExports } : {}),
         ...(Object.keys(unobserved).length > 0 && { unobserved }),
         ...(Object.keys(artifacts).length > 0 && { artifacts }),
         // Only written when deep. An absent field means identity, which is what