ADR 0015: Read-only connectors, agent service identity and ELN content canonicalisation

Status: Accepted
Date: 2026-09-14
Deciders: Founder

Context

The founder chose one ELN (Benchling) and one QMS/SOP source (Veeva Vault QualityDocs) for a mid-size biotech pilot. The ELN’s only notebook write path is early access with breaking-change notices; the QMS is the controlled record for SOPs; regulators expect agent changes to be attributable to the agent and separately approved by a person. No vendor offers a public developer sandbox.

Decision

Both connectors are read-only (write_policy = read_only). Agent drafts stay in Trovensa as proposals; scientists carry them into the notebook themselves with the provenance footer.
Agents act under a service identity agent:<agent_key>@<org_id> recorded as actor_agent_id, with the approving person recorded as approved_by_user_id; connectors use a per-connection service credential (client credentials or an integration user) with a minimal profile.
ELN entry versions are external_version = <payload_hash>@<modifiedAt> where the hash is sha256 of canonical JSON of the entry content (days in order, notes in order, table cells row-major, mentions expanded to type:id, attachments as id:sha256); target_ref = benchling:entry:<id>@<hash prefix>.
Inbound events arrive at POST /hooks/{provider_id}/{connection_id}, are verified before parsing, stored in webhook_deliveries and treated as pointers; the canonical object is re-fetched. Launch-from-notebook uses one-time launch_ids with a 10-minute expiry.
Fake servers with the same contract (Benchling, Vault) carry CI and the local demo until partner credentials arrive.

Consequences

Programs stay isolated by connection.scope_rules (project ids, document types) enforced in Trovensa even where the vendor token is tenant-wide.
Partner sandbox provisioning is a named blocker, not a gate; the demo path J1 needs no partner.

Alternatives considered

Delegated user credentials for writes: makes the vendor audit trail name a human for an agent’s change; rejected with read-only connectors.
Vendor MCP servers: protocol revision and audit attribution unverified; reference-only.
Org-level connections: a scope-model change; connections stay program-scoped in phase 2 (decision 0018).

Follow-ups

Notebook write-back through a stable versioned API when the vendor ships it (R3, feature-flagged).