create-ailk 0.17.0 → 0.19.0

package/templates/database/__tests__/member-contract.db.test.ts

@@ -0,0 +1,413 @@
+/**
+ * @file member-contract.db.test.ts
+ *
+ * LIVE-DATABASE proof of the member contract (#8168, spec
+ * docs/specs/8168-member-area-data-model-spec.md D1–D3, D8, D9; AC-2, AC-4).
+ * Requires DATABASE_URL pointing at a Postgres with the migrations applied —
+ * the suite SKIPS when DATABASE_URL is unset, keeping the workspace Jest run
+ * DB-free (the repo convention; the `apps/api Route Tests (Postgres)`
+ * workflow exercises it).
+ *
+ * Uses the `pg` driver directly, as `member-area.db.test.ts` does. What it
+ * proves that a mock cannot:
+ *   1. Every CHECK the migration adds to `interactions` and `piece_versions`
+ *      refuses its named shape, and an inbound `message` lands.
+ *   2. A version can only name a piece of ITS OWN Person and workspace
+ *      (piece_versions_piece_fk), and a version number is unique per piece.
+ *   3. The request-quote backfill, re-executed VERBATIM from the migration
+ *      file (the `flow-workspace-key.db.test.ts` technique), seeds a workspace
+ *      that has no magnet, leaves a workspace's own `request-quote` row
+ *      byte-for-byte, and adds nothing when run again. It runs inside a
+ *      transaction that is rolled back, so no other suite sharing the
+ *      database ever sees its rows.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { requestQuoteFlowConfig } from "@working-theory/validation";
+import { Client } from "pg";
+
+const describeDb = process.env.DATABASE_URL ? describe : describe.skip;
+
+const MIGRATION_SQL = readFileSync(
+  join(
+    __dirname,
+    "..",
+    "migrations",
+    "20261012120000_member_contract",
+    "migration.sql",
+  ),
+  "utf8",
+);
+
+/** The text between the `-- BEGIN request-quote backfill` / `-- END …` markers. */
+function backfillBlock(sql: string): string {
+  const match =
+    /-- BEGIN request-quote backfill\n([\s\S]*?)-- END request-quote backfill/.exec(
+      sql,
+    );
+  if (!match?.[1]) throw new Error("request-quote backfill markers not found");
+  return match[1];
+}
+
+describeDb("the member contract (#8168 D1–D3, AC-2, live DB)", () => {
+  let db: Client;
+  const WS_1 = "wksp_01920000-8168-7000-8000-0000000000b1";
+  const USER = "user_01920000-8168-7000-8000-0000000000b1";
+  const ASSET = "asset_01920000-8168-7000-8000-0000000000b1";
+  let person1: string;
+  let person2: string;
+  let piece1: string;
+
+  const cleanup = async () => {
+    await db.query(`DELETE FROM "piece_versions" WHERE "workspace_id" = $1`, [
+      WS_1,
+    ]);
+    await db.query(`DELETE FROM "interactions" WHERE "workspace_id" = $1`, [
+      WS_1,
+    ]);
+    await db.query(`DELETE FROM "pieces" WHERE "workspace_id" = $1`, [WS_1]);
+    await db.query(`DELETE FROM "people" WHERE "workspace_id" = $1`, [WS_1]);
+  };
+
+  beforeAll(async () => {
+    db = new Client({ connectionString: process.env.DATABASE_URL });
+    await db.connect();
+    await cleanup();
+    const insertPerson = (email: string) =>
+      db.query<{ id: string }>(
+        `INSERT INTO "people" ("workspace_id", "email", "updated_at") VALUES ($1, $2, now()) RETURNING "id"`,
+        [WS_1, email],
+      );
+    person1 = (await insertPerson("one@example.com")).rows[0]!.id;
+    person2 = (await insertPerson("two@example.com")).rows[0]!.id;
+    piece1 = (
+      await db.query<{ id: string }>(
+        `INSERT INTO "pieces" ("workspace_id", "person_id", "title", "stage", "updated_by", "updated_at")
+         VALUES ($1, $2, 'Homepage copy', 'writing', $3, now()) RETURNING "id"`,
+        [WS_1, person1, USER],
+      )
+    ).rows[0]!.id;
+  });
+
+  afterAll(async () => {
+    await cleanup();
+    await db.end();
+  });
+
+  type InteractionCols = {
+    direction?: string;
+    kind?: string;
+    subject?: string;
+    body?: string;
+    payload?: unknown;
+  };
+  const insertInteraction = (cols: InteractionCols = {}) =>
+    db.query<{ id: string; kind: string }>(
+      `INSERT INTO "interactions" ("workspace_id", "person_id", "channel", "direction", "kind", "subject", "body", "payload", "created_by")
+       VALUES ($1, $2, 'member', $3, $4, $5, $6, $7, $8) RETURNING "id", "kind"`,
+      [
+        WS_1,
+        person1,
+        cols.direction ?? "inbound",
+        cols.kind ?? "message",
+        cols.subject ?? "A question",
+        cols.body ?? "Can we talk?",
+        cols.payload === undefined ? null : JSON.stringify(cols.payload),
+        USER,
+      ],
+    );
+
+  const quotePayload = {
+    flowSlug: "request-quote",
+    items: [{ name: "need", label: "What do you need?", value: "A homepage" }],
+  };
+
+  it("an existing outbound row keeps kind `message` by default, and an inbound message lands", async () => {
+    const outbound = await db.query<{ kind: string }>(
+      `INSERT INTO "interactions" ("workspace_id", "person_id", "channel", "direction", "subject", "body", "created_by")
+       VALUES ($1, $2, 'member', 'outbound', 'Draft 1', 'Here it is', $3) RETURNING "kind"`,
+      [WS_1, person1, USER],
+    );
+    expect(outbound.rows[0]!.kind).toBe("message");
+    const inbound = await insertInteraction();
+    expect(inbound.rows[0]!.id).toMatch(/^intx_/);
+    const withLink = await insertInteraction({
+      payload: { link: "https://example.com" },
+    });
+    expect(withLink.rows[0]!.kind).toBe("message");
+  });
+
+  it("an inbound quote and review with a payload and an empty body land", async () => {
+    await insertInteraction({
+      kind: "quote",
+      subject: "Request a quote",
+      body: "",
+      payload: quotePayload,
+    });
+    await insertInteraction({
+      kind: "review",
+      subject: "Homepage copy",
+      body: "",
+      payload: { pieceId: piece1, version: 1, review: "approved" },
+    });
+  });
+
+  it.each([
+    [
+      "an outbound quote",
+      { direction: "outbound", kind: "quote", payload: quotePayload },
+      "interactions_outbound_shape",
+    ],
+    [
+      "an outbound message with a payload",
+      { direction: "outbound", payload: { link: "https://example.com" } },
+      "interactions_outbound_shape",
+    ],
+    [
+      "a quote with no payload",
+      { kind: "quote", body: "" },
+      "interactions_payload_by_kind",
+    ],
+    [
+      "a review with no payload",
+      { kind: "review", body: "" },
+      "interactions_payload_by_kind",
+    ],
+    ["an empty-body message", { body: "" }, "interactions_body_length"],
+    ["an all-space message body", { body: "   " }, "interactions_body_length"],
+    [
+      "a quote body over 10000 characters",
+      { kind: "quote", body: "b".repeat(10001), payload: quotePayload },
+      "interactions_body_length",
+    ],
+    ["kind `note`", { kind: "note" }, "interactions_kind_allowed"],
+    [
+      "direction `sideways`",
+      { direction: "sideways" },
+      "interactions_direction_allowed",
+    ],
+    [
+      "a quote whose payload is over 262144 bytes",
+      {
+        kind: "quote",
+        body: "",
+        payload: { ...quotePayload, pad: "x".repeat(262144) },
+      },
+      "interactions_payload_size",
+    ],
+  ])("refuses %s", async (_label, cols, constraint) => {
+    await expect(insertInteraction(cols)).rejects.toMatchObject({
+      code: "23514",
+      constraint,
+    });
+  });
+
+  type VersionCols = {
+    person_id?: string;
+    piece_id?: string;
+    version?: number;
+    asset_id?: string | null;
+    link?: string | null;
+    note?: string | null;
+    review?: string | null;
+    review_comment?: string | null;
+    reviewed_at?: string | null;
+  };
+  const insertVersion = (cols: VersionCols = {}) =>
+    db.query<{ id: string }>(
+      `INSERT INTO "piece_versions" ("workspace_id", "person_id", "piece_id", "version", "asset_id", "link", "note", "delivered_by", "review", "review_comment", "reviewed_at")
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11) RETURNING "id"`,
+      [
+        WS_1,
+        cols.person_id ?? person1,
+        cols.piece_id ?? piece1,
+        cols.version ?? 99,
+        cols.asset_id === undefined ? null : cols.asset_id,
+        cols.link === undefined ? "https://example.com/draft" : cols.link,
+        cols.note ?? null,
+        USER,
+        cols.review ?? null,
+        cols.review_comment ?? null,
+        cols.reviewed_at ?? null,
+      ],
+    );
+
+  it("mints a pver_ id and accepts a file version and a reviewed link version", async () => {
+    const file = await insertVersion({
+      version: 1,
+      asset_id: ASSET,
+      link: null,
+    });
+    expect(file.rows[0]!.id).toMatch(/^pver_[0-9a-f-]{36}$/);
+    await insertVersion({
+      version: 2,
+      note: "Second pass",
+      review: "changes-requested",
+      review_comment: "Shorter, please",
+      reviewed_at: new Date().toISOString(),
+    });
+  });
+
+  it.each([
+    [
+      "both a file and a link",
+      { asset_id: ASSET },
+      "piece_versions_one_target",
+    ],
+    ["neither a file nor a link", { link: null }, "piece_versions_one_target"],
+    [
+      "an http:// link",
+      { link: "http://example.com" },
+      "piece_versions_link_https",
+    ],
+    [
+      "an https://user@host link",
+      { link: "https://user@example.com" },
+      "piece_versions_link_https",
+    ],
+    [
+      "a link containing a space",
+      { link: "https://example.com/a b" },
+      "piece_versions_link_https",
+    ],
+    ["version 0", { version: 0 }, "piece_versions_version_positive"],
+    ["an all-space note", { note: "  " }, "piece_versions_note_length"],
+    [
+      "review `rejected`",
+      { review: "rejected", reviewed_at: "2026-10-10T00:00:00Z" },
+      "piece_versions_review_allowed",
+    ],
+    [
+      "changes-requested without a comment",
+      { review: "changes-requested", reviewed_at: "2026-10-10T00:00:00Z" },
+      "piece_versions_changes_need_comment",
+    ],
+    [
+      "a review without reviewed_at",
+      { review: "approved" },
+      "piece_versions_review_stamped",
+    ],
+    [
+      "a comment without a review",
+      { review_comment: "Hmm" },
+      "piece_versions_comment_needs_review",
+    ],
+    [
+      "a 5001-character comment",
+      {
+        review: "approved",
+        review_comment: "c".repeat(5001),
+        reviewed_at: "2026-10-10T00:00:00Z",
+      },
+      "piece_versions_comment_length",
+    ],
+    [
+      "a lead_ asset id",
+      { asset_id: "lead_01920000-8168-7000-8000-0000000000b1", link: null },
+      "piece_versions_asset_id_format",
+    ],
+  ])("refuses a version with %s", async (_label, cols, constraint) => {
+    await expect(insertVersion(cols)).rejects.toMatchObject({
+      code: "23514",
+      constraint,
+    });
+  });
+
+  it("refuses a version naming another Person's piece (the three-column FK)", async () => {
+    await expect(
+      insertVersion({ person_id: person2, version: 50 }),
+    ).rejects.toMatchObject({
+      code: "23503",
+      constraint: "piece_versions_piece_fk",
+    });
+  });
+
+  it("refuses a second version 1 of one piece", async () => {
+    await expect(insertVersion({ version: 1 })).rejects.toMatchObject({
+      code: "23505",
+      constraint: "piece_versions_piece_id_version_key",
+    });
+  });
+
+  it("refuses to delete a piece that has a version (RESTRICT)", async () => {
+    await expect(
+      db.query(`DELETE FROM "pieces" WHERE "id" = $1`, [piece1]),
+    ).rejects.toMatchObject({
+      code: "23503",
+      constraint: "piece_versions_piece_fk",
+    });
+  });
+});
+
+describeDb("the request-quote backfill (#8168 D8, D9, AC-4, live DB)", () => {
+  let db: Client;
+  const ORG = "org_01920000-8168-7000-8000-0000000000c1";
+  const WS_NEW = "wksp_01920000-8168-7000-8000-0000000000c1";
+  const WS_OWNS = "wksp_01920000-8168-7000-8000-0000000000c2";
+  const block = backfillBlock(MIGRATION_SQL);
+
+  beforeAll(async () => {
+    db = new Client({ connectionString: process.env.DATABASE_URL });
+    await db.connect();
+  });
+
+  afterAll(async () => {
+    await db.end();
+  });
+
+  const magnets = (workspaceId: string) =>
+    db.query<Record<string, unknown>>(
+      `SELECT * FROM "flow_definitions" WHERE "workspace_id" = $1 AND "slug" = 'request-quote'`,
+      [workspaceId],
+    );
+
+  it("seeds a workspace with no magnet, leaves a workspace's own row untouched, and adds nothing on re-run", async () => {
+    await db.query("BEGIN");
+    try {
+      await db.query(
+        `INSERT INTO "organizations" ("id", "name", "slug", "updated_at") VALUES ($1, 'O', $2, now())`,
+        [ORG, `o-8168-${Date.now()}`],
+      );
+      await db.query(
+        `INSERT INTO "workspaces" ("id", "organization_id", "name", "slug", "updated_at")
+         VALUES ($1, $3, 'New', 'new', now()), ($2, $3, 'Owns', 'owns', now())`,
+        [WS_NEW, WS_OWNS, ORG],
+      );
+      await db.query(
+        `INSERT INTO "flow_definitions" ("site_id", "workspace_id", "slug", "config", "kind", "title", "status", "updated_at")
+         VALUES ($1, $1, 'request-quote', '{"mine":true}', 'diagnostic', 'Theirs', 'live', now())`,
+        [WS_OWNS],
+      );
+      const before = (await magnets(WS_OWNS)).rows;
+
+      await db.query(block);
+
+      const seeded = (await magnets(WS_NEW)).rows;
+      expect(seeded).toHaveLength(1);
+      expect(seeded[0]).toMatchObject({
+        site_id: WS_NEW,
+        workspace_id: WS_NEW,
+        kind: "contact",
+        title: "Request a quote",
+        status: "draft",
+        customers_enabled: true,
+        config: requestQuoteFlowConfig,
+      });
+      expect((await magnets(WS_OWNS)).rows).toEqual(before);
+
+      const { rows: total } = await db.query<{ n: string }>(
+        `SELECT count(*)::text AS "n" FROM "flow_definitions" WHERE "slug" = 'request-quote'`,
+      );
+      await db.query(block);
+      const { rows: again } = await db.query<{ n: string }>(
+        `SELECT count(*)::text AS "n" FROM "flow_definitions" WHERE "slug" = 'request-quote'`,
+      );
+      expect(again[0]!.n).toBe(total[0]!.n);
+      expect((await magnets(WS_NEW)).rows).toEqual(seeded);
+      expect((await magnets(WS_OWNS)).rows).toEqual(before);
+    } finally {
+      await db.query("ROLLBACK");
+    }
+  });
+});

package/templates/database/__tests__/seed.test.ts

@@ -10,6 +10,12 @@
  * `createAuth({ prisma })` DI pattern in apps-paid/admin/__tests__.
  */
 
+import {
+  REQUEST_QUOTE_FLOW_SLUG,
+  REQUEST_QUOTE_FLOW_TITLE,
+  requestQuoteFlowConfig,
+} from "@working-theory/validation";
+
 import {
   DEFAULT_ORG_ID,
   DEFAULT_ORG_SLUG,
@@ -23,8 +29,9 @@ function makeStubPrisma(workspaceCount: number) {
   const organizationUpsert = jest.fn().mockResolvedValue({});
   const workspaceUpsert = jest.fn().mockResolvedValue({});
   const workspaceCountFn = jest.fn().mockResolvedValue(workspaceCount);
+  const flowDefinitionUpsert = jest.fn().mockResolvedValue({});
 
-  // Minimal Prisma delegate stub — only the two delegates
+  // Minimal Prisma delegate stub — only the three delegates
   // provisionDefaultWorkspace touches. The full PrismaClient delegate method
   // signatures are impractical to satisfy for a hand-built DB-free stub, so a
   // double assertion through `unknown` is the sanctioned boundary here.
@@ -32,9 +39,16 @@ function makeStubPrisma(workspaceCount: number) {
   const prisma = {
     organization: { upsert: organizationUpsert },
     workspace: { count: workspaceCountFn, upsert: workspaceUpsert },
+    flowDefinition: { upsert: flowDefinitionUpsert },
   } as unknown as DefaultWorkspacePrismaClient;
 
-  return { prisma, organizationUpsert, workspaceUpsert, workspaceCountFn };
+  return {
+    prisma,
+    organizationUpsert,
+    workspaceUpsert,
+    workspaceCountFn,
+    flowDefinitionUpsert,
+  };
 }
 
 describe("provisionDefaultWorkspace (#3622)", () => {
@@ -86,3 +100,41 @@ describe("provisionDefaultWorkspace (#3622)", () => {
     expect(workspaceUpsert).not.toHaveBeenCalled();
   });
 });
+
+describe("provisionDefaultWorkspace — the request-quote magnet (#8168 D8, C4, AC-5)", () => {
+  it("upserts the default workspace's draft request-quote magnet, insert-if-absent, after the workspace", async () => {
+    const { prisma, workspaceUpsert, flowDefinitionUpsert } = makeStubPrisma(0);
+
+    await provisionDefaultWorkspace(prisma);
+
+    expect(flowDefinitionUpsert).toHaveBeenCalledTimes(1);
+    expect(flowDefinitionUpsert).toHaveBeenCalledWith({
+      where: {
+        siteId_slug: { siteId: DEFAULT_WORKSPACE_ID, slug: REQUEST_QUOTE_FLOW_SLUG },
+      },
+      create: {
+        siteId: DEFAULT_WORKSPACE_ID,
+        workspaceId: DEFAULT_WORKSPACE_ID,
+        slug: "request-quote",
+        config: requestQuoteFlowConfig,
+        kind: "contact",
+        title: REQUEST_QUOTE_FLOW_TITLE,
+        status: "draft",
+        customersEnabled: true,
+      },
+      // Empty: an existing (site_id, slug) row is never overwritten (D8, C6).
+      update: {},
+    });
+    expect(workspaceUpsert.mock.invocationCallOrder[0]).toBeLessThan(
+      flowDefinitionUpsert.mock.invocationCallOrder[0] ?? 0,
+    );
+  });
+
+  it("makes no flowDefinition call when a workspace already exists", async () => {
+    const { prisma, flowDefinitionUpsert } = makeStubPrisma(1);
+
+    await provisionDefaultWorkspace(prisma);
+
+    expect(flowDefinitionUpsert).not.toHaveBeenCalled();
+  });
+});

package/templates/database/inbox/schema.prisma

@@ -81,6 +81,18 @@ model Lead {
   // Backfilled by database/migrations/20261010121000_person_backfill.
   personId String? @map("person_id")
 
+  // #8185 D1 — the hub's conclusion, at write time, that this lead is a
+  // spoke's LIVE paid checkout: the submit carried a registered spoke's key,
+  // was not relayed for a visitor, and passed the #7877 checkout plan rule's
+  // own predicate (a `cs_live_` Idempotency-Key and the checkout shape).
+  // Written only by `apps/api/src/services/lead-routing.ts`'s submit create
+  // and never updated; read only by `apps/api/src/lib/member-store.ts`'s
+  // `listMemberPurchases`, which serves a marked lead as a purchase. A lead
+  // written before the column existed reads false: `viaSpoke` was never
+  // stored, so its provenance cannot be proven (no backfill). No index: the
+  // read filters by the already-indexed `personId`.
+  spokeCheckout Boolean @default(false) @map("spoke_checkout")
+
   // #7869 — the idempotency guarantee, scoped per workspace so a key can
   // never reach another tenant's row.
   @@unique([workspaceId, idempotencyKey])
@@ -144,36 +156,92 @@ model Person {
 /// tenantDb(tenant).memberArea; read by a client only through
 /// lib/member-store.ts. `stage` is one of the workspace's declared stages
 /// (WorkspacePieceStages), checked at write time, never an enum.
+///
+/// #8168 D5 — `approvedAt` is set in the same transaction as an `approved`
+/// review of the latest PieceVersion and freezes review: once set, no further
+/// review lands. Approval is a piece-level fact; the version's own `review`
+/// records which version was approved.
 model Piece {
-  id          String   @id @default(dbgenerated("('piece_'::text || (uuidv7())::text)")) @db.Text
-  workspaceId String   @map("workspace_id")
-  personId    String   @map("person_id")
-  title       String   @db.VarChar(200)
-  stage       String   @db.VarChar(40)
-  needsClient Boolean  @default(false) @map("needs_client")
-  updatedBy   String   @map("updated_by")
-  createdAt   DateTime @default(now()) @map("created_at")
-  updatedAt   DateTime @updatedAt @map("updated_at")
+  id          String    @id @default(dbgenerated("('piece_'::text || (uuidv7())::text)")) @db.Text
+  workspaceId String    @map("workspace_id")
+  personId    String    @map("person_id")
+  title       String    @db.VarChar(200)
+  stage       String    @db.VarChar(40)
+  needsClient Boolean   @default(false) @map("needs_client")
+  updatedBy   String    @map("updated_by")
+  approvedAt  DateTime? @map("approved_at")
+  createdAt   DateTime  @default(now()) @map("created_at")
+  updatedAt   DateTime  @updatedAt @map("updated_at")
 
-  person Person @relation(fields: [personId, workspaceId], references: [id, workspaceId], onDelete: Restrict, map: "pieces_person_fk")
+  person   Person         @relation(fields: [personId, workspaceId], references: [id, workspaceId], onDelete: Restrict, map: "pieces_person_fk")
+  versions PieceVersion[]
 
   @@index([workspaceId, personId, createdAt])
+  // #8168 D1 — redundant with the PK, load-bearing as the target of
+  // piece_versions_piece_fk: a version names a piece of THIS Person in THIS
+  // workspace, as one database fact.
+  @@unique([id, personId, workspaceId])
   @@map("pieces")
 }
 
-/// Interaction — one message on a client's record (#7877): the original CRM
-/// spec's Interaction cut to one channel and one direction. An inbound reply
-/// is a later second `direction` value on this table. `readAt` is when a
-/// member read FIRST served the row to the client's spoke — a delivery
-/// stamp, not proof a human read it.
+/// PieceVersion — one delivery of a piece to its client (#8168 D1, D2): a
+/// file (`assetId`, a private library asset of the same workspace) or a link
+/// (`link`, https only), never both, numbered from 1 per piece. The client's
+/// review of it (`review`, `reviewComment`, `reviewedAt`) is recorded on the
+/// version itself. There is NO round count, limit or remaining-count column,
+/// by design (#8140 disposition 3).
+///
+/// Its one relation is the three-column FK onto `pieces(id, person_id,
+/// workspace_id)`, so the piece, its Person and the workspace are all one
+/// database fact. `assetId` and `deliveredBy` name rows of other namespaces:
+/// plain columns with format CHECKs, no foreign key (ADR 0009).
+model PieceVersion {
+  id            String    @id @default(dbgenerated("('pver_'::text || (uuidv7())::text)")) @db.Text
+  workspaceId   String    @map("workspace_id")
+  personId      String    @map("person_id")
+  pieceId       String    @map("piece_id")
+  version       Int
+  assetId       String?   @map("asset_id")
+  link          String?   @db.VarChar(2048)
+  note          String?   @db.Text
+  deliveredBy   String    @map("delivered_by")
+  deliveredAt   DateTime  @default(now()) @map("delivered_at")
+  review        String?   @db.VarChar(24)
+  reviewComment String?   @map("review_comment") @db.Text
+  reviewedAt    DateTime? @map("reviewed_at")
+
+  piece Piece @relation(fields: [pieceId, personId, workspaceId], references: [id, personId, workspaceId], onDelete: Restrict, map: "piece_versions_piece_fk")
+
+  @@unique([pieceId, version])
+  // A client's artifacts: workspace_id = $1 AND person_id = $2 ORDER BY delivered_at DESC.
+  @@index([workspaceId, personId, deliveredAt])
+  // The public asset read's "is this asset a version file" check (AC-MAA-21).
+  @@index([assetId])
+  @@map("piece_versions")
+}
+
+/// Interaction — one entry on a client's record (#7877): the original CRM
+/// spec's Interaction cut to one channel. `readAt` is when a member read
+/// FIRST served the row to the client's spoke — a delivery stamp, not proof a
+/// human read it.
+///
+/// #8168 D3/D4 — `direction` is `outbound` (an operator's message, #7877) or
+/// `inbound` (a client's own write); `kind` is `message`, `quote` or
+/// `review`. An outbound row is always a `message` with no `payload`
+/// (`interactions_outbound_shape`); a `quote` or `review` row carries the
+/// stored payload `packages/validation`'s member.ts types. Every existing
+/// reader filters to `direction: "outbound"`, so an inbound row is invisible
+/// to them until a reader opts in.
 model Interaction {
   id          String    @id @default(dbgenerated("('intx_'::text || (uuidv7())::text)")) @db.Text
   workspaceId String    @map("workspace_id")
   personId    String    @map("person_id")
   channel     String    @db.VarChar(16)
   direction   String    @db.VarChar(16)
+  kind        String    @default("message") @db.VarChar(16)
   subject     String    @db.VarChar(200)
   body        String    @db.Text
+  payload     Json?
   assetId     String?   @map("asset_id")
   createdBy   String    @map("created_by")
   createdAt   DateTime  @default(now()) @map("created_at")
@@ -338,6 +406,13 @@ model FlowDefinition {
   // across the namespace boundary, so this is a plain string — but a stated
   // one rather than a coincidence.
   listingId String?  @map("listing_id")
+  /// #8168 D7 — whether a signed-in client may submit this magnet from the
+  /// member area. A column, not a config block, because a spoke seed refuses
+  /// non-seedable config (#7876); `upsertFlowDefinition` never names it, so a
+  /// seed never changes it. Independent of `status`: the seeded
+  /// `request-quote` magnet is `draft` (never served anonymously) with
+  /// `customersEnabled = true`.
+  customersEnabled Boolean @default(false) @map("customers_enabled")
   createdAt DateTime @default(now()) @map("created_at")
   updatedAt DateTime @updatedAt @map("updated_at")