@intentius/chant 0.49.0 → 0.51.0

package/src/provenance.ts

@@ -5,9 +5,11 @@
  * entity object, so it never serializes into the emitted YAML/JSON — it is build
  * metadata, not declared configuration. Read it back with {@link getProvenance}.
  *
- * This is entity-level provenance (which file declared it, and which composite
- * expanded it), not a YAML-line source map. It answers "where did this resource
- * come from?", which is the question an agent asks before changing it.
+ * Entity-level provenance (which file declared it, and which composite expanded
+ * it) answers "where did this resource come from?", which is the question an
+ * agent asks before changing it. {@link PathOrigin} (chant #1443) answers the
+ * follow-up — "what set THIS field" — for the paths a build can attribute
+ * without guessing. Neither is a YAML-line source map.
  *
  * {@link BuildParamProvenance} (chant #1064) is the other half: not "where did
  * this ENTITY come from" but "what INPUTS was this whole BUILD invoked with" —
@@ -30,6 +32,58 @@ export interface EntityProvenance {
    * collapse a composite to a single node at coarse diagram detail levels (#494).
    */
   compositeInstance?: string;
+  /**
+   * Per-path origins within the entity's `props` (chant #1443). Read with
+   * {@link originOfPath}, which does the prefix resolution these keys are
+   * written for.
+   *
+   * Keys are dotted property paths only — `spec.template.spec.containers` —
+   * with `""` for the whole entity. They never carry an array segment, because
+   * a producing mechanism attributes a whole array at once: the coarsest path
+   * it actually determines is the honest one to record, and a positional key
+   * would go stale the moment an element moved.
+   *
+   * Query paths come from #1441's diff addressing and may carry `[#key]` for an
+   * element of an associative list or `[n]` for a positional one. Resolution is
+   * longest segment-boundary prefix, so `spec.containers[#app].image` finds a
+   * key recorded at `spec.containers`, and a key recorded at
+   * `spec.containers.image` never matches it. The two grammars agree without
+   * the recorder needing the lexicon's ordering hook, which it has no access to.
+   *
+   * Absent means this build could not record path origins, not that nothing
+   * governs the entity's fields — the run path executes modules and has no
+   * expression to inspect, and a sandboxed child's provenance does not survive
+   * the wire (`discovery/entity-wire-codec.ts` drops build metadata).
+   */
+  paths?: Record<string, PathOrigin>;
+}
+
+/**
+ * What produced one path inside an entity's props.
+ *
+ * - `authored` — written in the source file that declared the entity.
+ * - `composite` — the entity was expanded by a composite, or the path was
+ *   supplied by `propagate()`'s shared props at the instance.
+ * - `build-param` — the build parameters the authored expression for this path
+ *   *reads*, which is a syntactic dependency, not a value taint. For
+ *   `replicas: params.tier === "prod" ? 5 : 1` a taint says the value came from
+ *   the literal `5`, which is true and useless; the dependency says the field
+ *   is governed by `tier`, which is what an editor needs to know. Under-reports
+ *   (a shape the collector does not follow drops a dependency) and never
+ *   over-reports a parameter the expression does not mention.
+ */
+export type PathOrigin =
+  | { kind: "authored" }
+  | { kind: "composite"; composite: string; instance: string }
+  | { kind: "build-param"; params: string[] };
+
+/** True when `prefix` addresses `path` or an ancestor of it, on a segment boundary. */
+function isPathPrefix(prefix: string, path: string): boolean {
+  if (prefix === "") return true;
+  if (!path.startsWith(prefix)) return false;
+  if (path.length === prefix.length) return true;
+  const next = path[prefix.length];
+  return next === "." || next === "[";
 }
 
 /**
@@ -44,10 +98,16 @@ export function setProvenance(entity: object, prov: EntityProvenance): void {
     existing.sourceFile ??= prov.sourceFile;
     existing.composite ??= prov.composite;
     existing.compositeInstance ??= prov.compositeInstance;
+    if (prov.paths) {
+      existing.paths ??= {};
+      for (const [path, origin] of Object.entries(prov.paths)) {
+        existing.paths[path] ??= origin;
+      }
+    }
     return;
   }
   Object.defineProperty(entity, PROVENANCE, {
-    value: { ...prov },
+    value: { ...prov, ...(prov.paths ? { paths: { ...prov.paths } } : {}) },
     enumerable: false,
     writable: true,
     configurable: true,
@@ -59,6 +119,60 @@ export function getProvenance(entity: object): EntityProvenance | undefined {
   return (entity as Record<symbol, unknown>)[PROVENANCE] as EntityProvenance | undefined;
 }
 
+/**
+ * Record one path's origin, first writer wins — the same rule
+ * {@link setProvenance} applies to entity-level fields, and for the same
+ * reason: expansion runs innermost-composite-first, so the earliest writer is
+ * the most specific one.
+ */
+export function setPathProvenance(entity: object, path: string, origin: PathOrigin): void {
+  setProvenance(entity, { paths: { [path]: origin } });
+}
+
+/**
+ * An entity's recorded path origins in sorted key order, or `undefined` when
+ * none were recorded. Sorted because a build's outputs are compared byte for
+ * byte and object key order is not something insertion should decide.
+ */
+export function getPathProvenance(entity: object): Record<string, PathOrigin> | undefined {
+  const paths = getProvenance(entity)?.paths;
+  if (!paths) return undefined;
+  const keys = Object.keys(paths).sort();
+  if (keys.length === 0) return undefined;
+  const out: Record<string, PathOrigin> = {};
+  for (const key of keys) out[key] = paths[key];
+  return out;
+}
+
+/**
+ * The origin governing `path` — the longest recorded key that addresses it or
+ * one of its ancestors. See {@link PROVENANCE_PATH_GRAMMAR}.
+ */
+export function originOfPath(
+  paths: Readonly<Record<string, PathOrigin>> | undefined,
+  path: string,
+): PathOrigin | undefined {
+  if (!paths) return undefined;
+  let best: string | undefined;
+  for (const key of Object.keys(paths)) {
+    if (!isPathPrefix(key, path)) continue;
+    if (best === undefined || key.length > best.length) best = key;
+  }
+  return best === undefined ? undefined : paths[best];
+}
+
+/** One-line rendering of an origin, for diff output. */
+export function describePathOrigin(origin: PathOrigin): string {
+  switch (origin.kind) {
+    case "authored":
+      return "authored";
+    case "composite":
+      return `composite ${origin.composite} (${origin.instance})`;
+    case "build-param":
+      return `param ${origin.params.join(", ")}`;
+  }
+}
+
 /**
  * One resolved build-time parameter (chant #1064, see ../build-params.ts): its
  * final value and which source won it, so a build's parameter inputs are

package/src/runtime-adapter.ts

@@ -34,8 +34,13 @@ export interface RuntimeAdapter {
   readonly hashAlgorithm: string;
   /** Test whether filePath matches a glob pattern */
   globMatch(pattern: string, filePath: string): boolean;
-  /** Spawn a child process and collect output */
-  spawn(cmd: string[], opts?: { cwd?: string }): Promise<SpawnResult>;
+  /**
+   * Spawn a child process and collect output. When `opts.stdin` is set, it is
+   * written to the child's stdin and the stream is closed — the caller never
+   * needs to round-trip content through a shell (`sh -c "echo … | cmd"`) just
+   * to feed a command that reads from stdin (e.g. `git hash-object --stdin`).
+   */
+  spawn(cmd: string[], opts?: { cwd?: string; stdin?: string }): Promise<SpawnResult>;
   /** Commands to use when spawning package manager / executor */
   readonly commands: RuntimeCommands;
 }
@@ -59,16 +64,32 @@ class NodeRuntimeAdapter implements RuntimeAdapter {
     return picomatch(pattern)(filePath);
   }
 
-  async spawn(cmd: string[], opts?: { cwd?: string }): Promise<SpawnResult> {
+  async spawn(cmd: string[], opts?: { cwd?: string; stdin?: string }): Promise<SpawnResult> {
     return new Promise((resolve) => {
-      execFile(cmd[0], cmd.slice(1), { cwd: opts?.cwd, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
-        resolve({
-          stdout: stdout ?? "",
-          stderr: stderr ?? "",
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          exitCode: err ? (err as any).code ?? 1 : 0,
+      const child = execFile(
+        cmd[0],
+        cmd.slice(1),
+        { cwd: opts?.cwd, maxBuffer: 10 * 1024 * 1024 },
+        (err, stdout, stderr) => {
+          resolve({
+            stdout: stdout ?? "",
+            stderr: stderr ?? "",
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            exitCode: err ? (err as any).code ?? 1 : 0,
+          });
+        },
+      );
+      // Content is written verbatim (utf-8) — no shell involved, so nothing
+      // reinterprets backslash-escape sequences or needs quote-escaping.
+      // The error handler is load-bearing: a child that exits without reading
+      // stdin (any command that ignores it) makes this write race the pipe
+      // teardown, and an unhandled EPIPE 'error' event crashes the process.
+      if (child.stdin) {
+        child.stdin.on("error", () => {
+          /* EPIPE: child exited without consuming stdin — harmless */
         });
-      });
+        child.stdin.end(opts?.stdin ?? "");
+      }
     });
   }
 }

package/src/serializer.ts

@@ -42,6 +42,24 @@ export interface SerializerResult {
   primary: string;
   /** Additional files keyed by filename (e.g. "network.template.json" → content) */
   files?: Record<string, string>;
+  /**
+   * Basenames from `files` that must reach disk byte-for-byte — never
+   * `JSON.parse`d, key-sorted, or reformatted to YAML by the build's
+   * additional-file writer (chant#1937).
+   *
+   * A separate field rather than a per-file flag on `files` (e.g. widening
+   * its value to `string | { content: string; verbatim: boolean }`) so every
+   * existing lexicon serializer that returns `files: Record<string, string>`
+   * keeps compiling and behaving unchanged: this list defaults to empty, and
+   * only a serializer that actually carries opaque/pre-formatted bytes
+   * (committed ciphertext, a vendored file) needs to populate it.
+   *
+   * Before this field existed, "JSON.parse fails on this content" was the
+   * only way to opt out of round-tripping — true for YAML that happens not to
+   * parse as JSON, but never a structural guarantee (YAML is a JSON
+   * superset).
+   */
+  verbatimFiles?: string[];
   /**
    * Non-fatal diagnostics produced during serialization (e.g. a dialect
    * dropping keys the target platform ignores). The build pipeline collects

package/src/testing.test.ts

@@ -3,8 +3,14 @@ import { mkdir, writeFile, rm } from "node:fs/promises";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { createMockPlugin } from "@intentius/chant-test-utils";
-import { deployStack, testEnvName, TeardownIncompleteError } from "./testing";
+import { createMockPlugin, staticObservation } from "@intentius/chant-test-utils";
+import {
+  deployStack,
+  testEnvName,
+  TeardownIncompleteError,
+  LiveAssertionError,
+  UnobservedAssertionError,
+} from "./testing";
 import type { ActivityFn } from "./op/activity-registry";
 import type { TeardownExecution } from "./lexicon";
 
@@ -258,4 +264,85 @@ describe("deployStack", () => {
     await expect(deployStack(harness(nativeApply, { applyTargets: {} }))).rejects.toThrow(/nothing to deploy/);
     expect(nativeApply).not.toHaveBeenCalled();
   });
+
+  describe("assertLive", () => {
+    const nativeApply = vi.fn(async (_args: Record<string, unknown>) => ({ applied: 1, pruned: 0, notAttempted: 0 }));
+
+    test("resolves the metadata for an entity observed present and marker-matched", async () => {
+      await writeProject(dir);
+      const plugin = createMockPlugin({
+        name: "mock",
+        describeResources: (opts) =>
+          Promise.resolve({
+            bucket: { type: "Mock::Bucket", status: "READY", marker: { stack: "harness-fixture", env: opts.environment } },
+          }),
+      });
+      const stack = await deployStack(harness(nativeApply, { plugins: [plugin] }));
+
+      const meta = await stack.assertLive("bucket");
+      expect(meta.status).toBe("READY");
+    });
+
+    test("checks status when given", async () => {
+      await writeProject(dir);
+      const plugin = createMockPlugin({
+        name: "mock",
+        describeResources: (opts) =>
+          Promise.resolve({
+            bucket: { type: "Mock::Bucket", status: "READY", marker: { stack: "harness-fixture", env: opts.environment } },
+          }),
+      });
+      const stack = await deployStack(harness(nativeApply, { plugins: [plugin] }));
+
+      await expect(stack.assertLive("bucket", { status: "READY" })).resolves.toBeDefined();
+      await expect(stack.assertLive("bucket", { status: "GONE" })).rejects.toThrow(LiveAssertionError);
+    });
+
+    test("throws naming the entity when observed absent", async () => {
+      await writeProject(dir);
+      const plugin = createMockPlugin({ name: "mock", describeResources: staticObservation({}) });
+      const stack = await deployStack(harness(nativeApply, { plugins: [plugin] }));
+
+      await expect(stack.assertLive("bucket")).rejects.toThrow(/bucket.*observed absent/s);
+    });
+
+    test("throws UnobservedAssertionError, not a plain failure, when NOT-OBSERVED", async () => {
+      await writeProject(dir);
+      const plugin = createMockPlugin({
+        name: "mock",
+        describeResources: staticObservation({}, { bucket: { reason: "no-binding", type: "Mock::Bucket" } }),
+      });
+      const stack = await deployStack(harness(nativeApply, { plugins: [plugin] }));
+
+      const err = await stack.assertLive("bucket").then(
+        () => undefined,
+        (e: unknown) => e,
+      );
+      expect(err).toBeInstanceOf(UnobservedAssertionError);
+      expect(err).not.toBeInstanceOf(LiveAssertionError);
+    });
+
+    test("throws when the observed resource carries another environment's marker — a same-named leftover cannot satisfy it", async () => {
+      await writeProject(dir);
+      const plugin = createMockPlugin({
+        name: "mock",
+        describeResources: staticObservation({
+          bucket: { type: "Mock::Bucket", status: "READY", marker: { stack: "harness-fixture", env: "test-someone-else-000000" } },
+        }),
+      });
+      const stack = await deployStack(harness(nativeApply, { plugins: [plugin] }));
+
+      await expect(stack.assertLive("bucket")).rejects.toThrow(/not this deploy's/);
+    });
+
+    test("an unknown entity name throws before any read is attempted", async () => {
+      await writeProject(dir);
+      const describeResources = vi.fn(staticObservation({}));
+      const plugin = createMockPlugin({ name: "mock", describeResources });
+      const stack = await deployStack(harness(nativeApply, { plugins: [plugin] }));
+
+      await expect(stack.assertLive("nope")).rejects.toThrow(/no such entity/);
+      expect(describeResources).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/testing.ts

@@ -15,6 +15,12 @@
  *   in-process for exactly this suite's environment. Stateless by design:
  *   a crashed suite's environment is recovered by calling destroy again (or
  *   `chant lifecycle teardown <env> --yes`).
+ * - **assertLive** (#1857) — `describeResources()` against exactly one
+ *   declared entity, turned into a pass or a thrown failure. Preserves
+ *   #1089's tri-state rather than collapsing it: NOT-OBSERVED throws {@link
+ *   UnobservedAssertionError}, never a silent pass and never an ordinary
+ *   failure, because chant could not read the entity is not the same claim
+ *   as chant read it and it is gone.
  *
  * ## Isolation
  *
@@ -44,7 +50,7 @@ import { basename, join, resolve } from "node:path";
 import { mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { build } from "./build";
-import type { Declarable } from "./declarable";
+import { isResourceDeclarable, type Declarable } from "./declarable";
 import type { SerializerResult } from "./serializer";
 import {
   loadChantConfigUpward,
@@ -55,12 +61,20 @@ import { resolveBuildParams, type BuildParamValue } from "./build-params";
 import { ENV_VAR, unknownEnvError } from "./env";
 import { applyLiveEndpoint } from "./live-endpoint";
 import { loadPlugins, resolveProjectLexicons, collectBuildRootContributors } from "./cli/plugins";
-import type { LexiconPlugin } from "./lexicon";
+import type { LexiconPlugin, ResourceMetadata } from "./lexicon";
 import type { OwnershipMarker } from "./ownership";
 import { runOpLocally } from "./op/local-executor";
 import { loadActivities, loadProfiles, type ActivityFn, type ActivityProfile } from "./op/activity-registry";
 import type { OpConfig, ActivityStep } from "./op/types";
 import { executeTeardown, type TeardownReport } from "./lifecycle/teardown";
+import {
+  assertLiveEntity,
+  LiveAssertionError,
+  UnobservedAssertionError,
+  type AssertLiveOptions,
+} from "./lifecycle/assert-live";
+
+export { LiveAssertionError, UnobservedAssertionError, type AssertLiveOptions };
 
 /**
  * Which `nativeApply` target deploys each lexicon's built output. Only these
@@ -118,6 +132,19 @@ export interface DeployedStack {
   entities: Map<string, Declarable>;
   /** The environment this deploy targeted — the teardown key. */
   env: string;
+  /**
+   * Assert that a declared entity is live: observed present in this
+   * deploy's environment, not confirmed as another stack/env's resource,
+   * and — when `status` is given — reporting that status.
+   *
+   * Rides the observation contract (#1089): an entity `describeResources`
+   * could not cover throws {@link UnobservedAssertionError}, never a pass
+   * and never a plain failure — NOT-OBSERVED is not the same claim as
+   * absent. Observed-absent, a confirmed-foreign identity, or a status
+   * mismatch throws {@link LiveAssertionError}. Resolves to the entity's
+   * `ResourceMetadata` on success.
+   */
+  assertLive(name: string, options?: AssertLiveOptions): Promise<ResourceMetadata>;
   /**
    * Tear down everything carrying this suite's marker `{ stack, env }`.
    * Throws {@link TeardownIncompleteError} when any candidate failed to
@@ -321,6 +348,39 @@ export async function deployStack(options: DeployStackOptions): Promise<Deployed
     applied.restore();
   }
 
+  const assertLive = async (name: string, assertOptions: AssertLiveOptions = {}): Promise<ResourceMetadata> => {
+    const entity = result.entities.get(name);
+    if (!entity) {
+      throw new LiveAssertionError(
+        `assertLive("${name}"): no such entity — this deploy built ${[...result.entities.keys()].join(", ") || "nothing"}.`,
+      );
+    }
+    const entityPlugin = plugins.find((p) => p.name === entity.lexicon);
+    if (!entityPlugin) {
+      throw new LiveAssertionError(`assertLive("${name}"): no loaded lexicon named "${entity.lexicon}".`);
+    }
+    const entityOutput = result.outputs.get(entity.lexicon);
+    const entityBuildOutput =
+      entityOutput === undefined ? "" : typeof entityOutput === "string" ? entityOutput : entityOutput.primary;
+    const props = isResourceDeclarable(entity) ? ((entity.props ?? {}) as Record<string, unknown>) : {};
+
+    const endpointForAssert = applyLiveEndpoint(config.environments, env, plugins);
+    try {
+      return await assertLiveEntity({
+        plugin: entityPlugin,
+        name,
+        entityType: entity.entityType,
+        props,
+        buildOutput: entityBuildOutput,
+        environment: env,
+        marker,
+        ...assertOptions,
+      });
+    } finally {
+      endpointForAssert.restore();
+    }
+  };
+
   const destroy = async (): Promise<TeardownReport> => {
     const endpointForTeardown = applyLiveEndpoint(config.environments, env, plugins);
     let report: TeardownReport;
@@ -334,5 +394,5 @@ export async function deployStack(options: DeployStackOptions): Promise<Deployed
     return report;
   };
 
-  return { outputs: result.outputs, entities: result.entities, env, destroy };
+  return { outputs: result.outputs, entities: result.entities, env, assertLive, destroy };
 }