Skip to main content
Jira progress: loading…

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.



GitHub RepoRequest for Change (RFC)
Tags:
Last updated on by automation-bot