@fjall/deploy-core 2.27.0 → 2.29.0

package/dist/src/orchestration/application/plan/loadDeployPlan.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Deploy-plan loading — reads each changed stack's synthesised template from
+ * cdk.out and delegates to {@link computeDeployPlan} (live-template diff +
+ * registry overlay). Extracted from the approval gate so the unconditional
+ * destruction gate shares the SAME computation: `createMemoisedPlanLoader`
+ * guarantees a plan-gated deploy never diffs twice, while a non-engaged deploy
+ * computes the plan exactly once for the destruction gate.
+ */
+import { type Result } from "@fjall/generator";
+import type { CfnRegistrySummaryReader } from "../../../services/infrastructure/CfnRegistryService.js";
+import type { ChangeSetProbeRunner } from "../../../services/infrastructure/changeSetProbe.js";
+import { type CfnTemplateReader } from "./computeDeployPlan.js";
+import type { DeployPlan } from "./types.js";
+export interface LoadDeployPlanParams {
+    cfnService: CfnTemplateReader;
+    cdkOutPath: string;
+    changedStacks: string[];
+    assemblyDigest: string;
+    registry?: CfnRegistrySummaryReader;
+    changeSetProbe?: ChangeSetProbeRunner;
+    abortSignal?: AbortSignal;
+}
+/** A zero-argument plan supplier shared between the gates. */
+export type DeployPlanLoader = () => Promise<Result<DeployPlan, Error>>;
+export declare function loadDeployPlan(params: LoadDeployPlanParams): Promise<Result<DeployPlan, Error>>;
+/**
+ * Memoise the plan computation for one deploy invocation: the first call
+ * computes (template reads + live diff + registry overlay), every later call
+ * returns the same settled promise — including a failure, which both gates
+ * must observe identically.
+ */
+export declare function createMemoisedPlanLoader(params: LoadDeployPlanParams): DeployPlanLoader;

package/dist/src/orchestration/application/plan/loadDeployPlan.js

@@ -0,0 +1 @@
+import{join as c}from"node:path";import{readFile as a}from"node:fs/promises";import{failure as l}from"@fjall/generator";import{maskSensitiveOutput as s}from"@fjall/util";import{computeDeployPlan as f}from"./computeDeployPlan.js";async function d(e){const t=[];for(const r of e.changedStacks){const i=c(e.cdkOutPath,`${r}.template.json`);let o;try{o=JSON.parse(await a(i,"utf8"))}catch(n){return l(new Error(s(`Failed to read synthesised template for ${r}: ${n instanceof Error?n.message:String(n)}`)))}t.push({stackName:r,newTemplate:o})}return f({cfnService:e.cfnService,stacks:t,assemblyDigest:e.assemblyDigest,...e.registry!==void 0?{registry:e.registry}:{},...e.changeSetProbe!==void 0?{changeSetProbe:e.changeSetProbe}:{},...e.abortSignal!==void 0?{abortSignal:e.abortSignal}:{}})}function y(e){let t;return()=>(t??=d(e),t)}export{y as createMemoisedPlanLoader,d as loadDeployPlan};

package/dist/src/orchestration/application/plan/pinnedNames.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Pinned-name detection: a resource is custom-named iff the property named by
+ * the registry schema's `primaryIdentifier` (fallback: the small
+ * `@fjall/util` map for types whose identifier is a generated attribute) is
+ * explicitly present in the synthesised template with a LITERAL value. The
+ * template is the source of truth — CDK-generated names arrive as intrinsics
+ * (`Ref` / `Fn::*`) or are omitted entirely, so a literal string here means
+ * the author pinned the physical name.
+ *
+ * `replacement-required ∧ custom-named ⇒ pinned-name-replacement`: the update
+ * fails at apply time with "CloudFormation cannot update a stack when a
+ * custom-named resource requires replacing" — the Phase 2 destruction gate
+ * consumes this signal; Phase 1 annotates it on the plan row.
+ */
+/**
+ * Detect a pinned physical name on a template resource. Returns the literal
+ * name, or undefined when the resource is CDK-named (intrinsic or absent) or
+ * the naming property cannot be determined.
+ */
+export declare function findPinnedPhysicalName(params: {
+    resourceType: string;
+    /** The resource's template `Properties` block. */
+    properties: Record<string, unknown> | undefined;
+    /** Registry `primaryIdentifier` pointers, when the oracle resolved them. */
+    primaryIdentifier?: readonly string[];
+}): string | undefined;
+/**
+ * Extract a resource's `Properties` block from a parsed CloudFormation
+ * template without asserting the template's overall shape.
+ */
+export declare function resourcePropertiesFromTemplate(template: unknown, logicalId: string): Record<string, unknown> | undefined;

package/dist/src/orchestration/application/plan/pinnedNames.js

@@ -0,0 +1 @@
+import{PHYSICAL_NAME_FALLBACK_PROPERTIES as f}from"@fjall/util";const o="/properties/";function d(e){if(e===void 0||e.length!==1)return;const r=e[0];if(r===void 0||!r.startsWith(o))return;const n=r.slice(o.length);if(!(n===""||n.includes("/")))return n}function u(e){if(typeof e=="string"&&e!=="")return e;if(typeof e=="number")return String(e)}function s(e){if(e.properties===void 0)return;const r=d(e.primaryIdentifier);if(r!==void 0){const t=u(e.properties[r]);if(t!==void 0)return t}const n=f[e.resourceType];if(n!==void 0)return u(e.properties[n])}function p(e,r){if(typeof e!="object"||e===null)return;const n=e.Resources;if(typeof n!="object"||n===null)return;const t=n[r];if(typeof t!="object"||t===null)return;const i=t.Properties;if(!(typeof i!="object"||i===null||Array.isArray(i)))return i}export{s as findPinnedPhysicalName,p as resourcePropertiesFromTemplate};

package/dist/src/orchestration/application/plan/registryOverlay.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Registry verdict overlay — Layer 1 of the replacement oracle. The
+ * cloudformation-diff verdict (Layer 0) is computed from a stale bundled CDK
+ * resource spec and is retained only as the trigger; every changed property
+ * path is recomputed against the live registry catalogue
+ * (`createOnlyProperties` / `conditionalCreateOnlyProperties`):
+ *
+ *   path ∈ createOnly            → `will` (destructive)
+ *   path ∈ conditionalCreateOnly → `conditional` (destructive worst-case,
+ *                                   pending the Phase 3 change-set escalation)
+ *   path in NEITHER              → `none` — even where cloudformation-diff
+ *                                   said WILL_REPLACE (kills the false
+ *                                   AWS::RDS::DBInstance.Port replacement)
+ *
+ * Nested-path conservatism: cloudformation-diff reports top-level property
+ * names, so a change to a property with a createOnly SUB-pointer
+ * (`/properties/Foo/Bar`) is `conditional`, never silently `none`.
+ *
+ * Fail-closed degradation: when the oracle is unavailable for a type, the
+ * original diff verdict stands, annotated `verdictSource: "cdk-spec
+ * (unverified)"` — the oracle never fails the deploy.
+ *
+ * Every Layer-0 / Layer-1 disagreement is logged as stale-spec telemetry.
+ */
+import type { CfnRegistrySchemaSummary } from "../../../services/infrastructure/CfnRegistryService.js";
+import type { CfnRegistrySummaryReader } from "../../../services/infrastructure/CfnRegistryService.js";
+import type { ReplacementMode } from "../../../types/deployEvent.js";
+import type { StackTemplatePair } from "./buildDeployPlan.js";
+import type { DeployPlan, DeployPlanResourceChange } from "./types.js";
+type RegistryPathVerdict = "will" | "conditional" | "none";
+/**
+ * Advisory interruption notes for in-place updates that still disrupt service.
+ * Keyed `<resourceType>#<topLevelProperty>`. Display-only — never gates.
+ * Exported for the probe-parity pin: any note teaching "pin it" must name a
+ * pair `pinProbeCoverage` covers, or the note teaches a consent the
+ * destruction gate would halt as unprobeable.
+ */
+export declare const INTERRUPTION_NOTES: Readonly<Record<string, string>>;
+/** Recompute one changed top-level property's verdict from the catalogue. */
+export declare function registryVerdictForProperty(propertyName: string, summary: CfnRegistrySchemaSummary): RegistryPathVerdict;
+/** A Layer-0 vs Layer-1 disagreement — logged as stale-spec telemetry. */
+export interface RegistryVerdictDisagreement {
+    stack: string;
+    address: string;
+    resourceType: string;
+    cdkSpecMode: ReplacementMode;
+    registryMode: ReplacementMode;
+    /** The changed property paths whose verdicts drove the registry mode. */
+    paths: string[];
+}
+export interface OverlayResourceChangeResult {
+    change: DeployPlanResourceChange;
+    disagreement?: RegistryVerdictDisagreement;
+}
+/**
+ * Pure per-row recomputation. `summary === undefined` means the oracle was
+ * unavailable — the diff verdict stands, annotated unverified.
+ */
+export declare function overlayResourceChange(change: DeployPlanResourceChange, summary: CfnRegistrySchemaSummary | undefined, templateProperties: Record<string, unknown> | undefined): OverlayResourceChangeResult;
+/** Per-action tally — shared with the change-set escalation's recount. */
+export declare function recountActions(changes: readonly DeployPlanResourceChange[]): {
+    create: number;
+    update: number;
+    replace: number;
+    delete: number;
+    read: number;
+    "no-op": number;
+};
+export interface ApplyRegistryOverlayParams {
+    plan: DeployPlan;
+    registry: CfnRegistrySummaryReader;
+    /** The diffed template pairs — pinned-name detection reads Properties. */
+    stacks: readonly StackTemplatePair[];
+    abortSignal?: AbortSignal;
+}
+/**
+ * Apply the registry overlay to a computed plan. Never throws and never
+ * fails the plan: unavailable summaries degrade per-row to
+ * `"cdk-spec (unverified)"`. Summaries are fetched once per distinct resource
+ * type (the service memoises per run underneath).
+ */
+export declare function applyRegistryOverlay(params: ApplyRegistryOverlayParams): Promise<DeployPlan>;
+export {};

package/dist/src/orchestration/application/plan/registryOverlay.js

@@ -0,0 +1 @@
+import{maskSensitiveOutput as S}from"@fjall/util";import{logger as m}from"@fjall/util/logger";import{isAborted as g}from"../../../aws/organisations/types.js";import{isDataLoss as O}from"./classify.js";import{findPinnedPhysicalName as v,resourcePropertiesFromTemplate as h}from"./pinnedNames.js";import{renderPlanSummary as R}from"./renderDeployPlan.js";const P="RegistryOverlay",C={"AWS::RDS::DBInstance#Port":"port changes apply in place with a brief interruption (instance reboot + dependent-service re-point window); to keep the live port instead, pin it \u2014 set `port` in your fjall config to the current live value and the change disappears","AWS::RDS::DBCluster#Port":"port changes apply in place with a brief interruption (cluster reboot + dependent-service re-point window); to keep the live port instead, pin it \u2014 set `port` in your fjall config to the current live value and the change disappears"},N="/properties/";function k(e,t){const o=`${N}${e}`;if(t.createOnlyProperties.includes(o))return"will";if(t.conditionalCreateOnlyProperties.includes(o))return"conditional";const i=`${o}/`;return t.createOnlyProperties.some(s=>s.startsWith(i))||t.conditionalCreateOnlyProperties.some(s=>s.startsWith(i))?"conditional":"none"}function I(e){return e.includes("will")?"will":e.includes("conditional")?"conditional":"none"}function b(e,t){const o=t.map(i=>C[`${e.resourceType}#${i}`]).filter(i=>i!==void 0);if(o.length!==0)return o.join("; ")}function T(e){return(e.action==="update"||e.action==="replace")&&!e.retained}function D(e){return T(e)||e.action==="delete"}function M(e,t,o){if(e.action==="delete"&&t!==void 0){const n=v({resourceType:e.resourceType,properties:o,primaryIdentifier:t.primaryIdentifier});return{change:{...e,...n!==void 0?{pinnedPhysicalName:n}:{}}}}if(!T(e))return{change:e};if(t===void 0||e.propertyChanges.length===0)return{change:{...e,verdictSource:"cdk-spec (unverified)"}};const i=e.propertyChanges.map(n=>({path:n.path,verdict:k(n.path,t)})),p=I(i.map(n=>n.verdict)),s=p==="none"?"update":"replace",c=p,y=p!=="none",d=O({action:s,retained:e.retained,resourceType:e.resourceType}),u=e.propertyChanges.map((n,w)=>({...n,forcesReplacement:i[w]?.verdict!=="none"})),r=i.filter(n=>n.verdict==="none").map(n=>n.path),a=p==="none"?b(e,r):void 0,l=v({resourceType:e.resourceType,properties:o,primaryIdentifier:t.primaryIdentifier}),f={...e,action:s,replacementMode:c,destructive:y,dataLoss:d,propertyChanges:u,verdictSource:"registry",...a!==void 0?{interruptionNote:a}:{},...l!==void 0?{pinnedPhysicalName:l}:{}};return e.replacementMode===c?{change:f}:{change:f,disagreement:{stack:e.stack,address:e.address,resourceType:e.resourceType,cdkSpecMode:e.replacementMode,registryMode:c,paths:i.map(n=>n.path)}}}function x(e){const t={create:0,update:0,replace:0,delete:0,read:0,"no-op":0};for(const o of e)t[o.action]+=1;return t}async function B(e){const{plan:t,registry:o,stacks:i,abortSignal:p}=e,s=new Set(t.changes.filter(D).map(r=>r.resourceType));if(s.size===0)return t;const c=new Map;for(const r of s){if(g(p))break;const a=await o.getSchemaSummary(r,p);a.success?c.set(r,a.data):m.warn(P,"Registry oracle unavailable for type",{typeName:r,error:S(a.error.message)})}const y=new Map(i.map(r=>[r.stackName,r])),d=t.changes.map(r=>{const a=y.get(r.stack),l=r.action==="delete"?h(a?.oldTemplate,r.address):h(a?.newTemplate,r.address),{change:f,disagreement:n}=M(r,c.get(r.resourceType),l);return n!==void 0&&m.warn(P,"Registry verdict disagrees with bundled CDK spec",{...n,paths:n.paths.join(",")}),f}),u=x(d);return u["no-op"]=t.counts["no-op"],{...t,changes:d,counts:u,hasDestructiveChanges:d.some(r=>r.destructive),summary:R({counts:u,changes:d})}}export{C as INTERRUPTION_NOTES,B as applyRegistryOverlay,M as overlayResourceChange,x as recountActions,k as registryVerdictForProperty};

package/dist/src/orchestration/application/plan/renderDeployPlan.d.ts

@@ -14,5 +14,8 @@ export declare function renderPlanSummary(plan: Pick<DeployPlan, "counts" | "cha
 /** One line per resource change, grouped by action, e.g.
  * "± replace AWS::ECS::Service  WebAppCompute/Service (data loss)". */
 export declare function renderPlanLines(plan: Pick<DeployPlan, "changes">): string[];
-/** Map a computed plan's changes down to the wire `plan.available` PlanChange[]. */
+/** Map a computed plan's changes down to the wire `plan.available` PlanChange[].
+ * `verdictSource` is deliberately NOT threaded here — the wire shape is a
+ * cross-package contract; it lands with the Phase 2 destruction-ticket wire
+ * contract. */
 export declare function toWirePlanChanges(plan: Pick<DeployPlan, "changes">): PlanChange[];

package/dist/src/orchestration/application/plan/renderDeployPlan.js

@@ -1 +1 @@
-const p={create:0,update:1,replace:2,delete:3,read:4,"no-op":5},c={create:"+",update:"~",replace:"\xB1",delete:"-",read:">","no-op":" "};function i(a){const{counts:e}=a,t=[];if(e.create>0&&t.push(`${e.create} to create`),e.update>0&&t.push(`${e.update} to update`),e.replace>0&&t.push(`${e.replace} to replace`),e.delete>0&&t.push(`${e.delete} to destroy`),e.read>0&&t.push(`${e.read} to read`),t.length===0)return"No changes";const s=a.changes.filter(n=>n.destructive).length,o=a.changes.filter(n=>n.dataLoss).length,r=[];s>0&&r.push(`${s} destructive`),o>0&&r.push(`${o} with data loss`);const d=t.join(", ");return r.length>0?`${d} (${r.join(", ")})`:d}function u(a){return a.changes.slice().sort((e,t)=>p[e.action]-p[t.action]||`${e.stack}/${e.address}`.localeCompare(`${t.stack}/${t.address}`)).map(e=>{const t=[];e.replacementMode==="may"&&t.push("may replace"),e.dataLoss&&t.push("data loss"),e.retained&&t.push("retained");const s=t.length>0?` (${t.join(", ")})`:"";return`${c[e.action]} ${e.action.padEnd(7)} ${e.resourceType}  ${e.stack}/${e.address}${s}`})}function l(a){return a.changes.map(e=>({address:e.address,resourceType:e.resourceType,action:e.action,stack:e.stack,replacementMode:e.replacementMode,dataLoss:e.dataLoss,...e.propertyChanges.length>0&&{propertyChanges:e.propertyChanges}}))}export{u as renderPlanLines,i as renderPlanSummary,l as toWirePlanChanges};
+const i={create:0,update:1,replace:2,delete:3,read:4,"no-op":5},c={create:"+",update:"~",replace:"\xB1",delete:"-",read:">","no-op":" "};function p(a){const{counts:e}=a,t=[];if(e.create>0&&t.push(`${e.create} to create`),e.update>0&&t.push(`${e.update} to update`),e.replace>0&&t.push(`${e.replace} to replace`),e.delete>0&&t.push(`${e.delete} to destroy`),e.read>0&&t.push(`${e.read} to read`),t.length===0)return"No changes";const s=a.changes.filter(n=>n.destructive).length,o=a.changes.filter(n=>n.dataLoss).length,r=[];s>0&&r.push(`${s} destructive`),o>0&&r.push(`${o} with data loss`);const d=t.join(", ");return r.length>0?`${d} (${r.join(", ")})`:d}function u(a){return a.changes.slice().sort((e,t)=>i[e.action]-i[t.action]||`${e.stack}/${e.address}`.localeCompare(`${t.stack}/${t.address}`)).map(e=>{const t=[];e.replacementMode==="may"&&t.push("may replace"),e.replacementMode==="conditional"&&t.push("conditional replace"),e.dataLoss&&t.push("data loss"),e.retained&&t.push("retained"),(e.verdictSource==="cdk-spec (unverified)"||e.verdictSource==="registry (change-set unverified)")&&t.push("unverified");const s=t.length>0?` (${t.join(", ")})`:"";return`${c[e.action]} ${e.action.padEnd(7)} ${e.resourceType}  ${e.stack}/${e.address}${s}`})}function l(a){return a.changes.map(e=>({address:e.address,resourceType:e.resourceType,action:e.action,stack:e.stack,replacementMode:e.replacementMode,dataLoss:e.dataLoss,...e.propertyChanges.length>0&&{propertyChanges:e.propertyChanges}}))}export{u as renderPlanLines,p as renderPlanSummary,l as toWirePlanChanges};

package/dist/src/orchestration/application/plan/types.d.ts

@@ -8,6 +8,20 @@
  * maps a DeployPlan down to the wire shape.
  */
 import type { ChangeCounts, PlanAction, PlanPropertyChange, ReplacementMode } from "../../../types/deployEvent.js";
+/**
+ * Which oracle layer produced a row's replacement verdict. Precedence:
+ * change-set > registry > cdk-spec. `"change-set"` rows carry the
+ * authoritative verdict from the Phase 3 review-only change-set probe
+ * (`applyChangeSetEscalation`). `"registry (change-set unverified)"` marks a
+ * registry-conditional row the probe was escalated for but could not verify
+ * (probe denied, timed out, or aborted) — the conservative registry verdict
+ * stands. `"cdk-spec (unverified)"` marks rows the registry oracle could not
+ * verify (oracle unavailable, or a replacement verdict with no property paths
+ * to recompute from) — the stale bundled CDK spec is never silently treated
+ * as authoritative.
+ */
+export declare const REPLACEMENT_VERDICT_SOURCES: readonly ["registry", "registry (change-set unverified)", "change-set", "cdk-spec (unverified)"];
+export type ReplacementVerdictSource = (typeof REPLACEMENT_VERDICT_SOURCES)[number];
 /** A single resource change in a computed deploy plan. */
 export interface DeployPlanResourceChange {
     /** The stack the resource belongs to. */
@@ -28,6 +42,23 @@ export interface DeployPlanResourceChange {
     retained: boolean;
     /** Per-property change detail — paths only, never values (no secret leak). */
     propertyChanges: PlanPropertyChange[];
+    /**
+     * Oracle layer behind the replacement verdict. Absent when no verdict
+     * question arises (creates, imports, rows the overlay never evaluated).
+     */
+    verdictSource?: ReplacementVerdictSource;
+    /**
+     * Advisory service-interruption note for an in-place update (e.g. an RDS
+     * port change reboots the instance). Display-only — never gates.
+     */
+    interruptionNote?: string;
+    /**
+     * Literal physical name pinned in the template (via the registry
+     * `primaryIdentifier` or the `@fjall/util` fallback map). A pinned name on
+     * a replacement row means CloudFormation will REFUSE the update
+     * ("cannot update a stack when a custom-named resource requires replacing").
+     */
+    pinnedPhysicalName?: string;
 }
 /** A fully computed deploy plan, ready to render and to gate on. */
 export interface DeployPlan {

package/dist/src/orchestration/application/plan/types.js

@@ -0,0 +1 @@
+const e=["registry","registry (change-set unverified)","change-set","cdk-spec (unverified)"];export{e as REPLACEMENT_VERDICT_SOURCES};

package/dist/src/orchestration/contextHelpers.d.ts

@@ -3,7 +3,7 @@ import type { TrailLifecycleState } from "@fjall/util/config";
 import type { ResourceEvent } from "@fjall/util/aws";
 import type { OrgConfig } from "../types/config/orgConfig.js";
 import type { DeployIdentity } from "../types/credentials.js";
-import type { AwsProviderCredentials } from "../aws/AwsProvider.js";
+import type { AwsProvider, AwsProviderCredentials } from "../aws/AwsProvider.js";
 import { SimpleAwsProvider } from "../aws/SimpleAwsProvider.js";
 import type { DeploymentContext } from "../types/deployment/DeploymentTypes.js";
 import type { DeployCallbacks } from "../types/callbacks.js";
@@ -76,6 +76,42 @@ export declare function buildParamsContext(params: {
  * provider the Account stack legitimately owns.
  */
 export declare function resolveAccountBootstrapSkipOidc(deployType: "organisation" | "platform" | "account", orgConfig: OrgConfig | undefined, explicitSkipOidc: boolean | undefined, targetIsOrganisationTier?: boolean): boolean | undefined;
+/** Synth-time context flags the OIDC gate mirror reads — see {@link synthCarriedOidcConnector}. */
+export interface SynthOidcContextFlags {
+    fjallOrgId?: string;
+    fjallOidcConfigured?: boolean;
+    fjallAccountGlobalsConfigured?: boolean;
+}
+/**
+ * Whether the synthesised Account/Platform stack carried the OidcConnector —
+ * the deploy-core mirror of the construct gate in
+ * `components/infrastructure/lib/patterns/aws/account.ts` (`receivesDeployRole()
+ * && fjallOrgId && !oidcAlreadyConfigured && !accountGlobalsConfigured`).
+ * `receivesDeployRole` is structural here: only platform/account deploys reach
+ * the post-deploy OIDC reconcile, and both patterns receive the deploy role
+ * (the Organisation pattern, which does not, only synthesises under
+ * `deployType: "organisation"`). An empty-string `fjallOrgId` reads as absent,
+ * matching both coupled sites: the construct gate tests truthiness and
+ * CdkArgumentBuilder drops the `-c fjallOrgId` argument entirely for `""`.
+ *
+ * Gates {@link reconcileOidcProviderIfCarried}: the reconcile enforces
+ * provider presence only where the current template claims ownership. A stack
+ * that deliberately skipped the connector — solo/standalone-management
+ * (Quick-Create owns its provider; restore is RECONNECT, never redeploy),
+ * non-home region, or no org identity — must never have a provider created
+ * for it on the deploy path.
+ */
+export declare function synthCarriedOidcConnector(context: SynthOidcContextFlags): boolean;
+/**
+ * Post-CFN OIDC provider reconcile, gated on {@link synthCarriedOidcConnector}.
+ * A pre-2.20.0 → current template migration deletes the account-global OIDC
+ * provider during CloudFormation's cleanup phase (after the replacement
+ * adopt-or-create resource has already run), so callers MUST invoke this only
+ * after their deploy — or unchanged-skip probe — returns. Composing the gate
+ * with the reconcile here keeps any future deploy path from invoking the
+ * reconcile ungated.
+ */
+export declare function reconcileOidcProviderIfCarried(context: SynthOidcContextFlags, provider: Pick<AwsProvider, "getClient">, callbacks: DeployCallbacks, abortSignal?: AbortSignal): Promise<void>;
 /** Forward onOutput callback — reduces lambda repetition across orchestration files. */
 export declare function forwardOutput(callbacks: DeployCallbacks): (chunk: string) => void;
 /** Forward onResourceProgress callback — reduces lambda repetition across orchestration files. */

package/dist/src/orchestration/contextHelpers.js

@@ -1 +1 @@
-import{success as f,failure as i}from"@fjall/generator";import{getErrorMessage as m,maskSensitiveOutput as d,sleep as y}from"@fjall/util";import{logger as C}from"@fjall/util/logger";import{hasOrganisationTierAccount as R}from"../aws/organisations/accountGlobals.js";import{SimpleAwsProvider as S}from"../aws/SimpleAwsProvider.js";const w={account:"active",draining:"draining",org:"removed"};function T(e,r){return e!==void 0&&e!==""&&r!==void 0&&r!==""&&e!==r}function D(e){const r=T(e.region,e.primaryRegion);return{...e.orgConfig!==void 0?{orgConfig:JSON.stringify(e.orgConfig)}:{},...e.identity!==void 0?{fjallOrgId:e.identity.fjallOrgId}:{},...e.skipOidc?{fjallOidcConfigured:!0}:{},...r?{fjallAccountGlobalsConfigured:!0}:{},...e.trailLifecycle!==void 0?{fjallAccountTrailState:w[e.trailLifecycle]}:{}}}function P(e,r,t,n){if(t!==void 0)return t;if(e==="account")return R(r?.providerAccounts)?n===!0:!0}function _(e){return r=>e.onOutput?.(r)}function B(e){return r=>e.onResourceProgress?.(r)}function j(e){if(!e.success||e.data.length===0)return;const r={};for(const t of e.data)t.OutputKey&&t.OutputValue!==void 0&&(r[t.OutputKey]=t.OutputValue);return Object.keys(r).length>0?r:void 0}const E="OrganizationAccountAccessRole",l=5,$=5e3,b=3e4;function h(e){return`arn:aws:iam::${e}:role/${E}`}function K(e,r){return r===void 0?y(e):r.aborted?Promise.resolve():new Promise(t=>{const n=()=>{t()};r.addEventListener("abort",n,{once:!0}),y(e).then(()=>{r.removeEventListener("abort",n),t()})})}async function F(e,r,t,n,o){if(!e.assumeRole)return i(new Error("AwsProvider does not support assumeRole"));const u=h(r),g=e.assumeRole.bind(e);let s;for(let c=0;c<=l;c++)try{s=await g(u,n);break}catch(a){const p=a instanceof Error?a.name:void 0;if(p==="AccessDenied"||p==="AccessDeniedException")return i(new Error(`Access denied assuming ${E} in account ${r}. The role may not exist or may not trust the management account.`));if(c<l){const A=Math.min($*2**c,b);if(C.debug("assumeCascadeRole",`Attempt ${c+1} failed for account ${r}, retrying in ${Math.round(A/1e3)}s`,{error:d(m(a))}),await K(A,o),o?.aborted)return i(new Error(`Aborted while retrying assume-role for account ${r}`));continue}return i(new Error(`Failed to assume role in account ${r} after ${l+1} attempts: ${d(m(a))}`))}if(!s)return i(new Error(`Failed to assume role in account ${r}`));const O=new S({accessKeyId:s.accessKeyId,secretAccessKey:s.secretAccessKey,sessionToken:s.sessionToken,region:t,accountId:r});return f({provider:O,credentials:{accessKeyId:s.accessKeyId,secretAccessKey:s.secretAccessKey,sessionToken:s.sessionToken}})}async function Y(e,r,t,n){const o=await e.cdkService.runCdkSynth(r,u=>t.onCdkOutput?.(u,"synth"));if(!o.success){const u=new Error(d(`${n}: ${o.error}`));return t.onError?.(u),i(u)}return f(void 0)}async function I(e,r,t){t.onCDKBootstrap?.("bootstrapping");const n=await e.cdkService.runCdkBootstrap(r,_(t));if(!n.success){t.onCDKBootstrap?.("failed");const o=new Error(d(`Bootstrap failed: ${n.error}`));return t.onError?.(o),i(o)}return t.onCDKBootstrap?.("complete"),f(void 0)}export{F as assumeCascadeRole,I as bootstrapOrFail,h as buildCascadeRoleArn,D as buildParamsContext,j as collectStackOutputs,_ as forwardOutput,B as forwardResourceProgress,P as resolveAccountBootstrapSkipOidc,Y as synthOrFail,T as targetsNonPrimaryRegion};
+import{success as f,failure as s}from"@fjall/generator";import{getErrorMessage as m,maskSensitiveOutput as a,sleep as y}from"@fjall/util";import{logger as O}from"@fjall/util/logger";import{IAMClient as R}from"@aws-sdk/client-iam";import{hasOrganisationTierAccount as S}from"../aws/organisations/accountGlobals.js";import{reconcileOidcProviderAfterDeploy as w}from"../aws/organisations/oidcProvider.js";import{SimpleAwsProvider as b}from"../aws/SimpleAwsProvider.js";const h={account:"active",draining:"draining",org:"removed"};function T(e,r){return e!==void 0&&e!==""&&r!==void 0&&r!==""&&e!==r}function F(e){const r=T(e.region,e.primaryRegion);return{...e.orgConfig!==void 0?{orgConfig:JSON.stringify(e.orgConfig)}:{},...e.identity!==void 0?{fjallOrgId:e.identity.fjallOrgId}:{},...e.skipOidc?{fjallOidcConfigured:!0}:{},...r?{fjallAccountGlobalsConfigured:!0}:{},...e.trailLifecycle!==void 0?{fjallAccountTrailState:h[e.trailLifecycle]}:{}}}function Y(e,r,t,n){if(t!==void 0)return t;if(e==="account")return S(r?.providerAccounts)?n===!0:!0}function _(e){return e.fjallOrgId!==void 0&&e.fjallOrgId!==""&&e.fjallOidcConfigured!==!0&&e.fjallAccountGlobalsConfigured!==!0}async function G(e,r,t,n){_(e)&&await w(r.getClient(R),t,n)}function $(e){return r=>e.onOutput?.(r)}function N(e){return r=>e.onResourceProgress?.(r)}function U(e){if(!e.success||e.data.length===0)return;const r={};for(const t of e.data)t.OutputKey&&t.OutputValue!==void 0&&(r[t.OutputKey]=t.OutputValue);return Object.keys(r).length>0?r:void 0}const g="OrganizationAccountAccessRole",l=5,v=5e3,K=3e4;function x(e){return`arn:aws:iam::${e}:role/${g}`}function M(e,r){return r===void 0?y(e):r.aborted?Promise.resolve():new Promise(t=>{const n=()=>{t()};r.addEventListener("abort",n,{once:!0}),y(e).then(()=>{r.removeEventListener("abort",n),t()})})}async function V(e,r,t,n,o){if(!e.assumeRole)return s(new Error("AwsProvider does not support assumeRole"));const u=x(r),E=e.assumeRole.bind(e);let i;for(let c=0;c<=l;c++)try{i=await E(u,n);break}catch(d){const p=d instanceof Error?d.name:void 0;if(p==="AccessDenied"||p==="AccessDeniedException")return s(new Error(`Access denied assuming ${g} in account ${r}. The role may not exist or may not trust the management account.`));if(c<l){const A=Math.min(v*2**c,K);if(O.debug("assumeCascadeRole",`Attempt ${c+1} failed for account ${r}, retrying in ${Math.round(A/1e3)}s`,{error:a(m(d))}),await M(A,o),o?.aborted)return s(new Error(`Aborted while retrying assume-role for account ${r}`));continue}return s(new Error(`Failed to assume role in account ${r} after ${l+1} attempts: ${a(m(d))}`))}if(!i)return s(new Error(`Failed to assume role in account ${r}`));const C=new b({accessKeyId:i.accessKeyId,secretAccessKey:i.secretAccessKey,sessionToken:i.sessionToken,region:t,accountId:r});return f({provider:C,credentials:{accessKeyId:i.accessKeyId,secretAccessKey:i.secretAccessKey,sessionToken:i.sessionToken}})}async function z(e,r,t,n){const o=await e.cdkService.runCdkSynth(r,u=>t.onCdkOutput?.(u,"synth"));if(!o.success){const u=new Error(a(`${n}: ${o.error}`));return t.onError?.(u),s(u)}return f(void 0)}async function J(e,r,t){t.onCDKBootstrap?.("bootstrapping");const n=await e.cdkService.runCdkBootstrap(r,$(t));if(!n.success){t.onCDKBootstrap?.("failed");const o=new Error(a(`Bootstrap failed: ${n.error}`));return t.onError?.(o),s(o)}return t.onCDKBootstrap?.("complete"),f(void 0)}export{V as assumeCascadeRole,J as bootstrapOrFail,x as buildCascadeRoleArn,F as buildParamsContext,U as collectStackOutputs,$ as forwardOutput,N as forwardResourceProgress,G as reconcileOidcProviderIfCarried,Y as resolveAccountBootstrapSkipOidc,_ as synthCarriedOidcConnector,z as synthOrFail,T as targetsNonPrimaryRegion};

package/dist/src/orchestration/drift/classifyDriftFailure.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Class 1 drift classification over a stack's last CloudFormation operation
+ * (drift-remediation plan § Phase 5 item 1). Fetches the failure events of
+ * the most recent operation via `DescribeStackEvents` (newest-first), maps
+ * them onto the shared NotFound anchors (`@fjall/util/aws` `driftSuspects`,
+ * derived from the Phase 0 BC fixture `__tests__/fixtures/bc-stack-events.json`)
+ * and returns out-of-band-deletion SUSPECTS — never verdicts; `driftProbe.ts`
+ * confirms.
+ *
+ * Suspect `statusReason`s are masked at construction (a CloudFormation status
+ * reason can embed anything a failed handler echoed), so journal writes and
+ * CLI sinks may surface them directly.
+ */
+import { type Result } from "@fjall/generator";
+import { type ResourceEvent } from "@fjall/util/aws";
+import type { AwsProvider } from "../../aws/AwsProvider.js";
+import type { DriftSuspect } from "../../types/drift.js";
+/**
+ * Fetch the events of the stack's most recent operation, newest-first. Pages
+ * `DescribeStackEvents` until the operation's opening event (inclusive — the
+ * shared `isOperationOpeningEvent` boundary, which a CancelUpdateStack
+ * rollback's "User Initiated" stamp does NOT satisfy) or the page budget is
+ * exhausted.
+ */
+export declare function fetchLastOperationEvents(aws: AwsProvider, stackName: string, abortSignal?: AbortSignal): Promise<Result<ResourceEvent[], Error>>;
+/**
+ * Classify a stack's last-operation events into drift suspects. Pure —
+ * callers fetch events via {@link fetchLastOperationEvents} or hand over a
+ * monitor's history.
+ */
+export declare function classifyDriftFailure(stackName: string, events: readonly ResourceEvent[]): DriftSuspect[];

package/dist/src/orchestration/drift/classifyDriftFailure.js

@@ -0,0 +1 @@
+import{CloudFormationClient as p,DescribeStackEventsCommand as m}from"@aws-sdk/client-cloudformation";import{success as a,failure as d}from"@fjall/generator";import{getErrorMessage as g,maskSensitiveOutput as l}from"@fjall/util";import{classifyDriftSuspectEvents as y,isOperationOpeningEvent as R}from"@fjall/util/aws";import{logger as E}from"@fjall/util/logger";import{composeSdkAbortSignal as S,isAborted as v}from"../../aws/organisations/types.js";const I="DriftClassify",h=5;function T(e){return e.includes("FAILED")}function D(e){return e.LogicalResourceId===void 0||e.ResourceType===void 0||e.ResourceStatus===void 0?null:{logicalId:e.LogicalResourceId,resourceType:e.ResourceType,status:e.ResourceStatus,timestamp:e.Timestamp??new Date(0),...e.PhysicalResourceId!==void 0&&e.PhysicalResourceId!==""?{physicalId:e.PhysicalResourceId}:{},...e.ResourceStatusReason!==void 0?{statusReason:e.ResourceStatusReason}:{}}}async function L(e,n,r){const t=e.getClient(p),o=[];let s,u=0;try{do{if(v(r))return d(new Error(`Drift event scan aborted for ${n}`));const i=await t.send(new m({StackName:n,...s!==void 0?{NextToken:s}:{}}),{abortSignal:S(r)});u+=1;for(const f of i.StackEvents??[]){const c=D(f);if(c!==null&&(o.push(c),R(c,n)))return a(o)}if(s=i.NextToken,u>=h&&s!==void 0)return E.debug(I,"Event scan truncated at page budget",{stackName:n,pages:u,eventsCollected:o.length}),a(o)}while(s!==void 0);return a(o)}catch(i){return d(new Error(`Failed to read stack events for ${n}: ${l(g(i))}`))}}function O(e,n){const r=n.filter(t=>T(t.status));return y(r).map(t=>({stackName:e,logicalId:t.logicalId,resourceType:t.resourceType,...t.physicalId!==void 0?{physicalId:t.physicalId}:{},failedStatus:t.failedStatus,statusReason:l(t.statusReason)}))}export{O as classifyDriftFailure,L as fetchLastOperationEvents};

package/dist/src/orchestration/drift/detectStackDrift.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The drift-detection pipeline for one stack: last-operation event scan →
+ * suspect classification → journal merge → probe → journal upkeep. Shared by
+ * `fjall drift detect` and the [G2] deploy pre-flight so both surfaces report
+ * identical findings for identical state.
+ *
+ * Journal upkeep: confirmed or unconfirmed findings (the wedge persists or
+ * could not be ruled out) re-record the journal so the next deploy re-probes;
+ * all-present or stack-missing findings clear it.
+ */
+import { type Result } from "@fjall/generator";
+import type { AwsProvider } from "../../aws/AwsProvider.js";
+import type { DriftFinding, DriftSuspect } from "../../types/drift.js";
+import type { DriftProbeRunner } from "./driftProbe.js";
+import { type DriftJournalOptions } from "./driftSuspectJournal.js";
+export interface DetectStackDriftDeps {
+    aws: AwsProvider;
+    probe: DriftProbeRunner;
+    journal?: DriftJournalOptions;
+    /** Injectable clock for journal timestamps. */
+    now?: () => Date;
+}
+export interface DetectStackDriftParams {
+    stackName: string;
+    abortSignal?: AbortSignal;
+}
+export interface StackDriftReport {
+    stackName: string;
+    suspects: DriftSuspect[];
+    findings: DriftFinding[];
+    /** How many suspects came from the live event scan vs the journal. */
+    suspectSources: {
+        events: number;
+        journal: number;
+    };
+}
+export declare function detectStackDrift(deps: DetectStackDriftDeps, params: DetectStackDriftParams): Promise<Result<StackDriftReport, Error>>;

package/dist/src/orchestration/drift/detectStackDrift.js

@@ -0,0 +1 @@
+import{STACK_NOT_FOUND_PATTERN as b}from"@fjall/util/aws";import{success as g,failure as S}from"@fjall/generator";import{classifyDriftFailure as D,fetchLastOperationEvents as h}from"./classifyDriftFailure.js";import{clearDriftSuspects as j,readDriftSuspects as _,recordDriftSuspects as I}from"./driftSuspectJournal.js";async function E(e,m){const{stackName:t,abortSignal:o}=m,n=e.aws.getAccountId(),a=e.aws.getRegion(),r=await h(e.aws,t,o);let c=[];if(r.success)c=D(t,r.data);else if(!r.error.message.includes(b))return S(r.error);const l=await _(n,a,t,e.journal),v=new Set(c.map(s=>s.logicalId)),f=(l?.suspects??[]).filter(s=>!v.has(s.logicalId)),i=[...c,...f];if(i.length===0)return g({stackName:t,suspects:[],findings:[],suspectSources:{events:0,journal:0}});const u=await e.probe.probeSuspects({stackName:t,suspects:i,...o!==void 0?{abortSignal:o}:{}});if(!u.success)return S(u.error);const d=u.data,p=d.filter(s=>s.verdict==="confirmed-deleted"||s.verdict==="unconfirmed").map(({verdict:s,verdictDetail:R,probeMethod:A,verbs:N,...w})=>w);return p.length>0?await I({accountId:n,region:a,stackName:t,recordedAt:(e.now?.()??new Date).toISOString(),suspects:p},e.journal):l!==null&&await j(n,a,t,e.journal),g({stackName:t,suspects:i,findings:d,suspectSources:{events:c.length,journal:f.length}})}export{E as detectStackDrift};

package/dist/src/orchestration/drift/driftPreFlight.d.ts

@@ -0,0 +1,73 @@
+/**
+ * [G2] Stateless drift pre-flight (drift-remediation plan § Phase 5).
+ * Before the cdk spawn, each stack about to deploy is checked for the Class 1
+ * wedge: a stack in a failed/rolled-back status, or one carrying journalled
+ * suspects, is probed (bounded); a CONFIRMED out-of-band deletion blocks the
+ * deploy with a named finding — the deploy would only re-wedge.
+ *
+ * Statelessness: the trigger reads live stack status, so a fresh machine with
+ * an empty journal still catches the wedge. Deviation from the plan text
+ * recorded in the Phase 5 report: the plan assumed the active-deployment
+ * guard's DescribeStacks already ran on the deploy path — it is destroy-only,
+ * so this pre-flight issues ONE `getStackStatus` (DescribeStacks) per stack
+ * to deploy. Healthy stacks with an empty journal pay nothing further.
+ *
+ * Fail-open on probe infrastructure errors: only `confirmed-deleted` blocks;
+ * unconfirmed findings surface as warnings and the deploy proceeds.
+ */
+import { type Result } from "@fjall/generator";
+import type { CloudFormationService } from "../../services/infrastructure/CloudFormationService.js";
+import type { DriftFinding } from "../../types/drift.js";
+import { type DetectStackDriftDeps } from "./detectStackDrift.js";
+/**
+ * Stack statuses that evidence a possibly-wedged last operation. Narrow by
+ * design: rollback-complete and update-failed are where the BC wedge lands;
+ * rollback-failed is the same class one step worse. IN_PROGRESS states are
+ * the active-deployment guard's concern, not drift's.
+ */
+export declare const DRIFT_PREFLIGHT_TRIGGER_STATUSES: ReadonlySet<string>;
+/** Bounds the whole pre-flight so a slow probe cannot stall the deploy. */
+export declare const DRIFT_PREFLIGHT_BUDGET_MS = 90000;
+export interface RunDriftPreFlightParams {
+    stackNames: readonly string[];
+    cfnService: Pick<CloudFormationService, "getStackStatus">;
+    abortSignal?: AbortSignal;
+    budgetMs?: number;
+}
+export interface DriftPreFlightOutcome {
+    confirmed: DriftFinding[];
+    unconfirmed: DriftFinding[];
+    /** Stacks whose status or journal triggered a probe. */
+    probedStacks: string[];
+}
+export declare function runDriftPreFlight(deps: DetectStackDriftDeps, params: RunDriftPreFlightParams): Promise<Result<DriftPreFlightOutcome, Error>>;
+export interface DriftPreFlightBlockExtras {
+    /** Journal says flip-applied but the live template VERIFIABLY no longer
+     * carries the flip — surgery must re-run before deploying. */
+    flipNotLive?: ReadonlyArray<{
+        finding: DriftFinding;
+        opId: string;
+    }>;
+    /** The live template could not be read, so the flip's liveness is
+     * unverifiable — the cure is retrying the deploy, not re-running repair.
+     * `message` is pre-masked at construction. */
+    flipUnverified?: ReadonlyArray<{
+        finding: DriftFinding;
+        opId: string;
+        message: string;
+    }>;
+    /** Flip is live but the deploy's synth still declares the target — this
+     * deploy is not the converge. */
+    stillDeclared?: ReadonlyArray<{
+        finding: DriftFinding;
+        opId: string;
+    }>;
+}
+/**
+ * Compose the blocking failure message for confirmed pre-flight findings.
+ * `inProgressOpIds` names forget operations that cover blocked findings but
+ * have not yet applied the Retain flip — the cure is resuming them, not
+ * deploying ([G2] × remediation-journal interaction). `extras` carries the
+ * partition's suppression-refused buckets, each with its own cure.
+ */
+export declare function formatDriftPreFlightBlock(confirmed: readonly DriftFinding[], inProgressOpIds?: readonly string[], extras?: DriftPreFlightBlockExtras): string;

package/dist/src/orchestration/drift/driftPreFlight.js

@@ -0,0 +1,7 @@
+import{success as g}from"@fjall/generator";import{detectStackDrift as $}from"./detectStackDrift.js";import{readDriftSuspects as v}from"./driftSuspectJournal.js";const y=new Set(["UPDATE_ROLLBACK_COMPLETE","UPDATE_ROLLBACK_FAILED","UPDATE_FAILED"]),b=9e4;async function D(o,l){const n=l.budgetMs??b,d=l.abortSignal!==void 0?AbortSignal.any([l.abortSignal,AbortSignal.timeout(n)]):AbortSignal.any([AbortSignal.timeout(n)]),r={confirmed:[],unconfirmed:[],probedStacks:[]},u=await Promise.all(l.stackNames.map(async i=>{const a=await l.cfnService.getStackStatus(i);return{stackName:i,status:a.success?a.data?.status??null:null}}));for(const{stackName:i,status:a}of u){if(!(a!==null&&y.has(a))){const t=await v(o.aws.getAccountId(),o.aws.getRegion(),i,o.journal);if(t===null||t.suspects.length===0)continue}r.probedStacks.push(i);const c=await $(o,{stackName:i,abortSignal:d});if(c.success)for(const t of c.data.findings)t.verdict==="confirmed-deleted"?r.confirmed.push(t):(t.verdict==="unconfirmed"||t.verdict==="stack-missing")&&r.unconfirmed.push(t)}return g(r)}function I(o,l=[],n={}){const d=o.map(e=>`  ${e.stackName} \u203A ${e.logicalId} (${e.resourceType})${e.physicalId!==void 0?` [${e.physicalId}]`:""} \u2014 ${e.verdictDetail}`),r=l.map(e=>`Remediation ${e} is in progress \u2014 run 'fjall drift resume ${e}' to continue it.`),u=(n.flipNotLive??[]).map(({finding:e,opId:s})=>`Remediation ${s} recorded its Retain flip on ${e.stackName} \u203A ${e.logicalId}, but the flip is no longer live on the stack \u2014 re-run 'fjall drift repair' to re-verify before deploying.`),i=(n.flipUnverified??[]).map(({finding:e,opId:s,message:h})=>`Remediation ${s} should complete with this deploy, but ${e.stackName} \u203A ${e.logicalId} could not be verified: the live template could not be read to confirm the Retain flip is still live \u2014 ${h}. Retry the deploy.`),a=(n.stillDeclared??[]).map(({finding:e,opId:s})=>`Remediation ${s} is ready to converge, but ${e.stackName} \u203A ${e.logicalId} is still declared in your fjall config \u2014 remove the resource from the config, then deploy to complete the forget.`),f=[...r,...u,...i,...a],c=new Set((n.flipUnverified??[]).map(({finding:e})=>`${e.stackName}/${e.logicalId}`)),t=o.length>0&&o.every(e=>c.has(`${e.stackName}/${e.logicalId}`)),m=t?`Deploy blocked: the Retain-flip state of ${o.length} mid-remediation resource(s) could not be verified (the live template could not be read):
+`:`Deploy blocked: CloudFormation still tracks ${o.length} resource(s) deleted outside CloudFormation \u2014 deploying would fail and re-wedge the stack:
+`,p=t?"Retry the deploy \u2014 verification is transient when the live template read fails; if it keeps failing, check CloudFormation access to the stack template.":"Run 'fjall drift detect' for the full report, then 'fjall drift repair --remediate <physicalName>=<verb>' to remediate confirmed deletions.";return m+`${d.join(`
+`)}
+${p}${f.length>0?`
+${f.join(`
+`)}`:""}`}export{b as DRIFT_PREFLIGHT_BUDGET_MS,y as DRIFT_PREFLIGHT_TRIGGER_STATUSES,I as formatDriftPreFlightBlock,D as runDriftPreFlight};

package/dist/src/orchestration/drift/driftProbe.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Drift-suspect confirmation probe (drift-remediation plan § Phase 5 item 2).
+ * Turns SUSPECTS from `classifyDriftFailure.ts` into per-resource verdicts:
+ *
+ * - A `DescribeStacks` existence check first — a deleted stack short-circuits
+ *   every suspect to `stack-missing` (it must never read as "nothing wrong").
+ * - A `ListStackResources` membership gate next — a suspect the stack no
+ *   longer tracks (cured by removing it from the template) reads `present`
+ *   (recovered), never probed against the owning service; probing its
+ *   long-dead physicalId would wrongly confirm and re-journal forever.
+ * - Direct per-type probes (KMS DescribeKey, S3 HeadBucket/GetBucketPolicy,
+ *   Secrets Manager DescribeSecret) — only an authoritative NotFound from the
+ *   owning service (or a KMS key in PendingDeletion/PendingReplicaDeletion,
+ *   which the CloudFormation handler maps to NotFound) yields
+ *   `confirmed-deleted`.
+ * - CloudFormation drift-API fallback (`DetectStackDrift` → poll →
+ *   `DescribeStackResourceDrifts`) for types without a direct probe.
+ *
+ * Fail-closed throughout: throttles, AccessDenied, network failures and abort
+ * all yield `unconfirmed` (repair-only presentation downstream), never a
+ * destructive-eligible verdict.
+ *
+ * [G8] boundary audit (2026-07-08): every action this probe issues —
+ * cloudformation:DescribeStacks/ListStackResources/DetectStackDrift/
+ * DescribeStackDriftDetectionStatus/DescribeStackResourceDrifts,
+ * kms:DescribeKey, s3:HeadBucket (s3:ListBucket)/GetBucketPolicy,
+ * secretsmanager:DescribeSecret — is read-only and appears in no Deny of the
+ * deploy session policy (`deploySessionPolicy.ts` fences foreign CFN/ECR
+ * MUTATION only) nor of any security-tier permissions boundary
+ * (`generator/src/schemas/securityBoundary.ts`). No policy change needed.
+ *
+ * Finding `verdictDetail`s are masked at construction, so CLI/journal sinks
+ * may surface them directly.
+ */
+import { type Result } from "@fjall/generator";
+import type { AwsProvider } from "../../aws/AwsProvider.js";
+import { type DriftFinding, type DriftSuspect, type DriftVerdict } from "../../types/drift.js";
+export interface ProbeDriftSuspectsParams {
+    stackName: string;
+    suspects: readonly DriftSuspect[];
+    abortSignal?: AbortSignal;
+}
+/** The narrow surface callers need — DriftProbe satisfies it; tests stub. */
+export interface DriftProbeRunner {
+    probeSuspects(params: ProbeDriftSuspectsParams): Promise<Result<DriftFinding[], Error>>;
+}
+export interface DriftProbeOptions {
+    /** Poll cadence for the drift-API fallback; defaults to 3 s. */
+    pollIntervalMs?: number;
+    /** Overall drift-API poll budget; defaults to 90 s. */
+    pollTimeoutMs?: number;
+    /** Injectable clock for timeout tests. */
+    now?: () => number;
+}
+/**
+ * probeMethod stamped by the ListStackResources membership gate below. Its
+ * "present" verdict means "no longer tracked by the stack — cured by removal
+ * from the template", NOT physical presence: no owning service was consulted.
+ * Forget-closure accounting discriminates on this constant to keep
+ * membership-gate verdicts out of the retained-by-redeclaration bucket
+ * (coupled values — shared at 2 occurrences with forgetResource.ts).
+ */
+export declare const MEMBERSHIP_GATE_PROBE_METHOD = "cloudformation:ListStackResources";
+export interface PhysicalPresenceOutcome {
+    /** `present` (alive), `confirmed-deleted`, or `unconfirmed` — never a
+     * membership-gate verdict; the stack listing is deliberately not consulted. */
+    verdict: Extract<DriftVerdict, "present" | "confirmed-deleted" | "unconfirmed">;
+    detail: string;
+    /** The owning-service action consulted, or "none" for unsupported types. */
+    probeMethod: string;
+}
+/**
+ * [G6] Gate-bypassing physical-presence probe: ask the OWNING SERVICE whether
+ * `physicalId` is alive, with no ListStackResources membership gate in front.
+ * `probeSuspects`' gate is correct for drift confirmation (an untracked
+ * suspect is cured) but poisonous at absent-bucket closure — every
+ * absent-from-stack target would read "present"/cured with ZERO physical
+ * verification, so a DELETE_FAILED orphan closed by a later update-cleanup
+ * strip would be recorded as an executed deletion. Types without a direct
+ * probe return `unconfirmed` (probeMethod "none") — callers close hedged.
+ * Fail-soft: SDK failures are `unconfirmed`, never a throw.
+ */
+export declare function probePhysicalPresence(aws: AwsProvider, params: {
+    resourceType: string;
+    physicalId: string;
+    abortSignal?: AbortSignal;
+}): Promise<PhysicalPresenceOutcome>;
+export declare class DriftProbe implements DriftProbeRunner {
+    private readonly aws;
+    private readonly pollIntervalMs;
+    private readonly pollTimeoutMs;
+    private readonly now;
+    constructor(aws: AwsProvider, options?: DriftProbeOptions);
+    probeSuspects(params: ProbeDriftSuspectsParams): Promise<Result<DriftFinding[], Error>>;
+    private checkStackExists;
+    /**
+     * The stack's current resources: logicalId → PhysicalResourceId ("" when
+     * CloudFormation reports none). Key presence is the membership ground
+     * truth for the cured-by-template-removal gate, so this ALWAYS lists —
+     * suspect-supplied physicalIds (journal-sourced) must never bypass the
+     * membership check. Returns null when the listing fails or aborts
+     * mid-pagination (fail-soft: probing proceeds on suspect-supplied ids and
+     * membership stays unverified rather than misread as "not a member").
+     */
+    private listStackResources;
+    /**
+     * Generic fallback for types without a direct probe: run stack drift
+     * detection, then read each suspect's drift status. Only a DELETED drift
+     * status confirms; IN_SYNC/MODIFIED prove presence; everything else
+     * (detection failure, NOT_CHECKED, unsupported type) stays unconfirmed.
+     */
+    private probeViaDriftApi;
+}

package/dist/src/orchestration/drift/driftProbe.js

@@ -0,0 +1 @@
+import{CloudFormationClient as T,DescribeStacksCommand as R,DescribeStackDriftDetectionStatusCommand as _,DescribeStackResourceDriftsCommand as P,DetectStackDriftCommand as K,ListStackResourcesCommand as O}from"@aws-sdk/client-cloudformation";import{KMSClient as N,DescribeKeyCommand as C}from"@aws-sdk/client-kms";import{S3Client as I,HeadBucketCommand as v,GetBucketPolicyCommand as F}from"@aws-sdk/client-s3";import{SecretsManagerClient as A,DescribeSecretCommand as B}from"@aws-sdk/client-secrets-manager";import{success as w,failure as L}from"@fjall/generator";import{getErrorMessage as b,maskSensitiveOutput as E}from"@fjall/util";import{STACK_NOT_FOUND_PATTERN as $}from"@fjall/util/aws";import{logger as U}from"@fjall/util/logger";import{composeSdkAbortSignal as l,extractErrorName as D,isAborted as k}from"../../aws/organisations/types.js";import{sleepAbortable as G}from"../../util/sleepAbortable.js";import{verbsForDriftVerdict as H}from"../../types/drift.js";const W="DriftProbe",V=3e3,Y=9e4,M=new Set(["NotFoundException"]),j=new Set(["NotFound","NoSuchBucket"]),q=new Set(["NoSuchBucketPolicy","NoSuchBucket","NotFound"]),z=new Set(["ResourceNotFoundException"]);function p(o){return{verdict:"confirmed-deleted",detail:o}}function y(o){return{verdict:"present",detail:o}}function g(o){return{verdict:"unconfirmed",detail:`Probe could not confirm: ${E(b(o))}`}}async function J(o,r,t){try{const n=(await o.getClient(N).send(new C({KeyId:r}),{abortSignal:l(t)})).KeyMetadata?.KeyState;return n==="PendingDeletion"||n==="PendingReplicaDeletion"?p(`Key is scheduled for deletion (state: ${n}) \u2014 CloudFormation treats it as NotFound; cancellable via kms:CancelKeyDeletion until the waiting period ends`):y(n!==void 0?`Key exists (state: ${n})`:"Key exists")}catch(e){return M.has(D(e))?p("kms:DescribeKey returned NotFoundException"):g(e)}}async function Q(o,r,t){try{const n=(await o.getClient(N).send(new C({KeyId:r}),{abortSignal:l(t)})).KeyMetadata?.KeyState;return y(n!==void 0?`Alias exists (resolved key state: ${n})`:"Alias exists")}catch(e){return M.has(D(e))?p("kms:DescribeKey returned NotFoundException for the alias"):g(e)}}async function X(o,r,t){try{return await o.getClient(I).send(new v({Bucket:r}),{abortSignal:l(t)}),y("Bucket exists")}catch(e){return j.has(D(e))?p("s3:HeadBucket returned NotFound"):g(e)}}async function Z(o,r,t){try{return await o.getClient(I).send(new F({Bucket:r}),{abortSignal:l(t)}),y("Bucket policy exists")}catch(e){return q.has(D(e))?p("s3:GetBucketPolicy reported no such bucket policy or bucket"):g(e)}}async function ee(o,r,t){try{const e=await o.getClient(A).send(new B({SecretId:r}),{abortSignal:l(t)});return e.DeletedDate!==void 0?p(`Secret is scheduled for deletion (DeletedDate: ${e.DeletedDate.toISOString()}) \u2014 restorable via secretsmanager:RestoreSecret until the recovery window ends`):y("Secret exists")}catch(e){return z.has(D(e))?p("secretsmanager:DescribeSecret returned ResourceNotFoundException"):g(e)}}const te="cloudformation:ListStackResources",x={"AWS::KMS::Key":{probe:J,method:"kms:DescribeKey"},"AWS::KMS::Alias":{probe:Q,method:"kms:DescribeKey"},"AWS::S3::Bucket":{probe:X,method:"s3:HeadBucket"},"AWS::S3::BucketPolicy":{probe:Z,method:"s3:GetBucketPolicy"},"AWS::SecretsManager::Secret":{probe:ee,method:"secretsmanager:DescribeSecret"}};async function me(o,r){const t=x[r.resourceType];if(t===void 0)return{verdict:"unconfirmed",detail:`no direct owning-service probe for ${r.resourceType} in this release`,probeMethod:"none"};if(k(r.abortSignal))return{verdict:"unconfirmed",detail:"Probe aborted",probeMethod:"none"};const e=await t.probe(o,r.physicalId,r.abortSignal);return e.verdict!=="present"&&e.verdict!=="confirmed-deleted"?{verdict:"unconfirmed",detail:e.detail,probeMethod:t.method}:{verdict:e.verdict,detail:e.detail,probeMethod:t.method}}function u(o,r,t,e){return{...o,verdict:r,verdictDetail:t,probeMethod:e,verbs:H(r)}}class Se{aws;pollIntervalMs;pollTimeoutMs;now;constructor(r,t){this.aws=r,this.pollIntervalMs=t?.pollIntervalMs??V,this.pollTimeoutMs=t?.pollTimeoutMs??Y,this.now=t?.now??(()=>Date.now())}async probeSuspects(r){const{stackName:t,suspects:e,abortSignal:n}=r;if(e.length===0)return w([]);if(k(n))return L(new Error(`Drift probe aborted before starting for ${t}`));const a=await this.checkStackExists(t,n);if(a==="missing")return w(e.map(i=>u(i,"stack-missing",`Stack ${t} no longer exists in CloudFormation`,"cloudformation:DescribeStacks")));if(a!=="exists")return w(e.map(i=>u(i,"unconfirmed",a.detail,"cloudformation:DescribeStacks")));const f=await this.listStackResources(t,n),d=[],S=[];for(const i of e){if(k(n)){d.push(u(i,"unconfirmed","Probe aborted","none"));continue}if(f!==null&&!f.has(i.logicalId)){d.push(u(i,"present",`No longer tracked by stack ${t} \u2014 cured by removal from the template`,te));continue}const h=x[i.resourceType],m=f?.get(i.logicalId),c=m!==void 0&&m!==""?m:i.physicalId;if(h===void 0||c===void 0||c===""){S.push(i);continue}const s=await h.probe(this.aws,c,n);d.push(u({...i,physicalId:c},s.verdict,s.detail,h.method))}return S.length>0&&d.push(...await this.probeViaDriftApi(t,S,n)),w(d)}async checkStackExists(r,t){try{return await this.aws.getClient(T).send(new R({StackName:r}),{abortSignal:l(t)}),"exists"}catch(e){return b(e).includes($)?"missing":{detail:`Stack existence check failed: ${E(b(e))}`}}}async listStackResources(r,t){const e=new Map,n=this.aws.getClient(T);try{let a;do{if(k(t))return null;const f=await n.send(new O({StackName:r,...a!==void 0?{NextToken:a}:{}}),{abortSignal:l(t)});for(const d of f.StackResourceSummaries??[])d.LogicalResourceId!==void 0&&e.set(d.LogicalResourceId,d.PhysicalResourceId??"");a=f.NextToken}while(a!==void 0)}catch(a){return U.debug(W,"Stack resource listing failed \u2014 falling back",{stackName:r,error:E(b(a))}),null}return e}async probeViaDriftApi(r,t,e){const n="cloudformation:DetectStackDrift",a=this.aws.getClient(T);try{const d=(await a.send(new K({StackName:r}),{abortSignal:l(e)})).StackDriftDetectionId;if(d===void 0)return t.map(c=>u(c,"unconfirmed","Drift detection returned no detection id",n));const S=this.now();let i;for(;!k(e)&&(i=(await a.send(new _({StackDriftDetectionId:d}),{abortSignal:l(e)})).DetectionStatus,i==="DETECTION_IN_PROGRESS");){if(this.now()-S>=this.pollTimeoutMs)return t.map(s=>u(s,"unconfirmed",`Drift detection timed out after ${this.pollTimeoutMs}ms`,n));await G(this.pollIntervalMs,e)}if(i!=="DETECTION_COMPLETE")return t.map(c=>u(c,"unconfirmed",`Drift detection did not complete (status: ${i??"aborted"})`,n));const h=new Map;let m;do{if(k(e))break;const c=await a.send(new P({StackName:r,...m!==void 0?{NextToken:m}:{}}),{abortSignal:l(e)});for(const s of c.StackResourceDrifts??[])s.LogicalResourceId!==void 0&&s.StackResourceDriftStatus!==void 0&&h.set(s.LogicalResourceId,s.StackResourceDriftStatus);m=c.NextToken}while(m!==void 0);return t.map(c=>{const s=h.get(c.logicalId);return s==="DELETED"?u(c,"confirmed-deleted","CloudFormation drift detection reported the resource DELETED",n):s==="IN_SYNC"||s==="MODIFIED"?u(c,"present",`CloudFormation drift detection reported ${s}`,n):u(c,"unconfirmed",s===void 0?"Resource not reported by drift detection (type may not support it)":`Drift detection reported ${s}`,n)})}catch(f){const d=`Drift-API fallback failed: ${E(b(f))}`;return t.map(S=>u(S,"unconfirmed",d,n))}}}export{Se as DriftProbe,te as MEMBERSHIP_GATE_PROBE_METHOD,me as probePhysicalPresence};