Skip to main content

Component Metadata Profile Specification

1. Purpose​

The Component Metadata Profile Specification defines the governed type-specific Constitutional Header blocks used to make ZAYAZ components self-explainable.

This specification covers the first-round reusable component profiles for:

  • Micro Engines (MICE);
  • Major Engines;
  • APIs;
  • Registries;
  • Validators;
  • Reports;
  • Agents;
  • Workflows.

Pergamum Pulse is intentionally excluded from this version because its metadata requirements are materially larger and require a dedicated profile specification.

The governing principle is:

Every component SHALL be able to explain what it is, what it does, what it consumes, what it produces, what it depends on, and how it participates in governed ZAYAZ execution.

2. Architectural Position​

Constitutional Metadata Standard
            |
            v
Universal Constitutional Header
            |
            v
Document Type Profile
            |
            v
Component Metadata Profile
            |
            v
VW-DL Validation
            |
            v
Self-Describing Architecture Graph

The universal Constitutional Header establishes the identity and governance of the document.

The Component Metadata Profile describes the component represented by the document.

3. Common Component Semantics​

Every component profile SHOULD support the following common concepts:

purpose:
signals_in:
signals_out:
dependencies:
interfaces:
validation:
status:

A component SHOULD be able to answer:

  1. What am I?
  2. What capability do I provide?
  3. What governed signals do I require?
  4. What governed signals do I emit?
  5. What other components do I depend on?
  6. What interfaces do I expose?
  7. What validation applies to me?
  8. What lifecycle state am I in?

4. CSI Signal Contract​

4.1 Header Form​

Constitutional Headers SHALL use the unversioned CSI family form:

<csi_module>.<csi_component>.<csi_kind>.<csi_name>

Example:

comp.AIIL.INPUT.TRUST_SCORE

Runtime or published CSI contracts may use:

<csi_module>.<csi_component>.<csi_kind>.<csi_name>.v<major>_<minor>

Example:

comp.AIIL.INPUT.TRUST_SCORE.v1_0

The omission of the version in Constitutional Header metadata is intentional. The Header expresses the signal family; runtime binding resolves concrete versions.

The grammar of both forms is defined by the Canonical Identifier Architecture (CIA §2) and is applied as authored: csi_module is the four-letter code of the module that owns the emitting component, csi_component is the emitting component's document id, csi_kind is a zar.kind_registry value and csi_name matches ^[A-Z][A-Z0-9_]*$ (underscore separators; the hyphen is reserved for component ids).

4.2 Registry Authority​

Published CSI bindings SHALL resolve through:

zar.signal_csi_binding

4.3 Missing CSI​

If a CSI family is not found:

  • VW-DL SHALL describe the missing signal;
  • VW-DL SHALL emit a structured finding;
  • the finding SHALL identify zar.signal_csi_binding as the expected registry;
  • the signal SHALL be marked missing-registration;
  • missing registration MAY be a warning for proposed/draft components;
  • missing registration SHOULD be an error for active production components.

Example:

{
  "rule_id": "CSI-005",
  "severity": "WARNING",
  "status": "missing-registration",
  "signal": "comp.TRUSTGATE.OUTPUT.TRUST-DELTA",
  "registry": "zar.signal_csi_binding",
  "message": "CSI signal family is declared by the component but is not published in zar.signal_csi_binding."
}

5. Micro Engine (MICE) Profile​

5.1 Purpose​

The mice: block describes a governed Micro Engine.

A Micro Engine is a specialised component with a governed Micro Engine Identifier (MEID), defined domain/capability/function identity, explicit signal contracts, lifecycle status, registry presence and CMI binding.

5.2 Canonical Block​

mice:
  meid:
  category:
  domain:
  capability:
  function:
  status:
  purpose:
  signals_in: []
  signals_out: []
  input_types: []
  supported_modes: []
  api:
    route:
    method:
  metric_types_supported: []
  source_map_ref:
  cmi_binding:

5.3 MEID Grammar​

MEID SHALL follow:

MEID_<DOMAIN>_<CAPABILITY>_<FUNCTION>

Example:

MEID_TRUST_ENRICH_FEEDBACK

5.4 MEID Authorities​

MEID validation SHALL use:

zar.meid_domain
zar.meid_capability
zar.meid_function
zar.meid_status
zar.meid_registry
zar.meid_cmi_binding
zar.generate_meid

5.5 MICE Rules​

RuleDescription
MICE-001mice.meid exists
MICE-002MEID matches governed grammar
MICE-003DOMAIN resolves through zar.meid_domain
MICE-004CAPABILITY resolves through zar.meid_capability
MICE-005FUNCTION resolves through zar.meid_function
MICE-006zar.generate_meid reproduces declared MEID
MICE-007MEID resolves through zar.meid_registry
MICE-008Status resolves through zar.meid_status
MICE-009CMI binding resolves through zar.meid_cmi_binding
MICE-010Every signals_in CSI is syntactically valid
MICE-011Every signals_out CSI is syntactically valid
MICE-012Published CSI families resolve through zar.signal_csi_binding
MICE-013API metadata is valid where an API is declared
MICE-014Supported modes use governed values when a registry exists

5.6 Example​

mice:
  meid: MEID_TRUST_ENRICH_FEEDBACK
  category: ENRICH
  domain: trust
  capability: enrich
  function: feedback
  status: proposed
  purpose: >
    Enriches governed trust feedback for publication, telemetry,
    learning and assurance intelligence.
  signals_in:
    - comp.TRUSTGATE.INPUT.FEEDBACK
    - comp.DAL.OUTPUT.VERIFICATION
  signals_out:
    - comp.TRUSTGATE.OUTPUT.FEEDBACK-PUBLISHED
    - comp.TRUSTGATE.OUTPUT.TRUST-DELTA
  input_types:
    - json
  supported_modes:
    - ai-feedback
    - telemetry-publication
    - trust-learning
    - assurance-intelligence
  api:
    route: /api/trustgate/MEID_TRUST_ENRICH_FEEDBACK
    method: POST
  source_map_ref: EngineAliasMap

6. Major Engine Profile​

6.1 Purpose​

The engine: block describes a major engine or governed engine-class component.

A major engine may depend on Micro Engines and other engines and SHALL explicitly describe its signal contracts and dependencies.

6.2 Canonical Block​

engine:
  eid:
  category:
  domain:
  status:
  purpose:
  signals_in: []
  signals_out: []
  micro_engines: []
  engine_dependencies: []
  interfaces: []
  api:
    route:
    method:
  registries: []
  validators: []
  cmi_bindings: []

6.3 Engine Rules​

RuleDescription
ENG-001EID exists
ENG-002EID satisfies the governed EID grammar
ENG-003EID resolves through the canonical Engine registry
ENG-004Engine status resolves through the canonical lifecycle registry
ENG-005Engine domain resolves
ENG-006Declared Micro Engines resolve through zar.meid_registry
ENG-007Engine dependencies resolve
ENG-008Circular engine dependencies are prohibited unless explicitly governed
ENG-009signals_in CSI families are valid
ENG-010signals_out CSI families are valid
ENG-011Published CSI families resolve through zar.signal_csi_binding
ENG-012CMI bindings resolve
ENG-013Declared validators resolve
ENG-014Declared registries resolve

6.4 EID Finalisation Requirement​

The exact EID grammar and authoritative Engine registry SHALL be finalised before ENG-002 and ENG-003 become blocking.

Until then:

  • unresolved EID grammar SHALL be reported as profile-governance-pending;
  • registry checks SHALL be warning-level unless an authoritative Engine registry exists;
  • no local EID convention SHALL silently become canonical through VW-DL implementation.

7. API Profile​

7.1 Canonical Block​

api:
  api_id:
  status:
  route:
  method:
  purpose:
  signals_in: []
  signals_out: []
  input_schema:
  output_schema:
  authentication:
  authorization:
  rate_limit_profile:
  versioning:

7.2 API Rules​

RuleDescription
API-001API identity exists where registry governance requires one
API-002Route is declared
API-003HTTP method is valid
API-004Input schema resolves
API-005Output schema resolves
API-006Authentication model is declared
API-007Authorization model is declared where required
API-008CSI signals resolve
API-009Versioning model is declared for published APIs

8. Registry Profile​

8.1 Canonical Block​

registry:
  registry_id:
  status:
  purpose:
  authority:
  owner:
  schema:
  version:
  storage:
  write_policy:
  read_policy:
  generated:
  generator:
  dependencies: []

8.2 Registry Rules​

RuleDescription
REG-001Registry identity exists
REG-002Registry identity resolves where a canonical registry-of-registries exists
REG-003Owner exists
REG-004Authority is declared
REG-005Schema resolves
REG-006Version valid
REG-007Generated registries declare generator
REG-008Dependencies resolve
REG-009Write policy exists for authoritative registries

9. Validator Profile​

9.1 Canonical Block​

validator:
  validator_id:
  status:
  purpose:
  validates:
  evidence_requirements: []
  signals_in: []
  signals_out: []
  rulesets: []
  schemas: []
  severity_model:
  hecate_profile:
  deterministic:

9.2 Validator Rules​

RuleDescription
VAL-001Validator identity exists
VAL-002Validator status valid
VAL-003Validation target is declared
VAL-004Evidence requirements defined
VAL-005Rulesets resolve
VAL-006Schemas resolve
VAL-007CSI signals resolve
VAL-008Severity model declared
VAL-009HECATE profile resolves where declared
VAL-010Deterministic/non-deterministic behaviour declared

10. Report Profile​

10.1 Canonical Block​

report:
  report_id:
  status:
  report_type:
  purpose:
  data_sources: []
  signals_in: []
  signals_out: []
  generation_profile:
  output_formats: []
  assurance_profile:
  publication_profile:

10.2 Report Rules​

RuleDescription
REP-001Report identity exists
REP-002Report type resolves
REP-003Data sources resolve
REP-004CSI inputs resolve
REP-005CSI outputs resolve
REP-006Generation profile resolves
REP-007Output formats declared
REP-008Assurance profile resolves where required
REP-009Publication profile resolves where required

11. Agent Profile​

11.1 Canonical Block​

agent:
  agent_id:
  status:
  purpose:
  operating_mode:
  authority_scope:
  signals_in: []
  signals_out: []
  tools: []
  dependencies: []
  proposal_only:
  canonical_write_allowed:
  validation_profile:
  escalation_profile:

11.2 Agent Rules​

RuleDescription
AGT-001Agent identity exists
AGT-002Status valid
AGT-003Operating mode declared
AGT-004Authority scope declared
AGT-005CSI signals resolve
AGT-006Tool references resolve
AGT-007Dependencies resolve
AGT-008Canonical write authority explicitly declared
AGT-009Proposal-only agents SHALL NOT claim canonical write authority
AGT-010Escalation profile resolves where human review is required

12. Workflow Profile​

12.1 Canonical Block​

workflow:
  workflow_id:
  status:
  purpose:
  trigger_signals: []
  completion_signals: []
  stages: []
  roles: []
  gates: []
  dependencies: []
  exceptions: []
  replay_supported:

12.2 Workflow Rules​

RuleDescription
WF-001Workflow identity exists
WF-002Status valid
WF-003Trigger CSI signals resolve
WF-004Completion CSI signals resolve
WF-005Stages defined
WF-006Roles resolve
WF-007Gates resolve
WF-008Dependencies resolve
WF-009Exception paths declared where required
WF-010Replay support declared

13. Profile Composition​

One documentation asset MAY describe more than one component dimension.

Examples:

Engine Specification
+
Engine Profile
+
API Profile

or:

Validator Specification
+
Validator Profile
+
API Profile
+
Registry Profile

VW-DL SHALL:

  1. resolve applicable profiles;
  2. merge required-field obligations;
  3. execute all applicable validators;
  4. detect incompatible declarations;
  5. preserve findings by originating profile.

14. Lifecycle-Aware Validation​

Recommended severity model:

LifecycleMissing governed binding
draftINFO or WARNING
proposedWARNING
reviewWARNING or ERROR depending on rule
approvedERROR
activeERROR
deprecatedERROR only for integrity-breaking defects
retiredhistorical validation profile

This allows incomplete registries to coexist with controlled development without normalising missing governance.

15. Structured Findings​

Example:

{
  "rule_id": "ENG-006",
  "severity": "ERROR",
  "profile": "engine",
  "field": "engine.micro_engines[0]",
  "value": "MEID_TRUST_ENRICH_FEEDBACK",
  "message": "Referenced Micro Engine is not present in zar.meid_registry.",
  "registry": "zar.meid_registry",
  "autofix": false
}

Findings SHALL be consumable by:

  • GitHub annotations;
  • JSON reports;
  • VW-DL dashboards;
  • ZARA remediation proposals;
  • HECATE validation workflows.

16. VW-DL Resolution Strategy​

Read Constitutional Header
        |
        v
Resolve Document Type
        |
        v
Resolve Component Blocks
        |
        +--> mice
        +--> engine
        +--> api
        +--> registry
        +--> validator
        +--> report
        +--> agent
        +--> workflow
        |
        v
Load Applicable Profile Rules
        |
        v
Resolve Registries and CSI Bindings
        |
        v
Generate Findings

17. Implementation Requirements​

Recommended structure:

viroway_tools/
└── docs_lint/
    ├── core/
    │   ├── parser.py
    │   ├── findings.py
    │   └── profile_resolver.py
    └── profiles/
        ├── mice.py
        ├── engine.py
        ├── api.py
        ├── registry.py
        ├── validator.py
        ├── report.py
        ├── agent.py
        └── workflow.py

Registry access SHOULD be abstracted from validators so the same rules can operate against PostgreSQL registries, exported JSON registries, test fixtures and CI snapshots.

18. Non-Goals​

Version 0.1.0 intentionally does not define the Pergamum Pulse metadata profile.

It also does not finalise:

  • the EID grammar;
  • the authoritative Engine registry;
  • all possible CSI kinds;
  • every component family in ZAYAZ.

Those SHALL be governed separately rather than inferred.

19. Foundational Principle​

A ZAYAZ component is not fully defined merely because implementation code exists.

A governed component SHALL expose enough constitutional metadata to allow humans, agents, validators and architecture tooling to understand:

Identity
Purpose
Inputs
Outputs
Signals
Dependencies
Interfaces
Governance
Lifecycle
Validation

The Component Metadata Profile Specification provides the reusable metadata contract that turns the ZAYAZ documentation corpus into a self-describing architecture graph.



GitHub RepoRequest for Change (RFC)
Last updated on by ZAYAZ