@disclosureos/origins 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to `@disclosureos/origins` 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 Origins layer.
+
+### Added
+- The Origin Classification System (OCS) taxonomy across the Physical, Psychosocial,
+  and Metaphysical domains, with traversal utilities (`getNode`, …).
+- `OriginClaim` + `createOriginClaim`; the `origin` slot is an array of competing
+  claims, with every node id validated against the live taxonomy.
+- Typed reference systems: Hynek, Vallée, AARO, GEIPAN.
+- `validateOriginClassification` and the `origin` augmentation of `Observation`.
+- The DX quintet; committed JSON Schema artifact (`schema/origins.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,95 @@
+# @disclosureos/origins
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Classification taxonomy for the [DisclosureOS](https://github.com/disclosurefoundation)
+ecosystem — the **Origins** layer. It answers *"what might explain the observation?"*
+via the **Origin Classification System (OCS)**: a tree of origin hypotheses across the
+Physical, Psychosocial, and Metaphysical domains, plus typed mappings to the reference
+systems researchers already use (Hynek, Vallée, AARO, GEIPAN).
+
+## The DisclosureOS model
+
+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: **Origins**.)*
+
+## Built on records
+
+This package depends on [`@disclosureos/records`](../disclosureos-records), the shared
+substrate — it reuses its confidence and claim primitives. Importing this package
+**augments** the `Observation` type with the `origin` slot:
+
+```typescript
+import '@disclosureos/origins'; // `observation.origin` is now typed
+```
+
+> **See it end to end.** [`examples/golden-path.ts`](../../examples/golden-path.ts)
+> takes one observation through every layer — records → observables → origins → 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/origins @disclosureos/records zod
+```
+
+## Quick start
+
+```typescript
+import { createOriginClaim, getNode } from '@disclosureos/origins';
+import type { Observation } from '@disclosureos/records';
+
+const observation: Observation = {
+  // ...records core fields...
+  origin: [
+    { primaryHypothesis: '1.1.3', confidence: 0.9, evaluatedBy: 'analyst-a' },
+  ],
+};
+
+getNode('1.1.3'); // resolve an OCS node by id
+```
+
+The `origin` slot is an **array of competing claims** (one per evaluator/verdict), so
+contested classifications are represented directly. Every `primaryHypothesis` /
+`alternativeHypotheses` node id is validated against the live taxonomy.
+
+> ⚠️ A raw `ObservationSchema.parse()` strips this slot. Validate enriched records with
+> `validateOriginClassification()` (this package) or `parseEnrichedObservation()` from
+> [`@disclosureos/schema`](../disclosureos-schema).
+
+## Subpath exports
+
+| Subpath | Contents |
+|---|---|
+| `@disclosureos/origins` | `OriginClaim`, `createOriginClaim`, `getNode`, `validateOriginClassification` |
+| `@disclosureos/origins/taxonomy` (+ `/physical`, `/psychosocial`, `/metaphysical`) | The OCS tree + traversal |
+| `@disclosureos/origins/reference/*` | Hynek · Vallée · AARO · GEIPAN reference systems |
+| `@disclosureos/origins/{classification,labels,constants,guards,factories,formatters}` | Claims + the DX quintet |
+| `@disclosureos/origins/schema` | The committed JSON Schema (`origins.schema.json`) |
+
+## Standard Schema
+
+The Zod schemas here implement [Standard Schema v1](https://standardschema.dev) via
+their `~standard` property — a guarantee of Zod 4. Any Standard-Schema-compatible
+validator or framework can consume them directly, with no DisclosureOS-specific adapter.
+
+## License
+
+MIT © [Disclosure Foundation](https://disclosure.org)

package/dist/classification/index.d.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+
+/**
+ * A weighted origin hypothesis: an OCS node id plus the confidence assigned to it.
+ */
+declare const HypothesisWeightSchema: z.ZodObject<{
+    nodeId: z.ZodString;
+    confidence: z.ZodNumber;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type HypothesisWeight = z.infer<typeof HypothesisWeightSchema>;
+/**
+ * A single attributed origin claim — one evaluator's verdict on what an
+ * observation is: a primary OCS hypothesis with its confidence, optional
+ * `alternativeHypotheses` (the intra-claim axis), and the shared {@link ClaimSchema}
+ * envelope (`evaluatedAt` / `evaluatedBy` / `rationale` + `evidenceRefs`).
+ *
+ * The `Observation.origin` slot is a *list* of these (the inter-claim axis), so
+ * competing classifications from different evaluators coexist without one being
+ * privileged — endorsement is a scoring concern, not a records one.
+ */
+declare const OriginClaimSchema: z.ZodObject<{
+    evaluatedAt: z.ZodOptional<z.ZodISODateTime>;
+    evaluatedBy: z.ZodOptional<z.ZodString>;
+    rationale: z.ZodOptional<z.ZodString>;
+    evidenceRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    primaryHypothesis: z.ZodString;
+    confidence: z.ZodNumber;
+    alternativeHypotheses: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        nodeId: z.ZodString;
+        confidence: z.ZodNumber;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+type OriginClaim = z.infer<typeof OriginClaimSchema>;
+/**
+ * A full distribution of confidence across hypotheses, with `unresolved` holding
+ * the remaining confidence not assigned to any hypothesis.
+ */
+declare const ConfidenceDistributionSchema: z.ZodObject<{
+    hypotheses: z.ZodArray<z.ZodObject<{
+        nodeId: z.ZodString;
+        confidence: z.ZodNumber;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    unresolved: z.ZodNumber;
+    evaluatedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+type ConfidenceDistribution = z.infer<typeof ConfidenceDistributionSchema>;
+/**
+ * Simplified category-level confidence distribution for quick classification.
+ * Each key maps to a broad OCS category. Values are confidence levels (0-1) that should sum to ~1.0.
+ *
+ * - `conventional` → OCS 1.1.1 (Prosaic explanations)
+ * - `cryptoterrestrial` → OCS 1.1.2 (Hidden Earth-based entities)
+ * - `extraterrestrial` → OCS 1.1.3 (Off-world visitors)
+ * - `extradimensional` → OCS 1.2 (Other dimensions)
+ * - `interdimensional` → OCS 1.3 (Dimension-traversing)
+ * - `psychosocial` → OCS 2.0 (Perceptual/social factors)
+ * - `metaphysical` → OCS 3.0 (Beyond conventional science)
+ * - `insufficientData` → Cannot classify due to lack of information
+ */
+declare const CategoryConfidenceSchema: z.ZodObject<{
+    conventional: z.ZodNumber;
+    cryptoterrestrial: z.ZodNumber;
+    extraterrestrial: z.ZodNumber;
+    extradimensional: z.ZodNumber;
+    interdimensional: z.ZodNumber;
+    psychosocial: z.ZodNumber;
+    metaphysical: z.ZodNumber;
+    insufficientData: z.ZodNumber;
+}, z.core.$strip>;
+type CategoryConfidence = z.infer<typeof CategoryConfidenceSchema>;
+
+export { type CategoryConfidence, CategoryConfidenceSchema, type ConfidenceDistribution, ConfidenceDistributionSchema, type HypothesisWeight, HypothesisWeightSchema, type OriginClaim, OriginClaimSchema };

package/dist/classification/index.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { ConfidenceSchema, ClaimSchema } from '@disclosureos/records/shared';
+
+// src/classification/types.ts
+var HypothesisWeightSchema = z.object({
+  nodeId: z.string().min(1).describe('OCS node id (e.g., "1.1.3").'),
+  confidence: ConfidenceSchema,
+  label: z.string().optional()
+}).meta({ id: "HypothesisWeight" }).describe("A weighted origin hypothesis (OCS node + confidence).");
+var OriginClaimSchema = ClaimSchema.extend({
+  primaryHypothesis: z.string().min(1).describe("OCS node id of the primary hypothesis."),
+  confidence: ConfidenceSchema.describe("Confidence in the primary hypothesis, in [0,1]."),
+  alternativeHypotheses: z.array(HypothesisWeightSchema).optional().describe(
+    "Other OCS hypotheses this same evaluator weighs as possible, each with its own confidence \u2014 the intra-claim uncertainty axis."
+  )
+}).meta({ id: "OriginClaim" }).describe("An attributed origin-hypothesis classification for an observation.");
+var ConfidenceDistributionSchema = z.object({
+  hypotheses: z.array(HypothesisWeightSchema),
+  unresolved: ConfidenceSchema.describe("Remaining confidence not assigned to any hypothesis."),
+  evaluatedAt: z.iso.datetime()
+}).meta({ id: "ConfidenceDistribution" }).describe("Confidence distribution across origin hypotheses.");
+var CategoryConfidenceSchema = z.object({
+  conventional: ConfidenceSchema,
+  cryptoterrestrial: ConfidenceSchema,
+  extraterrestrial: ConfidenceSchema,
+  extradimensional: ConfidenceSchema,
+  interdimensional: ConfidenceSchema,
+  psychosocial: ConfidenceSchema,
+  metaphysical: ConfidenceSchema,
+  insufficientData: ConfidenceSchema
+}).meta({ id: "CategoryConfidence" }).describe("Quick category-level confidence distribution across broad OCS categories.");
+
+export { CategoryConfidenceSchema, ConfidenceDistributionSchema, HypothesisWeightSchema, OriginClaimSchema };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/classification/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/classification/types.ts"],"names":[],"mappings":";;;;AAMO,IAAM,sBAAA,GAAyB,EACnC,MAAA,CAAO;AAAA,EACN,MAAA,EAAQ,EAAE,MAAA,EAAO,CAAE,IAAI,CAAC,CAAA,CAAE,SAAS,8BAA8B,CAAA;AAAA,EACjE,UAAA,EAAY,gBAAA;AAAA,EACZ,KAAA,EAAO,CAAA,CAAE,MAAA,EAAO,CAAE,QAAA;AACpB,CAAC,CAAA,CACA,KAAK,EAAE,EAAA,EAAI,oBAAoB,CAAA,CAC/B,SAAS,uDAAuD;AAc5D,IAAM,iBAAA,GAAoB,YAAY,MAAA,CAAO;AAAA,EAClD,iBAAA,EAAmB,EAAE,MAAA,EAAO,CAAE,IAAI,CAAC,CAAA,CAAE,SAAS,wCAAwC,CAAA;AAAA,EACtF,UAAA,EAAY,gBAAA,CAAiB,QAAA,CAAS,iDAAiD,CAAA;AAAA,EACvF,uBAAuB,CAAA,CACpB,KAAA,CAAM,sBAAsB,CAAA,CAC5B,UAAS,CACT,QAAA;AAAA,IACC;AAAA;AAEN,CAAC,CAAA,CACE,KAAK,EAAE,EAAA,EAAI,eAAe,CAAA,CAC1B,SAAS,oEAAoE;AAQzE,IAAM,4BAAA,GAA+B,EACzC,MAAA,CAAO;AAAA,EACN,UAAA,EAAY,CAAA,CAAE,KAAA,CAAM,sBAAsB,CAAA;AAAA,EAC1C,UAAA,EAAY,gBAAA,CAAiB,QAAA,CAAS,sDAAsD,CAAA;AAAA,EAC5F,WAAA,EAAa,CAAA,CAAE,GAAA,CAAI,QAAA;AACrB,CAAC,CAAA,CACA,KAAK,EAAE,EAAA,EAAI,0BAA0B,CAAA,CACrC,SAAS,mDAAmD;AAiBxD,IAAM,wBAAA,GAA2B,EACrC,MAAA,CAAO;AAAA,EACN,YAAA,EAAc,gBAAA;AAAA,EACd,iBAAA,EAAmB,gBAAA;AAAA,EACnB,gBAAA,EAAkB,gBAAA;AAAA,EAClB,gBAAA,EAAkB,gBAAA;AAAA,EAClB,gBAAA,EAAkB,gBAAA;AAAA,EAClB,YAAA,EAAc,gBAAA;AAAA,EACd,YAAA,EAAc,gBAAA;AAAA,EACd,gBAAA,EAAkB;AACpB,CAAC,CAAA,CACA,KAAK,EAAE,EAAA,EAAI,sBAAsB,CAAA,CACjC,SAAS,2EAA2E","file":"index.js","sourcesContent":["import { z } from 'zod';\nimport { ClaimSchema, ConfidenceSchema } from '@disclosureos/records/shared';\n\n/**\n * A weighted origin hypothesis: an OCS node id plus the confidence assigned to it.\n */\nexport const HypothesisWeightSchema = z\n  .object({\n    nodeId: z.string().min(1).describe('OCS node id (e.g., \"1.1.3\").'),\n    confidence: ConfidenceSchema,\n    label: z.string().optional(),\n  })\n  .meta({ id: 'HypothesisWeight' })\n  .describe('A weighted origin hypothesis (OCS node + confidence).');\n\nexport type HypothesisWeight = z.infer<typeof HypothesisWeightSchema>;\n\n/**\n * A single attributed origin claim — one evaluator's verdict on what an\n * observation is: a primary OCS hypothesis with its confidence, optional\n * `alternativeHypotheses` (the intra-claim axis), and the shared {@link ClaimSchema}\n * envelope (`evaluatedAt` / `evaluatedBy` / `rationale` + `evidenceRefs`).\n *\n * The `Observation.origin` slot is a *list* of these (the inter-claim axis), so\n * competing classifications from different evaluators coexist without one being\n * privileged — endorsement is a scoring concern, not a records one.\n */\nexport const OriginClaimSchema = ClaimSchema.extend({\n  primaryHypothesis: z.string().min(1).describe('OCS node id of the primary hypothesis.'),\n  confidence: ConfidenceSchema.describe('Confidence in the primary hypothesis, in [0,1].'),\n  alternativeHypotheses: z\n    .array(HypothesisWeightSchema)\n    .optional()\n    .describe(\n      'Other OCS hypotheses this same evaluator weighs as possible, each with its own confidence — the intra-claim uncertainty axis.',\n    ),\n})\n  .meta({ id: 'OriginClaim' })\n  .describe('An attributed origin-hypothesis classification for an observation.');\n\nexport type OriginClaim = z.infer<typeof OriginClaimSchema>;\n\n/**\n * A full distribution of confidence across hypotheses, with `unresolved` holding\n * the remaining confidence not assigned to any hypothesis.\n */\nexport const ConfidenceDistributionSchema = z\n  .object({\n    hypotheses: z.array(HypothesisWeightSchema),\n    unresolved: ConfidenceSchema.describe('Remaining confidence not assigned to any hypothesis.'),\n    evaluatedAt: z.iso.datetime(),\n  })\n  .meta({ id: 'ConfidenceDistribution' })\n  .describe('Confidence distribution across origin hypotheses.');\n\nexport type ConfidenceDistribution = z.infer<typeof ConfidenceDistributionSchema>;\n\n/**\n * Simplified category-level confidence distribution for quick classification.\n * Each key maps to a broad OCS category. Values are confidence levels (0-1) that should sum to ~1.0.\n *\n * - `conventional` → OCS 1.1.1 (Prosaic explanations)\n * - `cryptoterrestrial` → OCS 1.1.2 (Hidden Earth-based entities)\n * - `extraterrestrial` → OCS 1.1.3 (Off-world visitors)\n * - `extradimensional` → OCS 1.2 (Other dimensions)\n * - `interdimensional` → OCS 1.3 (Dimension-traversing)\n * - `psychosocial` → OCS 2.0 (Perceptual/social factors)\n * - `metaphysical` → OCS 3.0 (Beyond conventional science)\n * - `insufficientData` → Cannot classify due to lack of information\n */\nexport const CategoryConfidenceSchema = z\n  .object({\n    conventional: ConfidenceSchema,\n    cryptoterrestrial: ConfidenceSchema,\n    extraterrestrial: ConfidenceSchema,\n    extradimensional: ConfidenceSchema,\n    interdimensional: ConfidenceSchema,\n    psychosocial: ConfidenceSchema,\n    metaphysical: ConfidenceSchema,\n    insufficientData: ConfidenceSchema,\n  })\n  .meta({ id: 'CategoryConfidence' })\n  .describe('Quick category-level confidence distribution across broad OCS categories.');\n\nexport type CategoryConfidence = z.infer<typeof CategoryConfidenceSchema>;\n"]}

package/dist/constants/index.d.ts

@@ -0,0 +1,41 @@
+import { OriginClaim } from '../classification/index.js';
+import 'zod';
+
+declare const ORIGIN_DOMAINS: ("psychosocial" | "metaphysical" | "physical")[];
+/**
+ * Provenance of the OCS taxonomy. The three-domain structure (Physical /
+ * Psychosocial / Metaphysical) is adapted from Col. Karl Nell's "Proposed
+ * Taxonomy of UAP Origin Hypotheses," presented at the Sol Foundation
+ * Symposium (Stanford University, November 2023). Surfaced as data so any
+ * consumer renders the same credit.
+ */
+declare const OCS_PROVENANCE: {
+    readonly author: "Col. Karl Nell (U.S. Army, ret.)";
+    readonly work: "Proposed Taxonomy of UAP Origin Hypotheses";
+    readonly venue: "Sol Foundation Symposium, Stanford University";
+    readonly date: "November 2023";
+};
+declare const ALL_OCS_IDS: readonly string[];
+declare const TESTABLE_IDS: readonly string[];
+declare const LEAF_IDS: readonly string[];
+declare const PHYSICAL_IDS: readonly string[];
+declare const PSYCHOSOCIAL_IDS: readonly string[];
+declare const METAPHYSICAL_IDS: readonly string[];
+/**
+ * Canonical shape for the `Observation.origin` slot, registered on `Observation`
+ * via module augmentation when this package is imported.
+ *
+ * A *list* of {@link OriginClaim}s: competing classifications from different
+ * evaluators coexist without one being privileged (the inter-claim axis).
+ *
+ * @example
+ * ```typescript
+ * import type { Observation } from '@disclosureos/records';
+ * import '@disclosureos/origins'; // augments Observation with `origin`
+ *
+ * const obs: Observation = { ...base, origin: [claim] };
+ * ```
+ */
+type OriginClassificationSlot = OriginClaim[];
+
+export { ALL_OCS_IDS, LEAF_IDS, METAPHYSICAL_IDS, OCS_PROVENANCE, ORIGIN_DOMAINS, type OriginClassificationSlot, PHYSICAL_IDS, PSYCHOSOCIAL_IDS, TESTABLE_IDS };