ZCT
ZAYAZ Contract Taxonomy
1. Purpose
The ZAYAZ Contract Taxonomy defines the canonical contract types used to govern interoperability between ZAYAZ components, interfaces, schemas, rulesets, workflows, services, agents, and external integrations.
A contract is a versioned interoperability promise.
It defines what one system element guarantees to another.
2. Core Principle
Components implement behavior.
Interfaces expose capabilities.
Contracts define promises.
Schemas define structure.
Rulesets define meaning.
Workflow tests validate behavior.
Component
→ Interface
→ Contract
→ Schema
→ Ruleset
→ Workflow Test
3. Contract Identity
Each contract SHALL have two identifiers:
zct_id: ZCT-000001
contract_id: contract.trustgate.csi.trust-scores.v1
zct_id is immutable.
contract_id is semantic and versioned.
Recommended pattern:
contract.<domain>.<component>.<capability>.v<major>
Example:
contract.trustgate.csi.trust-scores.v1
contract.dal.anchor-candidates.v1
contract.zara.intent-dispatch.v1
4. Contract Types
contract_types:
- schema_contract
- api_contract
- event_contract
- workflow_contract
- ruleset_contract
- data_product_contract
- agent_contract
- ui_contract
- external_integration_contract
- migration_contract
- assurance_contract
5. Contract Record
zct_id: ZCT-000001
contract_id: contract.trustgate.csi.trust-scores.v1
status: active
version: 1.0.0
contract_type: event_contract
producer:
component_id: TG-CSI
interface_id: TG-CSI.trust-score-generation.v1
zir_id: ZIR-000001
consumers:
resolution: graph-derived
known_consumers:
- AII
- DAL
- FAGF
artifact_refs:
schemas:
- schema.trust_scores@1.0.0
rulesets:
- ruleset.trustgate.csi.trust-score-calculation@1.0.0
workflows:
- workflow.trust-score-generation@1.0.0
compatibility:
semver_policy: strict
backward_compatible: true
forward_compatible: true
breaking_change_requires_major: true
governance:
security_level: critical
compliance_relevant: true
assurance_relevant: true
audit_required: true
approval_required:
- cto
- architecture_owner
- assurance_owner
6. Contract Type Definitions
6.1. Schema Contract
Defines the structural payload promise.
Used for:
JSON Schema
YAML Schema
database row shape
message payload shape
Example:
contract_type: schema_contract
artifact_refs:
schemas:
- schema.project_emissions_reduction_profile@1.0.0
6.2 API Contract
Defines service-to-service request/response behavior.
Used for:
REST
GraphQL
RPC
internal service endpoints
Example:
contract_type: api_contract
artifact_refs:
openapi:
- openapi.trustgate-csi@1.0.0
6.3 Event Contract
Defines asynchronous event payloads and delivery expectations.
Used for:
Kafka
outbox events
webhooks
internal event bus
Example:
contract_type: event_contract
event:
name: TrustScoreGenerated
delivery: transactional_outbox
idempotency_required: true
6.4 Workflow Contract
Defines multi-component behavioral flow.
Used for:
Hecate Need creation
ZARA dispatch
CSRD report generation
verifier workflow
rollback validation
Example:
contract_type: workflow_contract
workflow_ref: workflow.trustgate.replay-validation@1.0.0
6.5 Ruleset Contract
Defines which rulesets are required for valid behavior.
Example:
contract_type: ruleset_contract
rulesets:
required:
- ruleset.trustgate.csi.replay-validation@1.0.0
6.6 Agent Contract
Defines what an AI agent may read, write, suggest, or execute.
Example:
contract_type: agent_contract
agent_permissions:
may_read:
- schemas
- rulesets
- component_docs
may_write:
- draft_pr
- test_plan
may_not_write:
- prod_ruleset
- approved_schema
- frozen_contract
6.7 Assurance Contract
Defines evidence, verification, audit, and traceability promises.
Example:
contract_type: assurance_contract
evidence_required: true
verifier_visible: true
altd_logging_required: true
dal_anchor_required: true
7. Compatibility Rules
Contract changes SHALL follow semantic versioning.
major:
- breaking schema change
- renamed field
- removed field
- changed meaning
- changed event ordering
- changed required ruleset
- changed security posture
minor:
- additive optional field
- additional event metadata
- new non-breaking ruleset
- new consumer-safe workflow step
patch:
- documentation
- typo correction
- metadata clarification
- non-behavioral governance update
8. Contract Lifecycle
status:
- draft
- review
- active
- deprecated
- superseded
- retired
- frozen
Rules:
draft → review → active → deprecated → retired
active → frozen
active → superseded
Production systems may only depend on:
allowed_prod_status:
- active
- frozen
9. Contract Registry Linkage
Contracts must link to:
required_links:
- producer_component
- producer_interface
- schemas_or_payload_definition
- compatibility_policy
- owner
- lifecycle_status
Recommended links:
recommended_links:
- rulesets
- workflow_profiles
- rollback_profiles
- test_profiles
- Jira references
- GitHub references
10. Hecate Integration
Hecate SHALL resolve contracts during Need creation.
Need
↓
Component
↓
ZIR Interface Lookup
↓
ZCT Contract Lookup
↓
Schema / Ruleset / Workflow Resolution
↓
Blast Radius
↓
Test Plan
↓
Rollback Plan
↓
Jira
Derived Jira fields:
affected_contracts:
- contract.trustgate.csi.trust-scores.v1
contract_change_type:
- none
- patch
- minor
- major
contract_review_required: true
11. Agentic Development Integration
Coding agents SHALL receive contract context before implementation.
Agent context pack:
contracts:
- contract_id:
contract_type:
producer:
consumers:
schemas:
rulesets:
compatibility:
forbidden_changes:
required_tests:
Agents may not modify frozen or production contracts unless the Jira Need explicitly authorizes a contract change.
12. Workflow Test Integration
Every contract SHALL map to at least one test profile.
test_profiles:
- contract.compatibility
- contract.consumer-roundtrip
- contract.event-idempotency
- contract.schema-validation
- contract.ruleset-semantics
13. Rollback Integration
Every active contract SHALL define rollback behavior.
rollback_profiles:
- contract-revert
- compatibility-shim
- consumer-fallback
- event-replay
For breaking changes, rollback planning is mandatory.
14. Governance Requirements
Critical contracts require approval from:
approval_required:
- architecture_owner
- security_owner
- compliance_owner
Assurance contracts additionally require:
approval_required:
- assurance_owner
- verifier_workflow_owner
All contract changes SHALL be logged through ALTD.
15. Contract Validation Gates
Before merge:
required_gates:
- contract_schema_valid
- compatibility_check_passed
- downstream_consumers_identified
- workflow_tests_generated
- rollback_plan_exists
- blast_radius_computed
- approval_requirements_satisfied
16. Relationship to ZIR
ZIR answers:
What capability exists?
Who produces and consumes it?
ZCT answers:
What promises govern that capability?
What breaks compatibility?
What must be tested?
17. Normative Statement
ZCT is the authoritative taxonomy for all ZAYAZ interoperability contracts.
No component, interface, agent, workflow, or external integration may rely on an undocumented contract once ZCT is adopted.