Skip to content

docs: name the example generators as the corpus expansion path - #8

Open
josemontesdeoca wants to merge 1 commit into
mainfrom
corpus-topology-attribution
Open

docs: name the example generators as the corpus expansion path#8
josemontesdeoca wants to merge 1 commit into
mainfrom
corpus-topology-attribution

Conversation

@josemontesdeoca

Copy link
Copy Markdown
Member

Why the change

The corpus READMEs in the language repository now say that their node and edge counts come from this harness's per-entity expansion rather than from mounting src/, so this names the files on our side that actually perform that expansion and a reader arriving from either repository gets the same account of where the numbers come from.

Special things to note

  • Documentation only — one sentence, one file, no code, no tests, no behavior. There is nothing to run.
  • The pointer is accurate but stops one hop short for three examples. Five of the eight attributed examples (implementation-pipeline, agent-observatory, support-inbox-router, press-desk, feedback-pulse) hold their topology directly in tests/open-prose/examples/<name>/generate.ts. The other three — monorepo-ci, inbox-triage, research-tree — delegate to the shared devtools fixtures under packages/reactor-devtools/src/fixtures/, so a reader following the sentence lands on a generator whose header comment names the fixture. Worth a one-clause amendment if we would rather the sentence carry that hop itself.
  • The two repositories have to keep telling the same story, but neither can break the other. No test here reads the corpus READMEs and no test there reads these generators, so the two changes can land in either order or apart. The cost of them diverging is a reader who gets two accounts of the same number, not a failure.

Change outline

One paragraph, added after the example-library intro and before the example table, where a reader has just been told the corpus is the tour of the language.

 README.md — the example library
 
 The examples in `skills/open-prose/examples/` are the tour of the language …
 The thirteen below are replayable keyless, driving the real reconciler at zero
 model spend …
 
+The per-example `generate.ts` files under `tests/open-prose/examples/` are the
+expansion path from the corpus's authored contracts to the described topologies:
+`src/` alone mounts only the contracts an example authors, and the node and edge
+counts the corpus READMEs state are what these generators produce.
 
 | Example | What it shows | Domain |

What the sentence points at — 16 generators, of which these 8 back a count the corpus now attributes:

tests/open-prose/examples/
├── implementation-pipeline/generate.ts     topology declared in the generator
├── agent-observatory/generate.ts           topology declared in the generator
├── support-inbox-router/generate.ts        topology declared in the generator
├── press-desk/generate.ts                  topology declared in the generator
├── feedback-pulse/generate.ts              topology declared in the generator
├── monorepo-ci/generate.ts        ─┐
├── inbox-triage/generate.ts        ├─ delegate to the shared devtools fixture,
└── research-tree/generate.ts      ─┘  packages/reactor-devtools/src/fixtures/<name>.ts,
                                       so the learning corpus and the replay corpus
                                       cannot drift apart

The language repository's example READMEs now attribute their expanded
node and edge counts to the reference harness. Say on this side that
the per-example generate.ts files are that expansion path, so a reader
arriving from either repository finds the same account of where the
numbers come from.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants