ZIR
ZAYAZ Interface Registry Specification
1. Purpose
The ZAYAZ Interface Registry (ZIR) is the canonical registry of all interfaces within the ZAYAZ ecosystem.
ZIR provides the authoritative mapping between:
- Components
- Interfaces
- Schemas
- Contracts
- Rulesets
- Producers
- Consumers
- Workflow Tests
- Rollback Procedures
ZIR exists to support:
- Dependency analysis
- Impact analysis
- Blast radius calculation
- Workflow generation
- Agent routing
- Automated testing
- Governance auditing
2. Core Principle
Components are implementation units.
Interfaces are capability units.
ZIR tracks capabilities rather than implementations.
Example:
TG-CSI Component
├─ Trust Score Generation Interface
├─ Replay Validation Interface
└─ Federation Trust Interface
A single component may expose many interfaces.
3. Interface Definition
Every interface SHALL have a globally unique identifier.
Example:
interface_id: TG-CSI.trust-score-generation.v1
Pattern:
<ComponentID>.<capability>.<version>
Example:
TG-CSI.trust-score-generation.v1
TG-CSI.replay-validation.v1
DAL.anchor-publishing.v2
Interfaces SHALL remain stable even when Jira tickets change.
4. Registry Structure
Example ZIR record:
interface_id: TG-CSI.trust-score-generation.v1
component:
component_id: TG-CSI
semantic_id: zar.component.trustgate.csi.catalog
status: active
version: 1.0.0
purpose:
Generate trust scores from assurance signals
owners:
- cto@viroway.com
jira_refs:
- ZYZ-123
schemas:
consumes:
- schema.trust_signals@1.0.0
- schema.lineage_events@1.0.0
produces:
- schema.trust_scores@1.0.0
- schema.trust_attestations@1.0.0
contracts:
consumes:
- contract.assurance.signals.v1
produces:
- contract.trustgate.trust-scores.v1
rulesets:
- ruleset.trustgate.csi.trust-score-calculation@1.0.0
- ruleset.trustgate.csi.replay-validation@1.0.0
workflow_profiles:
- trust-score-generation
- replay-validation
rollback_profiles:
- standard-component-rollback
criticality:
level: high
compliance_relevant: true
assurance_relevant: true
public_output: false
5. Producer / Consumer Resolution
ZIR SHALL automatically resolve dependencies.
Example:
TG-CSI
produces trust_scores
AII
consumes trust_scores
ZIR derives:
producer:
TG-CSI
consumers:
- AII
Consumers SHALL NOT be manually maintained.
Consumers are graph-derived.
6. Relationship Model
ZIR relationships:
Component
↓
Interface
↓
Schema
↓
Contract
↓
Ruleset
↓
Workflow
Graph representation:
[TG-CSI]
↓
[trust-score-generation]
↓
[schema.trust_scores]
↓
[contract.trust_scores]
↓
[AII]
7. Interface Lifecycle
Allowed states:
status:
- draft
- review
- active
- deprecated
- superseded
- retired
Rules:
draft
↓
review
↓
active
↓
deprecated
↓
retired
Superseded interfaces reference successors.
Example:
superseded_by:
TG-CSI.trust-score-generation.v2
8. Versioning
Interface versioning follows semantic versioning.
Example:
TG-CSI.trust-score-generation.v1
TG-CSI.trust-score-generation.v2
Rules:
Major:
Breaking contract changes
Breaking schema changes
Breaking workflow changes
Minor:
Backward-compatible additions
Patch:
Documentation
Metadata
Governance updates
9. Workflow Integration
Every interface SHALL be linked to workflow profiles.
Example:
workflow_profiles:
- trust-score-generation
workflow_tests:
- test.trust-score-generation.success
- test.trust-score-generation.failure
- test.trust-score-generation.replay
Hecate uses these to generate test plans.
10. Blast Radius Integration
Each interface contributes to blast-radius calculations.
Example factors:
blast_radius_factors:
consumer_count:
contract_count:
ruleset_count:
compliance_relevance:
assurance_relevance:
public_output:
Derived automatically.
11. Rollback Integration
Interfaces SHALL reference rollback profiles.
Example:
rollback_profiles:
- standard-component-rollback
- replay-validation
Rollback plans are generated from profile composition.
12. Hecate Integration
Hecate SHALL query ZIR during Need creation.
Pipeline:
Need
↓
Component
↓
ZIR Lookup
↓
Dependency Graph
↓
Impact Analysis
↓
Workflow Tests
↓
Rollback Plan
↓
Jira Ticket
13. Agentic Development Integration
Agents SHALL NOT reason directly from component descriptions.
Agents receive:
component:
interface:
schemas:
contracts:
rulesets:
workflow_tests:
rollback_profiles:
blast_radius:
Generated from ZIR.
This ensures agents operate on governed architecture rather than free-text documentation.
14. Future Extensions
Planned additions:
ZIR Event Registry Integration
ZIR Workflow Registry Integration
ZIR GraphQL API
ZIR Impact Simulation Engine
ZIR Dependency Replay Engine
ZIR Agent Context Service