@disclosureos/records 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to `@disclosureos/records` are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 1.0.0
+
+Initial public release — the core of the DisclosureOS standard.
+
+### Added
+- `Observation` — the primary record type — with `ObservationSchema` (Zod 4) and the
+  non-stripping `validateObservation` validator.
+- `@disclosureos/records/shared`: the cross-package substrate (`Confidence`,
+  `Attribution`, `Claim` + `evidenceRef` helpers, `validateWith`, `schemaId`,
+  `jsonSchemaEnvelope`, enum guards, branded ids).
+- The `ObservationExtensions` extension point for satellite slots.
+- The DX quintet (labels, constants, guards, factories, formatters, validators) and
+  temporal / geo / media / extension subpaths.
+- Committed JSON Schema artifact (`schema/records.schema.json`, draft 2020-12).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Disclosure Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# @disclosureos/records
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Structured vocabulary for describing UAP observations — the **data dictionary** of
+the [DisclosureOS](https://github.com/disclosurefoundation) ecosystem. Its primary
+type, `Observation`, is the core unit every other package builds on.
+
+DisclosureOS is a **five-part standard**. Each part answers one question about an
+observation; `@disclosureos/schema` binds the package-owned pieces into one portable
+contract (a single TS type + JSON Schema + non-stripping parse).
+
+| Part | Package surface | Question it answers |
+|---|---|---|
+| **Records** | `@disclosureos/records` | *What was observed?* |
+| **Observables** | `@disclosureos/observables` | *What anomalous characteristics did it show?* |
+| **Origins** | `@disclosureos/origins` | *What might explain it?* |
+| **Claims** | `@disclosureos/records/shared` | *Who assessed it, why, and on what evidence?* |
+| **Scoring** | `@disclosureos/scoring` | *How complete / compelling is the case?* |
+
+Supporting packages: **`@disclosureos/schema`** (the portable contract that composes the
+package-owned pieces), **`@disclosureos/cli`** (tooling), and
+**`@disclosureos/examples`** (the runnable golden path). *(You are here: **Records**.)*
+
+## records is the shared vocabulary
+
+`records` has no DisclosureOS dependencies — it depends only on [Zod](https://zod.dev).
+The other layers depend on **it**: they import shared primitives (confidence scales,
+attribution, claims, validation, JSON-Schema helpers) from `@disclosureos/records/shared`
+instead of re-inventing them. Import a layer package and its slot is automatically
+typed on `Observation` (see [The extension point](#the-extension-point)).
+
+New to the vocabulary? The [glossary](../../docs/disclosureos-glossary.md) defines the
+terms that are easy to conflate — Attribution vs Claim vs Assessment, `confidence` vs
+`ConfidenceLevel` vs `SourceCredibility`, and `alternativeHypotheses` vs `contested`.
+
+> **See it end to end.** [`examples/golden-path.ts`](../../examples/golden-path.ts)
+> takes one observation through every part — records → observables → origins → claims → scoring,
+> validated as a whole by `@disclosureos/schema` — in a single type-checked file. Run it
+> with `pnpm --filter @disclosureos/examples golden-path`.
+>
+> **Migrating an existing dataset?** See [`examples/migration-path.ts`](../../examples/migration-path.ts)
+> and the [onboarding workspace](https://os.disclosure.org/onboard).
+
+## Install
+
+```bash
+pnpm add @disclosureos/records zod
+```
+
+## Quick start
+
+```typescript
+import { ObservationSchema, validateObservation, type Observation } from '@disclosureos/records';
+
+const observation: Observation = {
+  id: 'nimitz-2004',
+  temporal: { date: '2004-11-14', dateCertainty: 'exact' },
+  location: { id: 'l', name: 'Pacific', country: 'US', longitude: -117, latitude: 32, siteType: 'ocean' },
+  status: 'published',
+  createdAt: '2004-11-14T00:00:00Z',
+  updatedAt: '2024-01-01T00:00:00Z',
+};
+
+const issues = validateObservation(observation); // [] when valid
+```
+
+## The extension point
+
+The satellite slots (`observableAssessments`, `origin`) are **not** part of
+`ObservationSchema` — `records` cannot import its own satellites. Instead each layer
+package augments the `Observation` type via `declare module '@disclosureos/records'`,
+so simply importing the package types its slot:
+
+```typescript
+import '@disclosureos/observables'; // adds `observableAssessments` to Observation
+import '@disclosureos/origins';     // adds `origin` to Observation
+```
+
+> ⚠️ **Strip hazard.** Because those slots aren't in the `z.object`, a raw
+> `ObservationSchema.parse(record)` **silently drops** `observableAssessments` and
+> `origin` (Zod strips unknown keys). To validate an enriched record:
+> - use **`validateObservation(record)`** here — it returns issues *without* stripping
+>   your object, or
+> - use **`parseEnrichedObservation()`** from [`@disclosureos/schema`](../disclosureos-schema),
+>   the non-stripping composed parse that validates core + slots in one call.
+>
+> Do not use a raw `.parse()` round-trip to "clean" an enriched record.
+
+## Subpath exports
+
+Each surface is independently importable (tree-shakeable):
+
+| Subpath | Contents |
+|---|---|
+| `@disclosureos/records` | `Observation`, `ObservationSchema`, `validateObservation` |
+| `@disclosureos/records/shared` | Shared primitives: `Confidence`, `Attribution`, `Claim`, `validateWith`, `schemaId`, … |
+| `@disclosureos/records/temporal` · `/geo` · `/media` | Temporal, geographic, and media primitives |
+| `@disclosureos/records/extensions/*` | Off-the-hot-path slots: `provenance`, `identifiers`, `testimony`, `physical`, `document` |
+| `@disclosureos/records/{labels,constants,guards,factories,formatters,validators}` | The DX quintet |
+| `@disclosureos/records/schema` | The committed JSON Schema (`records.schema.json`) |
+
+## JSON Schema
+
+A committed, versioned JSON Schema (draft 2020-12) ships at
+`@disclosureos/records/schema`, `$id` hosted at `os.disclosure.org`. The core
+`Observation` root is intentionally **open** so satellite slots compose in at the
+all-packages step ([`@disclosureos/schema`](../disclosureos-schema)). Regenerate with
+`pnpm --filter @disclosureos/records emit:schema`; a drift test keeps it honest.
+
+## Standard Schema
+
+The Zod schemas here (`ObservationSchema`, …) implement
+[Standard Schema v1](https://standardschema.dev) via their `~standard` property —
+a guarantee of Zod 4. Any Standard-Schema-compatible validator or framework
+(`tRPC`, `TanStack Form`, …) can consume them directly, with no DisclosureOS-specific
+adapter.
+
+## License
+
+MIT © [Disclosure Foundation](https://disclosure.org)

package/dist/attachment-Hrg8uHuf.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+
+declare const MediaAttachmentSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<{
+        image: "image";
+        video: "video";
+        document: "document";
+        audio: "audio";
+    }>;
+    url: z.ZodString;
+    thumbnailUrl: z.ZodOptional<z.ZodString>;
+    caption: z.ZodOptional<z.ZodString>;
+    credit: z.ZodOptional<z.ZodString>;
+    mimeType: z.ZodOptional<z.ZodString>;
+    fileSize: z.ZodOptional<z.ZodNumber>;
+    duration: z.ZodOptional<z.ZodNumber>;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type MediaAttachment = z.infer<typeof MediaAttachmentSchema>;
+
+export { type MediaAttachment as M, MediaAttachmentSchema as a };

package/dist/confidence-level-CV3P1W5_.d.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+
+/**
+ * The single qualitative confidence magnitude for the ecosystem.
+ * Merges the former `ConfidenceLevel` (investigation) and `CredibilityRating`
+ * (testimony) — which were byte-identical — plus the inline high/medium/low
+ * scales in `provenance/digital`.
+ *
+ * Distinct from `SourceCredibility` (trust tier), `TemporalCertainty` (time
+ * precision), and `AssessmentLevel` (evidentiary tier) — those are the other
+ * three orthogonal axes and are intentionally NOT merged here.
+ */
+declare const ConfidenceLevelSchema: z.ZodEnum<{
+    high: "high";
+    moderate: "moderate";
+    low: "low";
+    unassessed: "unassessed";
+    very_high: "very_high";
+    very_low: "very_low";
+}>;
+type ConfidenceLevel = z.infer<typeof ConfidenceLevelSchema>;
+declare const CONFIDENCE_LEVELS: ("high" | "moderate" | "low" | "unassessed" | "very_high" | "very_low")[];
+declare function isConfidenceLevel(value: unknown): value is ConfidenceLevel;
+
+export { type ConfidenceLevel as C, ConfidenceLevelSchema as a, CONFIDENCE_LEVELS as b, isConfidenceLevel as i };

package/dist/constants/index.d.ts

@@ -0,0 +1,28 @@
+declare const SOURCE_TYPES: ("other" | "foia" | "official_report" | "official_statement" | "congressional_testimony" | "congressional_report" | "military_document" | "intelligence_document" | "whistleblower" | "firsthand_witness" | "secondhand_account" | "news_article" | "documentary" | "interview" | "book" | "academic_paper" | "investigation_report" | "database_entry" | "social_media" | "website")[];
+declare const SOURCE_CREDIBILITIES: ("unknown" | "verified" | "unverified" | "official" | "credible" | "questionable" | "disputed")[];
+declare const TEMPORAL_CERTAINTIES: ("exact" | "approximate" | "estimated" | "unknown")[];
+declare const DATE_GRANULARITIES: ("exact" | "unknown" | "month" | "quarter" | "year" | "decade" | "century")[];
+declare const DATE_RANGE_TYPES: ("span" | "uncertainty" | "active_period" | "investigation_period" | "observation_window")[];
+declare const TIMES_OF_DAY: ("unknown" | "astronomical_dawn" | "nautical_dawn" | "civil_dawn" | "sunrise" | "morning" | "noon" | "afternoon" | "sunset" | "civil_dusk" | "nautical_dusk" | "astronomical_dusk" | "night")[];
+declare const MEDIA_TYPES: ("image" | "video" | "document" | "audio")[];
+declare const SITE_TYPES: ("unknown" | "military_air_base" | "military_naval_base" | "military_army_base" | "military_missile_site" | "military_radar_station" | "military_research_facility" | "military_training_area" | "military_other" | "nuclear_power_plant" | "nuclear_weapons_storage" | "nuclear_research_facility" | "nuclear_waste_storage" | "nuclear_other" | "civilian_airport" | "private_airfield" | "heliport" | "seaport" | "offshore_platform" | "naval_vessel" | "government_facility" | "embassy" | "intelligence_facility" | "power_plant" | "dam" | "telecommunications" | "water_treatment" | "research_facility" | "test_range" | "space_station" | "archaeological_site" | "volcano" | "command_center" | "residential" | "commercial" | "industrial" | "agricultural" | "wilderness" | "ocean" | "lake" | "mountain" | "desert" | "forest" | "urban" | "suburban" | "rural" | "other")[];
+declare const TERRAIN_TYPES: ("unknown" | "ocean" | "lake" | "desert" | "forest" | "urban" | "suburban" | "rural" | "coastal" | "river" | "wetland" | "plains" | "hills" | "mountains" | "jungle" | "tundra" | "arctic" | "underground" | "underwater" | "airborne" | "space")[];
+declare const AIRSPACE_CLASSES: ("unknown" | "A" | "B" | "C" | "D" | "E" | "G" | "restricted" | "prohibited" | "warning" | "moa" | "alert" | "cfa" | "national_security" | "tfr" | "international")[];
+declare const LOCATION_SENSITIVITIES: ("critical" | "high" | "moderate" | "standard" | "none")[];
+declare const COORDINATE_PRECISIONS: ("exact" | "approximate" | "unknown" | "address" | "locality" | "region")[];
+declare const OBJECT_SHAPES: ("unknown" | "other" | "sphere" | "orb" | "disc" | "saucer" | "oval" | "egg" | "cylinder" | "cigar" | "tic_tac" | "triangle" | "delta" | "boomerang" | "chevron" | "diamond" | "rectangle" | "square" | "cube" | "cross" | "star" | "amorphous" | "changing" | "light_only")[];
+declare const MANEUVER_TYPES: ("other" | "hover" | "instant_acceleration" | "instant_stop" | "right_angle_turn" | "zigzag" | "pendulum" | "split" | "merge" | "disappear" | "appear" | "transmedium_entry" | "transmedium_exit" | "vertical_ascent" | "vertical_descent" | "rotation" | "wobble")[];
+declare const RELATION_KINDS: ("corroborates" | "contradicts" | "duplicate_of" | "same_object" | "supersedes" | "superseded_by" | "re_analysis_of" | "part_of")[];
+declare const CONFIDENCE_LEVELS: ("high" | "moderate" | "low" | "unassessed" | "very_high" | "very_low")[];
+declare const WITNESS_CATEGORIES: ("unknown" | "military_other" | "military_pilot" | "military_aircrew" | "military_ground" | "military_naval" | "military_radar_operator" | "commercial_pilot" | "commercial_aircrew" | "private_pilot" | "air_traffic_controller" | "aviation_other" | "government_official" | "elected_official" | "intelligence_officer" | "law_enforcement" | "scientist" | "astronomer" | "meteorologist" | "engineer" | "medical_professional" | "maritime" | "civilian" | "civilian_group" | "anonymous")[];
+declare const DETECTION_METHODS: ("unknown" | "other" | "radar_primary" | "radar_secondary" | "radar_doppler" | "radar_phased_array" | "infrared_flir" | "infrared_other" | "electro_optical" | "visual_camera" | "satellite_imagery" | "sonar_active" | "sonar_passive" | "electromagnetic" | "radiation_detector" | "magnetometer" | "gravimeter" | "acoustic" | "seismic" | "lidar" | "spectroscopic" | "radio_frequency" | "multiple")[];
+declare const SENSOR_TYPES: ("other" | "military_radar" | "civilian_radar" | "airborne_radar" | "shipborne_radar" | "ground_radar" | "flir" | "eo_sensor" | "satellite" | "sonar" | "electromagnetic_sensor" | "radiation_sensor" | "civilian_camera" | "security_camera" | "dashcam" | "phone_camera")[];
+declare const EVIDENCE_TYPES: ("other" | "video" | "material_sample" | "ground_trace" | "radiation_reading" | "electromagnetic_recording" | "photographic" | "audio_recording" | "biological_sample" | "implant" | "debris" | "soil_sample" | "water_sample" | "vegetation_sample" | "impression" | "burn_mark")[];
+declare const EVIDENCE_QUALITIES: ("unknown" | "laboratory_grade" | "field_collected" | "uncontrolled" | "degraded" | "contaminated")[];
+declare const CHAIN_OF_CUSTODY_STATUSES: ("unknown" | "destroyed" | "classified" | "verified" | "partial" | "unverified" | "government_held" | "private_held" | "lost")[];
+declare const VERIFICATION_METHODS: ("other" | "metadata_analysis" | "forensic_analysis" | "hash_verification" | "chain_of_custody" | "source_confirmation" | "expert_review" | "ai_analysis")[];
+declare const VERIFICATION_RESULTS: ("unknown" | "authentic" | "likely_authentic" | "inconclusive" | "likely_manipulated" | "manipulated" | "ai_generated" | "deepfake" | "composite")[];
+declare const HASH_ALGORITHMS: ("sha256" | "sha512" | "sha1" | "md5")[];
+declare const PUBLICATION_STATUSES: ("archived" | "draft" | "review" | "published" | "retracted")[];
+
+export { AIRSPACE_CLASSES, CHAIN_OF_CUSTODY_STATUSES, CONFIDENCE_LEVELS, COORDINATE_PRECISIONS, DATE_GRANULARITIES, DATE_RANGE_TYPES, DETECTION_METHODS, EVIDENCE_QUALITIES, EVIDENCE_TYPES, HASH_ALGORITHMS, LOCATION_SENSITIVITIES, MANEUVER_TYPES, MEDIA_TYPES, OBJECT_SHAPES, PUBLICATION_STATUSES, RELATION_KINDS, SENSOR_TYPES, SITE_TYPES, SOURCE_CREDIBILITIES, SOURCE_TYPES, TEMPORAL_CERTAINTIES, TERRAIN_TYPES, TIMES_OF_DAY, VERIFICATION_METHODS, VERIFICATION_RESULTS, WITNESS_CATEGORIES };