feat!: infer TypeScript types from pattern guards

[turadg]

closes: #2392
supports: Agoric/agoric-sdk#6160

Summary

Add comprehensive TypeScript type inference from pattern guards (M.* matchers) to exo methods and interfaces. When makeExo, defineExoClass, and defineExoClassKit are called with typed InterfaceGuard values, method signatures are now inferred from the guard at compile time.

Changes

Core Features

• TypeFromPattern<P> — infer static types from any pattern matcher (string, bigint, remotable, arrays, records, etc.)
• TypeFromMethodGuard<G> — infer function signatures from M.call() or M.callWhen() guards
• TypeFromInterfaceGuard<G> — infer method records from interface guard definitions
• M.remotable<typeof Guard>() — facet-isolated return types with guard polymorphism
• Per-facet ThisType in defineExoClassKit — this.facets and this.state properly typed

Breaking Changes

• defineExoClassKit now requires facet method types to match their guard signatures (compile-time check)
• makeExo and defineExoClass enforce method signatures against guard at compile time
• Single-facet exos have this.self (not this.facets); multi-facet kits have this.facets (not this.self)

Type System Architecture

• New types-index.d.ts / types-index.js convention for re-exporting values with enhanced type signatures
• .ts files (e.g. type-from-pattern.ts) contain type definitions only; no runtime code
• JSDoc @import for type-only imports in .js files

Documentation

• AGENTS.md — TypeScript conventions for monorepo contributors
• Enhanced JSDoc in src/types.d.ts explaining ClassContext vs KitContext
• Comprehensive type test suite in types.test-d.ts covering all inference cases

Tests

• Full runtime test coverage for kit facet isolation and this context
• Type-level tests (tsd) for guard-driven method inference
• Tests for M.callWhen, M.await, M.promise, and async method returns

[changeset-bot]

⚠️ No Changeset found

Latest commit: f1eebed

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[erights]

No change suggested.

Just noting that I'm glad to be reminded of this, since we're in progress with changing what a passable symbol is.

[erights]

This is awesome as it expresses what anyone using M.remotable expects to express but still keeps a clear and locally visible separation of what types are enforced/sound and which are not.

[erights]

Curious: When using the type parameter, do you expect to also include the string parameter? I ask because I made the mistake of giving remotable an unenforced string parameter but not M.promise. Your type parameterization of these looks similar, which is great. But I wonder whether we should better align them by deprecating the remotable string parameter, or by adding a promise string parameter.

In my tentative opinion, I think both should have a string parameter, as it is useful in runtime diagnostics.

[turadg]

Agreed, both should have a label string param for runtime diagnostics.

We could add label?: string to M.promise<T>(label?: string) signature to match M.remotable<T>(label?: string). Do you want that in this PR?

[erights]

What are "facet-isolated return types" ?

[turadg]

In a defineExoClassKit, when facet A's method should return facet B's object, you want the TS return type to be the full B-facet interface, not just bare RemotableObject. By writing M.remotable<typeof PublicI>() in the guard, TypeFromPattern (via TFRemotable) walks the InterfaceGuard and resolves a methods-record type. That's what "facet-isolated" means — each facet's return type is independently typed to its own interface shape.

[erights]

For all of these, does

Suggested change

	lt: (rightOperand: Key) => MatcherOf<'lt'>;
	lt: (rightOperand: Key) => MatcherOf<'lt', Key>;

make sense? If so, what about

Suggested change

	lt: (rightOperand: Key) => MatcherOf<'lt'>;
	lt: <K extends Key = Key>(rightOperand: K) => MatcherOf<'lt', K>;

?

[turadg]

The first suggestion MatcherOf<'lt', Key> (explicit Payload = Key) is accurate and we can adopt it for clarity.

The second <K extends Key = Key> would be incorrect semantics. The comparison matchers don't narrow the matched value to the operand's type — M.lt(5n) matches any Key that is less than 5n, which could include strings in the compareKeys ordering,

I'll update lt/lte/eq/neq/gte/gt to MatcherOf<'lt', Key>.

[erights]

No change suggested.

Just checking my understanding: The reason you did not try to parameterize the Pattern is because it would need to be overloaded, and an overloaded type parameter would not be very useful. Yes?

[erights]

The rest is part of the payload. Should it be included in the tuple?

Likewise below.

[turadg]

Good catch!
I'll:

• Add optional 3rd element: MatcherOf<'splitArray', [Req, Opt, Rest?]> (or use MatcherOf<'splitArray', [Req, Opt] | [Req, Opt, Rest]>)
• Update TFSplitArray to accept and spread the rest type
• Same for splitRecord with rest

[erights]

Curious why you did not give Req a default? Likewise below.

[turadg]

Oversight. I'll add Req extends Pattern[] = Pattern[] default to avoid callers needing to specify it explicitly.

[erights]

I don't understand the MatcherOf<'kind', 'undefined'>

[turadg]

opt(P) desugars to M.or(P, M.undefined()). M.undefined() returns MatcherOf<'kind', 'undefined'>. In TFKindMap, key 'undefined' maps to the JS type undefined. So TypeFromPattern for the whole or produces TypeFromPattern<P> | undefined. The MatcherOf<'kind', 'undefined'> is just M.undefined() written in its fully-expanded internal form.

What code comment would help to include? Note that the above was generated by Claude so that's one option for answering the question in the future.

[erights]

Should the return type somehow appear? Likewise for callWhen.

[turadg]

The return guard is captured when .returns(RG) is called — MethodGuardMaker<CK, A>.returns<RG>(...) → MethodGuard<CK, A, OptArgs, RG>. At M.call(...) time we only have the arg guards; there is no return guard yet. Fully-typed inference happens only once .returns() is finalized.

[erights]

Are we there yet?

[turadg]

Not TMK. This PR is purely additive TS types.

[erights]

What is special about the zeroth element of a CopyArray?

[erights]

What about empty CopyArrays?

[turadg]

What is special about the zeroth element of a CopyArray?

This is to handle tuples. The P extends readonly [infer H, ...infer T] branch in TypeFromPattern handles TypeScript tuple literal types, not CopyArray runtime values. When a caller writes [M.string(), M.nat()] (a literal tuple as a pattern), TS infers the type as a tuple [MatcherOf<'string'>, MatcherOf<'nat'>], and this branch maps it element-by-element to [string, bigint]. It's not about CopyArray the data structure — actual M.arrayOf(...) patterns come in as CopyTagged and are handled by the match:arrayOf branch.

What about empty CopyArrays?

An empty tuple [] doesn't match [infer H, ...infer T] (needs at least one element), so it falls through to the identity P branch, returning []. That's correct — an empty pattern tuple matches nothing extra.

[erights]

Please keep static concepts distinct from dynamic runtime concepts

Suggested change

	* These matchers return their Payload directly or a fixed type, with no
	* These matcher types return their Payload type directly or a fixed type, with no

[erights]

Am I confused or should this be "can only widen to Key" ?

[turadg]

Good catch! I'll revise to,

Suggested change

	// Comparison matchers — can only narrow to Key
	// Comparison matchers — can only infer as broad as Key (operand type is not preserved)

[erights]

No change suggested.

Just noting that we expect to change the type of byteArray to Uint8Array (or possibly readonly Uint8Array ?).

[erights]

I remember when we had both a Remotable type and a Remotable runtime value. The collision kept causing annoyance so we renamed the type to RemotableObject. I thought that since then we try to avoid such collisions. Why is having an M type ok?

[erights]

I also see that we're using M as a type parameter in many places. The collision of these with the runtime M seems unproblematic.

What about the collision of M type parameters with this exported namespace type M ?

[turadg]

I remember when we had both a Remotable type and a Remotable runtime value. The collision kept causing annoyance so we renamed the type to RemotableObject

IIRC, the problem there was they were different shapes. Here, M is the namespace for both.

Why is having an M type ok?

TypeScript allows value + namespace declaration merging: export declare const M: MatcherNamespace (value) and export namespace M { type infer<P> = ... } (namespace) co-exist cleanly. The namespace adds only type-level members (type infer<P>), not runtime-accessible properties. This is different from the Remotable/RemotableObject case where both a class (type + value) and another runtime value shared the same name, causing confusion about which was meant at runtime.

What about the collision of M type parameters with this exported namespace type M ?

TypeScript resolves identifiers by scope. An M extends InterfaceGuard type parameter shadows the namespace M within that generic's scope. Since the namespace M is only used at the type level and only for M.infer<...>, and type parameters named M appear in different scopes (each generic function), there is no runtime collision and the TS compiler correctly distinguishes them.

Worth noting in a comment?

[erights]

This is declaring the type of the runtime matches function, right? This is a really cool payoff (likewise with mustMatch below).

I am surprised you can separate a function's type declaration from the function's declaration in this way. But even if we can, is it a good idea?

[turadg]

This is declaring the type of the runtime matches function, right?

Right.

is it a good idea?

Good question. Claude says: it's the standard pattern for augmenting JS runtime exports with richer TS types than JSDoc can express. The declare function in a .ts / .d.ts file overlays the type seen by consumers without emitting duplicate code. The runtime implementation stays in patternMatchers.js. Many major libraries (Zod, Effect) use this approach. "The key invariant to maintain: the declared signature must be a subtype of the runtime behavior."

And while that invariant would be easier to maintain as a single .ts file, it's a big lift right now because patternMatcher.js has ts-nocheck. I think this is the right approach for the scope of this PR and a separate PR could refactor the .js/.ts and build steps to make that work.

Meanwhile there is one improvement I'll make:

// In types-index.ts — verify runtime impl is assignable to base signature
import { matches as _m } from './patternMatchers.js';
// Widened (non-predicate) base check — if sig drifts this line will error
const _matchesCompat: (specimen: unknown, patt: Pattern) => boolean = _m;

This is a lightweight guard that catches any future signature divergence at the types-index boundary, since types-index.js is not @ts-nocheck-ed. The declare function overlay in type-from-pattern.ts is then a safe, intentional narrowing (adding the type predicate) on top of a verified base.

[erights]

This sentence leaves me puzzle about whether the return type in inferred from the concrete method or whether it is inferred by from the guard and enforced on the concrete method. (I hope the latter)

[erights]

This seems to me to be a fundamental limitation, not a TS limitation. How could a hypothetical better type system surmount this limitation?

[turadg]

You're absolutely right. With Claude's help to see why: when defaultGuards: 'passable', the guard accepts any method, so InterfaceGuard<any> is the correct representation.

I'll reword: "Expected behavior: when the guard uses defaultGuards: 'passable', TypeFromInterfaceGuard produces a broad index-signature, and guard-driven enforcement is intentionally disabled."

[erights]

It could be tightened only if your types are cognizant of defaultGuards. If defaultGuards: 'passable', then you must allow "extra" methods.

[turadg]

True. I'll add a TODO to make the strict overload (MakeInterfaceGuardStrict) infer a type that rejects extra methods, while the sloppy overload (MakeInterfaceGuardSloppy) allows them.

[erights]

Does makeExo(tag, undefined, methods) have the same type as

makeExo(
  tag,
  M.interface(something, undefined, { defaultGuards: 'passable' },
  methods);

?
I ask because this is the runtime meaning of omitting the interfaceGuard argument from makeExo. Likewise for all similar overloads below.

[turadg]

They're semantically equivalent at runtime, but the typed overload with defaultGuards: 'passable' allows weaker static checking. A follow-up could collapse these into one via better overload.

[erights]

Since this is still Draft, I'll stop here for now.

I look forward to using this!

Will we manage the breakage of agoric-sdk by doing a major version bump on @endo/patterns and @endo/exo? There are no runtime changes so I hope not. But I don't see how to make it work otherwise.

[turadg]

Since this is still Draft, I'll stop here for now.

Cool. I'll fixup, repush and prepare for a full review.

Will we manage the breakage of agoric-sdk by doing a major version bump on @endo/patterns and @endo/exo? There are no runtime changes so I hope not.

It's been our policy not to include static type checks in semver. Claude affirms this:

• The breaking changes are compile-time only (TS type errors, no JS runtime changes). agoric-sdk's runtime won't break.
• TypeScript errors require source fixes in agoric-sdk but no behavioral changes.
• Industry convention (e.g., Zod, fp-ts) treats type-only breaking changes as minor since they don't affect semver (JS runtime).
• However, endo does ship TS types as part of the package contract. We should probably do a minor bump with a clear CHANGELOG noting the type-level enforcement changes.

So I intend a minor version bump on @endo/patterns and @endo/exo with migration notes via changeset.