docs: add runnable Node package manifest walkthrough

[shoaibyazdani]

Closes #20

This adds a runnable Node package manifest walkthrough to docs/EXAMPLES.md,
reusing the existing benchmarks/node-package/ fixture and its Python oracle.
Every command below was executed from the repository root with the temporary
output parent outside the fixture.

python3 scripts/check_docs.py

Documentation check passed (44 Markdown file(s)).

python3 benchmarks/run_offline.py --only node-package

PASS node-package
offline benchmarks: 1 passed, 0 skipped, 0 failed

Payload validation evidence

out_parent="$(mktemp -d /tmp/repomin-node-package.XXXXXX)"
PYTHONPATH=src python3 -m repomin benchmarks/node-package \
  --command 'python3 reproduce.py' \
  --match 'ORIGINAL_FAILURE' \
  --adapter node \
  --source-reducer none \
  --output "$out_parent/result"

PYTHONPATH=src python3 -m repomin report validate \
  "$out_parent/result.repomin/report.json" \
  --payload "$out_parent/result" --json

{
  "accepted_mutations": 6,
  "attempts": 36,
  "backend": "host",
  "budget_exhausted": false,
  "byte_retention_ratio": 0.419408,
  "bytes_removed": 1059,
  "cache_hits": 8,
  "file_retention_ratio": 0.666667,
  "files_removed": 1,
  "holdout_status": "not_requested",
  "oracle_mode": "match",
  "output_bytes": 765,
  "output_files": 2,
  "payload_checked": true,
  "payload_fingerprint_mode": "exact",
  "payload_fingerprint_verified": true,
  "repomin_version": "0.1.0.dev9",
  "schema_version": 1,
  "source_bytes": 1824,
  "source_files": 3,
  "summary_schema_version": 2,
  "valid": true
}

The accompanying report.json records the exact payload fingerprint under the
tree-sha256-v2 policy:

{
  "tree_fingerprint_policy": "tree-sha256-v2",
  "tree_sha256": "05910a3ddba2610a0fd9752024fa34f3c2243e9fdbf77b63bd3ae61442bfe58b",
  "tree_content_fingerprint_policy": "tree-content-sha256-v1",
  "tree_content_sha256": "131932bc106bfb2f046ae19482de42eca5bcad930ab0ab67a05af85c99300cb0",
  "bytes": 765,
  "files": 2
}

So the validator's payload_checked: true,
payload_fingerprint_mode: "exact", and payload_fingerprint_verified: true
fields together are the expected exact fingerprint evidence.

Independent oracle rerun of the exported payload

( cd "$out_parent/result" && python3 reproduce.py )

stdout (suppressed), exit code, then stderr:

ORIGINAL_FAILURE
$ echo $?
1

The exported payload's oracle exits 1 and prints ORIGINAL_FAILURE on
stderr — the same marker the reducer matched during reduction, so the
required dependency + workspace contract holds without rerunning ReproMin.

Boundary statement

This fixture needs no Node runtime, no npm install, no registry access, no
lifecycle scripts, and no external network. It validates only the configured
Python oracle (reproduce.py) against the exported package.json; it is
adapter evidence for that oracle, not proof that an arbitrary minimized npm
application installs, builds, or behaves correctly.

[fly1d]

Thanks for the focused contribution. I ran the documented workflow from a clean review worktree: scripts/check_docs.py passed, the node-package benchmark passed, reduction produced the stated two-file payload, validation returned an exact verified fingerprint, and the independent oracle returned exit code 1 with ORIGINAL_FAILURE.

Please make two factual corrections before merge:

1. The engines block is not "removable in principle" in this workflow. The current Node adapter deliberately discovers entries only in its supported object/array categories; it does not target engines, and the observed payload retains that block unchanged. Please say that engines is outside the adapter categories and remains unchanged, or omit that sentence.

2. tree-sha256-v2 is stronger than a byte-only comparison: it also covers paths, entry kinds, permission modes, modification times, root metadata, and supported filesystem metadata. Please replace "matches ... byte-for-byte under the tree-sha256-v2 policy" with wording that says the exported tree content and recorded metadata match exactly. The transport-friendly content-only fallback is a separate mode.

Everything else is in scope and matches #20. One update addressing these two points should be enough; no broader rewrite is needed.

[shoaibyazdani]

Pushed commit 9c83f97 addressing both points:

1. engines sentence replaced with: "The engines block is outside the adapter categories and is preserved unchanged."
2. tree-sha256-v2 description replaced to mention tree content + recorded metadata matching exactly, with the transport-friendly content-only fallback called out as a separate mode.

Local re-verification against the updated docs/EXAMPLES.md:

• python3 scripts/check_docs.py → Documentation check passed (44 Markdown file(s)).
• python3 benchmarks/run_offline.py --only node-package → PASS node-package / offline benchmarks: 1 passed, 0 skipped, 0 failed

Note: the new push (9c83f97) shows the upstream CI workflow in action_required state on the GitHub side — gh pr checks 21 reports no checks reported and actions/runs/33632861736 is sitting at conclusion: action_required. Looks like a fork-PR workflow approval gate. A maintainer-side "Approve and run" on that run should let the 8-job matrix complete cleanly; no code or fixture touched, so the existing green matrix should reproduce.

[shoaibyazdani]

Hey @fly1d — pushed commit 9c83f97 on top of the previous one to address the two corrections from your earlier CHANGES_REQUESTED review:

1. engines — reworded to "outside the adapter categories and is preserved unchanged".
2. tree-sha256-v2 — reworded to "the exported tree content and recorded metadata match exactly under the tree-sha256-v2 policy. The transport-friendly content-only fallback is a separate mode."

Both edits are confined to docs/EXAMPLES.md — no other changes. Local re-runs of scripts/check_docs.py and benchmarks/run_offline.py --only node-package both pass.

⚠️ The CI re-run on commit 2 is sitting on the first-run-from-fork approval gate (action_required). Since this is a docs-only change on top of the previously green 8-job matrix (commit 1), the same run should reproduce the prior pass result once approved. Could you click "Approve and run" on that CI run when you have a moment?

Also, your CHANGES_REQUESTED review is on commit 1 — it would be great if you could re-review or dismiss-and-re-review on commit 2 when you get there. Happy to address any further notes.

Thanks!

[fly1d]

Verified the revised walkthrough against the current Node adapter and report semantics. The documented reduction, exact fingerprint validation, independent oracle rerun, and no-install trust boundary all reproduce as stated. Full CI is green. Thank you for tightening the factual wording and for the runnable contribution.