Kind and facets
One entity, one kind, many roles: how Synap separates what a thing is from the roles it plays.
One real-world thing is one entity in your pod. What it is used as in a given context is a role (also called a facet), attached to that entity. A role is never a second entity.
The rule
Every entity answers three separate questions:
- What it is: its kind. A person, a company, a task. Every entity has exactly one kind, set when it is created, and it rarely changes.
- What it is used as, and where: its roles. A client in your sales space, an investor in another, a speaker at one event. Roles are attached and detached over time, and an entity can have several at once.
- What it is connected to: its relations. Works at, assigned to, blocks. See Entity connections.
The mistake this prevents: recording "Anna is now a client" by creating a second record called "client" next to the
person Anna. In Synap, Anna stays one person, and a client role is attached to her. Everything about Anna (her
email, her notes, her meetings, the deals she is part of) stays on one entity, whatever roles she plays.
A role carries its own status and its own fields. A client role can have a status such as active or paused and a
"became client at" date; those live on the role, not on the person. A role can also be attached in one space only, so
the people in that space see it while the person stays the same entity everywhere.
When something should be a kind instead
Not every recurring role should stay a role. Ask: does it have its own life, with its own timeline, its own links to other things and its own states that outlive any single person or company? If so, it is a kind.
A deal is a kind. It is not "a person in the won state": it has its own buyer, its own stage, its own value and close
date, and its own linked contacts and documents. An event is a kind for the same reason: a time-bound thing, not a
role someone plays.
client, partner and lead are roles. They describe a stance a person or company takes and have no existence
outside that person or company. Detach a role and the entity is untouched; delete the entity and its roles go with it.
Rule of thumb: if it could outlive its parent, or be shared by several parents with links of its own, it is a kind. If it belongs to one entity and only changes that entity's stance, it is a role.
Example: a CRM
The CRM template models relationship state as roles on people and companies, with deals as their own kind:
personandcompanyare kinds. The CRM adds a few contact fields to them, such as lead source and next follow-up date, but no pipeline stage: a lead's stage lives on itsleadrole, a deal's on the deal.lead,clientandpartnerare roles. A person you start pursuing gets theleadrole; when you win a deal, the company gets theclientrole. The person and the company stay the same entities throughout.dealis a kind, with its own stage, value and close date. It links to the person or company; it is not a role.
A client who leaves keeps their entity: you change the client role's status or detach the role, and their history
stays on the person or company.
Finding the right entity first
Before attaching a role, the pod helps you find the entity that already exists, so the role does not land on a duplicate:
- Strong signals (an email address, a phone number, a URL such as a LinkedIn profile or a website, a handle, an external id) identify one entity. A match on any of them resolves to that entity: enrich it or attach a role to it, do not create a new one.
- Weak signals (a name) only suggest candidates. They never merge two records on their own; when two people share a name, you or the agent choose.
How an app or agent attaches a role
Through MCP:
| Tool | What it does |
|---|---|
synap_resolve_identity | Checks, before creating anything, whether an entity already matches the signals you have. It never writes. |
synap_attach_facet | Attaches a role to an existing entity, by the role's slug (for example client). |
synap_detach_facet | Detaches a role. The entity is never deleted. |
synap_define_role | Defines a new role, or widens the kinds an existing role applies to. |
synap_list_profiles | Lists the kinds and roles on your pod, and which kinds each role applies to. |
Through the Hub REST API: POST /api/hub/identity/resolve runs the same identity check, GET and
POST /api/hub/entities/{entityId}/facets list and attach roles, PATCH /api/hub/facets/{facetId} changes a role's
status or fields, and DELETE /api/hub/facets/{facetId} detaches it. See the Hub REST API.
Attaching a role again after it was detached works: a client who leaves and comes back needs no special case.
By default an agent's attach, update and detach of a role apply directly; a detached role is kept in the history and
can be attached again. An agent defining a new role always becomes a proposal for you to approve. Any of these calls may answer status: "proposed": that means the
change waits for review, not that it failed. See Validation policy.
Related
- Entity connections: relations and structural links
- Profile schemas: how fields are defined and scoped