@zapier/kitcore 0.4.0 → 0.5.1

package/dist/index.mjs

@@ -553,6 +553,19 @@ function isNestedMethodCall() {
   const store = scope.get();
   return store !== void 0 && store.depth > 0;
 }
+var observerReentrancy = 0;
+function runIsolatedObserver(fn) {
+  observerReentrancy++;
+  try {
+    fn();
+  } catch {
+  } finally {
+    observerReentrancy--;
+  }
+}
+function isInsideObserver() {
+  return observerReentrancy > 0;
+}
 function runInMethodScope(fn) {
   if (!scope.available) return fn();
   const currentDepth = scope.get()?.depth ?? -1;
@@ -561,7 +574,36 @@ function runInMethodScope(fn) {
 var runWithTelemetryContext = runInMethodScope;
 var isTelemetryNested = isNestedMethodCall;
 
+// src/utils/core-options.ts
+function defaultLogDeprecation({
+  methodName,
+  deprecation
+}) {
+  logDeprecation(`${methodName}() is deprecated. ${deprecation.message}`);
+}
+var CORE_OPTIONS_ID = "kitcore/coreOptions";
+
 // src/utils/function-utils.ts
+function resolveCoreOptions(context) {
+  const entry = context.plugins?.[CORE_OPTIONS_ID];
+  if (entry) {
+    return entry.getValue ? entry.getValue() : entry.value;
+  }
+  return context.core;
+}
+var INTERNAL_CALL = Symbol("kitcore.internalCall");
+function signalDeprecation(context, methodName, getDeprecation) {
+  if (isInsideObserver()) return;
+  const deprecation = getDeprecation?.();
+  if (!deprecation?.message) return;
+  const warning = {
+    type: "deprecation",
+    methodName,
+    deprecation
+  };
+  const handler = resolveCoreOptions(context)?.logDeprecation ?? defaultLogDeprecation;
+  runIsolatedObserver(() => handler(warning));
+}
 function normalizeError(error, adaptError) {
   if (error instanceof Error) return error;
   const message = typeof error === "object" && error !== null && "message" in error && typeof error.message === "string" ? error.message : String(error);
@@ -575,17 +617,20 @@ function normalizeError(error, adaptError) {
   );
 }
 function createFunction(coreFn, options) {
-  const { sdk, schema, name } = options;
+  const { sdk, schema, name, getDeprecation } = options;
   const functionName = name || coreFn.name;
   const namedFunctions = {
     [functionName]: async function(callOptions) {
+      if (arguments[1] !== INTERNAL_CALL) {
+        signalDeprecation(sdk.context, functionName, getDeprecation);
+      }
       return runInMethodScope(async () => {
         const startTime = Date.now();
         const normalizedOptions = callOptions ?? {};
         const args = [normalizedOptions];
         const depth = getCurrentDepth();
-        const hooks = sdk.context.hooks;
-        const adaptError = sdk.context.core?.adaptError;
+        const hooks = isInsideObserver() ? void 0 : sdk.context.hooks;
+        const adaptError = resolveCoreOptions(sdk.context)?.adaptError;
         hooks?.onMethodStart?.({
           methodName: functionName,
           args,
@@ -634,6 +679,62 @@ function createFunction(coreFn, options) {
   };
   return namedFunctions[functionName];
 }
+function createRawFunction(coreFn, options) {
+  const { sdk, name, schema, positional, getDeprecation } = options;
+  return function(rawInput) {
+    if (arguments[1] !== INTERNAL_CALL) {
+      signalDeprecation(sdk.context, name, getDeprecation);
+    }
+    return runInMethodScope(() => {
+      const startTime = Date.now();
+      const depth = getCurrentDepth();
+      const hooks = isInsideObserver() ? void 0 : sdk.context.hooks;
+      const adaptError = resolveCoreOptions(sdk.context)?.adaptError;
+      const input = schema ? rawInput ?? {} : rawInput;
+      const record = input;
+      const args = positional ? positional.filter((key2) => record?.[key2] !== void 0).map((key2) => record?.[key2]) : [input];
+      hooks?.onMethodStart?.({
+        methodName: name,
+        args,
+        isPaginated: false,
+        depth
+      });
+      const fireEnd = (error) => {
+        hooks?.onMethodEnd?.({
+          methodName: name,
+          args,
+          isPaginated: false,
+          depth,
+          durationMs: Date.now() - startTime,
+          ...error ? { error } : {}
+        });
+      };
+      try {
+        const parsed = schema ? validateOptions(schema, input, { adaptError }) : input;
+        const result = coreFn(parsed);
+        if (result !== null && typeof result === "object" && typeof result.then === "function") {
+          return result.then(
+            (value) => {
+              fireEnd();
+              return value;
+            },
+            (error) => {
+              fireEnd(
+                error instanceof Error ? error : new Error(String(error))
+              );
+              throw error;
+            }
+          );
+        }
+        fireEnd();
+        return result;
+      } catch (error) {
+        fireEnd(error instanceof Error ? error : new Error(String(error)));
+        throw error;
+      }
+    });
+  };
+}
 function isSdkPage(value) {
   if (typeof value !== "object" || value === null) return false;
   const page = value;
@@ -662,7 +763,7 @@ function createPageFunction(coreFn, {
       } catch (error) {
         throw normalizeError(
           error,
-          sdk.context.core?.adaptError
+          resolveCoreOptions(sdk.context)?.adaptError
         );
       }
     }
@@ -670,82 +771,98 @@ function createPageFunction(coreFn, {
   return namedFunctions[functionName];
 }
 function createPaginatedFunction(coreFn, options) {
-  const { sdk, schema, name, defaultPageSize, adaptPage } = options;
+  const { sdk, schema, name, defaultPageSize, adaptPage, getDeprecation } = options;
   const pageFunction = createPageFunction(coreFn, { sdk, adaptPage });
   const functionName = name || coreFn.name;
   const namedFunctions = {
     [functionName]: function(callOptions) {
+      if (arguments[1] !== INTERNAL_CALL) {
+        signalDeprecation(sdk.context, functionName, getDeprecation);
+      }
       return runInMethodScope(() => {
         const startTime = Date.now();
         const normalizedOptions = callOptions ?? {};
         const args = [normalizedOptions];
         const depth = getCurrentDepth();
-        const hooks = sdk.context.hooks;
-        const adaptError = sdk.context.core?.adaptError;
+        const hooks = isInsideObserver() ? void 0 : sdk.context.hooks;
+        const adaptError = resolveCoreOptions(sdk.context)?.adaptError;
         hooks?.onMethodStart?.({
           methodName: functionName,
           args,
           isPaginated: true,
           depth
         });
-        const validatedOptions = {
-          ...normalizedOptions,
-          ...schema ? createValidator(schema, { adaptError })(normalizedOptions) : normalizedOptions
-        };
-        const pageSize = validatedOptions.pageSize ?? defaultPageSize;
-        const optimizedOptions = {
-          ...validatedOptions,
-          pageSize
-        };
-        const iterator = paginate(pageFunction, optimizedOptions);
-        const firstPagePromise = iterator.next().then((result) => {
-          if (result.done) {
-            throw new Error("Paginate should always iterate at least once");
-          }
-          return result.value;
-        });
-        if (hooks?.onMethodEnd) {
-          firstPagePromise.then(() => {
-            hooks.onMethodEnd({
-              methodName: functionName,
-              args,
-              isPaginated: true,
-              depth,
-              durationMs: Date.now() - startTime
-            });
-          }).catch((error) => {
-            hooks.onMethodEnd({
-              methodName: functionName,
-              args,
-              isPaginated: true,
-              depth,
-              durationMs: Date.now() - startTime,
-              error: error instanceof Error ? error : new Error(String(error))
-            });
+        try {
+          const validatedOptions = {
+            ...normalizedOptions,
+            ...schema ? createValidator(schema, { adaptError })(normalizedOptions) : normalizedOptions
+          };
+          const pageSize = validatedOptions.pageSize ?? defaultPageSize;
+          const optimizedOptions = {
+            ...validatedOptions,
+            pageSize
+          };
+          const iterator = paginate(pageFunction, optimizedOptions);
+          const firstPagePromise = iterator.next().then((result) => {
+            if (result.done) {
+              throw new Error("Paginate should always iterate at least once");
+            }
+            return result.value;
           });
-        }
-        const pageStream = async function* () {
-          yield await firstPagePromise;
-          for await (const page of iterator) {
-            yield page;
+          if (hooks?.onMethodEnd) {
+            firstPagePromise.then(() => {
+              hooks.onMethodEnd({
+                methodName: functionName,
+                args,
+                isPaginated: true,
+                depth,
+                durationMs: Date.now() - startTime
+              });
+            }).catch((error) => {
+              hooks.onMethodEnd({
+                methodName: functionName,
+                args,
+                isPaginated: true,
+                depth,
+                durationMs: Date.now() - startTime,
+                error: error instanceof Error ? error : new Error(String(error))
+              });
+            });
           }
-        }();
-        return Object.assign(firstPagePromise, {
-          [Symbol.asyncIterator]() {
-            return pageStream;
-          },
-          items: function() {
-            return {
-              [Symbol.asyncIterator]: async function* () {
-                for await (const page of pageStream) {
-                  for (const item of page.data) {
-                    yield item;
+          const pageStream = async function* () {
+            yield await firstPagePromise;
+            for await (const page of iterator) {
+              yield page;
+            }
+          }();
+          return Object.assign(firstPagePromise, {
+            [Symbol.asyncIterator]() {
+              return pageStream;
+            },
+            items: function() {
+              return {
+                [Symbol.asyncIterator]: async function* () {
+                  for await (const page of pageStream) {
+                    for (const item of page.data) {
+                      yield item;
+                    }
                   }
                 }
-              }
-            };
-          }
-        });
+              };
+            }
+          });
+        } catch (error) {
+          const normalizedError = normalizeError(error, adaptError);
+          hooks?.onMethodEnd?.({
+            methodName: functionName,
+            args,
+            isPaginated: true,
+            depth,
+            durationMs: Date.now() - startTime,
+            error: normalizedError
+          });
+          throw normalizedError;
+        }
       });
     }
   };
@@ -754,6 +871,9 @@ function createPaginatedFunction(coreFn, options) {
 
 // src/utils/plugin-utils.ts
 function createPluginMethod(sdk, config) {
+  logDeprecation(
+    "createPluginMethod() is deprecated. Author methods with defineMethod instead."
+  );
   const { name, inputSchema, handler, ...metaFields } = config;
   const namedHandlers = {
     [name]: async function(options) {
@@ -777,6 +897,9 @@ function createPluginMethod(sdk, config) {
   };
 }
 function createPaginatedPluginMethod(sdk, config) {
+  logDeprecation(
+    'createPaginatedPluginMethod() is deprecated. Author list methods with defineMethod output "list" instead.'
+  );
   const {
     name,
     inputSchema,
@@ -1008,6 +1131,9 @@ function composePlugins(...plugins) {
   return collapseStackEntries(entries, "composePlugins");
 }
 function createPluginStack() {
+  logDeprecation(
+    "createPluginStack() is deprecated. Compose with definePlugin and build with createSdk instead."
+  );
   return buildPluginStack(null, "createPluginStack");
 }
 function buildPluginStack(head, callerLabel) {
@@ -1092,7 +1218,7 @@ function normalizeImports(deps) {
   if (!deps) return { plugins: [], bindings: [] };
   const seen = /* @__PURE__ */ new Map();
   const bindings = [];
-  const add = (binding, id) => {
+  const add = (binding, id, optional) => {
     const priorId = seen.get(binding);
     if (priorId !== void 0 && priorId !== id) {
       throw new Error(
@@ -1101,7 +1227,7 @@ function normalizeImports(deps) {
     }
     if (priorId === void 0) {
       seen.set(binding, id);
-      bindings.push({ binding, id });
+      bindings.push(optional ? { binding, id, optional } : { binding, id });
     }
   };
   for (const plugin of deps) {
@@ -1109,8 +1235,9 @@ function normalizeImports(deps) {
       for (const [binding, child] of Object.entries(plugin.exports)) {
         add(binding, child.id);
       }
+    } else if (plugin.pluginType === "hook") {
     } else {
-      add(plugin.name, plugin.id);
+      add(plugin.name, plugin.id, plugin.optional);
     }
   }
   return { plugins: deps, bindings };
@@ -1122,6 +1249,26 @@ function collectLeafMeta(config) {
   }
   return meta;
 }
+function formatDynamicMemberName(path) {
+  return path.map((seg) => typeof seg === "string" ? seg : `{${seg.param}}`).join(".");
+}
+function collectDynamicMembers(members) {
+  if (!members?.length) return void 0;
+  return members.map((member) => {
+    const root = member.path[0];
+    if (typeof root !== "string") {
+      throw new Error(
+        "defineProperty: a dynamicMember path must start with a literal segment (the owning binding), not a { param }."
+      );
+    }
+    const leaf = collectLeafMeta(member) ?? {};
+    return {
+      name: formatDynamicMemberName(member.path),
+      rootBinding: root,
+      meta: member.inputSchema ? { ...leaf, inputSchema: member.inputSchema } : leaf
+    };
+  });
+}
 function defineMethod(config) {
   const deps = normalizeImports(config.imports);
   return {
@@ -1132,15 +1279,29 @@ function defineMethod(config) {
     imports: deps.plugins,
     importBindings: deps.bindings,
     inputSchema: config.inputSchema,
+    skipInputValidation: config.skipInputValidation,
     meta: collectLeafMeta(config),
     resolvers: config.resolvers,
     formatter: config.formatter,
     output: config.output,
     positional: config.positional,
     setup: config.setup,
+    dispose: config.dispose,
     run: config.run
   };
 }
+function defineMethodOverride(config) {
+  const { target, namespace, ...rest } = config;
+  return {
+    pluginType: "method-override",
+    name: `override:${target}`,
+    id: namespace ? `${namespace}/override:${target}` : `override:${target}`,
+    target,
+    imports: [],
+    importBindings: [],
+    meta: collectLeafMeta(rest)
+  };
+}
 function defineResolver(config) {
   const deps = normalizeImports(config.imports);
   const base = { imports: deps.plugins, importBindings: deps.bindings };
@@ -1232,9 +1393,11 @@ function defineProperty(config) {
     imports: deps.plugins,
     importBindings: deps.bindings,
     setup: config.setup,
+    dispose: config.dispose,
     value: config.value,
     get: config.get,
-    meta: collectLeafMeta(config)
+    meta: collectLeafMeta(config),
+    dynamicMembers: collectDynamicMembers(config.dynamicMembers)
   };
 }
 function declareProperty(config) {
@@ -1249,6 +1412,37 @@ function declareProperty(config) {
     importBindings: []
   };
 }
+function declareOptionalProperty(config) {
+  const { name, namespace } = parseId(config.id);
+  return {
+    pluginType: "property",
+    name,
+    namespace,
+    id: makeId(name, namespace),
+    standIn: true,
+    optional: true,
+    imports: [],
+    importBindings: []
+    // Requires nothing (phantom carrier `<never, never>`): a consumer that
+    // imports it still passes `createSdk`'s completeness check unprovided. The
+    // import binding is still typed `TValue | undefined` from the descriptor.
+  };
+}
+function defineHook(config) {
+  const deps = normalizeImports(config.imports);
+  return {
+    pluginType: "hook",
+    name: config.name,
+    namespace: config.namespace,
+    id: makeId(config.name, config.namespace),
+    imports: deps.plugins,
+    importBindings: deps.bindings,
+    setup: config.setup,
+    dispose: config.dispose,
+    wrap: config.wrap,
+    observe: config.observe
+  };
+}
 function declarePlugin(config) {
   const { name, namespace } = parseId(config.id);
   return {
@@ -1263,7 +1457,12 @@ function declarePlugin(config) {
   };
 }
 function definePlugin(fnOrConfig) {
-  if (typeof fnOrConfig === "function") return fnOrConfig;
+  if (typeof fnOrConfig === "function") {
+    logDeprecation(
+      "definePlugin(fn) (the function form) is deprecated. Author plugins with defineMethod/defineProperty/definePlugin({ ... }) instead."
+    );
+    return fnOrConfig;
+  }
   const config = fnOrConfig;
   const deps = normalizeImports(config.imports);
   return {
@@ -1271,12 +1470,24 @@ function definePlugin(fnOrConfig) {
     name: config.name,
     namespace: config.namespace,
     id: makeId(config.name, config.namespace, "aggregate"),
-    imports: deps.plugins,
+    // A re-export synthetic (`selectExports` / `omitExports`) is flattened by
+    // `normalizeExports` into bare bindings, which drops its own `imports:
+    // [source]`. That edge is how `omitExports` keeps an omitted (unbound) leaf
+    // materialized + addressable by id, so preserve every exported aggregate's
+    // imports as extra reachability edges here (bindings unaffected).
+    imports: [...deps.plugins, ...exportedAggregateImports(config.exports)],
     importBindings: deps.bindings,
-    exports: normalizeExports(config.exports),
-    middleware: config.middleware
+    exports: normalizeExports(config.exports)
   };
 }
+function exportedAggregateImports(exports) {
+  if (!exports) return [];
+  const out = [];
+  for (const element of exports) {
+    if (element.pluginType === "aggregate") out.push(...element.imports);
+  }
+  return out;
+}
 function normalizeExports(exports) {
   if (!exports) return {};
   const out = {};
@@ -1336,9 +1547,33 @@ function selectExports(source, ...specs) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
   };
 }
+function omitExports(source, omit) {
+  const omitSet = new Set(omit);
+  for (const name of omit) {
+    if (!(name in source.exports)) {
+      throw new Error(`omitExports: "${source.id}" has no export "${name}".`);
+    }
+  }
+  const kept = {};
+  for (const [binding, child] of Object.entries(source.exports)) {
+    if (!omitSet.has(binding)) kept[binding] = child;
+  }
+  return {
+    pluginType: "aggregate",
+    name: makeId(`omit`, source.name, "aggregate"),
+    id: `${source.id}#omit:${selectSeq++}`,
+    imports: [source],
+    importBindings: [],
+    exports: kept
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  };
+}
 
 // src/model/legacy.ts
 function fromFunctionPlugin(fn, config) {
+  logDeprecation(
+    "fromFunctionPlugin() is deprecated. Author plugins with defineMethod/definePlugin instead."
+  );
   return {
     pluginType: "legacy",
     name: config.name,
@@ -1350,6 +1585,9 @@ function fromFunctionPlugin(fn, config) {
   };
 }
 function defineLegacyMerge(args) {
+  logDeprecation(
+    "defineLegacyMerge() is deprecated. Build directly with createSdk(root, { configuration }) instead."
+  );
   return {
     pluginType: "legacy-merge",
     name: args.name,
@@ -1416,40 +1654,60 @@ function pluginEntryMeta(entry) {
   if (entry.pluginType === "property" && entry.meta) return entry.meta;
   return void 0;
 }
-function buildSurfaceRegistry(context, packageFilter) {
+function foldDynamicMembers(entry, surfaceBindings, meta) {
+  if (entry.pluginType !== "property" || !entry.dynamicMembers) return;
+  for (const member of entry.dynamicMembers) {
+    if (!surfaceBindings.has(member.rootBinding)) {
+      throw new Error(
+        `dynamicMember "${member.name}": its root "${member.rootBinding}" is not a surfaced member. A dynamic member's path must start with a real binding.`
+      );
+    }
+    meta[member.name] = member.meta;
+  }
+}
+function collectSurfaceProjection(context, formatterSdk) {
   const meta = {};
-  const surface = {};
   const entries = {};
   for (const [binding, id] of Object.entries(context.surface)) {
     const entry = context.plugins[id];
     if (!entry || entry.pluginType === "aggregate") continue;
-    surface[binding] = entry.value;
     entries[binding] = entry;
     const m = pluginEntryMeta(entry);
     if (m) meta[binding] = m;
   }
+  const surfaceBindings = new Set(Object.keys(context.surface));
+  for (const entry of Object.values(entries)) {
+    foldDynamicMembers(entry, surfaceBindings, meta);
+  }
   const formatters = {};
   const boundResolvers = {};
   const positional = {};
   for (const [binding, entry] of Object.entries(entries)) {
-    const f = normalizeFormatter(entry, surface);
+    const f = normalizeFormatter(entry, formatterSdk);
     if (f) formatters[binding] = f;
     const r = normalizeBoundResolvers(entry);
     if (r) boundResolvers[binding] = r;
     const p = methodPositional(entry);
     if (p) positional[binding] = p;
   }
+  return { meta, formatters, boundResolvers, positional };
+}
+function buildSurfaceRegistry(context, packageFilter) {
+  const surface = {};
+  for (const [binding, id] of Object.entries(context.surface)) {
+    const entry = context.plugins[id];
+    if (!entry || entry.pluginType === "aggregate") continue;
+    surface[binding] = entry.pluginType === "property" && entry.getValue ? entry.getValue() : entry.value;
+  }
   return buildRegistry({
     sdk: surface,
-    meta,
-    formatters,
-    boundResolvers,
-    positional,
+    ...collectSurfaceProjection(context, surface),
     packageFilter
   });
 }
 
 // src/model/builtins.ts
+var coreOptionsPluginRef = declareOptionalProperty({ id: CORE_OPTIONS_ID });
 var dangerousContextPlugin = {
   pluginType: "property",
   name: "context",
@@ -1468,12 +1726,15 @@ var getRegistryPlugin = defineMethod({
 });
 
 // src/model/materialize.ts
+var FRAMEWORK_CONFIGURATION_IDS = /* @__PURE__ */ new Set([
+  CORE_OPTIONS_ID
+]);
 function normalizeOutput(output) {
   if (output === void 0) return { type: "raw" };
   if (typeof output === "string") return { type: output };
   return output;
 }
-var CONTEXT = Symbol("kitcore.context");
+var CONTEXT = Symbol.for("kitcore.context");
 function getContext(sdk) {
   return sdk[CONTEXT];
 }
@@ -1535,7 +1796,7 @@ function topoOrder(descriptors) {
   for (const id of descriptors.keys()) visit(id);
   return order;
 }
-function collectPlugins(root, materialized = /* @__PURE__ */ new Set()) {
+function collectPlugins(root, materialized = /* @__PURE__ */ new Set(), configuration) {
   const byId = /* @__PURE__ */ new Map();
   const visit = (plugin) => {
     if (materialized.has(plugin.id)) return;
@@ -1558,8 +1819,51 @@ function collectPlugins(root, materialized = /* @__PURE__ */ new Set()) {
     for (const edge of edgesOf(plugin)) visit(edge);
   };
   visit(root);
+  if (configuration) {
+    for (const [id, value] of Object.entries(configuration)) {
+      const existing = byId.get(id);
+      if (!existing) {
+        if (FRAMEWORK_CONFIGURATION_IDS.has(id)) {
+          const { name, namespace } = parseId(id);
+          byId.set(id, {
+            pluginType: "property",
+            name,
+            namespace,
+            id,
+            imports: [],
+            importBindings: [],
+            value
+          });
+          continue;
+        }
+        throw new Error(
+          `createSdk: configuration id "${id}" matches no plugin in the graph. An injected value must satisfy a property stand-in reachable from the root.`
+        );
+      }
+      if (existing.pluginType !== "property") {
+        throw new Error(
+          `createSdk: configuration id "${id}" resolves to a "${existing.pluginType}" plugin; only property values can be injected.`
+        );
+      }
+      if (!isStandIn(existing)) {
+        throw new Error(
+          `createSdk: configuration id "${id}" collides with a registered provider. A property is either injected or provided by a plugin, not both.`
+        );
+      }
+      byId.set(id, {
+        pluginType: "property",
+        name: existing.name,
+        namespace: existing.namespace,
+        id,
+        imports: [],
+        importBindings: [],
+        value
+      });
+    }
+  }
   for (const [id, plugin] of byId) {
     if (isStandIn(plugin)) {
+      if ("optional" in plugin && plugin.optional) continue;
       throw new Error(
         `createSdk: missing dependency "${id}". A plugin depends on it (via a stand-in) but no implementation was registered.`
       );
@@ -1567,7 +1871,7 @@ function collectPlugins(root, materialized = /* @__PURE__ */ new Set()) {
   }
   return byId;
 }
-function bindValue(target, key2, entry) {
+function bindValue(target, key2, entry, callType = "surface") {
   if (entry.pluginType === "property" && entry.getValue) {
     Object.defineProperty(target, key2, {
       get: entry.getValue,
@@ -1575,8 +1879,9 @@ function bindValue(target, key2, entry) {
       configurable: true
     });
   } else {
+    const value = callType === "internal" && entry.pluginType === "method" ? entry.internalValue ?? entry.value : entry.value;
     Object.defineProperty(target, key2, {
-      value: entry.value,
+      value,
       writable: true,
       enumerable: true,
       configurable: true
@@ -1594,8 +1899,18 @@ function buildSurface(context, ...maps) {
 }
 function buildImports(plugins, importBindings) {
   const imports = {};
-  for (const { binding, id } of importBindings) {
-    bindValue(imports, binding, plugins[id]);
+  for (const { binding, id, optional } of importBindings) {
+    const entry = plugins[id];
+    if (!entry && optional) {
+      Object.defineProperty(imports, binding, {
+        value: void 0,
+        writable: true,
+        enumerable: true,
+        configurable: true
+      });
+      continue;
+    }
+    bindValue(imports, binding, entry, "internal");
   }
   return imports;
 }
@@ -1619,9 +1934,31 @@ function materialize(descriptors, context) {
   buildEagerArtifacts(descriptors, context, states);
   bindAttachments(descriptors, context);
   resolveAggregates(descriptors, context);
-  assembleMiddleware(descriptors, context);
+  assembleMiddleware(descriptors, context, states);
+  assembleHooks(descriptors, context, states);
+  applyMethodOverrides(descriptors, context);
   return context.plugins;
 }
+function applyMethodOverride(context, override) {
+  const entry = context.plugins[override.target];
+  if (!entry) {
+    throw new Error(
+      `defineMethodOverride: no method "${override.target}" to override. Include the target method in the SDK build.`
+    );
+  }
+  if (entry.pluginType !== "method") {
+    throw new Error(
+      `defineMethodOverride: "${override.target}" is a ${entry.pluginType}, not a method; only methods can be overridden.`
+    );
+  }
+  entry.meta = { ...entry.meta, ...override.meta };
+}
+function applyMethodOverrides(descriptors, context) {
+  for (const descriptor of descriptors.values()) {
+    if (descriptor.pluginType !== "method-override") continue;
+    applyMethodOverride(context, descriptor);
+  }
+}
 function bindResolver(resolver, plugins) {
   switch (resolver.type) {
     case "static":
@@ -1667,25 +2004,24 @@ function bindResolver(resolver, plugins) {
         bound.definitions = bindDefinitions(resolver.definitions, plugins);
       return bound;
     }
-    default: {
+    case "dynamic": {
       const imports = buildImports(plugins, resolver.importBindings);
-      const bound = {
-        type: "dynamic",
-        requireParameters: resolver.requireParameters,
-        inputType: resolver.inputType,
-        placeholder: resolver.placeholder,
-        prompt: resolver.prompt
-      };
       const {
         getContext: getContext2,
         listItems,
         tryResolveWithoutPrompt,
         tryResolveFromSearch
       } = resolver;
+      const bound = {
+        type: "dynamic",
+        requireParameters: resolver.requireParameters,
+        inputType: resolver.inputType,
+        placeholder: resolver.placeholder,
+        prompt: resolver.prompt,
+        listItems: ({ input, context, search, cursor }) => listItems({ imports, input, context, search, cursor })
+      };
       if (getContext2)
         bound.getContext = ({ input }) => getContext2({ imports, input });
-      if (listItems)
-        bound.listItems = ({ input, context, search, cursor }) => listItems({ imports, input, context, search, cursor });
       if (tryResolveWithoutPrompt) {
         bound.tryResolveWithoutPrompt = ({ input }) => tryResolveWithoutPrompt({ imports, input });
       }
@@ -1694,6 +2030,12 @@ function bindResolver(resolver, plugins) {
       }
       return bound;
     }
+    default: {
+      const unhandled = resolver;
+      throw new Error(
+        `unhandled resolver kind: ${unhandled.type}`
+      );
+    }
   }
 }
 function bindFields(fields, plugins) {
@@ -1764,25 +2106,11 @@ function runLegacyPass(descriptors, context) {
     if (!("getRegistry" in exports)) {
       let getRegistry2 = function(options) {
         const sdk = this ?? exports;
-        const meta2 = {};
-        const formatters = {};
-        const boundResolvers = {};
-        for (const [binding, id2] of Object.entries(context.surface)) {
-          const entry = context.plugins[id2];
-          if (!entry || entry.pluginType === "aggregate") continue;
-          const m = pluginEntryMeta(entry);
-          if (m) meta2[binding] = m;
-          const f = normalizeFormatter(entry, sdk);
-          if (f) formatters[binding] = f;
-          const r = normalizeBoundResolvers(entry);
-          if (r) boundResolvers[binding] = r;
-        }
-        Object.assign(meta2, context.meta);
+        const projection = collectSurfaceProjection(context, sdk);
+        Object.assign(projection.meta, context.meta);
         return buildRegistry({
           sdk,
-          meta: meta2,
-          formatters,
-          boundResolvers,
+          ...projection,
           packageFilter: options?.package
         });
       };
@@ -1827,7 +2155,10 @@ function buildMethodEntries(descriptors, context, states) {
         next = (i) => wrap.run({
           imports: buildImports(plugins, wrap.owner.importBindings),
           next: inner,
-          input: i
+          input: i,
+          // Overwritten by the chain item's own closure with the owning
+          // hook's setup state.
+          state: void 0
         });
       }
       return next(input);
@@ -1841,7 +2172,8 @@ function buildMethodEntries(descriptors, context, states) {
           schema: descriptor.inputSchema,
           name: descriptor.name,
           defaultPageSize: out.defaultPageSize,
-          adaptPage: out.adaptPage
+          adaptPage: out.adaptPage,
+          getDeprecation: () => entry.meta?.deprecation
         }
       );
     } else if (out.type === "item") {
@@ -1850,25 +2182,43 @@ function buildMethodEntries(descriptors, context, states) {
       });
       entry.value = createFunction(
         fold(itemCore),
-        { sdk, schema: descriptor.inputSchema, name: descriptor.name }
+        {
+          sdk,
+          schema: descriptor.inputSchema,
+          name: descriptor.name,
+          getDeprecation: () => entry.meta?.deprecation
+        }
       );
     } else {
-      entry.value = (rawInput) => {
-        const input = descriptor.inputSchema ? descriptor.inputSchema.parse(rawInput) : rawInput;
-        return fold(callRun)(input);
-      };
+      entry.value = createRawFunction(
+        (input) => fold(callRun)(input),
+        {
+          sdk,
+          name: descriptor.name,
+          schema: descriptor.skipInputValidation ? void 0 : descriptor.inputSchema,
+          positional: descriptor.positional,
+          // The boundary reads the deprecation LIVE off the entry, so a
+          // deprecation merged after build (defineMethodOverride, addPlugin)
+          // fires too.
+          getDeprecation: () => entry.meta?.deprecation
+        }
+      );
     }
+    const canonicalValue = entry.value;
     if (descriptor.positional) {
       const names = descriptor.positional;
-      const canonicalValue = entry.value;
-      entry.value = (...args) => {
+      const pack = (args) => {
         const packed = {};
         names.forEach((name, i) => {
           if (i < args.length) packed[name] = args[i];
         });
-        return canonicalValue(packed);
+        return packed;
       };
+      entry.value = (...args) => canonicalValue(pack(args));
+      entry.internalValue = (...args) => canonicalValue(pack(args), INTERNAL_CALL);
       entry.positional = names;
+    } else {
+      entry.internalValue = (input) => canonicalValue(input, INTERNAL_CALL);
     }
     plugins[id] = entry;
   }
@@ -1880,7 +2230,7 @@ function buildEagerArtifacts(descriptors, context, states) {
   const ensureBuilt = (id) => {
     if (built.has(id)) return;
     const descriptor = descriptors.get(id);
-    if (!descriptor || descriptor.pluginType === "aggregate" || descriptor.pluginType === "legacy") {
+    if (!descriptor || descriptor.pluginType === "aggregate" || descriptor.pluginType === "legacy" || descriptor.pluginType === "method-override" || isStandIn(descriptor)) {
       built.add(id);
       return;
     }
@@ -1889,6 +2239,30 @@ function buildEagerArtifacts(descriptors, context, states) {
     }
     building.add(id);
     for (const { id: depId } of descriptor.importBindings) ensureBuilt(depId);
+    const recordDisposer = () => {
+      const dispose = descriptor.dispose;
+      if (!dispose) return;
+      context.disposers?.push({
+        id,
+        dispose: (input) => dispose({
+          imports: buildImports(plugins, descriptor.importBindings),
+          state: states.get(id),
+          input
+        })
+      });
+    };
+    if (descriptor.pluginType === "hook") {
+      states.set(
+        id,
+        descriptor.setup ? descriptor.setup({
+          imports: buildImports(plugins, descriptor.importBindings)
+        }) : void 0
+      );
+      recordDisposer();
+      building.delete(id);
+      built.add(id);
+      return;
+    }
     if (descriptor.pluginType === "method") {
       states.set(
         id,
@@ -1908,7 +2282,8 @@ function buildEagerArtifacts(descriptors, context, states) {
           pluginType: "property",
           name: descriptor.name,
           value: context,
-          meta: descriptor.meta
+          meta: descriptor.meta,
+          dynamicMembers: descriptor.dynamicMembers
         };
       } else if (descriptor.get) {
         const get = descriptor.get;
@@ -1920,22 +2295,68 @@ function buildEagerArtifacts(descriptors, context, states) {
             imports: buildImports(plugins, importBindings),
             state: states.get(id)
           }),
-          meta: descriptor.meta
+          meta: descriptor.meta,
+          dynamicMembers: descriptor.dynamicMembers
         };
       } else {
         plugins[id] = {
           pluginType: "property",
           name: descriptor.name,
           value: descriptor.value,
-          meta: descriptor.meta
+          meta: descriptor.meta,
+          dynamicMembers: descriptor.dynamicMembers
         };
       }
     }
+    recordDisposer();
     building.delete(id);
     built.add(id);
   };
   for (const id of descriptors.keys()) ensureBuilt(id);
 }
+function resolvePlugin(sdk, ref) {
+  const entry = getContext(sdk).plugins[ref.id];
+  if (!entry) {
+    if (ref.optional) {
+      return void 0;
+    }
+    throw new Error(
+      `resolvePlugin: plugin "${ref.id}" is not materialized on the SDK.`
+    );
+  }
+  if (entry.pluginType === "property" && entry.getValue) {
+    return entry.getValue();
+  }
+  if (entry.pluginType === "method" && entry.internalValue) {
+    return entry.internalValue;
+  }
+  return entry.value;
+}
+var CoreDisposeError = class extends Error {
+  constructor(errors) {
+    super(`disposeSdk: ${errors.length} dispose callback(s) failed.`);
+    this.name = "CoreDisposeError";
+    this.errors = errors;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+function disposeSdk(sdk, input) {
+  const context = getContext(sdk);
+  if (context.disposed) return context.disposed;
+  const disposers = context.disposers ?? [];
+  context.disposed = (async () => {
+    const errors = [];
+    for (let i = disposers.length - 1; i >= 0; i--) {
+      try {
+        await disposers[i].dispose(input);
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    if (errors.length > 0) throw new CoreDisposeError(errors);
+  })();
+  return context.disposed;
+}
 function resolveAggregates(descriptors, context) {
   const plugins = context.plugins;
   for (const [id, descriptor] of descriptors) {
@@ -1947,39 +2368,74 @@ function resolveAggregates(descriptors, context) {
     plugins[id] = { pluginType: "aggregate", name: descriptor.name, exports };
   }
 }
-function assembleMiddleware(descriptors, context) {
+function assembleMiddleware(descriptors, context, states) {
   const plugins = context.plugins;
   for (const id of topoOrder(descriptors)) {
     const descriptor = descriptors.get(id);
-    if (!descriptor || descriptor.pluginType !== "aggregate" || !descriptor.middleware) {
+    if (!descriptor || descriptor.pluginType !== "hook" || !descriptor.wrap) {
       continue;
     }
-    for (const [targetBinding, fn] of Object.entries(descriptor.middleware)) {
+    for (const [targetBinding, fn] of Object.entries(descriptor.wrap)) {
       const edge = descriptor.importBindings.find(
         (b) => b.binding === targetBinding
       );
       if (!edge) {
         throw new Error(
-          `createSdk: middleware target "${targetBinding}" in plugin "${id}" is not a direct dependency. A middleware target must be a declared dependency of the wrapping plugin.`
+          `createSdk: wrap target "${targetBinding}" in hook "${id}" is not a direct dependency. A wrap target must be a declared import of the wrapping hook.`
         );
       }
       const target = plugins[edge.id];
       if (!target || target.pluginType !== "method") {
         throw new Error(
-          `createSdk: middleware target "${targetBinding}" in plugin "${id}" does not resolve to a method.`
+          `createSdk: wrap target "${targetBinding}" in hook "${id}" does not resolve to a method.`
         );
       }
       if (target.output?.type === "list") {
         throw new Error(
-          `createSdk: middleware target "${targetBinding}" in plugin "${id}" resolves to a list-output method, which does not support middleware yet.`
+          `createSdk: wrap target "${targetBinding}" in hook "${id}" resolves to a list-output method, which does not support wrapping yet.`
         );
       }
-      target.chain.push({ run: fn, owner: descriptor });
+      target.chain.push({
+        run: (bag) => fn({ ...bag, state: states.get(id) }),
+        owner: descriptor
+      });
+    }
+  }
+}
+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) {
+      continue;
     }
+    const { observe } = descriptor;
+    const imports = buildImports(plugins, descriptor.importBindings);
+    const state = states.get(id);
+    const contributed = {};
+    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 }));
+      };
+    }
+    context.hooks = buildHooks(context.hooks, contributed);
   }
 }
-function createSdk(root) {
-  const context = { plugins: {}, meta: {}, hooks: {}, surface: {} };
+function createSdk(root, options) {
+  const context = {
+    plugins: {},
+    meta: {},
+    hooks: {},
+    surface: {},
+    disposers: []
+  };
   if (root.pluginType === "legacy-merge") {
     const { legacy, plugin } = root;
     const collectRoot = {
@@ -1990,7 +2446,10 @@ function createSdk(root) {
       importBindings: [],
       exports: {}
     };
-    const plugins2 = materialize(collectPlugins(collectRoot), context);
+    const plugins2 = materialize(
+      collectPlugins(collectRoot, void 0, options?.configuration),
+      context
+    );
     const legacyExports = plugins2[legacy.id].exports;
     let pluginSurface;
     if (plugin.pluginType === "aggregate") {
@@ -2007,7 +2466,10 @@ function createSdk(root) {
     }
     return buildSurface(context, legacyExports, pluginSurface);
   }
-  const plugins = materialize(collectPlugins(root), context);
+  const plugins = materialize(
+    collectPlugins(root, void 0, options?.configuration),
+    context
+  );
   if (root.pluginType === "method" || root.pluginType === "property") {
     context.surface[root.name] = root.id;
     const sdk = buildSurface(context);
@@ -2021,7 +2483,7 @@ function createSdk(root) {
 function addModelPlugin(sdk, plugin, options = {}) {
   const override = options.override === true;
   const context = getContext(sdk);
-  const surfaceKeys = plugin.pluginType === "aggregate" ? Object.keys(plugin.exports) : [plugin.name];
+  const surfaceKeys = plugin.pluginType === "aggregate" ? Object.keys(plugin.exports) : plugin.pluginType === "hook" ? [] : [plugin.name];
   checkRootKeyCollisions(sdk, surfaceKeys, override, "addPlugin");
   const materialized = new Set(Object.keys(context.plugins));
   if (override && materialized.has(plugin.id)) {
@@ -2030,6 +2492,7 @@ function addModelPlugin(sdk, plugin, options = {}) {
     );
   }
   materialize(collectPlugins(plugin, materialized), context);
+  if (plugin.pluginType === "hook") return;
   const entry = context.plugins[plugin.id];
   if (entry.pluginType === "aggregate") {
     Object.defineProperties(
@@ -2063,6 +2526,13 @@ function addPlugin(sdk, plugin, options) {
     }
     return;
   }
+  if (plugin.pluginType === "method-override") {
+    applyMethodOverride(
+      getContext(sdk),
+      plugin
+    );
+    return;
+  }
   addModelPlugin(
     sdk,
     plugin,
@@ -2145,20 +2615,14 @@ function objectShape(schema) {
 }
 function topoOrder2(specs) {
   const byName = new Map(specs.map((s) => [s.name, s]));
-  const ordered = [];
   const placed = /* @__PURE__ */ new Set();
-  let progressed = true;
-  while (ordered.length < specs.length && progressed) {
-    progressed = false;
-    for (const spec of specs) {
-      if (placed.has(spec.name)) continue;
-      const ready = spec.requires.every((r) => !byName.has(r) || placed.has(r));
-      if (ready) {
-        ordered.push(spec);
-        placed.add(spec.name);
-        progressed = true;
-      }
-    }
+  const ordered = [];
+  const isReady = (spec) => spec.requires.every((r) => !byName.has(r) || placed.has(r));
+  for (; ; ) {
+    const next = specs.find((s) => !placed.has(s.name) && isReady(s));
+    if (!next) break;
+    ordered.push(next);
+    placed.add(next.name);
   }
   for (const spec of specs) if (!placed.has(spec.name)) ordered.push(spec);
   return ordered;
@@ -2166,7 +2630,12 @@ function topoOrder2(specs) {
 function planParameters(entry) {
   const shape = objectShape(entry.inputSchema);
   const resolvers = entry.boundResolvers ?? {};
-  const names = shape ? Object.keys(shape) : Object.keys(resolvers);
+  const names = shape ? [
+    ...Object.keys(shape),
+    ...Object.keys(resolvers).filter(
+      (name) => !(name in shape) && resolvers[name].type === "constant"
+    )
+  ] : Object.keys(resolvers);
   const specs = names.map((name) => {
     const field = shape?.[name];
     const { inner, required } = field ? unwrap(field) : { inner: void 0, required: false };
@@ -2180,7 +2649,13 @@ function planParameters(entry) {
       requires: resolver?.requireParameters ?? []
     };
   });
-  return { parameters: topoOrder2(specs) };
+  const declared = shape ? specs.filter((s) => s.name in shape) : specs;
+  const scan = [
+    ...shape ? specs.filter((s) => !(s.name in shape)) : [],
+    ...declared.filter((s) => s.required),
+    ...declared.filter((s) => !s.required)
+  ];
+  return { parameters: topoOrder2(scan) };
 }
 
 // src/model/resolution/engine.ts
@@ -2205,10 +2680,12 @@ var key = (path) => path.join(".");
 function isSettled(state, path) {
   return state.settled.includes(key(path));
 }
-function settle(state, path) {
-  const k = key(path);
+function remember(state, k) {
   if (!state.settled.includes(k)) state.settled.push(k);
 }
+function settle(state, path) {
+  remember(state, key(path));
+}
 function clone(state) {
   return JSON.parse(JSON.stringify(state));
 }
@@ -2225,8 +2702,9 @@ function coerce(leaf, raw) {
   return raw;
 }
 async function validationError(leaf, value, state) {
+  if (leaf.resolver?.type !== "dynamic") return null;
   const context = await resolveContext(leaf, state.resolved);
-  const config = leaf.resolver?.prompt?.({
+  const config = leaf.resolver.prompt?.({
     items: state.listing?.items ?? [],
     input: mergeInput(state.resolved, leaf.extraInput),
     context
@@ -2236,11 +2714,6 @@ async function validationError(leaf, value, state) {
   if (verdict === true) return null;
   return typeof verdict === "string" ? verdict : `${leaf.name}: invalid value`;
 }
-function toChoice(c) {
-  const label = "label" in c ? c.label : c.name;
-  const hint = Array.isArray(c.hint) ? c.hint.join(", ") : c.hint;
-  return { label, value: String(c.value), hint };
-}
 function isRef(r) {
   return typeof r === "object" && r !== null && "ref" in r;
 }
@@ -2256,6 +2729,7 @@ function toLeaf(name, field, definitions) {
   return {
     name,
     required: field.required ?? false,
+    label: field.label,
     resolver,
     extraInput,
     // Carry the field's value type so nested answers coerce (number/boolean)
@@ -2303,6 +2777,9 @@ function arrayItem(resolver) {
     requires: []
   };
 }
+function autoSettles(resolver) {
+  return resolver.type === "constant" || resolver.type === "info";
+}
 function mergeInput(input, extra) {
   return extra ? { ...input, ...extra } : input;
 }
@@ -2346,25 +2823,6 @@ async function arrayInfoAt(ctx, path, resolved) {
     item: { ...arrayItem(resolver), name: String(path[path.length - 1]) }
   };
 }
-var AFFORDANCE = {
-  choose: { action: "choose", description: "Pick one of the listed options" },
-  custom: {
-    action: "custom",
-    description: "Provide a value directly",
-    supply: "value"
-  },
-  search: {
-    action: "search",
-    description: "Filter the options by a search term",
-    supply: "term"
-  },
-  more: { action: "more", description: "Load more options" },
-  skip: { action: "skip", description: "Omit this optional parameter" },
-  add: { action: "add", description: "Add another item" },
-  done: { action: "done", description: "Finish the list" },
-  retry: { action: "retry", description: "Retry loading the options" },
-  cancel: { action: "cancel", description: "Cancel resolution" }
-};
 async function firstPage(result) {
   const page = await result;
   return {
@@ -2373,18 +2831,19 @@ async function firstPage(result) {
   };
 }
 async function resolveContext(leaf, input) {
-  return leaf.resolver?.getContext?.({
+  if (leaf.resolver?.type !== "dynamic") return void 0;
+  return leaf.resolver.getContext?.({
     input: mergeInput(input, leaf.extraInput)
   });
 }
 async function fetchListing(leaf, input, opts = {}) {
   const page = await firstPage(
-    leaf.resolver?.listItems?.({
+    leaf.resolver?.type === "dynamic" ? leaf.resolver.listItems({
       input: mergeInput(input, leaf.extraInput),
       context: opts.context,
       search: opts.search,
       cursor: opts.cursor
-    })
+    }) : void 0
   );
   return {
     items: [...opts.priorItems ?? [], ...page.data],
@@ -2393,15 +2852,52 @@ async function fetchListing(leaf, input, opts = {}) {
     exhausted: page.nextCursor == null
   };
 }
+
+// src/model/resolution/questions.ts
+function toChoice(c) {
+  const label = "label" in c ? c.label : c.name;
+  const hint = Array.isArray(c.hint) ? c.hint.join(", ") : c.hint;
+  return { label, value: String(c.value), hint };
+}
+var AFFORDANCE = {
+  choose: { action: "choose", description: "Pick one of the listed options" },
+  custom: {
+    action: "custom",
+    description: "Provide a value directly",
+    supply: "value"
+  },
+  search: {
+    action: "search",
+    description: "Filter the options by a search term",
+    supply: "term"
+  },
+  more: { action: "more", description: "Load more options" },
+  skip: { action: "skip", description: "Omit this optional parameter" },
+  add: { action: "add", description: "Add another item" },
+  done: { action: "done", description: "Finish the list" },
+  retry: { action: "retry", description: "Retry loading the options" },
+  cancel: { action: "cancel", description: "Cancel resolution" }
+};
 function selectActions(leaf, listing, multiple) {
+  const searchMode = leaf.resolver?.type === "dynamic" && leaf.resolver.inputType === "search";
+  if (searchMode && listing.search === void 0 && listing.items.length === 0) {
+    const actions2 = multiple ? [AFFORDANCE.search] : [AFFORDANCE.search, AFFORDANCE.custom];
+    if (!leaf.required) actions2.push(AFFORDANCE.skip);
+    return actions2;
+  }
   const actions = multiple ? [AFFORDANCE.choose] : [AFFORDANCE.choose, AFFORDANCE.custom];
-  if (leaf.resolver?.inputType === "search") actions.push(AFFORDANCE.search);
+  if (searchMode) actions.push(AFFORDANCE.search);
   if (listing.cursor) actions.push(AFFORDANCE.more);
   if (!leaf.required) actions.push(AFFORDANCE.skip);
   return actions;
 }
+function labeledMessage(leaf) {
+  if (!leaf.label) return void 0;
+  return `${leaf.label} (${leaf.required ? "required" : "optional"}):`;
+}
 function selectQuestion(leaf, input, listing, context) {
-  const config = leaf.resolver?.prompt?.({
+  const resolver = leaf.resolver?.type === "dynamic" ? leaf.resolver : void 0;
+  const config = resolver?.prompt?.({
     items: listing.items,
     input: mergeInput(input, leaf.extraInput),
     context
@@ -2409,10 +2905,15 @@ function selectQuestion(leaf, input, listing, context) {
   const multiple = config?.type === "checkbox";
   return {
     type: "select",
-    message: config?.message ?? `Select ${leaf.name}:`,
+    // A labeled field's title beats the resolver's message: per-field
+    // resolvers are shared across fields (one choices-fetcher for every
+    // field), so only the leaf knows which field is being asked.
+    message: labeledMessage(leaf) ?? config?.message ?? `Select ${leaf.name}:`,
     choices: (config?.choices ?? []).map(toChoice),
     ...multiple ? { multiple: true } : {},
     ...config?.notes?.length ? { notes: config.notes } : {},
+    ...listing.search !== void 0 ? { search: listing.search } : {},
+    ...resolver?.placeholder ? { placeholder: resolver.placeholder } : {},
     actions: selectActions(leaf, listing, multiple)
   };
 }
@@ -2445,8 +2946,20 @@ function failedResult(state, name, error) {
 async function buildQuestion(leaf, input) {
   const optional = !leaf.required;
   const resolver = leaf.resolver;
-  if (resolver?.listItems) {
+  if (resolver?.type === "dynamic") {
     const context = await resolveContext(leaf, input);
+    if (resolver.inputType === "search") {
+      const listing2 = {
+        items: [],
+        cursor: void 0,
+        search: void 0,
+        exhausted: true
+      };
+      return {
+        question: selectQuestion(leaf, input, listing2, context),
+        listing: listing2
+      };
+    }
     const listing = await fetchListing(leaf, input, { context });
     return {
       question: selectQuestion(leaf, input, listing, context),
@@ -2465,37 +2978,29 @@ async function buildQuestion(leaf, input) {
       }
     };
   }
-  const inputType = resolver?.inputType && resolver.inputType !== "search" ? resolver.inputType : "text";
+  const textSource = resolver?.type === "static" ? resolver : void 0;
+  const inputType = textSource?.inputType && textSource.inputType !== "search" ? textSource.inputType : "text";
   const actions = [AFFORDANCE.custom];
   if (optional) actions.push(AFFORDANCE.skip);
   return {
     question: {
       type: "input",
-      message: `Enter ${leaf.name}:`,
+      // The optional marker makes Enter-to-pass discoverable on a bare
+      // parameter; a labeled field carries its marker via labeledMessage.
+      message: labeledMessage(leaf) ?? `Enter ${leaf.name}${optional ? " (optional)" : ""}:`,
       inputType,
-      placeholder: resolver?.placeholder,
+      placeholder: textSource?.placeholder,
       actions
     }
   };
 }
-function finalize(ctx, resolved) {
-  if (!ctx.schema) return { status: "done", value: resolved };
-  const parsed = ctx.schema.safeParse(resolved);
-  if (parsed.success) {
-    return { status: "done", value: parsed.data };
-  }
-  const issues = parsed.error.issues.map((i) => ({
-    parameter: i.path.map(String).join(".") || void 0,
-    message: i.message
-  }));
-  return { status: "invalid", issues };
-}
 function collectionQuestion(t) {
   const actions = [AFFORDANCE.add];
   if (t.count >= t.min) actions.push(AFFORDANCE.done);
   return {
     type: "collection",
-    message: `Add another ${t.path[t.path.length - 1]}? (${t.count} so far)`,
+    message: `Add ${t.path[t.path.length - 1]}[${t.count}]?`,
+    container: "array",
     count: t.count,
     min: t.min,
     // An unbounded array's max is Infinity, which JSON.stringify turns to null;
@@ -2504,6 +3009,56 @@ function collectionQuestion(t) {
     actions
   };
 }
+function objectGateQuestion(path) {
+  return {
+    type: "collection",
+    message: `Add ${path[path.length - 1]}?`,
+    container: "object",
+    actions: [
+      {
+        action: "add",
+        description: "Provide values for these fields"
+      },
+      { action: "done", description: "Skip these fields" }
+    ]
+  };
+}
+function optionalsGateQuestion(pending) {
+  return {
+    type: "collection",
+    // The prompt and its context ride separately so a host renders the info
+    // line above the confirm without composing any text of its own.
+    message: "Would you like to configure optional fields?",
+    description: `There are ${pending.length} optional field(s) available.`,
+    container: "object",
+    // The gated fields' projection, so a smart host can show WHAT `add` would
+    // walk (or render a form section) instead of a blind yes/no.
+    fields: pending.map((leaf) => ({
+      key: leaf.name,
+      ...leaf.label ? { label: leaf.label } : {},
+      ...leaf.valueType ? { valueType: leaf.valueType } : {}
+    })),
+    actions: [
+      { action: "add", description: "Configure the optional fields" },
+      { action: "done", description: "Skip the optional fields" }
+    ]
+  };
+}
+
+// src/model/resolution/walk.ts
+function finalize(ctx, resolved) {
+  if (!ctx.schema) return { status: "done", value: resolved };
+  const parsed = ctx.schema.safeParse(resolved);
+  if (parsed.success) {
+    return { status: "done", value: parsed.data };
+  }
+  const issues = parsed.error.issues.map((i) => ({
+    parameter: i.path.map(String).join(".") || void 0,
+    message: i.message
+  }));
+  return { status: "invalid", issues };
+}
+var optionalsMarker = (path) => `${key(path)}?optionals`;
 async function findInArray(ctx, state, path) {
   if (isSettled(state, path)) return null;
   if (getAtPath(state.resolved, path) == null)
@@ -2517,8 +3072,11 @@ async function findInArray(ctx, state, path) {
   const len = items.length;
   const itemType = item.resolver?.type;
   if (len > 0 && (itemType === "object" || itemType === "array")) {
-    const inner = await findNext(ctx, state, [...path, len - 1]);
-    if (inner) return inner;
+    const itemPath = [...path, len - 1];
+    if (!isSettled(state, itemPath)) {
+      const inner = await findNext(ctx, state, itemPath);
+      if (inner) return inner;
+    }
   }
   if (len < min) return descendItem(ctx, state, path, len, item);
   if (len < max) return { kind: "array", path, count: len, min, max };
@@ -2546,14 +3104,60 @@ async function descendItem(ctx, state, arrayPath, index, item) {
 }
 async function findNext(ctx, state, path = []) {
   const container = getAtPath(state.resolved, path) ?? {};
-  for (const leaf of await childrenAt(ctx, path, state.resolved)) {
+  const children = await childrenAt(ctx, path, state.resolved);
+  const inObject = path.length > 0;
+  const ordered = inObject ? [
+    ...children.filter((c) => c.required),
+    ...children.filter((c) => !c.required)
+  ] : children;
+  const asksUser = (c) => c.resolver ? !autoSettles(c.resolver) : c.required;
+  const isPendingChild = (c) => container[c.name] === void 0 && !isSettled(state, [...path, c.name]);
+  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)) continue;
+    if (!leaf.requires.every(
+      (r) => 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");
+    if (inObject && !inArrayItem && state.interactive && hasAskableRequired && !leaf.required && asksUser(leaf) && isPendingChild(leaf) && !state.settled.includes(optionalsMarker(path)) && !children.some((c) => c.required && asksUser(c) && isPendingChild(c))) {
+      const pending = ordered.filter(
+        (c) => !c.required && asksUser(c) && isPendingChild(c)
+      );
+      return { kind: "optionals", path, pending };
+    }
     if (leaf.resolver?.type === "object") {
-      if (getAtPath(state.resolved, childPath) == null)
+      if (isSettled(state, childPath)) continue;
+      if (getAtPath(state.resolved, childPath) == null) {
+        if (!leaf.required && !inArrayItem) {
+          if (!state.interactive) {
+            settle(state, childPath);
+            continue;
+          }
+          return { kind: "object", path: childPath, leaf };
+        }
         setAtPath(state.resolved, childPath, {});
+      }
       const inner = await findNext(ctx, state, childPath);
       if (inner) return inner;
+      if (!leaf.required) {
+        const value = getAtPath(state.resolved, childPath);
+        if (value !== null && typeof value === "object" && Object.keys(value).length === 0) {
+          const grandchildren = await childrenAt(
+            ctx,
+            childPath,
+            state.resolved
+          );
+          const pending = grandchildren.some(
+            (c) => value[c.name] === void 0 && !isSettled(state, [...childPath, c.name])
+          );
+          if (!pending) {
+            delete container[leaf.name];
+            settle(state, childPath);
+          }
+        }
+      }
       continue;
     }
     if (leaf.resolver?.type === "array") {
@@ -2569,6 +3173,7 @@ async function findNext(ctx, state, path = []) {
 }
 async function askLeaf(state, path, leaf, opts = {}) {
   state.current = path;
+  delete state.gate;
   try {
     const { question, listing } = await buildQuestion(leaf, state.resolved);
     state.listing = listing;
@@ -2590,21 +3195,52 @@ async function advance(ctx, state) {
     const target = await findNext(ctx, state);
     if (!target) {
       delete state.current;
+      delete state.gate;
       delete state.listing;
       return { state, result: finalize(ctx, state.resolved) };
     }
     if (target.kind === "array") {
       state.current = target.path;
+      state.gate = "array";
       delete state.listing;
       return {
         state,
         result: { status: "ask", question: collectionQuestion(target) }
       };
     }
+    if (target.kind === "object") {
+      state.current = target.path;
+      state.gate = "entry";
+      delete state.listing;
+      return {
+        state,
+        result: { status: "ask", question: objectGateQuestion(target.path) }
+      };
+    }
+    if (target.kind === "optionals") {
+      state.current = target.path;
+      state.gate = "optionals";
+      delete state.listing;
+      return {
+        state,
+        result: {
+          status: "ask",
+          question: optionalsGateQuestion(target.pending)
+        }
+      };
+    }
     const { path, leaf } = target;
-    const auto = await leaf.resolver?.tryResolveWithoutPrompt?.({
+    const resolver = leaf.resolver;
+    if (resolver && autoSettles(resolver)) {
+      if (resolver.type === "constant") {
+        setAtPath(state.resolved, path, resolver.value);
+      }
+      settle(state, path);
+      continue;
+    }
+    const auto = resolver?.type === "dynamic" ? await resolver.tryResolveWithoutPrompt?.({
       input: mergeInput(state.resolved, leaf.extraInput)
-    });
+    }) : void 0;
     if (auto) {
       if (auto.resolvedValue !== void 0)
         setAtPath(state.resolved, path, auto.resolvedValue);
@@ -2624,23 +3260,22 @@ async function advance(ctx, state) {
   }
 }
 async function start(ctx, input = {}, interactive = true) {
-  const resolved = {};
-  for (const spec of ctx.parameters) {
-    if (spec.resolver?.type === "constant")
-      resolved[spec.name] = spec.resolver.value;
-  }
-  Object.assign(resolved, input);
-  return advance(ctx, {
+  const state = {
     method: ctx.method,
-    resolved,
+    resolved: { ...input },
     settled: [],
     interactive
-  });
+  };
+  for (const [name, value] of Object.entries(input)) {
+    if (value !== void 0) settle(state, [name]);
+  }
+  return advance(ctx, state);
 }
 async function step(ctx, prior, action) {
   const state = clone(prior);
   if (action.type === "cancel") {
     delete state.current;
+    delete state.gate;
     delete state.listing;
     return { state, result: { status: "cancelled" } };
   }
@@ -2651,12 +3286,27 @@ async function step(ctx, prior, action) {
     return refine(ctx, state, leaf, path, action);
   }
   if (action.type === "add" || action.type === "done") {
+    const gate = state.gate;
+    if (!gate) {
+      throw new Error(
+        `action "${action.type}" is not supported here: no container decision is outstanding`
+      );
+    }
     delete state.current;
+    delete state.gate;
     delete state.listing;
     if (action.type === "done") {
       settle(state, path);
       return advance(ctx, state);
     }
+    if (gate === "entry") {
+      setAtPath(state.resolved, path, {});
+      return advance(ctx, state);
+    }
+    if (gate === "optionals") {
+      remember(state, optionalsMarker(path));
+      return advance(ctx, state);
+    }
     const items = getAtPath(state.resolved, path) ?? [];
     const { item } = await arrayInfoAt(ctx, path, state.resolved);
     const itemPath = [...path, items.length];
@@ -2664,12 +3314,35 @@ async function step(ctx, prior, action) {
       return askLeaf(state, itemPath, item);
     return advance(ctx, state);
   }
+  if (state.gate) {
+    throw new Error(
+      `action "${action.type}" is not supported here: a container decision (${state.gate}) is outstanding`
+    );
+  }
   switch (action.type) {
     case "choose":
     case "custom": {
       if (leaf) {
         const error = await validationError(leaf, action.value, state);
-        if (error) return askLeaf(state, path, leaf, { error });
+        if (error) {
+          if (state.listing && leaf.resolver?.type === "dynamic") {
+            const context = await resolveContext(leaf, state.resolved);
+            return {
+              state,
+              result: {
+                status: "ask",
+                question: selectQuestion(
+                  leaf,
+                  state.resolved,
+                  state.listing,
+                  context
+                ),
+                error
+              }
+            };
+          }
+          return askLeaf(state, path, leaf, { error });
+        }
       }
       setAtPath(
         state.resolved,
@@ -2696,10 +3369,10 @@ async function refine(ctx, state, leaf, path, action) {
   };
   try {
     if (action.type === "search") {
-      const exact = await leaf.resolver?.tryResolveFromSearch?.({
+      const exact = leaf.resolver?.type === "dynamic" ? await leaf.resolver.tryResolveFromSearch?.({
         input: mergeInput(state.resolved, leaf.extraInput),
         search: action.term
-      });
+      }) : void 0;
       if (exact) {
         setAtPath(state.resolved, path, coerce(leaf, exact.resolvedValue));
         delete state.current;
@@ -2750,10 +3423,11 @@ function projectMethod(entry) {
   const inputProperties = toJsonSchema(entry.inputSchema)?.properties;
   const parameters = {};
   for (const spec of planParameters(entry).parameters) {
+    const dynamic = spec.resolver?.type === "dynamic" ? spec.resolver : void 0;
     parameters[spec.name] = {
       required: spec.required,
-      dynamic: Boolean(spec.resolver?.listItems),
-      ...spec.resolver?.inputType === "search" ? { searchable: true } : {},
+      dynamic: Boolean(dynamic),
+      ...dynamic?.inputType === "search" ? { searchable: true } : {},
       ...inputProperties?.[spec.name] ? { schema: inputProperties[spec.name] } : {},
       ...spec.staticChoices ? { choices: spec.staticChoices } : {},
       ...spec.requires.length ? { requireParameters: spec.requires } : {}
@@ -2820,12 +3494,13 @@ function createController(sdk) {
     const spec = contextFor(method).parameters.find(
       (p) => p.name === parameter
     );
-    if (!spec?.resolver?.listItems) return { data: [] };
-    const context = await spec.resolver.getContext?.({ input });
+    const dynamic = spec?.resolver?.type === "dynamic" ? spec.resolver : void 0;
+    if (!dynamic) return { data: [] };
+    const context = await dynamic.getContext?.({ input });
     const page = await firstPage(
-      spec.resolver.listItems({ input, context, search, cursor })
+      dynamic.listItems({ input, context, search, cursor })
     );
-    const config = spec.resolver.prompt?.({ items: page.data, input, context });
+    const config = dynamic.prompt?.({ items: page.data, input, context });
     const data = (config?.choices ?? []).map(toChoice);
     return { data, nextCursor: page.nextCursor };
   };
@@ -2834,6 +3509,9 @@ function createController(sdk) {
 
 // src/utils/core-plugin.ts
 function createCorePlugin(options) {
+  logDeprecation(
+    "createCorePlugin() is deprecated. Inject the options under CORE_OPTIONS_ID via createSdk's configuration instead."
+  );
   return () => ({
     context: {
       core: options
@@ -2896,14 +3574,17 @@ function openEnum(values, description) {
 export {
   CONTEXT,
   CORE_ERROR_SYMBOL,
+  CORE_OPTIONS_ID,
   CORE_SIGNAL_SYMBOL,
   CoreCancelledSignal,
+  CoreDisposeError,
   CoreError,
   CoreErrorCode,
   CoreSignal,
   addPlugin,
   composePlugins,
   concatPaginated,
+  coreOptionsPluginRef,
   createAsyncContext,
   createController,
   createCoreError,
@@ -2919,15 +3600,20 @@ export {
   createValidator,
   dangerousContextPlugin,
   declareMethod,
+  declareOptionalProperty,
   declarePlugin,
   declareProperty,
   decodeIncomingCursor,
+  defaultLogDeprecation,
   defineFormatter,
+  defineHook,
   defineLegacyMerge,
   defineMethod,
+  defineMethodOverride,
   definePlugin,
   defineProperty,
   defineResolver,
+  disposeSdk,
   fromFunctionPlugin,
   getContext,
   getCoreErrorCause,
@@ -2943,10 +3629,12 @@ export {
   isNestedMethodCall,
   isPositional,
   isTelemetryNested,
+  omitExports,
   openEnum,
   paginate,
   paginateBuffered,
   paginateMaxItems,
+  resolvePlugin,
   runInMethodScope,
   runWithTelemetryContext,
   selectExports,