@intentius/chant 0.39.0 → 0.41.0

package/dist/apply.d.ts

@@ -0,0 +1,171 @@
+/**
+ * The apply contract (#1446) — what a lexicon's applier is allowed to mean.
+ *
+ * The peer of `./observation.ts`, and it exists for the same reason on the other
+ * side of the lifecycle.
+ *
+ * The read path had two ways to return nothing for a declared entity and no way
+ * to tell them apart — "the provider says it is absent" versus "I never looked"
+ * — and the second was classifying as `create`. #1089 made that a tri-state and
+ * #1201 built a conformance suite so a lexicon could not pass by returning a
+ * well-shaped result that still proposed a create.
+ *
+ * The write path had the identical hole. An applier could skip a resource and
+ * report nothing:
+ *
+ *     const mapper = MAPPERS[r.kind];
+ *     if (!mapper) {
+ *       console.log(`skip: no mapper for kind ${r.kind}`);
+ *       continue;                    // never appears in `applied`, or anywhere
+ *     }
+ *
+ * A caller receiving `{ applied: [...] }` could not distinguish a complete apply
+ * from one that dropped half the manifest, and `ApplyOp` had nothing to gate on.
+ * A `console.log` on stdout is not a signal in a result, the same way a warn on
+ * stderr was not a signal in a change set (#1447 was the concrete bug; #1457
+ * found the same shape in two more appliers).
+ *
+ * The contract is a tri-state, per resource in the plan:
+ *
+ *   - **APPLIED** — the provider was called and converged. Carries the action
+ *     (`created` / `updated` / `unchanged`) and the physical id when resolved.
+ *   - **PRUNED** — owned, no longer declared, deleted.
+ *   - **NOT-ATTEMPTED** — carrying a total {@link NotAttemptedReason}. Never
+ *     silent, never inferred from absence.
+ *
+ * The three are **disjoint and total**: every resource the applier was given
+ * appears in exactly one. That is the assertion the conformance suite exists to
+ * make, and the one the gcp skip failed.
+ *
+ * Compatibility: an applier may keep returning its own shape. The envelope is
+ * discriminated by its literal `apply: "v1"` field, the same mechanism
+ * `observation: "v1"` uses, so an un-migrated applier normalizes to "everything
+ * I was handed, I attempted" and nothing breaks. Reporting NOT-ATTEMPTED
+ * requires the envelope — which is the point: you cannot claim the guarantee
+ * without adopting the shape that can express its absence.
+ */
+/**
+ * Why a resource in the plan was not attempted. Total: an applier that skips a
+ * resource must pick one of these, and consumers may switch exhaustively.
+ *
+ * - `unsupported-kind` — the lexicon has no mapper/writer for this type. The
+ *   resource is declared and simply was not written.
+ * - `no-credentials` — no usable credentials/authorization for the target.
+ * - `no-binding` — the environment resolves to no concrete target (no cluster
+ *   context, no subscription, no resource group, no endpoint).
+ * - `dependency-failed` — an upstream resource in the same run failed, so this
+ *   one was never reached. Distinct from a failure of its own.
+ * - `filtered` — reached but deliberately withheld by a caller-requested scope.
+ * - `not-prunable` — an owned orphan of a kind the applier cannot enumerate or
+ *   delete. The prune-side shape: not "there was nothing to prune" but "I could
+ *   not look for anything to prune here".
+ */
+export type NotAttemptedReason = "unsupported-kind" | "no-credentials" | "no-binding" | "dependency-failed" | "filtered" | "not-prunable";
+/** Every legal {@link NotAttemptedReason}, for validation and conformance checks. */
+export declare const NOT_ATTEMPTED_REASONS: readonly NotAttemptedReason[];
+/** True when `value` is a legal {@link NotAttemptedReason}. */
+export declare function isNotAttemptedReason(value: unknown): value is NotAttemptedReason;
+/** What an apply did to a resource that it did reach. */
+export type AppliedAction = "created" | "updated" | "unchanged";
+/** Every legal {@link AppliedAction}. */
+export declare const APPLIED_ACTIONS: readonly AppliedAction[];
+/** How a resource is named across appliers whose native vocabularies differ. */
+export interface ApplyRef {
+    /**
+     * The provider's own type name — a CNRM `kind`, an ARM `type`, a
+     * CloudFormation resource type, a Fly entity class. Kept verbatim rather than
+     * normalized into a chant vocabulary, so an applier stays true to its target.
+     */
+    kind: string;
+    /** The resource's name within its scope. */
+    name: string;
+}
+/** APPLIED — the provider was called and the resource converged. */
+export interface AppliedResource extends ApplyRef {
+    action: AppliedAction;
+    /** Provider-assigned identifier, when the response carried one. */
+    physicalId?: string;
+}
+/** PRUNED — owned, no longer declared, deleted. */
+export interface PrunedResource extends ApplyRef {
+    /**
+     * False when the delete was a no-op because the resource was already gone.
+     * Still PRUNED: the applier looked, decided, and acted.
+     */
+    deleted: boolean;
+}
+/** NOT-ATTEMPTED — no provider call was made, and why. */
+export interface NotAttemptedResource extends ApplyRef {
+    reason: NotAttemptedReason;
+    /** Detail for the operator: the status and body, the missing binding, the unsupported kind. */
+    detail?: string;
+}
+/**
+ * The apply envelope. Explicitly versioned: `apply: "v1"`, which discriminates
+ * it from an applier's own return shape.
+ */
+export interface ApplyResult {
+    /** Discriminant + wire version. */
+    readonly apply: "v1";
+    applied: AppliedResource[];
+    pruned?: PrunedResource[];
+    /** Omit or leave empty when everything in the plan was attempted. */
+    notAttempted?: NotAttemptedResource[];
+}
+/** Normalized form every consumer works with. All three arrays always present. */
+export interface NormalizedApply {
+    applied: AppliedResource[];
+    pruned: PrunedResource[];
+    notAttempted: NotAttemptedResource[];
+}
+/** True when `value` is the versioned {@link ApplyResult} envelope. */
+export declare function isApplyResult(value: unknown): value is ApplyResult;
+/**
+ * Build an {@link ApplyResult}. Appliers use this rather than writing the
+ * discriminant by hand.
+ */
+export declare function applyResult(applied: AppliedResource[], pruned?: PrunedResource[], notAttempted?: NotAttemptedResource[]): ApplyResult;
+/**
+ * Normalize an applier's return value.
+ *
+ * A non-envelope value normalizes to "everything I was handed, I attempted" —
+ * an empty `notAttempted`. That is the compatibility path, and it is also
+ * exactly the claim an un-migrated applier is implicitly making, so nothing is
+ * invented on its behalf.
+ *
+ * `undefined` normalizes to three empty arrays. An applier that means "I applied
+ * nothing because I could not" must say so with {@link notAttemptedAll} rather
+ * than returning nothing, for the same reason `unobservedAll` exists on the read
+ * side.
+ */
+export declare function normalizeApply(value: ApplyResult | Partial<NormalizedApply> | undefined): NormalizedApply;
+/**
+ * Mark every named resource NOT-ATTEMPTED with one reason — the whole-run
+ * failure case (no credentials, no binding, the transport never came up). Core
+ * applies this when an applier throws, so a thrown apply degrades to an honest
+ * "did not attempt" per resource instead of an empty result that reads as a
+ * successful no-op.
+ */
+export declare function notAttemptedAll(refs: Iterable<ApplyRef>, reason: NotAttemptedReason, detail?: string): NotAttemptedResource[];
+/** A resource's identity within one apply, for disjointness checks. */
+export declare function applyRefKey(ref: ApplyRef): string;
+/**
+ * Every resource that appears in more than one bucket. Empty is the contract;
+ * a non-empty result means the applier both wrote and skipped the same
+ * resource, which is not a state that can be true.
+ *
+ * Pruned is checked against the other two but not against itself: an applier
+ * may legitimately apply a resource and prune a different, same-named one only
+ * if their kinds differ, and {@link applyRefKey} already separates those.
+ */
+export declare function overlappingRefs(result: NormalizedApply): string[];
+/**
+ * Resources in `plan` that the result accounts for in no bucket — the silent
+ * drop this contract exists to make impossible.
+ *
+ * The conformance suite's central assertion. Before #1447, gcp's applier failed
+ * exactly this: an unmapped kind was in the plan, in no bucket, and the result
+ * looked complete.
+ */
+export declare function unaccountedRefs(plan: Iterable<ApplyRef>, result: NormalizedApply): string[];
+//# sourceMappingURL=apply.d.ts.map

package/dist/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../src/apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,kBAAkB,GAC1B,kBAAkB,GAClB,gBAAgB,GAChB,YAAY,GACZ,mBAAmB,GACnB,UAAU,GACV,cAAc,CAAC;AAEnB,qFAAqF;AACrF,eAAO,MAAM,qBAAqB,EAAE,SAAS,kBAAkB,EAO9D,CAAC;AAEF,+DAA+D;AAC/D,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAEhF;AAED,yDAAyD;AACzD,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;AAEhE,yCAAyC;AACzC,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EAAwC,CAAC;AAE7F,gFAAgF;AAChF,MAAM,WAAW,QAAQ;IACvB;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,oEAAoE;AACpE,MAAM,WAAW,eAAgB,SAAQ,QAAQ;IAC/C,MAAM,EAAE,aAAa,CAAC;IACtB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,mDAAmD;AACnD,MAAM,WAAW,cAAe,SAAQ,QAAQ;IAC9C;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,0DAA0D;AAC1D,MAAM,WAAW,oBAAqB,SAAQ,QAAQ;IACpD,MAAM,EAAE,kBAAkB,CAAC;IAC3B,+FAA+F;IAC/F,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,mCAAmC;IACnC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IACrB,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,MAAM,CAAC,EAAE,cAAc,EAAE,CAAC;IAC1B,qEAAqE;IACrE,YAAY,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACvC;AAED,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,YAAY,EAAE,oBAAoB,EAAE,CAAC;CACtC;AAED,uEAAuE;AACvE,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,eAAe,EAAE,EAC1B,MAAM,CAAC,EAAE,cAAc,EAAE,EACzB,YAAY,CAAC,EAAE,oBAAoB,EAAE,GACpC,WAAW,CAOb;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,GAAG,SAAS,GAAG,eAAe,CAOzG;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC,EACxB,MAAM,EAAE,kBAAkB,EAC1B,MAAM,CAAC,EAAE,MAAM,GACd,oBAAoB,EAAE,CAExB;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAEjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,EAAE,CAYjE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,eAAe,GAAG,MAAM,EAAE,CAM3F"}

package/dist/cli/commands/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/doctor.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CA4PvE"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/doctor.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAoSvE"}

package/dist/codegen/naming.d.ts

@@ -1,12 +1,32 @@
 /**
  * Collision-free naming strategy for TypeScript class names.
  *
- * 5-phase algorithm:
+ * 6-phase algorithm:
  * 1. Priority names (backward compatibility)
+ * 1a. Reserved names — names this lexicon has already published (chant #1459)
  * 2. Priority aliases (additional short names)
  * 3. Short names (last segment of type)
  * 4. Collision resolution (service-prefixed)
  * 5. Property type aliases (globally unique defs)
+ *
+ * ## Why phase 1a exists
+ *
+ * Phases 3 and 4 assign a short name to whoever asks first and service-qualify
+ * everyone after. Membership of that contest is the whole input set, so a
+ * resource's name was a function of its NEIGHBOURS: removing
+ * `AWS::Athena::Session` upstream freed `Session`, and `AWS::Macie::Session`
+ * silently changed from `MacieSession` to `Session` — a breaking rename for a
+ * resource whose schema had not moved. Adding a resource does the same in
+ * reverse: `AWS::QuickSight::Space` appearing renamed `AWS::SageMaker::Space`
+ * from `Space` to `SageMakerSpace`.
+ *
+ * Worse, it is reversible. These are read-only registry types that come and go,
+ * so a name could flip back on the next upgrade and break consumers again.
+ *
+ * Reserved names invert the bias: a name that has already shipped belongs to
+ * the type that shipped it, and a newcomer colliding with it gets qualified
+ * instead. A published name then changes only when its own type disappears,
+ * which is a genuine breaking change rather than an incidental one.
  */
 /**
  * Minimal input required by the naming strategy — avoids coupling
@@ -35,7 +55,34 @@ export interface NamingConfig {
     shortName: (typeName: string) => string;
     /** Extract the service name from a type name (e.g. "Vendor::Service::Resource" → "Service"). */
     serviceName: (typeName: string) => string;
+    /**
+     * chant #1459 — spec type name → the TypeScript name this lexicon has
+     * already published for it, normally read from the committed
+     * `surface.snapshot.json` via {@link reservedNamesFromSnapshot}.
+     *
+     * Claimed before short names are contested, so a shipped name is not taken
+     * away from its owner by an unrelated upstream change. Omit for a lexicon
+     * with no published surface yet; an entry for a type that is no longer in
+     * the input is ignored, so a removed type frees its name for reuse.
+     */
+    reservedNames?: Record<string, string>;
 }
+/**
+ * The names a lexicon has already published, read from a committed surface
+ * snapshot (chant #1459).
+ *
+ * The snapshot is keyed by TypeScript name with the spec type inside, which is
+ * exactly the mapping phase 1a needs, inverted. Only `resource` entries are
+ * reserved: property-type names are derived from their owning resource's name
+ * (phase 5), so pinning the resource pins them, and reserving them separately
+ * would freeze aliases that are meant to follow their parent.
+ */
+export declare function reservedNamesFromSnapshot(snapshot: {
+    entries?: Record<string, {
+        kind?: string;
+        resourceType?: string;
+    }>;
+} | undefined): Record<string, string>;
 export declare class NamingStrategy {
     private config;
     private assigned;

package/dist/codegen/naming.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../../src/codegen/naming.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxC;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,oEAAoE;IACpE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC1C,yDAAyD;IACzD,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChE,+DAA+D;IAC/D,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,+FAA+F;IAC/F,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IACxC,gGAAgG;IAChG,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;CAC3C;AAED,qBAAa,cAAc;IAMW,OAAO,CAAC,MAAM;IALlD,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,gBAAgB,CAA0C;gBAEtD,OAAO,EAAE,WAAW,EAAE,EAAU,MAAM,EAAE,YAAY;IA8GhE,gDAAgD;IAChD,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI7C,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE;IAInC,sDAAsD;IACtD,cAAc,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE;IAcpC,8CAA8C;IAC9C,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS;CAGvE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAG5E"}
+{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../../src/codegen/naming.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxC;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,oEAAoE;IACpE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC1C,yDAAyD;IACzD,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChE,+DAA+D;IAC/D,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,+FAA+F;IAC/F,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IACxC,gGAAgG;IAChG,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IAC1C;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,GAAG,SAAS,GAC3F,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASxB;AAED,qBAAa,cAAc;IAMW,OAAO,CAAC,MAAM;IALlD,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,gBAAgB,CAA0C;gBAEtD,OAAO,EAAE,WAAW,EAAE,EAAU,MAAM,EAAE,YAAY;IA+HhE,gDAAgD;IAChD,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI7C,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE;IAInC,sDAAsD;IACtD,cAAc,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE;IAcpC,8CAA8C;IAC9C,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS;CAGvE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAG5E"}

package/dist/codegen/validate.d.ts

@@ -14,6 +14,11 @@ export interface ValidateResult {
     success: boolean;
     checks: ValidateCheck[];
 }
+/**
+ * Set by the publish workflow to arm the release-time surface gate
+ * (chant #1473). Absent in ordinary CI, where upstream drift is expected.
+ */
+export declare const RELEASE_GATE_ENV = "CHANT_RELEASE_GATE";
 export interface LexiconValidationConfig {
     /** Filename of the lexicon JSON (e.g. "lexicon-mydom.json") */
     lexiconJsonFilename: string;
@@ -29,6 +34,32 @@ export interface LexiconValidationConfig {
     requiredNamesMatchSubstring?: boolean;
     /** Base path of the lexicon package */
     basePath: string;
+    /**
+     * chant #1473 — this lexicon's release is gated on the generated API
+     * matching the committed `surface.snapshot.json`.
+     *
+     * Two conditions, both required. The lexicon opts in here, AND
+     * {@link RELEASE_GATE_ENV} is set — which the publish workflow does and
+     * ordinary CI does not.
+     *
+     * The env half is not caution, it is correctness. `validate` runs on every
+     * PR, and the upstream a lexicon generates from can move at any time: the
+     * CloudFormation archive republishes schemas several times a day, and some
+     * of those edits do change the surface. A hard surface check on every PR
+     * would turn any unrelated change red the moment upstream moved, which is
+     * the same trap the spec pin fell into one level down. Drift between
+     * releases is expected and is what the scheduled lexicon-upgrade job exists
+     * to report (#1423).
+     *
+     * What must never happen is *publishing* a surface nobody reviewed. That is
+     * a release-time property, so it is checked at release time.
+     *
+     * Opt-in per lexicon because k8s and azure are currently adrift from their
+     * own baselines (393 and 483 entries, #1475).
+     */
+    checkSurfaceSnapshot?: boolean;
+    /** Environment to read {@link RELEASE_GATE_ENV} from. Defaults to `process.env`; overridden in tests. */
+    env?: NodeJS.ProcessEnv;
     /** Path to the generated directory (defaults to basePath/src/generated) */
     generatedDir?: string;
     /** Coverage thresholds (optional) */

package/dist/codegen/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/codegen/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAoC,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEvF,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC,+DAA+D;IAC/D,mBAAmB,EAAE,MAAM,CAAC;IAC5B,yEAAyE;IACzE,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB;;;;;;OAMG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;CACzC;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,cAAc,CAAC,CA4GvG;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAWlE"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/codegen/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAoC,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGvF,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,uBAAuB,CAAC;AAErD,MAAM,WAAW,uBAAuB;IACtC,+DAA+D;IAC/D,mBAAmB,EAAE,MAAM,CAAC;IAC5B,yEAAyE;IACzE,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB;;;;;;OAMG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,yGAAyG;IACzG,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;CACzC;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,cAAc,CAAC,CAqJvG;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAWlE"}

package/dist/discovery/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/discovery/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAQ/C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAI1D;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;IACrB,gGAAgG;IAChG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,YAAY,EAAE,CAAC;IAE5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE7B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClC,8DAA8D;IAC9D,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACvC,qDAAqD;IACrD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mDAAmD;IACnD,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB;;;OAGG;IACH,aAAa,EAAE,YAAY,EAAE,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAyRjG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/discovery/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAQ/C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AA8D1D;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;IACrB,gGAAgG;IAChG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,YAAY,EAAE,CAAC;IAE5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE7B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClC,8DAA8D;IAC9D,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACvC,qDAAqD;IACrD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mDAAmD;IACnD,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB;;;OAGG;IACH,aAAa,EAAE,YAAY,EAAE,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CA0RjG"}

package/dist/index.d.ts

@@ -48,6 +48,7 @@ export * from "./import/parser.js";
 export * from "./import/generator.js";
 export * from "./lexicon.js";
 export * from "./observation.js";
+export * from "./apply.js";
 export * from "./deep-observation.js";
 export * from "./owner-chain.js";
 export * from "./lexicon-integrity.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,QAAQ,CAAC;AACvB,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC;AACtB,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,4BAA4B,CAAC;AAC3C,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,YAAY,GAClB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,kBAAkB,EAClB,2BAA2B,EAC3B,oBAAoB,EACpB,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,qBAAqB,GAC3B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,OAAO,EACP,YAAY,EACZ,YAAY,EACZ,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,gBAAgB,GACtB,MAAM,0BAA0B,CAAC;AAClC,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAElC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAClE,cAAc,EAAE,iBAAiB,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC5F,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/apply.test.ts

@@ -0,0 +1,169 @@
+import { describe, test, expect } from "vitest";
+import {
+  NOT_ATTEMPTED_REASONS,
+  isNotAttemptedReason,
+  isApplyResult,
+  applyResult,
+  normalizeApply,
+  notAttemptedAll,
+  applyRefKey,
+  overlappingRefs,
+  unaccountedRefs,
+  type ApplyRef,
+} from "./apply";
+
+const ref = (kind: string, name: string): ApplyRef => ({ kind, name });
+
+describe("NotAttemptedReason is total (#1446)", () => {
+  test("every reason is recognised, and nothing else is", () => {
+    for (const r of NOT_ATTEMPTED_REASONS) expect(isNotAttemptedReason(r)).toBe(true);
+    expect(isNotAttemptedReason("skipped")).toBe(false);
+    expect(isNotAttemptedReason("")).toBe(false);
+    expect(isNotAttemptedReason(undefined)).toBe(false);
+  });
+
+  // The write-side peer of UnobservedReason. Free-form strings are what let the
+  // gcp skip say "no mapper for kind X" to stdout and nothing to the caller.
+  test("the prune-side reason exists, because it is a different fact", () => {
+    expect(NOT_ATTEMPTED_REASONS).toContain("not-prunable");
+    expect(NOT_ATTEMPTED_REASONS).toContain("unsupported-kind");
+  });
+});
+
+describe("the envelope discriminates itself (#1446)", () => {
+  test("isApplyResult recognises the versioned shape only", () => {
+    expect(isApplyResult(applyResult([]))).toBe(true);
+    expect(isApplyResult({ applied: [], pruned: [] })).toBe(false);
+    expect(isApplyResult({ apply: "v2" })).toBe(false);
+    expect(isApplyResult(null)).toBe(false);
+  });
+
+  test("applyResult omits empty buckets rather than emitting empty arrays", () => {
+    expect(applyResult([{ ...ref("Bucket", "a"), action: "created" }])).toEqual({
+      apply: "v1",
+      applied: [{ kind: "Bucket", name: "a", action: "created" }],
+    });
+  });
+});
+
+describe("normalizeApply (#1446)", () => {
+  test("an un-migrated applier's shape means 'everything I was handed, I attempted'", () => {
+    // The compatibility path. Nothing is invented on its behalf — an empty
+    // notAttempted is exactly the claim that shape implicitly makes.
+    const n = normalizeApply({ applied: [{ ...ref("K", "a"), action: "created" }] });
+    expect(n.notAttempted).toEqual([]);
+    expect(n.pruned).toEqual([]);
+    expect(n.applied).toHaveLength(1);
+  });
+
+  test("the envelope's notAttempted survives normalization", () => {
+    const n = normalizeApply(
+      applyResult([], [], [{ ...ref("SQLInstance", "db"), reason: "unsupported-kind" }]),
+    );
+    expect(n.notAttempted).toEqual([{ kind: "SQLInstance", name: "db", reason: "unsupported-kind" }]);
+  });
+
+  // The read side has the same rule for the same reason: returning nothing must
+  // not be a way to claim success over work that never happened.
+  test("undefined normalizes to empty, so 'I could not' must be said explicitly", () => {
+    expect(normalizeApply(undefined)).toEqual({ applied: [], pruned: [], notAttempted: [] });
+  });
+});
+
+describe("notAttemptedAll (#1446)", () => {
+  test("marks a whole plan with one reason, for the run-level failure", () => {
+    const out = notAttemptedAll([ref("K", "a"), ref("K", "b")], "no-credentials", "no token");
+    expect(out).toEqual([
+      { kind: "K", name: "a", reason: "no-credentials", detail: "no token" },
+      { kind: "K", name: "b", reason: "no-credentials", detail: "no token" },
+    ]);
+  });
+
+  test("omits detail when none is given", () => {
+    expect(notAttemptedAll([ref("K", "a")], "no-binding")).toEqual([
+      { kind: "K", name: "a", reason: "no-binding" },
+    ]);
+  });
+});
+
+describe("the three buckets are disjoint (#1446)", () => {
+  test("no overlap is the contract", () => {
+    expect(
+      overlappingRefs({
+        applied: [{ ...ref("K", "a"), action: "created" }],
+        pruned: [{ ...ref("K", "b"), deleted: true }],
+        notAttempted: [{ ...ref("K", "c"), reason: "unsupported-kind" }],
+      }),
+    ).toEqual([]);
+  });
+
+  // A resource cannot be both written and skipped. An applier reporting that has
+  // a bug the return shape would otherwise hide.
+  test("the same resource in two buckets is reported", () => {
+    expect(
+      overlappingRefs({
+        applied: [{ ...ref("K", "a"), action: "created" }],
+        pruned: [],
+        notAttempted: [{ ...ref("K", "a"), reason: "filtered" }],
+      }),
+    ).toEqual(["K/a"]);
+  });
+
+  test("same name, different kind, is not an overlap", () => {
+    expect(
+      overlappingRefs({
+        applied: [{ ...ref("Bucket", "x"), action: "created" }],
+        pruned: [{ ...ref("Topic", "x"), deleted: true }],
+        notAttempted: [],
+      }),
+    ).toEqual([]);
+  });
+});
+
+describe("nothing in the plan is dropped (#1446)", () => {
+  // The suite's central assertion, and the one gcp failed before #1447: the
+  // unmapped kind was in the plan, in no bucket, and the result looked complete.
+  test("a plan entry in no bucket is reported", () => {
+    const plan = [ref("Bucket", "mapped"), ref("SQLInstance", "unmapped")];
+    const dropped = unaccountedRefs(plan, {
+      applied: [{ ...ref("Bucket", "mapped"), action: "created" }],
+      pruned: [],
+      notAttempted: [],
+    });
+    expect(dropped).toEqual(["SQLInstance/unmapped"]);
+  });
+
+  test("the same plan accounted for in notAttempted passes", () => {
+    const plan = [ref("Bucket", "mapped"), ref("SQLInstance", "unmapped")];
+    expect(
+      unaccountedRefs(plan, {
+        applied: [{ ...ref("Bucket", "mapped"), action: "created" }],
+        pruned: [],
+        notAttempted: [{ ...ref("SQLInstance", "unmapped"), reason: "unsupported-kind" }],
+      }),
+    ).toEqual([]);
+  });
+
+  test("an empty plan is trivially accounted for", () => {
+    expect(unaccountedRefs([], { applied: [], pruned: [], notAttempted: [] })).toEqual([]);
+  });
+
+  // Prune deletes things the plan does not contain, by definition — so a pruned
+  // resource being outside the plan is correct, not a drop.
+  test("a pruned resource outside the plan is not a drop", () => {
+    expect(
+      unaccountedRefs([ref("Bucket", "keep")], {
+        applied: [{ ...ref("Bucket", "keep"), action: "unchanged" }],
+        pruned: [{ ...ref("Bucket", "orphan"), deleted: true }],
+        notAttempted: [],
+      }),
+    ).toEqual([]);
+  });
+});
+
+describe("applyRefKey", () => {
+  test("separates resources by kind and name", () => {
+    expect(applyRefKey(ref("Bucket", "x"))).toBe("Bucket/x");
+    expect(applyRefKey(ref("Topic", "x"))).not.toBe(applyRefKey(ref("Bucket", "x")));
+  });
+});