feat(spatial): qualify context-bound 3D relations before HDC scene-graph projection

Purpose

Define a metric/contextual 3D relation layer above persistent object hypotheses (#591) without pretending every relation is an observer-independent physical fact or letting HDC relation triples become the source of geometric truth.

The current VisionManifold scene graph uses image-plane relations:

Above
Below
LeftOf
RightOf
Near
Far
Overlapping

Those are useful perceptual/cognitive descriptors, but a qualified 3D world model needs to say relative to what frame, viewpoint, gravity convention, tolerance, geometry, and uncertainty a relation was derived.

Intended composition:

#575 physical free-space/surface belief
        ↓
#591 persistent object hypotheses
        ↓
THIS ISSUE: contextual metric/geometric relation beliefs
        ↓
HDC relation projection / semantic scene graph
        ↓
later functional/causal relations and planning

Core non-equivalences

Freeze explicitly:

2D image relation != 3D world relation
left/right in camera image != world-invariant left/right
above/below != meaningful without an up/gravity/reference convention
near/far != universal physical predicates
bounding-box overlap != physical contact
surface proximity != support
vertical ordering != support
partial enclosure cue != containment
occlusion != object-object intrinsic relation
semantic plausibility != geometric truth
HDC relation vector != verified relation
relation confidence != action authority
missing relation != false relation

Also:

relation not currently observable != relation false

Relation families must be typed by transformation/reference behavior

Do not use one flat enum whose predicates silently mix incompatible semantics.

Conceptually separate at least:

RelationBeliefV1
├── MetricRelation(...)
├── WorldDirectionalRelation(...)
├── ObserverRelativeRelation(...)
├── SurfaceTopologyRelation(...)
└── SemanticOrFunctionalRelation(...)   // downstream / separately qualified

Exact Rust representation may use tagged structs rather than enums, but a caller must be able to tell what reference context makes the predicate meaningful.

1. Metric relations

These are explicitly quantitative or thresholded over metric state, for example:

centroid_distance_m
minimum_supported_surface_distance_m
separation_along_axis

If Near is exposed, it must bind an exact threshold/profile:

NearV1 {
    threshold_m,
    metric_definition,
    geometry_profile,
}

Changing the threshold changes relation derivation identity.

Do not make Near a timeless semantic fact when task/object scale changes its meaning.

2. World/gravity-relative directional relations

Above / Below require a declared up direction or gravity frame.

Conceptually:

GravityAlignedRelationContextV1
├── world_frame
├── up_axis / gravity_direction
├── tolerance
└── profile_version

Then a predicate may mean something precise such as:

object A's supported spatial interval lies higher than object B's along the declared gravity axis by at least the declared margin.

Do not infer gravity from camera image vertical direction.

If gravity/up is unknown, return unsupported/indeterminate rather than guessing.

3. Observer-relative relations

Predicates such as:

LeftOf
RightOf
InFrontOf
Behind
Occludes

may depend on observer/camera pose.

Bind the exact viewpoint/reference:

ObserverRelativeRelationContextV1
├── observer_frame / camera frame
├── viewpoint pose identity
├── projection model
├── comparison profile
└── observation/prediction provenance

The same object pair may legitimately change Left/Right under viewpoint rotation without the world changing.

Occludes(A,B,view) is explicitly ternary/contextual in meaning even if encoded as an edge with attached context.

Occludes(A,B,view1) != Occludes(A,B,view2)

4. Surface/topological relations

Be conservative about what #575/#591 can establish.

Contact

A useful V1 predicate may be:

SurfaceContactWithinToleranceV1

rather than metaphysical exact contact.

It binds:

• surface-support geometry;
• positional uncertainty;
• spatial resolution;
• tolerance/model version.

Support

Do not infer Supports(A,B) from vertical proximity alone.

A qualified support relation needs enough witness/model structure to justify at least relevant combinations of:

• contact/proximity;
• gravity-relative ordering;
• projected support overlap / stability criterion;
• uncertainty;
• later dynamics/force information where the stronger meaning requires it.

V1 may expose GeometricSupportCandidateV1 or defer support entirely until the witness is qualified.

Containment

Do not infer physical Inside/Contains from incomplete front surfaces or centroid-in-bounding-box heuristics.

If the enclosing geometry is not sufficiently closed/qualified, expose a weaker relation such as:

InsideObservedBoundsCandidateV1

or remain indeterminate.

Strong containment belongs downstream of a qualified topology/closed-volume model.

Relation truth state

Avoid bare booleans where observability/uncertainty matter.

Conceptually:

RelationAssessmentV1
├── relation_kind
├── subject_ref
├── object_ref
├── context_ref
├── state: Supported | Refuted | Indeterminate | Unobservable
├── support / uncertainty diagnostics
├── geometric witness refs
└── lineage

Indeterminate and Unobservable are different:

Indeterminate:
    relevant evidence exists but does not resolve the predicate

Unobservable:
    current geometry/view/evidence cannot test it adequately

Do not turn missing relation labels into negatives.

Geometric relation witnesses

Each positive relation should retain the actual evidence/features that made it testable.

Conceptually:

RelationWitnessV1
├── object-state refs
├── physical-belief refs
├── exact geometric measurements
├── uncertainty / tolerance
├── viewpoint/gravity context where relevant
├── predicate evaluator version
└── witness_digest

A semantic model may propose candidate relations, but proposal alone is not a geometric witness.

Inverse / symmetric / transformation laws

Freeze algebra per predicate instead of assuming all relations behave alike.

Examples:

Above(A,B,g) <-> Below(B,A,g)
LeftOf(A,B,v) <-> RightOf(B,A,v)
Contact(A,B) == Contact(B,A)
Near(A,B,r) == Near(B,A,r)
Occludes(A,B,v) != Occludes(B,A,v)
Contains(A,B) <-> Inside(B,A)   // only when strong containment is qualified

Also declare whether each relation is:

• observer invariant;
• equivariant under frame/view transformation;
• symmetric/asymmetric;
• inverse-paired;
• potentially transitive;
• explicitly non-transitive.

Do not assume Near, contact, or occlusion are transitive.

HDC projection comes after relation derivation

Once a relation assessment exists, Symthaea may project it into cognitive HDC form:

subject_semantic_hv
    ⊗ relation_basis
    ⊗ object_semantic_hv
    ⊗ optional context_hv
        ↓
relation_hv

But:

relation_hv = semantic representation of a relation assessment
relation_hv != authority that the metric relation is true

Unbinding/query results are hypotheses/semantic retrieval, not geometric proof.

Any ContinuousHV bundling used in the evidence-bearing path must depend on the qualified #561/#509 contract.

Relationship to existing VisionManifold graph

Keep the current visual graph as an observer-centric perceptual layer.

Prefer an explicit bridge:

VisualSceneGraph
    (image-plane / perceptual)
          ↓ proposal/context
SpatialRelationAssessmentV1
    (metric/context-bound world belief)
          ↓
HDC semantic scene graph

Do not silently change the semantics of the existing SpatialRelation enum and break old callers/checkpoints.

V1 positive predicate set

Keep the first qualified set intentionally small, for example:

1. metric object/object distance;
2. gravity-relative above/below when up is explicitly known;
3. observer-relative left/right for an exact viewpoint;
4. observer-relative occlusion for an exact viewpoint;
5. surface-contact-within-tolerance;
6. explicit unknown/indeterminate/unobservable states.

Treat strong support, containment, attachment, part-of, reachable-by, affordance, ownership, and semantic relations as later tranches unless their witness models are separately qualified.

Qualification fixtures

Include controlled scenes for at least:

1. fixed scene, rotating camera: observer Left/Right changes correctly;
2. fixed scene, camera yaw rotation with world Above/Below invariant under fixed gravity context;
3. unknown gravity -> Above/Below indeterminate/unsupported;
4. exact object pair at multiple metric distances;
5. Near threshold boundary with uncertainty;
6. partial occlusion vs full occlusion from two viewpoints;
7. A occludes B from view1 but not view2;
8. surfaces within contact tolerance;
9. surfaces near but outside contact tolerance;
10. vertically stacked but non-contacting objects -> no support claim;
11. centroid inside another object's bounding box with open/incomplete geometry -> no strong containment claim;
12. missing/occluded evidence -> unobservable rather than false;
13. symmetric/inverse-law property tests;
14. frame-generation mismatch;
15. object-hypothesis ambiguity propagated into relation uncertainty;
16. changed predicate threshold/profile -> changed derivation identity.

Required measurements

Report at least:

• precision/recall for each qualified predicate;
• false-positive rate on tempting but invalid support/containment fixtures;
• viewpoint equivariance/invariance error by predicate family;
• inverse/symmetry law violations;
• indeterminate/unobservable calibration or coverage;
• sensitivity to object pose/extent uncertainty;
• threshold-boundary stability;
• replay/state digest determinism;
• bounded relation-update cost.

Canonical identity

Separate:

relation_state_digest
    = canonical relation assessments

relation_profile_digest
    = predicate schemas
    + reference-context semantics
    + geometry/tolerance rules
    + evaluator versions

relation_witness_digest
    = exact object/physical inputs
    + measured relation features
    + context

lineage_digest
    = #511 state kind/schema
    + object-state parents
    + relation profile/witnesses
    + relation state digest

Changing viewpoint, gravity convention, tolerance, or metric rule must change the relevant relation identity even when the rendered scene looks unchanged.

Ordering

#575 physical belief
        ↓
#591 persistent object hypotheses
        ↓
THIS ISSUE: context-bound 3D relations
        ↓
HDC semantic relation projection
        +
#594 metric time / transition evidence
        ↓
dynamics / functional relations / affordances

Exit gate

V1 qualifies only if:

1. observer-relative and world-relative predicates are structurally distinguishable;
2. gravity-dependent relations cannot be asserted without gravity/up context;
3. occlusion binds an exact viewpoint;
4. Near/Far cannot exist without explicit metric/profile semantics;
5. surface proximity cannot silently become support/contact/containment;
6. unknown/unobservable relation state is preserved;
7. HDC relation encoding is downstream of, not authority for, the geometric assessment;
8. relation lineage binds every replay-critical frame/view/tolerance rule;
9. no relation output grants action or physical-truth authority.

Start by locating the existing VisionManifold graph, the SpatialRelation enum, and the ContinuousHV relation-encoding path. Map how those current observer-centric relations flow into the scene graph before defining the qualified V1 assessment layer. Done means the specified context distinctions, uncertainty states, witnesses, fixtures, measurements, and downstream-only HDC projection are covered without changing existing relation semantics.