refactor(patterns): Deprecate sloppy interface guard option (#2955)

Refs: #1831, Agoric/agoric-sdk#11931

## Description

We wish to visibly deprecate the `sloppy` option of `@endo/patterns`
interface guards. To avoid an explosion of `@typedef` blocks, we migrate
the `@endo/patterns` types to TypeScript and then add the minimally
required `@deprecated` tags.

### Security Considerations

N/A

### Scaling Considerations

N/A

### Documentation Considerations

N/A

### Testing Considerations

This modifies the implementation of the `@endo/patterns` types, but
should not modify them. Since the number of lines changed is larged, we
should attempt to convince ourselves that the types are in fact the
same.

### Compatibility Considerations

N/A

### Upgrade Considerations

Deprecates but does not remove the `sloppy` option. `NEWS.md` is
updated.

Author: rekmarks

.gitignore

@@ -101,6 +101,7 @@ api-docs
 !packages/far/src/exports.d.ts
 !packages/lp32/types.d.ts
 !packages/pass-style/src/types.d.ts
+!packages/patterns/types-index.d.ts
 !packages/ses/src/reporting-types.d.ts
 !packages/ses/types.d.ts
 !packages/stream/types.d.ts

packages/patterns/NEWS.md

@@ -1,5 +1,9 @@
 User-visible changes in `@endo/patterns`:
 
+# Next release
+
+- The `sloppy` option for `@endo/patterns` interface guards is deprecated. Use `defaultGuards` instead.
+
 # 1.7.0 (2025-07-11)
 
 - `@endo/marshal` introduces an environment variable config option `ENDO_RANK_STRINGS` to change the rank ordering of strings from the current (incorrect) ordering by UTF-16 code unit used by JavaScript's `<` and `.sort()` operations to (correct and OCapN-conformant) ordering by Unicode code point. It currently defaults to "utf16-code-unit-order", matching the previously-unconditional behavior.

packages/patterns/index.js

@@ -76,7 +76,7 @@ export {
 } from './src/patterns/getGuardPayloads.js';
 
 // eslint-disable-next-line import/export
-export * from './src/types.js';
+export * from './types-index.js';
 
 // /////////////////////////// Deprecated //////////////////////////////////////
 

packages/patterns/src/patterns/types.js

@@ -0,0 +1,59 @@
+/// <reference types="ses"/>
+
+import type { Rejector } from '@endo/errors/rejector.js';
+import type { Passable } from '@endo/pass-style';
+import type {
+  MatcherNamespace,
+  Pattern,
+  GetRankCover,
+  Kind,
+} from '../types.js';
+
+/**
+ * This factors out only the parts specific to each kind of Matcher. It is
+ * encapsulated, and its methods can make the stated unchecked assumptions
+ * enforced by the common calling logic.
+ */
+export type MatchHelper = {
+  /**
+   * Reports whether `allegedPayload` is valid as the payload of a CopyTagged
+   * whose tag corresponds with this MatchHelper's Matchers.
+   */
+  confirmIsWellFormed: (allegedPayload: Passable, reject: Rejector) => boolean;
+
+  /**
+   * Assuming validity of `matcherPayload` as the payload of a Matcher corresponding
+   * with this MatchHelper, reports whether `specimen` is matched by that Matcher.
+   */
+  confirmMatches: (
+    specimen: Passable,
+    matcherPayload: Passable,
+    reject: Rejector,
+  ) => boolean;
+
+  /**
+   * Assumes this is the payload of a CopyTagged with the corresponding
+   * matchTag. Return a RankCover to bound from below and above,
+   * in rank order, all possible Passables that would match this Matcher.
+   * The left element must be before or the same rank as any possible
+   * matching specimen. The right element must be after or the same
+   * rank as any possible matching specimen.
+   */
+  getRankCover: GetRankCover;
+};
+
+export type PatternKit = {
+  confirmMatches: (
+    specimen: any,
+    patt: Passable,
+    reject: Rejector,
+    label?: string | number,
+  ) => boolean;
+  matches: (specimen: any, patt: Pattern) => boolean;
+  mustMatch: (specimen: any, patt: Pattern, label?: string | number) => void;
+  assertPattern: (patt: Pattern) => void;
+  isPattern: (patt: any) => boolean;
+  getRankCover: GetRankCover;
+  M: MatcherNamespace;
+  kindOf: (specimen: Passable, reject: Rejector) => Kind | undefined;
+};