Skip to content

docs: document protected_root renderer in egg_anchor [doc-updater] #3263

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jwbron merged 2 commits into from
Jun 25, 2026
Merged

docs: document protected_root renderer in egg_anchor [doc-updater] #3263

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
40bcbea
docs: document protected_root renderer in egg_anchor [doc-updater]
jwbron Jun 25, 2026
13fc523
docs: clarify BRCDerivedAnchors import comment in egg_anchor README
egg-reviewer[bot] Jun 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/development/STRUCTURE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -294,7 +294,8 @@ shared/
│ ├── loader.py # Atomic file read/write (temp-then-rename), API sync helper
│ ├── validator.py # Schema validation, size budget enforcement (soft/hard limits)
│ ├── constants.py # Re-exports anchor constants from egg_config
│ └── tests/ # Unit tests for models, loader, validator
│ ├── protected_root.py # Deterministic byte-stable protected-root renderer for event-pump BRC agents (RootCaps, render_protected_root)
│ └── tests/ # Unit tests for models, loader, validator, protected root renderer
├── egg_config/ # Configuration utilities
│ ├── constants.py # Centralized constants (ports, networks, container names, infrastructure branch names, anchor size limits)
│ ├── compose_config.py # Bridges config.yaml settings to docker-compose environment variables
Expand Down
34 changes: 32 additions & 2 deletions shared/egg_anchor/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,16 +177,46 @@ Orchestrator
| `validate_anchor(anchor)` | Validate against JSON Schema. Returns list of error strings (empty = valid). |
| `check_size_budget(anchor, is_team=False)` | Check size limits. Returns `SizeBudgetResult`. |

### Protected Root Renderer (`egg_anchor.protected_root`)

Assembles the byte-stable protected root injected at the top of an event-pump BRC agent's context. The render is byte-identical for identical input — which makes it a cacheable prompt prefix (warm resume, #3186) and a deterministic reseed source (#3200).

| Symbol | Description |
|--------|-------------|
| `render_protected_root(*, role, role_contract, task_description=None, derived=None, directives=None, caps=None)` | Render the four-section protected root as a single string. Returns byte-identical output for identical input. |
| `RootCaps` | Frozen dataclass of per-section character/count caps. Override to tighten or relax limits; defaults are deliberately generous. |

**Section order** (fixed, deterministic):
1. **ROLE CONTRACT** — behavioural spec for the role (capped at `RootCaps.role_contract_chars`)
2. **TASK** — task anchor from `compose_task_description` (#3163, capped at `task_chars`)
3. **BRC ANCHORS (#3189)** — last-reviewed SHA, latest verdicts, open NACKs, conditional-ACK obligations; all collections sorted by deterministic key
4. **NON-NEGOTIABLE DIRECTIVES** — ordered bullet list or raw string (capped at `directives_chars`)

```python
from egg_anchor import RootCaps, render_protected_root
from egg_anchor import BRCDerivedAnchors # re-exported from .models

root = render_protected_root(
role="reviewer_code",
role_contract="You are a code reviewer...",
task_description=task_desc, # from compose_task_description()
derived=derived_anchors, # BRCDerivedAnchors from derive_brc_anchors()
directives=["Never approve without citing a line number."],
caps=RootCaps(task_chars=6000), # tighten if needed
)
```

## Files

| File | Purpose |
|------|---------|
| `__init__.py` | Public API exports (models, loader, validator) |
| `__init__.py` | Public API exports (models, loader, validator, protected root renderer) |
| `models.py` | Pydantic models with field validators for array size constraints |
| `loader.py` | Atomic file I/O (temp-then-rename), API sync via HTTP POST |
| `validator.py` | JSON Schema validation, size budget checking (SizeBudgetResult) |
| `constants.py` | Re-exports anchor constants from egg_config (with fallback defaults) |
| `tests/` | Unit tests for models, loader, validator |
| `protected_root.py` | Deterministic byte-stable protected-root renderer for event-pump BRC agents |
| `tests/` | Unit tests for models, loader, validator, protected root renderer |

## Integration Points

Expand Down
Loading