Pergamum Pulse Schema Registry Architecture and Governance

Version 0.1 — Governed Schema Infrastructure Contract

This document defines the architecture and governance model for Pergamum Pulse schemas.

The schema registry provides the machine-readable contract layer connecting:

• Pergamum Pulse objects;
• ZARA Agents;
• HECATE validation;
• APIs;
• workflow engines;
• database persistence;
• user interfaces;
• event payloads;
• test fixtures;
• historical replay.

The governing principle is:

GitHub is the canonical authoring source. AWS is the governed publication and distribution layer. Published schemas are immutable contracts.

1. Architecture

The canonical flow is:

GitHub Repository
        |
        v
Schema Validation Pipeline
        |
        +-- JSON Schema validation
        +-- reference resolution
        +-- fixture testing
        +-- HECATE schema checks
        +-- digest generation
        +-- registry manifest generation
        |
        v
AWS Schema Registry
        |
        v
https://schemas.zayaz.io

GitHub SHALL remain the source of truth.

AWS SHALL provide governed distribution.

2. Schema Design Principles

Schemas SHALL be:

• modular;
• versioned;
• immutable after release;
• independently addressable;
• machine-readable;
• HECATE-validatable;
• reusable across Modules and Components.

The registry SHALL avoid large monolithic schemas where reusable contracts can be separated.

3. Canonical Registry Namespace

The preferred schema authority is:

https://schemas.zayaz.io/

Example:

https://schemas.zayaz.io/pergamum-pulse/ingest-workbench/0.1.0/workflow/ingest-case.schema.json

Existing schema identifiers SHALL remain immutable.

New schemas SHALL use the canonical registry namespace.

4. Versioning

Schema references SHALL use explicit versions.

Normative references SHALL NOT depend on:

/latest/
/current/

Version rules:

• patch version: non-breaking correction;
• minor version: backwards-compatible extension;
• major version: breaking contract change.

Released schema versions SHALL remain retrievable permanently.

5. Repository Structure

Recommended structure:

schemas/
└── pergamum-pulse/
    └── ingest-workbench/
        ├── common/
        ├── source/
        ├── page/
        ├── document/
        ├── workflow/
        ├── review/
        ├── retrieval/
        ├── hecate/
        ├── admission/
        ├── events/
        └── fixtures/

6. Page-Level Knowledge Model

Pergamum Pulse SHALL treat document pages as first-class intermediate objects.

The ingestion model is:

Source Object
      |
Source Capture
      |
Document Page
      |
Page Representation
      |
Document AST
      |
Source Fragment
      |
Knowledge Object

A page is not a Source Fragment.

A page represents physical evidence structure.

A Source Fragment represents semantic evidence structure.

7. Page Schema Family

The registry SHALL include page schemas:

page/
├── page.schema.json
├── page-block.schema.json
├── page-layout.schema.json
├── page-representation.schema.json
└── page-image.schema.json

A page MAY contain:

• text blocks;
• headings;
• tables;
• images;
• coordinates;
• OCR metadata;
• layout information;
• extraction confidence.

8. Source and Extraction Schema Family

source/
├── source-submission.schema.json
├── source-artifact.schema.json
├── source-capture.schema.json
├── source-locator.schema.json
├── transformation.schema.json
├── extraction-candidate.schema.json
└── extraction-conflict.schema.json

9. Workflow Schema Family

workflow/
├── ingest-case.schema.json
├── ingest-profile.schema.json
├── workflow-instance.schema.json
├── workflow-stage.schema.json
├── workflow-task.schema.json
└── assignment.schema.json

10. Review Schema Family

review/
├── proposal.schema.json
├── proposal-evidence.schema.json
├── confidence.schema.json
├── review-decision.schema.json
└── stage-approval.schema.json

The schema layer SHALL preserve the distinction:

ZARA Proposal
      !=
Approved Knowledge

11. Retrieval Schema Family

retrieval/
├── chunking-profile.schema.json
├── chunk-plan.schema.json
├── chunk-position.schema.json
├── structural-locator.schema.json
└── retrieval-eligibility.schema.json

Chunks SHALL remain derived projections.

12. HECATE Integration

HECATE SHALL validate:

• schema structure;
• references;
• lifecycle;
• provenance;
• scope;
• lineage;
• workflow prerequisites.

HECATE SHALL NOT create authority.

13. Registry Publication Architecture

Recommended deployment:

GitHub
 |
CI/CD
 |
Schema Build
 |
Private AWS S3
 |
CloudFront
 |
Route53
 |
https://schemas.zayaz.io

Production schemas SHOULD use:

• private S3 origin;
• CloudFront distribution;
• HTTPS;
• immutable versioned paths;
• registry manifests;
• digest verification.

14. Registry Manifest

The registry SHOULD publish:

manifest.json
catalog.json
checksums.sha256
dependency-graph.json
deprecations.json

The manifest SHALL identify:

• schema identifier;
• URI;
• version;
• digest;
• status;
• Module;
• Component;
• dependencies.

15. Fixtures

Every schema family SHOULD contain:

• valid examples;
• invalid examples;
• boundary cases;
• migration examples;
• HECATE validation fixtures.

16. Security

Schemas SHALL preserve:

• integrity;
• provenance;
• access control;
• tenant boundaries;
• white-label boundaries.

Published schemas SHALL never contain secrets.

17. Governance

Every schema SHALL identify:

• owner;
• Module;
• Component;
• version;
• lifecycle;
• source authority;
• migration policy;
• deprecation policy.

18. Foundational Principle

Schemas are not merely technical validation files. They are executable contracts defining how ZAYAZ knowledge, governance, workflows and intelligence systems communicate.

By creating a modular, versioned and immutable schema registry from the beginning, Pergamum Pulse can scale from document ingestion to a global knowledge infrastructure without losing traceability, compatibility or constitutional control.

---