[akhileshthite]

Closes #114

Adds three exports to @chelonia/lib/functions, next to parseCID, for when parsing every ID costs too much, like validating route parameters:

• CHELONIA_CID_REGEX: the shape of every CID parseCID accepts (CIDv1, base58btc, blake2b-256, a codec from multicodes)
• CONTRACT_ID_REGEX: Chelonia contract IDs only
• CID_REGEX: any CID that CID.parse decodes on its own (CIDv0, or CIDv1 in base32 or base58btc)

A match only means the string has the right shape. For a definite answer, maybeParseCID is still the one to use.

The prefixes were checked against the lowest and highest CID each codec can have, so they hold for every CID, not just the ones tested. A test builds CIDs for every codec in multicodes, so adding a codec without updating the regex fails it.

Testing: lint passes, and all 476 tests pass (4 new).

AI Usage: Claude Opus 5.5 Max
Self review: Approved

[akhileshthite]

/review

---

AI review started.

[github-actions]

Advanced AI Review

• Type: Agentic (crush)
• Model: glm-5.3

Click to expand review

Code Review

Base: origin/main (9c3afd2)
Head: bdfbbc9 — feat: export quick regex checks for Chelonia CIDs and contract IDs
Date: 2026-10-20
Model: glm-5.3

---

Summary

Adds CHELONIA_CID_REGEX, CONTRACT_ID_REGEX, and CID_REGEX to src/functions.ts as fast shape checks for Chelonia CIDs and contract IDs, plus a new src/functions.test.ts covering them.

Verification performed (beyond reading the diff): ran the new tests and the full suite (476/476 pass), ran ESLint on both files (clean), and independently probed the regexes against the installed @chelonia/multiformats:

• All seven multicodes prefixes and exact lengths (52/53/56) confirmed against min-digest, max-digest, and ~35k random CIDs — zero misses. The extremes-based test design is sound: base58 encoding is monotonic for a fixed digit count, so if both digest extremes share the prefix, every digest does.
• CID.parse in this build decodes exactly the Qm…/b…/z… forms the CID_REGEX comment claims (uppercase base32, padded c…, hex, base36 all throw), so the doc comment is accurate.
• The Qm + 44, ba[e-h], and z-first-char-never-1 claims all hold mathematically and empirically.
• No ReDoS: all three patterns are alternations of single, non-nested repeats (linear time); the 1M-char test confirms. Anchors are newline-safe in JS ($ does not match before a trailing \n — verified).

The implementation is correct and well tested. Only two minor issues below.

1. ⚪ Duplicated SHELTER_CONTRACT_DATA prefix across the two Chelonia regexes

• Addressed
• Dismissed

src/functions.ts:47-52 encodes the same fact — the base58 prefix of the SHELTER_CONTRACT_DATA codec — twice: as DXeQ2AgfCu inside CHELONIA_CID_REGEX's alternation and as zLDXeQ2AgfCu in CONTRACT_ID_REGEX. If the codec value ever changes, both literals must be updated in sync. The new test would catch a missed update, but sharing the constant makes the coupling explicit instead of test-enforced:

const CONTRACT_ID_PREFIX = 'zLDXeQ2AgfCu'

export const CHELONIA_CID_REGEX = new RegExp(
  `^z(?:9brRu3V|yop8PQyp|L(?:7mM9d4Xb4T|AeVmpcc88g|${CONTRACT_ID_PREFIX.slice(1)}|GQo2DimCH8|KHweRGqjMM))${BASE58}{44}$`
)

export const CONTRACT_ID_REGEX = new RegExp(`^${CONTRACT_ID_PREFIX}${BASE58}{44}$`)

2. ⚪ "What parseCID accepts" comment is slightly overbroad

• Addressed
• Dismissed

The comment above CHELONIA_CID_REGEX (src/functions.ts:44-46) says the regex matches "What parseCID accepts", but parseCID never checks the digest size, so it also accepts blake2b-256 CIDs with nonstandard digests (verified: a 33-byte digest, string length 58, passes parseCID's 52–64 window) that the regex deliberately rejects by pinning the length to exactly 44 trailing base58 chars. The regex being stricter is the right call for a shape check — arguably parseCID is the lax one, a pre-existing quirk outside this PR — but the comment could note the regex additionally assumes the spec-compliant 32-byte digest, so future readers don't treat the two as equivalent. One-line fix:

// What `parseCID` accepts: CIDv1, base58btc, blake2b-256 and a codec from
// `multicodes`. Each codec gives a fixed prefix and length, so the prefixes
// have to change when `multicodes` does. A test checks every codec. (Unlike
// `parseCID`, this also pins the digest to its spec size of 32 bytes.)

---

Review generated using glm-5.3 via Z.AI. Comment /review to re-run.

[taoeffect]

LGTM!