create-ailk 0.14.0 → 0.15.0

package/templates/apps/api/src/openapi/spec.ts

@@ -751,7 +751,25 @@ export function buildOpenApiSpec(
             "only), or, on a deployment with no database, the site operator's inbox " +
             "by email (`persisted: \"email\"`); with a database, the response's " +
             "`email` field reports, best-effort, whether the operator was notified. " +
-            "A lead is never reported captured when nothing stored or delivered it.",
+            "A lead is never reported captured when nothing stored or delivered it. " +
+            "An optional `Idempotency-Key` header makes a retry safe: with a " +
+            "database, a repeat of a stored key in the same workspace with the same " +
+            "`email`, `source` and `payload` writes nothing and answers the first " +
+            "lead's id with a 201; with anything different it is a 422. Keys are " +
+            "scoped per workspace, are first-write-wins, and should be unguessable " +
+            "(a UUID, a Stripe Checkout Session id). Without a database there is no " +
+            "stored lead to match, so the key has no effect.",
+          parameters: [
+            {
+              name: "Idempotency-Key",
+              in: "header",
+              required: false,
+              description:
+                "An unguessable value identifying this lead write, so a retry " +
+                "answers the first lead instead of writing a second (#7869).",
+              schema: { type: "string", pattern: "^[\\x21-\\x7E]{16,255}$" },
+            },
+          ],
           requestBody: {
             required: true,
             content: {
@@ -770,13 +788,31 @@ export function buildOpenApiSpec(
               },
             },
             "400": {
-              description: "Validation error — invalid request body",
+              description:
+                "Validation error — invalid request body, or a malformed Idempotency-Key",
               content: {
                 "application/json": {
                   schema: { $ref: "#/components/schemas/InvalidInputResponse" },
                 },
               },
             },
+            "422": {
+              description:
+                "The Idempotency-Key was already used in this workspace for a lead " +
+                "with a different email, source or payload; nothing was written",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    required: ["error", "message"],
+                    properties: {
+                      error: { type: "string", enum: ["idempotency_key_reused"] },
+                      message: { type: "string" },
+                    },
+                  },
+                },
+              },
+            },
             "503": {
               description:
                 "Lead capture unavailable — persistence failed, delivery failed, or " +

package/templates/apps/api/src/routes/checkout/__tests__/sessions.test.ts

@@ -1080,7 +1080,8 @@ describe("POST /v1/checkout/sessions — signed-in buyer stamp (#6866)", () => {
     expect(res.statusCode).toBe(201);
     const arg = mockCreateCheckoutSession.mock.calls[0][0];
     expect(arg).not.toHaveProperty("buyer");
-    expect(arg).not.toHaveProperty("metadata");
+    // #7868 D4 — the only metadata is the hub's own site stamp.
+    expect(arg.metadata).toEqual({ site: "default" });
     expect(arg).not.toHaveProperty("ailk_user_id");
   });
 
@@ -1093,7 +1094,8 @@ describe("POST /v1/checkout/sessions — signed-in buyer stamp (#6866)", () => {
 
     const arg = mockCreateCheckoutSession.mock.calls[0][0];
     expect(arg.buyer.userId).toBe("usr_buyer");
-    expect(arg).not.toHaveProperty("metadata");
+    // #7868 D4 — the only metadata is the hub's own site stamp.
+    expect(arg.metadata).toEqual({ site: "default" });
   });
 
   it("#6866 R5: with no cookie, the call is exactly today's argument object", async () => {
@@ -1109,6 +1111,8 @@ describe("POST /v1/checkout/sessions — signed-in buyer stamp (#6866)", () => {
       successUrl: VALID_BODY.successUrl,
       cancelUrl: VALID_BODY.cancelUrl,
       quantity: 1,
+      // #7868 D4 — the hub's own site stamp (AILK_SITE_ID unset).
+      metadata: { site: "default" },
     });
     expect(prisma.session.findUnique).not.toHaveBeenCalled();
     expect(prisma.user.findUnique).not.toHaveBeenCalled();
@@ -1116,6 +1120,50 @@ describe("POST /v1/checkout/sessions — signed-in buyer stamp (#6866)", () => {
     expect(createdLog()).not.toHaveProperty("identity");
   });
 
+  it("#7868 D4: the site stamp follows AILK_SITE_ID", async () => {
+    const original = process.env.AILK_SITE_ID;
+    process.env.AILK_SITE_ID = "wksp_hub";
+    try {
+      const res = await post({});
+
+      expect(res.statusCode).toBe(201);
+      expect(mockCreateCheckoutSession.mock.calls[0][0].metadata).toEqual({
+        site: "wksp_hub",
+      });
+    } finally {
+      if (original === undefined) delete process.env.AILK_SITE_ID;
+      else process.env.AILK_SITE_ID = original;
+    }
+  });
+
+  it("#7868 D4: the anonymous retry after a stale customer carries the site stamp too", async () => {
+    givenUser({ billingProvider: "stripe", billingCustomerId: "cus_bound" });
+    mockCreateCheckoutSession.mockRejectedValueOnce(new UnknownCustomerError());
+
+    const res = await signedIn();
+
+    expect(res.statusCode).toBe(201);
+    expect(mockCreateCheckoutSession).toHaveBeenCalledTimes(2);
+    expect(mockCreateCheckoutSession.mock.calls[0][0].metadata).toEqual({
+      site: "default",
+    });
+    expect(mockCreateCheckoutSession.mock.calls[1][0].metadata).toEqual({
+      site: "default",
+    });
+  });
+
+  it("#7868 D4: a signed-in call carries both the buyer and the site stamp", async () => {
+    const res = await signedIn();
+
+    expect(res.statusCode).toBe(201);
+    const arg = mockCreateCheckoutSession.mock.calls[0][0];
+    expect(arg.buyer).toEqual({
+      userId: "usr_buyer",
+      email: "buyer@example.com",
+    });
+    expect(arg.metadata).toEqual({ site: "default" });
+  });
+
   it.each([
     [
       "an unknown session",

package/templates/apps/api/src/routes/checkout/sessions.ts

@@ -22,6 +22,11 @@
  *     identifies a buyer. Any lookup failure, and a pinned customer Stripe
  *     does not know, degrades to today's anonymous Checkout — never an error.
  *     The stamped id is never echoed or logged.
+ *   - Site stamp (#7868): every session carries `metadata.site` from
+ *     `siteStamp()` (lib/site.ts) — on the signed-in try and the anonymous
+ *     retry alike — so the Stripe webhook can tell this site's sessions from
+ *     a spoke's on a shared account. The body schema has no metadata field,
+ *     so no caller can set or override the stamp.
  *   - X-Internal-Auth gate: when OSS_API_INTERNAL_SECRET env var is set,
  *     the X-Internal-Auth header must match; requests without a matching header
  *     are rejected with 401. When the env var is unset, no gate is applied
@@ -55,6 +60,7 @@ import type { FastifyReply, FastifyRequest } from "fastify";
 import { z } from "zod";
 
 import { config } from "../../config/index.js";
+import { siteStamp } from "../../lib/site.js";
 import {
   assertSandboxKey,
   createCheckoutSession,
@@ -306,6 +312,7 @@ export async function checkoutSessionsHandler(
     // Omitted when the caller says nothing — Stripe's default (no promo-code
     // field) is unchanged for every existing caller.
     ...(allowPromotionCodes !== undefined && { allowPromotionCodes }),
+    metadata: siteStamp(),
   };
   // Built only from the session cookie — never from `parsed.data` (#6866 D5).
   let { buyer, identity } = await resolveBuyer(request);

package/templates/apps/api/src/routes/leads/__tests__/index.test.ts

@@ -54,6 +54,11 @@ jest.mock("@working-theory/license", () => ({
   }),
 }));
 
+// #7869 — the Idempotency-Key suite asserts a replay records no new capture
+// event; `track` is fire-and-forget and never throws, so mocking it changes
+// nothing for the cases above.
+jest.mock("@working-theory/analytics/server", () => ({ track: jest.fn() }));
+
 import {
   leadSubmitRoute,
   leadSubscribeRoute,
@@ -1336,3 +1341,273 @@ describe("POST /v1/leads/submit — #6730 delivery modes", () => {
     await expect(fs.access(fileEnv.getCaptureFilePath())).rejects.toThrow();
   });
 });
+
+// ── #7869 — Idempotency-Key on submit (spec D1, D3–D7, D10 cases 1–8) ─────────
+//
+// `inbox` delivery (DATABASE_URL set), the sentinel workspace resolvable. The
+// app logs into `logLines` so case 8 can prove the key reaches no log line.
+describe("POST /v1/leads/submit — Idempotency-Key (#7869)", () => {
+  let app: FastifyInstance;
+  let logLines: string[];
+  const KEY = "fixture-retry-0000-0000-0002";
+  const STORED_ID = "lead_00000000-0000-7000-8000-00000000a7a7";
+  const NEW_ID = "lead_00000000-0000-7000-8000-00000000b8b8";
+  const sendLeadNotification = jest.requireMock("@working-theory/email")
+    .sendLeadNotification as jest.Mock;
+  const track = jest.requireMock("@working-theory/analytics/server")
+    .track as jest.Mock;
+
+  const body = {
+    kind: "submit",
+    source: "contact",
+    email: "visitor@example.com",
+    payload: { message: "hello", name: "Jamie" },
+  };
+  const send = (
+    headers: Record<string, string> = {},
+    url = "/v1/leads/submit",
+    payload: Record<string, unknown> = body,
+  ) => app.inject({ method: "POST", url, headers, payload });
+  const keyLookups = () =>
+    jest
+      .mocked(prisma.lead.findUnique)
+      .mock.calls.filter(
+        (c) => "workspaceId_idempotencyKey" in (c[0]?.where ?? {}),
+      );
+  const keyIsNowhere = (resBody: string) => {
+    expect(resBody).not.toContain(KEY);
+    for (const line of logLines) expect(line).not.toContain(KEY);
+  };
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    stateSentinelWorkspaceExists();
+    process.env.DATABASE_URL = "postgres://stub";
+    process.env.AILK_LEAD_NOTIFICATION_TO = "owner@example.com";
+    process.env.AILK_LEAD_NOTIFICATION_FROM = "noreply@example.com";
+    (prisma.lead.create as jest.Mock).mockResolvedValue({ id: NEW_ID });
+    (prisma.lead.findUnique as jest.Mock).mockResolvedValue(null);
+
+    logLines = [];
+    const fastify = require("fastify")({
+      logger: {
+        level: "info",
+        stream: { write: (msg: string) => logLines.push(msg) },
+      },
+    });
+    await fastify.register(leadSubmitRoute);
+    await fastify.register(leadSubscribeRoute);
+    await fastify.register(leadCallbackRoute);
+    app = fastify;
+  });
+
+  afterEach(async () => {
+    await app.close();
+    delete process.env.DATABASE_URL;
+    delete process.env.AILK_LEAD_NOTIFICATION_TO;
+    delete process.env.AILK_LEAD_NOTIFICATION_FROM;
+  });
+
+  it("case 1 — no header: one create with no idempotencyKey, no key lookup, 201", async () => {
+    const res = await send();
+
+    expect(res.statusCode).toBe(201);
+    expect(prisma.lead.create).toHaveBeenCalledTimes(1);
+    expect(
+      jest.mocked(prisma.lead.create).mock.calls[0]?.[0].data,
+    ).not.toHaveProperty("idempotencyKey");
+    expect(keyLookups()).toHaveLength(0);
+  });
+
+  it("case 2 — a key with no stored row: scoped lookup, the create carries the key, 201", async () => {
+    const res = await send({ "Idempotency-Key": KEY });
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json()).toEqual({
+      id: NEW_ID,
+      persisted: "db",
+      email: { ok: true, messageId: "msg-test" },
+    });
+    expect(keyLookups()[0]?.[0]).toEqual({
+      where: {
+        workspaceId_idempotencyKey: {
+          workspaceId: RESOLVED_WORKSPACE_ID,
+          idempotencyKey: KEY,
+        },
+      },
+      select: { id: true, email: true, source: true, payload: true },
+    });
+    expect(
+      jest.mocked(prisma.lead.create).mock.calls[0]?.[0].data,
+    ).toMatchObject({
+      idempotencyKey: KEY,
+    });
+    keyIsNowhere(res.body);
+  });
+
+  it("case 3 — a stored row with the same email, source and payload (keys reordered) replays: 201, the stored id, no create, no notification, no track, no capture line", async () => {
+    (prisma.lead.findUnique as jest.Mock).mockResolvedValue({
+      id: STORED_ID,
+      email: body.email,
+      source: body.source,
+      payload: { name: "Jamie", message: "hello" },
+    });
+
+    const res = await send({ "Idempotency-Key": KEY });
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json()).toEqual({
+      id: STORED_ID,
+      persisted: "db",
+      email: { skipped: true, reason: "idempotent_replay" },
+    });
+    expect(Object.keys(res.json()).sort()).toEqual([
+      "email",
+      "id",
+      "persisted",
+    ]);
+    expect(prisma.lead.create).not.toHaveBeenCalled();
+    expect(sendLeadNotification).not.toHaveBeenCalled();
+    expect(track).not.toHaveBeenCalled();
+    await expect(fs.access(fileEnv.getCaptureFilePath())).rejects.toThrow();
+    const routed = logLines.find((l) => l.includes("lead routed"));
+    expect(JSON.parse(routed!)).toMatchObject({ replayed: true });
+    keyIsNowhere(res.body);
+  });
+
+  it.each([
+    ["email", { email: "other@example.com" }],
+    ["source", { source: "footer" }],
+    ["payload", { payload: { message: "a different message", name: "Jamie" } }],
+  ])(
+    "case 4 — a stored row with a different %s is 422 idempotency_key_reused, no create, one warn log",
+    async (_field, override) => {
+      (prisma.lead.findUnique as jest.Mock).mockResolvedValue({
+        id: STORED_ID,
+        email: body.email,
+        source: body.source,
+        payload: body.payload,
+        ...override,
+      });
+
+      const res = await send({ "Idempotency-Key": KEY });
+
+      expect(res.statusCode).toBe(422);
+      expect(res.json()).toEqual({
+        error: "idempotency_key_reused",
+        message: "This Idempotency-Key was used for a different lead.",
+      });
+      expect(prisma.lead.create).not.toHaveBeenCalled();
+      const warns = logLines
+        .map((l) => JSON.parse(l) as Record<string, unknown>)
+        .filter((l) => l["outcome"] === "idempotency_conflict");
+      expect(warns).toHaveLength(1);
+      expect(warns[0]).toMatchObject({
+        level: 40,
+        kind: "submit",
+        siteId: RESOLVED_WORKSPACE_ID,
+      });
+      keyIsNowhere(res.body);
+    },
+  );
+
+  it.each([
+    ["empty", ""],
+    ["15 characters", "a".repeat(15)],
+    ["256 characters", "a".repeat(256)],
+    ["a space", "abcdefghij klmnopqrs"],
+    ["a non-ASCII character", "abcdefghijéklmnopqrs"],
+  ])(
+    "case 5 — a malformed key (%s) is 400 invalid_input with no lead read or write",
+    async (_label, key) => {
+      const res = await app.inject({
+        method: "POST",
+        url: "/v1/leads/submit",
+        headers: { "idempotency-key": key },
+        payload: body,
+      });
+
+      expect(res.statusCode).toBe(400);
+      expect(res.json()).toEqual({
+        error: "invalid_input",
+        message: "Idempotency-Key must be 16 to 255 visible ASCII characters.",
+      });
+      expect(prisma.lead.findUnique).not.toHaveBeenCalled();
+      expect(prisma.lead.create).not.toHaveBeenCalled();
+    },
+  );
+
+  it("case 6 — the same key stored only in another workspace is a miss here: create, 201 with the new id", async () => {
+    jest.mocked(prisma.lead.findUnique).mockImplementation((async (args: {
+      where: { workspaceId_idempotencyKey?: { workspaceId: string } };
+    }) =>
+      args.where.workspaceId_idempotencyKey?.workspaceId ===
+      FOREIGN_WORKSPACE_ID
+        ? {
+            id: STORED_ID,
+            email: body.email,
+            source: body.source,
+            payload: body.payload,
+          }
+        : null) as never);
+
+    const res = await send({ "Idempotency-Key": KEY });
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json().id).toBe(NEW_ID);
+    expect(prisma.lead.create).toHaveBeenCalledTimes(1);
+  });
+
+  it("case 8 — the key reaches no response body and no log line on a fresh write, a replay or a conflict", async () => {
+    const stored = {
+      id: STORED_ID,
+      email: body.email,
+      source: body.source,
+      payload: body.payload,
+    };
+    (prisma.lead.findUnique as jest.Mock)
+      .mockResolvedValueOnce(null) // fresh write
+      .mockResolvedValueOnce(stored) // replay
+      .mockResolvedValueOnce({ ...stored, email: "other@example.com" }); // conflict
+
+    const statuses: number[] = [];
+    for (let i = 0; i < 3; i++) {
+      const res = await send({ "Idempotency-Key": KEY });
+      statuses.push(res.statusCode);
+      keyIsNowhere(res.body);
+    }
+
+    expect(statuses).toEqual([201, 201, 422]);
+    expect(logLines.length).toBeGreaterThan(0);
+  });
+
+  it("case 7 — subscribe and callback ignore the header", async () => {
+    (prisma.subscriber.create as jest.Mock).mockResolvedValue({
+      id: "subscr_1",
+    });
+    (prisma.callback.create as jest.Mock).mockResolvedValue({ id: "callbk_1" });
+
+    const sub = await send(
+      { "Idempotency-Key": "bad" },
+      "/v1/leads/subscribe",
+      {
+        kind: "subscribe",
+        email: "sub@example.com",
+        source: "footer",
+      },
+    );
+    const cb = await send({ "Idempotency-Key": KEY }, "/v1/leads/callback", {
+      kind: "callback",
+      name: "Alice",
+      phone: "+15551234567",
+      payload: {},
+    });
+
+    expect(sub.statusCode).toBe(201);
+    expect(cb.statusCode).toBe(201);
+    expect(keyLookups()).toHaveLength(0);
+    expect(
+      jest.mocked(prisma.callback.create).mock.calls[0]?.[0].data,
+    ).not.toHaveProperty("idempotencyKey");
+  });
+});

package/templates/apps/api/src/routes/leads/index.ts

@@ -42,6 +42,28 @@
  * unchanged. So does a keyless request whose hub-status read fails before the
  * process has any answer: lead capture is never lost (#7633, conductor
  * amendment to NFR3). The body's `siteId` stays ignored on every branch.
+ *
+ * IDEMPOTENCY KEY (#7869, roadmap D5). `POST /v1/leads/submit` accepts an
+ * optional `Idempotency-Key` header: 16 to 255 visible ASCII characters, and
+ * it must be UNGUESSABLE (a UUID, a Stripe Checkout Session id) — a key is
+ * first-write-wins inside its workspace, so a short or predictable one could
+ * be claimed by someone else first (SEC-7869-1). It is checked after the
+ * tenant gate and before `routeLead`; a malformed key is `400 invalid_input`
+ * with no read or write. A repeat of a stored key in the same workspace with
+ * the same `email`, `source` and `payload` answers the first lead's 201 and
+ * writes nothing; with anything different it is `422
+ * idempotency_key_reused`. The key dedupes only where a `Lead` row exists —
+ * `inbox` delivery — so a first write that fell back to email or a local
+ * file leaves nothing to find, and its retry writes again. `subscribe` and
+ * `callback` never read the header. The key is never logged or echoed.
+ *
+ * API↔MCP PARITY for the header (#7869 D9, roadmap §12 Q5): NO guard entry.
+ * The guard binds a route's arguments to the validation export its handler
+ * `.safeParse`s on `request.params|query|body`; the header check below is a
+ * regex test, not such a parse, so this route still binds as
+ * `api-args-unbound` and the `capture_lead` row is unchanged. The 201 body's
+ * field set is unchanged too, and `capture_lead` sends no header. If the
+ * guard ever models headers, this becomes an API-side `arg-only-in`.
  */
 
 import { track } from "@working-theory/analytics/server";
@@ -58,6 +80,9 @@ import {
 import { resolveCallerSite } from "../../services/public-site-resolver.js";
 import { sendRequestConfirmLink } from "../../services/request-confirm.js";
 
+/** #7869 D1 — 16 to 255 visible ASCII characters; no spaces, no list. */
+const IDEMPOTENCY_KEY_PATTERN = /^[\x21-\x7E]{16,255}$/;
+
 /**
  * Read a named string field from the body, falling back to the same-named
  * field inside `body.payload` when the top-level value is absent — the
@@ -199,12 +224,46 @@ function makeLeadsRoute(kind: LeadKind): FastifyPluginAsync {
         workspaceId = resolved;
       }
 
+      // #7869 D1 — after the tenant gate, before any read or write. Node
+      // lower-cases header names, and joins a duplicated header with ", ",
+      // which the pattern refuses.
+      let idempotencyKey: string | undefined;
+      if (kind === "submit") {
+        const rawKey = request.headers["idempotency-key"];
+        if (rawKey !== undefined) {
+          if (
+            typeof rawKey !== "string" ||
+            !IDEMPOTENCY_KEY_PATTERN.test(rawKey)
+          ) {
+            return reply.status(400).send({
+              error: "invalid_input",
+              message:
+                "Idempotency-Key must be 16 to 255 visible ASCII characters.",
+            });
+          }
+          idempotencyKey = rawKey;
+        }
+      }
+
       const result = await routeLead(
         buildInput(kind, body, workspaceId),
         sourceMeta,
+        idempotencyKey === undefined ? {} : { idempotencyKey },
       );
 
       if (!result.ok) {
+        if (result.error.kind === "idempotency_conflict") {
+          // #7869 D6 — the operator's signal that a keyed lead was refused.
+          // Never the key, the email or the payload.
+          request.log.warn(
+            { kind, siteId: workspaceId, outcome: "idempotency_conflict" },
+            "lead idempotency_conflict",
+          );
+          return reply.status(422).send({
+            error: "idempotency_key_reused",
+            message: "This Idempotency-Key was used for a different lead.",
+          });
+        }
         if (result.error.kind === "invalid_input") {
           return reply
             .status(400)
@@ -252,6 +311,7 @@ function makeLeadsRoute(kind: LeadKind): FastifyPluginAsync {
           ip: sourceMeta.ip,
           persisted: result.persisted,
           emailKind,
+          replayed: result.replayed === true,
         },
         "lead routed",
       );
@@ -292,12 +352,15 @@ function makeLeadsRoute(kind: LeadKind): FastifyPluginAsync {
       }
 
       // Fire-and-forget: track() never throws; no need to hold the response.
-      void track("lead-captured", {
-        source: body["source"] as string | undefined,
-        locale: (body["payload"] as Record<string, unknown> | undefined)?.[
-          "locale"
-        ] as string | undefined,
-      });
+      // #7869 D6 — a replay records nothing new: the first write counted it.
+      if (!result.replayed) {
+        void track("lead-captured", {
+          source: body["source"] as string | undefined,
+          locale: (body["payload"] as Record<string, unknown> | undefined)?.[
+            "locale"
+          ] as string | undefined,
+        });
+      }
 
       return reply.status(201).send({
         id: result.id,

package/templates/apps/api/src/routes/webhooks/README.md

@@ -132,6 +132,45 @@ and the row is still stamped — the quote is never overwritten. The stamp
 runs beside the telemetry + billing tasks, never instead of them, and an
 event without the key never touches `flowCheckout`. Always 200.
 
+## Site filter (#7868)
+
+The hub's Stripe account is shared with its spoke sites, so this endpoint
+receives every site's events. A Checkout session says which site opened it
+through `metadata.site`.
+
+- **The stamp.** Every session the hub creates — `POST /v1/checkout/sessions`
+  and the recommender's quoted checkout (`POST /v1/flows/:slug/checkout`) —
+  carries `metadata.site` = `currentSiteId()`: `AILK_SITE_ID`, else
+  `"default"`. The key, the stamp and the foreign test are defined once in
+  `lib/site.ts` (`SITE_STAMP_KEY`, `siteStamp()`, `isForeignSiteStamp()`).
+  No request field can set or override it.
+- **The filter.** A `checkout.session.completed` or `checkout.session.expired`
+  whose `metadata.site` is a non-empty string other than `currentSiteId()` is
+  another site's. The handler takes no action — no telemetry, billing bind,
+  recommender stamp or request-paid stamp — logs `outcome: "foreign_site"`
+  with the foreign `stamp` (first 64 characters) and the hub's `ownSite`, and
+  answers 200. The comparison is exact and case-sensitive. The event is still
+  marked seen, so a redelivery is the usual duplicate short-circuit.
+- **Unstamped is own.** A session with no stamp, or an empty one, is the hub's
+  and is handled as before: hub Payment Links, hosted invoices, portal events
+  and sessions opened before the stamp shipped carry none, so strict equality
+  would stop hub checkout (roadmap D4).
+- **One alias per deployment.** Two deployments on one Stripe account that
+  both leave `AILK_SITE_ID` unset both stamp `"default"` and treat each
+  other's sessions as their own — give each a distinct `AILK_SITE_ID`. The
+  alias is a deployment-wide constant: every instance and environment on the
+  account must agree on it, and change it only while no Checkout session is
+  open (a session lives up to 24 hours). A session whose stamp no longer
+  matches is acked as foreign and never retried, so its hub side effects are
+  lost; the `stamp` / `ownSite` pair in the log line is how to spot that drift.
+- **Not filtered.** `customer.*`, `invoice.*` and subscription events carry no
+  session metadata and are handled as before. Filtering them needs a stamp on
+  those objects, which the spoke-checkout package writes (spoke pattern
+  Phase 3).
+- **A label, not a boundary.** The stamp is written by whoever holds the
+  account's secret key. It separates cooperating sites on one account, not
+  tenants.
+
 ## Dunning (#6034)
 
 Two arms record a per-subscriber lifecycle state so a failed renewal is no