Jira progress: loading…

USO-PS

USO Runtime Provenance System

Universal Signal Ontology — Type, Instance, and Lineage Tracking

1. Purpose

The Universal Signal Ontology (USO) is ZAYAZ’s semantic and runtime provenance system.

It provides two distinct but connected layers:

1. USO Type Defines the semantic class of a signal, such as:

uso_type:emissions.calc_engine.estimate.spend_based.scope3.category1@v1

2. USO Instance Defines a specific runtime or registry-time signal birth event, identified by an immutable uso_id.

The USO system ensures that every signal can be traced across:

what it is → CSI
who produced it → CMI
why it exists semantically → USO Type
which specific instance it is → USO Instance
how it was validated → TrustGate Telemetry

---

2. Lifecycle Overview

Signal Lineage Lifecycle

Signal Definition
      ↓
CSI Binding
      ↓
CMI Assignment
      ↓
USO Type Binding
      ↓
USO Instance Minting
      ↓
TrustGate Telemetry
      ↓
Publication / Audit / Reporting

Step-by-step

1. Signal Definition A signal is published into zar.signal_registry.
2. CSI Binding The signal is assigned or linked to a canonical CSI in zar.signal_csi_binding.
3. CMI Assignment The producing or publishing artifact is identified through cmid.
4. USO Type Binding The signal is linked to an approved semantic class in zar.signal_uso_type_binding.
5. USO Instance Minting A runtime lineage record is created in zar.uso_instance.
6. TrustGate Telemetry Validation, trust scores, policy results, and assurance signals are recorded in zar.trustgate_telemetry_event.

---

3. Database Representation

3.1. USO Type

Stored in:

zar.uso_type_registry

The USO Type defines semantic meaning using the six-level model:

Level	Meaning	Example
0	Domain	emissions
1	Origin	calc_engine
2	Signal class	estimate
3	Method / subtype	spend_based
4	Scope / category	scope3
5	Sub-category / detail	category1

Example:

uso_type:emissions.calc_engine.estimate.spend_based.scope3.category1@v1

---

3.2. USO Type Binding

Stored in:

zar.signal_uso_type_binding

This table links a canonical signal to its approved USO Type.

signal_id → uso_type_id → uso_type

This is a definition-time semantic binding.

---

3.3. USO Instance

Stored in:

zar.uso_instance

This table represents a specific signal birth or lineage instance.

Key fields:

Field	Description
uso_instance_id	Surrogate database ID
uso_id	Immutable runtime lineage identifier
signal_registry_id	Linked canonical signal registry row
signal_id	Canonical signal ID
uso_type_id	Linked semantic USO Type
uso_type	Denormalized USO Type string
csi	Canonical Signal Identifier
cmi	Computation / artifact identity
primary_origin_cmi	Original producing artifact
primary_origin_component_id	Original component
origin_chain	Ordered list of CMIs that handled the signal
origin_chain_codes	Compact lineage codes
trustgate_telemetry_id	Latest TrustGate telemetry reference
trustgate_event_id	Latest TrustGate event reference
execution_context	Runtime or registry-time context
input_hash / output_hash	Optional integrity hashes
born_at	Signal birth timestamp
first_seen_at / last_seen_at	Runtime lineage timestamps

---

4. Lineage Operations

Operation	Trigger	Effect
Create	Signal publish or runtime signal birth	Creates new uso_id and initializes lineage
Extend	Downstream engine processes signal	Appends CMI / ZAR code to origin_chain
Validate	TrustGate evaluates signal	Creates telemetry event and updates latest TrustGate reference
Fork	Signal creates child outputs	Future child USO instances reference parent context
Aggregate	Multiple signals are combined	Future aggregate USO instance references source instances
Seal	Publication / disclosure / archive	Future final hash and closure metadata applied

---

5. TrustGate Integration

TrustGate telemetry is stored in:

zar.trustgate_telemetry_event

It records:

• validation stage
• decision
• trust score
• policy result
• validator result
• evidence payload
• execution context

The enriched audit surface is:

zar.v_trustgate_telemetry_enriched

This view joins TrustGate telemetry with:

• signal_registry
• uso_instance
• uso_type_registry
• CSI / CMI context

TrustGate Telemetry (audit + validation)

trustgate-telemetry.jsonGitHub ↗

{
  "trustgate_event_id": "...",
  "uso_id": "0196F...",
  "signal_id": "sssr:compute_method_registry.created_at",
  "trustgate_stage": "validation",
  "trustgate_decision": "pass",
  "trustgate_status": "observed",
  "trust_score": 0.98,
  "policy_id": "...",
  "policy_result": "pass",
  "validator_id": "...",
  "validator_result": "pass",
  "telemetry_payload": {
    "input_hash": "...",
    "output_hash": "..."
  },
  "evidence_payload": {
    "evidence_type": "required_fields_check"
  }
}

---

6. Example (Lineage JSON Excerpt)

example-lineage.jsonGitHub ↗

{
  "uso_id": "0196F...",
  "signal_id": "sssr:compute_method_registry.created_at",
  "uso_type": "uso_type:governance.audit_workflow.assurance.direct_measurement.total.total@v1",
  "csi": "COMP.AIIL_CON.SIGNAL.CREATED_AT.V1",
  "cmi": "CMID-ZYZ-000001",
  "primary_origin_cmi": "CMID-ZYZ-000001",
  "origin_chain": ["CMID-ZYZ-000001"],
  "origin_chain_codes": [],
  "input_hash": "...",
  "output_hash": "...",
  "execution_context": {
    "source": "signal_proposal_publish",
    "source_table": "compute_method_registry",
    "column_reference": "created_at"
  },
  "born_at": "2026-04-28T09:07:16Z",
  "trustgate_event_id": "tg_evt_1777367236168_5p0nadnl"
}

---

7. Design Principles

1. USO Type and USO Instance are separate Semantic class and runtime identity must not be mixed.
2. CSI defines what the signal is structurally CSI is the canonical signal identity.
3. CMI defines who produced or processed the signal CMI anchors the computational/artifact origin.
4. USO Type defines why the signal exists semantically It links the signal to ESG / ISO / IPCC / PEF meaning.
5. USO Instance defines which signal occurrence exists It is the lineage passport for a specific signal birth event.
6. TrustGate records validation and assurance Trust decisions are captured as telemetry, not hidden inside the signal record.
7. Lineage must be append-friendly Future processing steps extend lineage without destroying prior history.

---

8. Lifecycle Diagram

---

9. Execution Audit Event Layer

Purpose:

zar.execution_audit_event stores reproducibility-grade execution evidence for engines, validators, transformations, and TrustGate decisions. It is used when ZAYAZ must prove not only that an event happened, but how it can be reconstructed.

zar.execution_audit_event is the optional reproducibility layer beneath TrustGate telemetry.

Where zar.uso_instance identifies the signal occurrence, and zar.trustgate_telemetry_event records validation and trust outcomes, zar.execution_audit_event stores the technical evidence required to replay or verify how an engine, validator, or policy decision was produced.

This table is intended for high-assurance workflows, including:

• engine replay
• audit reconstruction
• validator reproducibility
• evidence preservation
• regulatory and third-party assurance

It should not replace USO Instance or TrustGate telemetry. It complements them.

execution_audit_event.sqlGitHub ↗

CREATE TABLE IF NOT EXISTS zar.execution_audit_event (
  execution_audit_event_id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,

  execution_event_id text NOT NULL UNIQUE,

  uso_instance_id bigint REFERENCES zar.uso_instance(uso_instance_id),
  uso_id text,
  signal_registry_id bigint,
  signal_id text,

  trustgate_telemetry_id bigint REFERENCES zar.trustgate_telemetry_event(trustgate_telemetry_id),
  trustgate_event_id text,

  cmi text,
  csi text,
  uso_type_id bigint REFERENCES zar.uso_type_registry(uso_type_id),
  uso_type text,

  engine_component_id text,
  engine_cmi text,
  engine_build_sha text,
  engine_version text,

  schema_cmi text,
  ruleset_cmi text,
  policy_id text,
  validator_id text,

  operation_type text NOT NULL,
  execution_status text NOT NULL DEFAULT 'completed',

  input_hash text,
  output_hash text,
  payload_hash text,

  input_ref jsonb,
  output_ref jsonb,
  full_payload_snapshot jsonb,
  replay_context jsonb,
  environment_context jsonb,

  started_at timestamptz,
  completed_at timestamptz,
  observed_at timestamptz NOT NULL DEFAULT now(),

  status text NOT NULL DEFAULT 'active',
  version text NOT NULL DEFAULT '1_0_0',
  created_at timestamptz NOT NULL DEFAULT now(),
  updated_at timestamptz NOT NULL DEFAULT now(),
  updated_by text
);

CREATE INDEX IF NOT EXISTS idx_execution_audit_uso_id
ON zar.execution_audit_event(uso_id);

CREATE INDEX IF NOT EXISTS idx_execution_audit_signal_id
ON zar.execution_audit_event(signal_id);

CREATE INDEX IF NOT EXISTS idx_execution_audit_cmi
ON zar.execution_audit_event(cmi);

CREATE INDEX IF NOT EXISTS idx_execution_audit_trustgate_event_id
ON zar.execution_audit_event(trustgate_event_id);

CREATE INDEX IF NOT EXISTS idx_execution_audit_observed_at
ON zar.execution_audit_event(observed_at);

USO Instance = identity + lineage
TrustGate Telemetry = validation + trust outcome
Execution Audit Event = replay + reproducibility evidence

---

10. Final Principle

The USO system turns every ZAYAZ signal from a simple data point into a traceable semantic event.

CSI says what it is.
CMI says who produced it.
USO Type says what it means.
USO Instance says which occurrence it is.
TrustGate says whether it can be trusted.

This is the runtime provenance foundation for ZAYAZ auditability, ESG assurance, and explainable sustainability intelligence.

---