Jira progress: loading…

SGNL-FLOW

ZAYAZ Signal Lineage Flow (CSI → CMI → USO → TrustGate)

1. Purpose

This document defines the end-to-end lifecycle of a signal in ZAYAZ, from definition to runtime validation.

It explains how the system ensures:

• Semantic consistency (USO)
• Structural consistency (SSSR)
• Computational traceability (CMI)
• Auditability and assurance (TrustGate)

This flow is the core architecture of ZAYAZ.

---

2. High-Level Flow

Signal Definition (SSSR)
        ↓
CSI (Canonical Signal Identity)
        ↓
CMI (Producing / Processing Artifact)
        ↓
USO Type (Semantic Classification)
        ↓
USO Instance (Runtime Signal Birth)
        ↓
TrustGate Telemetry (Validation & Audit)

---

3. Stage 1 — Signal Definition (SSSR)

Source:

zar.signal_registry

A signal is first defined as a canonical data structure.

Field	Description
signal_id	Global identifier (e.g. sssr:compute_method_registry.created_at)
signal_name	Human-readable name
data_type	Storage type
signal_domain	Domain classification
signal_role	Semantic role

Key Principle

A signal is defined once and reused everywhere.

---

4. Stage 2 — CSI (Canonical Signal Identity)

Source:

zar.signal_csi_binding

CSI defines what type of signal this is structurally.

<module>.<component>.<kind>.<name>.v<maj>_<min>

Example:

comp.TAC.OUTPUT.CO2E.v1_0

Purpose

• Standardizes signal identity across engines
• Enables interoperability
• Drives routing and processing logic

---

5. Stage 3 — CMI (Computation / Micro-Engine Identity)

Source:

zar.signal_registry.cmid
zar.signal_component_binding

CMI defines who produced or processed the signal.

Example:

comp.TAC.Engine.1_1_0

Key Role

• Defines execution provenance
• Enables lineage tracking
• Supports audit trails

---

6. Stage 4 — USO Type (Semantic Classification)

Source:

zar.uso_type_registry

USO Type defines what the signal represents semantically.

uso_type:<domain>.<origin>.<class>.<method>.<scope>.<category>@v1

Example:

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

Structure (6 Levels)

Level	Meaning	Example
0	Domain	emissions
1	Origin	calc_engine
2	Signal Class	estimate
3	Method	spend_based
4	Scope	scope3
5	Category	category1

Key Principle

USO Type defines the **semantic meaning**, not the data structure.

---

7. Stage 5 — USO Instance (Signal Birth)

Source:

zar.uso_instance

A USO Instance is created every time a signal is produced.

USO Instance = runtime identity of a signal

Example

uso-instance-example.jsonGitHub ↗

{
  "uso_id": "01JBF0W8S9Q0R1S2T3U4V5W6X",
  "signal_id": "sssr:compute_method_registry.created_at",
  "uso_type": "uso_type:emissions.calc_engine.estimate.spend_based.scope3.category1@v1",
  "primary_origin_cmi": "comp.TAC.Engine.1_1_0",
  "origin_chain": ["comp.TAC.Engine.1_1_0"]
}

Key Fields

Field	Description
uso_id	Unique runtime identity (ULID)
uso_type_id	Semantic classification
csi	Signal type
cmi	Producing artifact
origin_chain	Execution lineage

Key Principle

USO Instance = “this specific occurrence of a signal”

---

8. Stage 6 — TrustGate Telemetry

Source:

zar.trustgate_telemetry_event

TrustGate captures validation, policy enforcement, and audit signals.

Example

trustgate-telemetry-example.jsonGitHub ↗

{
  "trustgate_stage": "validation",
  "trustgate_decision": "pass",
  "trust_score": 0.9825,
  "policy_id": "TG-POLICY-SIGNAL-VALIDATION-v1",
  "validator_id": "trustgate.signal.required_fields.v1"
}

Purpose

• Validate signals
• Enforce policies
• Provide audit trail
• Support ESG assurance

---

9. Enriched View (Full Context)

Source:

zar.v_trustgate_telemetry_enriched

This view joins:

• Signal
• CSI
• CMI
• USO Type
• USO Instance
• TrustGate telemetry

Result

A fully traceable ESG data point:

Signal → Type → Producer → Semantic Meaning → Instance → Validation

---

10. End-to-End Example

[Invoice Data]
   ↓
Signal: sssr:invoice.amount
   ↓
CSI: comp.invoice.INPUT.amount.v1_0
   ↓
CMI: MICE.Parser.Invoice.1_0_0
   ↓
USO Type: emissions.invoicecrawler.raw.scope3.category1@v1
   ↓
USO Instance: 01JBF0W8S9Q...
   ↓
TrustGate:
   - validation: pass
   - trust_score: 0.98

---

11. Core Design Principles

1. Separation of Concerns

Layer	Responsibility
CSI	Structure
CMI	Execution
USO Type	Semantics
USO Instance	Runtime identity
TrustGate	Validation

---

2. Immutability

• USO IDs never change
• CSI definitions are versioned
• CMI identities are fixed

---

3. Full Traceability

Every signal can be traced:

Where it came from
What it represents
Who processed it
How it was validated

---

4. ESG Compliance Alignment

The system supports:

• ESRS (E1–E5)
• GHG Protocol (Scope 1–3)
• IPCC categories
• PEF/OEF modeling

---

12. Why This Matters

This architecture enables:

• Audit-ready ESG reporting
• Explainable AI decisions
• Regulatory compliance (CSRD/ESRS)
• End-to-end data lineage

---

13. Summary

SSSR defines the signal
CSI defines the structure
CMI defines the producer
USO Type defines the meaning
USO Instance defines the occurrence
TrustGate validates the outcome

---

14. Sequence Diagram — Signal Publish Flow

sequenceDiagram
  participant UI as Signal Registry Authoring UI
  participant API as ZAYAZ Admin API
  participant SPR as zar.signal_proposal_results
  participant SR as zar.signal_registry
  participant CSI as zar.signal_csi_binding
  participant USOT as zar.signal_uso_type_binding
  participant USOI as zar.uso_instance

  UI->>API: POST /admin/signal-registry/proposals/publish
  API->>SPR: Load approved signal proposal
  API->>SR: Insert/update canonical signal
  SR-->>API: signal_registry_id
  API->>SR: Write final CMID
  API->>CSI: Insert CSI binding if approved CSI exists
  API->>USOT: Bind signal to USO Type
  API->>USOI: Mint USO Instance / uso_id
  API->>SPR: Mark proposal accepted + published
  API-->>UI: Publish result with signal IDs + uso_id

---

15. Sequence Diagram — CSI Proposal Review Flow

sequenceDiagram
  participant UI as CSI Proposal Review UI
  participant API as ZAYAZ Admin API
  participant SPR as zar.signal_proposal_results
  participant CPR as zar.csi_proposal_results
  participant SCB as zar.signal_csi_binding

  UI->>API: POST /admin/csi/proposals/generate-missing
  API->>SPR: Find signal proposals without CSI proposals
  API->>CPR: Insert generated CSI proposals
  API-->>UI: generated_count

  UI->>API: GET /admin/csi/proposals/list
  API->>CPR: Load CSI proposal queue
  API-->>UI: CSI proposal rows

  UI->>API: POST /admin/csi/proposals/publish
  API->>CPR: Load reviewed CSI proposal
  API->>SCB: Insert/update approved CSI binding
  API->>CPR: Mark approved + published
  API-->>UI: Publish result

---

16. Sequence Diagram — TrustGate Telemetry Ingestion

sequenceDiagram
  participant TG as TrustGate / Validator
  participant API as ZAYAZ Admin API
  participant UI as zar.uso_instance
  participant SR as zar.signal_registry
  participant TGE as zar.trustgate_telemetry_event
  participant VIEW as zar.v_trustgate_telemetry_enriched

  TG->>API: POST /admin/trustgate/telemetry/ingest
  API->>UI: Resolve uso_instance by uso_id / uso_instance_id / signal_id
  API->>SR: Resolve canonical signal
  API->>TGE: Insert telemetry event
  API->>UI: Update latest TrustGate event reference
  API-->>TG: trustgate_telemetry_id + trustgate_event_id
  VIEW-->>TG: Enriched audit context available

---

17. Sequence Diagram — Full Lineage Chain

flowchart LR
  A[Signal Proposal] --> B[Signal Registry]
  B --> C[CSI Binding]
  B --> D[CMI / Component Binding]
  B --> E[USO Type Binding]
  E --> F[USO Instance]
  F --> G[TrustGate Telemetry]
  G --> H[Audit / Assurance / Reporting]

  C -. defines what .-> F
  D -. defines who .-> F
  E -. defines why .-> F
  F -. defines which instance .-> G

---

18. API Example — Publish Signal Proposal

curl -X POST \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  https://zayaz-search-api.fly.dev/admin/signal-registry/proposals/publish \
  -d '{
    "proposals": [
      {
        "signal_proposal_id": 123,
        "overrides": {
          "status": "draft",
          "version": "1_0_0"
        }
      }
    ],
    "updated_by": "cto@viroway.com"
  }'

Expected response shape:

publish-signal-proposal-response.jsonGitHub ↗

{
  "ok": true,
  "summary": {
    "published": 1,
    "failed": 0
  },
  "results": [
    {
      "signal_proposal_id": 123,
      "status": "ok",
      "published_to_signal_registry_id": 456,
      "published_to_signal_binding_registry_id": 789,
      "published_to_signal_csi_binding_id": 12,
      "published_to_signal_uso_binding_id": 34,
      "published_to_uso_instance_id": 56,
      "uso_id": "0196F..."
    }
  ]
}

---

19. API Example — Generate Missing CSI Proposals

curl -X POST \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  https://zayaz-search-api.fly.dev/admin/csi/proposals/generate-missing \
  -d '{}'

Expected response shape:

generate-missing-csi-proposals-response.jsonGitHub ↗

{
  "ok": true,
  "generated_count": 54,
  "signals": [
    {
      "signal_proposal_id": 1,
      "signal_id": "sssr:compute_method_registry.created_at",
      "csi": "COMP.AIIL_CON.SIGNAL.CREATED_AT.V1"
    }
  ]
}

---

20. API Example — List CSI Proposals

curl -X GET \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  https://zayaz-search-api.fly.dev/admin/csi/proposals/list

Expected response shape:

list-csi-proposals-response.jsonGitHub ↗

{
  "ok": true,
  "count": 54,
  "rows": [
    {
      "csi_proposal_id": 1,
      "signal_proposal_id": 1,
      "signal_id": "sssr:compute_method_registry.created_at",
      "csi_kind": "SIGNAL",
      "csi": "COMP.AIIL_CON.SIGNAL.CREATED_AT.V1",
      "review_status": "pending"
    }
  ]
}

---

21. API Example — Publish CSI Proposal

curl -X POST \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  https://zayaz-search-api.fly.dev/admin/csi/proposals/publish \
  -d '{
    "proposals": [
      {
        "csi_proposal_id": 1,
        "overrides": {
          "csi_kind": "SIGNAL",
          "status": "draft",
          "version": "1_0_0"
        }
      }
    ],
    "updated_by": "cto@viroway.com"
  }'

---

22. API Example — Ingest TrustGate Telemetry

curl -X POST \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  https://zayaz-search-api.fly.dev/admin/trustgate/telemetry/ingest \
  -d '{
    "signal_id": "sssr:compute_method_registry.created_at",
    "trustgate_stage": "validation",
    "trustgate_decision": "pass",
    "trustgate_status": "observed",
    "trust_score": 0.9825,
    "policy_id": "TG-POLICY-SIGNAL-VALIDATION-v1",
    "policy_result": "pass",
    "validator_id": "trustgate.signal.required_fields.v1",
    "validator_result": "pass",
    "telemetry_payload": {
      "source": "manual_test"
    },
    "updated_by": "cto@viroway.com"
  }'

Expected response shape:

ingest-trustgate-telemetry-response.jsonGitHub ↗

{
  "ok": true,
  "trustgate_telemetry_id": 1,
  "trustgate_event_id": "tg_evt_1777367236168_5p0nadnl",
  "uso_instance_id": 56,
  "uso_id": "0196F..."
}

---

23. SQL Example — View Enriched TrustGate Telemetry

example-enriched-trustgate-telemetry.sqlGitHub ↗

SELECT
  trustgate_telemetry_id,
  trustgate_event_id,
  signal_id,
  signal_name,
  uso_id,
  uso_type,
  uso_label,
  csi,
  cmi,
  trustgate_stage,
  trustgate_decision,
  trust_score,
  observed_at
FROM zar.v_trustgate_telemetry_enriched
ORDER BY observed_at DESC
LIMIT 20;

---

23. SQL Example — Inspect Complete Signal Lineage

example-inspect-complete-signal-lineage.sqlGitHub ↗

SELECT
  sr.signal_registry_id,
  sr.signal_id,
  sr.signal_name,
  sr.cmid,
  csi.csi,
  uso.uso_type,
  ui.uso_id,
  ui.origin_chain,
  ui.origin_chain_codes,
  t.trustgate_event_id,
  t.trustgate_decision,
  t.trust_score
FROM zar.signal_registry sr
LEFT JOIN zar.signal_csi_binding csi
  ON csi.signal_id = sr.signal_id
LEFT JOIN zar.signal_uso_type_binding uso
  ON uso.signal_id = sr.signal_id
LEFT JOIN zar.uso_instance ui
  ON ui.signal_id = sr.signal_id
LEFT JOIN zar.trustgate_telemetry_event t
  ON t.uso_instance_id = ui.uso_instance_id
WHERE sr.signal_id = 'sssr:compute_method_registry.created_at'
ORDER BY ui.created_at DESC, t.observed_at DESC;

---

24. Developer Note

The Docusaurus manual describe architecture and usage, while the future AWS ZAR Admin Platform will provide operational management for:

• USO Type vocabulary
• USO Type approvals
• signal proposal review
• CSI proposal review
• TrustGate telemetry inspection
• lineage graph exploration
• integrity alerts

Docusaurus is the specification surface. AWS Admin is the operational control surface.

API Security

All admin endpoints require: Authorization: Bearer YOUR_ADMIN_TOKEN

Runtime vs Registry-Time Lineage

Registry-time publishing creates the first canonical USO Instance for the signal definition.

Runtime engines may later mint additional USO Instances for real executions, calculations, validations, or TrustGate decisions.

Registry-time:
Signal definition → USO Instance

Runtime:
Engine execution → USO Instance → TrustGate Telemetry

---