Add modular federated-zk compliance docs, link validator, tests, and CI workflow

.github/workflows/federated-zk-docs-validation.yml

@@ -0,0 +1,33 @@
+name: Federated ZK Docs Validation
+
+on:
+  push:
+    paths:
+      - 'FEDERATED_ZK_AI_COMPLIANCE_RESEARCH_PROGRAM_SYNTHESIS.md'
+      - 'docs/federated-zk-compliance/**'
+      - 'tests/test_federated_zk_validate_docs.py'
+      - '.github/workflows/federated-zk-docs-validation.yml'
+  pull_request:
+    paths:
+      - 'FEDERATED_ZK_AI_COMPLIANCE_RESEARCH_PROGRAM_SYNTHESIS.md'
+      - 'docs/federated-zk-compliance/**'
+      - 'tests/test_federated_zk_validate_docs.py'
+      - '.github/workflows/federated-zk-docs-validation.yml'
+
+jobs:
+  validate-doc-links:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Run validator unit tests
+        run: python -m unittest discover -s tests -p 'test_federated_zk_validate_docs.py'
+
+      - name: Validate federated-zk doc links (strict)
+        run: python docs/federated-zk-compliance/validate_docs.py --strict

FEDERATED_ZK_AI_COMPLIANCE_RESEARCH_PROGRAM_SYNTHESIS.md

@@ -0,0 +1,26 @@
+# Federated ZK AI Compliance Research Program Synthesis
+
+This document is now the **navigation entrypoint** for the modularized synthesis package.
+
+## Why modularized
+
+The prior single-file draft became too large for review workflows. The content has been reorganized into focused documents to support:
+- easier regulator/legal review,
+- clearer ownership by workstream,
+- cleaner change-tracking over time.
+
+## Document map
+
+- `docs/federated-zk-compliance/_index.md` — package index and recommended review path.
+- `docs/federated-zk-compliance/full_synthesis_v0.5.md` — complete integrated synthesis (legacy single-file equivalent).
+- `docs/federated-zk-compliance/01_architecture_stack.md` — layered architecture and formal model.
+- `docs/federated-zk-compliance/02_enterprise_governance.md` — containment and constitutional controls.
+- `docs/federated-zk-compliance/03_crypto_and_federation.md` — zk pipeline and verifier federation.
+- `docs/federated-zk-compliance/04_infrastructure_and_regulation.md` — Terraform/Kubernetes and EU supervisory mapping.
+- `docs/federated-zk-compliance/05_treaty_recoverability_rollout.md` — GACP, recoverability metrics, rollout playbooks.
+- `docs/federated-zk-compliance/06_annexes.md` — artifact templates, glossary, and traceability matrix.
+
+## Versioning
+
+- Prior monolithic draft: v0.4
+- Current modular package baseline: v0.5

docs/federated-zk-compliance/01_architecture_stack.md

@@ -0,0 +1,31 @@
+# 01 — Layered Architecture and Formal Model
+
+## Purpose
+Define the canonical L0–L9 stack and the formal semantics used by all downstream governance, infrastructure, and supervisory artifacts.
+
+## L0–L9 Architecture
+- **L0 Ontology/Epistemics**: claim types, evidentiary semantics, uncertainty operators.
+- **L1 Formal Semantics**: state-transition admissibility and proof obligations.
+- **L2 Cryptographic Fabric**: commitments, zk circuits, recursive aggregation.
+- **L3 Runtime Substrate**: deterministic telemetry and reproducible execution environments.
+- **L4 Enterprise Governance**: constitutional policy and containment controls.
+- **L5 Regulatory Mapping**: control-to-obligation alignment (EU AI Act, Basel, DORA).
+- **L6 Jurisprudential Layer**: admissibility, appeals, and precedent mapping.
+- **L7 Federation Layer**: verifier membership, quorum governance, dispute protocol.
+- **L8 Recoverability Layer**: continuity metrics and reconstruction workflows.
+- **L9 Frontier Layer**: bounded theoretical hypotheses requiring falsifiability.
+
+## Minimal Formal Semantics
+Let `S` = states, `A` = actions, `T` = transitions, `C` = controls, `R` = reporting windows.
+- Admissibility predicate: `P: S × A -> {0,1}`.
+- Evidence map: `E: T -> H` where `H` is hash-linked evidence history.
+- Compliance satisfaction `Sat(i,j,c,r)=1` iff verifier `j` accepts proof for statement `stmt(i,c,r)` with required evidence commitments.
+
+## Deterministic Supervisory Equivalence (DSE)
+For shared controls across jurisdictions, DSE is satisfied when harmonized predicates yield equivalent supervisory outcomes under agreed assumptions.
+
+## Outputs of this workstream
+1. Versioned architecture map.
+2. Predicate dictionary.
+3. Cross-layer dependency table.
+4. DSE harmonization profile template.

docs/federated-zk-compliance/02_enterprise_governance.md

@@ -0,0 +1,27 @@
+# 02 — Enterprise AGI/ASI Governance and Containment
+
+## Purpose
+Specify enterprise controls for high-capability AI systems with constitutional constraints, deterministic auditing, and recoverable fail-safe pathways.
+
+## Constitutional Control Hierarchy
+1. **Foundational invariants**: non-overridable constraints (e.g., human override domains).
+2. **Statutory controls**: jurisdiction and sector obligations.
+3. **Operational directives**: deployment-time rules bounded by higher invariants.
+
+## Control Plane Design
+- Signed policy bundles and versioned lineage.
+- Immutable evidence logging for privileged actions.
+- Segmented execution zones (training/eval/deploy/actuation).
+- Preventive and detective controls with automatic quarantine policies.
+
+## TLA+ Property Families
+- **Safety**: no unauthorized external actuation.
+- **Liveness**: all fault states converge to safe fallback.
+- **Auditability**: all privileged actions produce verifiable evidence.
+- **Rollback integrity**: policy rollback cannot bypass required controls.
+
+## Pilot Readiness Artifacts
+1. Policy-kernel specification.
+2. TLA+ property pack and model-check results.
+3. Runtime-control test protocol.
+4. Incident escalation and replay runbook.

docs/federated-zk-compliance/03_crypto_and_federation.md

@@ -0,0 +1,30 @@
+# 03 — zk Proof Pipeline and Verifier Federation
+
+## Purpose
+Define the cryptographic compliance lifecycle from evidence generation through supervisory verification, including federation governance.
+
+## Proof Pipeline
+1. Canonicalize and sign evidence events.
+2. Build commitments for reporting windows.
+3. Execute zk circuits for mapped controls.
+4. Aggregate proofs recursively for submission efficiency.
+5. Verify against jurisdiction policy profiles.
+6. Publish evidence envelope and verifier receipts.
+
+## Security Requirements
+- Completeness and soundness.
+- Non-malleability of supervisory submissions.
+- Domain separation across institutions and jurisdictions.
+- Key-rotation continuity and forward security.
+
+## Verifier Federation Model
+- Roles: national supervisor, regional supervisor, multilateral observer.
+- Governance: threshold validation `(n,t)` and quorum publication.
+- Challenge-response: time-bounded dispute procedures with evidence replay.
+- Membership discipline: accession, suspension, reinstatement.
+
+## Required Artifacts
+1. Assumption register.
+2. Proof-system profile matrix.
+3. Federation policy configuration.
+4. Challenge-response SOP.

docs/federated-zk-compliance/04_infrastructure_and_regulation.md

@@ -0,0 +1,26 @@
+# 04 — Infrastructure and Regulatory Mapping
+
+## Purpose
+Provide deployable infrastructure patterns and regulatory crosswalks for supervisory-grade AI compliance operations.
+
+## Infrastructure Blueprint
+- Terraform modules for identity/KMS, regional GPU compute, evidence stream, and verifier gateway.
+- Kubernetes controls for signed image admission, policy sidecars, immutable audit exporters, and quarantine namespaces.
+- Regional partitioning and sovereign key custody for jurisdictional compliance.
+
+## Regulatory Mapping
+- **EU AI Act**: risk management, traceability, incident/post-market obligations.
+- **Basel alignment**: model risk governance evidence and maturity indicators.
+- **DORA alignment**: resilience controls and continuity stress evidence.
+
+## Regulator Submission Dossier
+1. Control crosswalk matrix.
+2. Proof summary and assumption register.
+3. Exception ledger + compensating controls.
+4. Continuity/resilience package.
+5. Independent attestation memo.
+
+## Deliverables
+- Reference Terraform interface contracts.
+- Kubernetes policy baseline.
+- Regulator submission template pack.

docs/federated-zk-compliance/05_treaty_recoverability_rollout.md

@@ -0,0 +1,28 @@
+# 05 — Treaty Layer, Recoverability, and Rollout
+
+## Purpose
+Define multilateral governance lifecycle, continuity metrics, and phased deployment strategy.
+
+## GACP Lifecycle
+- **Accession**: capability declaration and conformance trial.
+- **Conditional membership**: bounded production participation.
+- **Full membership**: reciprocal equivalence rights.
+- **Suspension/Reinstatement**: treaty-triggered, evidence-based procedures.
+
+## Recoverability Metric Pack
+- `RL`: reconstruction latency.
+- `CIS`: continuity integrity score.
+- `PSR`: proof survivability ratio.
+- `CPI`: constitutional preservation index.
+
+## Rollout Phases (0–36 months)
+- Phase 0: standards and ontology harmonization.
+- Phase 1: bilateral regulator sandboxes.
+- Phase 2: regional federation interoperability.
+- Phase 3: multilateral accession and treaty pilots.
+
+## Phase Exit Criteria
+- Verified control conformance.
+- Demonstrated resilience drills.
+- Accepted supervisory dossier outcomes.
+- Documented dispute-resolution performance.

docs/federated-zk-compliance/06_annexes.md

@@ -0,0 +1,24 @@
+# 06 — Annexes
+
+## Purpose
+Provide concrete starter templates and shared vocabulary for execution.
+
+## Annex Inventory
+1. TLA+ property checklist.
+2. OSCAL starter control mappings.
+3. zk proof submission envelope skeleton.
+4. Terraform/Kubernetes reference control contracts.
+5. Supervisory dossier template.
+6. KPI scorecard.
+7. Glossary of core terms.
+8. Requirement-to-artifact traceability matrix.
+
+## Usage Guidance
+- Treat annexes as baseline patterns, not exhaustive standards.
+- Version all templates with explicit assumption and jurisdiction tags.
+- Require independent review before adoption in supervisory production flows.
+
+## Governance of Annexes
+- Update cadence: quarterly or on major legal/crypto change.
+- Review owners: legal, supervisory engineering, security assurance.
+- Approval gate: federation council + independent assessor concurrence.

docs/federated-zk-compliance/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog — Federated ZK Compliance Docs
+
+## v0.5 (current)
+- Introduced modular package structure and navigation entrypoint.
+- Added focused workstream modules (`01`–`06`).
+- Added integrated full synthesis reference.
+- Added package README and versioning guidance.
+
+## Change control rules
+- Increment **patch** for editorial clarifications.
+- Increment **minor** for new module sections, templates, or governance artifacts.
+- Increment **major** for taxonomy changes (e.g., architecture layers, formal predicate semantics, or treaty lifecycle model changes).

docs/federated-zk-compliance/README.md

@@ -0,0 +1,23 @@
+# Federated ZK Compliance Documentation Package (v0.5)
+
+## Overview
+This directory contains the modularized federated zk AI compliance synthesis package.
+
+## Files
+- `full_synthesis_v0.5.md` — full integrated reference.
+- `01_architecture_stack.md` — architecture and formal semantics.
+- `02_enterprise_governance.md` — enterprise containment/governance controls.
+- `03_crypto_and_federation.md` — zk pipeline and verifier federation.
+- `04_infrastructure_and_regulation.md` — infra and regulatory mapping.
+- `05_treaty_recoverability_rollout.md` — treaty lifecycle and rollout strategy.
+- `06_annexes.md` — annex inventory and governance.
+
+## Change management
+- Baseline version: `v0.5`
+- Update policy: maintain module-level updates with synchronized version notes in the top-level navigation file.
+
+## Contribution workflow
+1. Edit the smallest relevant module first (`01`–`06`).
+2. If needed, mirror substantial updates into `full_synthesis_v0.5.md`.
+3. Update `CHANGELOG.md` with version-impact notes.
+4. Keep version labels synchronized across this README, top-level navigation, and full synthesis metadata.

docs/federated-zk-compliance/_index.md

@@ -0,0 +1,20 @@
+# Federated ZK Compliance Package Index
+
+## Quick navigation
+- [README](README.md)
+- [CHANGELOG](CHANGELOG.md)
+- [Full synthesis v0.5](full_synthesis_v0.5.md)
+
+## Workstream modules
+1. [01 — Layered Architecture and Formal Model](01_architecture_stack.md)
+2. [02 — Enterprise AGI/ASI Governance and Containment](02_enterprise_governance.md)
+3. [03 — zk Proof Pipeline and Verifier Federation](03_crypto_and_federation.md)
+4. [04 — Infrastructure and Regulatory Mapping](04_infrastructure_and_regulation.md)
+5. [05 — Treaty Layer, Recoverability, and Rollout](05_treaty_recoverability_rollout.md)
+6. [06 — Annexes](06_annexes.md)
+
+## Review path (recommended)
+1. `README.md` (scope/versioning)
+2. `01` → `05` (core technical/governance flow)
+3. `06_annexes.md` (templates)
+4. `full_synthesis_v0.5.md` (integrated reference)