ud 0.1.0

UpDate! — A fast, universal dependency updater.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
# ud — v0.1.1 Fix & Preview-Hardening Spec

> **Status:** Approved for execution **Target version:** v0.1.1 (patch —
> behavior fixes, tests, fixtures; no frozen-surface breaks) **Baseline:**
> v0.1.0 as landed (47-file tree, kernel/ports/descriptor architecture)
> **Inputs:** post-landing code review (7 items, all verified against source) +
> alignment loop (6 decisions) **Executor contract:** this document is
> self-contained. Zero open questions. If something here contradicts the code,
> the code review already verified the code — re-read the relevant section here
> before improvising.

---

## 0. Executive Summary

v0.1.0 landed the ports-and-descriptor architecture at ~95% spec fidelity. The
remaining 5% is: two user-visible verdict regressions (yanked detection silently
dead; npm dist-tags leaking as permanent false `Outdated`), one latent kernel
coupling (`update()` re-discovers and index-aligns against `run()`'s report),
one macro footgun (inherent/trait `id()` shadowing), a set of small
report/registry polish items, and the missing §13 test matrix including the
architecture fitness functions that are the freeze's tripwire. This release
fixes all of it and, as its one feature, upgrades the preview story: the
`large_project` fixture gains a `package.json` and a `deno.json` engineered for
exhaustive case coverage (every constraint operator, every specifier form, every
skip path), with a mocked E2E mirror in `tests/multi_manifest.rs` so everything
`just preview` demonstrates live is also asserted in CI. Documentation rewrite
(review item 5) is explicitly deferred.

---

## 1. Context, Decisions, Constraints

### 1.1 Decision record (from alignment)

| #   | Decision                        | Choice                                                                                                                                                                                                                                                                                 |
| --- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| D-1 | Yanked semantics                | **(A)** `Verdict::Yanked` fires iff the constraint is satisfiable _only_ by yanked versions — i.e. no non-yanked version satisfies, but at least one yanked version does. A newer non-yanked satisfier wins and produces a normal verdict.                                             |
| D-2 | `update()`/`run()` coupling     | **(B)** Root fix: split `run` into `discover` + an internal job-driven runner. `update` discovers once and reuses the same jobs vector. The alignment invariant becomes true by construction.                                                                                          |
| D-3 | Preview fixture composition     | **(B, interpreted as exhaustive case coverage)** One entry per distinct parser / scheme / routing / skip code path — every operator modifier, every specifier form, every manifest section, every negative case. NOT raw volume: ~14 entries per new file, each with a stated purpose. |
| D-4 | CI twin for the preview         | **(B)** Extend the mocked `multi_manifest.rs` E2E to mirror the fixture's shapes, so the live preview's guarantees are CI-asserted.                                                                                                                                                    |
| D-5 | `just update` temp-copy variant | **Out of scope.** The update recipe keeps mutating the tracked fixture; developer restores with git.                                                                                                                                                                                   |
| D-6 | Docs rewrite (review item 5)    | **Out of scope, deferred.** When docs are eventually rewritten they must describe _post-v0.1.1_ behavior (tags rejected at read, Yanked reachable, three-port freeze). Recorded in §9.                                                                                                 |

### 1.2 Standing assumptions (accepted in alignment)

- All review-item-7 polish ships (see Phase 4).
- All review-item-6 tests ship (see Phase 5).
- `http_registry!` fix = macro emits a `REGISTRY_ID` constant; trait impls
  reference it.
- Dist-tag fix lives at read time: reject constraints whose parsed npm
  requirement has no range (tag form). Extended to specifier-derived constraints
  — see [EXTENSION] in §3.1.
- jsr-in-package.json fixture form: alias entries of the shape name →
  `jsr:@scope/pkg@<range>` (the Deno/Bun-flavored form ud's parser supports;
  vanilla npm's `npm:@jsr/scope__name` compat form is out of scope and must be
  called out when docs are written).
- One additive, serde-defaulted field on `Verdict::Unsatisfiable` (§3.5). The
  README freeze policy states additive changes are minor/patch bumps; this ships
  in the patch. [REVISIT] if you'd rather reserve schema additions for minor
  releases, bump to 0.2.0 instead — nothing else in this release forces that.

### 1.3 Constraints

- **Frozen surface holds:** the three ports (`Manifest`, `Registry`, `Scheme`),
  the `Ecosystem` descriptor, and the `--json` payload structure change only
  additively. `Verdict::Yanked` is already in the frozen schema; making it
  reachable again is a bug fix, not a schema change.
- **Dependency direction rule holds:** `core/` never imports `ecosystems/`;
  `resolve.rs` never touches any semver implementation. Phase 5 turns these from
  convention into fitness tests.
- **No new CLI flags. No new configuration.** Every change traces to a review
  item or to D-3/D-4.
- **Behavioral repo rules apply:** surgical diffs, no drive-by reformats, tests
  define done.

---

## 2. Architecture Overview (unchanged; point deltas only)

The kernel/ports/descriptor shape is untouched. This release makes five point
changes inside existing components:

```
main.rs ──▶ kernel (discover · run_jobs · run · update)   ◀── Phase 2 reshapes internals only
               │
               ├─▶ resolve.rs  ◀── Phase 1: yanked-satisfier check, prerelease-availability signal
               ├─▶ report.rs   ◀── Phase 4: scheme-owned prerelease check, labels, hint
               └─▶ contract.rs (frozen — no changes)
ecosystems/
  rust/  registry.rs  ◀── Phase 3: REGISTRY_ID trait impls
  web/   registry.rs  ◀── Phase 3 + Phase 4 (IgnoredAny)
         package_json.rs · deno_json.rs · specifier.rs ◀── Phase 1: dist-tag gate
core/macros.rs ◀── Phase 3: http_registry! emits REGISTRY_ID
tests/  ◀── Phases 5–6: architecture.rs (new), matrix gap-fills, fixture mirror
tests/fixtures/large_project/ ◀── Phase 6: + package.json, + deno.json
```

Core domain (model, contract, kernel, resolve) is where Phases 1–2 live;
everything else is supporting.

---

## 3. Work Packages (the what and the why, per review item)

### 3.1 WP-1 — Verdict correctness (review items 1 + 3) [HIGH RISK — user-visible semantics]

**Yanked (item 1).** `resolve::verdict` currently filters yanked versions before
any reasoning, so `Verdict::Yanked` is unreachable — a dead enum variant with
live rendering code. Restore it under D-1 semantics:

- Build the candidate set with the prerelease filter applied per options, but
  **without** the yanked filter.
- Compute whether any **non-yanked** version satisfies the constraint. If yes →
  proceed exactly as today (yanked-filtered logic, `Outdated`/`Current` as
  before).
- If no non-yanked version satisfies but at least one **yanked** version does →
  return `Verdict::Yanked`.
- If nothing satisfies at all, or the candidate set is empty → `Unsatisfiable`
  (with the §3.5 signal).
- Ordering matters: the yanked-satisfier check runs **before** the
  empty-candidates `Unsatisfiable` return, so an exact pin whose only satisfier
  is yanked reports `Yanked` even when every version in the registry is yanked.

Worked semantics (these become tests in Phase 5):

- Exact pin `1.0.0`, registry has `1.0.0 (yanked)` and `1.2.0` → `Yanked` (1.2.0
  does not satisfy an exact pin).
- Caret `^1.0.0`, registry has `1.0.0 (yanked)` and `1.4.0` → normal verdict
  (1.4.0 satisfies; the yanked floor is irrelevant).
- Exact pin `1.0.0`, registry has only `1.0.0 (yanked)` → `Yanked`, not
  `Unsatisfiable`.

`Verdict::Yanked` stays a unit variant — no schema change.

**Dist-tags (item 3).** In `package_json.rs`, a bare value like `next` passes
the `parse_npm_version_req` gate (deno_semver parses bare words as tags), flows
to `declared_floor → None → is_upgrade defaults true → Outdated forever`, and is
unfixable since `rewrite` returns `None`. Fix at read: after a successful
requirement parse, additionally require that the parsed requirement has a
version range; a tag-form requirement (no range) is skipped with the same
debug-log treatment as other skips. Keep the existing explicit
`latest`/`*`/empty checks — they're now a self-documenting fast path in front of
the general gate.

**[EXTENSION — deliberate, not scope creep].** The same bug exists via the
specifier route the review didn't flag: `npm:typescript@next` in either JSON
manifest yields a source-routed dependency with constraint `next`, which is
equally `Outdated`-forever-unfixable. Apply the identical no-range gate to
specifier-derived constraints in both `package_json.rs` and `deno_json.rs`.
Implement the gate once as a small shared predicate ("this constraint is
checkable") in the web module — `specifier.rs` is the natural home since it
already owns specifier semantics — and call it from both manifests' read paths.
Do not duplicate the deno_semver call at both sites.

**Docs note:** `overview.md` claims tags like `next` are ignored; after this WP
the claim becomes true. Do not edit the doc (D-6) — just stop contradicting it.

### 3.2 WP-2 — Kernel decoupling (review item 2)

`update()` calls `run()` (which discovers), then calls `discover` again and
indexes `report.manifests[job_idx]` assuming perfect alignment. That holds only
because `run` sorts by job index and the filesystem doesn't change between the
calls — a manifest created mid-run, or any future reordering, silently writes
edits against the wrong file's verdicts.

Per D-2: extract everything in `run` after discovery into an internal,
job-driven runner that takes the jobs slice and produces the `Report` (same
read-error synthetic rows, same fan-out resolution, same sort — behavior
byte-identical). `run` becomes discover-then-runner. `update` discovers
**once**, invokes the runner on those jobs, then iterates jobs zipped with
`report.manifests` — alignment is now guaranteed because both derive from the
same vector. Keep a defense-in-depth check that each zipped pair's paths match;
on mismatch, fail the update with an internal-invariant error rather than
writing (never write on a broken invariant — same philosophy as the
`write_batch_json` splice guard). The runner stays private to the kernel; the
public API (`discover`, `run`, `update`) is unchanged.

The residual TOCTOU on _file contents_ between resolution and write is inherent
to the design and stays out of scope.

### 3.3 WP-3 — Macro hardening (review item 4)

`http_registry!` generates an inherent `pub fn id(&self)`, and each `Registry`
trait impl is written as `fn id(&self) { self.id() }` — which resolves only
because inherent methods win over trait methods. Rename the inherent method and
it becomes silent infinite recursion (runtime stack overflow, zero compiler
warning).

Fix per the review's proposal: the macro emits an associated constant
`REGISTRY_ID: &'static str` (value = the declared id) instead of (or in addition
to — prefer _instead of_, removing the inherent method entirely so the footgun
class is gone) the inherent `id()`. All three trait impls (`CratesRegistry`,
`NpmRegistry`, `JsrRegistry`) construct their `RegistryId` from
`Self::REGISTRY_ID`. Grep for any other caller of the inherent `id()` before
deleting it; route them through the trait or the constant.

### 3.4 WP-4 — Polish (review item 7, all four)

1. **Packument memory.** `NpmPackument.versions` deserializes every version's
   full metadata into `serde_json::Value` just to throw it away. Switch the
   map's value type to serde's ignored-any deserializer. No behavior change;
   large-packument memory drops.
2. **Nameless error rows.** The synthetic `Dependency` for manifest-level read
   errors has an empty coordinate and renders as a nameless row. In the human
   reporter, when a verdict row's coordinate is empty, render the literal label
   `(manifest)` in place of the coordinate. (The file path is already in the
   section header; don't repeat it.)
3. **Scheme-owned prerelease check in the reporter.** `report.rs` has a local
   `is_prerelease` (`contains('-')`) duplicating knowledge the scheme owns, and
   the ecosystems are already passed into the renderer. Use the resolved
   scheme's `is_prerelease` where a scheme was found; keep the local heuristic
   only as the fallback for the (theoretical) no-matching-ecosystem case. Delete
   nothing else in that file.
4. **Unsatisfiable hint.** See §3.5.

### 3.5 The one additive schema change: prerelease-availability on `Unsatisfiable`

`Unsatisfiable` currently renders as "no versions found" even when the real
story is "only prereleases exist — run with `--pre`". The reporter can't know
this without data, so the signal must ride the verdict:

- `Verdict::Unsatisfiable` gains a boolean field, serde-defaulted so
  absent-field deserialization still works, alongside the existing `constraint`.
  Name it for what it means: prereleases were available but filtered.
- `resolve::verdict` sets it true exactly when: prerelease inclusion was off,
  the pre-filter version set was non-empty, and filtering prereleases is what
  emptied (or de-satisfied) the candidate set.
- The human reporter, when the flag is true, appends a dim hint after the
  existing "no versions found" text: only prereleases available — retry with
  `--pre`.
- JSON output carries the field naturally; that's the additive change licensed
  by the freeze policy (§1.2, [REVISIT] note).
- Existing tests constructing `Unsatisfiable` values (e.g. the rust pipeline
  yanked test being repurposed in Phase 1) must be updated for the new field.

---

## 4. Component Map (touched surface only)

| Path                                                                                                                                         | Change                                                                              | Phase |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ----- |
| `src/core/resolve.rs`                                                                                                                        | D-1 yanked logic; prerelease-availability signal. Still zero semver imports.        | 1     |
| `src/ecosystems/web/specifier.rs`                                                                                                            | New shared "constraint is checkable" predicate (no-range tag rejection).            | 1     |
| `src/ecosystems/web/package_json.rs`                                                                                                         | Bare-value and specifier constraints pass the tag gate.                             | 1     |
| `src/ecosystems/web/deno_json.rs`                                                                                                            | Specifier constraints pass the tag gate.                                            | 1     |
| `src/core/kernel.rs`                                                                                                                         | Internal job-driven runner; `update` single-discover; zip-with-path-guard.          | 2     |
| `src/core/macros.rs`                                                                                                                         | `http_registry!` emits `REGISTRY_ID` const; inherent `id()` removed.                | 3     |
| `src/ecosystems/rust/registry.rs`                                                                                                            | Trait impl uses `REGISTRY_ID`.                                                      | 3     |
| `src/ecosystems/web/registry.rs`                                                                                                             | Both trait impls use `REGISTRY_ID`; packument values become ignored-any.            | 3, 4  |
| `src/core/model.rs`                                                                                                                          | Additive defaulted field on `Unsatisfiable`.                                        | 4     |
| `src/core/report.rs`                                                                                                                         | `(manifest)` label; scheme-owned prerelease check; `--pre` hint.                    | 4     |
| `tests/architecture.rs`                                                                                                                      | **New.** Fitness functions (§6).                                                    | 5     |
| `tests/rust_pipeline.rs`                                                                                                                     | Yanked assertions flipped to D-1 semantics; `Unsatisfiable` field updates.          | 1, 5  |
| `tests/web_read.rs`                                                                                                                          | Tag-rejection cases (bare and specifier forms).                                     | 1, 5  |
| `tests/web_scheme.rs` / rust scheme tests                                                                                                    | `scheme_cases!` for `CargoScheme`; bare-caret vs bare-exact contrast on both sides. | 5     |
| `tests/multi_manifest.rs`                                                                                                                    | Discovery shadow test; fixture-mirroring mocked E2E (D-4); routing assertions.      | 5, 6  |
| Fan-out unit test (in `multi_manifest.rs` or a new `tests/fanout.rs` — executor's choice, prefer colocating with the existing mock registry) | Error-vs-empty never-lie branch.                                                    | 5     |
| `tests/fixtures/large_project/package.json`                                                                                                  | **New.** §7 table A.                                                                | 6     |
| `tests/fixtures/large_project/deno.json`                                                                                                     | **New.** §7 table B.                                                                | 6     |
| `tests/fixtures/large_project/Cargo.toml`                                                                                                    | **Unchanged.**                                                                      | —     |

Nothing else is touched. In particular: `contract.rs`, `main.rs`, CLI flags,
`json_walk.rs`, all just recipes, and every doc file are frozen for this
release.

---

## 5. Trade-off Blocks (decisions carried from alignment)

```
DECISION: When does Verdict::Yanked fire?
OPTIONS:  A. Only when the constraint is satisfiable solely by yanked versions.
          B. Whenever the declared floor is yanked, even with better satisfiers.
CHOSEN:   A
REASON:   Matches the v0.0.4 signal ("your pinned version was yanked") with zero
          noise; B spams warnings for ^-ranges whose floor happens to be yanked.
          Also matches how real resolvers behave: they route around yanked
          versions when the range permits.
REVISIT IF: users ask for a "floor is yanked" informational note — that would be
          a new report annotation, not a verdict change.
```

```
DECISION: Fix update()/run() coupling by path-matching or by restructuring?
OPTIONS:  A. Match ManifestReport to Job by path (band-aid).
          B. Single discover; internal job-driven runner shared by run and update.
CHOSEN:   B
REASON:   A patches the symptom while the double-discover TOCTOU remains; B makes
          the invariant structural. kernel.rs is small; the refactor is cheap now
          and expensive later (year-3 argument: every new kernel entry point
          would re-inherit the trap under A).
REVISIT IF: never — plus a path guard as belt-and-braces.
```

```
DECISION: Preview fixture: exhaustive cases vs realistic volume?
OPTIONS:  A. ~5 deps, happy paths only.
          B. Exhaustive case coverage: every operator, specifier form, section,
             and negative case (user's choice, interpreted per D-3).
          C. ~60 realistic deps mirroring Cargo.toml.
CHOSEN:   B
REASON:   The preview's job is to prove code paths against live registries, and
          B is the smallest fixture that proves all of them. C costs ~120 live
          HTTP calls per preview and proves nothing extra; A leaves the operator
          and negative paths demonstrated nowhere.
REVISIT IF: preview runtime becomes annoying — trim negative cases first (they
          cost zero HTTP anyway; the trim would be cosmetic).
```

```
DECISION: Are the fixture's guarantees CI-asserted?
OPTIONS:  A. No — preview is a manual live smoke; CI keeps existing mocks.
          B. Yes — mocked multi-manifest E2E mirrors the fixture's shapes.
CHOSEN:   B
REASON:   Without B, the exact source-mixing and operator-preservation
          combinations the preview demonstrates are asserted nowhere a machine
          can see; live-network tests are not an option (flaky, slow, rate-limited).
REVISIT IF: never.
```

```
DECISION: Where does the dist-tag rejection live?
OPTIONS:  A. Read time (manifest parsers), via the no-range check.
          B. Resolve time (treat rangeless constraints as skip verdicts).
CHOSEN:   A
REASON:   A tag is not a checkable dependency declaration — it should never
          become a Dependency at all. B would force the frozen Verdict enum to
          grow a skip concept, and resolve.rs to learn requirement parsing it
          is architecturally forbidden from having.
REVISIT IF: a future "show skipped entries" feature wants tags surfaced —
          that's a read-layer report concern, still not resolve's.
```

---

## 6. Phased Implementation Plan

Phases are independently shippable; each ends green. Regression tests are
written **before** the fix they pin, per repo convention.

### Phase 1 — Verdict correctness (WP-1) [ships user-visible fixes]

- **Goal:** `Yanked` reachable under D-1; dist-tags never enter the pipeline.
- **Steps:**
  1. Flip the existing rust-pipeline yanked test from asserting `Unsatisfiable`
     to asserting `Yanked` (it currently pins the bug) → _verify: test fails
     against v0.1.0 code._
  2. Add resolve unit tests for the three worked-semantics cases in §3.1 →
     _verify: red._
  3. Implement the D-1 resolve logic → _verify: green, and all pre-existing
     resolve tests still pass unchanged._
  4. Add web_read tests: bare `next` value skipped; `npm:…@next` specifier
     skipped in both JSON manifests; `latest`/`*` still skipped → _verify: red._
  5. Add the shared checkable-constraint predicate; wire both manifests →
     _verify: green._
- **Exit criteria:** full `cargo test` green; a scratch package.json containing
  a tag dependency produces no row for it in `run` output.
- **Risk flags:** [HIGH RISK] semantics change — the worked examples in §3.1 are
  normative; if implementation and examples disagree, the examples win.

### Phase 2 — Kernel decoupling (WP-2)

- **Goal:** one discovery per `update`; alignment structural.
- **Steps:** extract runner → _verify: `run` behavior byte-identical (existing
  multi-manifest E2E green untouched)_ → rewire `update` with the zip + path
  guard → _verify: E2E green, including the idempotent rerun._
- **Exit criteria:** `discover` is called exactly once per `update` invocation
  (assert by inspection/trace); no public API change.
- **Risk flags:** the read-error synthetic-row path must survive the extraction
  — it's the easiest behavior to drop silently.

### Phase 3 — Macro hardening (WP-3)

- **Goal:** the `id()` recursion footgun is structurally impossible.
- **Steps:** macro emits `REGISTRY_ID`, inherent `id()` deleted, three trait
  impls rewired → _verify: compile; grep confirms no remaining inherent `id` on
  registry types; existing registry tests green._
- **Exit criteria:** renaming anything in this area now produces compile errors,
  never recursion.

### Phase 4 — Polish (WP-4 + §3.5)

- **Goal:** the four small items, including the additive schema field.
- **Steps:** ignored-any packument → `(manifest)` label → scheme-owned
  prerelease in reporter → `Unsatisfiable` field + resolve signal + reporter
  hint, updating every test that constructs `Unsatisfiable` → _verify after
  each: green._
- **Exit criteria:** JSON output for an unsatisfiable-because-prerelease-only
  dep carries the new field as true; human output shows the `--pre` hint; a
  manifest parse error renders a `(manifest)` labeled row.
- **Risk flags:** [REVISIT] version-number policy note from §1.2 applies here
  and only here.

### Phase 5 — Test-matrix completion & fitness functions (review item 6)

- **Goal:** the freeze gets its tripwires; every §13 gap closes.
- **Deliverables:**
  1. **`tests/architecture.rs`** — two fitness functions reading source files at
     test time:
     - No file under `src/core/` imports the ecosystems module (check for the
       crate-relative ecosystems path in any `use` or path expression).
     - `resolve.rs` depends on no semver implementation. **Precision matters:**
       a naive check for the pattern `semver::` also matches inside
       `deno_semver::` — anchor the check so a path segment beginning exactly
       with `semver` and the deno_semver crate name are each independently
       forbidden. Both greps must be documented in the test as the freeze's
       enforcement.
  2. **Discovery shadow test** — a temp dir containing both `deno.json` and
     `deno.jsonc` discovers only `deno.json` (file_names order is the contract).
  3. **Fan-out never-lie test** — source-less dep, one mock registry returns an
     error, all others return empty → `availability` must be an error, never
     silently empty. Also assert the inverse: one non-empty + one error → Ok
     with the merged versions (current documented behavior).
  4. **`scheme_cases!` for `CargoScheme`** — satisfies/rewrite tables asserting
     bare-means-caret on the rust side, sitting next to (or referencing) the
     node bare-means-exact table so the contrast is asserted on both sides.
  5. **Complex-range reported-but-skipped E2E** — mocked: a range like
     `>=1.0.0 <2.0.0` appears as `Outdated` in the report, the file is
     byte-identical after `update`, and human output with update shows the
     skipped-complex-range notice.
- **Exit criteria:** deleting the dependency-direction rule from any source file
  breaks CI within this test file. All five tests green.

### Phase 6 — Preview fixture + mocked mirror (D-3, D-4)

- **Goal:** `just preview` exercises all three registries, both JSON manifests,
  and every case in §7; CI asserts the same shapes with mocks.
- **Steps:**
  1. Materialize `tests/fixtures/large_project/package.json` and `deno.json`
     from the §7 tables → _verify: `just preview` (post-build) renders three
     manifest sections; every positive row shows the expected verdict class; no
     negative-case row appears._
  2. Extend `tests/multi_manifest.rs` per §8 → _verify: green, including the
     routing assertions and idempotent rerun._
- **Exit criteria:** live preview shows: fan-out rows (bare deps), a scoped-bare
  row proving the live JSR 404→empty path, source-routed npm and jsr rows, every
  operator preserved in the rendered target constraint, and zero rows for
  tags/protocols/versionless entries. Mocked mirror asserts the same shapes
  deterministically.
- **Dependencies:** Phase 1 (fixture's tag entries must be skipped, not shown)
  and Phase 2 (update-path assertions in the mirror rely on the decoupled
  kernel).
- **Risk flags:** live registry data drifts; §7's expected-verdict column pins
  the _class_ of outcome, not exact versions. The executor must sanity-check at
  implementation time that each pinned floor is still several versions behind
  latest (they are, by years, as of 2026-07 — but verify).

**Sequencing / critical path:** 1 → (2, 3, 4 in any order) → 5 → 6. Phase 1 is
the critical path: Phases 5 and 6 both assert its semantics.

---

## 7. Preview Fixture Specification (normative content)

Materialize these as ordinary JSON (package.json) and JSON (deno.json — plain,
not jsonc). Every entry exists to prove the stated case; do not add, rename, or
"improve" entries. All coordinates are real, live packages; all pins are
deliberately old so the preview always shows movement.

### Table A — `tests/fixtures/large_project/package.json`

| #  | Section              | Entry (name → value)                   | Case proved                                                                 | Expected preview outcome                                   |
| -- | -------------------- | -------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------- |
| 1  | dependencies         | `react` → `^17.0.2`                    | bare caret; fan-out; unscoped name takes the JSR zero-HTTP shortcut         | Outdated: compatible within 17.x, breaking-latest suffix   |
| 2  | dependencies         | `@types/node` → `>=18.0.0`             | scoped bare; `>=` operator; fan-out where the live JSR request 404s → empty | Outdated; `>=` preserved on target                         |
| 3  | dependencies         | `lodash` → `4.17.20`                   | bare exact (node bare-means-exact)                                          | Outdated; bare form preserved                              |
| 4  | dependencies         | `express` → `~4.17.1`                  | tilde operator                                                              | Outdated; `~` preserved                                    |
| 5  | dependencies         | `rimraf` → `=5.0.0`                    | explicit `=` operator                                                       | Outdated; `=` preserved                                    |
| 6  | dependencies         | `glob` → `>=10.0.0 <11.0.0`            | complex range: read + reported, never rewritten                             | Outdated in check mode; skipped-complex-range under update |
| 7  | dependencies         | `chalk-legacy` → `npm:chalk@^4.1.0`    | `npm:` alias specifier; source-routed (no fan-out)                          | Outdated (chalk 5+ breaking)                               |
| 8  | dependencies         | `std-fs` → `jsr:@std/fs@^1.0.0`        | `jsr:` alias in package.json; source-routed to JSR                          | Outdated or Current-with-compatible-bumps within 1.x       |
| 9  | dependencies         | `typescript` → `next`                  | **negative:** dist-tag rejected at read (Phase 1)                           | absent from output                                         |
| 10 | dependencies         | `local-lib` → `file:../local-lib`      | **negative:** protocol skip                                                 | absent                                                     |
| 11 | dependencies         | `ws-lib` → `workspace:*`               | **negative:** protocol skip                                                 | absent                                                     |
| 12 | dependencies         | `std-path-noversion` → `jsr:@std/path` | **negative:** versionless specifier skip                                    | absent                                                     |
| 13 | devDependencies      | `vitest` → `^1.0.0`                    | section coverage: devDependencies                                           | Outdated                                                   |
| 14 | peerDependencies     | `react-dom` → `^17.0.2`                | section coverage: peerDependencies                                          | Outdated                                                   |
| 15 | optionalDependencies | `fsevents` → `^2.3.2`                  | section coverage: optionalDependencies                                      | Outdated or Current                                        |

### Table B — `tests/fixtures/large_project/deno.json`

| # | Entry (imports key → value)              | Case proved                                               | Expected preview outcome                |
| - | ---------------------------------------- | --------------------------------------------------------- | --------------------------------------- |
| 1 | `@std/fs` → `jsr:@std/fs@^1.0.0`         | jsr specifier, caret                                      | Outdated/Current within 1.x             |
| 2 | `@std/path` → `jsr:@std/path@~1.0.0`     | jsr specifier, tilde                                      | tilde preserved                         |
| 3 | `@oak/oak` → `jsr:@oak/oak@14`           | partial (major-only) constraint: reported, not rewritable | Outdated in check; skipped under update |
| 4 | `chalk` → `npm:chalk@^4.1.0`             | npm specifier inside deno.json                            | Outdated                                |
| 5 | `lodash` → `npm:lodash@4.17.20`          | npm specifier, exact                                      | Outdated; bare form preserved           |
| 6 | `@luca/cases` → `jsr:@luca/cases@^1.0.0` | second live JSR package (scope variety)                   | Current or Outdated                     |
| 7 | `typescript` → `npm:typescript@next`     | **negative:** tag via specifier ([EXTENSION] gate)        | absent                                  |
| 8 | `@std/internal` → `jsr:@std/internal`    | **negative:** versionless specifier                       | absent                                  |
| 9 | `utils/` → `./src/utils/`                | **negative:** relative path import (not a specifier)      | absent                                  |

Formatting rule for both files: ordinary two-space-indented JSON, keys in the
table order — the point is a human eyeballs `just preview` against these tables.

---

## 8. Mocked Mirror Specification (`tests/multi_manifest.rs` extension)

Extend the existing mock-registry E2E so CI asserts what the live preview only
demonstrates. The mocked temp-dir project mirrors §7's _shapes_ with smaller
version universes. Required assertions, on top of everything the test already
checks:

1. **Mixed sources within one file:** the mocked package.json contains at least
   a bare dep, an `npm:` alias, and a `jsr:` alias; the mocked deno.json
   contains at least one `jsr:` and one `npm:` specifier. All resolve; all
   appear under the correct manifest section of the report.
2. **Routing correctness (no accidental fan-out):** the npm mock and jsr mock
   serve _different_ version sets for the same coordinate. Assert a
   source-routed jsr dep resolves against the jsr mock's data and a
   source-routed npm dep against the npm mock's — proving source presence
   suppresses fan-out.
3. **Fan-out union:** a bare dep served (with disjoint version sets) by both
   mocks resolves against the merged set.
4. **Operator preservation per operator:** after `update`, the rewritten file
   preserves `^`, `~`, `>=`, `=`, and bare-exact forms respectively; the
   complex-range entry and the partial-version entry are byte-identical to
   before.
5. **Negative cases:** a tag entry, a protocol entry, and a versionless
   specifier appear in the temp files and in **no** report row.
6. **Idempotency:** second `update` changes nothing (already asserted — keep it
   green across the new entries).
7. **Yanked passthrough (mocked):** one exact-pinned dep whose only satisfying
   mock version is yanked asserts `Verdict::Yanked` end-to-end through the
   kernel — the live fixture can't safely demonstrate this, so the mock must.

---

## 9. Deferred & Out of Scope (the record)

- **Docs rewrite (review item 5) — deferred by D-6.** The README still documents
  the pre-0.1.0 flat JSON schema (`source_hint`), declares the freeze as two
  traits instead of three ports + descriptor, omits the web ecosystem;
  overview.md oversells discovery as recursive. **When docs are written, they
  must describe post-v0.1.1 behavior** (tags rejected at read, `Yanked`
  reachable per D-1, the `Unsatisfiable` prerelease field, the three-port
  freeze, the supported jsr-in-package.json alias form and the explicit
  non-support of npm's `@jsr/…` compat form). Until then: known-stale,
  deliberately untouched.
- **`just update` temp-copy variant — rejected in alignment (D-5).** Running
  `just update` against the enhanced fixture now mutates three tracked files;
  restore with git.
- **Live-network CI, `--recursive` discovery, python/go ecosystems,
  complex-range rewriting, registry attribution in merged output** — unchanged
  from the v0.1.0 out-of-scope list.
- **Content TOCTOU between resolve and write** — inherent; out of scope (§3.2).

## Risks

- **Live-registry drift (Phase 6):** expected outcomes are pinned by class, not
  version; executor re-verifies floors are stale at implementation time.
- **D-1 edge disagreements:** the worked examples in §3.1 are normative; any
  implementation/example conflict resolves in favor of the examples.
- **Schema-field version policy:** additive-at-patch is licensed by the README's
  own freeze wording, but see [REVISIT] in §1.2 if the policy reading changes.
- **Fitness-test false negatives:** the `deno_semver`/`semver` substring overlap
  in §6-Phase-5 is the one place a lazy grep silently passes while enforcing
  nothing — the anchoring note there is load-bearing.