@agent-ix/quoin 0.15.1 → 0.19.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/.codex-plugin/plugin.json +1 -1
  3. package/default-modules.yaml +15 -6
  4. package/dist/advisor/advise.d.ts +14 -1
  5. package/dist/advisor/advise.d.ts.map +1 -1
  6. package/dist/advisor/methods.d.ts +11 -1
  7. package/dist/advisor/methods.d.ts.map +1 -1
  8. package/dist/{advisor-D35K3_iI.js → advisor-a9axb4Jl.js} +21 -8
  9. package/dist/assurance/graph.d.ts +79 -0
  10. package/dist/assurance/graph.d.ts.map +1 -0
  11. package/dist/assurance/index.d.ts +9 -0
  12. package/dist/assurance/index.d.ts.map +1 -0
  13. package/dist/assurance/render.d.ts +3 -0
  14. package/dist/assurance/render.d.ts.map +1 -0
  15. package/dist/auditor/audit.d.ts +37 -5
  16. package/dist/auditor/audit.d.ts.map +1 -1
  17. package/dist/auditor/combinatorial.d.ts +53 -0
  18. package/dist/auditor/combinatorial.d.ts.map +1 -0
  19. package/dist/auditor/index.d.ts +1 -1
  20. package/dist/auditor/index.d.ts.map +1 -1
  21. package/dist/auditor-W2jFinr6.js +188 -0
  22. package/dist/{base-CtpwIg4M.js → base-BE20w0jY.js} +1 -1
  23. package/dist/cli.js +1 -1
  24. package/dist/combinatorial-Cq01XfhV.js +80 -0
  25. package/dist/commands/advise.d.ts +16 -0
  26. package/dist/commands/advise.d.ts.map +1 -0
  27. package/dist/commands/advise.js +164 -0
  28. package/dist/commands/assurance.d.ts +14 -0
  29. package/dist/commands/assurance.d.ts.map +1 -0
  30. package/dist/commands/assurance.js +179 -0
  31. package/dist/commands/catalog/list.js +2 -2
  32. package/dist/commands/catalog/methods.js +3 -3
  33. package/dist/commands/catalog/show.js +2 -2
  34. package/dist/commands/catalog/validate.js +2 -2
  35. package/dist/commands/completeness.d.ts +16 -0
  36. package/dist/commands/completeness.d.ts.map +1 -0
  37. package/dist/commands/completeness.js +49 -0
  38. package/dist/commands/config/doctor.js +1 -1
  39. package/dist/commands/config/edit.js +1 -1
  40. package/dist/commands/config/get.js +1 -1
  41. package/dist/commands/config/set.js +1 -1
  42. package/dist/commands/evidence/affirm.d.ts.map +1 -1
  43. package/dist/commands/evidence/affirm.js +36 -50
  44. package/dist/commands/evidence/audit.d.ts +11 -0
  45. package/dist/commands/evidence/audit.d.ts.map +1 -1
  46. package/dist/commands/evidence/audit.js +60 -154
  47. package/dist/commands/evidence/baseline.d.ts +14 -0
  48. package/dist/commands/evidence/baseline.d.ts.map +1 -0
  49. package/dist/commands/evidence/baseline.js +79 -0
  50. package/dist/commands/evidence/gc.js +2 -2
  51. package/dist/commands/evidence/index.d.ts.map +1 -1
  52. package/dist/commands/evidence/index.js +4 -2
  53. package/dist/commands/evidence/record.d.ts +3 -0
  54. package/dist/commands/evidence/record.d.ts.map +1 -1
  55. package/dist/commands/evidence/record.js +97 -53
  56. package/dist/commands/matrix.js +1 -1
  57. package/dist/commands/module/ensure-defaults.js +3 -3
  58. package/dist/commands/module/install.js +2 -2
  59. package/dist/commands/module/list.js +2 -2
  60. package/dist/commands/module/remove.js +2 -2
  61. package/dist/commands/review.js +1 -1
  62. package/dist/commands/to-plan.js +1 -1
  63. package/dist/commands/update.js +2 -2
  64. package/dist/commands/write.js +3 -3
  65. package/dist/completeness/assess.d.ts +82 -0
  66. package/dist/completeness/assess.d.ts.map +1 -0
  67. package/dist/completeness/bundle.d.ts +52 -0
  68. package/dist/completeness/bundle.d.ts.map +1 -0
  69. package/dist/completeness/declarations.d.ts +46 -0
  70. package/dist/completeness/declarations.d.ts.map +1 -0
  71. package/dist/completeness/index.d.ts +11 -0
  72. package/dist/completeness/index.d.ts.map +1 -0
  73. package/dist/completeness/run.d.ts +35 -0
  74. package/dist/completeness/run.d.ts.map +1 -0
  75. package/dist/completeness-BeqcskAI.js +228 -0
  76. package/dist/evidence/adapters/agent-eval.d.ts +26 -0
  77. package/dist/evidence/adapters/agent-eval.d.ts.map +1 -0
  78. package/dist/evidence/adapters/audit-script.d.ts +25 -0
  79. package/dist/evidence/adapters/audit-script.d.ts.map +1 -0
  80. package/dist/evidence/adapters/cargo-mutants.d.ts +3 -0
  81. package/dist/evidence/adapters/cargo-mutants.d.ts.map +1 -0
  82. package/dist/evidence/adapters/junit.d.ts +17 -0
  83. package/dist/evidence/adapters/junit.d.ts.map +1 -0
  84. package/dist/evidence/adapters/registry.d.ts +63 -0
  85. package/dist/evidence/adapters/registry.d.ts.map +1 -0
  86. package/dist/evidence/adapters/sarif.d.ts +35 -0
  87. package/dist/evidence/adapters/sarif.d.ts.map +1 -0
  88. package/dist/evidence/adapters/sbom.d.ts +35 -0
  89. package/dist/evidence/adapters/sbom.d.ts.map +1 -0
  90. package/dist/evidence/adapters/types.d.ts +55 -0
  91. package/dist/evidence/adapters/types.d.ts.map +1 -0
  92. package/dist/evidence/index.d.ts +11 -1
  93. package/dist/evidence/index.d.ts.map +1 -1
  94. package/dist/evidence/record.d.ts +6 -0
  95. package/dist/evidence/record.d.ts.map +1 -1
  96. package/dist/evidence/store.d.ts +124 -8
  97. package/dist/evidence/store.d.ts.map +1 -1
  98. package/dist/evidence/types.d.ts +110 -5
  99. package/dist/evidence/types.d.ts.map +1 -1
  100. package/dist/evidence-FRF9RN77.js +595 -0
  101. package/dist/{flow-command-BSMqxass.js → flow-command-BrzzKBo9.js} +1 -1
  102. package/dist/index.js +6 -6
  103. package/dist/{modules-Ckfaq5p4.js → modules-_FQTZ3gx.js} +2 -2
  104. package/dist/{plugins-CLuXx2Jr.js → plugins-Q1MtCIE5.js} +1 -1
  105. package/dist/quire/contract.d.ts +1 -1
  106. package/dist/quire/contract.d.ts.map +1 -1
  107. package/dist/quire/exec.d.ts +44 -0
  108. package/dist/quire/exec.d.ts.map +1 -0
  109. package/dist/quire/index.d.ts +1 -0
  110. package/dist/quire/index.d.ts.map +1 -1
  111. package/dist/{quire-MbMdffPh.js → quire-Dis3ky5t.js} +316 -262
  112. package/dist/{version-By2YFRZQ.js → version-D0l3nDPZ.js} +1 -1
  113. package/dist/{write-8JJ8Dumo.js → write-CMA6BDUq.js} +1 -1
  114. package/package.json +2 -1
  115. package/skills/spec-evidence-analysis/SKILL.md +27 -11
  116. package/skills/spec-fuzz/SKILL.md +94 -0
  117. package/skills/spec-fuzz/assets/templates/atheris.py.md +74 -0
  118. package/skills/spec-fuzz/assets/templates/cargo-fuzz.rs.md +83 -0
  119. package/skills/spec-fuzz/assets/templates/fast-check.ts.md +76 -0
  120. package/skills/spec-fuzz/references/step-0-scope-and-harness.md +51 -0
  121. package/skills/spec-fuzz/references/step-1-select-obligations.md +47 -0
  122. package/skills/spec-fuzz/references/step-2-ground-entry-point.md +55 -0
  123. package/skills/spec-fuzz/references/step-3-emit-targets.md +65 -0
  124. package/skills/spec-fuzz/references/step-4-report.md +56 -0
  125. package/dist/evidence-BvUyw-Yv.js +0 -171
@@ -11,7 +11,7 @@ function a(e) {
11
11
  return e || i();
12
12
  }
13
13
  function o() {
14
- return a("0.15.1");
14
+ return a("0.19.2");
15
15
  }
16
16
  //#endregion
17
17
  export { a as n, o as t };
@@ -1,4 +1,4 @@
1
- import { i as e } from "./base-CtpwIg4M.js";
1
+ import { i as e } from "./base-BE20w0jY.js";
2
2
  import { n as t, r as n, t as r } from "./config-schema-Dp-vlxuR.js";
3
3
  import { ConfigService as i } from "@agent-ix/ix-cli-core";
4
4
  import { existsSync as a, readFileSync as o, statSync as s } from "node:fs";
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@agent-ix/quoin",
3
3
  "description": "Spec-driven development for Claude Code — author validated, ISO/IEC/IEEE 29148-aligned specs, then plan and build against them.",
4
- "version": "0.15.1",
4
+ "version": "0.19.2",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "files": [
@@ -97,6 +97,7 @@
97
97
  "zod": ">=4.4.3"
98
98
  },
99
99
  "devDependencies": {
100
+ "@agent-ix/quire-cli": "^0.23.0",
100
101
  "@types/node": "26.1.2",
101
102
  "@typescript-eslint/eslint-plugin": "8.66.0",
102
103
  "@typescript-eslint/parser": "8.66.0",
@@ -23,7 +23,22 @@ declared catalog**, and flags where the authored choice disagrees.
23
23
  - At **Matrix** time, to plan which suites the chosen methods imply.
24
24
  - Whenever a new NFR is added — NFRs are the ones most prone to a defaulted method.
25
25
 
26
- ## Read the catalog, do not recall it
26
+ ## Run the advisor, do not recall the table
27
+
28
+ ```bash
29
+ quoin advise # every obligation, with its recommendations
30
+ quoin advise --mismatch-only # only where the authored method disagrees
31
+ quoin advise --inconclusive-only # only where no rule matched — your work list
32
+ quoin advise --json # for scripting
33
+ ```
34
+
35
+ `quoin advise` derives the obligations from `quire coverage --json`, reads each
36
+ criterion's FR-052 property shape from `quire properties --json`, and matches
37
+ both against the catalog's `applicability` rules. **This is the deterministic
38
+ half of the analysis and it is not optional** — a method you recalled is a
39
+ method nobody can check.
40
+
41
+ The catalog behind it:
27
42
 
28
43
  ```bash
29
44
  quoin catalog methods # human-readable, grouped by class
@@ -31,28 +46,29 @@ quoin catalog methods --json # the merged catalog, for scripting
31
46
  quoin catalog methods --class Analysis
32
47
  ```
33
48
 
34
- The catalog is merged first-wins across active modules, exactly as quire-rs
35
- merges it — so the method you are advised is the method the auditor will later
36
- check conformance against.
49
+ Merged first-wins across active modules, exactly as quire-rs merges it — so the
50
+ method you are advised is the method the auditor will later check conformance
51
+ against.
37
52
 
38
53
  ## Process
39
54
 
40
- 1. **Derive the obligations.** `quire coverage --json` carries them
41
- (quire-rs FR-053): id, statement, statement hash, authored method,
42
- criticality. Do not restate them by hand.
55
+ 1. **Run `quoin advise`.** It carries the obligations (quire-rs FR-053: id,
56
+ statement, hash, authored method, criticality) *and* the recommendations.
57
+ Do not restate either by hand.
43
58
 
44
59
  2. **Take the deterministic recommendations first.** They come from the
45
60
  catalog's `applicability` rules matched against facts about the obligation:
46
- its statement's characteristics, its FR-052 property shape, the object types
47
- near it, its archetype. Rules match or they do not.
61
+ its statement's characteristics, its FR-052 property shape, its archetype.
62
+ Rules match or they do not. Each recommendation names the rule and the value
63
+ that matched, so you can check the reasoning rather than trust it.
48
64
 
49
65
  3. **Judge only the residue, and label it.** Where the rules are inconclusive
50
66
  the advisor says so and stops rather than guessing. That is where your
51
67
  judgement belongs — and it must be recorded *as* judgement. Never present an
52
68
  LLM conclusion as a verdict (the ADR-0010 discipline).
53
69
 
54
- 4. **Confirm or correct the authored method.** A flagged mismatch is advisory:
55
- the human decides. The confirmed method lands in the spec, becomes the
70
+ 4. **Confirm or correct the authored method.** A mismatch (`⚠` in the human
71
+ output, `mismatch: true` in JSON) is advisory: the human decides. The confirmed method lands in the spec, becomes the
56
72
  obligation's method, and is what `quoin evidence` records discharge against.
57
73
 
58
74
  5. **Plan the suite.** A method implies an evidence kind; a suite in
@@ -0,0 +1,94 @@
1
+ ---
2
+ name: spec-fuzz
3
+ description: Turn Fuzz-kind obligations into runnable fuzz targets. Consumes `quoin advise
4
+ --json`, selects the obligations whose verification method carries `evidence_kind: Fuzz`,
5
+ grounds each one's entry-point symbol in the repository's source, and emits targets in the
6
+ repo's own harness (cargo-fuzz / atheris / fast-check) keyed on the obligation id. Writes
7
+ nothing where the tooling is absent or the entry point cannot be grounded — a finding
8
+ instead. Emits a validated SpecReview recording every obligation it could not serve.
9
+ ---
10
+
11
+ # Spec Fuzz
12
+
13
+ Use this skill to **generate fuzz targets from robustness requirements you already wrote**.
14
+
15
+ *"Never panic on arbitrary input"* and *"reject malformed frontmatter"* are property-shaped
16
+ over an input surface. `spec-correctness` generates example and property tests, not fuzz
17
+ targets, so a consumer that parses anything gets nothing from its spec toward a harness —
18
+ the method can be advised from the catalog and materializing it is entirely manual.
19
+
20
+ Specified by [FR-038](../../spec/functional/FR-038-generate-fuzz-harnesses.md).
21
+
22
+ ## The rule that is not negotiable
23
+
24
+ **Writing a target discharges nothing.**
25
+
26
+ This is where fuzz differs from every other generator in this family. A property test that
27
+ exists and passes is evidence. A fuzz target that exists has proved nothing — fuzzing is a
28
+ search, and an unrun target is a search never started.
29
+
30
+ The obligation is discharged by a **recorded run** (FR-030), in its own suite with
31
+ `Evidence Kind: Fuzz`. A generated target that has never run is precisely the
32
+ `vacuous-evidence` shape FR-034 exists to name. Report generated targets as **undischarged**,
33
+ always, and never imply otherwise in the handoff.
34
+
35
+ Three more:
36
+
37
+ - **Never install anything.** No `cargo install`, no dependency added, no fuzz workspace
38
+ scaffolded. Absent tooling is a finding. (CON-2.)
39
+ - **Never decide which methods are fuzz methods.** That is the catalog's, read at run time.
40
+ (CON-1.)
41
+ - **Never write a framework name into `spec/**`.** Inherited from FR-028-CON-2.
42
+
43
+ ## When to use
44
+
45
+ - After `quoin advise` recommends `fuzzing` for an obligation and nothing implements it.
46
+ - On a repository that parses untrusted or structured input and has no fuzz suite.
47
+ - To extend an existing fuzz suite to surfaces the spec names and the suite misses.
48
+
49
+ Not for: authoring the requirement (`specify`), choosing the method (`quoin advise`), or
50
+ running the fuzzer. Running is the consumer's CI — quoin transcribes, it does not execute.
51
+
52
+ ## Inputs
53
+
54
+ - The target repository.
55
+ - `quoin advise --repo <repo> --json` — obligations with their authored method and
56
+ recommendations.
57
+ - The active `verification_catalog` — which methods are Fuzz-kind, and the `tooling` each
58
+ names. **Read it; do not carry a list here.**
59
+
60
+ ## Steps
61
+
62
+ 0. **[Scope and harness](references/step-0-scope-and-harness.md)** — detect the repository's
63
+ language and fuzz tooling from its manifest. Absent tooling stops the run here, with
64
+ findings.
65
+ 1. **[Select the obligations](references/step-1-select-obligations.md)** — those whose
66
+ method has `evidence_kind: Fuzz`, from the catalog rather than by name.
67
+ 2. **[Ground the entry point](references/step-2-ground-entry-point.md)** — find the symbol
68
+ the target will call, in the source. Ungrounded means a finding, not a guess.
69
+ 3. **[Emit the targets](references/step-3-emit-targets.md)** — harness-native, two trace
70
+ carriers, one provenance line.
71
+ 4. **[Report](references/step-4-report.md)** — a validated `SpecReview` naming every
72
+ obligation not served and why, and the handoff that says the targets are undischarged.
73
+
74
+ ## What "could not be served" looks like
75
+
76
+ Three distinct outcomes, and they are not interchangeable:
77
+
78
+ | Outcome | Meaning | What to write |
79
+ |---|---|---|
80
+ | **no tooling** | the repo has no fuzz harness | finding per obligation; **no files** |
81
+ | **ungrounded** | no entry-point symbol found in the source | finding naming the obligation; **no file for it** |
82
+ | **already covered** | an existing target already claims the id | nothing; record as covered |
83
+
84
+ Never collapse these into "skipped". The first is a decision for the repository owner, the
85
+ second is a gap in the spec or the code, and the third is success.
86
+
87
+ ## Why there is no `quoin fuzz` command
88
+
89
+ The selection is mechanical and the emission is not. Choosing the entry point for
90
+ *"the parser SHALL NOT panic on arbitrary input"* means reading the parser, and a command
91
+ that guessed would produce targets that do not compile.
92
+
93
+ `quoin advise` supplies the mechanical half as JSON. This skill is the judgement half, and
94
+ it records which is which in the provenance line so a reviewer can tell them apart.
@@ -0,0 +1,74 @@
1
+ # atheris target template
2
+
3
+ One file per obligation, at `fuzz/fuzz_<obligation_slug>_<surface>.py`, executable.
4
+
5
+ Atheris instruments at import time, so **`atheris.instrument_imports()` must wrap the import
6
+ of the module under test**. An import outside that block is uninstrumented: the fuzzer runs,
7
+ reports coverage, finds nothing, and looks like it worked.
8
+
9
+ ## Bytes in, no interpretation
10
+
11
+ ```python
12
+ #!/usr/bin/env python3
13
+ """The config loader does not raise on arbitrary input.
14
+
15
+ Trace: NFR-003-M-1
16
+
17
+ spec-fuzz: obligation=NFR-003-M-1 harness=atheris entry=myapp.config.parse_config origin=advised
18
+ """
19
+
20
+ import sys
21
+
22
+ import atheris
23
+
24
+ with atheris.instrument_imports():
25
+ from myapp.config import parse_config
26
+
27
+
28
+ def test_one_input(data: bytes) -> None:
29
+ fdp = atheris.FuzzedDataProvider(data)
30
+ text = fdp.ConsumeUnicodeNoSurrogates(fdp.remaining_bytes())
31
+ try:
32
+ parse_config(text)
33
+ except (ValueError, KeyError):
34
+ # The declared rejection path. Raising a *declared* error on garbage is
35
+ # the requirement being met, so it must not read as a crash. Catch the
36
+ # exception types the requirement names — never bare `except Exception`,
37
+ # which would swallow the AttributeError and IndexError this exists to find.
38
+ pass
39
+
40
+
41
+ atheris.Setup(sys.argv, test_one_input)
42
+ atheris.Fuzz()
43
+ ```
44
+
45
+ The narrow `except` is the whole design of the file. `except Exception` turns a target that
46
+ finds real bugs into one that can never fail, and it looks more careful.
47
+
48
+ ## Which exceptions to catch
49
+
50
+ From the requirement, not from the code. If the requirement says *"rejects malformed input"*
51
+ and the code raises `ConfigError`, catch `ConfigError`. If the code also raises `TypeError`
52
+ on some path, that is a **finding** — the requirement says reject, and `TypeError` is a
53
+ crash, not a rejection.
54
+
55
+ Do not widen the catch to make the target quiet. That is the same move as widening a rule to
56
+ lower a finding count.
57
+
58
+ ## Structured input
59
+
60
+ `FuzzedDataProvider` builds typed values without a hand-rolled decoder:
61
+
62
+ ```python
63
+ def test_one_input(data: bytes) -> None:
64
+ fdp = atheris.FuzzedDataProvider(data)
65
+ document = fdp.ConsumeUnicodeNoSurrogates(fdp.ConsumeIntInRange(0, 4096))
66
+ selector = fdp.ConsumeUnicodeNoSurrogates(fdp.remaining_bytes())
67
+ try:
68
+ run_query(selector, document)
69
+ except QueryError:
70
+ pass
71
+ ```
72
+
73
+ Consume the bounded field first and the unbounded one last, or the second field is almost
74
+ always empty and half the input surface is never reached.
@@ -0,0 +1,83 @@
1
+ # cargo-fuzz target template
2
+
3
+ One file per obligation, at `fuzz/fuzz_targets/fuzz_<obligation-slug>_<surface>.rs`, plus a
4
+ `[[bin]]` block in `fuzz/Cargo.toml`.
5
+
6
+ **The `[[bin]]` block is not optional.** cargo-fuzz discovers targets from `Cargo.toml`, not
7
+ from the directory — a `.rs` file with no block is a file nobody runs, which is the same
8
+ "green over nothing" shape this whole program exists to catch.
9
+
10
+ ## Bytes in, no interpretation
11
+
12
+ ```rust
13
+ #![no_main]
14
+
15
+ use libfuzzer_sys::fuzz_target;
16
+
17
+ use quire_rs::loader::manifest::parse_manifest;
18
+
19
+ /// The manifest loader does not panic on arbitrary input.
20
+ ///
21
+ /// Trace: NFR-003-M-1
22
+ ///
23
+ /// spec-fuzz: obligation=NFR-003-M-1 harness=cargo-fuzz entry=loader::manifest::parse_manifest origin=advised
24
+ fuzz_target!(|data: &[u8]| {
25
+ // `from_utf8` rather than `from_utf8_lossy`: lossy conversion silently
26
+ // repairs the invalid sequences that are the most interesting inputs a
27
+ // byte fuzzer produces, so the parser never sees them.
28
+ if let Ok(text) = std::str::from_utf8(data) {
29
+ let _ = parse_manifest(text);
30
+ }
31
+ });
32
+ ```
33
+
34
+ Note what is absent: no `unwrap()`, no assertion on the result, no `expect`. `parse_manifest`
35
+ returning `Err` on garbage **is the requirement being met**. The `let _ =` is deliberate.
36
+
37
+ ## Structured input, via `arbitrary`
38
+
39
+ Where the surface takes a typed value rather than bytes, derive `Arbitrary` instead of
40
+ hand-rolling a decoder — a hand-rolled one spends most of the corpus failing its own parse
41
+ before reaching the code under test.
42
+
43
+ ```rust
44
+ #![no_main]
45
+
46
+ use arbitrary::Arbitrary;
47
+ use libfuzzer_sys::fuzz_target;
48
+
49
+ use quire_rs::query::{run_query, Query};
50
+
51
+ #[derive(Arbitrary, Debug)]
52
+ struct Input {
53
+ document: String,
54
+ selector: String,
55
+ }
56
+
57
+ /// The query engine does not panic on any selector against any document.
58
+ ///
59
+ /// Trace: FR-010-AC-3
60
+ ///
61
+ /// spec-fuzz: obligation=FR-010-AC-3 harness=cargo-fuzz entry=query::run_query origin=authored
62
+ fuzz_target!(|input: Input| {
63
+ if let Ok(query) = Query::parse(&input.selector) {
64
+ let _ = run_query(&query, &input.document);
65
+ }
66
+ });
67
+ ```
68
+
69
+ `arbitrary` must be a declared dependency of the **fuzz** crate. If it is not, that is the
70
+ absent-tooling case from step 0 — add nothing, report it.
71
+
72
+ ## The `[[bin]]` block
73
+
74
+ ```toml
75
+ [[bin]]
76
+ name = "fuzz_nfr_003_m_1_parse_manifest"
77
+ path = "fuzz_targets/fuzz_nfr_003_m_1_parse_manifest.rs"
78
+ test = false
79
+ doc = false
80
+ ```
81
+
82
+ `test = false` and `doc = false` keep the target out of `cargo test` and `cargo doc`, which
83
+ is what stops a nightly-only target from breaking a stable build.
@@ -0,0 +1,76 @@
1
+ # fast-check target template
2
+
3
+ TypeScript has no libFuzzer equivalent in ordinary use, so the harness is `fast-check`
4
+ running in the repo's existing test runner. That has one consequence worth stating: **this is
5
+ a bounded search, not a fuzzing campaign.** It runs for N cases and stops.
6
+
7
+ Say so in the report rather than implying parity with cargo-fuzz.
8
+
9
+ ## Placement is the thing that bites
10
+
11
+ The `Trace:` carrier goes **immediately above `it(`** — never above `describe(`. A `describe`
12
+ block groups tests and registers no symbol of its own, so a tag above it binds to nothing
13
+ while reading correctly and matching a grep (`agent-ix/quoin#61`).
14
+
15
+ ```ts
16
+ import fc from "fast-check";
17
+ import { describe, expect, it } from "vitest";
18
+
19
+ import { parseManifest } from "../src/manifest.js";
20
+
21
+ describe("the manifest parser under arbitrary input", () => {
22
+ // The parser does not throw an unexpected error on any string.
23
+ //
24
+ // Trace: NFR-003-M-1
25
+ //
26
+ // spec-fuzz: obligation=NFR-003-M-1 harness=fast-check entry=parseManifest origin=advised
27
+ it("NFR-003-M-1 never throws outside its declared rejection", () => {
28
+ fc.assert(
29
+ fc.property(fc.string(), (text) => {
30
+ try {
31
+ parseManifest(text);
32
+ } catch (error) {
33
+ // The declared rejection path. Any OTHER error is the bug this
34
+ // target exists to find, so it is rethrown rather than swallowed —
35
+ // a bare catch would make this target incapable of failing.
36
+ if (!(error instanceof ManifestError)) throw error;
37
+ }
38
+ }),
39
+ { numRuns: 10_000 },
40
+ );
41
+ });
42
+ });
43
+ ```
44
+
45
+ ## Generators that reach past the first parse
46
+
47
+ `fc.string()` finds shallow crashes and then plateaus — almost every case fails validation in
48
+ the first few bytes and the code behind it is never reached. Where the surface takes
49
+ structured text, build the structure and mutate it:
50
+
51
+ ```ts
52
+ const manifestish = fc.record({
53
+ name: fc.string(),
54
+ version: fc.oneof(fc.string(), fc.constant("1.0.0")),
55
+ entries: fc.array(fc.record({ id: fc.string(), ref: fc.string() }), { maxLength: 8 }),
56
+ });
57
+
58
+ fc.assert(
59
+ fc.property(manifestish, (value) => {
60
+ try {
61
+ parseManifest(JSON.stringify(value));
62
+ } catch (error) {
63
+ if (!(error instanceof ManifestError)) throw error;
64
+ }
65
+ }),
66
+ );
67
+ ```
68
+
69
+ Mixing `fc.constant("1.0.0")` into an otherwise arbitrary field is deliberate: it keeps a
70
+ fraction of cases valid enough to get past the field's own check, which is where the
71
+ interesting behaviour is.
72
+
73
+ ## Seeds and reproduction
74
+
75
+ `fc.assert` prints the failing counterexample and its seed. Put the seed in the bug, not a
76
+ copy of the input — the seed reproduces the shrink as well as the failure.
@@ -0,0 +1,51 @@
1
+ # Step 0: Scope and harness
2
+
3
+ **Goal**: know what the repository can actually run before generating anything for it.
4
+
5
+ ## Detect the harness from the manifest, never from the requirement
6
+
7
+ The requirement says *"the parser SHALL NOT panic on arbitrary input"*. It does not say Rust.
8
+ The **repository's manifest** says Rust, and that is the only thing that may choose a harness
9
+ (FR-038-AC-7).
10
+
11
+ | Manifest | Harness | Present when |
12
+ |---|---|---|
13
+ | `Cargo.toml` | cargo-fuzz / libFuzzer | a `fuzz/Cargo.toml` exists with `cargo-fuzz = true`, or `cargo fuzz --version` resolves |
14
+ | `pyproject.toml` / `setup.py` | atheris | `atheris` is a declared dev-dependency |
15
+ | `package.json` | fast-check | `fast-check` is a declared dependency |
16
+
17
+ A repository with several manifests has several harnesses; scope each obligation to the one
18
+ its entry point lives in.
19
+
20
+ ## Absent tooling stops the run
21
+
22
+ If the manifest is present but the harness is not, **stop here**. Emit one finding per
23
+ selected obligation and write no files (FR-038-AC-4).
24
+
25
+ Do not:
26
+
27
+ - run `cargo install cargo-fuzz`
28
+ - add `atheris` or `fast-check` to a dependency list
29
+ - create `fuzz/Cargo.toml`, a `[[bin]]` block, or a nightly toolchain file
30
+
31
+ A fuzz workspace is not a generated artifact. It is a dev-dependency, a nightly toolchain
32
+ requirement and a CI job, and adding all three to somebody's repository because their spec
33
+ mentioned a parser is a decision that belongs to them (ADR-0011: generated artifacts are
34
+ consumer-owned).
35
+
36
+ The finding is the deliverable in this case, and it is a good one — it says *"your spec
37
+ declares N fuzzable surfaces and this repository cannot fuzz"*, which is a fact nobody had
38
+ written down.
39
+
40
+ ## Record what you detected
41
+
42
+ The provenance line carries it, so a re-run and a reviewer can both see which harness was
43
+ chosen and why:
44
+
45
+ ```
46
+ spec-fuzz: obligation=NFR-012-M-2 harness=cargo-fuzz entry=quire_rs::parse_document origin=advised
47
+ ```
48
+
49
+ `origin ∈ {advised, authored}` — whether the method came from `quoin advise`'s
50
+ recommendation or from the requirement's own `Verification` cell. They are different claims
51
+ and the distinction survives into the report.
@@ -0,0 +1,47 @@
1
+ # Step 1: Select the obligations
2
+
3
+ **Goal**: the set of obligations that want a fuzz target, decided by module data.
4
+
5
+ ## The selector
6
+
7
+ An obligation is in scope when its verification method carries **`evidence_kind: Fuzz`** in
8
+ the active `verification_catalog`.
9
+
10
+ ```
11
+ quoin advise --repo <repo> --json
12
+ quoin catalog methods --json # the catalog, with each method's evidence_kind
13
+ ```
14
+
15
+ Take the method from the obligation's authored `Verification` cell if it has one, and from
16
+ the top recommendation otherwise. Record which in `origin=` (step 0).
17
+
18
+ ## Do not carry a list of fuzz methods here
19
+
20
+ Today the catalog declares two — `fuzzing` and `grammar-based-fuzzing`. **Do not hardcode
21
+ those two names.** A module adding a third, or renaming one, must change this skill's
22
+ behaviour without changing this skill (FR-038-CON-1).
23
+
24
+ The test for "is this a fuzz method" is `evidence_kind === "Fuzz"`, every time.
25
+
26
+ ## Two facts about today's catalog worth knowing
27
+
28
+ Neither changes the selector; both change what you should expect to see.
29
+
30
+ **`grammar-based-fuzzing` is never advised.** It is keyed on `structured-input` and
31
+ `grammar-declared`, and `characteristicsOf` mints neither, so no statement can reach it
32
+ (`agent-ix/quoin#128`). It arrives only as an authored method. If you were expecting the
33
+ advisor to suggest it for a grammar, that is why it did not.
34
+
35
+ **`fuzzing` is advised from two of its three keys.** `untrusted-input` and `parser` are
36
+ mintable; `deserializer` is not. An obligation about deserialization that says neither
37
+ "untrusted" nor "pars…" will not be advised, and is a legitimate authored-method case.
38
+
39
+ ## What a good selection looks like
40
+
41
+ Obligations that survive this step describe an **input surface**: something that consumes
42
+ bytes or text from outside and must not crash. If a selected obligation is about a return
43
+ value, a threshold or an ordering, the method is wrong — say so in the report rather than
44
+ generating a target that fuzzes the wrong thing.
45
+
46
+ That is a finding about the method, not about the requirement. Do not reword the
47
+ requirement, and do not silently drop it (FR-038-AC-9).
@@ -0,0 +1,55 @@
1
+ # Step 2: Ground the entry point
2
+
3
+ **Goal**: the symbol the target will call. It must exist.
4
+
5
+ ## Why this step cannot be skipped
6
+
7
+ A property test that grounds nothing is a weak test. **A fuzz target that calls nothing is a
8
+ build error in somebody's CI**, and it arrives in a harness most reviewers do not run
9
+ locally, so it fails in the one place nobody is watching.
10
+
11
+ The entry point is therefore *found in the source*, never inferred from the requirement's
12
+ wording (FR-038-AC-2).
13
+
14
+ ## How to find it
15
+
16
+ In order, stopping at the first that resolves:
17
+
18
+ 1. **The requirement's `## Inputs` section**, if it names a symbol or a module path. This is
19
+ the author telling you directly.
20
+ 2. **An existing target in the same suite** covering a neighbouring surface — its imports
21
+ show the shape of a callable entry point in this repository.
22
+ 3. **The public surface**: a function taking `&[u8]`, `&str`, `bytes` or `string` and
23
+ returning a `Result`/`Option`, exported from the module the requirement names.
24
+
25
+ Read the function. Confirm it takes the input the requirement describes and that calling it
26
+ has no side effect outside the process — a fuzz target that writes files or opens sockets
27
+ will be killed by the fuzzer's own sanitizers and produce nothing but noise.
28
+
29
+ ## Ungrounded is a finding, not a guess
30
+
31
+ If none of the three resolves, **write no file for that obligation** and record a finding
32
+ naming it and what you looked for (FR-038-AC-3).
33
+
34
+ This is the honest outcome and it is often the useful one. *"NFR-003 declares the config
35
+ loader must not panic on arbitrary input, and there is no function in `src/` that takes
36
+ arbitrary bytes"* means either the surface does not exist yet or the requirement is about
37
+ something else. Both are worth a reviewer's attention; a generated target guessing at
38
+ `load_config()` is not.
39
+
40
+ ## Do not fuzz through a wrapper
41
+
42
+ Where the requirement names a surface and the obvious public function wraps it in file I/O,
43
+ ground on the **inner** function that takes the bytes. Fuzzing the wrapper spends the whole
44
+ run on the filesystem and reaches the parser a few thousand times instead of a few hundred
45
+ million.
46
+
47
+ Record the choice in the provenance line, because it is a judgement:
48
+
49
+ ```
50
+ spec-fuzz: obligation=NFR-003-M-1 harness=cargo-fuzz entry=loader::manifest::parse_manifest origin=advised
51
+ ```
52
+
53
+ If you grounded on an inner function while the requirement named the outer one, say so in
54
+ the report. It is the kind of thing that is obviously right when explained and looks like an
55
+ error when not.
@@ -0,0 +1,65 @@
1
+ # Step 3: Emit the targets
2
+
3
+ **Goal**: a target that compiles, runs, and reconciles.
4
+
5
+ Templates: [cargo-fuzz](../assets/templates/cargo-fuzz.rs.md) ·
6
+ [atheris](../assets/templates/atheris.py.md) ·
7
+ [fast-check](../assets/templates/fast-check.ts.md)
8
+
9
+ ## The tag contract
10
+
11
+ Inherited from `spec-correctness` step 4, unchanged, because `gap-analysis` reconciles by the
12
+ same grep. **Two independent carriers**, so one formatting change cannot break reconciliation:
13
+
14
+ 1. `Trace: NFR-003-M-1` on its own line in the doc comment or docstring.
15
+ 2. The target's own name containing the id — `fuzz_nfr_003_m_1_parse_manifest`.
16
+
17
+ ### Placement, which is where this bites
18
+
19
+ A carrier binds to the **symbol whose source span encloses it**. For a libfuzzer target that
20
+ span is the `fuzz_target!` block — so the doc comment goes immediately above `fuzz_target!`,
21
+ not at the top of the file.
22
+
23
+ A file-header comment reads correctly, passes review, matches a grep, and **binds to
24
+ nothing**. Six generated files shipped that way in `@agent-ix/quoin@0.12.x` and every
25
+ criterion in them scored zero (`agent-ix/quoin#61`). Do not verify placement with grep — grep
26
+ does not care where a comment sits, which is exactly why that shipped.
27
+
28
+ ## The provenance line
29
+
30
+ One per target, ignored by the reconciliation grep, read by this skill on re-runs:
31
+
32
+ ```
33
+ spec-fuzz: obligation=<id> harness=<harness> entry=<symbol> origin=<advised|authored>
34
+ ```
35
+
36
+ Add `wrapped=<outer-symbol>` when step 2 grounded on an inner function.
37
+
38
+ ## Idempotent re-runs
39
+
40
+ Same obligation, same harness, same entry → **leave the file alone** (FR-038-AC-6).
41
+
42
+ A changed entry point is a real change: rewrite the target and say so in the report. A
43
+ changed requirement *statement* is not — the target calls a symbol, not a sentence, so a
44
+ reworded requirement with the same surface needs no new file.
45
+
46
+ ## What the target must not do
47
+
48
+ - **No assertions about correctness.** Fuzzing looks for crashes, hangs and assertion
49
+ failures inside the code under test — not for wrong answers. An `assert_eq!` on the result
50
+ turns every interesting input into a false positive.
51
+ - **No `unwrap()` on the result.** The function returning `Err` on garbage is the requirement
52
+ being *met*. Unwrapping turns success into a crash and the fuzzer will find it in seconds.
53
+ - **No file, network or process access.** Sanitizers will kill it and the run produces noise.
54
+ - **No `panic!` as a way of reporting.** The fuzzer's crash is the report.
55
+
56
+ The body is therefore usually three lines: take the bytes, make the input the function
57
+ expects, call it and drop the result.
58
+
59
+ ## Corpus and seeds
60
+
61
+ Out of scope. A seed corpus makes a fuzzer dramatically more effective and building one from
62
+ the repository's own fixtures is real work with its own decisions.
63
+
64
+ Say so in the report rather than shipping an empty `corpus/` directory that looks like it was
65
+ considered.