@fjall/deploy-core 2.27.0 → 2.29.0

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

@@ -0,0 +1,121 @@
+/**
+ * The `pin` arm — the non-destructive escape hatch (plan § 3): probe the LIVE
+ * value of each offending property from its owning service and emit an
+ * edit-ready codemod into the user's fjall config so the diff disappears.
+ * Degrades to report-only carrying the exact config line whenever any step
+ * cannot complete confidently — never a partial edit (the
+ * `restoreAndReconcileQuarantinedBucket` reconcile doctrine). The codemod is
+ * OFFERED to the caller (Q6): this module only computes `modifiedContent`;
+ * the surface that owns the config file decides to write it.
+ *
+ * v1 probe table: RDS DBInstance/DBCluster `Port`. Every other
+ * (resourceType, property) pair degrades honestly to `no-probe-support`
+ * naming the pair.
+ *
+ * Failure messages are pre-masked at construction.
+ */
+import type { AwsProvider } from "../../aws/AwsProvider.js";
+export interface PinTarget {
+    stack: string;
+    logicalId: string;
+    resourceType: string;
+    /** Ticket `physicalName` — a pinned literal, or the shared placeholder
+     * shape (`remediationPlaceholderPhysicalId`) for unpinned rows. */
+    physicalName: string;
+    /** Offending property paths from the ticket row (bare names or
+     * `/properties/`-prefixed pointers). */
+    offendingProperties: readonly string[];
+}
+/** One probed live value plus the exact config line that pins it. */
+export interface PinnedProperty {
+    /** CloudFormation property name (e.g. "Port"). */
+    property: string;
+    /** fjall config property the codemod writes (e.g. "port"). */
+    configProperty: string;
+    liveValue: string | number;
+    /** The exact config line for manual application (e.g. `port: 5433`). */
+    configLine: string;
+}
+export type PinReportOnlyReason = "no-probe-support" | "physical-id-unresolved" | "probe-failed" | "no-infrastructure-content" | "unresolved-construct" | "edit-failed"
+/** The codemod was a byte-identical no-op — the config already carries the
+ * probed value(s), so claiming an edit would loop the deploy forever. */
+ | "already-pinned";
+interface PinTargetIdentity {
+    stack: string;
+    logicalId: string;
+    resourceType: string;
+    physicalName: string;
+}
+export type PinResourceOutcome = (PinTargetIdentity & {
+    outcome: "edit-ready";
+    /** The construct symbol the codemod edited. */
+    constructName: string;
+    pinned: PinnedProperty[];
+}) | (PinTargetIdentity & {
+    outcome: "report-only";
+    reason: PinReportOnlyReason;
+    /** Pre-masked human detail (unsupported pairs, probe error, edit error). */
+    detail?: string;
+    /** Probed values that WERE resolved — the exact config lines the
+     * operator can apply by hand even though no edit was emitted. */
+    pinned?: PinnedProperty[];
+    /** Candidate construct names on ambiguous resolution. */
+    candidates?: string[];
+});
+export interface PinRemediationReport {
+    outcomes: PinResourceOutcome[];
+    /** The config content with EVERY edit-ready outcome applied, present iff
+     * at least one target reached edit-ready. Later targets compose on top of
+     * earlier edits. */
+    modifiedContent?: string;
+    /** The exact source snapshot the edits were composed against — present iff
+     * `modifiedContent` is. The write-back owner MUST verify the file on disk
+     * still matches this snapshot before replacing it wholesale: the consent
+     * ceremony can sit for minutes, and a whole-file write composed from a
+     * stale read silently reverts a concurrent user edit (lost update). */
+    sourceContent?: string;
+}
+export interface PinProbeCoverage {
+    /** True iff EVERY offending property has a live-value probe. */
+    covered: boolean;
+    /** The `<resourceType>#<property>` pairs without a probe (all pairs when
+     * no offending properties were recorded — nothing is probeable). */
+    unsupportedPairs: string[];
+}
+/**
+ * Whether the v1 probe table can execute a pin for this resource. The
+ * destruction gate consults this BEFORE accepting a `pin` consent — declaring
+ * the verb executable and then degrading every target to report-only
+ * (no-probe-support) would stop the deploy for a write-back that can never
+ * happen.
+ */
+export declare function pinProbeCoverage(resourceType: string, offendingProperties: readonly string[]): PinProbeCoverage;
+/**
+ * One-line detail for a pin outcome (everything after the physical name).
+ * Shared by `renderPinReportLines` and the CLI's labelled row rendering so
+ * both surfaces stay byte-identical. Identifier-only plus pre-masked details
+ * — safe for any sink.
+ */
+export declare function formatPinOutcomeDetail(outcome: PinResourceOutcome): string;
+/**
+ * Render the per-resource pin outcome lines every surface shares (engine
+ * callbacks, CLI human output, agent output).
+ */
+export declare function renderPinReportLines(report: PinRemediationReport): string[];
+export interface RunPinRemediationParams {
+    targets: readonly PinTarget[];
+    /** The user's infrastructure config source. Absent (worker surfaces with
+     * no config checkout) degrades every target to report-only with the exact
+     * config lines. */
+    infrastructureContent?: string;
+    /** Display path for codemod diagnostics. */
+    infrastructureFilePath?: string;
+    abortSignal?: AbortSignal;
+}
+/**
+ * Run the pin arm over consented targets. Never throws; every failure mode
+ * is an in-band report-only outcome (pre-masked at construction). Outcomes
+ * may be fewer than targets when the abort signal fires mid-loop.
+ */
+export declare function runPinRemediation(aws: AwsProvider, params: RunPinRemediationParams): Promise<PinRemediationReport>;
+export {};

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

@@ -0,0 +1 @@
+import{CloudFormationClient as w,DescribeStackResourceCommand as B}from"@aws-sdk/client-cloudformation";import{DescribeDBClustersCommand as O,DescribeDBInstancesCommand as T,RDSClient as R}from"@aws-sdk/client-rds";import{success as h,failure as f}from"@fjall/generator";import{listResources as L,modifyResource as A}from"@fjall/generator/codemod";import{getErrorMessage as P,maskSensitiveOutput as D}from"@fjall/util";import{logger as j}from"@fjall/util/logger";import{composeSdkAbortSignal as C,isAborted as k}from"../../aws/organisations/types.js";import{remediationPlaceholderPhysicalId as x}from"../../types/remediation.js";const F="PinRemediation",N="/properties/";async function V(e,n,o){try{const i=(await e.getClient(R).send(new T({DBInstanceIdentifier:n}),{abortSignal:C(o)})).DBInstances?.[0]?.Endpoint?.Port;return i===void 0?f(new Error(`rds:DescribeDBInstances returned no endpoint port for '${n}'`)):h(i)}catch(t){return f(new Error(D(P(t))))}}async function W(e,n,o){try{const i=(await e.getClient(R).send(new O({DBClusterIdentifier:n}),{abortSignal:C(o)})).DBClusters?.[0]?.Port;return i===void 0?f(new Error(`rds:DescribeDBClusters returned no port for '${n}'`)):h(i)}catch(t){return f(new Error(D(P(t))))}}const v={"AWS::RDS::DBInstance#Port":{configProperty:"port",constructType:"database",method:"rds:DescribeDBInstances",probe:V},"AWS::RDS::DBCluster#Port":{configProperty:"port",constructType:"database",method:"rds:DescribeDBClusters",probe:W}};function E(e){return e.startsWith(N)?e.slice(N.length):e}function Z(e,n){if(n.length===0)return{covered:!1,unsupportedPairs:[`${e} (no offending properties recorded)`]};const o=n.map(E).filter(t=>v[`${e}#${t}`]===void 0).map(t=>`${e}#${t}`);return{covered:o.length===0,unsupportedPairs:o}}function _(e){return typeof e=="number"?String(e):JSON.stringify(e)}async function G(e,n,o){const t=x(n.stack,n.logicalId);if(n.physicalName!==t)return h(n.physicalName);try{const s=(await e.getClient(w).send(new B({StackName:n.stack,LogicalResourceId:n.logicalId}),{abortSignal:C(o)})).StackResourceDetail?.PhysicalResourceId;return s===void 0||s===""?f(new Error(`cfn:DescribeStackResource resolved no physical id for ${n.stack}/${n.logicalId}`)):h(s)}catch(r){return f(new Error(D(P(r))))}}function H(e,n,o){const t=L(e,n);if(!t.success)return{detail:`config parse failed: ${t.error.kind}`};const r=t.data.resources.filter(i=>i.type===o);return r.length===1&&r[0]!==void 0?{constructName:r[0].name}:r.length===0?{detail:`no ${o} construct found in the config`}:{candidates:r.map(i=>i.name),detail:`${r.length} ${o} constructs found \u2014 cannot pin unambiguously`}}function J(e){if(e.outcome==="edit-ready")return`pinned ${e.pinned.map(r=>r.configLine).join(", ")} on construct '${e.constructName}' \u2014 edit ready`;const n=e.detail!==void 0?` \u2014 ${e.detail}`:"",o=e.candidates!==void 0&&e.candidates.length>0?`; candidate constructs: ${e.candidates.join(", ")}`:"",t=e.reason!=="already-pinned"&&e.pinned!==void 0&&e.pinned.length>0?`; apply by hand: ${e.pinned.map(r=>r.configLine).join(", ")}`:"";return`report-only (${e.reason})${n}${o}${t}`}function ee(e){return e.outcomes.map(n=>`${n.physicalName}: ${J(n)}`)}async function ne(e,n){const o=n.infrastructureFilePath??"infrastructure.ts",t=[];let r=n.infrastructureContent,i=!1;for(const s of n.targets){if(k(n.abortSignal)){j.debug(F,"Aborted mid-loop \u2014 remaining targets not probed",{remaining:n.targets.length-t.length});break}const d={stack:s.stack,logicalId:s.logicalId,resourceType:s.resourceType,physicalName:s.physicalName},g=s.offendingProperties.map(E).map(c=>({property:c,spec:v[`${s.resourceType}#${c}`]})),b=g.filter(c=>c.spec!==void 0);if(g.length===0||b.length<g.length){const c=g.filter(u=>u.spec===void 0),p=g.length===0?`${s.resourceType} (no offending properties recorded)`:c.map(u=>`${s.resourceType}#${u.property}`).join(", ");t.push({...d,outcome:"report-only",reason:"no-probe-support",detail:`no live-value probe for ${p} in this release`});continue}const $=await G(e,s,n.abortSignal);if(!$.success){t.push({...d,outcome:"report-only",reason:"physical-id-unresolved",detail:$.error.message});continue}const a=[];let m;for(const{property:c,spec:p}of b){if(k(n.abortSignal)){m="aborted before probing completed";break}const u=await p.probe(e,$.data,n.abortSignal);if(!u.success){m=`${p.method}: ${u.error.message}`;break}a.push({property:c,configProperty:p.configProperty,liveValue:u.data,configLine:`${p.configProperty}: ${_(u.data)}`})}if(m!==void 0){t.push({...d,outcome:"report-only",reason:"probe-failed",detail:m,...a.length>0?{pinned:a}:{}});continue}if(r===void 0){t.push({...d,outcome:"report-only",reason:"no-infrastructure-content",detail:"no infrastructure config available on this surface \u2014 apply the config line(s) by hand",pinned:a});continue}const S=b[0]?.spec.constructType??"database",l=H(r,o,S);if(l.constructName===void 0){t.push({...d,outcome:"report-only",reason:"unresolved-construct",...l.detail!==void 0?{detail:l.detail}:{},...l.candidates!==void 0?{candidates:l.candidates}:{},pinned:a});continue}const I={};for(const c of a)I[c.configProperty]=c.liveValue;const y=A(r,{type:S,name:l.constructName,properties:I,filePath:o});if(!y.success){t.push({...d,outcome:"report-only",reason:"edit-failed",detail:`codemod failed: ${y.error.kind}`,pinned:a});continue}if(y.data.content===r){t.push({...d,outcome:"report-only",reason:"already-pinned",detail:"the config already contains the probed value(s) \u2014 no edit needed; if the deploy still plans a replacement, the drift lies outside these properties",pinned:a});continue}r=y.data.content,i=!0,t.push({...d,outcome:"edit-ready",constructName:l.constructName,pinned:a})}return{outcomes:t,...i&&r!==void 0&&n.infrastructureContent!==void 0?{modifiedContent:r,sourceContent:n.infrastructureContent}:{}}}export{J as formatPinOutcomeDetail,Z as pinProbeCoverage,ee as renderPinReportLines,ne as runPinRemediation};

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};