Harden bind-text-block: deterministic element resolution + library-immutable item_type guard

[jfrench9]

Summary

Two hardening items in the new bind-text-block path
(robosystems/operations/roboledger/commands/text_blocks.py). Neither is a
security hole — both paths are tenant-scoped and write-gated — but both are
data-integrity / robustness looseness worth closing before the disclosure
authoring surface goes live in prod.

(a) Non-deterministic element resolution, no structure-membership check

_resolve_element resolves a qname via Element.qname == ... .limit(1) with no
ordering, then bind_text_block stamps the fact with structure_id = body.structure_id + element_id = element.id. Nothing verifies the element is
actually an arc member of that structure, and a qname duplicated across
taxonomies in the tenant schema resolves arbitrarily.

Result: a narrative can be attached to the wrong structure.

Fix: make the qname lookup deterministic/unique, and validate the element
participates in body.structure_id (via associations).

(b) item_type stamp can trip the library-immutability trigger

bind_text_block sets element.item_type = "text_block" on first bind
(text_blocks.py:145-149). If the target element is ever library-owned
(created_by = 'library-seeder'), the UPDATE elements on flush hits the
raise_library_immutable_elements trigger (migration 0002) → P0001, which
surfaces as an uncategorized InternalError → 500 (MCP: generic
command_failed).

Unreachable today: the only library text-block-CAP disclosure structures are
abstract (rejected by the is_abstract guard first), and the only concrete
library concepts are the 5 rs-metric ratios (not text-block). It becomes a live
crash the moment the library ships a concrete text-block concept.

Fix: only stamp item_type when created_by != 'library-seeder', drive the
write through the sanctioned library_resync path, or set item_type at
authoring time in create-taxonomy-block instead of lazily on bind.

Test gap

The bind_text_block command itself has no direct unit test (only the
envelope/dispatch and serialization paths are covered), so the item_type path is
untested.

Found during the v1.6.6 pre-release review.

[jfrench9]

Splitting the two halves by priority, after checking this against examples/coffee_roaster_demo (the Driftline demo, which exercises the disclosure authoring surface end-to-end in dev):

(a) is the one worth doing. It fails silently — a narrative attaches to the wrong structure rather than erroring — and the non-deterministic qname resolution is also what makes (b)'s library-collision case reachable by accident rather than by intent.

(b) is off the designed path. The demo authors driftline:* concepts through the reporting_extension envelope and binds documents to those; its docstring is explicit that "nothing is added to the framework source — this is the extend-and-map path." Tenant-owned rows aren't trigger-protected, so the item_type stamp writes cleanly and the immutability trigger never fires. Still worth closing, since no rs-gaap package declares itemType (only rs-driver and rs-metric do) — library rs-gaap elements really do carry item_type = NULL and would trip the stamp if something targeted them directly.

Also downgraded this from a blocker to recommended on #901: with (b) off-path, no item of substance gates flipping TAXONOMY_AUTHORING_ENABLED.

[jfrench9]

Re-verified against main (2026-08-04). Both halves still reproduce; the "Test gap" section is now stale.

Test gap — superseded

tests/operations/roboledger/commands/test_text_blocks.py shipped with the command itself (5be7965) and does cover the item_type path directly:

• test_stamps_element_item_type_when_null — asserts the stamp to "text_block"
• test_preserves_existing_item_type — asserts an existing item_type is left alone

So "the bind_text_block command itself has no direct unit test" is wrong as written. The residual gap is narrower and worth stating precisely: the suite builds its Element from a MagicMock helper (_element(...)), so it exercises the Python-side branch but cannot exercise the raise_library_immutable_elements trigger — which is where (b)'s failure actually lives. Whatever fix lands for (b) needs a test that hits a real element row, not a mock.

Nothing in the suite covers (a): no test asserts that the resolved element is an arc member of body.structure_id.

(a) unchanged — still the one worth doing

_resolve_element (operations/roboledger/commands/text_blocks.py:92-97) is still select(Element).where(Element.qname == body.element_qname).limit(1) — no ordering, no uniqueness, no structure-membership check — and bind_text_block still stamps structure_id = body.structure_id alongside it at :144. A qname duplicated across taxonomies in the tenant schema still resolves arbitrarily, and a narrative can still attach to the wrong structure with no error.

(b) unchanged

The unconditional stamp is still at text_blocks.py:145-149, gated only on item_type is None, with no created_by != 'library-seeder' check. Still off the designed path per the earlier comment.

[MHa55anY]

Happy to take (a) as a fork PR if that works — deterministic qname resolution plus checking the element actually belongs to body.structure_id via associations. I'll extend tests/operations/roboledger/commands/test_text_blocks.py for the structure-membership case and leave (b) for a follow-up unless you'd prefer it bundled.

Planning to branch on my fork and open against main here — let me know if there's anything you'd want done differently before I start.