Problem
GraphForge returns typed Arrow results, but the extension currently decodes each table into plain JavaScript rows, preserves little schema information, stores one lastResult, and heuristically recognizes generic source/target fields. Canonical GraphForge schemas instead use UUID-bearing fields such as node_uuid, edge_uuid, source_uuid, target_uuid, UUID lists, metrics, communities, paths, and embeddings.
Consequently, canonical edge/path results may not become graph geometry; identity, field types, relation metadata, path order, metrics, and embeddings may be dropped or manually reconstructed. Full JSON row copies also bypass XYG's typed-buffer/native scale path.
Objective
Create one schema-aware GraphForge-to-XYG projection boundary that preserves Arrow types, entity identity, provenance, and result semantics for every GraphForge result family.
Locked Decisions
- The target is faithful GraphForge data visualization, not cross-library payload compatibility.
- This is pre-v1: replace the current visualization schema/renderer choices cleanly; no legacy reader or migration work is required.
- GraphForge Core owns computation and canonical Arrow schemas. The extension owns result-to-visualization intent. XYG owns visualization geometry, layout, LOD, encoding, paint, and interaction.
- Generic file rendering/export comes from XYG and is not rebuilt here.
Requirements
- Preserve Arrow field types and GraphForge schema metadata after engine execution.
- Pass compatible columnar/typed data into XYG without converting all numeric values to JSON rows.
- Define semantic projections for canonical property graphs and every stable rank, cluster, similarity, path, traversal, walk/cycle, flow/cut/tree/matching/coloring, structural, search, and embedding schema.
- Correctly recognize
node_uuid, edge_uuid, src_uuid/dst_uuid, source_uuid/target_uuid, UUID-list columns, relation types, metrics, communities, path order/rank/cost, and embedding vectors.
- Preserve stable row/node/edge identity so selections round-trip between result tables and XYG.
- Bind projections to their source result and graph generation; fail on incompatible or stale joins.
- Maintain a coverage ledger with a tested default visualization, explicit composition, or intentional table-only disposition for every registered GraphForge result schema.
- Do not infer coordinate fields, timezones, CRS, embedding reductions, chart types, or semantic joins without explicit intent.
- Keep property values and result rows out of logs.
Acceptance Criteria
- Every current GraphForge algorithm/result schema has an explicit tested disposition.
- Canonical graph, edge, path, rank, community, similarity, and embedding fixtures preserve exact identities and semantics.
- Table-to-visualization and visualization-to-table selection use UUID/provenance rather than row position.
- Large results use bounded typed/columnar transfer compatible with XYG's scale contract.
- Unsupported or ambiguous schemas fail with a stable explanation and next action.
- Requirements, architecture, Arrow/projection docs, quickstart examples, and tests are current.
BDD Completion Scenarios
Scenario: Canonical edge/path result renders faithfully
Given a GraphForge-produced Arrow result using canonical UUID fields and ordered path/list columns
When the extension opens its XYG visualization
Then nodes, edges, order, metrics, types, and source rows are preserved
And no user-authored rename or row remapping is required.
Scenario: Analytical result is not silently misinterpreted
Given an embedding, scalar structural result, or ambiguous table
When no safe visualization intent exists
Then the extension requires an explicit supported composition or presents it as table-only
And never invents coordinates or semantic joins.
Implementation Notes
Likely affected surfaces include arrowCodec.ts, GraphForgeSession, graph payload/projection models, visualization registry/spec, project commands, results selection linking, XYG Node adapter, and quickstart fixtures.
Observability
Report safe result kind, schema ID/version, row/entity counts, transfer/projection duration, and stable error code only.
Security And Privacy
Validate schema metadata and types, bound buffers/rows, escape displayed text, and never log result values, vectors, coordinates, or paths.
Testing
GraphForge-produced Arrow fixtures for every result family, type/metadata preservation, identity joins, stale-generation negatives, large typed transfer, row/element selection, extension-host E2E, and memory/performance evidence.
Documentation
Update requirements, architecture, testing, command/agent contracts, result-schema coverage ledger, quickstart, and developer integration guide.
Non-Goals
Third-party renderer compatibility, legacy visualization readers, GraphForge algorithm execution in the extension, automatic chart recommendation, or first-two-dimension embedding plots.
Related Issues
Rust/WASM Architecture Amendment
- The extension supplies GraphForge schema metadata, typed columns, generation identity, and explicit visualization intent to XYG; Rust owns canonical composition and scene decisions.
- The adapter must support the selected XYG execution host—native Node or direct browser WASM—through the same versioned typed scene contract without extension-owned joins, LOD, layout, or encoding policy.
- TypeScript may orchestrate instances, transfers, presentation, and table coordination, but must not reconstruct a second analytical registry or canonical scene.
- Tests include native/WASM equivalence for supported fixtures and explicit unsupported-host or protocol mismatch diagnostics.
This section is authoritative over any earlier host-ownership wording in this issue. It does not broaden third-party payload compatibility or legacy-reader scope.
Problem
GraphForge returns typed Arrow results, but the extension currently decodes each table into plain JavaScript rows, preserves little schema information, stores one
lastResult, and heuristically recognizes genericsource/targetfields. Canonical GraphForge schemas instead use UUID-bearing fields such asnode_uuid,edge_uuid,source_uuid,target_uuid, UUID lists, metrics, communities, paths, and embeddings.Consequently, canonical edge/path results may not become graph geometry; identity, field types, relation metadata, path order, metrics, and embeddings may be dropped or manually reconstructed. Full JSON row copies also bypass XYG's typed-buffer/native scale path.
Objective
Create one schema-aware GraphForge-to-XYG projection boundary that preserves Arrow types, entity identity, provenance, and result semantics for every GraphForge result family.
Locked Decisions
Requirements
node_uuid,edge_uuid,src_uuid/dst_uuid,source_uuid/target_uuid, UUID-list columns, relation types, metrics, communities, path order/rank/cost, and embedding vectors.Acceptance Criteria
BDD Completion Scenarios
Scenario: Canonical edge/path result renders faithfully
Given a GraphForge-produced Arrow result using canonical UUID fields and ordered path/list columns
When the extension opens its XYG visualization
Then nodes, edges, order, metrics, types, and source rows are preserved
And no user-authored rename or row remapping is required.
Scenario: Analytical result is not silently misinterpreted
Given an embedding, scalar structural result, or ambiguous table
When no safe visualization intent exists
Then the extension requires an explicit supported composition or presents it as table-only
And never invents coordinates or semantic joins.
Implementation Notes
Likely affected surfaces include
arrowCodec.ts,GraphForgeSession, graph payload/projection models, visualization registry/spec, project commands, results selection linking, XYG Node adapter, and quickstart fixtures.Observability
Report safe result kind, schema ID/version, row/entity counts, transfer/projection duration, and stable error code only.
Security And Privacy
Validate schema metadata and types, bound buffers/rows, escape displayed text, and never log result values, vectors, coordinates, or paths.
Testing
GraphForge-produced Arrow fixtures for every result family, type/metadata preservation, identity joins, stale-generation negatives, large typed transfer, row/element selection, extension-host E2E, and memory/performance evidence.
Documentation
Update requirements, architecture, testing, command/agent contracts, result-schema coverage ledger, quickstart, and developer integration guide.
Non-Goals
Third-party renderer compatibility, legacy visualization readers, GraphForge algorithm execution in the extension, automatic chart recommendation, or first-two-dimension embedding plots.
Related Issues
Rust/WASM Architecture Amendment
This section is authoritative over any earlier host-ownership wording in this issue. It does not broaden third-party payload compatibility or legacy-reader scope.