From c4b430252e8295393e4c69c19010ba497994ccde Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Tue, 20 Oct 2026 12:29:25 -0700 Subject: [PATCH] docs(specs): plan a template rule that shares templated positions Record the outcome, requirements, non-goals, plan and tasks for prefix-variance, an opt-in environment-manifest rule that templates a literal segment with the parameter another tool already uses at that position, so a session's writes to one entity share the read's template. Co-Authored-By: Claude Opus 5.5 --- .../prefix-variance/plan.md | 18 +++++++ .../prefix-variance/spec.md | 49 +++++++++++++++++++ .../prefix-variance/tasks.md | 9 ++++ 3 files changed, 76 insertions(+) create mode 100644 docs/specs/agent-environments/prefix-variance/plan.md create mode 100644 docs/specs/agent-environments/prefix-variance/spec.md create mode 100644 docs/specs/agent-environments/prefix-variance/tasks.md diff --git a/docs/specs/agent-environments/prefix-variance/plan.md b/docs/specs/agent-environments/prefix-variance/plan.md new file mode 100644 index 0000000000..8e13bfe856 --- /dev/null +++ b/docs/specs/agent-environments/prefix-variance/plan.md @@ -0,0 +1,18 @@ +# Plan + +1. Move tool naming (`parameterNames`, `pathTemplate`, `toolName`, + `compareTools`) from `environmentManifestRules.ts` to a new + `environmentManifestNames.ts`, so the rules module has room for the rule. +2. Add `prefix-variance` to `TEMPLATE_RULES`. A `prefix-variance` parameter + records the rule it shares (`sharedRule`), which names it and keys it. +3. Add the pass after `sibling-variance`: walk positions in order, index the + opt-in parameters at each position by their preceding parts, template + qualifying literals, then rebucket by naming key, keeping a tool's own rule + for each merged position. +4. Share the 32-segment split between the three comparing passes and list the + segment-limited rules once for the limitation. +5. Document the rule in the view schema description and in + `docs/web-network-captures.md`. +6. Tests: shared positions across methods and depths, the spelling condition, + merges that keep a tool's own rule, pairs, format-rule positions and the + segment limit. diff --git a/docs/specs/agent-environments/prefix-variance/spec.md b/docs/specs/agent-environments/prefix-variance/spec.md new file mode 100644 index 0000000000..4c2fd6cbd4 --- /dev/null +++ b/docs/specs/agent-environments/prefix-variance/spec.md @@ -0,0 +1,49 @@ +# Share templated positions across tools + +Issue: https://github.com/morluto/rea/issues/4933 + +## Outcome + +A session usually edits one scratch entity: it creates it, then updates and +deletes it at a fixed path such as `/api/v1/collections/0RZ576QZQA5KG`. The +manifest templates a segment only when sibling routes of the same method vary +there, so those writes stay literal tools (`patch_collections_0rz576qzqa5kg`) +even though the reads of the same collection were templated as +`/api/v1/collections/{collection_id}`. A literal write tool addresses one +entity that may not exist in a later state, and nothing can model its effect. + +A new opt-in template rule, `prefix-variance`, templates such a literal with +the parameter another tool already uses at that position, so the write becomes +`patch_collections_by_collection_id` on the same template as the read. + +## Requirements + +- `prefix-variance` applies only when listed, after every other opt-in rule, so + it can share the parameters they produce. +- A literal at position `p` is templated when another tool on the same origin, + of any method and any segment count, has a parameter at `p` from one of the + other opt-in rules, after the same preceding parts. Parameters in the + preceding parts compare by the rule that names them, so a position templated + by `prefix-variance` matches the parameter it shares. +- The literal qualifies when it is one of the values any such tool observed at + that position, or when it carries a digit and has the length and character + classes (digits, lower case, upper case, each other character) of one of + them. An empty literal, a stop word or a `v1`-style version never qualifies. +- Positions templated by the four format rules are never shared, so + `/api/teams/{numeric}` still absorbs no literal. +- The parameter takes the name of the parameter it shares (`collection_id`, + `uid`, a pair's `_namespace` and `_name`) and is labelled `prefix-variance`. +- Tools whose routes now match, by method and by the rule that names each + parameter, merge. A merged parameter keeps the rule of a tool that templated + that position itself, when one did. +- Like the sibling rules, it compares routes of at most 32 segments and says so + in a limitation when a longer route exists. + +## Non-goals + +- No change to the default rules or to any other rule: manifests that do not + list `prefix-variance` are byte-for-byte unchanged. +- No templating from response bodies, such as an id a create returned; the + manifest reads request lines only. +- No change to which groups are excluded: a write whose response has no body + or content type outside `/api/` is still excluded as `non-json`. diff --git a/docs/specs/agent-environments/prefix-variance/tasks.md b/docs/specs/agent-environments/prefix-variance/tasks.md new file mode 100644 index 0000000000..5e6ae3b7d9 --- /dev/null +++ b/docs/specs/agent-environments/prefix-variance/tasks.md @@ -0,0 +1,9 @@ +# Tasks + +- [x] Record the outcome, requirements and non-goals. +- [x] Move tool naming into its own module. +- [x] Add the `prefix-variance` rule, its names, its merge and its limitation. +- [x] Document the rule in the schema and the capture guide. +- [x] Add rule tests. +- [x] Run static, formatting, duplication, documentation and test gates. +- [x] Project the 51 corpus captures with and without the rule and record the results.