@intentius/chant-lexicon-aws 0.46.0 → 0.49.0

package/src/lint/post-synth/waw062.test.ts

@@ -0,0 +1,109 @@
+import { describe, test, expect } from "vitest";
+import { createPostSynthContext } from "@intentius/chant-test-utils";
+import { waw062, checkDuplicateNamesAndExports } from "./waw062";
+
+function makeCtx(template: object) {
+  return createPostSynthContext({ aws: template });
+}
+
+describe("WAW062: Duplicate Name Or Export Within A Template", () => {
+  test("check metadata", () => {
+    expect(waw062.id).toBe("WAW062");
+    expect(waw062.description.toLowerCase()).toContain("duplicate");
+  });
+
+  test("duplicate Export Name → error", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyBucket: { Type: "AWS::S3::Bucket", Properties: {} },
+      },
+      Outputs: {
+        BucketArnA: { Value: { "Fn::GetAtt": ["MyBucket", "Arn"] }, Export: { Name: "shared-bucket-arn" } },
+        BucketArnB: { Value: { "Fn::GetAtt": ["MyBucket", "Arn"] }, Export: { Name: "shared-bucket-arn" } },
+      },
+    });
+    const diags = checkDuplicateNamesAndExports(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WAW062");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].message).toContain("shared-bucket-arn");
+    expect(diags[0].message).toContain("BucketArnA");
+    expect(diags[0].message).toContain("BucketArnB");
+    expect(diags[0].lexicon).toBe("aws");
+  });
+
+  test("unique Export Names → no diagnostic", () => {
+    const ctx = makeCtx({
+      Resources: {},
+      Outputs: {
+        A: { Value: "a", Export: { Name: "export-a" } },
+        B: { Value: "b", Export: { Name: "export-b" } },
+      },
+    });
+    expect(checkDuplicateNamesAndExports(ctx)).toHaveLength(0);
+  });
+
+  test("duplicate ECR RepositoryName across two composites → error", () => {
+    const ctx = makeCtx({
+      Resources: {
+        RepoOne: { Type: "AWS::ECR::Repository", Properties: { RepositoryName: "svc-images" } },
+        RepoTwo: { Type: "AWS::ECR::Repository", Properties: { RepositoryName: "svc-images" } },
+      },
+    });
+    const diags = checkDuplicateNamesAndExports(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("svc-images");
+    expect(diags[0].message).toContain("RepoOne");
+    expect(diags[0].message).toContain("RepoTwo");
+  });
+
+  test("duplicate LaunchTemplateName → error", () => {
+    const ctx = makeCtx({
+      Resources: {
+        LtA: { Type: "AWS::EC2::LaunchTemplate", Properties: { LaunchTemplateName: "worker-lt" } },
+        LtB: { Type: "AWS::EC2::LaunchTemplate", Properties: { LaunchTemplateName: "worker-lt" } },
+      },
+    });
+    expect(checkDuplicateNamesAndExports(ctx)).toHaveLength(1);
+  });
+
+  test("duplicate SecurityGroup GroupName → error", () => {
+    const ctx = makeCtx({
+      Resources: {
+        SgA: { Type: "AWS::EC2::SecurityGroup", Properties: { GroupName: "web-sg", GroupDescription: "a" } },
+        SgB: { Type: "AWS::EC2::SecurityGroup", Properties: { GroupName: "web-sg", GroupDescription: "b" } },
+      },
+    });
+    expect(checkDuplicateNamesAndExports(ctx)).toHaveLength(1);
+  });
+
+  test("same literal name across different resource types → no diagnostic (not comparable)", () => {
+    const ctx = makeCtx({
+      Resources: {
+        RepoOne: { Type: "AWS::ECR::Repository", Properties: { RepositoryName: "shared" } },
+        TableOne: { Type: "AWS::DynamoDB::Table", Properties: { TableName: "shared" } },
+      },
+    });
+    expect(checkDuplicateNamesAndExports(ctx)).toHaveLength(0);
+  });
+
+  test("intrinsic explicit names → no diagnostic (unprovable)", () => {
+    const ctx = makeCtx({
+      Resources: {
+        RepoOne: { Type: "AWS::ECR::Repository", Properties: { RepositoryName: { "Fn::Sub": "svc-${AWS::StackName}" } } },
+        RepoTwo: { Type: "AWS::ECR::Repository", Properties: { RepositoryName: { "Fn::Sub": "svc-${AWS::StackName}" } } },
+      },
+    });
+    expect(checkDuplicateNamesAndExports(ctx)).toHaveLength(0);
+  });
+
+  test("distinct explicit names → no diagnostic", () => {
+    const ctx = makeCtx({
+      Resources: {
+        RepoOne: { Type: "AWS::ECR::Repository", Properties: { RepositoryName: "svc-images-a" } },
+        RepoTwo: { Type: "AWS::ECR::Repository", Properties: { RepositoryName: "svc-images-b" } },
+      },
+    });
+    expect(checkDuplicateNamesAndExports(ctx)).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/waw063.test.ts

@@ -0,0 +1,220 @@
+import { describe, test, expect } from "vitest";
+import { createPostSynthContext } from "@intentius/chant-test-utils";
+import { waw063, checkDenyAllowContradiction } from "./waw063";
+
+function makeCtx(template: object) {
+  return createPostSynthContext({ aws: template });
+}
+
+describe("WAW063: IAM Policy Denies An Action It Also Allows", () => {
+  test("check metadata", () => {
+    expect(waw063.id).toBe("WAW063");
+    expect(waw063.description).toContain("Deny");
+  });
+
+  test("guardrail policy denies exactly what a workflow policy allows on the same role → error", () => {
+    // Mirrors the issue's own example: a role used by a StepFunctions workflow
+    // needs ec2:ModifyInstanceAttribute; a separately-attached guardrail policy
+    // denies it. Deploy succeeds; the workflow 403s at runtime.
+    const ctx = makeCtx({
+      Resources: {
+        WorkflowRole: { Type: "AWS::IAM::Role", Properties: { AssumeRolePolicyDocument: { Statement: [] } } },
+        WorkflowPolicy: {
+          Type: "AWS::IAM::Policy",
+          Properties: {
+            PolicyName: "workflow-needs",
+            Roles: [{ Ref: "WorkflowRole" }],
+            PolicyDocument: {
+              Statement: [{ Effect: "Allow", Action: "ec2:ModifyInstanceAttribute", Resource: "*" }],
+            },
+          },
+        },
+        SecurityGuardrailPolicy: {
+          Type: "AWS::IAM::Policy",
+          Properties: {
+            PolicyName: "guardrail",
+            Roles: [{ Ref: "WorkflowRole" }],
+            PolicyDocument: {
+              Statement: [{ Effect: "Deny", Action: "ec2:ModifyInstanceAttribute", Resource: "*" }],
+            },
+          },
+        },
+      },
+    });
+    const diags = checkDenyAllowContradiction(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WAW063");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].entity).toBe("WorkflowRole");
+    expect(diags[0].message).toContain("ec2:ModifyInstanceAttribute");
+    expect(diags[0].message).toContain("SecurityGuardrailPolicy");
+    expect(diags[0].message).toContain("WorkflowPolicy");
+    expect(diags[0].lexicon).toBe("aws");
+  });
+
+  test("wildcarded Deny nullifies a literal Allow on the same role's inline policy → error", () => {
+    const ctx = makeCtx({
+      Resources: {
+        AppRole: {
+          Type: "AWS::IAM::Role",
+          Properties: {
+            AssumeRolePolicyDocument: { Statement: [] },
+            Policies: [
+              {
+                PolicyName: "inline",
+                PolicyDocument: {
+                  Statement: [
+                    { Effect: "Allow", Action: "s3:GetObject", Resource: "*" },
+                    { Effect: "Deny", Action: "s3:*", Resource: "*" },
+                  ],
+                },
+              },
+            ],
+          },
+        },
+      },
+    });
+    expect(checkDenyAllowContradiction(ctx)).toHaveLength(1);
+  });
+
+  test("broad Allow with a narrow safety Deny (intentional guardrail) → no diagnostic", () => {
+    const ctx = makeCtx({
+      Resources: {
+        AppRole: {
+          Type: "AWS::IAM::Role",
+          Properties: {
+            AssumeRolePolicyDocument: { Statement: [] },
+            Policies: [
+              {
+                PolicyName: "inline",
+                PolicyDocument: {
+                  Statement: [
+                    { Effect: "Allow", Action: "ec2:*", Resource: "*" },
+                    { Effect: "Deny", Action: "ec2:TerminateInstances", Resource: "*" },
+                  ],
+                },
+              },
+            ],
+          },
+        },
+      },
+    });
+    expect(checkDenyAllowContradiction(ctx)).toHaveLength(0);
+  });
+
+  test("Deny on a different role than the Allow → no diagnostic", () => {
+    const ctx = makeCtx({
+      Resources: {
+        RoleA: {
+          Type: "AWS::IAM::Role",
+          Properties: {
+            AssumeRolePolicyDocument: { Statement: [] },
+            Policies: [{ PolicyName: "p", PolicyDocument: { Statement: [{ Effect: "Allow", Action: "ec2:ModifyInstanceAttribute", Resource: "*" }] } }],
+          },
+        },
+        RoleB: {
+          Type: "AWS::IAM::Role",
+          Properties: {
+            AssumeRolePolicyDocument: { Statement: [] },
+            Policies: [{ PolicyName: "p", PolicyDocument: { Statement: [{ Effect: "Deny", Action: "ec2:ModifyInstanceAttribute", Resource: "*" }] } }],
+          },
+        },
+      },
+    });
+    expect(checkDenyAllowContradiction(ctx)).toHaveLength(0);
+  });
+
+  test("Deny scoped to a disjoint literal resource → no diagnostic", () => {
+    const ctx = makeCtx({
+      Resources: {
+        AppRole: {
+          Type: "AWS::IAM::Role",
+          Properties: {
+            AssumeRolePolicyDocument: { Statement: [] },
+            Policies: [
+              {
+                PolicyName: "inline",
+                PolicyDocument: {
+                  Statement: [
+                    { Effect: "Allow", Action: "s3:GetObject", Resource: "arn:aws:s3:::bucket-a/*" },
+                    { Effect: "Deny", Action: "s3:GetObject", Resource: "arn:aws:s3:::bucket-b/*" },
+                  ],
+                },
+              },
+            ],
+          },
+        },
+      },
+    });
+    expect(checkDenyAllowContradiction(ctx)).toHaveLength(0);
+  });
+
+  test("conditional Deny is skipped (unprovable statically) → no diagnostic", () => {
+    const ctx = makeCtx({
+      Resources: {
+        AppRole: {
+          Type: "AWS::IAM::Role",
+          Properties: {
+            AssumeRolePolicyDocument: { Statement: [] },
+            Policies: [
+              {
+                PolicyName: "inline",
+                PolicyDocument: {
+                  Statement: [
+                    { Effect: "Allow", Action: "s3:GetObject", Resource: "*" },
+                    {
+                      Effect: "Deny",
+                      Action: "s3:GetObject",
+                      Resource: "*",
+                      Condition: { StringNotEquals: { "aws:SourceVpc": "vpc-123" } },
+                    },
+                  ],
+                },
+              },
+            ],
+          },
+        },
+      },
+    });
+    expect(checkDenyAllowContradiction(ctx)).toHaveLength(0);
+  });
+
+  test("Deny from a managed policy attached via ManagedPolicyArns collides with an inline Allow → error", () => {
+    const ctx = makeCtx({
+      Resources: {
+        AppRole: {
+          Type: "AWS::IAM::Role",
+          Properties: {
+            AssumeRolePolicyDocument: { Statement: [] },
+            ManagedPolicyArns: [{ Ref: "GuardrailManagedPolicy" }],
+            Policies: [{ PolicyName: "inline", PolicyDocument: { Statement: [{ Effect: "Allow", Action: "ec2:ModifyInstanceAttribute", Resource: "*" }] } }],
+          },
+        },
+        GuardrailManagedPolicy: {
+          Type: "AWS::IAM::ManagedPolicy",
+          Properties: {
+            PolicyDocument: { Statement: [{ Effect: "Deny", Action: "ec2:ModifyInstanceAttribute", Resource: "*" }] },
+          },
+        },
+      },
+    });
+    const diags = checkDenyAllowContradiction(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("GuardrailManagedPolicy");
+  });
+
+  test("role with only Allow statements → no diagnostic", () => {
+    const ctx = makeCtx({
+      Resources: {
+        AppRole: {
+          Type: "AWS::IAM::Role",
+          Properties: {
+            AssumeRolePolicyDocument: { Statement: [] },
+            Policies: [{ PolicyName: "p", PolicyDocument: { Statement: [{ Effect: "Allow", Action: "s3:GetObject", Resource: "*" }] } }],
+          },
+        },
+      },
+    });
+    expect(checkDenyAllowContradiction(ctx)).toHaveLength(0);
+  });
+});

package/src/op/activities/index.ts

@@ -46,6 +46,21 @@ export {
 } from "./aws-apply";
 export type { AwsApplyArgs, RollbackStackArgs, AwsHttp } from "./aws-apply";
 
+// Effect-receipt activities (#1835) — core's receipt seam (#1834) bound to
+// the SSM store, the way the k8s lexicon binds `ensureSecret` (#1830). The
+// registry keys exported functions by name, so the three bound activities are
+// re-exported individually: `receiptRead`/`receiptWrite` serve the `effect()`
+// step's read-compare-run-write, `receiptStaleness` serves WatchOp's
+// read-only phase. The store resolves its path identity and endpoint lazily
+// at first use, so this module stays cheap to load.
+import { receiptActivities } from "@intentius/chant/op/receipt-store";
+import { awsReceiptStore } from "../../receipt-store";
+
+const boundReceiptActivities = receiptActivities(awsReceiptStore());
+export const receiptRead = boundReceiptActivities.receiptRead;
+export const receiptWrite = boundReceiptActivities.receiptWrite;
+export const receiptStaleness = boundReceiptActivities.receiptStaleness;
+
 export { awsAgentCoreFetchTrace } from "../../agentcore/trace-fetch";
 export type {
   AgentCoreTraceSource,

package/src/plugin.ts

@@ -505,7 +505,7 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
     {
       file: "chant-aws-carve-terraform.md",
       name: "chant-aws-carve-terraform",
-      description: "Demo carving a resource out of Terraform into native chant — advise, emit, bridge, apply — fully offline",
+      description: "Demo carving a resource out of Terraform into native chant — advise, emit, audit, bridge, apply — fully offline",
       triggers: [
         { type: "context", value: "terraform" },
         { type: "context", value: "carve" },
@@ -581,6 +581,17 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
     // single-stack convention is the stack named after the environment (#932).
     const stackName = options.stack ?? `${options.environment}`;
 
+    // Effect receipt rows (#1835): a receipt is never a stack member (the
+    // applier never writes it, #1832), so the stack read honestly reports it
+    // absent even while the parameter exists — which would arrive downstream
+    // as "the effect never ran". The serializer rendered each receipt's
+    // derived path into the template Metadata; read those parameters directly,
+    // and report a failed read as an `unobserved` hole rather than a wrong
+    // answer.
+    const { observeReceiptRows } = await import("./receipt-store");
+    const receiptObs = await observeReceiptRows(options.entityNames, options.buildOutput, client);
+    const receiptHoles = Object.keys(receiptObs.unobserved).length > 0 ? receiptObs.unobserved : undefined;
+
     // Describe stack resources. The endpoint override rides the client, so a
     // local emulator (Floci) is observed instead of real AWS (#926) — behold
     // serve --local relies on this for the overlay.
@@ -598,7 +609,12 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
       if (err instanceof AwsReadError && stackDoesNotExist(err.message)) {
         const { observeByIdentity } = await import("./identity-observe");
         const identity = await observeByIdentity(options.entityNames, options.entities, resources, client);
-        return observation({ ...resources, ...identity.resources }, undefined, identity.queried, notes);
+        return observation(
+          { ...resources, ...identity.resources, ...receiptObs.resources },
+          receiptHoles,
+          identity.queried,
+          notes,
+        );
       }
       // Any other failure (credentials, throttling, a region that can't be
       // reached) establishes nothing about what is deployed. Reporting every
@@ -608,13 +624,16 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
       const reason = /credential|token|expired|AccessDenied|not authorized|Unauthorized/i.test(detail)
         ? "no-credentials"
         : "read-failed";
+      // A receipt row the leg above did read stays read: its answer came from
+      // GetParameter, not from the failed stack call, so it is not a hole.
+      const stackHoles = unobservedAll(
+        options.entityNames.filter((n) => !(n in receiptObs.resources)),
+        reason,
+        `DescribeStackResources failed for stack "${stackName}": ${detail}`,
+      );
       return observation(
-        {},
-        unobservedAll(
-          options.entityNames,
-          reason,
-          `DescribeStackResources failed for stack "${stackName}": ${detail}`,
-        ),
+        { ...receiptObs.resources },
+        { ...stackHoles, ...receiptObs.unobserved },
         undefined,
         notes,
       );
@@ -703,13 +722,25 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
           detail: `the stack was read, but this resource's own properties were not — ${own.failures.get(type) ?? "the describe call failed"}`,
         };
       }
-      return observation({ ...described, ...identity.resources }, holes, identity.queried, notes, stackExports);
+      return observation(
+        { ...described, ...identity.resources, ...receiptObs.resources },
+        { ...holes, ...receiptObs.unobserved },
+        identity.queried,
+        notes,
+        stackExports,
+      );
     }
 
     // Every entity the stack answered for was answered for: an entity the
     // template doesn't carry is genuinely not in this stack, which is an
     // absence, not a hole — unless the identity fallback saw it live (#1647).
-    return observation({ ...withProperties, ...identity.resources }, undefined, identity.queried, notes, stackExports);
+    return observation(
+      { ...withProperties, ...identity.resources, ...receiptObs.resources },
+      receiptHoles,
+      identity.queried,
+      notes,
+      stackExports,
+    );
   },
 
   /**

package/src/receipt-store.test.ts

@@ -0,0 +1,204 @@
+import { describe, it, expect } from "vitest";
+import { awsReceiptStore, observeReceiptRows, ssmGetParameter, ssmPutParameter } from "./receipt-store";
+import { EFFECT_RECEIPTS_METADATA_KEY } from "./effect-receipt-row";
+import { receiptActivities, type EffectReceiptRef } from "@intentius/chant/op/receipt-store";
+import type { AwsReadHttp } from "./api/read-client";
+import { mkdtempSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+/** A directory with no chant.config.ts anywhere upward. */
+const bareDir = mkdtempSync(join(tmpdir(), "chant-receipt-store-"));
+
+interface Call {
+  url: string;
+  target: string;
+  body: Record<string, unknown>;
+}
+
+/** Fake SSM endpoint: records calls, answers from a name → value map. */
+function fakeSsm(parameters: Record<string, string>, opts?: { failReads?: boolean }) {
+  const calls: Call[] = [];
+  const http: AwsReadHttp = async (url, init) => {
+    const body = JSON.parse(init.body) as Record<string, unknown>;
+    const target = init.headers["x-amz-target"] ?? "";
+    calls.push({ url, target: target.replace(/^AmazonSSM\./, ""), body });
+    if (target.endsWith("GetParameter")) {
+      if (opts?.failReads) return { status: 500, text: JSON.stringify({ __type: "InternalServerError" }) };
+      const value = parameters[body.Name as string];
+      if (value === undefined) {
+        return { status: 400, text: JSON.stringify({ __type: "ParameterNotFound" }) };
+      }
+      return { status: 200, text: JSON.stringify({ Parameter: { Name: body.Name, Value: value } }) };
+    }
+    if (target.endsWith("PutParameter")) {
+      if (parameters[body.Name as string] !== undefined && body.Overwrite !== true) {
+        return { status: 400, text: JSON.stringify({ __type: "ParameterAlreadyExists" }) };
+      }
+      parameters[body.Name as string] = body.Value as string;
+      return { status: 200, text: JSON.stringify({ Version: 1 }) };
+    }
+    return { status: 400, text: JSON.stringify({ __type: "InvalidAction" }) };
+  };
+  return { calls, http, parameters };
+}
+
+const ref: EffectReceiptRef = { name: "seeded", effect: "db-seed", flavor: "hash", inputs: { v: 1 } };
+
+function store(fake: ReturnType<typeof fakeSsm>, env: Record<string, string | undefined> = {}) {
+  return awsReceiptStore({
+    stack: "demo",
+    environment: "dev",
+    cwd: bareDir,
+    http: fake.http,
+    env,
+  });
+}
+
+describe("awsReceiptStore", () => {
+  it("read returns the stored value at the derived path", async () => {
+    const fake = fakeSsm({ "/chant-receipts/demo/dev/db-seed": "sha256:abc" });
+    await expect(store(fake).read(ref)).resolves.toBe("sha256:abc");
+    expect(fake.calls[0].target).toBe("GetParameter");
+    expect(fake.calls[0].body.Name).toBe("/chant-receipts/demo/dev/db-seed");
+  });
+
+  it("read returns undefined for an absent receipt — a real answer, not an error", async () => {
+    const fake = fakeSsm({});
+    await expect(store(fake).read(ref)).resolves.toBeUndefined();
+  });
+
+  it("read throws on a failed read rather than answering wrongly", async () => {
+    const fake = fakeSsm({}, { failReads: true });
+    await expect(store(fake).read(ref)).rejects.toThrow(/GetParameter/);
+  });
+
+  it("write creates plain String with the ownership tags", async () => {
+    const fake = fakeSsm({});
+    await store(fake).write(ref, "sha256:abc");
+    expect(fake.calls).toHaveLength(1);
+    const { body } = fake.calls[0];
+    expect(body.Type).toBe("String");
+    expect(body.Overwrite).toBeUndefined();
+    expect(body.Tags).toContainEqual({ Key: "chant:managed-by", Value: "chant" });
+    expect(body.Tags).toContainEqual({ Key: "chant:stack", Value: "demo" });
+    expect(body.Tags).toContainEqual({ Key: "chant:env", Value: "dev" });
+    expect(fake.parameters["/chant-receipts/demo/dev/db-seed"]).toBe("sha256:abc");
+  });
+
+  it("write overwrites an existing receipt — String + Overwrite, no tags on the retry", async () => {
+    const fake = fakeSsm({ "/chant-receipts/demo/dev/db-seed": "sha256:old" });
+    await store(fake).write(ref, "sha256:new");
+    expect(fake.calls.map((c) => c.target)).toEqual(["PutParameter", "PutParameter"]);
+    const retry = fake.calls[1].body;
+    expect(retry.Type).toBe("String");
+    expect(retry.Overwrite).toBe(true);
+    expect(retry.Tags).toBeUndefined();
+    expect(fake.parameters["/chant-receipts/demo/dev/db-seed"]).toBe("sha256:new");
+  });
+
+  it("honors AWS_ENDPOINT_URL_SSM, then AWS_ENDPOINT_URL (#1694)", async () => {
+    const perService = fakeSsm({});
+    await store(perService, { AWS_ENDPOINT_URL_SSM: "http://localhost:4566", AWS_ENDPOINT_URL: "http://elsewhere:1" }).read(ref);
+    expect(perService.calls[0].url).toBe("http://localhost:4566/");
+
+    const ambient = fakeSsm({});
+    await store(ambient, { AWS_ENDPOINT_URL: "http://localhost:4566" }).read(ref);
+    expect(ambient.calls[0].url).toBe("http://localhost:4566/");
+  });
+
+  it("errors without a stack identity", async () => {
+    const fake = fakeSsm({});
+    const s = awsReceiptStore({ environment: "dev", cwd: bareDir, http: fake.http, env: {} });
+    await expect(s.read(ref)).rejects.toThrow(/ownership: \{ stack \}/);
+  });
+
+  it("errors without an env — the segment is explicit (decision 4)", async () => {
+    const fake = fakeSsm({});
+    const s = awsReceiptStore({ stack: "demo", cwd: bareDir, http: fake.http, env: {} });
+    await expect(s.read(ref)).rejects.toThrow(/CHANT_ENV/);
+  });
+
+  it("reads CHANT_ENV for the env segment", async () => {
+    const fake = fakeSsm({ "/chant-receipts/demo/staging/db-seed": "x" });
+    const s = awsReceiptStore({ stack: "demo", cwd: bareDir, http: fake.http, env: { CHANT_ENV: "staging" } });
+    await expect(s.read(ref)).resolves.toBe("x");
+  });
+});
+
+describe("receiptActivities over the aws store", () => {
+  it("resolves receiptRead/receiptWrite/receiptStaleness against the SSM store", async () => {
+    const fake = fakeSsm({});
+    const activities = receiptActivities(store(fake));
+
+    const read = await activities.receiptRead({ receipt: ref, expectation: "sha256:abc" });
+    expect(read).toEqual({ current: null, expectation: "sha256:abc", applied: false });
+
+    await activities.receiptWrite({ receipt: ref, expectation: "sha256:abc" });
+    const again = await activities.receiptRead({ receipt: ref, expectation: "sha256:abc" });
+    expect(again.applied).toBe(true);
+
+    const staleness = await activities.receiptStaleness({
+      receipts: [{ receipt: ref, expectation: "sha256:other" }],
+    });
+    expect(staleness.stale).toBe(true);
+    expect(staleness.findings[0]).toMatchObject({ receipt: "seeded", kind: "differs" });
+  });
+
+  it("is wired into the op activities barrel by name", async () => {
+    const barrel = await import("./op/activities/index");
+    expect(typeof barrel.receiptRead).toBe("function");
+    expect(typeof barrel.receiptWrite).toBe("function");
+    expect(typeof barrel.receiptStaleness).toBe("function");
+  });
+});
+
+describe("observeReceiptRows (plan's live read)", () => {
+  const buildOutput = JSON.stringify({
+    AWSTemplateFormatVersion: "2010-09-09",
+    Metadata: {
+      [EFFECT_RECEIPTS_METADATA_KEY]: {
+        seeded: {
+          Type: "AWS::SSM::Parameter",
+          Properties: { Name: "/chant-receipts/demo/dev/db-seed", Type: "String", Value: "sha256:abc", Tags: [] },
+        },
+      },
+    },
+    Resources: {},
+  });
+
+  it("maps a present receipt's stored value onto attributes.value", async () => {
+    const fake = fakeSsm({ "/chant-receipts/demo/dev/db-seed": "sha256:abc" });
+    const obs = await observeReceiptRows(["seeded", "unrelated"], buildOutput, { http: fake.http, env: {} });
+    expect(obs.resources.seeded).toMatchObject({
+      type: "AWS::SSM::Parameter",
+      physicalId: "/chant-receipts/demo/dev/db-seed",
+      status: "EXTERNAL",
+      attributes: { value: "sha256:abc" },
+    });
+    expect(obs.unobserved).toEqual({});
+    // Only the rendered receipt was queried — never a guess for other entities.
+    expect(fake.calls).toHaveLength(1);
+  });
+
+  it("reports a confirmed absence as absence — in neither map", async () => {
+    const fake = fakeSsm({});
+    const obs = await observeReceiptRows(["seeded"], buildOutput, { http: fake.http, env: {} });
+    expect(obs.resources).toEqual({});
+    expect(obs.unobserved).toEqual({});
+  });
+
+  it("reports a failed read as unobserved, never a wrong answer", async () => {
+    const fake = fakeSsm({}, { failReads: true });
+    const obs = await observeReceiptRows(["seeded"], buildOutput, { http: fake.http, env: {} });
+    expect(obs.resources).toEqual({});
+    expect(obs.unobserved.seeded).toMatchObject({ type: "AWS::SSM::Parameter", reason: "read-failed" });
+  });
+
+  it("answers nothing for a template without receipt rows", async () => {
+    const fake = fakeSsm({});
+    const obs = await observeReceiptRows(["seeded"], JSON.stringify({ Resources: {} }), { http: fake.http, env: {} });
+    expect(obs).toEqual({ resources: {}, unobserved: {} });
+    expect(fake.calls).toHaveLength(0);
+  });
+});