# 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)
| 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)
| `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`
| 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`
| 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.