@intentius/chant 0.46.0 → 0.49.0

package/src/op/receipt-store.ts

@@ -0,0 +1,211 @@
+/**
+ * Receipt store seam (#1834, epic #1703) — how the `effect()` step and the
+ * receipt-reading Ops reach a materialized receipt without knowing which
+ * lexicon materializes it.
+ *
+ * The store is injectable: core defines the {@link ReceiptStore} interface and
+ * the activity contracts; the receipt row's lexicon implements the store over
+ * its own resource (#1835's aws row over `AWS::SSM::Parameter`) and exports
+ * the bound activities (`receiptRead`, `receiptWrite`, `receiptStaleness`)
+ * from its `op/activities` module via {@link receiptActivities}. The activity
+ * registry then resolves them by name, exactly like `ensureSecret`
+ * (#1829/#1830, provided by the k8s lexicon). Tests bind a mock store the
+ * same way.
+ *
+ * Write discipline (epic #1703 decision log, item 3): the `effect()` step is
+ * the SOLE writer of a receipt — on success of its nested steps, last. The
+ * store interface carries a `write`, but only the effect step's emitted
+ * read-compare-run-write (and its local-executor twin) reaches it.
+ * `receiptStaleness` — the WatchOp phase (#1834) — is read-only by
+ * construction: it never touches `write` and runs nothing.
+ *
+ * Expectation resolution follows the resolution split (decision 5): a fully
+ * static receipt's expectation is stamped at synthesis and rides the step
+ * data ({@link receiptCheckInput}); a hash-flavor receipt with reference
+ * inputs resolves at run, through the store lexicon's
+ * {@link ReceiptActivityOptions.resolveExpectation} hook — never by hashing
+ * placeholders.
+ */
+
+import {
+  EXISTENCE_EXPECTATION,
+  isEffectReceipt,
+  receiptExpectation,
+  referenceInputPaths,
+  type EffectReceiptDeclaration,
+  type EffectReceiptFlavor,
+} from "../effect-receipt";
+
+/**
+ * The serializable identity + declaration data of an effect receipt — what an
+ * `effect()` step and a `receiptStaleness` check carry through codegen. Built
+ * from the typed {@link EffectReceiptDeclaration} only ({@link receiptCheckInput});
+ * there is no string form. Reference inputs stay in placeholder form.
+ */
+export interface EffectReceiptRef {
+  /** The receipt's own name (the export-level identity of the witness). */
+  name: string;
+  /** The effect this receipt witnesses. */
+  effect: string;
+  /** How the receipt is compared: mere presence, or a digest of the inputs. */
+  flavor: EffectReceiptFlavor;
+  /** The effect's inputs as recorded at synthesis (references as placeholders). */
+  inputs: Record<string, unknown>;
+}
+
+/**
+ * The injectable seam over the materialized receipt (#1835 implements it for
+ * SSM; tests implement it with a map). `read` returns the receipt's current
+ * stored value, or `undefined` when the receipt is absent. `write` stores the
+ * expectation as the new value — called only by the effect step, on success,
+ * last.
+ */
+export interface ReceiptStore {
+  read(receipt: EffectReceiptRef): Promise<string | undefined>;
+  write(receipt: EffectReceiptRef, expectation: string): Promise<void>;
+}
+
+/** One receipt to check: its identity plus, when the receipt is fully static,
+ * the expectation stamped at synthesis. */
+export interface ReceiptCheckInput {
+  receipt: EffectReceiptRef;
+  /** Present when the expectation was computable at synthesis; absent when
+   * reference inputs resolve at run (decision 5). */
+  expectation?: string;
+}
+
+/**
+ * Snapshot a typed receipt declaration into check-input data: the
+ * {@link EffectReceiptRef} plus the synthesis-time expectation when the
+ * receipt is fully static. Used by the `effect()` builder and by WatchOp's
+ * staleness phase — the single place "static enough to hash now" is decided.
+ */
+export function receiptCheckInput(receipt: EffectReceiptDeclaration): ReceiptCheckInput {
+  if (!isEffectReceipt(receipt)) {
+    throw new Error(
+      "receiptCheckInput: expected an EffectReceipt declaration — import the exported const; there is no string form",
+    );
+  }
+  const ref: EffectReceiptRef = {
+    name: receipt.name,
+    effect: receipt.effect,
+    flavor: receipt.flavor,
+    inputs: receipt.inputs as Record<string, unknown>,
+  };
+  // An existence receipt's expectation is a constant, references or not; a
+  // hash receipt is static only when no reference inputs remain.
+  const isStatic = receipt.flavor === "existence" || referenceInputPaths(receipt).length === 0;
+  return isStatic ? { receipt: ref, expectation: receiptExpectation(receipt) } : { receipt: ref };
+}
+
+// ── Activity contracts ────────────────────────────────────────────────────────
+
+/** Args of the `receiptRead` activity, as the effect step's codegen emits them. */
+export interface ReceiptReadArgs extends ReceiptCheckInput {}
+
+/** Result of the `receiptRead` activity. `current` is `null` (not `undefined`)
+ * for an absent receipt so the value survives JSON transport. */
+export interface ReceiptReadResult {
+  /** The receipt's live stored value, or null when absent. */
+  current: string | null;
+  /** The resolved expectation the workflow compares and later writes. */
+  expectation: string;
+  /** Convenience: `current === expectation`. */
+  applied: boolean;
+}
+
+/** Args of the `receiptWrite` activity — the receipt and the resolved
+ * expectation returned by the preceding `receiptRead`. */
+export interface ReceiptWriteArgs {
+  receipt: EffectReceiptRef;
+  expectation: string;
+}
+
+/** Args of the read-only `receiptStaleness` activity (WatchOp). */
+export interface ReceiptStalenessArgs {
+  receipts: ReceiptCheckInput[];
+}
+
+/** One stale receipt, reported as a finding — never acted on. */
+export interface ReceiptStaleFinding {
+  /** The receipt's name. */
+  receipt: string;
+  /** The effect the receipt witnesses. */
+  effect: string;
+  /** `absent` — no receipt stored; `differs` — stored value is not the expectation. */
+  kind: "absent" | "differs";
+  /** The resolved expectation. */
+  expected: string;
+  /** The live stored value (present only for `differs`). */
+  current?: string;
+}
+
+/** Result of the `receiptStaleness` activity. */
+export interface ReceiptStalenessResult {
+  stale: boolean;
+  findings: ReceiptStaleFinding[];
+}
+
+/** Options for {@link receiptActivities}. */
+export interface ReceiptActivityOptions {
+  /**
+   * Resolve a reference-carrying receipt's expectation at run (decision 5) —
+   * the store lexicon's hook to deploy-time values, typically wrapping core's
+   * `resolveReceiptExpectation`. Without it, a check input that carries no
+   * synthesis-time expectation fails loudly rather than hashing placeholders.
+   */
+  resolveExpectation?: (receipt: EffectReceiptRef) => Promise<string> | string;
+}
+
+/** The three receipt activities, bound to one store. */
+export interface ReceiptActivities {
+  receiptRead: (args: ReceiptReadArgs, signal?: AbortSignal) => Promise<ReceiptReadResult>;
+  receiptWrite: (args: ReceiptWriteArgs, signal?: AbortSignal) => Promise<{ written: true; receipt: string }>;
+  receiptStaleness: (args: ReceiptStalenessArgs, signal?: AbortSignal) => Promise<ReceiptStalenessResult>;
+}
+
+/**
+ * Bind the receipt activities to a store. The store's lexicon calls this once
+ * and re-exports the result from its `op/activities` module; the activity
+ * registry picks the functions up by name for both executors.
+ */
+export function receiptActivities(store: ReceiptStore, opts?: ReceiptActivityOptions): ReceiptActivities {
+  const expectationOf = async (input: ReceiptCheckInput): Promise<string> => {
+    if (input.expectation !== undefined) return input.expectation;
+    if (input.receipt.flavor === "existence") return EXISTENCE_EXPECTATION;
+    if (opts?.resolveExpectation) return await opts.resolveExpectation(input.receipt);
+    throw new Error(
+      `receipt "${input.receipt.name}": no synthesis-time expectation and no resolveExpectation hook — ` +
+        `a hash-flavor receipt with reference inputs resolves at run (#1703 decision 5), ` +
+        `and hashing placeholders would be a wrong expectation`,
+    );
+  };
+
+  return {
+    async receiptRead(args: ReceiptReadArgs): Promise<ReceiptReadResult> {
+      const expectation = await expectationOf(args);
+      const current = await store.read(args.receipt);
+      return { current: current ?? null, expectation, applied: current === expectation };
+    },
+
+    async receiptWrite(args: ReceiptWriteArgs): Promise<{ written: true; receipt: string }> {
+      await store.write(args.receipt, args.expectation);
+      return { written: true, receipt: args.receipt.name };
+    },
+
+    // Read-only: reads and reports, runs nothing, never writes.
+    async receiptStaleness(args: ReceiptStalenessArgs): Promise<ReceiptStalenessResult> {
+      const findings: ReceiptStaleFinding[] = [];
+      for (const input of args.receipts) {
+        const expected = await expectationOf(input);
+        const current = await store.read(input.receipt);
+        if (current === undefined) {
+          findings.push({ receipt: input.receipt.name, effect: input.receipt.effect, kind: "absent", expected });
+        } else if (current !== expected) {
+          findings.push({ receipt: input.receipt.name, effect: input.receipt.effect, kind: "differs", expected, current });
+        }
+      }
+      return { stale: findings.length > 0, findings };
+    },
+  };
+}

package/src/op/types.ts

@@ -5,6 +5,8 @@
  * in core without pulling in @temporalio/* as a dependency.
  */
 
+import type { EffectReceiptRef } from "./receipt-store";
+
 export interface OpConfig {
   /** Kebab-case identifier. Used as the workflow function name (camelCase) and output directory name. */
   name: string;
@@ -33,7 +35,7 @@ export interface PhaseDefinition {
   parallel?: boolean;
 }
 
-export type StepDefinition = ActivityStep | GateStep;
+export type StepDefinition = ActivityStep | GateStep | EffectStep;
 
 export interface ActivityStep {
   kind: "activity";
@@ -61,6 +63,36 @@ export interface ActivityStep {
   outcomeAttribute?: { name: string; from?: string };
 }
 
+/**
+ * Read-compare-run-write over an effect receipt (#1834, epic #1703). The
+ * runtime reads the live receipt through the receipt store, compares it
+ * against the resolved expectation, skips the nested steps on a match, and
+ * otherwise runs them — writing the receipt only when every nested step
+ * succeeded, last. A nested-step failure leaves the receipt untouched
+ * (stale), so the next run re-proposes the effect.
+ *
+ * Authored via the `effect()` builder, which takes the typed EffectReceipt
+ * declaration only — there is no string form.
+ */
+export interface EffectStep {
+  kind: "effect";
+  /** Receipt identity + declaration data (references in placeholder form). */
+  receipt: EffectReceiptRef;
+  /**
+   * The expectation stamped at synthesis when the receipt is fully static;
+   * absent when reference inputs resolve at run (#1703 decision 5).
+   */
+  expectation?: string;
+  /**
+   * Steps run when the live receipt does not match, in authored order. A gate
+   * authored here pauses only when the effect will fire. Effect steps do not
+   * nest.
+   */
+  steps: Array<ActivityStep | GateStep>;
+  /** Annotation carried into the generated workflow as a comment. */
+  description?: string;
+}
+
 export interface GateStep {
   kind: "gate";
   /** Signal name. The generated workflow waits for this signal before continuing. */

package/src/secret-materialization.test.ts

@@ -0,0 +1,199 @@
+/**
+ * Generated-once materialization engine tests (#1829, epic #1365 decisions 3
+ * and 6): read-then-write, present means done, mismatch fails loudly naming
+ * key names and metadata keys — and no code path returns, logs, or retains
+ * the generated material.
+ */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { inspect } from "node:util";
+import {
+  SecretMaterial,
+  SecretContractMismatchError,
+  consumeSecretMaterial,
+  defaultSecretMaterialGenerator,
+  ensureSecretMaterialization,
+  type SecretMaterialGenerator,
+  type SecretStoreAdapter,
+  type SecretStoreDescription,
+} from "./secret-materialization";
+
+/** A recognizable plaintext no output may ever contain. */
+const CANARY = "canary-s3kr3t-material";
+
+/** Generator minting a per-key canary value, so leak assertions can grep for it. */
+const canaryGenerator: SecretMaterialGenerator = (key) => SecretMaterial.mint(`${CANARY}:${key}`);
+
+interface StoredSecret {
+  data: Record<string, string>;
+  metadata?: Record<string, string>;
+}
+
+/**
+ * In-memory fake store. `create` consumes each key's material exactly the way
+ * a real adapter writes it, so the tests can check the stored bytes without
+ * any material ever traveling back through the engine.
+ */
+function fakeStore(seed?: Record<string, StoredSecret>) {
+  const secrets = new Map<string, StoredSecret>(Object.entries(seed ?? {}));
+  const adapter: SecretStoreAdapter = {
+    exists: vi.fn(async (name: string) => secrets.has(name)),
+    describe: vi.fn(async (name: string): Promise<SecretStoreDescription> => {
+      const secret = secrets.get(name);
+      if (!secret) throw new Error(`fake store: no secret "${name}"`);
+      return { keys: Object.keys(secret.data), metadata: secret.metadata };
+    }),
+    create: vi.fn(async (name: string, keys: readonly string[], generate: SecretMaterialGenerator) => {
+      const data: Record<string, string> = {};
+      for (const key of keys) {
+        data[key] = consumeSecretMaterial(await generate(key));
+      }
+      secrets.set(name, { data });
+    }),
+  };
+  return { adapter, secrets };
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("ensureSecretMaterialization", () => {
+  it("absent: mints once through the adapter and reports created", async () => {
+    const { adapter, secrets } = fakeStore();
+    const outcome = await ensureSecretMaterialization(
+      adapter,
+      { name: "master-key", keys: ["MASTER_SECRETS_KEY"] },
+      canaryGenerator,
+    );
+    expect(outcome).toEqual({ outcome: "created", name: "master-key", keys: ["MASTER_SECRETS_KEY"] });
+    expect(adapter.create).toHaveBeenCalledTimes(1);
+    expect(secrets.get("master-key")?.data).toEqual({
+      MASTER_SECRETS_KEY: `${CANARY}:MASTER_SECRETS_KEY`,
+    });
+  });
+
+  it("present and matching: stops without any write — a rerun is byte-identical and create never fires twice", async () => {
+    const { adapter, secrets } = fakeStore();
+    const spec = { name: "master-key", keys: ["a", "b"] };
+
+    await ensureSecretMaterialization(adapter, spec, canaryGenerator);
+    const afterFirstRun = JSON.stringify(secrets.get("master-key"));
+
+    // Second run of the whole ensure — the fountain-ops e2e shape.
+    const outcome = await ensureSecretMaterialization(adapter, spec, canaryGenerator);
+    expect(outcome.outcome).toBe("present");
+    expect(adapter.create).toHaveBeenCalledTimes(1);
+    expect(JSON.stringify(secrets.get("master-key"))).toBe(afterFirstRun);
+  });
+
+  it("present with a missing declared key: fails loudly naming the key, never minting over the existing value", async () => {
+    const { adapter, secrets } = fakeStore({
+      "master-key": { data: { a: "pre-existing-value" } },
+    });
+    await expect(
+      ensureSecretMaterialization(adapter, { name: "master-key", keys: ["a", "b"] }, canaryGenerator),
+    ).rejects.toThrowError(SecretContractMismatchError);
+    await expect(
+      ensureSecretMaterialization(adapter, { name: "master-key", keys: ["a", "b"] }, canaryGenerator),
+    ).rejects.toThrowError(/missing declared key\(s\): b/);
+    expect(adapter.create).not.toHaveBeenCalled();
+    expect(secrets.get("master-key")?.data).toEqual({ a: "pre-existing-value" });
+  });
+
+  it("present with an undeclared extra key: fails naming the extra key", async () => {
+    const { adapter } = fakeStore({
+      "master-key": { data: { a: "x", rogue: "y" } },
+    });
+    await expect(
+      ensureSecretMaterialization(adapter, { name: "master-key", keys: ["a"] }, canaryGenerator),
+    ).rejects.toThrowError(/undeclared key\(s\) present: rogue/);
+  });
+
+  it("declared metadata mismatch: fails naming the metadata KEY only, never its values", async () => {
+    const { adapter } = fakeStore({
+      "master-key": {
+        data: { a: "x" },
+        metadata: { "chant.dev/provenance": "hand-rolled" },
+      },
+    });
+    let thrown: unknown;
+    try {
+      await ensureSecretMaterialization(
+        adapter,
+        {
+          name: "master-key",
+          keys: ["a"],
+          metadata: { "chant.dev/provenance": "generated-once", "chant.dev/stack": "fountain" },
+        },
+        canaryGenerator,
+      );
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toBeInstanceOf(SecretContractMismatchError);
+    const message = (thrown as Error).message;
+    expect(message).toContain("metadata key differs: chant.dev/provenance");
+    expect(message).toContain("missing declared metadata key: chant.dev/stack");
+    // The KEY is named; neither the declared nor the stored VALUE appears.
+    expect(message).not.toContain("hand-rolled");
+    expect(message).not.toContain("generated-once");
+  });
+
+  it("rejects an empty key-set — there is nothing to materialize", async () => {
+    const { adapter } = fakeStore();
+    await expect(
+      ensureSecretMaterialization(adapter, { name: "master-key", keys: [] }, canaryGenerator),
+    ).rejects.toThrowError(/at least one key/);
+    expect(adapter.exists).not.toHaveBeenCalled();
+  });
+
+  it("never emits the generated material on any log or error surface", async () => {
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const infoSpy = vi.spyOn(console, "info").mockImplementation(() => {});
+    const stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+    const stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+
+    const { adapter } = fakeStore({ mismatched: { data: { wrong: "stored-value" } } });
+    await ensureSecretMaterialization(adapter, { name: "fresh", keys: ["k1", "k2"] }, canaryGenerator);
+    const failure = await ensureSecretMaterialization(
+      adapter,
+      { name: "mismatched", keys: ["right"] },
+      canaryGenerator,
+    ).catch((e: Error) => e);
+
+    const captured = [logSpy, errorSpy, warnSpy, infoSpy, stdoutSpy, stderrSpy]
+      .flatMap((spy) => spy.mock.calls)
+      .map((call) => call.map((arg) => inspect(arg)).join(" "))
+      .join("\n");
+    expect(captured).not.toContain(CANARY);
+    expect((failure as Error).message).not.toContain(CANARY);
+    expect((failure as Error).message).not.toContain("stored-value");
+  });
+});
+
+describe("SecretMaterial", () => {
+  it("holds the plaintext out of reach: enumeration, JSON, string coercion, and inspect all redact", () => {
+    const material = SecretMaterial.mint(CANARY);
+    expect(Object.keys(material)).toEqual([]);
+    expect(JSON.stringify(material)).toBe('"[secret material]"');
+    expect(String(material)).toBe("[secret material]");
+    expect(inspect(material)).toBe("[secret material]");
+    expect(inspect({ nested: material })).not.toContain(CANARY);
+  });
+
+  it("is consumable exactly once — the adapter takes it, nothing re-reads it", () => {
+    const material = SecretMaterial.mint(CANARY);
+    expect(consumeSecretMaterial(material)).toBe(CANARY);
+    expect(() => consumeSecretMaterial(material)).toThrowError(/already consumed/);
+  });
+
+  it("default generator mints 32 CSPRNG bytes as base64url", () => {
+    const material = defaultSecretMaterialGenerator("any-key");
+    expect(material).toBeInstanceOf(SecretMaterial);
+    const plaintext = consumeSecretMaterial(material as SecretMaterial);
+    expect(plaintext).toMatch(/^[A-Za-z0-9_-]{43}$/);
+  });
+});