@intentius/chant-lexicon-k8s 0.124.41 → 0.124.43

package/dist/components/kubectl-apply.d.ts

@@ -159,6 +159,12 @@ export interface KubectlApplyOutputField {
     /** The field's dot path in the object; a list index is a number, `status.loadBalancer.ingress.0.hostname`. */
     field: string;
 }
+/**
+ * The documents `targets` name (#4300), each `Kind/namespace/name` or
+ * `Kind/name` as {@link addressOf} writes it, in manifest order. Throws for
+ * a target the manifest does not declare.
+ */
+export declare function targetedDocuments(member: string, manifest: string, documents: Record<string, unknown>[], targets: readonly string[]): Record<string, unknown>[];
 /** Factory with an injectable applier, so tests assert the delegation without
  * a cluster — the same seam `createGenerateSbomCapability` uses. The default
  * applier is resolved by dynamic import on first run, keeping the API-client

package/dist/components/kubectl-apply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kubectl-apply.d.ts","sourceRoot":"","sources":["../../src/components/kubectl-apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EAAE,UAAU,EAAiD,MAAM,wCAAwC,CAAC;AAOxH;;;;;;;;;;GAUG;AACH,UAAU,UAAU;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,4DAA4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,qDAAqD;IACrD,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,sFAAsF;IACtF,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IACxB,2GAA2G;IAC3G,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,UAAU,WAAW;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,yGAAyG;IACzG,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,OAAO,GAAG,YAAY,GAAG,OAAO,CAAC;CAC/C;AAED,KAAK,OAAO,GAAG,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;AACnE,KAAK,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;AAElE,wFAAwF;AACxF,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,oDAAoD;AACpD,UAAU,kBAAkB;IAC1B,GAAG,EAAE,UAAU,CAAC;IAChB,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,uFAAuF;AACvF,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB;AAED,KAAK,OAAO,GAAG,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAElE,0DAA0D;AAC1D,UAAU,cAAc;IACtB,IAAI,EAAE,UAAU,EAAE,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,gGAAgG;AAChG,KAAK,UAAU,GAAG,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC;AAEhG,qEAAqE;AACrE,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;CACtC;AAOD;;;;;;GAMG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;aAIjC,MAAM,EAAE,MAAM;aACd,QAAQ,EAAE,MAAM;aAChB,KAAK,EAAE,MAAM;IAL/B,QAAQ,CAAC,SAAS,QAAQ;IAC1B,QAAQ,CAAC,QAAQ,KAAK;IACtB,YACkB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EAO9B;CACF;AA2GD,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,YAAY,CAAC;IAChC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;CACnD;AAED,oDAAoD;AACpD,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,8GAA8G;IAC9G,KAAK,EAAE,MAAM,CAAC;CACf;AA4CD;;;uCAGuC;AACvC,wBAAgB,4BAA4B,CAC1C,KAAK,CAAC,EAAE,OAAO,EACf,IAAI,CAAC,EAAE,cAAc,EACrB,MAAM,CAAC,EAAE,OAAO,EAChB,QAAQ,CAAC,EAAE,UAAU,GACpB,UAAU,CAAC,iBAAiB,EAAE,mBAAmB,CAAC,CAsGpD;AAED,eAAO,MAAM,sBAAsB,oDAAiC,CAAC"}
+{"version":3,"file":"kubectl-apply.d.ts","sourceRoot":"","sources":["../../src/components/kubectl-apply.ts"],"names":[],"mappings":"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"}

package/dist/components/kubectl-apply.js

@@ -157,6 +157,36 @@ async function readOutputs(read, refs, input, where) {
     }
     return out;
 }
+/**
+ * The documents `targets` name (#4300), each `Kind/namespace/name` or
+ * `Kind/name` as {@link addressOf} writes it, in manifest order. Throws for
+ * a target the manifest does not declare.
+ */
+export function targetedDocuments(member, manifest, documents, targets) {
+    const addressOfDoc = (doc) => {
+        const metadata = (doc.metadata ?? {});
+        return addressOf({
+            apiVersion: String(doc.apiVersion ?? ""),
+            kind: String(doc.kind ?? ""),
+            name: String(metadata.name ?? ""),
+            ...(metadata.namespace !== undefined ? { namespace: String(metadata.namespace) } : {}),
+        });
+    };
+    const declared = new Set(documents.map(addressOfDoc));
+    const missing = targets.filter((t) => !declared.has(t));
+    if (missing.length > 0) {
+        throw new Error(`kubectl-apply "${member}": --target ${missing.join(", ")} names no object ${manifest} declares ` +
+            `(it declares ${[...declared].join(", ") || "nothing"})`);
+    }
+    const wanted = new Set(targets);
+    return documents.filter((d) => wanted.has(addressOfDoc(d)));
+}
+/**
+ * The input a targeted step plans and applies with (#4300): the same, with no
+ * prune. A prune over a narrowed set would delete every owned object the
+ * targets leave out.
+ */
+const narrowedInput = (ctx, input) => ctx.targets && ctx.targets.length > 0 ? { ...input, delete: "never" } : input;
 /** Factory with an injectable applier, so tests assert the delegation without
  * a cluster — the same seam `createGenerateSbomCapability` uses. The default
  * applier is resolved by dynamic import on first run, keeping the API-client
@@ -205,28 +235,61 @@ export function createKubectlApplyCapability(apply, read, dryRun, readLive) {
         }
         return { known, unknown: unknown.sort() };
     };
+    /**
+     * {@link plannedOutputs} for a targeted plan (#4300): an output of a
+     * targeted object as the plan says, and one of an object the targets leave
+     * out as the cluster holds it now, since the apply leaves that object alone.
+     */
+    const targetedPlannedOutputs = async (ctx, input, member, documents, dry, targets, declared) => {
+        if (!targets)
+            return plannedOutputs(ctx, input, member, documents, dry);
+        const wanted = new Set(targets);
+        const all = Object.entries(input.outputs ?? {});
+        const inside = Object.fromEntries(all.filter(([, spec]) => wanted.has(spec.object)));
+        const outside = Object.fromEntries(all.filter(([, spec]) => !wanted.has(spec.object)));
+        const planned = Object.keys(inside).length > 0 ? await plannedOutputs(ctx, { ...input, outputs: inside }, member, documents, dry) : { known: {}, unknown: [] };
+        if (Object.keys(outside).length === 0)
+            return planned;
+        const rest = { ...input, outputs: outside };
+        const live = await readOutputs(await liveReader(), outputRefs(member, rest, declared), rest, where(ctx, input));
+        const known = { ...planned.known, ...live };
+        const unknown = [...planned.unknown, ...Object.keys(outside).filter((n) => !(n in live))].sort();
+        return { known, unknown };
+    };
     return {
         kind: "kubectl-apply",
         // A server-side apply has no native undo (the previous object state is not
         // kept by the API server), so COMP003 requires the component to acknowledge
         // the compensation gap — the same posture as s3-sync/run-migration.
         rollbackPolicy: "needs-opt-out",
+        // #4300: a target names one object, `Kind/namespace/name`; the plan and the apply send those alone.
+        targets: "accept",
         /**
          * Dry-run the manifest against the cluster (#3998): the documents `run`
          * would apply, release attributes set, server-side applied with
          * `dryRun=All` as the same field manager, each compared with its live
          * object. The member is the step's `stack`, or the component.
          */
-        async plan(ctx, input) {
+        async plan(ctx, stepInput) {
+            const input = narrowedInput(ctx, stepInput);
             const member = input.stack ?? ctx.component;
-            const documents = (read ?? (await activities()).readManifestDocuments)(input.manifest);
+            const read_ = (read ?? (await activities()).readManifestDocuments)(input.manifest);
+            const targets = ctx.targets && ctx.targets.length > 0 ? ctx.targets : undefined;
+            const documents = targets ? targetedDocuments(member, input.manifest, read_, targets) : read_;
             const suffix = releaseAttributesSuffix(ctx.release);
             if (suffix !== "")
                 annotateRelease(documents, suffix);
             const { result, planDigest } = await dryRunOf(ctx, input, member, documents);
             const artifact = { kind: "kubectl-apply-plan", planDigest, documents };
-            const outputs = input.outputs ? await plannedOutputs(ctx, input, member, documents, result) : undefined;
-            return { member, planDigest, artifact, changeSet: changeSetPartOf(member, planDigest, result), ...(outputs ? { outputs } : {}) };
+            const outputs = input.outputs ? await targetedPlannedOutputs(ctx, input, member, documents, result, targets, read_) : undefined;
+            return {
+                member,
+                planDigest,
+                artifact,
+                changeSet: changeSetPartOf(member, planDigest, result),
+                ...(outputs ? { outputs } : {}),
+                ...(targets ? { targets } : {}),
+            };
         },
         /**
          * The fields the step names as outputs, as the cluster holds them now
@@ -239,7 +302,8 @@ export function createKubectlApplyCapability(apply, read, dryRun, readLive) {
             const documents = (read ?? (await activities()).readManifestDocuments)(input.manifest);
             return liveOutputs(ctx, input, documents);
         },
-        async run(ctx, input) {
+        async run(ctx, stepInput) {
+            const input = narrowedInput(ctx, stepInput);
             const member = input.stack ?? ctx.component;
             const approved = ctx.plans?.[member];
             if (isPlanArtifact(approved)) {
@@ -258,7 +322,13 @@ export function createKubectlApplyCapability(apply, read, dryRun, readLive) {
             // workload the build stamped, in what it applies; the committed manifest is not touched.
             const suffix = releaseAttributesSuffix(ctx.release);
             let documents;
-            if (suffix !== "") {
+            if (ctx.targets && ctx.targets.length > 0) {
+                // #4300: only the targeted objects, and no prune (`narrowedInput`).
+                documents = targetedDocuments(member, input.manifest, (read ?? loaded.readManifestDocuments)(input.manifest), ctx.targets);
+                if (suffix !== "")
+                    annotateRelease(documents, suffix);
+            }
+            else if (suffix !== "") {
                 documents = (read ?? loaded.readManifestDocuments)(input.manifest);
                 if (annotateRelease(documents, suffix) === 0)
                     documents = undefined;

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "9b2a09dba2af9e0c71158f1a6372fdc6c1e29cec5c9ade9f271e6d3d38b7375b",
+    "manifest.json": "0bb2e0d248aa5b1808d3d4ad070e78463f9c935177c09c7bb1fefaeb0d9b4b64",
     "meta.json": "c1831ac15083f5e0e45b29698d7b77f1c01646240fe6de5d6320753188594f69",
     "types/index.d.ts": "5c5340046d090ae9db5553039d923cf92a8b2eb57aa4dc941273ed5bcfb5bc9d",
     "rules/argo-appset-single-project.ts": "afa9f310753aa2d475f35012b13135b2dfaebed2a35d44edbe185ebc07673674",
@@ -78,5 +78,5 @@
     "skills/chant-k8s-argo.md": "24c9a85b78a2fc5c6657424baac9cc6d6caff6f47605b8146b2c0082133181cf",
     "skills/chant-k8s-flux.md": "9670efc2e9854bd14686b5adeb707396b9030a4dcaee6529b30abf56efe2c50c"
   },
-  "composite": "5e8e9876fad16ad70ca9496f6f9a383ecb8632e45189ff2f89b1a57d28b0daf0"
+  "composite": "fe30957da3c3498c28db61f85f707151d9f8a5ef6297632f8e080bcbf6ff5f68"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "k8s",
-  "version": "0.124.41",
+  "version": "0.124.43",
   "chantVersion": ">=0.1.0",
   "namespace": "K8s",
   "intrinsics": [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-k8s",
-  "version": "0.124.41",
+  "version": "0.124.43",
   "description": "Kubernetes lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -72,13 +72,13 @@
     "build": "../../scripts/tsc7.sh -p tsconfig.build.json --sourceMap false && tsc-alias -p tsconfig.build.json && cp src/generated/index.d.ts dist/generated/index.d.d.ts"
   },
   "dependencies": {
-    "@intentius/chant-lexicon-otel": "^0.124.41",
-    "@intentius/chant-lexicon-prometheus": "^0.124.41",
+    "@intentius/chant-lexicon-otel": "^0.124.43",
+    "@intentius/chant-lexicon-prometheus": "^0.124.43",
     "js-yaml": "^4.3.1",
     "@types/js-yaml": "^4.0.9"
   },
   "optionalDependencies": {
-    "@intentius/chant-k8s-client": "^0.124.41"
+    "@intentius/chant-k8s-client": "^0.124.43"
   },
   "devDependencies": {
     "@intentius/chant": "*",
@@ -86,6 +86,6 @@
   },
   "peerDependencies": {
     "zod": "^4.3.6",
-    "@intentius/chant": "^0.124.41"
+    "@intentius/chant": "^0.124.43"
   }
 }

package/src/components/kubectl-apply.test.ts

@@ -388,3 +388,52 @@ describe("kubectl-apply outputs: the fields a step names (#3999)", () => {
     expect((await cap.plan!(ctx, { manifest: "k8s.yaml", stack: "web" })).outputs).toBeUndefined();
   });
 });
+
+describe("kubectl-apply targets: one object at a time (#4300)", () => {
+  type DryRun = import("./kubectl-apply").KubectlApplyDryRun;
+  const doc = (kind: string, name: string, namespace?: string) => ({
+    apiVersion: kind === "Deployment" ? "apps/v1" : "v1",
+    kind,
+    metadata: { name, ...(namespace ? { namespace } : {}) },
+  });
+  const docs = () => [doc("Deployment", "web", "prod"), doc("Service", "web", "prod"), doc("Namespace", "prod")];
+  const none = (): DryRun => ({ fieldManager: "chant:web", stack: "web", objects: [], deletes: [], retained: [] });
+  const noApply = async (): Promise<never> => {
+    throw new Error("applied");
+  };
+
+  test("accepts targets", () => {
+    expect(createKubectlApplyCapability().targets).toBe("accept");
+  });
+
+  test("plans the targeted objects alone, with no prune, and gives the targets back", async () => {
+    let seen: Record<string, unknown> = {};
+    const cap = createKubectlApplyCapability(noApply, docs, async (args) => {
+      seen = args as never;
+      return none();
+    });
+    const ctx = { env: "prod", component: "api", targets: ["Namespace/prod", "Service/prod/web"] };
+    const planned = await cap.plan!(ctx, { manifest: "k8s.yaml", stack: "web", delete: "owned-only" });
+    expect(seen).toMatchObject({ documents: [doc("Service", "web", "prod"), doc("Namespace", "prod")], deleteMode: "never" });
+    expect(planned.targets).toEqual(["Namespace/prod", "Service/prod/web"]);
+    const whole = await cap.plan!({ env: "prod", component: "api" }, { manifest: "k8s.yaml", stack: "web", delete: "owned-only" });
+    expect(whole.planDigest).not.toBe(planned.planDigest);
+  });
+
+  test("a target the manifest does not declare refuses and names what it declares", async () => {
+    const cap = createKubectlApplyCapability(noApply, docs, async () => none());
+    await expect(cap.plan!({ env: "prod", component: "api", targets: ["Deployment/prod/api"] }, { manifest: "k8s.yaml" })).rejects.toThrow(
+      /--target Deployment\/prod\/api names no object k8s\.yaml declares \(it declares Deployment\/prod\/web, Service\/prod\/web, Namespace\/prod\)/,
+    );
+  });
+
+  test("run without a plan applies the targeted objects alone, with no prune", async () => {
+    let seen: Record<string, unknown> = {};
+    const cap = createKubectlApplyCapability(async (args) => {
+      seen = args as never;
+      return { fieldManager: "chant:web", applied: [], pruned: [] };
+    }, docs);
+    await cap.run({ env: "prod", component: "api", targets: ["Deployment/prod/web"] }, { manifest: "k8s.yaml", stack: "web", delete: "owned-only" });
+    expect(seen).toMatchObject({ documents: [doc("Deployment", "web", "prod")], deleteMode: "never" });
+  });
+});

package/src/components/kubectl-apply.ts

@@ -338,6 +338,41 @@ async function readOutputs(read: LiveReader, refs: Map<string, AppliedRef>, inpu
   return out;
 }
 
+/**
+ * The documents `targets` name (#4300), each `Kind/namespace/name` or
+ * `Kind/name` as {@link addressOf} writes it, in manifest order. Throws for
+ * a target the manifest does not declare.
+ */
+export function targetedDocuments(member: string, manifest: string, documents: Record<string, unknown>[], targets: readonly string[]): Record<string, unknown>[] {
+  const addressOfDoc = (doc: Record<string, unknown>): string => {
+    const metadata = (doc.metadata ?? {}) as { name?: unknown; namespace?: unknown };
+    return addressOf({
+      apiVersion: String(doc.apiVersion ?? ""),
+      kind: String(doc.kind ?? ""),
+      name: String(metadata.name ?? ""),
+      ...(metadata.namespace !== undefined ? { namespace: String(metadata.namespace) } : {}),
+    });
+  };
+  const declared = new Set(documents.map(addressOfDoc));
+  const missing = targets.filter((t) => !declared.has(t));
+  if (missing.length > 0) {
+    throw new Error(
+      `kubectl-apply "${member}": --target ${missing.join(", ")} names no object ${manifest} declares ` +
+        `(it declares ${[...declared].join(", ") || "nothing"})`,
+    );
+  }
+  const wanted = new Set(targets);
+  return documents.filter((d) => wanted.has(addressOfDoc(d)));
+}
+
+/**
+ * The input a targeted step plans and applies with (#4300): the same, with no
+ * prune. A prune over a narrowed set would delete every owned object the
+ * targets leave out.
+ */
+const narrowedInput = (ctx: DeployContext, input: KubectlApplyInput): KubectlApplyInput =>
+  ctx.targets && ctx.targets.length > 0 ? { ...input, delete: "never" } : input;
+
 /** Factory with an injectable applier, so tests assert the delegation without
  * a cluster — the same seam `createGenerateSbomCapability` uses. The default
  * applier is resolved by dynamic import on first run, keeping the API-client
@@ -389,27 +424,66 @@ export function createKubectlApplyCapability(
     }
     return { known, unknown: unknown.sort() };
   };
+  /**
+   * {@link plannedOutputs} for a targeted plan (#4300): an output of a
+   * targeted object as the plan says, and one of an object the targets leave
+   * out as the cluster holds it now, since the apply leaves that object alone.
+   */
+  const targetedPlannedOutputs = async (
+    ctx: DeployContext,
+    input: KubectlApplyInput,
+    member: string,
+    documents: Record<string, unknown>[],
+    dry: KubectlApplyDryRun,
+    targets: readonly string[] | undefined,
+    declared: Record<string, unknown>[],
+  ): Promise<PlannedOutputs> => {
+    if (!targets) return plannedOutputs(ctx, input, member, documents, dry);
+    const wanted = new Set(targets);
+    const all = Object.entries(input.outputs ?? {});
+    const inside = Object.fromEntries(all.filter(([, spec]) => wanted.has(spec.object)));
+    const outside = Object.fromEntries(all.filter(([, spec]) => !wanted.has(spec.object)));
+    const planned = Object.keys(inside).length > 0 ? await plannedOutputs(ctx, { ...input, outputs: inside }, member, documents, dry) : { known: {}, unknown: [] };
+    if (Object.keys(outside).length === 0) return planned;
+    const rest = { ...input, outputs: outside };
+    const live = await readOutputs(await liveReader(), outputRefs(member, rest, declared), rest, where(ctx, input));
+    const known = { ...planned.known, ...live };
+    const unknown = [...planned.unknown, ...Object.keys(outside).filter((n) => !(n in live))].sort();
+    return { known, unknown };
+  };
   return {
     kind: "kubectl-apply",
     // A server-side apply has no native undo (the previous object state is not
     // kept by the API server), so COMP003 requires the component to acknowledge
     // the compensation gap — the same posture as s3-sync/run-migration.
     rollbackPolicy: "needs-opt-out",
+    // #4300: a target names one object, `Kind/namespace/name`; the plan and the apply send those alone.
+    targets: "accept",
     /**
      * Dry-run the manifest against the cluster (#3998): the documents `run`
      * would apply, release attributes set, server-side applied with
      * `dryRun=All` as the same field manager, each compared with its live
      * object. The member is the step's `stack`, or the component.
      */
-    async plan(ctx: DeployContext, input: KubectlApplyInput): Promise<CapabilityPlan> {
+    async plan(ctx: DeployContext, stepInput: KubectlApplyInput): Promise<CapabilityPlan> {
+      const input = narrowedInput(ctx, stepInput);
       const member = input.stack ?? ctx.component;
-      const documents = (read ?? (await activities()).readManifestDocuments)(input.manifest);
+      const read_ = (read ?? (await activities()).readManifestDocuments)(input.manifest);
+      const targets = ctx.targets && ctx.targets.length > 0 ? ctx.targets : undefined;
+      const documents = targets ? targetedDocuments(member, input.manifest, read_, targets) : read_;
       const suffix = releaseAttributesSuffix(ctx.release);
       if (suffix !== "") annotateRelease(documents, suffix);
       const { result, planDigest } = await dryRunOf(ctx, input, member, documents);
       const artifact: KubectlApplyPlanArtifact = { kind: "kubectl-apply-plan", planDigest, documents };
-      const outputs = input.outputs ? await plannedOutputs(ctx, input, member, documents, result) : undefined;
-      return { member, planDigest, artifact, changeSet: changeSetPartOf(member, planDigest, result), ...(outputs ? { outputs } : {}) };
+      const outputs = input.outputs ? await targetedPlannedOutputs(ctx, input, member, documents, result, targets, read_) : undefined;
+      return {
+        member,
+        planDigest,
+        artifact,
+        changeSet: changeSetPartOf(member, planDigest, result),
+        ...(outputs ? { outputs } : {}),
+        ...(targets ? { targets } : {}),
+      };
     },
     /**
      * The fields the step names as outputs, as the cluster holds them now
@@ -421,7 +495,8 @@ export function createKubectlApplyCapability(
       const documents = (read ?? (await activities()).readManifestDocuments)(input.manifest);
       return liveOutputs(ctx, input, documents);
     },
-    async run(ctx: DeployContext, input: KubectlApplyInput): Promise<KubectlApplyOutcome> {
+    async run(ctx: DeployContext, stepInput: KubectlApplyInput): Promise<KubectlApplyOutcome> {
+      const input = narrowedInput(ctx, stepInput);
       const member = input.stack ?? ctx.component;
       const approved = ctx.plans?.[member];
       if (isPlanArtifact(approved)) {
@@ -439,7 +514,11 @@ export function createKubectlApplyCapability(
       // workload the build stamped, in what it applies; the committed manifest is not touched.
       const suffix = releaseAttributesSuffix(ctx.release);
       let documents: Record<string, unknown>[] | undefined;
-      if (suffix !== "") {
+      if (ctx.targets && ctx.targets.length > 0) {
+        // #4300: only the targeted objects, and no prune (`narrowedInput`).
+        documents = targetedDocuments(member, input.manifest, (read ?? loaded!.readManifestDocuments)(input.manifest), ctx.targets);
+        if (suffix !== "") annotateRelease(documents, suffix);
+      } else if (suffix !== "") {
         documents = (read ?? loaded!.readManifestDocuments)(input.manifest);
         if (annotateRelease(documents, suffix) === 0) documents = undefined;
       }