feat: searchable entry links — name-enriched links metadata + raw links.json (#143 #389)

[drernie]

What

When packaging a Benchling entry, the packager now makes the objects an entry references searchable by their human-readable name, and records the raw discovery separately. This is the top-line use case from the 2026-06-15 customer call: "show me all the experiments where QB-2743.1 was used."

Two artifacts, with a hard split between curated/searchable and raw facts:

1. links — curated, searchable (promoted into entry.json)

entry.json is the package's metadata_uri, so anything in it is queryable in Elasticsearch. We add a flat links array, one entry per referenced object, four fields each with one job:

"links": [
  { "type": "custom_entity", "id": "bfi_xCUXNVyG", "name": "QB-2743.1", "slug": "qb-2743-1" },
  { "type": "dna_sequence",  "id": "seq_asQya4lk", "name": null,        "slug": "example-seq" }
]

• type, id — free; id supports downstream linking.
• name — authoritative Benchling display name via best-effort get_by_id, or null when the lookup fails/isn't supported. The only search target, so every non-null links.name is a real name.
• slug — lossy token parsed from the webURL, for eyeballing/debugging only. Never searched as a name, never folded into name.

Search scopes to links.name; a bare keyword still matches the metadata.

2. links.json — raw facts (renamed from references.json)

Raw discovery of what the entry points at — id/type/web_url per link, plus entities and results_tables rows — so a re-parse or a changed classification never needs a re-fetch. Drops the derived classifications (category/fetchable/eventable/disposition): those are recomputed from type in code at runtime, not frozen to disk. schema_version bumped to 2.

Why name needs an API call (verified)

A note link is only {id, type, webURL} — no name. The webURL trailing segment is a lossy slug, confirmed against test/openapi.yaml:

webURL slug	record name	lost
…/bfi-xCUXNVyG-sbn000/edit → sbn000	sBN000	case
…/seq_bhuDUw9D-test-oligo-abc/edit → test-oligo-abc	Example DNA Oligo	slug ≠ name

QB-2743.1 would appear as qb-2743-1 (case + . gone), so a search would miss. The exact name must come from the API. Name resolution is best-effort and never raises, and requires the app to be a registry/project collaborator (setup requirement, not code).

Discovery layer (docker/src/entry_references.py, pure — no API calls)

• summarize_references(entry) → the raw links.json payload.
• link_metadata(entry) → the curated {type, id, name: None, slug} skeleton (caller fills name).
• slug_from_web_url(web_url, id) → strict slug parse (returns None unless an {id}- prefix is matched).
• classify_links / extract_entity_references / extract_results_tables cover the full 18-token EntryLink enum.

Name enrichment lives in the caller (EntryPackager._enrich_link_names) via a type → SDK service map (entities first, then inventory and entries — the types flagged on the call); unmapped types keep name=null.

Tests

Parser + packager suites updated for the v2 shape; added coverage for slug_from_web_url, link_metadata, and the entry.json.links / links.json split. Full suite green (443). black + isort + pyright clean.

Refs #143 #389

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a new pure-Python discovery module to extract (a) entity references and (b) assay results table references from a Benchling entry payload, with accompanying unit tests, intended to be reused by upcoming packaging/features (#143, #68/#69).

Changes:

• Introduces src.entry_references with helpers and dataclasses for extracting note links, entity references, and results-table references.
• Adds unit tests validating filtering, deduplication, field-shape handling, and defensive behavior on missing keys.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
docker/src/entry_references.py	New extraction utilities for entity links and results-table references from entry dicts.
docker/tests/test_entry_references.py	New unit tests covering key extraction behaviors and defensive parsing.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.