Claiming Observables

This guide is the workflow for adding observable claims to a record. The standard's credibility rests on claims being made honestly, so most of this guide is about restraint.

1. Make the evidence citable first

A claim without evidenceRefs is an assertion; a claim with them is auditable. Before claiming, make sure the evidence lives in the record with a stable id:

import { createObservation, createSensorReading } from '@disclosureos/records/factories';
import { evidenceRef } from '@disclosureos/records/shared';

const radar = createSensorReading('military_radar', 'radar_doppler', {
  id: 'redflag-range-radar',
  operator: 'USAF',
});

const obs = createObservation({
  // ...
  sensorEvidence: { sensors: [radar] },
});

const RADAR = evidenceRef('sensor', radar.id);

Testimony and physical evidence are citable too — see Extension Slots.

2. Pick the observable precisely

Read the definition before claiming — each observable has specific detectionSignals. "It moved fast" is not instantaneous_acceleration; a measured velocity change inconsistent with known aerospace capability is:

import { TECHNOLOGY_OBSERVABLES } from '@disclosureos/observables';

TECHNOLOGY_OBSERVABLES.instantaneous_acceleration.detectionSignals;
// ['Radar track showing extreme velocity change over minimal time', ...]

If no observable fits, claim nothing. The absence of claims is a valid, honest state for a record.

3. Choose the level the evidence supports

Resist level inflation. documented with a solid paper trail outranks an unsupportable confirmed in every way that matters — and compellingness scoring weighs evidence quality, not just the level word.

4. Set confidence separately

Confidence is your certainty in your own judgment, not the strength of the evidence class:

import { createObservableClaim } from '@disclosureos/observables';

const claim = createObservableClaim('measured', {
  confidence: 0.6,   // the data is instrumented, but the calibration is debatable
  rationale: 'Doppler velocity profile shows 40g lateral acceleration; sensor calibration records incomplete.',
  evidenceRefs: [RADAR],
  evaluatedBy: 'example-institution',
});

Always write the rationale. It's what lets another analyst — or Congress, or a journalist — understand the claim without calling you.

5. Attach without overwriting

Slots hold arrays. When re-assessing or disagreeing, append:

obs.observableAssessments ??= {};
obs.observableAssessments.technology ??= {};
(obs.observableAssessments.technology.instantaneous_acceleration ??= []).push(claim);

Never delete another evaluator's claim to make room for yours. Contradicting claims coexist — that's how the standard records a live dispute, and scoring will surface it as contested.

6. Validate the result

import { parseEnrichedObservation } from '@disclosureos/schema';

const result = parseEnrichedObservation(obs);

Or from the terminal — which also warns on evidence refs that don't resolve:

npx @disclosureos/cli validate observation.json

Worked end-to-end

The golden path shows the full sequence on the Nimitz case, and Scoring shows what your claims feed into.