plan: add resource system guidance

2026-05-23 16:49:53 +00:00 · 2026-05-20 19:17:48 +08:00
parent a1c0b83490
commit 45b9fd5262
1 changed files with 914 additions and 0 deletions
--- a/plan/2026-05-20_11_resource_material_sync_guidance_draft.md
+++ b/plan/2026-05-20_11_resource_material_sync_guidance_draft.md
@@ -0,0 +1,914 @@
+# Draft: Resource And Material Sync Guidance For Sirna And Similar Bioyond Systems
+
+Status: draft for discussion, not an implementation mandate.
+
+This note triangulates across five source categories with different authority:
+
+1. `docs/developer_guide/examples/workstation_architecture.md`: desired shape
+   and vocabulary. It is a design target, not proof that the current code has
+   every behavior.
+2. `BioyondWorkstation`, `BioyondResourceSynchronizer`, and shared graphio code:
+   the current compatibility anchor. New guidance should mostly preserve this
+   lifecycle and extend it deliberately.
+3. Existing non-Sirna Bioyond stations: practical examples of how the shared
+   base is used, including shortcuts that should not become policy.
+4. Sirna implementation, plans, findings, and guide notes: stress-test evidence.
+   They expose real missing cases, but the current Sirna code is not the
+   architecture authority because parts were added without fully aligning to the
+   shared base.
+5. UniLabOS resource framework behavior around PLR resources,
+   `ResourceTreeSet`, serialize/deserialize, and `update_resource(resources=...)`.
+
+The short recommendation is:
+
+Keep the shared Bioyond workstation lifecycle as the center of gravity. Evolve
+the shared synchronizer with small project hooks for classification, ID-based
+resolution, and non-slot material handling, rather than letting Sirna become a
+parallel synchronization model. For Sirna, those hooks should resolve placement
+by Bioyond IDs, distinguish physical slot labware from reagent liquid contents,
+preserve Bioyond IDs in `unilabos_extra`, mutate the local PLR deck, and publish
+the full deck through `update_resource(resources=[deck])`.
+
+Do not treat every Bioyond stock row as a deck resource.
+
+## Evidence Weighting
+
+This task is not a Sirna implementation retrospective. It is a best-practice
+alignment pass across the architecture target, the shared base class, observed
+station behavior, and Sirna's newly exposed edge cases.
+
+Use the sources this way:
+
+- Architecture doc: ask "what shape should this system eventually have?"
+- Shared Bioyond base: ask "what behavior must remain compatible today?"
+- Other Bioyond stations: ask "what patterns are already working in practice?"
+- Sirna current code and notes: ask "what did the base model fail to handle, and
+  which Sirna fixes conflict with the shared lifecycle?"
+- Live API/schema evidence: ask "what is true for this deployment's material,
+  warehouse, and coordinate data?"
+
+The Sirna AGENT_GUIDE is useful for finding caveats and prior investigations,
+but it should not be cited as an independent source of truth when source code,
+framework behavior, live API evidence, or architecture docs can answer the same
+question.
+
+## Mental Model
+
+There are three resource worlds. Confusing them is the main source of bugs.
+
+| World | Owner | Purpose | Recommended truth |
+| --- | --- | --- | --- |
+| Bioyond/LIMS | Bioyond APIs through `BioyondV1RPC` | External stock, material IDs, warehouse IDs, location IDs, inbound/outbound side effects | External material truth |
+| PLR deck | Workstation driver | Runtime workstation material layout, warehouse occupancy, liquid contents | Local mutation surface |
+| UniLabOS resource tree | `ResourceTreeSet` / ROS node / host resource APIs | Canonical UniLabOS/cloud representation | Framework/cloud truth |
+
+The architecture guide describes `Deck` as the local material system and
+`ResourceSynchronizer` as the optional external-system bridge
+(`docs/developer_guide/examples/workstation_architecture.md:221`). The broader
+framework serializes PLR objects into `ResourceTreeSet`, whose resource dicts
+carry `id`, `uuid`, `parent_uuid`, `type`, `class`, `pose`, `config`, `data`,
+and `extra` (`unilabos/resources/resource_tracker.py:107`).
+
+Therefore the correct path is:
+
+```text
+Bioyond rows
+  -> normalized material records
+  -> preserve Bioyond materialTypeMode: Sample / Consumables / Reagent
+  -> resolve material/location/warehouse IDs
+  -> choose UniLabOS handling for that mode
+  -> mutate PLR deck
+  -> ResourceTreeSet.from_plr_resources([deck])
+  -> ROS update_resource(resources=[deck])
+  -> host/cloud resource-tree update
+```
+
+Avoid direct cloud JSON patches and avoid treating Bioyond records as already
+being UniLabOS resource nodes.
+
+## Target Architecture
+
+The ideal architecture in `workstation_architecture.md` is still the right
+direction:
+
+1. `WorkstationBase` owns the local `deck`, workflow state, and hardware
+   interface.
+2. `ResourceSynchronizer` owns external material synchronization.
+3. `BioyondResourceSynchronizer` owns the Bioyond-specific use of
+   `BioyondV1RPC`.
+4. `ROS2WorkstationNode.update_resource(resources)` owns the UniLabOS/cloud
+   resource-tree update.
+5. Optional HTTP report handlers may trigger local deck mutation, external sync,
+   and cloud publication.
+
+The documented startup sequence is:
+
+1. Create workstation.
+2. Initialize PLR deck and warehouses.
+3. Create Bioyond RPC hardware interface.
+4. Create resource synchronizer.
+5. `sync_from_external()`.
+6. Initialize ROS node and children.
+7. `post_init(ros_node)`.
+8. Upload `resources=[deck]`.
+
+See `docs/developer_guide/examples/workstation_architecture.md:308`,
+`docs/developer_guide/examples/workstation_architecture.md:497`, and
+`docs/developer_guide/examples/workstation_architecture.md:737`.
+
+Important caveat: that document is the hope. It is still valuable because it
+names the desired responsibilities, but current Bioyond stations implement a
+more limited, best-effort side-effect sync. When the doc and current code
+diverge, use the doc to choose direction and the shared base code to choose the
+next compatible step.
+
+## Current Practical Behavior
+
+The shared `BioyondWorkstation` implementation is the current behavioral
+baseline. It does this today:
+
+1. Requires a deck.
+2. Reconstructs `deck.warehouses` from deck children/config when needed.
+3. Creates `BioyondV1RPC`.
+4. Installs `BioyondResourceSynchronizer`.
+5. Immediately calls `sync_from_external()`.
+6. Later, in `post_init`, publishes the whole deck with
+   `ROS2DeviceNode.run_async_func(self._ros_node.update_resource, True,
+   resources=[self.deck])`.
+
+Relevant code:
+
+- `BioyondResourceSynchronizer` is defined in
+  `unilabos/devices/workstation/bioyond_studio/station.py:117`.
+- `sync_from_external()` fetches stock `typeMode` 0, 1, and 2, then passes all
+  rows to `resource_bioyond_to_plr(...)`
+  (`unilabos/devices/workstation/bioyond_studio/station.py:147`).
+- `BioyondWorkstation.__init__` installs the synchronizer and syncs immediately
+  (`unilabos/devices/workstation/bioyond_studio/station.py:856`).
+- `post_init()` uploads the deck (`unilabos/devices/workstation/bioyond_studio/station.py:893`).
+- `resource_tree_add()` performs Bioyond create/inbound side effects
+  (`unilabos/devices/workstation/bioyond_studio/station.py:958`).
+
+This practical behavior works for simple physical-resource stock import, but it
+does not provide full continuous two-way sync, conflict resolution, or reliable
+stale-state cleanup. In particular:
+
+- Re-fetching stock does not clearly clear stale local deck state first.
+- Local-to-external update no-ops unless `unilabos_extra["update_resource_site"]`
+  is present.
+- `process_material_change_report()` is mostly TODO-level in the base station.
+- Some station-specific code bypasses the shared synchronizer with direct LIMS
+  calls.
+- Some existing stations contain shortcuts that should not be copied, such as
+  duplicate initialization, stale globals, or hardcoded warehouse/axis cases.
+
+Treat current Bioyond behavior as operationally useful and compatibility
+important, not as proof that the ideal architecture is already achieved. The
+goal is to tighten this base path, not replace it with a Sirna-only path.
+
+## Recommended Shared Pipeline
+
+For Sirna and similar Bioyond systems, the base synchronizer should evolve from
+the current shared path into one shared pipeline with small project hooks:
+
+```text
+sync_from_external()
+  fetch stock rows from Bioyond
+  update RPC material cache
+  normalize rows into a common internal shape
+  preserve materialTypeMode: Sample / Consumables / Reagent
+  resolve warehouse/location by Bioyond IDs when available
+  choose handling for the row's mode
+  apply Sample / Consumables rows as mapped slot labware by default
+  apply Reagent rows as physical reagent labware or liquid content by evidence
+  report unknown modes or unmapped handling loudly
+  publish deck if deck changed and ROS node is available
+```
+
+Suggested extension points:
+
+```python
+class BioyondResourceSynchronizer(ResourceSynchronizer):
+    def external_material_mode(self, row: dict) -> str:
+        return row["materialTypeMode"]  # Sample | Consumables | Reagent
+
+    def resolve_external_row(self, row: dict) -> dict:
+        ...
+
+    def apply_external_row(self, row: dict, mode: str, resolved: dict) -> None:
+        ...
+```
+
+The base class should continue to own:
+
+- stock fetches for `typeMode` 0/1/2;
+- material-cache refresh;
+- common normalization;
+- mode validation for `Sample` / `Consumables` / `Reagent`;
+- publication orchestration;
+- error aggregation;
+- stale-state policy once agreed.
+
+Project code should own only the parts that are truly deployment-specific:
+
+- material type/mode to PLR class mapping;
+- project-local handling inside `Sample` / `Consumables` / `Reagent`;
+- project-local warehouse ID/name mapping;
+- project-local coordinate conventions;
+- special row handling such as Sirna reagent-as-liquid.
+
+This keeps existing Bioyond stations close to the same lifecycle while still
+absorbing the Sirna lessons that the earlier base did not model. The default
+hook behavior can remain "Sample/Consumables/Reagent rows become mapped slot
+labware" for simpler stations; Sirna should override Reagent handling where
+evidence requires liquid-content behavior.
+
+## Sirna Findings To Feed Back Into Shared Design
+
+Treat Sirna as a stress test for the shared base, not as a replacement design.
+It raises real questions that earlier stations did not need to answer:
+
+- within the `Reagent` mode, some external rows may be liquid contents rather
+  than slot-occupying reagent labware;
+- placement should be ID-first where Bioyond supplies material/location IDs;
+- warehouse and axis metadata must survive serialize/deserialize;
+  project-specific mode handling is available.
+
+For Sirna-like deployments, the old implicit rule "stock row equals PLR
+resource" is too coarse. For simpler deployments, it can remain the default
+mode-handling behavior.
+
+### IDs Win
+
+Placement identity should prefer:
+
+```text
+materialId
+locationId
+materialTypeId
+warehouseId / whid
+```
+
+Display/debug fields are not identity:
+
+```text
+materialName
+materialCode
+locationCode
+locationShowName
+warehouseName / whName
+```
+
+`locationCode` such as `1-1` is not globally unique. It can exist in multiple
+warehouses. Code-only resolution may be kept as a diagnostic fallback, but it
+must raise on ambiguity.
+
+The current Sirna ID-first resolver is useful source evidence for this direction
+(`unilabos/devices/workstation/bioyond_studio/sirna_station/sirna_station.py:3659`).
+The Sirna mega plan captures the same concern, but the implementation and live
+Bioyond IDs are the stronger evidence.
+
+### Bioyond Modes And UniLabOS Handling Are Different
+
+Bioyond has three primary material modes in this context:
+
+```text
+Sample
+Consumables
+Reagent
+```
+
+Those modes should be preserved as the external taxonomy. UniLabOS still needs a
+handling decision inside the mode: should the row create/place a physical PLR
+resource, or update contents on an already-placed parent resource?
+
+Physical slot resources include things like:
+
+- tip racks;
+- plates;
+- cell culture plates;
+- empty trough/bottle labware;
+- other objects that occupy a warehouse slot.
+
+Reagents are contents of a parent labware when the row describes a liquid rather
+than a physical holder. For Sirna, Bioyond `stock_material(typeMode=2)` returns
+`materialTypeMode="Reagent"` rows; those rows still need evidence-based handling
+as either physical reagent labware or reagent liquid content. The finding in
+`temp_benyao/sirna/_findings/2026-05-07_reagents_vs_resources.md:6` records the
+bug: the generic path can fall back to `RegularContainer`, fail registry lookup,
+and drop reagent rows such as `试剂槽裂解液/Betame`.
+
+Recommended behavior:
+
+1. Validate `materialTypeMode` as `Sample`, `Consumables`, or `Reagent`.
+2. For `Sample` and `Consumables`, default to mapped slot labware: instantiate
+   the mapped PLR class and place it into the resolved warehouse slot.
+3. For `Reagent`, decide whether the row represents physical reagent labware or
+   reagent liquid content from material type evidence, row shape, and live data.
+4. For physical reagent labware, place the mapped PLR resource in the resolved
+   slot.
+5. For reagent liquid content, find the parent trough/bottle and attach liquid
+   metadata to its tracker.
+6. Preserve Bioyond IDs in `parent.unilabos_extra["reagent_bioyond_ids"]`.
+7. Make liquid attachment idempotent by Bioyond material ID.
+8. If the parent labware is missing or the mode/handling cannot be resolved,
+   defer or log with IDs; do not guess.
+
+The existing Sirna helper `_attach_liquid_to_parent()` already follows the
+idempotent metadata direction
+(`unilabos/devices/workstation/bioyond_studio/sirna_station/sirna_station.py:4074`).
+
+### The `0003` Question Must Stay Evidence-Based
+
+Do not blindly map `materialTypeCode 0003` to `BioyondSirna_ReagentTrough`.
+
+If live/schema evidence says a `0003` row is physical trough labware, map it to
+a PLR resource class. If evidence says it is liquid content, attach it to the
+parent trough. If evidence is contradictory, mark it unsupported and log the
+Bioyond IDs.
+
+Treat this as an open design decision until source/schema/live evidence settles
+the row shape. The Sirna plan records the question, but it should not decide the
+mapping by itself.
+
+### Sirna Warehouse And Axis Rules Are Project-Local
+
+Sirna warehouse layout and axis conventions must be verified from Sirna source,
+Sirna schema, current deck behavior, and live/read-only Sirna APIs when
+available. Do not import Peptide, reaction, dispensing, or cell station layout
+truth.
+
+For Sirna specifically, the current integrated deck display should be treated as
+the good baseline. The prior col-row slot-key fix is already present in the
+deck/graphio path, and any remaining x/y or y-reverse correction should be
+handled through shared warehouse metadata and shared graphio/display mapping
+rather than by reshaping the Sirna station display ad hoc.
+
+### Display Geometry: Evidence Before Axis Values
+
+Peptide resource sync should not be treated as a validated model, but its
+UniLabOS display work is useful and should influence this guidance.
+
+Confirmed Peptide behavior:
+
+- Peptide live warehouse evidence found `自动化堆栈` with 170 locations where
+  `code="10-17"` appears at `x=17, y=10`
+  (`../Uni-Lab-OS-Peptide/temp_benyao/peptide/_findings/2026-05-13_1404_peptide_col_row_deck.md:6`).
+- Peptide's current display convention is Peptide-specific evidence:
+  `bioyond_axis="xy_col_row"` and `bioyond_key_axis="col_row"` in the current
+  Peptide station implementation. Do not copy that pair into Sirna or any other
+  project without live warehouse evidence for that target system. With this
+  Peptide combination, graphio does not apply the legacy x/y swap
+  (`../Uni-Lab-OS-Peptide/unilabos/resources/graphio.py:868`).
+- Peptide models the main automation stack as 17 visual rows by 10 visual
+  columns while preserving labels such as `10-17`
+  (`../Uni-Lab-OS-Peptide/unilabos/resources/bioyond/decks.py:308`).
+- Peptide warehouses and deck child positions use `frontend_y_flip=True` /
+  `_frontend_y_flipped_coordinate(...)` so stored PLR coordinates compensate for
+  the frontend y-axis inversion
+  (`../Uni-Lab-OS-Peptide/unilabos/resources/bioyond/decks.py:299`;
+  `temp_benyao/peptide/_findings/2026-05-13_1514_frontend_y_flip_layout.md:6`).
+- The older Peptide graph-layout note is stale for the Sirna discussion. The
+  current Sirna integrated station/deck display is a good baseline; the reusable
+  Peptide lesson is axis metadata and frontend y-reverse compatibility.
+- Peptide tests encode the intended behavior: `10-17` lands at row 17 /
+  column 10, and after frontend y-flip the displayed site positions match the
+  expected top-to-bottom layout
+  (`../Uni-Lab-OS-Peptide/temp_benyao/peptide/tests/test_peptide_deck_layout.py:60`).
+
+Guidance for Sirna and similar systems:
+
+1. Treat `bioyond_axis` and `bioyond_key_axis` as two separate concepts:
+   - `bioyond_axis` describes how Bioyond numeric `x/y` map to visual axes.
+   - `bioyond_key_axis` describes how slot labels such as `10-17` are generated
+     or preserved.
+2. Do not infer display orientation from label strings alone. Both `row_col`
+   and `col_row` can preserve the same final label text while producing
+   different visual layouts and graphio swap behavior.
+3. Use live/read-only `code/x/y` evidence for each project and each warehouse
+   family before choosing axis metadata.
+4. Keep visual orientation fixes separate from material identity. IDs and slot
+   labels determine registration; display dimensions and frontend y-flip only
+   determine how the deck appears.
+5. Author intended display coordinates first, then convert stored y coordinates
+   for the active frontend convention:
+   - deck child stored y = `deck_height - display_y - child_height`;
+   - warehouse site stored y = `warehouse_height - display_y - site_height`;
+   - graph-level y values should be transformed only when the active frontend
+     convention requires it.
+6. Preserve the current Sirna display as the baseline unless concrete frontend
+   evidence shows a y-reverse problem. Do not change station/deck graph
+   semantics just to match stale Peptide layout notes.
+7. Add layout tests that assert:
+   - warehouse `num_items_x`, `num_items_y`, capacity, first key, and last key;
+   - representative `code/x/y` examples land on the intended site key;
+   - frontend y-flip produces expected displayed positions;
+   - generated deck children do not overlap in displayed coordinates.
+8. When borrowing from Peptide, borrow the evidence pattern: live discovery,
+   axis/key-axis metadata, y-flip tests, and display fixtures. Do not borrow a
+   literal axis pair or Peptide resource-sync behavior as a validated path.
+
+Concrete live discovery workflow:
+
+1. Prefer the reusable read-only probe pattern before reading old findings:
+
+```bash
+python3 temp_benyao/sirna/tests/probe_readonly_storage_inventory.py \
+  --base-url <api_host> \
+  --api-key <api_key> \
+  --output temp_benyao/<project>/_logs/<timestamp>_readonly_storage_inventory_probe.json
+```
+
+This probe checks swagger candidates, project storage/location endpoints,
+material type endpoints, `warehouse-info-by-mat-type-id`, and `stock-material`,
+then writes a redacted evidence file and a merged warehouse summary.
+
+2. For Sirna quick checks, `temp_benyao/sirna/tests/discover_sirna_warehouses.py`
+   is the narrower historical helper. Treat it as a template unless it has been
+   parameterized for the target config.
+3. Query `/api/storage/location/locations-by-type?type=0&typeMode=0&materialType=0`
+   first for stack names, warehouse IDs, full slot lists, `code`, `x`, `y`, `z`,
+   and display mode. This endpoint is the topology source when available.
+4. Cross-reference with `/api/lims/storage/material-types` and
+   `/api/lims/storage/warehouse-info-by-mat-type-id` to learn material-type
+   placement constraints. Use `stock-material` only for occupied-slot evidence;
+   it cannot reveal empty topology.
+5. Infer `bioyond_key_axis` from how slot labels must be generated or preserved,
+   and infer `bioyond_axis` from how raw Bioyond `x/y` must map to PLR holder
+   indices. A label such as `10-17` alone is ambiguous; compare it to the same
+   record's `x/y`, and use boundary examples from non-square stacks.
+6. Encode the discovered convention on the warehouse resource, not in a one-off
+   station branch. The metadata must serialize/deserialize with the warehouse
+   because graph load and cloud sync rebuild resources.
+7. Add or update layout tests before changing Sirna display behavior. For Sirna,
+   test against the current good display first, then only change shared x/y or
+   y-reverse mapping if the fixture demonstrates a real mismatch.
+
+### Deserialize Must Be Idempotent
+
+This is confirmed framework behavior, not a possible risk. Resource publication
+builds `ResourceTreeSet` from live PLR resources by calling
+`resource.serialize()` and `resource.serialize_all_state()`
+(`unilabos/resources/resource_tracker.py:547`). Readback/reconstruction goes
+through `ResourceTreeSet.to_plr_resources()`, finds the PLR subclass, calls
+`sub_cls.deserialize(...)`, then restores PLR state, UUIDs, and `unilabos_extra`
+(`unilabos/resources/resource_tracker.py:637`). `ResourceTreeSet.dump()` also
+serializes resource nodes while excluding `children` from each individual node
+record (`unilabos/resources/resource_tracker.py:914`), so parent/child
+relationships and object state must survive the framework tree shape rather than
+only an in-memory PLR object graph.
+
+Sirna resource/deck classes therefore must survive:
+
+1. registry-time construction;
+2. `Resource.deserialize()` round trips;
+3. cloud-synced deck state with serialized children.
+
+If a synced deck already has serialized `children`, default setup must not
+create duplicate/stale child resources. Sirna noticed this problem, but the
+reason is framework-level: cloud/resource-tree sync reconstructs PLR objects
+from serialized state, so constructors and setup logic must be idempotent.
+
+Existing Sirna deck code already acknowledges the issue: `BIOYOND_Sirna_Deck`
+turns `setup=False` during deserialize when serialized `children` are present
+(`unilabos/resources/bioyond/decks.py:153`). Sirna material classes also use
+registry-visible `@resource(...)` decorators and tolerant constructors with
+`*args, **kwargs`, defaults, and `ordering` fallbacks
+(`unilabos/resources/bioyond/sirna_materials.py:14`). Treat those as required
+patterns for any new synced resource class.
+
+Guidance:
+
+- Do not add a deck/resource class until it round-trips through
+  `Resource.serialize()` / `Resource.deserialize()` and
+  `ResourceTreeSet.from_plr_resources(...).to_plr_resources()`.
+- Preserve `unilabos_uuid`, parentage, `unilabos_extra`, and liquid state across
+  the round trip.
+- Make default setup conditional: if serialized children exist, do not recreate
+  default warehouses or default child resources on top of them.
+- Itemized PLR subclasses must provide `ordered_items` or `ordering`; otherwise
+  deserialization can fail or rebuild a different structure.
+
+## Startup And Resync Recommendation
+
+The current Sirna code installs `SirnaResourceSynchronizer` after
+`super().post_init(ros_node)` (`sirna_station.py:363`). That is useful as a
+phase patch and as evidence that classification hooks are needed, but it should
+not become the long-term lifecycle. Base initialization may already have run
+generic stock sync and base post-init may already have published the deck before
+the Sirna synchronizer is installed.
+
+Recommended pathway:
+
+1. Keep the `BioyondWorkstation` lifecycle as the base path.
+2. Add a synchronizer factory or hook registration point before eager sync, for
+   example `create_resource_synchronizer()`.
+3. Let Sirna provide classification/resolution hooks through that shared
+   synchronizer shape.
+4. Make startup sync use the installed hook-aware synchronizer before the first
+   deck publication.
+5. Make manual resync, reset resync, report-triggered resync, and future
+   periodic sync all call `self.resource_synchronizer.sync_from_external()`.
+6. Do not instantiate fresh base synchronizers inside Sirna actions, because
+   that bypasses the installed project logic.
+
+This directly addresses the overlap finding in
+`temp_benyao/sirna/_findings/2026-05-12_sirna_synchronizer_overlap.md:6`.
+
+## Material Registration From Create-Order Results
+
+Create-order allocation registration should remain separate from stock sync, but
+it should use the same classification and apply logic.
+
+Recommended create-order pipeline:
+
+1. Normalize allocation records into:
+
+```python
+{
+    "materialId": "...",
+    "materialCode": "...",
+    "materialName": "...",
+    "materialTypeId": "...",
+    "materialTypeCode": "...",
+    "materialTypeMode": "Sample|Consumables|Reagent",
+    "materialTypeName": "...",
+    "locationId": "...",
+    "locationCode": "...",
+    "locationShowName": "...",
+}
+```
+
+2. Resolve warehouse and slot by:
+
+```text
+material-info(materialId)
+  -> warehouse-info-by-mat-type-id(materialTypeId) matched by locationId
+  -> code-only diagnostic fallback only if unambiguous
+```
+
+3. Classify as `slot_labware`, `liquid_content`, or `unsupported`.
+4. Apply mutation to the PLR deck.
+5. Publish the full deck once after the batch.
+
+The current Sirna `_register_materials_to_tree()` already documents this flow
+(`sirna_station.py:3659`) and should be the local reference implementation until
+the shared hook is designed.
+
+## Cloud / UniLabOS Publication Rules
+
+Always mutate real tracked PLR resources first. Then publish through the
+framework.
+
+Correct call shape:
+
+```python
+ROS2DeviceNode.run_async_func(
+    self._ros_node.update_resource,
+    True,
+    **{"resources": [self.deck]},
+)
+```
+
+The real method is:
+
+```python
+async def update_resource(self, resources: List["ResourcePLR"])
+```
+
+See `unilabos/ros/nodes/base_device_node.py:727`.
+
+Do not call:
+
+```python
+update_resource(resource_name=..., resource_data=...)
+```
+
+Do not manually serialize the deck for this path. `update_resource()` creates a
+`ResourceTreeSet`, sends it to `/c2s_update_resource_tree`, and applies returned
+UUID mappings. Missing root parent UUIDs are auto-mounted to the current device,
+so parentage should be preserved on PLR objects before publication.
+
+## Metadata Contract
+
+Every Bioyond-originated slot resource should carry enough metadata for unload,
+audit, and later sync:
+
+```python
+plr_resource.unilabos_extra = {
+    "material_bioyond_id": mat["materialId"],
+    "material_bioyond_code": mat["materialCode"],
+    "material_bioyond_name": mat["materialName"],
+    "material_bioyond_type_id": mat["materialTypeId"],
+    "material_bioyond_type_code": mat["materialTypeCode"],
+    "material_bioyond_type_mode": mat["materialTypeMode"],
+    "location_bioyond_id": mat["locationId"],
+    "location_code": resolved["location_code"],
+    "warehouse_bioyond_id": resolved["warehouse_id"],
+    "warehouse_bioyond_name": resolved["warehouse_name"],
+    "location_resolution_source": resolved["source"],
+}
+```
+
+Every Bioyond-originated liquid content should preserve equivalent metadata on
+the parent labware:
+
+```python
+parent.unilabos_extra.setdefault("reagent_bioyond_ids", []).append({
+    "material_bioyond_id": mat["materialId"],
+    "material_bioyond_code": mat["materialCode"],
+    "material_bioyond_name": mat["materialName"],
+    "material_bioyond_type_id": mat["materialTypeId"],
+    "material_bioyond_type_code": mat["materialTypeCode"],
+    "location_bioyond_id": mat["locationId"],
+    "quantity": mat.get("quantity"),
+    "location_resolution_source": resolved["source"],
+})
+```
+
+This metadata is not decorative. It is required for correct unload, audit,
+duplicate prevention, and future round-trip sync.
+
+## Stale State And Conflict Policy
+
+This is confirmed current behavior, not just a theoretical risk.
+
+Current stock import places resources into empty warehouse slots and skips
+occupied slots. That prevents overwrites, but it can leave stale local resources
+after external moves/deletes.
+
+Evidence:
+
+- `BioyondResourceSynchronizer.sync_from_external()` fetches Bioyond stock and
+  delegates to `resource_bioyond_to_plr(...)`, but it does not compute a
+  before/after diff or remove local resources absent from the snapshot
+  (`unilabos/devices/workstation/bioyond_studio/station.py:147`).
+- `resource_bioyond_to_plr(...)` only assigns when the target warehouse position
+  is empty or a placeholder; when a real resource already occupies the slot, it
+  logs "跳过放置" and leaves the existing object in place
+  (`unilabos/resources/graphio.py:936`).
+- Bioyond outbound/removal logic exists in separate local-to-external hooks such
+  as `resource_tree_remove(...)`, but that is not invoked by stock refresh for
+  Bioyond rows that disappeared externally
+  (`unilabos/devices/workstation/bioyond_studio/station.py:987`).
+
+Recommended direction:
+
+1. Define Bioyond as the source of truth for external stock snapshots unless a
+   local operation is in progress.
+2. Before applying a stock snapshot, compute a diff by Bioyond material ID.
+3. Remove or mark local resources whose Bioyond IDs disappeared from the
+   snapshot, subject to workflow safety checks.
+4. Move local resources whose Bioyond location ID changed.
+5. Attach/detach liquid contents idempotently by Bioyond material ID.
+6. Publish once after applying the batch.
+7. In ambiguous or active-operation cases, log and require manual confirmation.
+
+Until this policy exists, call the current implementation "refresh/import" rather
+than "authoritative synchronization."
+
+## External-To-Local And Local-To-External Boundaries
+
+External-to-local:
+
+- Bioyond stock and create-order allocation rows mutate the local PLR deck.
+- Then UniLabOS publication derives resource trees from the PLR deck.
+
+Local-to-external:
+
+- `resource_tree_add` / update / remove may call Bioyond add, inbound, outbound,
+  or move APIs.
+- These paths should require Bioyond IDs or explicit creation parameters.
+- Movement should use `unilabos_extra["update_resource_site"]` only as an
+  explicit request, not as hidden ambient state.
+- After successful Bioyond side effects, refresh or update the PLR deck and
+  publish the deck.
+
+Avoid station-level direct LIMS calls that bypass the synchronizer unless the
+action explicitly reconciles the deck afterward.
+
+## Error Handling Rules
+
+Fail loudly on:
+
+- unknown material type code/name;
+- unresolved warehouse ID/name;
+- location ID not found in `warehouse-info-by-mat-type-id`;
+- code-only location ambiguity;
+- missing parent labware for liquid content;
+- invalid PLR resource class or `Resource.deserialize()` failure;
+- Bioyond RPC returning empty/fallback values where an ID is required.
+
+Do not silently create `RegularContainer` to hide mapping failures. The Sirna
+finding at `temp_benyao/sirna/_findings/2026-05-07_reagents_vs_resources.md:52`
+calls this out as a reusable trap.
+
+## Tests And Validation
+
+Minimum offline tests:
+
+1. `update_resource` is called only with `resources=[deck]`.
+2. `ResourceTreeSet.from_plr_resources([deck])` preserves UUIDs, parentage,
+   `data`, and `unilabos_extra`.
+3. Sirna allocation records resolve by `material-info` first.
+4. `warehouse-info-by-mat-type-id` resolves by `locationId`.
+5. Code-only fallback raises on ambiguous slots.
+6. `Sample` and `Consumables` rows become slot labware.
+7. Reagent content rows become parent liquid metadata.
+8. Re-running registration does not duplicate liquid entries.
+9. Missing parent labware is deferred/logged, not guessed.
+10. Unknown material type emits Bioyond IDs.
+11. Deck deserialize does not recreate duplicate default children.
+12. Warehouse coordinate mapping is tested per warehouse, not globally.
+13. A synced Sirna deck round-trips through PLR deserialize and
+    `ResourceTreeSet` conversion without duplicate default children.
+14. Stock refresh with a missing Bioyond material ID proves current add/skip
+    behavior first, then verifies the chosen diff/delete policy once implemented.
+15. Display geometry tests cover project-local live discovery fixtures,
+    `bioyond_axis`, `bioyond_key_axis`, representative `code/x/y` mappings,
+    frontend y-flip, and no-overlap deck layout.
+
+Focused Sirna command:
+
+```bash
+pytest temp_benyao/sirna/tests/test_sirna_resource_system.py -q
+```
+
+Shared conversion command, when changing graphio or Bioyond converters:
+
+```bash
+pytest tests/resources/test_converter_bioyond.py -q
+```
+
+Live/read-only validation should capture fixtures for:
+
+- `stock_material(typeMode=0/1/2, includeDetail=true)`;
+- `material-info(materialId)`;
+- `warehouse-info-by-mat-type-id(materialTypeId)`;
+- create-order allocation records;
+- frontend/cloud resource-tree readback after publication.
+
+## Discrepancies To Discuss
+
+### 1. Architecture Is Direction; Base Code Is The Compatibility Anchor
+
+The architecture guide presents `ResourceSynchronizer` as bidirectional. Current
+Bioyond code is mostly eager external import plus selected add/remove/update
+side effects. It has no complete continuous conflict-resolution loop.
+
+Sirna current code should be read in this context: it exposes missing
+capabilities, but parts of it conflict with the existing base lifecycle because
+it was layered on after the base sync behavior already existed.
+
+Recommendation: keep the bidirectional architecture as the target, preserve
+`BioyondWorkstation` as the implementation anchor, and introduce shared hooks
+for the missing Sirna-class problems. Describe the current implementation as
+best-effort refresh plus Bioyond side effects until a diff/conflict policy
+exists.
+
+### 2. The Doc Centers `Deck`; The Framework Centers `ResourceTreeSet`
+
+The architecture guide uses PLR `Deck` as the material system. UniLabOS resource
+tracking uses `ResourceTreeSet` as the canonical serialized representation.
+
+Recommendation: phrase the model as "Deck is the local PLR mutation surface;
+ResourceTreeSet is the UniLabOS/cloud representation derived from it."
+
+### 3. Base Bioyond Sync Treats Every Stock Row As PLR Resource
+
+`BioyondResourceSynchronizer.sync_from_external()` currently feeds typeMode
+0/1/2 rows into `resource_bioyond_to_plr(...)`.
+
+Sirna evidence shows this is wrong for reagent/content-like rows.
+
+Recommendation: add classification hooks before conversion. Rows classified as
+liquid content must not go through standalone PLR resource conversion.
+
+### 4. Sirna Fix Exists As A Fork, Not A Shared Hook
+
+Current `SirnaResourceSynchronizer` captures the important reagent-as-liquid
+question, but it duplicates or bypasses shared sync mechanics. Startup can run
+base sync before the Sirna synchronizer is installed, and manual/reset paths
+have used fresh base synchronizers.
+
+Recommendation: keep the discovered behavior where evidence supports it, but
+refactor the shape. A factory/hook in the shared synchronizer is preferable to a
+long-lived parallel sync class.
+
+### 5. Sirna Create-Order Registration Is Stronger Than Stock Sync
+
+Create-order registration now has ID-first resolution and a clearer classifier.
+That is valuable evidence, not automatically the canonical sync design. The
+stock sync path still resolves external liquid rows by warehouse name/code and
+stores weaker metadata.
+
+Recommendation: extract the stronger resolver/classifier ideas into shared
+hooks, then converge stock sync and create-order registration on the same
+functions.
+
+### 6. Graphio Has Shared Fragility
+
+`resource_bioyond_to_plr()` contains hardcoded warehouse/coordinate cases and a
+fallback to `RegularContainer`. Hardening it affects multiple Bioyond projects.
+
+Recommendation: after Sirna is green, discuss shared graphio hardening in a
+separate change: no silent `RegularContainer`, explicit unknown-type diagnostics,
+and project-specific axis metadata instead of hardcoded names.
+
+### 7. Serialize/Deserialize Is A Gating Contract
+
+This is not optional documentation neatness. Any new resource/deck class or sync
+metadata must pass the framework serialize/deserialize path before it can be
+trusted in cloud-synced operation.
+
+Recommendation: make round-trip tests part of acceptance for resource-system
+changes, especially for Sirna deck setup, warehouse metadata, `reagent_bioyond_ids`,
+liquid tracker state, and itemized labware ordering.
+
+### 8. Existing Stock Sync Is Add/Skip-Biased, Not Delete-Aware
+
+Current `sync_from_external()` imports and places observed Bioyond resources,
+but it does not delete local resources missing from the latest stock snapshot.
+When a target slot is occupied by a real resource, graphio skips placement rather
+than replacing it.
+
+Recommendation: describe the current behavior as "stock refresh/import" until a
+Bioyond-ID diff policy is implemented. Deletion/removal must be a deliberate
+phase, with workflow-safety checks and tests, not implied by the current stock
+sync name.
+
+### 9. Peptide Display Is Useful; Peptide Sync Is Not Yet Authority
+
+Peptide's latest display work is useful evidence for Peptide's own warehouse
+axis/key-axis metadata and for the shared need to account for frontend y-axis
+inversion. It does not define Sirna's axis values. Its resource sync remains
+untested/problematic and should not be treated as the model for Sirna sync
+behavior.
+
+Recommendation: fold the Peptide display lesson into shared guidance as a
+discovery-and-test pattern, not as a literal axis pair. Keep Sirna display
+behavior grounded in Sirna live evidence and the current good deck baseline; keep
+resource synchronization recommendations grounded in the Sirna ID-first
+registration path and the shared Bioyond synchronizer refactor.
+
+### 10. Some Existing Stations Should Be Examples Only, Not Templates
+
+Non-Sirna stations show useful patterns, but also shortcuts:
+
+- direct LIMS calls bypassing the synchronizer;
+- duplicate `super().__init__()` in reaction station;
+- stale/undefined `WAREHOUSE_MAPPING` references;
+- RPC methods collapsing failures into empty values;
+- no robust stale deck cleanup on stock refresh.
+
+Recommendation: borrow the shared deck publication and Bioyond ID metadata
+patterns, not the incidental shortcuts.
+
+## Recommended Discussion Path
+
+For the next implementation discussion, decide these in order:
+
+1. What is the smallest shared-base extension that lets project hooks exist
+   before eager sync without breaking existing Bioyond stations?
+2. Should `BioyondWorkstation` gain a synchronizer factory, a hook registry, or
+   a delayed eager-sync point?
+3. Is `materialTypeCode 0003` in current Sirna live data physical labware,
+   liquid content, or both depending on row shape?
+4. Where should Sirna warehouse Bioyond IDs live: station config, deck metadata,
+   or both?
+5. Should stock refresh clear/diff deck state now, or remain append/skip until
+   after create-order registration is stable?
+6. Should `update_resource` remain async/non-blocking for material registration,
+   or should selected user-facing actions fail if publication fails?
+7. Which parts of the Sirna reagent-as-liquid rule are project-local, and which
+   should become shared Bioyond behavior after Peptide/cell validation?
+8. Should graphio fallback hardening land before or after Sirna stock sync is
+   fully validated?
+9. Should any remaining Sirna x/y or y-reverse issue be fixed in shared
+   graphio/display mapping after a live fixture proves it, or should the current
+   Sirna deck remain untouched?
+
+## Recommended Pathway
+
+The pragmatic path is:
+
+1. Preserve and test the current `BioyondWorkstation` lifecycle as the shared
+   compatibility baseline.
+2. Treat Sirna create-order registration as a local proof of the missing
+   classification/ID-resolution behavior, not as the architecture shape to copy.
+3. Validate live/read-only Sirna fixtures for `0003`, warehouse IDs, and stock
+   reagent rows.
+4. Refactor the shared Bioyond synchronizer to expose classification,
+   resolution, and non-slot row hooks with default behavior matching existing
+   stations.
+5. Make Sirna install hooks before the first external sync and first deck
+   publication through the shared lifecycle.
+6. Route startup, manual resync, reset resync, and report-triggered resync
+   through the installed synchronizer.
+7. Converge stock sync and create-order registration on one
+   resolver/classifier/apply implementation.
+8. Add stale-state diffing only after the basic ID-first path is stable.
+9. Harden graphio fallback as a shared follow-up.
+
+This gives Sirna the necessary behavior without locking in a second Bioyond sync
+system that future projects will have to debug around.