@disclosureos/schema 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to `@disclosureos/schema` 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 portable contract.
+
+### Added
+- `composeObservationSchema()` — merges the records core and every registered slot
+  schema into one enriched `Observation` JSON Schema, tightening the root to
+  `additionalProperties: false` while preserving the `extensions` bag.
+- `parseEnrichedObservation()` — non-stripping validation of core + slots in one call,
+  closing the strip hazard at the integration layer.
+- `ExtensionRegistry` / `defaultRegistry` — the runtime mirror of the TS augmentation.
+- `EnrichedObservation` convenience type and the committed composed schema
+  (`schema/enriched-observation.schema.json`, draft 2020-12).
+- ESM-only distribution.

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,97 @@
+# @disclosureos/schema
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+The **portable contract** for DisclosureOS. It composes the slot-bearing packages —
+[`@disclosureos/records`](../disclosureos-records) (the core),
+[`@disclosureos/observables`](../disclosureos-observables) (the
+`observableAssessments` slot), and [`@disclosureos/origins`](../disclosureos-origins)
+(the `origin` slot) — into one **enriched `Observation`** that means the same thing
+in TypeScript, JSON Schema, and any other language.
+
+DisclosureOS is a **five-part standard** (records → observables → origins → claims → scoring).
+`schema` is the contract that *binds* records and the package-owned slots into one
+portable artifact. It is a supporting package, not another part of the standard. (Scoring
+consumes the enriched record, so it is not part of the composed schema.)
+
+> ESM-only. CommonJS consumers can load it with a dynamic `import()`.
+
+## Why this package exists
+
+In TypeScript, importing the satellite packages augments `Observation` with their
+slots. That augmentation is compile-time only — invisible to JSON Schema or Python,
+and `ObservationSchema.parse()` silently **drops** the slots. This package closes
+that gap with three things:
+
+- **`composeObservationSchema()`** — merges the records core and every registered
+  slot into one `enriched-observation.schema.json` (draft 2020-12). The root is
+  tightened to `additionalProperties: false`, so unknown top-level keys are
+  rejected while the `extensions` bag still carries third-party data.
+- **`parseEnrichedObservation(value)`** — validates core + slots in one call
+  **without stripping** them (it delegates to each package's own validator).
+- **`ExtensionRegistry` / `defaultRegistry`** — the runtime mirror of the TS
+  augmentation: a map of `slot → { owner, schemaId, version, jsonSchema, validate }`.
+  Importing this package registers the first-party slots. The registry drives **both**
+  `composeObservationSchema()` (JSON Schema) and `parseEnrichedObservation()`
+  (validation), so registering a slot once wires it into both — nothing is hard-coded.
+
+> **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/schema @disclosureos/records @disclosureos/observables @disclosureos/origins zod
+```
+
+## Quickstart
+
+```ts
+import { parseEnrichedObservation, type EnrichedObservation } from '@disclosureos/schema';
+
+const observation: EnrichedObservation = {
+  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: '2020-01-01T00:00:00Z',
+  updatedAt: '2020-01-01T00:00:00Z',
+  observableAssessments: { technology: { antigravity_lift: [{ level: 'confirmed', confidence: 1 }] } },
+  origin: [{ primaryHypothesis: '1.1.3', confidence: 0.9 }],
+};
+
+const result = parseEnrichedObservation(observation);
+if (!result.success) console.error(result.issues);
+// result.data still has observableAssessments + origin — nothing stripped.
+```
+
+## The composed JSON Schema
+
+`schema/enriched-observation.schema.json` is the committed, versioned artifact
+(`$id` at `https://os.disclosure.org/schema/schema/<version>/enriched-observation.json`).
+Regenerate it after any layer-schema change:
+
+```bash
+pnpm --filter @disclosureos/schema emit:schema
+```
+
+A drift test fails if the committed file diverges from the emitted one. Because the
+composed schema depends on three layer schemas, bumping a layer schema may bump this
+artifact too.
+
+## Standard Schema
+
+`parseEnrichedObservation` delegates to each layer's own Zod validator, and those
+schemas implement [Standard Schema v1](https://standardschema.dev) via their
+`~standard` property (a guarantee of Zod 4). So the slot validators this package
+composes are consumable directly by any Standard-Schema-compatible tool, with no
+DisclosureOS-specific adapter.
+
+## License
+
+MIT © [Disclosure Foundation](https://disclosure.org)

package/dist/index.d.ts

@@ -0,0 +1,117 @@
+import { ValidationIssue } from '@disclosureos/records/shared';
+import { Observation } from '@disclosureos/records';
+
+/**
+ * `ExtensionRegistry` — the runtime mirror of the TypeScript module augmentation.
+ *
+ * In TS, importing `@disclosureos/observables` / `@disclosureos/origins` augments
+ * `Observation` with the `observableAssessments` / `origin` slots. That augmentation
+ * is compile-time only — invisible to JSON Schema, Python, or any non-TS consumer.
+ *
+ * This registry makes the same fact available at runtime: it maps each satellite
+ * slot to its owner package, canonical schema `$id`, version, and a function that
+ * emits the slot's standalone JSON Schema. {@link composeObservationSchema} walks
+ * the registry to fold every registered slot into one enriched `Observation` schema,
+ * so adding a new first-party (or third-party) slot is a single `register()` call —
+ * no edit to the composition logic OR the validation logic: {@link composeObservationSchema}
+ * walks the registry for JSON Schema and `parseEnrichedObservation` walks it for runtime
+ * validation, both driven entirely by what is registered.
+ */
+
+/** One satellite slot on `Observation`, described for runtime composition. */
+interface SlotRegistration {
+    /** Property name on `Observation` (e.g. `"observableAssessments"`, `"origin"`). */
+    slot: string;
+    /** Package that owns the slot (e.g. `"@disclosureos/observables"`). */
+    owner: string;
+    /** Canonical, versioned `$id` of the slot's standalone JSON Schema. */
+    schemaId: string;
+    /** Schema version of the slot (its `x-schema-version`). */
+    version: string;
+    /**
+     * Emit the slot's standalone JSON Schema (the same enveloped artifact the owner
+     * package commits). Called by {@link composeObservationSchema} during merge.
+     */
+    jsonSchema: () => Record<string, unknown>;
+    /**
+     * Validate the slot's value with the owner package's canonical, schema-backed
+     * validator. Called by `parseEnrichedObservation` for every present slot, so
+     * enriched validation stays brand-free (each package validates with its own Zod)
+     * and registry-driven (no slot is hard-coded in the parse path).
+     */
+    validate: (value: unknown) => ValidationIssue[];
+}
+/**
+ * A mutable map of `slot → registration`. Use the shared {@link defaultRegistry}
+ * for the first-party slots; construct your own only for isolated tests or to
+ * compose a custom subset of slots.
+ */
+declare class ExtensionRegistry {
+    private readonly slots;
+    /**
+     * Register a slot. Throws on a duplicate slot name (one owner per slot).
+     *
+     * @experimental First-party slots (observables, origins) are registered for you
+     * on {@link defaultRegistry}. Registering *third-party* slots is supported but the
+     * extensibility contract (how external slots compose, version, and resolve) is
+     * still settling and may change in a minor release.
+     */
+    register(registration: SlotRegistration): this;
+    /** Look up a slot's registration, or `undefined` if not registered. */
+    get(slot: string): SlotRegistration | undefined;
+    /** Whether a slot is registered. */
+    has(slot: string): boolean;
+    /** All registrations, in insertion order. */
+    list(): SlotRegistration[];
+}
+/**
+ * The shared registry, pre-populated with the first-party satellite slots. Import
+ * sites that need the full enriched contract should use this; it is the runtime
+ * counterpart to importing both satellite packages for their TS augmentation.
+ */
+declare const defaultRegistry: ExtensionRegistry;
+
+/**
+ * Version of the emitted composed-schema artifact. Bump on any intentional change
+ * to the enriched shape — note that bumping a *layer* schema can also change this
+ * artifact, so the drift test guards both.
+ */
+declare const ENRICHED_OBSERVATION_SCHEMA_VERSION = "1.0.0";
+declare const ENRICHED_OBSERVATION_SCHEMA_ID: string;
+/**
+ * Compose the enriched `Observation` JSON Schema (draft 2020-12) from the records
+ * core plus every slot in `registry` (defaults to the first-party
+ * {@link defaultRegistry}).
+ *
+ * The result is the standard enveloped artifact: a `$ref` to `#/$defs/Observation`,
+ * where `Observation` carries the records core properties plus one property per
+ * registered slot, and `additionalProperties: false` rejects unknown top-level keys.
+ */
+declare function composeObservationSchema(registry?: ExtensionRegistry): Record<string, unknown>;
+
+/**
+ * A complete observation: the records core plus the satellite slots. Because both
+ * satellite packages augment `Observation`, the slots are already part of the
+ * `Observation` type wherever `@disclosureos/schema` (which imports both) is loaded;
+ * this alias names that enriched shape explicitly as the public contract type.
+ */
+type EnrichedObservation = Observation;
+/** Outcome of {@link parseEnrichedObservation}: issues are empty iff `success`. */
+interface EnrichedParseResult {
+    success: boolean;
+    /** The validated record (reference-equal to the input) when `success`. */
+    data?: EnrichedObservation;
+    /** Flat list of validation issues (empty when valid). */
+    issues: ValidationIssue[];
+}
+/**
+ * Validate an enriched observation (records core + `observableAssessments` + `origin`)
+ * in one call, WITHOUT stripping the satellite slots.
+ *
+ * Returns `{ success: true, data }` (where `data` is the same object you passed in)
+ * when valid, or `{ success: false, issues }` with a flat list of path-tagged issues.
+ * Unknown top-level keys are rejected; arbitrary data still belongs under `extensions`.
+ */
+declare function parseEnrichedObservation(value: unknown): EnrichedParseResult;
+
+export { ENRICHED_OBSERVATION_SCHEMA_ID, ENRICHED_OBSERVATION_SCHEMA_VERSION, type EnrichedObservation, type EnrichedParseResult, ExtensionRegistry, type SlotRegistration, composeObservationSchema, defaultRegistry, parseEnrichedObservation };

package/dist/index.js

@@ -0,0 +1,149 @@
+import { recordsJsonSchema, validateObservation } from '@disclosureos/records';
+import { schemaId, jsonSchemaEnvelope } from '@disclosureos/records/shared';
+import { validateObservableAssessments, observablesJsonSchema, OBSERVABLES_SCHEMA_VERSION, OBSERVABLES_SCHEMA_ID } from '@disclosureos/observables';
+import { validateOriginClassification, originsJsonSchema, ORIGINS_SCHEMA_VERSION, ORIGINS_SCHEMA_ID } from '@disclosureos/origins';
+
+// src/registry.ts
+var ExtensionRegistry = class {
+  constructor() {
+    this.slots = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Register a slot. Throws on a duplicate slot name (one owner per slot).
+   *
+   * @experimental First-party slots (observables, origins) are registered for you
+   * on {@link defaultRegistry}. Registering *third-party* slots is supported but the
+   * extensibility contract (how external slots compose, version, and resolve) is
+   * still settling and may change in a minor release.
+   */
+  register(registration) {
+    if (this.slots.has(registration.slot)) {
+      const existing = this.slots.get(registration.slot);
+      throw new Error(
+        `Slot "${registration.slot}" is already registered by ${existing.owner}; cannot re-register it for ${registration.owner}.`
+      );
+    }
+    this.slots.set(registration.slot, registration);
+    return this;
+  }
+  /** Look up a slot's registration, or `undefined` if not registered. */
+  get(slot) {
+    return this.slots.get(slot);
+  }
+  /** Whether a slot is registered. */
+  has(slot) {
+    return this.slots.has(slot);
+  }
+  /** All registrations, in insertion order. */
+  list() {
+    return [...this.slots.values()];
+  }
+};
+var defaultRegistry = new ExtensionRegistry();
+var ENRICHED_OBSERVATION_SCHEMA_VERSION = "1.0.0";
+var ENRICHED_OBSERVATION_SCHEMA_ID = schemaId(
+  "schema",
+  "enriched-observation",
+  ENRICHED_OBSERVATION_SCHEMA_VERSION
+);
+defaultRegistry.register({
+  slot: "observableAssessments",
+  owner: "@disclosureos/observables",
+  schemaId: OBSERVABLES_SCHEMA_ID,
+  version: OBSERVABLES_SCHEMA_VERSION,
+  jsonSchema: observablesJsonSchema,
+  validate: validateObservableAssessments
+}).register({
+  slot: "origin",
+  owner: "@disclosureos/origins",
+  schemaId: ORIGINS_SCHEMA_ID,
+  version: ORIGINS_SCHEMA_VERSION,
+  jsonSchema: originsJsonSchema,
+  validate: validateOriginClassification
+});
+function splitSlotSchema(schema) {
+  const { $schema, $id, "x-schema-version": _version, $defs, ...body } = schema;
+  return { body, defs: $defs ?? {} };
+}
+function composeObservationSchema(registry = defaultRegistry) {
+  const records = recordsJsonSchema();
+  const defs = structuredClone(records.$defs ?? {});
+  const observation = defs["Observation"];
+  if (!observation) {
+    throw new Error('records schema is missing the "Observation" $def; cannot compose.');
+  }
+  const slotProperties = {};
+  for (const registration of registry.list()) {
+    const { body, defs: slotDefs } = splitSlotSchema(registration.jsonSchema());
+    for (const [name, def] of Object.entries(slotDefs)) {
+      if (name in defs) {
+        throw new Error(
+          `$defs collision composing enriched schema: "${name}" is defined by both the records core and ${registration.owner}. Slots must own disjoint $defs.`
+        );
+      }
+      defs[name] = def;
+    }
+    slotProperties[registration.slot] = body;
+  }
+  observation["properties"] = {
+    ...observation["properties"],
+    ...slotProperties
+  };
+  observation["additionalProperties"] = false;
+  const composed = {
+    description: "A complete DisclosureOS observation: the records core enriched with observable assessments and origin classification. The portable contract across TypeScript, JSON Schema, and other languages.",
+    $ref: "#/$defs/Observation",
+    $defs: defs
+  };
+  return jsonSchemaEnvelope(composed, {
+    id: ENRICHED_OBSERVATION_SCHEMA_ID,
+    version: ENRICHED_OBSERVATION_SCHEMA_VERSION
+  });
+}
+function underSlot(slot, issues) {
+  return issues.map((issue) => ({
+    path: issue.path ? `${slot}.${issue.path}` : slot,
+    message: issue.message
+  }));
+}
+var allowedTopLevelKeys;
+function getAllowedTopLevelKeys() {
+  if (!allowedTopLevelKeys) {
+    const composed = composeObservationSchema();
+    const observation = composed.$defs["Observation"];
+    const properties = observation?.["properties"] ?? {};
+    allowedTopLevelKeys = new Set(Object.keys(properties));
+  }
+  return allowedTopLevelKeys;
+}
+function parseEnrichedObservation(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return { success: false, issues: [{ path: "", message: "expected an observation object" }] };
+  }
+  const record = value;
+  const issues = [];
+  issues.push(...validateObservation(record));
+  for (const registration of defaultRegistry.list()) {
+    const slotValue = record[registration.slot];
+    if (slotValue !== void 0) {
+      issues.push(...underSlot(registration.slot, registration.validate(slotValue)));
+    }
+  }
+  const allowed = getAllowedTopLevelKeys();
+  for (const key of Object.keys(record)) {
+    if (!allowed.has(key)) {
+      issues.push({
+        path: key,
+        message: `unknown top-level key "${key}" \u2014 third-party data belongs under "extensions".`
+      });
+    }
+  }
+  if (issues.length > 0) {
+    return { success: false, issues };
+  }
+  return { success: true, data: record, issues: [] };
+}
+
+export { ENRICHED_OBSERVATION_SCHEMA_ID, ENRICHED_OBSERVATION_SCHEMA_VERSION, ExtensionRegistry, composeObservationSchema, defaultRegistry, parseEnrichedObservation };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/registry.ts","../src/compose.ts","../src/parse.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * `ExtensionRegistry` — the runtime mirror of the TypeScript module augmentation.\n *\n * In TS, importing `@disclosureos/observables` / `@disclosureos/origins` augments\n * `Observation` with the `observableAssessments` / `origin` slots. That augmentation\n * is compile-time only — invisible to JSON Schema, Python, or any non-TS consumer.\n *\n * This registry makes the same fact available at runtime: it maps each satellite\n * slot to its owner package, canonical schema `$id`, version, and a function that\n * emits the slot's standalone JSON Schema. {@link composeObservationSchema} walks\n * the registry to fold every registered slot into one enriched `Observation` schema,\n * so adding a new first-party (or third-party) slot is a single `register()` call —\n * no edit to the composition logic OR the validation logic: {@link composeObservationSchema}\n * walks the registry for JSON Schema and `parseEnrichedObservation` walks it for runtime\n * validation, both driven entirely by what is registered.\n */\nimport type { ValidationIssue } from '@disclosureos/records/shared';\n\n/** One satellite slot on `Observation`, described for runtime composition. */\nexport interface SlotRegistration {\n  /** Property name on `Observation` (e.g. `\"observableAssessments\"`, `\"origin\"`). */\n  slot: string;\n  /** Package that owns the slot (e.g. `\"@disclosureos/observables\"`). */\n  owner: string;\n  /** Canonical, versioned `$id` of the slot's standalone JSON Schema. */\n  schemaId: string;\n  /** Schema version of the slot (its `x-schema-version`). */\n  version: string;\n  /**\n   * Emit the slot's standalone JSON Schema (the same enveloped artifact the owner\n   * package commits). Called by {@link composeObservationSchema} during merge.\n   */\n  jsonSchema: () => Record<string, unknown>;\n  /**\n   * Validate the slot's value with the owner package's canonical, schema-backed\n   * validator. Called by `parseEnrichedObservation` for every present slot, so\n   * enriched validation stays brand-free (each package validates with its own Zod)\n   * and registry-driven (no slot is hard-coded in the parse path).\n   */\n  validate: (value: unknown) => ValidationIssue[];\n}\n\n/**\n * A mutable map of `slot → registration`. Use the shared {@link defaultRegistry}\n * for the first-party slots; construct your own only for isolated tests or to\n * compose a custom subset of slots.\n */\nexport class ExtensionRegistry {\n  private readonly slots = new Map<string, SlotRegistration>();\n\n  /**\n   * Register a slot. Throws on a duplicate slot name (one owner per slot).\n   *\n   * @experimental First-party slots (observables, origins) are registered for you\n   * on {@link defaultRegistry}. Registering *third-party* slots is supported but the\n   * extensibility contract (how external slots compose, version, and resolve) is\n   * still settling and may change in a minor release.\n   */\n  register(registration: SlotRegistration): this {\n    if (this.slots.has(registration.slot)) {\n      const existing = this.slots.get(registration.slot)!;\n      throw new Error(\n        `Slot \"${registration.slot}\" is already registered by ${existing.owner}; `\n          + `cannot re-register it for ${registration.owner}.`,\n      );\n    }\n    this.slots.set(registration.slot, registration);\n    return this;\n  }\n\n  /** Look up a slot's registration, or `undefined` if not registered. */\n  get(slot: string): SlotRegistration | undefined {\n    return this.slots.get(slot);\n  }\n\n  /** Whether a slot is registered. */\n  has(slot: string): boolean {\n    return this.slots.has(slot);\n  }\n\n  /** All registrations, in insertion order. */\n  list(): SlotRegistration[] {\n    return [...this.slots.values()];\n  }\n}\n\n/**\n * The shared registry, pre-populated with the first-party satellite slots. Import\n * sites that need the full enriched contract should use this; it is the runtime\n * counterpart to importing both satellite packages for their TS augmentation.\n */\nexport const defaultRegistry = new ExtensionRegistry();\n","/**\n * `composeObservationSchema()` — fold the records core schema and every registered\n * satellite slot schema into one enriched `Observation` JSON Schema.\n *\n * This is the **portable contract**: the single artifact that means the same thing\n * in TypeScript, JSON Schema, Python, and the docs. The records core schema is\n * deliberately OPEN (`additionalProperties: true`) because its satellite slots\n * attach via augmentation; here we fold those slots back in as real properties and\n * TIGHTEN the root to `additionalProperties: false` — unknown top-level keys are\n * rejected, while the `extensions` bag (a named property) still carries arbitrary\n * third-party data.\n *\n * Composition is a brand-free, plain-data merge: each layer's committed JSON Schema\n * (records + the slots from {@link defaultRegistry}) is merged by `$defs` name. The\n * three layers own disjoint `$defs` (records: `Observation`/`Temporal`/…;\n * observables: `ObservableAssessmentMap`/…; origins: `OriginClaim`/…), so the merge\n * needs no `$ref` rewriting; a collision throws loudly rather than silently winning.\n */\nimport { recordsJsonSchema } from '@disclosureos/records';\nimport { schemaId, jsonSchemaEnvelope } from '@disclosureos/records/shared';\nimport {\n  observablesJsonSchema,\n  validateObservableAssessments,\n  OBSERVABLES_SCHEMA_ID,\n  OBSERVABLES_SCHEMA_VERSION,\n} from '@disclosureos/observables';\nimport {\n  originsJsonSchema,\n  validateOriginClassification,\n  ORIGINS_SCHEMA_ID,\n  ORIGINS_SCHEMA_VERSION,\n} from '@disclosureos/origins';\nimport { defaultRegistry, ExtensionRegistry } from './registry';\n\n/**\n * Version of the emitted composed-schema artifact. Bump on any intentional change\n * to the enriched shape — note that bumping a *layer* schema can also change this\n * artifact, so the drift test guards both.\n */\nexport const ENRICHED_OBSERVATION_SCHEMA_VERSION = '1.0.0';\n\nexport const ENRICHED_OBSERVATION_SCHEMA_ID = schemaId(\n  'schema',\n  'enriched-observation',\n  ENRICHED_OBSERVATION_SCHEMA_VERSION,\n);\n\n// Runtime mirror of the TS augmentation: register the first-party slots once, at\n// module load. Importing `@disclosureos/schema` is the runtime counterpart to\n// importing both satellite packages for their compile-time augmentation.\ndefaultRegistry\n  .register({\n    slot: 'observableAssessments',\n    owner: '@disclosureos/observables',\n    schemaId: OBSERVABLES_SCHEMA_ID,\n    version: OBSERVABLES_SCHEMA_VERSION,\n    jsonSchema: observablesJsonSchema,\n    validate: validateObservableAssessments,\n  })\n  .register({\n    slot: 'origin',\n    owner: '@disclosureos/origins',\n    schemaId: ORIGINS_SCHEMA_ID,\n    version: ORIGINS_SCHEMA_VERSION,\n    jsonSchema: originsJsonSchema,\n    validate: validateOriginClassification,\n  });\n\n/** Strip the standard envelope (`$schema`/`$id`/`x-schema-version`) and pull `$defs` off a slot schema. */\nfunction splitSlotSchema(schema: Record<string, unknown>): {\n  body: Record<string, unknown>;\n  defs: Record<string, unknown>;\n} {\n  const { $schema, $id, 'x-schema-version': _version, $defs, ...body } = schema as Record<\n    string,\n    unknown\n  > & { $defs?: Record<string, unknown> };\n  void $schema;\n  void $id;\n  void _version;\n  return { body, defs: $defs ?? {} };\n}\n\n/**\n * Compose the enriched `Observation` JSON Schema (draft 2020-12) from the records\n * core plus every slot in `registry` (defaults to the first-party\n * {@link defaultRegistry}).\n *\n * The result is the standard enveloped artifact: a `$ref` to `#/$defs/Observation`,\n * where `Observation` carries the records core properties plus one property per\n * registered slot, and `additionalProperties: false` rejects unknown top-level keys.\n */\nexport function composeObservationSchema(\n  registry: ExtensionRegistry = defaultRegistry,\n): Record<string, unknown> {\n  const records = recordsJsonSchema();\n  const defs = structuredClone(records.$defs ?? {}) as Record<string, Record<string, unknown>>;\n\n  const observation = defs['Observation'];\n  if (!observation) {\n    throw new Error('records schema is missing the \"Observation\" $def; cannot compose.');\n  }\n\n  const slotProperties: Record<string, unknown> = {};\n\n  for (const registration of registry.list()) {\n    const { body, defs: slotDefs } = splitSlotSchema(registration.jsonSchema());\n\n    for (const [name, def] of Object.entries(slotDefs)) {\n      if (name in defs) {\n        throw new Error(\n          `$defs collision composing enriched schema: \"${name}\" is defined by both `\n            + `the records core and ${registration.owner}. Slots must own disjoint $defs.`,\n        );\n      }\n      defs[name] = def as Record<string, unknown>;\n    }\n\n    slotProperties[registration.slot] = body;\n  }\n\n  // Fold the slots in as real properties and close the root: unknown top-level keys\n  // are rejected; the `extensions` bag (a named property) keeps the third-party seam.\n  observation['properties'] = {\n    ...(observation['properties'] as Record<string, unknown> | undefined),\n    ...slotProperties,\n  };\n  observation['additionalProperties'] = false;\n\n  const composed = {\n    description:\n      'A complete DisclosureOS observation: the records core enriched with observable '\n      + 'assessments and origin classification. The portable contract across TypeScript, '\n      + 'JSON Schema, and other languages.',\n    $ref: '#/$defs/Observation',\n    $defs: defs,\n  };\n\n  return jsonSchemaEnvelope(composed, {\n    id: ENRICHED_OBSERVATION_SCHEMA_ID,\n    version: ENRICHED_OBSERVATION_SCHEMA_VERSION,\n  });\n}\n","/**\n * `parseEnrichedObservation()` — the non-stripping validation entry point.\n *\n * The records core `ObservationSchema` does not know about the satellite slots, so\n * a raw `ObservationSchema.parse(record)` SILENTLY DROPS `observableAssessments` and\n * `origin` (the A1 \"strip hazard\"). This function closes that hazard at the\n * integration layer: it validates the core and each present slot with the SAME\n * canonical validators each package ships, rejects unknown top-level keys, and\n * returns the caller's object untouched on success — slots intact.\n *\n * It composes by delegation (not by re-parsing through one mega-Zod-object), so it\n * is brand-free: each package validates its own slot with its own Zod instance,\n * exactly as the CLI does.\n */\nimport { validateObservation } from '@disclosureos/records';\nimport type { Observation } from '@disclosureos/records';\nimport type { ValidationIssue } from '@disclosureos/records/shared';\nimport { composeObservationSchema } from './compose';\nimport { defaultRegistry } from './registry';\n\n/**\n * A complete observation: the records core plus the satellite slots. Because both\n * satellite packages augment `Observation`, the slots are already part of the\n * `Observation` type wherever `@disclosureos/schema` (which imports both) is loaded;\n * this alias names that enriched shape explicitly as the public contract type.\n */\nexport type EnrichedObservation = Observation;\n\n/** Outcome of {@link parseEnrichedObservation}: issues are empty iff `success`. */\nexport interface EnrichedParseResult {\n  success: boolean;\n  /** The validated record (reference-equal to the input) when `success`. */\n  data?: EnrichedObservation;\n  /** Flat list of validation issues (empty when valid). */\n  issues: ValidationIssue[];\n}\n\n/** Prefix slot-local issue paths with the slot name so errors point at the right field. */\nfunction underSlot(slot: string, issues: ValidationIssue[]): ValidationIssue[] {\n  return issues.map((issue) => ({\n    path: issue.path ? `${slot}.${issue.path}` : slot,\n    message: issue.message,\n  }));\n}\n\n// The composed schema is the single source of truth for which top-level keys are\n// allowed (records core properties + every registered slot). Computed once.\nlet allowedTopLevelKeys: Set<string> | undefined;\nfunction getAllowedTopLevelKeys(): Set<string> {\n  if (!allowedTopLevelKeys) {\n    const composed = composeObservationSchema();\n    const observation = (composed.$defs as Record<string, Record<string, unknown>>)['Observation'];\n    const properties = (observation?.['properties'] as Record<string, unknown>) ?? {};\n    allowedTopLevelKeys = new Set(Object.keys(properties));\n  }\n  return allowedTopLevelKeys;\n}\n\n/**\n * Validate an enriched observation (records core + `observableAssessments` + `origin`)\n * in one call, WITHOUT stripping the satellite slots.\n *\n * Returns `{ success: true, data }` (where `data` is the same object you passed in)\n * when valid, or `{ success: false, issues }` with a flat list of path-tagged issues.\n * Unknown top-level keys are rejected; arbitrary data still belongs under `extensions`.\n */\nexport function parseEnrichedObservation(value: unknown): EnrichedParseResult {\n  if (typeof value !== 'object' || value === null || Array.isArray(value)) {\n    return { success: false, issues: [{ path: '', message: 'expected an observation object' }] };\n  }\n\n  const record = value as Record<string, unknown>;\n  const issues: ValidationIssue[] = [];\n\n  issues.push(...validateObservation(record));\n\n  // Validate every present slot with its owner's validator — driven by the registry,\n  // so a newly registered slot is validated here without editing this function.\n  for (const registration of defaultRegistry.list()) {\n    const slotValue = record[registration.slot];\n    if (slotValue !== undefined) {\n      issues.push(...underSlot(registration.slot, registration.validate(slotValue)));\n    }\n  }\n\n  const allowed = getAllowedTopLevelKeys();\n  for (const key of Object.keys(record)) {\n    if (!allowed.has(key)) {\n      issues.push({\n        path: key,\n        message: `unknown top-level key \"${key}\" — third-party data belongs under \"extensions\".`,\n      });\n    }\n  }\n\n  if (issues.length > 0) {\n    return { success: false, issues };\n  }\n  return { success: true, data: record as unknown as EnrichedObservation, issues: [] };\n}\n"]}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@disclosureos/schema",
+  "version": "1.0.0",
+  "description": "The DisclosureOS portable contract — composes the records core, observable assessments, and origin classification into one enriched Observation schema (TypeScript + JSON Schema), with a non-stripping parse",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/disclosurefoundation/disclosureos"
+  },
+  "homepage": "https://github.com/disclosurefoundation/disclosureos#readme",
+  "bugs": {
+    "url": "https://github.com/disclosurefoundation/disclosureos/issues"
+  },
+  "keywords": [
+    "disclosureos",
+    "UAP",
+    "schema",
+    "json-schema",
+    "observation",
+    "typescript"
+  ],
+  "sideEffects": false,
+  "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./schema": "./schema/enriched-observation.schema.json",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "schema",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@disclosureos/records": "1.0.0",
+    "@disclosureos/observables": "1.0.0",
+    "@disclosureos/origins": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsup": "^8.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.2",
+    "vitest": "^4.0.18",
+    "@arethetypeswrong/cli": "^0.18.3",
+    "publint": "^0.3.21",
+    "@repo/typescript-config": "0.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint .",
+    "type-check": "tsc --noEmit",
+    "emit:schema": "tsx scripts/emit-schema.ts",
+    "clean": "rm -rf dist",
+    "test": "vitest",
+    "lint:publish": "publint --strict && attw --pack . --profile esm-only"
+  }
+}