feat(PlutusSchema): annotation-driven Plutus Data encoding

[solidsnakedev]

Plutus Data encoding currently requires TSchema-specific combinators (TSchema.Struct, TSchema.Variant, etc.) that users must learn on top of Effect Schema. There is no way to derive encoding from standard Effect Schema types, and no compile-time enforcement that all AST node types are handled.

This adds PlutusSchema — an annotation-driven compiler that derives Plutus Data encoding from any Effect Schema. Users write Plutus.data(Schema.Struct({...})) and the compiler walks the AST using Effect's canonical Match<A> + getCompiler pattern (same as Pretty, Arbitrary) to produce bidirectional codecs. Custom annotations (ConstrIndexId, FlatInUnionId, etc.) control encoding where inference isn't enough. The compiler handles all 22 AST node types exhaustively, throws for unsupported types (Date, Duration, String, Number) instead of silently passing through, and produces CBOR output byte-for-byte identical to TSchema. TSchema continues to work unchanged — this is additive.

New modules: PlutusAnnotation (5 annotation symbols + module augmentation), PlutusCompiler (internal AST compiler), PlutusSchema (public API). 175 tests covering annotations, compiler handlers, real-world types (Address, Credential, Value, CIP68), edge cases, and benchmarks.

[Copilot]

Pull request overview

Adds an annotation-driven Plutus Data derivation layer on top of Effect Schema (PlutusSchema), backed by an internal AST compiler (PlutusCompiler) and a small annotation module (PlutusAnnotation), plus a large consolidated test suite validating byte-for-byte CBOR compatibility with existing TSchema.

Changes:

• Introduces PlutusAnnotation (symbol-based annotations + module augmentation) to control encoding details.
• Implements PlutusCompiler (SchemaAST.Match + getCompiler) to derive bidirectional toData / fromData codecs from Effect Schema AST.
• Adds PlutusSchema public API (data(), codec(), re-exports) and wires exports through the package barrel.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/evolution/src/PlutusAnnotation.ts	Defines Plutus-specific annotation symbols, getters/helpers, and SchemaAST module augmentation.
packages/evolution/src/PlutusCompiler.ts	Internal AST compiler producing Plutus Data codecs from annotated Effect Schema AST nodes.
packages/evolution/src/PlutusSchema.ts	Public API wrapping the compiler as a Schema<A, Data.Data> transform and re-exporting TSchema primitives.
packages/evolution/src/index.ts	Exposes PlutusAnnotation and PlutusSchema via barrel exports.
packages/evolution/test/PlutusData.test.ts	Consolidated test suite for annotations, compiler handlers, public API, real-world types, edge cases, and benchmarks.
.claude/research/*	Research/design logs documenting implementation rationale and cleanup loop progress.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

countStructFields() is used to determine how many parent Constr fields to slice when decoding flatFields, but it hard-codes tag stripping based on KNOWN_TAG_FIELDS only. This can miscount when the nested struct uses TagFieldId overrides (custom tag field name) or explicitly disables tag stripping (TagFieldId: false), causing misaligned slicing and incorrect decoding for flatFields structs.

Suggestion: make countStructFields use the same tag detection logic as the TypeLiteral handler (i.e., respect PA.getTagField(ast) and isLiteralTag(ps, tagFieldOverride)), or derive the count from the already-compiled nested struct codec metadata instead of re-implementing tag logic.

Suggested change

	const ps = typeLiteral.propertySignatures
	// Count non-tag fields (same logic as the TypeLiteral handler)
	let count = 0
	for (const p of ps) {
	const name = p.name as string
	if ((KNOWN_TAG_FIELDS as ReadonlyArray<string>).includes(name)) {
	// Check if it's actually a literal tag
	if (p.type._tag === "Literal") continue
	if (p.type._tag === "Transformation" && p.type.to._tag === "Literal") continue
	}
	const isLiteralTagField = (p: SchemaAST.PropertySignature): boolean =>
	p.type._tag === "Literal" ||
	(p.type._tag === "Transformation" && p.type.to._tag === "Literal")
	const tagFieldOverride = PA.getTagField(ast)
	const ps = typeLiteral.propertySignatures
	// Count non-tag fields using the same tag-field semantics as the TypeLiteral handler:
	// - explicit string override => only that field is considered the tag field
	// - explicit false => never strip a tag field
	// - otherwise fall back to well-known tag field names
	let count = 0
	for (const p of ps) {
	const name = p.name as string
	if (tagFieldOverride === false) {
	count++
	continue
	}
	if (typeof tagFieldOverride === "string") {
	if (name === tagFieldOverride && isLiteralTagField(p)) continue
	count++
	continue
	}
	if ((KNOWN_TAG_FIELDS as ReadonlyArray<string>).includes(name) && isLiteralTagField(p)) {
	continue
	}

[Copilot]

Union encoding currently doesn’t actually select the correct member: if no tag field is detected it always picks member 0, and even when a tag field is detected it falls back to member 0 when the tag value isn’t in tagMap. This makes unions like Schema.Union(Schema.BigIntFromSelf, Schema.Boolean) encode true using the first member’s codec, producing invalid/incorrect Plutus Data without an error.

Suggestion: implement real member selection (e.g., similar to TSchema.Union using Schema.is / ParseResult.is against each member AST), and throw a descriptive error when no member matches or when a detected tag value is unknown.

[Copilot]

Union decoding assumes constr.index is a positional index for non-flat members (memberCodecs[idx]), but encoding allows arbitrary ConstrIndexId on any member (memberIndex = getConstrIndex(t) ?? i). If a non-flat member has a custom index, encoding will emit Constr(customIndex, [encoded]) but decoding will either pick the wrong member or throw because idx is out of range.

Suggestion: decode by looking up the member by its declared member.index (for both flat and non-flat), rather than indexing into memberCodecs by position. Alternatively, constrain ConstrIndexId usage to flat members only and enforce/throw if a non-flat member has a custom index.

Suggested change

	// Find matching member by index
	const flatMember = memberCodecs.find((m) => m.isFlat && m.index === idx)
	if (flatMember) {
	return flatMember.codec.fromData(d) // Flat: decode directly from Constr
	}
	// Non-flat: member at position idx, unwrap one level
	const member = memberCodecs[idx]
	if (!member) {
	throw new Error(`PlutusCompiler: invalid union index ${idx}, expected 0..${memberCodecs.length - 1}`)
	}
	// Find matching member by its declared constructor index
	const member = memberCodecs.find((m) => m.index === idx)
	if (!member) {
	throw new Error(`PlutusCompiler: invalid union index ${idx}`)
	}
	if (member.isFlat) {
	return member.codec.fromData(d) // Flat: decode directly from Constr
	}
	// Non-flat: unwrap the single encoded payload field

[Copilot]

booleanCodec.fromData treats any Constr index other than 1n as false and doesn’t validate the Constr shape (index must be 0/1 and fields must be empty). This diverges from TSchema.Boolean which throws on invalid indices/fields, and can cause malformed data (e.g., Constr(3, [])) to silently decode as false.

Suggestion: add the same validation as TSchema.Boolean (reject indices other than 0/1 and non-empty fields) so invalid Plutus data doesn’t silently coerce to a boolean.

Suggested change

	fromData: (d: Data.Data) => (d as Data.Constr).index === 1n
	fromData: (d: Data.Data) => {
	if (!(d instanceof Data.Constr)) {
	throw new Error("Invalid boolean data: expected Constr")
	}
	if (d.fields.length !== 0) {
	throw new Error("Invalid boolean data: expected empty Constr fields")
	}
	if (d.index !== 0n && d.index !== 1n) {
	throw new Error(`Invalid boolean data: expected Constr index 0 or 1, got ${String(d.index)}`)
	}
	return d.index === 1n
	}