@zapier/kitcore 0.10.1 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @zapier/kitcore
 
+## 0.11.0
+
+### Minor Changes
+
+- 60892be: Added an explicit per-call annotation channel for attaching and reading per-invocation metadata:
+  - A method's `run` bag now includes the live `callContext` plus an `annotate(metadata)` function for recording per-invocation metadata onto the call's annotation bag.
+  - The `onMethodStart` / `onMethodEnd` hook context now carries `callId`, the call's `annotations`, and a `callOrigin` field (`"surface"` | `"internal"`), so observers can read a call's correlation id, annotations, and origin directly.
+  - `CallContext` gains a `callOrigin` field (`"surface"` | `"internal"`) that marks framework-internal calls, letting observers distinguish user calls from framework machinery (e.g. to keep framework calls out of telemetry). It is inherited by child calls, so a delegated subtree shares its root's origin.
+  - `defineHook` gains an optional `annotator` for deriving annotations from a call's input before `onMethodStart`. Multiple plugins' annotators compose (merged right-additively into the call's annotation bag), so annotation is contributed through the plugin graph rather than a single handler.
+  - `defineMethod` gains an optional pre-run `annotator` whose result merges into the call's annotations before `run`.
+  - Exported the `CallContext`, `Annotations`, and `CallOrigin` types, plus the `MethodAnnotator`, `HookAnnotator`, and `ComposedAnnotator` annotator function types.
+
 ## 0.10.1
 
 ### Patch Changes

package/README.md

@@ -44,7 +44,7 @@ There are four kinds of plugin, and an SDK is just a materialized plugin:
 
 - **Method** (`defineMethod`) — a leaf that _is_ a function.
 - **Property** (`defineProperty`) — a leaf that _is_ a value.
-- **Hook** (`defineHook`) — a leaf contributing cross-cutting behavior (see [Hooks](#hooks-wrap-and-observe)).
+- **Hook** (`defineHook`) — a leaf contributing cross-cutting behavior (see [Hooks](#hooks-wrap-observe-and-annotate)).
 - **Aggregate** (`definePlugin`) — re-exports other plugins under binding names.
 
 A plugin declares `imports` (an array of the plugins it depends on) and receives them as a flat `imports` bag, with each import bound under its own name. The two ends share the word the way ES modules do: `import { x } from "y"` is the declaration, `x` is the binding.
@@ -120,6 +120,26 @@ sdk.next(); // 2
 
 `setup` can read `imports`, so state can be built from dependencies. Because state lives behind `setup`, several small "state plugins" can each own a slice instead of one monolith.
 
+## Per-call context and annotations
+
+Every method `run` bag includes a live `callContext` with the invocation's `callId`, `depth`, `callOrigin`, and `annotations`. Each method invocation gets its own annotation bag; a delegated child shares its root's call ID and origin but starts with empty annotations.
+
+Use the run bag's `annotate(fields)` helper for metadata learned during execution. For metadata available from raw input, a method can declare a synchronous `annotator`; it runs before validation, `onMethodStart`, and `run`, so its `input` is `unknown` and must be narrowed before fields are read.
+
+```ts
+const runJob = defineMethod({
+  name: "runJob",
+  annotator: () => ({ operationType: "write" }),
+  run: async ({ input, callContext, annotate }) => {
+    const worker = await selectWorker(input);
+    annotate({ worker });
+    return executeJob(input, callContext.annotations);
+  },
+});
+```
+
+Both forms merge into the same bag. `annotator` supplies fields before the method starts; `annotate` adds fields as the method runs.
+
 ## Properties
 
 A property is a value rather than a function. It can be a static `value`, or a **live** `get` re-derived on every read, with an optional `setup` building the state `get` returns. So `setup` + `get` mirrors a method's `setup` + `run`.
@@ -217,9 +237,9 @@ const fetchMethod = defineMethod({
 sdk.fetch("https://example.com", { method: "GET" });
 ```
 
-## Hooks: wrap and observe
+## Hooks: wrap, observe, and annotate
 
-Cross-cutting behavior lives in a **hook** (`defineHook`), a fourth kind of leaf with two faces.
+Cross-cutting behavior lives in a **hook** (`defineHook`), a fourth kind of leaf with three faces.
 
 `wrap` is targeted middleware. An entry is keyed by the import binding it wraps and receives `{ imports, next, input }`. It must preserve the target's contract (enforced by the types), so it cannot change the public signature.
 
@@ -260,6 +280,17 @@ const telemetry = defineHook({
 });
 ```
 
+`annotator` adds cross-cutting annotations before `onMethodStart`. It is a synchronous mapper over `{ methodName, input, state }`; like method annotators, it receives raw pre-validation input. Multiple hook annotators compose in graph order, later fields win on collision, and the method's own annotator runs last. Each contributor is best-effort, so a thrown annotation error never breaks the method or suppresses other contributors.
+
+```ts
+const classifyOperations = defineHook({
+  name: "classifyOperations",
+  annotator: ({ methodName }) => ({ methodCategory: classify(methodName) }),
+});
+```
+
+Hook annotators run only for outermost surface-origin calls. They are suppressed for nested and internal-origin calls, and for methods called from an observer or another hook annotator. A method's own annotator still runs for every invocation, including those suppressed cases, so method behavior does not depend on how the method was reached.
+
 A hook joins the graph like any other plugin: import or export it from an aggregate.
 
 ## Dependency injection