Measure substance. The datamancer assays the specification — is it a program or a description? A file full of comments is a rock that glitters. The assayer crushes it and reports the fraction.
Comments tell the human. Expressions tell the wards. — The Forge
The five wards check the quality of what exists. The assay checks whether it exists at all. A specification file that's mostly comments passes sever, reap, scry, gaze, and forge — because those wards test the expressions that are present. The assay tests how many expressions are present.
Count the lines that are actual s-expressions (forms that begin with () versus lines that are comments (begin with ;; or ;). Report the ratio.
| Ratio | Verdict |
|---|---|
| < 2:1 comments:code | Program — the specification expresses the system |
| 2:1 to 4:1 | Mixed — some prose, some program. Identify which sections are prose |
| > 4:1 |
| Description — the specification narrates but does not model |
| Comments only | Empty — no specification exists, only documentation |
For each define in the file, does the body contain actual expressions or commented-out pseudocode?
define with a let* chain of real bindings: expresseddefine with comments describing what the Rust does: describeddefine that returns its input unchanged with prose between: hollowReport: N functions defined, M fully expressed, P described, Q hollow.
Can the forge test the joints between functions in this file? If a function calls another function that exists only in comments, the joint is untestable. Count:
Compare the wat file against its Rust counterpart. How many of the Rust's public functions/methods have corresponding define forms in the wat?
definedefine, classify as expressed / described / hollow.Skip findings annotated with rune:assay(category) in a comment at the site.
;; rune:assay(prose) — this section describes an algorithm too imperative
;; for wat; the contract is specified, the Rust implements the mechanism
Categories: prose (intentionally described, not expressed), pending (will be expressed when the feature is built).
A specification that doesn't specify is a letter about a program, not the program itself. The assayer doesn't judge quality — the other five wards do that. The assayer measures quantity. Is there gold in this rock, or is it just rock?
The datamancer assays. The rock yields its fraction. What's metal becomes the program. What's slag becomes a rune explaining why.