@fjall/deploy-core 2.27.0 → 2.30.0

package/dist/src/types/params.d.ts

@@ -6,7 +6,9 @@ import type { ApiClientInterface } from "./apiClient.js";
 import type { OrgConfig } from "./config/orgConfig.js";
 import type { DockerProvider } from "../orchestration/dockerInterface.js";
 import type { DomainDeployProvider } from "../orchestration/domainInterface.js";
+import type { PinRemediationReport } from "../orchestration/remediation/pinRemediation.js";
 import type { ApprovalGate, ApprovalGatePlanDetail } from "./approval.js";
+import type { DestructionConsent, DestructionConsentGate, DestructionOutcome, DestructionTicket } from "./destruction.js";
 import type { FailureAnalysis } from "@fjall/util/aws";
 import type { DockerBuildSecretRef } from "@fjall/util/manifest/schemas";
 export interface DeployParams {
@@ -76,6 +78,26 @@ export interface DeployParams {
      * the gate even when this is omitted.
      */
     approvalGate?: ApprovalGate;
+    /**
+     * Optional interactive destruction-consent resolver — the ceremony seam for
+     * the UNCONDITIONAL destruction gate (mirrors `approvalGate`'s injected-
+     * resolver mechanism). Consulted ONLY when the gate ticketed destructive
+     * rows and no `options.destructionConsents` were supplied; the returned
+     * pairs are re-evaluated engine-side (exact-match + digest TOCTOU), so the
+     * resolver can never widen consent beyond what the `--remediate` flags
+     * could. Omitted ⇒ the gate withholds fail-closed exactly as before. No
+     * flag can disengage the gate; this only changes HOW consent is obtained.
+     */
+    destructionConsentGate?: DestructionConsentGate;
+    /**
+     * The user's fjall infrastructure config source, consumed by the pin arm
+     * when a destructive change is consented with `pin`: the engine composes an
+     * edit-ready codemod against it and returns the result for surface-side
+     * write-back — the engine never writes the file. Absent (worker surfaces
+     * with no config checkout) the pin arm degrades to report-only outcomes
+     * carrying the exact config lines.
+     */
+    infrastructureSource?: InfrastructureSource;
     /**
      * Asked before the post-deploy database-endpoint reconcile restarts the
      * application's ECS services (fires only when a deploy replaced the
@@ -85,6 +107,34 @@ export interface DeployParams {
      * non-interactive CLI) must not block on consent.
      */
     confirmDatabaseEndpointRestart?: (request: DatabaseEndpointRestartRequest) => Promise<boolean>;
+    /**
+     * Optional stack-boundary lease gate (§5.3). Invoked immediately before each
+     * stack's first mutating CloudFormation operation. The engine passes the
+     * stack name and the caller's shutdown signal; the resolver returns the lease
+     * verdict:
+     *   - "denied"  ⇒ the deployment's lease is gone (swept, superseded, adopted
+     *     by another runner, or force-released). The engine aborts BEFORE
+     *     starting that stack with a typed `LeaseDeniedError`; already-completed
+     *     stacks stand.
+     *   - "unknown" ⇒ the liveness probe could not reach the server. Fail OPEN
+     *     and proceed — leases are a liveness signal, not a safety gate, and
+     *     CloudFormation's own ClientRequestToken is the fencing backstop.
+     *   - "ok"      ⇒ proceed.
+     * Omitted ⇒ no gate (fully backward-compatible). The CLI wires this to the
+     * DeploymentTracker's on-demand heartbeat; the worker omits it.
+     */
+    assertLeaseForStack?: (stackName: string, abortSignal?: AbortSignal) => Promise<StackLeaseVerdict>;
+}
+/** Verdict of the stack-boundary lease gate (§5.3 heartbeat protocol). */
+export type StackLeaseVerdict = "ok" | "denied" | "unknown";
+/**
+ * The infrastructure config source handed to the pin arm — the surface that
+ * owns the config checkout supplies both halves so codemod diagnostics and
+ * the eventual write-back target the same file.
+ */
+export interface InfrastructureSource {
+    content: string;
+    filePath: string;
 }
 /**
  * Context handed to `confirmDatabaseEndpointRestart` so an interactive
@@ -182,6 +232,22 @@ export interface DeployOptions {
      * validated through `DockerBuildSecretRefSchema` (CLI) before it reaches here.
      */
     flagBuildSecrets?: readonly DockerBuildSecretRef[];
+    /**
+     * Destruction-gate consents: exact, case-sensitive `{physicalName, verb}`
+     * pairs from the repeatable `--remediate <name>=<verb>` / `--allow-replace
+     * <name>` flags (or a surface's pre-authorisation). The unconditional gate
+     * fail-closes unless EVERY ticketed resource is covered; surplus, misspelt
+     * or wrong-verb consents fail closed with a verdict table. `autoApprove`,
+     * `skipConfirmation`, `force` and approval tokens never satisfy the gate.
+     */
+    destructionConsents?: readonly DestructionConsent[];
+    /**
+     * The `ticketDigest` the consents were minted against (webapp pre-auth /
+     * resumed runs). Re-verified against the digest recomputed at apply time;
+     * a mismatch fail-closes every consent (TOCTOU discipline). Flag-minted
+     * consents omit it — they are supplied at apply time by definition.
+     */
+    destructionConsentDigest?: string;
 }
 export type DeploymentType = "application" | "organisation";
 export interface DeployResult {
@@ -265,6 +331,73 @@ export interface DeployResult {
      * resume token never computed one).
      */
     planDetail?: ApprovalGatePlanDetail;
+    /**
+     * Destruction-gate: set when the unconditional gate withheld the deploy —
+     * the plan contained destructive rows without full named consent (or a
+     * consented verb has no execution arm yet). Nothing was mutated. Surfaces
+     * map this to exit code 4 (distinct from rejection/failure).
+     */
+    destructionPending?: boolean;
+    /**
+     * Destruction-gate: the ticket enumerating every destructive resource, its
+     * finding, cause and legal verbs. Present with `destructionPending`, and on
+     * an `awaitingApproval` plan-only result whose plan carries destructive
+     * rows (so a plan consumer can mint consents against `ticketDigest`).
+     */
+    destructionTicket?: DestructionTicket;
+    /**
+     * Destruction-gate: WHY the deploy was withheld. Present with
+     * `destructionPending`. Surfaces branch on this so a user who consented
+     * (`consent-not-executable`) or declined (`declined`) is never shown the
+     * generic "requires named consent" message or told to redo their consent.
+     */
+    destructionOutcome?: DestructionOutcome;
+    /**
+     * Destruction-gate: the halt/decline reason lines (identifier-only,
+     * pre-masked by construction) — e.g. "verb 'repair' is accepted vocabulary
+     * but not yet executable in this release for resource-deleted". Present
+     * with `destructionPending`; may be empty.
+     */
+    destructionHaltReasons?: string[];
+    /**
+     * Destruction-gate: a fresh approval token re-minted at withhold time for
+     * approval-gated runs, bound to the withheld run's assembly digest with the
+     * consent-ceremony TTL (`DESTRUCTION_RESUME_TTL_MS`). The original approval
+     * token's 15-minute TTL expires during a ceremony that can take hours; the
+     * consented re-queue MUST carry this token instead. Present with
+     * `destructionPending` only when the run was approval-gated. NOT a secret —
+     * digest-bound capability, same trust model as `approvalToken`.
+     */
+    destructionResumeToken?: string;
+    /**
+     * Destruction-gate: ISO expiry of `destructionResumeToken`. Present
+     * together with it.
+     */
+    destructionResumeExpiresAt?: string;
+    /**
+     * Pin arm: set when consented `pin` verb(s) ran the pre-bootstrap
+     * live-value probes and the deploy stopped for config write-back. Nothing
+     * was mutated — CloudFormation never ran. Surfaces render `pinReport` and
+     * re-run the deploy once the config change lands (the plan then carries no
+     * pinned rows). Distinct from `destructionPending` (consent withheld) —
+     * pin consent was GIVEN and its arm executed.
+     */
+    pinPending?: boolean;
+    /**
+     * Pin arm: per-resource outcomes, plus the composed `modifiedContent` when
+     * at least one target reached edit-ready. Present with `pinPending`. The
+     * surface that supplied `DeployParams.infrastructureSource` owns writing
+     * `modifiedContent` back to the config file.
+     */
+    pinReport?: PinRemediationReport;
+    /**
+     * Pin arm: count of consented NON-pin change(s) (e.g. recreate rows) the
+     * pin stop deferred — they did not run in this deploy and re-consent
+     * against the recomputed plan on the next one. Present with `pinPending`;
+     * 0 when the consent set was pure-pin. Surfaces MUST NOT claim "no
+     * --remediate needed" on the re-run when this is non-zero.
+     */
+    pinDeferredConsents?: number;
 }
 /**
  * Parameters for the destroy entry point.
@@ -302,6 +435,15 @@ export interface DestroyParams {
      * (mirrors DeployParams.abortSignal).
      */
     abortSignal?: AbortSignal;
+    /**
+     * Optional stack-boundary lease gate (§5.3) — the destroy twin of
+     * `DeployParams.assertLeaseForStack`, same resolver and verdict semantics:
+     * "denied" aborts BEFORE the stack's DeleteStack (already-destroyed stacks
+     * stand), "unknown" fails open, absent ⇒ no gate. Consulted immediately
+     * before each stack's DeleteStack; a parallel destroy group gates once on
+     * entry.
+     */
+    assertLeaseForStack?: DeployParams["assertLeaseForStack"];
 }
 export interface DestroyOptions {
     /** Skip interactive confirmation prompts */

package/dist/src/types/remediation.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The remediation-journal contract for the two-deploy `forget` orchestration
+ * and its snapshot-flip `recreate` variant (drift-remediation plan § 3.2 /
+ * Phase 7). Declared ONCE here; the CLI re-exports, never redeclares (coupled
+ * discriminated unions share a source at 2 occurrences).
+ *
+ * Phases are strictly ordered: `captured → flip-verified → flip-applied →
+ * removal-applied → done`. Every phase re-derives its precondition from live
+ * state before acting, so a lost journal degrades to correct re-detection via
+ * the in-template `fjall:forget` / `fjall:recreate` marker [G3] — the journal
+ * is the local resume record and audit trail, not the sole authority.
+ * Exception: targets advanced via the FLIPLESS fast-path (`fliplessTargets` —
+ * live policies already satisfied the flip spec, so no UpdateStack ran and no
+ * marker was stamped; 2026-07-12 live defect #5) and via the
+ * FLIPLESS-BY-NECESSITY path (`fliplessByNecessity` — the flip was
+ * structurally impossible and the target verified physically deleted; same
+ * incident, second direction) carry no AWS-side resume state — their
+ * lost-journal degradation is re-consent at the ceremony, never a silent
+ * skip.
+ */
+import { z } from "zod";
+export declare const REMEDIATION_PHASES: readonly ["captured", "flip-verified", "flip-applied", "removal-applied", "done"];
+export declare const RemediationPhaseSchema: z.ZodEnum<{
+    captured: "captured";
+    "flip-verified": "flip-verified";
+    "flip-applied": "flip-applied";
+    "removal-applied": "removal-applied";
+    done: "done";
+}>;
+export type RemediationPhase = z.infer<typeof RemediationPhaseSchema>;
+/** Ordinal comparison for phase progression checks. */
+export declare function remediationPhaseRank(phase: RemediationPhase): number;
+export declare const RemediationTargetSchema: z.ZodObject<{
+    logicalId: z.ZodString;
+    resourceType: z.ZodString;
+    physicalId: z.ZodString;
+}, z.core.$strict>;
+export type RemediationTarget = z.infer<typeof RemediationTargetSchema>;
+/**
+ * Placeholder physicalId for a target whose live physical id is unknown —
+ * an adopted foreign-op target recovered from the `fjall:forget` marker, or
+ * a confirmed finding whose membership listing could not resolve an id. The
+ * shape is structurally recognisable so probe paths can refuse to treat it
+ * as an owning-service address: probing `MyStack/MyKey` against
+ * kms:DescribeKey returns an authoritative NotFound for a resource that may
+ * be live. Coupled values, one home — every minting site routes through this
+ * builder: the CLI's journal targets, the drift-repair ticket's [G6]
+ * `physicalName` fallback (which must byte-agree with those targets so the
+ * consent covers what is operated on), and the deploy destruction ticket's
+ * unpinned-name fallback (the same resource renders on both tickets in the
+ * blocked-deploy → repair flow); deploy-core's closure probe recognises the
+ * shape via the predicate below.
+ */
+export declare function remediationPlaceholderPhysicalId(stackName: string, logicalId: string): string;
+/**
+ * True when the target's physicalId is the placeholder minted by
+ * `remediationPlaceholderPhysicalId` — never a probeable address.
+ */
+export declare function isRemediationPlaceholderPhysicalId(target: RemediationTarget, stackName: string): boolean;
+/** Proof record that the retain flip was verified metadata-only (§3.2 ph 2). */
+export declare const RemediationFlipProofSchema: z.ZodObject<{
+    diffGuardPassed: z.ZodBoolean;
+    changeSetMetadataOnly: z.ZodBoolean;
+    noChanges: z.ZodBoolean;
+    provenAt: z.ZodString;
+}, z.core.$strict>;
+export type RemediationFlipProof = z.infer<typeof RemediationFlipProofSchema>;
+/**
+ * The verbs with an orchestrated surgery arm. `forget` retains-and-abandons
+ * (converge removes the declaration); `recreate` snapshot-flips and surgically
+ * removes so the converge re-CREATEs under the same pinned name. The opId
+ * derivation deliberately excludes the verb — both orchestrators verb-guard
+ * the journal they read, failing closed on a cross-verb collision.
+ */
+export declare const RemediationVerbWithSurgerySchema: z.ZodEnum<{
+    forget: "forget";
+    recreate: "recreate";
+}>;
+export type RemediationVerbWithSurgery = z.infer<typeof RemediationVerbWithSurgerySchema>;
+export declare const RemediationJournalRecordSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    opId: z.ZodString;
+    verb: z.ZodEnum<{
+        forget: "forget";
+        recreate: "recreate";
+    }>;
+    accountId: z.ZodString;
+    region: z.ZodString;
+    stackName: z.ZodString;
+    appName: z.ZodOptional<z.ZodString>;
+    targets: z.ZodArray<z.ZodObject<{
+        logicalId: z.ZodString;
+        resourceType: z.ZodString;
+        physicalId: z.ZodString;
+    }, z.core.$strict>>;
+    phase: z.ZodEnum<{
+        captured: "captured";
+        "flip-verified": "flip-verified";
+        "flip-applied": "flip-applied";
+        "removal-applied": "removal-applied";
+        done: "done";
+    }>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    liveTemplateDigest: z.ZodOptional<z.ZodString>;
+    forensicsPath: z.ZodOptional<z.ZodString>;
+    proof: z.ZodOptional<z.ZodObject<{
+        diffGuardPassed: z.ZodBoolean;
+        changeSetMetadataOnly: z.ZodBoolean;
+        noChanges: z.ZodBoolean;
+        provenAt: z.ZodString;
+    }, z.core.$strict>>;
+    consentedPhysicalNames: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    retainedByRedeclaration: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    fliplessTargets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    fliplessByNecessity: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    recreatedResources: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    snapshotPolicies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+        Snapshot: "Snapshot";
+        Delete: "Delete";
+    }>>>;
+    orphanedResources: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    unverifiedRemovals: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    completedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type RemediationJournalRecord = z.infer<typeof RemediationJournalRecordSchema>;

package/dist/src/types/remediation.js

@@ -0,0 +1 @@
+import{z as e}from"zod";const t=["captured","flip-verified","flip-applied","removal-applied","done"],r=e.enum(t);function p(i){return t.indexOf(i)}const o=e.object({logicalId:e.string().min(1),resourceType:e.string().min(1),physicalId:e.string().min(1)}).strict();function a(i,n){return`${i}/${n}`}function m(i,n){return i.physicalId===a(n,i.logicalId)}const s=e.object({diffGuardPassed:e.boolean(),changeSetMetadataOnly:e.boolean(),noChanges:e.boolean(),provenAt:e.string().min(1)}).strict(),l=e.enum(["forget","recreate"]),d=e.object({version:e.literal(1),opId:e.string().min(1),verb:l,accountId:e.string().min(1),region:e.string().min(1),stackName:e.string().min(1),appName:e.string().min(1).optional(),targets:e.array(o).min(1),phase:r,createdAt:e.string().min(1),updatedAt:e.string().min(1),liveTemplateDigest:e.string().min(1).optional(),forensicsPath:e.string().min(1).optional(),proof:s.optional(),consentedPhysicalNames:e.array(e.string()).optional(),retainedByRedeclaration:e.array(e.string().min(1)).optional(),fliplessTargets:e.array(e.string().min(1)).optional(),fliplessByNecessity:e.array(e.string().min(1)).optional(),recreatedResources:e.array(e.string().min(1)).optional(),snapshotPolicies:e.record(e.string().min(1),e.enum(["Snapshot","Delete"])).optional(),orphanedResources:e.array(e.string().min(1)).optional(),unverifiedRemovals:e.array(e.string().min(1)).optional(),completedAt:e.string().min(1).optional()}).strict();export{t as REMEDIATION_PHASES,s as RemediationFlipProofSchema,d as RemediationJournalRecordSchema,r as RemediationPhaseSchema,o as RemediationTargetSchema,l as RemediationVerbWithSurgerySchema,m as isRemediationPlaceholderPhysicalId,p as remediationPhaseRank,a as remediationPlaceholderPhysicalId};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/deploy-core",
-  "version": "2.27.0",
+  "version": "2.30.0",
   "description": "Shared deployment engine for Fjall — used by CLI and webapp worker",
   "type": "module",
   "main": "dist/src/index.js",
@@ -48,6 +48,7 @@
   "scripts": {
     "clean": "rm -rf ./dist ./sourcemaps",
     "build": "npm run clean && tsc && node ../scripts/minify-dist.mjs dist",
+    "prepack": "node ../scripts/check-dist-freshness.mjs",
     "watch": "npm run build && tsc --watch --preserveWatchOutput",
     "watch:only": "tsc --watch --preserveWatchOutput",
     "typecheck": "tsc --noEmit",
@@ -76,14 +77,15 @@
     "@aws-sdk/client-kms": "^3.1065.0",
     "@aws-sdk/client-organizations": "^3.1038.0",
     "@aws-sdk/client-ram": "^3.1038.0",
+    "@aws-sdk/client-rds": "^3.1038.0",
     "@aws-sdk/client-s3": "^3.1038.0",
     "@aws-sdk/client-secrets-manager": "^3.1038.0",
     "@aws-sdk/client-sqs": "^3.1067.0",
     "@aws-sdk/client-ssm": "^3.1038.0",
     "@aws-sdk/client-sso-admin": "^3.1038.0",
     "@aws-sdk/client-sts": "^3.1038.0",
-    "@fjall/generator": "^2.27.0",
-    "@fjall/util": "^2.27.0",
+    "@fjall/generator": "^2.30.0",
+    "@fjall/util": "^2.30.0",
     "@smithy/node-http-handler": "^4.6.1",
     "aws-cdk": "^2.1128.1",
     "tsx": "^4.21.0",
@@ -94,5 +96,5 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.5"
   },
-  "gitHead": "921ecd4f65f52c17037a8a24834d7e4c196b9347"
+  "gitHead": "ec35b16db566dfa5feb714c16f132c55b4663c86"
 }