0035: Contacts on the object engine¶
Status¶
Proposed (2026-11-10). Builds on ADR 0015 (metadata-driven objects; §6
leaves Contacts on its typed store "until it is migrated"), ADR 0033 §2
(plugin-declared engine objects), ADR 0012 (plugin extensions), ADR 0013
(storage backends), ADR 0014 (standard record fields), ADR 0016 (sharing),
ADR 0017 (field history and change sources) and ADR 0011 (UX). This is a
design; delivery slices are in §8 and docs/roadmap/README.md.
Delivered (2026-11-17): gap G1, archiving engine records, on both stores:
archive and unarchive routes (edits needing edit access), status=archived
and status=all on lists, archived_at and include_archived in the query
language, platform.objects.record-archived.v1 and -unarchived.v1,
archived and unarchived history entries, updated change-log entries
naming archived_at, replicas taking the server's archive state, and the
Archive action on the generic record page. Archived records stay readable
and editable, and are left out of default lists, queries, global search,
lookup pickers and related lists (see docs/api/objects.md, "Archiving").
Archiving on a synced device offline is not part of it: the bridge answers
sync.server_only. G2, G3, G5 and G8 are delivered too (below); every other
gap and slice is still to do.
Decided in review (2026-11-10):
- Person's name is split into first and last name as part of the migration (§1, gap G17).
- Migrated records are owned by their creator while that user is still a member (§2).
- The custom-field read permissions are enforced on the server (§4).
- A manifest may name an optional plugin's objects in a starting allowlist, so Activities includes Person and Organisation itself (§7, gap G18).
- The 30-day rollback window and the six-month deprecation are accepted provisionally, to be confirmed before slice 5 ships.
Delivered:
- G5, field-level permissions (2026-11-17). A field names an optional
read_permissionandwrite_permission, set on workspace fields by administrators withobjects.manageand declared by plugins on their manifest fields, stored in both stores and carried to replicas with the definitions. Without the read permission a field is hidden from records, queries (where it is an unknown field, as ADR 0019 §3 planned), search matching and results, history, the change log, replicas, related lists, timelines and reports; formulas and roll-ups are computed with full access and hidden when they depend on a hidden field. Without the write permission, changes are refused withrecords.field_not_writable. System context (the kernel, the installer, the G4 migrator once it lands, automations, validation rules and lookup filters) bypasses the check, as it bypasses sharing. The check is one function that role-based field-level security (#316) extends. See Field permissions. - G2, the recycle-bin purge (2026-11-18). Records 15 days in the bin (an
engine constant, as ADR 0014 §5) are removed for good by a per-workspace
worker job that runs as the platform through the store, under the
workspace's row-level security, in bounded batches: the record with its
pivots, search terms, shares, history, change-log rows and kept cleared
lookups. Audit and published events stay; each batch writes one
records.recycle_bin.purgedaudit entry and oneplatform.objects.record-purged.v1event per record. A record undeleted meanwhile is never purged. Values on other records pointing at a purged record are cleared as system updates, and details go with their master. Synced devices hold their recycle bin in the revocation manifest, and a record in the server's bin is no longer revoked; change pages carry apurgescount, and a device that sees it move asks for revocations, which name the purged records. - G3, restoring cleared lookups (2026-11-18). Deleting a record keeps each
lookup value it clears, with the referencing record's version, in a
tenant-scoped table with forced row-level security; a write to that field
marks it changed. Undeleting the record puts back each value whose
referencing record is live and unchanged, as a system update with its own
version, history, change and
record-updatedevent, without validation rules or automations, and counts restored and skipped links on the undelete response. The clear itself is unchanged (the accepted change). See Recycle bin. - G8, long email addresses (2026-11-21). Email fields take a
max_lengthfrom 1 to 320, declared on workspace fields, in manifests and when the field is changed; without one they allow 255, as before. An address's local part has at most 64 characters and its domain at most 255 (RFC 5321), replacing the engine's former 254-byte limit on the whole address.
Context¶
Contacts (platform.contacts) is the last first-party capability with its
own typed storage. Everything built since ADR 0015 (sharing, the query
language, validation rules, automations, quick actions, related lists, the
Activity timeline, field history with change sources, global search, bulk
jobs, API clients, change data capture and device replicas) works on engine
objects only. People and organisations get none of it, and ADR 0033 had to
leave Activities' Who field pointing at workspace objects, because Person
is not an engine object.
What Contacts is today¶
Records. Two record kinds in p_contacts (PostgreSQL) and in
p_contacts_* tables in each workspace file (SQLite):
| Kind | Public ID | Own fields | Other columns |
|---|---|---|---|
Person (people) |
per… |
full_name (name, 1 to 240 characters), email (up to 320), telephone (not validated), organisation_id (foreign key to an organisation), tags (free-form text[], no limits) |
custom_fields jsonb, extensions jsonb, version, archived_at, deleted_at, created_*, updated_*, touched_at, name_key, email_key |
Organisation (organisations) |
org… |
name (1 to 240), email, telephone |
the same, without tags or a parent |
Public IDs use the platform format (platform_id, 18 characters) from
per-workspace counters in p_contacts.public_id_counters; the prefixes are
registered in the kernel's id_prefix_registry. Records have no owner.
Supporting tables. custom_field_definitions (per workspace and
target: __c API name, label, type, required, unique, indexed, options,
validation_schema limited to min_length/max_length and
minimum/maximum, data_classification, purpose, retention_days,
encrypted, and an active → disabled → archived lifecycle), list_cursors
(keyset cursors, cleaned by a job), and activity, the change timeline
built by the worker consumer platform.contacts.activity-timeline-v1 from
the plugin's own events (event id, action, version, actor, time; never
values). Name and email search keys are computed in Rust (migration 0007).
All tables are tenant-first with forced RLS and a restrictive
app.plugin_id = 'platform.contacts' policy (migration 0005).
Custom field types are text, textarea, email, phone, number,
boolean, date, datetime, select, multi_select and json.
Extensions (ADR 0012). Other plugins add simple fields (text,
number, boolean, date, choice) to platform.contacts.person and
platform.contacts.organisation. Values live in extensions keyed by
plugin and then field key, each field with its own read and write
permission; the kernel extension service validates every write and
Contacts applies it in its transaction. The loyalty fixture is the
reference extender.
Behaviour. Create, update (whole-record PUT with expected_version),
archive, delete to the recycle bin and undelete; a purge job removes
records 15 days after deletion and unlinks people from purged
organisations as a system change. Lists filter by name (substring of the
name key), email (exact, case-insensitive), organisation, extension field
and status (active, archived, all, deleted), sorted by name,
creation or update.
Permissions. contacts.people.read|write,
contacts.organisations.read|write, contacts.settings.manage (custom
field definitions), and contacts.people.custom-fields.read /
contacts.organisations.custom-fields.read. Write covers create, update,
archive and delete of any record. The two custom-field permissions are
checked only by the web app (apps/web/src/contacts); the API returns
custom fields to every reader.
Events. Fourteen platform.contacts.*.v1 types: person and
organisation -created, -updated, -archived, -deleted,
-undeleted, and custom-field definition -created, -updated,
-disabled, -archived. Payloads carry only the public ID (or the
definition id and target) and the version. Audit entries name the action
and never values.
API. /api/v1/workspaces/{id}/contacts/people and
.../organisations (list, create, get, PUT, DELETE, /archive,
/undelete, PATCH /extensions, GET /activity),
.../contacts/custom-fields (create, list per target, get, update,
/disable, /archive), and the prototype
.../odata/contacts/people with its $metadata.
UI. Hand-written React pages in apps/web/src/contacts (people and
organisation directories, person and organisation detail, person form)
driven by the plugin's page and resource metadata (plugins/contacts/ui),
with ADR 0012 field zones on the person pages and workspace
customisation overlays (ADR 0011 §4). The shell imports these pages
directly.
Devices. Contacts does not reach phones. Device replicas (ADR 0024) carry engine objects only, so no Contacts data is synced today.
Tests. The store conformance suite runs on both adapters
(plugins/contacts/backend/tests); scripts/test-contacts-api.sh,
scripts/test-plugin-extensions-acceptance.sh,
scripts/test-plugin-lifecycle-acceptance.sh,
apps/worker/tests/contacts_worker_postgres.rs,
tests/security/tenant_isolation.sql and tests/contacts-metadata cover
the API, extensions, lifecycle, worker and isolation.
Found while investigating. PostgreSQL migration 0004 limits
p_contacts.activity.action to created, updated and archived, but
the worker also writes deleted and undeleted (the SQLite table has no
such check). Those inserts fail as retryable on PostgreSQL. This is a
separate defect to fix on the current store; the migration in §2 must not
depend on those rows existing.
Decision¶
Contacts moves onto the object engine. People and organisations become plugin-declared engine objects; existing data is copied per workspace by a verified, restartable, reversible migration; the public REST API and events stay as a thin compatibility layer for a deprecation period; the UI becomes the generic engine pages. Afterwards the plugin owns metadata and a little translation code, and no tables.
1. Target model¶
Contacts declares two objects through [[objects]] in its manifest. Their
key prefixes stay per and org, which ADR 0015 §3 already names as the
plugin prefixes, so every existing public ID stays valid.
| Object | Label / plural | name_label |
Prefix | Sharing | History |
|---|---|---|---|---|---|
platform.contacts:person |
Person / People | Name | per |
read_write |
tracked |
platform.contacts:organisation |
Organisation / Organisations | Name | org |
read_write |
tracked |
read_write is the starting value because it matches today: every member
with object access sees and edits every record. Workspaces may tighten it
afterwards (ADR 0033 §2).
Fields (API names platform.contacts:<name>):
| Object | Field | Type | Flags |
|---|---|---|---|
| Person | first_name |
text | max_length 120, history tracked |
| Person | last_name |
text | required, max_length 120, history tracked |
| Person | standard name |
composed from first_name and last_name (gap G17) |
searchable, as every name |
| Person | email |
indexed, searchable, max_length 320 (see gap G8) |
|
| Person | telephone |
phone | searchable |
| Person | organisation |
lookup to platform.contacts:organisation |
delete_behaviour = "clear", history tracked |
| Person | tags |
text list (gap G7) | indexed |
| Organisation | standard name |
(name) | searchable |
| Organisation | email |
indexed, searchable | |
| Organisation | telephone |
phone | searchable |
The person → organisation relation is an ordinary lookup, so the
organisation page gets a People related list (ADR 0028) and the query
language traverses it (platform.contacts:organisation.name).
Person's name is split now. Person gains first_name and last_name,
and its standard name is composed from them (G17): the first name, a
space and the last name, or the last name alone. Members edit the two
parts and never the name itself, which stays the field that search, lookups,
list titles and the query language use, so nothing that reads a record's
name changes. Last name is required, as a person always has a name today.
The migration splits each full_name by one rule, also used by the v1 API
(§3) for writes that send full_name: trim and collapse runs of white space
to one space; a name of one word becomes the last name with no first name;
otherwise the last word is the last name and everything before it the first
name. The rule is wrong for some names ("Ludwig van Beethoven", names
written family name first), so the dry run lists every name of three or
more words, and administrators may correct the parts through the current
API before cutover or on the engine afterwards. It does not block the
migration. A part longer than 120 characters does block it, as do the
other refusals in §2.
Engine gaps¶
The engine cannot yet express everything Contacts does. Each gap is either engine work that ships first (slice 1) or an accepted behaviour change.
| # | Gap | Plan |
|---|---|---|
| G1 | Archiving. records.archived_at exists, but the engine has no archive operation, list filter or event. |
Engine first: archive and unarchive operations (an edit, needing edit access), status=archived and status=all on lists, archived_at in the query language, platform.objects.record-archived.v1 and -unarchived.v1, and a lifecycle entry in history. Unarchive is new for Contacts. |
| G2 | Recycle-bin purge. Engine records in the bin stay forever; Contacts purges after 15 days (ADR 0014 §5). | Engine first: a per-workspace purge job with the same 15-day window and batch audit, removing pivots, history and change-log rows with the record. |
| G3 | Restoring cleared lookups. Deleting an engine record clears lookups to it at once, as members' edits, and undelete does not put them back. Contacts keeps the people → organisation link until the purge. | Engine first: undeleting a record restores the lookup values its deletion cleared, where the referencing record has not changed that field since (Salesforce behaviour). Accepted change: the clear itself, which moves each person's version and emits person-updated when their organisation is deleted. |
| G4 | Importing with preserved identity. The engine keeps an assigned id only from the device range (ADR 0031), stamps the caller and now, starts version 1, and runs validation rules and automations. | Engine first: a kernel-only migrator caller (like ObjectCaller::plugin_installer, never reachable from a request) that writes a record with a given server-range public id and internal id, stamps, version, archive and delete state and owner; writes the change log but no per-record outbox events, runs no automations or validation rules, and leaves one audit entry per batch; raises the object's record_sequence to at least the source counter; and appends backdated history entries with a system source. |
| G5 | Field-level permissions. Extension fields have their own read and write permissions, enforced by the kernel; the engine has none (#316). | Engine first: a field may name a read_permission and write_permission (permission ids); without them a field is hidden from reads, queries, search results, history, replicas and the change feed, and refused on writes. Role-based field-level security (#316) can build on the same check later. |
| G6 | Fields one plugin adds to another plugin's object. ADR 0033 §2 lets a plugin declare fields only on its own objects. | Engine first: the installer accepts ADR 0012 [[extensions.fields]] whose host resource maps to an engine object (§2), creating fields in the extending plugin's namespace (example.loyalty:tier, origin plugin, owner the extender), suspended with the extender, kept on removal for the ADR 0012 retention window, then retired. Extension types map to text, number, boolean, date and picklist. |
| G7 | Free-form tags. A multi-select picklist needs a fixed option list (at most 200) that only the plugin may change on a plugin field. | Engine first: a domain-neutral text list field type: up to 50 distinct values of up to 80 characters, compared without case, indexed per value for INCLUDES filters. The dry run reports tags beyond those limits. |
| G8 | Long email addresses. Engine email values are limited to 255 characters; Contacts allows 320. | Engine first: let email fields declare max_length up to 320. |
| G9 | Field governance metadata. Custom fields carry data_classification, purpose, retention_days and encrypted; Contacts requires a purpose for non-public fields and encrypted for sensitive ones. Engine fields carry none of this. |
Engine first: the same four properties, with the same rules, on every engine field (domain-neutral; every object benefits). They stay declarations, as today: nothing enforces retention or encryption yet. |
| G10 | Customising one object. contacts.settings.manage lets a role manage Contacts' custom fields only; the engine needs objects.manage, which covers every object. |
Engine first: an object permission flag customise (add, change and retire custom fields, validation rules, quick actions and automations on that object), granted per role like the other flags. objects.manage keeps implying it. |
| G11 | Keeping plugin objects dormant. Installing a plugin's objects resumes them when the plugin is enabled. Contacts' objects must exist but stay out of service until a workspace is migrated. | Engine first: an object a manifest marks dormant = true is installed suspended, and only its plugin's explicit resume (the cutover, §3) brings it into service. |
| G12 | Substring name search. Contacts' search matches anywhere in the name; engine global search matches term prefixes. |
No gap: the compatibility list maps search to name LIKE '%…%' in the query language, which scans one object in one workspace (ADR 0015 consequences). Global search in the shell uses prefixes, as for every object. |
| G13 | JSON custom fields. The engine has no JSON type. | Accepted change: a json custom field becomes a custom: long-text field holding the canonical JSON text. The compatibility API parses it back, so v1 clients see no change; the engine API and pages show text. |
| G14 | Disabled custom fields. The engine's field lifecycle is active or deleted (retired, values kept). | Accepted change: disabled and archived definitions become retired fields. Their values stay in the record document, hidden as today's archived values are; a disabled field can no longer be read back. |
| G15 | Formula fields in manifests. Not declarable (roadmap). | Not needed: Contacts declares none. |
| G17 | A name composed from fields. An engine object's name is a stored field that members write directly. | Engine first: an object may declare name_from (two or three of its own text fields and a separator). The engine then computes the name on every write from those fields, refuses writes to the name itself (objects.name_composed), and recomputes every record's name in a batch job when the declaration changes. The name stays a stored, indexed, searchable column, so reads do not change. |
| G18 | Starting allowlist values for an optional plugin's objects. A manifest may name only objects of plugins it depends on (ADR 0033 §2), and an upgrade never overwrites an installed allowlist. | Engine first: a manifest may declare optional_dependencies (plugin ids with a version range). A related-to or lookup field may then list objects of those plugins in its starting allowlist. Such an entry is added to the field when the named object first becomes active in the workspace, including on installations that already exist, and is tracked like an offered related action (ADR 0033 §2): added once per field, never re-added after an administrator removes it, and never required for the field to work. An optional dependency grants nothing; it only allows naming. |
| G16 | Workspace page layouts. Contacts pages carry field zones and published customisation overlays; generic engine pages have no layouts yet. | Handled by the UI slice (§3): a workspace with published overlays or arranged field zones keeps the Contacts pages until the engine has record layouts. |
Unique custom fields compare without case in the engine (ADR 0015 §2); Contacts compares exact JSON values. The dry run reports values that collide under the engine rule and the unique fields whose type the engine cannot make unique (only text, email, phone, URL and number can be); both block the migration until an administrator resolves them through the current API.
2. Data migration¶
A kernel migration tool, contacts-to-engine, runs per workspace on both
stores. It is kernel code because it reads the Contacts tables and writes
engine tables through the G4 migrator caller; it runs in the Contacts
execution context for reads and the engine context for writes, with
app.tenant_id set transaction-locally, so forced RLS and the restrictive
plugin policies apply as for any other code. It is exposed as an
administrator operation (POST .../contacts/migration with dry_run,
start, status, rollback), needing platform.plugins.manage, and in
the admin CLI.
What is copied¶
| Source | Target |
|---|---|
people.id, public_id; organisations.id, public_id |
the engine record's internal and public id, unchanged |
full_name |
first_name and last_name, split by the rule in §1; the standard name is composed from them |
name (organisation) |
the standard name |
email, telephone, organisation_id, tags |
the plugin fields of §1; the lookup by internal id |
version, created_at, created_by, updated_at, updated_by, touched_at |
the same standard columns, unchanged |
archived_at, deleted_at |
the same; recycle-bin records stay in the bin with their deletion time, so the G2 purge keeps the 15-day window |
| (no owner) | owner_id = created_by when that user is still a workspace member, otherwise no owner; the dry run counts records left without an owner |
public_id_counters |
record_sequence of each object, raised to at least the counter |
custom_field_definitions |
custom: fields on the plugin objects: foo__c becomes custom:foo (ADR 0015 §3, #294), keeping the definition id as the field id, label, description, required, unique, indexed, options and the G9 governance properties; validation_schema limits become max_length where the type has one, and workspace validation rules otherwise (LEN(custom:foo) >= 3, custom:size <= 10) |
custom_fields values |
the record document under the new API names |
extensions values |
the record document under the extender's field API names (example.loyalty:tier), the fields created first by the G6 installer |
activity |
backdated history entries (G4): created, deleted and undeleted as lifecycle entries, updated as a change with no field values ("details not recorded"), archived as a change of archived_at; actor and time kept, source system |
Custom field types map text → text (long text when any value or the
declared max_length exceeds 255), textarea → long text, email,
phone, number (scale from the data, at most 8, rounding reported),
boolean and date → the same, datetime → date-time, select →
picklist, multi_select → multi-select picklist, json → long text (G13).
Extension fields become the extending plugin's engine fields (G6),
rather than workspace custom: fields or a side store. ADR 0012 §3
already keeps simple extension values with the host record, under the
host's tenancy, version and audit; on the engine that is simply a field in
the extender's namespace on the host object, with its own permissions
(G5) and the extender's lifecycle. Extending plugins change nothing:
Contacts' manifest maps its resource ids platform.contacts.person and
platform.contacts.organisation to the two objects, and the kernel
extension service resolves declarations and writes through the engine.
Values that ADR 0012 keeps in the extender's own tables are untouched.
Audit entries and outbox events already written stay where they are; the migration does not rewrite evidence.
How it runs¶
- Dry run. Reads everything, writes nothing, and reports per object:
record counts by state, the field mapping, every value the engine would
refuse (phone format on
telephone, which Contacts never validated; lengths; tags beyond G7's limits; case-insensitive unique collisions; unique fields of non-unique types), roles whose grants change shape (§4), published page customisations (G16), and an estimated duration. Any refusal blocks the start until fixed through the current API. - Copy while live. Batches of 1,000 records in id order, organisations
before people, each batch one engine transaction that inserts or
replaces by id and records a checkpoint in a Contacts-owned migration
state row (
p_contacts.engine_migration, one per workspace: phase, checkpoint, cutover time, rollback deadline, checksums). The copy is idempotent and restartable: rerunning skips records whose checksum already matches and continues after the checkpoint. - Catch up. Repeated passes copy records whose
touched_atmoved since the previous pass and remove engine records whose source was purged, until a pass finds fewer than 100 changes. Custom-field definition changes do not touch records, so every pass also compares each definition (type, label, required, unique, indexed, options, validation, governance properties, lifecycle state) with its engine field and re-applies any that differ, before copying records. - Freeze and cut over. Contacts writes for the workspace, including
custom-field definition and settings writes, answer
503 contacts.migratingwithRetry-After; reads continue from the old store. A final catch-up pass and the verification run, then the phase becomesengineand the dormant objects are resumed (G11), in one transaction on SQLite and as ordered, idempotent steps on PostgreSQL like the ADR 0033 §2 install. Only Contacts writes in that workspace pause, normally for seconds; the dry run's estimate decides whether a workspace needs a scheduled window. - Verify. Counts per object and state must match, and a per-record
checksum over a canonical form (ids, name, every field value, stamps,
version, states, owner rule; for people, the normalised
full_nameagainst the composed name) computed by the same Rust code on both sides must agree, as must an aggregate digest over the sorted ids. The same applies to definitions: a per-definition checksum over the canonical metadata listed in step 3 must match its engine field. Verification failing leaves the phase unchanged and writes unfrozen.
Reversal¶
For 30 days after cutover (the ADR 0012 retention window) an administrator
may roll a workspace back. The tool freezes writes, copies engine records
touched since cutover back to the old tables (new records keep their ids;
the old counters are raised past them), marks records deleted or purged
on the engine as deleted, re-creates definitions for custom: fields
added since cutover when their type maps back, suspends the objects again
and sets the phase back to legacy. A rollback that would lose data (a
field type with no Contacts equivalent, or values in fields added by
extenders after cutover) is refused with a report unless the administrator
accepts the listed losses. History, shares and owners created on the
engine are kept with the suspended objects, so migrating again later picks
them up. The old store is never written after cutover except by a rollback,
and the old activity consumer keeps projecting the compatibility events
(§3), so a rolled-back workspace keeps a complete timeline. After the
window the workspace's old rows are deleted (slice 7).
3. Compatibility¶
The REST API and events stay as v1 over the engine, deprecated, rather than being versioned. A v2 would only repeat the engine's own record API, which is the API new clients should use; keeping v1 working unchanged lets existing integrations move on their own schedule.
- REST. After cutover the Contacts routes serve the engine: the
plugin's handlers call the object service as the member (so object
permissions, sharing, field permissions, validation rules and automations
apply), translate field names (
full_name,custom_fields.foo__c,organisation_id), turn a whole-recordPUTinto a full update, mapstatusand sorts onto engine lists and the query language, serve/activityfrom history lifecycle entries, and map engine error codes to the existing Contacts codes. List cursors issued before cutover answer400 contacts.cursor_invalid, and clients start again. The custom-field routes managecustom:fields on the plugin objects under the G10customiseflag. Responses carryDeprecationandSunsetheaders once the compatibility layer ships. - Events. Engine events are the source of truth for migrated
workspaces. A Contacts worker consumer translates
platform.objects.record-*.v1,-archived.v1and field events for its two objects into the same fourteenplatform.contacts.*.v1types, with the same payloads (public ID and version), the engine event as causation and the same correlation and actor. It writes through the outbox in its own transaction, so delivery stays at least once and ordered per record. - Deprecation timeline. Removed no earlier than six months after the compatibility
layer ships and not before the platform's 0.3 contract: the v1 Contacts
routes, the prototype OData endpoint, and the
platform.contacts.*.v1events, which consumers replace withplatform.objects.*events filtered by object. The removal is a Contacts major version. Until then the plugin stays in the0.1line so extenders'>=0.1.0,<0.2.0dependency ranges keep working.
The UI becomes the generic engine pages. Contacts keeps no custom pages
over engine data: the object home, record page and form of ADR 0011 §3
(apps/web/src/objects) already serve plugin objects, and keeping custom
pages would mean maintaining a second set of record screens forever. For a
migrated workspace the navigation entries come from the objects
(in_navigation), People and Organisations open the generic pages, and the
person page gets sharing, history, related lists, quick actions and the
Activity timeline. A workspace with published customisation overlays or
arranged field zones on Contacts pages (G16) keeps the Contacts pages,
working through the compatibility API, until engine record layouts exist;
the dry run lists such workspaces. Once no workspace needs them, the
Contacts pages and the shell's direct imports of them are removed, which
also puts the shell back on contribution-only navigation.
4. Permissions¶
At cutover each role's Contacts permissions become object permissions on the two objects, so nobody loses or gains record access:
| Contacts permission | Object permission on the matching object |
|---|---|
contacts.people.read |
Person: read |
contacts.people.write |
Person: read, create, edit, delete, view all, modify all |
contacts.organisations.read |
Organisation: read |
contacts.organisations.write |
Organisation: read, create, edit, delete, view all, modify all |
contacts.settings.manage |
both: customise (G10) |
contacts.people.custom-fields.read |
read permission of Person's custom: fields (G5) |
contacts.organisations.custom-fields.read |
read permission of Organisation's custom: fields (G5) |
- Writers need modify all because ADR 0016 §1 lets only owners, the
hierarchy above them and modify-all holders delete, while Contacts lets
every writer delete any record. With the
read_writemodel this reproduces today exactly. It also lets writers manage shares and transfer owners, which do not exist today; the dry run names these roles. A workspace that later tightens the sharing model must review these grants, which the Object Manager will point out. - A role with write but not read gains read, because engine edit implies read; the dry run lists such roles.
- The custom-field read permissions become server-enforced. Today only the web app hides custom fields, so API callers without them lose API access to custom field values; the dry run lists such roles.
- Extension fields keep their own permissions through G5.
- After cutover the
contacts.*permissions no longer decide anything in that workspace; role screens mark them as replaced. They leave the manifest when the compatibility layer is removed. - The
contacts.basicentitlement still decides whether the workspace may enable the plugin (ADR 0006); it never becomes a permission.
5. Plugin boundary¶
After a workspace is migrated, the Contacts plugin owns:
- its manifest: the two objects and their fields, the resource-to-object mapping for extenders, navigation, permissions during deprecation, and the dormant flag;
- the compatibility REST handlers and the event-translating consumer, both calling only the engine and the outbox, as any plugin may;
- no tables.
Applied migrations are history, so plugins/contacts/migrations keeps
0001 to 0009 and gains a final migration (and a SQLite tenant step) that
drops the p_contacts tables once no workspace is in legacy phase or inside its
rollback window. The per and org rows in id_prefix_registry stay,
because the prefixes remain Contacts'. Retiring the old tables, the ContactsStore port, both
adapters, the conformance suite and the purge and cursor jobs is slice 7,
a later release. When the compatibility layer is removed too, Contacts
becomes a manifest-only plugin like Activities, with
capabilities.database = false.
6. Devices¶
Contacts reaches no device today. Once a workspace is migrated, people and
organisations sync to phones as ordinary engine replicas (ADR 0024): pulled
from the change log under sharing and field permissions, pushed as
composite requests, created offline with device-range ids (ADR 0031) under
per and org, and dropped from the device by the revocation set when
access is lost. The migrator's change-log entries (G4) let replicas and
change-feed clients pick up migrated records without per-record events. A
device's contacts-import capability (ADR 0024 §6) targets
platform.contacts:person.
7. Activities follow-up¶
Activities declares Contacts as an optional dependency (G18) and names
platform.contacts:person in Who and both Contacts objects in Related
to. Activities still works without Contacts. When a workspace's Contacts
objects come into service at cutover, those entries are added to the two
fields once, which also gives people and organisations Log a call and the
Activity timeline. An administrator who removes them keeps them removed.
The cutover's completion report says what was added.
8. Delivery slices¶
Each slice ships alone and can be reverted without touching data written by earlier slices.
- Engine gaps G1 to G11, G17 and G18, each its own change with both stores, the API and conformance tests. They serve every object and change nothing for Contacts.
- Dual definitions. Contacts' manifest declares the two dormant objects and the resource mapping; installing creates them suspended and empty in every workspace. Reverting the manifest leaves suspended, empty definitions.
- Migration tool with dry run, copy, catch-up, verification and rollback, on both stores, and acceptance runs on fixture workspaces. The cutover step is present but refused until slice 5.
- Compatibility layer. The v1 REST handlers over the engine and the
event translator, exercised by running
scripts/test-contacts-api.shand the extension and lifecycle acceptance scripts against a migrated workspace. Not reachable in production until slice 5. - Per-workspace cutover. The phase flag decides which store serves a workspace; cutover and rollback become available to administrators. Off by default; rolled out workspace by workspace.
- UI. Generic engine pages for migrated workspaces without page customisations, Activities' optional dependency of §7, and the removal of the Contacts pages once no workspace needs them (G16).
- Retire the typed store after every workspace has passed its rollback window: delete old rows per workspace, then a release drops the tables, the store port, the adapters and the old jobs. Removing the v1 routes and events follows the §3 timeline.
9. Alternatives considered¶
- Keep typed storage forever. No migration risk, but every engine service stays unavailable to the most used objects or has to be rebuilt for one store on two backends, Activities cannot point at people, and two storage models live on indefinitely. Rejected; ADR 0015 §6 already made the engine the default.
- Big-bang migration of every workspace in one release. Simpler code, but one failure blocks every workspace, a rollback is all or nothing, and large workspaces force downtime on everyone. Rejected for per-workspace phases.
- A sync bridge keeping both stores current in both directions. It avoids a cutover, but it needs conflict resolution between two version counters, duplicates every event, makes "which store is right" a permanent question, and keeps the typed store alive. Rejected; the one-way copy with a bounded reverse copy gives reversibility without it.
- Workspace
custom:fields for extension values. Simpler for the engine, but it hands another plugin's fields to the workspace, loses their permissions and their removal lifecycle, and breaks ADR 0012. Rejected for G6. - Versioning the Contacts API as v2. It would duplicate the engine's record API. Rejected for a deprecated v1 over the engine.
10. Risks and consequences¶
- Engine work comes first. Eleven gaps must ship before any data moves; most are small, but G4 (the migrator), G5 (field permissions) and G6 (cross-plugin fields) touch security-relevant paths and need careful review and tests, including forced RLS and evidence checks.
- The migrator is a powerful caller. It writes ids, stamps and states no member can. It must stay kernel-only, workspace-scoped, audited per batch, and unreachable from requests and plugins.
- Behaviour changes that members and integrations will notice: an owner on every record, deleting an organisation clears its people's link as an edit (restored on undelete, G3), stricter phone validation, case-insensitive uniqueness, JSON custom fields as text in the engine API, disabled custom fields no longer readable, server-enforced custom-field read permissions, and invalidated list cursors at cutover.
- Performance. Contacts lists used typed columns; engine lists use the
record table and pivots.
name,emailandtagsare indexed, and a substring name search scans one object in one workspace. The migration acceptance runs include the 10,000-record measurement of ADR 0024 and the plans intests/performanceon engine tables. - Two paths during deprecation. Until slice 7 both stores exist and the compatibility layer must be tested on both phases; the acceptance scripts run against a legacy and a migrated workspace.
- Gains. Once migrated, people and organisations get sharing, the query language, validation rules, automations, quick actions, related lists, the Activity timeline, history with sources, global search, reports, bulk jobs and API clients, change data capture and device sync, and the platform has one storage model.
Open questions¶
The review settled the first four questions (see Status). One stays open:
- Are a 30-day rollback window and a deprecation of at least six months (and not before the 0.3 contract) right? They are accepted provisionally and must be confirmed before the cutover slice (5) ships.