@zapier/kitcore 0.19.0 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,156 @@
 # @zapier/kitcore
 
+## 0.21.0
+
+### Minor Changes
+
+- 2102c00: **Removed the legacy function-plugin bridge.** A plugin is now always a
+  descriptor built by `define*` / `declare*`, never a `(sdk) => provides`
+  function. These exits shipped deprecated with runtime warnings in 0.5.0 and are
+  now gone:
+
+  | Removed                                                                           | Use instead                                                             |
+  | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+  | `createPluginStack`, `composePlugins`                                             | `definePlugin({ name, exports })` and `createSdk(root)`                 |
+  | `createPluginMethod`, `createPaginatedPluginMethod`                               | `defineMethod({ output: "item" })` / `defineMethod({ output: "list" })` |
+  | `createCorePlugin(options)`                                                       | `createSdk(root, { configuration: { [CORE_OPTIONS_ID]: options } })`    |
+  | `fromFunctionPlugin`, `defineLegacyMerge`                                         | `createSdk(root)` on a descriptor root                                  |
+  | `definePlugin(fn)` (the function form)                                            | `defineMethod` / `defineProperty` / `definePlugin({ ... })`             |
+  | `Plugin<TSdk, TProvides>` (the function-plugin type)                              | `Plugin` now names the descriptor a `define*` call returns              |
+  | `PluginProvides`, `Sdk`, `PluginStack`, `LegacyPlugin`, `LegacyMergePlugin` types | `PluginSurface<typeof plugin>` for a plugin's own surface               |
+  | `OutputFormatter` type                                                            | `defineFormatter`, whose result is a `Formatter`                        |
+
+  Also removed, with no deprecation warning: `createFunction`,
+  `createPaginatedFunction`, and the `AdaptPage` type. Only a function plugin
+  could use their output. Author with `defineMethod({ output: "item" })` or
+  `defineMethod({ output: "list" })` instead.
+
+  Consequences for code that builds with `createSdk`:
+  - `addPlugin(sdk, plugin)` types `plugin` as a descriptor, so a function or
+    any other non-plugin no longer compiles, and it refuses one at runtime too.
+  - `context.meta` and `context.core` are gone. Read metadata with
+    `getRegistry(sdk)`, and inject framework options under `CORE_OPTIONS_ID`.
+  - `SdkContext` has no index signature, so `sdk.context.anything` no longer
+    typechecks.
+  - Description fields live flat on the descriptor, as the author wrote them,
+    and flat on the built entry, like its runtime fields. There is no `meta` bag
+    on either any more. A `defineOverride` carries its fields as
+    `MethodOverridePlugin.patch` and writes them into the entry, so the
+    descriptor still shows what the author wrote.
+  - The description fields split by kind. `PropertyMeta` is what any leaf can
+    carry: `description`, `categories`, `packages`, `stability`, `experimental`,
+    `deprecation`. `MethodMeta` extends it with what only a callable has: `type`,
+    `itemType`, `returnType`, `confirm`, `aliases`, `supportsJsonOutput`. A
+    property config no longer accepts `aliases`, and a `defineOverride` patch is
+    typed as `OverridableMetaFields` instead of the whole bag. `PluginMeta` and
+    `LeafMeta` are deprecated aliases of `MethodMeta`. Gone from all of them:
+    `formatter`, `resolvers`, the `TSdk` type parameter, `inputSchema` and
+    `outputSchema` (method fields, since they drive validation), and the
+    `[key: string]: any` index signature, so an unknown field no longer compiles.
+    `skipOutputValidation` is a runtime switch and lives on the method config
+    beside `skipInputValidation`.
+  - Every descriptor kind extends `PluginBase` (`pluginType`, `name`,
+    `namespace`, `id`, `imports`, `importBindings`). Methods and properties extend
+    `LeafBase` (stand-in and default markers, `setup`, `dispose`), and a hook adds
+    `PluginLifecycle`. `PluginType` names the discriminant union. No shape
+    changed; the shared fields are declared once.
+  - Pagination helpers are exported by name rather than through a wildcard. The
+    helpers themselves are unchanged.
+  - `getRegistry` is no longer a reserved root key. `context` still is, and
+    `createSdk` now refuses it for a root too, not only `addPlugin`.
+
+  Errors that used to surface as a `TypeError` about a kitcore internal now name
+  the mistake:
+  - `getContext(sdk)` and `getRegistry(sdk)` throw `CoreErrorCode.NoSdkContext`
+    when the object has no plugin graph. `getRegistry(sdk)` still falls back to a
+    surfaced `getRegistry()` first.
+  - `createSdk` and `addPlugin` refuse a non-descriptor, a `declare*` stand-in,
+    and any `pluginType` the model does not build. An extension built against a
+    kitcore that still had the bridge fails this way, with
+    `unknown pluginType "legacy"`, and must be rebuilt against this release.
+    Nested plugins are checked too, and `definePlugin`, `defineMethod`,
+    `defineProperty`, and `defineHook` check each `imports` and `exports` entry as
+    it is written.
+
+  `context.plugins` now holds every plugin in the graph. A hook and a
+  `defineOverride` have entries too, with no value, and every entry carries
+  `descriptor`, the plugin object it was built from.
+
+  `addPlugin` is transactional and checks identity:
+  - A failed add rolls back everything it wrote and rethrows the original error.
+    A `dispose` registered by a `setup` that completed runs during the rollback.
+    Only its synchronous part is guaranteed, so release before the first `await`.
+  - A plugin whose id another plugin already claimed is refused instead of being
+    dropped silently. Re-adding the same descriptor still works, as does a
+    provider for an optional stand-in that nothing satisfied. Two overrides of
+    one method need distinct `namespace`s. A provider for an id a `declareDefault`
+    claimed belongs in the `createSdk` graph.
+
+  `Plugin` is the type of any `define*` result, for typing a slot that accepts
+  plugins. It replaces the function-plugin type of the same name.
+
+  Fixed: an inline `define*` call inside `definePlugin({ exports: [...] })` keeps
+  its inferred types instead of widening `input` to `any`.
+
+  Fixed: a plugin named `__proto__` replaced the prototype of kitcore's internal
+  plugin table instead of being stored. Every table kitcore keys by an
+  author-chosen name (plugin id, binding name) is now created without a
+  prototype, so any `Object.prototype` member name (`toString`, `constructor`,
+  `__proto__`) is an ordinary plugin name.
+
+## 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

@@ -366,7 +366,7 @@ Re-export the built-in `getRegistryPlugin` if you also want a `getRegistry()` me
 
 The result is memoized per SDK and per package filter, and `addPlugin` drops it, so a registry read still reflects anything added after the build. Because every reader shares that one object, its `functions` and `categories` arrays are frozen: copy before sorting or filtering in place.
 
-That holds for an SDK with a kitcore context, which is anything `createSdk` built. An SDK without one, meaning a `createPluginStack()` build, has no memo to share: `getRegistry(sdk)` forwards to the SDK's own `getRegistry()` and hands back whatever it builds, fresh and mutable on every call.
+That holds for an SDK with a kitcore context, which is anything `createSdk` built. An object without one that still surfaces its own `getRegistry()`, such as a test stub or a wrapper projecting someone else's registry, has no memo to share: `getRegistry(sdk)` forwards to that accessor and hands back whatever it builds, fresh and mutable on every call.
 
 ## Resolving inputs: controllers
 
@@ -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).