ADR-038: Spatial Intelligence Architecture Patterns

Date: September 30, 2025 (Updated: October 1, 2025) Status: Accepted · AMENDED 2026-07-30 (Amendment A, Arch) — decision stands; verification claims corrected. Read Amendment A at the foot of this file before citing any operational claim. Context: CORE-GREAT-2C Verification Work (GitHub Issue #194), CORE-GREAT-2D Discovery (GitHub Issue #195) Supersedes: None Superseded by: None


⚠️ Before relying on this ADR’s verification claims — read Amendment A (at the foot of this file)

The decision below stands and is validated. Its verification claims are corrected. In one line: this ADR was right about the pattern and wrong about which connector proved it — notion_spatial, cited here as the Embedded-Intelligence proof, has zero importers, while Notion’s spatial capability is live by another route. Do not cite §§106–112, 134, 144 or 204 as current fact.

Spatial deletions remain HELD pending PM’s call; spatial intelligence is protected representation. Update 2026-08-29: PM ruled 2026-08-15/16 (spatial committed-theory review closed) and the cold-island disposal is now EXECUTED — notion_spatial and its cold peers are deleted from the live tree, retained as prior art via commit-hash references in the 2026-08-29 spatial-disposal entry of docs/internal/architecture/decisions/decisions.log. The live spatial layer (github_spatial, place_service, place_detector, home_state_service, spatial_intent_classifier, the spatial_adapter base class, the slack socket-path pair) stays — rescope, not abandonment.

(Two interim CXO notices stood here from 2026-07-29 as placeholders pending the amendment. Amendment A supersedes them and folds in their substance, so they are collapsed to this pointer rather than left to rot — they had already gone stale twice, describing three layers where the measured map has four. Removing the duplicate copy is the fix; m-46: don’t keep a measurable fact in two places, and when one is superseded, delete it rather than leaving a reader to discover which is current. — CXO, 2026-07-30)


Decision

Piper Morgan will support three distinct spatial intelligence patterns optimized for different integration domains:

  1. Granular Adapter Pattern for complex coordination scenarios
  2. Embedded Intelligence Pattern for streamlined knowledge management
  3. Delegated MCP Pattern for Model Context Protocol integrations (NEW - Oct 1, 2025)

All patterns are considered first-class architectural approaches, and new integrations should choose the pattern most appropriate for their domain.


Context

During CORE-GREAT-2C verification work (Phases 1-2, September 30, 2025), we discovered that Slack and Notion integrations implement fundamentally different but equally valid spatial architecture approaches.

During CORE-GREAT-2D investigation (Phase 0, October 1, 2025), we discovered Calendar implements a third distinct pattern using Model Context Protocol (MCP) delegation.

Slack Implementation (Granular Adapter Pattern)

Notion Implementation (Embedded Intelligence Pattern)

Calendar Implementation (Delegated MCP Pattern) - NEW

Verification Results


Options Considered

Option 1: Standardize on Single Pattern (REJECTED)

Force all integrations to use the same architectural approach.

Advantages:

Disadvantages:

Option 2: Support Multiple Patterns (CHOSEN)

Allow domain-optimized architectures based on integration characteristics.

Advantages:

Disadvantages:

Decision: CHOSEN - Benefits outweigh costs. October 2025 update: Calendar’s Delegated MCP Pattern confirms this approach scales well for protocol-based integrations.

Option 3: Hybrid Approach (REJECTED)

Combine both patterns in single implementation (e.g., granular components with embedded access).

Advantages:

Disadvantages:


Decision Rationale

Core Principle: Domain-Optimized Architecture

Key Insight: Domain-specific optimization outweighs standardization for standardization’s sake.

Different integration domains have fundamentally different spatial requirements:

Reactive Coordination (Slack):

Analytical Intelligence (Notion):

Evidence-Based Decision

Production Validation:

Architectural Quality:

Developer Experience:


Implementation

Pattern Selection Criteria

New spatial integrations must choose pattern based on:

  1. Domain Complexity:

    • Many distinct capabilities (>5) → Granular
    • Few focused capabilities (≤5) → Embedded
    • MCP Protocol required → Delegated MCP (Oct 2025)
  2. Requirement Stability:

    • Evolving requirements → Granular (easier to extend)
    • Stable requirements → Embedded (lower overhead)
    • Protocol-driven → Delegated MCP
  3. Performance Criticality:

    • Performance critical → Embedded (minimal overhead)
    • Performance adequate → Either pattern
    • External service → Delegated MCP (protocol overhead acceptable)
  4. Testing Requirements:

    • Component-level isolation needed → Granular
    • Integration-level testing sufficient → Embedded
    • Protocol compliance testing → Delegated MCP
  5. Team Structure:

    • Multiple developers on feature → Granular (parallel work)
    • Single developer or small team → Embedded (simpler)
    • MCP team + integration team → Delegated MCP (separation of concerns)
  6. Domain Nature:

    • Reactive coordination → Granular
    • Analytical intelligence → Embedded
    • Temporal/contextual awareness via protocol → Delegated MCP
  7. Integration Architecture (NEW - Oct 2025):

    • Model Context Protocol (MCP) required → Delegated MCP
    • Separate consumer layer exists → Delegated MCP
    • Protocol-specific spatial logic → Delegated MCP
    • All other cases → Granular or Embedded

Pattern Descriptions

Granular Adapter Pattern

When to Use:

Structure:

services/integrations/{integration}/
  spatial_types.py          # Domain types and primitives
  spatial_adapter.py        # Main adapter (inherits BaseSpatialAdapter)
  spatial_agent.py          # Navigation and awareness
  spatial_intent_classifier.py  # Intent classification
  spatial_mapper.py         # Domain-specific mapping
  spatial_memory.py         # Memory storage/retrieval
  tests/
    test_spatial_*.py       # Component-level tests

Access Pattern:

router = IntegrationRouter()
adapter = router.get_spatial_adapter()
result = await adapter.map_to_position(context)

Embedded Intelligence Pattern

When to Use:

Structure:

services/intelligence/spatial/{integration}_spatial.py
  # Single comprehensive class
  # 8-dimensional analysis methods
  # Built-in analytics tracking
  # Internal router usage

Access Pattern:

spatial = IntegrationSpatialIntelligence()
await spatial.connect()
analysis = await spatial.get_comprehensive_spatial_analysis(item_id)

Delegated MCP Pattern (NEW - Oct 2025)

When to Use:

Structure:

services/integrations/{integration}/
  {integration}_integration_router.py  # Minimal router (delegation only)

services/mcp/consumer/
  {integration}_adapter.py             # MCP adapter (inherits BaseSpatialAdapter)
    # Spatial intelligence implementation
    # MCP protocol compliance
    # Custom spatial context extraction

Access Pattern:

router = IntegrationRouter()
# Router methods delegate to MCP adapter
events = await router.get_todays_events()
# Spatial methods also available
context = router.get_context(external_id)

Key Characteristics:

Example: Calendar integration

Common Requirements

All spatial patterns must:

  1. Router Integration:

    • Use IntegrationRouter (directly or indirectly)
    • Support feature flag control (USESPATIAL*)
    • Provide health check capabilities
    • Update Oct 2025: Delegated MCP Pattern delegates through router to MCP adapter
  2. 8-Dimensional Spatial Metaphor:

    • Implement relevant dimensions for domain
    • Use consistent naming (HIERARCHY, TEMPORAL, PRIORITY, COLLABORATIVE, FLOW, QUANTITATIVE, CAUSAL, CONTEXTUAL)
    • Document which dimensions supported
    • Update Oct 2025: Calendar implements TEMPORAL dimension via temporal_summary
  3. Backward Compatibility:

    • Graceful degradation when spatial disabled
    • Don’t break existing functionality
    • Support legacy mode via feature flags
    • Update Oct 2025: All 3 patterns support feature flag control
  4. Async Patterns:

    • Use async/await for I/O operations
    • Support concurrent operations where appropriate
    • Handle cleanup properly
  5. Observability:

    • Log spatial operations appropriately
    • Track analytics/metrics
    • Support debugging and troubleshooting
    • Update Oct 2025: Delegated MCP Pattern includes circuit breaker pattern for resilience

Consequences

Positive Consequences

  1. Optimal Performance: Each integration uses pattern suited to its needs
  2. Appropriate Complexity: No over-engineering or under-engineering
  3. Production-Proven: Both patterns validated and operational
  4. Clear Guidance: Selection criteria documented
  5. Flexibility: Future integrations can choose appropriate pattern
  6. No Breaking Changes: Both existing patterns continue working

Negative Consequences

  1. Multiple Patterns: Two patterns to maintain instead of one
  2. Documentation Overhead: Must document both patterns
  3. Training: Developers need to understand pattern selection
  4. Consistency Risk: Must ensure both patterns follow core requirements

Mitigation Strategies

For Multiple Patterns:

For Documentation Overhead:

For Training:

For Consistency:


Compliance Requirements

For Existing Implementations

Slack (Granular Adapter Pattern):

Notion (Embedded Intelligence Pattern):

For New Implementations

New spatial integrations must:

  1. Choose Pattern: Use decision framework to select appropriate pattern
  2. Document Choice: Create brief rationale document explaining pattern choice
  3. Follow Requirements: Implement all common requirements
  4. Feature Flags: Support USESPATIAL{INTEGRATION}=true/false
  5. Router Integration: Integrate with IntegrationRouter infrastructure
  6. Dimensions: Implement relevant 8-dimensional analysis
  7. Testing: Provide appropriate test coverage (component or integration)
  8. Documentation: Update spatial pattern guide with integration

Review Process

Pattern selection should be reviewed during:


References

Documentation

Source Code

Verification


Version History

Date Version Author Changes
2025-09-30 1.0 Claude Code Initial ADR creation based on GREAT-2C verification

Approval

Approved by: CORE-GREAT-2C Verification Work (Phases 1-4) Implementation Status: Complete and Operational Production Status: Both patterns deployed and validated


Next Review: After next spatial integration implementation Related ADRs: None (first spatial architecture ADR) Supersedes: None Superseded by: None (active)


Update October 2025

See ADR-034: Plugin Architecture Implementation for the plugin system that now manages all spatial intelligence integrations. The three spatial patterns documented in this ADR are now implemented as plugins following the Wrapper/Adapter pattern, providing:

All spatial intelligence patterns remain valid architectural choices, now enhanced with plugin capabilities.


This ADR documents the discovery and validation of two production spatial patterns during GREAT-2C verification work (September 30, 2025).


Amendment A — 2026-07-30 (Arch)

Status of the amendment: ACCEPTED as a correction to this ADR’s verification claims. The decision is NOT reversed. Authored by: Chief Architect · Sources: ../spatial-intelligence-layer-map-and-costed-options.md (the measured map), ../spatial-intelligence-experience-thesis.md (CXO, the experience argument). Supersedes: the two ⚠️ notices at the head of this file, which were placeholders pending this amendment. Their substance is folded in here.

A1 — The decision stands. The three-pattern pluralism is VALIDATED, not aspirational.

ADR-038 replaced ADR-013’s maximalism (“ALL external tool integrations MUST use the unified MCP + Spatial Intelligence pattern”) with domain-appropriate pluralism. That call was right and the evidence has strengthened, not weakened. Every connector a user can actually connect today has a live spatial path, and they arrive by different patterns — which is precisely what this ADR predicted:

Advertised connector Live spatial path Pattern
Slack integrations/slack/spatial_adapter (3 importers) Granular Adapter
Notion mcp/consumer/notion_adapter → notion_integration_router (see A2 — not the pattern this ADR cited)
Calendar mcp/consumer/google_calendar_adapter → calendar_integration_router Delegated MCP
GitHub integrations/spatial/github_spatial + mcp/consumer/github_adapter full 8-dimensional, live

No part of this ADR’s decision requires amendment. What requires amendment is how it evidenced the decision.

A2 — ⚠️ The verification claims are CORRECTED. One of three citations went stale.

The Verification Results section (and the “Production-proven / Proven operational” lines at §§112, 134, 144, 204) asserted per-connector operational status. Measured 2026-07-30:

ADR-038 claim Current state Verdict
“Slack spatial: 11 files, 100% operational” slack/spatial_adapter live — 3 importers ✅ holds
“Calendar spatial: 2 files, 100% operational, MCP protocol integration” google_calendar_adapter live via calendar_integration_router ✅ holds
“Notion spatial: 1 file, 100% operational, 8-dimensional analysis working” intelligence/spatial/notion_spatial has ZERO importers and ~12 undefined methods (~75% abandoned) ❌ CONTRADICTED

But Notion’s spatial capability is live — via mcp/consumer/notion_adapter, which produces SpatialContext/SpatialPosition. Notion users are not missing place-modeling. What is dead is the specific file this ADR cited as proof.

Do not cite §§106–112, 134, 144 or 204 as current fact. They were true when written; one is now false, and all four are frozen snapshots of a moving system.

A3 — ★ The methodological error, named so it doesn’t recur

ADR-038 was right about the pattern and wrong about which connector proved it.

The notion_spatial citation didn’t go stale because the pattern failed. It went stale because CORE-MCP-MIGRATION #198 moved the implementation — replacing per-connector direct-API spatial modules with MCP consumer adapters built on the same spatial contract (BaseSpatialAdapter / SpatialContext, services/integrations/spatial_adapter.py) — while this ADR kept pointing at the superseded predecessor.

The error class: citing an IMPLEMENTATION as evidence for a PATTERN that outlives it. An implementation is a point-in-time fact with a short half-life; a pattern is a decision. Binding the second to the first means a successful migration makes the ADR look falsified — and that is exactly what happened here. An agent reading §107 against the cold notion_spatial file would conclude the pattern failed. It succeeded so thoroughly that the code it was demonstrated on became redundant.

Forward rule for this corpus: an ADR may cite implementations as illustration, never as proof of continuing validity. Where an ADR needs to make a live/cold claim, it must point at a command that re-derives it rather than freezing a table. (This amendment follows that rule — see A4.)

A4 — Where the facts live now

This amendment deliberately does not restate the live/cold inventory. It lives in ../spatial-intelligence-layer-map-and-costed-options.md, and every claim there is re-derivable:

python3 scripts/reachability-map.py services/integrations/spatial services/intelligence/spatial services/mcp/consumer

If any table in this corpus disagrees with that command, the command is right. (CXO’s formulation, 2026-07-30: “prose can’t be re-run; the tool can” — adopted here as a corpus convention, not just a note.)

⚠️ A string match on a module name is not an import edge. Both CXO and I independently mistook config_service.py:222’s feature-flag string "notion_spatial_mapping" for a notion_spatial importer, within a day of each other. Use the tool.

A5 — What is still open (this amendment closes none of it)

The committed-theory review has not concluded. Open: PPM’s roadmap-dependency slice; Lead’s cost estimate for an L4 (ambient-presence) monitoring loop; and PM’s call on the 10-module cold island, which should be described as “superseded implementation strategy, retained as prior art” rather than dead code — it holds the only worked examples of place-modeling for four connectors.

Spatial deletions remain HELD. Spatial intelligence is protected representation under PM’s standing rule, and nothing here authorizes removal.