Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
4 changes: 2 additions & 2 deletions docs/review/devils-advocate.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@ Challenge the most consequential claim first, one objection at a time, each with
a `path:line` and a concrete scenario. In this repository the claims that have
failed before are:

- a HermitCrab performance win asserted without a measured artifact, or a memo
key that omits a field a rule reads;
- a HermitCrab speedup asserted without a measured artifact, or a merge that ignores
state read by an analysis rule;
- a USFM or reference change whose test proves the happy path only;
- a parity claim about `machine.py` with no checked comparison.

Expand Down
19 changes: 7 additions & 12 deletions docs/review/hermitcrab.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,15 @@
# HermitCrab Review

*Review HermitCrab morphology changes for analysis equivalence, memoization-key
completeness, retained-memory bounds, parallelism, and hot-path cost.*
*Review HermitCrab morphology changes for analysis equivalence, state-sensitive
merging, parallelism, and hot-path cost.*

Governs `src/SIL.Machine.Morphology.HermitCrab/**/*.cs`.

- Treat analysis output as the primary contract. A faster parse, more memo hits, or a
successful build does not prove equivalent analyses.
- When changing analysis-side rules or state, re-audit every field the rule reads
against `AnalysisStateKey`. Check freezing, cached hashes, mutable dictionaries,
equality, rule counts, non-head counts, feature structures, and stratum identity.
- Memoized results must represent fully expanded subtrees. Check replay prefixes,
deduplication, empty/nogood entries, in-flight recursion, and the separation between
sequential and parallel scopes.
- Do not weaken an existing memo or retained-word bound without measured evidence
and a test. Read the current limits from the code.
- Treat analysis output as the primary contract. A faster parse or a successful build
does not prove equivalent analyses.
- When changing analysis-side rules or state, check every field a rule reads and
whether equivalent analyses can be merged safely. Check rule counts, non-head
counts, feature structures, and stratum identity.
- Inspect allocations and retained object lifetimes only in changed inner loops. If the
change claims a performance improvement, require a reproducible benchmark or measured
artifact in addition to semantic regression tests.
Expand Down
6 changes: 3 additions & 3 deletions docs/review/machine-tests.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ Governs `tests/**/*.cs`.
when the contract is ordinal identity.
- For async code, assert cancellation and completion behavior where the change promises
it; do not hide unobserved tasks.
- For HermitCrab changes, compare analysis semantics, not only memo-hit counts or
execution success. Exercise key completeness, replay, resource caps, and
parallel/sequential equivalence when touched.
- For HermitCrab changes, compare analysis semantics, not only execution success.
Exercise state-sensitive merging, resource caps, and parallel/sequential
equivalence when touched.
- Name the test that proves the change. "Where is the test?" is the single most
common review question in this repository; answer it before it is asked.
134 changes: 0 additions & 134 deletions src/SIL.Machine.Morphology.HermitCrab/AnalysisScope.cs

This file was deleted.

126 changes: 0 additions & 126 deletions src/SIL.Machine.Morphology.HermitCrab/AnalysisStateKey.cs

This file was deleted.

Loading
Loading