@fjall/deploy-core 2.25.0 → 2.29.0

package/dist/src/orchestration/remediation/postFailureRepairOffer.d.ts

@@ -0,0 +1,77 @@
+/**
+ * In-session post-failure repair offer (drift-remediation plan § 8 Phase 6):
+ * when a stack deploy step fails, the engine re-probes that stack in the SAME
+ * session through the bounded [G2] pipeline (the failure analysis has just
+ * journalled any NotFound-classified suspects). A CONFIRMED out-of-band
+ * deletion upgrades the returned error to the typed
+ * `DriftRepairAvailableError` — the interactive surface defers on the class
+ * (the `BuildxUnavailableInteractive` shape) while the non-interactive
+ * surface reads the same offer from the message text.
+ *
+ * Best-effort by contract: any probe failure, abort, or empty verdict returns
+ * the ORIGINAL error untouched — the offer must never mask the deploy's true
+ * root cause.
+ *
+ * Messages are pre-masked at construction: the original analysed error is
+ * masked at the monitor boundary, and the appended offer lines are
+ * identifier-only (stack, logical ID, resource type, physical ID). The
+ * command teaches the flag SHAPE with a placeholder name, never a filled
+ * consent [G5].
+ */
+import type { AwsProvider } from "../../aws/AwsProvider.js";
+import type { CloudFormationService } from "../../services/infrastructure/CloudFormationService.js";
+import type { DriftFinding } from "../../types/drift.js";
+import type { DriftJournalOptions } from "../drift/driftSuspectJournal.js";
+import { type RemediationJournalOptions } from "./remediationJournal.js";
+export declare class DriftRepairAvailableError extends Error {
+    readonly findings: readonly DriftFinding[];
+    constructor(message: string, findings: readonly DriftFinding[]);
+}
+/** Identifier-only offer block appended beneath the analysed deploy error. */
+export declare function formatDriftRepairOffer(findings: readonly DriftFinding[], appName?: string, repairTarget?: string): string;
+/** One confirmed finding covered by an in-flight recreate journal [G1]. */
+export interface RecreateCoveredFinding {
+    finding: DriftFinding;
+    opId: string;
+    appName?: string;
+}
+/**
+ * [G1] Identifier-only notice for confirmed deletions COVERED by an in-flight
+ * recreate operation. The `=forget` offer must never be taught for these —
+ * the forget arm's verb guard fails closed on the recreate journal, whose
+ * teach names the deploy, whose failure re-offers `=forget`: a circular teach
+ * loop. The two-cure block is the only terminating exit.
+ */
+export declare function formatRecreateCoveredNotice(covered: readonly RecreateCoveredFinding[], fallbackAppName?: string): string;
+export interface ComposePostFailureRepairOfferParams {
+    /** The stack(s) whose deploy step just failed. */
+    stackNames: readonly string[];
+    /** Names the repair command's target in the offer. */
+    appName?: string;
+    /**
+     * Overrides the repair command's target fragment in the offer (e.g.
+     * "--stack Account" for a single-component deploy, whose stack is not
+     * addressable by app name). `appName` still names the recreate cures —
+     * those teach 'fjall deploy', where a flag fragment would be wrong.
+     */
+    repairTarget?: string;
+    originalError: Error;
+    cfnService: Pick<CloudFormationService, "getStackStatus">;
+    journal?: DriftJournalOptions;
+    /** Remediation-journal root override — tests point this at a temp dir. */
+    remediationJournal?: RemediationJournalOptions;
+    abortSignal?: AbortSignal;
+}
+/**
+ * Upgrade a failed deploy's error with the in-session repair offer when the
+ * post-failure probe CONFIRMS an out-of-band deletion on the failed stack.
+ * Returns the original error on every other outcome.
+ *
+ * [G1] Findings covered by an in-flight RECREATE journal never receive the
+ * `=forget` offer (circular teach — see `formatRecreateCoveredNotice`): a
+ * covered-only verdict returns a PLAIN Error carrying the two-cure notice
+ * (never `DriftRepairAvailableError`, whose interactive drift-repair offer
+ * would walk the same loop), and a mixed verdict offers `=forget` for the
+ * uncovered findings only, with the covered notice appended.
+ */
+export declare function composePostFailureRepairOffer(aws: AwsProvider, params: ComposePostFailureRepairOfferParams): Promise<Error>;

package/dist/src/orchestration/remediation/postFailureRepairOffer.js

@@ -0,0 +1,14 @@
+import{getErrorMessage as m,maskSensitiveOutput as g}from"@fjall/util";import{logger as h}from"@fjall/util/logger";import{DriftProbe as $}from"../drift/driftProbe.js";import{runDriftPreFlight as N}from"../drift/driftPreFlight.js";import{formatRecreateInFlightCures as v}from"./forgetResource.js";import{listActiveRemediationOps as y}from"./remediationJournal.js";const I="PostFailureRepairOffer";class b extends Error{findings;constructor(e,r){super(e),this.name="DriftRepairAvailableError",this.findings=r}}function k(o,e,r){const i=o.map(n=>`  ${n.stackName} \u203A ${n.logicalId} (${n.resourceType})${n.physicalId!==void 0?` [${n.physicalId}]`:""} \u2014 ${n.verdictDetail}`),t=r!==void 0&&r!==""?r:e!==void 0&&e!==""?e:"<target>";return`Out-of-band deletion CONFIRMED \u2014 CloudFormation still tracks ${o.length} deleted resource(s):
+${i.join(`
+`)}
+Repair in this session: fjall drift repair ${t} --remediate <physicalName>=forget
+(names are exact and case-sensitive; 'fjall drift detect' shows the full report)`}function u(o,e){const r=o.map(({finding:t,opId:n})=>`  ${t.stackName} \u203A ${t.logicalId} (${t.resourceType})${t.physicalId!==void 0?` [${t.physicalId}]`:""} \u2014 covered by in-flight recreate remediation ${n}`),i=o.find(t=>t.appName!==void 0)?.appName??e;return`${o.length} deleted resource(s) are already covered by an in-flight recreate remediation:
+${r.join(`
+`)}
+Do not use '--remediate <physicalName>=forget' for these \u2014 the forget arm fails closed on the in-flight recreate journal. ${v(i)}`}async function F(o,e){try{const r=await N({aws:o,probe:new $(o),...e.journal!==void 0?{journal:e.journal}:{}},{stackNames:e.stackNames,cfnService:e.cfnService,...e.abortSignal!==void 0?{abortSignal:e.abortSignal}:{}});if(!r.success||r.data.confirmed.length===0)return e.originalError;const{covered:i,uncovered:t}=await R(o,r.data.confirmed,e.remediationJournal);if(t.length===0)return new Error(`${e.originalError.message}
+
+${u(i,e.appName)}`);const n=i.length>0?`
+
+${u(i,e.appName)}`:"";return new b(`${e.originalError.message}
+
+${k(t,e.appName,e.repairTarget)}${n}`,t)}catch(r){return h.debug(I,"Post-failure repair probe threw \u2014 offer skipped",{stackNames:[...e.stackNames],error:g(m(r))}),e.originalError}}async function R(o,e,r){const i=o.getAccountId(),t=o.getRegion(),n=new Map,l=[],d=[];for(const a of e){let c=n.get(a.stackName);c===void 0&&(c=await y(i,t,a.stackName,r),n.set(a.stackName,c));const s=c.find(f=>f.verb==="recreate"&&f.targets.some(p=>p.logicalId===a.logicalId));s!==void 0?l.push({finding:a,opId:s.opId,...s.appName!==void 0?{appName:s.appName}:{}}):d.push(a)}return{covered:l,uncovered:d}}export{b as DriftRepairAvailableError,F as composePostFailureRepairOffer,k as formatDriftRepairOffer,u as formatRecreateCoveredNotice};

package/dist/src/orchestration/remediation/recreatePreFlight.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The recreate pre-flight — ONE pure-read pass over EVERY consented stack
+ * BEFORE any recreate surgery mutates anything (drift-remediation plan §
+ * Phase 7 fix pass 1). The surgery's removal phase can only fail EXPENSIVELY
+ * once the snapshot flip has landed (a burned UpdateStack, an orphaned
+ * mid-surgery journal), so every check that can be answered from reads runs
+ * here, pre-capture, across the whole consented set:
+ *
+ *  1. reference scan — `deriveRemovalTemplate` over the live template bytes:
+ *     a remaining resource referencing a target fails closed with the paths;
+ *  2. export-consumer scan — every Output the removal would strip that
+ *     carries an `Export` is checked via cfn:ListImports: CloudFormation
+ *     refuses to drop an export while imports exist, so an imported export
+ *     fails closed naming the importing stacks;
+ *  3. delete-blocking probe — targets whose owning service exposes a
+ *     delete-refusal setting (RDS DeletionProtection — fjall's own database
+ *     constructs default it ON) are probed live: an enabled setting fails
+ *     closed pre-capture, because CloudFormation's delete would DELETE_FAILED
+ *     mid-surgery after the flip already mutated the stack.
+ *
+ * All-stacks-before-any-flip: a multi-stack consent must never delete stack
+ * A's resource and then discover stack B was doomed — the caller passes every
+ * consented stack and nothing runs until all pass.
+ *
+ * Failure messages are pre-masked at construction (identifier-only content
+ * plus masked SDK error text).
+ */
+import { type Result } from "@fjall/generator";
+import type { AwsProvider } from "../../aws/AwsProvider.js";
+import { type RemediationTarget } from "../../types/remediation.js";
+export interface RecreatePreFlightStack {
+    stackName: string;
+    targets: readonly RemediationTarget[];
+}
+export interface RunRecreatePreFlightParams {
+    /** EVERY consented stack — the pass must clear all of them before the
+     * caller flips any. */
+    stacks: readonly RecreatePreFlightStack[];
+    abortSignal?: AbortSignal;
+}
+/**
+ * Run the merged pre-flight over every consented stack. Pure reads only —
+ * the first failure aborts the whole consented set before any surgery runs.
+ * Safe on resume paths too: targets already absent from the live template
+ * (removal landed) skip their checks.
+ */
+export declare function runRecreatePreFlight(aws: AwsProvider, params: RunRecreatePreFlightParams): Promise<Result<void, Error>>;

package/dist/src/orchestration/remediation/recreatePreFlight.js

@@ -0,0 +1 @@
+import{CloudFormationClient as y,ListImportsCommand as D}from"@aws-sdk/client-cloudformation";import{DescribeDBClustersCommand as $,DescribeDBInstancesCommand as E,RDSClient as h}from"@aws-sdk/client-rds";import{success as l,failure as i}from"@fjall/generator";import{getErrorMessage as m,maskSensitiveOutput as p}from"@fjall/util";import{logger as I}from"@fjall/util/logger";import{composeSdkAbortSignal as f,isAborted as g}from"../../aws/organisations/types.js";import{isRemediationPlaceholderPhysicalId as N}from"../../types/remediation.js";import{fetchLiveStackState as C}from"./forgetResource.js";import{deriveRemovalTemplate as S}from"./removalUpdate.js";const k="RecreatePreFlight",R=/is not imported by any stack/i;function b(t){const o=typeof t=="object"&&t!==null&&"name"in t?String(t.name):"";return/NotFound/i.test(o)}async function x(t,o,r){try{const n=await t.getClient(h).send(new E({DBInstanceIdentifier:o}),{abortSignal:f(r)});return l({blocked:n.DBInstances?.[0]?.DeletionProtection===!0,setting:"DeletionProtection"})}catch(n){return b(n)?l({blocked:!1,setting:"DeletionProtection"}):i(new Error(p(m(n))))}}async function P(t,o,r){try{const n=await t.getClient(h).send(new $({DBClusterIdentifier:o}),{abortSignal:f(r)});return l({blocked:n.DBClusters?.[0]?.DeletionProtection===!0,setting:"DeletionProtection"})}catch(n){return b(n)?l({blocked:!1,setting:"DeletionProtection"}):i(new Error(p(m(n))))}}const v={"AWS::RDS::DBInstance":{probe:x,method:"rds:DescribeDBInstances",disableCommand:t=>`aws rds modify-db-instance --db-instance-identifier ${t} --no-deletion-protection`},"AWS::RDS::DBCluster":{probe:P,method:"rds:DescribeDBClusters",disableCommand:t=>`aws rds modify-db-cluster --db-cluster-identifier ${t} --no-deletion-protection`}};async function B(t,o,r){const n=t.getClient(y),d=[];let c;try{do{if(g(r))return i(new Error(`aborted while listing imports of export '${o}'`));const s=await n.send(new D({ExportName:o,...c!==void 0?{NextToken:c}:{}}),{abortSignal:f(r)});d.push(...s.Imports??[]),c=s.NextToken}while(c!==void 0);return l(d)}catch(s){return R.test(m(s))?l([]):i(new Error(p(m(s))))}}async function G(t,o){for(const{stackName:r,targets:n}of o.stacks){if(g(o.abortSignal))return i(new Error(`Recreate pre-flight aborted before ${r} was checked \u2014 nothing was mutated in this run.`));const d=n.map(e=>e.logicalId),c=await C(t,r,o.abortSignal);if(!c.success)return i(new Error(`${c.error.message} Nothing was mutated in this run.`));const s=S(c.data.templateBody,d,r);if(!s.success)return i(new Error(`${s.error.message} Nothing was mutated in this run.`));const w=new Set(s.data.alreadyAbsent);for(const e of s.data.strippedExports){if(e.exportName===void 0)return i(new Error(`Recreate pre-flight for ${r}: removing ${d.join(", ")} strips output '${e.outputName}' whose Export name is not a literal string, so its cross-stack consumers cannot be verified \u2014 perform the replacement manually. Nothing was mutated in this run.`));const a=await B(t,e.exportName,o.abortSignal);if(!a.success)return i(new Error(`Recreate pre-flight for ${r}: could not verify whether export '${e.exportName}' (output '${e.outputName}') is imported by other stacks: ${a.error.message}. Retry the deploy. Nothing was mutated in this run.`));if(a.data.length>0)return i(new Error(`Recreate pre-flight for ${r}: removing ${d.join(", ")} strips export '${e.exportName}' (output '${e.outputName}'), which is imported by ${a.data.join(", ")} \u2014 CloudFormation refuses to drop an export while imports exist, so the surgery would fail mid-deploy. Redeploy the importing stack(s) without the import first, or perform the replacement manually. Nothing was mutated in this run.`))}for(const e of n){if(w.has(e.logicalId))continue;const a=v[e.resourceType];if(a===void 0)continue;if(N(e,r)){I.debug(k,"No live physical id to probe \u2014 skipping",{stackName:r,logicalId:e.logicalId});continue}const u=await a.probe(t,e.physicalId,o.abortSignal);if(!u.success)return i(new Error(`Recreate pre-flight for ${r}: could not verify that ${e.physicalId} (${e.logicalId}) is deletable \u2014 ${a.method} failed: ${u.error.message}. Retry the deploy. Nothing was mutated in this run.`));if(u.data.blocked)return i(new Error(`Recreate pre-flight for ${r}: ${e.physicalId} (${e.logicalId}) has ${u.data.setting} enabled \u2014 CloudFormation cannot delete it, so the pinned-name replacement would fail mid-surgery. Disable it on the live resource (e.g. '${a.disableCommand(e.physicalId)}'), then re-run the deploy. Nothing was mutated in this run.`))}}return l(void 0)}export{G as runRecreatePreFlight};

package/dist/src/orchestration/remediation/recreateResource.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The `recreate` orchestrator — the snapshot-flip variant of the forget
+ * surgery (drift-remediation plan § Phase 7), for the pinned-name-replacement
+ * class: CloudFormation refuses to replace a custom-named resource in place
+ * ("cannot update a stack when a custom-named resource requires replacing"),
+ * so fjall performs the replacement surgically inside the SAME deploy run:
+ *
+ *   captured → flip-verified (snapshot flip) → flip-applied →
+ *   removal-applied (surgical UpdateStack deletes the physical resource,
+ *   snapshotting per policy) → (the deploy continues and re-CREATEs the
+ *   resource under its pinned name) → done (post-deploy sweep)
+ *
+ * Unlike forget, the removal phase IS here: the synthesised template still
+ * declares the resource, so the converge cannot remove it — a surgical
+ * live-template-minus-targets update (`removalUpdate.ts`) deletes it first,
+ * freeing the pinned name. Closure then flows through the SAME machinery as
+ * forget (`completeForgetAfterConverge` → `resolveConvergedTargets`, marker
+ * key derived from the journal's verb): a re-created target is
+ * present-unmarked and physically probed live. Absent targets at sweep
+ * closure were removed instead of re-created (the config no longer declares
+ * them) — correct to close, the deletion was consented.
+ *
+ * Consent is the CALLER's job (the destruction ceremony runs before 3f
+ * invokes this). Resumability rides the deploy path, not `drift resume`: at
+ * any phase before removal-applied the pinned-name finding still fires, the
+ * ceremony re-consents, and this surgery resumes idempotently; after
+ * removal-applied the plan shows a plain CREATE (no ticket) and the sweep
+ * closes the journal. `drift resume`/`drift repair` fail closed on recreate
+ * journals (verb guard in `forgetResource.ts`) teaching the deploy re-run.
+ *
+ * Cross-incarnation edge: a NEW pinned-name finding on the same stack +
+ * logical-ID set reuses the opId (derivation excludes the verb and has no
+ * incarnation component). A resume that finds the prior incarnation at
+ * removal-applied first attempts closure; a closed journal then archives and
+ * restarts fresh under `doneJournalPolicy: "archive-and-restart"` (the 3f
+ * caller's policy), so the new consent gets a new surgery.
+ *
+ * The `fjall:recreate` marker key is deliberately distinct from
+ * `fjall:forget`: the two surgeries' resume/ownership scans never adopt each
+ * other's markers. Overlapping forget + recreate operations on one resource
+ * are an operator error, guarded at the opId collision point by the journal
+ * verb checks.
+ *
+ * Failure messages are pre-masked at construction.
+ */
+import { type Result } from "@fjall/generator";
+import type { AwsProvider } from "../../aws/AwsProvider.js";
+import type { DriftFinding } from "../../types/drift.js";
+import { type RemediationJournalRecord, type RemediationPhase, type RemediationTarget } from "../../types/remediation.js";
+import { type ForgetOrchestrationOptions } from "./forgetResource.js";
+import { type FlipDeletionPolicy } from "./retainFlip.js";
+/** Options shape shared with the forget orchestrator (coupled machinery). */
+export type RecreateOrchestrationOptions = ForgetOrchestrationOptions;
+/**
+ * CFN resource types that support `DeletionPolicy: Snapshot`
+ * (CloudFormation UserGuide § aws-attribute-deletionpolicy). Everything else
+ * flips to `Delete` — the data loss was consented at the ceremony; the
+ * snapshot is best-effort mitigation where the platform offers it.
+ */
+export declare const SNAPSHOT_CAPABLE_RESOURCE_TYPES: ReadonlySet<string>;
+export declare function snapshotPolicyForType(resourceType: string): Extract<FlipDeletionPolicy, "Snapshot" | "Delete">;
+export interface RecreateSurgeryParams {
+    stackName: string;
+    targets: readonly RemediationTarget[];
+    /** The deploy target that owns the stack — names the resume command. */
+    appName?: string;
+    /** Evidence persisted in the forensics bundle. */
+    findings?: readonly DriftFinding[];
+    /** Audit trail: the exact physical names consented at the ceremony. */
+    consentedPhysicalNames?: readonly string[];
+    /** Mirror of the forget arm's policy — the 3f deploy caller passes
+     * "archive-and-restart" so a done journal from a prior incarnation of the
+     * same stack + logical-ID set never false-reports completion. */
+    doneJournalPolicy?: "report-completed" | "archive-and-restart";
+    /**
+     * [G7] Logical IDs the CURRENT deploy plan replaces under a pinned name.
+     * A removal-applied resume whose closure could NOT verify a target
+     * (converge-pending) must FAIL CLOSED when that target overlaps this set —
+     * a converge-pending success would fall through to the native pinned-name
+     * replacement CloudFormation refuses, burning the run. The 3f caller passes
+     * its consented rows' logical IDs (by construction the plan replaces every
+     * one of them); callers with no planned replacement may omit.
+     */
+    plannedReplacementLogicalIds?: readonly string[];
+    onProgress?: (message: string) => void;
+    abortSignal?: AbortSignal;
+}
+export interface RecreateSurgeryReport {
+    opId: string;
+    /** Journal phase after this pass. */
+    phase: RemediationPhase;
+    /** True until the deploy re-creates the targets and the post-deploy sweep
+     * closes the journal — the caller MUST continue the deploy on true. */
+    convergePending: boolean;
+    forensicsPath?: string;
+    /** The DeletionPolicy stamped per target logical ID. */
+    snapshotPolicies: Record<string, "Snapshot" | "Delete">;
+    journal: RemediationJournalRecord;
+}
+/**
+ * The orchestrated recreate: forensics capture (abort on failure — no
+ * capture, no mutate), snapshot-flip derivation + both proofs, flip apply,
+ * surgical removal (proof + apply + GetTemplate absence verification), then
+ * removal-applied. The report is convergePending — the SAME deploy run
+ * continues past the surgery and re-creates the resource under its pinned
+ * name; the post-deploy sweep closes the journal. Idempotent and resumable:
+ * safe to re-run at any phase (resumption rides the deploy path — the
+ * pinned-name finding re-fires and re-consents until the removal lands).
+ */
+export declare function runRecreateSurgery(aws: AwsProvider, params: RecreateSurgeryParams, options?: RecreateOrchestrationOptions): Promise<Result<RecreateSurgeryReport, Error>>;

package/dist/src/orchestration/remediation/recreateResource.js

@@ -0,0 +1 @@
+import{success as j,failure as w}from"@fjall/generator";import{completeForgetAfterConverge as z,fetchLiveStackState as B}from"./forgetResource.js";import{archiveCompletedRemediationJournal as Q,computeRemediationOpId as X,formatArchivedOperationNotice as Z,formatCompletedOperationNotice as ee,readRemediationJournal as te,writeRemediationJournal as ae}from"./remediationJournal.js";import{captureRemediationForensics as re}from"./forensicsCapture.js";import{applyRetainFlip as x,computeTemplateDigest as H,deriveRetainFlipTemplate as ne,findMarkedResourcesByOpId as oe,proveFlipMetadataOnly as ie,readRetainFlipState as I,verifyRetainFlipDiff as se,RECREATE_MARKER_KEY as A}from"./retainFlip.js";import{deriveRemovalTemplate as le,findRemovalDeletionFailures as ce,proveRemovalTargetsOnly as de}from"./removalUpdate.js";const pe=new Set(["AWS::DocDB::DBCluster","AWS::EC2::Volume","AWS::ElastiCache::CacheCluster","AWS::ElastiCache::ReplicationGroup","AWS::Neptune::DBCluster","AWS::RDS::DBCluster","AWS::RDS::DBInstance","AWS::Redshift::Cluster"]);function ue(i){return pe.has(i)?"Snapshot":"Delete"}const fe=30*6e4;function me(i){const o={};for(const s of i)o[s.logicalId]=ue(s.resourceType);return o}function U(i,o,s,e){const R=e.filter(n=>n!==s);if(R.length===0)return j(void 0);const p=R.map(n=>{const f=oe(i,n,o,A);return`${n} covers ${f.success&&f.data.length>0?f.data.join(", "):"(could not recover its target set)"}`});return w(new Error(`Recreate operation ${s} on ${o} found target resources already carrying a ${A} marker from a different operation \u2014 its journal may live on another machine, and completing this operation over it would strand that surgery. Marked resources recovered from the live template: ${p.join("; ")}. Complete the foreign operation first (re-run its converge deploy on the machine that holds its journal), then re-run this deploy. Nothing was mutated.`))}async function we(i,o,s){const{stackName:e,targets:R,onProgress:p,abortSignal:n}=o;if(R.length===0)return w(new Error("Recreate surgery requires at least one target"));const f=s?.now??(()=>new Date),O=i.getAccountId(),N=i.getRegion(),u=R.map(a=>a.logicalId),l=X(e,u),P=me(R),b={markerKey:A,policyForTarget:a=>P[a]??"Delete"},E=o.appName!==void 0?`Re-run 'fjall deploy ${o.appName}' to resume the recreate.`:"Re-run the deploy to resume the recreate.",F=a=>a.snapshotPolicies??P;let t=await te(O,N,e,l,s?.journal);if(t!==null&&t.verb!=="recreate"&&t.phase!=="done")return w(new Error(`Recreate operation ${l} on ${e} collides with an in-flight '${t.verb}' operation covering the same resources \u2014 complete it first with 'fjall drift resume ${l}', then re-run this deploy. Nothing was mutated.`));if(t!==null&&t.phase==="removal-applied"){const a=await z(i,{journal:t,...n!==void 0?{abortSignal:n}:{}},s);if(!a.success)return a;if(t=a.data.journal,a.data.status==="converge-pending"){const d=a.data.unverified,y=(o.plannedReplacementLogicalIds??[]).filter(c=>d.includes(c));if(y.length>0){const c=o.appName!==void 0?`fjall deploy ${o.appName}`:"fjall deploy";return w(new Error(`Recreate operation ${l} on ${e} already applied its removal, but the closure check could not verify ${y.join(", ")} (re-created, removed, or still orphaned) \u2014 and this deploy plans a pinned-name replacement for the same target(s), which CloudFormation would refuse while the name may still be held. Nothing further was mutated. Retry the deploy once AWS settles \u2014 a re-assert or converge still in flight clears on its own. If it persists, verify the resource state in the owning service; the terminating cure is to remove the resource(s) from the fjall config and re-run '${c}' \u2014 the converge clears the unverifiable declaration and the operation closes as removed \u2014 then re-add the configuration to re-create them under their pinned names.`))}return p?.(`Removal already applied on ${e} \u2014 the deploy re-creates any still-missing ${u.join(", ")} under the pinned names; already-present targets close once the post-deploy sweep verifies them`),j({opId:l,phase:t.phase,convergePending:!0,...t.forensicsPath!==void 0?{forensicsPath:t.forensicsPath}:{},snapshotPolicies:F(t),journal:t})}}if(t!==null&&t.phase==="done"){if(o.doneJournalPolicy!=="archive-and-restart")return p?.(ee(t)),j({opId:l,phase:"done",convergePending:!1,...t.forensicsPath!==void 0?{forensicsPath:t.forensicsPath}:{},snapshotPolicies:F(t),journal:t});const a=await Q(t,s?.journal);if(!a.success)return a;p?.(Z(t)),t=null}const C=async a=>{const d=await ae(a,s?.journal);return d.success?j(a):w(d.error)};let m;if(t===null){const a=await B(i,e,n);if(!a.success)return a;const d=I(a.data.templateBody,u,e,b);if(!d.success)return d;const y=U(a.data.templateBody,e,l,d.data.markerOpIds);if(!y.success)return y;if(d.data.markerOpIds.includes(l)){p?.(`Recognised in-flight recreate markers on ${e} \u2014 resuming from the ${A} marker`);const c=f().toISOString(),$=await C({version:1,opId:l,verb:"recreate",accountId:O,region:N,stackName:e,...o.appName!==void 0?{appName:o.appName}:{},targets:[...R],phase:d.data.allFlipped?"flip-applied":"captured",createdAt:c,updatedAt:c,snapshotPolicies:P});if(!$.success)return $;t=$.data,m=a.data}else{p?.(`Capturing forensics for ${e} (${l})`);const c=await re(i,{stackName:e,opId:l,findings:o.findings??[],...n!==void 0?{abortSignal:n}:{}},s?.forensics);if(!c.success)return c;const $=f().toISOString(),D=await C({version:1,opId:l,verb:"recreate",accountId:O,region:N,stackName:e,...o.appName!==void 0?{appName:o.appName}:{},targets:[...R],phase:"captured",createdAt:$,updatedAt:$,forensicsPath:c.data.forensicsPath,snapshotPolicies:P,...o.consentedPhysicalNames!==void 0?{consentedPhysicalNames:[...o.consentedPhysicalNames]}:{}});if(!D.success)return D;t=D.data,m={templateBody:c.data.liveTemplateBody,capabilities:c.data.capabilities,parameterKeys:c.data.parameterKeys}}}if(m===void 0){const a=await B(i,e,n);if(!a.success)return a;m=a.data}let h=m.templateBody,v=I(h,u,e,b);if(!v.success)return v;const W=U(h,e,l,v.data.markerOpIds);if(!W.success)return W;const q=new Set(v.data.absentTargets),g=u.filter(a=>!q.has(a));if(g.length>0){if(v.data.unflippedTargets.filter(r=>g.includes(r)).length>0){p?.(`Deriving the snapshot flip for ${e}`);const r=ne({liveTemplateBody:h,stackName:e,targets:g,opId:l,at:f().toISOString(),spec:b});if(!r.success)return r;const T=se(h,r.data.flipTemplateBody,g,e,A);if(!T.success)return T;p?.("Proving the flip is metadata-only (review change set)");const S=await ie(i,{stackName:e,flipTemplateBody:r.data.flipTemplateBody,targets:g,parameterKeys:m.parameterKeys,...n!==void 0?{abortSignal:n}:{}},s?.flip);if(!S.success)return S;const K=await C({...t,phase:"flip-verified",updatedAt:f().toISOString(),liveTemplateDigest:r.data.liveTemplateDigest,proof:{diffGuardPassed:!0,changeSetMetadataOnly:!0,noChanges:S.data.noChanges,provenAt:f().toISOString()}});if(!K.success)return K;t=K.data,p?.(`Applying the snapshot flip to ${e}`);const M=await x(i,{stackName:e,flipTemplateBody:r.data.flipTemplateBody,capabilities:m.capabilities,parameterKeys:m.parameterKeys,derivedFromTemplateDigest:r.data.liveTemplateDigest,opId:l,operationLabel:"Snapshot-flip",resumeHint:E,...n!==void 0?{abortSignal:n}:{}},s?.flip);if(!M.success)return M;const _=await B(i,e,n);if(!_.success)return _;if(h=_.data.templateBody,v=I(h,u,e,b),!v.success)return v;const V=new Set(v.data.absentTargets),J=v.data.unflippedTargets.filter(Y=>!V.has(Y));if(J.length>0)return w(new Error(`Snapshot flip on ${e} reported ${M.data.outcome} but GetTemplate does not show the snapshot policy + the ${A} marker on ${J.join(", ")} \u2014 aborting to manual repair.`))}if(t.phase==="captured"||t.phase==="flip-verified"){const r=await C({...t,phase:"flip-applied",updatedAt:f().toISOString(),liveTemplateDigest:H(h)});if(!r.success)return r;t=r.data}p?.(`Deriving the surgical removal of ${g.join(", ")} from ${e}`);const d=le(h,u,e);if(!d.success)return w(new Error(`${d.error.message} The snapshot flip has already been applied on ${e}. ${E}`));p?.("Proving the removal touches only the recreate targets (review change set)");const y=await de(i,{stackName:e,removalTemplateBody:d.data.removalTemplateBody,targets:u,parameterKeys:m.parameterKeys,...n!==void 0?{abortSignal:n}:{}},s?.flip);if(!y.success)return y;if(!y.data.noChanges){const r=g.map(S=>`${S} \u2192 ${P[S]??"Delete"}`).join(", ");p?.(`Removing ${g.join(", ")} from ${e} (deletion policies: ${r})`);const T=await x(i,{stackName:e,flipTemplateBody:d.data.removalTemplateBody,capabilities:m.capabilities,parameterKeys:m.parameterKeys,derivedFromTemplateDigest:d.data.liveTemplateDigest,opId:l,operationLabel:"Recreate-removal",resumeHint:E,...n!==void 0?{abortSignal:n}:{}},{...s?.flip,updateTimeoutMs:s?.flip?.updateTimeoutMs??fe});if(!T.success)return T}const c=await B(i,e,n);if(!c.success)return c;h=c.data.templateBody;const $=I(h,u,e,b);if(!$.success)return $;const D=new Set($.data.absentTargets),L=u.filter(r=>!D.has(r));if(L.length>0)return w(new Error(`Recreate removal on ${e} completed but GetTemplate still shows ${L.join(", ")} \u2014 aborting to manual repair. ${E}`));if(!y.data.noChanges){const r=await ce(i,e,u,n);if(!r.success)return w(new Error(`Recreate removal on ${e} removed ${g.join(", ")} from the template, but the physical deletion outcome could not be verified: ${r.error.message}. ${E}`));if(r.data.length>0){const T=r.data.map(S=>`${S.logicalId}${S.statusReason!==void 0?` (${S.statusReason})`:""}`).join("; ");return w(new Error(`Recreate removal on ${e} removed ${g.join(", ")} from the template, but CloudFormation reported DELETE_FAILED for ${T} \u2014 the physical resource(s) still exist outside the stack and hold the pinned name(s), so the deploy's re-create would collide. Resolve the deletion failure and delete the orphaned resource(s) manually, then re-run the deploy to resume.`))}}const G=g.filter(r=>P[r]==="Snapshot");G.length>0&&p?.(`Final snapshots were requested for ${G.join(", ")} \u2014 locate them in the owning service's console to restore data into the re-created resources`)}const k=await C({...t,phase:"removal-applied",updatedAt:f().toISOString(),liveTemplateDigest:H(h)});return k.success?(t=k.data,p?.(`Surgical removal complete on ${e} \u2014 the deploy now re-creates ${u.join(", ")} under the pinned names`),j({opId:l,phase:t.phase,convergePending:!0,...t.forensicsPath!==void 0?{forensicsPath:t.forensicsPath}:{},snapshotPolicies:F(t),journal:t})):k}export{pe as SNAPSHOT_CAPABLE_RESOURCE_TYPES,we as runRecreateSurgery,ue as snapshotPolicyForType};

package/dist/src/orchestration/remediation/remediationJournal.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Persistent remediation journal for the two-deploy `forget` orchestration
+ * (drift-remediation plan § 3.2). One JSON file per operation under
+ * `~/.fjall/state/remediation/<accountId>/<region>/<stackName>/<opId>.json`;
+ * writes are atomic (tmp + rename) against concurrent processes sharing the
+ * directory.
+ *
+ * Unlike the drift-suspect journal (a hint), journal WRITES here fail loudly
+ * — a phase transition that cannot persist aborts the orchestration rather
+ * than mutating without a resume record. READS stay fail-soft: a corrupt or
+ * schema-drifted file reads as `null` (warn-logged) because the AWS-side
+ * `fjall:forget` marker [G3] re-derives the state a lost journal would have
+ * carried.
+ *
+ * Completed records are the audit trail, retained 90 days
+ * (`sweepExpiredRemediationJournals`); the sweep also removes the record's
+ * forensics bundle — the done journal holds the only `forensicsPath` pointer,
+ * so a bundle outliving its journal would accumulate unreferenced forever.
+ */
+import { type Result } from "@fjall/generator";
+import { type RemediationJournalRecord } from "../../types/remediation.js";
+export declare const REMEDIATION_JOURNAL_RETENTION_DAYS = 90;
+export interface RemediationJournalOptions {
+    /** Override the journal root — tests point this at a temp dir. */
+    journalDir?: string;
+}
+export declare function defaultRemediationJournalDir(): string;
+/**
+ * opId = digest of stack + logical-ID set (plan §3.2) — order-insensitive so
+ * re-detection reproduces the same id and a re-run resumes instead of forking
+ * a second operation. 16 hex chars keeps it path- and prompt-friendly.
+ */
+export declare function computeRemediationOpId(stackName: string, logicalIds: readonly string[]): string;
+/**
+ * [G5] Verb-accurate done-journal notices, shared by BOTH surgery orchestrators
+ * (`runForgetSurgery` and `runRecreateSurgery` each meet cross-verb DONE
+ * journals — coupled values, one home). Deriving from `journal.verb` keeps a
+ * done RECREATE journal read through the forget arm from reporting "Forget
+ * operation … already completed", and vice versa.
+ */
+export declare function formatCompletedOperationNotice(journal: Pick<RemediationJournalRecord, "verb" | "opId">): string;
+export declare function formatArchivedOperationNotice(journal: Pick<RemediationJournalRecord, "verb" | "opId">): string;
+/**
+ * Persist the journal record (atomic tmp + rename). Fails loudly — callers
+ * abort the orchestration when the resume record cannot be written.
+ */
+export declare function writeRemediationJournal(record: RemediationJournalRecord, options?: RemediationJournalOptions): Promise<Result<string, Error>>;
+/**
+ * Read one operation's journal. Missing, corrupt, or schema-drifted files
+ * read as `null` (warn-logged) — the fjall:forget marker [G3] re-derives.
+ */
+export declare function readRemediationJournal(accountId: string, region: string, stackName: string, opId: string, options?: RemediationJournalOptions): Promise<RemediationJournalRecord | null>;
+/**
+ * Archive a COMPLETED journal out of the resume keyspace: renamed to
+ * `<opId>.done-<completedAt>.json` in place, it stops matching
+ * `findRemediationJournalByOpId` and the fresh-repair read while remaining a
+ * parseable done record — `listActiveRemediationOps` still excludes it and
+ * the retention sweep still ages it out. Used when a fresh repair meets a
+ * done journal from a prior incarnation of the same opId.
+ */
+export declare function archiveCompletedRemediationJournal(record: RemediationJournalRecord, options?: RemediationJournalOptions): Promise<Result<string, Error>>;
+export interface RemediationJournalContext {
+    accountId: string;
+    region: string;
+}
+/**
+ * Locate a journal by opId alone (`fjall drift resume <opId>` has no stack
+ * context). Scans the account/region/stack keyspace for `<opId>.json`. The
+ * opId has no account/region component, so the same operation replayed in two
+ * contexts (staging + prod) collides — with multiple matches the one under
+ * the current credentials' account/region wins; when none matches, the
+ * failure enumerates every match so the operator can switch context.
+ */
+export declare function findRemediationJournalByOpId(opId: string, context?: RemediationJournalContext, options?: RemediationJournalOptions): Promise<Result<RemediationJournalRecord | null, Error>>;
+/** All non-done operations for one stack — the [G2] pre-flight consumes. */
+export declare function listActiveRemediationOps(accountId: string, region: string, stackName: string, options?: RemediationJournalOptions): Promise<RemediationJournalRecord[]>;
+/**
+ * All non-done operations across EVERY stack in one account/region — the
+ * post-deploy closure sweep consumes (an open recreate journal can live on a
+ * stack the current deploy skipped, and that sweep is the recreate arm's
+ * sole closure point).
+ */
+export declare function listActiveRemediationOpsForContext(accountId: string, region: string, options?: RemediationJournalOptions): Promise<RemediationJournalRecord[]>;
+/**
+ * Best-effort sweep of completed journals past the 90-day audit retention.
+ * Never fails the caller.
+ */
+export declare function sweepExpiredRemediationJournals(options?: RemediationJournalOptions, now?: () => Date): Promise<void>;

package/dist/src/orchestration/remediation/remediationJournal.js

@@ -0,0 +1,2 @@
+import{createHash as J}from"node:crypto";import{mkdir as b,readdir as j,readFile as $,rename as N,rm as x,rmdir as E,writeFile as S}from"node:fs/promises";import{homedir as T}from"node:os";import{basename as O,dirname as I,join as m}from"node:path";import{success as h,failure as g}from"@fjall/generator";import{getErrorMessage as f,maskSensitiveOutput as s}from"@fjall/util";import{logger as l}from"@fjall/util/logger";import{RemediationJournalRecordSchema as _}from"../../types/remediation.js";const d="RemediationJournal",k=90;function w(){return m(T(),".fjall","state","remediation")}function V(e,n){const r=J("sha256");r.update(e);for(const t of[...n].sort())r.update(`
+`),r.update(t);return r.digest("hex").slice(0,16)}function q(e){return`${C(e.verb)} operation ${e.opId} already completed`}function Q(e){return`Archived completed ${e.verb} operation ${e.opId} from a previous incarnation \u2014 starting a fresh operation`}function C(e){return e.charAt(0).toUpperCase()+e.slice(1)}const D=/^[A-Za-z0-9][A-Za-z0-9-]*$/,F=/^[a-f0-9]{8,64}$/;function v(e,n,r,t,a){for(const[o,u,i]of[["accountId",n,D],["region",r,D],["stackName",t,D],["opId",a,F]])if(!i.test(u))return g(new Error(`Refusing remediation journal path: unsafe ${o} segment "${s(u)}"`));return h(m(e,n,r,t,`${a}.json`))}async function X(e,n){const r=n?.journalDir??w(),t=v(r,e.accountId,e.region,e.stackName,e.opId);if(!t.success)return t;try{await b(I(t.data),{recursive:!0});const a=`${t.data}.tmp-${process.pid}`;return await S(a,JSON.stringify(e,null,2),"utf8"),await N(a,t.data),h(t.data)}catch(a){return g(new Error(`Failed to write remediation journal for ${e.stackName}/${e.opId}: ${s(f(a))}`))}}async function P(e,n,r,t,a){const o=a?.journalDir??w(),u=v(o,e,n,r,t);if(!u.success)return null;let i;try{i=await $(u.data,"utf8")}catch{return null}return R(i,`${r}/${t}`)}function R(e,n){let r;try{r=JSON.parse(e)}catch(a){return l.warn(d,"Corrupt remediation journal ignored",{label:n,error:s(f(a))}),null}const t=_.safeParse(r);return t.success?t.data:(l.warn(d,"Schema-drifted remediation journal ignored",{label:n,error:s(t.error.message)}),null)}async function ee(e,n){const r=n?.journalDir??w(),t=v(r,e.accountId,e.region,e.stackName,e.opId);if(!t.success)return t;const a=(e.completedAt??e.updatedAt).replace(/[^0-9A-Za-z.-]/g,""),o=t.data.replace(/\.json$/,`.done-${a}.json`);try{return await N(t.data,o),h(o)}catch(u){return g(new Error(`Failed to archive the completed remediation journal for ${e.stackName}/${e.opId}: ${s(f(u))}`))}}async function te(e,n,r){if(!F.test(e))return h(null);const t=r?.journalDir??w();let a;try{a=await A(t,3)}catch{return h(null)}const o=[];for(const i of a.filter(c=>c.endsWith(`/${e}.json`))){let c;try{c=await $(i,"utf8")}catch{continue}const p=R(c,e);p!==null&&o.push(p)}if(o.length===0)return h(null);if(o.length===1)return h(o[0]??null);const u=o.find(i=>i.accountId===n?.accountId&&i.region===n?.region);return u!==void 0?h(u):g(new Error(`Remediation operation ${e} exists in more than one context: ${o.map(i=>`${i.accountId}/${i.region}`).join(", ")}${n!==void 0?` \u2014 none matches the current credentials (${n.accountId}/${n.region}). Switch to the matching account/region and re-run 'fjall drift resume ${e}'.`:"."}`))}async function M(e,n,r,t){const a=t?.journalDir??w(),o=m(a,e,n,r);if(!D.test(r))return[];let u;try{u=await j(o)}catch{return[]}const i=[];for(const c of u){if(!c.endsWith(".json"))continue;let p;try{p=await $(m(o,c),"utf8")}catch{continue}const y=R(p,`${r}/${c}`);y!==null&&y.phase!=="done"&&i.push(y)}return i}async function re(e,n,r){const t=r?.journalDir??w();let a;try{a=await j(m(t,e,n))}catch{return[]}const o=[];for(const u of a)o.push(...await M(e,n,u,r));return o}async function ne(e,n=()=>new Date){const r=e?.journalDir??w(),t=n().getTime()-k*24*60*60*1e3;let a;try{a=await A(r,3)}catch{return}for(const o of a){let u;try{u=await $(o,"utf8")}catch{continue}const i=R(u,o);if(i===null||i.phase!=="done")continue;const c=Date.parse(i.completedAt??i.updatedAt);if(Number.isNaN(c)||c>=t)continue;let p=!0;await x(o,{force:!0}).catch(y=>{p=!1,l.debug(d,"Failed to sweep expired remediation journal",{file:o,error:s(f(y))})}),!(!p||i.forensicsPath===void 0)&&await K(i.forensicsPath,i.opId)}}async function K(e,n){const r=I(e),t=O(e)===n;if(!F.test(n)||!t&&O(r)!==n){l.debug(d,"Kept forensics bundle \u2014 unexpected path shape",{forensicsPath:e});return}if(t){await z(e);return}let a=!0;await x(e,{recursive:!0,force:!0}).catch(o=>{a=!1,l.warn(d,"Failed to sweep the expired journal's forensics",{forensicsPath:e,error:s(f(o))})}),a&&await E(r).catch(o=>{l.debug(d,"Kept forensics opId directory",{opDir:r,error:s(f(o))})})}async function z(e){let n;try{n=await j(e,{withFileTypes:!0})}catch(t){l.warn(d,"Failed to sweep the expired journal's forensics",{forensicsPath:e,error:s(f(t))});return}let r=!1;for(const t of n){if(!t.isFile()){r=!0;continue}await x(m(e,t.name),{force:!0}).catch(a=>{r=!0,l.warn(d,"Failed to sweep the expired journal's forensics",{forensicsPath:m(e,t.name),error:s(f(a))})})}if(r){l.debug(d,"Kept flat forensics directory \u2014 nested bundles live",{forensicsPath:e});return}await E(e).catch(t=>{l.debug(d,"Kept forensics opId directory",{forensicsPath:e,error:s(f(t))})})}async function A(e,n){const r=await j(e,{withFileTypes:!0}),t=[];for(const a of r){const o=m(e,a.name);a.isFile()&&a.name.endsWith(".json")?t.push(o):a.isDirectory()&&n>0&&t.push(...await A(o,n-1).catch(()=>[]))}return t}export{k as REMEDIATION_JOURNAL_RETENTION_DAYS,ee as archiveCompletedRemediationJournal,V as computeRemediationOpId,w as defaultRemediationJournalDir,te as findRemediationJournalByOpId,Q as formatArchivedOperationNotice,q as formatCompletedOperationNotice,M as listActiveRemediationOps,re as listActiveRemediationOpsForContext,P as readRemediationJournal,ne as sweepExpiredRemediationJournals,X as writeRemediationJournal};

package/dist/src/orchestration/remediation/removalUpdate.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The surgical removal update — the recreate orchestration's middle phase
+ * (drift-remediation plan § Phase 7): derive a removal template from the LIVE
+ * template (`GetTemplate`, never synth) with the target resources deleted, so
+ * CloudFormation deletes the physical resources under the snapshot-flip's
+ * DeletionPolicy (Snapshot where supported) and frees the pinned names for
+ * the converge deploy to re-create.
+ *
+ * Derivation is deliberately conservative:
+ *  - target resources are removed; each remaining resource's `DependsOn`
+ *    edges to a target are pruned (a dangling DependsOn fails validation);
+ *  - Outputs whose subtree references a target (Ref / Fn::GetAtt / Fn::Sub)
+ *    are removed (a dangling output reference fails validation);
+ *  - a REMAINING RESOURCE that references a target fails the derivation
+ *    closed with the referencing paths (paths only, never values) — silently
+ *    deleting or rewriting a live sibling resource is never fjall's call.
+ *
+ * `proveRemovalTargetsOnly` mirrors the retain flip's review change set: a
+ * `fjall-preflight-` change set must report ONLY `Remove` actions on the
+ * target logical IDs before the apply may run. The apply itself reuses
+ * `applyRetainFlip` (template-agnostic UpdateStack + TOCTOU digest re-check +
+ * poll) under a "Recreate-removal" label.
+ *
+ * Failure messages are pre-masked at construction (all content is
+ * identifier-only: logical IDs, paths, stack names).
+ */
+import { type Result } from "@fjall/generator";
+import type { AwsProvider } from "../../aws/AwsProvider.js";
+import { type RetainFlipOptions } from "./retainFlip.js";
+/**
+ * The logical IDs of RESOURCES that reference any target via Ref, Fn::GetAtt
+ * or Fn::Sub (DependsOn excluded — it names an ordering edge, not a value
+ * CloudFormation must resolve). The forget arm's defect-#5 referrer guard:
+ * CloudFormation re-resolves a modified resource's Ref/GetAtt for its
+ * dependents at execution time, which fails for a DEAD target — so a flip
+ * UpdateStack on a policy-pending dead target with live referrers can never
+ * succeed and must fail closed before any mutation. Reuses the removal
+ * derivation's canonical reference traversal (single source of truth).
+ *
+ * Unlike the removal derivation (where targets vanish together, so
+ * target-to-target references are moot), the flip MODIFIES targets in place —
+ * a target referencing a modified dead sibling is re-evaluated exactly like
+ * an outside referrer (the live incident proved even DEAD referrers fail the
+ * re-resolution), so distinct targets referencing each other are reported.
+ *
+ * Scan covers the Resources section only. An Output referencing a modified
+ * dead target is NOT flagged: whether CloudFormation re-evaluates Outputs at
+ * execution time is unproven live, and Output-references-stateful-resource is
+ * so common in CDK synth that guarding on it would block legitimate flips; a
+ * missed referrer degrades to a clean rollback, never an unsafe mutation
+ * (residual recorded in the flipless ADR, 2026-07-12).
+ */
+export declare function findTargetReferrers(liveTemplateBody: string, targets: readonly string[], stackName: string): Result<string[], Error>;
+export interface DeadReferenceFromTarget {
+    /** The policy-pending target whose own properties carry the reference. */
+    pendingTarget: string;
+    /** The dead siblings it references (Ref / Fn::GetAtt / Fn::Sub). */
+    deadReferences: string[];
+}
+/**
+ * The policy-pending targets whose OWN properties reference another dead
+ * target. The defect-#5 guard's outbound direction: the second live incident
+ * (2026-07-12, KMS alias flip) proved CloudFormation also resolves a MODIFIED
+ * resource's own outbound Ref/GetAtt at execution time — even when the
+ * referenced resource is not itself modified — so a flip UpdateStack on a
+ * pending target referencing ANY dead sibling rolls back exactly like the
+ * inbound referrer case. `findTargetReferrers` cannot see this shape: it
+ * scans for references TO the pending set, and the doomed reference points
+ * FROM the pending target at a sibling outside that set.
+ *
+ * `deadTargets` is the caller's known-deleted set (for the forget arm: the
+ * op's targets minus any retained-by-redeclaration, which are proven
+ * physically present and safe to reference). Self-references are excluded to
+ * mirror the intra-set precedent, though CloudFormation rejects them anyway.
+ */
+export declare function findDeadReferencesFromTargets(liveTemplateBody: string, pendingTargets: readonly string[], deadTargets: readonly string[], stackName: string): Result<DeadReferenceFromTarget[], Error>;
+/** An Output the derivation stripped that carries an `Export` block — the
+ * pre-flight must prove no other stack imports it before any mutation. */
+export interface StrippedExport {
+    outputName: string;
+    /** The literal export name; undefined when `Export.Name` is not a plain
+     * string (unresolvable locally — the pre-flight fails closed on it). */
+    exportName?: string;
+}
+export interface RemovalDerivation {
+    removalTemplateBody: string;
+    liveTemplateDigest: string;
+    /** Targets already absent from the live template (removal landed). */
+    alreadyAbsent: string[];
+    /** Stripped Outputs carrying an Export — cross-stack consumers of these
+     * make the removal update fail mid-deploy (CFN refuses to drop an export
+     * while imports exist); `runRecreatePreFlight` checks them via ListImports. */
+    strippedExports: StrippedExport[];
+}
+/**
+ * Derive the removal template: live template minus the target resources,
+ * with DependsOn edges pruned and target-referencing Outputs dropped. A
+ * remaining RESOURCE referencing a target fails closed with the paths.
+ */
+export declare function deriveRemovalTemplate(liveTemplateBody: string, targets: readonly string[], stackName: string): Result<RemovalDerivation, Error>;
+export interface RemovalDeletionFailure {
+    logicalId: string;
+    /** Masked at construction — a status reason can embed handler output. */
+    statusReason?: string;
+}
+/**
+ * GetTemplate absence alone cannot prove the physical deletions succeeded:
+ * CloudFormation deletes removed resources during the update-CLEANUP phase,
+ * and a DELETE_FAILED there leaves the stack UPDATE_COMPLETE with the target
+ * gone from the template but orphaned alive — still holding its pinned name,
+ * so the converge's re-create would collide. Scan the just-settled
+ * operation's events for DELETE_FAILED on the targets. Only meaningful
+ * immediately after this run's removal update (the scan reads the LAST
+ * operation's events).
+ */
+export declare function findRemovalDeletionFailures(aws: AwsProvider, stackName: string, targets: readonly string[], abortSignal?: AbortSignal): Promise<Result<RemovalDeletionFailure[], Error>>;
+export interface RemovalProofResult {
+    /** CFN reported the removal contains no changes — the caller MUST re-verify
+     * target absence via GetTemplate, never assume the removal landed. */
+    noChanges: boolean;
+}
+export interface ProveRemovalTargetsOnlyParams {
+    stackName: string;
+    removalTemplateBody: string;
+    targets: readonly string[];
+    /** Live parameter keys, echoed UsePreviousValue (see retainFlip). */
+    parameterKeys: readonly string[];
+    abortSignal?: AbortSignal;
+}
+/**
+ * Review-only `fjall-preflight-` change set proving every reported resource
+ * change is a `Remove` on a target logical ID. Nothing is executed; the
+ * change set is deleted in `finally`.
+ */
+export declare function proveRemovalTargetsOnly(aws: AwsProvider, params: ProveRemovalTargetsOnlyParams, options?: RetainFlipOptions): Promise<Result<RemovalProofResult, Error>>;

package/dist/src/orchestration/remediation/removalUpdate.js

@@ -0,0 +1 @@
+import{randomUUID as I}from"node:crypto";import{CloudFormationClient as k,CreateChangeSetCommand as _,DeleteChangeSetCommand as F,DescribeChangeSetCommand as O}from"@aws-sdk/client-cloudformation";import{success as h,failure as m}from"@fjall/generator";import{getErrorMessage as N,maskSensitiveOutput as A}from"@fjall/util";import{logger as L}from"@fjall/util/logger";import{composeSdkAbortSignal as $,isAborted as R}from"../../aws/organisations/types.js";import{PREFLIGHT_CHANGE_SET_PREFIX as j}from"../../services/infrastructure/changeSetProbe.js";import{sleepAbortable as x}from"../../util/sleepAbortable.js";import{fetchLastOperationEvents as M}from"../drift/classifyDriftFailure.js";import{composeFlipCapabilities as P,computeTemplateDigest as U,echoPreviousParameters as G,resolveTemplateLocation as H,deleteStagedTemplate as J}from"./retainFlip.js";const B="RemovalUpdate",K=/didn't contain changes|No updates are to be performed/i,z=new Set(["CREATE_COMPLETE","FAILED"]),V=3e3,X=9e4;function v(a,o){let r;try{r=JSON.parse(a)}catch{return m(new Error(`The live template for ${o} is not JSON (YAML-authored stacks are not supported by the removal update) \u2014 aborting to manual repair.`))}return typeof r!="object"||r===null||Array.isArray(r)?m(new Error(`The live template for ${o} did not parse to an object \u2014 aborting to manual repair.`)):h(r)}function S(a,o,r){if(typeof a=="string")return[];if(Array.isArray(a))return a.flatMap((s,c)=>S(s,o,`${r}[${c}]`));if(typeof a!="object"||a===null)return[];const t=a,e=[],u=t.Ref;typeof u=="string"&&o.has(u)&&e.push(`${r}/Ref(${u})`);const n=t["Fn::GetAtt"];typeof n=="string"&&o.has(n.split(".")[0]??"")&&e.push(`${r}/Fn::GetAtt(${n.split(".")[0]??""})`),Array.isArray(n)&&typeof n[0]=="string"&&o.has(n[0])&&e.push(`${r}/Fn::GetAtt(${n[0]})`);const f=t["Fn::Sub"],i=typeof f=="string"?f:Array.isArray(f)&&typeof f[0]=="string"?f[0]:void 0;if(i!==void 0)for(const s of i.matchAll(/\$\{([^!}][^}]*)\}/g)){const c=(s[1]??"").split(".")[0]??"";o.has(c)&&e.push(`${r}/Fn::Sub(${c})`)}for(const[s,c]of Object.entries(t))e.push(...S(c,o,`${r}/${s}`));return e}function se(a,o,r){const t=v(a,r);if(!t.success)return t;const e=new Set(o),u=[];for(const[n,f]of Object.entries(t.data.Resources??{})){const i=e.has(n)?new Set([...e].filter(s=>s!==n)):e;i.size!==0&&S(f,i,n).length>0&&u.push(n)}return h(u)}function ie(a,o,r,t){const e=v(a,t);if(!e.success)return e;const u=e.data.Resources??{},n=[];for(const f of o){const i=u[f];if(i===void 0)continue;const s=r.filter(c=>c!==f&&S(i,new Set([c]),f).length>0);s.length>0&&n.push({pendingTarget:f,deadReferences:s})}return h(n)}function Y(a,o){const r=a.DependsOn;if(typeof r=="string"){o.has(r)&&delete a.DependsOn;return}if(Array.isArray(r)){const t=r.filter(e=>typeof e!="string"||!o.has(e));t.length===0?delete a.DependsOn:t.length!==r.length&&(a.DependsOn=t)}}function ce(a,o,r){const t=v(a,r);if(!t.success)return t;const e=t.data,u=e.Resources??{},n=new Set(o),f=o.filter(l=>u[l]===void 0);for(const l of o)delete u[l];const i=[];for(const[l,p]of Object.entries(u))Y(p,n),i.push(...S(p,n,l));if(i.length>0)return m(new Error(`Cannot orchestrate the recreate for ${r}: other resources still reference ${[...n].join(", ")} at ${i.slice(0,10).join(", ")}${i.length>10?` (+${i.length-10} more)`:""} \u2014 removing the target would break them. Restructure the dependency or perform the replacement manually.`));const s=[],c=e.Outputs;if(typeof c=="object"&&c!==null){for(const[l,p]of Object.entries(c))if(S(p,n,`Outputs/${l}`).length>0){const d=typeof p=="object"&&p!==null?p.Export:void 0;if(typeof d=="object"&&d!==null){const g=d.Name;s.push({outputName:l,...typeof g=="string"?{exportName:g}:{}})}delete c[l]}Object.keys(c).length===0&&delete e.Outputs}return h({removalTemplateBody:JSON.stringify(e),liveTemplateDigest:U(a),alreadyAbsent:f,strippedExports:s})}async function le(a,o,r,t){const e=await M(a,o,t);if(!e.success)return e;const u=new Set(r);return h(e.data.filter(n=>u.has(n.logicalId)&&n.status==="DELETE_FAILED").map(n=>({logicalId:n.logicalId,...n.statusReason!==void 0?{statusReason:A(n.statusReason)}:{}})))}async function fe(a,o,r){const{stackName:t,abortSignal:e}=o,u=r?.pollIntervalMs??V,n=r?.changeSetTimeoutMs??X,f=r?.now??(()=>Date.now()),i=a.getClient(k),s=`${j}removal-${I()}`;let c;try{const l=await H(a,s,o.removalTemplateBody,e);if(!l.success)return l;c=l.data.key,await i.send(new _({StackName:t,ChangeSetName:s,ChangeSetType:"UPDATE",IncludeNestedStacks:!0,Capabilities:P([]),Description:"fjall recreate-removal targets-only proof \u2014 review-only, never executed",...G(o.parameterKeys),...l.data.location}),{abortSignal:$(e)});const p=f();let d,g;for(;!R(e);){const y=await i.send(new O({StackName:t,ChangeSetName:s}),{abortSignal:$(e)});if(d=y.Status,g=y.StatusReason,d!==void 0&&z.has(d))break;if(f()-p>=n)return m(new Error(`Recreate-removal proof timed out after ${n}ms for ${t} (last status: ${d??"unknown"})`));await x(u,e)}if(R(e))return m(new Error(`Recreate-removal proof aborted while polling ${t}`));if(d==="FAILED")return g!==void 0&&K.test(g)?h({noChanges:!0}):m(new Error(`Recreate-removal proof change set failed for ${t}: ${A(g??"no status reason reported")}`));const T=[],D=new Set(o.targets);let b;do{if(R(e))return m(new Error(`Recreate-removal proof aborted while reading ${t}`));const y=await i.send(new O({StackName:t,ChangeSetName:s,...b!==void 0?{NextToken:b}:{}}),{abortSignal:$(e)});for(const C of y.Changes??[]){if(C.Type!=="Resource")continue;const w=C.ResourceChange,E=w?.LogicalResourceId;if(!(w===void 0||E===void 0)){if(!D.has(E)){T.push(`${E} (not a removal target)`);continue}w.Action!=="Remove"&&T.push(`${E} (action ${w.Action??"unknown"})`)}}b=y.NextToken}while(b!==void 0);return T.length>0?m(new Error(`Recreate removal is NOT targets-only for ${t} \u2014 the review change set reported changes at ${[...new Set(T)].join(", ")}. Aborting before the removal ran; the snapshot flip has already been applied, so re-run the deploy to resume once the change is understood.`)):h({noChanges:!1})}catch(l){return m(new Error(`Recreate-removal proof failed for ${t}: ${A(N(l))}`))}finally{await i.send(new F({StackName:t,ChangeSetName:s}),{abortSignal:$()}).catch(l=>{L.warn(B,"Failed to delete recreate-removal proof change set",{stackName:t,changeSetName:s,error:A(N(l))})}),c!==void 0&&await J(a,c)}}export{ce as deriveRemovalTemplate,ie as findDeadReferencesFromTargets,le as findRemovalDeletionFailures,se as findTargetReferrers,fe as proveRemovalTargetsOnly};