Initial Commit
This commit is contained in:
186
openspec/archive/2026-05-11-enterprise-tides/proposal.md
Normal file
186
openspec/archive/2026-05-11-enterprise-tides/proposal.md
Normal file
@@ -0,0 +1,186 @@
|
||||
# OpenSpec Change: enterprise-tides
|
||||
|
||||
- **Change ID**: enterprise-tides
|
||||
- **Package**: `@suaveplan/tides`
|
||||
- **Category**: universal
|
||||
- **Target path**: `universal/geo/tides`
|
||||
- **Status**: IN PROGRESS
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/tides.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/tides` on the genesis branch from scratch at enterprise quality. The package provides UK tidal prediction using offline TICON harmonic constituent data and ADMIRALTY-compatible algorithms: load harmonic data for any UK port, compute water height at any minute over any date range, find high/low-water times within a window, compute tidal range and mean water, generate 24-hour or multi-day tide tables, and a streaming prediction generator. Fully offline — no network calls. The main-branch version sat at 97.82% coverage. Genesis adds structured errors, Zod schemas, OTel instrumentation, injectable clock, and property-based tests to reach 100%.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
The package does not exist on genesis yet — this is a fresh build.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` (`workspace:^`) | `TidesError`; `TIDES.*` error codes |
|
||||
| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `Clock` |
|
||||
| `@suaveplan/geo` (`workspace:^`) | `LatLng` type for port location |
|
||||
| `zod` (`catalog:forms`) | Schema validation |
|
||||
| `@opentelemetry/api` (`catalog:observability`) | Spans + counters |
|
||||
|
||||
Dev deps: `vitest`, `@vitest/coverage-istanbul`, `fast-check` (all `catalog:testing`).
|
||||
|
||||
---
|
||||
|
||||
## Public API surface
|
||||
|
||||
### Core types
|
||||
|
||||
```ts
|
||||
interface TidalPort {
|
||||
id: string // ADMIRALTY port code e.g. '0113'
|
||||
name: string
|
||||
location: LatLng
|
||||
constituents: TidalConstituent[]
|
||||
timezone: string // IANA timezone
|
||||
meanHighWaterSprings: number // metres
|
||||
meanLowWaterSprings: number
|
||||
chartDatum: number // LAT in metres
|
||||
}
|
||||
|
||||
interface TidalConstituent {
|
||||
name: string // e.g. 'M2', 'S2', 'N2'
|
||||
amplitude: number // metres
|
||||
phase: number // degrees
|
||||
speed: number // degrees/hour
|
||||
}
|
||||
|
||||
interface TidePrediction {
|
||||
time: Date
|
||||
height: number // metres above chart datum
|
||||
type?: 'high' | 'low'
|
||||
}
|
||||
|
||||
interface TideTable {
|
||||
portId: string
|
||||
date: string // ISO date
|
||||
predictions: TidePrediction[]
|
||||
highWaters: TidePrediction[]
|
||||
lowWaters: TidePrediction[]
|
||||
range: number
|
||||
meanLevel: number
|
||||
}
|
||||
```
|
||||
|
||||
### `TidePredictor`
|
||||
|
||||
```ts
|
||||
class TidePredictor {
|
||||
constructor(options?: TidePredictorOptions)
|
||||
|
||||
loadPort(port: TidalPort): void
|
||||
listPorts(): string[]
|
||||
|
||||
predict(portId: string, time: Date): number // metres at single instant
|
||||
predictRange(portId: string, from: Date, to: Date, intervalMinutes?: number): TidePrediction[]
|
||||
findExtrema(portId: string, from: Date, to: Date): TidePrediction[]
|
||||
generateTable(portId: string, date: Date): TideTable
|
||||
generateTables(portId: string, from: Date, to: Date): TideTable[]
|
||||
stream(portId: string, from: Date, to: Date, intervalMinutes?: number): AsyncGenerator<TidePrediction>
|
||||
}
|
||||
|
||||
interface TidePredictorOptions {
|
||||
clock?: Clock
|
||||
logger?: LoggerLike
|
||||
}
|
||||
```
|
||||
|
||||
### Data loaders
|
||||
|
||||
```ts
|
||||
function loadBuiltinPorts(): TidalPort[] // bundled TICON data for UK ports
|
||||
function parseTiconData(raw: string): TidalPort[]
|
||||
function harmonicHeight(constituents: TidalConstituent[], time: Date): number
|
||||
```
|
||||
|
||||
### Error codes
|
||||
|
||||
```ts
|
||||
type TidesErrorCode =
|
||||
| 'TIDES_PORT_NOT_FOUND'
|
||||
| 'TIDES_INVALID_DATE_RANGE'
|
||||
| 'TIDES_INVALID_CONSTITUENT'
|
||||
| 'TIDES_PARSE_FAILED'
|
||||
| 'TIDES_PREDICTION_FAILED'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Genesis additions
|
||||
|
||||
1. **`TidesError`** extends `SuaveplanError` with five stable codes.
|
||||
2. **Zod schemas** for `TidalPort`, `TidalConstituent`, `TidePrediction`, `TideTable`.
|
||||
3. **Streaming `stream()` method** — returns an `AsyncGenerator<TidePrediction>` for memory-efficient prediction over long date ranges.
|
||||
4. **Injectable clock** — `TidePredictorOptions.clock` allows time-travel in tests; `predict()` without a `time` argument uses `clock.now()`.
|
||||
5. **OTel instrumentation** — span `tides.predict_range` with attributes `tides.port_id`, `tides.interval_minutes`; counter `tides.table_generate_total`; histogram `tides.predict_duration_ms`.
|
||||
6. **Property-based tests** — harmonic height at known published times (deterministic); extrema always come in alternating high/low order; prediction is a continuous function (no discontinuities > 0.5m per minute).
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
universal/geo/tides/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
error-codes.ts
|
||||
constants/
|
||||
index.ts # DEGREES_PER_HOUR, G (gravitational const)
|
||||
types/
|
||||
common.ts
|
||||
common.md
|
||||
core/
|
||||
tide-predictor/
|
||||
tide-predictor.ts
|
||||
tide-predictor.md
|
||||
tide-predictor.types.ts
|
||||
tide-predictor.test.ts
|
||||
index.ts
|
||||
harmonic-engine/
|
||||
harmonic-engine.ts
|
||||
harmonic-engine.md
|
||||
harmonic-engine.test.ts
|
||||
index.ts
|
||||
extrema-finder/
|
||||
extrema-finder.ts
|
||||
extrema-finder.md
|
||||
extrema-finder.test.ts
|
||||
index.ts
|
||||
data/
|
||||
ticon-loader/
|
||||
ticon-loader.ts
|
||||
ticon-loader.md
|
||||
ticon-loader.test.ts
|
||||
index.ts
|
||||
builtin-ports.json # bundled TICON data for UK ports
|
||||
__benchmarks__/
|
||||
tides.bench.ts
|
||||
tests/
|
||||
integration.test.ts
|
||||
property.test.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
**Downstream consumers**: `@suaveplan/ports` (tidal windows for port scheduling).
|
||||
|
||||
**Workspace dep prerequisites**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/geo`.
|
||||
67
openspec/archive/2026-05-11-enterprise-tides/tasks.md
Normal file
67
openspec/archive/2026-05-11-enterprise-tides/tasks.md
Normal file
@@ -0,0 +1,67 @@
|
||||
# Tasks: enterprise-tides
|
||||
|
||||
**Change ID**: enterprise-tides
|
||||
**Package**: `@suaveplan/tides`
|
||||
**Target path**: `universal/geo/tides`
|
||||
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/geo`
|
||||
|
||||
---
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [ ] Create `universal/geo/tides/` with `src/`, `tests/`, `src/__benchmarks__/` and all feature subdirectories per the layout in `proposal.md`.
|
||||
- [ ] Write `package.json` at version `0.1.0` with `"type": "module"`, `"sideEffects": false`, correct `exports` map, `dependencies`, and `devDependencies`.
|
||||
- [ ] Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`.
|
||||
- [ ] Write `vitest.config.ts` using `createTestConfig()` from `@suaveplan/testing/config`.
|
||||
- [ ] Add `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check` scripts.
|
||||
|
||||
---
|
||||
|
||||
## 2. Types + errors
|
||||
|
||||
- [ ] `src/types/common.ts` — `TidalPort`, `TidalConstituent`, `TidePrediction`, `TideTable`, `TidePredictorOptions`.
|
||||
- [ ] `src/types/common.md` (≥200 words, both examples, API reference).
|
||||
- [ ] `src/error-codes.ts` — `TidesErrorCode` (5 codes), metadata, register, eager call.
|
||||
- [ ] `src/constants/index.ts` — `DEGREES_PER_HOUR`, `EPOCH_1900` (for ADMIRALTY-style time base).
|
||||
- [ ] `src/types/schemas.ts` + `schemas.md` — Zod schemas.
|
||||
|
||||
---
|
||||
|
||||
## 3. Core modules
|
||||
|
||||
- [ ] **`src/core/harmonic-engine/`** — `harmonicHeight(constituents, time): number`: for each constituent compute `amplitude * cos(speed * t + phase)` where `t` is hours since a reference epoch; sum all constituents. Tests: known published tide heights at 3 reference ports at known times (deterministic); result in `[-maxAmplitude, +maxAmplitude]`.
|
||||
- [ ] **`src/core/extrema-finder/`** — `findExtrema(predictor, portId, from, to): TidePrediction[]`: samples at 15-minute intervals, applies 3-point peak/trough detection, refines each extremum to 1-minute resolution via golden-section search. Tests: at least one high and one low in a 24-hour window; alternating high/low ordering; extrema `height` is a local maximum/minimum relative to neighbours.
|
||||
- [ ] **`src/data/ticon-loader/`** — `parseTiconData(raw): TidalPort[]`: parses a structured text format (space-delimited columns: port code, name, lat, lng, constituent rows). `loadBuiltinPorts()`: imports `builtin-ports.json` (bundled data for ≥30 UK ports). Tests: round-trip parse for 3 manually constructed port entries.
|
||||
- [ ] **`src/core/tide-predictor/`** — `TidePredictor`: `loadPort`, `listPorts`, `predict(portId, time)`, `predictRange`, `findExtrema`, `generateTable`, `generateTables`, `stream(portId, from, to, interval)`. `stream` is an `AsyncGenerator<TidePrediction>`. `generateTable` includes `highWaters`, `lowWaters`, `range`, `meanLevel`. Tests: predict at known time matches `harmonicHeight` directly; generateTable for 24h has ≥2 extrema; stream yields predictions in order; stream abort exits.
|
||||
- [ ] **`src/data/builtin-ports.json`** — bundled TICON-format data for ≥30 UK ports (curated from publicly available harmonic constituent data).
|
||||
|
||||
---
|
||||
|
||||
## 4. OTel instrumentation
|
||||
|
||||
- [ ] Span `tides.predict_range` with attributes `tides.port_id`, `tides.interval_minutes`; counter `tides.table_generate_total`; histogram `tides.predict_duration_ms`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Property-based tests (`tests/property.test.ts`)
|
||||
|
||||
- [ ] Harmonic height bounds: for arbitrary constituent arrays with amplitudes ≤5 m, result is always in `[-sum(amplitudes), +sum(amplitudes)]`.
|
||||
- [ ] Extrema ordering: `findExtrema` always returns alternating `high`/`low` types.
|
||||
- [ ] Prediction continuity: for any two adjacent predictions 1 minute apart, `|height_t+1 - height_t| < 0.5` (no discontinuities).
|
||||
|
||||
---
|
||||
|
||||
## 6. Benchmarks (`src/__benchmarks__/tides.bench.ts`)
|
||||
|
||||
- [ ] `predictRange` for 7-day window at 1-minute resolution for one port.
|
||||
- [ ] `findExtrema` for 30-day window.
|
||||
|
||||
---
|
||||
|
||||
## 7. Docs + verify
|
||||
|
||||
- [ ] One `.md` per implementation file (≥200 words, both examples, API reference). Root `README.md`.
|
||||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/tides` — green.
|
||||
- [ ] `bunx turbo test:coverage --filter=@suaveplan/tides` — 100%.
|
||||
- [ ] `bun scripts/publish.ts --package @suaveplan/tides`.
|
||||
- [ ] Archive: `openspec/archive/2026-04-24-enterprise-tides/`.
|
||||
Reference in New Issue
Block a user