@intentius/chant-lexicon-k8s 0.42.1 → 0.44.2

package/dist/skills/chant-k8s-flux.md

@@ -0,0 +1,162 @@
+---
+skill: chant-k8s-flux
+description: Flux CD composites for GitOps reconciliation — FluxGitSource + FluxAppFor, the one-source-many-apps shape, dependsOn ordering, the FLUX rules, and the flux-reconcile deploy step
+user-invocable: true
+---
+
+# Flux CD Composites
+
+Chant authors typed infrastructure into manifests. Flux continuously reconciles those manifests into a cluster from git. These composites are the opt-in bridge — the k8s lexicon itself stays runtime-agnostic and only emits YAML; nothing here is implied unless you reach for it.
+
+## The split
+
+| Layer | Owns | In Chant |
+|---|---|---|
+| **Chant** | Authoring typed infra → manifests, committed to git | the lexicons |
+| **Flux** | Continuously reconciling those manifests (source-controller fetches, kustomize-controller applies) | `FluxGitSource` / `FluxAppFor` |
+| **Chant again** | Reading convergence back | `flux-reconcile` deploy step, `chant components status --live` |
+
+Flux never learns Chant exists — it fetches a git path and applies what it finds there. Chant's job ends at emitting the manifests and the Flux CRs that point at them.
+
+## Prerequisites
+
+The Flux controllers must be installed in the target cluster before applying any Flux CRs:
+
+```bash
+kubectl apply -f https://github.com/fluxcd/flux2/releases/download/v2.9.1/install.yaml
+kubectl -n flux-system wait deploy --all --for=condition=Available --timeout=180s
+```
+
+(Or `flux install` / `flux bootstrap` with the Flux CLI. `flux bootstrap` also creates a `flux-system` `GitRepository` — FLUX002 knows about it, see below.)
+
+## When to use which
+
+| Composite | Use case |
+|---|---|
+| `FluxGitSource` | Declare the git repo the source-controller fetches — **once per repo** |
+| `FluxAppFor` | One `Kustomization` reconciling one path out of a declared source — once per app |
+
+---
+
+## FluxGitSource — declare the repo once
+
+```typescript
+import { FluxGitSource } from "@intentius/chant-lexicon-k8s";
+
+export const source = FluxGitSource("home-chant", {
+  url: "https://github.com/jhgaylor/home-chant",
+  branch: "main",
+});
+```
+
+`FluxGitSource(name, options)` returns `{ gitRepository }` — a single `K8s::Flux::GitRepository` in `flux-system`. Options:
+
+- **`url`** (required) — the repo the source-controller fetches.
+- **`branch`** — defaults to `"main"`. **`tag`** pins a tag instead and wins over `branch`.
+- **`interval`** — fetch interval, default `"5m"`.
+- **`secretRef`** — name of the Secret holding git credentials, for private repos.
+- **`fluxNamespace`** — where the CR lives, default `"flux-system"`.
+
+> **FLUX001** — a hand-written `GitRepository` whose spec has a `url` but no `ref` is flagged: an unset `spec.ref` falls back to the `master` branch, which on most repos no longer exists, so the source stalls with a checkout error and every Kustomization downstream stalls too. `FluxGitSource` always emits a `ref` (branch or tag), so composite output is FLUX001-clean by construction.
+
+## FluxAppFor — one Kustomization per app
+
+```typescript
+import { FluxAppFor } from "@intentius/chant-lexicon-k8s";
+
+export const hello = FluxAppFor("hello-chant", {
+  source,                          // the FluxGitSource result above
+  path: "./apps/hello-chant/k8s",
+  targetNamespace: "default",
+  dependsOn: ["cert-manager", "traefik"],
+});
+```
+
+`FluxAppFor(target, options)` returns `{ kustomization }` — a single `K8s::Flux::Kustomization`. Defaults are taken from real Flux estates, not the docs:
+
+- **`interval`** — `"10m"` (the source polls at 5m; reconcile less often than you fetch).
+- **`prune: true`** — resources that disappear from the source are deleted.
+- **`wait: true`** — the Kustomization reports Ready only when the reconciled resources are ready.
+- **`targetNamespace`** — optional; sets `spec.targetNamespace` (kustomize-controller stamps it on every reconciled resource).
+- **`timeout`**, **`suspend`**, **`serviceAccountName`** — pass-throughs for the matching spec fields.
+
+### The source option
+
+`source` accepts three shapes:
+
+```typescript
+FluxAppFor("app", { source,                         path: "./apps/app" });  // FluxGitSource result
+FluxAppFor("app", { source: "flux-system",           path: "./apps/app" });  // name of an existing GitRepository
+FluxAppFor("app", { source: { kind: "OCIRepository", name: "images" }, path: "./apps/app" });  // explicit ref
+```
+
+The first is the normal case. The second targets a source declared elsewhere — typically the bootstrap-created `flux-system` repo. The third covers `OCIRepository` / `Bucket` sources.
+
+> **FLUX002** — every `Kustomization.spec.sourceRef` must name a source the build declares (`GitRepository`, `OCIRepository`, or `Bucket`), or the kustomize-controller waits forever on an artifact that never arrives. The bootstrap-created `flux-system` `GitRepository` is exempt — it always exists on a bootstrapped cluster, the Flux analogue of ARGO002's built-in `default` project.
+
+### One source, many apps
+
+The common estate shape is **one `GitRepository` shared by many `Kustomization`s** — a multi-app repo with one Kustomization per path. A `GitRepository` per app is the mistake the composite split makes hard: declare the source once, hand its result to every `FluxAppFor`.
+
+```typescript
+const source = FluxGitSource("infra", { url: "https://github.com/acme/infra" });
+
+export const platform = FluxAppFor("platform", { source, path: "./dist/platform" });
+export const api      = FluxAppFor("api",      { source, path: "./dist/apps/api", dependsOn: ["platform"] });
+export const web      = FluxAppFor("web",      { source, path: "./dist/apps/web", dependsOn: ["platform", "api"] });
+```
+
+### dependsOn — ordering as a validated name list
+
+`dependsOn` is a plain string list rendered to `spec.dependsOn`; the Kustomization stays pending until every named Kustomization is Ready. In raw YAML those names have no referential integrity — a typo, or an entry left behind after a rename, stalls the app silently.
+
+> **FLUX003** — every `dependsOn` entry is joined against the Kustomizations the build actually declares. An entry naming nothing is a warning (not an error — estates legitimately split infra and apps across repos, so `cert-manager` may be declared by a build this one never sees). A self-referencing entry is always flagged: Flux can never satisfy it.
+
+---
+
+## Deploying — the flux-reconcile step
+
+Applying `dist/flux.yaml` with `kubectl` works. For the component model, `fluxReconcile` is the typed deploy leaf (the sibling of `argo-app`):
+
+```typescript
+import { phase, type Component } from "@intentius/chant/components/component";
+import { fluxReconcile } from "@intentius/chant-lexicon-k8s/components";
+
+export const bootstrap: Component = {
+  name: "flux-bootstrap",
+  archetype: "service",
+  dependsOn: [],
+  deploy: [
+    phase("Reconcile", [
+      fluxReconcile({
+        manifest: "dist/flux.yaml",
+        stack: "my-estate",
+        noRollback: "server-side apply keeps no previous object state; the declared source is the restore path",
+      }),
+    ]),
+  ],
+};
+```
+
+What it does:
+
+1. **Applies** the Flux CRs through the same server-side apply `kubectl-apply` uses — ownership stamping, marker-scoped prune, stack labels all identical.
+2. **Waits for Ready, sources first.** A Kustomization cannot become Ready before its GitRepository has an artifact, so gating on `source.toolkit.fluxcd.io` kinds first surfaces a wedged clone as the source's error rather than a reconciler timeout downstream. The generic `waitForReady` handles the rest of the toolkit (kstatus-conformant), with fail-fast on wedge reasons like `BuildFailed` or `UpgradeFailed` from the readiness registry.
+3. **Refuses non-Flux manifests.** If the manifest applies no Flux CR at all, the step errors — a plain manifest belongs on `kubectl-apply`, and two things applying the same resources is the failure mode worth engineering against.
+
+It is a `needs-opt-out` capability (COMP003): every step needs `noRollback: "<reason>"`, a component `rollback` phase, or a sibling safety step — same posture as `kubectl-apply`, and for the same reason.
+
+## Reading convergence back
+
+The build stamps `app.kubernetes.io/managed-by: chant` and (with `ownership` configured) `chant.intentius.io/stack: <stack>` labels on every resource. Flux applies the manifests, but the labels travel with them — so `chant components status --live` attributes the running workloads to the stack through the k8s lexicon's label-selector read, regardless of who did the applying. Flux prunes by its own labels; chant observes by its own labels; neither needs the other's.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Kustomization stuck, no artifact | Source stalled — unset `spec.ref` fell back to `master` | Pin a branch/tag (FLUX001); `FluxGitSource` does this by default |
+| Kustomization waits forever | `sourceRef` names an undeclared source | Declare it with `FluxGitSource`, or point at the bootstrap `flux-system` repo (FLUX002) |
+| App pending, dependencies "not ready" | `dependsOn` names a Kustomization that doesn't exist (typo/rename) | Fix the name (FLUX003), or confirm the other repo declares it |
+| App pending forever, no error | `dependsOn` self-reference | Remove the self-edge (FLUX003 flags it) |
+| Resources deleted unexpectedly | `prune: true` (the default) and the path stopped emitting them | Intended GitOps behavior; pass `prune: false` to opt out |
+| `flux-reconcile` step errors immediately | Manifest contains no Flux CR | Use `kubectl-apply` for plain manifests |

package/dist/types/index.d.ts

@@ -2,6 +2,18 @@
 
 // --- Kubernetes Resource classes ---
 
+export declare class Addon {
+  constructor(props: {
+    /** Standard object's metadata. */
+    metadata?: ObjectMeta;
+    /** Spec provides information about the on-disk manifest backing this resource. */
+    spec?: Record<string, unknown>;
+  });
+  readonly name: string;
+  readonly namespace: string;
+  readonly uid: string;
+}
+
 export declare class Alert {
   constructor(props: {
     /** Standard object's metadata. */
@@ -920,6 +932,19 @@ export declare class FlowSchemaList {
   readonly uid: string;
 }
 
+export declare class FluxHelmChart {
+  constructor(props: {
+    /** Standard object's metadata. */
+    metadata?: ObjectMeta;
+    /** HelmChartSpec specifies the desired state of a Helm chart. */
+    spec?: Record<string, unknown>;
+  });
+  readonly name: string;
+  readonly namespace: string;
+  readonly status: Record<string, unknown>;
+  readonly uid: string;
+}
+
 export declare class FluxInstance {
   constructor(props: {
     /** Standard object's metadata. */
@@ -999,16 +1024,16 @@ export declare class GRPCRoute {
   readonly uid: string;
 }
 
-export declare class HelmChart {
+export declare class HelmChartConfig {
   constructor(props: {
     /** Standard object's metadata. */
     metadata?: ObjectMeta;
-    /** HelmChartSpec specifies the desired state of a Helm chart. */
+    /** HelmChartConfigSpec represents additional user-configurable details of an installed and configured Helm chart release.
+These fields are merged with or override the corresponding fields on the related HelmChart resource. */
     spec?: Record<string, unknown>;
   });
   readonly name: string;
   readonly namespace: string;
-  readonly status: Record<string, unknown>;
   readonly uid: string;
 }
 
@@ -1325,6 +1350,19 @@ export declare class JobList {
   readonly uid: string;
 }
 
+export declare class K3sHelmChart {
+  constructor(props: {
+    /** Standard object's metadata. */
+    metadata?: ObjectMeta;
+    /** HelmChartSpec represents the user-configurable details for installation and upgrade of a Helm chart release. */
+    spec?: Record<string, unknown>;
+  });
+  readonly name: string;
+  readonly namespace: string;
+  readonly status: Record<string, unknown>;
+  readonly uid: string;
+}
+
 export declare class Kustomization {
   constructor(props: {
     /** Standard object's metadata. */

package/dist/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAElG,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAuBvF;;GAEG;AACH,wBAAsB,QAAQ,CAAC,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAQpF"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAElG,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAuBvF;;GAEG;AACH,wBAAsB,QAAQ,CAAC,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAYpF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-k8s",
-  "version": "0.42.1",
+  "version": "0.44.2",
   "description": "Kubernetes lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -76,7 +76,7 @@
     "@types/js-yaml": "^4.0.9"
   },
   "optionalDependencies": {
-    "@intentius/chant-k8s-client": "^0.41.5"
+    "@intentius/chant-k8s-client": "^0.44.2"
   },
   "devDependencies": {
     "@intentius/chant": "*",
@@ -84,7 +84,7 @@
   },
   "peerDependencies": {
     "zod": "^4.3.6",
-    "@intentius/chant": "^0.42.1",
+    "@intentius/chant": "^0.44.2",
     "typescript": "^5.9.3"
   }
 }

package/src/api/classify.test.ts

@@ -93,6 +93,43 @@ describe("classifyApiFailure", () => {
     }
   });
 
+  test("the detail names the context the client read, when the failure carries it (#1488)", () => {
+    const err = status(500, "InternalError");
+    err.contextNote = 'context "k3d-kubemicrovm-local" (ambient; no k8s.profiles.local binding)';
+    const outcome = classifyApiFailure(err);
+    expect(outcome.kind).toBe("unobserved");
+    if (outcome.kind === "unobserved") {
+      expect(outcome.detail).toContain('context "k3d-kubemicrovm-local" (ambient; no k8s.profiles.local binding)');
+    }
+  });
+
+  test("the context note leads the detail, so it survives the one-line cap and any consumer truncation (#1488, #1620)", () => {
+    const err = new K8sApiError(500, "InternalError", "x".repeat(500));
+    err.contextNote = 'context "prod-eks" (bound by k8s.profiles.prod.context)';
+    const outcome = classifyApiFailure(err);
+    expect(outcome.kind).toBe("unobserved");
+    if (outcome.kind === "unobserved") {
+      expect(outcome.detail.startsWith('context "prod-eks" (bound by k8s.profiles.prod.context)')).toBe(true);
+      // The error itself still follows — leading with the cluster does not
+      // cost the message.
+      expect(outcome.detail).toContain("xxx");
+    }
+  });
+
+  test("the context appears within the first 160 chars of a long multi-line error's detail (#1620)", () => {
+    // behold's estate overlay truncates a reason to its first line / 160 chars;
+    // the context must land inside that window or it vanishes exactly on the
+    // failures long enough to need it.
+    const err = new K8sApiError(500, "InternalError", `${"y".repeat(300)}\n${"z".repeat(300)}`);
+    err.contextNote = 'context "prod-eks" (bound by k8s.profiles.prod.context)';
+    const outcome = classifyApiFailure(err);
+    expect(outcome.kind).toBe("unobserved");
+    if (outcome.kind === "unobserved") {
+      const firstLine = outcome.detail.split("\n")[0];
+      expect(firstLine.slice(0, 160)).toContain('context "prod-eks" (bound by k8s.profiles.prod.context)');
+    }
+  });
+
   test("classification survives a duplicated copy of the client package", () => {
     // Discrimination is by `name`, not `instanceof`, so an error from a second
     // physical copy of the package in a consumer's tree still classifies.

package/src/api/classify.ts

@@ -47,6 +47,8 @@ interface ErrorLike {
   message?: string;
   statusCode?: number;
   reason?: string;
+  /** Which cluster the failing read talked to — stamped by the typed client (chant #1488). */
+  contextNote?: string;
 }
 
 function shapeOf(err: unknown): ErrorLike {
@@ -140,5 +142,13 @@ export const MISSING_CLIENT_DETAIL =
 function detailOf(err: unknown): string {
   const text = err instanceof Error ? err.message : String(err);
   const line = text.split("\n").find((l) => l.trim().length > 0)?.trim() ?? text.trim();
-  return line.length > 200 ? `${line.slice(0, 197)}...` : line;
+  const capped = line.length > 200 ? `${line.slice(0, 197)}...` : line;
+  // #1488 — a reason that does not say which cluster was read turned an
+  // ambient-context switch into an afternoon. The client stamps the context it
+  // resolved onto every failure. The note LEADS the detail (#1620): consumers
+  // truncate a reason to its first line and ~160 chars, and a note appended
+  // after a long error is cut off exactly when the error is long enough to
+  // need it. Leading, it survives any suffix truncation.
+  const note = shapeOf(err).contextNote;
+  return note ? `${note} — ${capped}` : capped;
 }

package/src/api/connect.ts

@@ -65,6 +65,7 @@ export const defaultK8sConnector: K8sConnector = async (options) => {
     const client = await createK8sClient({
       context: options.context,
       contextSource: "bound",
+      contextLabel: "explicit --context",
       ...options.client,
     });
     return { client, target: { context: options.context, source: "bound" } };
@@ -84,10 +85,19 @@ export const defaultK8sConnector: K8sConnector = async (options) => {
   // is supplied.
   const target = await resolveClusterTarget(config as Record<string, unknown>, options.environment, "k8s");
 
+  // #1488 — every failure the client throws names the cluster it read and how
+  // that cluster was selected, so a `read-failed` against the wrong context is
+  // legible from the reason alone.
+  const contextLabel =
+    target.source === "bound"
+      ? `bound by k8s.profiles.${options.environment}.context`
+      : `ambient; no k8s.profiles.${options.environment} binding`;
+
   const client = await createK8sClient({
     ...options.client,
     ...(target.context ? { context: target.context } : {}),
     contextSource: target.source,
+    contextLabel,
     ...(execAllowlist ? { execAllowlist } : {}),
   });
   return { client, target };

package/src/codegen/docs.ts

@@ -409,6 +409,16 @@ Quality checks for the [Argo CD composites](/chant/lexicons/k8s/argo-composites/
 | ARGO004 | \`ApplicationSet\` template doesn't scope to a single static \`AppProject\` |
 | ARGO005 | \`Application\` \`source.path\` doesn't resolve to a directory (warn) |
 
+### Flux
+
+Quality checks for the [Flux composites](/chant/lexicons/k8s/flux-composites/) (\`FluxGitSource\` / \`FluxAppFor\`). FLUX001 is declarative (source AST); FLUX002/003 are post-synth (cross-resource).
+
+| Rule | Description |
+|------|-------------|
+| FLUX001 | \`GitRepository\` has no \`spec.ref\` pin — Flux falls back to the \`master\` branch |
+| FLUX002 | \`Kustomization.spec.sourceRef\` references an undeclared source (the bootstrap \`flux-system\` repo is exempt) |
+| FLUX003 | \`Kustomization.spec.dependsOn\` names a \`Kustomization\` nothing in the build declares, or itself (warn) |
+
 ## Running lint
 
 \`\`\`bash
@@ -1160,6 +1170,7 @@ The lexicon also provides MCP (Model Context Protocol) tools and resources:
       },
       { label: "CRD-Generated Classes", slug: "crd-classes" },
       { label: "Argo CD Composites", slug: "argo-composites" },
+      { label: "Flux Composites", slug: "flux-composites" },
       {
         label: "Vendor Composites",
         items: [

package/src/components/argo-app.test.ts

@@ -0,0 +1,137 @@
+/**
+ * `argo-app` (#1549 piece 2) — the Argo CD deploy leaf. What must hold: the
+ * capability registers under its kind in the gitops family, the apply goes
+ * through the SAME applier delegation kubectl-apply uses (env + stack +
+ * deleteMode), the wait runs `waitForArgoSync` once per applied Application
+ * (and only for Applications), a manifest with no Application is an error
+ * not a silent no-wait, and the stack is the deploy unit core's status walk
+ * reads.
+ */
+import { describe, test, expect } from "vitest";
+import { createArgoAppCapability, argoAppCapability, type ArgoAppInput } from "./argo-app";
+import { k8sCapabilityPlugin, K8S_VERB_FAMILIES } from "./capability-plugin";
+import { isCapabilityPlugin } from "@intentius/chant/components/capability-plugin";
+import type { DeployContext } from "@intentius/chant/components/capability";
+
+const ctx = { env: "dev" } as DeployContext;
+
+const APP_REF = { apiVersion: "argoproj.io/v1alpha1", kind: "Application", name: "web", namespace: "argocd" };
+const PROJECT_REF = { apiVersion: "argoproj.io/v1alpha1", kind: "AppProject", name: "team" };
+
+describe("argo-app capability (#1549 piece 2)", () => {
+  test("registers on the k8s plugin, in the gitops family", () => {
+    expect(isCapabilityPlugin(k8sCapabilityPlugin)).toBe(true);
+    expect(k8sCapabilityPlugin.capabilities().map((c) => c.kind)).toContain("argo-app");
+    expect(K8S_VERB_FAMILIES.gitops).toContain("argo-app");
+  });
+
+  test("rollback is needs-opt-out — a server-side apply keeps no previous state", () => {
+    expect(argoAppCapability.rollbackPolicy).toBe("needs-opt-out");
+  });
+
+  test("applies through the kubectl-apply delegation, then waits Healthy+Synced on each Application only", async () => {
+    const applierArgs: unknown[] = [];
+    const waited: unknown[] = [];
+    const cap = createArgoAppCapability(
+      async (args) => {
+        applierArgs.push(args);
+        return { fieldManager: "chant:gitops", applied: [PROJECT_REF, APP_REF], pruned: [] };
+      },
+      async (args) => {
+        waited.push(args);
+        return { health: "Healthy", sync: "Synced" };
+      },
+    );
+
+    const outcome = await cap.run(ctx, {
+      manifest: "argo/app.yaml",
+      stack: "gitops",
+      delete: "owned-only",
+      intervalMs: 500,
+    } as ArgoAppInput as never);
+
+    // The exact args kubectl-apply hands the shared applier — same path, same stamping.
+    expect(applierArgs).toEqual([
+      { manifest: "argo/app.yaml", environment: "dev", stack: "gitops", deleteMode: "owned-only" },
+    ]);
+    // One wait, for the Application — the AppProject applies but is not synced on.
+    expect(waited).toEqual([{ appName: "web", namespace: "argocd", intervalMs: 500 }]);
+    expect(outcome.synced).toEqual([{ name: "web", namespace: "argocd", health: "Healthy", sync: "Synced" }]);
+    expect(outcome.fieldManager).toBe("chant:gitops");
+  });
+
+  test("REST-API wait knobs (server/authToken/insecure) and context pass through to waitForArgoSync", async () => {
+    const waited: unknown[] = [];
+    const cap = createArgoAppCapability(
+      async () => ({ fieldManager: "chant", applied: [APP_REF], pruned: [] }),
+      async (args) => {
+        waited.push(args);
+        return { health: "Healthy", sync: "Synced" };
+      },
+    );
+    await cap.run(ctx, {
+      manifest: "argo/app.yaml",
+      context: "kind-dev",
+      server: "https://argocd.example.com",
+      authToken: "t0ken",
+      insecure: true,
+    } as ArgoAppInput as never);
+    expect(waited).toEqual([
+      {
+        appName: "web",
+        namespace: "argocd",
+        server: "https://argocd.example.com",
+        authToken: "t0ken",
+        insecure: true,
+        context: "kind-dev",
+      },
+    ]);
+  });
+
+  test("an Application without a namespace waits in argocd, the controller's default", async () => {
+    const waited: Array<{ namespace?: string }> = [];
+    const cap = createArgoAppCapability(
+      async () => ({
+        fieldManager: "chant",
+        applied: [{ apiVersion: "argoproj.io/v1alpha1", kind: "Application", name: "web" }],
+        pruned: [],
+      }),
+      async (args) => {
+        waited.push(args);
+        return { health: "Healthy", sync: "Synced" };
+      },
+    );
+    await cap.run(ctx, { manifest: "argo/app.yaml" } as ArgoAppInput as never);
+    expect(waited[0]?.namespace).toBe("argocd");
+  });
+
+  test("a manifest that applied no Application is an error, not a silent no-wait", async () => {
+    const cap = createArgoAppCapability(
+      async () => ({ fieldManager: "chant", applied: [PROJECT_REF], pruned: [] }),
+      async () => ({ health: "Healthy", sync: "Synced" }),
+    );
+    await expect(cap.run(ctx, { manifest: "argo/project.yaml" } as ArgoAppInput as never)).rejects.toThrow(
+      /no argoproj\.io Application/,
+    );
+  });
+
+  test("a failed sync propagates — the step does not report success past a Degraded app", async () => {
+    const cap = createArgoAppCapability(
+      async () => ({ fieldManager: "chant", applied: [APP_REF], pruned: [] }),
+      async () => {
+        throw new Error('Argo Application "web" reached a terminal unhealthy state');
+      },
+    );
+    await expect(cap.run(ctx, { manifest: "argo/app.yaml" } as ArgoAppInput as never)).rejects.toThrow(
+      /terminal unhealthy state/,
+    );
+  });
+
+  test("the stack field is the deploy unit core's status walk reads (#1549 piece 2)", async () => {
+    const { deployUnits } = await import("@intentius/chant/components/deploy-units");
+    const units = deployUnits([
+      { phase: "Apply", steps: [{ kind: "argo-app", manifest: "argo/app.yaml", stack: "gitops" }] } as never,
+    ]);
+    expect(units).toEqual([{ unit: "gitops", lexicon: "k8s" }]);
+  });
+});