@patronage/factory-ci 1.0.0-alpha.16 → 1.0.0-alpha.18

package/README.md

@@ -197,6 +197,65 @@ Trust boundary: candidate routing is a cost control inside the pull request's ow
 
 The step calls `psf candidate:impact` with the pull request's exact `base` and `head` commits (`github.event.pull_request.base.sha` / `head.sha` by default) and classifies the merge-base-to-head delta. It is `continue-on-error`, and every generated target condition keeps work demanded unless the command succeeded, reported a usable decision, and explicitly withdrew that target — unreadable identity, malformed or unsupported graph data, and classifier refusal all route to full demand. The decision checkout must check out the exact head commit with full history (`fetchDepth: 0`, `ref` = the head SHA); the default merge-ref checkout refuses withdrawal because the head is not `HEAD`. Surface job names, runners, commands, and credentials stay with the consumer, and `factoryProductionImpactWorkflow` keeps its merge-push contract unchanged.
 
+The non-credentialed lifecycle-contract lane follows the same ownership line through `factoryLifecycleContractLane` (#765). Presence is a profile declaration (`lifecycleContract` in `software-factory.profile.json`); this package never loads the profile. Pass the parsed object, or omit it, and include or skip the returned job:
+
+```ts
+const lane = factoryLifecycleContractLane(profile.lifecycleContract);
+
+const jobs = [
+  core,
+  ...(lane
+    ? [
+        job(lane.jobId, {
+          name: lane.jobName,
+          permissions: { contents: "read" },
+          steps: [...setupSteps, ...lane.steps],
+        }),
+      ]
+    : []),
+];
+```
+
+When declared, the helper returns job id `factory-contracts`, display name `Factory / Alchemy Contracts` (overridable), a `run:` step that is exactly the declared package-script command, and an `always()` evidence summary that states what the lane proves and that it does not prove live deploy, D1, smoke, convergence, or cleanup. When omitted, the helper returns `undefined` and the caller emits no such job.
+
+**Command contract.** Consumers expose a root package script and declare its invocation in the profile. The conventional name is `test:factory`:
+
+```json
+{
+  "lifecycleContract": {
+    "command": "pnpm test:factory"
+  }
+}
+```
+
+Hosted CI runs that package script only. The allowed grammar is `pnpm run <script>` (and the npm/yarn/bun `run` equivalents) or a shorthand whose script name contains `:` (`pnpm test:factory`). Optional pnpm `--filter <pkg>` may precede either form. A bare manager verb (`pnpm create`, `npm init`) is not a script invocation. Shell operators, GitHub expressions, `secrets.`, Cloudflare/Alchemy credential env, extra flags, and direct Vitest are refused. The generated job and steps carry no `secrets.`, no Cloudflare or Alchemy password env, and no GitHub `environment:` that would inject deploy credentials. The lane must stay green in fork and no-secret contexts. Setup, runners, job `if:` conditions, and topology stay with the caller. The contract suites themselves stay consumer-owned.
+
+The preview-cleanup residue audit follows the same ownership line through `factoryPreviewCleanupTopology` (#764). Callers pass the stack names and the whole-stage audit command; this package never loads a profile and never decides what counts as residue. Destroy _steps_ stay consumer-owned. The helper returns one destroy job id per stack and exactly one audit job whose `needs` lists every destroy:
+
+```ts
+const topology = factoryPreviewCleanupTopology({
+  stacks: ["website", "loop"],
+  audit: { command: "assert-stage-absent" },
+});
+
+const jobs = [
+  ...topology.destroyJobs.map((destroy) =>
+    job(destroy.jobId, {
+      name: `Destroy ${destroy.stack}`,
+      steps: [...setupSteps, consumerDestroy(destroy.stack)],
+    })
+  ),
+  job(topology.auditJob.jobId, {
+    name: topology.auditJob.jobName,
+    if: topology.auditJob.if,
+    needs: topology.auditJob.needs,
+    steps: [...setupSteps, ...topology.auditJob.steps],
+  }),
+];
+```
+
+The audit job is `always()` so a failed destroy still runs the stage-wide check. It does not receive a stack name or path filter — per-stack audit filters are rejected because they trade away the whole-stage guarantee (paitronage#1143). `previewCleanupDestroyJobId(stack)` is the same id mapping callers can use when they assemble destroy jobs by hand.
+
 ### Generated shell
 
 ```ts
@@ -282,7 +341,7 @@ import { bundleAlchemyEntry, executeAlchemyEntry } from "@patronage/factory-ci";
 
 `alias` is a specifier-to-target map handed to esbuild. Substitution runs before the `packages` and `external` decisions, so an aliased bare specifier is inlined even under `packages: "external"` — that is how a repo points a workspace-only or duplicated package at one file. Give absolute paths or package names; which aliases a repo needs is consumer policy and this package ships no defaults. `executeAlchemyEntry` passes its whole `bundle` option through, so the map is available there too. Because substitution runs first, an alias on `alchemy`, `effect`, or any of their subpaths would silently defeat the externals and bundle a second copy, so those keys are rejected outright. Targets are not string-matched — no rule over how a path is spelled can survive `..` segments or symlinks — so instead the build's metafile is checked afterwards and the bundle is rejected if it carries any input from a reserved package, however that file was reached. A consumer shim that re-exports `effect` by bare specifier stays external naturally and is allowed.
 
-`executeAlchemyEntry({ from, bundle, args, ... })` owns the repeated choreography: resolve the consumer's Alchemy CLI from `from`, bundle the entry, run that CLI under the current Node binary with the absolute bundled entry appended, and throw on spawn errors, signals, missing statuses, or non-zero exits. It returns only after status 0.
+`executeAlchemyEntry({ from, bundle, args, ... })` owns the repeated choreography: resolve the consumer's Alchemy CLI from `from`, bundle the entry, run that CLI under the current Node binary with the absolute bundled entry appended, and throw on spawn errors, signals, missing statuses, or non-zero exits. It returns only after status 0. Pass `bundledEntry` (absolute or cwd-relative) to skip the bundle step and reuse a path from a prior `bundleAlchemyEntry` call; `bundle` is then optional. Captured output (`stdio: "pipe"`) honors `maxBuffer` only when the caller supplies it (Node's `spawnSync` default is 1 MiB; pass `EXECUTE_ALCHEMY_ENTRY_MAX_BUFFER` for 64 MiB) and, when supplied, a `redact: (text: string) => string` hook applied to stdout and stderr before they are returned. Default `stdio: "inherit"` still streams the child unredacted. This package does not own a secret-name policy.
 
 The caller still owns deploy/destroy/plan arguments, stage admission, credentials, environment shaping, destructive-plan guards, and convergence. Failure messages never repeat arguments or environment values.
 
@@ -298,6 +357,46 @@ import {
 
 `local-pr-<pr>-<short sha>` construction and interpretation live behind one private grammar. `localPreviewStage({ pr, headSha, shaLength? })` accepts a positive PR, a full 40-character SHA, and a 7–40-character slice length (default 12). `parseLocalPreviewStage(stage, expected?)` returns the PR and SHA prefix, optionally proving ownership against a PR and full head SHA. `isLocalPreviewStage(stage, pr?)` is the boolean type guard. The raw regex is not public.
 
+### Preview-proof lifecycle
+
+```ts
+import { previewProofLifecycle } from "@patronage/factory-ci";
+```
+
+`previewProofLifecycle` owns the commodity preview-proof state machine that two consumers had each written: admit a disposable stage, register envelope-bound proof at the candidate head, and record cleanup. `transition(state, event)` is the only mutation. `recover(state, cleanupEvent)` re-enters that same cleanup event from a failed outcome; it is not a second machine and not a CLI command. `resolve(state, query?)` is the consumer-readable registration read model: stack, stage, head SHA, proof identity, and cleanup status.
+
+Events:
+
+- `begin` — the pre-deploy gate. Refuses a draft, a closed PR, a dirty or mismatched worktree, and any stage the disposable grammar does not own for this PR head. Does not create a registration.
+- `register` — the same identity gate, plus passed smoke, passed convergence, and a passing three-way-bound evidence envelope at this head. Writes a registration with `cleanupStatus: "pending"`. Machine evidence is that envelope; this module never posts a PR comment.
+- `cleanup` — records an explicit passed or failed outcome onto an existing registration. Cleanup is never inferred from whether the stage still exists. `recover` is the failed-to-resolved re-entry of this event.
+
+Proof runs entirely on one side of GitHub's draft/ready boundary: both `begin` and `register` refuse `isDraft: true`. Undraft first, then prove. Callers still own deploy, destroy, credentials, smoke probes, envelope emission, and stack names.
+
+### Preview-proof inventory
+
+```ts
+import { previewProofInventory } from "@patronage/factory-ci";
+
+const store = previewProofInventory.githubStore({
+  fetch,
+  token: process.env.GITHUB_TOKEN,
+});
+const rows = await previewProofInventory.list({ owner, repo, pr }, { store });
+```
+
+`previewProofInventory` is the hosted read and write API on that registration read model. A consumer workflow enumerates registered preview deployments for a PR (stack, stage, head SHA, proof identity, cleanup status) and records a cleanup outcome against a registration so the proof record reflects closure.
+
+Registration is a consumer-readable read model. Cleanup outcomes are recorded by this API; they are never inferred from whether a Cloudflare or Alchemy stage still exists. Physical stage listing is a different artifact.
+
+Persistence is an injectable GitHub transport in the same style as `mintInstallationToken`: the caller passes `fetch` and a token. This package does not read operator config or hold secrets. Records bind to the Patronage Factory GitHub App (`FACTORY_PROOF_GATE_APP_ID`) and the disposable-stage grammar. Check-runs named `patronage-factory/preview-proof` (`PREVIEW_PROOF_INVENTORY_CHECK_NAME`) carry the registration JSON. This API does not POST or PATCH issue comments.
+
+`list({ owner, repo, pr }, { token })` works with a workflow `GITHUB_TOKEN` (read). `persist` and `recordCleanup` write App-owned check-runs, which GitHub only allows the producing App to update. Pass an installation token the caller minted (`mintInstallationToken`); a job `GITHUB_TOKEN` cannot write those records. There is no `psf` command for this surface.
+
+`recordCleanup` loads the PR's registrations, applies `previewProofLifecycle.transition(..., { type: "cleanup" })`, then persists. Failed then passed uses that same event; in-memory re-entry from a failed outcome is `previewProofLifecycle.recover`, which calls that transition. Unknown stack or stage, and an identity mismatch on the disposable stage or head SHA, fail closed. Check-runs from another App, including `github-actions`, are ignored.
+
+Pass `{ store }` to substitute the GitHub adapter. `previewProofInventory.memoryStore()` is an in-memory `list`/`put` port for tests. `githubStore({ token, fetch, timeoutMs? })` is the GitHub-backed implementation. Stack names stay caller strings.
+
 ### GitHub App installation tokens
 
 ```ts

package/dist/index.d.ts

@@ -161,6 +161,195 @@ interface LocalPreviewStageOptions {
  */
 declare const localPreviewStage: (options: LocalPreviewStageOptions) => LocalPreviewStage;
 //#endregion
+//#region src/preview-proof-lifecycle.d.ts
+/**
+ * Preview-proof lifecycle: admit a disposable preview, register envelope-bound
+ * proof at head, and record cleanup. One `transition` path owns those state
+ * changes. Recovery (#766) re-enters cleanup through the same event. Hosted
+ * inventory listing and cleanup-outcome persistence live in
+ * `previewProofInventory`, which sits on the registration read model `resolve`
+ * already returns.
+ *
+ * Proof sits entirely on one side of GitHub's draft/ready boundary
+ * (paitronage#1089): a draft candidate cannot begin or register. Machine
+ * evidence is the envelope at head (#355), never a PR comment.
+ */
+type PreviewProofCleanupStatus = "failed" | "passed" | "pending";
+interface PreviewProofCandidate {
+  readonly branch: string;
+  readonly dirty: boolean;
+  readonly headSha: string;
+  readonly isDraft: boolean;
+  readonly pr: number;
+  readonly prHeadRef: string;
+  readonly prHeadSha: string;
+  readonly prRepository: string;
+  readonly prState: "CLOSED" | "MERGED" | "OPEN";
+  readonly repository: string;
+}
+interface PreviewProofEnvelopeEvidence {
+  readonly check: string;
+  readonly headSha: string;
+  readonly mergeBaseSha: string;
+  readonly outcome: "fail" | "pass";
+  readonly patchId: string;
+}
+interface PreviewProofCleanupOutcome {
+  readonly evidence: readonly string[];
+  readonly outcome: Exclude<PreviewProofCleanupStatus, "pending">;
+  readonly runUrl?: string;
+}
+interface PreviewProofRegistration {
+  readonly cleanup: {
+    readonly evidence: readonly string[];
+    readonly outcome: PreviewProofCleanupStatus;
+    readonly runUrl?: string;
+  };
+  readonly cleanupStatus: PreviewProofCleanupStatus;
+  readonly convergence: {
+    readonly detail: string;
+    readonly status: "passed";
+  };
+  readonly convergenceStatus: "passed";
+  readonly headSha: string;
+  readonly pr: number;
+  readonly proof: {
+    readonly check: string;
+    readonly headSha: string;
+    readonly mergeBaseSha: string;
+    readonly patchId: string;
+  };
+  readonly smoke: {
+    readonly detail: string;
+    readonly outcome: "passed";
+  };
+  readonly smokeStatus: "passed";
+  readonly source: "local-self-certified";
+  readonly stack: string;
+  readonly stage: LocalPreviewStage;
+  readonly url: string;
+}
+interface PreviewProofLifecycleState {
+  readonly registrations: readonly PreviewProofRegistration[];
+}
+type PreviewProofLifecycleEvent = {
+  readonly candidate: PreviewProofCandidate;
+  readonly stage: string;
+  readonly type: "begin";
+} | {
+  readonly candidate: PreviewProofCandidate;
+  readonly convergence: {
+    readonly detail: string;
+    readonly status: "failed" | "passed";
+  };
+  readonly evidence: PreviewProofEnvelopeEvidence;
+  readonly smoke: {
+    readonly detail: string;
+    readonly outcome: "failed" | "passed";
+  };
+  readonly stack: string;
+  readonly stage: string;
+  readonly type: "register";
+  readonly url: string;
+} | {
+  readonly evidence: readonly string[];
+  readonly outcome: Exclude<PreviewProofCleanupStatus, "pending">;
+  readonly pr: number;
+  readonly runUrl?: string;
+  readonly stack: string;
+  readonly stage: string;
+  readonly type: "cleanup";
+};
+interface PreviewProofResolveQuery {
+  readonly pr?: number;
+  readonly stack?: string;
+  readonly stage?: string;
+}
+declare const previewProofLifecycle: {
+  readonly empty: () => PreviewProofLifecycleState;
+  readonly recover: (state: PreviewProofLifecycleState, event: Extract<PreviewProofLifecycleEvent, {
+    type: "cleanup";
+  }>) => PreviewProofLifecycleState;
+  readonly resolve: (state: PreviewProofLifecycleState, query?: PreviewProofResolveQuery) => readonly PreviewProofRegistration[];
+  readonly transition: (state: PreviewProofLifecycleState, event: PreviewProofLifecycleEvent) => PreviewProofLifecycleState;
+};
+//#endregion
+//#region src/preview-proof-inventory.d.ts
+/**
+ * Hosted preview-proof inventory (#639): persist and list Factory-App
+ * registrations, and record cleanup outcomes, without PR comments.
+ *
+ * `list` is a read over App-owned commit check-runs and works with a workflow
+ * `GITHUB_TOKEN`. `persist` and `recordCleanup` write those check-runs, which
+ * GitHub only allows the producing App to update. Pass an installation token
+ * the caller minted; this package does not read operator config or hold
+ * secrets. Cleanup writes go through `previewProofLifecycle.transition` with
+ * `{ type: "cleanup" }`. Outcomes are never inferred from whether a stage
+ * still exists.
+ */
+/** Check-run name that carries one registration JSON payload. Not a gate. */
+declare const PREVIEW_PROOF_INVENTORY_CHECK_NAME = "patronage-factory/preview-proof";
+interface PreviewProofInventoryStore {
+  list: (input: {
+    owner: string;
+    pr: number;
+    repo: string;
+  }) => Promise<readonly PreviewProofRegistration[]>;
+  put: (input: {
+    owner: string;
+    registration: PreviewProofRegistration;
+    repo: string;
+  }) => Promise<void>;
+}
+interface PreviewProofInventoryTransport {
+  /** Injectable `fetch` (tests, or a caller with its own instrumented one). */
+  fetch?: typeof fetch;
+  /** Per-request timeout; defaults to five seconds. */
+  timeoutMs?: number;
+  /**
+   * Bearer token. `list` accepts a workflow `GITHUB_TOKEN` (read). `persist`
+   * and `recordCleanup` must use a Factory App installation token: GitHub
+   * refuses GITHUB_TOKEN writes to App-owned check-runs.
+   */
+  token: string;
+}
+interface PreviewProofInventoryAccess {
+  fetch?: typeof fetch;
+  store?: PreviewProofInventoryStore;
+  timeoutMs?: number;
+  token?: string;
+}
+interface PreviewProofInventoryListInput {
+  owner: string;
+  pr: number;
+  repo: string;
+  stack?: string;
+  stage?: string;
+}
+interface PreviewProofInventoryPersistInput {
+  owner: string;
+  registration: PreviewProofRegistration;
+  repo: string;
+}
+interface PreviewProofInventoryCleanupInput {
+  evidence: readonly string[];
+  headSha?: string;
+  outcome: Exclude<PreviewProofCleanupStatus, "pending">;
+  owner: string;
+  pr: number;
+  repo: string;
+  runUrl?: string;
+  stack: string;
+  stage: string;
+}
+declare const previewProofInventory: {
+  readonly githubStore: (transport: PreviewProofInventoryTransport) => PreviewProofInventoryStore;
+  readonly list: (input: PreviewProofInventoryListInput, access: PreviewProofInventoryAccess) => Promise<readonly PreviewProofRegistration[]>;
+  readonly memoryStore: () => PreviewProofInventoryStore;
+  readonly persist: (input: PreviewProofInventoryPersistInput, access: PreviewProofInventoryAccess) => Promise<void>;
+  readonly recordCleanup: (input: PreviewProofInventoryCleanupInput, access: PreviewProofInventoryAccess) => Promise<PreviewProofRegistration>;
+};
+//#endregion
 //#region src/factory-workflow.d.ts
 interface WorkflowStep {
   readonly continueOnError?: boolean;
@@ -282,19 +471,43 @@ declare const mintInstallationToken: (input: {
 }, options?: GithubAppTokenOptions) => Promise<string>;
 //#endregion
 //#region src/execute-alchemy-entry.d.ts
+/** Node's spawnSync default is 1 MiB; Alchemy plans routinely exceed that. */
+declare const EXECUTE_ALCHEMY_ENTRY_MAX_BUFFER: number;
 interface ExecuteAlchemyEntryOptions {
   /**
    * CLI arguments before the bundled entry. The absolute entry path is always
    * appended as the final argument.
    */
   readonly args: readonly string[];
-  readonly bundle: BundleAlchemyEntryOptions;
+  /**
+   * Bundle the consumer entry before execution. Required unless `bundledEntry`
+   * is set. Ignored when `bundledEntry` is set.
+   */
+  readonly bundle?: BundleAlchemyEntryOptions;
+  /**
+   * Already-bundled entry path. When set, skips the internal bundle step and
+   * appends this path as the CLI's final argument.
+   */
+  readonly bundledEntry?: string;
   /** Child working directory. Defaults to the bundle root, then process.cwd. */
   readonly cwd?: string;
   /** Child environment. Defaults to process.env. */
   readonly env?: NodeJS.ProcessEnv;
   /** Consumer module context; normally the caller's import.meta.url. */
   readonly from: string | URL;
+  /**
+   * Largest captured stdout or stderr, in bytes. Omitted unless the caller
+   * sets it, so Node's spawnSync default (1 MiB) stays in force. Has no
+   * effect when stdio is `"inherit"`. Callers that need a larger capture
+   * pass `EXECUTE_ALCHEMY_ENTRY_MAX_BUFFER` or another explicit value.
+   */
+  readonly maxBuffer?: number;
+  /**
+   * Applied to captured stdout and stderr before they are returned. Unused
+   * when stdio is `"inherit"`. This package does not supply a secret-name
+   * policy; the caller owns redaction.
+   */
+  readonly redact?: (text: string) => string;
   /** Child stdio. Default "inherit". */
   readonly stdio?: "inherit" | "pipe";
 }
@@ -307,6 +520,11 @@ interface ExecuteAlchemyEntryResult {
  * Bundle a consumer-owned Alchemy entry, resolve that consumer's Alchemy CLI,
  * run it under the current Node binary, and return only on a successful exit.
  *
+ * Pass `bundledEntry` to skip the bundle step and reuse an already-bundled
+ * path. Captured stdout and stderr (`stdio: "pipe"`) can be redacted through
+ * `redact` before they are returned; `stdio: "inherit"` still streams the
+ * child unredacted.
+ *
  * Deploy/destroy/plan selection, stage admission, credentials, and every
  * convergence or destructive-change policy remain the caller's responsibility.
  */
@@ -623,6 +841,7 @@ declare const factoryProofReuseSummaryStep: (options: FactoryProofReusePresentat
 declare const FACTORY_CANDIDATE_IMPACT_STEP_ID = "candidate_impact";
 declare const FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT = "decision";
 declare const FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT = "basis";
+declare const FACTORY_CANDIDATE_IMPACT_INERT_OUTPUT = "inert_paths";
 declare const FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT = "unsubscribed_paths";
 interface FactoryCandidateImpactWorkflowOptions {
   readonly base?: string;
@@ -655,6 +874,72 @@ interface FactoryCandidateImpactWorkflow {
  */
 declare const factoryCandidateImpactWorkflow: (options: FactoryCandidateImpactWorkflowOptions) => FactoryCandidateImpactWorkflow;
 //#endregion
+//#region src/lifecycle-contract-lane.d.ts
+declare const FACTORY_LIFECYCLE_CONTRACT_JOB_ID = "factory-contracts";
+declare const FACTORY_LIFECYCLE_CONTRACT_JOB_NAME = "Factory / Alchemy Contracts";
+interface FactoryLifecycleContractLaneOptions {
+  readonly command: string;
+  readonly jobId?: string;
+  readonly jobName?: string;
+}
+interface FactoryLifecycleContractLane {
+  readonly jobId: string;
+  readonly jobName: string;
+  readonly steps: readonly WorkflowStep[];
+}
+/**
+ * Generate the factory-owned non-credentialed lifecycle-contract lane
+ * (#765). Consumers declare the package-script command in
+ * `software-factory.profile.json`; this helper never loads that profile.
+ * Callers pass the parsed declaration (or omit it) and include or skip the
+ * returned job. Setup, runners, topology, and credentials stay with the
+ * caller — and this lane must never receive credentials.
+ *
+ * The generated steps run only the declared package script and write an
+ * always() evidence summary of what the lane proves and does not prove.
+ * The command must be a package-script invocation: `run <script>`, or a
+ * shorthand whose script name contains `:` (`pnpm test:factory`). Optional
+ * pnpm `--filter <pkg>` may precede either form. Shell operators, credential
+ * env, extra flags, and direct Vitest are refused.
+ */
+declare const factoryLifecycleContractLane: (declaration?: FactoryLifecycleContractLaneOptions) => FactoryLifecycleContractLane | undefined;
+//#endregion
+//#region src/preview-cleanup-topology.d.ts
+declare const FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_ID = "stage-residue-audit";
+declare const FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_NAME = "Stage residue audit";
+interface FactoryPreviewCleanupTopologyOptions {
+  readonly audit: {
+    readonly command: string;
+    readonly jobId?: string;
+    readonly jobName?: string;
+  };
+  readonly stacks: readonly string[];
+}
+interface FactoryPreviewCleanupDestroyJob {
+  readonly jobId: string;
+  readonly stack: string;
+}
+interface FactoryPreviewCleanupAuditJob {
+  readonly if: "always()";
+  readonly jobId: string;
+  readonly jobName: string;
+  readonly needs: readonly string[];
+  readonly steps: readonly WorkflowStep[];
+}
+interface FactoryPreviewCleanupTopology {
+  readonly auditJob: FactoryPreviewCleanupAuditJob;
+  readonly destroyJobs: readonly FactoryPreviewCleanupDestroyJob[];
+}
+declare const previewCleanupDestroyJobId: (stack: string) => string;
+/**
+ * Generate the factory-owned preview-cleanup topology (#764): one destroy
+ * job identity per stack, then exactly one stage-wide residue-audit job
+ * that `needs` every destroy. The audit is whole-stage — this helper never
+ * threads a stack name or path filter into it. Callers own destroy steps,
+ * what counts as residue, credentials, and runners.
+ */
+declare const factoryPreviewCleanupTopology: (options: FactoryPreviewCleanupTopologyOptions) => FactoryPreviewCleanupTopology;
+//#endregion
 //#region src/production-impact-workflow.d.ts
 declare const FACTORY_PRODUCTION_IMPACT_STEP_ID = "production_impact";
 declare const FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT = "decision";
@@ -1016,4 +1301,4 @@ declare const assertWorkflowShellParses: (yaml: string, options: {
   readonly source: string;
 }) => void;
 //#endregion
-export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT, FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT, FACTORY_CANDIDATE_IMPACT_STEP_ID, FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_CANDIDATE_PULL_REQUEST_TYPES, FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT, FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT, FACTORY_PRODUCTION_IMPACT_STEP_ID, FACTORY_PRODUCTION_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_CHECK_NAME, FACTORY_PROOF_GATE_GUARD, FACTORY_PROOF_GATE_IF, FACTORY_PROOF_GATE_MODE_OUTPUT, FACTORY_PROOF_GATE_OUTPUT, FACTORY_PROOF_GATE_REASONS, FACTORY_PROOF_GATE_REASON_OUTPUT, FACTORY_PROOF_GATE_SHELL, FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT, FACTORY_PROOF_GATE_STEP_ID, FACTORY_PROOF_GATE_STEP_NAME, FACTORY_PUSH_IDENTITY_SCHEMA_VERSION, type FactoryCandidateImpactWorkflow, type FactoryCandidateImpactWorkflowOptions, type FactoryProductionImpactWorkflow, type FactoryProductionImpactWorkflowOptions, type FactoryProofGateOptions, type FactoryProofGateReason, type FactoryProofGateStep, type FactoryProofReusePresentationOptions, type FactoryProofReuseSummaryStep, type FactoryProofTimingStartStep, type FactoryPushIdentityConsumer, type FactoryPushIdentityConsumerOptions, type FactoryPushIdentityDisposition, type FactoryPushIdentityEnvelope, type FactoryPushIdentityProducer, type FactoryPushIdentityProducerOptions, type FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, GitHubApiError, type GithubAppCredentials, type GithubAppTokenOptions, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_NODE24, type NodePnpmActionFamily, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, type ProofReuseCommand, type ProofReuseCoverageInput, type ProofReuseCoverageReport, type SetupNodeStepOptions, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, type VitestJsonReport, type VitestProfile, type VitestProfileDependencies, type VitestProfileDurationSummary, type VitestProfileEnvironment, VitestProfileError, type VitestProfileOptions, type VitestProfileReadResult, type VitestProfileSample, type VitestProfileSampleExecution, type VitestTestStatus, type WorkflowShellParseFailure, type WorkflowStep, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryCandidateImpactWorkflow, factoryCandidateOrPushCondition, factoryProductionImpactWorkflow, factoryProofGateScript, factoryProofGateStep, factoryProofReuseSummaryStep, factoryProofTimingStartStep, factoryPushIdentityConsumer, factoryPushIdentityProducer, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, productionImpactTargetOutput, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };
+export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, EXECUTE_ALCHEMY_ENTRY_MAX_BUFFER, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT, FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT, FACTORY_CANDIDATE_IMPACT_INERT_OUTPUT, FACTORY_CANDIDATE_IMPACT_STEP_ID, FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_CANDIDATE_PULL_REQUEST_TYPES, FACTORY_LIFECYCLE_CONTRACT_JOB_ID, FACTORY_LIFECYCLE_CONTRACT_JOB_NAME, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_ID, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_NAME, FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT, FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT, FACTORY_PRODUCTION_IMPACT_STEP_ID, FACTORY_PRODUCTION_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_CHECK_NAME, FACTORY_PROOF_GATE_GUARD, FACTORY_PROOF_GATE_IF, FACTORY_PROOF_GATE_MODE_OUTPUT, FACTORY_PROOF_GATE_OUTPUT, FACTORY_PROOF_GATE_REASONS, FACTORY_PROOF_GATE_REASON_OUTPUT, FACTORY_PROOF_GATE_SHELL, FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT, FACTORY_PROOF_GATE_STEP_ID, FACTORY_PROOF_GATE_STEP_NAME, FACTORY_PUSH_IDENTITY_SCHEMA_VERSION, type FactoryCandidateImpactWorkflow, type FactoryCandidateImpactWorkflowOptions, type FactoryLifecycleContractLane, type FactoryLifecycleContractLaneOptions, type FactoryPreviewCleanupAuditJob, type FactoryPreviewCleanupDestroyJob, type FactoryPreviewCleanupTopology, type FactoryPreviewCleanupTopologyOptions, type FactoryProductionImpactWorkflow, type FactoryProductionImpactWorkflowOptions, type FactoryProofGateOptions, type FactoryProofGateReason, type FactoryProofGateStep, type FactoryProofReusePresentationOptions, type FactoryProofReuseSummaryStep, type FactoryProofTimingStartStep, type FactoryPushIdentityConsumer, type FactoryPushIdentityConsumerOptions, type FactoryPushIdentityDisposition, type FactoryPushIdentityEnvelope, type FactoryPushIdentityProducer, type FactoryPushIdentityProducerOptions, type FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, GitHubApiError, type GithubAppCredentials, type GithubAppTokenOptions, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_NODE24, type NodePnpmActionFamily, PREVIEW_PROOF_INVENTORY_CHECK_NAME, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, type PreviewProofCandidate, type PreviewProofCleanupOutcome, type PreviewProofCleanupStatus, type PreviewProofEnvelopeEvidence, type PreviewProofInventoryAccess, type PreviewProofInventoryCleanupInput, type PreviewProofInventoryListInput, type PreviewProofInventoryPersistInput, type PreviewProofInventoryStore, type PreviewProofInventoryTransport, type PreviewProofLifecycleEvent, type PreviewProofLifecycleState, type PreviewProofRegistration, type PreviewProofResolveQuery, type ProofReuseCommand, type ProofReuseCoverageInput, type ProofReuseCoverageReport, type SetupNodeStepOptions, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, type VitestJsonReport, type VitestProfile, type VitestProfileDependencies, type VitestProfileDurationSummary, type VitestProfileEnvironment, VitestProfileError, type VitestProfileOptions, type VitestProfileReadResult, type VitestProfileSample, type VitestProfileSampleExecution, type VitestTestStatus, type WorkflowShellParseFailure, type WorkflowStep, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryCandidateImpactWorkflow, factoryCandidateOrPushCondition, factoryLifecycleContractLane, factoryPreviewCleanupTopology, factoryProductionImpactWorkflow, factoryProofGateScript, factoryProofGateStep, factoryProofReuseSummaryStep, factoryProofTimingStartStep, factoryPushIdentityConsumer, factoryPushIdentityProducer, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, previewCleanupDestroyJobId, previewProofInventory, previewProofLifecycle, productionImpactTargetOutput, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };