@intentius/chant-lexicon-aws 0.124.31 → 0.124.33

package/dist/generated/runtime.js

@@ -0,0 +1,4 @@
+/**
+ * Runtime factory constructors — re-exported from core.
+ */
+export { createResource, createProperty } from "@intentius/chant/runtime";

package/dist/governance.js

@@ -0,0 +1,131 @@
+/**
+ * AWS governance authoring: the desired-state config
+ * shape an external governance reconciler applies, and `landingZoneConfig()` —
+ * the typed authoring layer that emits it.
+ *
+ * This is deliberately NOT a composite. The evaluability rules (EVL002/004,
+ * #916/#952) require composites to declare a fixed set of resources, so a
+ * data-driven OU tree walker cannot be one. The split mirrors the SCM
+ * reconcilers: authoring emits config (this module, arbitrary cardinality);
+ * resources for greenfield bootstrap are the fixed-shape composites in
+ * `composites/landing-zone.ts`; the reconciler consumes only the config.
+ *
+ * GCP (Folder/OrgPolicy/AuditConfig) and Azure (blocked on #1545)
+ * counterparts followed the same shape.
+ */
+// ---------------------------------------------------------------------------
+// Baseline guardrails (shared with the bootstrap composites)
+// ---------------------------------------------------------------------------
+export const DENY_LEAVE_ORGANIZATION = {
+    description: "Member accounts may not remove themselves from the organization.",
+    document: {
+        Version: "2012-10-17",
+        Statement: [{ Effect: "Deny", Action: "organizations:LeaveOrganization", Resource: "*" }],
+    },
+};
+export const DENY_AUDIT_TAMPER = {
+    description: "Audit trails and recorders cannot be stopped or deleted from member accounts.",
+    document: {
+        Version: "2012-10-17",
+        Statement: [
+            {
+                Effect: "Deny",
+                Action: [
+                    "cloudtrail:StopLogging",
+                    "cloudtrail:DeleteTrail",
+                    "config:StopConfigurationRecorder",
+                    "config:DeleteConfigurationRecorder",
+                    "config:DeleteDeliveryChannel",
+                ],
+                Resource: "*",
+            },
+        ],
+    },
+};
+/** Deny requests outside `regions`, excepting global services. */
+export function regionRestriction(regions) {
+    return {
+        description: `Deny requests outside [${regions.join(", ")}] except global services.`,
+        document: {
+            Version: "2012-10-17",
+            Statement: [
+                {
+                    Effect: "Deny",
+                    NotAction: [
+                        "iam:*",
+                        "organizations:*",
+                        "route53:*",
+                        "cloudfront:*",
+                        "sts:*",
+                        "support:*",
+                        "budgets:*",
+                    ],
+                    Resource: "*",
+                    Condition: { StringNotEquals: { "aws:RequestedRegion": regions } },
+                },
+            ],
+        },
+    };
+}
+/**
+ * The recommended foundation OU structure. Exported so callers can extend it
+ * rather than restate it.
+ */
+export const FOUNDATION_OUS = {
+    Security: { scps: ["deny-audit-tamper"] },
+    Infrastructure: {},
+    Sandbox: {},
+    Workloads: {},
+};
+/**
+ * Author the desired-state tree an external governance reconciler applies.
+ * Pure. Throws when the tree attaches an SCP name with no definition; only
+ * SCPs the tree actually attaches are included in the output.
+ */
+export function landingZoneConfig(props = {}) {
+    const foundation = props.foundation ?? true;
+    const scps = {
+        ...(foundation
+            ? { "deny-leave-organization": DENY_LEAVE_ORGANIZATION, "deny-audit-tamper": DENY_AUDIT_TAMPER }
+            : {}),
+        ...(props.allowedRegions?.length ? { "region-restriction": regionRestriction(props.allowedRegions) } : {}),
+        ...props.scps,
+    };
+    const ous = { ...(foundation ? FOUNDATION_OUS : {}), ...props.ous };
+    const rootScps = [
+        ...(foundation ? ["deny-leave-organization"] : []),
+        ...(props.allowedRegions?.length ? ["region-restriction"] : []),
+        ...(props.rootScps ?? []),
+    ];
+    const attached = new Set(rootScps);
+    const collect = (tree) => {
+        for (const node of Object.values(tree)) {
+            for (const s of node.scps ?? [])
+                attached.add(s);
+            if (node.children)
+                collect(node.children);
+        }
+    };
+    collect(ous);
+    for (const name of attached) {
+        if (!scps[name])
+            throw new Error(`landingZoneConfig: SCP "${name}" is attached but not defined in scps`);
+    }
+    if (props.identity) {
+        const granted = [...(props.identity.assignments ?? []), ...(props.identity.breakGlass ? [props.identity.breakGlass] : [])];
+        for (const a of granted) {
+            if (!props.identity.permissionSets[a.permissionSet]) {
+                throw new Error(`landingZoneConfig: assignment for "${a.principal}" references permission set "${a.permissionSet}" not defined in identity.permissionSets`);
+            }
+        }
+    }
+    return {
+        organization: rootScps.length ? { scps: rootScps } : {},
+        ous,
+        scps: Object.fromEntries(Object.entries(scps).filter(([n]) => attached.has(n))),
+        ...(props.identity ? { identity: props.identity } : {}),
+        ...(props.cloudtrailBucket
+            ? { auditSinks: { cloudtrail: { bucket: props.cloudtrailBucket, multiRegion: true } } }
+            : {}),
+    };
+}

package/dist/health.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Runtime health for AWS (#4177): Route 53 health checks and ECS services.
+ *
+ * The stack's own resource list maps each logical id (the graph's node id) to
+ * the physical id the health APIs take. A stack that does not exist yet means
+ * nothing is deployed, so every entity is absent. Any other stack failure is a
+ * hole for every entity, never `unhealthy`.
+ *
+ * - `AWS::Route53::HealthCheck`: `GetHealthCheckStatus`, aggregated as Route 53
+ *   does: healthy when more than 18% of the checkers report healthy.
+ * - `AWS::ECS::Service`: `DescribeServices`, `runningCount` against
+ *   `desiredCount`.
+ *
+ * Both go through the read transport's endpoint rule, so `AWS_ENDPOINT_URL`
+ * (Floci) answers them.
+ */
+import type { HealthEntry, HealthReadOptions, HealthReadResult } from "@intentius/chant/lexicon";
+import { type AwsReadClientOptions } from "./api/read-client.js";
+export declare const AWS_HEALTH_TYPES: readonly ["AWS::Route53::HealthCheck", "AWS::ECS::Service"];
+/** Injectable HTTP for both calls, so tests never reach the network. */
+export type AwsHealthHttp = (method: "GET" | "POST", url: string, init: {
+    headers: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    status: number;
+    text: string;
+}>;
+export interface AwsHealthOptions extends HealthReadOptions {
+    http?: AwsHealthHttp;
+    /** Read client for the stack list and the signing decision. Tests inject `http` and `env` here. */
+    client?: AwsReadClientOptions;
+    now?: () => Date;
+}
+/** One checker's report, as `GetHealthCheckStatus` returns it. */
+export interface CheckerObservation {
+    region?: string;
+    ipAddress?: string;
+    status: string;
+    checkedTime?: string;
+}
+/** Parse `GetHealthCheckStatusResponse`'s observations. */
+export declare function parseHealthCheckStatus(xml: string): CheckerObservation[];
+/** Route 53's verdict over its checkers' observations. */
+export declare function healthCheckEntry(observations: CheckerObservation[], observedAt: string): HealthEntry;
+/** The parts of an ECS service `DescribeServices` returns that decide health. */
+export interface EcsServiceState {
+    status?: string;
+    desiredCount?: number;
+    runningCount?: number;
+    pendingCount?: number;
+    deployments?: Array<{
+        rolloutState?: string;
+        updatedAt?: number | string;
+    }>;
+}
+/** Running against desired. Scaled to zero is `unknown`: nothing is serving, by choice. */
+export declare function ecsServiceEntry(service: EcsServiceState, observedAt: string): HealthEntry;
+/** The cluster a service ARN names: `service/<cluster>/<name>`, or the default cluster for the old `service/<name>` form. */
+export declare function clusterOfServiceArn(arn: string): string;
+export declare function observeHealthAws(options: AwsHealthOptions): Promise<HealthReadResult>;
+//# sourceMappingURL=health.d.ts.map

package/dist/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../src/health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,gBAAgB,EAAoB,MAAM,0BAA0B,CAAC;AACnH,OAAO,EASL,KAAK,oBAAoB,EAC1B,MAAM,mBAAmB,CAAC;AAI3B,eAAO,MAAM,gBAAgB,YAAI,2BAA2B,EAAE,mBAAmB,CAAU,CAAC;AAE5F,wEAAwE;AACxE,MAAM,MAAM,aAAa,GAAG,CAC1B,MAAM,EAAE,KAAK,GAAG,MAAM,EACtB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,KACrD,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAO/C,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IACzD,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,mGAAmG;IACnG,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAKD,kEAAkE;AAClE,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,2DAA2D;AAC3D,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAcxE;AAOD,0DAA0D;AAC1D,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,kBAAkB,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,WAAW,CAepG;AAED,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,KAAK,CAAC;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC,CAAC;CAC7E;AAED,2FAA2F;AAC3F,wBAAgB,eAAe,CAAC,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,GAAG,WAAW,CAazF;AAED,6HAA6H;AAC7H,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIvD;AAkED,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgF3F"}

package/dist/health.js

@@ -0,0 +1,216 @@
+/**
+ * Runtime health for AWS (#4177): Route 53 health checks and ECS services.
+ *
+ * The stack's own resource list maps each logical id (the graph's node id) to
+ * the physical id the health APIs take. A stack that does not exist yet means
+ * nothing is deployed, so every entity is absent. Any other stack failure is a
+ * hole for every entity, never `unhealthy`.
+ *
+ * - `AWS::Route53::HealthCheck`: `GetHealthCheckStatus`, aggregated as Route 53
+ *   does: healthy when more than 18% of the checkers report healthy.
+ * - `AWS::ECS::Service`: `DescribeServices`, `runningCount` against
+ *   `desiredCount`.
+ *
+ * Both go through the read transport's endpoint rule, so `AWS_ENDPOINT_URL`
+ * (Floci) answers them.
+ */
+import { AwsReadError, describeStackResources, requestHeaders, serviceUrl, withChainCredentials, withEndpointOverride, xmlError, xmlLeaves, } from "./api/read-client.js";
+import { resolveCredentials, signRequest } from "./api/sigv4.js";
+import { stackDoesNotExist } from "./stack-errors.js";
+export const AWS_HEALTH_TYPES = ["AWS::Route53::HealthCheck", "AWS::ECS::Service"];
+const defaultHttp = async (method, url, init) => {
+    const res = await fetch(url, { method, headers: init.headers, ...(init.body !== undefined ? { body: init.body } : {}) });
+    return { status: res.status, text: await res.text() };
+};
+/** Route 53 treats an endpoint as healthy when more than this share of checkers says so. */
+const ROUTE53_HEALTHY_SHARE = 0.18;
+/** Parse `GetHealthCheckStatusResponse`'s observations. */
+export function parseHealthCheckStatus(xml) {
+    const out = [];
+    for (const m of xml.matchAll(/<HealthCheckObservation>([\s\S]*?)<\/HealthCheckObservation>/g)) {
+        const body = m[1] ?? "";
+        const report = xmlLeaves(body.match(/<StatusReport>([\s\S]*?)<\/StatusReport>/)?.[1] ?? "");
+        const top = xmlLeaves(body.replace(/<StatusReport>[\s\S]*?<\/StatusReport>/, ""));
+        out.push({
+            ...(top.Region ? { region: top.Region } : {}),
+            ...(top.IPAddress ? { ipAddress: top.IPAddress } : {}),
+            status: report.Status ?? "",
+            ...(report.CheckedTime ? { checkedTime: report.CheckedTime } : {}),
+        });
+    }
+    return out;
+}
+/** A checker's status text starts with `Success` when it found the endpoint healthy. */
+function checkerHealthy(o) {
+    return /^success/i.test(o.status.trim());
+}
+/** Route 53's verdict over its checkers' observations. */
+export function healthCheckEntry(observations, observedAt) {
+    const type = "AWS::Route53::HealthCheck";
+    if (observations.length === 0) {
+        return { type, state: "unknown", detail: "no checker has reported yet", observedAt };
+    }
+    const healthy = observations.filter(checkerHealthy).length;
+    const latest = [...observations].sort((a, b) => (b.checkedTime ?? "").localeCompare(a.checkedTime ?? ""))[0];
+    const state = healthy / observations.length > ROUTE53_HEALTHY_SHARE ? "healthy" : "unhealthy";
+    return {
+        type,
+        state,
+        detail: `${healthy}/${observations.length} checkers healthy; last: ${latest.status}`,
+        observedAt,
+        ...(latest.checkedTime ? { checkedAt: latest.checkedTime } : {}),
+    };
+}
+/** Running against desired. Scaled to zero is `unknown`: nothing is serving, by choice. */
+export function ecsServiceEntry(service, observedAt) {
+    const type = "AWS::ECS::Service";
+    const desired = service.desiredCount ?? 0;
+    const running = service.runningCount ?? 0;
+    const pending = service.pendingCount ?? 0;
+    const counts = `${running}/${desired} running${pending > 0 ? `, ${pending} pending` : ""}`;
+    const rollout = service.deployments?.find((d) => d.rolloutState)?.rolloutState;
+    const detail = `${counts}${rollout ? `, rollout ${rollout}` : ""}`;
+    if (service.status && service.status !== "ACTIVE") {
+        return { type, state: "unhealthy", detail: `service is ${service.status}; ${detail}`, observedAt };
+    }
+    if (desired === 0)
+        return { type, state: "unknown", detail: `desired count is 0; ${detail}`, observedAt };
+    return { type, state: running >= desired ? "healthy" : "unhealthy", detail, observedAt };
+}
+/** The cluster a service ARN names: `service/<cluster>/<name>`, or the default cluster for the old `service/<name>` form. */
+export function clusterOfServiceArn(arn) {
+    const resource = arn.split(":").slice(5).join(":");
+    const parts = resource.split("/");
+    return parts.length >= 3 ? parts[1] : "default";
+}
+function holeFrom(type, err) {
+    const detail = err instanceof AwsReadError && err.code ? `${err.code}: ${err.message}` : err instanceof Error ? err.message : String(err);
+    const reason = /credential|token|expired|AccessDenied|not authorized|Unauthorized/i.test(detail) ? "no-credentials" : "read-failed";
+    return { type, reason, detail: detail.slice(0, 200) };
+}
+async function getHealthCheckStatus(id, client, http) {
+    const options = await withChainCredentials(withEndpointOverride("route53", client));
+    // Route 53 is global: one host, signed in us-east-1.
+    const base = (options.endpoint ?? "https://route53.amazonaws.com").replace(/\/$/, "");
+    const url = `${base}/2013-04-01/healthcheck/${encodeURIComponent(id)}/status`;
+    const env = options.env ?? process.env;
+    const credentials = resolveCredentials(options.credentials, env);
+    const signable = credentials && (!options.endpoint || options.signEndpointOverride === true);
+    const headers = signable
+        ? signRequest({ method: "GET", url, headers: {}, body: "", service: "route53", region: "us-east-1", credentials, ...(options.now ? { now: options.now } : {}) })
+        : {};
+    const res = await http("GET", url, { headers });
+    const err = xmlError(res.text);
+    if (err || res.status >= 400) {
+        throw new AwsReadError(err?.message ?? `GetHealthCheckStatus failed with HTTP ${res.status}`, res.status, err?.code);
+    }
+    return parseHealthCheckStatus(res.text);
+}
+async function describeServices(cluster, arns, client, http) {
+    const options = await withChainCredentials(withEndpointOverride("ecs", client));
+    const url = serviceUrl("ecs", options.endpoint, options.region);
+    const body = JSON.stringify({ cluster, services: arns });
+    const headers = requestHeaders("ecs", url, body, { "content-type": "application/x-amz-json-1.1", "x-amz-target": "AmazonEC2ContainerServiceV20141113.DescribeServices" }, options);
+    const res = await http("POST", url, { headers, body });
+    let parsed = {};
+    try {
+        const value = JSON.parse(res.text);
+        if (value && typeof value === "object" && !Array.isArray(value))
+            parsed = value;
+    }
+    catch {
+        throw new AwsReadError("unparseable DescribeServices response", res.status);
+    }
+    const errType = typeof parsed.__type === "string" ? parsed.__type.split("#").pop() : undefined;
+    if (errType || res.status >= 400) {
+        const message = typeof parsed.message === "string" ? parsed.message : `DescribeServices failed with HTTP ${res.status}`;
+        throw new AwsReadError(message, res.status, errType);
+    }
+    return {
+        services: Array.isArray(parsed.services) ? parsed.services : [],
+        failures: Array.isArray(parsed.failures) ? parsed.failures : [],
+    };
+}
+export async function observeHealthAws(options) {
+    const http = options.http ?? defaultHttp;
+    const observedAt = (options.now?.() ?? new Date()).toISOString();
+    const client = { ...(options.client ?? {}), ...(options.region ? { region: options.region } : {}) };
+    const entities = {};
+    const unobserved = {};
+    const absent = [];
+    if (options.entities.size === 0)
+        return { entities, unobserved, absent };
+    const stackName = options.stack ?? options.environment;
+    let physical;
+    try {
+        const resources = await describeStackResources(stackName, client);
+        physical = new Map(resources.filter((r) => r.physicalId).map((r) => [r.logicalId, r.physicalId]));
+    }
+    catch (err) {
+        if (err instanceof AwsReadError && stackDoesNotExist(err.message))
+            return { entities, unobserved, absent: [...options.entities.keys()] };
+        for (const [name, { entityType }] of options.entities) {
+            unobserved[name] = holeFrom(entityType, err);
+            unobserved[name].detail = `DescribeStackResources failed for stack "${stackName}": ${unobserved[name].detail}`;
+        }
+        return { entities, unobserved, absent };
+    }
+    const services = new Map();
+    const checks = [];
+    for (const [name, { entityType }] of options.entities) {
+        const id = physical.get(name);
+        if (!id) {
+            absent.push(name);
+            continue;
+        }
+        if (entityType === "AWS::ECS::Service") {
+            const cluster = clusterOfServiceArn(id);
+            const list = services.get(cluster) ?? [];
+            list.push({ name, arn: id });
+            services.set(cluster, list);
+        }
+        else if (entityType === "AWS::Route53::HealthCheck") {
+            checks.push({ name, id });
+        }
+    }
+    await Promise.all(checks.map(async ({ name, id }) => {
+        try {
+            entities[name] = healthCheckEntry(await getHealthCheckStatus(id, client, http), observedAt);
+        }
+        catch (err) {
+            if (err instanceof AwsReadError && err.code === "NoSuchHealthCheck")
+                absent.push(name);
+            else
+                unobserved[name] = holeFrom("AWS::Route53::HealthCheck", err);
+        }
+    }));
+    await Promise.all([...services].map(async ([cluster, members]) => {
+        // DescribeServices takes at most ten services per call.
+        for (let i = 0; i < members.length; i += 10) {
+            const batch = members.slice(i, i + 10);
+            try {
+                const { services: found, failures } = await describeServices(cluster, batch.map((m) => m.arn), client, http);
+                for (const member of batch) {
+                    const service = found.find((s) => s.serviceArn === member.arn || s.serviceArn?.endsWith(`/${member.arn.split("/").pop()}`));
+                    const failure = failures.find((f) => f.arn === member.arn);
+                    if (service)
+                        entities[member.name] = ecsServiceEntry(service, observedAt);
+                    else if (failure?.reason === "MISSING")
+                        absent.push(member.name);
+                    else {
+                        unobserved[member.name] = {
+                            type: "AWS::ECS::Service",
+                            reason: "read-failed",
+                            detail: failure?.reason ? `DescribeServices: ${failure.reason}` : "DescribeServices did not return the service",
+                        };
+                    }
+                }
+            }
+            catch (err) {
+                for (const member of batch)
+                    unobserved[member.name] = holeFrom("AWS::ECS::Service", err);
+            }
+        }
+    }));
+    return { entities, unobserved, absent };
+}

package/dist/identity-observe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"identity-observe.d.ts","sourceRoot":"","sources":["../src/identity-observe.ts"],"names":[],"mappings":"AAwBA,OAAO,EAA4C,KAAK,oBAAoB,EAAgC,MAAM,mBAAmB,CAAC;AACtI,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAmBjE;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAazG;AAkCD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EAAE,EACrB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,GAAG,SAAS,EACzF,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,EACzC,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC,CA4B3F"}
+{"version":3,"file":"identity-observe.d.ts","sourceRoot":"","sources":["../src/identity-observe.ts"],"names":[],"mappings":"AAyBA,OAAO,EAA4C,KAAK,oBAAoB,EAAgC,MAAM,mBAAmB,CAAC;AACtI,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAmBjE;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAazG;AAkCD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EAAE,EACrB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,GAAG,SAAS,EACzF,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,EACzC,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC,CA4B3F"}

package/dist/identity-observe.js

@@ -0,0 +1,127 @@
+/**
+ * The identity fallback on the stack read (#1647).
+ *
+ * `describeResources` asks CloudFormation exactly one question — is there a
+ * logical id named <entity> in this stack? — which reads a freshly
+ * carve-emitted, still-Terraform-owned resource as confirmed-absent even
+ * though the declared `BucketName` names it precisely. When a declared entity
+ * is absent from the stack AND its props spell the type's full primary
+ * identifier (the spec knowledge the codegen already compiled into
+ * `lexicon-aws.json`), ask Cloud Control for it by identity. Found means
+ * OBSERVED: `ownership: "foreign"` (it exists and something other than this
+ * stack owns it — Terraform, a console hand, another tool) and
+ * `status: "EXTERNAL"` (live outside the stack, deliberately not a
+ * CloudFormation status word).
+ *
+ * Best-effort ON TOP of a stack answer, never instead of one: a genuine miss
+ * (`ResourceNotFoundException`) keeps the stack's absent verdict, and so does
+ * every other refusal (`UnsupportedOperation` — a Floci without Cloud
+ * Control — credentials, throttling). The stack read succeeded; absence at
+ * stack scope is an honest verdict this fallback can refine but must never
+ * degrade into a hole, or a pre-first-apply plan would stop proposing
+ * `create` the moment the emulator lacks Cloud Control.
+ */
+import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
+import { AwsReadError, getResource, listResources } from "./api/read-client.js";
+const require = createRequire(moduleSourceUrl(import.meta.url));
+let byResourceType;
+function manifestByType() {
+    if (!byResourceType) {
+        const manifest = require("./generated/lexicon-aws.json");
+        byResourceType = new Map(Object.values(manifest).map((e) => [e.resourceType, e]));
+    }
+    return byResourceType;
+}
+/**
+ * The Cloud Control identifier the declared props spell, or undefined when the
+ * type has no primary identifier on record or any part of it is absent or
+ * non-scalar (a Ref, an intrinsic, a server-assigned name). Multi-part
+ * identifiers join with `|`, Cloud Control's own separator.
+ */
+export function declaredIdentifier(entityType, props) {
+    const entry = manifestByType().get(entityType);
+    const parts = entry?.primaryIdentifier;
+    if (!entry || entry.kind !== "resource" || !parts || parts.length === 0)
+        return undefined;
+    const values = [];
+    for (const part of parts) {
+        const v = props[part];
+        if (typeof v !== "string" && typeof v !== "number")
+            return undefined;
+        const s = String(v);
+        if (!s)
+            return undefined;
+        values.push(s);
+    }
+    return values.join("|");
+}
+/**
+ * `GetResource`, with a `ListResources` + identifier-match fallback when the
+ * endpoint says the operation itself is unsupported. That is Floci's exact
+ * answer (read-client's own note) while it serves `ListResources` fine — and
+ * an emulator is exactly where the carve state lives, so without this leg the
+ * fallback proves itself everywhere except the one place the walkthrough
+ * films it. Every other refusal propagates: the caller decides what a failed
+ * refinement means.
+ */
+async function readByIdentity(typeName, identifier, client) {
+    try {
+        return await getResource(typeName, identifier, client);
+    }
+    catch (err) {
+        if (!(err instanceof AwsReadError) || err.code !== "UnsupportedOperation")
+            throw err;
+        const listed = await listResources(typeName, client);
+        return listed.find((d) => d.identifier === identifier) ?? null;
+    }
+}
+/** The same scrub the stack-output path applies, on live property KEYS. */
+function redactSensitive(properties) {
+    const out = {};
+    for (const [key, value] of Object.entries(properties)) {
+        out[key] = /password|secret|token/i.test(key) ? "[REDACTED]" : value;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Identity-read every entity the stack did not answer for and whose props
+ * spell an identifier. `already` is the stack's answer — an entity the stack
+ * DID return is never re-read. The `queried` map records the address each
+ * attempted read was issued against (#1620), whatever the verdict.
+ */
+export async function observeByIdentity(entityNames, entities, already, client) {
+    const resources = {};
+    const queried = {};
+    if (!entities)
+        return { resources, queried };
+    for (const name of entityNames) {
+        if (already[name])
+            continue;
+        const entity = entities.get(name);
+        if (!entity)
+            continue;
+        const identifier = declaredIdentifier(entity.entityType, entity.props ?? {});
+        if (!identifier)
+            continue;
+        queried[name] = `cloudcontrol:GetResource:${entity.entityType}:${identifier}`;
+        try {
+            const found = await readByIdentity(entity.entityType, identifier, client);
+            if (!found)
+                continue;
+            resources[name] = {
+                type: entity.entityType,
+                physicalId: found.identifier || identifier,
+                status: "EXTERNAL",
+                ownership: "foreign",
+                ...(redactSensitive(found.properties) ? { attributes: redactSensitive(found.properties) } : {}),
+            };
+        }
+        catch {
+            // Refusals of every kind keep the stack's verdict — see the module
+            // comment for why a failed refinement must not become a hole.
+            continue;
+        }
+    }
+    return { resources, queried };
+}