@zapier/kitcore 0.16.0 → 0.17.0

package/dist/index.cjs

@@ -70,6 +70,7 @@ __export(index_exports, {
   defineLegacyMerge: () => defineLegacyMerge,
   defineMethod: () => defineMethod,
   defineMethodOverride: () => defineMethodOverride,
+  defineOverride: () => defineOverride,
   definePlugin: () => definePlugin,
   defineProperty: () => defineProperty,
   defineResolver: () => defineResolver,
@@ -85,6 +86,7 @@ __export(index_exports, {
   getFieldDescriptions: () => getFieldDescriptions,
   getNegatable: () => getNegatable,
   getOutputSchema: () => getOutputSchema,
+  getRegistry: () => getRegistry,
   getRegistryPlugin: () => getRegistryPlugin,
   getSchemaDescription: () => getSchemaDescription,
   initializeHttpRequestPlugin: () => initializeHttpRequestPlugin,
@@ -96,6 +98,7 @@ __export(index_exports, {
   isTelemetryNested: () => isTelemetryNested,
   normalizeConnectionPlugin: () => normalizeConnectionPlugin,
   normalizeStability: () => normalizeStability,
+  objectShapeOf: () => objectShapeOf,
   omitExports: () => omitExports,
   openEnum: () => openEnum,
   paginate: () => paginate,
@@ -117,6 +120,7 @@ __export(index_exports, {
   toIterable: () => toIterable,
   toSnakeCase: () => toSnakeCase,
   toTitleCase: () => toTitleCase,
+  unwrapSchema: () => unwrapSchema,
   validateOptions: () => validateOptions,
   withOutputSchema: () => withOutputSchema,
   withPositional: () => withPositional,
@@ -155,6 +159,30 @@ function canonicalInputSchema(schema) {
   }
   return schema;
 }
+function unwrapSchema(schema) {
+  let inner = schema;
+  let required = true;
+  for (; ; ) {
+    if (inner instanceof import_zod.z.ZodOptional || inner instanceof import_zod.z.ZodDefault) {
+      required = false;
+      inner = inner.unwrap();
+    } else if (inner instanceof import_zod.z.ZodNullable) {
+      inner = inner.unwrap();
+    } else {
+      break;
+    }
+  }
+  return { inner, required };
+}
+function objectShapeOf(schema) {
+  const canonical = canonicalInputSchema(schema);
+  if (!canonical) return void 0;
+  const { inner } = unwrapSchema(canonical);
+  if (inner instanceof import_zod.z.ZodObject) {
+    return inner.shape;
+  }
+  return void 0;
+}
 function getOutputSchema(inputSchema) {
   return inputSchema._zod.def.outputSchema;
 }
@@ -775,6 +803,120 @@ function createValidator(schema, { adaptError } = {}) {
 }
 var validateOptions = (schema, options, { adaptError } = {}) => parseOrThrow(schema, options, { adaptError });
 
+// src/utils/call-options.ts
+var import_zod2 = require("zod");
+var CallFrameworkOptionsSchema = import_zod2.z.object({
+  /** Page to fetch. Opaque to kitcore: the head's API defines the format. */
+  cursor: import_zod2.z.string().optional(),
+  /** Items per page. */
+  pageSize: import_zod2.z.number().int().min(1).optional(),
+  /** Stop after this many items, across pages. */
+  maxItems: import_zod2.z.number().int().min(0).optional(),
+  /** Bypass output validation for this one call. */
+  skipOutputDataValidation: import_zod2.z.boolean().optional()
+});
+var ITEM_FRAMEWORK_OPTIONS = {
+  claims: ["skipOutputDataValidation"],
+  injects: []
+};
+var LIST_FRAMEWORK_OPTIONS = {
+  claims: ["cursor", "pageSize", "maxItems", "skipOutputDataValidation"],
+  injects: ["cursor", "pageSize"]
+};
+var PAGE_FRAMEWORK_OPTIONS = {
+  claims: ["cursor", "pageSize", "maxItems"],
+  injects: ["cursor", "pageSize", "maxItems"]
+};
+var NO_FRAMEWORK_OPTIONS = {
+  claims: [],
+  injects: []
+};
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function strictlyRefused(error, claims) {
+  const refused = /* @__PURE__ */ new Set();
+  for (const issue of error.issues) {
+    if (issue.code !== "unrecognized_keys" || issue.path.length > 0) continue;
+    for (const key of issue.keys) {
+      if (claims.includes(key)) refused.add(key);
+    }
+  }
+  return [...refused];
+}
+function withoutKeys(options, keys) {
+  const next = {};
+  for (const [key, value] of Object.entries(options)) {
+    if (!keys.includes(key)) next[key] = value;
+  }
+  return next;
+}
+function parseCallOptions(options, {
+  schema,
+  policy = NO_FRAMEWORK_OPTIONS,
+  adaptError
+} = {}) {
+  const claims = policy.claims;
+  const call = isRecord(options) ? options : void 0;
+  let framework = {};
+  if (call && claims.length > 0) {
+    const present = {};
+    for (const key of claims) {
+      if (key in call) present[key] = call[key];
+    }
+    framework = parseOrThrow2(CallFrameworkOptionsSchema, present, adaptError);
+  }
+  if (!schema) return { framework, domain: options, supplied: /* @__PURE__ */ new Set() };
+  const first = schema.safeParse(options);
+  if (first.success) {
+    return { framework, domain: first.data, supplied: /* @__PURE__ */ new Set() };
+  }
+  const refused = call ? strictlyRefused(first.error, claims) : [];
+  if (refused.length === 0) throw toCoreError(first.error, options, adaptError);
+  const retry = schema.safeParse(withoutKeys(call, refused));
+  if (!retry.success) {
+    throw toCoreError(retry.error, options, adaptError);
+  }
+  return { framework, domain: retry.data, supplied: new Set(refused) };
+}
+function mergeCallOptions({
+  framework,
+  domain
+}) {
+  const claimed = Object.entries(framework);
+  if (!isRecord(domain) || claimed.length === 0) return domain;
+  return { ...domain, ...Object.fromEntries(claimed) };
+}
+function withheldFromRun(policy) {
+  return new Set(policy.claims.filter((key) => !policy.injects.includes(key)));
+}
+function stripFrameworkOnlyOptions(options, withheld) {
+  if (withheld.size === 0 || !isRecord(options)) return options;
+  const entries = Object.entries(options);
+  if (!entries.some(([key]) => withheld.has(key))) return options;
+  return Object.fromEntries(entries.filter(([key]) => !withheld.has(key)));
+}
+function parseOrThrow2(schema, input, adaptError) {
+  const result = schema.safeParse(input);
+  if (result.success) return result.data;
+  throw toCoreError(result.error, input, adaptError);
+}
+function toCoreError(error, input, adaptError) {
+  const messages = error.issues.map((issue) => {
+    const path = issue.path.length > 0 ? issue.path.join(".") : "input";
+    return `${path}: ${issue.message}`;
+  });
+  return createCoreError(
+    {
+      code: CoreErrorCode.Validation,
+      message: `Validation failed:
+  ${messages.join("\n  ")}`,
+      details: { zodErrors: error.issues, input }
+    },
+    adaptError
+  );
+}
+
 // src/utils/async-context.ts
 var import_node_async_hooks = require("async_hooks");
 function createAsyncContext() {
@@ -972,7 +1114,15 @@ function normalizeError(error, adaptError) {
   );
 }
 function createFunction(coreFn, options) {
-  const { sdk, schema, name, annotator, getDeprecation, getStability } = options;
+  const {
+    sdk,
+    schema,
+    name,
+    annotator,
+    frameworkOptions,
+    getDeprecation,
+    getStability
+  } = options;
   const functionName = name || coreFn.name;
   const namedFunctions = {
     [functionName]: async function(callOptions) {
@@ -1008,25 +1158,15 @@ function createFunction(coreFn, options) {
         };
         hooks?.onMethodStart?.({ ...hookBase });
         try {
-          let result;
-          if (schema) {
-            const validatedOptions = validateOptions(
-              schema,
-              normalizedOptions,
-              {
-                adaptError
-              }
-            );
-            result = await coreFn(
-              {
-                ...normalizedOptions,
-                ...validatedOptions
-              },
-              context
-            );
-          } else {
-            result = await coreFn(normalizedOptions, context);
-          }
+          const parsed = parseCallOptions(normalizedOptions, {
+            schema,
+            policy: frameworkOptions,
+            adaptError
+          });
+          const result = await coreFn(
+            mergeCallOptions(parsed),
+            context
+          );
           hooks?.onMethodEnd?.({
             ...hookBase,
             durationMs: Date.now() - startTime
@@ -1147,7 +1287,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 finalizePage ? finalizePage(page) : page;
+        return finalizePage ? finalizePage(page, options) : page;
       } catch (error) {
         throw normalizeError(
           error,
@@ -1167,6 +1307,7 @@ function createPaginatedFunction(coreFn, options) {
     adaptPage,
     annotator,
     finalizePage,
+    frameworkOptions,
     getDeprecation,
     getStability
   } = options;
@@ -1210,10 +1351,13 @@ function createPaginatedFunction(coreFn, options) {
         };
         hooks?.onMethodStart?.({ ...hookBase });
         try {
-          const validatedOptions = {
-            ...normalizedOptions,
-            ...schema ? createValidator(schema, { adaptError })(normalizedOptions) : normalizedOptions
-          };
+          const validatedOptions = mergeCallOptions(
+            parseCallOptions(normalizedOptions, {
+              schema,
+              policy: frameworkOptions,
+              adaptError
+            })
+          );
           const pageSize = validatedOptions.pageSize ?? defaultPageSize;
           const optimizedOptions = {
             ...validatedOptions,
@@ -1339,6 +1483,10 @@ function createPaginatedPluginMethod(sdk, config) {
     sdk,
     schema: inputSchema,
     name,
+    // The page loop reads the page controls out of the call object, so a
+    // handler's schema does not have to declare them. It reads nothing else:
+    // no legacy handler honors the caller's output skip.
+    frameworkOptions: PAGE_FRAMEWORK_OPTIONS,
     defaultPageSize,
     adaptPage
   });
@@ -1582,6 +1730,7 @@ function buildPluginStack(head, callerLabel) {
 }
 
 // src/model/shared.ts
+var CONTEXT = Symbol.for("kitcore.context");
 function parseId(id) {
   const at = id.lastIndexOf("/");
   return at === -1 ? { name: id, namespace: void 0 } : { name: id.slice(at + 1), namespace: id.slice(0, at) };
@@ -1691,7 +1840,12 @@ function collectDynamicMembers(members) {
     };
   });
 }
-function defineMethod(config) {
+function defineMethod(configOrRef, refConfig) {
+  const config = refConfig === void 0 ? configOrRef : {
+    ...refConfig,
+    name: configOrRef.name,
+    namespace: configOrRef.namespace
+  };
   const deps = normalizeImports(config.imports);
   return {
     pluginType: "method",
@@ -1714,8 +1868,27 @@ function defineMethod(config) {
     run: config.run
   };
 }
-function defineMethodOverride(config) {
-  const { target, namespace, ...rest } = config;
+var OVERRIDABLE = [
+  "description",
+  "categories",
+  "itemType",
+  "returnType",
+  "packages",
+  "experimental",
+  "deprecation",
+  "supportsJsonOutput"
+];
+function assertOverridable(target, fields) {
+  const offered = Object.keys(fields).filter(
+    (key) => !OVERRIDABLE.includes(key)
+  );
+  if (offered.length === 0) return;
+  throw new Error(
+    `defineOverride("${target}"): cannot override ${offered.join(", ")}. An override changes how a surface presents a method, never what it does. The method's declared type is fixed at \`defineMethod\` and nothing re-checks it afterwards, so patching behavior here would let a call fail against a contract its own return type says it satisfies. Overridable: ${OVERRIDABLE.join(", ")}.`
+  );
+}
+function buildOverride(target, namespace, fields) {
+  assertOverridable(target, fields);
   return {
     pluginType: "method-override",
     name: `override:${target}`,
@@ -1723,12 +1896,34 @@ function defineMethodOverride(config) {
     target,
     imports: [],
     importBindings: [],
-    meta: collectLeafMeta(rest)
+    meta: collectLeafMeta(fields)
   };
 }
+function defineOverride(ref, config = {}) {
+  const { namespace, ...fields } = config;
+  return buildOverride(ref.id, namespace, fields);
+}
+function defineMethodOverride(config) {
+  logDeprecation(
+    "defineMethodOverride({ target }) is deprecated. Use defineOverride(method, { ... }), which takes the method or its declareMethod stand-in."
+  );
+  const { target, namespace, ...fields } = config;
+  return buildOverride(target, namespace, fields);
+}
+function assertRequirementPaths(requirements) {
+  if (!requirements) return;
+  for (const requirement of requirements) {
+    if (typeof requirement !== "string" && requirement.length === 0) {
+      throw new Error(
+        "defineResolver: a requireParameters path must name at least one segment. An empty path names no parameter, and the engine would read it as already satisfied."
+      );
+    }
+  }
+}
 function defineResolver(config) {
   const deps = normalizeImports(config.imports);
   const base = { imports: deps.plugins, importBindings: deps.bindings };
+  assertRequirementPaths(config.requireParameters);
   const gates = {
     requireParameters: config.requireParameters
   };
@@ -1832,21 +2027,26 @@ function declareOptionalMethod(config) {
     // `| undefined`.
   };
 }
-function defineProperty(config) {
-  const deps = normalizeImports(config.imports);
+function defineProperty(config, refConfig) {
+  const cfg = refConfig === void 0 ? config : {
+    ...refConfig,
+    name: config.name,
+    namespace: config.namespace
+  };
+  const deps = normalizeImports(cfg.imports);
   return {
     pluginType: "property",
-    name: config.name,
-    namespace: config.namespace,
-    id: makeId(config.name, config.namespace),
+    name: cfg.name,
+    namespace: cfg.namespace,
+    id: makeId(cfg.name, cfg.namespace),
     imports: deps.plugins,
     importBindings: deps.bindings,
-    setup: config.setup,
-    dispose: config.dispose,
-    value: config.value,
-    get: config.get,
-    meta: collectLeafMeta(config),
-    dynamicMembers: collectDynamicMembers(config.dynamicMembers)
+    setup: cfg.setup,
+    dispose: cfg.dispose,
+    value: cfg.value,
+    get: cfg.get,
+    meta: collectLeafMeta(cfg),
+    dynamicMembers: collectDynamicMembers(cfg.dynamicMembers)
   };
 }
 function declareProperty(config) {
@@ -2072,7 +2272,7 @@ function legacyGraphEntry(name, value, pluginMeta) {
 }
 
 // src/model/builtins.ts
-var import_zod2 = require("zod");
+var import_zod3 = require("zod");
 
 // src/model/registry-support.ts
 function adaptLegacyFormatter(legacy, sdk) {
@@ -2150,6 +2350,34 @@ function collectSurfaceProjection(context, formatterSdk) {
   }
   return { meta, formatters, resolvers, positional, skipInputValidation };
 }
+var REGISTRY_CACHE = Symbol.for("kitcore.registryCache");
+function freezeContainers(registry) {
+  Object.freeze(registry.functions);
+  for (const category of registry.categories) {
+    Object.freeze(category.functions);
+    Object.freeze(category);
+  }
+  Object.freeze(registry.categories);
+  return Object.freeze(registry);
+}
+function getCachedRegistry(context, packageFilter) {
+  const key = packageFilter ?? "";
+  const caching = context;
+  let byFilter = caching[REGISTRY_CACHE];
+  if (!byFilter) {
+    byFilter = /* @__PURE__ */ new Map();
+    caching[REGISTRY_CACHE] = byFilter;
+  }
+  let registry = byFilter.get(key);
+  if (!registry) {
+    registry = freezeContainers(buildSurfaceRegistry(context, packageFilter));
+    byFilter.set(key, registry);
+  }
+  return registry;
+}
+function invalidateRegistryCache(context) {
+  delete context[REGISTRY_CACHE];
+}
 function buildSurfaceRegistry(context, packageFilter) {
   const surface = {};
   for (const [binding, id] of Object.entries(context.surface)) {
@@ -2157,9 +2385,11 @@ function buildSurfaceRegistry(context, packageFilter) {
     if (!entry || entry.pluginType === "aggregate") continue;
     surface[binding] = entry.pluginType === "property" && entry.getValue ? entry.getValue() : entry.value;
   }
+  const projection = collectSurfaceProjection(context, surface);
+  Object.assign(projection.meta, context.meta);
   return buildRegistry({
     sdk: surface,
-    ...collectSurfaceProjection(context, surface),
+    ...projection,
     packageFilter
   });
 }
@@ -2179,12 +2409,12 @@ var getRegistryPlugin = defineMethod({
   name: "getRegistry",
   namespace: "kitcore",
   imports: [dangerousContextPlugin],
-  inputSchema: import_zod2.z.object({ package: import_zod2.z.string().optional() }).optional(),
-  run: ({ imports, input }) => buildSurfaceRegistry(imports.context, input?.package)
+  inputSchema: import_zod3.z.object({ package: import_zod3.z.string().optional() }).optional(),
+  run: ({ imports, input }) => getCachedRegistry(imports.context, input?.package)
 });
 
 // src/utils/output-policy.ts
-function isRecord(value) {
+function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function diffDroppedPaths(raw, parsed, prefix = "") {
@@ -2207,7 +2437,7 @@ function walkDroppedPaths(raw, parsed, prefix, out) {
     }
     return;
   }
-  if (isRecord(raw) && isRecord(parsed)) {
+  if (isRecord2(raw) && isRecord2(parsed)) {
     for (const key of Object.keys(raw)) {
       const path = prefix ? `${prefix}.${key}` : key;
       if (!(key in parsed)) {
@@ -2219,7 +2449,22 @@ function walkDroppedPaths(raw, parsed, prefix, out) {
     return;
   }
 }
-function parseOutput(schema, value, policy, locator) {
+var SKIP_OUTPUT_DATA_VALIDATION = "skipOutputDataValidation";
+function readSkipOutputDataValidation(options) {
+  return isRecord2(options) && options[SKIP_OUTPUT_DATA_VALIDATION] === true;
+}
+function resolveValidatingSchema(policy) {
+  if (policy.skipOutputValidation || policy.skippedByCaller) return void 0;
+  return policy.outputSchema;
+}
+function shouldReport(policy) {
+  return policy.skippedByCaller === true && policy.outputSchema !== void 0 && !policy.skipOutputValidation;
+}
+function parseOutput(schema, value, policy, {
+  locator,
+  hint,
+  callerCanSkip = true
+} = {}) {
   const result = schema.safeParse(value);
   if (result.success) return result.data;
   const issues = result.error.issues.map((issue) => {
@@ -2234,43 +2479,91 @@ function parseOutput(schema, value, policy, locator) {
       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.`,
+` + (hint ? `${hint}
+
+` : "") + `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.` + (callerCanSkip ? ` A caller who cannot change the method can pass \`skipOutputDataValidation: true\` with the input to bypass this one call.` : ``),
       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 schema = resolveValidatingSchema(policy);
+  const report = shouldReport(policy);
+  if (!schema && !report) return result;
+  if (!isRecord2(result) || !("data" in result)) return result;
+  if (!schema) {
+    return {
+      ...result,
+      meta: withOutputValidation(result.meta, { skipped: true })
+    };
+  }
   const data = parseOutput(schema, result.data, policy);
+  const validation = buildValidatedReport({
+    policy,
+    before: result.data,
+    after: data
+  });
   const next = { ...result, data };
-  if (policy.includeOutputValidationDroppedPaths) {
-    const droppedPaths = diffDroppedPaths(result.data, data);
-    if (droppedPaths.length > 0) {
-      next.meta = withOutputValidation(result.meta, droppedPaths);
-    }
-  }
+  if (validation) next.meta = withOutputValidation(result.meta, validation);
   return next;
 }
-function withOutputValidation(existing, droppedPaths) {
-  const base = isRecord(existing) ? existing : {};
-  return { ...base, outputValidation: { droppedPaths } };
+function applyRawOutputPolicy(result, policy) {
+  const schema = resolveValidatingSchema(policy);
+  if (!schema) return result;
+  const looksLikeEnvelope = isRecord2(result) && "data" in result;
+  parseOutput(schema, result, policy, {
+    hint: looksLikeEnvelope ? 'This returned a `{ data }` envelope, and with no `output` mode the schema is matched against the WHOLE return. Did you mean `output: "item"` (or `"list"`)?' : void 0,
+    // Raw reserves nothing in the caller's call object, so there is no per-call
+    // skip to point at. Offering one would be advice that does nothing.
+    callerCanSkip: false
+  });
+  return result;
+}
+function withOutputValidation(existing, outputDataValidation) {
+  const base = isRecord2(existing) ? existing : {};
+  const deprecated = outputDataValidation.skipped === false && outputDataValidation.droppedPaths ? {
+    outputValidation: { droppedPaths: outputDataValidation.droppedPaths }
+  } : {};
+  return { ...base, outputDataValidation, ...deprecated };
+}
+function buildValidatedReport({
+  policy,
+  before,
+  after
+}) {
+  const droppedPaths = policy.includeOutputValidationDroppedPaths ? diffDroppedPaths(before, after) : [];
+  if (droppedPaths.length === 0) return void 0;
+  return {
+    skipped: false,
+    droppedPaths,
+    instruction: `Some fields were removed from \`data\` by output validation. To receive the raw, unvalidated result instead, set \`${SKIP_OUTPUT_DATA_VALIDATION}\`.`
+  };
 }
 function applyListOutputPolicy(page, policy) {
-  const schema = policy.outputSchema;
-  if (!schema || policy.skipOutputValidation) return page;
+  const schema = resolveValidatingSchema(policy);
+  const report = shouldReport(policy);
+  if (!schema && !report) return page;
+  if (!schema) {
+    return {
+      ...page,
+      meta: withOutputValidation(page.meta, { skipped: true })
+    };
+  }
   const data = page.data.map(
-    (item, index) => parseOutput(schema, item, policy, `data[${index}]`)
+    (item, index) => parseOutput(schema, item, policy, { locator: `data[${index}]` })
   );
+  const validation = buildValidatedReport({
+    policy,
+    before: page.data,
+    after: data
+  });
   const next = { ...page, data };
-  if (policy.includeOutputValidationDroppedPaths) {
-    const droppedPaths = diffDroppedPaths(page.data, data);
-    if (droppedPaths.length > 0) {
-      next.meta = { ...page.meta, outputValidation: { droppedPaths } };
-    }
-  }
+  if (validation)
+    next.meta = withOutputValidation(
+      page.meta,
+      validation
+    );
   return next;
 }
 
@@ -2278,15 +2571,44 @@ function applyListOutputPolicy(page, policy) {
 var FRAMEWORK_CONFIGURATION_IDS = /* @__PURE__ */ new Set([
   CORE_OPTIONS_ID
 ]);
+function isPromiseLike(value) {
+  return value !== null && typeof value === "object" && typeof value.then === "function";
+}
 function normalizeOutput(output) {
   if (output === void 0) return { type: "raw" };
   if (typeof output === "string") return { type: output };
   return output;
 }
-var CONTEXT = Symbol.for("kitcore.context");
 function getContext(sdk) {
   return sdk[CONTEXT];
 }
+function assertDynamicMemberRoot(entry) {
+  if (!entry.dynamicMembers?.length) return;
+  const value = entry.getValue ? entry.getValue() : entry.value;
+  if (typeof value === "object" && value !== null) return;
+  throw new Error(
+    `Property "${entry.name}" declares dynamicMembers, so its value must be an object when the SDK is built; got ${value === null ? "null" : typeof value}. Build the root in \`setup\` and return it from \`get\`, so members like "${entry.dynamicMembers[0].name}" are reportable from the first registry read.`
+  );
+}
+function getRegistry(sdk, packageFilter) {
+  if (typeof sdk !== "object" && typeof sdk !== "function" || sdk === null)
+    throw createNoRegistryError();
+  const context = getContext(sdk);
+  if (context?.surface) return getCachedRegistry(context, packageFilter);
+  const surfaced = sdk.getRegistry;
+  if (typeof surfaced === "function") {
+    return surfaced.call(
+      sdk,
+      packageFilter ? { package: packageFilter } : void 0
+    );
+  }
+  throw createNoRegistryError();
+}
+function createNoRegistryError() {
+  return new Error(
+    "getRegistry: sdk has no kitcore context and no surfaced getRegistry()."
+  );
+}
 function isResolverRef(value) {
   return "ref" in value;
 }
@@ -2792,23 +3114,17 @@ function runLegacyPass(descriptors, context) {
     Object.assign(context, contextRest);
     context.hooks = buildHooks(context.hooks, hooks);
     const exports2 = mirrorLegacyRootKeys(context, rootKeys, meta);
+    for (const name of Object.keys(rootKeys)) context.surface[name] = name;
     if (!("getRegistry" in exports2)) {
-      let getRegistry2 = function(options) {
-        const sdk = this ?? exports2;
-        const projection = collectSurfaceProjection(context, sdk);
-        Object.assign(projection.meta, context.meta);
-        return buildRegistry({
-          sdk,
-          ...projection,
-          packageFilter: options?.package
-        });
+      let getRegistry3 = function(options) {
+        return getCachedRegistry(context, options?.package);
       };
-      var getRegistry = getRegistry2;
-      exports2.getRegistry = getRegistry2;
+      var getRegistry2 = getRegistry3;
+      exports2.getRegistry = getRegistry3;
       plugins.getRegistry = {
         pluginType: "method",
         name: "getRegistry",
-        value: getRegistry2,
+        value: getRegistry3,
         chain: []
       };
     }
@@ -2872,50 +3188,73 @@ function buildMethodEntries(descriptors, context, states) {
     const sdk = { context };
     const methodAnnotator = descriptor.annotator;
     const boundAnnotator = methodAnnotator ? (input) => methodAnnotator({ input }) : void 0;
-    const outputPolicy = () => {
+    const outputPolicy = (callOptions) => {
       const core = resolveCoreOptions(context);
       return {
         outputSchema: descriptor.meta?.outputSchema,
         skipOutputValidation: descriptor.skipOutputValidation,
+        skippedByCaller: readSkipOutputDataValidation(callOptions),
         includeOutputValidationDroppedPaths: core?.includeOutputValidationDroppedPaths,
         methodName: descriptor.name,
         adaptError: core?.adaptError
       };
     };
+    const frameworkOptions = out.type === "list" ? LIST_FRAMEWORK_OPTIONS : ITEM_FRAMEWORK_OPTIONS;
+    const withheld = withheldFromRun(frameworkOptions);
     if (out.type === "list") {
       entry.value = createPaginatedFunction(
-        fold(callRun),
+        fold(
+          (input, ctx) => callRun(stripFrameworkOnlyOptions(input, withheld), ctx)
+        ),
         {
           sdk,
           schema: descriptor.inputSchema,
           name: descriptor.name,
+          frameworkOptions,
           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()),
+          finalizePage: (page, callOptions) => applyListOutputPolicy(page, outputPolicy(callOptions)),
           getDeprecation: () => entry.meta?.deprecation,
           getStability: () => entry.meta ? normalizeStability(entry.meta) : void 0
         }
       );
     } else if (out.type === "item") {
-      const itemCore = async (input, ctx) => applyItemOutputPolicy(await callRun(input, ctx), outputPolicy());
+      const itemCore = async (input, ctx) => applyItemOutputPolicy(
+        await callRun(stripFrameworkOnlyOptions(input, withheld), ctx),
+        outputPolicy(input)
+      );
       entry.value = createFunction(
         fold(itemCore),
         {
           sdk,
           schema: descriptor.inputSchema,
           name: descriptor.name,
+          frameworkOptions,
           annotator: boundAnnotator,
           getDeprecation: () => entry.meta?.deprecation,
           getStability: () => entry.meta ? normalizeStability(entry.meta) : void 0
         }
       );
     } else {
+      const rawValidates = descriptor.meta?.outputSchema !== void 0 && !descriptor.skipOutputValidation;
+      const validateRaw = (out2) => {
+        const policy = outputPolicy(void 0);
+        if (isPromiseLike(out2)) {
+          return Promise.resolve(out2).then(
+            (value) => applyRawOutputPolicy(value, policy)
+          );
+        }
+        return applyRawOutputPolicy(out2, policy);
+      };
       entry.value = createRawFunction(
-        (input, ctx) => fold(callRun)(input, ctx),
+        (input, ctx) => {
+          const out2 = fold(callRun)(input, ctx);
+          return rawValidates ? validateRaw(out2) : out2;
+        },
         {
           sdk,
           name: descriptor.name,
@@ -3068,6 +3407,7 @@ function buildEagerArtifacts(descriptors, context, states) {
           dynamicMembers: descriptor.dynamicMembers
         };
       }
+      assertDynamicMemberRoot(plugins[id]);
     }
     recordDisposer();
     building.delete(id);
@@ -3291,38 +3631,33 @@ function addModelPlugin(sdk, plugin, options = {}) {
   }
 }
 function addPlugin(sdk, plugin, options) {
-  if (typeof plugin === "function") {
-    const record = sdk;
-    const contribution = applyPluginToSdk(
-      record,
-      plugin,
-      options ?? {}
-    );
-    const context = record[CONTEXT];
-    if (context) {
-      mirrorLegacyRootKeys(context, contribution.rootKeys, contribution.meta);
-      for (const name of Object.keys(contribution.rootKeys)) {
-        context.surface[name] = name;
+  const record = sdk;
+  const context = getContext(record);
+  try {
+    if (typeof plugin === "function") {
+      const contribution = applyPluginToSdk(
+        record,
+        plugin,
+        options ?? {}
+      );
+      if (context) {
+        mirrorLegacyRootKeys(context, contribution.rootKeys, contribution.meta);
+        for (const name of Object.keys(contribution.rootKeys)) {
+          context.surface[name] = name;
+        }
       }
+    } else if (plugin.pluginType === "method-override") {
+      applyMethodOverride(context, plugin);
+    } else {
+      addModelPlugin(record, plugin, options ?? {});
     }
-    return;
-  }
-  if (plugin.pluginType === "method-override") {
-    applyMethodOverride(
-      getContext(sdk),
-      plugin
-    );
-    return;
+  } finally {
+    if (context) invalidateRegistryCache(context);
   }
-  addModelPlugin(
-    sdk,
-    plugin,
-    options ?? {}
-  );
 }
 
 // src/model/resolution/controller.ts
-var import_zod4 = require("zod");
+var import_zod5 = require("zod");
 
 // src/types/signals.ts
 var CORE_SIGNAL_SYMBOL = Symbol.for("kitcore.signal");
@@ -3355,55 +3690,33 @@ function isCoreCancelledSignal(value) {
 }
 
 // src/model/resolution/plan.ts
-var import_zod3 = require("zod");
-function unwrap(schema) {
-  let inner = schema;
-  let required = true;
-  for (; ; ) {
-    if (inner instanceof import_zod3.z.ZodOptional) {
-      required = false;
-      inner = inner._zod.def.innerType;
-    } else if (inner instanceof import_zod3.z.ZodDefault) {
-      required = false;
-      inner = inner._zod.def.innerType;
-    } else if (inner instanceof import_zod3.z.ZodNullable) {
-      inner = inner._zod.def.innerType;
-    } else {
-      break;
-    }
-  }
-  return { inner, required };
-}
+var import_zod4 = require("zod");
 function valueTypeOf(inner) {
-  if (inner instanceof import_zod3.z.ZodString) return "string";
-  if (inner instanceof import_zod3.z.ZodNumber) return "number";
-  if (inner instanceof import_zod3.z.ZodBoolean) return "boolean";
-  if (inner instanceof import_zod3.z.ZodEnum) return "string";
-  if (inner instanceof import_zod3.z.ZodArray) return "array";
-  if (inner instanceof import_zod3.z.ZodObject) return "object";
-  if (inner instanceof import_zod3.z.ZodRecord) return "object";
+  if (inner instanceof import_zod4.z.ZodString) return "string";
+  if (inner instanceof import_zod4.z.ZodNumber) return "number";
+  if (inner instanceof import_zod4.z.ZodBoolean) return "boolean";
+  if (inner instanceof import_zod4.z.ZodEnum) return "string";
+  if (inner instanceof import_zod4.z.ZodArray) return "array";
+  if (inner instanceof import_zod4.z.ZodObject) return "object";
+  if (inner instanceof import_zod4.z.ZodRecord) return "object";
   return void 0;
 }
 function staticChoicesOf(inner) {
-  if (inner instanceof import_zod3.z.ZodEnum) {
+  if (inner instanceof import_zod4.z.ZodEnum) {
     const values = inner.options;
     return values.map((value) => ({ label: value, value }));
   }
   return void 0;
 }
-function objectShape(schema) {
-  const canonical = canonicalInputSchema(schema);
-  const { inner } = canonical ? unwrap(canonical) : { inner: void 0 };
-  if (inner instanceof import_zod3.z.ZodObject) {
-    return inner.shape;
-  }
-  return void 0;
-}
 function topoOrder2(specs) {
   const byName = new Map(specs.map((s) => [s.name, s]));
   const placed = /* @__PURE__ */ new Set();
   const ordered = [];
-  const isReady = (spec) => spec.requires.every((r) => !byName.has(r) || placed.has(r));
+  const topLevelNameOf = (r) => typeof r === "string" ? r : r.length === 1 && typeof r[0] === "string" ? r[0] : void 0;
+  const isReady = (spec) => spec.requires.every((r) => {
+    const name = topLevelNameOf(r);
+    return name === void 0 || !byName.has(name) || placed.has(name);
+  });
   for (; ; ) {
     const next = specs.find((s) => !placed.has(s.name) && isReady(s));
     if (!next) break;
@@ -3414,7 +3727,7 @@ function topoOrder2(specs) {
   return ordered;
 }
 function planParameters(entry) {
-  const shape = objectShape(entry.inputSchema);
+  const shape = objectShapeOf(entry.inputSchema);
   const resolvers = entry.resolvers ?? {};
   const names = shape ? [
     ...Object.keys(shape),
@@ -3424,7 +3737,7 @@ function planParameters(entry) {
   ] : Object.keys(resolvers);
   const specs = names.map((name) => {
     const field = shape?.[name];
-    const { inner, required } = field ? unwrap(field) : { inner: void 0, required: false };
+    const { inner, required } = field ? unwrapSchema(field) : { inner: void 0, required: false };
     const resolver = resolvers[name];
     return {
       name,
@@ -4073,9 +4386,13 @@ async function findNext(ctx, state, path = []) {
   const hasAskableRequired = children.some((c) => c.required && asksUser(c));
   for (const leaf of ordered) {
     const childPath = [...path, leaf.name];
-    if (!leaf.requires.every(
-      (r) => container[r] !== void 0 || getAtPath(state.resolved, [r]) !== void 0 || isSettled(state, [...path, r]) || isSettled(state, [r])
-    )) {
+    if (!leaf.requires.every((r) => {
+      if (typeof r !== "string") {
+        if (getAtPath(state.resolved, [...r]) !== void 0) return true;
+        return r.some((_, index) => isSettled(state, r.slice(0, index + 1)));
+      }
+      return container[r] !== void 0 || getAtPath(state.resolved, [r]) !== void 0 || isSettled(state, [...path, r]) || isSettled(state, [r]);
+    })) {
       continue;
     }
     const inArrayItem = path.some((segment) => typeof segment === "number");
@@ -4479,7 +4796,7 @@ function positionAfter(pagination, action) {
 function toJsonSchema(schema) {
   if (!schema) return void 0;
   try {
-    return import_zod4.z.toJSONSchema(schema);
+    return import_zod5.z.toJSONSchema(schema);
   } catch {
     return void 0;
   }
@@ -4517,7 +4834,7 @@ function projectMethod(entry) {
 }
 function createController(sdk) {
   function entryFor(method) {
-    const entry = sdk.getRegistry().functions.find((f) => f.name === method);
+    const entry = getRegistry(sdk).functions.find((f) => f.name === method);
     if (!entry) throw new Error(`unknown method "${method}"`);
     return entry;
   }
@@ -4556,7 +4873,7 @@ function createController(sdk) {
     throw new Error(`invalid input for "${method}": ${detail}`);
   };
   const listMethods = () => ({
-    data: sdk.getRegistry().functions.map(projectSummary)
+    data: getRegistry(sdk).functions.map(projectSummary)
   });
   const getMethod = ({ method }) => ({
     data: projectMethod(entryFor(method))
@@ -4597,10 +4914,10 @@ function createCorePlugin(options) {
 }
 
 // src/transport/attempt-http-request.ts
-var import_zod9 = require("zod");
+var import_zod10 = require("zod");
 
 // src/transport/authorize-http-request.ts
-var import_zod5 = require("zod");
+var import_zod6 = require("zod");
 function describeUnclaimedConnection(connection) {
   const delimiterIndex = connection.indexOf(":");
   if (delimiterIndex === -1) {
@@ -4611,7 +4928,7 @@ function describeUnclaimedConnection(connection) {
 var authorizeHttpRequestPlugin = defineMethod({
   name: "authorizeHttpRequest",
   namespace: "kitcore",
-  inputSchema: import_zod5.z.custom(),
+  inputSchema: import_zod6.z.custom(),
   skipInputValidation: true,
   run: async ({ input }) => {
     const { connection } = input.request;
@@ -4626,7 +4943,7 @@ var authorizeHttpRequestPlugin = defineMethod({
 });
 
 // src/transport/dispatch-http-request.ts
-var import_zod6 = require("zod");
+var import_zod7 = require("zod");
 function toFetchInput(request) {
   const init = { ...request };
   const { url } = request;
@@ -4637,7 +4954,7 @@ function toFetchInput(request) {
 var dispatchHttpRequestPlugin = defineMethod({
   name: "dispatchHttpRequest",
   namespace: "kitcore",
-  inputSchema: import_zod6.z.custom(),
+  inputSchema: import_zod7.z.custom(),
   skipInputValidation: true,
   run: async ({ input }) => {
     const { url, init } = toFetchInput(input.request);
@@ -4646,21 +4963,21 @@ var dispatchHttpRequestPlugin = defineMethod({
 });
 
 // src/transport/prepare-http-request.ts
-var import_zod7 = require("zod");
+var import_zod8 = require("zod");
 var prepareHttpRequestPlugin = defineMethod({
   name: "prepareHttpRequest",
   namespace: "kitcore",
-  inputSchema: import_zod7.z.custom(),
+  inputSchema: import_zod8.z.custom(),
   skipInputValidation: true,
   run: async ({ input }) => input.request
 });
 
 // src/transport/receive-http-response.ts
-var import_zod8 = require("zod");
+var import_zod9 = require("zod");
 var receiveHttpResponsePlugin = defineMethod({
   name: "receiveHttpResponse",
   namespace: "kitcore",
-  inputSchema: import_zod8.z.custom(),
+  inputSchema: import_zod9.z.custom(),
   skipInputValidation: true,
   run: async ({ input }) => input.response
 });
@@ -4675,7 +4992,7 @@ var attemptHttpRequestPlugin = defineMethod({
     declareDefault({ plugin: dispatchHttpRequestPlugin }),
     declareDefault({ plugin: receiveHttpResponsePlugin })
   ],
-  inputSchema: import_zod9.z.custom(),
+  inputSchema: import_zod10.z.custom(),
   skipInputValidation: true,
   run: async ({ input, imports }) => {
     const { attempt } = input;
@@ -4700,7 +5017,7 @@ var attemptHttpRequestPlugin = defineMethod({
 });
 
 // src/transport/initialize-http-request.ts
-var import_zod10 = require("zod");
+var import_zod11 = require("zod");
 function isReplayableBody(body) {
   if (body == null || typeof body !== "object") return true;
   return typeof Blob !== "undefined" && body instanceof Blob || // File extends Blob
@@ -4712,7 +5029,7 @@ function withStringUrl(request) {
 var initializeHttpRequestPlugin = defineMethod({
   name: "initializeHttpRequest",
   namespace: "kitcore",
-  inputSchema: import_zod10.z.custom(),
+  inputSchema: import_zod11.z.custom(),
   skipInputValidation: true,
   run: async ({ input }) => {
     const request = withStringUrl(input.request);
@@ -4849,7 +5166,7 @@ function canRetry(attemptNumber, maxAttempts, replayable) {
 }
 
 // src/transport/send-http-request.ts
-var import_zod11 = require("zod");
+var import_zod12 = require("zod");
 function createOperationId() {
   return globalThis.crypto?.randomUUID?.() ?? `http-${Date.now()}`;
 }
@@ -4860,7 +5177,7 @@ var sendHttpRequestPlugin = defineMethod({
     declareDefault({ plugin: initializeHttpRequestPlugin }),
     declareDefault({ plugin: attemptHttpRequestPlugin })
   ],
-  inputSchema: import_zod11.z.custom(),
+  inputSchema: import_zod12.z.custom(),
   skipInputValidation: true,
   run: async ({ input, imports }) => {
     const start2 = {
@@ -4884,13 +5201,13 @@ var sendHttpRequestPlugin = defineMethod({
 });
 
 // src/transport/fetch.ts
-var import_zod12 = require("zod");
+var import_zod13 = require("zod");
 var fetchPlugin = defineMethod({
   name: "fetch",
   namespace: "kitcore",
   imports: [declareDefault({ plugin: sendHttpRequestPlugin })],
   positional: ["url", "init"],
-  inputSchema: import_zod12.z.custom(),
+  inputSchema: import_zod13.z.custom(),
   skipInputValidation: true,
   run: ({ input, imports }) => {
     const { url, init } = input;
@@ -4933,22 +5250,22 @@ function redactHttpRequest(request) {
 }
 
 // src/connections/default-connection-scheme.ts
-var import_zod13 = require("zod");
+var import_zod14 = require("zod");
 var defaultConnectionSchemePlugin = defineMethod({
   name: "defaultConnectionScheme",
   namespace: "kitcore",
-  inputSchema: import_zod13.z.custom(),
+  inputSchema: import_zod14.z.custom(),
   skipInputValidation: true,
   run: () => void 0
 });
 
 // src/connections/normalize-connection.ts
-var import_zod14 = require("zod");
+var import_zod15 = require("zod");
 var normalizeConnectionPlugin = defineMethod({
   name: "normalizeConnection",
   namespace: "kitcore",
   imports: [declareDefault({ plugin: defaultConnectionSchemePlugin })],
-  inputSchema: import_zod14.z.custom(),
+  inputSchema: import_zod15.z.custom(),
   skipInputValidation: true,
   run: ({ input, imports }) => {
     const { connection } = input;
@@ -4973,11 +5290,11 @@ var normalizeConnectionPlugin = defineMethod({
 });
 
 // src/connections/resolve-connection.ts
-var import_zod15 = require("zod");
+var import_zod16 = require("zod");
 var resolveConnectionPlugin = defineMethod({
   name: "resolveConnection",
   namespace: "kitcore",
-  inputSchema: import_zod15.z.custom(),
+  inputSchema: import_zod16.z.custom(),
   skipInputValidation: true,
   run: ({ input }) => input.connection
 });
@@ -5033,6 +5350,7 @@ var resolveConnectionPlugin = defineMethod({
   defineLegacyMerge,
   defineMethod,
   defineMethodOverride,
+  defineOverride,
   definePlugin,
   defineProperty,
   defineResolver,
@@ -5048,6 +5366,7 @@ var resolveConnectionPlugin = defineMethod({
   getFieldDescriptions,
   getNegatable,
   getOutputSchema,
+  getRegistry,
   getRegistryPlugin,
   getSchemaDescription,
   initializeHttpRequestPlugin,
@@ -5059,6 +5378,7 @@ var resolveConnectionPlugin = defineMethod({
   isTelemetryNested,
   normalizeConnectionPlugin,
   normalizeStability,
+  objectShapeOf,
   omitExports,
   openEnum,
   paginate,
@@ -5080,6 +5400,7 @@ var resolveConnectionPlugin = defineMethod({
   toIterable,
   toSnakeCase,
   toTitleCase,
+  unwrapSchema,
   validateOptions,
   withOutputSchema,
   withPositional,