# Checkpoints

Scope note: this repository is the SDK. Migration-plan Phases 6–11 (BitVid
shadow mode, cutovers, and duplicate removal) modify the consumer repositories
and are tracked there, not here.

## Checkpoint 0 — Repo skeleton (completed)

Delivered: npm workspaces monorepo, Node 22 + ESM, Vitest, JSDoc typecheck,
GitHub Actions CI, reference import guard, provenance docs.

Later additions: GPL-3.0-or-later `LICENSE`, `CHANGELOG.md`, architecture
decision records under `docs/adr/`, and a working per-package type build. The
`types` fields previously pointed at paths the build never produced, so
consumers received no declarations; declarations now emit into each package.

## Checkpoint 1 — Characterization corpus (completed)

Delivered:
- 34 fixtures under `fixtures/bitvid/cases/`, generated by
  `scripts/build-characterization-corpus.mjs`
- conformance harness (`packages/testing/src/conformance.js`) that builds a
  snapshot, evaluates it, and diffs against a partial expectation
- conformance suite (`tests/conformance/bitvid-fixtures.test.js`) asserting
  every required behavior, determinism, and input immutability

Characterized values, read from the pinned reference commit and cross-checked
against the migration plan's baseline section:

```text
Trusted report blur threshold:       3
Trusted report autoplay threshold:   3
Trusted mute hide threshold:        20
Trusted spam-report hide threshold:  5
Trusted mute validity window:       60 days
```

These live in `@nostr-governance/bitvid-compat` as one application's profile,
not as engine defaults.

Provenance: fixtures are authored from the reference source and its documented
configuration, not captured from a live relay. They pin the behavior the
extraction must reproduce; they are not a recording of production traffic.

## Checkpoint 2 — Pure core (completed)

Delivered: identifiers, targets, authority, administrative-state reduction,
reasons, evidence, policy engine, fingerprints, evaluator, adapter contract.

Acceptance:
- identical snapshots produce identical decisions (asserted per fixture)
- evaluation performs no I/O and reads an injected clock
- evaluation mutates no input (asserted per fixture)
- the core imports no browser globals and has no dependencies
- the core contains no application-specific terms or thresholds

## Checkpoint 3 — Nostr codecs (completed)

Delivered: bech32/NIP-19 (verified against the NIP-19 test vector), canonical v1
on `kind:30078`, NIP-56 reports, NIP-51 mute lists, legacy administrative lists
covering all five migration stages, replaceable selection with a deterministic
same-timestamp tiebreak, injected signature verification.

## Checkpoint 4 — Runtime stores (completed)

Delivered: `GovernanceAdminStore`, `TrustGraphStore`, `ReportStore`,
`TrustedMuteStore`, `PolicyStore`, `OverrideStore`, `GovernanceRuntime`.

Acceptance: injected transport, storage, and clock; change-only emission; viewer
switching clears viewer-scoped state while keeping operator seeds; subscriptions
close on destroy; report subscriptions are chunked (200 per filter) rather than
opened per target; author evidence is queryable in batches; expired mute lists
prune against the injected clock.

## Checkpoint 5 — Public commands (completed)

Delivered: contribution, role, policy, community-source, report, and override
commands with stable error codes.

Acceptance: every command checks capability locally before the signer is
invoked, so an unauthorized actor cannot produce a signed mutation; revoked
actors' contributions stop affecting effective state; protected actors are
refused at the command boundary; first relay acceptance completes the command
while remaining relay results stay observable.

## Checkpoint 6 — Reusability proof (completed)

Delivered: `examples/commerce`, a marketplace built entirely on the public API,
covering the ten proof-of-fit behaviors the migration plan requires — including
that no core change was needed. Plus `README.md`, `docs/integration-guide.md`,
and `examples/commerce/README.md`.

## Status

CI gates green: reference guard, typecheck, 556 tests, per-package type build.

## Not done here

Migration-plan Phases 6–11 operate on BitVid and BitRoad:

- Phase 6 — BitVid compatibility facade and shadow mode
- Phase 7 — cut over BitVid administrative state
- Phase 8 — cut over BitVid reports and trust
- Phase 9 — cut over BitVid policy
- Phase 10 — validate through BitRoad itself
- Phase 11 — remove duplicated BitVid logic

The commerce example stands in for Phase 10's API-shape validation without
touching the BitRoad repository.