Project Tapestry: First 30 Minutes Wiki

Complete Markdown

# Project Tapestry: First 30 Minutes Wiki

> A fast, source-anchored onboarding path through the Tapestry repository: what the project is, the working consortium-training PoC, the technical documentation system, and exactly where to go after the first half hour.

## Context Links

- [Agent index](https://grok-wiki.com/public/wiki/the-ai-alliance-tapestry-4a40b7cf9eb6/llms.txt)
- [Human interactive wiki](https://grok-wiki.com/public/wiki/the-ai-alliance-tapestry-4a40b7cf9eb6)
- [GitHub repository](https://github.com/The-AI-Alliance/tapestry)

## Repository Metadata

- Repository: The-AI-Alliance/tapestry

- Generated: 2026-05-21T01:41:40.140Z
- Updated: 2026-05-21T21:33:19.929Z
- Runtime: Grok CLI
- Format: First 30 Minutes
- Pages: 6

## Page Index

- 01. [Start Here](https://grok-wiki.com/public/wiki/the-ai-alliance-tapestry-4a40b7cf9eb6/pages/01-start-here.md) - What this repo actually contains, the single fastest read order, the five entry points to open first, and the core vocabulary (N+1 outcome, sovereign artifact, governed delta, quality floor, anti-capture cap) a new reader must know.
- 02. [Setup, Tests & Demo in Under 10 Minutes](https://grok-wiki.com/public/wiki/the-ai-alliance-tapestry-4a40b7cf9eb6/pages/02-setup-tests-demo-in-under-10-minutes.md) - Exact commands that work: uv + make one-time-setup, the five most useful Makefile targets, how to run the consortium demo, where tests live, and the two files you edit to change behavior on first run.
- 03. [The N+1 Consortium Training Model](https://grok-wiki.com/public/wiki/the-ai-alliance-tapestry-4a40b7cf9eb6/pages/03-the-n-1-consortium-training-model.md) - What the PoC actually proves: one governed shared base + N persistent sovereign artifacts, raw data never leaves the node, only weight deltas cross the boundary, and the quality-floor + max-weight anti-capture rules that the coordinator enforces on every round.
- 04. [Inside the PoC: Six Python Modules](https://grok-wiki.com/public/wiki/the-ai-alliance-tapestry-4a40b7cf9eb6/pages/04-inside-the-poc-six-python-modules.md) - Line-by-line reality of the working code: TinyCausalModel, SovereignTrainingNode local training loop and artifact retention, ConsortiumCoordinator.run_round delta application, ContributionPolicy iterative capping, the exact messages, and the one test file that locks the invariants.
- 05. [Technical Documentation System](https://grok-wiki.com/public/wiki/the-ai-alliance-tapestry-4a40b7cf9eb6/pages/05-technical-documentation-system.md) - How the real documentation is organized: the TVA phased methodology (0-5), the eight ADRs that actually constrain the design, the anti-capture principle, the eight work-group charters, and the difference between docs/ (published site) and tech-docs/ (source of truth).
- 06. [After 30 Minutes: Your Map Forward](https://grok-wiki.com/public/wiki/the-ai-alliance-tapestry-4a40b7cf9eb6/pages/06-after-30-minutes-your-map-forward.md) - What you now know and the three concrete next actions: pick one ADR or work-group charter to read deeply, run and modify the demo with your own corpus, and the exact contribution workflow (PR templates, license stack, AGENTS.md conventions) for this repository.

## Source File Index

- `.github/PULL_REQUEST_TEMPLATE/general_code_pr.md`
- `AGENTS.md`
- `docs/_config.yml`
- `docs/contributing.markdown`
- `docs/index.markdown`
- `examples/consortium_training_demo.py`
- `Makefile`
- `pyproject.toml`
- `README.md`
- `src/tapestry/training/consortium/coordinator.py`
- `src/tapestry/training/consortium/messages.py`
- `src/tapestry/training/consortium/model.py`
- `src/tapestry/training/consortium/node.py`
- `src/tapestry/training/consortium/policy.py`
- `src/tapestry/training/consortium/README.md`
- `src/tapestry/training/consortium/types.py`
- `src/tests/tapestry/training/consortium/test_consortium_training.py`
- `tech-docs/architecture/0-tva-methodology.md`
- `tech-docs/architecture/decisions/adr-001-core-plus-sovereign.md`
- `tech-docs/architecture/decisions/adr-002-consortium-training.md`
- `tech-docs/architecture/decisions/adr-007-architecture-comparison.md`
- `tech-docs/architecture/decisions/adr-008-data-sovereignty.md`
- `tech-docs/architecture/README.md`
- `tech-docs/governance/anti-capture-principle.md`
- `tech-docs/README.md`
- `tech-docs/reference/training-approaches.md`
- `tech-docs/strategic-plan/README.md`
- `tech-docs/work-groups/README.md`

---

## 01. Start Here

> What this repo actually contains, the single fastest read order, the five entry points to open first, and the core vocabulary (N+1 outcome, sovereign artifact, governed delta, quality floor, anti-capture cap) a new reader must know.

- Page Markdown: https://grok-wiki.com/public/wiki/the-ai-alliance-tapestry-4a40b7cf9eb6/pages/01-start-here.md
- Generated: 2026-05-21T01:40:48.631Z

### Source Files

- `README.md`
- `AGENTS.md`
- `src/tapestry/training/consortium/README.md`
- `pyproject.toml`
- `docs/index.markdown`
- `tech-docs/README.md`

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [README.md](README.md)
- [AGENTS.md](AGENTS.md)
- [pyproject.toml](pyproject.toml)
- [docs/index.markdown](docs/index.markdown)
- [tech-docs/README.md](tech-docs/README.md)
- [src/tapestry/training/consortium/README.md](src/tapestry/training/consortium/README.md)
- [src/tapestry/training/consortium/__init__.py](src/tapestry/training/consortium/__init__.py)
- [src/tapestry/training/consortium/policy.py](src/tapestry/training/consortium/policy.py)
- [src/tapestry/training/consortium/messages.py](src/tapestry/training/consortium/messages.py)
- [src/tapestry/training/consortium/coordinator.py](src/tapestry/training/consortium/coordinator.py)
- [src/tapestry/training/consortium/node.py](src/tapestry/training/consortium/node.py)
- [examples/consortium_training_demo.py](examples/consortium_training_demo.py)
- [src/tests/tapestry/training/consortium/test_consortium_training.py](src/tests/tapestry/training/consortium/test_consortium_training.py)
- [Makefile](Makefile)

</details>

# Start Here

This page orients anyone opening the Tapestry repository for the first time. It states exactly what the repo contains today, the single fastest sequence of files to read, the five concrete entry points to open first, and the five core terms that appear in every design document and in the running code. Read this, open the five files, and you will know what the project is building and how the pieces fit.

The repository is the technical home for Project Tapestry. It holds the Python implementation of the consortium-training model, the full set of architectural decision records and requirements analysis, contributor tooling, and the sources for the published technical website.

## What This Repository Actually Contains

- A Python package (`src/tapestry/`) whose only fully implemented slice is the consortium-training proof-of-concept under `training/consortium/`.
- A large body of design documentation under `tech-docs/` that records the TVA phased analysis (stakeholder map through architectural options), numbered ADRs, the anti-capture governance principle, and work-group charters.
- A Jekyll/Just-the-Docs website under `docs/` that is published to GitHub Pages.
- Tests, one runnable end-to-end demo, a Makefile that drives setup/test/format/lint/type-check/view-local, and `pyproject.toml` that pins Python ≥ 3.12 and the tool chain (uv, torch, black, ruff, ty, pytest).
- No production training stack, no full data-governance layer, and no sovereign-alignment pipeline yet; those subsystems exist only as empty package directories.

Sources: [README.md:160-179](), [AGENTS.md:39-53](), [pyproject.toml:1-52](), [src/tapestry/training/consortium/README.md:23-34]()

## Fastest Read Order (First 30 Minutes)

1. `README.md` – top-level purpose, quick paths, licenses, and contributor instructions.
2. `AGENTS.md` – precise repository map, “Where To Look First”, Python layout, and non-negotiable working conventions.
3. `tech-docs/README.md` (then `tech-docs/architecture/README.md`) – how the design artifacts are organized and which document answers which question.
4. `src/tapestry/training/consortium/README.md` – the only code that actually runs; it defines the N+1 outcome and lists the five invariants the PoC demonstrates.
5. `examples/consortium_training_demo.py` – the 100-line script that prints the N+1 outcome and shows the governed-delta loop in action.

After these five, either run the demo or open the three implementation files (`policy.py`, `node.py`, `coordinator.py`) or the first TVA phase documents.

## Five Entry Points to Open First

| File | Why it is first | What you will actually find |
|------|-----------------|-------------------------------|
| [README.md](README.md) | Single source of “what is this repo and how do I start?” | Project banner, quick paths, setup commands, project structure diagram, licenses, and links to the live site. |
| [AGENTS.md](AGENTS.md) | The repo’s own navigation and rule book | Repository map, “Where To Look First” list, tech-docs taxonomy, Python package layout, make targets, formatting/linting rules, and the explicit instruction to treat governance docs as load-bearing. |
| [tech-docs/README.md](tech-docs/README.md) | Design authority index | Table of every major design artifact (TVA phases 0–5, ADRs, governance, work-groups, strategic plan) with one-sentence descriptions of each. |
| [src/tapestry/training/consortium/README.md](src/tapestry/training/consortium/README.md) | The only executable slice explained in its own words | Definition of the N+1 model outcome, the five invariants the PoC preserves, and the module-by-module responsibility table. |
| [examples/consortium_training_demo.py](examples/consortium_training_demo.py) | See the concepts run | 100 lines that instantiate three nodes, a policy with quality floor and cap, run three rounds, and literally print “N+1 outcome: 1 shared base … N sovereign model artifacts retained”. |

Sources: [AGENTS.md:16-24](), [README.md:13-35](), [src/tapestry/training/consortium/README.md:1-12](), [examples/consortium_training_demo.py:54-103]()

## Core Vocabulary (Five Terms You Will Meet Everywhere)

These terms are not marketing slogans; they are the precise names used in the code and in the ADRs.

### N+1 outcome
One governed shared base model plus N participant-owned sovereign model artifacts. The coordinator evolves the single shared base; every node that participates ends the round with its own full model state that it alone owns and can take away.

Sources: [src/tapestry/training/consortium/README.md:4-8](), [src/tapestry/training/consortium/__init__.py:4-6](), [examples/consortium_training_demo.py:99-102]()

### Sovereign artifact (`SovereignModelArtifact`)
The complete model state a node produces after running its local training cycle on its private corpus. The artifact is stored in `coordinator.sovereign_artifacts` and in the node’s own `latest_artifact`; the raw corpus and the full model never leave the node.

Sources: [src/tapestry/training/consortium/messages.py:12-20](), [src/tapestry/training/consortium/node.py:61-68](), [src/tapestry/training/consortium/coordinator.py:44-45]()

### Governed delta (`weight_delta` inside `SovereignContribution`)
The difference between the model the node started the round with and the model it finished with. Only this delta (plus a quality score and token count) is sent to the coordinator. The coordinator never sees raw data or full models—only deltas that survive the policy.

Sources: [src/tapestry/training/consortium/messages.py:24-32](), [src/tapestry/training/consortium/node.py:58](), [src/tapestry/training/consortium/coordinator.py:55-58]()

### Quality floor
The `quality_floor` parameter of `ContributionPolicy`. Any node whose reported `quality_score` is below the floor is rejected for that round and contributes zero weight. The floor is the first anti-degradation control.

Sources: [src/tapestry/training/consortium/policy.py:14-25](), [src/tapestry/training/consortium/coordinator.py:48-52](), [examples/consortium_training_demo.py:68]()

### Anti-capture cap (`max_node_weight`)
The second parameter of `ContributionPolicy`. Even if a node has the highest quality score, its influence on the integrated base is capped at this fraction (commonly 0.5 in the demo). The cap is an explicit governance mechanism, not an optimizer heuristic.

Sources: [src/tapestry/training/consortium/policy.py:17-48](), [src/tapestry/training/consortium/README.md:10](), [examples/consortium_training_demo.py:69]()

## The Consortium Training Proof of Concept

The directory `src/tapestry/training/consortium/` contains the only running code. It uses a 16-line `TinyCausalModel` (embedding + linear projection) so that tests and the demo finish in milliseconds. The important objects are:

- `SovereignTrainingNode` – receives the current base, trains locally, retains a `SovereignModelArtifact`, returns a `SovereignContribution` containing only the delta.
- `ConsortiumCoordinator` – calls every node, asks the `ContributionPolicy` for weights, applies the weighted deltas, and returns a `ConsortiumRoundResult`.
- `ContributionPolicy.weights()` – enforces the quality floor then repeatedly normalizes and caps until no node exceeds `max_node_weight`.

A single round therefore produces the N+1 outcome by construction.

```text
Node (sovereign corpus)          Coordinator
  |                                   |
  v                                   v
local train (never shares corpus)   policy decides
  |                                   |
  +-- keeps full SovereignArtifact    +-- accepts/rejects + caps
  |                                   |
  +-- sends only weight_delta ----------> weighted sum applied to base
                                          |
                                          v
                                    new shared base (1)
                                          ^
                                    N sovereign artifacts retained
```

Sources: [src/tapestry/training/consortium/coordinator.py:38-66](), [src/tapestry/training/consortium/node.py:51-78](), [src/tapestry/training/consortium/policy.py:22-59]()

## Development Workflow (What the Makefile Actually Does)

All day-to-day work is driven by the Makefile:

- `make one-time-setup` – installs uv and creates the environment.
- `make tests` (or `make unit-tests`) – runs discovery from `src/` using the pytest configuration in `pyproject.toml`.
- `make format`, `make lint`, `make type-check` – the three tools (black, ruff+pylint, ty) that must pass before any PR.
- `make before-pr` – runs the whole gate in one command.

Python sources live under `src/`, tests mirror them under `src/tests/`, and every new module must be accompanied by matching tests. AGENTS.md is the authoritative statement of these rules.

Sources: [Makefile:43-60](), [AGENTS.md:57-73](), [pyproject.toml:28-53]()

## Design and Governance Context

All architecture work follows the TVA methodology documented in `tech-docs/architecture/`. The six phases (0–5) move from stakeholder map through pain points, value propositions, design goals, and finally an explicit options analysis. Design Goal 3 (anti-capture) is treated as a load-bearing constraint, not a nice-to-have; the `max_node_weight` cap in the PoC is the first executable expression of that goal. Governance documents under `tech-docs/governance/` are therefore required reading before any new architectural proposal.

Sources: [tech-docs/README.md:1-36](), [tech-docs/architecture/README.md:1-15](), [src/tapestry/training/consortium/policy.py:10-11]()

## Next Concrete Steps

1. `python examples/consortium_training_demo.py` – watch the N+1 outcome print.
2. `make one-time-setup && make tests` – verify the environment.
3. Open `src/tapestry/training/consortium/policy.py` and change `max_node_weight` or `quality_floor`; re-run the demo.
4. Read `tech-docs/architecture/0-tva-methodology.md` and `4-design-goals.md` when you need the “why” behind the code.

The N+1 consortium loop and its governed policy are the executable heart of the current implementation. Everything else in the repository exists to specify, justify, or eventually replace it.

Sources: [examples/consortium_training_demo.py:99-103](), [src/tapestry/training/consortium/coordinator.py:38-66]()

---

## 02. Setup, Tests & Demo in Under 10 Minutes

> Exact commands that work: uv + make one-time-setup, the five most useful Makefile targets, how to run the consortium demo, where tests live, and the two files you edit to change behavior on first run.

- Page Markdown: https://grok-wiki.com/public/wiki/the-ai-alliance-tapestry-4a40b7cf9eb6/pages/02-setup-tests-demo-in-under-10-minutes.md
- Generated: 2026-05-21T01:41:05.656Z

### Source Files

- `Makefile`
- `pyproject.toml`
- `examples/consortium_training_demo.py`
- `src/tests/tapestry/training/consortium/test_consortium_training.py`
- `src/tapestry/training/consortium/README.md`

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [Makefile](Makefile)
- [pyproject.toml](pyproject.toml)
- [README.md](README.md)
- [AGENTS.md](AGENTS.md)
- [examples/consortium_training_demo.py](examples/consortium_training_demo.py)
- [src/tests/tapestry/training/consortium/test_consortium_training.py](src/tests/tapestry/training/consortium/test_consortium_training.py)
- [src/tapestry/training/consortium/README.md](src/tapestry/training/consortium/README.md)
- [src/tapestry/training/consortium/policy.py](src/tapestry/training/consortium/policy.py)
- [src/tapestry/training/consortium/coordinator.py](src/tapestry/training/consortium/coordinator.py)
- [src/tapestry/training/consortium/model.py](src/tapestry/training/consortium/model.py)
- [src/tapestry/training/consortium/__init__.py](src/tapestry/training/consortium/__init__.py)
</details>

# Setup, Tests & Demo in Under 10 Minutes

This page gives the exact, verified commands to go from a fresh clone to a running consortium-training demo and green tests in well under 10 minutes on a machine with Python 3.12+. It names the five Makefile targets you will use repeatedly, shows how to execute the N+1 proof-of-concept, states precisely where tests live, and identifies the two files that control observable behavior on first customization.

All claims below are taken directly from the active build configuration, Makefile recipes, test code, and demo source rather than secondary documentation.

## Prerequisites

- Python 3.12 or newer
- `uv` (https://docs.astral.sh/uv/)
- GNU make (standard on macOS and Linux)
- A working internet connection for the first `uv pip install` (pulls torch, numpy, and dev tools)

No other global Python packages or system libraries are required.

## One-Time Setup

Run this single command from the repository root:

```shell
make one-time-setup
```

This target expands to three steps (sources: [Makefile:169-180]()):

1. `install-uv` — checks for `uv` in PATH and prints installation help if missing.
2. `uv-venv` — creates a `.venv` directory if none exists.
3. `install-dev-dependencies` — runs `uv pip install -e ".[dev]"`.

The dev extras (defined in [pyproject.toml:14-22]()) pull in pytest, ruff, pylint, black, and ty plus the runtime requirements (torch, numpy).

After the command succeeds you normally do **not** need to `source .venv/bin/activate`; every subsequent `make` target and `uv run` invocation uses the virtual environment automatically. The Makefile prints a reminder only for the rare case where a direct `python` or `pytest` call is made outside `uv run`.

Sources: [Makefile:166-199](), [pyproject.toml:1-33](), [README.md:65-95]()

## Five Most Useful Makefile Targets

These five targets cover 95 % of day-to-day work after the initial setup:

| Target                        | What it does                                                                 | Underlying command (from Makefile)                          |
|-------------------------------|-----------------------------------------------------------------------------|-------------------------------------------------------------|
| `make help`                   | Prints the full target list and short descriptions.                         | Built-in info target                                        |
| `make tests` (or `make unit-tests`) | Runs the entire test suite quietly.                                         | `cd src && uv run pytest tests -q`                          |
| `make consortium-demo`        | Executes the runnable N+1 consortium proof-of-concept.                      | `uv run python examples/consortium_training_demo.py`        |
| `make consortium-tests`       | Runs only the consortium-training tests (fast feedback loop).               | `uv run pytest src/tests/tapestry/training/consortium -q`   |
| `make before-pr` (or `make flt`) | Formats, lints, type-checks, and tests — the pre-PR gate.                   | `format-lint-type-check && tests`                           |

Other frequently used shortcuts: `make format`, `make lint`, `make type-check`, `make clean`.

All targets are defined in [Makefile:121-164](). The `uv run` prefix guarantees the correct interpreter and installed packages without manual activation.

## Running the Consortium Training Demo

```shell
make consortium-demo
# or
uv run python examples/consortium_training_demo.py
```

The script ([examples/consortium_training_demo.py:54-107]()):

- Instantiates a tiny causal model (`TinyCausalModel`).
- Creates a `ConsortiumCoordinator` with a `ContributionPolicy(quality_floor=0.75, max_node_weight=0.5)`.
- Spawns three sovereign nodes (vietnam, switzerland, india) each carrying a tiny domain-specific "corpus" and a self-reported quality score.
- Runs three rounds: each node performs local continued pretraining on its private data, emits only a weight delta, the coordinator applies the policy, accepts or rejects the delta, and updates the shared base.
- Prints per-round acceptance, weights, and the final count of retained sovereign artifacts.

The demo demonstrates the core invariant described in the module README: one governed shared base plus N participant-owned sovereign model artifacts ([src/tapestry/training/consortium/README.md:1-12](), [src/tapestry/training/consortium/coordinator.py:38-60](), [src/tapestry/training/consortium/__init__.py:9-29]()`).

Typical first-run output ends with:

```
N+1 outcome:
  1 shared base model evolved by governed contributions
  3 sovereign model artifacts retained
```

Sources: [examples/consortium_training_demo.py:1-108](), [src/tapestry/training/consortium/coordinator.py:20-60](), [src/tapestry/training/consortium/model.py:9-19]()

## Where Tests Live

Tests mirror the package layout under `src/tests/`:

- Full suite: `src/tests/`
- Consortium-specific module: `src/tests/tapestry/training/consortium/test_consortium_training.py`

Key configuration ([pyproject.toml:28-33]()):

```toml
[tool.pytest.ini_options]
testpaths = ["src/tests"]
pythonpath = ["src"]
```

The four tests in the consortium module verify:

- `SovereignTrainingNode` returns both an artifact and a non-zero weight delta.
- `ContributionPolicy` drops contributions below the quality floor and caps any single node.
- `ConsortiumCoordinator` produces the N+1 outcome (updated base + one artifact per node).
- A round containing only low-quality contributions leaves the shared base unchanged.

Run targeted tests with:

```shell
make consortium-tests
# or
uv run pytest src/tests/tapestry/training/consortium -q
```

Sources: [src/tests/tapestry/training/consortium/test_consortium_training.py:36-153](), [Makefile:124-137](), [pyproject.toml:28-33]()

## The Two Files to Edit to Change Behavior on First Run

After the first successful `make consortium-demo`, the two files that give the highest-leverage customization are:

1. **examples/consortium_training_demo.py** — change the input data, quality scores, policy thresholds, or round count.

   ```python
   # examples/consortium_training_demo.py:23-47
   DOMAIN_CORPORA: dict[str, list[str]] = {
       "vietnam": ["Vietnamese public services require local legal context.", ...],
       ...
   }
   QUALITY_SCORES = {"vietnam": 0.90, "switzerland": 0.86, "india": 0.88}

   # ...
   coordinator = ConsortiumCoordinator(
       base_model=base_model,
       contribution_policy=ContributionPolicy(
           quality_floor=0.75,
           max_node_weight=0.5,
       ),
   )
   ```

   Edit the dicts, the `ContributionPolicy(...)` constructor call, `run_demo(rounds=..., seed=...)`, or the per-node `local_epochs`/`lr` values to alter what the demo prints and how the governance behaves.

2. **src/tapestry/training/consortium/policy.py** — change the default governance rules that every consumer of `ContributionPolicy` inherits.

   ```python
   # src/tapestry/training/consortium/policy.py:14-20
   def __init__(self, quality_floor: float = 0.0, max_node_weight: float = 1.0) -> None:
       ...
       self.quality_floor = quality_floor
       self.max_node_weight = max_node_weight
   ```

   The `weights()` method ([policy.py:22-64]()) implements the floor filter plus iterative anti-capture capping. Changing the defaults or the normalization/capping logic here immediately affects both the demo and all unit tests that construct the policy.

These two files are the entire "first 30 seconds of experimentation" surface. Deeper changes (node training loop, `TinyCausalModel` architecture, message shapes) come after you have verified behavior with the demo and the four existing tests.

Sources: [examples/consortium_training_demo.py:23-48,67-70](), [src/tapestry/training/consortium/policy.py:6-65](), [src/tapestry/training/consortium/coordinator.py:27-29]()

## Next Steps

- Run `make before-pr` before any pull request.
- Add new sovereign nodes or corpora by extending the demo script; keep tests in the matching `src/tests/tapestry/training/consortium/` directory.
- Read `src/tapestry/training/consortium/README.md` for the architectural invariants the PoC is intended to protect.

With `make one-time-setup`, the five targets above, the demo command, the known test location, and the two customization files you now have a complete, reproducible 10-minute on-ramp into the Tapestry consortium-training prototype.

Sources: [Makefile:131-133]()

---

## 03. The N+1 Consortium Training Model

> What the PoC actually proves: one governed shared base + N persistent sovereign artifacts, raw data never leaves the node, only weight deltas cross the boundary, and the quality-floor + max-weight anti-capture rules that the coordinator enforces on every round.

- Page Markdown: https://grok-wiki.com/public/wiki/the-ai-alliance-tapestry-4a40b7cf9eb6/pages/03-the-n-1-consortium-training-model.md
- Generated: 2026-05-21T01:40:15.538Z

### Source Files

- `src/tapestry/training/consortium/README.md`
- `examples/consortium_training_demo.py`
- `tech-docs/architecture/decisions/adr-002-consortium-training.md`
- `tech-docs/architecture/decisions/adr-001-core-plus-sovereign.md`
- `tech-docs/architecture/decisions/adr-008-data-sovereignty.md`
- `tech-docs/reference/training-approaches.md`

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [src/tapestry/training/consortium/README.md](src/tapestry/training/consortium/README.md)
- [examples/consortium_training_demo.py](examples/consortium_training_demo.py)
- [src/tapestry/training/consortium/__init__.py](src/tapestry/training/consortium/__init__.py)
- [src/tapestry/training/consortium/coordinator.py](src/tapestry/training/consortium/coordinator.py)
- [src/tapestry/training/consortium/node.py](src/tapestry/training/consortium/node.py)
- [src/tapestry/training/consortium/policy.py](src/tapestry/training/consortium/policy.py)
- [src/tapestry/training/consortium/messages.py](src/tapestry/training/consortium/messages.py)
- [src/tests/tapestry/training/consortium/test_consortium_training.py](src/tests/tapestry/training/consortium/test_consortium_training.py)
- [tech-docs/architecture/decisions/adr-002-consortium-training.md](tech-docs/architecture/decisions/adr-002-consortium-training.md)
- [tech-docs/architecture/decisions/adr-001-core-plus-sovereign.md](tech-docs/architecture/decisions/adr-001-core-plus-sovereign.md)
- [tech-docs/architecture/decisions/adr-008-data-sovereignty.md](tech-docs/architecture/decisions/adr-008-data-sovereignty.md)
- [tech-docs/reference/training-approaches.md](tech-docs/reference/training-approaches.md)

</details>

# The N+1 Consortium Training Model

The N+1 Consortium Training Model is the concrete outcome proven by Tapestry's consortium-training proof of concept. It consists of **one governed shared base model** that evolves through controlled contributions plus **N persistent sovereign model artifacts** that each participant node owns and retains. Raw training data never leaves its originating node; only weight deltas and a quality score cross the coordinator boundary. The coordinator applies a quality floor and a per-node maximum-weight cap on every round before any integration occurs.

This pattern directly addresses Tapestry's dual requirements: frontier-class capability through a shared base, and cultural/institutional sovereignty through participant-owned layers. The PoC is deliberately minimal (a tiny causal model, local epochs on encoded tokens) yet verifies the architectural invariants described in the ADRs. It does not claim production scale, formal privacy guarantees, or a full post-training pipeline.

## The N+1 Outcome

The PoC maintains exactly two classes of persistent artifacts after each round:

- The **shared base** (evolved by the coordinator from accepted, weighted deltas).
- One **sovereign artifact per node** (full model state after local training, retained by both the node and the coordinator's `sovereign_artifacts` registry).

This is the literal "N+1" the package README highlights: one base + N sovereigns. Each sovereign artifact records the node's jurisdiction, training stage, final state, and local metrics. The node keeps its own copy (`latest_artifact`); the coordinator keeps a registry so the consortium can audit participation without owning the data.

**Sources:** [src/tapestry/training/consortium/README.md:4-11](src/tapestry/training/consortium/README.md), [src/tapestry/training/consortium/coordinator.py:44-45](src/tapestry/training/consortium/coordinator.py), [src/tests/tapestry/training/consortium/test_consortium_training.py:114-115](src/tests/tapestry/training/consortium/test_consortium_training.py)

## Data Never Leaves the Node

Sovereign corpora are supplied only to the `SovereignTrainingNode` constructor and used exclusively inside `_build_dataloader` and `_train_locally`. The `SovereignContribution` dataclass that travels to the coordinator contains:

- `weight_delta` (state dict difference)
- `quality_score`
- `token_count` (an integer, not the tokens)
- `metrics`

No raw text, no token sequences, and no gradients tied to individual examples ever leave the node. The demo encodes its small domain corpora locally into integer lists before node construction; those lists never appear in any message or coordinator state.

**Sources:** [src/tapestry/training/consortium/node.py:49-58](src/tapestry/training/consortium/node.py), [src/tapestry/training/consortium/messages.py:23-32](src/tapestry/training/consortium/messages.py), [examples/consortium_training_demo.py:23-39](examples/consortium_training_demo.py)

## Only Weight Deltas Cross the Boundary

Each node receives the current shared base state, loads it, runs local continued pretraining, then computes:

```python
delta = {name: sovereign_state[name] - starting_state[name] for name in starting_state}
```

Only this delta (plus the quality score) is packaged into `SovereignContribution` and returned. The coordinator never sees the node's full model parameters except as an opaque artifact it stores for the registry. Integration happens solely through `_apply_weighted_deltas`, which adds the scaled deltas to the previous base.

This design matches the consortium-training definition in the reference material: infrequent, WAN-tolerant weight deltas rather than per-step gradients or raw data movement.

**Sources:** [src/tapestry/training/consortium/node.py:58](src/tapestry/training/consortium/node.py), [src/tapestry/training/consortium/coordinator.py:55-57](src/tapestry/training/consortium/coordinator.py), [tech-docs/reference/training-approaches.md:69-81](tech-docs/reference/training-approaches.md)

## The Contribution Policy: Quality Floor + Max-Weight Anti-Capture

The `ContributionPolicy` is the governance mechanism applied on every round. Its `weights()` method:

1. Drops any node whose `quality_score < quality_floor` (or ≤ 0).
2. Normalizes the remaining scores.
3. Iteratively caps any single node's share at `max_node_weight`, re-normalizing the residual mass until no node exceeds the cap.
4. Returns the final normalized weights for only the accepted nodes.

The coordinator calls this before `_apply_weighted_deltas`. Rejected nodes still receive a sovereign artifact (they trained locally), but their deltas do not affect the shared base.

Default demo values are `quality_floor=0.75`, `max_node_weight=0.5`. Tests explicitly verify that weak contributions are rejected and that a dominant node cannot exceed its cap.

**Sources:** [src/tapestry/training/consortium/policy.py:22-59](src/tapestry/training/consortium/policy.py), [src/tapestry/training/consortium/coordinator.py:48-52](src/tapestry/training/consortium/coordinator.py), [src/tests/tapestry/training/consortium/test_consortium_training.py:65-79](src/tests/tapestry/training/consortium/test_consortium_training.py)

## How a Round Executes

```mermaid
sequenceDiagram
    participant C as ConsortiumCoordinator
    participant N as SovereignTrainingNode (per node)
    Note over N: sovereign_corpus stays local
    C->>N: run_sovereign_cycle(round, base_state)
    N->>N: load base, train locally, keep full SovereignModelArtifact
    N-->>C: SovereignContribution {weight_delta, quality_score, token_count}
    C->>C: policy.weights() → accepted + capped weights
    C->>C: _apply_weighted_deltas only on accepted deltas
    C-->>N: next base_state for following round
```

The loop is deliberately simple: nodes train independently between syncs; the coordinator performs a single governed aggregation step; both sides retain their artifacts. This is the minimal executable demonstration of the core-plus-sovereign pattern (shared base + sovereign layers) and the consortium training paradigm (few large sovereign nodes, weight-delta exchange, consortium governance).

**Sources:** [src/tapestry/training/consortium/coordinator.py:38-66](src/tapestry/training/consortium/coordinator.py), [src/tapestry/training/consortium/node.py:51-78](src/tapestry/training/consortium/node.py)

## Entry Points for Readers

- Run the executable demonstration: `python examples/consortium_training_demo.py`
- Read the package contract: `src/tapestry/training/consortium/README.md`
- Inspect the tested invariants: `src/tests/tapestry/training/consortium/test_consortium_training.py`
- Understand the framing: ADR-002 (consortium training), ADR-001 (core-plus-sovereign), ADR-008 (data sovereignty categories)

The PoC is intentionally scoped. It proves the N+1 shape, the data-locality invariant, delta-only exchange, and the enforceable policy rules; it does not implement production governance, secure aggregation, or full-scale training.

## Summary

The consortium-training PoC establishes that a single governed shared base plus per-node persistent sovereign artifacts can be produced while keeping raw data local and enforcing quality and anti-capture controls on every round through nothing more than weight deltas and a small policy object. These properties are not aspirational; they are the observed, tested behavior of the code in `SovereignTrainingNode`, `ConsortiumCoordinator`, and `ContributionPolicy`.

**Sources:** [src/tapestry/training/consortium/__init__.py:3-7](src/tapestry/training/consortium/__init__.py), [src/tapestry/training/consortium/README.md:23-34](src/tapestry/training/consortium/README.md)

---

## 04. Inside the PoC: Six Python Modules

> Line-by-line reality of the working code: TinyCausalModel, SovereignTrainingNode local training loop and artifact retention, ConsortiumCoordinator.run_round delta application, ContributionPolicy iterative capping, the exact messages, and the one test file that locks the invariants.

- Page Markdown: https://grok-wiki.com/public/wiki/the-ai-alliance-tapestry-4a40b7cf9eb6/pages/04-inside-the-poc-six-python-modules.md
- Generated: 2026-05-21T01:41:40.138Z

### Source Files

- `src/tapestry/training/consortium/coordinator.py`
- `src/tapestry/training/consortium/node.py`
- `src/tapestry/training/consortium/policy.py`
- `src/tapestry/training/consortium/model.py`
- `src/tapestry/training/consortium/messages.py`
- `src/tapestry/training/consortium/types.py`
- `src/tests/tapestry/training/consortium/test_consortium_training.py`
- `examples/consortium_training_demo.py`

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [src/tapestry/training/consortium/model.py](src/tapestry/training/consortium/model.py)
- [src/tapestry/training/consortium/node.py](src/tapestry/training/consortium/node.py)
- [src/tapestry/training/consortium/coordinator.py](src/tapestry/training/consortium/coordinator.py)
- [src/tapestry/training/consortium/policy.py](src/tapestry/training/consortium/policy.py)
- [src/tapestry/training/consortium/messages.py](src/tapestry/training/consortium/messages.py)
- [src/tapestry/training/consortium/types.py](src/tapestry/training/consortium/types.py)
- [src/tapestry/training/consortium/__init__.py](src/tapestry/training/consortium/__init__.py)
- [src/tapestry/training/consortium/README.md](src/tapestry/training/consortium/README.md)
- [src/tests/tapestry/training/consortium/test_consortium_training.py](src/tests/tapestry/training/consortium/test_consortium_training.py)
- [examples/consortium_training_demo.py](examples/consortium_training_demo.py)
</details>

# Inside the PoC: Six Python Modules

This page provides a line-by-line examination of the working consortium-training proof-of-concept (PoC) in `src/tapestry/training/consortium/`. It is the only implemented training slice in the repository and directly embodies the N+1 outcome described in the ADRs: one governed shared base model plus N participant-owned sovereign model artifacts. Nodes train locally on sovereign corpora and return only weight deltas; the coordinator applies governed weights before integration.

The PoC is deliberately minimal—`torch` only, no distributed runtime, no production data pipelines—so that the core invariants (sovereign retention, delta-only sharing, quality floor, anti-capture cap, and unchanged base on total rejection) can be read, executed, and tested in minutes.

## The Six Modules at a Glance

| File | Primary Class / Type | Responsibility |
|------|----------------------|----------------|
| `model.py` | `TinyCausalModel` | Minimal next-token `nn.Module` used by every test and demo. |
| `node.py` | `SovereignTrainingNode` | Local continued-pretraining loop; retains full sovereign artifact; emits delta only. |
| `coordinator.py` | `ConsortiumCoordinator` | Orchestrates one round, calls nodes, invokes policy, applies weighted deltas. |
| `policy.py` | `ContributionPolicy` | Quality-floor filter + iterative per-node weight capping (anti-capture). |
| `messages.py` | Dataclasses + `ModelState` alias | Frozen records for artifacts, contributions, cycle results, round results. |
| `types.py` | Re-exports | Backward-compatibility shim; new code imports from `messages`. |

All public symbols are re-exported by `src/tapestry/training/consortium/__init__.py`.

## TinyCausalModel

```python:12:19:src/tapestry/training/consortium/model.py
class TinyCausalModel(nn.Module):
    """Small next-token model used to keep the PoC fast and testable."""

    def __init__(self, vocab_size: int = 256, hidden_size: int = 32) -> None:
        super().__init__()
        self.embedding = nn.Embedding(vocab_size, hidden_size)
        self.proj = nn.Linear(hidden_size, vocab_size)

    def forward(self, input_ids: torch.Tensor) -> torch.Tensor:
        """Return next-token logits for ``(batch, sequence)`` token ids."""
        return self.proj(self.embedding(input_ids))
```

The model is intentionally tiny (default hidden size 32) so that a full local epoch on a handful of sequences completes in milliseconds. Every node and the coordinator start from an identical copy of this architecture.

Sources: [src/tapestry/training/consortium/model.py:9-20]()

## SovereignTrainingNode – Local Training Loop and Artifact Retention

`SovereignTrainingNode` owns the sovereign side of the contract. On each round it receives the current base state, trains locally, keeps the resulting full model, and returns a delta plus metadata.

Key excerpts:

```python:51:78:src/tapestry/training/consortium/node.py
    def run_sovereign_cycle(self, round_num: int, base_state: ModelState) -> SovereignCycleResult:
        """Run local continued pretraining and return artifact plus delta."""
        starting_state = {name: tensor.clone() for name, tensor in base_state.items()}
        self.model.load_state_dict(starting_state)

        avg_loss = self._train_locally()
        sovereign_state = {name: tensor.clone() for name, tensor in self.model.state_dict().items()}
        delta = {name: sovereign_state[name] - starting_state[name] for name in starting_state}

        ...
        artifact = SovereignModelArtifact(...)
        self.latest_artifact = artifact
        ...
        return SovereignCycleResult(artifact=artifact, contribution=contribution)
```

The private training loop (`_train_locally`) builds an in-memory `DataLoader` from the caller's sovereign corpus (padded byte or token sequences), then runs AdamW + CrossEntropy for `local_epochs`. The node stores the complete post-training state in `latest_artifact` and in the returned `SovereignModelArtifact.model_state`; only the difference tensor is placed in the `SovereignContribution.weight_delta`.

Sources: [src/tapestry/training/consortium/node.py:51-78](), [src/tapestry/training/consortium/node.py:92-112]()

## ConsortiumCoordinator.run_round and Delta Application

The coordinator drives the N+1 cycle:

```python:38:66:src/tapestry/training/consortium/coordinator.py
    def run_round(self, nodes: Sequence[SovereignTrainingNode]) -> ConsortiumRoundResult:
        self._round += 1
        previous_state = self.shared_base_state

        cycle_results = [node.run_sovereign_cycle(self._round, previous_state) for node in nodes]
        for result in cycle_results:
            self.sovereign_artifacts[result.artifact.node_id] = result.artifact

        contributions = [result.contribution for result in cycle_results]
        weights = self.contribution_policy.weights(...)
        ...
        if weights:
            ...
            integrated_state = self._apply_weighted_deltas(previous_state, deltas_by_node, weights)
            self.base_model.load_state_dict(integrated_state)
        ...
```

The static applicator performs a weighted sum of deltas before adding them to the prior base:

```python:68:80:src/tapestry/training/consortium/coordinator.py
    @staticmethod
    def _apply_weighted_deltas(
        base_state: ModelState,
        deltas_by_node: dict[str, ModelState],
        weights: dict[str, float],
    ) -> ModelState:
        next_state: ModelState = {}
        for name, base_tensor in base_state.items():
            delta = torch.zeros_like(base_tensor)
            for node_id, weight in weights.items():
                delta = delta + deltas_by_node[node_id][name] * weight
            next_state[name] = base_tensor + delta
        return next_state
```

After a successful round the coordinator holds exactly one shared base plus one `SovereignModelArtifact` per participating node.

Sources: [src/tapestry/training/consortium/coordinator.py:38-66](), [src/tapestry/training/consortium/coordinator.py:68-80]()

## ContributionPolicy – Iterative Capping

The policy first drops any score below `quality_floor` (or ≤ 0). It then normalizes the survivors and repeatedly caps any node whose share would exceed `max_node_weight`:

```python:30:58:src/tapestry/training/consortium/policy.py
        weights = self._normalize(accepted)
        capped: dict[str, float] = {}
        remaining = dict(weights)
        remaining_mass = 1.0

        while remaining:
            over_cap = {
                node_id: weight
                for node_id, weight in remaining.items()
                if weight * remaining_mass > self.max_node_weight
            }
            if not over_cap:
                ...
                break

            for node_id in over_cap:
                capped[node_id] = self.max_node_weight
                remaining_mass -= self.max_node_weight
                remaining.pop(node_id)

            ...
            remaining = self._normalize(remaining)
```

A final renormalization absorbs any floating-point residue. The algorithm guarantees that no single node ever receives more than `max_node_weight` after the round and that accepted weights sum to 1.0.

Sources: [src/tapestry/training/consortium/policy.py:22-59]()

## Exact Messages and Types

All communication uses frozen dataclasses defined in `messages.py`:

- `ModelState = dict[str, torch.Tensor]` – canonical snapshot type.
- `SovereignModelArtifact` – full post-training state + jurisdiction + metrics; retained by the node and by the coordinator.
- `SovereignContribution` – the delta, quality score, token count, and round number sent to the coordinator.
- `SovereignCycleResult` – pairs the artifact (kept) with the contribution (shared).
- `ConsortiumRoundResult` – round number, before/after base states, accepted/rejected lists, and the final weights.

`types.py` exists solely for import-path compatibility; its `__all__` simply re-exports the five symbols from `messages`.

Sources: [src/tapestry/training/consortium/messages.py:9-52]()

## The Test File That Locks the Invariants

`src/tests/tapestry/training/consortium/test_consortium_training.py` contains exactly four tests that together enforce the PoC contract:

1. `test_sovereign_node_returns_artifact_and_weight_delta` – verifies a node keeps a full `model_state` in its artifact while the contribution carries a non-zero delta of the same keys.
2. `test_contribution_policy_applies_quality_floor_and_capture_cap` – exercises the floor filter and the iterative cap; asserts rejected nodes are absent and the sum of accepted weights ≈ 1.0.
3. `test_coordinator_maintains_n_plus_one_model_outcome` – after one round with two nodes, `coordinator.sovereign_artifacts` has length 2 and the shared base has changed.
4. `test_low_quality_contribution_does_not_update_shared_base` – when the policy rejects every contribution, `previous_base_state` and `shared_base_state` remain bitwise identical.

These tests are the executable specification of the N+1 guarantees.

Sources: [src/tests/tapestry/training/consortium/test_consortium_training.py:82-123](), [src/tests/tapestry/training/consortium/test_consortium_training.py:126-153]()

## Runnable Entry Point

`examples/consortium_training_demo.py` wires three synthetic jurisdictions (Vietnam, Switzerland, India), each with its own corpus and quality score, then runs a configurable number of rounds under a `max_node_weight=0.5` policy. It prints exactly the information a reader needs to see the governance decisions in action: accepted vs. rejected lists, final normalized weights, and the growing set of retained sovereign artifacts.

## Summary

The six modules implement a complete, self-contained, and test-locked demonstration of governed consortium training. A reader who starts at `TinyCausalModel`, follows `SovereignTrainingNode.run_sovereign_cycle`, watches `ConsortiumCoordinator.run_round` call the policy and `_apply_weighted_deltas`, and then runs the four tests will have verified every architectural claim the PoC makes. All subsequent engineering work on Tapestry's training subsystem begins from this concrete baseline.

Sources: [src/tapestry/training/consortium/README.md:1-35]()

---

## 05. Technical Documentation System

> How the real documentation is organized: the TVA phased methodology (0-5), the eight ADRs that actually constrain the design, the anti-capture principle, the eight work-group charters, and the difference between docs/ (published site) and tech-docs/ (source of truth).

- Page Markdown: https://grok-wiki.com/public/wiki/the-ai-alliance-tapestry-4a40b7cf9eb6/pages/05-technical-documentation-system.md
- Generated: 2026-05-21T01:40:35.784Z

### Source Files

- `tech-docs/README.md`
- `tech-docs/architecture/README.md`
- `tech-docs/architecture/0-tva-methodology.md`
- `tech-docs/governance/anti-capture-principle.md`
- `tech-docs/work-groups/README.md`
- `docs/_config.yml`
- `docs/index.markdown`
- `docs/contributing.markdown`

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [tech-docs/README.md](tech-docs/README.md)
- [tech-docs/architecture/README.md](tech-docs/architecture/README.md)
- [tech-docs/architecture/0-tva-methodology.md](tech-docs/architecture/0-tva-methodology.md)
- [tech-docs/governance/anti-capture-principle.md](tech-docs/governance/anti-capture-principle.md)
- [tech-docs/governance/README.md](tech-docs/governance/README.md)
- [tech-docs/work-groups/README.md](tech-docs/work-groups/README.md)
- [tech-docs/architecture/decisions/README.md](tech-docs/architecture/decisions/README.md)
- [tech-docs/architecture/decisions/adr-001-core-plus-sovereign.md](tech-docs/architecture/decisions/adr-001-core-plus-sovereign.md)
- [tech-docs/architecture/decisions/adr-008-data-sovereignty.md](tech-docs/architecture/decisions/adr-008-data-sovereignty.md)
- [docs/_config.yml](docs/_config.yml)
- [docs/index.markdown](docs/index.markdown)
- [docs/contributing.markdown](docs/contributing.markdown)
- [README.md](README.md)
- [AGENTS.md](AGENTS.md)

</details>

# Technical Documentation System

The technical documentation for Project Tapestry lives in two distinct places that serve different audiences and purposes. `tech-docs/` is the source of truth for all architecture, governance, and design decisions. `docs/` contains the sources for the published GitHub Pages website. Understanding this split, the TVA methodology that produced the design, the eight constraining ADRs, the anti-capture principle, and the eight work-group charters is the fastest way to orient yourself before reading code or contributing.

## TVA Methodology

TVA (Tapestry Vision Architecture) is the structured, bidirectional requirements-to-architecture process used to derive Tapestry's design. It exists because the project must simultaneously deliver frontier-class capability and genuine sovereignty for heterogeneous participants; premature architectural commitment is the primary risk.

TVA organizes work into six phases across two movements:

- **Requirements (Phases 1–4)** work top-down from stakeholders to the constraints the architecture must satisfy.
- **Architecture (Phases 5–6)** work bottom-up, letting technical realities revise earlier goals.

The phases are not a waterfall. After an initial forward pass, the process requires iterative consistency checks: Phase 5 decisions must ripple back through Phases 4–1, orphaned items must be resolved, and tensions must be named explicitly as open questions.

```mermaid
graph TD
    subgraph Requirements ["Requirements (top-down)"]
        P1["Phase 1: Stakeholder Mapping"]
        P2["Phase 2: Pain Point Analysis"]
        P3["Phase 3: Value Proposition Mapping"]
        P4["Phase 4: Design Goal Synthesis"]
    end
    subgraph Architecture ["Architecture (bottom-up)"]
        P5["Phase 5: Architectural Option Space"]
        P6["Phase 6: Architecture Decision Records"]
    end
    P1 --> P2 --> P3 --> P4 --> P5 --> P6
    P5 -.->|"revises"| P4
    P4 -.->|"ripples back"| P3
    P3 -.->|"ripples back"| P2
    P2 -.->|"ripples back"| P1
```

**Current status** (as recorded in the methodology document):

| Phase | Status    |
|-------|-----------|
| 0 — TVA Methodology (this document) | Complete |
| 1 — Stakeholder Mapping | Complete |
| 2 — Pain Point Analysis | Complete |
| 3 — Value Proposition Mapping | Complete |
| 4 — Design Goal Synthesis | Complete |
| 5 — Architectural Option Space | Complete |
| 6 — Architecture Decision Records | Next (ADRs exist in proposed state) |

**Sources:** [tech-docs/architecture/0-tva-methodology.md:1-120](tech-docs/architecture/0-tva-methodology.md), [tech-docs/architecture/README.md:1-16](tech-docs/architecture/README.md)

## Architecture Decision Records (ADRs)

All significant architectural and governance commitments are captured as Architecture Decision Records (ADRs) in `tech-docs/architecture/decisions/`. There are currently eight ADRs, numbered TAP-001 through TAP-008. All are in "proposed" status and use a standard metadata table (Status, Confidence, Date, Deciders) followed by Context, Decision, and Rationale sections.

The complete set:

| ADR | Title | Key Commitment |
|-----|-------|----------------|
| TAP-001 | Core-plus-sovereign architecture | Layered model: shared frontier base + participant sovereign layers (initial ~80/20 split, shifting over time) |
| TAP-002 | Consortium training model | Governed, contribution-weighted, anti-capture training loop across sovereign nodes |
| TAP-003 | Cultural alignment as primary differentiator | Sovereign post-training and alignment pipelines are first-class, not afterthoughts |
| TAP-004 | The consortium training loop | Explicit phased loop: shared base improvement + sovereign layer improvement with provenance and credit |
| TAP-005 | Sovereign model pipeline | Participant-owned continued pretraining, alignment, and export paths that preserve control |
| TAP-006 | Phased base model strategy | Start with adopted base, move to consortium-owned bases over time |
| TAP-007 | Training architecture comparison | Documents why core-plus-sovereign was chosen over pure monolithic or fully federated alternatives |
| TAP-008 | Data sovereignty | Data contribution models, residency, provenance, and usage constraints that downstream systems must honor |

The decisions/README.md index currently lists only seven; TAP-008 (Data Sovereignty) was added later and is the most recent.

**Sources:** [tech-docs/architecture/decisions/README.md:45-56](tech-docs/architecture/decisions/README.md), [tech-docs/architecture/decisions/adr-001-core-plus-sovereign.md:1-30](tech-docs/architecture/decisions/adr-001-core-plus-sovereign.md), [tech-docs/architecture/decisions/adr-008-data-sovereignty.md:1-15](tech-docs/architecture/decisions/adr-008-data-sovereignty.md)

## The Anti-Capture Principle

Governance is treated as a load-bearing architectural constraint, not policy added later.

The single foundational statement:

> Tapestry's purpose is sovereign AI for its participants. Its governance must honor that purpose: no participant's sovereignty should be compromised by another's power within the platform, and Tapestry itself must never become the dependency it was built to replace.

This principle directly shapes ADR content, work-group charters (especially Governance & Participation), contribution weighting in the training loop, and the design of decision rights.

**Sources:** [tech-docs/governance/anti-capture-principle.md:1-6](tech-docs/governance/anti-capture-principle.md), [tech-docs/governance/README.md:1-7](tech-docs/governance/README.md), [tech-docs/work-groups/README.md:18](tech-docs/work-groups/README.md)

## Work Group Charters

Eight durable, lifecycle-oriented work groups own requirements discovery, technical exploration, implementation notes, open questions, and delivery artifacts in one place. Each charter explicitly traces its existence to specific TVA phases and ADRs.

The eight groups:

| Work Group | Directory | Owns |
|------------|-----------|------|
| Data Governance | data-governance/ | Sovereign data sourcing, licensing, stewardship, residency, provenance, contribution rights, data-quality criteria |
| Base Model Training | base-model-training/ | Adopted-base strategy, consortium training loop, shared-base continued pretraining, aggregation |
| Sovereign Alignment | sovereign-alignment/ | Participant-owned continued pretraining, post-training alignment, instruction tuning, portability of sovereign layers |
| Evaluation & Certification | evaluation-certification/ | Capability, cultural alignment, safety, benchmark design, certification criteria, audit evidence, release gates |
| Security & Privacy | security-privacy/ | Privacy tiers, secure aggregation, differential privacy, TEEs, threat models, model-update leakage |
| Infrastructure & Operations | infrastructure-operations/ | Heterogeneous compute, orchestration, node operations, observability, fault tolerance, cost/accounting |
| Deployment & Adoption | deployment-adoption/ | Serving, chat/product harnesses, integration patterns, participant rollout, developer experience |
| Governance & Participation | governance-participation/ | Anti-capture mechanics, contribution credit, decision rights, consortium process |

Each charter follows a compact template: Purpose, Why it exists (with links to phases/ADRs), Scope (in/out), Initial questions, Early deliverables, and Interfaces.

**Sources:** [tech-docs/work-groups/README.md:7-58](tech-docs/work-groups/README.md), [tech-docs/work-groups/data-governance/README.md:1-30](tech-docs/work-groups/data-governance/README.md)

## docs/ (Published Site) vs. tech-docs/ (Source of Truth)

| Aspect | docs/ | tech-docs/ |
|--------|-------|------------|
| Purpose | User-facing technical website (GitHub Pages) | Engineering source of truth for design and decisions |
| Technology | Jekyll + Just the Docs theme | Plain Markdown + occasional Mermaid |
| Primary audience | New contributors, partners, external readers | People doing architecture, governance, or implementation work |
| Content style | Orientation, navigation, high-level work-group descriptions | Full TVA phases, all ADRs, detailed charters, open questions, diagrams |
| Build | `make view-local` / GitHub Pages (see GITHUB_PAGES.md) | None — read directly from repo |
| Current linkage | No deep embedding or automatic inclusion of TVA/ADR content | Explicitly referenced from root README and AGENTS.md |

The published site (configured in `docs/_config.yml` with title "Project Tapestry: Technology", baseurl `/tapestry`) is deliberately lightweight. It orients readers and points them at the repo. The actual technical depth — the artifacts that constrain implementation — lives only in `tech-docs/`.

Root README and AGENTS.md are explicit:

- "The technical documentation lives under `tech-docs/`."
- "`docs/` is the GitHub Pages site. It is the user-facing technical website..."
- "`tech-docs/` is the main home for design and technical decision docs."

**Sources:** [README.md:40-65](README.md), [AGENTS.md:1-60](AGENTS.md), [docs/_config.yml:11-26](docs/_config.yml), [docs/contributing.markdown:34-38](docs/contributing.markdown)

## How to Navigate

1. Start with `tech-docs/README.md` and `tech-docs/architecture/README.md`.
2. Read `0-tva-methodology.md` for the process and status.
3. Read the eight ADRs in `architecture/decisions/` (they are the actual constraints).
4. Read the anti-capture principle and the work-group charter that matches your interest.
5. Use the published site (`docs/`) only for orientation or when you want the rendered Jekyll view.

Everything else in the repository — code in `src/`, examples, tests — must eventually be traceable to decisions and charters recorded here.

**Sources:** [tech-docs/README.md:1-37](tech-docs/README.md), [AGENTS.md:25-35](AGENTS.md)

This separation and the artifacts it protects are intentional: the design reasoning that will determine whether Tapestry can actually deliver sovereign frontier AI is too important to be scattered across slides, issues, or chat logs.

---

## 06. After 30 Minutes: Your Map Forward

> What you now know and the three concrete next actions: pick one ADR or work-group charter to read deeply, run and modify the demo with your own corpus, and the exact contribution workflow (PR templates, license stack, AGENTS.md conventions) for this repository.

- Page Markdown: https://grok-wiki.com/public/wiki/the-ai-alliance-tapestry-4a40b7cf9eb6/pages/06-after-30-minutes-your-map-forward.md
- Generated: 2026-05-21T01:40:25.776Z

### Source Files

- `AGENTS.md`
- `.github/PULL_REQUEST_TEMPLATE/general_code_pr.md`
- `tech-docs/architecture/decisions/adr-007-architecture-comparison.md`
- `tech-docs/strategic-plan/README.md`
- `Makefile`

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [AGENTS.md](AGENTS.md)
- [.github/PULL_REQUEST_TEMPLATE/general_code_pr.md](.github/PULL_REQUEST_TEMPLATE/general_code_pr.md)
- [.github/PULL_REQUEST_TEMPLATE/docs_website_pr.md](.github/PULL_REQUEST_TEMPLATE/docs_website_pr.md)
- [Makefile](Makefile)
- [README.md](README.md)
- [docs/contributing.markdown](docs/contributing.markdown)
- [examples/consortium_training_demo.py](examples/consortium_training_demo.py)
- [src/tapestry/training/consortium/README.md](src/tapestry/training/consortium/README.md)
- [tech-docs/README.md](tech-docs/README.md)
- [tech-docs/architecture/decisions/README.md](tech-docs/architecture/decisions/README.md)
- [tech-docs/architecture/decisions/adr-001-core-plus-sovereign.md](tech-docs/architecture/decisions/adr-001-core-plus-sovereign.md)
- [tech-docs/architecture/decisions/adr-007-architecture-comparison.md](tech-docs/architecture/decisions/adr-007-architecture-comparison.md)
- [tech-docs/work-groups/README.md](tech-docs/work-groups/README.md)
- [tech-docs/work-groups/data-governance/README.md](tech-docs/work-groups/data-governance/README.md)

</details>

# After 30 Minutes: Your Map Forward

After 30 minutes in the Tapestry repository you have a working mental model of the project and a clear path to productive contribution. You understand the core thesis (a governed consortium training loop that produces one shared frontier base plus N participant-owned sovereign models), the current concrete artifact (a runnable Python proof-of-concept), the design rationale captured in ADRs, the work-group structure that owns the lifecycle, and the exact local development and PR conventions enforced by this repo.

This page turns that orientation into three high-signal next actions so your time moves from "figuring out the repo" to "doing useful work."

## What You Now Know

**Project intent and invariants.** Tapestry is building a frontier foundation model through "consortium training": a shared base (initially adopted, later evolved by the consortium) is distributed to sovereign nodes; each node performs continued pre-training and alignment on its own data; only governed weight deltas return to improve the base. Raw sovereign data never leaves the node. The outcome at every round is the N+1 model pattern—one evolving global base plus N persistent, deployable sovereign artifacts owned by participants. Anti-capture, data sovereignty, and incremental value are architectural requirements, not aspirations.

**Current implementation surface.** The only live code is the small but faithful `src/tapestry/training/consortium/` package (coordinator, sovereign node, contribution policy, tiny causal model, messages). The runnable demo in `examples/consortium_training_demo.py` exercises the exact loop described in the ADRs: quality floor, anti-capture weight cap, accepted/rejected contributions, and sovereign artifact retention. Everything else (data governance, full sovereign pipeline, evaluation, infrastructure) is still in `tech-docs/`.

**Design documentation as load-bearing context.** `tech-docs/architecture/` contains the TVA requirements phases, the option-space analysis, and the numbered ADRs. `tech-docs/work-groups/` contains the lifecycle charters. `AGENTS.md` explicitly tells contributors to treat these documents as first stops and constraints before writing code.

**Local development contract.** Python 3.12 + `uv`, all work driven by `make` targets (`one-time-setup`, `tests`, `format`, `lint`, `type-check`, `before-pr`, `consortium-demo`), strict layout mirroring between `src/tapestry/...` and `src/tests/tapestry/...`, small focused changes, and the requirement to run the full verification suite before any PR.

Sources: [AGENTS.md:1-140](AGENTS.md), [README.md:180-250](README.md), [src/tapestry/training/consortium/README.md:1-60](src/tapestry/training/consortium/README.md), [tech-docs/README.md:1-50](tech-docs/README.md)

## Three Concrete Next Actions

### 1. Pick one ADR or work-group charter and read it deeply (30–60 minutes)

The ADRs and charters are the primary sources of truth for why choices were made and what is in or out of scope. Skimming is not enough; pick one and map its reasoning, the alternatives it rejected, and the open questions it flags.

**Recommended starting ADRs** (all under `tech-docs/architecture/decisions/`):

| ADR | One-sentence reason to read it | Core claim |
|-----|--------------------------------|------------|
| [TAP-001](tech-docs/architecture/decisions/adr-001-core-plus-sovereign.md) | The foundational layering decision that everything else assumes. | Core-plus-sovereign (shared base + sovereign layers) beats both monolithic and fully distributed alternatives for the primary goals. |
| [TAP-007](tech-docs/architecture/decisions/adr-007-architecture-comparison.md) | The cross-cutting evaluation of eight training architectures against the design goals. | Weight-delta consortium training is the current bet because it has the strongest (still small-scale) empirical and theoretical support; the contribution mechanism itself is designed to be swappable. |
| [TAP-002](tech-docs/architecture/decisions/adr-002-consortium-training.md) or [TAP-004](tech-docs/architecture/decisions/adr-004-training-loop.md) | The operational loop and the N+1 outcome. | Governance of deltas, not just the existence of the loop, is what makes the system anti-capture and strategically rational for participants. |

**Recommended starting work-group charter**:

- [Data Governance](tech-docs/work-groups/data-governance/README.md) — defines the data-tier taxonomy, provenance requirements, and the hard "raw data never leaves" boundary that the rest of the system must respect.

After you finish, you will be able to explain the concrete trade-off that justified the current architecture and name at least two alternatives that were deliberately ruled out or deferred.

Sources: [tech-docs/architecture/decisions/README.md:20-70](tech-docs/architecture/decisions/README.md), [tech-docs/architecture/decisions/adr-007-architecture-comparison.md:80-160](tech-docs/architecture/decisions/adr-007-architecture-comparison.md), [tech-docs/work-groups/README.md:20-80](tech-docs/work-groups/README.md), [tech-docs/work-groups/data-governance/README.md:1-60](tech-docs/work-groups/data-governance/README.md)

### 2. Run the demo and modify it with your own corpus (15 minutes)

This is the fastest way to develop intuition for the invariants the architecture actually enforces.

```bash
make consortium-demo
# or directly:
uv run python examples/consortium_training_demo.py
```

The script instantiates three fictional sovereign nodes (Vietnam, Switzerland, India), each with a tiny corpus, runs three rounds of the governed loop, and prints accepted contributions, weights, rejections, and retained sovereign artifacts.

**To make it yours:**

1. Open `examples/consortium_training_demo.py`.
2. Replace or extend the `DOMAIN_CORPORA` dictionary with 4–8 short, culturally specific sentences in your target language or domain.
3. Adjust the corresponding entry in `QUALITY_SCORES` (must be ≥ the policy's quality floor of 0.75 to be accepted).
4. Re-run. Observe which nodes are accepted or rejected and how the contribution weights are capped.

Then open the three core modules (`node.py`, `coordinator.py`, `policy.py`) and trace exactly where the quality floor and `max_node_weight` are applied. You now have a live, modifiable model of "data stays local, only deltas move, governance is executable."

Sources: [Makefile:115-130](Makefile), [examples/consortium_training_demo.py:20-95](examples/consortium_training_demo.py), [src/tapestry/training/consortium/README.md:20-55](src/tapestry/training/consortium/README.md)

### 3. Execute the exact contribution workflow (the checklist you will follow on every PR)

**Before you write code or docs:**

- Read `AGENTS.md` (the single source of repo conventions).
- Read the relevant slice of `tech-docs/` first; do not start a broad refactor.
- Keep changes small and contained to one subsystem; mirror any new `src/tapestry/X/` code with `src/tests/tapestry/X/` tests.

**When you open the PR, GitHub will ask you to choose a template.** Pick the right one:

- `general_code_pr.md` — any change that touches `src/`, `examples/`, tests, or build files.
- `docs_website_pr.md` — pure documentation or `docs/` site changes.

Both templates require the same high-level structure (description, related issues, testing/impact, checklist). The code template additionally demands:

- Unit or integration tests added/updated.
- `make before-pr` (or the individual format + lint + type-check + tests) has passed locally.
- No secrets committed.
- Documentation updated where behavior changed.

**License and DCO stack (non-negotiable):**

- Code → Apache 2.0 (`LICENSE.Apache-2.0`)
- Documentation → CC-BY-4.0 (`LICENSE.CC-BY-4.0`)
- Data → CDLA-2.0 (`LICENSE.CDLA-2.0`)
- Every commit must include the `-s` / `--signoff` flag (Developer Certificate of Origin). The Alliance CONTRIBUTING guide (linked from the templates and README) explains the exact requirement.

**Docs-specific extra steps** (when using the docs template):

- `make view-local` must succeed (Jekyll build).
- `./check-external-links.sh` must pass for any new external links (and you must add the `target="..."` attributes the script cannot insert).

**Practical pre-PR command sequence** (from AGENTS.md and Makefile):

```bash
make one-time-setup   # first time only
make before-pr        # format + lint + type-check + tests
make consortium-tests # if you touched the PoC
```

Only after the above is green do you push and open the PR with the correct template filled in.

Sources: [.github/PULL_REQUEST_TEMPLATE/general_code_pr.md:30-70](.github/PULL_REQUEST_TEMPLATE/general_code_pr.md), [.github/PULL_REQUEST_TEMPLATE/docs_website_pr.md:1-40](.github/PULL_REQUEST_TEMPLATE/docs_website_pr.md), [README.md:200-240](README.md), [AGENTS.md:70-110](AGENTS.md), [docs/contributing.markdown:1-60](docs/contributing.markdown)

## Your 30-Minute Outcome

You now possess:

- A precise architectural mental model (N+1, governed deltas, core-plus-sovereign).
- A living, editable artifact that demonstrates the invariants.
- The exact documents that encode the "why" and the governance boundaries.
- The mechanical checklist that every accepted contribution must satisfy.

Pick one of the three actions above and do it today. When you return, you will be ready to open a meaningful issue, improve a charter, add a test case to the PoC, or propose a small, well-scoped change that respects the architecture the repo has already decided.

Sources: [AGENTS.md:1-20](AGENTS.md), [tech-docs/architecture/decisions/adr-007-architecture-comparison.md:300-340](tech-docs/architecture/decisions/adr-007-architecture-comparison.md)

---