feat(candid): add Zod-inspired Candid codec API (Slice 1)

[b3hr4d]

Summary

Add the foundational Candid codec layer to @ic-reactor/candid — Slice 1 of the Candid Codec plan.

This introduces a Zod-inspired c namespace for building typed, metadata-rich Candid contracts in TypeScript:

import { c } from "@ic-reactor/candid"

const Account = c.record({
  owner: c.principal(),
  subaccount: c.opt(c.blob()),
})
type Account = c.infer<typeof Account>

const Ledger = c.service({
  icrc1_balance_of: c.query([Account], c.nat()),
  icrc1_transfer: c.update([TransferArg], TransferResult),
})

const idlFactory = Ledger.idlFactory
type _SERVICE = c.ServiceOf<typeof Ledger>

What's Included

New: packages/candid/src/codec/

File	Purpose
types.ts	CandidMetadata, manifest types
codec.ts	Abstract CandidCodec<T> base with immutable metadata chaining
primitives.ts	19 primitive factories (text, bool, nat, principal, etc.)
composites.ts	opt, vec, record, variant, tuple with full type inference
service.ts	query, update, oneway, service codecs with idlFactory & manifest()
index.ts	The c namespace (const + namespace merge for c.infer<T>)

Modified

• src/index.ts — added export * from "./codec"
• tests/unit/index.test.ts — added new exports to the allowlist

Key Design Decisions

• Immutable metadata: .describe(), .label(), .example(), .meta() return new instances
• Lazy IDL: toIDL() called at consumption time (enables future c.recursive())
• Namespace merge: c is both a const object and a TS namespace for c.infer<T> / c.ServiceOf<T>
• Zero breaking changes: purely additive, no existing code modified

Tests

63 new tests covering:

• Primitive IDL equivalence
• Metadata immutability
• Composite codec construction
• Service idlFactory equivalence with hand-written factories
• manifest() structured output
• IDL encode/decode roundtrips
• Compile-time type inference checks
• Edge cases

Verification

• ✅ vitest run tests/unit/codec.test.ts — 63/63 pass
• ✅ vitest run tests/unit/index.test.ts — 11/11 pass
• ✅ tsc --noEmit — clean type check

Next Steps

This is Slice 1 of 5 per the Candid Codec plan:

1. Codec primitives & service layer ✅ (this PR)
2. Codegen renderer
3. Parser schema (parseDid())
4. Comment metadata parsing
5. Replace v4 generated output