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-almanacand/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.
SkyEventmaps 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
LoggedObservationretains 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
NyxObservationto the browser-localoshun.nyxstore 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:v1first and later merges authenticated GET/PUT state byupdatedAt. 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 innyx-member-stores.tsare 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. CalendarSyncEntrymodels 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#
- Follow one moonrise from computed geometry into an observation invitation.
- Separate contract, executed computation, browser state, service state and product-route evidence.
- Map the consumer, power-user and mobile surface boundaries.
- Trace Julian time, solar and lunar geometry, illumination, observer transformation and rise/transit/set.
- Inspect known-answer tests and the composed depth-page model.
- Build a canonical
SkyEventfrom taxonomy, detail blocks, event invariants, regional windows and prediction sources. - Compare canonical
LoggedObservation, the compact service row and the richer local-first deep-log record. - Follow the tonight URL handoff and account for every field retained by the owner-scoped service.
- Separate browser-first event actions from the two server-side Nyx owners.
- Trace reminder routes into additive in-app delivery.
- Separate provider sync contracts from the implemented ICS export and label computed versus authored agenda rows.
- 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.