Documents and provenance

Keep each document copy connected to its own history. Two copies with the same title may have different bytes, page counts, markings and release events. A citation should identify the edition it describes.

Explore the document structure or download the worked example. The example is entirely fictional and uses the published 2.0.0-beta.3 packages.

Describe each edition

Research entities use independently identified, sourced assertions. Preserve known, approximate, unknown, redacted and unmapped values separately. Conflicting statements remain separate; omission does not mean false.

An edition binds to a source or product in the observation inventory and its declared SHA-256. A URL or title cannot substitute for this identity. If identity is unresolved, retain the inventory metadata and unresolved source record; never invent a digest.

Page counts are positive integers. Redaction percentages are bounded 0–100, separately from redaction categories; “partial” does not imply a percentage. Dates retain their precision. Historical markings do not establish present classification. Capture metadata remains a declaration, and GPS altitude retains its unit or null when unknown.

Preserve digital custody

Each custody action identifies the exact artifact. Its predecessor is another action on that artifact, a declared beginning, or an explicit unknown gap. Array order is not chronology. Predecessors and derivations must be acyclic; unambiguous sender/recipient and comparable time declarations must agree across handoffs.

Keep derived files distinct from their originals. Additional SHA-256, SHA-512, SHA-1 and MD5 declarations retain both algorithm and scope. An MD5 for an unavailable original does not verify the current copy. Physical sample custody belongs to the material workflow.

Cite and review the exact copy

An editionCitation names the exact entity snapshot, edition ID, artifact and page, time range or JSON pointer. Known single page counts bound page citations. Unknown or conflicting counts do not produce an invented bound.

Source statements may preserve reportedArtifactReview; assessed claims use artifactReview with explicit inputs, reviewer, method/version, evaluation time and rationale. Reviews can retain credentials, organization, historical review date, findings, report reference, qualitative confidence and manipulation declarations. Each independent review remains its own claim. A reported “authentic” finding is an attributed statement; parsing it does not execute or endorse the review.

Run the archival evaluator

Extract the worked example, then run npm install and npm start with Node.js 22. It contains two fictional editions, their declared history and exact snapshot references. No source artifact bytes are included.

From that folder, the evaluator can also be called directly:

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

parseArchivalEntities and parseArchivalClaimHistory, from @disclosureos/records/experimental/v2, check structure and local semantics. evaluateArchivalClaimHistory additionally checks supplied snapshot bytes, SHA-256, identities, scope and typed references. Supply referenced context or acquisition snapshots through the same documents map when present. Missing bytes leave external checks incomplete; mismatches fail.

Explicit JSON Schema exports are @disclosureos/records/experimental/v2/entities/schema/0.2.0 and @disclosureos/records/experimental/v2/claims/schema/0.4.0. History 0.4.0 uses entities 0.2.0. Older explicit contracts remain available; mixed entity versions are not projected automatically.

Successful archival evaluation leaves source artifact integrity, scientific interpretation, profile applicability, time normalization and sensor fusion not_checked. It never fetches URLs or reads source artifacts. Matching declarations does not authenticate files, establish complete custody or certify a research profile. Public fields reject unknown properties but are not a privacy sanitizer: names, URLs and free text must already be approved for publication.

Check source provenance

The released-document profile below separately checks selected public sources, release citations and supplied source bytes. It uses its own history and selection contracts; do not pass the archival history 0.4.0 into this evaluator. Use the separate provenance example.

Select the sources to check

A document selection identifies the exact claim history and observation, then names a nonempty list of unique source references. Each entry includes release:

• Known: releasedBy and reference identify the declared releasing authority/publisher and citation.
• Unknown: a reason preserves missing context, but does not satisfy the release-citation requirement.

This particular profile requires selected sources to declare kind: document and access: public. A restricted or withheld document can remain a valid source in the wider standard; do not change its access label to make this checklist pass. Public access does not establish permission to redistribute it.

Run the release-provenance evaluator

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

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

The selection schema is exported at @disclosureos/schema/experimental/v2/released-documents/schema, with identifier urn:disclosureos:experimental:released-document-selection:0.1.0.

Preserve passage provenance

Current source statements and observation value assertions directly citing selected sources form the extraction scope. Each supplied direct extraction requires a locator and extractor identity. Speaker/author attribution is recommended for this document profile; it is required in the testimony profile.

No direct extraction yields not_applicable for that requirement. It does not establish exhaustive extraction. Locators preserve page, time-range or JSON-pointer references, but the evaluator does not inspect their contents or bounds. Derived OCR, translations and transitive products need their own provenance.

Read the result

A selected public document, release citation, SHA-256 digest and matching nonempty local bytes are required. Titles and URIs are recommended citation aids. Missing required metadata or known byte mismatches fail; unavailable bytes leave an otherwise eligible profile unchecked. Incomplete unselected sources do not penalize selected documents.

external: passed means supplied source bytes match their declared digests. Release authenticity, redistribution rights, locator contents, extraction accuracy, assessment support and scientific eligibility remain not_checked. A claimed conclusion in the document is not established by its file hash.

Use claim histories to retain attributed statements and assessments, and testimony for separately represented accounts.