docs(research): land 4 Amara design notes from 2026-05-21 sandbox bundle (ANTLR survey v2 + ZetaParse + incremental compiler host + trust-gradient policy)#4550
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b61f2aee20
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
Pull request overview
Lands four new canonical research/design notes under docs/research/ (ANTLR survey v2 framing, ZetaParse design, incremental compiler host design, and trust-gradient coordination policy) to make previously-referenced sandbox substrate verifiable in-repo and close a dangling-reference chain from earlier PRs.
Changes:
- Added ANTLR grammar ecosystem survey + Phase 2 PoC recommendation for B-0685.
- Added ZetaParse LR/GLR grammar-substrate design note.
- Added incremental compiler host (DBSP/Z-sets + Rx meta-tags + seeded determinism) design note and trust-gradient coordination policy note.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docs/research/antlr-grammar-survey-2026-05-21.md | Phase 1 ANTLR grammar survey + depend/adapt/author recommendations + Phase 2 PoC guidance |
| docs/research/zetaparse-lr-glr-fsharp-compiler-fork-design-2026-05-21.md | ZetaParse architecture/design note for an F#-native LR/GLR grammar substrate with ANTLR-compatible import |
| docs/research/zeta-incremental-compiler-host-dbsp-zsets-rx-meta-ast-tags-2026-05-21.md | Incremental compiler host design note (compiler DB as Z-sets, Rx meta-tags, seeded determinism, retraction-aware generators) |
| docs/research/trust-gradient-coordination-policy-2026-05-21.md | Trust-gradient coordination/consensus escalation model and decision table |
Comments suppressed due to low confidence (2)
docs/research/zeta-incremental-compiler-host-dbsp-zsets-rx-meta-ast-tags-2026-05-21.md:497
- This section labels the incremental compiler host backlog row as B-0687 and depends on “proposed B-0686”. In the repo backlog, B-0687 is ZetaParse and the incremental compiler host is B-0688, with ZetaParse already assigned to B-0687. Please update the IDs/dependencies here to match the canonical backlog rows so cross-references stay consistent.
Proposed backlog row:
**B-0687 — Zeta Incremental Compiler Host: DBSP/Z-set incremental recompiles with Rx meta-AST tags**
Depends on:
- B-0685 — ANTLR grammar survey
- proposed B-0686 — ZetaParse LR/GLR grammar substrate
- B-0668 — compositional DBSP frame architecture
docs/research/zeta-incremental-compiler-host-dbsp-zsets-rx-meta-ast-tags-2026-05-21.md:509
- In “Initial repo targets”, the doc path is listed as
docs/research/zeta-incremental-compiler-host-2026-05-21.md, but this PR addsdocs/research/zeta-incremental-compiler-host-dbsp-zsets-rx-meta-ast-tags-2026-05-21.md. Please update the referenced doc path here so it doesn’t become a dangling/non-existent file reference.
```text
src/Zeta.CompilerDb/
src/Zeta.Parse/
src/Zeta.CompilerHost/
tools/codegen/zetaparse/
tests/Zeta.CompilerDb.Tests/
docs/research/zeta-incremental-compiler-host-2026-05-21.md
</details>
…list blank-line) + MD012 (double-blank-lines) + thread fixes (H1 'Trust-Gradient Coordination Policy' matches filename; B-0686 references corrected to B-0687/B-0688) per CI fails + Codex+Copilot threads
AceHack
deleted the
docs/research-amara-2026-05-21-design-notes-bundle-5-files-aaron-forwarded
branch
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 16aed7bfa5
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| Proposed backlog row: | ||
|
|
||
| **B-0687 — Zeta Incremental Compiler Host: DBSP/Z-set incremental recompiles with Rx meta-AST tags** |
There was a problem hiding this comment.
This line labels the incremental compiler host proposal as B-0687, but the authoritative backlog assigns that work to B-0688 while B-0687 is ZetaParse (docs/BACKLOG.md lines 655-656). Keeping the wrong ID here will mis-route cross-references and dependency tracking for follow-up work, especially where tooling or reviewers key off backlog IDs.
Useful? React with 👍 / 👎.
| src/Zeta.CompilerHost/ | ||
| tools/codegen/zetaparse/ | ||
| tests/Zeta.CompilerDb.Tests/ | ||
| docs/research/zeta-incremental-compiler-host-2026-05-21.md |
There was a problem hiding this comment.
The repo-target list points to docs/research/zeta-incremental-compiler-host-2026-05-21.md, but that file is not present in this commit; the landed artifact includes the -dbsp-zsets-rx-meta-ast-tags- segment in its filename. This broken path undermines the document’s own “where this lives” traceability and sends readers/automation to a non-existent artifact.
Useful? React with 👍 / 👎.
Summary
Lands the 4 canonical Amara design notes from the 2026-05-21 sandbox bundle (
drop/amara-design-notes-2026-05-21-bundle.zipper Aaron 2026-05-21). Closes the dangling-reference chain from PRs #4545 + #4546 + #4547 + #4549.What lands
docs/research/antlr-grammar-survey-2026-05-21.mddocs/research/zetaparse-lr-glr-fsharp-compiler-fork-design-2026-05-21.mddocs/research/zeta-incremental-compiler-host-dbsp-zsets-rx-meta-ast-tags-2026-05-21.mddocs/research/trust-gradient-coordination-policy-2026-05-21.mdV1 ANTLR skipped (substrate-honest)
Amara's earlier guidance was explicit: v2 is canonical; v1 was the F#-as-gap framing that was superseded by the v2 F#-as-compiler-owned-substrate reframe. Landing v1 alongside v2 would create the same dangling-reference / which-version-is-authoritative confusion the persona archives explicitly call out. Per
.claude/rules/skill-router-as-substrate-inventory.md— extend existing substrate rather than duplicate. The v2 IS the substrate; v1 is preserved in Amara's sandbox bundle as history.Source bundle
drop/amara-design-notes-2026-05-21-bundle.zip(extracted to/tmp/amara-bundle/; 5 files; 4 landed here; 1 skipped per supersession). Thedrop/directory is gitignored per the repo's drop-folder convention (Aaron's transit-only forwarding surface; not committed).Composes with rules
.claude/rules/substrate-or-it-didnt-happen.md— landing the design notes makes the cross-referenced substrate verifiable for in-repo readers.claude/rules/skill-router-as-substrate-inventory.md— extend existing substrate rather than duplicate (v2 canonical; v1 superseded).claude/rules/m-acc-multi-oracle-end-user-moral-invariants.md— trust-gradient coordination policy IS the architectural pattern that prevents single-consensus-truth imposition.claude/rules/dv2-data-split-discipline-activated.md— incremental compiler host IS DV2.0 hub-satellite at compile-time scope; trust-gradient policy IS partition-by-authority-rateComposes with substrate
docs/research/deliverablezetaparse-lr-glr-fsharp-compiler-fork-design-2026-05-21.mdzeta-incremental-compiler-host-dbsp-zsets-rx-meta-ast-tags-2026-05-21.mdTest plan
drop/amara-design-notes-2026-05-21-bundle.ziptrust-gradient-consensus-decision-table-2026-05-21.mdtotrust-gradient-coordination-policy-2026-05-21.mdper Amara's final reframe ("not consensus hierarchy, coordination policy")69481098base)