@intentius/chant-lexicon-aws 0.124.31 → 0.124.33

package/dist/properties.js

@@ -0,0 +1,166 @@
+/**
+ * A managed resource's own properties (#1279).
+ *
+ * `describe-stack-resources` returns identity and status — logical id, physical
+ * id, type, timestamp — and nothing about the resource itself. So the managed
+ * observation filled `attributes` with the *stack's* outputs instead, copied
+ * onto every resource in the stack. Every node in a stack came out carrying the
+ * same `expVpcId`/`expWebIp` keys, and no node carried its own `VpcId`.
+ *
+ * That is invisible until something asks. `search --show VpcId` printed a blank
+ * column for six instances, which reads as "the estate has no VPCs" rather than
+ * "chant never read that". An agent asked which instances were outside the
+ * default VPC concluded all six were, because nothing in the graph said
+ * otherwise.
+ *
+ * A deep read (Cloud Control) answers this properly but is a per-resource call
+ * and is not available on every endpoint. This is the cheap middle: one describe
+ * per kind for the whole observation, joined back by physical id. Stack outputs
+ * no longer ride the resource at all — they are the stack's, and travel on the
+ * observation envelope's `stackExports`. Whatever a resource already carries is
+ * kept underneath its own properties, which win a name collision because they
+ * are the resource's.
+ */
+import { applyAwsEndpointArgv } from "./components/cloud-executor.js";
+/**
+ * How to read each kind in bulk, and which field joins back to the physical id.
+ *
+ * Extending this is the way to widen coverage. Deliberately batch calls: one
+ * `describe-instances` for every instance in the stack, not one per instance.
+ */
+const DESCRIBE = {
+    "AWS::EC2::Instance": {
+        argv: ["ec2", "describe-instances"],
+        idFlag: "--instance-ids",
+        key: "Reservations",
+        nested: "Instances",
+        id: "InstanceId",
+    },
+    "AWS::EC2::VPC": { argv: ["ec2", "describe-vpcs"], idFlag: "--vpc-ids", key: "Vpcs", id: "VpcId" },
+    "AWS::EC2::Subnet": {
+        argv: ["ec2", "describe-subnets"],
+        idFlag: "--subnet-ids",
+        key: "Subnets",
+        id: "SubnetId",
+    },
+    "AWS::EC2::SecurityGroup": {
+        argv: ["ec2", "describe-security-groups"],
+        idFlag: "--group-ids",
+        key: "SecurityGroups",
+        id: "GroupId",
+    },
+};
+/**
+ * Stamp the region each resource was observed in (#1279).
+ *
+ * The observation is already scoped per stack and each stack declares its
+ * region, so the reader knows this and was throwing it away. Without it the
+ * only route to "which region is this in" was parsing
+ * `Placement.AvailabilityZone` and trimming the last character — a trick that
+ * happens to work for EC2 and for nothing else. Region is a dimension of the
+ * estate, not a substring of an availability zone.
+ */
+export function stampRegion(resources, region) {
+    // Fall back to the region the call would actually have used, so a
+    // single-region project gets the same attribute a multi-region one does.
+    const value = region ?? process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION;
+    if (!value)
+        return resources;
+    const stamped = {};
+    for (const [name, meta] of Object.entries(resources)) {
+        stamped[name] = { ...meta, attributes: { ...(meta.attributes ?? {}), region: value } };
+    }
+    return stamped;
+}
+/** True when this lexicon can read the kind's own properties. */
+export function canDescribe(kind) {
+    return kind in DESCRIBE;
+}
+/**
+ * Merge each resource's own properties into an observation, in place of nothing.
+ *
+ * Best-effort per kind: an endpoint that cannot answer `describe-subnets` still
+ * yields instance properties. A miss costs detail — with one exception that used
+ * to be silent and is now reported.
+ *
+ * The exception (#1206): these attributes are compared by `lifecycle diff`, so a
+ * read that fails after the resource is already identified does not degrade to
+ * "less detail", it degrades to *drift* — the snapshot has `GroupId`, the live
+ * read has nothing, and the differ reports the property as removed. A partial
+ * failure still rides the best-effort path, but a total one is a hole the caller
+ * has to declare rather than a thinner set of facts.
+ */
+export async function describeOwnProperties(resources, region) {
+    // Group the physical ids to look up by kind, so each kind is one call.
+    const wanted = new Map();
+    for (const [name, meta] of Object.entries(resources)) {
+        if (!meta.physicalId || !canDescribe(meta.type))
+            continue;
+        const byId = wanted.get(meta.type) ?? new Map();
+        byId.set(meta.physicalId, [...(byId.get(meta.physicalId) ?? []), name]);
+        wanted.set(meta.type, byId);
+    }
+    if (wanted.size === 0)
+        return { resources, transportFailed: false, failures: new Map() };
+    const { getRuntime } = await import("@intentius/chant/runtime-adapter");
+    const rt = getRuntime();
+    const regionArgs = region ? ["--region", region] : [];
+    const merged = { ...resources };
+    const failures = new Map();
+    /** The last failure for a kind, phrased for a human — stderr when there is any, the exit status otherwise. */
+    let lastReason = "";
+    /** One describe for a set of ids. `null` when the call itself failed. */
+    const read = async (spec, ids) => {
+        const argv = ["aws", ...spec.argv, spec.idFlag, ...ids, ...regionArgs, "--output", "json"];
+        const result = await rt.spawn(applyAwsEndpointArgv(argv, process.env.AWS_ENDPOINT_URL));
+        if (result.exitCode !== 0) {
+            const stderr = result.stderr.trim().split("\n")[0];
+            lastReason = `${spec.argv.join(" ")} failed${stderr ? `: ${stderr}` : ` (${result.exitCode})`}`;
+            return null;
+        }
+        return (JSON.parse(result.stdout)[spec.key] ?? []);
+    };
+    for (const [kind, byId] of wanted) {
+        const spec = DESCRIBE[kind];
+        try {
+            const ids = [...byId.keys()];
+            let top = await read(spec, ids);
+            // AWS fails the whole call on one bad id — a snapshot naming an instance
+            // that has since been terminated takes every other instance's properties
+            // down with it, and the result is indistinguishable from "the account has
+            // nothing to say". Retry one at a time so the damage stops at the bad id.
+            if (top === null && ids.length > 1) {
+                const perId = await Promise.all(ids.map((id) => read(spec, [id])));
+                // Every retry failing is the kind failing, not the kind being empty —
+                // the distinction the old `top = []` erased.
+                top = perId.every((r) => r === null) ? null : perId.flatMap((r) => r ?? []);
+            }
+            if (top === null) {
+                failures.set(kind, lastReason);
+                continue;
+            }
+            // `describe-instances` buries instances one level down under reservations;
+            // the others return the resources directly.
+            const rows = spec.nested
+                ? top.flatMap((r) => (r[spec.nested] ?? []))
+                : top;
+            for (const row of rows) {
+                const id = row[spec.id];
+                if (typeof id !== "string")
+                    continue;
+                for (const name of byId.get(id) ?? []) {
+                    merged[name] = {
+                        ...merged[name],
+                        // Own properties last: a resource's `VpcId` outranks anything the
+                        // entry already carried under the same name.
+                        attributes: { ...(merged[name].attributes ?? {}), ...row },
+                    };
+                }
+            }
+        }
+        catch (err) {
+            failures.set(kind, `${spec.argv.join(" ")} failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return { resources: merged, transportFailed: failures.size === wanted.size, failures };
+}

package/dist/pseudo.js

@@ -0,0 +1,25 @@
+import { PseudoParameter, createPseudoParameters } from "@intentius/chant/pseudo-parameter";
+export { PseudoParameter };
+export const { StackName, Region, AccountId, StackId, URLSuffix, NoValue, NotificationARNs, Partition } = createPseudoParameters({
+    StackName: "AWS::StackName",
+    Region: "AWS::Region",
+    AccountId: "AWS::AccountId",
+    StackId: "AWS::StackId",
+    URLSuffix: "AWS::URLSuffix",
+    NoValue: "AWS::NoValue",
+    NotificationARNs: "AWS::NotificationARNs",
+    Partition: "AWS::Partition",
+});
+/**
+ * AWS namespace containing all pseudo-parameters
+ */
+export const AWS = {
+    StackName,
+    Region,
+    AccountId,
+    StackId,
+    URLSuffix,
+    NoValue,
+    NotificationARNs,
+    Partition,
+};

package/dist/receipt-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"receipt-store.d.ts","sourceRoot":"","sources":["../src/receipt-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EAAoB,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAKL,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,WAAW,EACjB,MAAM,mBAAmB,CAAC;AAO3B;0EAC0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC;6DACyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;6EACyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB;0DACsD;IACtD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,wDAAwD;IACxD,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,iFAAiF;IACjF,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;iDACiD;AACjD,wBAAsB,OAAO,CAC3B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,CAyB5D;AAED;uCACuC;AACvC,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAI9E;AAQD;;;GAGG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQ7B;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,IAAI,CAAC,CAiBf;AA4CD,wEAAwE;AACxE,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC5C,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,gBAAgB,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EAAE,EACrB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,qBAAqB,CAAC,CA+ChC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,YAAY,CAyBlF"}
+{"version":3,"file":"receipt-store.d.ts","sourceRoot":"","sources":["../src/receipt-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EAAoB,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAML,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,WAAW,EACjB,MAAM,mBAAmB,CAAC;AAO3B;0EAC0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC;6DACyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;6EACyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB;0DACsD;IACtD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,wDAAwD;IACxD,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,iFAAiF;IACjF,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;iDACiD;AACjD,wBAAsB,OAAO,CAC3B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,CAyB5D;AAED;uCACuC;AACvC,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAI9E;AAQD;;;GAGG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQ7B;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,IAAI,CAAC,CAiBf;AA4CD,wEAAwE;AACxE,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC5C,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,gBAAgB,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EAAE,EACrB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,qBAAqB,CAAC,CA+ChC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,YAAY,CAyBlF"}

package/dist/receipt-store.js

@@ -0,0 +1,233 @@
+/**
+ * The aws `ReceiptStore` (#1835, epic #1703) — core's injectable receipt seam
+ * (#1834, `@intentius/chant/op/receipt-store`) implemented over SSM Parameter
+ * Store, plain `String`, at the path identity ./effect-receipt-row.ts derives
+ * from the ownership marker fields.
+ *
+ * The transport is the lexicon's own read/apply transport (./api/read-client,
+ * #1206), pointed at the SSM JSON API: `fetch`, SigV4 when credentials
+ * resolve, and the one endpoint-override rule (#1694) — the `endpoint`
+ * option, else `AWS_ENDPOINT_URL_SSM`, else `AWS_ENDPOINT_URL` — so a local
+ * emulator lane reads and writes receipts without any store-specific wiring.
+ *
+ * Write discipline (epic decision 3): `write` exists for the `effect()` step
+ * alone — the step's read-compare-run-write is the only path that reaches it,
+ * on success, last. `PutParameter` is `Type: "String"` always; the first
+ * write creates the parameter with the ownership tags, and a later write
+ * overwrites the value (SSM refuses `Overwrite` and `Tags` in one call, so
+ * tags ride creation only — they never change after).
+ *
+ * Identity: the parameter name needs `<stack>` and `<env>`, which the
+ * activity args deliberately do not carry (the `EffectReceiptRef` is
+ * identity-of-the-effect, not identity-of-the-deployment). The store resolves
+ * them once, lazily, at first use: an explicit option, else `CHANT_ENV` (what
+ * `chant run --env` sets) and the project's `ownership` block — the same
+ * fields that stamp markers (epic decision 4). Nothing resolving is an error,
+ * never a guessed segment.
+ */
+import { loadChantConfigUpward, resolveOwnershipStack } from "@intentius/chant/config";
+import { ownershipEntries } from "@intentius/chant/ownership";
+import { AwsReadError, requestHeaders, serviceUrl, withChainCredentials, withEndpointOverride, } from "./api/read-client.js";
+import { AWS_TAG_OWNERSHIP_KEYS } from "./ownership.js";
+import { AWS_EFFECT_RECEIPT_ENTITY_TYPE, EFFECT_RECEIPTS_METADATA_KEY, receiptParameterName } from "./effect-receipt-row.js";
+const SSM_SERVICE = "ssm";
+const SSM_TARGET_PREFIX = "AmazonSSM";
+/** One SSM JSON call. Exported for the observation leg (plugin.ts), which
+ * reads the same parameters the store writes. */
+export async function ssmCall(action, payload, options) {
+    const settled = await withChainCredentials(withEndpointOverride(SSM_SERVICE, options));
+    const url = serviceUrl(SSM_SERVICE, settled.endpoint, settled.region);
+    const body = JSON.stringify(payload);
+    const base = {
+        "content-type": "application/x-amz-json-1.1",
+        "x-amz-target": `${SSM_TARGET_PREFIX}.${action}`,
+    };
+    const headers = requestHeaders(SSM_SERVICE, url, body, base, settled);
+    const http = settled.http ??
+        (async (u, init, signal) => {
+            const res = await fetch(u, { method: "POST", headers: init.headers, body: init.body, signal });
+            return { status: res.status, text: await res.text() };
+        });
+    const res = await http(url, { headers, body }, settled.signal);
+    let json = {};
+    try {
+        json = res.text ? JSON.parse(res.text) : {};
+    }
+    catch {
+        if (res.status < 400) {
+            throw new AwsReadError(`SSM ${action}: unparseable response (status ${res.status})`, res.status);
+        }
+    }
+    return { status: res.status, json };
+}
+/** The API's own error code from a JSON-protocol error body — `__type`, with
+ * any `namespace#` prefix stripped. */
+export function ssmErrorCode(json) {
+    const type = json.__type;
+    if (typeof type !== "string")
+        return undefined;
+    return type.includes("#") ? type.slice(type.indexOf("#") + 1) : type;
+}
+function ssmError(action, status, json) {
+    const code = ssmErrorCode(json);
+    const message = typeof json.message === "string" ? json.message : typeof json.Message === "string" ? json.Message : "";
+    return new AwsReadError(`SSM ${action} failed (status ${status})${code ? ` ${code}` : ""}${message ? `: ${message}` : ""}`, status, code);
+}
+/**
+ * `GetParameter` by name. Absent (`ParameterNotFound`) is `undefined` — a real
+ * answer, distinct from a failed read, which throws.
+ */
+export async function ssmGetParameter(name, options = {}) {
+    const { status, json } = await ssmCall("GetParameter", { Name: name }, options);
+    if (status >= 400) {
+        if (ssmErrorCode(json) === "ParameterNotFound")
+            return undefined;
+        throw ssmError("GetParameter", status, json);
+    }
+    const value = json.Parameter?.Value;
+    return typeof value === "string" ? value : undefined;
+}
+/**
+ * `PutParameter`, plain `String`. Creation carries `tags`; an existing
+ * parameter is overwritten (`Overwrite: true`) without them — SSM refuses
+ * `Overwrite` and `Tags` in the same call, and ownership tags never change.
+ */
+export async function ssmPutParameter(name, value, tags, options = {}) {
+    const tagList = Object.entries(tags).map(([Key, Value]) => ({ Key, Value }));
+    const create = await ssmCall("PutParameter", { Name: name, Value: value, Type: "String", ...(tagList.length > 0 ? { Tags: tagList } : {}) }, options);
+    if (create.status < 400)
+        return;
+    if (ssmErrorCode(create.json) !== "ParameterAlreadyExists") {
+        throw ssmError("PutParameter", create.status, create.json);
+    }
+    const overwrite = await ssmCall("PutParameter", { Name: name, Value: value, Type: "String", Overwrite: true }, options);
+    if (overwrite.status >= 400)
+        throw ssmError("PutParameter", overwrite.status, overwrite.json);
+}
+async function resolveIdentity(options) {
+    const processEnv = options.env ?? process.env;
+    let stack = options.stack;
+    let env = options.environment ?? processEnv.CHANT_ENV;
+    if (!stack || !env) {
+        let config;
+        try {
+            config = (await loadChantConfigUpward(options.cwd ?? process.cwd())).config;
+        }
+        catch {
+            config = undefined;
+        }
+        if (config) {
+            stack = stack ?? resolveOwnershipStack(config);
+            // Only a literal env can answer here: a `{ param }` reference resolves
+            // per build, and an op run has no build parameters — `--env` does.
+            const configEnv = config.ownership?.env;
+            env = env ?? (typeof configEnv === "string" ? configEnv : undefined);
+        }
+    }
+    if (!stack) {
+        throw new Error("aws receipt store: no stack identity — the receipt path is " +
+            "/chant-receipts/<stack>/<env>/<effect>, derived from the same ownership fields that stamp " +
+            "markers (chant #1703, decision 4). Set ownership: { stack } in chant.config.ts.");
+    }
+    if (!env) {
+        throw new Error("aws receipt store: no environment resolved — the receipt path's <env> segment is explicit " +
+            "(chant #1703, decision 4). Run with --env <name>, set CHANT_ENV, or set a literal " +
+            "ownership.env in chant.config.ts.");
+    }
+    return { stack, env };
+}
+/**
+ * The plan-side live read of the receipt rows (#1835's observation leg).
+ *
+ * A receipt is not a stack member — the applier never writes it (#1832) — so
+ * `describe-stack-resources` honestly reports it absent even while the
+ * parameter exists. The serializer renders each receipt's derived path into
+ * the template's `Metadata` (./serializer.ts), so this leg reads the paths
+ * back from the build output — one derivation, decision 4 — and asks SSM
+ * `GetParameter` for each. Present maps the stored value onto
+ * `attributes.value` (core's `RECEIPT_VALUE_ATTRIBUTE`); `ParameterNotFound`
+ * is a real absence and stays one; a failed read is an `unobserved` hole,
+ * never a wrong answer — a receipt nobody could read must not arrive
+ * downstream as "the effect never ran".
+ */
+export async function observeReceiptRows(entityNames, buildOutput, options = {}) {
+    const out = { resources: {}, unobserved: {} };
+    let rows;
+    try {
+        const template = JSON.parse(buildOutput);
+        const block = template.Metadata?.[EFFECT_RECEIPTS_METADATA_KEY];
+        if (typeof block === "object" && block !== null) {
+            rows = block;
+        }
+    }
+    catch {
+        rows = undefined; // Not a JSON template — no receipt rows to read.
+    }
+    if (!rows)
+        return out;
+    for (const name of entityNames) {
+        const rendered = rows[name]?.Properties?.Name;
+        if (typeof rendered !== "string")
+            continue;
+        try {
+            const value = await ssmGetParameter(rendered, options);
+            if (value === undefined)
+                continue; // Confirmed absent — the effect has not stamped it yet.
+            out.resources[name] = {
+                type: AWS_EFFECT_RECEIPT_ENTITY_TYPE,
+                physicalId: rendered,
+                // Live outside the stack by design — the same word the identity
+                // fallback (#1647) uses for a resource CloudFormation does not hold.
+                status: "EXTERNAL",
+                // GetParameter returns no tags, so the marker channel is unreadable
+                // here; `unknown` is the total verdict, never a guess (#1089).
+                ownership: "unknown",
+                attributes: { value },
+            };
+        }
+        catch (err) {
+            const detail = err instanceof AwsReadError && err.code
+                ? `${err.code}: ${err.message}`
+                : String(err instanceof Error ? err.message : err);
+            const reason = /credential|token|expired|AccessDenied|not authorized|Unauthorized/i.test(detail)
+                ? "no-credentials"
+                : "read-failed";
+            out.unobserved[name] = {
+                type: AWS_EFFECT_RECEIPT_ENTITY_TYPE,
+                reason,
+                detail: `GetParameter failed for receipt "${rendered}": ${detail}`,
+            };
+        }
+    }
+    return out;
+}
+/**
+ * The `ReceiptStore` over SSM. Bind it once in the op activities barrel —
+ * `receiptActivities(awsReceiptStore())` — and the registry resolves
+ * `receiptRead`/`receiptWrite`/`receiptStaleness` by name, exactly like
+ * `ensureSecret` (#1830). Identity and endpoint resolve lazily at first use,
+ * so module load never reads the project or the environment.
+ */
+export function awsReceiptStore(options = {}) {
+    let identity;
+    const identityOf = () => (identity ?? (identity = resolveIdentity(options)));
+    const client = () => ({
+        ...(options.endpoint !== undefined ? { endpoint: options.endpoint } : {}),
+        ...(options.region !== undefined ? { region: options.region } : {}),
+        ...(options.http !== undefined ? { http: options.http } : {}),
+        ...(options.env !== undefined ? { env: options.env } : {}),
+        ...(options.credentials !== undefined ? { credentials: options.credentials } : {}),
+        ...(options.signEndpointOverride !== undefined ? { signEndpointOverride: options.signEndpointOverride } : {}),
+    });
+    return {
+        async read(receipt) {
+            const { stack, env } = await identityOf();
+            return ssmGetParameter(receiptParameterName(stack, env, receipt.effect), client());
+        },
+        async write(receipt, expectation) {
+            const { stack, env } = await identityOf();
+            const tags = ownershipEntries(AWS_TAG_OWNERSHIP_KEYS, { stack, env });
+            await ssmPutParameter(receiptParameterName(stack, env, receipt.effect), expectation, tags, client());
+        },
+    };
+}

package/dist/reference-catalog.js

@@ -0,0 +1,106 @@
+/**
+ * AWS reference catalog (#778, epic #776 v1) — how observed AWS resources
+ * reference each other, so `chant graph --live` can reconstruct the topology.
+ *
+ * Keyed to the per-resource describe/export attribute shape (`VpcId`,
+ * `SecurityGroups[].GroupId`, `TargetGroupArn`, …), not the thin
+ * `describe-stack-resources` metadata. Enough to draw the canonical 3-tier VPC
+ * (internet → ALB → ECS service → RDS, with SG attachments). `containment`
+ * relations (subnet ∈ VPC) feed #779's boundary boxes; `reference` relations are
+ * edges.
+ */
+export const awsReferenceCatalog = {
+    identities: [
+        { kind: "AWS::EC2::VPC", ids: ["VpcId"] },
+        { kind: "AWS::EC2::Subnet", ids: ["SubnetId"] },
+        { kind: "AWS::EC2::SecurityGroup", ids: ["GroupId"] },
+        { kind: "AWS::EC2::NetworkInterface", ids: ["NetworkInterfaceId"] },
+        { kind: "AWS::EC2::Instance", ids: ["InstanceId"] },
+        { kind: "AWS::EC2::InternetGateway", ids: ["InternetGatewayId"] },
+        { kind: "AWS::EC2::NatGateway", ids: ["NatGatewayId"] },
+        { kind: "AWS::EC2::RouteTable", ids: ["RouteTableId"] },
+        { kind: "AWS::EC2::LaunchTemplate", ids: ["LaunchTemplateId", "LaunchTemplateName"] },
+        { kind: "AWS::ElasticLoadBalancingV2::LoadBalancer", ids: ["LoadBalancerArn", "DNSName"] },
+        { kind: "AWS::ElasticLoadBalancingV2::TargetGroup", ids: ["TargetGroupArn"] },
+        { kind: "AWS::ECS::Cluster", ids: ["ClusterArn", "ClusterName"] },
+        { kind: "AWS::ECS::Service", ids: ["ServiceArn"] },
+        { kind: "AWS::ECS::TaskDefinition", ids: ["TaskDefinitionArn"] },
+        { kind: "AWS::RDS::DBInstance", ids: ["DBInstanceArn", "Endpoint.Address"] },
+    ],
+    refs: [
+        // ── containment (→ boundary boxes, #779) ──
+        { from: "AWS::EC2::Subnet", path: "VpcId", targetKind: "AWS::EC2::VPC", relation: "containment", label: "in VPC" },
+        { from: "AWS::EC2::SecurityGroup", path: "VpcId", targetKind: "AWS::EC2::VPC", relation: "containment", label: "in VPC" },
+        { from: "AWS::EC2::RouteTable", path: "VpcId", targetKind: "AWS::EC2::VPC", relation: "containment", label: "in VPC" },
+        { from: "AWS::EC2::Instance", path: "SubnetId", targetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet", viaAttr: "SubnetId" },
+        // An instance is in a VPC, and `describe-instances` says so directly. The
+        // other three kinds that sit in a VPC — subnet, security group, route table
+        // — all had this rule; the instance did not, so the estate's own topology
+        // was missing its most-asked-about member. Nothing derived it either: the
+        // instance reached its VPC only through its subnet, two hops, which a
+        // one-hop `<-` cannot cross.
+        { from: "AWS::EC2::Instance", path: "VpcId", targetKind: "AWS::EC2::VPC", relation: "containment", label: "in VPC" },
+        { from: "AWS::EC2::NatGateway", path: "SubnetId", targetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet" },
+        { from: "AWS::ElasticLoadBalancingV2::LoadBalancer", path: "AvailabilityZones[].SubnetId", targetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet" },
+        { from: "AWS::ElasticLoadBalancingV2::TargetGroup", path: "VpcId", targetKind: "AWS::EC2::VPC", relation: "containment", label: "in VPC" },
+        { from: "AWS::ECS::Service", path: "NetworkConfiguration.AwsvpcConfiguration.Subnets[]", targetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet" },
+        { from: "AWS::RDS::DBInstance", path: "DBSubnetGroup.Subnets[].SubnetIdentifier", targetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet" },
+        // ── references (→ edges) ──
+        { from: "AWS::EC2::Instance", path: "SecurityGroups[].GroupId", targetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg", viaAttr: "SecurityGroupIds" },
+        { from: "AWS::EC2::Instance", path: "SecurityGroupIds[]", targetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg", viaAttr: "SecurityGroupIds" },
+        // Security groups reached indirectly, through a launch template — the hop a
+        // flat describe-instances sweep misses, and the reason `effectiveIngress`
+        // exists as a fold rather than a passthrough.
+        { from: "AWS::EC2::Instance", path: "LaunchTemplate.LaunchTemplateId", targetKind: "AWS::EC2::LaunchTemplate", relation: "reference", label: "from template", viaAttr: "LaunchTemplateId" },
+        { from: "AWS::EC2::Instance", path: "LaunchTemplateId", targetKind: "AWS::EC2::LaunchTemplate", relation: "reference", label: "from template", viaAttr: "LaunchTemplateId" },
+        { from: "AWS::EC2::LaunchTemplate", path: "LaunchTemplateData.SecurityGroupIds[]", targetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg", viaAttr: "SecurityGroupIds" },
+        { from: "AWS::EC2::LaunchTemplate", path: "SecurityGroupIds[]", targetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg", viaAttr: "SecurityGroupIds" },
+        // The routing chain `internetFacing` walks. Route and association carry no
+        // physical id of their own, so they are only ever the `from` side.
+        { from: "AWS::EC2::Route", path: "RouteTableId", targetKind: "AWS::EC2::RouteTable", relation: "reference", label: "in table", viaAttr: "RouteTableId" },
+        { from: "AWS::EC2::SubnetRouteTableAssociation", path: "SubnetId", targetKind: "AWS::EC2::Subnet", relation: "reference", label: "associates", viaAttr: "SubnetId" },
+        { from: "AWS::EC2::SubnetRouteTableAssociation", path: "RouteTableId", targetKind: "AWS::EC2::RouteTable", relation: "reference", label: "to table", viaAttr: "RouteTableId" },
+        { from: "AWS::EC2::SecurityGroup", path: "IpPermissions[].UserIdGroupPairs[].GroupId", targetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "allows" },
+        // An ENI is where a security group is attached and where an instance's
+        // networking actually lives, so both edges are what make "unused" and
+        // "reachable" answerable from the graph rather than from a provider sweep.
+        { from: "AWS::EC2::NetworkInterface", path: "Groups[].GroupId", targetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg", viaAttr: "Groups" },
+        { from: "AWS::EC2::NetworkInterface", path: "Attachment.InstanceId", targetKind: "AWS::EC2::Instance", relation: "reference", label: "attached to", viaAttr: "Attachment" },
+        { from: "AWS::EC2::NetworkInterface", path: "SubnetId", targetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet" },
+        { from: "AWS::EC2::Route", path: "GatewayId", targetKind: "AWS::EC2::InternetGateway", relation: "reference", label: "via", viaAttr: "GatewayId" },
+        { from: "AWS::EC2::Route", path: "NatGatewayId", targetKind: "AWS::EC2::NatGateway", relation: "reference", label: "via" },
+        { from: "AWS::ElasticLoadBalancingV2::LoadBalancer", path: "SecurityGroups[]", targetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg" },
+        { from: "AWS::ElasticLoadBalancingV2::Listener", path: "LoadBalancerArn", targetKind: "AWS::ElasticLoadBalancingV2::LoadBalancer", relation: "reference", label: "on" },
+        { from: "AWS::ElasticLoadBalancingV2::Listener", path: "DefaultActions[].TargetGroupArn", targetKind: "AWS::ElasticLoadBalancingV2::TargetGroup", relation: "reference", label: "forwards to" },
+        { from: "AWS::ECS::Service", path: "ClusterArn", targetKind: "AWS::ECS::Cluster", relation: "reference", label: "in cluster" },
+        { from: "AWS::ECS::Service", path: "TaskDefinition", targetKind: "AWS::ECS::TaskDefinition", relation: "reference", label: "runs" },
+        { from: "AWS::ECS::Service", path: "LoadBalancers[].TargetGroupArn", targetKind: "AWS::ElasticLoadBalancingV2::TargetGroup", relation: "reference", label: "registered in" },
+        { from: "AWS::ECS::Service", path: "NetworkConfiguration.AwsvpcConfiguration.SecurityGroups[]", targetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg" },
+        { from: "AWS::RDS::DBInstance", path: "VpcSecurityGroups[].VpcSecurityGroupId", targetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg" },
+        // ── CloudFormation *template* property paths (#784) ──
+        // `enrichLiveAttrs` resolves the deployed template's `{Ref}`/`{Fn::GetAtt}`
+        // intrinsics to bare logical ids (= node ids), so these match by node id; the
+        // property names are the CFN template shape (SecurityGroupIds, Cluster, …),
+        // which differs from the describe/SDK shape above. No targetKind needed —
+        // logical ids are unique.
+        { from: "AWS::EC2::Subnet", path: "VpcId", relation: "containment", label: "in VPC" },
+        { from: "AWS::EC2::SecurityGroup", path: "VpcId", relation: "containment", label: "in VPC" },
+        { from: "AWS::EC2::RouteTable", path: "VpcId", relation: "containment", label: "in VPC" },
+        { from: "AWS::EC2::Instance", path: "SubnetId", relation: "containment", label: "in subnet" },
+        { from: "AWS::EC2::Instance", path: "SecurityGroupIds[]", relation: "reference", label: "sg" },
+        { from: "AWS::EC2::NatGateway", path: "SubnetId", relation: "containment", label: "in subnet" },
+        { from: "AWS::EC2::Route", path: "RouteTableId", relation: "reference", label: "in" },
+        { from: "AWS::EC2::Route", path: "GatewayId", relation: "reference", label: "via" },
+        { from: "AWS::EC2::Route", path: "NatGatewayId", relation: "reference", label: "via" },
+        { from: "AWS::ElasticLoadBalancingV2::LoadBalancer", path: "Subnets[]", relation: "containment", label: "in subnet" },
+        { from: "AWS::ElasticLoadBalancingV2::LoadBalancer", path: "SecurityGroups[]", relation: "reference", label: "sg" },
+        { from: "AWS::ElasticLoadBalancingV2::TargetGroup", path: "VpcId", relation: "containment", label: "in VPC" },
+        { from: "AWS::ElasticLoadBalancingV2::Listener", path: "LoadBalancerArn", relation: "reference", label: "on" },
+        { from: "AWS::ElasticLoadBalancingV2::Listener", path: "DefaultActions[].TargetGroupArn", relation: "reference", label: "forwards to" },
+        { from: "AWS::ECS::Service", path: "Cluster", relation: "reference", label: "in cluster" },
+        { from: "AWS::ECS::Service", path: "TaskDefinition", relation: "reference", label: "runs" },
+        { from: "AWS::ECS::Service", path: "LoadBalancers[].TargetGroupArn", relation: "reference", label: "registered in" },
+        { from: "AWS::RDS::DBInstance", path: "DBSubnetGroupName", relation: "reference", label: "subnets" },
+        { from: "AWS::RDS::DBInstance", path: "VPCSecurityGroups[]", relation: "reference", label: "sg" },
+    ],
+};

package/dist/rules/ext001.ts

@@ -13,6 +13,7 @@
 
 import { readFileSync } from "fs";
 import { join } from "path";
+import { moduleSourceDir } from "@intentius/chant/module-source";
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
 import { parseCFTemplate, type CFResource } from "./cf-refs";
 
@@ -36,9 +37,8 @@ interface LexiconEntry {
 function loadLexiconConstraints(): Map<string, ExtensionConstraint[]> {
   const map = new Map<string, ExtensionConstraint[]>();
   try {
-    // Navigate from src/lint/post-synth/ up to the package root
-    const pkgDir = join(__dirname, "..", "..", "..");
-    const lexiconPath = join(pkgDir, "src", "generated", "lexicon-aws.json");
+    // From src/lint/post-synth/ (or its compiled twin under dist/) to src/generated/
+    const lexiconPath = join(moduleSourceDir(import.meta.url), "..", "..", "generated", "lexicon-aws.json");
     const content = readFileSync(lexiconPath, "utf-8");
     const data = JSON.parse(content) as Record<string, LexiconEntry>;
 

package/dist/rules/waw016.ts

@@ -17,6 +17,7 @@
 
 import { readFileSync } from "fs";
 import { join } from "path";
+import { moduleSourceDir } from "@intentius/chant/module-source";
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
 import { parseCFTemplate } from "./cf-refs";
 
@@ -38,8 +39,7 @@ interface LexiconEntry {
 function loadDeprecatedProperties(): Map<string, Map<string, DeprecationBasis>> {
   const map = new Map<string, Map<string, DeprecationBasis>>();
   try {
-    const pkgDir = join(__dirname, "..", "..", "..");
-    const lexiconPath = join(pkgDir, "src", "generated", "lexicon-aws.json");
+    const lexiconPath = join(moduleSourceDir(import.meta.url), "..", "..", "generated", "lexicon-aws.json");
     const content = readFileSync(lexiconPath, "utf-8");
     const data = JSON.parse(content) as Record<string, LexiconEntry>;