Skip to content

Commit 1d3add8

Browse files
OneFineStarstuffOneFineStarstuff
committed
Use unittest for federated-zk docs validator checks
1 parent e8261d0 commit 1d3add8

14 files changed

Lines changed: 940 additions & 0 deletions

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

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: Federated ZK Docs Validation
2+
3+
on:
4+
push:
5+
paths:
6+
- 'FEDERATED_ZK_AI_COMPLIANCE_RESEARCH_PROGRAM_SYNTHESIS.md'
7+
- 'docs/federated-zk-compliance/**'
8+
- 'tests/test_federated_zk_validate_docs.py'
9+
- '.github/workflows/federated-zk-docs-validation.yml'
10+
pull_request:
11+
paths:
12+
- 'FEDERATED_ZK_AI_COMPLIANCE_RESEARCH_PROGRAM_SYNTHESIS.md'
13+
- 'docs/federated-zk-compliance/**'
14+
- 'tests/test_federated_zk_validate_docs.py'
15+
- '.github/workflows/federated-zk-docs-validation.yml'
16+
17+
jobs:
18+
validate-doc-links:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- name: Checkout
22+
uses: actions/checkout@v4
23+
24+
- name: Set up Python
25+
uses: actions/setup-python@v5
26+
with:
27+
python-version: '3.11'
28+
29+
- name: Run validator unit tests
30+
run: python -m unittest discover -s tests -p 'test_federated_zk_validate_docs.py'
31+
32+
- name: Validate federated-zk doc links (strict)
33+
run: python docs/federated-zk-compliance/validate_docs.py --strict

‎FEDERATED_ZK_AI_COMPLIANCE_RESEARCH_PROGRAM_SYNTHESIS.md‎

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

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

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

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

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

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

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# 03 — zk Proof Pipeline and Verifier Federation
2+
3+
## Purpose
4+
Define the cryptographic compliance lifecycle from evidence generation through supervisory verification, including federation governance.
5+
6+
## Proof Pipeline
7+
1. Canonicalize and sign evidence events.
8+
2. Build commitments for reporting windows.
9+
3. Execute zk circuits for mapped controls.
10+
4. Aggregate proofs recursively for submission efficiency.
11+
5. Verify against jurisdiction policy profiles.
12+
6. Publish evidence envelope and verifier receipts.
13+
14+
## Security Requirements
15+
- Completeness and soundness.
16+
- Non-malleability of supervisory submissions.
17+
- Domain separation across institutions and jurisdictions.
18+
- Key-rotation continuity and forward security.
19+
20+
## Verifier Federation Model
21+
- Roles: national supervisor, regional supervisor, multilateral observer.
22+
- Governance: threshold validation `(n,t)` and quorum publication.
23+
- Challenge-response: time-bounded dispute procedures with evidence replay.
24+
- Membership discipline: accession, suspension, reinstatement.
25+
26+
## Required Artifacts
27+
1. Assumption register.
28+
2. Proof-system profile matrix.
29+
3. Federation policy configuration.
30+
4. Challenge-response SOP.

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

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# 04 — Infrastructure and Regulatory Mapping
2+
3+
## Purpose
4+
Provide deployable infrastructure patterns and regulatory crosswalks for supervisory-grade AI compliance operations.
5+
6+
## Infrastructure Blueprint
7+
- Terraform modules for identity/KMS, regional GPU compute, evidence stream, and verifier gateway.
8+
- Kubernetes controls for signed image admission, policy sidecars, immutable audit exporters, and quarantine namespaces.
9+
- Regional partitioning and sovereign key custody for jurisdictional compliance.
10+
11+
## Regulatory Mapping
12+
- **EU AI Act**: risk management, traceability, incident/post-market obligations.
13+
- **Basel alignment**: model risk governance evidence and maturity indicators.
14+
- **DORA alignment**: resilience controls and continuity stress evidence.
15+
16+
## Regulator Submission Dossier
17+
1. Control crosswalk matrix.
18+
2. Proof summary and assumption register.
19+
3. Exception ledger + compensating controls.
20+
4. Continuity/resilience package.
21+
5. Independent attestation memo.
22+
23+
## Deliverables
24+
- Reference Terraform interface contracts.
25+
- Kubernetes policy baseline.
26+
- Regulator submission template pack.

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

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# 05 — Treaty Layer, Recoverability, and Rollout
2+
3+
## Purpose
4+
Define multilateral governance lifecycle, continuity metrics, and phased deployment strategy.
5+
6+
## GACP Lifecycle
7+
- **Accession**: capability declaration and conformance trial.
8+
- **Conditional membership**: bounded production participation.
9+
- **Full membership**: reciprocal equivalence rights.
10+
- **Suspension/Reinstatement**: treaty-triggered, evidence-based procedures.
11+
12+
## Recoverability Metric Pack
13+
- `RL`: reconstruction latency.
14+
- `CIS`: continuity integrity score.
15+
- `PSR`: proof survivability ratio.
16+
- `CPI`: constitutional preservation index.
17+
18+
## Rollout Phases (0–36 months)
19+
- Phase 0: standards and ontology harmonization.
20+
- Phase 1: bilateral regulator sandboxes.
21+
- Phase 2: regional federation interoperability.
22+
- Phase 3: multilateral accession and treaty pilots.
23+
24+
## Phase Exit Criteria
25+
- Verified control conformance.
26+
- Demonstrated resilience drills.
27+
- Accepted supervisory dossier outcomes.
28+
- Documented dispute-resolution performance.

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

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

‎docs/federated-zk-compliance/CHANGELOG.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Changelog — Federated ZK Compliance Docs
2+
3+
## v0.5 (current)
4+
- Introduced modular package structure and navigation entrypoint.
5+
- Added focused workstream modules (`01`–`06`).
6+
- Added integrated full synthesis reference.
7+
- Added package README and versioning guidance.
8+
9+
## Change control rules
10+
- Increment **patch** for editorial clarifications.
11+
- Increment **minor** for new module sections, templates, or governance artifacts.
12+
- Increment **major** for taxonomy changes (e.g., architecture layers, formal predicate semantics, or treaty lifecycle model changes).

‎docs/federated-zk-compliance/README.md‎

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

0 commit comments

Comments
 (0)