Testimony and recorded accounts

Keep a witness, each recorded account and a reviewer's interpretation distinct. A later retelling can refer to the same witness without becoming another independent witness. Event time, recording time and the time a qualification applied remain separate.

Explore the interactive testimony reference, download the fictional witness example, or inspect an individual JSON document.

Witnesses and accounts

The published research-entities 0.1.0 contract carries sourced assertions for four kinds of entity:

Unknown, withheld and omitted information remain distinct. An explicit false value requires a source; omission supplies no default. Alternative assertions can coexist. A summary identifies its summarizer, rather than attributing an editor's wording to the speaker. Qualifications carry a calendar time, context reference or explicit unknown time.

Private identity mappings and contact properties are excluded from the typed public fields. This is not a privacy sanitizer: public names, free text and URLs must already be approved for publication. Never serialize private intake envelopes into a public document.

Run the witness example

Extract the ZIP, open the witness-accounts folder and use Node.js 22 or later:

npm install
npm start

The archive pins records and schema to 2.0.0-beta.3. Its four JSON snapshots and runner come from the merged release; source.json records the source commit and file digests. All people and statements are fictional. The example preserves the third quarter of 1952, accounts recorded in 1981 and 1990, and explicitly unknown consent, oath, polygraph results and independence.

import {
  parseResearchEntities,
  parseResearchClaimHistory,
} from "@disclosureos/records/experimental/v2";
import { evaluateResearchClaimHistory } from "@disclosureos/schema/experimental/v2";
import { readFileSync } from "node:fs";
import { createHash } from "node:crypto";
const read = (name: string) => readFileSync(name);
const entities = JSON.parse(read("entities.json").toString("utf8"));
const history = JSON.parse(read("history.json").toString("utf8"));
console.log(
  parseResearchEntities(entities),
  parseResearchClaimHistory(history),
);
const documents = new Map(
  ["observation.json", "context.json", "entities.json"].map((name) => {
    const bytes = read(name);
    return [createHash("sha256").update(bytes).digest("hex"), bytes] as const;
  }),
);
console.log(await evaluateResearchClaimHistory(history, { documents }));

Use the explicit records schema exports /experimental/v2/entities/schema/0.1.0 and /experimental/v2/claims/schema/0.3.0. Package versions and document versions are different identifiers.

Attributable review

Claim-history 0.3.0 supports observation, measurement, context and research-entity subjects. An entity subject identifies an exact document ID and SHA-256, entity kind and scoped ID, with an optional field. Assertion inputs identify a particular assertion on that field. Changing the snapshot changes the review subject.

witnessReview belongs to an assessed claim with an entity subject, explicit inputs, evaluator, method/version, evaluation time and rationale. Ratings, factors, consistency and independence remain reviewer declarations. Anonymity does not create an automatic penalty; qualitative ratings do not become numeric scores. Competing reviews can coexist.

The parsers check structure and local relationships. The supplied-document evaluator checks exact bytes, document identities, observation scope and typed references. It does not fetch URLs or source artifacts. Source artifact integrity, scientific interpretation and profile applicability remain not_checked, even when supplied-document checks pass.

Check source provenance

The following historical-testimony profile uses its existing claim-history contract. It does not accept claim-history 0.3.0; do not strip witness or account information to pass an older evaluator. Run the separate provenance example for these checks.

The testimony workflow checks the provenance of selected accounts. It accepts unknown event time and location and does not require sensor measurements, assessments or a legal name for the speaker. The API is named historical-testimony; contemporary recorded accounts can use it too.

Explore the testimony structure, or download and run the synthetic examples.

Assemble the source record

1. Put the preserved account in the observation's sources inventory with kind: testimony, its actual access declaration and a SHA-256 digest.
2. Retain source statements in the claim history, including the passage locator, extractor and speaker attribution for direct extractions.
3. Supply a testimony selection naming the exact history/observation IDs and the sources to check.
4. Supply the local account bytes in an assets map under their source references.

Each selected account has sourceRef and recording. Known recording context includes recordedBy and reference; unknown context includes a reason. Unknown recording context is representable but does not satisfy the required citation.

Keep these identities distinct:

Never infer one identity from another. Mixed-speaker material needs passage-specific attribution. A document containing testimony may remain a document source; do not change source kind merely to pass this profile.

Run the provenance evaluator

Run this from the extracted example folder, after installing its pinned dependency:

import { readFileSync } from "node:fs";
import { evaluateHistoricalTestimony } from "@disclosureos/schema/experimental/v2";
const read = (name: string) => readFileSync(`testimony/${name}`);
const result = await evaluateHistoricalTestimony(
  JSON.parse(read("history.json").toString("utf8")),
  JSON.parse(read("selection.json").toString("utf8")),
  { assets: new Map([["source:report", new Uint8Array(read("account.txt"))]]) },
);
console.log(result.accounts, result.checks, result.scientificEligibility);

Import the selection JSON Schema through @disclosureos/schema/experimental/v2/historical-testimony/schema. Its identifier is urn:disclosureos:experimental:historical-testimony-selection:0.1.0.

Understand the checklist

Required inputs are a testimony source, recording citation, digest and matching nonempty bytes. Supplied direct extractions additionally require locator, extractor and speaker attribution. Source title and URI are recommended citation aids; missing recommendations do not become scientific penalties.

The extraction scope includes current source statements and observation value assertions directly citing a selected source. Superseded statements do not determine the current checklist. No supplied extraction means not_applicable, not that transcription is complete. OCR, translations and other derived material need their own processing provenance.

Missing required declarations fail the relevant requirements. Unavailable bytes leave an otherwise eligible profile not_checked; mismatching bytes fail. The evaluator never fetches the source URI.

Scope of the provenance result

external: passed here means selected local bytes match declared digests. Speaker identity, recording authenticity, account accuracy, firsthand knowledge, witness independence, extraction accuracy, assessment support, redistribution rights and scientific eligibility remain unchecked.

The returned history retains its access declarations; it is not a public projection. Witnesses, accounts and attributable reviews use the separate contracts described above. The provenance result does not establish those declarations as true. See Claims for the distinction between an author's conclusion and a validated record.