feat(transcode): Phase-2-B triples_to_batch (ExpandedTriple stream → RecordBatch)

[AdaWorldAPI]

Summary

Phase-2-B: the missing reverse-direction helper — triples_to_batch(soa, &[ExpandedTriple]) → RecordBatch. Takes a stream of triples (what Ontology::expand_entity() returns) and materialises one Arrow row per subject.

This is the Phase 5 / Phase 2-B bridge consumer code needs to roundtrip an entity through the SPO substrate.

Why this shape — not "walk SpoStore::scan(lookup)"

The original Phase-2 plan-doc described "walk SpoStore::scan(lookup)" as the read path. SpoStore doesn't expose a flat scan(lookup) — its API is per-verb (query_forward / query_reverse / query_relation) and the FNV-1a fingerprint is one-way (subject can't be reversed back to entity_id).

ExpandedTriple is the right input shape:

• Carries the canonical subject_label (entity:{type}:{id}) → entity_id is recoverable.
• The contract crate already mints these via SchemaExpander::expand_entity().

Consumers wire SpoStore → ExpandedTriple → RecordBatch through their own subject-id-aware reader (the side-table mapping subject fingerprint → entity_id is consumer-side state, not transcode's). This helper does the second step canonically, so every consumer doesn't reinvent it.

What ships

pub fn triples_to_batch(
    soa: &OuterSchema,
    triples: &[ExpandedTriple],
) -> Result<RecordBatch, TranscodeError>;

pub fn round1_lenient_schema(soa: &OuterSchema) -> SchemaRef;
fn parse_entity_id_from_label(label: &str, expected_type: &str) -> Option<u64>;

Behaviour

Input shape	Outcome
Triples for one subject	1 row, columns populated from matching predicates
Triples for N subjects	N rows, lex-sorted by subject_label (BTreeMap)
Triple's entity_type_id ≠ schema's	Err(EntityTypeMismatch)
subject_label not in entity:{type}:{id} form	Err(BadSubjectLabel)
Triple's predicate not in schema	silently dropped (BBB outer-view rule)
Required column with no triple in the group	Err(MissingColumn)
Empty input	empty batch with the right schema

Round-1 honesty: Utf8 everywhere on the body

triples_to_batch emits every body column as nullable Utf8 regardless of the schema's declared ArrowTypeCode. The typed surface (Currency → Float32, Date(_) → Date32, etc.) applies on the from_columns / from_columns_partial path which has typed input. Triple input is string-shaped (object_label), so round-1 keeps it Utf8. Round 3 adds typed-value reconstruction inside this function.

The schema returned by the function is round1_lenient_schema(soa) (every body column nullable Utf8). The typed schema (arrow_schema(soa)) is still the wire-shape contract; round-3 makes triples_to_batch emit it.

New TranscodeError variants

EntityTypeMismatch {
    expected: EntityTypeId,
    got: EntityTypeId,
},
BadSubjectLabel(String),

Both surface as concrete typed errors so consumers can branch on them rather than parsing display strings.

Tests

12/12 pass under --features query-lite,auth-rls-lite:

• 5 existing (regression coverage on from_columns / from_columns_partial)
• 7 new for triples_to_batch:
  • triples_to_batch_produces_one_row_per_subject — two patients via expand_entity
  • triples_to_batch_rejects_mixed_entity_types — Diagnosis triples fed to a Patient soa
  • triples_to_batch_returns_empty_batch_for_empty_input — clean empty case
  • triples_to_batch_drops_undeclared_predicates_silently — BBB outer-view
  • triples_to_batch_rejects_missing_required_column — required column gate
  • triples_to_batch_subject_label_round_trip — expand_entity(999_999) → id_col[0] == 999_999
  • triples_to_batch_preserves_lex_subject_order — BTreeMap-stable order

What's deferred to Round 3

• Typed value reconstruction: parse object_label according to semantic_type ("123.45" → Float32 123.45, "1980-04-15" → Date32 days_since_epoch, etc.). Schema agreement between triples_to_batch and arrow_schema once typed.
• SpoStore reader proper: needs the consumer-side fingerprint → entity_id side-table. Out of scope here; tracked in .claude/plans/sql-spo-ontology-bridge-v1.md.

Verified

• cargo check -p lance-graph-callcenter --no-default-features --features query-lite — clean
• cargo test transcode::zerocopy:: — 12/12 pass
• cargo clippy — zero zerocopy warnings
• rustfmt --check — clean

Files changed

• crates/lance-graph-callcenter/src/transcode/zerocopy.rs — +~250 / −~10

Cross-link

• lance-graph PR feat(callcenter::transcode): outer ↔ inner ontology mapper + parallelbetrieb #309 — original transcode submodule (introduced ExpandedTriple consumption)
• lance-graph PR feat(transcode): r2 fixes — typed Arrow + codec_route + partial writes + CachedOntology + route validation #310 — round-2 fixes (OuterColumn.codec_route, from_columns_partial)
• lance-graph PR feat(transcode): Phase-2-A pushdown classification (Inexact for recognised filters) #312 — Phase-2-A pushdown classification (the forward direction)

Generated by Claude Code

---

Generated by Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 66feaea26e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Preserve required-field nullability in lenient schema

round1_lenient_schema marks every body field as nullable, which drops the required/optional contract encoded in OuterSchema and used by arrow_schema. That means batches produced by triples_to_batch no longer carry non-null constraints for required properties, and can become schema-incompatible with batches built through from_columns for the same entity type. The field nullability should still follow PropertyKind even if the data type is temporarily widened to Utf8.

Useful? React with 👍 / 👎.