# Nyx observe loop · working package · 9 September 2026

This package completes the meaningful units in `V1/features/domain-nyx.md`. The
existing nine-slide Nyx introduction already establishes the product boundary,
tonight computation, observation quality, calendar loop and failure posture.
This guide follows one computed event farther: through the actual consumer
routes, canonical event and observation contracts, the compact private write,
the richer local-first deep log, event actions, reminder delivery and calendar
export.

Implementation baseline and primary citation pin:
`1ceae52c7896a59ac74a4429d410f3218f0b91c6`.

Visual thesis: present Nyx as a calm observing field guide. Cream paper, deep
ink and the route's night-sky image move from computation into evidence and
memory. Product captures establish the visual world; compact record anatomy and
handoff diagrams identify the state owner beneath it. Every prediction,
observation and persistence claim carries its evidence level in the slide.

Content plan: open with one Greenwich moonrise and establish the five evidence
levels. Map the five consumer destinations, the separate twenty-tool domain tree
and the mobile companion boundary. Walk the ephemeris from Julian time through
Sun, Moon, illumination, observer coordinates and horizon thresholds, then show
its known answers and twenty depth calculators. Move into the twenty-seven event
types, eleven families, source-support matrix and canonical event refinements.
Compare canonical `LoggedObservation` with the compact owner-scoped service
record and the richer browser-local `NyxObservation`. Follow tonight's event id
through the form, local-first merge, event actions, reminder routes, delivery
bridge, calendar contract and mixed computed/authored ICS feed. Finish with
cross-domain helper boundaries and a worked state trace.

Interaction thesis: use the established deck navigation, narration, source
drawer and keyboard-accessible image inspection. The computed room anchors the
opening third; the almanac, tonight, compact observation and agenda captures
reappear at each decision point. Ownership diagrams preserve exchange order in
HTML and PDF, while every image remains available at full resolution.

## Source review and corrected boundaries

The handbook's computational and contract descriptions are strong. The pinned
implementation needs the following evidence labels:

- The consumer tree has five destinations: `/nyx`, `/nyx/events`,
  `/nyx/observation`, `/nyx/sky-almanac` and `/nyx/tonight`. The separate
  `/domains/nyx/*` tree contains twenty power-user pages, including a dynamic
  event detail and two observation-log variants.
- The mobile app has a `TaraNyxPerspectiveCompanionCard`; no standalone Nyx
  mobile route exists at the pin.
- The ephemeris implements Julian Day, solar and lunar position, lunar
  illumination, sidereal time, horizontal coordinates and rise/transit/set.
  Longitude is east-positive. The standard altitudes are -0.8333 degrees for the
  Sun, +0.125 for the Moon and -0.5667 for a star.
- The depth library contains twenty calculators, twenty focused tests and one
  page builder. The actual Sky Almanac route composes four sections and fourteen
  rows for the declared observer.
- `SkyEvent` maps twenty-seven types into eleven families. It requires ordered
  times, unique internal ids, a family-specific detail block and at least one
  prediction source that supports the family. Weather and Bortle sources add
  context but support no event family on their own.
- Canonical `LoggedObservation` retains member, site, conditions, equipment,
  quality, attachments and sharing. The compact consumer form writes only event
  id, target, time, one of four condition bands and a note to an owner-scoped
  service store. It is not a persistence path for the full canonical contract.
- The deep observation workspace writes a richer `NyxObservation` to the
  browser-local `oshun.nyx` store before attempting the service POST. It
  compresses the condition fields for the service row, then records a server id
  on success and merges service readback with local history.
- The compact observation service has three store tiers: PostgreSQL when
  configured, a file snapshot for development, and memory in tests or when no
  file path is available. Every list filters by the authenticated owner; legacy
  unowned rows are served to nobody.
- The event-action hook writes `oshun:nyx:event-actions:v1` first and later
  merges authenticated GET/PUT state by `updatedAt`. The aggregate route uses a
  compatibility in-memory authority in development and returns 503 in production
  unless an authority is injected. Separately, saved objects, reminders and
  search counts in `nyx-member-stores.ts` are wired to durable snapshots. These
  are distinct server-side owners.
- The reminder bridge delivers existing enabled Nyx reminders through the in-app
  scheduler. It does not create opt-ins, uses
  `nyx-event:${userId}:${reminderId}` as stable identity and fails soft per
  user.
- `CalendarSyncEntry` models Google, Apple, Outlook and file export, including
  remote ids, sync timestamps and conflicts. The inspected customer action
  proves ICS generation. It does not prove provider OAuth synchronization.
- The upcoming feed computes principal lunar phases and solar season markers.
  Five meteor and eclipse rows are hard-coded featured templates. They have no
  attached source id, URI, attribution or citation record, even though the
  source comment calls them source-backed.
- Tara, Nisaba, Metis, Veritas and assistant relationship helpers return real,
  typed deterministic outputs and target paths. Those functions do not alone
  establish a shared cross-domain record or an executed consumer handoff.

## Working story

1. Follow one moonrise from computed geometry into an observation invitation.
2. Separate contract, executed computation, browser state, service state and
   product-route evidence.
3. Map the consumer, power-user and mobile surface boundaries.
4. Trace Julian time, solar and lunar geometry, illumination, observer
   transformation and rise/transit/set.
5. Inspect known-answer tests and the composed depth-page model.
6. Build a canonical `SkyEvent` from taxonomy, detail blocks, event invariants,
   regional windows and prediction sources.
7. Compare canonical `LoggedObservation`, the compact service row and the richer
   local-first deep-log record.
8. Follow the tonight URL handoff and account for every field retained by the
   owner-scoped service.
9. Separate browser-first event actions from the two server-side Nyx owners.
10. Trace reminder routes into additive in-app delivery.
11. Separate provider sync contracts from the implemented ICS export and label
    computed versus authored agenda rows.
12. Map cross-domain helper outputs, current implementation status and the
    complete worked moonrise trace.

## Acceptance and recovery

The final guide must preserve all twenty-two meaningful Nyx handbook units with
exact source hashes and exact slide fingerprints. Focused characterization must
prove route ownership, mobile scope, ephemeris constants and known answers,
depth-library counts, contract refinements, source support, observation-model
divergence, owner scoping, local-first merge, event-action authorities, reminder
delivery, calendar rules, mixed event provenance and cross-domain return-value
boundaries. Existing owning contract, domain, BFF and web suites remain separate
evidence.

The candidate must pass the presentation builder, focused manuscript and source
contracts, assignment validation, narration integrity, standalone Playwright,
Presentation Center review, PDF text and bounds checks and complete optical
review. The five product captures must retain their actual local Next/BFF route
scope and zero automated axe violations. No source-level, local-development or
contract-only pass is described as production, provider synchronization,
cross-device behavior, live external ingestion or human acceptance.

If generation is interrupted, stop only the owned renderer or browser process,
retain its log and resume missing narration by fingerprint. Canonical content is
promoted only after the rendered candidate passes. Existing guide HTML and audio
are hash-compared so a failed package cannot silently replace earlier delivered
work.
