source: .forge/design/data/entity-map.md · generated — edit the markdown, not this file

Empire Teas CRM — Conceptual Entity Map

Status: accepted — proposed 2026-08-31, accepted 2026-08-31 (lead sign-off: Tharinda) Scope: every persistent entity V1 needs, and every relationship between them, in the one public schema (FS-14 collapsed the former two) Related: .forge/project-prd.md §Domain Model, .forge/design/architecture.md §Core / Domain Separation, forge-et-be/docs/data-model.md AD #31 (2026-09-09, Rev 4 below): FS-14 collapsed the split — one public schema, feature-first packages. The Home column below names the unqualified table; the former per-schema prefixes are dropped and the cluster headings name the owning capability (its feature-first package once built). Relationships, cardinalities and statuses are unchanged; where a row reasons from the old boundary or a retired guard, read it as the historical rationale for a placement that now stands as plain data-model design.

Why this document exists

The PRD’s §Domain Model states each entity in one row; data-model.md §2 carries the verified schema for one subsystem (bulk pricing) and stubs for everything else; the architecture’s module layout names which module owns which entity family. No single document draws the whole graph, and several load-bearing edges cross feature boundaries — a quote’s relationship to a deal is neither F7’s decision alone nor F2’s; a lead’s conversion touches F11, F1 and F2 at once. Left unmapped, each feature spec would settle its corner independently, and the edges between corners would be settled twice, differently.

This map fixes the conceptual graph — entities, homes, edges, cardinalities — so every feature spec designs against the same picture. It deliberately contains no DDL and no field lists beyond what an edge needs: fields are the owning spec’s job, and the realized schema lives in data-model.md, which this map never overrides.

Authority (per .claude/rules/source-trust.md): the PRD outranks this map on what; data-model.md outranks it on any realized schema; architecture.md outranks it on layering. This map’s added value is the edges none of them state — each marked with a status and the spec that confirms it. On any conflict, raise it; two conflicts found during authoring are recorded in §Contradictions rather than silently resolved.

How to read it

Cardinality is written from the left entity: Deal N:1 Account = many deals per account. M:N via x names the join entity. Home is the owning table in the one public schema (FS-14) plus, via the cluster heading, the feature-first package that owns it. Every entity-bearing table additionally carries the §1 base columns from data-model.md (identity, version, audit stamps; effective-dated tables per the temporal conventions) — not restated per row.

Status Meaning
shipped Migration on main today
verified DDL written and proof-verified in data-model.md §2, not yet shipped (F26 / feature specs ship it)
designed Stated in an approved document (PRD §Domain Model, architecture module layout)
proposed This map’s recommendation — the named spec confirms or revises it
open Blocked on a decision or OQ — the note says which

The entangled entities (typed 1:1 tea extension tables, extension point 1): Account (struck at Rev 12 — F1-a ships it as flat columns), Deal, Product (struck at Rev 7 — the buying standard is the sellable record), Quote, LineItem (architecture §Entity extension, LineItem added by SP-ARCH-003). This map proposed Lead as a sixth; D-4 is closed against it at Rev 15 — F11-a ships lead as flat columns.

The spine

The hub entities and the edges everything else hangs off. [t] = has a tea 1:1 extension table.

                            app_user (owns most records; one role each — roles are Empire's, FS-6 + F5-k)
                                 │
   converts to (D-5)             │
lead    ──────────▶ account ◀──N:1── contact
   │                    │ 1:N
   │ N:1 source         ▼
   │                 deal[t] ──N:1─▶ stage ──N:1─▶ pipeline
   │                  │  │  │ 1:1
   │                  │  │  └─▶ product_brief (private label, F8)
   │                  │  └────▶ sample 1:N (rounds, F6)
   │                  │
   │           ┌──────┴──────────┐
   │           ▼ 1:N             ▼ 1:N (D-2)
   │        quote[t]        deal_line_item ─N:1▶ buying_standard
   │           │ 1:N                                │ 1:N
   │           ▼                                    ▼
   │        line_item ──1:1─▶ line_item_bulk_price ──▶ buying_standard_price
   │           │ N:1 buying_standard                    │ N:1        │ anchored to
   │           ▼                                        ▼            ▼
   │        quote_cost_line (N:1 quote)        buying_standard   auction_sale
   │                                            (N:1 account — the sellable record, Rev 7)
   │
one `public` schema (FS-14); `[t]` = has a typed 1:1 extension table (formerly a tea-schema table).
cross-cutting, attach to the entities above:
  activity · note · tag (per entity type) · email_message · attachment (D-6) · custom fields (JSONB, F34)
  timeline = stored timeline_event rows, one per event, written by each producer (D-7, confirmed by F1-a)
  search = each list's own q filter; no global search index (F31 dropped, Rev 25)

Clusters

1. Identity, access, audit — platform

Entity Home Status Realized by Notes
User app_user verified (§2.4) FS-6 + F5 Owns records across the system; region tag for P-34 scoping. Gains manager_id — a nullable self-reference (AD #30, 2026-09-07): the reporting hierarchy behind team scope — since AD #37 (2026-09-27) the hierarchy every key reaches down, so setting a manager is an access decision. Hierarchy and lifecycle policy — decided by AD #34 / AD #35 (2026-09-24), answering OQ-56: team is recursive through all levels; a user is pre-created by the settings.manage holder (access.manage until 2026-10-26; no auto-provisioning), deactivated and reactivated, never deleted; deactivation is refused while the user has direct reports or owns records, and deactivated users stay in the tree (F5-c)
User identity user_identity shipped (FS-6, 2026-09-15) FS-6 Microsoft-only login onto one user (AD #5 as refined by AD #28): provider (microsoft) + subject; table kept provider-generic so a later provider is data, not schema. No password hash anywhere — the local path was dropped (FS-6 spec Rev 1 removed user_credential). Changing a user’s email clears this link (AD #34), so the next sign-in re-links by the new address
Role role shipped (FS-6, 2026-09-15) — AD #15 as refined by AD #30, #26, #32, #34 FS-6 + F5 + F5-k Admin-authored roles (AD #30, 2026-09-07); no templates (AD #32, 2026-09-11). Realigned by AD #34 (2026-09-24), built by F5-k: no superadmin and no non-deletable system role — the is_system flag and the superadmin row FS-6 shipped are removed; each role has an immutable key generated at creation and an editable display name; the only seeded row is an ordinary, editable IT Admin role, seeded by one Flyway migration in every environment together with one active user, holding settings.manage (it was seeded with access.manage, which V54 folded into settings.manage on AD #34’s refinement of 2026-10-26 — Rev 36); Empire’s administrator creates every other role from the catalog (the six confirmed roles + the Managing Director role are the recommended day-one set, not data). The template_key column and the role_template* tables FS-6 spec Rev 3 shaped are removed by spec Rev 5 (2026-09-11). User↔role is N:1 — one role per user (app_user.role_id; the M:N join and the most-permissive union are dropped); a role held by any user, active or deactivated, cannot be deleted, and at least one active user always holds settings.manage
Permission / grant catalog in code (per-package constants); grants role_grant shipped (FS-6, 2026-09-15) — AD #15 as refined by AD #30, #26, #34, #37 FS-6 + F5-k + F5-l (role, permission_key) grants — no scope column (AD #37, 2026-09-27; F5-l drops role_grant.scope) — over a code-declared catalog whose metadata — label, description, UI group — lives in code, not in a table. Each entity that has an owner (lead, account; deal, quote, sample in Phase 2) has a third key, <entity>.all, which widens the holder’s view or manage on it to every record and is refused without one of them; without it a key reaches the records owned by, or shared with, the user or anyone below them in the reporting tree. Was, until AD #37: (role, permission_key, scope) with a scope-aware flag per key. AD #34 (2026-09-24) makes the catalog minimal: <entity>.view / <entity>.manage per business entity (manage implies view), plus settings.manage (all configuration and all user, role and hierarchy administration — it absorbed access.manage on 2026-10-26, Rev 36), email.manage (own mailbox only), price.publish and quote.approve_sub_floor — listed in FS-6 Appendix A. No category axis, no * wildcard grant. Until AD #37: scope own / team / all per grant, with shares counted in own and team (AD #35 — see the Record share row); shares now count for the user and everyone above them. quote.approve_sub_floor is held by the Managing Director role in the recommended configuration (AD #26 unchanged). Was: (role, resource, level) grants with the level as a column — superseded 2026-09-07; then ~100–150 <resource>.<action> keys each carrying a read / edit / execute category (AD #32) — superseded 2026-09-24. Confirmed by FS-6 spec Rev 3 (2026-09-07): the grant table is role_grant keyed UNIQUE (role_id, permission_key), and the separate named-permission store (role_permission) is removed, so one table answers every check. The Tea Room / Executive role contents are Empire’s configuration (OQ-53 closed as not required, PRD Rev 37)
Audit event audit_event shipped — confirmed by F39 (spec FR-1; V24__audit_event.sql) F39 Append-only log of every write and every security event (sign-in success and refusal, sign-out, deactivation and reactivation, role and permission changes, sharing and reassignment, exports), written in the same transaction as the change — only the sign-in, refusal and sign-out events commit in a transaction of their own (FR-8); not reads; kept indefinitely in V1. The actor is a kind, not a reserved user: actor_kind is USER, SYSTEM (background work, the job’s name in actor_label) or ANONYMOUS (a refused sign-in that matched no user), and actor_user_id is set exactly when the actor is a USER — a plain id with no foreign key (spec Rev 2: users are never deleted in the application). The record is a loose (entity_type, entity_id) pair — the record’s table name and id, both set or both null (D-8). changes (only the changed fields, old/new; a hard delete’s before-image; a sensitive field as {"changed": true}) and context are JSON objects. The database refuses every UPDATE, DELETE and TRUNCATE. Indexed for one record’s history, one user’s actions and a time window. Event codes: forge-et-be/docs/audit/README.md
Session Spring Session JDBC tables shipped (FS-6) (V7__spring_session.sql) FS-6 Infrastructure, not domain — listed to keep it out of the domain graph. Deactivating a user deletes that user’s session rows by the principal-name index (AD #34, F5-c)

Key edges: app_user 1:N owns {lead, account, deal, quote, saved_view, mailbox_connection…} (designed — PRD); app_user 1:N is assigned activity (F3-a — the assignee gives no reach; a follow-up’s reach is its linked record’s, Rev 29). Every audit stamp (created_by/modified_by) is an FK to app_user (shipped convention, §1; product’s pair was owed by the migration that creates app_user — moot once the table retires, Rev 7). Every table carries created_at / modified_at, and created_by / modified_by where a person makes the change (AD #36) — F39 checks every table on main and adds the columns where missing. How the SYSTEM actor is represented against the created_by FK (a reserved app_user row kept out of sign-in, the last-admin count, the directory and pickers — or a nullable stamp plus an actor column) is F39’s decision.

2. CRM spine — lead, account, contact, deal, pipeline (+ typed extensions)

Entity Home Status Realized by Notes
Account account (flat columns — no account_profile) shipped — confirmed by F1-a (spec FR-S1; V15__account.sql) F1-a One table: name, country, region, customer type, website, owner (owner_id NOT NULL — AD #35; shareable through record_share), archive flag, preferred packaging and Incoterms (TEXT[] with vocabulary CHECKs), migration identity (D-11) and source_owner_name (F4-d FR-S1 — the Pipedrive owner’s name, never shown). The tea attributes are flat columns, not a 1:1 account_profile extension — AD #31 removed the vocabulary rule the split existed for. Required certifications are the account_certification join (D-10). LTV is an entered estimate (estimated_ltv + ltv_currency, FR-S1) — nothing in V1 computes lifetime value, because there is no order entity to compute it from (OQ-63); dormancy stays derived, from the latest timeline_event.occurred_at (FR-S6; the account list’s dormant flag, AC-28)
Contact contact shipped — F1-a (V19__contact.sql) F1 N:1 account (nullable). A contact added from a user’s Outlook contacts (F22) gets an account unless the user holds account.all, who may choose none (F22 spec FR-7); the per-user mapping to Outlook is the Contact sync link row. Several email addresses (confirmed by F20-l, Rev 37): contact.email stays the main address; the others are contact_email (contact_id, email, position, base columns; unique per contact by lower(email); N:1 contact; at most 20 per contact), and both are matched on F11-d’s trimmed, lower-cased address key (F20-l FR-1, FR-8)
Lead lead (flat columns — no lead_profile, D-4 closed) shipped — confirmed by F11-a (spec FR-S1; the lead migration) F11-a (table, intake, single-lead API) · F11-c, F11-d, F11-g, F11-h, F11-e, F12 (their own columns) Triage inbox record, not on a pipeline. One table, every field a flat column: company name and contact name (at least one, lead_has_party), contact email / phone / job title, website, country, buyer type (the account.customer_type vocabulary), estimated value + value_currency (USD), lead_source + lead_source_detail, inquiry text, received_at, status (new / approved / converted / archived — Archive / nurture is the archived status, with no separate nurture status, and restore returns archived to new, F11-f decisions 2 and 3), owner (owner_id nullable only for a Pipedrive import — AD #35, the named CHECK lead_unowned_only_imported; an unowned lead is visible only at all scope, through F11-b’s Unassigned filter; shareable through record_share), the optional matched account and contact (key edges below), and the migration identity (D-11), which on lead is also the intake’s replay key. Added later by the features that write them, not by F11-a: the tea details F12 extracts — built by F12 (V38__ai_invocation_and_lead_tea_fields.sql, F12 spec FR-T1): product_line, grade, volume, packaging (TEXT[]), incoterm, destination_port and timeline as nullable columns on lead, with named vocabulary and length CHECKs, and the certifications as the join table lead_certification (D-10; buying_standard_certification’s shape — the API that reads and writes them is F12’s wave 2); the AI outputs — score, priority, confidence, “why” and recommended action (F11-g), drafted follow-up (F11-h); and the conversion links (F11-e, D-5); and source_owner_name — built by F4-b (FR-9): the Pipedrive owner’s name, never shown, written only by a Pipedrive migration run. The score storage is F11-g’s. F11-c’s research snapshot is not on lead either: it lives in lead_research, one row per lead, written only by F11-c’s background job and its person-removal action, beside search_call (one row per search, no query text) and search_provider_pause (F11-c spec FR-S1, FR-L2, FR-L4; Rev 33). F11-d’s summary, spam / duplicate tag and proposed customer match are not lead columns: they live in lead_triage, one row per lead, written only by F11-d’s background job and its dismiss action, so the job never moves the lead’s version (F11-d spec FR-S1, decision 5; Rev 32). A migrated lead’s summary from its linked email lives in lead_mail_summary (designed — F11-j), one row per lead, written only by F11-j’s background job, for the same reason (F11-j spec FR-S1, D-4; Rev 53). F11-g’s priority, confidence, reason and next action likewise live in lead_ranking, one row per lead, written by F11-g’s background job and, at the conversion of a captured lead, by its copy of the capture’s ranking (origin capture, against crm for the job’s rows), and keeping the campaign focus a ranking read in focus and focus_campaign_name through every later write (F11-g spec FR-S1, FR-S4, FR-A9 — Rev 6; F36-c FR-CV1); hot / cold is computed when read and stored nowhere (F11-g spec FR-S1, FR-E1, decisions 6 and 8; Rev 38)
Lead source lead_source + lead_source_detail columns on lead shipped — confirmed by F11-a (spec FR-S1, FR-R1) F11-a Fixed set (Website / Trade Fair / Referral / Email / Other) as a vocabulary CHECK mirrored by LeadVocabularies, + free-text detail (which fair — F36 attribution). F17 charts group by the vocabulary. Named lead_source, not source, because source / source_ref is the migration-identity pair on every migratable table (D-11) — a rep’s “Referral” and F4-b’s 'pipedrive' must not share a column
Deal deal + deal_profile designed (PRD) F2 Core: title, value, currency, owner, expected close, label, status. Tea profile: volume + units, brand (OQ-20; banned word in core), destination interest. Rotting/age-in-stage computed from last-touch, not stored (F18/F24)
Pipeline pipeline designed (PRD/AD #11) F24 Admin-configurable; seeded Private Label + Bulk
Stage stage designed (AD #11) F24 N:1 pipeline, ordered; editable name + stable stage_type (core: NEW/WON/LOST; tea registers BRIEF/SAMPLE/QUOTE… via StageTypeProvider); win probability, rotting days

Key edges:

Relationship Cardinality Status Settled by Notes
Contact → Account N:1 (nullable) shipped — F1-a (V19__contact.sql) F1
Deal → Account N:1 designed F2 Required — B2B; every deal has a buyer org
Deal → Contact (primary) N:1 (nullable) designed F2 PRD deal creation names a person + org
Deal → Stage N:1 designed F2/F24 Pipeline reached via stage; a cross-pipeline move is a stage change. If pipeline_id is ever denormalized onto deal, use the FR-I1 composite-FK idiom
Deal status vs stage — proposed F2 Deal carries its own status (open/won/lost) alongside stage; a stage_type = WON stage and status = won must agree — F2 owns the mechanism
Lead → converted Account / Contact / Deal N:1 each (nullable) proposed (D-5) F11 Set at conversion; the lead row is kept (status: converted) — OQ-21 forbids deleting history
Lead → matched Account / Contact N:1 each (nullable) shipped — confirmed by F11-a (spec FR-O6) F11-a The existing customer an inquiry comes from, before any conversion: lead.account_id and lead.contact_id. Set by the intake, by PATCH, by F4-b when it migrates a Pipedrive lead whose organisation F4-d wrote, and proposed by F11-d’s duplicate detection. Not the conversion link (the row above, D-5). Changes nobody’s reach (AD #35): a lead’s reach is its own owner and shares, never its account’s, and the account’s reach never extends to the lead. The contact and account must agree when the link is set — checked by the API at that moment, not stored, so a contact that later moves to another account leaves the match as recorded
Lead / Deal → Sequence M:N via enrollment designed F25 See cluster 7

3. Commerce — the buying standard as the sellable record, deal line items, quote, line items — quoting (the catalog package is retired, Rev 7)

Entity Home Status Realized by Notes
Product — (dropped: V11__drop_product.sql) removed — FS-15, 2026-09-16 FS-15 There is no products catalog: the Buying Standard (cluster 4) is the sellable record for bulk and private label and takes over code / name, grade, origin, brand, held certifications (cluster 6), cost and price history. The shipped table, the catalog package (Product, ProductController — FS-10’s worked API example), ListPriceModel and the product.* keys are retired by the backend hand-off in PRD Rev 27; until then the product_id FKs below are drift to remove, not design
Deal line item deal_line_item (was deal_product) proposed (D-2, retargeted Rev 7) F26 Buying standard attached to a deal with qty + discount; rolls up into deal value (PRD F26). Mutable working set
Quote quote + tea quote extension (D-3) verified (§2.4) / proposed F7 Core: account, deal (D-1), currency, status, payment terms. Tea extension: Incoterm, destination market, readiness config — see C-1
Quote line item line_item verified (§2.4) F7 N:1 quote (CASCADE), N:1 buying_standard (was N:1 product — Rev 7, retarget owed in §2.4); unit_price is an immutable snapshot (FR-T7 trigger) — so “refresh price” replaces lines, never updates them
Quote cost line quote_cost_line verified (§2.4) F7 Named human-entered amounts (freight, certification, export docs); never computed
Quote revision quote_revision proposed F7 Append-only log (v1/v2/v3 + note + actor); PRD requires revision history and price-refresh logging
Readiness checklist (8-item) ChecklistEngine config, computed designed (built by F7-b — FS-13 cancelled, AD #29) F7 Not an entity — computed from quote state per checklist definition; the GP-floor gate is a GateRule. Sub-floor approval record: the named-permission approval is audited (cluster 1)

Key edges:

Relationship Cardinality Status Settled by Notes
Quote → Deal N:1 proposed (D-1) F7 §2.4 has account_id only — F7 adds deal_id; keep both consistent via the FR-I1 composite FK. Recommended NOT NULL (see D-1)
Quote → Account N:1 verified (§2.4) F7 Retained; pinned to the deal’s account by D-1’s composite FK
Deal line item → Deal / Buying standard N:1 / N:1 proposed (D-2, retargeted Rev 7) F26
Line item → Quote / Buying standard N:1 / N:1 verified — retargeted by FS-15 (line_item.buying_standard_id; data-model.md §2.4) F7 Quote lines seeded from the deal’s line items at quote creation (D-2)
Line item → bulk price snapshot 1:1 verified (§2.5) F26 line_item_bulk_price — the fifth entangled entity; composite FKs pin it to a published price and its cost (state-narrowing idiom)

4. Bulk pricing — pricing — settled, do not re-derive

The whole cluster is specified and DDL-verified in data-model.md §2 (SP-ARCH-003). Edges only, for completeness — §2 is the authority:

Relationship Cardinality Status
Buying standard → Account N:1 verified
Buying standard → Product — removed — Rev 7 (PRD Rev 27: the standard is the sellable record and carries grade / origin / brand itself; buying_standard.product_id is dropped by the data-model revision — Tharinda)
Price → Buying standard × validity effective-dated, one published per key shipped — F26-a (V29__price_and_cost.sql, Rev 17): the Rev 23 (no market axis) and Rev 31 (four-figure build-up) shape of data-model.md §2.2/§2.5; a published row can be neither deleted nor reverted to draft (FR-S8)
Cost → Buying standard × validity effective-dated (no market axis) shipped — F26-a (V29__price_and_cost.sql, Rev 17)
Price / Cost → Auction sale (anchor) N:1 shipped — F26-a (V29__price_and_cost.sql, Rev 17): required on a price, optional on a cost
Line-item snapshot → Price / Cost composite FKs (published only) verified

market (destination markets — a customer attribute and quote field since PRD Rev 23, no longer a price key — distinct from account.region, which is an office/scope tag) and auction_sale are reference-grade entities in this cluster. PriceModel (extension point 8) is the seam: core resolves a line price as-of a date; tea’s implementation answers from this cluster; the shipped fallback was product.list_price (retired with the catalog — Rev 7).

5. Samples & private label — samples, privatelabel

Entity Home Status Realized by Notes
Sample (round) sample designed (PRD) F6 One row per round: N:1 deal, round number, 7-state lifecycle (on core RoundLifecycle), owner (taster) N:1 app_user, courier + tracking (manual V1), due, outcome, feedback. Rejected outcome auto-creates the next round
Product brief product_brief designed (PRD) F8 1:1 deal (private label only — UNIQUE(deal_id)); blocking open questions as GateRule config or child rows — F8’s call
Courier (lookup) courier reference proposed F6 Samples-only in V1; tea reference data

Key edge note — Sample → Account is deliberately absent (D-9): the PRD lists both N:1 Deal and N:1 Account, but account is derivable through the deal; storing both invites drift. Display joins through the deal. The sample→deal-stage automation (the prototype’s most detailed logic) keys off stage_type, not entities — F6/F2 seam, no extra edge.

6. Compliance — certifications & export docs — compliance

Entity Home Status Realized by Notes
Certification (taxonomy) certification shipped — F1-a (spec FR-S3; V14__certification.sql) F9 Reference entity (EU Organic, Halal, JAS, …)
Account required certs account_certification (join) shipped — confirmed by F1-a (spec FR-S3; V15__account.sql) F1-a / F9 M:N account↔certification, composite primary key and both foreign keys — a join table for FK integrity (D-10), not the text[] the architecture example once sketched. F9 reads it for the set difference
Standard held certs buying_standard_certification (join) shipped — F26-b (spec FR-S1; V32__buying_standard_certification.sql; Rev 20) F26-b Since PRD Rev 27 the buying standard carries its held certifications (no product catalog). Held per standard (OQ-9’s 2026-09-17 narrowing): a join with a composite primary key, the same shape as account_certification, so F9 compares the two sets in SQL (F26-b spec FR-S1). Where Empire’s existing data lives is OQ-9’s open client half, a migration source only. F9 reads it; proposal fallback for F9 is a manual checklist
Export document rule export_document_rule designed (PRD/arch) F10 Base + per-country + per-certification document rules (admin reference data)
Per-deal doc checklist state ChecklistEngine instance designed (built by F7-b — FS-13 cancelled, AD #29) F10 Manually-toggled items — so the engine must support stored (toggled) items as well as computed ones (F7’s) — worth stating in the F7-b spec

F9 itself stores nothing: it is TagSetCompatibility (extension point 4) — a set-difference of required vs held certification sets, computed at read time. Deal-level “certifications held” chips are derived from the deal’s buying standards.

7. Communications — mailbox, email, templates, sequences, calendar — comms

Entity Home Status Realized by Notes
Mailbox connection mailbox_connection confirmed — F20-a spec (approved 2026-09-21), row adopted unchanged F20-a N:1 app_user. Holds envelope-encrypted refresh token, Graph subscription state. F20-a ships the table with the owner nullable from the start, for the shared info@ inbox as an unowned connection (OQ-14), so F20-e would need no schema change; it also adds partial unique indexes enforcing at most one non-DISCONNECTED connection per owner and per provider_account_id. Since 2026-09-24 there is no unowned connection in V1: F20-e has left V1 and info@ reaches the CRM by forwarding to a rep, so no V1 row uses the nullable owner; whether to make it NOT NULL is an open schema question (ASK FIRST). A connection is only ever its owner’s — no key reads another person’s mailbox (AD #34). F20-b adds four sync-state columns by ALTER (spec FR-2b): delta_token, last_synced_at, backfill_cursor, backfill_completed_at — no edge changes
Email message email_message confirmed — F20-b spec (approved 2026-09-23), row revised on both halves (spec D-4, FR-2) F20-b (table, N:1 mailbox_connection, both directions) · F20-f (the auto-link edges, through email_link) · F20-g (tracking state) N:1 mailbox_connection — the only edge F20-b ships: a message is stored against its connection and nothing else. F20-b stores direction (derived at ingest from the sender, never from Graph), the Graph message id, internet message id and conversation id (threading — stored from the first migration so F20-f’s grouping is a rendering change), subject, participants (parallel TEXT[] pairs), sent/received times, the body in Postgres, not S3 (spec D-1), snippet, has_attachments, and the ai_drafted + “edited by you” flags; unique on (mailbox_connection_id, graph_message_id). The auto-link edges → account / contact / deal / lead / quote (each N:1 nullable) are F20-f’s to declare — none of those tables existed when F20-b shipped (spec D-4). (Rev 50) The links are not columns of this table: each link is a row of email_link (below), so one message can be linked to several records, one row per record (F20-f D-1); email_message itself is unchanged. Since F20-f, a message is stored only while it has at least one link, once F20-f’s sweep has run for its connection (F20-f FR-5, FR-8, FR-21). Tracking state is F20-g’s and is not a column here. Explicitly not F20-a’s (its decision D-4)
Email link email_link confirmed — F20-f spec (approved 2026-11-19; D-1) F20-f · F11-e (a converted lead’s links) · F20-j (past mail) One row per link of a stored message to one record: N:1 email_message (not null) and exactly one of N:1 lead, N:1 account, N:1 contact (a CHECK, as record_share does — AD #35); the method (ADDRESS, THREAD, SEND, MANUAL), linked_by (N:1 app_user, NULL for a link the system made) and the BaseEntity columns; unique per message and record column. Linked mail follows its record’s reach (AD #35, AD #37; F20-f D-9). Deals and quotes join in Phase 2 with a column each, as record_share will (F2-c). Removing a message’s last link deletes the message (F20-f D-7)
Email link refusal email_link_refusal confirmed — F20-f spec (approved 2026-11-19; D-7) F20-f · F20-j (checks it) One row per unlink: N:1 mailbox_connection, the message’s Graph id and the record (one of lead, account, contact), holding no message content. Automatic linking — F20-f’s and F20-j’s — makes no link of that message to that record while the row exists; a manual link of that message to that record removes it
Email attachment email_attachment confirmed — F20-f spec (approved 2026-11-19; D-6) F20-f One row per file of a stored message (the files the email carried, as received from Microsoft), inline images included: N:1 email_message, the Graph attachment id, the name, the content type Graph reports, the size, the inline content id, the S3 key (prefix email-attachments/<message id>/<attachment row id>) and a state (PENDING, STORED, SKIPPED_TOO_LARGE, FAILED), or one marker row in state LIST_UNAVAILABLE with no name, size or Graph id when the message’s attachment list could not be read. Not an FS-11 attachment row and not through its upload pipeline (F20-f D-6): any content type is kept, nothing is scanned, and the row and every S3 object version are deleted with the message (F20-f D-7)
Email block email_block confirmed — F20-k spec (approved 2026-11-20; D-2) F20-k · F20-f and F20-j (their automatic linking checks it) One row per blocked address or domain: N:1 app_user as owner_user_id (the user whose personal list it is, or NULL for the organisation list), kind (ADDRESS, DOMAIN), value (trimmed, lower case) and the BaseEntity columns; unique per list, kind and value; at most 1,000 entries per list. A blocked address never causes an automatic link (F20-k D-1); no other table references it
Email send email_send confirmed — F20-c spec (approved 2026-10-12; FR-R1) F20-c One row per send from the CRM: idempotency key unique per sender, a hash of the request, N:1 app_user (sender), N:1 mailbox_connection, kind (new / reply / reply-all / forward), N:1 email_message as the source (nullable), the origin as one nullable foreign key per type — lead, account, contact — at most one set (record_share’s shape), recipient count, the AI flags, status (SENDING / SENT / FAILED / UNCERTAIN), the Graph draft id, the internet message id, and N:1 email_message as the match once the Sent Items copy is ingested (nullable). No address, subject or body — the content is stored once, in email_message. F20-f reads the origin from it to link mail to records; F20-h adds the files sent (email_send_file, below), the send’s stored deadline and the count of forwarded originals removed (F20-h FR-R1, FR-S4); F20-g adds tracked (F20-g FR-T1)
Email send file email_send_file confirmed — F20-h spec (approved 2026-10-13; FR-R1) F20-h One row per new file a send carried: N:1 email_send, its position, N:1 attachment (the email_upload file; kept after the file is deleted, since the row is kept), the file name, content type and size. No file content — the sent file is in the user’s Sent Items
Email tracking email_tracking confirmed — F20-g spec (approved 2026-11-09; FR-T2, FR-T5) F20-g 1:1 email_send for a tracked send only: the token (unique, at least 128 random bits), the open and click counts, the first and last open and click times. No IP address, user agent or location (F20-g decision 3). Read by F37-b’s per-send summary (F20-g FR-T6)
Email tracked link email_tracked_link confirmed — F20-g spec (approved 2026-11-09; FR-T3) F20-g One row per rewritten link of a tracked send: N:1 email_send, its position, the original address (the only place the redirect reads from), its click count and last click time. Reached by the data-protection erasure path with the rest of a person’s email
Scheduled email scheduled_email confirmed — F20-g spec (approved 2026-11-09; FR-L2) F20-g One row per email scheduled for later: idempotency key unique per sender, a request hash, N:1 app_user (sender), N:1 mailbox_connection, kind, the source as N:1 email_message or a live Graph id (at most one), the origin as one nullable foreign key per type — lead, account, contact — at most one set, the recipients, subject and cleaned body (cleared once sent, cancelled or dismissed), the AI flags, track, the files and removed originals, send_at, status (SCHEDULED / SENDING / SENT / FAILED / UNCERTAIN / CANCELLED), the failure reason, attempts, and N:1 email_send once sent. Its uploads are kept from F20-h’s clean-up while it can still be sent (F20-g FR-L10)
Email template email_template confirmed — F20-d spec (approved 2026-10-15; FR-T1) F20-d A name, a subject and a body (HTML, cleaned to F20-c’s allow-list) holding merge-field tokens {{group.field}}; visibility shared (every email.manage holder uses it; settings.manage edits it) or personal (N:1 app_user as owner, owner only — a check constraint ties the owner to the kind); an optional purpose, unique where set, whose one value weekly_prices marks the template F26-d fills; deleted by marking (deleted_at, deleted_by), never removed; no attachments. Used by composes (F20-d), the weekly price send (F26-d), sequence steps (F25-a) and list sends (F37-b)
Price email price_email, price_email_price shipped — F26-d (spec FR-R1; V48__price_email.sql) F26-d One row per weekly price email sent and recorded: N:1 account, N:1 contact (the addressee), N:1 auction_sale (the week), 1:1 email_send (unique — the F20-c send that carried it; its sender, status, kind and origin are checked when the row is written), the sender, the send time and the number of standards; and price_email_price, N:M buying_standard_price — the prices listed. Insert-only (a trigger refuses update and delete). No address, subject or body. Writes one timeline_event row keyed on the send (the price-email rule); read by the account header’s “sent this week” marker and by F37-a, which records each email it sends the same way
Price broadcast price_broadcast, price_broadcast_item, price_broadcast_item_price confirmed — F37-a spec (approved 2026-11-15; FR-B1) F37-a One row per confirmed batch of weekly price emails: N:1 app_user (the sender), N:1 auction_sale, the copies and tracking choices, a status (SENDING, FINISHED, CANCELLED) and an idempotency key unique per sender. price_broadcast_item, one per customer in the batch: N:1 price_broadcast, N:1 account (unique within the batch), 0..1 contact (the addressee, stored before the send), 0..1 email_send, 0..1 price_email, a status, a reason and the attempt, re-claim and record counts the sweep uses; and price_broadcast_item_price, N:M buying_standard_price — the prices the email listed, stored before the send so the price email can be recorded later. No address, subject, body or price amount. Each item sent writes one price_email row the same way F26-d’s account-page send does
Bulk email bulk_email, bulk_email_item confirmed — F37-b spec (approved 2026-11-19; FR-B1) F37-b One row per confirmed bulk send: N:1 app_user (the sender), 0..1 saved_view (the contact list it was made from, set to null when the view is deleted; the list’s name is kept at confirmation), 0..1 email_template (when one was used), the subject and the body with merge fields unfilled, track, the status, an idempotency key unique per sender. One item per contact: N:1 bulk_email, N:1 contact, the address it went to, the status and reason, 0..1 email_send once sent, a unique unsubscribe token (at least 128 random bits), and when it bounced and when its token was used
Bulk email suppression bulk_email_suppression confirmed — F37-b spec (approved 2026-11-19; FR-U1) F37-b One row per address left out of every later bulk send: the address in lower case (unique), the reason (UNSUBSCRIBED, BOUNCED), when, 0..1 bulk_email_item (the email that caused it). Keyed by address, not by contact, so it holds whichever contact carries the address; read by F37-b only, never by F20-c, F20-g or F37-a. There is no per-contact consent state (PRD Rev 103)
Tracking event email_tracking_event proposed F20 Open/click events N:1 message (or counters on message — F20’s call)
Sequence sequence designed (PRD) F25 target_type locks to deals-only or leads-only on first use (PRD lifecycle)
Sequence step sequence_step designed (PRD) F25 Ordered; kind email (N:1 template, AI-drafted, HITL) or task
Sequence enrollment sequence_enrollment designed (PRD) F25 N:1 sequence + exactly one of deal / lead; status, current step, next-fire time; sends become email_message rows after human approval
Calendar sync link calendar_sync_link (or column on activity) proposed F21 Maps activity ↔ Graph event id for two-way sync. External non-CRM events: read-through or lightweight cache — F21’s call, flagged not settled
Contact sync link the contact suggestion table (name set by F22’s plan) confirmed — F22 spec (approved 2026-11-20; FR-5) F22 One row per (user, Graph contact id) for each Outlook contact that is suggested, dismissed or added: N:1 app_user, N:1 mailbox_connection, the copied name, job title, company, addresses and phones, N:1 account (the suggested account, nullable), a state (suggested / dismissed / added) and, when added, N:1 contact. Two users who hold the same person each have their own row; matching every address (F20-l) keeps the person to one CRM contact when the copies share an address (one held under different addresses can still become two). A row other than added is deleted when its Outlook contact is deleted, when it now matches a CRM contact, or with the connection or the switch; an added row then keeps only its state and contact id (spec FR-4, FR-5, FR-11, FR-13)

8. Activities, notes, timeline

Entity Home Status Realized by Notes
Activity activity confirmed — F3-a spec (FR-S2, FR-S3, approved 2026-10-13; Rev 29) F3-a (account and lead follow-ups) · F3-b (the deal link) N:1 activity_type; title; notes (one free-text field — no separate agenda or meeting notes; F16, which would have read them, was dropped — PRD Rev 61); links → account / lead (each N:1 nullable, exactly one by the named CHECK activity_has_one_record) — no deal column yet: F3-b adds deal_id and widens the check in its own migration, as F2-a does for note; assignee (assignee_id, N:1 app_user, required): an active user who holds the linked record’s manage key and reaches it, chosen when the follow-up is created or edited — the assignee gives no reach of its own, so a follow-up is not an owned record in the AD #35 sense and does not join F5-c’s owned-records refusal (F3-a decision 8); due_date (a Colombo business date) + optional due_time; done_at / done_by (both null or both set); soft delete — deleted_at / deleted_by, as F1-e’s notes. No stored status: overdue / today / upcoming / done is derived against the Colombo date (F3-a FR-A3). Reach follows the linked record — the record’s view key to read, its manage key for every write, no activity.* key (AD #34, AD #35; F3-a FR-P1)
Activity type activity_type confirmed — F3-a spec (FR-S1, approved 2026-10-13; Rev 29) F3-a (the built-in rows) · F3-b (custom types) key (unique, never changed), label, sort_order, active, built_in. F3-a’s migration seeds six built-in rows — call, meeting, task, deadline, email, lunch — and has no route that writes the table; F3-b adds the admin-defined custom types as rows with built_in = false
Email follow-up email_follow_up, with email_follow_up_email and the one-row email_follow_up_setting confirmed — F44 spec (FR-S1, FR-S2, approved 2026-11-19; Rev 51) F44 One row per follow-up F44 raised for an unanswered linked email: 1:1 activity (required, unique — the follow-up a person sees is an ordinary F3-a activity, type email, title Reply to email); N:1 email_message (nullable, ON DELETE SET NULL — the copy it points at); N:1 mailbox_connection (required — the mailbox it was raised from) and that copy’s Graph conversation id; the D-7 anchor (LEAD, ACCOUNT, CONTACT_ACCOUNT); open (mirrors the activity), outcome, reopened_at. email_follow_up_email (N:1 email_follow_up) lists every email key (Internet message id) the follow-up covers, unique, so an email raises at most one follow-up. No row is ever deleted. Reach follows the activity’s record (F3-a FR-P1); the follow-up holds no email content, and its sender and subject are read from the linked email while it is still linked to that record (F44 FR-A2). Closing one writes no timeline row (F44 D-10)
Note note shipped — confirmed by F1-a (spec FR-S4; V21__note.sql; the account and contact notes API is F1-e’s) · lead notes API built — F11-f (spec FR-N1, FR-N2; Rev 23): GET and POST /api/v1/leads/{id}/notes, list and add, in the lead package; lead note edit and delete built — F11-f (spec FR-N4, Rev 13; Rev 43): PATCH and DELETE /api/v1/leads/{id}/notes/{noteId}, on F1-e’s rule for every record type — any holder of lead.manage who reaches the lead may edit or delete any note on it, a deleted note is marked and left out of the list, and each note carries editedAt, editedBy and version F1-a (table) · F1-e (account/contact notes API, note editing) · F11-f (lead notes API) Author (created_by) + body; links → account / contact / lead (each N:1 nullable, at least one by the named CHECK note_has_target); lead_id shipped — confirmed by F11-a (spec FR-S3), which re-added note_has_target with lead_id and added note_lead_exclusive: a lead note has the lead as its only target, so its reach is the lead’s and no precedence is needed. deal_id is added by F2-a, which widens the CHECK again in its own migration. Migration identity per D-11. Reach (AD #35, F1-a WI-3.1 plan D16 — confirmed by F1-a): a note holds no permission key of its own and follows its parent’s reach, gated on the parent’s view / manage. A note with both account_id and contact_id follows its account — the account governs whenever it is set, and the contact’s reach applies only when account_id is null — because the account is the owned record, a contact can move between accounts, and the timeline already follows its account. A note whose only target is an account-less contact is therefore unowned, reachable only at all scope. When F11-a and F2-a add their columns they state the precedence on the same principle: the owned record the note was filed on governs. Account and contact notes API — specified by F1-e (spec FR-N1–N7, 2026-10-10; PRD Rev 59): list, add, edit and delete under /api/v1/accounts/{id}/notes and /api/v1/contacts/{id}/notes, in the account package; an account note has account_id only and a contact note contact_id only; any holder of the parent’s manage who reaches it may edit or delete any note, with optimistic locking on version; a deleted note is marked, never removed — F1-e adds deleted_at and deleted_by (null until deleted), and every route leaves a deleted note out; editedAt / editedBy are modified_at / modified_by once version is above 0. Lead notes adopted the editing and deletion rule in F11-f Rev 13 (Rev 43)
Timeline timeline_event (stored) shipped — confirmed by F1-a (spec FR-S6, revising D-7; V23__timeline_event.sql) F1-a (table) · F1-c (rendering) · each producer its own rows (F1-e, F3-a, F11-f, F20-f, …) One insert-once row per event: N:1 account (required), N:1 contact (nullable), kind (lead / order / sample / call / quote / note / email / activity), occurred_at, summary, actor_id → app_user (nullable — system-written rows have none), and the producing record as (source_type, source_id), loosely referenced per D-8. source_type and source_id are both NOT NULL, so a producer with no natural source record cannot write a timeline row — every future producer designs against this. UNIQUE (source_type, source_id, kind) makes a producer’s retry a no-op (AD #13). Immutable except summary and version — and, since F39, the modified_at / modified_by pair that stamps a summary refresh: F39’s FR-10 migration adds both columns and re-creates the forbid_value_update trigger with the writable set summary, version, modified_at, modified_by (spec FR-10, W-1); every other column stays immutable. When a source record changes, its producer refreshes summary through the same key — and must bump version in the same write (version = timeline_event.version + 1), because the trigger permits the bump but never performs it and version is the row’s only change signal. Indexed (account_id, occurred_at DESC) for F1-c and the account list’s lastContactAt / dormant (AC-28). A row follows its account’s reach (AD #35) and holds no key of its own. The lead rule (F11-f FR-T1–T5, T4a): while a lead is matched to an account, that account has exactly one row for it — source_type = 'lead', kind = 'lead', source_id the lead, the matched contact, occurred_at the lead’s received_at — whose summary is Inquiry received () — , rewritten when the lead’s status or leadSource changes; the lead service inserts, moves or deletes the row in the same transaction as the match change. The summary carries nothing else from the lead, the row is shown to every reader of the account (opening the lead still needs reach to the lead), and it counts as contact for lastContactAt and dormancy (F1-c owns the final rule). The note rule (F1-e FR-N6, FR-N7 — specified 2026-10-10): each account note has exactly one row — source_type = 'note', kind = 'note', source_id the note, contact_id null, occurred_at the note’s created_at, actor_id the author — whose summary is the body with whitespace collapsed, cut to 200 characters with …; editing the note rewrites the summary (bumping version and stamping modified_*), deleting it deletes the row. A contact note writes no row, because a contact’s account can change and a row’s cannot. A note row counts as contact, as Phase 1 criterion C1 states. The activity rule (F3-a FR-T1–T4 — specified 2026-10-13): each account follow-up that is done has exactly one row — source_type = 'activity', kind = 'activity', source_id the follow-up, contact_id null, occurred_at its done_at, actor_id the user who marked it done — whose summary is done: </em>, with the title’s whitespace collapsed and the whole cut to 200 characters with <code>…</code>. Reopening or deleting the follow-up deletes the row, and marking it done again writes a new one; editing the type or title of a done follow-up rewrites the summary (bumping <code>version</code> and stamping <code>modified_*</code>). An open follow-up writes no row, a lead follow-up writes none, open or done, and a follow-up F44 raised writes none (F44 D-10, Rev 51). An activity row counts as contact, so completing an account follow-up moves the account’s <code>lastContactAt</code> (F1-c owns the final rule). <strong>The price-email rule (F26-d FR-R3 — specified 2026-10-16):</strong> each recorded price email has exactly one row, <strong>keyed on its F20-c send</strong> — <code>source_type = 'email_send'</code>, <code>kind = 'email'</code>, <code>source_id</code> the <code>email_send</code> id, <code>contact_id</code> the addressee, <code>occurred_at</code> the send time, <code>actor_id</code> the sender — whose summary is <em>Weekly prices sent for <week> (<n> standards) — addressed to <contact name></em>, cut to 200 characters with <code>…</code>. When a row under that key already exists (F20-f linked the Sent Items copy first), F26-d rewrites its summary instead of inserting. F20-f keys the row of any CRM-sent message on the same key and writes none when one exists, so a send has one row and F20-f never reads F26-d’s tables (AD #31). It counts as contact</td> </tr> <tr> <td>Tag</td> <td><code>tag</code> + joins <code>account_tag</code>, <code>contact_tag</code> (F1-a) · <code>lead_tag</code> (F11-a) · <code>deal_tag</code> (F2-a)</td> <td><strong>shipped — confirmed by F1-a</strong> (spec FR-S5; <code>V22__tag.sql</code>; the read-only tag list <code>GET /api/v1/tags?entityType=…</code> is F11-b’s — F11-b spec FR-A5, Rev 21 — and the tag writes and account/contact assignment are F1-e’s) · <strong><code>lead_tag</code> shipped — confirmed by F11-a</strong> (spec FR-S2) · <strong>lead tag routes built — F11-f</strong> (spec FR-G1–FR-G3; Rev 23): attach and detach, <code>PUT</code> / <code>DELETE /api/v1/leads/{id}/tags/{tagId}</code>, in the <code>lead</code> package; lead tag create, <code>POST /api/v1/tags</code> with <code>entityType: lead</code>, in <code>tag</code>, taking <code>lead.manage</code> through the <code>tag.TagWriteAccess</code> contribution point that <code>lead</code> fills, so <code>tag</code> imports nothing from <code>lead</code> — F1-e makes account and contact tags creatable by adding its own contributions</td> <td>F1-a (<code>tag</code>, <code>account_tag</code>, <code>contact_tag</code>) · F11-a (<code>lead_tag</code>) · F2-a (<code>deal_tag</code>) · F11-b (read-only tag list) · F1-e (tag rename/retire, account/contact assignment and create) · F11-f (lead tag attach, detach and create)</td> <td>Labels <strong>per entity type</strong>, as Pipedrive’s are: <code>tag.entity_type</code> ∈ <code>account</code> / <code>contact</code> / <code>lead</code> / <code>deal</code> (a vocabulary <code>CHECK</code>, so the last two need no migration when their joins arrive); name, colour, archive flag; <strong>unique on <code>(entity_type, lower(name))</code></strong> by a functional index. Each join is M:N <code><entity> ↔ tag</code> with a composite primary key and both foreign keys (plus the base <code>id</code>, <code>version</code>, <code>created_*</code> its entity maps). Consumed by F32’s saved filters. <strong>Gating (F1-a WI-3.1 plan D16 — confirmed by F1-a):</strong> the tag name list is reference data, readable by any signed-in user (like the certification list); attaching or detaching a tag — and creating a new name while attaching — takes the tagged entity’s <code>manage</code> key (<code>account.manage</code> for an account or contact tag); renaming or retiring a name changes it on every record, so it takes <code>settings.manage</code> (AD #34). A join row follows its parent’s reach (AD #35). <strong>Account and contact tag routes and tag configuration — specified by F1-e</strong> (spec FR-G1–G7, 2026-10-10; PRD Rev 59): <code>GET</code> / <code>PUT</code> / <code>DELETE</code> under <code>/api/v1/accounts/{id}/tags</code> and <code>/api/v1/contacts/{id}/tags</code>; <code>POST /api/v1/tags</code> for <code>account</code> and <code>contact</code> through two <code>TagWriteAccess</code> contributions in <code>account</code>; <code>PATCH /api/v1/tags/{id}</code> under <code>settings.manage</code> for name, colour (one of the four Badge tones, or none) and <code>active</code>; the tag list gains an <code>active</code> filter (its items stay <code>{ id, name, colour }</code>), and <code>GET /api/v1/tags/{id}</code> returns one tag with its <code>entityType</code>, <code>active</code> and <code>version</code>. <strong>A tag is retired (<code>is_active = false</code>), never deleted:</strong> it stays on its records, cannot be newly attached through the routes, and can always be detached; the migration’s service path may attach a retired tag (FR-G7)</td> </tr> <tr> <td>Order (ERP reference)</td> <td><code>order</code></td> <td><strong>not in V1</strong> (F1-a builds no <code>order</code> table — OQ-63)</td> <td>F1</td> <td>Read-only reference rows: <code>N:1 account</code>, ref, value, date, <code>source = erp</code>. Feeds LTV, dormancy, reorder triggers, F13 briefings</td> </tr> </tbody> </table> <h3 id="9-ai-layer-ai"><a class="anchor" href="#9-ai-layer-ai" aria-hidden="true">#</a>9. AI layer — <code>ai</code></h3> <table> <thead> <tr> <th>Entity</th> <th>Home</th> <th>Status</th> <th>Realized by</th> <th>Notes</th> </tr> </thead> <tbody> <tr> <td>AI invocation log</td> <td><code>ai_invocation</code></td> <td><strong>built by F12</strong> (spec FR-B6; <code>V38__ai_invocation_and_lead_tea_fields.sql</code>)</td> <td>F12 (the AI capability’s first consumer); every later AI feature writes through it</td> <td>One insert-only row per call to the <code>AIProvider</code> seam, whatever the outcome: feature key, provider, model, prompt id and version, user (null for a <code>SYSTEM</code> caller, no foreign key), outcome, tokens, cost, latency, attempts — what makes spend attributable — with an <code>ai.invoked</code> audit event in the same transaction. <strong>Never the prompt, the user text or the reply</strong> (AD-O-6). References no record: the call’s result goes back to the caller, and the extraction’s id is this row’s (<code>forge-et-be/docs/data-model.md</code> §6)</td> </tr> <tr> <td>AI suggestion (HITL queue entry)</td> <td><code>ai_suggestion</code></td> <td>proposed — <strong>not built by F12</strong> (a synchronous, user-invoked extraction needs no queue; F12 spec § Out of Scope)</td> <td>the first background AI feature / F11 — <strong>not built by F11-d either</strong> (the first background AI feature: its tag and proposed match each have a typed home and action — F11-d decision 11, Rev 32)</td> <td>Generic proposed-action record (feature, target, payload, status proposed→approved/rejected, <code>edited</code> flag, actor) — the module layout names a “HITL queue”; features project it into their surfaces. Approved content lands in typed homes (lead fields, email drafts)</td> </tr> <tr> <td>AI feature config</td> <td><code>ai_feature_config</code></td> <td>designed (AD #19) — <strong>not built by F12</strong>: per-feature <code>{model, enabled}</code> is the <code>et.ai</code> configuration, read through one resolver so this table can replace it; the administrator switch and the monthly ceiling are F12 spec Q-1</td> <td>owner open (F12 spec Q-1)</td> <td>Per-feature <code>{model, enabled}</code> runtime config + monthly ceiling — admin-editable without deployment</td> </tr> <tr> <td>Prompts / extraction schemas</td> <td>code, in the <code>ai</code> package</td> <td>designed (arch guardrail)</td> <td>F11–F15, F36</td> <td><strong>Not data</strong> — prompts stay rich and live in one place (P-21; the former <code>PromptCatalog</code> extension point)</td> </tr> </tbody> </table> <p>Lead triage outputs (priority, confidence, summary, why, recommended action, draft reply) land as typed columns on <code>lead</code> — generic triage vocabulary, not tea. Account briefings / morning briefings / quote-assistant reads are <strong>generated, not persisted</strong> (regenerate on demand; consistent with AD-O-6) — if caching is ever wanted it is a feature-spec decision.</p> <h3 id="10-data-management-integration-datamgmt-integration"><a class="anchor" href="#10-data-management-integration-datamgmt-integration" aria-hidden="true">#</a>10. Data management & integration — <code>datamgmt</code>, <code>integration</code></h3> <table> <thead> <tr> <th>Entity</th> <th>Home</th> <th>Status</th> <th>Realized by</th> <th>Notes</th> </tr> </thead> <tbody> <tr> <td>File</td> <td><code>attachment</code></td> <td><strong>shipped — FS-11</strong> (<code>V9__attachment.sql</code>; <code>V33</code>, <code>V44</code>) · <strong>D-6 revised by F33-a</strong> (spec decision 1, Rev 41)</td> <td>FS-11 (table) · F33-a (accounts, contacts, leads) and F33-b (deals, quotes, samples, briefs) — Rev 39 · F20-h (<code>email_upload</code>)</td> <td>One table: the opaque S3 key, the original name, the sniffed content type, the size, the uploader (<code>N:1 app_user</code>) and the scan status (<code>PENDING</code>, <code>CLEAN</code>, <code>INFECTED</code>, <code>NOT_SCANNED</code>). <strong>A file names its one record by <code>owner_type</code> and <code>owner_id</code>, with no foreign key and no link tables</strong> (D-6, revised): <code>account</code> and <code>lead</code>, <code>contact</code> (F33-a — it follows its account’s reach and keys) and <code>email_upload</code>; each owner type has its own visibility and upload policy, and a record’s file follows the record’s reach (AD #35). <strong>F20-h (spec approved 2026-10-13):</strong> owner type <code>email_upload</code> (owner id the uploader’s <code>app_user</code> id), for files attached to an email before it is sent; and <code>deleted_at</code> — a deleted file keeps its row and its S3 version behind a delete marker, recoverable on request (proposal §A.5, §A.6.3), except FS-11 FR-S3’s purge on infection. F33-a deletes a record’s file the same way</td> </tr> <tr> <td>Custom field definition</td> <td><code>custom_field_definition</code></td> <td>designed (AD #8, F34); specified for account, contact and lead by <code>.forge/specs/F34-c-custom-fields-accounts-contacts-leads-spec.md</code> (approved 2026-11-08)</td> <td>F34-c (account, contact, lead); F34-a (deal, quote, buying standard, sample)</td> <td>Per entity (account/contact/deal/lead/quote/buying standard/sample); values in a <code>custom_fields JSONB</code> column <strong>on each of those tables</strong> (a JSONB column on <code>sample</code> is fine — the ban is on core→tea FKs and tea words in core, not on tea tables having columns)</td> </tr> <tr> <td>Record share</td> <td><code>record_share</code></td> <td><strong>confirmed — F5-f spec</strong> (FR-S1, approved 2026-10-02; AD #35; PRD Rev 29 / OQ-58)</td> <td><strong>F5-f</strong></td> <td>The third visibility path beside ownership and the reporting line. <code>shared_with_user_id</code> (<code>N:1 app_user</code>), <code>shared_by_user_id</code> (<code>N:1 app_user</code>) and <code>shared_at</code>, plus links → <code>account_id</code> / <code>lead_id</code> now, <code>deal_id</code> / <code>quote_id</code> when those tables land (each N:1 nullable, <strong>exactly one</strong> by a CHECK — the same shape as <code>activity</code> above, and chosen for that reason); unique per (record, user). <strong>No access level column, deliberately</strong>: a share widens reach, the recipient’s role grants authority (<code>design/data/record-sharing-model.md</code> §2.2). Owner stays singular on the record itself (<code>owner_id</code>). A share counts for its recipient and for everyone above them in the reporting tree while the recipient is active — shares roll up (AD #35, restated by AD #37 without scopes), and a share to a deactivated user is inert until they are reactivated (PRD Rev 49); a record with no owner cannot be shared; sharing is transitive; sharing, removing a share and reassigning the owner need the entity’s <code>manage</code>. Children — contacts, notes, tasks, attachments, timeline, record-linked email — follow their parent’s reach. Cascade-deletes with its record. <em>Confirming spec: F5-f, which builds the owner pattern, this table and the one visibility rule (lists and per-record checks) before any list read-path.</em></td> </tr> <tr> <td>Saved view</td> <td><code>saved_view</code></td> <td><strong>settled — F32-d spec</strong> (FR-V1–FR-V5; PRD Rev 87)</td> <td>F32-d (accounts, leads, contacts) · F32-a (deals, quotes, samples, standards)</td> <td><code>N:1 app_user</code> owner; the list it belongs to; name unique per owner and list regardless of case; personal or shared with everyone who holds the list’s <code>view</code> key; filters as <code>JSONB</code> (the list endpoint’s own parameters), sort, columns (the list row’s member names); only the owner changes or deletes it, except that <code>settings.users.manage</code> may delete a deactivated owner’s shared view</td> </tr> <tr> <td>List preference</td> <td><code>list_preference</code></td> <td><strong>settled — F32-d spec</strong> (FR-C3)</td> <td>F32-d</td> <td>A user’s column choice for one list: <code>N:1 app_user</code>, the list, columns (the list row’s member names); one row per user per list</td> </tr> <tr> <td>Import job</td> <td><code>import_job</code> (+ row-error child)</td> <td>proposed</td> <td>F4/F23</td> <td>The shared engine’s run record: source, mapping, counts, re-runnable (AD-O-7 replay + delta pass)</td> </tr> <tr> <td>External ref (migration identity)</td> <td>columns on migratable entities</td> <td>proposed (D-11) · <strong>on <code>account</code>: settled by F4-d</strong> (spec FR-S1; <code>V50__account_source_owner_name.sql</code>) · <strong>on <code>lead</code>: settled by F4-b</strong> (spec FR-9)</td> <td>F4</td> <td><code>source</code> + <code>source_ref</code> (Pipedrive id) on lead/contact/account/deal/activity/note — written with <code>OVERRIDING SYSTEM VALUE</code> where ids are preserved (FR-P1); serves AD-O-7’s skip-already-migrated delta pass. <strong><code>account</code> and <code>lead</code> also carry <code>source_owner_name</code></strong>, the Pipedrive owner’s name, never shown, read only by F32-c’s hand-out filter (F4-d FR-S1; F4-b FR-9): a nullable <code>TEXT</code> that only a Pipedrive migration run writes — on an account on create, merge and update, on a lead on create and update (F4-b FR-5, FR-13); contacts do not carry it, because a contact follows its account</td> </tr> <tr> <td>ERP handoff record</td> <td><code>handoff</code></td> <td>proposed</td> <td>F19</td> <td>On a Won deal: <code>N:1 deal</code>, readiness snapshot, status pending→generated, generated document (→ file). Payload/generator lives with the ERP feature (<code>ErpHandoffService</code>; the former <code>HandoffTarget</code> extension point)</td> </tr> <tr> <td>Search</td> <td>—</td> <td>withdrawn (Rev 25)</td> <td>—</td> <td>Global search (F31) is dropped and AD-O-2 closed (PRD Rev 60); no <code>tsvector</code> column or index is built. Each list endpoint keeps its own <code>q</code> filter</td> </tr> </tbody> </table> <p>Reference lists (PRD §Domain Model last row): activity types, customer/buyer types, currencies, countries, grades, packaging formats, markets, certifications, export-doc rules, couriers. Each is admin-managed reference data; the owning feature spec decides lookup-table vs validated-enum per list.</p> <p><strong>Capture app (F36):</strong> the PWA keeps its own repo and, on the phone, any capture not yet sent (F36-a’s keep-and-resend; F36-e’s offline queue was dropped). A capture is <strong>not</strong> a lead when it arrives. Since PRD Rev 95 the backend keeps it as a <strong>captured lead</strong> in the capture app until a person converts or rejects it, and since PRD Rev 96 the reps plan each show in the app with a <strong>capture campaign</strong> and its <strong>exhibitors</strong>; PRD Rev 97 adds the three to §Domain Model › Key Entities and the captured lead’s states to §Lifecycle States. The three tables are F36-a’s, in the <code>capture</code> package (F36-a spec FR-L1, FR-P1, FR-P3, decision D-3):</p> <table> <thead> <tr> <th>Entity</th> <th>Home</th> <th>Status</th> <th>Realized by</th> <th>Notes</th> </tr> </thead> <tbody> <tr> <td>Captured lead</td> <td><code>captured_lead</code></td> <td><strong>shipped — F36-a</strong> (spec FR-L1; <code>V71__captured_lead.sql</code>, <code>campaign_id</code> in <code>V73__capture_plan.sql</code>, later columns in <code>V75__captured_lead_card_read.sql</code> and <code>V77__captured_lead_review.sql</code>)</td> <td>F36-a · F36-b (the card’s contact fields) · F36-c (its research and ranking, in <code>capture_research</code>)</td> <td>One card photo or badge captured at a show: the capturing user, a client id unique per capturing user (the upload’s replay key, FR-C6), kind <code>card</code> or <code>badge</code>, the captured time, the booth note, the photo’s object key (a private <code>capture/</code> key in the attachments bucket, read only through the capture API — not an <code>attachment</code> row, FR-C7) or the badge’s raw text, the contact fields, status <code>to_review</code> → <code>converted</code> or <code>rejected</code>, and <code>rejected</code> → <code>to_review</code> (PRD Rev 97), with who decided and when, the CRM lead’s id on conversion, and the reject reason and note. <strong>No owner and no reach</strong> (FR-L2): every holder of <code>capture.use</code> sees every captured lead; AD #35’s owner applies only to the CRM lead a conversion creates</td> </tr> <tr> <td>Capture campaign</td> <td><code>capture_campaign</code></td> <td><strong>shipped — F36-a</strong> (spec FR-P1; <code>V73__capture_plan.sql</code>)</td> <td>F36-a · F36-c (its focus)</td> <td>One trade show: a name, the show’s first and last day (both optional), archived and restored. An optional <strong>focus</strong> (F36-c spec FR-FC1, its wave 3): one line of at most 300 characters that F36-c’s ranking reads for the campaign’s exhibitors and captured leads, as data; editing it ranks them again (FR-TR7). <em>Upcoming</em>, <em>Running</em> and <em>Ended</em> are computed from the days and the business clock, not stored. The rep’s active campaign is kept on the phone per user, not in the database (FR-P2). <strong>Not</strong> the marketing Campaign F28 would have built (dropped, PRD Rev 66)</td> </tr> <tr> <td>Exhibitor</td> <td><code>exhibitor</code></td> <td><strong>shipped — F36-a</strong> (spec FR-P3; <code>V73__capture_plan.sql</code>)</td> <td>F36-a · F36-c (its research and ranking, in <code>capture_research</code>)</td> <td>A company exhibiting at a show: company, website, booth code, hall, country, notes, how it was added (<code>upload</code> or <code>manual</code>), archived with an optional reason and note, and one visit — a note and a visited mark, each with who and when — shared by every holder of <code>capture.use</code> (FR-P6). An uploaded list is read and imported request by request; nothing is stored between its preview and its import (FR-P5)</td> </tr> <tr> <td>Capture research</td> <td><code>capture_research</code></td> <td><strong>shipped — F36-c</strong> (spec FR-ST1; <code>V76__capture_research.sql</code>, wave 1; its captured-lead columns used from wave 2)</td> <td>F36-c</td> <td>One row for each researched captured lead or exhibitor — exactly one of the two, each at most once. It holds the research (its state, the company findings and, for a captured lead, the person findings, the confidence, the research call) and the ranking (the priority P1–P3, shown in the app as the tier <em>Hot</em>, <em>Warm</em> or <em>Cold</em>, a fit score from 0 to 100, the reason, the next action, the basis, the ranking call and, from F36-c’s wave 3, the campaign focus the ranking read, <code>ranking_focus</code> (FR-ST1, FR-FC4)), with the fingerprint of the inputs it was computed for, the counted failures, and for a captured lead the removal of the person’s findings and when its <em>Ready to review</em> notification was written. Written only by F36-c’s research jobs, <em>Research Again</em> and the person removal, each audited; nothing is added to <code>captured_lead</code> or <code>exhibitor</code>, so a background write never refuses a rep’s open edit (FR-ST1, FR-ST3). Raw search results are never stored</td> </tr> <tr> <td>Capture notification</td> <td><code>capture_notification</code></td> <td><strong>shipped — F36-c</strong> (spec FR-ST2; <code>V79__capture_notification.sql</code>, wave 2)</td> <td>F36-c</td> <td>One in-app notification: its kind (<code>ready</code>, <code>converted</code> or <code>rejected</code>), the captured lead, and the user who converted or rejected it (none for <code>ready</code>). It holds ids only; its text is rendered from the captured lead when read. Kept; nothing deletes notifications in V1 (decision D-10)</td> </tr> <tr> <td>Capture notification recipient</td> <td><code>capture_notification_recipient</code></td> <td><strong>shipped — F36-c</strong> (spec FR-ST2; <code>V79__capture_notification.sql</code>, wave 2)</td> <td>F36-c</td> <td>One row for each notification and each user told of it — the show team (the capturing user and everyone who captured into the same campaign), less the user who acted — with when that user marked it read (FR-NT4, FR-NT5). Key <code>(notification_id, user_id)</code></td> </tr> </tbody> </table> <p>Key edges (F36-a spec; PRD Rev 97): <code>captured_lead N:1 capture_campaign</code> (nullable — a capture taken with no active campaign, or naming an archived or unknown one, has none, FR-C6); <code>exhibitor N:1 capture_campaign</code>; <code>captured_lead N:1 app_user</code> as its capturing user, and as the user who converted, rejected or reopened it; <strong>captured lead → lead on conversion</strong>, <code>1:1</code>, set only by converting (FR-L4): the conversion creates the lead through the F11 intake with <code>source = 'capture'</code> and <code>source_ref</code> = the captured lead’s id as the replay identity, <code>lead_source = 'Trade Fair'</code>, <code>lead_source_detail</code> = the campaign’s name, the converting user as the lead’s owner, and a card’s photo as an <strong>attachment</strong> on the new lead (FS-11), and the captured lead keeps the lead’s id. A rejected captured lead never reaches the CRM.</p> <p>Key edges (F36-c spec FR-ST1, FR-ST2, FR-CV1): <code>capture_research 1:1 captured_lead</code> or <code>capture_research 1:1 exhibitor</code> — exactly one is set on each row, and a subject has no row until its research job first writes for it; <code>capture_research N:1 ai_invocation</code> as its research call and as its ranking call; <code>capture_research N:1 app_user</code> as the user who removed the person’s findings (captured leads only); <code>capture_notification N:1 captured_lead</code>; <code>capture_notification N:1 app_user</code> as the user who converted or rejected the lead; <code>capture_notification 1:N capture_notification_recipient</code>; <code>capture_notification_recipient N:1 app_user</code>. <strong>On conversion</strong> a captured lead’s completed research is copied into the new lead’s <code>lead_research</code> row when the research’s fingerprint matches the new lead’s (FR-CV1) — a copy, not an edge. <em>(F36-c Rev 6, from its wave 3)</em> When the captured lead’s ranking is <code>done</code> for its current fingerprint, the conversion also copies it into the new lead’s <code>lead_ranking</code> row (FR-CV1; F11-g FR-S4): the tier as P1–P3, the confidence, the reason without its tier prefix, the next action and the ranking call, with <code>origin = 'capture'</code>, the focus the ranking read in <code>focus</code> and the campaign’s name at conversion in <code>focus_campaign_name</code> — again a copy, not an edge, since <code>focus_campaign_name</code> is text and not a reference to <code>capture_campaign</code>; only the 0–100 fit score is not carried, and stays on the captured lead.</p> <h2 id="cross-feature-decisions-this-map-proposes"><a class="anchor" href="#cross-feature-decisions-this-map-proposes" aria-hidden="true">#</a>Cross-feature decisions this map proposes</h2> <p>Each is a recommendation with its confirming owner — none is settled until the named spec adopts it (or revises it with reasons).</p> <p><strong>D-1 — Quote hangs off the Deal; the account edge is pinned by a composite FK.</strong> <code>data-model.md</code> §2.4’s <code>quote</code> carries <code>account_id</code> and no <code>deal_id</code> (it is the deliberately minimal pricing-facing shape). The PRD says “N:1 Account/Deal” and every journey creates quotes from a deal; both tea pipelines contain a quote stage. Recommendation: F7 adds <code>deal_id NOT NULL</code>, and <code>account_id</code> stays but is made unable to disagree with the deal’s account via the FR-I1 snapshot-consistency idiom (deal carries <code>UNIQUE (id, account_id)</code>; quote’s FK is composite <code>(deal_id, account_id)</code>). If a genuinely deal-less quote emerges in F7 discovery, relax to nullable — but decide it there, once. <em>Confirms: F7 spec (with a §2.4 companion revision + proof re-run, same procedure as FS-2’s FR-P1 rename).</em></p> <p><strong>D-2 — Deal line items and quote line items are two entities, not one.</strong> F26 requires buying standards attached to the deal (qty + discount, rolling into deal value, from the first stage); F7 requires priced quote lines with an immutable <code>unit_price</code> snapshot (§2.4 <code>line_item</code>, quote-scoped). One entity cannot be both a mutable working set and an immutable snapshot. Recommendation: <code>deal_line_item</code> (mutable; was <code>deal_product</code> — Rev 7) + <code>line_item</code> (quote-scoped, verified shape); creating a quote seeds its lines from the deal’s standards, then the quote’s lines evolve with revisions. The PRD’s own entity table already lists line items on both Deal and Quote. <em>Confirms: F26 + F7 specs.</em></p> <p><strong>D-3 — The quote’s trade fields (Incoterm, destination market).</strong> These once had to live on a <code>quote_profile</code> extension table, because the banned-vocabulary rule forbade <code>incoterm</code> as a core identifier and the module layout assigned Incoterm to the tea-quoting module. FS-14 removed both, so Incoterm + destination can sit on <code>quote</code> directly or on a <code>quote_profile</code> extension — a plain data-model choice for the F7 spec. §2.4 already ships an <code>incoterm</code> column on <code>quote</code> (see C-1, now resolved); the recommendation is to keep it there unless a profile split earns its keep. <em>Confirms: F7 spec.</em></p> <p><strong>D-4 — Lead carries a typed 1:1 extension table (sixth entangled entity).</strong> F12 extracts tea vocabulary onto the lead (grade, volume + units, packaging, certifications, Incoterm, destination port) and P-09 requires typed fields. The former banned-vocabulary rule forced these onto a separate <code>lead_profile</code> (1:1 on <code>lead</code>); FS-14 removed that rule, so keeping a separate profile vs folding the fields onto <code>lead</code> is now a plain data-model choice — record Lead’s shape here and in <code>data-model.md</code> when F11/F12 confirm it. <em>Confirms: F11/F12 specs.</em> <strong>Closed at Rev 15 — against the extension table.</strong> F11-a ships <code>lead</code> with every field as a flat column, and F12 adds its extracted fields to <code>lead</code> itself, next to the prompt that fills them (F11-a spec FR-S1, FR-D2 (a)). There is no <code>lead_profile</code>.</p> <p><strong>D-5 — Conversion links, not conversion moves.</strong> Converting a lead creates/matches an Account + Contact and creates a Deal; the lead row is retained with nullable <code>converted_*</code> FKs to all three and <code>status: converted</code>. Nothing is deleted (OQ-21’s import-everything posture extends naturally: history is kept, always). <em>Confirms: F11 spec.</em> F11-a (Rev 15) adds a separate, earlier link — the <strong>matched</strong> account and contact (key edges, cluster 2) — which is not a conversion link. <strong>Whether a conversion starts from the match</strong> (pre-fills the account and contact it creates or matches) is F11-e’s decision. <strong>The lead’s email on conversion</strong> (Rev 34; the lead, 2026-10-26): every email linked to the lead is also linked to the account, contact and deal the conversion sets — links to the one stored copy, not copies — and a converted lead is no longer a target of automatic linking. <em>Confirms: F11-e, F20-f.</em></p> <p><strong>D-6 — One file table; each file names its one record.</strong> <em>Revised — confirmed by F33-a (spec decision 1), which adopts a different shape from the one this map recommended.</em> <strong>The adopted shape:</strong> one <code>attachment</code> table (FS-11, <code>V9__attachment.sql</code>) holds the blob identity — the opaque S3 key, the original name, the sniffed type, the size, the uploader, the scan status and, since F20-h, <code>deleted_at</code> — and names its record in two columns, <code>owner_type</code> and <code>owner_id</code>, with no foreign key and no link tables. A file therefore belongs to exactly one record. Each owner type registers its own visibility (F5-f’s <code>RoutingRecordVisibilityCheck</code> routes the check to the type’s <code>OwnerTypeVisibility</code>) and its own upload policy (the type allow-list), and a file follows its record’s reach (AD #35). The owner types are <code>account</code> and <code>lead</code> (F5-f), <code>contact</code> (F33-a, following its account) and <code>email_upload</code> (F20-h); F33-b adds deals, quotes, samples and product briefs as owner types on the same table. Why no link tables (F33-a decision 1): the owner columns were already on <code>main</code>, the visibility routing already read them, and accounts and leads already used them, so a link table per record type would state the owner twice. Whether a lead’s files move or are copied when the lead converts is F11-e’s decision. <em>Original text, kept as the rationale that was revised:</em> F33 attaches files to deals, accounts, contacts, quotes, <strong>samples and product briefs</strong>, and since Rev 39 leads — F33-a on accounts, contacts and leads, F33-b on the rest. Recommendation: <code>file</code> holds the blob identity (S3, uploader, scan state) and a small link table per target type attaches it. The former core→tea FK ban that shaped this is gone (FS-14 — one schema), but one blob table plus per-target link tables stays the clean design. <em>Confirmed by: FS-11 (the table) and F33-a (spec decision 1, approved 2026-11-06); F33-b adds its owner types.</em></p> <p><strong>D-7 — The account timeline is a projection, never a table.</strong> <em>Revised — confirmed by F1-a (spec FR-S6), which adopts the opposite shape: a stored <code>timeline_event</code> table.</em> <strong>The adopted shape:</strong> one insert-once row per event, written by the feature that owns the event, keyed <code>UNIQUE (source_type, source_id, kind)</code> so a producer’s retry is a no-op (AD #13), and immutable except <code>summary</code> and <code>version</code> by the <code>forbid_value_update()</code> trigger. The drift this paragraph feared is closed by an edit rule rather than by not storing: when a source record changes, its producer rewrites its own row’s <code>summary</code> through the same key (bumping <code>version</code> in the same write), and <code>kind</code>, <code>occurred_at</code>, the source and the account never change — so the timeline never shows text the source no longer carries. Why stored (spec FR-S6’s rationale): (1) several kinds have no source table of their own in Phase 1 — a lead being approved or converted, an email being linked to the account — so a union would have nothing to read; (2) the union would grow by one branch per producing feature, coupling every producer to F1-c’s read path, where a write-a-row contract decouples them; (3) the drift is contained, because the row carries a pointer and the few fields the timeline renders, and the producing record stays the truth. The row follows its account’s reach (AD #35). <em>Original text, kept as the rationale that was revised:</em> every timeline kind (lead/order/sample/call/quote/note/email) already has a source entity; a stored <code>timeline_event</code> would be a second authoritative copy that drifts — the same reasoning that banned stored current/expiring/expired (FR-T4). Cost: a union query per account page, immaterial at PRD volumes. <em>Confirmed by: F1-a (Q-1 acknowledged by Tharinda, 2026-09-24).</em></p> <p><strong>D-8 — Log-class tables reference records loosely; domain tables never do.</strong> <code>audit_event</code> and <code>ai_invocation</code> reference “any record” — ten nullable FKs per log table is worse than a <code>(entity_type, entity_id)</code> pair on an append-only log that is never joined for integrity. This is a deliberate, named exception to the FK-integrity house style, scoped to log-class tables only — with one domain table also named (Rev 41): <strong><code>attachment</code></strong> names its record by <code>owner_type</code> and <code>owner_id</code> with no foreign key (D-6, revised by F33-a), because each owner type’s visibility routing checks the owner on every read and write, and a link table per record type would state the owner twice. <strong><code>timeline_event</code> is the third log-class table (F1-a):</strong> its <code>(source_type, source_id)</code> pair names the producing record loosely, and both columns are <code>NOT NULL</code>, so a producer with no natural source record cannot write a timeline row, and a producer that refreshes a row’s <code>summary</code> by raw SQL must bump <code>version</code> in the same write. F1-e, F1-c, F3-a, F11-f and F20-f design against both rules. <em>Confirms: F39 (audit — AD #36; was FS-6) — the audit half confirmed by F39 (spec FR-1, <code>V24__audit_event.sql</code>: <code>entity_type</code> is the record’s table name, both columns set or both null, and the actor’s <code>actor_user_id</code> is also a loose id, with no foreign key — spec Rev 2) / the AI capability (first consumer) spec; the timeline half confirmed by F1-a.</em></p> <p><strong>D-9 — Sample carries no direct account FK.</strong> Derivable via the deal; two paths drift. The PRD row listing both edges is read as navigational, not two stored columns. <em>Confirms: F6 spec.</em></p> <p><strong>D-10 — Certification sets are join tables, not arrays.</strong> The architecture’s <code>required_certifications text[]</code> sketch is illustrative; joins to <code>certification</code> give FK integrity, admin-editable taxonomy, and clean set-difference queries for F9. OQ-9 may force the standard side to a different grain (batch/lot) — the account side does not wait for it. <strong>The adopted shape (confirmed by F1-a, spec FR-S3):</strong> <code>account_certification (account_id, certification_id)</code>, a composite primary key and both foreign keys, into the admin-editable <code>certification</code> reference table whose codes are stable and whose names are editable — shipped in <code>V14__certification.sql</code> and <code>V15__account.sql</code>. The same join-not-array rule gives F1-a’s tags their <code>account_tag</code> and <code>contact_tag</code> joins. <em>Confirms: F1/F9 specs — the account side confirmed by F1-a; the standard side is still F9’s (OQ-9).</em></p> <p><strong>D-11 — Migration identity is per-entity columns, not a mapping table.</strong> <code>source</code> + <code>source_ref</code> (unique-per-source) on each migratable entity: typed, indexable, and exactly what AD-O-7’s delta-reconciliation pass needs to skip already-migrated records. <em>Confirms: F4 spec.</em></p> <h2 id="contradictions-and-gaps-surfaced-raise-dont-silently-fix"><a class="anchor" href="#contradictions-and-gaps-surfaced-raise-dont-silently-fix" aria-hidden="true">#</a>Contradictions and gaps surfaced (raise, don’t silently fix)</h2> <p><strong>C-1 — <code>quote.incoterm</code> (§2.4) — RESOLVED by FS-14.</strong> <code>data-model.md</code> §2.4 — authoritative for the schema, drift-checked against the proofs — declares <code>incoterm TEXT</code> on <code>quote</code>. This once conflicted with the banned-vocabulary ArchUnit rule (which forbade <code>incoterm</code> as a core identifier) and the module layout assigning Incoterm to the tea-quoting module — a JPA entity mapping that column would not have compiled past the suite. <strong>FS-14 removed both the rule and the module split, so the column compiles and the contradiction is gone.</strong> Whether Incoterm + destination live on <code>quote</code> or on a <code>quote_profile</code> extension (D-3) is now a plain data-model choice for the F7 spec, not a boundary question. <em>Owner: F7 spec author.</em></p> <p><strong>C-2 — Nothing owns getting ERP order data into V1.</strong> <code>order</code> is load-bearing (LTV, dormancy detection, reorder triggers, F13 briefings, the account 360°'s past-orders panel) and the PRD marks it “ERP-sourced, read-only” — but V1 has <strong>no ERP integration</strong> (AD #10; automated IFS sync is a priced follow-on) and no feature paragraph claims the import path. Options: an F23 spreadsheet import of an ERP order extract, a manual admin surface, or shipping F1 with the panel empty-stated. Needs an owner and a client conversation (does an order extract exist?). <em>Answered at F1 spec time: V1 has no <code>order</code> entity and no past-orders panel (F1-a, F1-d); the question to Empire is OQ-63 in <code>project-prd-signals.md</code>.</em></p> <p><strong>C-3 — MOOT since FS-14.</strong> The old architecture module summary listed “Account, Contact, Deal, Pipeline, Stage, Activity, Note, Timeline” and omitted Lead. FS-14 removed that module layout, and this map’s spine diagram carries Lead as a first-class hub entity — so the omission has nothing left to mislead. Lead is a plain spine entity (P-05 replicates Pipedrive’s leads inbox; F11 redesigns it).</p> <p><strong>C-4 — The <code>ChecklistEngine</code> must support stored and computed items.</strong> F7’s readiness items are computed from quote state; F10’s export-doc items are manually toggled and stored; F19 mixes both. If the engine models only one kind, two of its four consumers don’t fit. Not a data-model contradiction — a substrate requirement. FS-13 was cancelled (AD #29), and the engine is built by its first consumer, F7-b (<code>features.md</code>). <em>Owner: F7-b spec author.</em></p> <h2 id="maintenance"><a class="anchor" href="#maintenance" aria-hidden="true">#</a>Maintenance</h2> <ul> <li><strong>A feature spec that touches a listed edge cites this map in <code>## Input Sources</code></strong> and either adopts the row or revises it — a revised row gets the new answer, the spec pointer, and a status flip to settled. Silent divergence between a spec and this map is a review finding (<code>/forge-spec-review</code> dimension: consistency with dependency artifacts).</li> <li>When <code>data-model.md</code> gains a specified section for a cluster, that section becomes the authority; the cluster here shrinks to edges + a pointer (as §4 already does for pricing).</li> <li>Status flips (<code>proposed → settled</code>, <code>open → settled</code>) happen when the owning spec is approved, in the same change that approves the spec. This document never outranks a realized schema.</li> <li>The <code>## Revisions</code> convention from the spec rules applies once the team accepts this draft.</li> </ul> <h2 id="sources"><a class="anchor" href="#sources" aria-hidden="true">#</a>Sources</h2> <p>Derived 2026-08-31 from: <code>.forge/project-prd.md</code> (Rev 12 body — §Domain Model, §Functional Surface, §Lifecycle States, capability matrix), <code>.forge/design/prototypes/feature-detail.md</code> (2026-08-21 verification), <code>.forge/design/architecture.md</code> (Rev 25 — module layout, extension points, enforcement, pricing subsystem), <code>forge-et-be/docs/data-model.md</code> (§1 conventions, §2 verified pricing schema, §3–§7 stubs), FS-2 spec + shipped migrations (V1, V2, V200, V1000), and the AD table in <code>.claude/CLAUDE.md</code> (#5, #8, #11, #14–#17, #26). Where a statement here goes beyond those sources it is marked <strong>proposed</strong> and carries its confirming owner.</p> <h2 id="revisions"><a class="anchor" href="#revisions" aria-hidden="true">#</a>Revisions</h2> <h3 id="rev-1-2026-09-07"><a class="anchor" href="#rev-1-2026-09-07" aria-hidden="true">#</a>Rev 1 — 2026-09-07</h3> <ul> <li><strong>Changed:</strong> header note, the <code>Home</code> definition, D-4 and C-1 annotated for AD #29 — the core/domain split is no longer extended; the two-schema homes stand because the schemas and build guards FS-1/FS-2 shipped stay in place, not because a reusable core is still a goal. No edge, cardinality or status changed.</li> <li><strong>Why:</strong> AD #29 (2026-09-07) supersedes AD #17; this map’s placement arguments cited AD #17’s reuse goal and would otherwise read as if it still held.</li> <li><strong>Impact:</strong> none on any spec; F7 (C-1) and F11/F12 (D-4) inherit a placement decision instead of a reuse argument.</li> <li><strong>Approved by:</strong> Tharinda, 2026-09-07 — the approval on harness PR #52, alongside AD #29.</li> </ul> <h3 id="rev-2-2026-09-07"><a class="anchor" href="#rev-2-2026-09-07" aria-hidden="true">#</a>Rev 2 — 2026-09-07</h3> <ul> <li><strong>Changed:</strong> <code>User</code> gains <code>manager_id</code> (nullable self-reference — the reporting hierarchy behind <code>team</code> scope); <code>Role</code> becomes admin-authored with the six confirmed roles as copy-on-create templates and an M:N user↔role edge unioning to the most permissive grant; <code>Permission / grant</code> becomes <code>(role, permission_key, scope)</code> over a <strong>code-declared</strong> catalog (the permission metadata lives in code, not in a <code>permission</code> table) with scope <code>own</code> / <code>team</code> / <code>all</code> per permission. Statuses stay <code>designed</code>; realized-by widens to FS-6 + F5 for <code>Role</code>.</li> <li><strong>Why:</strong> AD #30 (2026-09-07, refining AD #15; PRD Rev 21) — Empire asked for fully configurable role management. The three rows cited the <code>(role, resource, level)</code> model and would otherwise read as the shape FS-6 should build.</li> <li><strong>Impact:</strong> FS-6 spec Rev 3 (owed) confirms the table names — <code>role_grant</code> is the FS-6 spec’s name and is used here provisionally; a role-template entity or flag is that revision’s to shape. Hierarchy policy (recursion, deactivating a manager with reports, unowned records, edit-vs-view) is OQ-56. No other edge changed.</li> <li><strong>Approved by:</strong> Tharinda, 2026-09-07 — with AD #30.</li> </ul> <h3 id="rev-3-2026-09-07"><a class="anchor" href="#rev-3-2026-09-07" aria-hidden="true">#</a>Rev 3 — 2026-09-07</h3> <ul> <li><strong>Changed:</strong> the two cluster-1 rows Rev 2 left provisional are <strong>confirmed against FS-6 spec Rev 3</strong>, authored the same day. <code>Role</code> gains the concrete shape — <code>is_system</code> (the non-deletable superadmin) and <code>template_key</code>, provenance for display and “reset to template” and deliberately <em>not</em> a foreign key, so copy-on-create is a snapshot. <code>Permission / grant</code> records that <code>role_grant</code> is keyed <code>UNIQUE (role_id, permission_key)</code> and that the separate named-permission store is <strong>removed</strong>, so one table answers every check; <code>APPROVE_SUB_FLOOR_QUOTE</code> is written in its catalog form, <code>quote.approve_sub_floor</code>. No edge, cardinality or status changed.</li> <li><strong>Why:</strong> Rev 2 deferred exactly these two questions to FS-6 spec Rev 3 (“confirms the table names… a role-template entity or flag is that revision’s to shape”). That revision exists now, so the deferral is discharged rather than left pointing at a document that has already answered.</li> <li><strong>Impact:</strong> none on any other spec. Template contents for Tea Room / Executive remain OQ-53(b); the hierarchy policy remains OQ-56; where template content physically lives is FS-6’s Q-12, still open as a plan decision, so this map names the columns and not the seed vehicle.</li> <li><strong>Approved by:</strong> <em>pending</em> — rides FS-6 spec Rev 3’s lead ack (Tharinda), since it records that revision’s outcome and nothing else.</li> </ul> <h3 id="rev-4-2026-09-10-schema-qualifiers-dropped-for-the-single-schema-collapse-ad-31-fs-14"><a class="anchor" href="#rev-4-2026-09-10-schema-qualifiers-dropped-for-the-single-schema-collapse-ad-31-fs-14" aria-hidden="true">#</a>Rev 4 — 2026-09-10 — schema qualifiers dropped for the single-schema collapse (AD #31, FS-14)</h3> <ul> <li><strong>Changed:</strong> the header note, the <code>Home</code> definition, the spine diagram, every <code>Home</code> cell and the D-4 / D-6 / C-1 blocks are de-qualified — the former <code>core.</code>/<code>tea.</code> schema prefixes are removed (one <code>public</code> schema since FS-14), cluster headings name the feature-first capability instead of the removed <code>core-*</code>/<code>tea-*</code> module, and the placement arguments that once cited the banned-vocabulary rule or the <code>core → tea</code> FK ban are reframed as plain data-model choices (those guards are gone). <strong>C-1 is marked RESOLVED</strong> — <code>quote.incoterm</code> no longer conflicts with anything once the vocabulary rule is removed.</li> <li><strong>Why:</strong> AD #31 (2026-09-09, FS-14) collapsed the two schemas into one and removed the split’s guards. The map’s homes and its boundary-driven reasoning would otherwise read as a schema layout and a set of constraints that no longer exist.</li> <li><strong>Impact:</strong> <strong>no edge, cardinality, status or entity changed</strong> — this is a naming/qualifier pass plus the discharge of C-1. The typed 1:1 extension tables survive as data-model design (now unqualified); a feature spec may fold one into its base table (D-4 notes this for Lead).</li> <li><strong>Approved by:</strong> Tharinda, 2026-09-09 — the AD #31 lead sign-off (the FS-14 cascade carries it).</li> </ul> <h3 id="rev-5-2026-09-11-the-price-loses-its-market-axis-prd-rev-23"><a class="anchor" href="#rev-5-2026-09-11-the-price-loses-its-market-axis-prd-rev-23" aria-hidden="true">#</a>Rev 5 — 2026-09-11 — the price loses its market axis (PRD Rev 23)</h3> <ul> <li><strong>Changed:</strong> the Price edge becomes <code>Buying standard × validity</code> with status <em>revision owed</em>; the <code>market</code> note states it is a customer attribute and quote field, not a price key. Cost was already market-free.</li> <li><strong>Why:</strong> Empire confirmed one price per standard on 2026-09-09 and their weekly price workbook matches; PRD Rev 23 records the decision (Dinil, 2026-09-11) and revises OQ-38’s Rev 6 answer.</li> <li><strong>Impact:</strong> <code>forge-et-be/docs/data-model.md</code> §2.2 and the price/snapshot DDL it describes need revising before the F26 spec — owner Tharinda (AD #31). No shipped migration carries the axis. The quote’s destination-market trade field (D-3) is unaffected.</li> </ul> <h3 id="rev-6-2026-09-11-the-role-model-is-simplified-ad-32-prd-rev-24"><a class="anchor" href="#rev-6-2026-09-11-the-role-model-is-simplified-ad-32-prd-rev-24" aria-hidden="true">#</a>Rev 6 — 2026-09-11 — the role model is simplified (AD #32, PRD Rev 24)</h3> <ul> <li><strong>Changed:</strong> the Role row — no templates (only the system superadmin is seeded; <code>template_key</code> and the <code>role_template*</code> tables go with FS-6 spec Rev 5), User↔Role becomes <strong>N:1</strong> (one role per user; the M:N join and the most-permissive union are dropped), and a role still held cannot be deleted. The Permission / grant row’s category list becomes read / edit / execute — AI is not a grantable level — and the Managing Director’s held key is described as a role, not a template.</li> <li><strong>Why:</strong> team decision (Tharinda, 2026-09-11; confirmed by Dinil) to remove complexity nobody asked for; recorded as AD #32 / PRD Rev 24.</li> <li><strong>Impact:</strong> FS-6 spec Rev 5 + plan revision (2026-09-11) drop <code>role_template</code>/<code>role_template_grant</code>, replace <code>user_role</code> with <code>app_user.role_id</code>, remove the union and the ai-use category); no other edge or entity changes; the FS-3 <code>PermissionDecision</code> seam is unaffected.</li> </ul> <h3 id="rev-7-2026-09-15-the-products-catalog-is-removed-the-buying-standard-is-the-sellable-record-prd-rev-27"><a class="anchor" href="#rev-7-2026-09-15-the-products-catalog-is-removed-the-buying-standard-is-the-sellable-record-prd-rev-27" aria-hidden="true">#</a>Rev 7 — 2026-09-15 — the products catalog is removed; the Buying Standard is the sellable record (PRD Rev 27)</h3> <ul> <li><strong>Changed:</strong> cluster 3’s <code>Product</code> row is struck (retired — removal owed) and the cluster re-headed; <code>deal_product</code> becomes <code>deal_line_item</code> and, with <code>line_item</code>, points at the <strong>buying standard</strong>; cluster 4’s <code>Buying standard → Product</code> edge is removed; cluster 6’s held-certs join becomes the standard’s; the <code>PriceModel</code> fallback note reads as history.</li> <li><strong>Why:</strong> PRD Rev 27 (2026-09-15): one list instead of two — every sellable item, bulk or private label, is a client’s standard, so the catalog and its <code>N:1 Product</code> edges have nothing left to carry. Applied to the prototype in harness PR #88.</li> <li><strong>Impact:</strong> <code>forge-et-be/docs/data-model.md</code> §2 (<code>buying_standard.product_id</code>, <code>line_item.product_id</code>, <code>product</code>, <code>ListPriceModel</code>) is revised by its owner — <strong>Tharinda (AD #31)</strong>; the shipped <code>catalog</code> package, <code>V3__product.sql</code> and <code>ProductPermissions</code> are retired with it (with F26’s spec or earlier). Whether private-label standards carry weekly prices is <strong>OQ-61</strong>; OQ-9’s grain question now attaches to the standard. No other edge, cardinality or entity changed.</li> <li><strong>Approved by:</strong> Tharinda, 2026-09-16 — the FS-15 spec approval (harness PR #99) carries PRD Rev 27’s lead ack.</li> </ul> <h3 id="rev-8-2026-09-16-fs-15-ships-the-removal-rev-7-recorded-as-owed"><a class="anchor" href="#rev-8-2026-09-16-fs-15-ships-the-removal-rev-7-recorded-as-owed" aria-hidden="true">#</a>Rev 8 — 2026-09-16 — FS-15 ships the removal Rev 7 recorded as owed</h3> <ul> <li><strong>Changed:</strong> the struck <code>Product</code> row’s status goes from <em>removal owed</em> to <strong>removed</strong> (<code>V11__drop_product.sql</code>), and the line-item edge from <em>retarget owed</em> to <strong>verified</strong> — <code>line_item</code> references <code>buying_standard</code> in <code>data-model.md</code> §2.4. The buying standard is the substrate’s reference entity, in the minimal shape FS-15’s <code>V10</code> ships; F26 extends it (the allocator <code>DEFAULT</code>) and F1 adds <code>account_id</code>.</li> <li><strong>Why:</strong> FS-15 (PRD Rev 27) implemented what Rev 7 had only recorded. Nothing else moves: no new entity, no cardinality change, and the held-certifications join is still OQ-9’s.</li> <li><strong>Impact:</strong> <code>forge-et-be</code> carries no <code>product</code> table, <code>catalog</code> package or <code>product.*</code> permission key.</li> <li><strong>Approved by:</strong> <em>(owed — the approval of the FS-15 harness PR carrying this revision)</em></li> </ul> <h3 id="rev-9-2026-09-22-the-mailbox_connection-row-is-confirmed-by-f20-a-email_message-is-re-attributed-to-f20-b"><a class="anchor" href="#rev-9-2026-09-22-the-mailbox_connection-row-is-confirmed-by-f20-a-email_message-is-re-attributed-to-f20-b" aria-hidden="true">#</a>Rev 9 — 2026-09-22 — the <code>mailbox_connection</code> row is confirmed by F20-a; <code>email_message</code> is re-attributed to F20-b</h3> <ul> <li><strong>Changed:</strong> §7’s <code>Mailbox connection</code> row moves from <em>designed (PRD/arch)</em> to <strong>confirmed</strong>, realized by <strong>F20-a</strong> rather than the umbrella <code>F20</code>, and records the two facts F20-a’s approved spec adds to the edge — the owner stays nullable from the start so F20-e needs no schema change (FR-4), and partial unique indexes enforce at most one non-<code>DISCONNECTED</code> connection per owner and per <code>provider_account_id</code>. The <code>Email message</code> row’s <code>Realized by</code> moves from <code>F20</code> to <strong>F20-b</strong>, with F20-a’s decision D-4 named.</li> <li><strong>Why:</strong> the F20-a spec (approved 2026-09-21) cites this file in <code>## Input Sources</code> and <strong>adopts</strong> the <code>mailbox_connection</code> row unchanged, which is the adopt-or-revise obligation the Reference Map states for any spec touching a listed edge — but no work item owned the write-back, so the row still read as un-confirmed after the spec that confirmed it. D-4 is recorded on the <code>email_message</code> row for the same reason: F20-a ships no table without a writer, and leaving the row attributed to <code>F20</code> invites the next reader to expect it in this feature.</li> <li><strong>Impact:</strong> none on code. No entity is added, no cardinality changes, and the held-certifications join is still OQ-9’s. F20-b confirms the <code>email_message</code> row when its spec is written.</li> <li><strong>Approved by:</strong> <em>(owed — the approval of the F20-a harness PR carrying this revision)</em></li> </ul> <h3 id="rev-10-2026-09-24-access-ownership-and-sharing-and-the-audit-trail-ad-34-ad-35-ad-36"><a class="anchor" href="#rev-10-2026-09-24-access-ownership-and-sharing-and-the-audit-trail-ad-34-ad-35-ad-36" aria-hidden="true">#</a>Rev 10 — 2026-09-24 — access, ownership and sharing, and the audit trail (AD #34, AD #35, AD #36)</h3> <ul> <li><strong>Changed — cluster 1:</strong> <code>User</code> records the hierarchy and lifecycle policy that answers OQ-56 (recursive <code>team</code>; pre-created users, deactivated and reactivated, never deleted; deactivation refused while the user has direct reports or owns records; deactivated users stay in the tree). <code>User identity</code> notes that an email change clears the link. <code>Role</code> drops the superadmin and <code>is_system</code> and records the Flyway-seeded, editable IT Admin role, the immutable role key, delete blocked while any user (active or deactivated) holds the role, and the last-admin invariant; realized-by adds F5-k. <code>Permission / grant</code> records AD #34’s minimal catalog (view / manage per entity, <code>manage</code> implies <code>view</code>, the special keys, one <code>access.manage</code>), with no category axis and no <code>*</code> grant; the ~100–150-key, category-carrying catalog becomes a <em>Was</em> line. <code>Audit event</code> moves to AD #36’s design, realized by <strong>F39</strong> (was “FS-6 / first consumer”). <code>Session</code> notes that deactivation deletes the user’s sessions. The key-edges note gains <code>created_at</code> / <code>modified_at</code> on every table and leaves the <code>SYSTEM</code> actor’s representation to F39. The spine diagram’s “six roles” becomes “one role each”.</li> <li><strong>Changed — clusters 2, 7 and 10:</strong> <code>Account</code> records <code>owner_id NOT NULL</code>; <code>Lead</code> records the owner nullable for import edge cases only, with unowned leads visible at <code>all</code> scope only. <code>Mailbox connection</code> records that no unowned connection exists in V1 (F20-e left V1 on 2026-09-24; <code>info@</code> arrives by forwarding), leaving the shipped nullable owner unused. <code>Record share</code> moves from <em>proposed</em> to <strong>designed</strong>, with AD #35’s columns (<code>shared_with_user_id</code>, <code>shared_by_user_id</code>, <code>shared_at</code>; <code>account_id</code> and <code>lead_id</code> now, <code>deal_id</code> and <code>quote_id</code> later; exactly one set; unique per record and user) and <strong>F5-f</strong> as the confirming spec in place of F1/F2. <code>Search</code> names the one visibility rule. D-8’s confirming spec for the audit half becomes F39.</li> <li><strong>Why:</strong> the lead’s access-model decisions, signed off 2026-09-24 as AD #34 (access model), AD #35 (ownership and sharing) and AD #36 (audit trail). Full rationale: <code>.forge/engagement-log.md</code> § AD #34, AD #35, AD #36; the sharing design record is <code>design/data/record-sharing-model.md</code> (revised the same day).</li> <li><strong>Impact:</strong> F5-k removes <code>is_system</code>, the superadmin row and the <code>*</code> grant and seeds IT Admin; F5-f builds <code>record_share</code> and the visibility rule; F39 builds <code>audit_event</code> and adds missing timestamp columns. <code>forge-et-be/docs/data-model.md</code> gains the <code>record_share</code> DDL with F5-f. No other entity or cardinality changes; the held-certifications join is still OQ-9’s.</li> <li><strong>Approved by:</strong> <em>(owed — the approval of the harness PR carrying the AD #34–#36 changes)</em></li> </ul> <h3 id="rev-11-2026-09-23-f20-b-confirms-email_message-revising-the-row-on-both-halves"><a class="anchor" href="#rev-11-2026-09-23-f20-b-confirms-email_message-revising-the-row-on-both-halves" aria-hidden="true">#</a>Rev 11 — 2026-09-23 — F20-b confirms <code>email_message</code>, revising the row on both halves</h3> <p><em>Written 2026-09-23 on the F20-b wave-1 branch as “Rev 10”; renumbered Rev 11 when that branch merged after the AD #34–#36 Rev 10 reached <code>main</code> first (an unmerged claim yields — <code>.claude/rules/tracker.md</code>, L-057).</em></p> <ul> <li><strong>Changed:</strong> §7’s <code>Email message</code> row moves from <em>designed (PRD)</em> to <strong>confirmed</strong> against the F20-b spec (approved 2026-09-23), and is <strong>revised rather than adopted</strong>, on both halves. (1) <strong>The auto-link edges</strong> → account / contact / deal / lead / quote are re-attributed to <strong>F20-f</strong>: F20-b ships only <code>N:1 mailbox_connection</code>. (2) <strong>Tracking state</strong> is re-attributed to <strong>F20-g</strong> and is not a column of the table F20-b ships. The row also records what F20-b decided that the old row left open — the body is stored in Postgres (spec D-1), <code>direction</code> is derived at ingest, <code>conversation_id</code> is stored from the first migration — and <code>Realized by</code> names all three owners. The <code>Mailbox connection</code> row notes F20-b’s four sync-state columns (spec FR-2b), with no edge change.</li> <li><strong>Why:</strong> spec D-4 — none of the five linked tables existed when F20-b was written (the schema then ran <code>V1…V13</code> with no account/contact/deal/lead/quote table), so F20-b could not declare those foreign keys at all, and F20-f is the feature that populates them. Tracking is F20-g’s by the decomposition. Leaving the row as it was would have told the next reader to expect the links and the tracking columns in F20-b. The adopt-or-revise obligation the Reference Map states for a spec touching a listed edge is discharged here, in the WI that ships the table (F20-b-WI-1.1, AC-3).</li> <li><strong>Impact:</strong> F20-f owns an <code>ALTER TABLE email_message</code> adding the five nullable link columns; F20-g owns the tracking columns or table. <code>forge-et-be/docs/data-model.md</code> §9.1 carries the shipped <code>CREATE TABLE</code>.</li> <li><strong>Approved by:</strong> <em>(owed — the approval of the F20-b wave-1 harness PR carrying this revision)</em></li> </ul> <h3 id="rev-12-2026-09-25-f1-a-confirms-the-account-and-contact-substrate-account-note-timeline-tag-d-7-d-8-d-10"><a class="anchor" href="#rev-12-2026-09-25-f1-a-confirms-the-account-and-contact-substrate-account-note-timeline-tag-d-7-d-8-d-10" aria-hidden="true">#</a>Rev 12 — 2026-09-25 — F1-a confirms the account and contact substrate: Account, Note, Timeline, Tag, D-7, D-8, D-10</h3> <ul> <li><strong>Changed — cluster 2:</strong> the <code>Account</code> row moves to <strong>shipped — confirmed by F1-a</strong>, revised on two halves (spec FR-D3 (a), (b)): the home is <code>account</code> alone, with the tea attributes as <strong>flat columns</strong> rather than an <code>account + account_profile</code> 1:1 split; and “LTV + dormancy are derived, never stored” becomes <strong>LTV is an entered estimate</strong> (<code>estimated_ltv</code> + <code>ltv_currency</code>) with <strong>dormancy still derived</strong>, from the latest <code>timeline_event.occurred_at</code>. The spine diagram’s <code>account[t]</code> loses its extension marker, and the entangled-entities list strikes Account.</li> <li><strong>Changed — cluster 6:</strong> <code>Account required certs</code> moves to <strong>shipped — confirmed by F1-a</strong>.</li> <li><strong>Changed — cluster 8:</strong> <code>Note</code> moves to <strong>shipped — confirmed by F1-a</strong>, with the named <code>note_has_target</code> <code>CHECK</code> that F11-a and F2-a widen, and the reach rule the F1-a WI-3.1 plan decided (D16, Q-10): a note holds no key of its own and follows its parent; a note with both targets follows its account; a note on an account-less contact is reachable only at <code>all</code>. <code>Timeline</code> is revised from <strong>no table</strong> to the stored <strong><code>timeline_event</code></strong> (spec FR-D3 ©), with its unique replay key, its <code>summary</code> / <code>version</code> writable set, the <code>NOT NULL</code> source pair and the caller’s <code>version</code> bump. <strong>A <code>Tag</code> row is added</strong> (spec FR-D3 (d)) — <code>tag</code> per <code>entity_type</code> with unique <code>(entity_type, lower(name))</code>; joins <code>account_tag</code> and <code>contact_tag</code> owned by F1-a, <code>lead_tag</code> and <code>deal_tag</code> owed by F11-a and F2-a — with D16’s vocabulary gate (names readable by any signed-in user, tagging under the tagged entity’s <code>manage</code>, rename and delete under <code>settings.manage</code>). The spine diagram’s cross-cutting line no longer calls the timeline a read-time projection, and lists <code>tag</code>.</li> <li><strong>Changed — decisions:</strong> D-7 is <strong>revised</strong> to the stored shape and keeps its original text as the rationale that was revised; D-8 names <code>timeline_event</code> as its third log-class table and records the two rules every producer designs against; D-10 records the shipped account-side join.</li> <li><strong>Why:</strong> F1-a (spec approved at Rev 5) ships these tables, and the Reference Map’s adopt-or-revise obligation for a spec touching a listed edge is discharged in the work item that ships them (F1-a-WI-3.1, subtask 8, AC-26 (d)). The stored timeline was Q-1 of the spec, acknowledged by Tharinda on 2026-09-24.</li> <li><strong>Impact:</strong> F1-e builds the notes and tags APIs to the D16 rules; F1-c renders <code>timeline_event</code> and owns the final dormancy rule; F3-a, F11-f and F20-f write timeline rows that always name a source and bump <code>version</code> when they refresh a summary; F11-a and F2-a add <code>lead_tag</code> / <code>deal_tag</code> and widen <code>note_has_target</code>. <code>forge-et-be/docs/data-model.md</code> §3 carries the shipped <code>CREATE</code>s.</li> <li><strong>Approved by:</strong> <em>(owed — the approval of the F1-a WI-3.1 harness PR carrying this revision)</em></li> </ul> <h3 id="rev-13-2026-09-25-f39-confirms-the-audit-trail-and-revises-the-timeline-row"><a class="anchor" href="#rev-13-2026-09-25-f39-confirms-the-audit-trail-and-revises-the-timeline-row" aria-hidden="true">#</a>Rev 13 — 2026-09-25 — F39 confirms the audit trail and revises the Timeline row</h3> <ul> <li><strong>Changed — cluster 1:</strong> the <code>Audit event</code> row moves from <strong>designed</strong> to <strong>shipped — confirmed by F39</strong> (spec FR-1, <code>V24__audit_event.sql</code>). It now names the actor-kind column (<code>USER</code>, <code>SYSTEM</code>, <code>ANONYMOUS</code>) instead of a reserved user, the plain <code>actor_user_id</code> with no foreign key (spec Rev 2), and the loose <code>(entity_type, entity_id)</code> pair, and records that the database refuses every update, delete and truncate.</li> <li><strong>Changed — cluster 8:</strong> the <code>Timeline</code> row records the <code>modified_at</code> / <code>modified_by</code> columns F39’s FR-10 migration adds and the widened trigger writable set (<code>summary</code>, <code>version</code>, <code>modified_at</code>, <code>modified_by</code>), replacing “no <code>modified_*</code> columns” (spec FR-10, W-1).</li> <li><strong>Changed — decisions:</strong> D-8’s audit half is confirmed by F39: <code>entity_type</code> is the record’s table name, and the actor’s user id is a loose reference too.</li> <li><strong>Why:</strong> F39 (spec approved, Rev 1 to Rev 4) ships the table, and the Reference Map’s adopt-or-revise obligation for a spec touching a listed edge is discharged in the work item that ships it (F39-WI-1.1, subtask 8). AD #36’s every-table timestamp rule is what reaches <code>timeline_event</code>.</li> <li><strong>Impact:</strong> every writing feature records its events through the audit service and adds any new code to <code>forge-et-be/docs/audit/README.md</code>; F5-c, F5-f and the first export feature write the codes reserved for them there. <code>timeline_event</code> producers (F1-e, F3-a, F11-f, F20-f) may stamp <code>modified_at</code> / <code>modified_by</code> when they refresh a summary. Biseni, the F1-a owner, was told of the Timeline revision in forge-et-be#68 and forge-et-harness#210. <code>forge-et-be/docs/data-model.md</code> §3 and §7.1 carry the shapes.</li> <li><strong>Approved by:</strong> Biseni Perera (approval of the F39 Wave 1 harness PR, forge-et-harness#210, 2026-09-25)</li> </ul> <h3 id="rev-14-2026-09-25-f26-a-adopts-cluster-4-the-price-rows-revision-owed-is-cleared"><a class="anchor" href="#rev-14-2026-09-25-f26-a-adopts-cluster-4-the-price-rows-revision-owed-is-cleared" aria-hidden="true">#</a>Rev 14 — 2026-09-25 — F26-a adopts cluster 4; the Price row’s “revision owed” is cleared</h3> <ul> <li><strong>Changed — cluster 4:</strong> the “Price → Buying standard × validity” row’s status moves from <strong>revision owed</strong> to <strong>verified</strong>: <code>data-model.md</code> §2.2/§2.5 now carry the Rev 23 (no market axis) and Rev 31 (four-figure build-up) revisions. The F26-a spec adopts the cluster-4 rows as written (F26-a spec Input Sources, FR-D2); the Price, Cost and “Price / Cost → Auction sale” rows move to <strong>shipped</strong> in the harness PR that accompanies F26-a’s backend PR. The “Line-item snapshot → Price / Cost” row, and cluster 3’s “Line item → bulk price snapshot” row, stay <em>verified</em> — Phase 2’s (F26-a spec Q-2).</li> <li><strong>Numbering:</strong> drafted as Rev 13 on the F26-a spec branch; renumbered Rev 14 when <code>main</code> merged in, because F39 landed its Rev 13 first.</li> <li><strong>Approved by:</strong> <em>(owed — the approval of the F26-a spec PR carrying this revision)</em></li> </ul> <h3 id="rev-15-2026-09-26-f11-a-confirms-the-lead-substrate-lead-lead-source-the-matched-account-and-contact-note-tag-d-4-d-5"><a class="anchor" href="#rev-15-2026-09-26-f11-a-confirms-the-lead-substrate-lead-lead-source-the-matched-account-and-contact-note-tag-d-4-d-5" aria-hidden="true">#</a>Rev 15 — 2026-09-26 — F11-a confirms the lead substrate: Lead, Lead source, the matched account and contact, Note, Tag, D-4, D-5</h3> <ul> <li><strong>Changed — cluster 2:</strong> the <code>Lead</code> row moves to <strong>shipped — confirmed by F11-a</strong> (spec FR-D2 (a), ©): the home is <code>lead</code> alone with every field as a flat column, not <code>lead + lead_profile</code>; the row lists the columns F11-a ships and names the columns later features add — F12’s extracted tea details (on <code>lead</code> itself), the AI outputs of F11-d, F11-g and F11-h, and F11-e’s conversion links — and the research-snapshot table and score storage as F11-c’s and F11-g’s. The <code>Lead source</code> row moves to <strong>shipped</strong> as <code>lead_source</code> + <code>lead_source_detail</code>, with the reason it is not <code>source</code> (FR-D2 (b)). <strong>A key-edges row is added</strong>, <em>Lead → matched Account / Contact</em> (N:1 each, nullable, F11-a), set by the intake, <code>PATCH</code>, F4-b and F11-d, not the conversion link, changing nobody’s reach (FR-D2 (e)). The spine diagram’s <code>lead[t]</code> loses its extension marker, and the entangled-entities sentence records Lead as closed.</li> <li><strong>Changed — cluster 8:</strong> the <code>Note</code> row marks <code>lead_id</code> <strong>shipped</strong>, with <code>note_lead_exclusive</code> (a lead note’s only target is the lead); the <code>Tag</code> row marks <code>lead_tag</code> <strong>shipped</strong> and names F11-f as the builder of the lead tags API (FR-D2 (d)).</li> <li><strong>Changed — cluster 10:</strong> the capture sentence reads <code>lead_source = 'Trade Fair'</code> + <code>lead_source_detail</code>, with <code>source = 'capture'</code> as the replay identity (FR-D2 (f)).</li> <li><strong>Changed — decisions:</strong> <strong>D-4 is closed</strong> against the <code>lead_profile</code> extension table; <strong>D-5</strong> gains a note that the match is a separate, earlier link and that F11-e decides whether a conversion starts from it (FR-D2 (e)).</li> <li><strong>Why:</strong> F11-a (spec approved 2026-09-25) ships <code>lead</code>, <code>lead_tag</code> and <code>note.lead_id</code>, and the Reference Map’s adopt-or-revise obligation for a spec touching a listed edge is discharged in the work item that ships them (F11-a-WI-1.1, subtask 5, AC-29 (d)). The flat-column decision and the move of the snapshot and score tables to F11-c and F11-g are the developer decisions of 2026-09-25 recorded in the spec’s <code>## Context</code>.</li> <li><strong>Impact:</strong> F12 adds its extracted fields to <code>lead</code> by migration; F11-c, F11-d, F11-g and F11-h add their own columns or tables; F11-e reads the match when it designs conversion; F4-b writes <code>lead_source</code> for the channel and <code>source = 'pipedrive'</code> for the identity, and sets the match it knows; F36-a writes <code>source = 'capture'</code>; F2-a still widens <code>note_has_target</code> for <code>deal_id</code>. <code>forge-et-be/docs/data-model.md</code> §3 carries the shipped <code>CREATE</code>s and the <code>note</code> <code>ALTER</code> block.</li> <li><strong>Numbering:</strong> drafted as Rev 14 on the F11-a wave branch; renumbered Rev 15 when <code>main</code> merged in, because F26-a landed its Rev 14 first.</li> <li><strong>Approved by:</strong> <em>(owed — the approval of the F11-a harness PR carrying this revision)</em></li> </ul> <h3 id="rev-16-2026-09-27-ad-37-a-grant-has-no-scope"><a class="anchor" href="#rev-16-2026-09-27-ad-37-a-grant-has-no-scope" aria-hidden="true">#</a>Rev 16 — 2026-09-27 — AD #37: a grant has no scope</h3> <ul> <li><strong>Changed:</strong> the <code>Permission / grant</code> row — grants are <code>(role, permission_key)</code> with no scope (F5-l drops <code>role_grant.scope</code>); each owned entity gains an <code><entity>.all</code> key; the scope-aware flag leaves the catalog metadata; F5-l joins the owner column. The <code>User</code> row notes that the reporting hierarchy is what every key reaches down, so setting a manager is an access decision. The <code>Record share</code> row states the roll-up without scopes.</li> <li><strong>Why:</strong> AD #37 (lead decision, 2026-09-27; PRD Rev 43). No other entity, column or relationship changes: <code>app_user.manager_id</code>, every <code>owner_id</code> and <code>record_share</code> stay as they are.</li> <li><strong>Approved by:</strong> Tharinda (lead), 2026-09-27 — the AD #37 sign-off.</li> </ul> <h3 id="rev-17-2026-09-28-f26-a-ships-the-price-cost-and-auction-sale-tables"><a class="anchor" href="#rev-17-2026-09-28-f26-a-ships-the-price-cost-and-auction-sale-tables" aria-hidden="true">#</a>Rev 17 — 2026-09-28 — F26-a ships the price, cost and auction-sale tables</h3> <ul> <li><strong>Changed — cluster 4:</strong> the rows “Price → Buying standard × validity”, “Cost → Buying standard × validity” and “Price / Cost → Auction sale (anchor)” move from <em>verified</em> to <strong>shipped — F26-a</strong>, naming <code>V29__price_and_cost.sql</code>. The “Line-item snapshot → Price / Cost” row, and cluster 3’s “Line item → bulk price snapshot” row, stay <em>verified</em> — Phase 2’s (F26-a spec Q-2).</li> <li><strong>Why:</strong> F26-a-WI-1.1 shipped <code>auction_sale</code>, <code>buying_standard_price</code> and <code>buying_standard_cost</code> with their base columns, the value-immutability opt-ins, the FR-S8 triggers (a published price can be neither deleted nor returned to draft) and the FR-S9 indexes, as Rev 14 said the rows would move in the harness PR beside the backend PR (F26-a spec FR-D2, AC-22). <code>forge-et-be/docs/data-model.md</code> §2.5 carries the shipped <code>CREATE</code>s.</li> <li><strong>Impact:</strong> none on other edges. F26-b, F26-c, F26-f and F26-g add their write paths against the shipped tables; Phase 2’s quote snapshot references <code>price_identity</code> and <code>cost_identity</code> as §2.5 shows.</li> <li><strong>Numbering:</strong> drafted as Rev 16 on the F26-a-WI-1.1 harness branch; renumbered Rev 17 when <code>main</code> merged in, because AD #37 landed its Rev 16 first.</li> <li><strong>Approved by:</strong> <em>(owed — the approval of the F26-a Wave 1 harness PR carrying this revision)</em></li> </ul> <h3 id="rev-18-2026-09-29-f26-b-takes-the-standards-held-certifications"><a class="anchor" href="#rev-18-2026-09-29-f26-b-takes-the-standards-held-certifications" aria-hidden="true">#</a>Rev 18 — 2026-09-29 — F26-b takes the standard’s held certifications</h3> <ul> <li><strong>Changed — cluster 6:</strong> the row “Standard held certs” moves from <em>open — OQ-9</em>, owner F9, to <strong>proposed — F26-b</strong>, owner F26-b, with the grain stated as <strong>per standard</strong> and the shape as a join with a composite primary key, like <code>account_certification</code>.</li> <li><strong>Why:</strong> OQ-9 was narrowed on 2026-09-17 to “held per standard”, with F26-b building the join and F9 comparing (F26-a spec Q-1). The F26-b spec (FR-S1, FR-D2) adopts the row. Only OQ-9’s client half stays open — where Empire’s existing data lives — and it is a migration source, not a shape.</li> <li><strong>Impact:</strong> F9 reads the join and builds no table of its own. The row moves to <em>shipped</em> in the harness PR that accompanies F26-b’s backend PR.</li> <li><strong>Approved by:</strong> Biseni Perera (2026-09-29, with the F26-b spec approval)</li> </ul> <h3 id="rev-19-2026-10-02-f5-f-confirms-record_share"><a class="anchor" href="#rev-19-2026-10-02-f5-f-confirms-record_share" aria-hidden="true">#</a>Rev 19 — 2026-10-02 — F5-f confirms <code>record_share</code></h3> <ul> <li><strong>Changed:</strong> the <code>Record share</code> row moves from <em>designed</em> to <strong>confirmed — F5-f spec</strong> (FR-S1), and states two rules: a share to a deactivated user is inert until they are reactivated, and a record with no owner cannot be shared.</li> <li><strong>Why:</strong> the F5-f spec (approved 2026-10-02) confirms the table’s shape and records both rules — the first a lead decision at spec authoring (PRD Rev 49), the second following the PRD’s “unowned records are visible only to <code>lead.all</code> holders”.</li> <li><strong>Impact:</strong> none to the shape. The row moves to <em>shipped</em> in the harness PR that accompanies F5-f’s backend PR.</li> <li><strong>Approved by:</strong> Tharinda Rajapaksha (2026-10-02, with the F5-f spec approval)</li> </ul> <h3 id="rev-20-2026-10-02-f26-b-ships-the-standards-held-certifications"><a class="anchor" href="#rev-20-2026-10-02-f26-b-ships-the-standards-held-certifications" aria-hidden="true">#</a>Rev 20 — 2026-10-02 — F26-b ships the standard’s held certifications</h3> <ul> <li><strong>Changed — cluster 6:</strong> the row “Standard held certs” moves from <em>proposed — F26-b</em> to <strong>shipped — F26-b</strong>, naming <code>V32__buying_standard_certification.sql</code>.</li> <li><strong>Why:</strong> F26-b-WI-1.1 shipped <code>buying_standard_certification</code> in the shape Rev 18 records — held per standard, a join with a composite primary key and both foreign keys, with <code>account_certification</code>’s post-F39 base columns — and the index on <code>certification_id</code> for F9’s reverse lookup (F26-b spec FR-S1, FR-S2, AC-34). <code>forge-et-be/docs/data-model.md</code> §2.5 carries the shipped <code>CREATE</code>; the join is written only through <code>BuyingStandard.heldCertifications</code>.</li> <li><strong>Impact:</strong> none on other edges. F9 compares the join with <code>account_certification</code> in SQL and builds no table of its own; loading Empire’s standard-held certification data (OQ-9’s client half) stays a migration source for F4-d / F23-b.</li> <li><strong>Approved by:</strong> <em>(owed — the approval of the F26-b Wave 1 harness PR carrying this revision)</em></li> <li><em>Renumbered from Rev 19 to Rev 20 when <code>main</code> was merged into the wave branch: F5-f’s Rev 19 merged first.</em></li> </ul> <h3 id="rev-21-2026-10-05-f11-b-takes-the-read-only-tag-list"><a class="anchor" href="#rev-21-2026-10-05-f11-b-takes-the-read-only-tag-list" aria-hidden="true">#</a>Rev 21 — 2026-10-05 — F11-b takes the read-only tag list</h3> <ul> <li><strong>Changed — the Tag row:</strong> the tags API is split by who builds each part. The read-only list of a type’s active tags, <code>GET /api/v1/tags?entityType=…</code>, is <strong>F11-b’s</strong> (its lead filter needs the options); tag writes and assignment to accounts and contacts stay <strong>F1-e’s</strong>, which extends that route rather than building a second list; attaching, detaching and creating lead tags is <strong>F11-f’s</strong>.</li> <li><strong>Why:</strong> the F11-b spec (2026-10-05, developer decision 3) filters the lead list by tag, and no tag read route exists on <code>forge-et-be</code> <code>main</code>. The F1-e stub had said “Lead tags — F11-b” and the F11-a spec (Q-1) had proposed F11-f; the F11-b spec settles it and corrects the F1-e and F11-f stubs.</li> <li><strong>Impact:</strong> no table, column or relationship changes; only the API owner column of the Tag row.</li> <li><strong>Approved by:</strong> <em>(owed — the approval of the F11-b spec PR carrying this revision)</em></li> </ul> <h3 id="rev-22-2026-10-06-f11-f-adds-the-lead-rule-to-the-timeline-row-and-the-nurture-meaning-to-the-lead-row"><a class="anchor" href="#rev-22-2026-10-06-f11-f-adds-the-lead-rule-to-the-timeline-row-and-the-nurture-meaning-to-the-lead-row" aria-hidden="true">#</a>Rev 22 — 2026-10-06 — F11-f adds the lead rule to the Timeline row and the nurture meaning to the Lead row</h3> <ul> <li><strong>Changed — cluster 8, the Timeline row:</strong> records the lead rule — one row per matched lead (<code>source_type = 'lead'</code>, <code>kind = 'lead'</code>, dated the lead’s <code>received_at</code>), its summary <em>Inquiry received (<lead source>) — <status></em> rewritten when the lead’s status or <code>leadSource</code> changes, the row moved or removed with the match, shown to every reader of the account, and counted as contact for <code>lastContactAt</code> and dormancy (F11-f spec FR-T1–T5, FR-T4a).</li> <li><strong>Changed — cluster 2, the Lead row:</strong> <em>Archive / nurture</em> is the <code>archived</code> status, with no separate nurture status, and restore returns <code>archived</code> to <code>new</code> (F11-f spec decisions 2 and 3).</li> <li><strong>Why:</strong> the F11-f spec (approved 2026-10-06) is the first writer of <code>timeline_event</code> and the first feature to change a lead’s status; its FR-H1 records both rules here.</li> <li><strong>Impact:</strong> no table, column or relationship changes. F1-c renders the lead rows and owns the final dormancy rule (F11-f Q-3). The Note and Tag rows mark F11-f’s lead routes as built when its backend PR merges.</li> <li><strong>Approved by:</strong> <em>(owed — the approval of the F11-f spec PR carrying this revision)</em></li> </ul> <h3 id="rev-23-2026-10-06-f11-f-builds-the-lead-notes-and-lead-tag-routes"><a class="anchor" href="#rev-23-2026-10-06-f11-f-builds-the-lead-notes-and-lead-tag-routes" aria-hidden="true">#</a>Rev 23 — 2026-10-06 — F11-f builds the lead notes and lead tag routes</h3> <ul> <li><strong>Changed — the Note row:</strong> the lead notes API is built by F11-f — <code>GET</code> and <code>POST /api/v1/leads/{id}/notes</code>, list and add (F11-f spec FR-N1, FR-N2), in the <code>lead</code> package over its own <code>LeadNoteRepository</code>. Note editing and deletion, and the account and contact notes API, stay F1-e’s.</li> <li><strong>Changed — the Tag row:</strong> F11-f builds lead tag attach and detach (<code>PUT</code> / <code>DELETE /api/v1/leads/{id}/tags/{tagId}</code>) and lead tag create (<code>POST /api/v1/tags</code> with <code>entityType: lead</code>, a <code>409</code> naming the existing tag with <code>existingTagId</code> and <code>existingTagActive</code>). The create learns its key from <code>tag.TagWriteAccess</code>, a contribution point the owning feature fills (<code>lead.manage</code> from <code>lead</code>), so <code>tag</code> imports nothing from <code>lead</code> (F11-f spec FR-G3, NFR-4); F1-e adds its own contributions for account and contact tags.</li> <li><strong>Why:</strong> F11-f spec FR-H1 — the Note and Tag rows mark F11-f’s lead routes as built with its backend PR (F11-f WI-1.2).</li> <li><strong>Impact:</strong> no table, column or relationship changes; only the build status and owner columns of the two rows.</li> <li><strong>Approved by:</strong> <em>(owed — the approval of the F11-f WI-1.2 harness PR carrying this revision)</em></li> </ul> <h3 id="rev-24-2026-10-10-f1-e-specifies-the-account-and-contact-notes-and-tags"><a class="anchor" href="#rev-24-2026-10-10-f1-e-specifies-the-account-and-contact-notes-and-tags" aria-hidden="true">#</a>Rev 24 — 2026-10-10 — F1-e specifies the account and contact notes and tags</h3> <ul> <li><strong>Changed — the Note row:</strong> F1-e specifies the account and contact notes API (list, add, edit, delete), the editing rule for every record type (any holder of the parent’s <code>manage</code> who reaches it) and deletion by marking: <code>note</code> gains <code>deleted_at</code> and <code>deleted_by</code> (F1-e spec FR-N1–N5; PRD Rev 59).</li> <li><strong>Changed — the Timeline row:</strong> the note rule — one row per account note, its summary the body cut to 200 characters, rewritten on edit and deleted with the note; contact notes write none (F1-e spec FR-N6, FR-N7).</li> <li><strong>Changed — the Tag row:</strong> “renaming or deleting a name” becomes “renaming or retiring”: a tag is retired, never deleted. F1-e specifies the account and contact tag routes, the two <code>TagWriteAccess</code> contributions, <code>PATCH /api/v1/tags/{id}</code> under <code>settings.manage</code>, <code>GET /api/v1/tags/{id}</code> and the list’s <code>active</code> filter (F1-e spec FR-G1–G7).</li> <li><strong>Why:</strong> F1-e spec FR-H1, in the spec PR, so the map and the spec agree before the plan is written.</li> <li><strong>Impact:</strong> one schema change, two nullable columns on <code>note</code> (built by F1-e’s backend work item, an ASK FIRST item in its plan); the build status of the three rows moves when that work merges.</li> <li><strong>Approved by:</strong> Biseni Perera, at the F1-e spec approval (2026-10-11)</li> </ul> <h3 id="rev-25-2026-10-11-the-search-row-is-withdrawn"><a class="anchor" href="#rev-25-2026-10-11-the-search-row-is-withdrawn" aria-hidden="true">#</a>Rev 25 — 2026-10-11 — the Search row is withdrawn</h3> <ul> <li><strong>Changed — the Search row:</strong> the per-entity <code>tsvector</code> design is withdrawn; nothing was built.</li> <li><strong>Why:</strong> the lead dropped global search (F31) on 2026-10-11 (PRD Rev 60), which closes AD-O-2.</li> <li><strong>Impact:</strong> none on the schema; each list endpoint keeps its own <code>q</code> filter.</li> <li><strong>Approved by:</strong> Tharinda (lead, 2026-10-11)</li> </ul> <h3 id="rev-26-2026-10-11-capture-app-storage-and-pointers-to-dropped-features"><a class="anchor" href="#rev-26-2026-10-11-capture-app-storage-and-pointers-to-dropped-features" aria-hidden="true">#</a>Rev 26 — 2026-10-11 — capture-app storage, and pointers to dropped features</h3> <ul> <li><strong>Changed — the capture-app line:</strong> the PWA keeps on the phone any capture not yet sent (F36-a’s keep-and-retry), not an offline queue (F36-e dropped, PRD Rev 64).</li> <li><strong>Changed — the Activity and Prompts rows:</strong> they no longer name F16 (dropped, PRD Rev 61) as a consumer.</li> <li><strong>Impact:</strong> none on the schema.</li> <li><strong>Approved by:</strong> Tharinda (lead, 2026-10-11)</li> </ul> <h3 id="rev-27-2026-10-12-the-email_send-row"><a class="anchor" href="#rev-27-2026-10-12-the-email_send-row" aria-hidden="true">#</a>Rev 27 — 2026-10-12 — the <code>email_send</code> row</h3> <ul> <li><strong>Added — §7 <code>Email send</code> (<code>email_send</code>), proposed by the F20-c spec (FR-R1):</strong> one row per email sent from the CRM, holding its idempotency key, outcome and origin record but none of its content; the Sent Items copy stays the one <code>email_message</code> row, matched to it by internet message id (F20-c FR-R2).</li> <li><strong>Impact:</strong> one new table, by F20-c’s migration; <code>email_message</code> is unchanged (F20-c copies the AI flags into its existing columns).</li> <li><strong>Approved by:</strong> with the F20-c spec’s approval (the row moves to <em>confirmed</em> then).</li> </ul> <h3 id="rev-28-2026-10-13-the-files-an-email-carries"><a class="anchor" href="#rev-28-2026-10-13-the-files-an-email-carries" aria-hidden="true">#</a>Rev 28 — 2026-10-13 — the files an email carries</h3> <ul> <li><strong>Added — §7 <code>Email send file</code> (<code>email_send_file</code>), by the F20-h spec (FR-R1):</strong> one row per new file a send carried, with its name, type and size and a link to the uploaded <code>attachment</code>; no file content.</li> <li><strong>Changed — §7 <code>Email send</code>:</strong> F20-h adds the send’s stored deadline and the count of forwarded originals removed (F20-h FR-R1, FR-S4).</li> <li><strong>Changed — §10 <code>File</code>:</strong> a new owner type, <code>email_upload</code>, owned by the uploading user, and <code>deleted_at</code>; a deleted file keeps its row and its S3 version behind a delete marker (F20-h decision 3).</li> <li><strong>Impact:</strong> one new table and two <code>email_send</code> columns, and one nullable <code>attachment</code> column, by F20-h’s migration.</li> <li><strong>Approved by:</strong> Dinil Gamage, with the F20-h spec’s approval (2026-10-13).</li> </ul> <h3 id="rev-29-2026-10-13-f3-a-confirms-activity-and-activity-type"><a class="anchor" href="#rev-29-2026-10-13-f3-a-confirms-activity-and-activity-type" aria-hidden="true">#</a>Rev 29 — 2026-10-13 — F3-a confirms Activity and Activity type</h3> <p><em>Rev 28 is claimed by the open branch <code>feature/F20-h-spec</code>. If another branch merges a Rev 29 first, this entry takes the next free number (an unmerged claim yields).</em></p> <ul> <li><strong>Changed — cluster 8, the Activity row:</strong> records the F3-a shape — exactly one linked record, an account or a lead, under the named <code>CHECK</code> <code>activity_has_one_record</code> (was “at least one” of account, deal or lead); no deal column until F3-b adds <code>deal_id</code> and widens the check; the owner becomes an <strong>assignee</strong>, an active user who holds the record’s <code>manage</code> key and reaches it and who gives no reach of its own; a Colombo <code>due_date</code> with an optional <code>due_time</code>; one <code>notes</code> field; <code>done_at</code> / <code>done_by</code>; soft delete with <code>deleted_at</code> / <code>deleted_by</code>; reach follows the linked record (F3-a spec FR-S2, FR-S3, FR-P1, decisions 3, 6 and 8).</li> <li><strong>Changed — cluster 8, the Activity type row:</strong> six seeded built-in rows, a <code>built_in</code> flag, custom rows added by F3-b (F3-a spec FR-S1).</li> <li><strong>Changed — cluster 8, the Timeline row:</strong> the activity rule — one row per completed account follow-up, its summary <em><Type> done: <title></em>, removed on reopen or delete, rewritten on a type or title edit of a done follow-up; none for an open or a lead follow-up; it counts as contact (F3-a spec FR-T1–T4).</li> <li><strong>Changed — cluster 1, the key edges:</strong> <code>activity</code> leaves the <code>owns</code> edge and gets its own <code>is assigned</code> edge, because a follow-up is not an owned record in the AD #35 sense (F3-a decision 8).</li> <li><strong>Why:</strong> F3-a spec FR-H1, in the spec PR, so the map and the spec agree before the plan is written.</li> <li><strong>Impact:</strong> two new tables, by F3-a’s migration (an ASK FIRST item in its plan). The Record share row’s “exactly one … the same shape as <code>activity</code>” now matches the Activity row. The PRD’s Activity and User rows still read “owner” until F3-a’s shipping harness PR records the PRD revision (F3-a FR-H1).</li> <li><strong>Approved by:</strong> Nanndish Satgunarajah, at the F3-a spec approval (2026-10-13)</li> </ul> <h3 id="rev-30-2026-10-15-f20-d-confirms-email-template"><a class="anchor" href="#rev-30-2026-10-15-f20-d-confirms-email-template" aria-hidden="true">#</a>Rev 30 — 2026-10-15 — F20-d confirms Email template</h3> <ul> <li><strong>Changed — §7, the Email template row:</strong> records the F20-d shape — shared or personal templates, a personal one owned by one user, an optional unique <code>purpose</code> for the weekly-prices template, merge-field tokens in the subject and body, deletion by marking (F20-d spec FR-T1, decisions 2, 3 and 5). It moves from <em>designed (PRD)</em> to <em>confirmed</em>, and its owner from F20 to F20-d.</li> <li><strong>Why:</strong> F20-d spec FR-D1, in the spec PR, so the map and the spec agree before the plan is written.</li> <li><strong>Impact:</strong> one new table and its seeded starter rows, by F20-d’s migrations. The sequence-step row’s <code>N:1 template</code> now points at a row that is never removed, so a step keeps reading a template that was deleted after the step was written.</li> <li><strong>Approved by:</strong> Dinil Gamage, at the F20-d spec approval (2026-10-15)</li> </ul> <h3 id="rev-31-2026-10-16-f26-d-proposes-price-email-and-the-price-email-timeline-rule"><a class="anchor" href="#rev-31-2026-10-16-f26-d-proposes-price-email-and-the-price-email-timeline-rule" aria-hidden="true">#</a>Rev 31 — 2026-10-16 — F26-d proposes Price email and the price-email timeline rule</h3> <ul> <li><strong>Added — §7, the Price email row (<code>price_email</code>, <code>price_email_price</code>):</strong> one insert-only record per weekly price email, tied one-to-one to the F20-c send that carried it, with the prices it listed (F26-d spec FR-R1, decision 5).</li> <li><strong>Changed — §7, the Timeline row:</strong> gains the price-email rule — one <code>email</code> row per record, keyed on its F20-c send <code>('email_send', <send id>, 'email')</code> (F26-d spec FR-R3, decision 6).</li> <li><strong>Why:</strong> F26-d spec FR-D1, in the spec PR, so the map and the spec agree before the plan is written. F20-c keeps no subject or body on <code>email_send</code>, so only a record of F26-d’s own says a send was a price email. Keying the row on the send lets F20-f find it through <code>timeline</code> without depending on F26-d’s package.</li> <li><strong>Impact:</strong> two new tables by one F26-d migration. F20-f, when specified, keys CRM-sent messages’ rows on the send and writes none where one exists (its stub carries the line).</li> <li><strong>Approved by:</strong> Dinil Gamage, at the F26-d spec approval (2026-10-16)</li> </ul> <h3 id="rev-32-2026-10-19-f11-d-keeps-its-ai-outputs-in-lead_triage-not-on-lead"><a class="anchor" href="#rev-32-2026-10-19-f11-d-keeps-its-ai-outputs-in-lead_triage-not-on-lead" aria-hidden="true">#</a>Rev 32 — 2026-10-19 — F11-d keeps its AI outputs in <code>lead_triage</code>, not on <code>lead</code></h3> <ul> <li><strong>Changed — cluster 2, the Lead row:</strong> F11-d’s summary, spam / duplicate tag and proposed customer match live in a table of their own, <code>lead_triage</code> (one row per lead), not as columns on <code>lead</code> (F11-d spec FR-S1, decision 5).</li> <li><strong>Changed — the AI suggestion row:</strong> notes that F11-d, the first background AI feature, did not build <code>ai_suggestion</code> (F11-d decision 11); the row stays proposed.</li> <li><strong>Why:</strong> a background job writing to <code>lead</code> would increment its <code>version</code> and turn a rep’s open edit into <code>409 STALE_VERSION</code> (F11-a FR-A3). A table of its own keeps the job’s writes off the lead. The tag and the proposed match each have a typed home and a typed action, so a generic queue adds nothing.</li> <li><strong>Impact:</strong> one new table by an F11-d migration; <code>forge-et-be/docs/data-model.md</code>’s sentence that the F11 AI outputs are <code>lead</code> columns is revised in F11-d’s backend PR (FR-H1). F11-g, when specified, decides its own storage with the same reason in view.</li> <li><strong>Approved by:</strong> Dinil Gamage, at the F11-d spec approval (2026-10-19)</li> </ul> <h3 id="rev-33-2026-10-21-f11-c-keeps-its-research-snapshot-in-lead_research"><a class="anchor" href="#rev-33-2026-10-21-f11-c-keeps-its-research-snapshot-in-lead_research" aria-hidden="true">#</a>Rev 33 — 2026-10-21 — F11-c keeps its research snapshot in <code>lead_research</code></h3> <ul> <li><strong>Changed — cluster 2, the Lead row:</strong> F11-c’s research snapshot lives in <code>lead_research</code> (one row per lead: the state, the company and person findings as JSON, each finding with its source URL), with <code>search_call</code> (one row per search, never the query text) and <code>search_provider_pause</code> (one row) beside it (F11-c spec FR-S1, FR-L2, FR-L4, decision 11).</li> <li><strong>Why:</strong> the same reason as Rev 32 — a background job writing to <code>lead</code> would move its <code>version</code> and break a rep’s open edit; and the search record holds no personal data, because a query can carry a person’s name.</li> <li><strong>Impact:</strong> three new tables by an F11-c migration; <code>forge-et-be/docs/data-model.md</code> gains them in F11-c’s backend PR (FR-H1).</li> <li><strong>Approved by:</strong> Dinil Gamage, at the F11-c spec approval (2026-10-21)</li> </ul> <h3 id="rev-34-2026-10-26-a-contacts-other-email-addresses-a-leads-email-on-conversion"><a class="anchor" href="#rev-34-2026-10-26-a-contacts-other-email-addresses-a-leads-email-on-conversion" aria-hidden="true">#</a>Rev 34 — 2026-10-26 — a contact’s other email addresses; a lead’s email on conversion</h3> <ul> <li><strong>Changed — cluster 2, the Contact row:</strong> a contact can hold several email addresses — <code>contact.email</code> stays the main one, and the others go in a new child table, one row per address, whose shape F20-l’s spec settles; matching uses every address.</li> <li><strong>Changed — D-5:</strong> conversion also links the lead’s emails to the account, contact and deal it sets, and a converted lead stops being a target of automatic linking.</li> <li><strong>Why:</strong> the lead’s decisions of 2026-10-26 (<code>.forge/design/architecture.md</code> § Mailbox integration, Rev 74): 246 people in the Pipedrive export have several work addresses; a converted lead’s history belongs on the records where the work continues.</li> <li><strong>Impact:</strong> one new table by an F20-l migration (F20-l was split from F20-f the same day, <code>project-prd-history.md</code> Rev 77), and the migration mapping change (F4-a Rev 10, F4-d Rev 1, F1-a Rev 10); F11-e’s conversion writes the email links (Phase 2).</li> <li><strong>Approved by:</strong> Tharinda (lead), 2026-10-26 (in session)</li> </ul> <h3 id="rev-35-2026-10-26-status-corrections-for-tables-already-on-main"><a class="anchor" href="#rev-35-2026-10-26-status-corrections-for-tables-already-on-main" aria-hidden="true">#</a>Rev 35 — 2026-10-26 — status corrections for tables already on <code>main</code></h3> <ul> <li><strong>Changed — the Status column of five rows:</strong> Session (<code>V7__spring_session.sql</code>), Contact and Contact → Account (<code>V19__contact.sql</code>), Certification (<code>V14__certification.sql</code>) and Price email (<code>V48__price_email.sql</code>) read <code>designed</code> or <code>proposed</code>, but each table’s migration is on <code>forge-et-be</code> <code>main</code>, which this map’s legend calls <strong>shipped</strong>. No edge, cardinality or note changes.</li> <li><strong>Not changed — the File row:</strong> the shipped table is <code>attachment</code> (FS-11, <code>V9__attachment.sql</code>, one polymorphic owner and no link tables), not the <code>file</code> table with per-target link tables the row describes, so the row needs its design notes reconciled against the shipped table rather than a status change.</li> <li><strong>Why:</strong> the harness review of 2026-10-26 found the five rows behind <code>main</code>.</li> <li><strong>Impact:</strong> none on any spec; the rows now match the migrations.</li> <li><strong>Approved by:</strong> Tharinda (lead), 2026-10-26, harness review.</li> </ul> <h3 id="rev-36-2026-10-26-accessmanage-folded-into-settingsmanage"><a class="anchor" href="#rev-36-2026-10-26-accessmanage-folded-into-settingsmanage" aria-hidden="true">#</a>Rev 36 — 2026-10-26 — <code>access.manage</code> folded into <code>settings.manage</code></h3> <ul> <li><strong>Changed — cluster 1, the User, Role and Permission / grant rows:</strong> <code>settings.manage</code> is the one key for all configuration and all user, role and hierarchy administration, and <code>access.manage</code> leaves the catalog. The seeded IT Admin role holds <code>settings.manage</code>, a user is pre-created by its holder, and the last-admin invariant holds on it. No table, edge or cardinality changes: the migration <code>forge-et-be</code> <code>V54</code> rewrites <code>role_grant</code> rows from <code>access.manage</code> to <code>settings.manage</code>, each change audited.</li> <li><strong>Why:</strong> AD #34 refined by Nanndish on 2026-10-26 (<code>.claude/CLAUDE.md</code>; <code>engagement-log.md § Architecture Decisions — full rationale archive</code>; PRD Rev 79; FS-6 spec Rev 19).</li> <li><strong>Impact:</strong> FS-6 Appendix A; the F5-c, F5-d, F5-e, F5-k specs’ revisions of the same date.</li> <li><strong>Approved by:</strong> Nanndish, 2026-10-26; the AD #34 refinement signed off by Tharinda, 2026-10-27.</li> </ul> <h3 id="rev-37-2026-10-28-f20-l-settles-the-contacts-other-email-addresses"><a class="anchor" href="#rev-37-2026-10-28-f20-l-settles-the-contacts-other-email-addresses" aria-hidden="true">#</a>Rev 37 — 2026-10-28 — F20-l settles the contact’s other email addresses</h3> <ul> <li><strong>Changed — cluster 2, the Contact row:</strong> Rev 34’s proposed child table is confirmed as <code>contact_email</code> with the shape F20-l FR-1 states, matched with <code>contact.email</code> on one address key (F20-l FR-8).</li> <li><strong>Why:</strong> F20-l spec approval, 2026-10-28.</li> <li><strong>Impact:</strong> one Flyway migration in F20-l’s backend work.</li> <li><strong>Approved by:</strong> Tharinda (lead), 2026-10-28, with the F20-l spec.</li> </ul> <h3 id="rev-38-2026-11-05-f11-gs-ranking-table-hot-cold-not-stored"><a class="anchor" href="#rev-38-2026-11-05-f11-gs-ranking-table-hot-cold-not-stored" aria-hidden="true">#</a>Rev 38 — 2026-11-05 — F11-g’s ranking table; hot / cold not stored</h3> <ul> <li><strong>Changed — cluster 9, the Lead row:</strong> the AI priority, confidence, reason and next action are in <code>lead_ranking</code>, one row per lead, written only by F11-g’s background job, not <code>lead</code> columns; the hot / cold status is computed from the buyer’s last message when read and has no column.</li> <li><strong>Why:</strong> F11-g spec approval, 2026-11-05 (decisions 6 and 8): a background write to <code>lead</code> would move its <code>version</code> and refuse a rep’s open edit, as for <code>lead_triage</code>; hot / cold is a date check that a stored value would let go stale.</li> <li><strong>Impact:</strong> one Flyway migration in F11-g’s backend work.</li> <li><strong>Approved by:</strong> Dinil Gamage, 2026-11-05, with the F11-g spec.</li> </ul> <h3 id="rev-39-2026-11-06-f33-split-leads-take-attachments"><a class="anchor" href="#rev-39-2026-11-06-f33-split-leads-take-attachments" aria-hidden="true">#</a>Rev 39 — 2026-11-06 — F33 split; leads take attachments</h3> <ul> <li><strong>Changed — the File row and D-6:</strong> the attaching features are F33-a (accounts, contacts, leads) and F33-b (deals, quotes, samples, product briefs); D-6’s target list gains leads, with one link table per target as before.</li> <li><strong>Why:</strong> Gate 3 Run 4 (reslice, 2026-11-06, lead: Tharinda; <code>.forge/project-prd-history.md</code> Rev 84) cut F33 by record type so the attachment store starts in Phase 1 on the records that exist; PRD §F33 now names leads.</li> <li><strong>Impact:</strong> F33-a builds the store, its first link tables and the panel; F33-b adds link tables. No change to the <code>file</code> row’s columns.</li> <li><strong>Approved by:</strong> Tharinda (lead), 2026-11-06.</li> </ul> <h3 id="rev-40-2026-11-06-f4-b-adds-source_owner_name-to-lead"><a class="anchor" href="#rev-40-2026-11-06-f4-b-adds-source_owner_name-to-lead" aria-hidden="true">#</a>Rev 40 — 2026-11-06 — F4-b adds <code>source_owner_name</code> to <code>lead</code></h3> <ul> <li><strong>Changed — cluster 10, the External ref (migration identity) row, and cluster 2, the Lead row:</strong> the migration-identity row is settled on <code>lead</code> by F4-b (spec FR-9), and its note says <code>lead</code> carries <code>source_owner_name</code> as <code>account</code> does, written on a lead’s create and update; the Lead row lists the column.</li> <li><strong>Why:</strong> F4-a FR-M5 — the feature that adds the column to a table revises this row in the same change; F4-b FR-22 names the row for the harness PR that ships the feature.</li> <li><strong>Impact:</strong> one Flyway migration in F4-b’s backend work (F4-b-WI-1.1), with <code>forge-et-be</code> <code>docs/data-model.md</code> changed in the same wave. No edge or cardinality changes.</li> <li><strong>Approved by:</strong> Dinil Gamage, 2026-11-06, with the F4-b spec.</li> </ul> <h3 id="rev-41-2026-11-06-f33-a-confirms-the-file-row-and-revises-d-6"><a class="anchor" href="#rev-41-2026-11-06-f33-a-confirms-the-file-row-and-revises-d-6" aria-hidden="true">#</a>Rev 41 — 2026-11-06 — F33-a confirms the File row and revises D-6</h3> <ul> <li><strong>Changed — cluster 10, the File row:</strong> the table is <code>attachment</code>, shipped by FS-11 (<code>V9__attachment.sql</code>), not a <code>file</code> table; a file names its one record by <code>owner_type</code> and <code>owner_id</code>, with no link tables; the owner types are listed, <code>contact</code> added by F33-a. The status moves from <em>designed</em> to <em>shipped</em>, the reconciliation Rev 35 left open.</li> <li><strong>Changed — D-6:</strong> revised to the adopted shape, its original text kept as the rationale that was revised, as D-7 keeps its own. Rev 39’s “one link table per target” no longer holds.</li> <li><strong>Changed — the spine:</strong> <code>file (D-6)</code> reads <code>attachment (D-6)</code>.</li> <li><strong>Changed — D-8:</strong> <code>attachment</code> is named as the one domain table that references its record loosely, with the reason (D-6, revised).</li> <li><strong>Why:</strong> F33-a spec decision 1 (Dinil, 2026-11-06): the owner columns, the visibility routing and two owner types were already on <code>main</code>, so link tables would state each file’s owner twice.</li> <li><strong>Impact:</strong> no migration — F33-a adds no table or column (spec § Constraints and Dependencies). F33-b adds owner types and upload policies, not link tables; its stub is reworded in F33-a’s harness PR.</li> <li><strong>Approved by:</strong> Dinil Gamage, 2026-11-06, with the F33-a spec.</li> </ul> <h3 id="rev-42-2026-11-09-f20-g-adds-email-tracking-and-scheduled-email"><a class="anchor" href="#rev-42-2026-11-09-f20-g-adds-email-tracking-and-scheduled-email" aria-hidden="true">#</a>Rev 42 — 2026-11-09 — F20-g adds email tracking and scheduled email</h3> <ul> <li><strong>Added — §7:</strong> <code>email_tracking</code>, <code>email_tracked_link</code> and <code>scheduled_email</code>, owner F20-g.</li> <li><strong>Changed — §7, the Email send row:</strong> <code>email_send</code> gains <code>tracked</code>.</li> <li><strong>Why:</strong> the F20-g spec (Dinil, 2026-11-09): tracking needs a token and counts per send and the original address of each rewritten link (FR-T2, FR-T3, FR-T5); a scheduled email must hold its content until it is sent, which <code>email_send</code> deliberately does not (F20-c decision 5; F20-g decision 5).</li> <li><strong>Impact:</strong> new tables and one column by Flyway migrations, named in the F20-g plan.</li> <li><strong>Approved by:</strong> Dinil Gamage, 2026-11-09, with the F20-g spec.</li> </ul> <h3 id="rev-44-2026-11-12-f36-a-adds-the-captured-lead-the-capture-campaign-and-the-exhibitor"><a class="anchor" href="#rev-44-2026-11-12-f36-a-adds-the-captured-lead-the-capture-campaign-and-the-exhibitor" aria-hidden="true">#</a>Rev 44 — 2026-11-12 — F36-a adds the captured lead, the capture campaign and the exhibitor</h3> <ul> <li><strong>Changed — cluster 10, the capture-app paragraph:</strong> a capture is no longer a lead when it arrives. The paragraph names three entities of F36-a’s, with a row each — <strong>Captured lead</strong> (<code>captured_lead</code>), <strong>Capture campaign</strong> (<code>capture_campaign</code>) and <strong>Exhibitor</strong> (<code>exhibitor</code>) — and their edges: captured lead → lead on conversion, campaign → captured leads, campaign → exhibitors, and the users who capture and decide. It replaces the paragraph that made a capture submission a lead with the capture app’s submission id as its replay identity and added no entity: a converted capture’s replay identity is now the captured lead’s id.</li> <li><strong>Why:</strong> PRD Revs 95, 96 and 97 (2026-11-12): captured leads wait in the capture app until a person converts or rejects them, and the reps plan each show in the app; the F36-a spec FR-L1, FR-P1, FR-P3 and FR-D1.</li> <li><strong>Impact:</strong> three tables by Flyway migrations in F36-a’s waves 2 and 3, named in their plans; their rows stay <code>designed</code> until those migrations are on <code>main</code>. F11-a’s spec records the change to a converted capture’s owner and <code>sourceRef</code> (its Rev 6).</li> <li><strong>Approved by:</strong> Nanndish, 2026-11-12, with the F36-a spec (approved by Claude under his overnight delegation, for his review).</li> </ul> <h3 id="rev-43-2026-11-11-lead-notes-adopt-f1-es-editing-and-deletion-rule"><a class="anchor" href="#rev-43-2026-11-11-lead-notes-adopt-f1-es-editing-and-deletion-rule" aria-hidden="true">#</a>Rev 43 — 2026-11-11 — lead notes adopt F1-e’s editing and deletion rule</h3> <ul> <li><strong>Changed — cluster 8, the Note row:</strong> the lead notes API gains <code>PATCH</code> and <code>DELETE /api/v1/leads/{id}/notes/{noteId}</code> (F11-f spec FR-N4, Rev 13): any holder of <code>lead.manage</code> who reaches the lead may edit or delete any note on it, with optimistic locking on <code>version</code>; a deleted note is marked with <code>deleted_at</code> and <code>deleted_by</code>, never removed, and left out of the list; each note carries <code>editedAt</code>, <code>editedBy</code> and <code>version</code>. The row no longer says lead notes are list and add only, and its pointer to the follow-up in <code>.forge/owed.md</code> is replaced by F11-f Rev 13.</li> <li><strong>Why:</strong> the CRM UI polish tracker, item i13 (Nanndish Satgunarajah, 2026-11-11): lead notes were the only notes in the CRM that could not be corrected or removed, and F1-e had settled the rule for every record type.</li> <li><strong>Impact:</strong> no migration — <code>note</code> already has <code>version</code>, <code>deleted_at</code> and <code>deleted_by</code> (F1-e). One new audit code, <code>lead.note_edited</code>, in <code>forge-et-be</code> <code>docs/audit/README.md</code>. No edge or cardinality changes.</li> <li><strong>Approved by:</strong> Nanndish Satgunarajah, 2026-11-11, with F11-f Rev 13.</li> </ul> <h3 id="rev-45-2026-11-15-f37-a-adds-the-price-broadcast"><a class="anchor" href="#rev-45-2026-11-15-f37-a-adds-the-price-broadcast" aria-hidden="true">#</a>Rev 45 — 2026-11-15 — F37-a adds the price broadcast</h3> <ul> <li><strong>Added — §7:</strong> the Price broadcast row (<code>price_broadcast</code>, <code>price_broadcast_item</code>, <code>price_broadcast_item_price</code>), owner F37-a.</li> <li><strong>Why:</strong> the F37-a spec (Tharinda, 2026-11-15, FR-B1, FR-S2, FR-S3): a batch of weekly price emails is confirmed once and sent by a sweep over the following minutes, so it needs a row per customer to claim, settle and report; and the addressee and listed prices are stored before each send so the price email can be recorded after it, without storing the email’s content.</li> <li><strong>Impact:</strong> three tables by Flyway migrations, named in the F37-a plan; the row stays <code>confirmed</code> until they are on <code>main</code>. Each item sent writes F26-d’s <code>price_email</code> rows; the Price email row does not change.</li> <li><strong>Approved by:</strong> Tharinda Rajapaksha, 2026-11-15, with the F37-a spec.</li> </ul> <h3 id="rev-46-2026-11-13-f36-c-adds-the-capture-research-table-and-the-two-notification-tables"><a class="anchor" href="#rev-46-2026-11-13-f36-c-adds-the-capture-research-table-and-the-two-notification-tables" aria-hidden="true">#</a>Rev 46 — 2026-11-13 — F36-c adds the capture research table and the two notification tables</h3> <ul> <li><strong>Changed — cluster 10, the capture-app table:</strong> three rows — <strong>Capture research</strong> (<code>capture_research</code>), <strong>Capture notification</strong> (<code>capture_notification</code>) and <strong>Capture notification recipient</strong> (<code>capture_notification_recipient</code>) — and a key-edges paragraph for them. The <em>Captured lead</em> and <em>Exhibitor</em> rows no longer say F36-c adds research and score columns to them: F36-c adds nothing to <code>captured_lead</code> or <code>exhibitor</code>, and keeps each one’s research and ranking in its <code>capture_research</code> row.</li> <li><strong>Why:</strong> the F36-c spec FR-ST1, FR-ST2 and decisions D-2, D-10, D-11 and D-19 (approved 2026-11-13): a background write to the captured lead or the exhibitor would move its <code>version</code> and refuse a rep’s open edit, as for <code>lead_research</code> (Rev 33); notifications are read per user.</li> <li><strong>Impact:</strong> Flyway migrations in F36-c’s backend work — <code>capture_research</code> in its wave 1 (F36-c-WI-1.1), the two notification tables in its wave 2 (F36-c-WI-2.1); the rows stay <code>designed</code> until those migrations are on <code>main</code> (<code>.forge/owed.md</code>). The copy of a captured lead’s research into the new lead’s <code>lead_research</code> row at conversion (FR-CV1) adds no edge; F11-c’s spec records it (its Rev 8).</li> <li><strong>Approved by:</strong> Nanndish, 2026-11-13, with the F36-c spec (approved by Claude under his overnight delegation of 2026-11-12, and confirmed by him on 2026-11-13, F36-c Rev 1).</li> </ul> <h3 id="rev-47-2026-11-18-four-capture-app-tables-marked-shipped"><a class="anchor" href="#rev-47-2026-11-18-four-capture-app-tables-marked-shipped" aria-hidden="true">#</a>Rev 47 — 2026-11-18 — four capture-app tables marked shipped</h3> <ul> <li><strong>Changed — cluster 10:</strong> <em>Captured lead</em>, <em>Capture campaign</em>, <em>Exhibitor</em> and <em>Capture research</em> move from <code>designed</code> to <code>shipped</code>, each citing its migration on <code>forge-et-be</code> <code>main</code>: <code>V71__captured_lead.sql</code>, <code>V73__capture_plan.sql</code> (the campaign, the exhibitor and <code>captured_lead.campaign_id</code>) and <code>V76__capture_research.sql</code>. <em>Capture notification</em> and <em>Capture notification recipient</em> stay <code>designed</code> until F36-c wave 2’s migration is on <code>main</code>.</li> <li><strong>Why:</strong> the <code>owed.md</code> rows “Move F36-a’s entity-map rows to shipped” and “Close F36-c’s wave-2 marks…”, which ask for each row to move once its migration is on <code>main</code> (Rev 44, Rev 46).</li> <li><strong>Impact:</strong> none; a record of what is built.</li> <li><strong>Approved by:</strong> Tharinda (lead), 2026-11-18.</li> </ul> <h3 id="rev-48-2026-11-19-f37-b-adds-the-bulk-email-and-the-suppression-list"><a class="anchor" href="#rev-48-2026-11-19-f37-b-adds-the-bulk-email-and-the-suppression-list" aria-hidden="true">#</a>Rev 48 — 2026-11-19 — F37-b adds the bulk email and the suppression list</h3> <ul> <li><strong>Added — §7:</strong> the Bulk email row (<code>bulk_email</code>, <code>bulk_email_item</code>) and the Bulk email suppression row (<code>bulk_email_suppression</code>), owner F37-b.</li> <li><strong>Why:</strong> the F37-b spec (Tharinda, 2026-11-19, FR-B1, FR-U1): a bulk send is confirmed once and sent by a sweep over the following minutes, as F37-a’s batch is, so it needs a row per contact to claim, record and summarise; OQ-62’s decision (PRD Rev 103) keeps unsubscribed and bounced addresses out of later sends, which needs a list keyed by address.</li> <li><strong>Impact:</strong> three tables by a Flyway migration named in the F37-b plan; both rows are <code>confirmed</code> with the spec’s approval (2026-11-19) and move to <code>shipped</code> once the migration is on <code>main</code>. Each item sent writes one F20-c <code>email_send</code>, whose row does not change.</li> <li><strong>Approved by:</strong> Tharinda Rajapaksha, 2026-11-19, with the F37-b spec.</li> </ul> <h3 id="rev-49-2026-11-18-f36-c-keeps-the-campaign-focus-and-carries-the-captures-ranking-into-the-crm"><a class="anchor" href="#rev-49-2026-11-18-f36-c-keeps-the-campaign-focus-and-carries-the-captures-ranking-into-the-crm" aria-hidden="true">#</a>Rev 49 — 2026-11-18 — F36-c keeps the campaign focus and carries the capture’s ranking into the CRM</h3> <ul> <li><strong>Changed — cluster 10:</strong> the <em>Capture campaign</em> row gains the campaign’s optional focus (<code>capture_campaign.focus</code>, F36-c FR-FC1) and names F36-c beside F36-a; the <em>Capture research</em> row gains <code>ranking_focus</code>, the focus each ranking read (FR-ST1, FR-FC4); the F36-c key-edges paragraph’s conversion sentence, which said the capture’s tier, score and next action are not carried into the CRM, now says the ranking is copied into the new lead’s <code>lead_ranking</code> row with <code>origin = 'capture'</code>, the focus and the campaign’s name, and only the fit score stays on the captured lead (FR-CV1, FR-DC2).</li> <li><strong>Changed — cluster 9, the Lead row:</strong> <code>lead_ranking</code> is written by F11-g’s job and by the conversion’s copy, and keeps the focus a ranking read in <code>focus</code> and <code>focus_campaign_name</code> (F11-g FR-S1, FR-S4, FR-A9).</li> <li><strong>Why:</strong> the F36-c spec’s Rev 6 and the F11-g spec’s Rev 7 (approved 2026-11-18; PRD Rev 101, the lead’s decision of 2026-11-18): a converted captured lead arrives in the CRM with its ranking as its priority instead of being ranked a second time, and a campaign’s focus is kept with every ranking made for it (F36-c FR-DC2, F11-g FR-H4).</li> <li><strong>Impact:</strong> one Flyway migration in F36-c’s wave 3 (F36-c-WI-3.1): <code>capture_campaign.focus</code>, <code>capture_research.ranking_focus</code>, and <code>lead_ranking</code>’s <code>origin</code>, <code>focus</code> and <code>focus_campaign_name</code>, each with its named <code>CHECK</code>. No new table and no new edge. The rows keep their status; the new columns are on <code>main</code> when wave 3’s migration is.</li> <li><strong>Approved by:</strong> Dinil Gamage, 2026-11-18, with the F36-c spec’s Rev 6 and the F11-g spec’s Rev 7 (the lead’s decision of 2026-11-18, PRD Rev 101). <em>Numbered Rev 49 at the merge of 2026-11-19: F37-b’s Rev 48 merged to <code>main</code> first (id-numbering rule 5).</em></li> </ul> <h3 id="rev-50-2026-11-19-f20-f-confirms-the-email-links-refusals-and-received-files"><a class="anchor" href="#rev-50-2026-11-19-f20-f-confirms-the-email-links-refusals-and-received-files" aria-hidden="true">#</a>Rev 50 — 2026-11-19 — F20-f confirms the email links, refusals and received files</h3> <ul> <li><strong>Changed — §7, the Email message row:</strong> the auto-link edges are no longer nullable columns on <code>email_message</code> (Rev 11’s planned <code>ALTER TABLE</code>, struck in the row); each link is a row of a new <code>email_link</code> table, so one message can be linked to several records. <code>email_message</code> is unchanged, and a message is stored only while it has a link.</li> <li><strong>Added — §7:</strong> the <em>Email link</em> (<code>email_link</code>), <em>Email link refusal</em> (<code>email_link_refusal</code>) and <em>Email attachment</em> (<code>email_attachment</code>) rows, owner F20-f. A received file is an <code>email_attachment</code> row under the <code>email-attachments/</code> S3 prefix, not an FS-11 <code>attachment</code> row, so the <em>File</em> row is unchanged.</li> <li><strong>Why:</strong> the F20-f spec (approved 2026-11-19): D-1 (one email often concerns several records — a buyer and a colleague on CC, a lead on the same thread), D-7 (an unlinked message is not linked back to the same record, and unlinking the last link deletes the copy without trace) and D-6 (a received file must be deletable without trace and needs none of FS-11’s upload rules).</li> <li><strong>Impact:</strong> three new tables by an F20-f Flyway migration, named in the F20-f plan; the rows stay <code>confirmed</code> until they are on <code>main</code>. F20-f’s spec lists the new columns on <code>lead</code>, <code>mailbox_connection</code> and <code>email_send</code> (its § Constraints and Dependencies); they add no edge.</li> <li><strong>Approved by:</strong> Tharinda (lead), with the F20-f spec, 2026-11-19.</li> </ul> <h3 id="rev-51-2026-11-19-f44-adds-the-email-follow-up"><a class="anchor" href="#rev-51-2026-11-19-f44-adds-the-email-follow-up" aria-hidden="true">#</a>Rev 51 — 2026-11-19 — F44 adds the email follow-up</h3> <ul> <li><strong>Added — §7:</strong> the <em>Email follow-up</em> row (<code>email_follow_up</code>, <code>email_follow_up_email</code>, <code>email_follow_up_setting</code>), owner F44.</li> <li><strong>Changed — the Timeline row’s activity rule:</strong> a follow-up F44 raised writes no timeline row.</li> <li><strong>Why:</strong> the F44 spec (approved 2026-11-19): D-1 (the follow-up is an ordinary F3-a activity with a side row of its own), D-3 and D-5 (one follow-up per email, one open per conversation and mailbox), D-10 (closing one is not contact with the buyer).</li> <li><strong>Impact:</strong> three new tables by an F44 Flyway migration, named in the F44 plan; the row stays <code>confirmed</code> until it is on <code>main</code>.</li> <li><strong>Approved by:</strong> Tharinda (lead), with the F44 spec, 2026-11-19.</li> </ul> <h3 id="rev-52-2026-11-20-the-two-capture-notification-tables-marked-shipped"><a class="anchor" href="#rev-52-2026-11-20-the-two-capture-notification-tables-marked-shipped" aria-hidden="true">#</a>Rev 52 — 2026-11-20 — the two capture notification tables marked shipped</h3> <ul> <li><strong>Changed — cluster 10:</strong> <em>Capture notification</em> and <em>Capture notification recipient</em> move from <code>designed</code> to <code>shipped</code>, citing <code>V79__capture_notification.sql</code> on <code>forge-et-be</code> <code>main</code> (F36-c wave 2, forge-et-be#475). No edge, cardinality or note changes.</li> <li><strong>Why:</strong> Rev 47 left the two rows <code>designed</code> until F36-c wave 2’s migration was on <code>main</code>; the <code>owed.md</code> row “Close F36-c’s wave-2 marks…” asked for the move, due at F36-c’s Reflect.</li> <li><strong>Impact:</strong> none; a record of what is built.</li> <li><strong>Approved by:</strong> Dinil Gamage, 2026-11-20 — made by Claude at F36-c’s Reflect under his overnight delegation of 2026-11-19, then reviewed and approved by him; it carries out the condition Rev 47 (approved by Tharinda, the lead) set. <em>Rev 50 and Rev 51 (F20-f, F44) were on <code>main</code> first; Rev 52 is the next free number (id-numbering rule 5).</em></li> </ul> <h3 id="rev-53-2026-11-20-f11-j-adds-the-migrated-leads-email-summary"><a class="anchor" href="#rev-53-2026-11-20-f11-j-adds-the-migrated-leads-email-summary" aria-hidden="true">#</a>Rev 53 — 2026-11-20 — F11-j adds the migrated lead’s email summary</h3> <ul> <li><strong>Changed — cluster 2, the Lead row:</strong> a migrated Pipedrive lead’s summary written from its linked received email lives in a table of its own, <code>lead_mail_summary</code> (one row per lead, <code>designed</code>), not on <code>lead</code> and not in <code>lead_triage</code>. No edge changes: it references <code>lead</code> and <code>ai_invocation</code>, and nothing references it.</li> <li><strong>Why:</strong> F11-j spec D-4 — a background write to <code>lead</code> would move its <code>version</code>, and <code>lead_triage</code> stays written only by F11-d (F11-d FR-S3).</li> <li><strong>Impact:</strong> F11-j’s backend migration creates it; the row moves to <code>shipped</code> when that migration is on <code>main</code>.</li> <li><strong>Approved by:</strong> Tharinda (lead), 2026-11-20, with the F11-j spec.</li> </ul> <h3 id="rev-54-2026-11-20-f22-confirms-the-contact-sync-link-as-a-per-user-suggestion-table"><a class="anchor" href="#rev-54-2026-11-20-f22-confirms-the-contact-sync-link-as-a-per-user-suggestion-table" aria-hidden="true">#</a>Rev 54 — 2026-11-20 — F22 confirms the contact sync link as a per-user suggestion table</h3> <ul> <li><strong>Changed — cluster 2:</strong> the <em>Contact sync link</em> row moves from <code>designed (PRD caveat)</code> to <code>confirmed</code>, as the F22 spec’s suggestion table (FR-5): one row per (user, Graph contact id), with the copied fields, a suggested account, a state and, when added, the contact. The <em>Contact</em> row’s F22 note no longer says a synced contact may precede its account: a contact added from Outlook gets an account unless the user holds <code>account.all</code>.</li> <li><strong>Why:</strong> the lead’s decisions of 2026-11-20 in the F22 spec: contacts are read one way into a per-user review list, and nothing is created without the user’s action (PRD Rev 107).</li> <li><strong>Impact:</strong> F22’s plan names the table and writes its migration; no shipped table changes.</li> <li><strong>Approved by:</strong> Tharinda Rajapaksha (the lead), 2026-11-20, with the F22 spec. <em>Rev 53 was taken by F11-j (forge-et-harness#1611); Rev 54 is the next free number (id-numbering rule 5).</em></li> </ul> <h3 id="rev-55-2026-11-20-f20-k-adds-the-email-block-list"><a class="anchor" href="#rev-55-2026-11-20-f20-k-adds-the-email-block-list" aria-hidden="true">#</a>Rev 55 — 2026-11-20 — F20-k adds the email block list</h3> <ul> <li><strong>Changed — the email rows:</strong> a new row, <code>email_block</code> (<code>confirmed</code>): one row per blocked address or domain, on a user’s personal list or the organisation list (<code>owner_user_id</code> <code>NULL</code>). It references <code>app_user</code>, and nothing references it.</li> <li><strong>Why:</strong> F20-k spec D-2 — both lists in one table, read together by F20-f’s automatic linking and F20-j’s scans.</li> <li><strong>Impact:</strong> F20-k’s backend migration creates it; the row moves to <code>shipped</code> when that migration is on <code>main</code>.</li> <li><strong>Approved by:</strong> Tharinda (lead), 2026-11-20, with the F20-k spec. <em>Rev 54 was taken by F22 (merged first); Rev 55 is the next free number (id-numbering rule 5).</em></li> </ul> </div> <p class="gen">Generated from <code>.forge/design/data/entity-map.md</code> by <code>.claude/lib/render-docs-html.js</code>. Markdown is canonical.</p> </main></div><script> (function(){ var box=document.getElementById('q'),toc=document.querySelectorAll('ul.toc li'),content=document.getElementById('content'); if(!box)return; function clearMarks(){var sp=content.querySelectorAll('span.hl');for(var i=0;i<sp.length;i++){var s=sp[i],p=s.parentNode;if(!p)continue;p.replaceChild(document.createTextNode(s.textContent),s);if(p.normalize)p.normalize();}} function hi(node,ql){ if(node.nodeType===3){ var data=node.data,low=data.toLowerCase(),idx=low.indexOf(ql); if(idx<0)return; var span=document.createElement('span'),pos=0;span.className='hl'; while(idx>=0){span.appendChild(document.createTextNode(data.slice(pos,idx)));var mk=document.createElement('mark');mk.textContent=data.slice(idx,idx+ql.length);span.appendChild(mk);pos=idx+ql.length;idx=low.indexOf(ql,pos);} span.appendChild(document.createTextNode(data.slice(pos))); node.parentNode.replaceChild(span,node); }else if(node.nodeType===1&&!/^(SCRIPT|STYLE|MARK)$/.test(node.tagName)&&!(node.classList&&node.classList.contains('mermaid'))){ for(var i=node.childNodes.length-1;i>=0;i--)hi(node.childNodes[i],ql); } } box.addEventListener('input',function(){ var q=box.value.trim(),ql=q.toLowerCase(); clearMarks(); for(var i=0;i<toc.length;i++){var a=toc[i].querySelector('a');toc[i].classList.toggle('hide',!!q&&a.textContent.toLowerCase().indexOf(ql)<0);} if(ql.length>=2){hi(content,ql);var first=content.querySelector('mark');if(first)first.scrollIntoView({block:'center'});} }); })(); (function(){ var k='et-guide-theme',root=document.documentElement,b=document.getElementById('theme-toggle'); function cur(){return root.getAttribute('data-theme')==='dark'?'dark':'light';} function lbl(){if(b)b.textContent=cur()==='dark'?'\u2600 Light':'\ud83c\udf19 Dark';} function stampSelf(t){try{var u=new URL(location.href);u.searchParams.set('theme',t);history.replaceState(null,'',u.href);}catch(e){}} lbl(); if(b)b.addEventListener('click',function(){var t=cur()==='dark'?'light':'dark';root.setAttribute('data-theme',t);try{localStorage.setItem(k,t);}catch(e){}stampSelf(t);lbl();}); document.addEventListener('click',function(ev){ var el=ev.target;while(el&&el.nodeType===1&&el.tagName!=='A')el=el.parentNode; if(!el||el.nodeType!==1||el.tagName!=='A')return; var h=el.getAttribute('href'); if(!h||/^(https?:|mailto:|javascript:|data:|#)/i.test(h)||!/\.html(\?|#|$)/i.test(h))return; try{var u=new URL(h,location.href);u.searchParams.set('theme',cur());el.setAttribute('href',u.href);}catch(e){} },true); })(); </script></body></html>