@intentius/chant-lexicon-aws 0.46.0 → 0.50.0

package/src/op/builders.ts

@@ -0,0 +1,72 @@
+/**
+ * Typed step-builder wrappers for this lexicon's activities (chant #1288
+ * Stage 2). See `lexicons/k8s/src/op/builders.ts`'s module doc for why these
+ * live beside their `*Args` interfaces rather than in core or the temporal
+ * barrel: core cannot import a lexicon's types (lexicons depend on core, not
+ * the reverse), and wiring them into the cloud-agnostic temporal barrel
+ * would make it depend on every cloud lexicon at runtime. `opts`'s type in
+ * each wrapper below IS the activity's own `*Args` interface (via
+ * `Omit`/`WithStepRefs`) — never restated. `core`'s own
+ * `awsApply`/`awsDelete`/`flociUp`/`flociDown` are unchanged and produce
+ * byte-identical `ActivityStep` output; these are purely additive.
+ */
+
+import {
+  activity,
+  takeProfileAndId,
+  type ActivityStep,
+  type NamedActivityStep,
+  type WithStepRefs,
+} from "@intentius/chant/op";
+import type { AwsApplyArgs, AwsDeleteArgs } from "./activities/aws-apply";
+import type { FlociUpArgs, FlociDownArgs } from "./activities/floci";
+
+/** Extra opts every wrapper below accepts alongside its activity's own fields. */
+type StepOpts = { profile?: ActivityStep["profile"]; id?: string };
+
+/**
+ * Deploy a built CloudFormation template directly against the CFN API — the
+ * fully typed twin of core's `awsApply`. `opts` is {@link AwsApplyArgs}
+ * itself, minus the positional `templatePath`. Defaults to the `longInfra`
+ * profile.
+ */
+export const awsApply = (
+  templatePath: string,
+  opts: WithStepRefs<Omit<AwsApplyArgs, "templatePath">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("awsApply", { templatePath, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+
+/**
+ * Delete a CloudFormation stack — the inverse of {@link awsApply}, fully
+ * typed twin of core's `awsDelete`. `opts` is {@link AwsDeleteArgs} itself,
+ * minus the positional `templatePath`. Defaults to the `longInfra` profile.
+ */
+export const awsDelete = (
+  templatePath: string,
+  opts: WithStepRefs<Omit<AwsDeleteArgs, "templatePath">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("awsDelete", { templatePath, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+
+/**
+ * Boot the local Floci AWS emulator — the fully typed twin of core's
+ * `flociUp`. `opts` is {@link FlociUpArgs} itself. Defaults to the
+ * `longInfra` profile.
+ */
+export const flociUp = (opts?: WithStepRefs<FlociUpArgs> & StepOpts): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("flociUp", args, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+
+/**
+ * Stop and remove the local Floci emulator container — the fully typed twin
+ * of core's `flociDown`. `opts` is {@link FlociDownArgs} itself. Defaults to
+ * the `fastIdempotent` profile.
+ */
+export const flociDown = (opts?: WithStepRefs<FlociDownArgs> & StepOpts): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("flociDown", args, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};

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);
+  });
+});

package/src/receipt-store.ts

@@ -0,0 +1,315 @@
+/**
+ * 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 type { EffectReceiptRef, ReceiptStore } from "@intentius/chant/op/receipt-store";
+import type { ResourceMetadata } from "@intentius/chant/lexicon";
+import type { UnobservedReason } from "@intentius/chant/observation";
+import {
+  AwsReadError,
+  requestHeaders,
+  serviceUrl,
+  withEndpointOverride,
+  type AwsCredentialSource,
+  type AwsReadClientOptions,
+  type AwsReadHttp,
+} from "./api/read-client";
+import { AWS_TAG_OWNERSHIP_KEYS } from "./ownership";
+import { AWS_EFFECT_RECEIPT_ENTITY_TYPE, EFFECT_RECEIPTS_METADATA_KEY, receiptParameterName } from "./effect-receipt-row";
+
+const SSM_SERVICE = "ssm";
+const SSM_TARGET_PREFIX = "AmazonSSM";
+
+/** Options for {@link awsReceiptStore}. All optional: the default store reads
+ * its identity from the project and its endpoint from the environment. */
+export interface AwsReceiptStoreOptions {
+  /** The path's `<stack>` segment. Omitted, the project's `ownership.stack`
+   * (chant.config.ts, found upward from `cwd`) answers. */
+  stack?: string;
+  /** The path's `<env>` segment — explicit by decision 4. Omitted, `CHANT_ENV`
+   * (set by `chant run --env`) answers, then a literal `ownership.env`. */
+  environment?: string;
+  /** Where to look for chant.config.ts. Defaults to the working directory. */
+  cwd?: string;
+  /** Endpoint override; omitted, `AWS_ENDPOINT_URL[_SSM]` answers (#1694). */
+  endpoint?: string;
+  /** Region for the real-AWS host. */
+  region?: string;
+  /** Injectable HTTP, mirroring the read client's. Tests avoid the network. */
+  http?: AwsReadHttp;
+  /** Environment record the endpoint/credential/identity fallbacks read.
+   * Defaults to `process.env`; injectable for tests. */
+  env?: Record<string, string | undefined>;
+  /** What to sign with — same seam as the read client. */
+  credentials?: AwsCredentialSource;
+  /** Sign even against an endpoint override — for an override that is real AWS. */
+  signEndpointOverride?: boolean;
+}
+
+/** One SSM JSON call. Exported for the observation leg (plugin.ts), which
+ * reads the same parameters the store writes. */
+export async function ssmCall(
+  action: string,
+  payload: Record<string, unknown>,
+  options: AwsReadClientOptions,
+): Promise<{ status: number; json: Record<string, unknown> }> {
+  const settled = 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: AwsReadHttp =
+    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: Record<string, unknown> = {};
+  try {
+    json = res.text ? (JSON.parse(res.text) as Record<string, unknown>) : {};
+  } 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: Record<string, unknown>): string | undefined {
+  const type = json.__type;
+  if (typeof type !== "string") return undefined;
+  return type.includes("#") ? type.slice(type.indexOf("#") + 1) : type;
+}
+
+function ssmError(action: string, status: number, json: Record<string, unknown>): AwsReadError {
+  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: string,
+  options: AwsReadClientOptions = {},
+): Promise<string | undefined> {
+  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 as { Value?: unknown } | undefined)?.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: string,
+  value: string,
+  tags: Record<string, string>,
+  options: AwsReadClientOptions = {},
+): Promise<void> {
+  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);
+}
+
+/** The resolved path identity plus the tags a creation stamps. */
+interface ReceiptIdentity {
+  stack: string;
+  env: string;
+}
+
+async function resolveIdentity(options: AwsReceiptStoreOptions): Promise<ReceiptIdentity> {
+  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 };
+}
+
+/** What the observation leg learned about the declared receipt rows. */
+export interface ReceiptRowObservation {
+  resources: Record<string, ResourceMetadata>;
+  unobserved: Record<string, { type: string; reason: UnobservedReason; detail: string }>;
+}
+
+/**
+ * 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: string[],
+  buildOutput: string,
+  options: AwsReadClientOptions = {},
+): Promise<ReceiptRowObservation> {
+  const out: ReceiptRowObservation = { resources: {}, unobserved: {} };
+  let rows: Record<string, { Properties?: { Name?: unknown } }> | undefined;
+  try {
+    const template = JSON.parse(buildOutput) as { Metadata?: Record<string, unknown> };
+    const block = template.Metadata?.[EFFECT_RECEIPTS_METADATA_KEY];
+    if (typeof block === "object" && block !== null) {
+      rows = block as Record<string, { Properties?: { Name?: unknown } }>;
+    }
+  } 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: UnobservedReason = /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: AwsReceiptStoreOptions = {}): ReceiptStore {
+  let identity: Promise<ReceiptIdentity> | undefined;
+  const identityOf = () => (identity ??= resolveIdentity(options));
+
+  const client = (): AwsReadClientOptions => ({
+    ...(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: EffectReceiptRef): Promise<string | undefined> {
+      const { stack, env } = await identityOf();
+      return ssmGetParameter(receiptParameterName(stack, env, receipt.effect), client());
+    },
+
+    async write(receipt: EffectReceiptRef, expectation: string): Promise<void> {
+      const { stack, env } = await identityOf();
+      const tags = ownershipEntries(AWS_TAG_OWNERSHIP_KEYS, { stack, env });
+      await ssmPutParameter(receiptParameterName(stack, env, receipt.effect), expectation, tags, client());
+    },
+  };
+}