Skip to content

feat(iid): add canonical IID parsing and derivation - #18

Merged
kamescg merged 1 commit into
update/v1.1.0-alphafrom
feat/iid
Aug 10, 2026
Merged

feat(iid): add canonical IID parsing and derivation#18
kamescg merged 1 commit into
update/v1.1.0-alphafrom
feat/iid

Conversation

@kamescg

@kamescg kamescg commented Aug 10, 2026

Copy link
Copy Markdown
Contributor

Summary

P02 of the iid-v1.1.0-alpha release train. Adds @0xintuition/iid — the pure, offline IID reference implementation: parsing, typed validation, all 26 scheme canonicalizers, NORM-1, gen1 derivation, and the new declarative identity-ladder engine.

Ported from the authoritative private reference (0xIntuition/intuition-v2 @ 8b9e9aa11), with two deliberate design changes over the private code:

  1. Declarative ladders replace executable callbacks. The public ladder contract is the serializable source/recipe union the public classifications package already declares (field, same-as, url-origin, geohash, podcast-guid, named derivations acct-strong/acct-weak/appid-bundle/rss-item/termset-term/caip10-eoa/caip10-contract/caip19-erc20; recipe fields field/year/text-hash/geohash). The engine interprets them as a pure function; no engine for these existed anywhere before this PR. Field keys per derivation are documented on the engine and frozen. same-as selection is order-independent (lexicographically smallest canonical wins).
  2. The parser matches the spec grammar. Value character class is now %x21-7E — space/non-ASCII values reject as malformed. The private parser's catch-all was recorded in iid-spec's implementation-notes; the two normative parse vectors it failed now pass.

Also adds the typed result API the plan calls for: inspectIntuitionId distinguishes malformed / unknown-scheme / noncanonical (with canonical repair for read paths — resolvable historical spellings are never valid new anchors) and reports anchor-ineligibility reasons (class-c vs polymorphic-scheme).

Package impact

Package Change
@0xintuition/iid new, 0.1.0-alpha.0
all existing packages none

Target versions

@0xintuition/iid@0.1.0-alpha.0. Peer: viem ^2.0.0. Dev: exact @0xintuition/iid-spec@0.1.0-alpha.0 (conformance corpus input).

Identity impact

Identity impact: none — no existing golden bytes change. All spec-stated golden values reproduce exactly (ISBN-10→13 upconversion, gen1 movie r4 fb681afe…, golden ISRC).

Fixture impact

none added; the full 145-vector corpus from @0xintuition/iid-spec executes in this package's tests (212 tests, Node via vitest; the clean-room smoke covers Bun).

Contract artifact

n/a

Rollout notes

  • Gate results: all conformance vectors pass; parsing preserves everything after the second colon (colon-bearing CAIP-10/gen1 vectors); packed tarball exposes only . and ./package.json entrypoints with compiled output; 12-package clean-room smoke passes on Node+Bun.
  • P03 next: classifications drops its duplicated scheme-class/typing tables and ladder types in favor of imports from this package (temporary re-exports for compatibility).

🤖 Generated with Claude Code

- Port the reference implementation from the private source
  (0xIntuition/intuition-v2 @ 8b9e9aa11): all 26 scheme canonicalizers,
  NORM-1, gen1 preimage/hash, geohash, UUIDv5/podcast-guid, keccak16.
- Fix the parser value character class to the spec grammar (%x21-7E):
  space and non-ASCII values now reject as malformed, matching the
  normative parse vectors (recorded in iid-spec implementation-notes).
- Redesign the identity-ladder contract around the public declarative
  source/recipe types (field, same-as, url-origin, geohash,
  podcast-guid, and the frozen named derivations) and implement the
  pure declarative derivation engine that interprets them; ladders are
  serializable data, never callbacks.
- Add the typed inspection API (inspectIntuitionId) distinguishing
  malformed / unknown-scheme / noncanonical, with canonical repair for
  read paths, plus anchor-eligibility reasons (class-c vs polymorphic).
- Execute the full 145-vector conformance corpus from
  @0xintuition/iid-spec in the test suite (212 tests) alongside ported
  and new engine tests.
- Register iid second in the central package registry.

Identity impact: none — no existing golden bytes change; all
spec-stated golden values (ISBN upconversion, gen1 movie r4)
reproduce exactly.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@kamescg
kamescg merged commit 501b770 into update/v1.1.0-alpha Aug 10, 2026
1 check passed
@kamescg kamescg mentioned this pull request Aug 10, 2026
13 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant