JudgmentEnvelope<T>

The universal value-with-metadata container that carries epistemic discipline across every wiring boundary in the platform.

What it is

JudgmentEnvelope<T> is the canonical container that wraps every value crossing a phase or subsystem boundary. Three specialisations (EnrichedEvidence, EvidencedScalar<T>, MetaDecisionRecord) are projections of one base shape — not parallel inventions.

Architectural intent:

  • Every value crossing a boundary travels with its substrate metadata attached, so ICD 203 § B (source quality, uncertainty, alternatives, change reason, attribution) becomes a property of the data shape rather than something downstream consumers must reconstruct from sidecar tables.
  • Field naming aligns with the nine substrate primitives so envelopes serialise into existing interchange formats without a translation layer.
  • Security metadata is first-class: trust level, sensitivity, origin, sanitization status, permission scope.

Minimal example

import {
  mintEnvelope,
  recordTransform,
  requireChangeReason,
} from '@luu/judgment-substrate';

const env = mintEnvelope(
  { score: 0.78, label: 'plausible' },
  'rapidh_scorer',
  'trace-abc-123',
  {
    trust: {
      level: 'verified',
      origin: 'internal',
      sensitivity: 'internal',
      sanitized: true,
    },
  },
);

// Append a transform when the envelope passes through another subsystem
const updated = recordTransform(
  env,
  'filtering_pipeline',
  'rapidh-rerank',
);

// TS-enforced invariant: every mutation must record a reason
const withReason = requireChangeReason(updated);
// → throws if updated.changeReason is missing

Shape

FieldRequiredPurpose
valueyesThe wrapped value
traceIdyesEnd-to-end trace ID, threaded through every subsystem
provenanceyesLineage chain, appended by every transformer
generatedAtyesISO 8601 mint timestamp
generatedByyesSubsystem that minted the envelope (typed enum)
evidence—Evidence supporting the value
sources—Source assessments
attribution—Claim/evidence/source bindings
uncertainty—Calibrated probability or distribution
alternatives—Competing hypotheses considered
informationGaps—Known unknowns acknowledged
decisionFrame—The question this envelope contributes to
changeReason—Why this value differs from the prior, if it does
trust—Level / origin / sensitivity / sanitized / permissionScope
validationState—Substrate-coverage gate result

Three named projections

  • EnrichedEvidence<NormalizedEvidenceValue> — for ingestion / signal pipeline
  • EvidencedScalar<T> — for scoring outputs
  • MetaDecisionRecord<TParam> — for adaptation / learning mutations

Required-field coercions

Three TS-enforced invariants raise at runtime when the envelope is missing required metadata:

  • requireChangeReason(env) — for any mutation
  • requireAlternatives(env) — for assessments that should have been red-teamed
  • requireTrust(env) — for any envelope that crosses a security boundary

A2A / MCP transport

Internal envelopes are natively transportable to external agents via CloudEvents 1.0 — no parallel transit format.

import { toA2aArtifact, toCloudEvent } from '@luu/judgment-substrate';

// Lossless serializer to a transport-neutral artifact
const artifact = toA2aArtifact(envelope);
// → { $schema: 'luu.judgment-envelope.v1', value, metadata, provenance }

// Wrap in CloudEvents 1.0 structured-mode envelope
const event = toCloudEvent(envelope, {
  source: '/api/v1/snapshot',
});
// → POST to subscribers, S3 archive, audit log, etc.

Coverage reporting

Every envelope can introspect its own substrate coverage — useful for ICD 203 ATS scoring and the wiring-retention harness:

import { reportCoverage } from '@luu/judgment-substrate';

const cov = reportCoverage(env);
// {
//   hasEvidence: true,
//   hasSources: true,
//   hasAttribution: true,
//   hasUncertainty: true,
//   hasAlternatives: false,
//   hasInformationGaps: false,
//   hasDecisionFrame: true,
//   hasChangeReason: true,
//   hasTrust: true,
//   coverageScore: 7,    // 0-9
//   provenanceDepth: 4,  // transforms applied
// }

Related