@intentius/chant-lexicon-aws 0.124.31 → 0.124.33

package/dist/disruption.js

@@ -0,0 +1,129 @@
+/**
+ * Replacement semantics for a pending update (#1665).
+ *
+ * CloudFormation already knows this and says so in the Registry schema:
+ * `createOnlyProperties` is the type's complete list of properties that cannot
+ * be updated without building a new resource, and `replacementStrategy` says
+ * whether the new one is created before the old is removed or after. The
+ * codegen compiles both into `lexicon-aws.json` alongside the types, which is
+ * why this is a lookup rather than a rule anyone maintains by hand.
+ *
+ * `conditionalCreateOnlyProperties` is the interesting case: the schema is
+ * saying "depends on the value", which is not an answer, so it degrades to
+ * `unknown` with the property named. That is the whole point of the contract
+ * having an `unknown` — a maybe reported as `in-place` is worse than no
+ * report.
+ *
+ * `rolling` is not produced here. Nothing in the Registry schema expresses a
+ * workload roll; that verdict belongs to a lexicon whose spec does.
+ */
+import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
+const require = createRequire(moduleSourceUrl(import.meta.url));
+/**
+ * Classify one pending update against the type's compiled schema. Pure — the
+ * spec table is passed in, so this is testable without generated artifacts.
+ */
+export function classifyAwsChange(query, specs) {
+    const spec = query.type ? specs.get(query.type) : undefined;
+    if (!spec || spec.kind !== "resource") {
+        return {
+            disruption: "unknown",
+            detail: query.type
+                ? `no CloudFormation registry schema on record for ${query.type}`
+                : "the observation reported no resource type",
+        };
+    }
+    const readOnly = readOnlyNames(spec);
+    const considered = [];
+    for (const delta of query.deltas) {
+        const property = propertyName(delta.path);
+        if (!property || readOnly.has(property))
+            continue;
+        considered.push({ path: delta.path, property });
+    }
+    const createOnly = new Set(spec.createOnly?.map(headSegment));
+    const forced = considered.filter((c) => createOnly.has(c.property));
+    if (forced.length > 0) {
+        const names = [...new Set(forced.map((c) => c.property))];
+        const destroys = spec.replacementStrategy === "delete_then_create";
+        return {
+            disruption: destroys ? "destroy" : "replace",
+            because: forced.map((c) => c.path),
+            detail: destroys
+                ? `${names.join(", ")} is create-only and ${spec.resourceType} replaces by deleting first — the resource is gone before the new one exists`
+                : `${names.join(", ")} is create-only — CloudFormation builds a new ${spec.resourceType} and removes the old one`,
+        };
+    }
+    const conditional = new Set(spec.conditionalCreateOnly?.map(headSegment));
+    const maybe = considered.filter((c) => conditional.has(c.property));
+    if (maybe.length > 0) {
+        const names = [...new Set(maybe.map((c) => c.property))];
+        return {
+            disruption: "unknown",
+            because: maybe.map((c) => c.path),
+            detail: `the schema marks ${names.join(", ")} conditionally create-only — whether this replaces depends on the value, and the schema does not say which way`,
+        };
+    }
+    if (considered.length === 0) {
+        return {
+            disruption: "in-place",
+            detail: "no configured property differs — only status, identity, or read-only attributes changed",
+        };
+    }
+    return {
+        disruption: "in-place",
+        detail: `no create-only property of ${spec.resourceType} changed`,
+    };
+}
+/**
+ * `LexiconPlugin.classifyDisruption` for aws. Loads the compiled registry once
+ * and answers every query from it. A registry that cannot be read leaves every
+ * change `unknown` — the honest answer, and the one the contract requires.
+ */
+export function awsDisruption(options) {
+    const specs = registryByType();
+    const out = {};
+    for (const change of options.changes) {
+        out[change.name] = classifyAwsChange(change, specs);
+    }
+    return out;
+}
+let cached;
+function registryByType() {
+    if (cached)
+        return cached;
+    try {
+        const manifest = require("./generated/lexicon-aws.json");
+        cached = new Map(Object.values(manifest).map((e) => [e.resourceType, e]));
+    }
+    catch {
+        cached = new Map();
+    }
+    return cached;
+}
+/** Every read-only attribute name the schema declares, top segment only. */
+function readOnlyNames(spec) {
+    const names = new Set();
+    for (const attr of Object.values(spec.attrs ?? {}))
+        names.add(attr.split(".")[0]);
+    return names;
+}
+/**
+ * The property a core delta path names, or undefined when the path is not
+ * about a property at all. Core's own observation fields (`status`,
+ * `physicalId`, `lastUpdated`) sit at the root of the change and say nothing
+ * about configuration; only what is under `attributes.` was read off the
+ * resource.
+ */
+function propertyName(path) {
+    const prefix = "attributes.";
+    if (!path.startsWith(prefix))
+        return undefined;
+    const rest = path.slice(prefix.length);
+    return rest ? headSegment(rest) : undefined;
+}
+/** The first segment of a JSON-pointer-ish property path (`Config/Engine` → `Config`). */
+function headSegment(path) {
+    return path.split(/[/.]/)[0];
+}

package/dist/effect-receipt-row.js

@@ -0,0 +1,107 @@
+/**
+ * The aws effect-receipt materialization row (#1835, epic #1703): an effect
+ * receipt stored as an `AWS::SSM::Parameter`, plain `String`, at
+ * `/chant-receipts/<stack>/<env>/<effect>`.
+ *
+ * Core's `EffectReceipt` factory (#1831) declares a receipt under the `chant`
+ * pseudo-lexicon, which no serializer claims — the designed shape until a
+ * lexicon materializes it. This module is that materialization for aws: the
+ * {@link EffectReceipt} factory here produces the same declaration shape but
+ * under `lexicon: "aws"`, so the build partitions it to the aws serializer,
+ * #1832's write-exclusion seam withholds it from the apply-bound entity set,
+ * and the serializer renders it for visibility through
+ * `SerializeContext.receipts` (see ./serializer.ts).
+ *
+ * Path identity (epic decision 4): the parameter name derives from the SAME
+ * ownership-block fields that stamp markers — `ownership.stack` and an
+ * explicit `ownership.env` — plus the receipt's `effect`. One derivation,
+ * {@link receiptParameterName}, shared by the serializer (the rendered row),
+ * the receipt store (../receipt-store.ts — what `receiptRead`/`receiptWrite`
+ * actually touch), and the observation leg (plan's live read). No env, no
+ * path: the callers error rather than guessing a segment.
+ *
+ * Plain store (epic decision 7, #1833's COR023): the parameter type is pinned
+ * to `String` at the source — the factory does not take a type, and the
+ * declared `props.Type` is the literal `"String"`. A receipt value is a
+ * witness (an existence marker or a `sha256:` digest), never a secret; a
+ * `SecureString` invites masking and rotation semantics that defeat the
+ * observe-and-compare loop, and the lint guard fails it.
+ */
+import { DECLARABLE_MARKER } from "@intentius/chant/declarable";
+import { EffectReceipt as CoreEffectReceipt, EFFECT_RECEIPT_MARKER, } from "@intentius/chant/effect-receipt";
+/** The entityType of the aws materialization row — the real resource kind the
+ * receipt is stored as, which is what lint's plain-store guard checks. */
+export const AWS_EFFECT_RECEIPT_ENTITY_TYPE = "AWS::SSM::Parameter";
+/** Template-level `Metadata` key the serializer renders receipt rows under.
+ * Beside `chant:ownership` (./ownership.ts) and like it deliberately outside
+ * `Resources` — the applier writes from `Resources`, and a receipt must never
+ * enter the apply-bound document (#1832; the `effect()` step is the sole
+ * writer, epic decision 3). */
+export const EFFECT_RECEIPTS_METADATA_KEY = "chant:effect-receipts";
+/** Every receipt parameter lives under this prefix, so read-only IAM can be
+ * scoped to `arn:…:parameter/chant-receipts/*` and nothing else. */
+export const RECEIPT_PATH_PREFIX = "/chant-receipts";
+/**
+ * The rendered `Value` of a hash-flavor receipt that still carries reference
+ * inputs at synthesis. References resolve at plan and at run, never at
+ * synthesis (epic decision 5) — so the row carries this note instead of a
+ * digest hashed over placeholders.
+ */
+export const RECEIPT_UNRESOLVED_VALUE_NOTE = "unresolved at synthesis — reference inputs; the expectation resolves at plan and at run (chant #1703, decision 5)";
+/** One path segment of the receipt parameter name. SSM hierarchical names are
+ * `/`-separated `[\w.-]+` segments, and the identity must stay one segment per
+ * field — a `/` inside a stack name would silently deepen the hierarchy. */
+const PATH_SEGMENT = /^[\w.-]+$/;
+function checkSegment(field, value) {
+    if (!PATH_SEGMENT.test(value)) {
+        throw new Error(`receipt path: ${field} "${value}" is not a valid SSM path segment — ` +
+            `use only letters, digits, ".", "_", "-" (the segment becomes one level of ` +
+            `${RECEIPT_PATH_PREFIX}/<stack>/<env>/<effect>)`);
+    }
+    return value;
+}
+/**
+ * The SSM parameter name of one effect's receipt:
+ * `/chant-receipts/<stack>/<env>/<effect>`, from the resolved ownership
+ * marker fields (epic decision 4). The single source of the path identity —
+ * the serializer's rendered row, the receipt store's reads and writes, and
+ * the observation leg all call this.
+ */
+export function receiptParameterName(stack, env, effect) {
+    return `${RECEIPT_PATH_PREFIX}/${checkSegment("stack", stack)}/${checkSegment("env", env)}/${checkSegment("effect", effect)}`;
+}
+/**
+ * Declare an aws-materialized effect receipt. Same signature and semantics as
+ * core's `EffectReceipt` (#1831) — the options are validated and frozen by the
+ * core factory — but the declaration lands in the aws partition, so the aws
+ * serializer renders the `AWS::SSM::Parameter` row and the receipt store
+ * (../receipt-store.ts) is its writer. Pass the returned const straight to the
+ * `effect(...)` op step.
+ */
+export function EffectReceipt(name, options) {
+    // Fail at declaration, not at serialize: the effect is the path's final
+    // segment, and a name that cannot become a segment has no receipt address.
+    if (typeof options?.effect === "string" && options.effect.length > 0) {
+        checkSegment("effect", options.effect);
+    }
+    const core = CoreEffectReceipt(name, options);
+    const decl = {
+        [DECLARABLE_MARKER]: true,
+        [EFFECT_RECEIPT_MARKER]: true,
+        lexicon: "aws",
+        entityType: AWS_EFFECT_RECEIPT_ENTITY_TYPE,
+        name: core.name,
+        effect: core.effect,
+        flavor: core.flavor,
+        // The same frozen structure the core factory built — intrinsic inputs stay
+        // live so discovery can stamp logical names onto attr-refs.
+        inputs: core.inputs,
+        props: Object.freeze({ Type: "String" }),
+    };
+    // Declared fields immutable, object extensible for discovery's own
+    // symbol-keyed metadata — the same lock the core factory applies.
+    for (const key of Object.keys(decl)) {
+        Object.defineProperty(decl, key, { writable: false, configurable: false });
+    }
+    return decl;
+}