source: .forge/design/data/record-sharing-model.md · generated — edit the markdown, not this file

Record Sharing — Decision Memo (OQ-58)

Status: decided 2026-09-16; revised 2026-09-24 by AD #35 and 2026-09-27 by AD #37; D-1 made explicit for reassignment 2026-09-30. Every numbered item (Q-1, C-1–C-3, D-1–D-5) is answered; this document is the record OQ-58 closes against. Revised 2026-09-24 (AD #35). The lead’s access-model decisions change six parts of this memo, and each is revised in place with the 2026-09-16 wording it replaces kept beside it: D-1 (sharing rides on the entity’s manage key, and anyone who holds it and reaches the record may share), D-2 (sharing is now transitive), D-3 (anyone with manage access removes any share), §2.3 (the table’s columns, one nullable foreign key per record type, and the lead’s owner nullable), §2.5 (team includes records shared with anyone below me; unowned records are visible only at all; built by F5-f before the list read-paths) and §4a (the picker offers only eligible users). Q-1, C-1, the §2.2 invariant, D-4 and D-5 stand. ## Revisions at the foot records the change. Revised 2026-09-27 (AD #37). A grant no longer carries a scope. A key on an owned entity reaches the records owned by, or shared with, the user or anyone below them in the reporting tree; the entity’s all key (lead.all, account.all, …) reaches every record. Where this memo says own, team or all, read: own = that rule for a user with nobody below them; team = the same rule for a manager; all = the role holds the entity’s all key. §2.1, §2.2 and §2.5 are revised in place; the other scope wording is left as dated text. Every sharing rule stands. Date: 2026-09-16 (revised 2026-09-24, 2026-09-27, 2026-09-30) Author: Dinil (with Claude) Related: .forge/project-prd-signals.md OQ-58 (and OQ-56, OQ-57), .forge/specs/foundation/006-auth-scaffolding-spec.md FR-P3/FR-P4, forge-et-be/docs/data-model.md §7, .claude/CLAUDE.md AD #26 / AD #30 / AD #32 / AD #34 / AD #35 / AD #36, .forge/specs/F5-f-team-visibility-scope-spec.md (the substrate that builds this), .forge/client/roles-and-permissions.md Decision owner: OQ-58’s owner — Dinil — for all nine items, decided 2026-09-16. C-1–C-3 were taken internally rather than put to Empire (§3): they are design questions answerable from what Empire has already told us, so they are stated to the client, not asked. The 2026-09-24 revisions are the lead’s (Tharinda), recorded as AD #35.


Why this exists

Empire asked for record sharing on 2026-09-09, in one sentence:

“The owner can share a lead or deal with a colleague, and that colleague then sees everything on it.”

It was flagged a confirmed V1 intent on 2026-09-13 (Tharinda) — working alongside the reporting hierarchy and own/team/all, not instead of them. A DB sketch exists (below). Everything else about it is undefined: not in the PRD body, not in the prototype, not in the entity map, and — most pressingly — not in client/roles-and-permissions.md, which is DRAFT awaiting Empire’s sign-off and currently describes access as role + ownership + hierarchy only.

This memo turns that one sentence into a decision set.

Not in scope here: participants on a lead (several organisations/contacts on one record) is OQ-57 — a domain relationship, not access control. Keep them separate; they will be confused otherwise.


§1 — The starting sketch, and what it settles

The model put forward:

user                role                     leads
uid  rid  reporter  rid  permissions         lid  owners
1    1    3         1    leads+view+team     1    1
2    1    3                                  2    2, 1
3    1    4                                  3    1

Two thirds of this is already built and matches.

Sketch Shipped Verdict
user (uid, rid, reporter) app_user (id, role_id, manager_id) — V6__app_user_and_identity.sql Matches. Keep the shipped name manager_id: “reporter” is directionally ambiguous, and the direction is load-bearing for the subtree walk.
role (rid, permissions) role_grant (role_id, permission_key, scope) with UNIQUE (role_id, permission_key) Matches, already normalised. leads+view+team is one role_grant row. Nothing to change.
leads (lid, owners) — The new idea, and the right one. See §2 for the storage.

The concept is correct and is the requirement: a lead must be reachable by people beyond its owner and the hierarchy. That is exactly what Empire asked for and the shipped permission model cannot express it (§2.1). The only thing this memo changes is where that list of people lives.

✅ Q-1 — Co-ownership, or owner + shared? — DECIDED: owner + shared (b), 2026-09-16, Dinil

owners = "2, 1" reads two ways, and they are different features:

  • (a) Co-ownership — 1 and 2 both own it, equally. Both see it in “my leads”, either can act as the owner, nobody is the grantor, there is nothing to revoke.
  • (b) Owner + shared — 1 owns it; 2 has been given sight of it by 1. One owner, revocable, with a grantor on the record.

Why (b): Empire’s wording is “the owner can share … with a colleague” — one party granting, one receiving. And PRD Rev 23 records Empire confirming that a deal or quote must always have an active owner (reassignment precedes deactivation), which co-ownership complicates: offboarding, region routing, “my leads” and reporting all key off a single owner today.

Decided (b) — §2’s design stands as written. One owner per record; sharing is a revocable grant on top.

Done — the lead confirmed the owner-plus-shares reading on 2026-09-23, in the design conversation that produced AD #35, which keeps one explicit owner per record plus shares. (The 2026-09-16 note here asked for a courtesy line to Tharinda, because his sketch’s owners = "2, 1" reads as co-ownership and this memo read it as owner + shared.)


§2 — The design

2.1 Why the shipped model can’t already do this

FS-6 shipped grants as (role, permission_key, scope) with scope ∈ own|team|all. The whole record-level input to a decision is one owner id:

// auth/access/OwnershipContext.java — as shipped
public record OwnershipContext(@Nullable Long ownerId) { }

DefaultPermissionChecker resolves ALL → true, OWN → ownerId == me, TEAM → ownerId in subtree(me), walking manager_id via TeamResolver’s recursive CTE. Every answer derives from one owner id plus the org chart.

The load-bearing distinction: scope is a property of a role grant — how far a role’s reach extends. A share is a property of a record — who else may reach this one. No value added to the scope enum can express “Kasun shared lead 4041 with Nuwan,” because an Administrator would have to tick it on a role, where it means nothing.

So sharing is a fourth visibility path, resolved as an OR beside the three:

visible = (own | team | all resolves)  OR  (this record is shared with me)

Revised 2026-09-24 (AD #35): the share is folded into each scope rather than added beside them. own covers records I own or that are shared with me; team covers records owned by, or shared with, me or anyone below me in the reporting tree (all levels), so shares roll up to managers; all covers every record, unowned ones included. §2.5 gives the rule.

Revised 2026-09-27 (AD #37): there is no scope to fold into. The one rule is: records owned by, or shared with, me or anyone below me in the reporting tree — for a user with nobody below them, exactly what own covered — and the entity’s all key reaches every record, unowned ones included.

The timing is good. OwnershipContext’s own javadoc records that no entity carries an owner yet and that F1/F2 inherit wiring the first real ownership context. Nothing is built on the seam. Adding sharing now is a field and a resolver; adding it after F1/F2 ship means revisiting every read path they wrote. (True on 2026-09-16. F1-a has since shipped account.owner_id and an account list that filters on it; that list is the interim F5-f replaces — §2.4.)

2.2 The invariant — the single most important rule here

A share widens reach, never authority.

can(key, ctx) = the user’s role holds key AND (its scope resolves OR the record is shared with them).

Revised 2026-09-27 (AD #37): can(key, ctx) = the user’s role holds key AND (the role holds the entity’s all key OR the record’s owner, or a user it is shared with, is the user or anyone below them).

The share carries no access level of its own (C-1). It puts the record in reach; the recipient’s role decides what they may do with it.

Consequences, all intended:

  • Share a deal with an R&D taster whose role holds no deal.view at all → still invisible. Since 2026-09-24 (AD #35) such a user is not offered in the share picker at all (§4a).
  • Share with someone holding deal.view → they see it, cannot edit it.
  • Share with someone holding deal.manage → they can work it. This is the “cover for me while I’m on leave” case, solved with no extra mechanism.

Without this rule, sharing becomes a back door around the permission catalog: reach would be grantable by any rep, invisible in the role editor, and AD #26’s guarantee — who holds a permission is configuration Empire owns, and it is visible in the role — would quietly stop being true.

2.3 The table

Follows the Activity pattern already in the entity map (“links → account / deal / lead (each N:1 nullable, at least one)”) rather than inventing a shape. Real FKs, cascade delete, one table, one service, one resolution query.

Revised 2026-09-24 (AD #35) — the shape below replaces the 2026-09-16 sketch. F5-f’s spec confirms the exact DDL.

CREATE TABLE record_share (
    id                  BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    -- One nullable foreign key per shareable record type; exactly one is set.
    lead_id             BIGINT REFERENCES lead(id)    ON DELETE CASCADE,
    account_id          BIGINT REFERENCES account(id) ON DELETE CASCADE,
    -- deal_id and quote_id arrive with the features that create those tables:
    -- one column and one CHECK arm each.
    shared_with_user_id BIGINT      NOT NULL REFERENCES app_user(id),
    shared_by_user_id   BIGINT      NOT NULL REFERENCES app_user(id),
    shared_at           TIMESTAMPTZ NOT NULL DEFAULT now(),
    -- No access column, deliberately (C-1): the share grants reach, the recipient's role grants
    -- authority. A per-record access level would be a permission a colleague hands out, which is
    -- exactly what AD #26 keeps in the role.
    version             BIGINT      NOT NULL DEFAULT 0,
    created_at          TIMESTAMPTZ NOT NULL DEFAULT now(),   -- the base columns every table
    created_by          BIGINT REFERENCES app_user(id),       -- carries (AD #36)
    modified_at         TIMESTAMPTZ NOT NULL DEFAULT now(),
    modified_by         BIGINT REFERENCES app_user(id),
    CONSTRAINT record_share_exactly_one CHECK (
        (lead_id IS NOT NULL)::int + (account_id IS NOT NULL)::int = 1
    )
);
-- Unique per (record, user): one partial unique index per record type, e.g.
--   UNIQUE (lead_id, shared_with_user_id)    WHERE lead_id    IS NOT NULL
--   UNIQUE (account_id, shared_with_user_id) WHERE account_id IS NOT NULL
-- plus an index on (shared_with_user_id) for the list rule in 2.5.

As sketched 2026-09-16 (superseded): a shared_with column, created_by doubling as “who shared it”, a deal_id column from the start, and one partial unique index per entity on (<fk>, shared_with). AD #35 names the columns shared_with_user_id, shared_by_user_id and shared_at, so who shared it and when are domain fields the record display reads (D-4), separate from the base audit columns every table carries (AD #36).

Owner stays singular on the record itself: one owner_id per shareable record, NOT NULL on account (and on deal and quote when they land), and nullable on lead, for import edge cases only — an unowned lead is visible only to all-scope holders (AD #35). The 2026-09-16 text had lead.owner_id BIGINT NOT NULL REFERENCES app_user(id).

Why not a multi-valued owners column: no FK, no referential integrity, no index able to answer “which leads can user 5 see?” — the query every list view runs — and nowhere to record who granted the share and when, which D-3’s revocation rule and the D-4 record display both need. It also conflates owner and sharee into one list where position carries meaning that nothing enforces.

Trade-off accepted: the DDL grows by one column and one CHECK arm per new shareable entity. That is a visible, reviewed change. The generic (record_type, record_id) alternative avoids it but gives up referential integrity and needs a deletion hook; revisit only if the shareable set passes ~5 entities.

2.4 The checker

Extend OwnershipContext; never the Scope enum. Add a ShareResolver, symmetric with TeamResolver — same argument its javadoc already makes for keeping the hierarchy rule in one query rather than spread across callers.

Revised 2026-09-24 (AD #35): the per-record check and the list query must give the same answer for every record, so both come from one scope-and-share visibility rule, exposed through auth.access. F5-f’s spec decides the mechanism (a ShareResolver beside TeamResolver, or one query shape both paths call); what is fixed is that there is one rule, not two. On main today F1-a’s account list filters team as own while the per-record check walks the tree, so a manager can open a report’s account by its link but not find it in the list — the interim F1-a records (its FR-O3, Q-11), which F5-f removes.

2.5 The list predicate — the real cost, and it is owed anyway

can() is a per-record check. There is no list-side filtering primitive in FS-6 and none was specced. For a lead list of ~692 migrated records you cannot call can() per row; visibility has to become SQL.

Revised 2026-09-27 (AD #37) — the rule, for a user whose role holds lead.view (a user whose role lacks the key sees no lead at all; the key is checked first). :holds_all is whether the role holds lead.all; :me_and_below is the user plus everyone below them in the reporting tree, all levels down (the recursive manager_id walk TeamResolver already does) — for a user with nobody below them, just the user.

WHERE :holds_all                                       -- lead.all: every lead, unowned ones included
   OR l.owner_id IN (:me_and_below)
   OR EXISTS (SELECT 1 FROM record_share s
               WHERE s.lead_id = l.id
                 AND s.shared_with_user_id IN (:me_and_below))

Three properties follow, and each is a test (test-strategy.md § The Always-Test List):

  • Shares roll up. A manager sees a record shared with anyone below them, not only records they or their reports own.
  • Unowned records are visible only with the all key. An unowned lead matches no owner_id IN (:me_and_below); F11-b gives lead.all holders an Unassigned filter for them, not a separate queue. Settled 2026-10-02 (F5-f spec FR-R1, FR-O1): a record with no owner cannot be shared (422 SHARE_RECORD_UNOWNED), so the EXISTS arm above never applies to one — the PRD’s “visible only to holders of lead.all” holds without exception.
  • A share to a deactivated user is inert. Settled 2026-10-02 (lead, F5-f spec FR-R3; PRD Rev 49): the EXISTS arm counts only shares whose recipient is active, so such a share reaches nobody — not the recipient, not their managers — and counts again if the recipient is reactivated. The row stays, shown as deactivated and removable (D-3).
  • The per-record check gives the same answer as this rule for every record (§2.4).

As revised 2026-09-24 (AD #35; superseded by AD #37) — :me_and_below was needed only at team:

WHERE :scope = 'all'                                   -- every lead, unowned ones included
   OR (:scope = 'own'  AND (l.owner_id = :me
                            OR EXISTS (SELECT 1 FROM record_share s
                                        WHERE s.lead_id = l.id
                                          AND s.shared_with_user_id = :me)))
   OR (:scope = 'team' AND (l.owner_id IN (:me_and_below)
                            OR EXISTS (SELECT 1 FROM record_share s
                                        WHERE s.lead_id = l.id
                                          AND s.shared_with_user_id IN (:me_and_below))))

Its three properties, as then written:

  • Shares roll up. A manager at team sees a record shared with anyone below them, not only records they or their reports own.
  • Unowned records are visible only at all. An unowned lead matches neither owner_id = :me nor owner_id IN (:me_and_below); F11-b gives all-scope holders an Unassigned filter for them, not a separate queue.
  • The per-record check gives the same answer as this rule for every record (§2.4).

As written 2026-09-16 (superseded):

WHERE ( :scope = 'all'
     OR (:scope = 'own'  AND l.owner_id = :me)
     OR (:scope = 'team' AND (l.owner_id IN (subtree) OR l.owner_id IS NULL)) )
   OR EXISTS (SELECT 1 FROM record_share s WHERE s.lead_id = l.id AND s.shared_with = :me)

— it showed unowned leads to team holders, and did not roll shares up the tree.

Without this, a shared record is visible only by direct navigation and never appears in the sharee’s list — which is not what Empire asked for.

Open for F5-f’s spec: whether a share to a deactivated user still counts for that user’s managers under team. AD #35 keeps such shares — inert, shown on the record as deactivated, and removable — but does not say whether they roll up. Closed 2026-10-02 (lead): it does not — the share is inert for everyone (the third property above; F5-f spec FR-R3; PRD Rev 49).

Size it honestly: the rule is owed regardless of sharing, because own/team scope needs it too. Sharing adds one EXISTS per scope to work that has to happen anyway. It is built by F5-f, as a substrate, before any lead, account or deal list read-path (AD #35) — not by F1/F2, as the 2026-09-16 text said.


§3 — How sharing behaves

All three decided internally on 2026-09-16 (Dinil), not put to Empire. These are design questions the team can answer from what Empire already told us; asking would have added a round-trip for no new information. They are stated to Empire in client/roles-and-permissions.md, not asked.

✅ C-1 — What may the shared user do? — DECIDED: whatever their own role allows

The share carries no access level. An owner shares a record; what the recipient may then do with it is decided entirely by their role’s permission set — exactly as it would be for a record they owned.

  • Role holds deal.view → they see it.
  • Role holds deal.manage → they can work it.

Why this beats an access level on the share (the earlier proposal): it keeps AD #26 whole — what a person may do stays their role’s configuration, never a per-record grant a colleague hands out. It also removes the access column, the picker in the share dialog, and the question of what happens when share-level and role-level disagree. And it solves “cover for me while I’m on leave” for free.

The one thing given up, accepted: you cannot share “look, don’t touch” with someone whose role holds manage. Acceptable — they can already work their own records, every change is audited, and Empire is 10–20 trusted users.

✅ C-2 — Does a share cover the record’s linked correspondence? — DECIDED ⚠️

The one with a privacy consequence. roles-and-permissions.md already promises Empire that personal mailboxes stay private — the mailbox permission is granted at own reach on every role and no role can widen it. Revised 2026-09-24 (AD #34): the promise is now stronger — there is no mailbox permission with a reach at all. email.manage covers only the holder’s own mailbox, and no role can read another person’s mailbox, as a fixed rule rather than a setting.

A share covers the record and everything attached as a record — notes, activities, samples, quotes, files — and record-linked mail on exactly the footing any team/all viewer already gets: children follow their parent’s reach (AD #35). It never opens a mailbox. Sharing makes one record reachable; it does not open anyone’s mailbox. (The 2026-09-16 text said “it never widens mailbox.read”; AD #34 retires that key into email.manage.)

State this explicitly in the client doc and in the F5-f and F1/F2 specs, or it will be got wrong in implementation.

✅ C-3 — Is this redundant with a manager’s team reach? — DECIDED: no, they are different cases

A manager already sees their reports’ records through team scope, so a manager never needs to be shared anything. Sharing exists for the case the hierarchy cannot reach: peer-to-peer and cross-line — a rep sharing with a rep in another region, or with the Tea Room. (The 2026-09-16 text added that this was real for Empire given OQ-52’s region-based routing of info@ inquiries. Since 2026-09-24 info@ reaches the CRM only by forwarding to a rep, and the shared inbox F20-e has left V1, so that reason no longer applies; the cross-line case stands.)

UI consequence (revised 2026-09-24, AD #35): someone who already reaches the record — through ownership, a share, the reporting tree or all scope — is not listed in the share picker at all — the lead’s worked example (2026-09-23) offers only the colleagues who cannot yet see the record — rather than silently creating a share that changes nothing; existing shares appear in the record’s shared-with list, with Remove. The picker offers only active users whose role holds the entity’s view key and who do not already reach the record.


§4 — Internal decisions

All five decided 2026-09-16 (Dinil). Recorded so they are visible rather than defaulted into. D-1, D-2 and D-3 were revised by the lead on 2026-09-24 (AD #35); each keeps its 2026-09-16 wording under As decided 2026-09-16 (superseded).

✅ D-1 — Sharing rides on manage; no new catalog key — DECIDED; revised 2026-09-24 (AD #35)

Sharing, removing a share and reassigning the owner are all covered by the entity’s manage key — lead.manage and account.manage now, deal.manage and quote.manage in Phase 2 (AD #34’s catalog; manage covers every action on the entity). Anyone whose role holds the entity’s manage and who reaches the record — as its owner, through the reporting tree, through the entity’s all key (AD #37), or through a share — may share it, remove any share on it (D-3) and reassign its owner. There is no separate owner-or-covering-manager rule, for any of the three. A user whose role holds only the entity’s view can do none of them. No catalog growth. Confirmed 2026-09-30 (lead): this includes a colleague the record was shared with — the lead kept this rule rather than limiting reassignment to the owner, the owner’s managers and all-key holders, after the client roles document was found saying a representative “cannot reassign records they do not own” (corrected there; PRD Rev 46).

As decided 2026-09-16 (superseded): FS-6 Rev 6 kept outward/sensitive actions as their own keys (email.send, price.publish, user.deactivate) and folded ordinary edits into manage; sharing was folded into manage because manage already contained reassigning the owner, and who may share was enforced as a domain rule in the service — the owner, or a team/all-scope manage holder covering that record. AD #34 has since retired email.send and user.deactivate (into email.manage and access.manage, itself folded into settings.manage on 2026-10-26); price.publish stays.

✅ D-2 — A share is transitive — REVISED 2026-09-24 (AD #35)

Someone who reached a record through a share, and whose role holds the entity’s manage, may share it on. Reach stays traceable without a ban on onward sharing: every share row records who shared it and when (shared_by_user_id, shared_at, §2.3), and every share and removal is written to the audit trail (AD #36). Accepted trade-off (AD #35): a share across reporting lines becomes visible up the recipient’s chain, and anyone with manage can spread a record further — accepted because removing a share is in V1 and every share is audited.

As decided 2026-09-16 (superseded): no onward sharing. Only the owner and covering managers share. Otherwise reach becomes untraceable and nothing can answer “why can this person see this?”

✅ D-3 — Removing a share — REVISED 2026-09-24 (AD #35)

Anyone whose role holds the entity’s manage and who reaches the record can remove any share on it; removing a share is in V1. Shares survive owner reassignment — they are about the record, not the person — and the previous owner loses reach unless the record is shared back to them. A share to a deactivated user stays: it is inert, shown on the record as deactivated, and removable (AD #34, AD #35).

As decided 2026-09-16 (superseded): revocation by the owner, the original sharer, and any manage holder at team/all covering the record; shares survived reassignment and the new owner could revoke; F5’s offboarding flow was to surface shares to a deactivated user rather than clean them up silently.

✅ D-4 — Shares appear on the record, not in the effective-permissions viewer — DECIDED

The viewer answers “why can this person see this?” from role + grant + scope. It is per-user; a share is per-record, so it cannot be enumerated there. (The viewer sits behind settings.manage; from AD #34 until 2026-10-26 it was access.manage.)

Proposed: surface on the record — “Shared with Nuwan, Priya — by Kasun, 12 Sep.” The viewer’s copy gains one line saying reach is role + reporting line + per-record shares, so the screen stops implying the role tells the whole story.

✅ D-5 — Pipedrive’s Lead - Visible to does not migrate into record_share — DECIDED

The leads export carries a Lead - Visible to column across ~692 leads.

Proposed: do not map it to shares. Pipedrive’s values are visibility-group semantics, not per-user grants; keep as source metadata and let role scope + the hierarchy carry it.

⚠️ Verify before relying on this. The exact Pipedrive visibility/follower semantics are not recorded in .forge/discovery/research/ — check against Pipedrive’s own documentation or the actual values in the export at spec time (.claude/rules/source-trust.md).


§4a — One consequence found while prototyping

A share onto a role that holds no permission for the record does nothing — and that is correct, but it will surprise people.

Building the picker surfaced it: the recommended Tea Room role is scoped to pricing only, so it holds no lead permission. Under the §2.2 invariant a lead shared with the Tea Room stays invisible to them — the share grants reach, their role grants nothing to reach it with. The same applies to R&D/Taster.

This is the invariant working, not a bug. But “I shared it and they still can’t see it” is a support call, so:

  • The prototype marks it in the picker (“No lead access”, with the full explanation on hover) rather than letting someone share into silence, and still lets the share be made. Superseded 2026-09-24 (AD #35): the real picker does not offer a user whose role lacks the entity’s view key, and the share operation refuses one, because the picker is not the boundary. The 2026-09-16 text said F5’s picker should mark such users as the prototype does. The prototype’s drift is recorded in .forge/design/prototypes/feature-detail.md (F5).
  • It is worth telling Empire, because it is a role-content decision they own: if reps are expected to pull the Tea Room onto a specific lead or deal for pricing input, the Tea Room role needs view on that record type. That is a tick in the role editor, not a code change — which is the model behaving as intended.
  • Folded into OQ-53(b) (the recommended Tea Room and Executive role contents), not raised as a new question.

§5 — What this touches once decided

Where What
client/roles-and-permissions.md Most urgent — a sharing section in the numbered-assumption style, stating how it works (C-1…C-3 are decided, not asked). DRAFT awaiting Empire’s sign-off; as it stands they would sign off an access model missing a confirmed V1 feature. The C-2 mailbox line goes in verbatim — it is the half that touches a promise already made to them. 2026-09-24: its sharing section was restated against AD #35 (transitive sharing, removal by any manage holder, the eligible-only picker) in the same change as this revision; the line telling Empire remains owed.
Prototype (design/prototypes/crm/) Share affordance on lead/deal/account detail; shared-in records visible and marked in list views (without this the feature is invisible); the effective-permissions copy from D-4. Drawn 2026-09-16; its “cannot pass it on further” footer, owner-or-manager-only sharing and “No lead access” picker entries are superseded by AD #35 — see the F5 drift rows in .forge/design/prototypes/feature-detail.md.
project-prd.md F1/F2/F5 bodies and § Multi-Tenancy gain the fourth visibility path. Rev + the three-write OQ-58 closure (.claude/rules/prd.md).
.forge/design/data/entity-map.md A record_share row with its cardinality and confirming spec. Done; entity-map Rev 10 records AD #35’s columns and F5-f as the confirming spec.
forge-et-be/docs/data-model.md §3 (Accounts/Contacts/Deals) currently a stub — the DDL lands with F5-f (revised 2026-09-24; was F1/F2).
Gate 3 Decomposition must carry sharing and the §2.5 list predicate as F1/F2 work, not leave them implicit. Revised 2026-09-24 (AD #35): carried by F5-f — the owner pattern, record_share and the one visibility rule, built before F1-b, F11-b, F5-g and F5-h. F5-g builds the sharing screens.

Two items to raise rather than decide here

  • Does this want an AD row? AD #30/#32 describe visibility as role + scope + hierarchy; a reader today would conclude that is the complete model. A fourth, record-level path is a genuine refinement — either its own AD row or an explicit note on AD #30. Because AD #30/#32 refine a DO-NOT-REVERSE row, that needs lead sign-off. Answered 2026-09-24: AD #35, with the lead’s sign-off.
  • Is sharing inside accepted scope? Proposal §3.2 quotes six roles plus granular levels; sharing is not named. Per L-001 the divergence is stated, not silently absorbed. AD #30’s precedent — V1 requirement, no change request, post-issue note on the proposal header — is the likely call, but it is a commercial judgment, and it should be recorded either way.

Revisions

2026-09-24 — revised for AD #34 and AD #35 (lead: Tharinda)

  • Changed, in place, with the 2026-09-16 wording kept beside each: D-1 (sharing, removing a share and reassigning the owner ride on the entity’s manage; anyone who holds it and reaches the record may share — no owner-or-covering-manager rule); D-2 (sharing is transitive); D-3 (anyone with manage access removes any share; shares to a deactivated user stay, inert and removable); §2.3 (shared_with_user_id, shared_by_user_id, shared_at; lead_id and account_id now, deal_id and quote_id later; exactly one set; unique per record and user; the lead’s owner nullable for import edge cases); §2.4 (one scope-and-share rule in auth.access for list queries and per-record checks); §2.5 (own and team include shares, shares roll up the tree, unowned records only at all; built by F5-f before the list read-paths); C-2 (no key reads another person’s mailbox — mailbox.read is retired into email.manage); C-3 (the info@ reason is withdrawn; people who already reach the record are not listed in the picker); §4a (the picker offers only active users whose role holds the entity’s view key). The Q-1 courtesy note is marked done, and the AD-row question in §5 is answered by AD #35.
  • Why: the lead’s access-model decisions of 2026-09-22 to 2026-09-24, signed off as AD #34 (the minimal catalog), AD #35 (ownership and sharing) and AD #36 (the audit trail that makes transitive sharing acceptable). Full rationale: .forge/engagement-log.md § AD #34, AD #35, AD #36.
  • Not changed: Q-1 (one owner plus shares), C-1 (a share carries no access level), the §2.2 invariant (a share widens reach, never authority), D-4 (shares shown on the record) and D-5 (Pipedrive’s Lead - Visible to does not migrate into shares).
  • Left open for F5-f’s spec: whether a share to a deactivated user still counts under team for that user’s managers (§2.5).

2026-09-27 — revised for AD #37 (lead: Tharinda)

  • Changed: the header gains a reading note (own / team / all in this memo now mean the one reporting-line rule for a user with nobody below them, the same rule for a manager, and the entity’s all key); §2.1 and §2.2 gain the AD #37 form of the fold and of can(key, ctx); §2.5’s rule is rewritten — :holds_all for the entity’s all key, :me_and_below for everyone else — with the AD #35 form kept below it as superseded.
  • Why: AD #37 (lead decision, 2026-09-27) removes the scope from a grant: team already equalled own for a user with nobody below them, and only “every record” needs a setting. Full rationale: .forge/engagement-log.md § AD #37.
  • Not changed: every sharing rule — Q-1, C-1–C-3, D-1–D-5, the §2.2 invariant, the picker (§4a) and the open question on shares to deactivated users (now: whether they count for that user’s managers).

2026-09-30 — D-1 made explicit for reassignment (lead: Tharinda)

  • Changed: D-1’s rule now names all three actions — share, remove any share, reassign the owner — for anyone whose role holds the entity’s manage and who reaches the record, and says “through the entity’s all key” where it said “at all scope”.
  • Why: the lead confirmed on 2026-09-30 that a colleague a record was shared with may reassign it, as AD #35 already implied; the client roles document had said otherwise and is corrected (PRD Rev 46).
  • Not changed: every rule. The picker still offers only eligible users (§4a) — someone whose role cannot view the entity, or who already reaches the record, gains nothing from a share.

2026-10-02 — the two §2.5 questions settled by the F5-f spec (lead: Tharinda)

  • Changed: §2.5 gains two settled properties: a record with no owner cannot be shared, so the share arm never applies to one; and a share to a deactivated user is inert — it reaches nobody, the recipient’s managers included, and counts again on reactivation. The §2.5 open item is closed.
  • Why: the F5-f spec (approved 2026-10-02). The first follows the PRD, which outranks this memo’s SQL (“visible only to holders of lead.all”); the second is the lead’s decision at spec authoring (PRD Rev 49). Records shared with a user do not block their deactivation — only records they own do — so the case is real.
  • Not changed: every other rule — Q-1, C-1–C-3, D-1–D-5, the §2.2 invariant and the picker (§4a).

2026-10-26 — the administration key renamed (Nanndish; signed off by Tharinda, 2026-10-27)

  • Changed: D-1’s superseded note and D-4 name settings.manage where they named access.manage, which AD #34’s refinement of 2026-10-26 folded into settings.manage (.claude/CLAUDE.md AD #34; PRD Rev 79).
  • Not changed: every sharing rule; the effective-permissions viewer still shows no shares.

Generated from .forge/design/data/record-sharing-model.md by .claude/lib/render-docs-html.js. Markdown is canonical.