feat: implement backfill command-family parity

[Ismail-elkorchi]

Acceptance Criteria

• All activated Invariants are satisfied by the updated parity gate, API contract text, and Node parity tests.
• Scope for this maintenance step is satisfied by backfill semantics, API exposure, and evidence-driven tests.

Checklist

• spec/state.yaml remains at the active phase value 18.
• node scripts/check exits with code 0 for node and deno and bun runtimes.
• Evidence artifacts are present under artifacts/gates and referenced below.

Simulated Role Reviews

Product review

Findings:

• Backfill now has a concrete API and deterministic behavior for requested object ordering and sparse-scoped hydration.
• The parity matrix claim for backfill now maps to executable evidence instead of a placeholder state.

Changes made:

• Added backfill object-model normalization in src/core/backfill/backfill.ts.
• Added Repo.backfill semantics and promisor normalization in src/index.ts and src/core/partial-clone/promisor.ts.
• Updated parity and API docs in docs/parity-matrix.md, spec/parity-roadmap.yaml, and docs/api.md.

Evidence pointers:

• tests/node/backfill.test.mjs contains option-status and sparse-scope parity assertions.
• scripts/parity_matrix_check now enforces backfill evidence requirements.
• artifacts/gates/INV-FEAT-0044.json and artifacts/gates/INV-SECU-0016.json are present.

QA review

Findings:

• Node parity suite passes with both new backfill tests green.
• Cross-runtime smoke checks pass for deno and bun.

Changes made:

• Added tests/node/backfill.test.mjs with CLI baseline comparisons and hydration-flow coverage.
• Kept existing runtime checks unchanged while extending command-family parity scope.

Evidence pointers:

• Command outputs: node scripts/check --runtime=node, node scripts/check --runtime=deno, node scripts/check --runtime=bun.
• Test file: tests/node/backfill.test.mjs.
• Parity gate: scripts/parity_matrix_check.

Security review

Findings:

• Backfill option validation rejects invalid minBatchSize values through INVALID_ARGUMENT.
• Promisor state normalization now rejects malformed object ids and malformed payload bytes.

Changes made:

• Added strict backfill option normalization in src/core/backfill/backfill.ts.
• Added OID normalization and payload validation paths in src/index.ts and src/core/partial-clone/promisor.ts.

Evidence pointers:

• tests/node/backfill.test.mjs invalid option assertion.
• tests/node/sparse-partial-clone.test.mjs integrity error coverage remains active.
• artifacts/gates/INV-SECU-0016.json is present.

Performance review

Findings:

• Backfill selection and output ordering are deterministic and bounded by current promisor set size.
• Sparse mode reduces fetch scope to indexed sparse-selected paths, limiting write operations.

Changes made:

• Implemented lexicographic OID ordering and sparse-scope filtering in src/index.ts.
• Added parity checks that validate min-batch-size skip behavior and completed status paths.

Evidence pointers:

• src/index.ts backfill selection and min-batch-size logic.
• tests/node/backfill.test.mjs sparse and threshold scenarios.
• Command output: node scripts/check --runtime=node.

Maintainer review

Findings:

• Command-family status and enforcement are now aligned across docs, roadmap, checks, and tests.
• Backfill semantics are documented in docs/api.md with machine-verifiable enforcement in parity checks.

Changes made:

• Updated docs/api.md with explicit backfill semantics.
• Updated docs/parity-matrix.md and spec/parity-roadmap.yaml to implemented state.
• Extended scripts/parity_matrix_check to require backfill API and evidence test coverage.

Evidence pointers:

• docs/api.md, docs/parity-matrix.md, spec/parity-roadmap.yaml.
• scripts/parity_matrix_check and tests/node/backfill.test.mjs.
• artifacts/gates/INV-FEAT-0052.json is present.