@zapier/kitcore 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # @zapier/kitcore
 
+## 0.20.0
+
+### Minor Changes
+
+- 4b9d735: `createSdk` now checks that each id's providers match the contract its reference
+  declared, not only that a provider exists. A graph joined by string id used to
+  compile on the strength of the string alone, so a provider whose types
+  contradicted the reference reached the consumer and broke at runtime.
+
+  ```ts
+  const doubleRef = declareMethod<"double", { value: number }, number>({
+    id: "double",
+  });
+  // Written for a display surface: it formats instead of computing.
+  const formatsIt = defineMethod({
+    name: "double",
+    run: ({ input }: { input: { value: number } }) => `${input.value * 2}`,
+  });
+  // Compiled clean before. Rejected at createSdk now.
+  ```
+
+  A provider may accept **wider** input and must return a **subtype** of the
+  declared output, since the comparison is on the call a consumer makes. See the
+  kitcore README for how this applies to optional references, module references,
+  and `declareDefault`.
+
+  `selectExports` and `omitExports` now forward their source's ledgers. They
+  returned a bare aggregate before, which dropped both the requirements and the
+  contract ledger for everything behind them, so a head that reached a module
+  through either helper got no graph checking at all.
+
+  **Both changes can surface an error in a graph that compiled before.** That is
+  the point, since the mismatch was already there. Correct the provider, or widen
+  the reference to what the provider actually offers.
+
+  This release also fixes a latent problem with nested plugins. The cost of
+  checking a graph grew exponentially with aggregate nesting depth, and with the
+  length of a method import chain. Deep enough composition failed to compile at
+  all, reporting `error TS2589`. Both are close to linear now, so nesting and
+  chaining stay affordable.
+
+  Contract checking itself is new work, and it grows the declaration files a
+  package publishes. Every downstream typecheck and editor pays that cost.
+
+  **A hand-written annotation must be updated to keep its check.** `LeafSummary`
+  now requires the surfaced binding as a fourth argument, so a three-argument use
+  is a compile error. A `PluginSummary` written with two arguments still compiles
+  and declares no contract, which drops that plugin out of the check silently.
+
+  Added `ContractEntry`, `MethodContract`, `DeclarationSummary`, and
+  `OptionalDeclarationSummary`, for annotating a plugin by hand instead of letting
+  `define*` infer it.
+
 ## 0.19.0
 
 ### Minor Changes

package/README.md

@@ -454,6 +454,51 @@ Two flavors, by what happens when nothing provides the id:
 - **Required** (`declareMethod` / `declareProperty`): an unsatisfied reference is a **compile-time** error (with a runtime backstop). Use when the capability must be present.
 - **Optional** (`declareOptionalProperty` / `declareOptionalMethod`): binds `undefined` instead of failing, so the consumer handles absence in code (`{ ...DEFAULTS, ...imports.config }` for a value, `imports.track?.(...)` for a method). Use to reference a _foreign_ capability userland may or may not import, without claiming its slot.
 
+### The contract is checked, not just the id
+
+`createSdk` checks that each id's providers match the contract the reference declared, not only that a provider exists. The comparison is on the call a consumer makes, so a provider may accept **wider** input and must return a **subtype** of the declared output. A provider written from scratch is checked the same as one written against the reference.
+
+```ts
+const doubleRef = declareMethod<"double", { value: number }, number>({
+  id: "double",
+});
+
+// Rejected at createSdk: this author wrote `double` for a display surface, so
+// it formats instead of computing. The declaration promised a number.
+defineMethod({
+  name: "double",
+  run: ({ input }: { input: { value: number } }) => `${input.value * 2}`,
+});
+
+// Also rejected: an `item` method is a fine plugin, but the declaration asked
+// for a bare number, not an envelope.
+defineMethod({
+  name: "double",
+  output: "item",
+  run: async ({ input }: { input: { value: number } }) => ({
+    data: input.value * 2,
+  }),
+});
+
+// Accepted.
+defineMethod({
+  name: "double",
+  run: ({ input }: { input: { value: number } }) => input.value * 2,
+});
+```
+
+Two modules declaring one id independently is the intended use, and stays legal while they agree. They are caught when they disagree, because no single provider can satisfy both. Every reachable provider under an id must honor the contract, so a sound `declareDefault` beside an unsound explicit provider is still rejected: the explicit one is what the runtime picks.
+
+An optional reference is checked the same way when a provider does appear. Its contract is the binding a consumer sees, so `undefined` is part of it: a consumer of an optional reference handles the absent case regardless, and a by-reference provider is allowed to pass `undefined` explicitly.
+
+A module reference (`declarePlugin`) is checked through its export references, leaf by leaf, so a module method typed differently from its reference is caught. What is NOT checked is whether the real module exports everything the reference promised: only the module's own id is a requirement, so a promised export the module lacks still fails at runtime.
+
+Spell the contract out. An id-only `declareMethod<"double">({ id: "double" })` defaults to `unknown` on both sides. That makes it over-strict on input, since a consumer may call it with no argument and any provider needing real input is rejected, and vacuous on output, since every provider returns a subtype of `unknown`. No `declare*` call opts out of the compatibility check.
+
+What the graph checks do NOT reach. A `defineHook` carries no summary, so a declaration reachable only through a hook's `imports` is checked by neither ledger. `addPlugin` performs no graph checks at all. And a positional surface cannot be declared by id: `declareMethod` describes an object call only, so a positional provider is correctly rejected against one, and referencing a positional method means casting past the ledger (`curl` does exactly that for `fetch`). Those three are limitations, not design.
+
+If you annotate a plugin by hand rather than letting `define*` infer it, pass the contract. `LeafSummary` takes the surfaced binding as a fourth argument (`LeafSummary<"", "setup", typeof imports, MethodContract<SetupOptions, Promise<void>>>`), and a reference is `DeclarationSummary<TId, TBinding>` or `OptionalDeclarationSummary<TId, TBinding>`. A `PluginSummary` written with two arguments still compiles and declares no contract, so a hand-annotated plugin drops out of the compatibility check silently.
+
 ## Defaults
 
 When you _own_ a capability slot and can ship a working implementation, register it as a default with `declareDefault({ plugin })` rather than referencing it. A default is a real, single node in the graph, so it works out of the box, hooks and middleware can wrap it, and an explicit provider of the same id silently preempts it (that is the seam for userland or another plugin to replace it).

package/dist/index.cjs

@@ -2028,8 +2028,9 @@ function declareOptionalMethod(config) {
         `Plugin "${id}" is an optional stand-in (declareOptionalMethod) with no implementation. Its binding is \`undefined\` unless a real plugin is registered under this id.`
       );
     }
-    // Requires nothing (phantom carrier `<never, never>`): a consumer that
-    // imports it still passes `createSdk`'s completeness check unprovided. The
+    // Requires nothing: a consumer that imports it still passes `createSdk`'s
+    // completeness check unprovided. The contract is still carried, so a
+    // provider that DOES appear under the id is checked against it. The
     // `optional: true` literal drives `PluginSurface` to type the binding
     // `| undefined`.
   };
@@ -2079,9 +2080,12 @@ function declareOptionalProperty(config) {
     optional: true,
     imports: [],
     importBindings: []
-    // Requires nothing (phantom carrier `<never, never>`): a consumer that
-    // imports it still passes `createSdk`'s completeness check unprovided. The
-    // import binding is still typed `TValue | undefined` from the descriptor.
+    // Requires nothing: a consumer that imports it still passes `createSdk`'s
+    // completeness check unprovided. The contract is the binding a consumer
+    // sees, `TValue | undefined`, which is also what a by-reference provider
+    // (`defineProperty(ref, { value })`) is allowed to pass. A consumer of an
+    // optional reference has to handle the absent case either way, so an
+    // explicit `undefined` breaks nothing a narrower contract would protect.
   };
 }
 function declareDefault({