@welldot/core 0.1.0 → 0.2.2

package/README.md

@@ -8,15 +8,18 @@ TypeScript types, Zod validators, and serialization utilities for the `.well` op
 
 ## What is `.well`?
 
-`.well` is an open file format for encoding the complete static record of a water well as a single, self-describing JSON document. A `.well` file contains:
+`.well` is an open file format for encoding the complete record of a water well as a single, self-describing JSON document. A `.well` file contains:
 
 - **Constructive data** — borehole geometry, casing strings, screens, reducers, gravel packs, and cement pads
 - **Geologic data** — lithological column, discrete fractures, and cave zones
-- **Administrative metadata** — name, driller, construction date, geographic coordinates, and elevation
+- **Administrative metadata** — well identity, authority-scoped IDs (`well_id`), driller, construction date, and geographic coordinates with explicit CRS
+- **Hydrodynamic events** — append-only ledger of static level readings, pumping tests (constant-rate, step-drawdown, airlift), and recovery phases
+- **Aquifer analysis** — interpreted parameter sets: transmissivity, specific capacity, storativity, and Jacob loss coefficients
+- **Operational history** — timestamped log of maintenance, inspections, and incidents with HTTPS attachment references
 
 The format is designed for three use cases: visualization of technical well profiles, registration with regulatory bodies, and hydrogeological research.
 
-See the [full format specification](./well-specifications.md) for the complete schema reference and design rationale.
+See the [v2 format specification](./docs/spec/v2/overview.md) for the complete schema reference and design rationale. The [v1 spec](./docs/spec/v1/well-format.md) remains available for reference.
 
 ## Installation
 
@@ -67,43 +70,79 @@ const empty = isWellEmpty(well);
 
 All types are exported as TypeScript type-only exports (zero runtime cost).
 
-| Type | Description |
-|------|-------------|
-| `Well` | Complete static record of a water well |
-| `BoreHole` | A drilled interval with diameter and optional drilling method |
-| `WellCase` | Steel or plastic casing installed in the borehole |
-| `Reduction` | Transition piece between different casing diameters |
-| `WellScreen` | Slotted screen section for water intake |
-| `SurfaceCase` | Protective casing near the surface |
-| `HoleFill` | Annular fill material (`gravel_pack` or `seal`) |
-| `CementPad` | Concrete wellhead pad dimensions |
-| `Lithology` | Geological description of a depth interval |
-| `Fracture` | A discrete fracture or fracture zone |
-| `Cave` | A cavity or void zone |
-| `Constructive` | Grouped type: borehole + casings + screens + fills |
-| `Geologic` | Grouped type: lithology + fractures + caves |
-| `Units` | `{ length: 'm' \| 'ft'; diameter: 'mm' \| 'inches' }` |
-| `LengthUnits` | `'m' \| 'ft'` |
-| `DiameterUnits` | `'mm' \| 'inches'` |
-| `UnitsTypes` | `'metric' \| 'imperial'` |
+| Type                    | Description                                                                     |
+| ----------------------- | ------------------------------------------------------------------------------- |
+| `Well`                  | Complete static record of a water well (v2)                                     |
+| `BoreHole`              | A drilled interval with diameter and optional drilling method                   |
+| `WellCase`              | Steel or plastic casing installed in the borehole                               |
+| `Reduction`             | Transition piece between different casing diameters                             |
+| `WellScreen`            | Slotted screen section for water intake (`screen_slot` in mm)                   |
+| `SurfaceCase`           | Protective casing near the surface                                              |
+| `HoleFill`              | Annular fill material (`gravel_pack` or `seal`)                                 |
+| `CementPad`             | Concrete wellhead pad dimensions                                                |
+| `Lithology`             | Geological description of a depth interval                                      |
+| `Texture`               | `{ code: string \| number; vocabulary?: string }` — lithology texture reference |
+| `Fracture`              | A discrete fracture or fracture zone                                            |
+| `Cave`                  | A cavity or void zone                                                           |
+| `Constructive`          | Grouped type: borehole + casings + screens + fills                              |
+| `Geologic`              | Grouped type: lithology + fractures + caves                                     |
+| `WellId`                | Authority-scoped well identifier `{ authority, id, primary? }`                  |
+| `Location`              | Geographic location with optional elevation and CRS properties                  |
+| `LocationProperties`    | CRS, datum, and precision metadata for a `Location`                             |
+| `LevelReading`          | A single depth/time reading during a pumping or recovery phase                  |
+| `RecoveryPhase`         | Time-series of level readings after pump shutdown                               |
+| `PumpingStep`           | One flow-rate step in a pumping test                                            |
+| `HydrodynamicEventBase` | Common fields shared by all hydrodynamic event types                            |
+| `SpotMeasurementEvent`  | A single static water level reading                                             |
+| `ConstantRateEvent`     | A constant-rate pumping test                                                    |
+| `StepDrawdownEvent`     | A step-drawdown pumping test                                                    |
+| `AirliftEvent`          | An air-lift development or test                                                 |
+| `RecoveryOnlyEvent`     | Recovery measurements without drawdown data                                     |
+| `HydrodynamicEvent`     | Discriminated union of all event types + x- custom events                       |
+| `AquiferAnalysis`       | An interpreted set of aquifer parameters                                        |
+| `Attachment`            | An HTTPS-referenced file attached to a history log entry                        |
+| `HistoryLogEntry`       | One entry in the operational history log                                        |
+| `Units`                 | `{ length: 'm' \| 'ft'; diameter: 'mm' \| 'inches' }`                           |
+| `LengthUnits`           | `'m' \| 'ft'`                                                                   |
+| `DiameterUnits`         | `'mm' \| 'inches'`                                                              |
+| `UnitsTypes`            | `'metric' \| 'imperial'`                                                        |
+| `TextureType`           | `{ code: TextureCode; label: string }` — a single FGDC texture entry (lookup)   |
+| `TextureCode`           | `number \| string` — numeric FGDC code or custom string code                    |
 
 ### Validators
 
 Each schema validates its corresponding type at runtime. All schemas are Zod objects and compose with standard Zod methods (`.parse`, `.safeParse`, `.extend`, etc.).
 
-| Export | Validates |
-|--------|-----------|
-| `WellSchema` | `Well` (the complete document) |
-| `BoreHoleSchema` | `BoreHole` |
-| `WellCaseSchema` | `WellCase` |
-| `ReductionSchema` | `Reduction` |
-| `WellScreenSchema` | `WellScreen` |
-| `SurfaceCaseSchema` | `SurfaceCase` |
-| `HoleFillSchema` | `HoleFill` |
-| `CementPadSchema` | `CementPad` |
-| `LithologySchema` | `Lithology` |
-| `FractureSchema` | `Fracture` |
-| `CaveSchema` | `Cave` |
+| Export                        | Validates                                                               |
+| ----------------------------- | ----------------------------------------------------------------------- |
+| `WellSchema`                  | `Well` (the complete document; `.passthrough()` preserves unknown keys) |
+| `BoreHoleSchema`              | `BoreHole`                                                              |
+| `WellCaseSchema`              | `WellCase`                                                              |
+| `ReductionSchema`             | `Reduction`                                                             |
+| `WellScreenSchema`            | `WellScreen`                                                            |
+| `SurfaceCaseSchema`           | `SurfaceCase`                                                           |
+| `HoleFillSchema`              | `HoleFill`                                                              |
+| `CementPadSchema`             | `CementPad`                                                             |
+| `LithologySchema`             | `Lithology`                                                             |
+| `TextureSchema`               | `Texture`                                                               |
+| `FractureSchema`              | `Fracture`                                                              |
+| `CaveSchema`                  | `Cave`                                                                  |
+| `WellIdSchema`                | `WellId`                                                                |
+| `LocationPropertiesSchema`    | `LocationProperties`                                                    |
+| `LocationSchema`              | `Location`                                                              |
+| `LevelReadingSchema`          | `LevelReading`                                                          |
+| `RecoveryPhaseSchema`         | `RecoveryPhase`                                                         |
+| `PumpingStepSchema`           | `PumpingStep`                                                           |
+| `HydrodynamicEventBaseSchema` | `HydrodynamicEventBase`                                                 |
+| `SpotMeasurementEventSchema`  | `SpotMeasurementEvent`                                                  |
+| `ConstantRateEventSchema`     | `ConstantRateEvent`                                                     |
+| `StepDrawdownEventSchema`     | `StepDrawdownEvent`                                                     |
+| `AirliftEventSchema`          | `AirliftEvent`                                                          |
+| `RecoveryOnlyEventSchema`     | `RecoveryOnlyEvent`                                                     |
+| `HydrodynamicEventSchema`     | `HydrodynamicEvent` (discriminated union + x- passthrough)              |
+| `AquiferAnalysisSchema`       | `AquiferAnalysis`                                                       |
+| `AttachmentSchema`            | `Attachment`                                                            |
+| `HistoryLogEntrySchema`       | `HistoryLogEntry`                                                       |
 
 ### Functions
 
@@ -113,58 +152,113 @@ Parses a raw JSON string and validates it against `WellSchema`. Throws a `ZodErr
 
 #### `serializeWell(well: Well): string`
 
-Serializes a `Well` object to a versioned `.well` JSON string (`"version": 1`). Omits `undefined` optional fields.
+Serializes a `Well` object to a versioned `.well` JSON string (`"version": 2`). Emits `location` when set; does not emit deprecated flat `lat`/`lng`/`elevation`. Omits `undefined` optional fields.
 
 #### `deserializeWell(jsonString: string): Well | null`
 
 Parses and normalizes a JSON string into a `Well`. Handles multiple formats:
 
-- Current versioned format (`"version": 1`)
+- v2 format (`"version": 2`) — passes v2-specific fields through directly
+- v1 format (`"version": 1`) — applies v1→v2 normalizations: `fgdc_texture` → `texture`, `screen_slot_mm` → `screen_slot`, flat `lat/lng/elevation` → `location`
 - Legacy formats with `constructive` / `geologic` sub-objects
 - Legacy `diam_pol` inch diameters → `diameter` mm conversion (`× 25.4`)
 - Typo `bole_hole` → `bore_hole` compatibility
 
-Returns `null` if the parsed data is empty.
+Returns `null` if the parsed data is empty. Throws on unrecognized version numbers.
 
 #### `isWellEmpty(well: Well | null | undefined): boolean`
 
 Returns `true` when all constructive and geologic arrays are empty. Accepts `null` and `undefined` (both treated as empty).
 
+## FGDC Texture Patterns
+
+`FGDC_TEXTURES_OPTIONS` is a typed array of 284 texture pattern entries drawn from the **FGDC Digital Cartographic Standard for Geologic Map Symbolization (FGDC-STD-013-2006)**. Assign a `code` to the `texture` field of a `Lithology` record to attach a standardized fill pattern to a depth interval.
+
+```typescript
+import { FGDC_TEXTURES_OPTIONS } from '@welldot/core';
+import type { Texture, TextureCode } from '@welldot/core';
+
+// Lookup by code
+const sandstone = FGDC_TEXTURES_OPTIONS.find(t => t.code === 607);
+// { code: 607, label: 'Massive sand or sandstone' }
+
+// Build a select list for a UI
+const options = FGDC_TEXTURES_OPTIONS.map(t => ({
+  value: t.code,
+  label: t.label,
+}));
+```
+
+Codes are grouped by series:
+
+| Series | Category                                               |
+| ------ | ------------------------------------------------------ |
+| 100    | Surficial deposits                                     |
+| 200    | Sedimentary patterns                                   |
+| 300    | Igneous patterns                                       |
+| 400    | Miscellaneous / Metamorphic patterns                   |
+| 500    | Glacial / Periglacial patterns                         |
+| 600    | Sedimentary lithology _(most useful for well logging)_ |
+| 700    | Metamorphic and igneous lithology                      |
+
+See [fgdc-textures.md](./docs/reference/fgdc-textures.md) for the complete annotated list of all 284 codes.
+
 ## `.well` Format Overview
 
 All depths are in **meters** from ground level (0 = surface). All diameters are in **millimeters**. Geographic coordinates use WGS84 decimal degrees. The MIME type is `application/vnd.well+json`.
 
-A minimal `.well` document:
+A minimal v2 `.well` document:
 
 ```json
 {
-  "version": 1,
+  "version": 2,
   "well_type": "tubular",
   "name": "PP-01",
-  "lat": -1.4558,
-  "lng": -48.5039,
-  "elevation": 12.5,
-  "bore_hole": [{ "from": 0, "to": 80, "diameter": 250, "drilling_method": "rotary" }],
+  "location": { "lat": -1.4558, "lng": -48.5039, "elevation": 12.5 },
+  "bore_hole": [
+    { "from": 0, "to": 80, "diameter": 250, "drilling_method": "rotary" }
+  ],
   "well_case": [{ "from": 0, "to": 60, "type": "steel", "diameter": 200 }],
   "reduction": [],
-  "well_screen": [{ "from": 60, "to": 80, "type": "wire_wound", "diameter": 150, "screen_slot_mm": 0.5 }],
+  "well_screen": [
+    {
+      "from": 60,
+      "to": 80,
+      "type": "wire_wound",
+      "diameter": 150,
+      "screen_slot": 0.5
+    }
+  ],
   "surface_case": [{ "from": 0, "to": 3, "diameter": 300 }],
-  "hole_fill": [{ "from": 60, "to": 80, "type": "gravel_pack", "diameter": 250, "description": "2-4mm gravel" }],
-  "cement_pad": { "type": "square", "width": 1.0, "thickness": 0.15, "length": 1.0 },
+  "hole_fill": [
+    {
+      "from": 60,
+      "to": 80,
+      "type": "gravel_pack",
+      "diameter": 250,
+      "description": "2-4mm gravel"
+    }
+  ],
+  "cement_pad": {
+    "type": "square",
+    "width": 1.0,
+    "thickness": 0.15,
+    "length": 1.0
+  },
   "lithology": [],
   "fractures": [],
   "caves": []
 }
 ```
 
-For the complete schema reference, field vocabulary, design rationale, and versioning policy see the [`.well` format specification](./well-specifications.md).
+For the complete schema reference, field vocabulary, and design rationale see the [`.well` v2 format specification](./docs/spec/v2/overview.md). The [v1 spec](./docs/spec/v1/well-format.md) remains available for reference.
 
 ## Contributing
 
-Issues and pull requests are welcome. The source lives in `packages/core` within the [well-profiler monorepo](https://github.com/rafaeelneto/well-profiler).
+Issues and pull requests are welcome. The source lives in `packages/core` within the [well-profiler monorepo](https://github.com/rafaeelneto/welldot).
 
 ```bash
-git clone https://github.com/rafaeelneto/well-profiler.git
+git clone https://github.com/rafaeelneto/welldot.git
 cd well-profiler
 pnpm install
 cd packages/core
@@ -175,5 +269,3 @@ pnpm test
 ## License
 
 [Apache 2.0](./LICENSE) — see `LICENSE` for the full text.
-
-The broader well-profiler application is licensed separately under [CC BY-NC-ND 4.0](https://creativecommons.org/licenses/by-nc-nd/4.0/).