@intentius/chant-lexicon-aws 0.13.1 → 0.15.0

package/dist/components/job-submission.d.ts

@@ -0,0 +1,89 @@
+/**
+ * job submission family — point a running compute service at an artifact.
+ * Cloud-shaped (EMR here; the same shape reuses for Glue / Batch / Step
+ * Functions / SageMaker per docs/components/cloud-boundary). Typically
+ * consumes a producer component's published artifact, e.g.
+ * `jar: "@jar-lib.publish.uri"`.
+ *
+ * `emr-start-job-run` is a real implementation (#561, epic #551) — just
+ * enough against the injectable `CloudExecutor` (./cloud-executor.ts) to run
+ * the JAR-producer -> EMR-consumer cross-component example end to end (a
+ * mocked cloud is acceptable per #561's acceptance criteria; the full EMR
+ * surface — retries, Serverless vs EMR-on-EC2 branching, Glue/Batch peers —
+ * stays out of scope, per #561 explicitly deferring "the emr-start-job-run
+ * cloud impl beyond what the example needs"). `emr-submit-step` is a
+ * different verb (submit a step to an already-running EMR-on-EC2 cluster
+ * rather than starting an ephemeral job run), also real over the executor
+ * (`aws emr add-steps`) and unit-tested against the mock — the same
+ * "mocked cloud is acceptable" basis #561 set for its sibling, since a live
+ * long-running EMR cluster is not part of gating CI.
+ */
+import type { Capability } from "@intentius/chant/components/capability";
+import { type CloudExecutor } from "./cloud-executor.js";
+export interface EmrStartJobRunInput {
+    /**
+     * EMR (Serverless) application id, or EMR on EC2 cluster id. Optional here
+     * (unlike the underlying `CloudExecutor.emr.startJobRun` args) because the
+     * epic's worked JAR->EMR example (component-contract fixture
+     * `../__fixtures__/emr-job-consumer.json`, docs/components/composition-and-wiring.mdx)
+     * wires it as env config rather than a literal in the component
+     * declaration; falls back to `ctx.vars.emrApplicationId`, matching how
+     * `wait-cluster-healthy` (../verbs/wait-verify.ts) falls back to
+     * `ctx.vars.clusterEndpoints` for the same reason (env resolution is the
+     * caller's `DeployContext.vars`, not a literal every component must repeat).
+     */
+    clusterOrApplicationId?: string;
+    /** Entry point artifact reference — resolved by the graph before this capability runs (e.g. from `"@jar-lib.publish.uri"` to a concrete S3 URI). */
+    jar: string;
+    /** Arguments passed to the job's main class/entry point. */
+    args?: string[];
+    /** Execution role ARN. */
+    executionRoleArn?: string;
+}
+export interface EmrStartJobRunOutput {
+    /** EMR job run id, for polling via `wait-job`. */
+    runId: string;
+}
+/**
+ * Start an EMR job run (Serverless application or EMR-on-EC2 cluster)
+ * against a published artifact. `input.jar` arrives already resolved by the
+ * driver's graph-driven wiring (`@<component>.publish.uri`) — this capability
+ * never resolves the reference itself, keeping cross-component wiring
+ * entirely the graph's job (../driver.ts's `resolveWiring`), never a
+ * capability- or orchestrator-level special case. No rollback: starting a
+ * job run has no "undo" that restores prior state — a failed/cancelled run
+ * simply produced no usable output, matching `wait-for-stack`/`wait-job`'s
+ * read-only-observation story (there is nothing to compensate for having
+ * asked the cluster to run something).
+ */
+export declare function createEmrStartJobRunCapability(executor?: CloudExecutor): Capability<EmrStartJobRunInput, EmrStartJobRunOutput>;
+/** Default `emr-start-job-run` capability, backed by the real `CloudExecutor`. */
+export declare const emrStartJobRunCapability: Capability<EmrStartJobRunInput, EmrStartJobRunOutput>;
+export interface EmrSubmitStepInput {
+    /** EMR-on-EC2 cluster id to submit the step to. */
+    clusterId: string;
+    /** Step name, shown in the EMR console. */
+    name: string;
+    /** Entry point artifact reference (e.g. `"@jar-lib.publish.uri"`) — resolved by the graph before this capability runs, exactly like `emr-start-job-run`'s `jar`. */
+    jar: string;
+    /** Arguments passed to the step. */
+    args?: string[];
+    /** What EMR does if the step fails. Default: "CONTINUE". */
+    actionOnFailure?: "CONTINUE" | "CANCEL_AND_WAIT" | "TERMINATE_CLUSTER";
+}
+export interface EmrSubmitStepOutput {
+    /** EMR step id, for polling via `wait-job`. */
+    stepId: string;
+}
+/**
+ * Submit a step to a long-running EMR-on-EC2 cluster (as opposed to
+ * `emr-start-job-run`, which starts an ephemeral Serverless/EC2 job run) via
+ * `aws emr add-steps` through the injectable `CloudExecutor`. Returns the step
+ * id for polling via `wait-job`. Like its sibling, `input.jar` arrives
+ * already resolved by the driver's graph-driven wiring, and there is no
+ * rollback — a submitted step has no "undo" that restores prior state.
+ */
+export declare function createEmrSubmitStepCapability(executor?: CloudExecutor): Capability<EmrSubmitStepInput, EmrSubmitStepOutput>;
+/** Default `emr-submit-step` capability, backed by the real `CloudExecutor`. */
+export declare const emrSubmitStepCapability: Capability<EmrSubmitStepInput, EmrSubmitStepOutput>;
+//# sourceMappingURL=job-submission.d.ts.map

package/dist/components/job-submission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-submission.d.ts","sourceRoot":"","sources":["../../src/components/job-submission.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AACzE,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAI5E,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;OAUG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,oJAAoJ;IACpJ,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,0BAA0B;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACnC,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,GAAE,aAAsC,GAC/C,UAAU,CAAC,mBAAmB,EAAE,oBAAoB,CAAC,CAgBvD;AAED,kFAAkF;AAClF,eAAO,MAAM,wBAAwB,EAAE,UAAU,CAAC,mBAAmB,EAAE,oBAAoB,CACzD,CAAC;AAInC,MAAM,WAAW,kBAAkB;IACjC,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,oKAAoK;IACpK,GAAG,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,4DAA4D;IAC5D,eAAe,CAAC,EAAE,UAAU,GAAG,iBAAiB,GAAG,mBAAmB,CAAC;CACxE;AAED,MAAM,WAAW,mBAAmB;IAClC,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,GAAE,aAAsC,GAC/C,UAAU,CAAC,kBAAkB,EAAE,mBAAmB,CAAC,CAerD;AAED,gFAAgF;AAChF,eAAO,MAAM,uBAAuB,EAAE,UAAU,CAAC,kBAAkB,EAAE,mBAAmB,CACvD,CAAC"}

package/dist/components/publish.d.ts

@@ -0,0 +1,194 @@
+/**
+ * publish family — deploy-time promotion by identity to the env location.
+ *
+ * "Make the image available at the deploy target" has more than one backend:
+ * `publish-image` promotes into a registry (ECR/ACR/Artifact Registry, pulled
+ * by the target); `load-image-on-host` copies the tarball straight onto a host
+ * and `docker load`s it (registry-less). Both satisfy the same
+ * `PublishImageBackend` interface — the backend is env config, not a pipeline
+ * fork. `publish-asset`/`publish-artifact` is the non-image sibling (S3 /
+ * CodeArtifact) used by producer/library components (e.g. a jar for EMR).
+ * See docs/components/build-archive.mdx.
+ *
+ * `publish-image` is a real implementation (#557, epic #551): it loads the
+ * archived image tarball, tags it for the destination registry, logs in via
+ * ECR, and pushes — promoting by digest, per the epic's build-once invariant.
+ *
+ * `load-image-on-host` is a real implementation (#564, epic #551 "4. Build
+ * archive + deferred publish"): it copies the archived tarball onto a host
+ * and runs `docker load` there via the injected `CloudExecutor.host` — no
+ * registry in the path at all. Both backends promote **by digest**, never
+ * rebuilding: the bytes they move are exactly what `docker-build` produced
+ * into the archive (see ./build-archive.ts). `selectPublishBackend` below is
+ * the per-environment choice between them — env config, not a pipeline fork,
+ * per docs/components/build-archive.mdx#backend-selection-is-per-environment.
+ *
+ * `publish-artifact` (aliased `publish-asset`) uploads a single archive
+ * artifact (jar/zip/asset) to S3 via `aws s3 cp` through the same
+ * endpoint-aware `CloudExecutor`, returning the object URI and a content digest
+ * of the uploaded bytes — the non-image sibling of `publish-image`.
+ *
+ * **#610 addition: publish-time SBOM/BOM referrer attach.** `publish-image`
+ * optionally registers the archive's SBOM (and, when given, the
+ * component-level aggregate BOM) as an OCI referrer on the just-pushed image
+ * digest via `oras attach` — a registry-side convenience for `oras
+ * discover`/`cosign tree` layered on top of the archive-carried copy, never a
+ * replacement for it (see ../../lifecycle/build-ledger.ts's module doc: the
+ * archive remains the universal home, working for every artifact type and
+ * the registry-less `load-image-on-host` path, which this attach step
+ * deliberately does not touch — non-image/registry-less publishes stay
+ * archive-carried only). Attach is opt-in per call (`input.sbom` supplied),
+ * guarded on `oras` availability, and never fails the publish itself: a
+ * missing `oras` binary or a failed attach is reported back on the output
+ * (`referrerAttach.attached: false` + a reason) rather than thrown, since the
+ * image is already successfully promoted by the time this step runs — the
+ * one part of this capability that is genuinely best-effort.
+ */
+import type { Capability } from "@intentius/chant/components/capability";
+import { type CloudExecutor } from "./cloud-executor.js";
+import { type ProcessRunner } from "@intentius/chant/components/verbs/process-runner";
+/**
+ * Common input shape both image-publish backends accept: promote the image
+ * bytes at archive path `from` to wherever the deploy target can consume
+ * them. `to` (registry) and `host` (bare host) are each meaningful to only
+ * one backend, so a component authors one step shape (see
+ * docs/components/build-archive.mdx) and the env-selected backend (see
+ * `selectPublishBackend` below) reads whichever field it needs — the
+ * unselected backend's field is simply unused, never a pipeline fork.
+ */
+export interface PublishImageInput {
+    /** Path of the image tarball inside the build archive (as produced by `docker-build`; an `archive:`-prefixed reference is accepted and stripped). */
+    from: string;
+    /** Destination registry — required by `publish-image`, ignored by `load-image-on-host` (e.g. `$env.registry` resolved by the orchestrator). */
+    to?: string;
+    /** Target host — required by `load-image-on-host`, ignored by `publish-image` (SSM instance id, hostname, or host group). */
+    host?: string;
+    /** Destination path for the tarball on the host, used only by `load-image-on-host`. Default: `/tmp/chant-archive/<basename of from>`. */
+    hostPath?: string;
+    /** Additional tags to apply alongside the digest, used only by `publish-image`. */
+    tags?: string[];
+    /**
+     * #610: the artifact's software SBOM (typically wired from a prior
+     * `generate-sbom` step's `sbom` output — see ./sbom.ts's
+     * `GenerateSbomOutput`) to attach as an OCI referrer on the pushed image
+     * digest, via `oras attach`. Used only by `publish-image`; ignored by
+     * `load-image-on-host` (registry-less — nothing to attach to). Omit to
+     * skip the attach step entirely (the archive-carried copy remains the
+     * SBOM's home either way).
+     */
+    sbom?: {
+        bytes: string;
+        mediaType: string;
+    };
+    /**
+     * #610: the component-level aggregate BOM (wired from
+     * ./component-bom.ts's `aggregateComponentBom` output), attached as a
+     * second OCI referrer alongside `sbom` when supplied. Optional and
+     * independent of `sbom` — a caller may attach either, both, or neither.
+     */
+    componentBom?: {
+        bytes: string;
+        mediaType: string;
+    };
+}
+/** Result of `publish-image`'s best-effort OCI-referrer attach step (#610) — always present when `input.sbom`/`input.componentBom` was supplied, `undefined` when neither was (nothing to attach, attach step skipped entirely). */
+export interface ReferrerAttachResult {
+    /** True once every requested attach (`sbom`, `componentBom`) succeeded. `false` if `oras` was unavailable or any `oras attach` invocation failed. */
+    attached: boolean;
+    /** Human-readable reason `attached` is `false` (e.g. "oras is not installed"), omitted when `attached` is `true`. */
+    reason?: string;
+}
+export interface PublishImageOutput {
+    /** Content-addressed digest of the promoted image (`sha256:...`) — what the apply step references. */
+    digest: string;
+    /** Image reference the apply step can pull/run: `registry/repo@sha256:...` for `publish-image`, a host-local reference for `load-image-on-host`. */
+    uri: string;
+    /** #610: outcome of the best-effort SBOM/component-BOM referrer attach, when `input.sbom`/`input.componentBom` was supplied. `undefined` for `load-image-on-host` (no attach concept — registry-less) and for `publish-image` calls that supplied neither. */
+    referrerAttach?: ReferrerAttachResult;
+}
+/**
+ * Common shape both image-publish backends satisfy: promote the image bytes
+ * held in the build archive to wherever the deploy target can consume them,
+ * and return the identity the apply step references. The backend is
+ * selected per environment (`selectPublishBackend`), never per component.
+ */
+export type PublishImageBackend = Capability<PublishImageInput, PublishImageOutput>;
+/**
+ * Promote a built image from the archive into the environment's container
+ * registry: `docker load` the archived tarball, tag it for `to` (the env
+ * registry), `aws ecr get-login-password | docker login`, then `docker push`.
+ * Returns the pushed image's registry digest — what `cfn-deploy`/
+ * `ecs-update-service` reference via `imageRef: "@Publish.digest"`. No
+ * rollback: an already-pushed, still-valid image in the registry is not
+ * itself a problem to compensate (immutable, content-addressed, and simply
+ * unreferenced if a later step fails) — the opt-out this capability takes.
+ *
+ * #610: when `input.sbom` and/or `input.componentBom` are supplied, also
+ * attaches them as OCI referrers on the pushed digest via `oras attach` (see
+ * `attachReferrers` above) — best-effort, guarded on `oras` availability,
+ * surfaced on the output's `referrerAttach` rather than failing the publish.
+ */
+export declare function createPublishImageCapability(executor?: CloudExecutor, processRunner?: ProcessRunner): PublishImageBackend;
+/** Default `publish-image` capability, backed by the real `CloudExecutor`. */
+export declare const publishImageCapability: PublishImageBackend;
+/**
+ * Copy the image tarball straight onto a host and `docker load` it there —
+ * genuinely registry-free promotion (#564): no `docker.push`, no ECR login,
+ * no registry ever in the path. Still promotes **by digest**: the tarball
+ * copied is the exact archive artifact `docker-build` produced, so the image
+ * loaded on the host is byte-identical to the one tested in any other
+ * environment, satisfying the same build-once invariant `publish-image`
+ * does. No rollback, for the same reason `publish-image` declares none: an
+ * already-loaded, content-addressed image sitting in a host's local Docker
+ * store is not itself a problem to compensate.
+ *
+ * See docs/components/build-archive.mdx#registry-less-caveat: this makes
+ * *your built* image registry-free. Third-party images a compose file
+ * references (`postgres:16`, `redis`) still pull from their upstream
+ * registry at `compose up` unless they are archived and loaded the same way.
+ */
+export declare function createLoadImageOnHostCapability(executor?: CloudExecutor): PublishImageBackend;
+/** Default `load-image-on-host` capability, backed by the real `CloudExecutor`. */
+export declare const loadImageOnHostCapability: PublishImageBackend;
+/** The `kind` of either image-publish backend — what an environment's config declares as its choice. */
+export type PublishImageBackendKind = "publish-image" | "load-image-on-host";
+/**
+ * Resolve which publish backend an environment uses, given its declared
+ * `kind` (`$env.publish.kind` in the component's env config — see
+ * docs/components/build-archive.mdx#backend-selection-is-per-environment).
+ * The decision is per environment, not per component: the same component's
+ * `Publish` phase runs `publish-image` against dev's ECR and
+ * `load-image-on-host` against a locked-down prod host, with no change to
+ * the component's own composition — only the env config `kind` differs.
+ *
+ * Accepts an optional registry of backends so a caller can extend the set
+ * (e.g. a third-party plugin registering another `PublishImageBackend`)
+ * without this function needing to change; defaults to the two starter-set
+ * backends built above.
+ */
+export declare function selectPublishBackend(kind: PublishImageBackendKind, backends?: Partial<Record<PublishImageBackendKind, PublishImageBackend>>): PublishImageBackend;
+export interface PublishArtifactInput {
+    /** Path of the artifact inside the build archive (e.g. a jar or zip). */
+    from: string;
+    /** Destination (e.g. `$env.s3` resolved by the orchestrator). */
+    to: string;
+}
+export interface PublishArtifactOutput {
+    /** Location the artifact was published to — referenced downstream as `@<component>.publish.uri`. */
+    uri: string;
+    /** Content hash of the published artifact. */
+    digest: string;
+}
+/** Promote a non-image artifact (jar, zip, arbitrary asset) from the archive to S3/CodeArtifact. */
+/**
+ * Publish a single archive artifact (a jar, zip, or asset) to S3 via `aws s3 cp`
+ * (endpoint-aware through the `CloudExecutor`). Returns the object's URI —
+ * referenced downstream as `@<component>.publish.uri` — and a content digest of
+ * the exact bytes uploaded.
+ */
+export declare function createPublishArtifactCapability(executor?: CloudExecutor): Capability<PublishArtifactInput, PublishArtifactOutput>;
+/** Default `publish-artifact` capability, backed by the real `CloudExecutor`. */
+export declare const publishArtifactCapability: Capability<PublishArtifactInput, PublishArtifactOutput>;
+/** Alias for `publish-artifact` — same capability, the docs/epic use both names for the same verb. */
+export declare const publishAssetCapability: Capability<PublishArtifactInput, PublishArtifactOutput>;
+//# sourceMappingURL=publish.d.ts.map

package/dist/components/publish.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish.d.ts","sourceRoot":"","sources":["../../src/components/publish.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AAGzE,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE5E,OAAO,EAA2B,KAAK,aAAa,EAAE,MAAM,kDAAkD,CAAC;AAI/G;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,qJAAqJ;IACrJ,IAAI,EAAE,MAAM,CAAC;IACb,+IAA+I;IAC/I,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,6HAA6H;IAC7H,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yIAAyI;IACzI,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C;;;;;OAKG;IACH,YAAY,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD;AAED,oOAAoO;AACpO,MAAM,WAAW,oBAAoB;IACnC,qJAAqJ;IACrJ,QAAQ,EAAE,OAAO,CAAC;IAClB,qHAAqH;IACrH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,sGAAsG;IACtG,MAAM,EAAE,MAAM,CAAC;IACf,oJAAoJ;IACpJ,GAAG,EAAE,MAAM,CAAC;IACZ,8PAA8P;IAC9P,cAAc,CAAC,EAAE,oBAAoB,CAAC;CACvC;AAED;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,UAAU,CAAC,iBAAiB,EAAE,kBAAkB,CAAC,CAAC;AA4DpF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,GAAE,aAAsC,EAChD,aAAa,GAAE,aAAsC,GACpD,mBAAmB,CAgCrB;AAED,8EAA8E;AAC9E,eAAO,MAAM,sBAAsB,EAAE,mBAAoD,CAAC;AAU1F;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,GAAE,aAAsC,GAC/C,mBAAmB,CAYrB;AAED,mFAAmF;AACnF,eAAO,MAAM,yBAAyB,EAAE,mBAAuD,CAAC;AAIhG,wGAAwG;AACxG,MAAM,MAAM,uBAAuB,GAAG,eAAe,GAAG,oBAAoB,CAAC;AAE7E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,uBAAuB,EAC7B,QAAQ,GAAE,OAAO,CAAC,MAAM,CAAC,uBAAuB,EAAE,mBAAmB,CAAC,CAGrE,GACA,mBAAmB,CAQrB;AAID,MAAM,WAAW,oBAAoB;IACnC,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,qBAAqB;IACpC,oGAAoG;IACpG,GAAG,EAAE,MAAM,CAAC;IACZ,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,oGAAoG;AACpG;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,GAAE,aAAsC,GAC/C,UAAU,CAAC,oBAAoB,EAAE,qBAAqB,CAAC,CAYzD;AAED,iFAAiF;AACjF,eAAO,MAAM,yBAAyB,EAAE,UAAU,CAAC,oBAAoB,EAAE,qBAAqB,CAC3D,CAAC;AAEpC,sGAAsG;AACtG,eAAO,MAAM,sBAAsB,yDAA4B,CAAC"}

package/dist/components/safety.d.ts

@@ -0,0 +1,49 @@
+/**
+ * safety / rollback family — explicit snapshot-and-restore capabilities, used
+ * alongside the per-capability `rollback` compensation for cases that need an
+ * up-front capture (e.g. before a `cfn-deploy` with `onReplace: "snapshot-first"`).
+ *
+ * Both dispatch to the kind-appropriate AWS backup/restore mechanism through the
+ * injectable `CloudExecutor` (DynamoDB backup, RDS DB snapshot, EBS snapshot).
+ */
+import type { Capability } from "@intentius/chant/components/capability";
+import { type CloudExecutor } from "./cloud-executor.js";
+export interface SnapshotBeforeInput {
+    /** Resource identifier to snapshot (e.g. a DynamoDB table name, an RDS instance id). */
+    resource: string;
+    /** Resource kind, used to select the right snapshot mechanism. */
+    resourceKind: "dynamodb-table" | "rds-instance" | "opensearch-domain" | "ebs-volume";
+}
+export interface SnapshotBeforeOutput {
+    /** Snapshot identifier, for `rollback-previous` to restore from. */
+    snapshotId: string;
+}
+/**
+ * Capture a restorable snapshot before a risky/destructive apply step, via the
+ * kind-appropriate AWS backup mechanism through the injectable `CloudExecutor`
+ * (DynamoDB on-demand backup, RDS DB snapshot, or EBS volume snapshot). Returns
+ * the backup/snapshot id `rollback-previous` restores from.
+ */
+export declare function createSnapshotBeforeCapability(executor?: CloudExecutor): Capability<SnapshotBeforeInput, SnapshotBeforeOutput>;
+/** Default `snapshot-before` capability, backed by the real `CloudExecutor`. */
+export declare const snapshotBeforeCapability: Capability<SnapshotBeforeInput, SnapshotBeforeOutput>;
+export interface RollbackPreviousInput {
+    /** Snapshot identifier to restore (typically `"@snapshot-before.snapshotId"`). */
+    snapshotId: string;
+    /** Resource identifier being restored. */
+    resource: string;
+}
+export interface RollbackPreviousOutput {
+    /** True once the restore completed. */
+    restored: boolean;
+}
+/**
+ * Restore a resource from a prior `snapshot-before` capture — an explicit,
+ * caller-composed rollback (not the auto-triggered per-capability compensation).
+ * Dispatches by the snapshot-id shape through the `CloudExecutor` and waits for
+ * the restore to become available.
+ */
+export declare function createRollbackPreviousCapability(executor?: CloudExecutor): Capability<RollbackPreviousInput, RollbackPreviousOutput>;
+/** Default `rollback-previous` capability, backed by the real `CloudExecutor`. */
+export declare const rollbackPreviousCapability: Capability<RollbackPreviousInput, RollbackPreviousOutput>;
+//# sourceMappingURL=safety.d.ts.map

package/dist/components/safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety.d.ts","sourceRoot":"","sources":["../../src/components/safety.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AACzE,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAI5E,MAAM,WAAW,mBAAmB;IAClC,wFAAwF;IACxF,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,YAAY,EAAE,gBAAgB,GAAG,cAAc,GAAG,mBAAmB,GAAG,YAAY,CAAC;CACtF;AAED,MAAM,WAAW,oBAAoB;IACnC,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,QAAQ,GAAE,aAAsC,GAAG,UAAU,CAAC,mBAAmB,EAAE,oBAAoB,CAAC,CAOtJ;AAED,gFAAgF;AAChF,eAAO,MAAM,wBAAwB,EAAE,UAAU,CAAC,mBAAmB,EAAE,oBAAoB,CACzD,CAAC;AAInC,MAAM,WAAW,qBAAqB;IACpC,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,uCAAuC;IACvC,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAAC,QAAQ,GAAE,aAAsC,GAAG,UAAU,CAAC,qBAAqB,EAAE,sBAAsB,CAAC,CAQ5J;AAED,kFAAkF;AAClF,eAAO,MAAM,0BAA0B,EAAE,UAAU,CAAC,qBAAqB,EAAE,sBAAsB,CAC7D,CAAC"}

package/dist/components/wait-aws.d.ts

@@ -0,0 +1,65 @@
+/**
+ * wait / verify family — the cloud-specific members, owned by the aws lexicon:
+ * `wait-for-stack` (CloudFormation), `wait-steady-state` (ECS), `wait-job`
+ * (EMR). The agnostic waits (`wait-cluster-healthy`, `wait-endpoint`,
+ * `health-gate`) stay in core. All poll a real cloud through the injectable aws
+ * `CloudExecutor` (./cloud-executor.ts); none has a rollback — a wait is a
+ * read-only observation, never a mutation.
+ */
+import type { Capability } from "@intentius/chant/components/capability";
+import { type CloudExecutor } from "./cloud-executor.js";
+export interface WaitForStackInput {
+    /** CloudFormation stack name. */
+    stack: string;
+    /** Poll interval in ms. Default: 10000. */
+    intervalMs?: number;
+    /** Overall timeout in ms. */
+    timeoutMs?: number;
+}
+export interface WaitForStackOutput {
+    /** Terminal stack status (`CREATE_COMPLETE`, `UPDATE_COMPLETE`, ...). */
+    stackStatus: string;
+}
+/** Poll a CloudFormation stack until it reaches a terminal status. No rollback: a wait is a read-only observation. */
+export declare function createWaitForStackCapability(executor?: CloudExecutor): Capability<WaitForStackInput, WaitForStackOutput>;
+/** Default `wait-for-stack` capability, backed by the real aws `CloudExecutor`. */
+export declare const waitForStackCapability: Capability<WaitForStackInput, WaitForStackOutput>;
+export interface WaitSteadyStateInput {
+    /** Service identifier (e.g. an ECS service name). */
+    service: string;
+    /** ECS cluster name/ARN the service lives in. Default: "default". */
+    cluster?: string;
+    /** Poll interval in ms. Default: 10000. */
+    intervalMs?: number;
+    /** Overall timeout in ms. Default: 10 minutes. */
+    timeoutMs?: number;
+}
+export interface WaitSteadyStateOutput {
+    /** Running task/instance count once steady state is reached. */
+    runningCount: number;
+}
+/** Poll an ECS service until running count matches desired and no deployment is in flight. No rollback: read-only. */
+export declare function createWaitSteadyStateCapability(executor?: CloudExecutor): Capability<WaitSteadyStateInput, WaitSteadyStateOutput>;
+/** Default `wait-steady-state` capability, backed by the real aws `CloudExecutor`. */
+export declare const waitSteadyStateCapability: Capability<WaitSteadyStateInput, WaitSteadyStateOutput>;
+export interface WaitJobInput {
+    /** Job/step run id (e.g. from `emr-start-job-run` or `emr-submit-step`). */
+    runId: string;
+    /** Poll interval in ms. Default: 10000. */
+    intervalMs?: number;
+    /** Overall timeout in ms. */
+    timeoutMs?: number;
+}
+export interface WaitJobOutput {
+    /** Terminal job state (`COMPLETED`, `FAILED`, `CANCELLED`). */
+    state: string;
+}
+/**
+ * Poll a submitted job/step (e.g. an EMR job run started by `emr-start-job-run`)
+ * until it reaches a terminal state, failing the step if that state is not
+ * `COMPLETED`. No rollback: read-only observation.
+ */
+export declare function createWaitJobCapability(executor?: CloudExecutor): Capability<WaitJobInput, WaitJobOutput>;
+/** Default `wait-job` capability, backed by the real aws `CloudExecutor`. */
+export declare const waitJobCapability: Capability<WaitJobInput, WaitJobOutput>;
+//# sourceMappingURL=wait-aws.d.ts.map

package/dist/components/wait-aws.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-aws.d.ts","sourceRoot":"","sources":["../../src/components/wait-aws.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AACzE,OAAO,EAA+B,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAInF,MAAM,WAAW,iBAAiB;IAChC,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,sHAAsH;AACtH,wBAAgB,4BAA4B,CAC1C,QAAQ,GAAE,aAAsC,GAC/C,UAAU,CAAC,iBAAiB,EAAE,kBAAkB,CAAC,CAWnD;AAED,mFAAmF;AACnF,eAAO,MAAM,sBAAsB,EAAE,UAAU,CAAC,iBAAiB,EAAE,kBAAkB,CAAkC,CAAC;AAIxH,MAAM,WAAW,oBAAoB;IACnC,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,sHAAsH;AACtH,wBAAgB,+BAA+B,CAC7C,QAAQ,GAAE,aAAsC,GAC/C,UAAU,CAAC,oBAAoB,EAAE,qBAAqB,CAAC,CAiBzD;AAED,sFAAsF;AACtF,eAAO,MAAM,yBAAyB,EAAE,UAAU,CAAC,oBAAoB,EAAE,qBAAqB,CAC3D,CAAC;AAIpC,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,GAAE,aAAsC,GAC/C,UAAU,CAAC,YAAY,EAAE,aAAa,CAAC,CAczC;AAED,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,EAAE,UAAU,CAAC,YAAY,EAAE,aAAa,CAA6B,CAAC"}