REST_REDUCTION_VISIBILITY_IMPLEMENTATION_PLAN

REST Reduction Visibility Implementation Plan

Status: active implementation plan

Purpose

This document defines the implementation sequence for bringing the Moira REST surface into full alignment with the reduction-visibility contract.

It is not the contract itself. It is not the audit ledger.

Those roles remain owned by:

• ENGINE_VS_SERVICE_BOUNDARY.md
• SERVICE_LAYER_GUIDE.md
• REST_REDUCTION_VISIBILITY_AUDIT.md

This plan governs rollout order, transport shape decisions, verification obligations, and deferral discipline.

---

1. Governing Objective

The REST API must not collapse facade-visible computational truth into an opaque final-only transport when the engine already exposes meaningful reduction, policy, fallback, classification, or branch truth.

The implementation goal is therefore:

• preserve compact consumer-facing routes where useful
• add lawful reduction access without breaking existing callers
• keep transport truth summary-grade rather than exposing unstable internal implementation details
• expand route families in a controlled order, starting with foundational surfaces

---

2. Current Baseline

As of 2026-06-04:

• positions is the first fully remediated pilot family
  • compact routes remain:
    • /v1/positions/planet
    • /v1/positions/sky
  • sibling reduction routes now exist:
    • /v1/positions/planet/reduction
    • /v1/positions/sky/reduction
• chart now has a sibling reduction route:
  • /v1/chart/reduction
• transits and relationship already preserve substantial doctrinal truth
• primary-directions now has a sibling reduction route on the core arc-search surface:
  • /v1/primary-directions/arcs/reduction
• primary-directions search-derived routes now also include:
  • /v1/primary-directions/profile/reduction
  • /v1/primary-directions/network/reduction
• progressions chart-producing routes now have sibling reduction routes:
  • /v1/progressions/secondary/reduction
  • /v1/progressions/secondary-declination/reduction
  • /v1/progressions/arc/reduction
  • /v1/progressions/time-key/reduction
• progressions family completion routes now also include:
  • /v1/progressions/house-frame/reduction
  • /v1/progressions/house-frame/arc/reduction
  • /v1/progressions/profile/reduction
  • /v1/progressions/network/reduction
• several other route families are structurally healthy but inconsistent in how directly they expose reduction truth

This baseline is tracked in the live audit:

• REST_REDUCTION_VISIBILITY_AUDIT.md

---

3. Rollout Strategy

The rollout proceeds in four waves.

Wave 1: Foundational Surface Closure

Goal:

• make the foundational entry surfaces reduction-visible

Status:

• implemented as of 2026-06-04 on the current admitted surface

Families:

• chart
• houses only as needed for symmetry with chart-level reduction transport

Primary deliverables:

• add a lawful chart reduction surface
• expose normalized datetime and Julian-day reduction
• expose observer context when present
• expose chart assembly policy actually applied
• expose per-body reduction summaries without requiring callers to reconstruct them body-by-body from separate endpoints

Preferred transport shape:

• sibling reduction endpoint
  • /v1/chart/reduction

Why:

• it preserves the current compact /v1/chart contract
• chart reduction is heavier than the positions reduction payload
• the chart route is foundational enough that a separate truth surface is easier to keep stable

Exit criteria:

• a chart reduction route exists
• compact /v1/chart remains backward-compatible
• chart reduction includes enough information to explain how each returned body reached transport form

Current state:

• satisfied by /v1/chart/reduction
• houses remains compact, with later sibling expansion left optional rather than required for wave closure

Wave 2: Doctrinal Tension Closure

Goal:

• resolve families whose current transport language explicitly understates engine truth

Status:

• implemented as of 2026-06-04 on the current search-derived route family

Families:

• primary-directions

Primary deliverables:

• remove any transport posture that implies permanent omission of policy truth
• add a lawful path to fuller reduction or policy surfaces
• preserve current compact or opt-in ergonomics where possible

Preferred transport shape:

• likely sibling reduction routes or stronger expansion flags
• this family should not be widened casually on the main result routes

Exit criteria:

• no model or serializer language remains in open tension with the service contract
• a caller can inspect direction doctrine, policy, and branch truth without reading engine internals directly

Current state:

• satisfied on the search-derived route family through:
  • /v1/primary-directions/arcs/reduction
  • /v1/primary-directions/profile/reduction
  • /v1/primary-directions/network/reduction
• speculum remains compact-first and may remain so unless a later service decision requires a sibling truth surface

Wave 3: Family Consistency Sweep

Goal:

• normalize partially compliant families so that similar truth domains are exposed through similar transport conventions

Status:

• started as of 2026-06-04 on the progression chart-producing routes

Families:

• progressions
• timelords
• returns
• varshaphal
• visibility
• phenomena

Primary deliverables:

• route-by-route audit against the now-stabilized pattern
• add reduction flags or sibling reduction routes where real gaps remain
• align field naming for:
  • computation truth
  • classification
  • relation
  • condition profile
  • observer context
  • policy actually applied

Exit criteria:

• no major family remains merely "accidentally partial"
• comparable route families use comparable truth vocabulary

Current state:

• progressions is now functionally closed at the family level
• house-frame/cusps remains intentionally compact
• timelords, returns, varshaphal, visibility, and phenomena remain unswept in Wave 3 terms

Wave 4: Aggregate Surface Integrity

Goal:

• ensure aggregate routes do not erase per-item reduction truth

Status:

• started as of 2026-06-04 on batch/charts and batch/progressions

Families:

• batch
• any multi-result wrappers introduced later

Primary deliverables:

• preserve or embed per-result reduction where the wrapped family already has a lawful truth surface
• define when aggregate routes may intentionally omit reduction for payload economy and how the caller recovers it

Exit criteria:

• aggregation does not silently black-box already-compliant route families

Current state:

• /v1/batch/charts/reduction now preserves per-item chart reduction truth
• /v1/batch/progressions/reduction now preserves per-item progression reduction truth
• compact batch/transits and transit/ingress-style batch/events already preserve embedded wrapped-family truth through their event payloads
• batch/returns remains bounded by the weaker direct returns family
• heterogeneous batch/events remain mixed because not every event subtype has the same admitted reduction depth
• Wave 4 is therefore started but not closed

---

4. Transport Shape Rules

This plan freezes the following implementation preferences.

4.1 Compact Base Routes Stay Compact

Do not widen every existing response with large optional reduction fields by default.

Reason:

• backward-compatibility
• payload economy
• easier client migration

4.2 Prefer Sibling Reduction Endpoints For Heavy Foundational Routes

Preferred examples:

• /v1/chart/reduction
• /v1/positions/planet/reduction
• /v1/positions/sky/reduction

Use sibling reduction endpoints when:

• the reduction payload is large
• the family is foundational
• the same request body can be reused cleanly

4.3 Use Expansion Flags Only When The Truth Surface Is Modestly Additive

Use include_* style expansions when:

• the payload increase is small
• the route already uses opt-in enrichment
• the truth being added is structurally subordinate to the main result

Likely candidates:

• parts of primary-directions
• selective progressions enrichments

4.4 Do Not Expose Unstable Internal Implementation State

Reduction transport should preserve:

• admitted stage sequence
• applied policy
• branch/fallback/classification truth
• normalized inputs
• observer context

Reduction transport should not promise:

• volatile helper-level internals
• debug-only intermediate vectors
• unstable substrate-private caches

---

5. Implementation Order

The concrete next steps are:

1. Audit whether houses needs a sibling reduction endpoint or only chart-level embedding.
2. Decide whether primary-directions/speculum should remain compact-only or gain a sibling reduction route.
3. Sweep timelords.
4. Sweep varshaphal, visibility, and phenomena. (returns direct family now complete with embedded reduction contract + controls.)
5. Update batch/returns now that direct returns has a family-level reduction contract (embedded computation_truth).
6. Revisit heterogeneous batch/events only after the weaker event subtypes have stronger family-level truth surfaces.

Sequencing law:

• do not start broad family consistency work until chart is closed
• do not widen aggregate routes before the embedded families stabilize

---

6. Verification Liturgy

Each implementation wave must satisfy both transport and behavioral checks.

6.1 Transport Checks

For each remediated route family:

• server route tests must verify compact-route backward compatibility
• server route tests must verify reduction-route truth presence
• validation-envelope behavior must remain unchanged for malformed input
• response models must remain strict (extra="forbid")

6.2 Truth Checks

Reduction-route tests should verify, where relevant:

• normalized datetime and Julian-day truth
• observer context
• policy actually applied
• fallback or effective-system truth
• classification truth
• admitted stage sequence
• result/reduction agreement

6.3 Deferral Honesty

If a family is judged too underdetermined for immediate remediation:

• record the reason in the audit
• do not mark the family compliant prematurely
• do not hide the gap behind "future expansion" language

---

7. Non-Goals

This plan does not authorize:

• replacing the engine-facing facade with REST-first semantics
• exposing raw debug internals as if they were stable public doctrine
• refactoring unrelated route families for aesthetic uniformity
• breaking existing compact-route clients unless a separate compatibility decision is made explicitly

---

8. Completion Standard

This roadmap is complete only when:

• every foundational family has a lawful reduction path
• every partially compliant family has been either remediated or explicitly deferred with a stated reason
• no service-layer document still frames transport opacity as an intended endpoint
• batch and aggregate routes preserve, rather than erase, already-admitted reduction truth

Until then, the audit remains the live state ledger and this plan remains the governing rollout sequence.