promote: 0.25.0 to prod (oddkit_resolve action — link-rot Phase 2)

[klappy]

Promotes oddkit_resolve (PR #140) to production.

What ships

• New MCP action oddkit_resolve — protocol-level URI resolution with transparent supersession traversal. URI in, current canonical answer out. Walks superseded_by chains in existing frontmatter to terminus, normalizing across the three shapes used in canon authoring (full klappy:// URI, repo-relative path with .md, repo-relative path without).
• Status enum: FOUND | NOT_FOUND | INVALID_INPUT | CIRCULAR_SUPERSESSION
• Wired into the unified oddkit router (action: "resolve") and exposed as a standalone oddkit_resolve tool
• Backward-compatible — purely additive net-new action; existing callers unchanged
• Reads only the existing index (fetcher.getIndex); no new caches, no new frontmatter fields
• Three smoke tests added to tests/cloudflare-production.test.sh (direct hit, supersession walk against real canon data, NOT_FOUND, INVALID_INPUT)

Version

0.24.0 → 0.25.0

Campaign context

Phase 2 of the link-rot-elimination campaign per klappy://docs/planning/link-rot-elimination-campaign. Realizes the architectural answer named in klappy://canon/principles/identity-resolved-by-protocol (Phase 1, klappy/klappy.dev #142, merged): identity references are resolved by the protocol, never authored as locations. Vodka discipline applied — every other piece in the v3 spec (batch action, resolve_links flag, aliases field, identity-by-meaning queries) was deferred per klappy://docs/planning/link-rot-deferred-concerns.

Validation receipts

PR #140 cleared every gate the canon requires for load-bearing surface promotion per klappy://canon/constraints/release-validation-gate (E0008.3):

• ✅ Workers Builds — success
• ✅ Test CF Preview (smoke tests including new supersession-walk regression test) — success
• ✅ Version Sync — success
• ✅ Creed Freshness — success
• ✅ Cursor Bugbot — success (caught three real bugs on the initial commit: VALID_ACTIONS array missing resolve, field-name inconsistency on supersession_chain, state-threading parity — all fixed)
• ✅ Independent Sonnet 4.6 validator dispatched per E0008.3 — PASS (caught a fourth real bug: superseded_by lookup originally only handled URI form, broke for the path forms canon authors actually use; fix verified against the same canon entry that surfaced the bug)

The release-validation-gate constraint earned its keep on the very first PR it gated. Validator caught a production-blocking bug that CI could not catch because CI's smoke tests didn't exercise mixed-shape supersession against real canon data.

Post-promotion verification (recommended)

After CF auto-deploy completes (1–3 min), verify against https://oddkit.klappy.dev/mcp:

1. oddkit_version returns 0.25.0
2. The unified router accepts action: "resolve" (12 enum values, not 11)
3. oddkit_resolve with klappy://docs/oddkit/proactive/dolche-vocabulary returns status: FOUND, resolved.uri: klappy://canon/definitions/dolcheo-vocabulary, supersession_chain populated with one entry, no warning field

Refs

• PR feat(resolve): add oddkit_resolve MCP action with transparent supersession #140 (the implementation PR being promoted)
• klappy/klappy.dev promote: 0.25.0 to prod (oddkit_resolve action — link-rot Phase 2) #142 (Phase 1 canon — merged)
• Spec: klappy://docs/oddkit/specs/oddkit-resolve (DRAFT v4)
• Principle: klappy://canon/principles/identity-resolved-by-protocol
• Campaign: klappy://docs/planning/link-rot-elimination-campaign
• Deferred concerns: klappy://docs/planning/link-rot-deferred-concerns

---

Note

Medium Risk
Adds a new MCP tool/action that changes request routing and response shapes for a new surface area; risk is mainly around resolver edge cases (cycles/dangling successors) and relying on index/frontmatter correctness, but existing actions are unchanged.

Overview
Adds a new oddkit_resolve MCP tool and unified-router action:"resolve" that takes a klappy:// URI, looks it up in the index, and returns a canonical resolved document (plus supersession_chain) after walking any superseded_by chain with cycle and depth safeguards.

The resolver normalizes superseded_by references across URI and repo-path forms (with/without .md) and surfaces explicit statuses (FOUND, NOT_FOUND, INVALID_INPUT, CIRCULAR_SUPERSESSION) plus a truncation warning for dangling successors.

Updates production smoke tests to cover direct resolve, mixed-shape supersession traversal, and error statuses, and bumps package versions/CHANGELOG to 0.25.0.

^{Reviewed by Cursor Bugbot for commit 3d20ff3. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	oddkit	3d20ff3	Commit Preview URL Branch Preview URL	Apr 26 2026, 03:50 PM