VW-DL Phase 1 — Constitutional Header Validation Specification
1. Purpose
VW-DL Phase 1 defines deterministic validation rules ensuring that canonical ZAYAZ documentation assets contain valid Constitutional Headers and that specialised component metadata correctly describes the architecture.
The objective is:
Make every ZAYAZ document and component self-explainable.
A conformant asset should explain:
- what it is;
- why it exists;
- who owns it;
- what it depends on;
- what inputs it consumes;
- what outputs it produces;
- what signals it receives;
- what signals it emits;
- what APIs and registries it uses;
- what validation applies.
2. Validation Architecture
VW-DL validates three layers:
Constitutional Metadata Standard
|
v
Constitutional Header
|
v
VW-DL Validation Engine
|
v
Document and Component Profiles
|
v
Governed ZAYAZ Architecture Graph
JSON Schemas validate objects.
VW-DL validates documentation governance.
HECATE validates conformance and assurance.
3. Universal Constitutional Header Rules
Required identity fields:
id:
semantic_id:
title:
version:
document_type:
Rules:
| ID | Rule |
|---|---|
| CH-ID-001 | ID exists |
| CH-ID-002 | ID format valid |
| CH-ID-003 | semantic_id exists |
| CH-ID-004 | semantic_id unique |
| CH-ID-005 | version follows SemVer |
| CH-ID-006 | document_type resolves |
Governance fields:
owners:
status:
security_level:
classification:
Rules:
| ID | Rule |
|---|---|
| CH-GOV-001 | Owner exists |
| CH-GOV-002 | Status valid |
| CH-GOV-003 | Security classification valid |
| CH-GOV-004 | Classification vocabulary valid |
4. Relationship Validation
Supported relationship fields:
governed_by:
references:
depends_on:
interfaces_with:
consumes:
produces:
Rules:
| ID | Rule |
|---|---|
| REL-001 | Relationship target exists |
| REL-002 | Relationship type valid |
| REL-003 | Relationship direction valid |
| REL-004 | No orphan references |
| REL-005 | No circular dependency |
5. Component Self-Description
Components SHOULD declare:
component_profile:
component_type:
purpose:
signals_in:
signals_out:
inputs:
outputs:
dependencies:
interfaces:
validation:
This allows every component to answer:
- what enters it;
- what leaves it;
- how it interacts;
- how it is validated.
6. CSI Signal Validation
Signals SHALL use CSI codes.
Runtime CSI format:
<csi_module>.<csi_component>.<csi_kind>.<csi_name>.v<major>_<minor>
Constitutional Header format:
<csi_module>.<csi_component>.<csi_kind>.<csi_name>
Example:
Runtime:
comp.AIIL.INPUT.TRUST-SCORE.v1_0
Header:
signals_in:
- comp.AIIL.INPUT.TRUST-SCORE
Published CSI bindings are resolved through:
zar.signal_csi_binding
Rules:
| ID | Rule |
|---|---|
| CSI-001 | CSI syntax valid |
| CSI-002 | CSI module exists |
| CSI-003 | CSI component exists |
| CSI-004 | CSI kind exists |
| CSI-005 | CSI binding exists |
| CSI-006 | Missing CSI recorded |
Missing CSI SHALL be recorded as a governed finding.
7. Micro Engine (MICE) Profile
Micro Engines use:
mice:
meid:
category:
domain:
capability:
function:
signals_in:
signals_out:
Example:
mice:
meid: MEID_TRUST_ENRICH_FEEDBACK
signals_in:
- comp.TRUSTGATE.INPUT.FEEDBACK
signals_out:
- comp.TRUSTGATE.OUTPUT.TRUST-DELTA
MEID format:
MEID_<DOMAIN>_<CAPABILITY>_<FUNCTION>
Registry sources:
zar.meid_domain
zar.meid_capability
zar.meid_function
zar.meid_status
zar.meid_registry
zar.meid_cmi_binding
Rules:
| ID | Rule |
|---|---|
| MICE-ID-001 | MEID exists |
| MICE-ID-002 | MEID format valid |
| MICE-ID-003 | Domain resolves |
| MICE-ID-004 | Capability resolves |
| MICE-ID-005 | Function resolves |
| MICE-ID-006 | Generated MEID matches helper function |
| MICE-ID-007 | Registry entry exists |
| MICE-ID-008 | Status valid |
| MICE-ID-009 | CMI binding exists |
8. Engine Profile
Engines SHALL describe:
engine:
eid:
purpose:
signals_in:
signals_out:
micro_engines:
dependencies:
Rules:
| ID | Rule |
|---|---|
| ENG-001 | Engine ID exists |
| ENG-002 | Engine registry resolves |
| ENG-003 | Engine status valid |
| ENG-004 | Dependencies resolve |
| ENG-005 | Micro-engine dependencies resolve |
| ENG-006 | No dependency cycles |
| ENG-007 | CMI binding exists |
9. API, Registry, Validator and Report Profiles
API
api:
route:
method:
input_schema:
output_schema:
Rules:
- API route exists.
- Method valid.
- Schemas resolve.
- Authentication declared.
Registry
registry:
registry_id:
schema:
owner:
version:
Rules:
- Registry exists.
- Schema resolves.
- Owner exists.
- Version declared.
Validator
validator:
validator_id:
hecate_profile:
evidence_requirements:
Rules:
- Validator registered.
- HECATE profile resolves.
- Evidence requirements exist.
Report
report:
report_id:
report_type:
data_sources:
generation_profile:
Rules:
- Report identity exists.
- Sources resolve.
- Generation profile exists.
10. Pergamum Pulse Profile
Pergamum Pulse components SHOULD declare:
pergamum_pulse:
ingestion_profile:
rights_profile:
retrieval_profile:
knowledge_type:
Rules:
| ID | Rule |
|---|---|
| PP-001 | Ingestion Profile exists |
| PP-002 | Rights Profile exists |
| PP-003 | Retrieval Profile exists |
| PP-004 | Knowledge type valid |
| PP-005 | Source lineage required |
11. Validation Findings
Findings SHALL be structured objects.
Example:
{
"rule_id": "MICE-ID-003",
"severity": "ERROR",
"field": "mice.domain",
"message": "Domain does not exist in zar.meid_domain",
"registry": "zar.meid_domain"
}
Outputs:
- GitHub annotations;
- JSON reports;
- HECATE Findings;
- ZARA remediation proposals.
12. Phase 1 Implementation Scope
Phase 1 supports:
- YAML parsing;
- CMS validation;
- registry lookup;
- profile resolution;
- finding generation;
- GitHub output;
- JSON output.
Initial profiles:
- document;
- specification;
- micro-engine;
- engine;
- API;
- registry;
- validator;
- report;
- Pergamum Pulse.
13. Foundational Principle
Documentation is not merely descriptive text. In ZAYAZ it is a governed architectural interface.
A component without identity, ownership, dependencies, signals, inputs and outputs cannot be reliably understood, validated or maintained.
VW-DL ensures that every canonical documentation asset contributes to a self-describing architecture graph where humans, AI agents and assurance systems can understand what exists, how it operates and how changes propagate.