@zapier/kitcore 0.10.1 → 0.12.0

package/dist/index.mjs

@@ -197,12 +197,19 @@ function composeVoid(existing, added) {
   isolated.add(composed);
   return composed;
 }
+function composeAnnotators(existing, added) {
+  if (!existing) return added;
+  if (!added) return existing;
+  return (ctx) => ({ ...existing(ctx), ...added(ctx) });
+}
 function buildHooks(existing, added) {
   const result = {};
   const start2 = composeVoid(existing.onMethodStart, added.onMethodStart);
   if (start2) result.onMethodStart = start2;
   const end = composeVoid(existing.onMethodEnd, added.onMethodEnd);
   if (end) result.onMethodEnd = end;
+  const annotator = composeAnnotators(existing.annotator, added.annotator);
+  if (annotator) result.annotator = annotator;
   return result;
 }
 
@@ -677,11 +684,14 @@ function generateCallId() {
   }
   return null;
 }
-function rootCallContext() {
+function rootCallContext({
+  callOrigin = "surface"
+} = {}) {
   return {
     callId: generateCallId(),
     depth: 0,
     annotations: {},
+    callOrigin,
     [CALL_CONTEXT_BRAND]: true
   };
 }
@@ -690,6 +700,7 @@ function childCallContext(parent) {
     callId: parent.callId,
     depth: parent.depth + 1,
     annotations: {},
+    callOrigin: parent.callOrigin,
     [CALL_CONTEXT_BRAND]: true
   };
 }
@@ -715,6 +726,28 @@ var INTERNAL_CALL = Symbol("kitcore.internalCall");
 function resolveCallContext(secondArg) {
   return isCallContext(secondArg) ? secondArg : rootCallContext();
 }
+var hookAnnotatorReentrancy = 0;
+function applyAnnotations({
+  context,
+  methodName,
+  input,
+  hookAnnotator,
+  methodAnnotator
+}) {
+  if (hookAnnotator && !isInsideObserver() && context.depth === 0 && context.callOrigin !== "internal" && hookAnnotatorReentrancy === 0) {
+    hookAnnotatorReentrancy++;
+    try {
+      Object.assign(context.annotations, hookAnnotator({ methodName, input }));
+    } catch {
+    } finally {
+      hookAnnotatorReentrancy--;
+    }
+  }
+  try {
+    Object.assign(context.annotations, methodAnnotator?.(input));
+  } catch {
+  }
+}
 function signalDeprecation(context, methodName, getDeprecation) {
   if (isInsideObserver()) return;
   const deprecation = getDeprecation?.();
@@ -740,7 +773,7 @@ function normalizeError(error, adaptError) {
   );
 }
 function createFunction(coreFn, options) {
-  const { sdk, schema, name, getDeprecation } = options;
+  const { sdk, schema, name, annotator, getDeprecation } = options;
   const functionName = name || coreFn.name;
   const namedFunctions = {
     [functionName]: async function(callOptions) {
@@ -754,14 +787,26 @@ function createFunction(coreFn, options) {
         const normalizedOptions = callOptions ?? {};
         const args = [normalizedOptions];
         const depth = Math.max(context.depth, getCurrentDepth());
-        const hooks = isInsideObserver() ? void 0 : sdk.context.hooks;
+        const insideObserver = isInsideObserver();
+        const hooks = insideObserver ? void 0 : sdk.context.hooks;
         const adaptError = resolveCoreOptions(sdk.context)?.adaptError;
-        hooks?.onMethodStart?.({
+        applyAnnotations({
+          context,
+          methodName: functionName,
+          input: normalizedOptions,
+          hookAnnotator: hooks?.annotator,
+          methodAnnotator: annotator
+        });
+        const hookBase = {
           methodName: functionName,
           args,
           isPaginated: false,
-          depth
-        });
+          depth,
+          callId: context.callId,
+          callOrigin: context.callOrigin,
+          annotations: context.annotations
+        };
+        hooks?.onMethodStart?.({ ...hookBase });
         try {
           let result;
           if (schema) {
@@ -783,20 +828,14 @@ function createFunction(coreFn, options) {
             result = await coreFn(normalizedOptions, context);
           }
           hooks?.onMethodEnd?.({
-            methodName: functionName,
-            args,
-            isPaginated: false,
-            depth,
+            ...hookBase,
             durationMs: Date.now() - startTime
           });
           return result;
         } catch (error) {
           const normalizedError = normalizeError(error, adaptError);
           hooks?.onMethodEnd?.({
-            methodName: functionName,
-            args,
-            isPaginated: false,
-            depth,
+            ...hookBase,
             durationMs: Date.now() - startTime,
             error: normalizedError
           });
@@ -808,7 +847,7 @@ function createFunction(coreFn, options) {
   return namedFunctions[functionName];
 }
 function createRawFunction(coreFn, options) {
-  const { sdk, name, schema, positional, getDeprecation } = options;
+  const { sdk, name, schema, positional, annotator, getDeprecation } = options;
   return function(rawInput) {
     const internal = arguments[1];
     const context = resolveCallContext(internal);
@@ -818,23 +857,32 @@ function createRawFunction(coreFn, options) {
     return runInMethodScope(() => {
       const startTime = Date.now();
       const depth = Math.max(context.depth, getCurrentDepth());
-      const hooks = isInsideObserver() ? void 0 : sdk.context.hooks;
+      const insideObserver = isInsideObserver();
+      const hooks = insideObserver ? void 0 : sdk.context.hooks;
       const adaptError = resolveCoreOptions(sdk.context)?.adaptError;
       const input = schema ? rawInput ?? {} : rawInput;
+      applyAnnotations({
+        context,
+        methodName: name,
+        input,
+        hookAnnotator: hooks?.annotator,
+        methodAnnotator: annotator
+      });
       const record = input;
       const args = positional ? positional.filter((key) => record?.[key] !== void 0).map((key) => record?.[key]) : [input];
-      hooks?.onMethodStart?.({
+      const hookBase = {
         methodName: name,
         args,
         isPaginated: false,
-        depth
-      });
+        depth,
+        callId: context.callId,
+        callOrigin: context.callOrigin,
+        annotations: context.annotations
+      };
+      hooks?.onMethodStart?.({ ...hookBase });
       const fireEnd = (error) => {
         hooks?.onMethodEnd?.({
-          methodName: name,
-          args,
-          isPaginated: false,
-          depth,
+          ...hookBase,
           durationMs: Date.now() - startTime,
           ...error ? { error } : {}
         });
@@ -876,7 +924,8 @@ function isSdkPage(value) {
 }
 function createPageFunction(coreFn, {
   sdk,
-  adaptPage
+  adaptPage,
+  finalizePage
 }) {
   const functionName = coreFn.name + "Page";
   const namedFunctions = {
@@ -889,7 +938,7 @@ function createPageFunction(coreFn, {
             `${functionName}: paginated result must be exactly { data: TItem[], nextCursor? } (produced by the handler or its \`adaptPage\`); got keys [${page && typeof page === "object" ? Object.keys(page).join(", ") : typeof page}]. If the handler returns a raw shape, set \`adaptPage\` to translate it; if \`adaptPage\` already runs, it must return only \`data\`/\`nextCursor\`.`
           );
         }
-        return page;
+        return finalizePage ? finalizePage(page) : page;
       } catch (error) {
         throw normalizeError(
           error,
@@ -901,8 +950,21 @@ function createPageFunction(coreFn, {
   return namedFunctions[functionName];
 }
 function createPaginatedFunction(coreFn, options) {
-  const { sdk, schema, name, defaultPageSize, adaptPage, getDeprecation } = options;
-  const pageFunction = createPageFunction(coreFn, { sdk, adaptPage });
+  const {
+    sdk,
+    schema,
+    name,
+    defaultPageSize,
+    adaptPage,
+    annotator,
+    finalizePage,
+    getDeprecation
+  } = options;
+  const pageFunction = createPageFunction(coreFn, {
+    sdk,
+    adaptPage,
+    finalizePage
+  });
   const functionName = name || coreFn.name;
   const namedFunctions = {
     [functionName]: function(callOptions) {
@@ -916,14 +978,26 @@ function createPaginatedFunction(coreFn, options) {
         const normalizedOptions = callOptions ?? {};
         const args = [normalizedOptions];
         const depth = Math.max(context.depth, getCurrentDepth());
-        const hooks = isInsideObserver() ? void 0 : sdk.context.hooks;
+        const insideObserver = isInsideObserver();
+        const hooks = insideObserver ? void 0 : sdk.context.hooks;
         const adaptError = resolveCoreOptions(sdk.context)?.adaptError;
-        hooks?.onMethodStart?.({
+        applyAnnotations({
+          context,
+          methodName: functionName,
+          input: normalizedOptions,
+          hookAnnotator: hooks?.annotator,
+          methodAnnotator: annotator
+        });
+        const hookBase = {
           methodName: functionName,
           args,
           isPaginated: true,
-          depth
-        });
+          depth,
+          callId: context.callId,
+          callOrigin: context.callOrigin,
+          annotations: context.annotations
+        };
+        hooks?.onMethodStart?.({ ...hookBase });
         try {
           const validatedOptions = {
             ...normalizedOptions,
@@ -949,19 +1023,13 @@ function createPaginatedFunction(coreFn, options) {
             firstPagePromise.then(
               () => {
                 hooks.onMethodEnd({
-                  methodName: functionName,
-                  args,
-                  isPaginated: true,
-                  depth,
+                  ...hookBase,
                   durationMs: Date.now() - startTime
                 });
               },
               (error) => {
                 hooks.onMethodEnd({
-                  methodName: functionName,
-                  args,
-                  isPaginated: true,
-                  depth,
+                  ...hookBase,
                   durationMs: Date.now() - startTime,
                   error: error instanceof Error ? error : new Error(String(error))
                 });
@@ -1000,10 +1068,7 @@ function createPaginatedFunction(coreFn, options) {
         } catch (error) {
           const normalizedError = normalizeError(error, adaptError);
           hooks?.onMethodEnd?.({
-            methodName: functionName,
-            args,
-            isPaginated: true,
-            depth,
+            ...hookBase,
             durationMs: Date.now() - startTime,
             error: normalizedError
           });
@@ -1425,9 +1490,11 @@ function defineMethod(config) {
     importBindings: deps.bindings,
     inputSchema: config.inputSchema,
     skipInputValidation: config.skipInputValidation,
+    skipOutputValidation: config.skipOutputValidation,
     meta: collectLeafMeta(config),
     resolvers: config.resolvers,
     formatter: config.formatter,
+    annotator: config.annotator,
     output: config.output,
     positional: config.positional,
     setup: config.setup,
@@ -1530,6 +1597,29 @@ function declareMethod(config) {
     }
   };
 }
+function declareOptionalMethod(config) {
+  const { name, namespace } = parseId(config.id);
+  const id = makeId(name, namespace);
+  return {
+    pluginType: "method",
+    name,
+    namespace,
+    id,
+    standIn: true,
+    optional: true,
+    imports: [],
+    importBindings: [],
+    run: () => {
+      throw new Error(
+        `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
+    // `optional: true` literal drives `PluginSurface` to type the binding
+    // `| undefined`.
+  };
+}
 function defineProperty(config) {
   const deps = normalizeImports(config.imports);
   return {
@@ -1575,6 +1665,11 @@ function declareOptionalProperty(config) {
     // import binding is still typed `TValue | undefined` from the descriptor.
   };
 }
+function declareDefault({
+  plugin
+}) {
+  return { ...plugin, defaultSource: plugin };
+}
 function defineHook(config) {
   const deps = normalizeImports(config.imports);
   return {
@@ -1587,7 +1682,8 @@ function defineHook(config) {
     setup: config.setup,
     dispose: config.dispose,
     wrap: config.wrap,
-    observe: config.observe
+    observe: config.observe,
+    annotator: config.annotator
   };
 }
 function declarePlugin(config) {
@@ -1875,6 +1971,97 @@ var getRegistryPlugin = defineMethod({
   run: ({ imports, input }) => buildSurfaceRegistry(imports.context, input?.package)
 });
 
+// src/utils/output-policy.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function diffDroppedPaths(raw, parsed, prefix = "") {
+  const paths = [];
+  walkDroppedPaths(raw, parsed, prefix, paths);
+  return paths;
+}
+function walkDroppedPaths(raw, parsed, prefix, out) {
+  if (Array.isArray(raw) && Array.isArray(parsed)) {
+    const seen = /* @__PURE__ */ new Set();
+    const length = Math.min(raw.length, parsed.length);
+    for (let index = 0; index < length; index++) {
+      const elementPaths = [];
+      walkDroppedPaths(raw[index], parsed[index], `${prefix}[]`, elementPaths);
+      for (const path of elementPaths) {
+        if (seen.has(path)) continue;
+        seen.add(path);
+        out.push(path);
+      }
+    }
+    return;
+  }
+  if (isRecord(raw) && isRecord(parsed)) {
+    for (const key of Object.keys(raw)) {
+      const path = prefix ? `${prefix}.${key}` : key;
+      if (!(key in parsed)) {
+        out.push(path);
+        continue;
+      }
+      walkDroppedPaths(raw[key], parsed[key], path, out);
+    }
+    return;
+  }
+}
+function parseOutput(schema, value, policy, locator) {
+  const result = schema.safeParse(value);
+  if (result.success) return result.data;
+  const issues = result.error.issues.map((issue) => {
+    const path = issue.path.length > 0 ? issue.path.join(".") : "data";
+    return `${path}: ${issue.message}`;
+  });
+  const subject = policy.methodName ? ` for "${policy.methodName}"` : "";
+  const at = locator ? ` at ${locator}` : "";
+  throw createCoreError(
+    {
+      code: CoreErrorCode.Validation,
+      message: `Output validation failed${subject}${at}:
+  ${issues.join("\n  ")}
+
+The response does not match the method's \`outputSchema\`. Correct the schema, or set \`skipOutputValidation: true\` on the method to pass the response through unvalidated.`,
+      details: { zodErrors: result.error.issues, output: value }
+    },
+    policy.adaptError
+  );
+}
+function applyItemOutputPolicy(result, policy) {
+  const schema = policy.outputSchema;
+  if (!schema || policy.skipOutputValidation) return result;
+  if (!isRecord(result) || !("data" in result)) return result;
+  const data = parseOutput(schema, result.data, policy);
+  const next = { ...result, data };
+  if (policy.includeOutputValidationDroppedPaths) {
+    const droppedPaths = diffDroppedPaths(result.data, data);
+    if (droppedPaths.length > 0) {
+      next.meta = withOutputValidation(result.meta, droppedPaths);
+    }
+  }
+  return next;
+}
+function withOutputValidation(existing, droppedPaths) {
+  const base = isRecord(existing) ? existing : {};
+  return { ...base, outputValidation: { droppedPaths } };
+}
+function applyListOutputPolicy(page, policy) {
+  const schema = policy.outputSchema;
+  if (!schema || policy.skipOutputValidation) return page;
+  const data = page.data.map(
+    (item, index) => parseOutput(schema, item, policy, `data[${index}]`)
+  );
+  const next = { ...page, data };
+  if (policy.includeOutputValidationDroppedPaths) {
+    const droppedPaths = diffDroppedPaths(page.data, data);
+    if (droppedPaths.length > 0) {
+      next.meta = { ...page.meta, outputValidation: { droppedPaths } };
+    }
+  }
+  return next;
+}
+
 // src/model/materialize.ts
 var FRAMEWORK_CONFIGURATION_IDS = /* @__PURE__ */ new Set([
   CORE_OPTIONS_ID
@@ -1938,6 +2125,9 @@ function edgesOf(plugin) {
 function isStandIn(plugin) {
   return (plugin.pluginType === "method" || plugin.pluginType === "property" || plugin.pluginType === "aggregate") && plugin.standIn === true;
 }
+function isDefault(plugin) {
+  return (plugin.pluginType === "method" || plugin.pluginType === "property") && plugin.defaultSource !== void 0;
+}
 function topoOrder(descriptors) {
   const order = [];
   const visited = /* @__PURE__ */ new Set();
@@ -1952,28 +2142,89 @@ function topoOrder(descriptors) {
   return order;
 }
 function collectPlugins(root, materialized = /* @__PURE__ */ new Set(), configuration) {
+  const rank = (plugin) => isStandIn(plugin) ? 0 : isDefault(plugin) ? 1 : 2;
+  const allNodes = [];
+  const seen = /* @__PURE__ */ new Set();
+  const collect = (plugin) => {
+    if (materialized.has(plugin.id) || seen.has(plugin)) return;
+    seen.add(plugin);
+    allNodes.push(plugin);
+    for (const edge of edgesOf(plugin)) collect(edge);
+  };
+  collect(root);
+  const childrenOf = /* @__PURE__ */ new Map();
+  const candidatesById = /* @__PURE__ */ new Map();
+  for (const node of allNodes) {
+    childrenOf.set(
+      node,
+      edgesOf(node).filter((edge) => seen.has(edge))
+    );
+    const candidates = candidatesById.get(node.id);
+    if (candidates) candidates.push(node);
+    else candidatesById.set(node.id, [node]);
+  }
+  const live = new Set(allNodes);
+  for (; ; ) {
+    const reachable = /* @__PURE__ */ new Set();
+    if (live.has(root)) reachable.add(root);
+    const queue = reachable.has(root) ? [root] : [];
+    while (queue.length) {
+      const node = queue.pop();
+      for (const child of childrenOf.get(node) ?? []) {
+        if (reachable.has(child)) continue;
+        reachable.add(child);
+        if (live.has(child)) queue.push(child);
+      }
+    }
+    let changed = false;
+    for (const node of live) {
+      if (!reachable.has(node)) {
+        live.delete(node);
+        changed = true;
+      }
+    }
+    for (const candidates of candidatesById.values()) {
+      let maxRank = -1;
+      for (const candidate of candidates) {
+        if (live.has(candidate)) maxRank = Math.max(maxRank, rank(candidate));
+      }
+      if (maxRank < 0) continue;
+      for (const candidate of candidates) {
+        if (live.has(candidate) && rank(candidate) < maxRank) {
+          live.delete(candidate);
+          changed = true;
+        }
+      }
+    }
+    if (!changed) break;
+  }
   const byId = /* @__PURE__ */ new Map();
-  const visit = (plugin) => {
-    if (materialized.has(plugin.id)) return;
-    const existing = byId.get(plugin.id);
-    if (existing === plugin) return;
-    if (existing) {
-      const bothReal = !isStandIn(existing) && !isStandIn(plugin);
-      if (bothReal) {
+  const conflictedDefaults = /* @__PURE__ */ new Set();
+  const isOptional = (plugin) => "optional" in plugin && plugin.optional === true;
+  for (const [id, candidates] of candidatesById) {
+    const liveCandidates = candidates.filter(
+      (candidate) => live.has(candidate)
+    );
+    const winner = liveCandidates.find((candidate) => !isOptional(candidate)) ?? liveCandidates[0];
+    if (!winner) continue;
+    if (liveCandidates.length > 1) {
+      const winnerRank = rank(winner);
+      if (winnerRank === 2) {
         throw new Error(
-          `createSdk: duplicate plugin id "${plugin.id}". Two different plugins registered under the same id.`
+          `createSdk: duplicate plugin id "${id}". Two different plugins registered under the same id.`
         );
       }
-      if (isStandIn(existing) && !isStandIn(plugin)) {
-        byId.set(plugin.id, plugin);
-        for (const edge of edgesOf(plugin)) visit(edge);
+      if (winnerRank === 1) {
+        const sources = new Set(
+          liveCandidates.map(
+            (candidate) => candidate.defaultSource
+          )
+        );
+        if (sources.size > 1) conflictedDefaults.add(id);
       }
-      return;
     }
-    byId.set(plugin.id, plugin);
-    for (const edge of edgesOf(plugin)) visit(edge);
-  };
-  visit(root);
+    byId.set(id, winner);
+  }
   if (configuration) {
     for (const [id, value] of Object.entries(configuration)) {
       const existing = byId.get(id);
@@ -2024,9 +2275,24 @@ function collectPlugins(root, materialized = /* @__PURE__ */ new Set(), configur
       );
     }
   }
+  for (const id of conflictedDefaults) {
+    const winner = byId.get(id);
+    if (winner && isDefault(winner)) {
+      throw new Error(
+        `createSdk: conflicting defaults for "${id}". Two different plugins were declared as defaults for the same id and nothing else provides it. Register an explicit (non-default) plugin for this id to choose the winner, or give the implementations distinct ids if they are meant to coexist.`
+      );
+    }
+  }
   return byId;
 }
-function bindValue(target, key, entry, callType = "surface", ctx) {
+function bindValue({
+  target,
+  key,
+  entry,
+  bindMode = "surface",
+  ctx,
+  frameworkOrigin = false
+}) {
   if (entry.pluginType === "property" && entry.getValue) {
     Object.defineProperty(target, key, {
       get: entry.getValue,
@@ -2034,7 +2300,7 @@ function bindValue(target, key, entry, callType = "surface", ctx) {
       configurable: true
     });
   } else {
-    const value = callType === "internal" && entry.pluginType === "method" ? entry.bindInternal?.(ctx) ?? entry.internalValue ?? entry.value : entry.value;
+    const value = bindMode === "internal" && entry.pluginType === "method" ? entry.bindInternal?.({ ctx, frameworkOrigin }) ?? entry.internalValue ?? entry.value : entry.value;
     Object.defineProperty(target, key, {
       value,
       writable: true,
@@ -2052,7 +2318,12 @@ function buildSurface(context, ...maps) {
   sdk[CONTEXT] = context;
   return sdk;
 }
-function buildImports(plugins, importBindings, ctx) {
+function buildImports({
+  plugins,
+  importBindings,
+  ctx,
+  frameworkOrigin = false
+}) {
   const imports = {};
   for (const { binding, id, optional } of importBindings) {
     const entry = plugins[id];
@@ -2065,10 +2336,31 @@ function buildImports(plugins, importBindings, ctx) {
       });
       continue;
     }
-    bindValue(imports, binding, entry, "internal", ctx);
+    bindValue({
+      target: imports,
+      key: binding,
+      entry,
+      bindMode: "internal",
+      ctx,
+      frameworkOrigin
+    });
   }
   return imports;
 }
+function bindInternalTwin({
+  ctx,
+  frameworkOrigin,
+  withContext,
+  internalValue
+}) {
+  if (ctx) {
+    return (...args) => withContext(childCallContext(ctx))(...args);
+  }
+  if (frameworkOrigin) {
+    return (...args) => withContext(rootCallContext({ callOrigin: "internal" }))(...args);
+  }
+  return internalValue;
+}
 function mirrorLegacyRootKeys(context, rootKeys, meta) {
   const exports = {};
   for (const [name, value] of Object.entries(rootKeys)) {
@@ -2132,7 +2424,11 @@ function bindResolver(resolver, plugins) {
     case "info":
       return { type: "info", text: resolver.text };
     case "object": {
-      const imports = buildImports(plugins, resolver.importBindings);
+      const imports = buildImports({
+        plugins,
+        importBindings: resolver.importBindings,
+        frameworkOrigin: true
+      });
       const bound = {
         type: "object",
         requireParameters: resolver.requireParameters
@@ -2173,7 +2469,11 @@ function bindResolver(resolver, plugins) {
       return bound;
     }
     case "dynamic": {
-      const imports = buildImports(plugins, resolver.importBindings);
+      const imports = buildImports({
+        plugins,
+        importBindings: resolver.importBindings,
+        frameworkOrigin: true
+      });
       const {
         getContext: getContext2,
         listItems,
@@ -2228,7 +2528,11 @@ function bindDefinitions(definitions, plugins) {
   return out;
 }
 function bindFormatter(formatter, plugins) {
-  const imports = buildImports(plugins, formatter.importBindings);
+  const imports = buildImports({
+    plugins,
+    importBindings: formatter.importBindings,
+    frameworkOrigin: true
+  });
   const bound = { format: formatter.format };
   const { getContext: getContext2 } = formatter;
   if (getContext2)
@@ -2302,6 +2606,7 @@ function buildMethodEntries(descriptors, context, states) {
   const plugins = context.plugins;
   for (const [id, descriptor] of descriptors) {
     if (descriptor.pluginType !== "method") continue;
+    if (isStandIn(descriptor)) continue;
     const out = normalizeOutput(descriptor.output);
     const entry = {
       pluginType: "method",
@@ -2316,17 +2621,32 @@ function buildMethodEntries(descriptors, context, states) {
       // Replaced below; never called.
       value: () => void 0
     };
-    const callRun = (input, ctx) => descriptor.run({
-      imports: buildImports(plugins, descriptor.importBindings, ctx),
-      state: states.get(id),
-      input
-    });
+    const callRun = (input, ctx) => {
+      const callContext = ctx ?? rootCallContext();
+      return descriptor.run({
+        imports: buildImports({
+          plugins,
+          importBindings: descriptor.importBindings,
+          ctx: callContext
+        }),
+        state: states.get(id),
+        input,
+        callContext,
+        annotate: (metadata) => {
+          Object.assign(callContext.annotations, metadata);
+        }
+      });
+    };
     const fold = (coreFn) => (input, ctx) => {
       let next = (i) => coreFn(i, ctx);
       for (const wrap of entry.chain) {
         const inner = next;
         next = (i) => wrap.run({
-          imports: buildImports(plugins, wrap.owner.importBindings, ctx),
+          imports: buildImports({
+            plugins,
+            importBindings: wrap.owner.importBindings,
+            ctx
+          }),
           next: inner,
           input: i,
           // Overwritten by the chain item's own closure with the owning
@@ -2337,6 +2657,18 @@ function buildMethodEntries(descriptors, context, states) {
       return next(input);
     };
     const sdk = { context };
+    const methodAnnotator = descriptor.annotator;
+    const boundAnnotator = methodAnnotator ? (input) => methodAnnotator({ input }) : void 0;
+    const outputPolicy = () => {
+      const core = resolveCoreOptions(context);
+      return {
+        outputSchema: descriptor.meta?.outputSchema,
+        skipOutputValidation: descriptor.skipOutputValidation,
+        includeOutputValidationDroppedPaths: core?.includeOutputValidationDroppedPaths,
+        methodName: descriptor.name,
+        adaptError: core?.adaptError
+      };
+    };
     if (out.type === "list") {
       entry.value = createPaginatedFunction(
         fold(callRun),
@@ -2346,17 +2678,23 @@ function buildMethodEntries(descriptors, context, states) {
           name: descriptor.name,
           defaultPageSize: out.defaultPageSize,
           adaptPage: out.adaptPage,
+          annotator: boundAnnotator,
+          // Validate + strip each item against the item `outputSchema`
+          // (item mode's sibling); dropped paths surface as `[].x` in the page's
+          // `meta`, unioned across items.
+          finalizePage: (page) => applyListOutputPolicy(page, outputPolicy()),
           getDeprecation: () => entry.meta?.deprecation
         }
       );
     } else if (out.type === "item") {
-      const itemCore = async (input, ctx) => callRun(input, ctx);
+      const itemCore = async (input, ctx) => applyItemOutputPolicy(await callRun(input, ctx), outputPolicy());
       entry.value = createFunction(
         fold(itemCore),
         {
           sdk,
           schema: descriptor.inputSchema,
           name: descriptor.name,
+          annotator: boundAnnotator,
           getDeprecation: () => entry.meta?.deprecation
         }
       );
@@ -2368,6 +2706,7 @@ function buildMethodEntries(descriptors, context, states) {
           name: descriptor.name,
           schema: descriptor.skipInputValidation ? void 0 : descriptor.inputSchema,
           positional: descriptor.positional,
+          annotator: boundAnnotator,
           // The boundary reads the deprecation LIVE off the entry, so a
           // deprecation merged after build (defineMethodOverride, addPlugin)
           // fires too.
@@ -2388,12 +2727,22 @@ function buildMethodEntries(descriptors, context, states) {
       const internalValue = (...args) => canonicalValue(pack(args), INTERNAL_CALL);
       entry.value = (...args) => canonicalValue(pack(args));
       entry.internalValue = internalValue;
-      entry.bindInternal = (ctx) => ctx ? (...args) => canonicalValue(pack(args), childCallContext(ctx)) : internalValue;
+      entry.bindInternal = (opts) => bindInternalTwin({
+        ...opts,
+        withContext: (context2) => {
+          return (...args) => canonicalValue(pack(args), context2);
+        },
+        internalValue
+      });
       entry.positional = names;
     } else {
       const internalValue = (input) => canonicalValue(input, INTERNAL_CALL);
       entry.internalValue = internalValue;
-      entry.bindInternal = (ctx) => ctx ? (input) => canonicalValue(input, childCallContext(ctx)) : internalValue;
+      entry.bindInternal = (opts) => bindInternalTwin({
+        ...opts,
+        withContext: (context2) => (input) => canonicalValue(input, context2),
+        internalValue
+      });
     }
     plugins[id] = entry;
   }
@@ -2419,8 +2768,14 @@ function buildEagerArtifacts(descriptors, context, states) {
       if (!dispose) return;
       context.disposers?.push({
         id,
+        // Teardown is framework-internal: an SDK method a `dispose` calls runs
+        // on an internal-origin root (dropped from telemetry).
         dispose: (input) => dispose({
-          imports: buildImports(plugins, descriptor.importBindings),
+          imports: buildImports({
+            plugins,
+            importBindings: descriptor.importBindings,
+            frameworkOrigin: true
+          }),
           state: states.get(id),
           input
         })
@@ -2430,7 +2785,10 @@ function buildEagerArtifacts(descriptors, context, states) {
       states.set(
         id,
         descriptor.setup ? descriptor.setup({
-          imports: buildImports(plugins, descriptor.importBindings)
+          imports: buildImports({
+            plugins,
+            importBindings: descriptor.importBindings
+          })
         }) : void 0
       );
       recordDisposer();
@@ -2442,14 +2800,20 @@ function buildEagerArtifacts(descriptors, context, states) {
       states.set(
         id,
         descriptor.setup ? descriptor.setup({
-          imports: buildImports(plugins, descriptor.importBindings)
+          imports: buildImports({
+            plugins,
+            importBindings: descriptor.importBindings
+          })
         }) : void 0
       );
     } else {
       states.set(
         id,
         descriptor.setup ? descriptor.setup({
-          imports: buildImports(plugins, descriptor.importBindings)
+          imports: buildImports({
+            plugins,
+            importBindings: descriptor.importBindings
+          })
         }) : void 0
       );
       if (descriptor.privileged) {
@@ -2467,7 +2831,7 @@ function buildEagerArtifacts(descriptors, context, states) {
           pluginType: "property",
           name: descriptor.name,
           getValue: () => get({
-            imports: buildImports(plugins, importBindings),
+            imports: buildImports({ plugins, importBindings }),
             state: states.get(id)
           }),
           meta: descriptor.meta,
@@ -2503,7 +2867,7 @@ function resolvePlugin(sdk, ref) {
     return entry.getValue();
   }
   if (entry.pluginType === "method" && entry.internalValue) {
-    return entry.internalValue;
+    return entry.bindInternal?.({ frameworkOrigin: true }) ?? entry.internalValue;
   }
   return entry.value;
 }
@@ -2538,7 +2902,7 @@ function resolveAggregates(descriptors, context) {
     if (descriptor.pluginType !== "aggregate") continue;
     const exports = {};
     for (const [binding, child] of Object.entries(descriptor.exports)) {
-      bindValue(exports, binding, plugins[child.id]);
+      bindValue({ target: exports, key: binding, entry: plugins[child.id] });
     }
     plugins[id] = { pluginType: "aggregate", name: descriptor.name, exports };
   }
@@ -2581,23 +2945,39 @@ function assembleHooks(descriptors, context, states) {
   const plugins = context.plugins;
   for (const id of topoOrder(descriptors)) {
     const descriptor = descriptors.get(id);
-    if (!descriptor || descriptor.pluginType !== "hook" || !descriptor.observe) {
+    if (!descriptor || descriptor.pluginType !== "hook" || !descriptor.observe && !descriptor.annotator) {
       continue;
     }
-    const { observe } = descriptor;
-    const imports = buildImports(plugins, descriptor.importBindings);
+    const { observe, annotator } = descriptor;
     const state = states.get(id);
     const contributed = {};
-    if (observe.onMethodStart) {
-      const onStart = observe.onMethodStart;
-      contributed.onMethodStart = (input) => {
-        runIsolatedObserver(() => onStart({ imports, input, state }));
-      };
+    if (observe?.onMethodStart || observe?.onMethodEnd) {
+      const imports = buildImports({
+        plugins,
+        importBindings: descriptor.importBindings,
+        frameworkOrigin: true
+      });
+      if (observe.onMethodStart) {
+        const onStart = observe.onMethodStart;
+        contributed.onMethodStart = (input) => {
+          runIsolatedObserver(() => onStart({ imports, input, state }));
+        };
+      }
+      if (observe.onMethodEnd) {
+        const onEnd = observe.onMethodEnd;
+        contributed.onMethodEnd = (input) => {
+          runIsolatedObserver(() => onEnd({ imports, input, state }));
+        };
+      }
     }
-    if (observe.onMethodEnd) {
-      const onEnd = observe.onMethodEnd;
-      contributed.onMethodEnd = (input) => {
-        runIsolatedObserver(() => onEnd({ imports, input, state }));
+    if (annotator) {
+      const annotatorFn = annotator;
+      contributed.annotator = ({ methodName, input }) => {
+        try {
+          return annotatorFn({ methodName, input, state });
+        } catch {
+          return {};
+        }
       };
     }
     context.hooks = buildHooks(context.hooks, contributed);
@@ -2631,7 +3011,11 @@ function createSdk(root, options) {
       pluginSurface = plugins2[plugin.id].exports;
     } else {
       pluginSurface = {};
-      bindValue(pluginSurface, plugin.name, plugins2[plugin.id]);
+      bindValue({
+        target: pluginSurface,
+        key: plugin.name,
+        entry: plugins2[plugin.id]
+      });
     }
     for (const key of Object.keys(legacyExports)) context.surface[key] = key;
     if (plugin.pluginType === "aggregate") {
@@ -2648,7 +3032,7 @@ function createSdk(root, options) {
   if (root.pluginType === "method" || root.pluginType === "property") {
     context.surface[root.name] = root.id;
     const sdk = buildSurface(context);
-    bindValue(sdk, root.name, plugins[root.id]);
+    bindValue({ target: sdk, key: root.name, entry: plugins[root.id] });
     return sdk;
   }
   if (root.pluginType === "aggregate")
@@ -2680,7 +3064,7 @@ function addModelPlugin(sdk, plugin, options = {}) {
       context.surface[binding] = child.id;
     }
   } else {
-    bindValue(sdk, plugin.name, entry);
+    bindValue({ target: sdk, key: plugin.name, entry });
     context.surface[plugin.name] = plugin.id;
   }
 }
@@ -4019,7 +4403,9 @@ export {
   createSdk,
   createValidator,
   dangerousContextPlugin,
+  declareDefault,
   declareMethod,
+  declareOptionalMethod,
   declareOptionalProperty,
   declarePlugin,
   declareProperty,