Per-kind ids: schema 3 and docket migrate

[NovusEdge]

Schema 3 gives claims, decisions and questions independent id counters (c1, d1, q1) and adds a one-run migration from schema 1 or 2.

What changes

• Ids and validation. Ids count per kind, allocated as that kind's highest number plus one. Every line carries schema: 3. Readers refuse an older ledger with an instruction to run docket migrate, and the session hook passes that instruction to the agent in place of a briefing (stdout, exit 0). docket check compares order per kind.

• docket migrate. Schema 1 and 2 both reach 3 in one run, in one file-order pass:

  • each record keeps its old id in a hidden migrated_from field;
  • relations, correction and review targets, and id mentions in record prose are rewritten, each mention once so shifted ids never chain, with schema-1 records resolving through legacy.source_id;
  • .docket/features.jsonl and its archive are remapped and move to features schema 2.

  Writes are crash-safe: features and named files are replaced first, the original ledger is hard-linked to ledger.jsonl.schemaN, and the ledger is swapped in one os.replace. A rerun finishes an interrupted run, and the migration refuses if the ledger changed underneath it. --dry-run lists every prose rewrite and every unresolved id token. --rewrite FILE... rewrites citations in tracked, clean files.

• Merges. Each branch migrates itself. The merge driver and docket rebase refuse mixed schemas, and the driver leaves conflict markers naming the side that is behind. A pre-migration BASE is upgraded in memory for matching only. Matching ignores migrated_from and id tokens in prose, so two branches migrated separately merge without duplicates.

• Finding old ids. docket list --where was:ID finds the record that carried an old id, retired records included. docket show OLD points at that search.

• Docs. A new docs/schemas.md page covers the schema versions and the upgrade procedure. docs/ledger.md, the skill and the changelog are updated.

Testing

• python3 -m unittest discover -s tests -p 'test_*.py': 1252 tests, OK, 9 skipped. Three of the skips are temporary guards for tests that read this repository's own ledger, which stays at schema 2 until it is migrated after this merges.
• ruff 0.16.7 format and check are clean.
• The renumber is linear: 0.41 s at 6,000 records and 0.94 s at 12,000.
• A whole-branch review traced this repository's real ledger through dry run, migrate, check, show, was: and context. It also merged two branches migrated separately through the driver, with no duplicates and a clean check.

After merge

1. Migrate this repository's ledger on main and commit ledger.jsonl and features.jsonl, not the backup.
2. Remove the three temporary test skips.
3. Run just release 0.26.0, then install 0.26.0.

Between the migration and the install, the installed 0.25.1 hook cannot read the ledger.

Summary by CodeRabbit

• New Features

  • Added migration to schema 3, with IDs numbered independently by record type and former IDs retained for lookup.
  • Added was:ID searches for records by their pre-migration IDs.
  • Migration can preview changes and rewrite citations in eligible tracked files.

• Bug Fixes

  • Merge and rebase now handle independently migrated branches while refusing incompatible schema versions.
  • Validation and command output provide migration guidance for outdated ledgers.

• Documentation

  • Updated migration, schema compatibility, backup, and branch coordination guidance.

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 9b38fe25-5ea4-4ab9-afb6-b0ac0ca8568b

📥 Commits

Reviewing files that changed from the base of the PR and between 07ad68f and 4bac39b.

📒 Files selected for processing (52)

• .docket/ledger.jsonl
• CHANGELOG.md
• README.md
• docket/cli/__init__.py
• docket/cli/admin.py
• docket/cli/context_cmd.py
• docket/cli/graph.py
• docket/cli/query.py
• docket/construct/accept.py
• docket/context.py
• docket/corrections.py
• docket/feature_archive.py
• docket/features.py
• docket/ledger.py
• docket/merge_driver.py
• docket/migrate.py
• docket/rebase.py
• docket/reviews.py
• docket/where.py
• docs/SUMMARY.md
• docs/commands.md
• docs/decision-chains.md
• docs/definitions.md
• docs/ledger.md
• docs/maintenance.md
• docs/north-star.md
• docs/schemas.md
• hooks/guard_ledger.py
• skills/docket/SKILL.md
• tests/golden/context_snapshots.json
• tests/golden/regenerate.py
• tests/test_check_order.py
• tests/test_correct_cli.py
• tests/test_corrections.py
• tests/test_docket.py
• tests/test_feature_cli.py
• tests/test_features.py
• tests/test_graph_cli.py
• tests/test_graph_export.py
• tests/test_guard_ledger.py
• tests/test_ledger.py
• tests/test_merge_driver.py
• tests/test_migrate_cli.py
• tests/test_migration.py
• tests/test_rebase.py
• tests/test_review_cli.py
• tests/test_reviews.py
• tests/test_supersede_reason.py
• tests/test_support.py
• tests/test_support_smoke.py
• tests/test_web.py
• tests/test_where.py

 ____________________________________________________________________________________________________________________________________________________________________________________________
< The object-oriented model makes it easy to build up programs by accretion. What this often means, in practice, is that it provides a structured way to write spaghetti code. - Paul Graham >
 --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
  \
   \   \
        \ /\
        ( )
      .( o ).

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}