Package entry-linked resources beyond entities (full EntryLink type map)

[drernie]

Summary

Follow-on to #143 (Package Entities). When packaging a notebook entry, the entities it references live in entry.days[].notes[].links[]. But links[] carries 18 possible resource types, not just entities. This issue scopes which of the other link types are package candidates, and which have webhook events (so they could also be packaged independently, à la #143 behavior 2).

The canonical link-type set

The set is a closed enum — EntryLink.type in the Benchling OpenAPI spec (test/openapi.yaml, EntryLink schema). All 18 tokens:

link, user, request, entry, stage_entry, protocol, workflow,
custom_entity, aa_sequence, dna_sequence, batch, box, container,
location, plate, insights_dashboard, folder, sql_dashboard

Note: many resources you'd expect are not linkable inline (no @-mention as an EntryLink): dna_oligo, rna_oligo, mixture, assay_run, assay_result, individual workflow_task. They reach notebooks via structured note parts / inventory tables instead.

What's actually in the wild (quilt-dtt tenant, 137 entries scanned)

Only three types observed: custom_entity (21), sql_dashboard (7, axdash_), link (120 — plain external URLs, no Benchling ID). So real-world density is low and entity-dominated, but the long tail matters for completeness.

Package candidates — full table

link type	id prefix	fetch endpoint (packageable?)	webhook event
custom_entity	bfi_	GET /custom-entities/{id} — yes	v2.entity.registered (registration only)
dna_sequence	seq_	GET /dna-sequences/{id} — yes	v2.entity.registered
aa_sequence	prtn_	GET /aa-sequences/{id} — yes	v2.entity.registered
batch	bat_	GET /batches/{id} — yes	v2.entity.registered
container	con_	GET /containers/{id} — yes (inventory)	none
box	box_	GET /boxes/{id} — yes (inventory)	none
plate	plt_	GET /plates/{id} — yes (inventory)	none
location	loc_	GET /locations/{id} — yes (no webURL)	none
entry	etr_	GET /entries/{id} — yes	v2.entry.created, .updated.fields, .updated.reviewRecord
request	req_	GET /requests/{id} — yes	v2.request.created, .updated.fields, .updated.status
workflow (task group)	wfgrp_	GET /workflow-task-groups/{id} — yes	v2.workflowTaskGroup.created, .mappingCompleted, .updated.watchers
stage_entry	etr_-like	v2-alpha only — uncertain	v2-alpha.stageEntry.*
protocol	—	no GET-by-id endpoint — not packageable	none
user	ent_	GET /users/{id} — metadata only	none
folder (legacy)	lib_	GET /folders/{id} — metadata only	none
sql_dashboard / insights_dashboard	axdash_	NO read API — pure Insights/analytics UI artifact, queries run against the Warehouse only	none
link (external URL)	n/a	n/a — webURL is the literal URL	n/a

Conclusions

• Confidently packageable (stable GET-by-id, first-class records): custom_entity, dna_sequence, aa_sequence, batch, container, box, plate, location, entry, request, workflow (task group). Use :bulk-get variants to batch-fetch.
• Metadata-only pointers (low value to package as records): user, folder.
• NOT packageable — no API exists: sql_dashboard / insights_dashboard. Dashboard definitions/results are only reachable via the read-only Warehouse (separate SQL surface), not REST. The closest path is manually creating a Dataset from a dashboard query (GET /datasets/{id}), which is not reachable from the axdash_ link ID. Recommend: skip dashboards; the entry already preserves the webURL deep link.
• Uncertain: stage_entry (v2-alpha only), protocol (linkable but no read endpoint in stable spec) — verify against the deployed tenant's API version before relying on them.

Independently-eventable resources (could be packaged on their own, like #143 behavior 2)

Resources whose link type also has a creation/update webhook: entities (v2.entity.registered), entry, request, workflow task group. Inventory (container/box/plate/location) is packageable-on-reference but has no events, so it can only be captured via an entry, not independently.

For event-mapping completeness, these fire events but are not inline-linkable: assay_run (v2.assayRun.*), individual workflow_task (v2.workflowTask.*), workflow_output (v2.workflowOutput.*), automation transforms. (assay_result has a GET endpoint but no webhook.)

Suggested scope

1. Implement entity packaging (Package Entities #143) first — highest density, clear value.
2. Generalize the link walker to handle the full packageable set with a type → endpoint dispatch map + dedup + :bulk-get.
3. Explicitly exclude sql_dashboard/insights_dashboard/protocol/user from record-fetching; keep their webURL as a reference only.
4. Relates to assay results #68 (assay results) — assay_run/assay_result are a separate note-part mechanism, not links[].

---

Grounding: EntryLink enum verified in test/openapi.yaml; tenant scan via quilt-dtt (137 entries); event strings from docs.benchling.com/docs/events-reference.