Assessment and review

DisclosureOS keeps document checks, attributed assessments and numerical scoring separate. A result should identify what was supplied, which rules ran and what remains unchecked. The Scoring explorer demonstrates this distinction with fictional records and source files.

Availability: this guide describes the canonical source candidate used by the portal. Some APIs are available in the npm beta, but its 2.0.0-beta.3 release does not contain every change described here. For matching code and definitions, use the pinned checkout in the example source guide. npm publication remains on hold for the coordinated V2 release.

Read a check result

Read each result in the scope of its evaluator. The same status label can refer to different work in different profiles.

passed means the named check passed within that scope. failed means an attempted check found a problem. not_checked means the evaluator did not establish a result. Preserve these states; do not replace an unchecked result with a pass or a zero.

Read success together with the checks and explicit limits. For example, a history evaluator can return success: true after checking structure and references while leaving its profile unrun. A receipt can preserve a failed result. Neither case establishes that a scientific conclusion is correct.

The saved example checks cover three different records: specimen reviews, a material-to-field relationship and a calculation record. All three retain profile: not_checked. The packet also records scorePolicy: not_applied. Its matching file hashes and reproduced arithmetic do not supply an overall case grade.

Profiles and completion

A profile selects requirements for a particular task. Choose one because it matches the document and purpose, not because it produces a favorable result.

These functions are exported from @disclosureos/schema/experimental/v2. Use the input contract accepted by the selected function. In particular, the assessment-documentation and related completion paths use the original experimental claim-history 0.1.0 contract; they are not universal adapters for every later history type.

Documentation checklist states are satisfied, missing, failed, not_checked and not_applicable. The selected instrument-research checklist uses the first four. Counts refer to requirement groups, not independent observations, percentages of scientific certainty or weighted points. A requirement that is not applicable should not count as missing.

A checklist can tell a developer to obtain the source bytes, document the measurement frame or supply a review report. It cannot create that information. Retain rejected and inconclusive reviews, unknown timing and unavailable calibration. Do not adjust a declaration merely to make a check pass.

The research result still leaves scientific eligibility, calibration adequacy, timing-model adequacy and reviewer authenticity unchecked. A declared accepted review is an input, not an independent validation of that review. See the instrument example for the difference between a matching measurement binding and completed scientific review.

The document, testimony and physical-sample profiles have different requirements. In those profiles, external: passed can mean that the selected source bytes match their declared digests. Release authenticity, speaker authenticity and physical custody remain separate questions. The provenance examples retain those limits alongside their passing checks.

Assessment summaries

summarizeClaimHistory is exported from @disclosureos/scoring/experimental/v2. It accepts the original claim_history schema version 0.1.0, whose subjects are an observation or a measurement. It does not summarize the later archival, laboratory, contextual or case-history contracts. Validate those documents with their corresponding evaluators and retain their attributed results.

The summary groups current declarations by topic and subject. It keeps source assertions, unassessed entries and assessed outcomes separate, retains superseded references and collapses exact duplicate declarations. When comparing duplicates, it excludes the claim ID, recording time and supersession links; assessment input order is also normalized. It does not treat repeated copies as additional votes or merge differently attributed reviews.

import { summarizeClaimHistory } from "@disclosureos/scoring/experimental/v2";

// The caller supplies a claim_history document with schemaVersion "0.1.0".
export function inspectDeclaredAssessments(history: unknown) {
  const result = summarizeClaimHistory(history);
  if (!result.success) {
    return { checks: result.checks, issues: result.issues };
  }

  return {
    policy: result.policy,
    groups: result.groups,
    sharedInputs: result.sharedInputs,
    supersededClaimRefs: result.supersededClaimRefs,
    scientificEligibility: result.scientificEligibility,
  };
}

declaredOutcomes lists the outcomes present in a group. multiple_declared_outcomes describes differing declarations; it does not decide which is correct. Shared input references and equal declared artifact hashes indicate possible dependence. They do not establish statistical independence or verify the source bytes. The summary leaves scientific eligibility, artifact integrity, vocabulary membership, statistical independence and reproducibility unchecked.

Observable terms describe reported or investigated characteristics. The Origin Classification System organizes possible explanations. Use a shared vocabulary binding to identify the exact catalog revision and term separately from the subject and supporting inputs. A valid binding establishes identity and membership, not the assessment's scientific support. See Claims and Origins.

Receipts and reproduction

A receipt preserves the request and computed result of a fixed, versioned workflow. The available wrappers serve different purposes:

Each workflow pins its declared input files and dependency artifacts using SHA-256 and byte length. It records built-in rule identities and hashes exact serialized request and output strings. These wrappers run fixed package evaluators; they do not accept arbitrary executable policies or caller-supplied passing results. They do not fetch source URLs or execute supplied implementation artifacts.

Preserve the manifest, exact input bytes, dependency artifacts, rule versions, requestJson, outputJson and their hashes. Hashing the receipt strings checks agreement with those saved strings. Re-running the matching workflow with the retained inputs checks reproduction. These are distinct operations. A failed profile can be faithfully reproduced; a successful replay is not a passing profile.

Receipts are unsigned. They do not authenticate an author, establish a trusted timestamp or attest that a supplied implementation or environment artifact was the one previously executed. A vocabulary file pin does not by itself check the meaning or membership of its terms. Read the wrapper and nested profile results together: a wrapper's external: passed may only establish that its declared files match their pins, while the nested profile still fails a source check.

The showcase's saved verification report is an application report over named canonical evaluator results and a separate arithmetic check. Do not label it as one of these receipt contracts or infer that the wrapper workflows ran. Its original rule scope and unchecked fields remain visible in the verification workspace.

Numerical scores

There is no universal V2 case score. The current packages retain numerical utilities with narrower meanings:

• getPopulationCoverage counts populated paths in the legacy record schema. It does not validate scientific quality, determine which fields apply or run a research profile. getCompleteness is an older name for the same counter.
• The source candidate's score function accepts origin-only inputs in the legacy observation shape. It rejects any nonempty descriptive observable-assessment list. Descriptive support such as “reported” or “measured” is not an anomaly-strength input. Rejection is not a zero score or a finding that a characteristic is absent.
• The origin calculation uses attributed origin confidence, the configured prosaic prefixes, relative weights and optional evaluator weighting. Its range describes the spread of supplied claims under that method; it is not a statistical confidence interval or a probability that an origin is true.
• calibrationTrust supplies an optional weighting hook based on declared calibration status resolved through sensor references. It does not review calibration adequacy. The hook changes the point estimate, not the reported range or contestedness.

The retained default weights still include technology and biologics components, although the candidate scorer leaves those contributions at zero. Consequently an origin-only result is not automatically normalized to the full output range. Preserve the exact configuration and scoringVersion; do not present the number as a calibrated measure of anomaly strength.

No replacement numerical method for descriptive observable assessments has been established. Applications can exchange their own results through the optional provider-scoring format below. A provider's policy must state its purpose, applicable inputs, method, scale, missing-data treatment and limits. Conforming to the exchange format does not make that policy an endorsed DisclosureOS method.

Provider scores

The source candidate adds two optional documents in @disclosureos/scoring/experimental/v2:

A numeric policy declares its bounds, unit and direction. Optional grade bands must cover the scale in order without gaps or overlaps. Lower boundaries are inclusive; upper boundaries are exclusive except for the last maximum. An ordinal policy defines stable level identifiers and labels with an explicit ordering direction. Neither establishes a universal case grade.

validateProviderScorePolicy checks structural and semantic rules. evaluateProviderScore accepts the result plus supplied policyBytes, inputFiles, derivationFiles and methodFiles. It checks the declarations and fingerprints, verifies scale membership and any declared grade, and returns separate structural, semantic and external statuses. The standalone JSON Schemas cover structure; use the semantic evaluator for cross-field rules and supplied-file checks.

These functions do not fetch URLs, execute supplied code, recompute arbitrary policies, authenticate a provider, resolve the subject against its records or establish scientific validity. A successful check can preserve a valid unavailable result. Conversely, a provider-declared number is not ready for comparison when its required files cannot be verified.

The result keeps the common source material in inputs and the provider's own review worksheets in derivation. Reviewers can therefore disagree about the same material without pretending that their different worksheets are different source observations. subject identifies what is being evaluated; it is separate from both file lists.

Comparing provider results

compareProviderScores(left, right, { left: options, right: options }) checks both results and returns eligibleForComparison with explicit reasons when the pair is ineligible. Eligibility requires scored outcomes, the same exact policy, subject, input scope and common source files, with no declared missing inputs. Each provider's derivation is checked separately and can differ.

This is eligibility for inspecting declared scores under shared rules. It does not establish scientific equivalence, reviewer independence, a winner, an average or a combined confidence. A common 0–100 scale is insufficient: documentation coverage and follow-up priority measure different things. Ranking a collection additionally requires a declared population, inclusion rules and treatment of ties; this exchange format does not supply a universal ranking algorithm.

Reproduce the teaching example

The provider comparison on the Scoring page uses fictional review teams and the retained material record from the DisclosureOS example case. Both teams inspect the same seven files. They award different credit for the detail of the laboratory method, producing 85 and 70 under the same documentation-review policy. A separate result of 75 uses a follow-up-priority policy and is not eligible for a direct comparison. An unfinished worksheet produces no score.

The documentation-review method allocates 25 points to source traceability, 25 to specimen identity, 30 to method detail and 20 to stated limits. A reviewer supplies a rating of 0, 0.5 or 1 for each criterion. The example sums each rating multiplied by its weight, without redistributing weights or replacing missing ratings with zero. These are authored judgments, not automatic classifications of source truth.

The portal checks the retained files with the canonical evaluator and independently repeats this example's fixed arithmetic before rendering. It does not execute a provider-supplied script. The retained example also includes a runnable calculation for developers:

• Example manifest
• Documentation-review policy
• Follow-up-priority policy
• First review worksheet and second review worksheet
• Calculation implementation

The canonical repository's examples/provider-scoring/verify.mjs verifies the complete example. Keep the manifest and exact method, worksheet and source bytes together. Reproducing the arithmetic does not independently justify the reviewers' decisions.

Levels, grades and rankings

The retained support-label definitions distinguish witness reports, supporting documentation, quantitative measurements, and peer-reviewed analysis with independent verification. not_indicated does not prove absence. These labels must not be converted automatically into anomaly strength, confidence in an origin, or a V2 claim outcome.

The fictional documentation policy uses its own A–D bands. The Disclosure Index application's existing A–F grades belong to that application's policy, not to this example or a universal V2 ladder. Identical letters across methods need not have identical meanings.

Source-file example

The Scoring page uses the retained fictional weather file, observation and source selections to demonstrate a bounded byte check. It narrows a copy of the selection document to the existing temperature-meter layout and its first temperature row, preserving the instrument partition and measurement reference, then calls evaluateProductSourceSelection with product-reference keys in its assets map.

The altered copy exists only for this demonstration; it does not overwrite the retained source or its digest. The same file can support separate products for the two weather instruments without turning them into independent files. A source-byte pass establishes neither physical calibration nor the truth of the synthetic measurements.

Start with the Scoring explorer for the public explanation, or build from the showcase to inspect and reproduce the full example.