feat: full EntryLink type map + classify_links; fix entity set (#389)

Generalize the discovery layer from entities-only to the full EntryLink enum
(18 types from test/openapi.yaml), per #389.

- classify_links(entry): surfaces ALL note links, each labeled with a
  LinkCategory (entity/inventory/reference/metadata/not_packageable/uncertain/
  external/unknown). Consumers filter, e.g. `r.is_packageable`. Unknown/future
  types surface as UNKNOWN rather than being silently dropped.
- LINK_TYPE_CATEGORY: type -> category for all 18 tokens; PACKAGEABLE_CATEGORIES.
- Fix entity set: ENTITY_LINK_TYPES now {custom_entity, dna_sequence,
  aa_sequence, batch}. Adds `batch` (a real registry entity, was missed);
  drops dna_oligo/rna_oligo (NOT EntryLink types -- can't appear as note links).
- spec/entry-link-types.json: human-facing reference map (category, packageable,
  id prefix, GET endpoint, webhook events) for all 18 types, plus the
  not-inline-linkable resources. A test asserts its categories match the module
  so it can't drift.

26 unit tests; black/isort/pyright clean.

Refs #143 #389 #68

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: drernie

docker/src/entry_references.py

@@ -1,38 +1,82 @@
 """Extract typed references out of a Benchling entry's structured data.
 
-A Benchling entry can point at other Benchling objects in three places:
+A Benchling entry points at other Benchling objects in three places:
 
-1. Note links -- ``days[].notes[].links[]``, each ``{id, type, webURL}``. Entity
-   mentions appear as ``custom_entity`` / ``dna_sequence`` / ``aa_sequence`` /
-   ``dna_oligo`` / ``rna_oligo``; the same list also carries non-entity types
-   (e.g. ``sql_dashboard``), so callers must filter by ``type``.
+1. Note links -- ``days[].notes[].links[]``, each ``{id, type, webURL}``. ``type``
+   is a closed enum (``EntryLink.type`` in the Benchling OpenAPI spec) of 18
+   tokens spanning entities, inventory, references, dashboards, and plain
+   external hyperlinks -- see :data:`LINK_TYPE_CATEGORY`.
 2. Entity-link fields -- ``fields[name]`` whose ``type`` mentions ``entity``,
    carrying one or more entity IDs directly in ``value``.
 3. Results tables -- ``results_table`` notes carrying an ``assayResultSchemaId``
    (the discovery site for assay results, issues #68/#69).
 
 This module is pure: it operates on the entry dict already fetched by
 ``EntryPackager`` and makes no Benchling API calls. Resolving each reference to a
-full record (``get_by_id`` / ``bulk_get``) is the caller's job.
+full record (``get_by_id`` / ``bulk_get``) is the caller's job; this layer only
+discovers and classifies what an entry points at.
 
-Shared discovery layer for entity packaging (#143) and assay results (#68/#69).
+Shared discovery layer for entity packaging (#143), the full entry-linked
+resource map (#389), and assay results (#68/#69).
 """
 
 from dataclasses import dataclass
+from enum import Enum
 from typing import Any, Dict, Iterator, List, Optional, Tuple
 
-# Note-link / field ``type`` values that denote a registry entity. Used to keep
-# entity references out of the non-entity links (dashboards, etc.) that share
-# the same ``links[]`` array.
-ENTITY_LINK_TYPES = frozenset(
-    {
-        "custom_entity",
-        "dna_sequence",
-        "aa_sequence",
-        "dna_oligo",
-        "rna_oligo",
-    }
-)
+
+class LinkCategory(str, Enum):
+    """How a note-link type relates to packaging (per #389 conclusions)."""
+
+    ENTITY = "entity"  # registry entity; GET-by-id + v2.entity.registered event
+    INVENTORY = "inventory"  # packageable via GET-by-id; no webhook events
+    REFERENCE = "reference"  # packageable; has its own create/update events
+    METADATA = "metadata"  # GET works but low value to package as a record
+    NOT_PACKAGEABLE = "not_packageable"  # no read API (dashboards, protocol)
+    UNCERTAIN = "uncertain"  # endpoint depends on tenant API version; verify first
+    EXTERNAL = "external"  # plain http(s) hyperlink ("link"); no Benchling ID
+    UNKNOWN = "unknown"  # type not in the known enum -- surfaced, not dropped
+
+
+# EntryLink.type -> category. Covers all 18 enum tokens from test/openapi.yaml.
+# Unknown/future tokens fall through to LinkCategory.UNKNOWN via classify_link_type.
+LINK_TYPE_CATEGORY: Dict[str, LinkCategory] = {
+    # entities (eventable via v2.entity.registered)
+    "custom_entity": LinkCategory.ENTITY,
+    "dna_sequence": LinkCategory.ENTITY,
+    "aa_sequence": LinkCategory.ENTITY,
+    "batch": LinkCategory.ENTITY,
+    # inventory (packageable on reference, no events)
+    "container": LinkCategory.INVENTORY,
+    "box": LinkCategory.INVENTORY,
+    "plate": LinkCategory.INVENTORY,
+    "location": LinkCategory.INVENTORY,
+    # references (packageable, own events)
+    "entry": LinkCategory.REFERENCE,
+    "request": LinkCategory.REFERENCE,
+    "workflow": LinkCategory.REFERENCE,
+    # metadata-only pointers
+    "user": LinkCategory.METADATA,
+    "folder": LinkCategory.METADATA,
+    # no read API exists -- keep the webURL as a reference only
+    "sql_dashboard": LinkCategory.NOT_PACKAGEABLE,
+    "insights_dashboard": LinkCategory.NOT_PACKAGEABLE,
+    "protocol": LinkCategory.NOT_PACKAGEABLE,
+    # endpoint depends on tenant API version (v2-alpha) -- verify before relying
+    "stage_entry": LinkCategory.UNCERTAIN,
+    # plain external hyperlink (no Benchling id)
+    "link": LinkCategory.EXTERNAL,
+}
+
+# Note: dna_oligo / rna_oligo / mixture / assay_run / assay_result / workflow_task
+# are NOT EntryLink types -- they cannot appear as note links. They reach an entry
+# via structured note parts / inventory tables, not links[].
+
+# Categories whose resources can be fetched as a record via GET-by-id.
+PACKAGEABLE_CATEGORIES = frozenset({LinkCategory.ENTITY, LinkCategory.INVENTORY, LinkCategory.REFERENCE})
+
+# Linkable entity types (subset of LINK_TYPE_CATEGORY that are LinkCategory.ENTITY).
+ENTITY_LINK_TYPES = frozenset(t for t, cat in LINK_TYPE_CATEGORY.items() if cat is LinkCategory.ENTITY)
 
 # Note ``type`` values that carry tabular assay results.
 RESULTS_TABLE_NOTE_TYPES = frozenset(
@@ -44,6 +88,21 @@
 )
 
 
+@dataclass(frozen=True)
+class LinkRef:
+    """A classified note link. ``id``/``web_url`` are absent for some types
+    (``link`` has no id; ``location`` has no webURL)."""
+
+    type: str
+    category: LinkCategory
+    id: Optional[str] = None
+    web_url: Optional[str] = None
+
+    @property
+    def is_packageable(self) -> bool:
+        return self.category in PACKAGEABLE_CATEGORIES
+
+
 @dataclass(frozen=True)
 class EntityReference:
     """A reference to a Benchling entity discovered inside an entry.
@@ -105,10 +164,25 @@ def _field_value_ids(fval: Dict[str, Any]) -> List[str]:
     return []
 
 
+def _link_web_url(link: Dict[str, Any]) -> Optional[str]:
+    return link.get("webURL") or link.get("web_url")
+
+
+def classify_link_type(link_type: Optional[str]) -> LinkCategory:
+    """Map an EntryLink ``type`` token to its :class:`LinkCategory`.
+
+    Unknown/future tokens map to ``UNKNOWN`` rather than being silently dropped.
+    """
+    if not link_type:
+        return LinkCategory.UNKNOWN
+    return LINK_TYPE_CATEGORY.get(link_type, LinkCategory.UNKNOWN)
+
+
 def extract_note_links(entry_data: Dict[str, Any]) -> List[Dict[str, Any]]:
-    """Return every link object across all note bodies, unfiltered.
+    """Return every link object across all note bodies, unfiltered and untyped.
 
-    Lower-level primitive; most callers want :func:`extract_entity_references`.
+    Lowest-level primitive; most callers want :func:`classify_links` or
+    :func:`extract_entity_references`.
     """
     links: List[Dict[str, Any]] = []
     for note in _iter_notes(entry_data):
@@ -118,14 +192,44 @@ def extract_note_links(entry_data: Dict[str, Any]) -> List[Dict[str, Any]]:
     return links
 
 
+def classify_links(entry_data: Dict[str, Any]) -> List[LinkRef]:
+    """Return every note link, classified by category and deduped.
+
+    Surfaces the *full* set of objects an entry points at -- entities, inventory,
+    references, metadata pointers, dashboards, and external URLs -- so callers can
+    decide what to fetch (e.g. ``[r for r in classify_links(e) if r.is_packageable]``).
+    Deduped by Benchling ID when present, else by URL; first-seen order preserved.
+    """
+    seen: set[str] = set()
+    refs: List[LinkRef] = []
+    for link in extract_note_links(entry_data):
+        link_type = link.get("type")
+        link_id = link.get("id")
+        web_url = _link_web_url(link)
+        dedup_key = link_id or web_url
+        if dedup_key is not None:
+            if dedup_key in seen:
+                continue
+            seen.add(dedup_key)
+        refs.append(
+            LinkRef(
+                type=str(link_type) if link_type is not None else "",
+                category=classify_link_type(link_type),
+                id=link_id,
+                web_url=web_url,
+            )
+        )
+    return refs
+
+
 def extract_entity_references(
     entry_data: Dict[str, Any],
     *,
     types: "frozenset[str] | set[str]" = ENTITY_LINK_TYPES,
 ) -> List[EntityReference]:
     """Return deduped entity references from note links and entity-link fields.
 
-    Note links are filtered to ``types`` (default: all known entity types).
+    Note links are filtered to ``types`` (default: all linkable entity types).
     Entity-link fields are detected by an ``entity`` substring in the field
     ``type`` and are included regardless of ``types``. References are deduped by
     ID, preserving first-seen order (note links before fields).
@@ -143,7 +247,7 @@ def extract_entity_references(
             EntityReference(
                 id=str(link_id),
                 type=str(link_type),
-                web_url=link.get("webURL") or link.get("web_url"),
+                web_url=_link_web_url(link),
                 source="note_link",
             )
         )

docker/tests/test_entry_references.py

@@ -1,9 +1,18 @@
 """Tests for entry_references extractor (shared discovery for #143 + #68/#69)."""
 
+import json
+from pathlib import Path
+
 from src.entry_references import (
     ENTITY_LINK_TYPES,
+    LINK_TYPE_CATEGORY,
+    PACKAGEABLE_CATEGORIES,
     EntityReference,
+    LinkCategory,
+    LinkRef,
     ResultsTableReference,
+    classify_link_type,
+    classify_links,
     extract_entity_references,
     extract_note_links,
     extract_results_tables,
@@ -126,3 +135,130 @@ def test_dedupes_by_api_and_schema(self):
         note = {"type": "results_table", "apiId": "tbl_1", "assayResultSchemaId": "assaysch_1"}
         entry = _entry(dict(note), dict(note))
         assert len(extract_results_tables(entry)) == 1
+
+
+class TestEntityLinkTypes:
+    """Lock the linkable-entity set to the EntryLink enum (#389)."""
+
+    def test_set_matches_entrylink_entities(self):
+        # custom_entity, dna_sequence, aa_sequence, batch -- and nothing else.
+        assert ENTITY_LINK_TYPES == {"custom_entity", "dna_sequence", "aa_sequence", "batch"}
+
+    def test_batch_is_an_entity_reference(self):
+        entry = _entry(_link_note({"id": "bat_1", "type": "batch", "webURL": "u"}))
+        assert [r.id for r in extract_entity_references(entry)] == ["bat_1"]
+
+    def test_oligos_are_not_link_types(self):
+        # dna_oligo / rna_oligo cannot appear as note links -- not in the enum.
+        for t in ("dna_oligo", "rna_oligo"):
+            assert t not in ENTITY_LINK_TYPES
+            assert t not in LINK_TYPE_CATEGORY
+
+
+class TestClassifyLinkType:
+    def test_full_enum_is_mapped(self):
+        # All 18 EntryLink.type tokens from test/openapi.yaml.
+        enum = {
+            "link", "user", "request", "entry", "stage_entry", "protocol", "workflow",
+            "custom_entity", "aa_sequence", "dna_sequence", "batch", "box", "container",
+            "location", "plate", "insights_dashboard", "folder", "sql_dashboard",
+        }  # fmt: skip
+        assert set(LINK_TYPE_CATEGORY) == enum
+        # none fall through to UNKNOWN
+        assert all(classify_link_type(t) is not LinkCategory.UNKNOWN for t in enum)
+
+    def test_category_assignments(self):
+        assert classify_link_type("custom_entity") is LinkCategory.ENTITY
+        assert classify_link_type("batch") is LinkCategory.ENTITY
+        assert classify_link_type("container") is LinkCategory.INVENTORY
+        assert classify_link_type("entry") is LinkCategory.REFERENCE
+        assert classify_link_type("user") is LinkCategory.METADATA
+        assert classify_link_type("sql_dashboard") is LinkCategory.NOT_PACKAGEABLE
+        assert classify_link_type("stage_entry") is LinkCategory.UNCERTAIN
+        assert classify_link_type("link") is LinkCategory.EXTERNAL
+
+    def test_unknown_and_empty_fall_through(self):
+        assert classify_link_type("future_type") is LinkCategory.UNKNOWN
+        assert classify_link_type(None) is LinkCategory.UNKNOWN
+        assert classify_link_type("") is LinkCategory.UNKNOWN
+
+
+class TestClassifyLinks:
+    def test_surfaces_all_types_classified(self):
+        entry = _entry(
+            _link_note(
+                {"id": "bfi_1", "type": "custom_entity", "webURL": "u1"},
+                {"id": "con_1", "type": "container", "webURL": "u2"},
+                {"id": "axdash_1", "type": "sql_dashboard", "webURL": "u3"},
+                {"type": "link", "webURL": "https://example.com"},
+            )
+        )
+        refs = classify_links(entry)
+        assert refs == [
+            LinkRef(type="custom_entity", category=LinkCategory.ENTITY, id="bfi_1", web_url="u1"),
+            LinkRef(type="container", category=LinkCategory.INVENTORY, id="con_1", web_url="u2"),
+            LinkRef(
+                type="sql_dashboard",
+                category=LinkCategory.NOT_PACKAGEABLE,
+                id="axdash_1",
+                web_url="u3",
+            ),
+            LinkRef(type="link", category=LinkCategory.EXTERNAL, id=None, web_url="https://example.com"),
+        ]
+
+    def test_is_packageable_filter(self):
+        entry = _entry(
+            _link_note(
+                {"id": "bfi_1", "type": "custom_entity", "webURL": "u1"},
+                {"id": "axdash_1", "type": "sql_dashboard", "webURL": "u3"},
+                {"type": "link", "webURL": "https://example.com"},
+            )
+        )
+        packageable = [r.id for r in classify_links(entry) if r.is_packageable]
+        assert packageable == ["bfi_1"]
+
+    def test_dedupes_by_id_then_url(self):
+        entry = _entry(
+            _link_note(
+                {"id": "bfi_1", "type": "custom_entity", "webURL": "u1"},
+                {"id": "bfi_1", "type": "custom_entity", "webURL": "u1"},
+                {"type": "link", "webURL": "https://dup.com"},
+                {"type": "link", "webURL": "https://dup.com"},
+            )
+        )
+        refs = classify_links(entry)
+        assert [(r.type, r.id or r.web_url) for r in refs] == [
+            ("custom_entity", "bfi_1"),
+            ("link", "https://dup.com"),
+        ]
+
+    def test_packageable_categories_membership(self):
+        assert PACKAGEABLE_CATEGORIES == {
+            LinkCategory.ENTITY,
+            LinkCategory.INVENTORY,
+            LinkCategory.REFERENCE,
+        }
+
+
+class TestEntryLinkTypesJson:
+    """Guard spec/entry-link-types.json against drift from the module."""
+
+    def _load(self):
+        path = Path(__file__).resolve().parents[2] / "spec" / "entry-link-types.json"
+        return json.loads(path.read_text())
+
+    def test_json_covers_same_types(self):
+        ref = self._load()
+        json_types = {row["type"] for row in ref["link_types"]}
+        assert json_types == set(LINK_TYPE_CATEGORY)
+
+    def test_json_categories_match_module(self):
+        ref = self._load()
+        for row in ref["link_types"]:
+            module_cat = LINK_TYPE_CATEGORY[row["type"]]
+            assert row["category"] == module_cat.value, row["type"]
+            assert row["packageable"] == (module_cat in PACKAGEABLE_CATEGORIES), row["type"]
+
+    def test_json_packageable_categories_match_module(self):
+        ref = self._load()
+        assert set(ref["packageable_categories"]) == {c.value for c in PACKAGEABLE_CATEGORIES}

spec/entry-link-types.json

@@ -0,0 +1,38 @@
+{
+  "$comment": "Reference map of Benchling EntryLink.type tokens -> how the packager treats them. Source of truth for `type` enum: test/openapi.yaml (EntryLink schema, 18 tokens). Categories mirror docker/src/entry_references.py (LINK_TYPE_CATEGORY); test_entry_references.py asserts they agree. Endpoints / id prefixes / events per issue #389. See issues #143, #389, #68.",
+  "categories": {
+    "entity": "Registry entity; GET-by-id and v2.entity.registered event. Packageable.",
+    "inventory": "Packageable via GET-by-id; no webhook events.",
+    "reference": "Packageable; has its own create/update webhook events.",
+    "metadata": "GET works but low value to package as a record.",
+    "not_packageable": "No read API exists; keep the webURL as a reference only.",
+    "uncertain": "Endpoint depends on tenant API version (e.g. v2-alpha); verify before relying.",
+    "external": "Plain http(s) hyperlink ('link' type); no Benchling ID.",
+    "unknown": "Type not in the known enum; surfaced rather than dropped."
+  },
+  "packageable_categories": ["entity", "inventory", "reference"],
+  "link_types": [
+    {"type": "custom_entity", "category": "entity", "packageable": true, "id_prefix": "bfi_", "get_endpoint": "GET /custom-entities/{id}", "webhook_events": ["v2.entity.registered"]},
+    {"type": "dna_sequence", "category": "entity", "packageable": true, "id_prefix": "seq_", "get_endpoint": "GET /dna-sequences/{id}", "webhook_events": ["v2.entity.registered"]},
+    {"type": "aa_sequence", "category": "entity", "packageable": true, "id_prefix": "prtn_", "get_endpoint": "GET /aa-sequences/{id}", "webhook_events": ["v2.entity.registered"]},
+    {"type": "batch", "category": "entity", "packageable": true, "id_prefix": "bat_", "get_endpoint": "GET /batches/{id}", "webhook_events": ["v2.entity.registered"]},
+    {"type": "container", "category": "inventory", "packageable": true, "id_prefix": "con_", "get_endpoint": "GET /containers/{id}", "webhook_events": []},
+    {"type": "box", "category": "inventory", "packageable": true, "id_prefix": "box_", "get_endpoint": "GET /boxes/{id}", "webhook_events": []},
+    {"type": "plate", "category": "inventory", "packageable": true, "id_prefix": "plt_", "get_endpoint": "GET /plates/{id}", "webhook_events": []},
+    {"type": "location", "category": "inventory", "packageable": true, "id_prefix": "loc_", "get_endpoint": "GET /locations/{id}", "webhook_events": [], "notes": "Locations do not have a webURL."},
+    {"type": "entry", "category": "reference", "packageable": true, "id_prefix": "etr_", "get_endpoint": "GET /entries/{id}", "webhook_events": ["v2.entry.created", "v2.entry.updated.fields", "v2.entry.updated.reviewRecord"]},
+    {"type": "request", "category": "reference", "packageable": true, "id_prefix": "req_", "get_endpoint": "GET /requests/{id}", "webhook_events": ["v2.request.created", "v2.request.updated.fields", "v2.request.updated.status"]},
+    {"type": "workflow", "category": "reference", "packageable": true, "id_prefix": "wfgrp_", "get_endpoint": "GET /workflow-task-groups/{id}", "webhook_events": ["v2.workflowTaskGroup.created", "v2.workflowTaskGroup.mappingCompleted", "v2.workflowTaskGroup.updated.watchers"]},
+    {"type": "stage_entry", "category": "uncertain", "packageable": false, "id_prefix": "etr_", "get_endpoint": "v2-alpha only", "webhook_events": ["v2-alpha.stageEntry.*"], "notes": "Verify against the deployed tenant's API version before relying on it."},
+    {"type": "protocol", "category": "not_packageable", "packageable": false, "id_prefix": null, "get_endpoint": null, "webhook_events": [], "notes": "Linkable but no GET-by-id endpoint in the stable spec."},
+    {"type": "user", "category": "metadata", "packageable": false, "id_prefix": "ent_", "get_endpoint": "GET /users/{id}", "webhook_events": [], "notes": "Metadata only."},
+    {"type": "folder", "category": "metadata", "packageable": false, "id_prefix": "lib_", "get_endpoint": "GET /folders/{id}", "webhook_events": [], "notes": "Legacy; metadata only."},
+    {"type": "sql_dashboard", "category": "not_packageable", "packageable": false, "id_prefix": "axdash_", "get_endpoint": null, "webhook_events": [], "notes": "No read API; Insights/analytics artifact reachable only via the Warehouse. Keep webURL deep link."},
+    {"type": "insights_dashboard", "category": "not_packageable", "packageable": false, "id_prefix": "axdash_", "get_endpoint": null, "webhook_events": [], "notes": "Legacy alias of sql_dashboard; no read API."},
+    {"type": "link", "category": "external", "packageable": false, "id_prefix": null, "get_endpoint": null, "webhook_events": [], "notes": "Plain external hyperlink; id omitted, webURL is the literal URL."}
+  ],
+  "not_inline_linkable": {
+    "$comment": "Resources that are NOT EntryLink types -- they cannot appear in links[]. They reach an entry via structured note parts / inventory tables instead.",
+    "types": ["dna_oligo", "rna_oligo", "mixture", "assay_run", "assay_result", "workflow_task", "workflow_output"]
+  }
+}