@zapier/kitcore 0.0.0 → 0.5.0

package/dist/index.mjs

@@ -0,0 +1,3646 @@
+// src/registry.ts
+import { z } from "zod";
+
+// src/utils/string-utils.ts
+function toTitleCase(input) {
+  return input.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[_\-]+/g, " ").replace(/\s+/g, " ").trim().split(" ").map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()).join(" ");
+}
+function toSnakeCase(input) {
+  let result = input.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[\s\-]+/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "").toLowerCase();
+  if (/^[0-9]/.test(result)) {
+    result = "_" + result;
+  }
+  return result;
+}
+function pluralize(word) {
+  if (/s$/i.test(word)) return word;
+  if (/[bcdfghjklmnpqrstvwxz]y$/i.test(word)) {
+    return word.slice(0, -1) + "ies";
+  }
+  return word + "s";
+}
+function pluralizeLastWord(title) {
+  const words = title.split(" ");
+  return [...words.slice(0, -1), pluralize(words[words.length - 1])].join(" ");
+}
+
+// src/registry.ts
+function resolveCategoryDefinition(ref) {
+  const def = typeof ref === "string" ? { key: ref } : ref;
+  const title = def.title ?? toTitleCase(def.key);
+  return {
+    key: def.key,
+    title,
+    titlePlural: def.titlePlural ?? pluralizeLastWord(title)
+  };
+}
+function canonicalInputSchema(schema) {
+  if (schema instanceof z.ZodUnion) {
+    return schema.options[0];
+  }
+  return schema;
+}
+function buildRegistry({
+  sdk,
+  meta,
+  formatters,
+  boundResolvers,
+  positional,
+  packageFilter
+}) {
+  const definitionsByKey = /* @__PURE__ */ new Map();
+  const objectDeclaredKeys = /* @__PURE__ */ new Set();
+  for (const m of Object.values(meta)) {
+    for (const ref of m.categories ?? []) {
+      const key2 = typeof ref === "string" ? ref : ref.key;
+      if (typeof ref === "object") {
+        objectDeclaredKeys.add(key2);
+        definitionsByKey.set(key2, resolveCategoryDefinition(ref));
+      } else if (!objectDeclaredKeys.has(key2)) {
+        definitionsByKey.set(key2, resolveCategoryDefinition(ref));
+      }
+    }
+  }
+  if (!definitionsByKey.has("other")) {
+    definitionsByKey.set("other", resolveCategoryDefinition("other"));
+  }
+  const knownCategories = Array.from(definitionsByKey.keys());
+  const functions = Object.keys(meta).filter((key2) => {
+    const property = sdk[key2];
+    if (typeof property === "function") return true;
+    const [rootKey] = key2.split(".");
+    const rootProperty = sdk[rootKey];
+    return typeof rootProperty === "object" && rootProperty !== null;
+  }).map((key2) => {
+    const m = meta[key2];
+    return {
+      name: key2,
+      description: m.description,
+      type: m.type,
+      itemType: m.itemType,
+      returnType: m.returnType,
+      inputSchema: canonicalInputSchema(m.inputSchema),
+      inputParameters: m.inputParameters,
+      outputSchema: m.outputSchema,
+      positional: positional?.[key2],
+      categories: (m.categories ?? []).map(
+        (c) => typeof c === "string" ? c : c.key
+      ),
+      resolvers: m.resolvers,
+      boundResolvers: boundResolvers?.[key2],
+      formatter: formatters?.[key2],
+      experimental: m.experimental,
+      packages: m.packages,
+      confirm: m.confirm ?? (m.type === "delete" ? "delete" : void 0),
+      deprecation: m.deprecation,
+      aliases: m.aliases,
+      supportsJsonOutput: m.supportsJsonOutput ?? true
+    };
+  }).sort((a, b) => a.name.localeCompare(b.name));
+  const filteredFunctions = packageFilter ? functions.filter((f) => !f.packages || f.packages.includes(packageFilter)) : functions;
+  const filteredCategories = knownCategories.slice().sort((a, b) => {
+    if (a === "other") return 1;
+    if (b === "other") return -1;
+    return definitionsByKey.get(a).title.localeCompare(definitionsByKey.get(b).title);
+  }).map((categoryKey) => {
+    const categoryFunctions = filteredFunctions.filter(
+      (f) => f.categories.includes(categoryKey) || categoryKey === "other" && !f.categories.some((c) => knownCategories.includes(c))
+    ).map((f) => f.name).sort();
+    const def = definitionsByKey.get(categoryKey);
+    return {
+      key: categoryKey,
+      title: def.title,
+      titlePlural: def.titlePlural,
+      functions: categoryFunctions
+    };
+  }).filter((category) => category.functions.length > 0);
+  return { functions: filteredFunctions, categories: filteredCategories };
+}
+
+// src/utils/build-hooks.ts
+function composeVoid(existing, added) {
+  if (!existing) return added;
+  if (!added) return existing;
+  return (ctx) => {
+    existing(ctx);
+    added(ctx);
+  };
+}
+function buildHooks(existing, added) {
+  const result = {};
+  const start2 = composeVoid(existing.onMethodStart, added.onMethodStart);
+  if (start2) result.onMethodStart = start2;
+  const end = composeVoid(existing.onMethodEnd, added.onMethodEnd);
+  if (end) result.onMethodEnd = end;
+  return result;
+}
+
+// src/utils/logging.ts
+function createDeprecationLogger(tag) {
+  const loggedDeprecations = /* @__PURE__ */ new Set();
+  return {
+    logDeprecation(message) {
+      if (loggedDeprecations.has(message)) return;
+      loggedDeprecations.add(message);
+      console.warn(`[${tag}] Deprecation: ${message}`);
+    },
+    resetDeprecationWarnings() {
+      loggedDeprecations.clear();
+    }
+  };
+}
+var { logDeprecation, resetDeprecationWarnings } = createDeprecationLogger("core");
+
+// src/types/errors.ts
+var CORE_ERROR_SYMBOL = Symbol.for("kitcore.error");
+var CoreErrorCode = {
+  Validation: "VALIDATION_ERROR",
+  Unknown: "UNKNOWN_ERROR"
+};
+var CoreError = class extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "CoreError";
+    if (options.statusCode !== void 0) this.statusCode = options.statusCode;
+    if (options.errors !== void 0) this.errors = options.errors;
+    if (options.cause !== void 0) this.cause = options.cause;
+    if (options.response !== void 0) this.response = options.response;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+function createCoreError(options, adaptError) {
+  const error = adaptError?.(options) ?? new CoreError(options.message, { cause: options.cause });
+  Object.defineProperty(error, CORE_ERROR_SYMBOL, {
+    value: true,
+    enumerable: false,
+    configurable: true,
+    writable: false
+  });
+  Object.defineProperty(error, "coreCode", {
+    value: options.code,
+    enumerable: false,
+    configurable: true,
+    writable: false
+  });
+  return error;
+}
+function isCoreError(value) {
+  return Boolean(
+    value && typeof value === "object" && value[CORE_ERROR_SYMBOL] === true
+  );
+}
+function getCoreErrorCode(value) {
+  if (!isCoreError(value)) return void 0;
+  return value.coreCode;
+}
+function getCoreErrorCause(value) {
+  if (!isCoreError(value)) return void 0;
+  return value.cause;
+}
+
+// src/utils/pagination-utils.ts
+var CURSOR_VERSION = 1;
+var CURSOR_SOURCE = {
+  API: "api",
+  SDK: "sdk"
+};
+function encodeBase64(str) {
+  return btoa(
+    Array.from(
+      new TextEncoder().encode(str),
+      (b) => String.fromCharCode(b)
+    ).join("")
+  );
+}
+function decodeBase64(str) {
+  return new TextDecoder().decode(
+    Uint8Array.from(atob(str), (c) => c.charCodeAt(0))
+  );
+}
+function encodeApiCursor(cursor) {
+  const envelope = {
+    v: CURSOR_VERSION,
+    source: CURSOR_SOURCE.API,
+    cursor
+  };
+  return encodeBase64(JSON.stringify(envelope));
+}
+function encodeSdkCursor(offset, cursor) {
+  const envelope = {
+    v: CURSOR_VERSION,
+    source: CURSOR_SOURCE.SDK,
+    cursor,
+    offset
+  };
+  return encodeBase64(JSON.stringify(envelope));
+}
+function decodeIncomingCursor(incoming) {
+  if (!incoming) {
+    return { offset: 0, cursor: void 0 };
+  }
+  try {
+    const decoded = decodeBase64(incoming);
+    const envelope = JSON.parse(decoded);
+    if (envelope.v !== CURSOR_VERSION) {
+      return { offset: 0, cursor: incoming };
+    }
+    if (envelope.source === CURSOR_SOURCE.SDK) {
+      return { offset: envelope.offset ?? 0, cursor: envelope.cursor };
+    }
+    if (envelope.source === CURSOR_SOURCE.API) {
+      return { offset: 0, cursor: envelope.cursor };
+    }
+    return { offset: 0, cursor: incoming };
+  } catch {
+    return { offset: 0, cursor: incoming };
+  }
+}
+function createPrefixedCursor(prefix, cursor) {
+  if (!cursor) {
+    return `${prefix}::`;
+  }
+  return `${prefix}::${cursor}`;
+}
+function splitPrefixedCursor(cursor, prefixes) {
+  if (!cursor) {
+    return [void 0, void 0];
+  }
+  const [prefix, ...rest] = cursor.split("::");
+  if (prefixes && !prefixes.includes(prefix)) {
+    return [void 0, cursor];
+  }
+  cursor = rest.join("::");
+  if (!cursor) {
+    return [prefix, void 0];
+  }
+  return [prefix, cursor];
+}
+async function* paginateMaxItemsWithUnencodedCursor(pageFunction, pageOptions) {
+  let cursor = pageOptions?.cursor;
+  let totalItemsYielded = 0;
+  const maxItems = pageOptions?.maxItems;
+  const pageSize = pageOptions?.pageSize;
+  do {
+    const options = {
+      ...pageOptions || {},
+      cursor,
+      pageSize: maxItems !== void 0 && pageSize !== void 0 ? Math.min(pageSize, maxItems) : pageSize
+    };
+    const page = await pageFunction(options);
+    if (maxItems !== void 0) {
+      const remainingItems = maxItems - totalItemsYielded;
+      if (page.data.length >= remainingItems) {
+        yield {
+          ...page,
+          data: page.data.slice(0, remainingItems),
+          nextCursor: void 0
+        };
+        break;
+      }
+    }
+    yield page;
+    totalItemsYielded += page.data.length;
+    cursor = page.nextCursor;
+  } while (cursor);
+}
+async function* paginateMaxItems(pageFunction, pageOptions) {
+  const { cursor } = decodeIncomingCursor(pageOptions?.cursor);
+  const options = {
+    ...pageOptions || {},
+    cursor
+  };
+  for await (const page of paginateMaxItemsWithUnencodedCursor(
+    pageFunction,
+    options
+  )) {
+    yield {
+      ...page,
+      nextCursor: page.nextCursor ? encodeApiCursor(page.nextCursor) : void 0
+    };
+  }
+}
+async function* paginateBuffered(pageFunction, pageOptions) {
+  const pageSize = pageOptions?.pageSize;
+  const { offset: cursorOffset, cursor: initialCursor } = decodeIncomingCursor(
+    pageOptions?.cursor
+  );
+  const requestedMaxItems = pageOptions?.maxItems;
+  const options = {
+    ...pageOptions || {},
+    cursor: initialCursor,
+    // SDK cursors can carry an offset into a raw backend page. Since maxItems
+    // is expected to be relative to the resumed position, we add that offset
+    // so raw pagination still yields enough items after offset slicing.
+    maxItems: requestedMaxItems !== void 0 && cursorOffset > 0 ? requestedMaxItems + cursorOffset : requestedMaxItems
+  };
+  if (!pageSize) {
+    for await (const page of paginateMaxItemsWithUnencodedCursor(
+      pageFunction,
+      options
+    )) {
+      yield {
+        ...page,
+        nextCursor: page.nextCursor ? encodeApiCursor(page.nextCursor) : void 0
+      };
+    }
+    return;
+  }
+  let bufferedPages = [];
+  let isFirstPage = true;
+  let rawCursor;
+  for await (let page of paginateMaxItemsWithUnencodedCursor(
+    pageFunction,
+    options
+  )) {
+    const nextRawCursor = page.nextCursor;
+    if (isFirstPage) {
+      isFirstPage = false;
+      if (cursorOffset) {
+        page = {
+          ...page,
+          data: page.data.slice(cursorOffset)
+        };
+      }
+    }
+    const bufferedLength = bufferedPages.reduce(
+      (acc, p) => acc + p.data.length,
+      0
+    );
+    if (bufferedLength + page.data.length < pageSize) {
+      bufferedPages.push(page);
+      rawCursor = nextRawCursor;
+      continue;
+    }
+    const bufferedItems = bufferedPages.map((p) => p.data).flat();
+    const allItems = [...bufferedItems, ...page.data];
+    const pageItems = allItems.slice(0, pageSize);
+    const remainingItems = allItems.slice(pageItems.length);
+    if (remainingItems.length === 0) {
+      yield {
+        ...page,
+        data: pageItems,
+        nextCursor: nextRawCursor ? encodeApiCursor(nextRawCursor) : void 0
+      };
+      bufferedPages = [];
+      rawCursor = nextRawCursor;
+      continue;
+    }
+    yield {
+      ...page,
+      data: pageItems,
+      nextCursor: encodeSdkCursor(
+        page.data.length - remainingItems.length,
+        rawCursor
+      )
+    };
+    while (remainingItems.length > pageSize) {
+      const chunkItems = remainingItems.splice(0, pageSize);
+      yield {
+        ...page,
+        data: chunkItems,
+        nextCursor: encodeSdkCursor(
+          page.data.length - remainingItems.length,
+          rawCursor
+        )
+      };
+    }
+    bufferedPages = [
+      {
+        ...page,
+        data: remainingItems
+      }
+    ];
+    rawCursor = nextRawCursor;
+  }
+  if (bufferedPages.length > 0) {
+    const lastBufferedPage = bufferedPages.slice(-1)[0];
+    const bufferedItems = bufferedPages.map((p) => p.data).flat();
+    yield {
+      ...lastBufferedPage,
+      data: bufferedItems
+    };
+  }
+}
+var paginate = paginateBuffered;
+function concatPaginated({
+  sources,
+  dedupe,
+  pageSize = 100
+}) {
+  if (sources.length === 0) {
+    const empty = { data: [] };
+    return Object.assign(Promise.resolve(empty), {
+      [Symbol.asyncIterator]: async function* () {
+        yield empty;
+      }
+    });
+  }
+  let sourceIndex = 0;
+  let currentIterator = null;
+  const seen = /* @__PURE__ */ new Set();
+  const pageFunction = async (_options) => {
+    while (sourceIndex < sources.length) {
+      if (!currentIterator) {
+        const result = sources[sourceIndex]();
+        currentIterator = result[Symbol.asyncIterator]();
+      }
+      const next = await currentIterator.next();
+      if (next.done) {
+        sourceIndex++;
+        currentIterator = null;
+        continue;
+      }
+      let items = next.value.data;
+      if (dedupe) {
+        if (sourceIndex > 0) {
+          items = items.filter((item) => !seen.has(dedupe(item)));
+        }
+        for (const item of items) {
+          seen.add(dedupe(item));
+        }
+      }
+      const hasMoreInSource = next.value.nextCursor != null;
+      const hasMoreSources = sourceIndex < sources.length - 1;
+      return {
+        data: items,
+        nextCursor: hasMoreInSource || hasMoreSources ? "__has_more__" : void 0
+      };
+    }
+    return { data: [] };
+  };
+  const iterator = paginateBuffered(pageFunction, { pageSize });
+  const firstPagePromise = iterator.next().then((result) => {
+    if (result.done) {
+      return { data: [] };
+    }
+    return result.value;
+  });
+  return Object.assign(firstPagePromise, {
+    [Symbol.asyncIterator]: async function* () {
+      yield await firstPagePromise;
+      for await (const page of { [Symbol.asyncIterator]: () => iterator }) {
+        yield page;
+      }
+    }
+  });
+}
+function toIterable(source) {
+  return { [Symbol.asyncIterator]: () => source[Symbol.asyncIterator]() };
+}
+
+// src/utils/validation.ts
+var parseOrThrow = (schema, input, { adaptError } = {}) => {
+  const result = schema.safeParse(input);
+  if (!result.success) {
+    const errorMessages = result.error.issues.map((issue) => {
+      const path = issue.path.length > 0 ? issue.path.join(".") : "input";
+      return `${path}: ${issue.message}`;
+    });
+    throw createCoreError(
+      {
+        code: CoreErrorCode.Validation,
+        message: `Validation failed:
+  ${errorMessages.join("\n  ")}`,
+        details: {
+          zodErrors: result.error.issues,
+          input
+        }
+      },
+      adaptError
+    );
+  }
+  return result.data;
+};
+function createValidator(schema, { adaptError } = {}) {
+  return function validateFn(input) {
+    return parseOrThrow(schema, input, { adaptError });
+  };
+}
+var validateOptions = (schema, options, { adaptError } = {}) => parseOrThrow(schema, options, { adaptError });
+
+// src/utils/async-context.ts
+import {
+  AsyncLocalStorage
+} from "async_hooks";
+function createAsyncContext() {
+  let store = null;
+  try {
+    store = new AsyncLocalStorage();
+  } catch {
+    store = null;
+  }
+  return {
+    available: store !== null,
+    run(value, fn) {
+      return store ? store.run(value, fn) : fn();
+    },
+    get() {
+      return store?.getStore();
+    }
+  };
+}
+
+// src/utils/method-scope.ts
+var scope = createAsyncContext();
+function getCurrentScope() {
+  return scope.get();
+}
+function getCurrentDepth() {
+  return getCurrentScope()?.depth ?? 0;
+}
+function isNestedMethodCall() {
+  if (!scope.available) return true;
+  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;
+  return scope.run({ depth: currentDepth + 1 }, 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);
+  return createCoreError(
+    {
+      code: CoreErrorCode.Unknown,
+      message,
+      cause: error
+    },
+    adaptError
+  );
+}
+function createFunction(coreFn, 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 = isInsideObserver() ? void 0 : sdk.context.hooks;
+        const adaptError = resolveCoreOptions(sdk.context)?.adaptError;
+        hooks?.onMethodStart?.({
+          methodName: functionName,
+          args,
+          isPaginated: false,
+          depth
+        });
+        try {
+          let result;
+          if (schema) {
+            const validatedOptions = validateOptions(
+              schema,
+              normalizedOptions,
+              {
+                adaptError
+              }
+            );
+            result = await coreFn({
+              ...normalizedOptions,
+              ...validatedOptions
+            });
+          } else {
+            result = await coreFn(normalizedOptions);
+          }
+          hooks?.onMethodEnd?.({
+            methodName: functionName,
+            args,
+            isPaginated: false,
+            depth,
+            durationMs: Date.now() - startTime
+          });
+          return result;
+        } catch (error) {
+          const normalizedError = normalizeError(error, adaptError);
+          hooks?.onMethodEnd?.({
+            methodName: functionName,
+            args,
+            isPaginated: false,
+            depth,
+            durationMs: Date.now() - startTime,
+            error: normalizedError
+          });
+          throw normalizedError;
+        }
+      });
+    }
+  };
+  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;
+  if (!Array.isArray(page.data)) return false;
+  if (page.nextCursor !== void 0 && typeof page.nextCursor !== "string") {
+    return false;
+  }
+  return Object.keys(page).every((k) => k === "data" || k === "nextCursor");
+}
+function createPageFunction(coreFn, {
+  sdk,
+  adaptPage
+}) {
+  const functionName = coreFn.name + "Page";
+  const namedFunctions = {
+    [functionName]: async function(options) {
+      try {
+        const response = await coreFn(options);
+        const page = adaptPage ? adaptPage(response) : response;
+        if (!isSdkPage(page)) {
+          throw new Error(
+            `${functionName}: paginated result must be exactly { data: TItem[], nextCursor? } (produced by the handler or its \`adaptPage\`); got keys [${page && typeof page === "object" ? Object.keys(page).join(", ") : typeof page}]. If the handler returns a raw shape, set \`adaptPage\` to translate it; if \`adaptPage\` already runs, it must return only \`data\`/\`nextCursor\`.`
+          );
+        }
+        return page;
+      } catch (error) {
+        throw normalizeError(
+          error,
+          resolveCoreOptions(sdk.context)?.adaptError
+        );
+      }
+    }
+  };
+  return namedFunctions[functionName];
+}
+function createPaginatedFunction(coreFn, 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 = isInsideObserver() ? void 0 : sdk.context.hooks;
+        const adaptError = resolveCoreOptions(sdk.context)?.adaptError;
+        hooks?.onMethodStart?.({
+          methodName: functionName,
+          args,
+          isPaginated: true,
+          depth
+        });
+        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;
+          });
+          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))
+              });
+            });
+          }
+          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;
+        }
+      });
+    }
+  };
+  return namedFunctions[functionName];
+}
+
+// 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) {
+      return handler({ sdk, options });
+    }
+  };
+  const wrappedFn = createFunction(namedHandlers[name], {
+    sdk,
+    schema: inputSchema
+  });
+  return {
+    [name]: wrappedFn,
+    context: {
+      meta: {
+        [name]: {
+          ...metaFields,
+          ...inputSchema ? { inputSchema } : {}
+        }
+      }
+    }
+  };
+}
+function createPaginatedPluginMethod(sdk, config) {
+  logDeprecation(
+    'createPaginatedPluginMethod() is deprecated. Author list methods with defineMethod output "list" instead.'
+  );
+  const {
+    name,
+    inputSchema,
+    handler,
+    adaptPage,
+    defaultPageSize,
+    ...metaFields
+  } = config;
+  const namedHandlers = {
+    [name]: function(options) {
+      return handler({ sdk, options });
+    }
+  };
+  const wrappedFn = createPaginatedFunction(namedHandlers[name], {
+    sdk,
+    schema: inputSchema,
+    name,
+    defaultPageSize,
+    adaptPage
+  });
+  return {
+    [name]: wrappedFn,
+    context: {
+      meta: {
+        [name]: {
+          ...metaFields,
+          ...inputSchema ? { inputSchema } : {}
+        }
+      }
+    }
+  };
+}
+function splitPluginContribution(result) {
+  const { context, ...rootKeys } = result;
+  const { meta, hooks, ...contextRest } = context ?? {};
+  return {
+    rootKeys,
+    meta: meta ?? {},
+    hooks: hooks ?? {},
+    contextRest
+  };
+}
+var RESERVED_ROOT_KEYS = /* @__PURE__ */ new Set([
+  "context",
+  "getRegistry"
+]);
+function hasOwn(obj, key2) {
+  return Object.prototype.hasOwnProperty.call(obj, key2);
+}
+function setOwn(target, key2, value) {
+  Object.defineProperty(target, key2, {
+    value,
+    enumerable: true,
+    configurable: true,
+    writable: true
+  });
+}
+function checkCollisions(target, source, kind, callerLabel, override) {
+  if (kind === "root key") {
+    checkRootKeyCollisions(target, Object.keys(source), override, callerLabel);
+    return;
+  }
+  for (const key2 of Object.keys(source)) {
+    if (!override && hasOwn(target, key2)) {
+      throw new Error(
+        `${callerLabel}: duplicate ${kind} "${key2}". If the override is intentional, pass { override: true } in the options.`
+      );
+    }
+  }
+}
+function checkRootKeyCollisions(target, keys, override, callerLabel) {
+  for (const key2 of keys) {
+    if (RESERVED_ROOT_KEYS.has(key2)) {
+      throw new Error(
+        `${callerLabel}: plugin attempted to register reserved root key "${key2}". The SDK uses this key for its own accessor; rename the plugin's method.`
+      );
+    }
+    if (!override && hasOwn(target, key2)) {
+      throw new Error(
+        `${callerLabel}: duplicate root key "${key2}". If the override is intentional, pass { override: true } in the options.`
+      );
+    }
+  }
+}
+function applyOwnProperties(target, source) {
+  for (const key2 of Object.keys(source)) {
+    setOwn(target, key2, source[key2]);
+  }
+}
+function createPluginAccumulator(initialProperties = {}, initialContext = {}) {
+  const initialMeta = initialContext.meta ?? {};
+  const initialHooks = initialContext.hooks ?? {};
+  const context = {
+    ...initialContext,
+    meta: { ...initialMeta },
+    hooks: { ...initialHooks }
+  };
+  const view = { ...initialProperties, context };
+  return { view, context };
+}
+function mergeContribution(propertiesTarget, contextTarget, contribution, options) {
+  checkCollisions(
+    propertiesTarget,
+    contribution.rootKeys,
+    "root key",
+    options.callerLabel,
+    options.override
+  );
+  checkCollisions(
+    contextTarget.meta,
+    contribution.meta,
+    "context.meta key",
+    options.callerLabel,
+    options.override
+  );
+  checkCollisions(
+    contextTarget,
+    contribution.contextRest,
+    "context key",
+    options.callerLabel,
+    options.override
+  );
+  applyOwnProperties(propertiesTarget, contribution.rootKeys);
+  applyOwnProperties(contextTarget.meta, contribution.meta);
+  applyOwnProperties(contextTarget, contribution.contextRest);
+  contextTarget.hooks = buildHooks(contextTarget.hooks, contribution.hooks);
+}
+function applyPluginContribution(acc, contribution, options) {
+  mergeContribution(acc.view, acc.context, contribution, options);
+}
+function wrapAsSdk(properties, context) {
+  const sdk = {
+    ...properties,
+    context,
+    getRegistry(qopts) {
+      return buildRegistry({
+        sdk,
+        meta: context.meta,
+        packageFilter: qopts?.package
+      });
+    }
+  };
+  return sdk;
+}
+function wrapAccumulatorAsSdk(acc) {
+  const { context: _ctx, ...rootKeys } = acc.view;
+  return wrapAsSdk(
+    rootKeys,
+    acc.context
+  );
+}
+function applyPluginToSdk(sdk, plugin, options) {
+  const context = sdk.context;
+  const contribution = splitPluginContribution(
+    plugin(sdk)
+  );
+  mergeContribution(sdk, context, contribution, {
+    callerLabel: "addPlugin",
+    override: options.override === true
+  });
+  return contribution;
+}
+function resolveStack(head) {
+  const entries = [];
+  let node = head;
+  while (node) {
+    entries.unshift({ apply: node.entry, override: node.override });
+    node = node.prev;
+  }
+  return entries;
+}
+function composeStackHooks(hooks) {
+  let composed = {};
+  for (const h of hooks) composed = buildHooks(composed, h);
+  return composed;
+}
+function collapseStackEntries(entries, callerLabel) {
+  return (outerSdk) => {
+    const { context: outerContext, ...outerProperties } = outerSdk ?? {};
+    const viewAcc = createPluginAccumulator(outerProperties, outerContext);
+    const contribsAcc = createPluginAccumulator();
+    const hooks = [];
+    for (const { apply, override } of entries) {
+      const contribution = splitPluginContribution(
+        apply(viewAcc.view)
+      );
+      const hookless = { ...contribution, hooks: {} };
+      applyPluginContribution(viewAcc, hookless, { callerLabel, override });
+      applyPluginContribution(contribsAcc, hookless, { callerLabel, override });
+      hooks.push(contribution.hooks);
+    }
+    const stackHooks = composeStackHooks(hooks);
+    viewAcc.context.hooks = buildHooks(viewAcc.context.hooks, stackHooks);
+    contribsAcc.context.hooks = stackHooks;
+    const { context: _ignored, ...contributedRoot } = contribsAcc.view;
+    return {
+      ...contributedRoot,
+      context: contribsAcc.context
+    };
+  };
+}
+function buildStackAccumulator(head, callerLabel) {
+  const entries = resolveStack(head);
+  const acc = createPluginAccumulator();
+  const hooks = [];
+  for (const { apply, override } of entries) {
+    const contribution = splitPluginContribution(
+      apply(acc.view)
+    );
+    applyPluginContribution(
+      acc,
+      { ...contribution, hooks: {} },
+      { callerLabel, override }
+    );
+    hooks.push(contribution.hooks);
+  }
+  acc.context.hooks = composeStackHooks(hooks);
+  return acc;
+}
+function composePlugins(...plugins) {
+  logDeprecation(
+    "composePlugins(...) is deprecated. Use createPluginStack().use(a).use(b).use(c).toPlugin({ name }) instead. The stack carries the same collision-detection and hook-composition behavior and supports per-step { override: true } for intentional duplicates."
+  );
+  let head = null;
+  for (const plugin of plugins) {
+    head = { entry: plugin, override: false, prev: head };
+  }
+  const entries = resolveStack(head);
+  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) {
+  const stack = {
+    use(plugin, options) {
+      const next = {
+        entry: plugin,
+        override: options?.override === true,
+        prev: head
+      };
+      return buildPluginStack(next, callerLabel);
+    },
+    toPlugin() {
+      const entries = resolveStack(head);
+      return collapseStackEntries(entries, callerLabel);
+    },
+    toSdk() {
+      return wrapAccumulatorAsSdk(
+        buildStackAccumulator(head, callerLabel)
+      );
+    }
+  };
+  return stack;
+}
+
+// src/model/shared.ts
+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) };
+}
+function makeId(name, namespace, kind = "leaf") {
+  validateName(name, kind);
+  if (namespace !== void 0) validateNamespace(namespace);
+  return namespace ? `${namespace}/${name}` : name;
+}
+var NAME_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+var SEGMENT_RE = /^@?[A-Za-z0-9._-]+$/;
+function validateName(name, kind) {
+  if (name === "") throw new Error("Plugin name must not be empty.");
+  if (kind === "leaf") {
+    if (!NAME_RE.test(name)) {
+      throw new Error(
+        `Plugin name "${name}" must be a valid JS identifier (it is the binding name).`
+      );
+    }
+  } else if (!SEGMENT_RE.test(name)) {
+    throw new Error(
+      `Plugin name "${name}" must be package-like (letters, digits, ".", "_", "-", optional leading "@") with no "/".`
+    );
+  }
+}
+function validateNamespace(namespace) {
+  if (namespace === "") throw new Error("Plugin namespace must not be empty.");
+  for (const segment of namespace.split("/")) {
+    if (!SEGMENT_RE.test(segment)) {
+      throw new Error(
+        `Plugin namespace "${namespace}" is invalid: each "/"-separated segment must be package-like (letters, digits, ".", "_", "-", optional leading "@").`
+      );
+    }
+  }
+}
+
+// src/model/types.ts
+var LEAF_META_KEYS = [
+  "description",
+  "categories",
+  "type",
+  "itemType",
+  "returnType",
+  "outputSchema",
+  "inputParameters",
+  "packages",
+  "experimental",
+  "confirm",
+  "deprecation",
+  "aliases",
+  "supportsJsonOutput"
+];
+
+// src/model/define.ts
+function normalizeImports(deps) {
+  if (!deps) return { plugins: [], bindings: [] };
+  const seen = /* @__PURE__ */ new Map();
+  const bindings = [];
+  const add = (binding, id, optional) => {
+    const priorId = seen.get(binding);
+    if (priorId !== void 0 && priorId !== id) {
+      throw new Error(
+        `Import binding "${binding}" is declared twice. Two different plugins ("${priorId}" and "${id}") bind the same name; wrap one in selectExports to rename it.`
+      );
+    }
+    if (priorId === void 0) {
+      seen.set(binding, id);
+      bindings.push(optional ? { binding, id, optional } : { binding, id });
+    }
+  };
+  for (const plugin of deps) {
+    if (plugin.pluginType === "aggregate") {
+      for (const [binding, child] of Object.entries(plugin.exports)) {
+        add(binding, child.id);
+      }
+    } else if (plugin.pluginType === "hook") {
+    } else {
+      add(plugin.name, plugin.id, plugin.optional);
+    }
+  }
+  return { plugins: deps, bindings };
+}
+function collectLeafMeta(config) {
+  let meta;
+  for (const key2 of LEAF_META_KEYS) {
+    if (config[key2] !== void 0) (meta ?? (meta = {}))[key2] = config[key2];
+  }
+  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 {
+    pluginType: "method",
+    name: config.name,
+    namespace: config.namespace,
+    id: makeId(config.name, config.namespace),
+    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 };
+  const gates = {
+    requireParameters: config.requireParameters
+  };
+  switch (config.type) {
+    case "static":
+      return {
+        ...base,
+        ...gates,
+        type: "static",
+        inputType: config.inputType,
+        placeholder: config.placeholder
+      };
+    case "constant":
+      return { ...base, ...gates, type: "constant", value: config.value };
+    case "info":
+      return { ...base, type: "info", text: config.text ?? "" };
+    case "object":
+      return {
+        ...base,
+        ...gates,
+        type: "object",
+        properties: config.properties,
+        definitions: config.definitions,
+        getProperties: config.getProperties
+      };
+    case "array":
+      return {
+        ...base,
+        ...gates,
+        type: "array",
+        items: config.items,
+        minItems: config.minItems,
+        maxItems: config.maxItems,
+        itemValueType: config.itemValueType,
+        definitions: config.definitions
+      };
+    default:
+      return {
+        ...base,
+        ...gates,
+        type: "dynamic",
+        inputType: config.inputType,
+        placeholder: config.placeholder,
+        getContext: config.getContext,
+        listItems: config.listItems,
+        prompt: config.prompt,
+        tryResolveWithoutPrompt: config.tryResolveWithoutPrompt,
+        tryResolveFromSearch: config.tryResolveFromSearch
+      };
+  }
+}
+function defineFormatter(config) {
+  const deps = normalizeImports(config.imports);
+  return {
+    imports: deps.plugins,
+    importBindings: deps.bindings,
+    getContext: config.getContext,
+    format: config.format
+  };
+}
+function declareMethod(config) {
+  const { name, namespace } = parseId(config.id);
+  const id = makeId(name, namespace);
+  return {
+    pluginType: "method",
+    name,
+    namespace,
+    id,
+    standIn: true,
+    imports: [],
+    importBindings: [],
+    run: () => {
+      throw new Error(
+        `Plugin "${id}" is a stand-in (declareMethod) with no implementation. Register the real plugin under this id.`
+      );
+    }
+  };
+}
+function defineProperty(config) {
+  const deps = normalizeImports(config.imports);
+  return {
+    pluginType: "property",
+    name: config.name,
+    namespace: config.namespace,
+    id: makeId(config.name, config.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)
+  };
+}
+function declareProperty(config) {
+  const { name, namespace } = parseId(config.id);
+  return {
+    pluginType: "property",
+    name,
+    namespace,
+    id: makeId(name, namespace),
+    standIn: true,
+    imports: [],
+    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 {
+    pluginType: "aggregate",
+    name,
+    namespace,
+    id: makeId(name, namespace, "aggregate"),
+    standIn: true,
+    imports: [],
+    importBindings: [],
+    exports: normalizeExports(config.exports)
+  };
+}
+function definePlugin(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 {
+    pluginType: "aggregate",
+    name: config.name,
+    namespace: config.namespace,
+    id: makeId(config.name, config.namespace, "aggregate"),
+    // 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)
+  };
+}
+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 = {};
+  const add = (binding, leaf) => {
+    const existing = out[binding];
+    if (existing && existing.id !== leaf.id) {
+      throw new Error(
+        `definePlugin: duplicate export binding "${binding}". Two different plugins ("${existing.id}" and "${leaf.id}") bind the same name; wrap one in selectExports to rename it.`
+      );
+    }
+    out[binding] = leaf;
+  };
+  for (const element of exports) {
+    if (element.pluginType === "aggregate") {
+      for (const [binding, child] of Object.entries(element.exports)) {
+        add(binding, child);
+      }
+    } else {
+      add(element.name, element);
+    }
+  }
+  return out;
+}
+
+// src/model/exports.ts
+var selectSeq = 0;
+function selectExports(source, ...specs) {
+  const selected = {};
+  const pick = (binding, fromName) => {
+    const child = source.exports[fromName];
+    if (!child) {
+      throw new Error(
+        `selectExports: "${source.id}" has no export "${fromName}".`
+      );
+    }
+    selected[binding] = child;
+  };
+  for (const spec of specs) {
+    if (typeof spec === "string") {
+      pick(spec, spec);
+    } else {
+      for (const [newName, fromName] of Object.entries(spec)) {
+        pick(newName, fromName);
+      }
+    }
+  }
+  const id = `${source.id}#select:${selectSeq++}`;
+  return {
+    pluginType: "aggregate",
+    name: makeId(`select`, source.name, "aggregate"),
+    id,
+    // Depend on the source so it is materialized; the selected bindings resolve
+    // to the source's own leaves (kept identity).
+    imports: [source],
+    importBindings: [],
+    exports: selected
+    // 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,
+    namespace: config.namespace,
+    id: makeId(config.name, config.namespace, "aggregate"),
+    imports: [],
+    importBindings: [],
+    run: fn
+  };
+}
+function defineLegacyMerge(args) {
+  logDeprecation(
+    "defineLegacyMerge() is deprecated. Build directly with createSdk(root, { configuration }) instead."
+  );
+  return {
+    pluginType: "legacy-merge",
+    name: args.name,
+    namespace: args.namespace,
+    id: makeId(args.name, args.namespace, "aggregate"),
+    legacy: fromFunctionPlugin(args.legacy, {
+      name: args.name,
+      namespace: args.namespace
+    }),
+    plugin: args.plugin
+  };
+}
+function legacyGraphEntry(name, value, pluginMeta) {
+  const { inputSchema, ...rest } = pluginMeta ?? {};
+  const meta = Object.keys(rest).length ? rest : void 0;
+  if (typeof value === "function") {
+    return {
+      pluginType: "method",
+      name,
+      value,
+      chain: [],
+      ...inputSchema ? { inputSchema } : {},
+      ...meta ? { meta } : {}
+    };
+  }
+  return { pluginType: "property", name, value, ...meta ? { meta } : {} };
+}
+
+// src/model/builtins.ts
+import { z as z2 } from "zod";
+
+// src/model/registry-support.ts
+function adaptLegacyFormatter(legacy, sdk) {
+  const legacyFetch = legacy.fetch;
+  return {
+    getContext: legacyFetch ? async ({ items, input, context }) => {
+      let ctx = context;
+      for (const item of items) {
+        ctx = await legacyFetch(sdk, input, item, ctx);
+      }
+      return ctx;
+    } : void 0,
+    format: ({ item, context }) => legacy.format(item, context)
+  };
+}
+function normalizeFormatter(entry, sdk) {
+  if (entry.pluginType !== "method") return void 0;
+  if (entry.formatter) return entry.formatter;
+  const legacy = entry.meta?.formatter;
+  return legacy ? adaptLegacyFormatter(legacy, sdk) : void 0;
+}
+function normalizeBoundResolvers(entry) {
+  if (entry.pluginType !== "method") return void 0;
+  return entry.resolvers;
+}
+function methodPositional(entry) {
+  if (entry.pluginType !== "method") return void 0;
+  return entry.positional;
+}
+function pluginEntryMeta(entry) {
+  if (entry.pluginType === "method" && entry.meta) {
+    return entry.inputSchema ? { ...entry.meta, inputSchema: entry.inputSchema } : entry.meta;
+  }
+  if (entry.pluginType === "property" && entry.meta) return entry.meta;
+  return void 0;
+}
+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 entries = {};
+  for (const [binding, id] of Object.entries(context.surface)) {
+    const entry = context.plugins[id];
+    if (!entry || entry.pluginType === "aggregate") continue;
+    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, 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,
+    ...collectSurfaceProjection(context, surface),
+    packageFilter
+  });
+}
+
+// src/model/builtins.ts
+var coreOptionsPluginRef = declareOptionalProperty({ id: CORE_OPTIONS_ID });
+var dangerousContextPlugin = {
+  pluginType: "property",
+  name: "context",
+  namespace: "kitcore",
+  id: "kitcore/context",
+  imports: [],
+  importBindings: [],
+  privileged: true
+};
+var getRegistryPlugin = defineMethod({
+  name: "getRegistry",
+  namespace: "kitcore",
+  imports: [dangerousContextPlugin],
+  inputSchema: z2.object({ package: z2.string().optional() }).optional(),
+  run: ({ imports, input }) => buildSurfaceRegistry(imports.context, input?.package)
+});
+
+// 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.for("kitcore.context");
+function getContext(sdk) {
+  return sdk[CONTEXT];
+}
+function isResolverRef(value) {
+  return "ref" in value;
+}
+function nestedResolvers(resolver) {
+  const out = [];
+  if (resolver.type === "object") {
+    for (const field of Object.values(resolver.properties ?? {})) {
+      if (!isResolverRef(field.resolver)) out.push(field.resolver);
+    }
+    out.push(...Object.values(resolver.definitions ?? {}));
+  } else if (resolver.type === "array") {
+    if (!isResolverRef(resolver.items)) out.push(resolver.items);
+    out.push(...Object.values(resolver.definitions ?? {}));
+  }
+  return out;
+}
+function resolverImportEdges(resolver) {
+  const out = [...resolver.imports];
+  for (const child of nestedResolvers(resolver)) {
+    out.push(...resolverImportEdges(child));
+  }
+  return out;
+}
+function methodAttachmentEdges(plugin) {
+  const out = [];
+  if (plugin.resolvers) {
+    for (const resolver of Object.values(plugin.resolvers)) {
+      out.push(...resolverImportEdges(resolver));
+    }
+  }
+  if (plugin.formatter) out.push(...plugin.formatter.imports);
+  return out;
+}
+function edgesOf(plugin) {
+  if (plugin.pluginType === "aggregate") {
+    return [...Object.values(plugin.exports), ...plugin.imports];
+  }
+  if (plugin.pluginType === "method") {
+    return [...plugin.imports, ...methodAttachmentEdges(plugin)];
+  }
+  return plugin.imports;
+}
+function isStandIn(plugin) {
+  return (plugin.pluginType === "method" || plugin.pluginType === "property" || plugin.pluginType === "aggregate") && plugin.standIn === true;
+}
+function topoOrder(descriptors) {
+  const order = [];
+  const visited = /* @__PURE__ */ new Set();
+  const visit = (id) => {
+    if (visited.has(id)) return;
+    visited.add(id);
+    const descriptor = descriptors.get(id);
+    if (descriptor) for (const edge of edgesOf(descriptor)) visit(edge.id);
+    order.push(id);
+  };
+  for (const id of descriptors.keys()) visit(id);
+  return order;
+}
+function collectPlugins(root, materialized = /* @__PURE__ */ new Set(), configuration) {
+  const byId = /* @__PURE__ */ new Map();
+  const visit = (plugin) => {
+    if (materialized.has(plugin.id)) return;
+    const existing = byId.get(plugin.id);
+    if (existing === plugin) return;
+    if (existing) {
+      const bothReal = !isStandIn(existing) && !isStandIn(plugin);
+      if (bothReal) {
+        throw new Error(
+          `createSdk: duplicate plugin id "${plugin.id}". Two different plugins registered under the same id.`
+        );
+      }
+      if (isStandIn(existing) && !isStandIn(plugin)) {
+        byId.set(plugin.id, plugin);
+        for (const edge of edgesOf(plugin)) visit(edge);
+      }
+      return;
+    }
+    byId.set(plugin.id, plugin);
+    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.`
+      );
+    }
+  }
+  return byId;
+}
+function bindValue(target, key2, entry, callType = "surface") {
+  if (entry.pluginType === "property" && entry.getValue) {
+    Object.defineProperty(target, key2, {
+      get: entry.getValue,
+      enumerable: true,
+      configurable: true
+    });
+  } else {
+    const value = callType === "internal" && entry.pluginType === "method" ? entry.internalValue ?? entry.value : entry.value;
+    Object.defineProperty(target, key2, {
+      value,
+      writable: true,
+      enumerable: true,
+      configurable: true
+    });
+  }
+}
+function buildSurface(context, ...maps) {
+  const sdk = {};
+  for (const map of maps) {
+    Object.defineProperties(sdk, Object.getOwnPropertyDescriptors(map));
+  }
+  sdk.context = context;
+  sdk[CONTEXT] = context;
+  return sdk;
+}
+function buildImports(plugins, importBindings) {
+  const imports = {};
+  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;
+}
+function mirrorLegacyRootKeys(context, rootKeys, meta) {
+  const exports = {};
+  for (const [name, value] of Object.entries(rootKeys)) {
+    context.plugins[name] = legacyGraphEntry(name, value, meta[name]);
+    exports[name] = value;
+  }
+  return exports;
+}
+function recordExportSurface(context, exports) {
+  for (const [binding, child] of Object.entries(exports)) {
+    context.surface[binding] = child.id;
+  }
+}
+function materialize(descriptors, context) {
+  const states = /* @__PURE__ */ new Map();
+  runLegacyPass(descriptors, context);
+  buildMethodEntries(descriptors, context, states);
+  buildEagerArtifacts(descriptors, context, states);
+  bindAttachments(descriptors, context);
+  resolveAggregates(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":
+      return {
+        type: "static",
+        requireParameters: resolver.requireParameters,
+        inputType: resolver.inputType,
+        placeholder: resolver.placeholder
+      };
+    case "constant":
+      return {
+        type: "constant",
+        value: resolver.value,
+        requireParameters: resolver.requireParameters
+      };
+    case "info":
+      return { type: "info", text: resolver.text };
+    case "object": {
+      const imports = buildImports(plugins, resolver.importBindings);
+      const bound = {
+        type: "object",
+        requireParameters: resolver.requireParameters
+      };
+      if (resolver.properties)
+        bound.properties = bindFields(resolver.properties, plugins);
+      if (resolver.definitions)
+        bound.definitions = bindDefinitions(resolver.definitions, plugins);
+      const { getProperties } = resolver;
+      if (getProperties)
+        bound.getProperties = ({ input }) => getProperties({ imports, input });
+      return bound;
+    }
+    case "array": {
+      const bound = {
+        type: "array",
+        requireParameters: resolver.requireParameters,
+        minItems: resolver.minItems,
+        maxItems: resolver.maxItems,
+        itemValueType: resolver.itemValueType,
+        items: isResolverRef(resolver.items) ? resolver.items : bindResolver(resolver.items, plugins)
+      };
+      if (resolver.definitions)
+        bound.definitions = bindDefinitions(resolver.definitions, plugins);
+      return bound;
+    }
+    case "dynamic": {
+      const imports = buildImports(plugins, resolver.importBindings);
+      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 (tryResolveWithoutPrompt) {
+        bound.tryResolveWithoutPrompt = ({ input }) => tryResolveWithoutPrompt({ imports, input });
+      }
+      if (tryResolveFromSearch) {
+        bound.tryResolveFromSearch = ({ input, search }) => tryResolveFromSearch({ imports, input, search });
+      }
+      return bound;
+    }
+    default: {
+      const unhandled = resolver;
+      throw new Error(
+        `unhandled resolver kind: ${unhandled.type}`
+      );
+    }
+  }
+}
+function bindFields(fields, plugins) {
+  const out = {};
+  for (const [key2, field] of Object.entries(fields)) {
+    out[key2] = {
+      ...field,
+      resolver: isResolverRef(field.resolver) ? field.resolver : bindResolver(field.resolver, plugins)
+    };
+  }
+  return out;
+}
+function bindDefinitions(definitions, plugins) {
+  const out = {};
+  for (const [key2, def] of Object.entries(definitions)) {
+    out[key2] = bindResolver(def, plugins);
+  }
+  return out;
+}
+function bindFormatter(formatter, plugins) {
+  const imports = buildImports(plugins, formatter.importBindings);
+  const bound = { format: formatter.format };
+  const { getContext: getContext2 } = formatter;
+  if (getContext2)
+    bound.getContext = ({ items, input, context }) => getContext2({ imports, items, input, context });
+  return bound;
+}
+function bindAttachments(descriptors, context) {
+  const plugins = context.plugins;
+  for (const [id, descriptor] of descriptors) {
+    if (descriptor.pluginType !== "method") continue;
+    const entry = plugins[id];
+    if (!entry || entry.pluginType !== "method") continue;
+    if (descriptor.resolvers) {
+      const bound = {};
+      for (const [param, resolver] of Object.entries(descriptor.resolvers)) {
+        bound[param] = bindResolver(resolver, plugins);
+      }
+      entry.resolvers = bound;
+    }
+    if (descriptor.formatter) {
+      entry.formatter = bindFormatter(descriptor.formatter, plugins);
+    }
+  }
+}
+function runLegacyPass(descriptors, context) {
+  const plugins = context.plugins;
+  const compatView = new Proxy(
+    {},
+    {
+      get: (_target, prop) => {
+        if (prop === "context") return context;
+        const entry = plugins[prop];
+        return entry?.value;
+      }
+    }
+  );
+  for (const id of topoOrder(descriptors)) {
+    const descriptor = descriptors.get(id);
+    if (!descriptor || descriptor.pluginType !== "legacy") continue;
+    const { rootKeys, meta, hooks, contextRest } = splitPluginContribution(
+      descriptor.run(compatView)
+    );
+    Object.assign(context.meta, meta);
+    Object.assign(context, contextRest);
+    context.hooks = buildHooks(context.hooks, hooks);
+    const exports = mirrorLegacyRootKeys(context, rootKeys, meta);
+    if (!("getRegistry" in exports)) {
+      let getRegistry2 = function(options) {
+        const sdk = this ?? exports;
+        const projection = collectSurfaceProjection(context, sdk);
+        Object.assign(projection.meta, context.meta);
+        return buildRegistry({
+          sdk,
+          ...projection,
+          packageFilter: options?.package
+        });
+      };
+      var getRegistry = getRegistry2;
+      exports.getRegistry = getRegistry2;
+      plugins.getRegistry = {
+        pluginType: "method",
+        name: "getRegistry",
+        value: getRegistry2,
+        chain: []
+      };
+    }
+    plugins[id] = { pluginType: "aggregate", name: descriptor.name, exports };
+  }
+}
+function buildMethodEntries(descriptors, context, states) {
+  const plugins = context.plugins;
+  for (const [id, descriptor] of descriptors) {
+    if (descriptor.pluginType !== "method") continue;
+    const out = normalizeOutput(descriptor.output);
+    const entry = {
+      pluginType: "method",
+      name: descriptor.name,
+      chain: [],
+      inputSchema: descriptor.inputSchema,
+      // Derive the presentation type from the output mode when the author did
+      // not set one; an explicit meta.type (e.g. "create") still wins.
+      meta: out.type === "raw" || descriptor.meta?.type ? descriptor.meta : { ...descriptor.meta, type: out.type },
+      output: out,
+      // Replaced below; never called.
+      value: () => void 0
+    };
+    const callRun = (input) => descriptor.run({
+      imports: buildImports(plugins, descriptor.importBindings),
+      state: states.get(id),
+      input
+    });
+    const fold = (coreFn) => (input) => {
+      let next = coreFn;
+      for (const wrap of entry.chain) {
+        const inner = next;
+        next = (i) => wrap.run({
+          imports: buildImports(plugins, wrap.owner.importBindings),
+          next: inner,
+          input: i,
+          // Overwritten by the chain item's own closure with the owning
+          // hook's setup state.
+          state: void 0
+        });
+      }
+      return next(input);
+    };
+    const sdk = { context };
+    if (out.type === "list") {
+      entry.value = createPaginatedFunction(
+        fold(callRun),
+        {
+          sdk,
+          schema: descriptor.inputSchema,
+          name: descriptor.name,
+          defaultPageSize: out.defaultPageSize,
+          adaptPage: out.adaptPage,
+          getDeprecation: () => entry.meta?.deprecation
+        }
+      );
+    } else if (out.type === "item") {
+      const itemCore = async (input) => ({
+        data: await callRun(input)
+      });
+      entry.value = createFunction(
+        fold(itemCore),
+        {
+          sdk,
+          schema: descriptor.inputSchema,
+          name: descriptor.name,
+          getDeprecation: () => entry.meta?.deprecation
+        }
+      );
+    } else {
+      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 pack = (args) => {
+        const packed = {};
+        names.forEach((name, i) => {
+          if (i < args.length) packed[name] = args[i];
+        });
+        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;
+  }
+}
+function buildEagerArtifacts(descriptors, context, states) {
+  const plugins = context.plugins;
+  const built = /* @__PURE__ */ new Set();
+  const building = /* @__PURE__ */ new Set();
+  const ensureBuilt = (id) => {
+    if (built.has(id)) return;
+    const descriptor = descriptors.get(id);
+    if (!descriptor || descriptor.pluginType === "aggregate" || descriptor.pluginType === "legacy" || descriptor.pluginType === "method-override" || isStandIn(descriptor)) {
+      built.add(id);
+      return;
+    }
+    if (building.has(id)) {
+      throw new Error(`createSdk: dependency cycle at "${id}".`);
+    }
+    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,
+        descriptor.setup ? descriptor.setup({
+          imports: buildImports(plugins, descriptor.importBindings)
+        }) : void 0
+      );
+    } else {
+      states.set(
+        id,
+        descriptor.setup ? descriptor.setup({
+          imports: buildImports(plugins, descriptor.importBindings)
+        }) : void 0
+      );
+      if (descriptor.privileged) {
+        plugins[id] = {
+          pluginType: "property",
+          name: descriptor.name,
+          value: context,
+          meta: descriptor.meta,
+          dynamicMembers: descriptor.dynamicMembers
+        };
+      } else if (descriptor.get) {
+        const get = descriptor.get;
+        const importBindings = descriptor.importBindings;
+        plugins[id] = {
+          pluginType: "property",
+          name: descriptor.name,
+          getValue: () => get({
+            imports: buildImports(plugins, importBindings),
+            state: states.get(id)
+          }),
+          meta: descriptor.meta,
+          dynamicMembers: descriptor.dynamicMembers
+        };
+      } else {
+        plugins[id] = {
+          pluginType: "property",
+          name: descriptor.name,
+          value: descriptor.value,
+          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) {
+    if (descriptor.pluginType !== "aggregate") continue;
+    const exports = {};
+    for (const [binding, child] of Object.entries(descriptor.exports)) {
+      bindValue(exports, binding, plugins[child.id]);
+    }
+    plugins[id] = { pluginType: "aggregate", name: descriptor.name, exports };
+  }
+}
+function assembleMiddleware(descriptors, context, states) {
+  const plugins = context.plugins;
+  for (const id of topoOrder(descriptors)) {
+    const descriptor = descriptors.get(id);
+    if (!descriptor || descriptor.pluginType !== "hook" || !descriptor.wrap) {
+      continue;
+    }
+    for (const [targetBinding, fn] of Object.entries(descriptor.wrap)) {
+      const edge = descriptor.importBindings.find(
+        (b) => b.binding === targetBinding
+      );
+      if (!edge) {
+        throw new Error(
+          `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: wrap target "${targetBinding}" in hook "${id}" does not resolve to a method.`
+        );
+      }
+      if (target.output?.type === "list") {
+        throw new Error(
+          `createSdk: wrap target "${targetBinding}" in hook "${id}" resolves to a list-output method, which does not support wrapping yet.`
+        );
+      }
+      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, options) {
+  const context = {
+    plugins: {},
+    meta: {},
+    hooks: {},
+    surface: {},
+    disposers: []
+  };
+  if (root.pluginType === "legacy-merge") {
+    const { legacy, plugin } = root;
+    const collectRoot = {
+      pluginType: "aggregate",
+      name: root.name,
+      id: `${root.id}:merge`,
+      imports: [legacy, plugin],
+      importBindings: [],
+      exports: {}
+    };
+    const plugins2 = materialize(
+      collectPlugins(collectRoot, void 0, options?.configuration),
+      context
+    );
+    const legacyExports = plugins2[legacy.id].exports;
+    let pluginSurface;
+    if (plugin.pluginType === "aggregate") {
+      pluginSurface = plugins2[plugin.id].exports;
+    } else {
+      pluginSurface = {};
+      bindValue(pluginSurface, plugin.name, plugins2[plugin.id]);
+    }
+    for (const key2 of Object.keys(legacyExports)) context.surface[key2] = key2;
+    if (plugin.pluginType === "aggregate") {
+      recordExportSurface(context, plugin.exports);
+    } else {
+      context.surface[plugin.name] = plugin.id;
+    }
+    return buildSurface(context, legacyExports, pluginSurface);
+  }
+  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);
+    bindValue(sdk, root.name, plugins[root.id]);
+    return sdk;
+  }
+  if (root.pluginType === "aggregate")
+    recordExportSurface(context, root.exports);
+  return buildSurface(context, plugins[root.id].exports);
+}
+function addModelPlugin(sdk, plugin, options = {}) {
+  const override = options.override === true;
+  const context = getContext(sdk);
+  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)) {
+    throw new Error(
+      `addPlugin: cannot override already-materialized plugin "${plugin.id}" on the incremental path. Rebuild the SDK with the replacement via createSdk.`
+    );
+  }
+  materialize(collectPlugins(plugin, materialized), context);
+  if (plugin.pluginType === "hook") return;
+  const entry = context.plugins[plugin.id];
+  if (entry.pluginType === "aggregate") {
+    Object.defineProperties(
+      sdk,
+      Object.getOwnPropertyDescriptors(entry.exports)
+    );
+    for (const [binding, child] of Object.entries(
+      plugin.exports
+    )) {
+      context.surface[binding] = child.id;
+    }
+  } else {
+    bindValue(sdk, plugin.name, entry);
+    context.surface[plugin.name] = plugin.id;
+  }
+}
+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;
+      }
+    }
+    return;
+  }
+  if (plugin.pluginType === "method-override") {
+    applyMethodOverride(
+      getContext(sdk),
+      plugin
+    );
+    return;
+  }
+  addModelPlugin(
+    sdk,
+    plugin,
+    options ?? {}
+  );
+}
+
+// src/model/resolution/controller.ts
+import { z as z4 } from "zod";
+
+// src/types/signals.ts
+var CORE_SIGNAL_SYMBOL = Symbol.for("kitcore.signal");
+var CoreSignal = class extends Error {
+  constructor(message) {
+    super(message);
+    Object.setPrototypeOf(this, new.target.prototype);
+    Object.defineProperty(this, CORE_SIGNAL_SYMBOL, {
+      value: true,
+      enumerable: false,
+      configurable: true,
+      writable: false
+    });
+  }
+};
+function isCoreSignal(value) {
+  return Boolean(
+    value && typeof value === "object" && value[CORE_SIGNAL_SYMBOL] === true
+  );
+}
+var CoreCancelledSignal = class extends CoreSignal {
+  constructor(message = "resolution cancelled") {
+    super(message);
+    this.name = "CoreCancelledSignal";
+    this.code = "CANCELLED";
+  }
+};
+
+// src/model/resolution/plan.ts
+import { z as z3 } from "zod";
+function unwrap(schema) {
+  let inner = schema;
+  let required = true;
+  for (; ; ) {
+    if (inner instanceof z3.ZodOptional) {
+      required = false;
+      inner = inner._zod.def.innerType;
+    } else if (inner instanceof z3.ZodDefault) {
+      required = false;
+      inner = inner._zod.def.innerType;
+    } else if (inner instanceof z3.ZodNullable) {
+      inner = inner._zod.def.innerType;
+    } else {
+      break;
+    }
+  }
+  return { inner, required };
+}
+function valueTypeOf(inner) {
+  if (inner instanceof z3.ZodString) return "string";
+  if (inner instanceof z3.ZodNumber) return "number";
+  if (inner instanceof z3.ZodBoolean) return "boolean";
+  if (inner instanceof z3.ZodEnum) return "string";
+  if (inner instanceof z3.ZodArray) return "array";
+  if (inner instanceof z3.ZodObject) return "object";
+  return void 0;
+}
+function staticChoicesOf(inner) {
+  if (inner instanceof z3.ZodEnum) {
+    const values = inner.options;
+    return values.map((value) => ({ label: value, value }));
+  }
+  return void 0;
+}
+function objectShape(schema) {
+  const { inner } = schema ? unwrap(schema) : { inner: void 0 };
+  if (inner instanceof z3.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));
+  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;
+}
+function planParameters(entry) {
+  const shape = objectShape(entry.inputSchema);
+  const resolvers = entry.boundResolvers ?? {};
+  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 };
+    const resolver = resolvers[name];
+    return {
+      name,
+      required,
+      valueType: inner ? valueTypeOf(inner) : void 0,
+      staticChoices: inner ? staticChoicesOf(inner) : void 0,
+      resolver,
+      requires: resolver?.requireParameters ?? []
+    };
+  });
+  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
+function getAtPath(root, path) {
+  let node = root;
+  for (const seg of path) {
+    if (node == null || typeof node !== "object") return void 0;
+    node = node[seg];
+  }
+  return node;
+}
+function setAtPath(root, path, value) {
+  let node = root;
+  for (let i = 0; i < path.length - 1; i++) {
+    const seg = path[i];
+    if (node[seg] == null || typeof node[seg] !== "object") node[seg] = {};
+    node = node[seg];
+  }
+  node[path[path.length - 1]] = value;
+}
+var key = (path) => path.join(".");
+function isSettled(state, path) {
+  return state.settled.includes(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));
+}
+function coerce(leaf, raw) {
+  if (typeof raw !== "string") return raw;
+  if (leaf.valueType === "number") {
+    const n = Number(raw);
+    return raw.trim() !== "" && !Number.isNaN(n) ? n : raw;
+  }
+  if (leaf.valueType === "boolean") {
+    if (raw === "true") return true;
+    if (raw === "false") return false;
+  }
+  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?.({
+    items: state.listing?.items ?? [],
+    input: mergeInput(state.resolved, leaf.extraInput),
+    context
+  });
+  if (!config?.validate) return null;
+  const verdict = config.validate(value);
+  if (verdict === true) return null;
+  return typeof verdict === "string" ? verdict : `${leaf.name}: invalid value`;
+}
+function isRef(r) {
+  return typeof r === "object" && r !== null && "ref" in r;
+}
+function toLeaf(name, field, definitions) {
+  let resolver;
+  let extraInput;
+  if (isRef(field.resolver)) {
+    resolver = definitions?.[field.resolver.ref];
+    extraInput = field.resolver.input;
+  } else {
+    resolver = field.resolver;
+  }
+  return {
+    name,
+    required: field.required ?? false,
+    label: field.label,
+    resolver,
+    extraInput,
+    // Carry the field's value type so nested answers coerce (number/boolean)
+    // the same way top-level params do. Without this a nested `z.number()`
+    // field's typed answer stays a string and fails final validation.
+    valueType: field.valueType,
+    requires: resolver?.requireParameters ?? []
+  };
+}
+async function objectChildren(resolver, input) {
+  if (resolver.properties) {
+    return Object.entries(resolver.properties).map(
+      ([name, field]) => toLeaf(name, field, resolver.definitions)
+    );
+  }
+  if (!resolver.getProperties) return [];
+  const fields = await resolver.getProperties({ input });
+  return Object.entries(fields).map(([name, field]) => {
+    if (!isRef(field.resolver) && (field.resolver.imports?.length ?? 0) > 0) {
+      throw new Error(
+        `dynamic object field "${name}" inlines an import-bearing resolver; use { ref } into the object's definitions so its imports bind`
+      );
+    }
+    return toLeaf(name, field, resolver.definitions);
+  });
+}
+function arrayItem(resolver) {
+  const items = resolver.items;
+  const valueType = resolver.itemValueType;
+  if (isRef(items)) {
+    return {
+      name: "",
+      required: true,
+      resolver: resolver.definitions?.[items.ref],
+      extraInput: items.input,
+      valueType,
+      requires: []
+    };
+  }
+  return {
+    name: "",
+    required: true,
+    resolver: items,
+    valueType,
+    requires: []
+  };
+}
+function autoSettles(resolver) {
+  return resolver.type === "constant" || resolver.type === "info";
+}
+function mergeInput(input, extra) {
+  return extra ? { ...input, ...extra } : input;
+}
+async function childrenAt(ctx, path, resolved) {
+  if (path.length === 0) return ctx.parameters;
+  const leaf = await leafAt(ctx, path, resolved);
+  if (!leaf?.resolver || leaf.resolver.type !== "object") return [];
+  return objectChildren(leaf.resolver, mergeInput(resolved, leaf.extraInput));
+}
+async function leafAt(ctx, path, resolved) {
+  let children = ctx.parameters;
+  let leaf;
+  for (let i = 0; i < path.length; i++) {
+    const seg = path[i];
+    if (typeof seg === "number") {
+      if (leaf?.resolver?.type !== "array") return void 0;
+      leaf = arrayItem(leaf.resolver);
+    } else {
+      leaf = children.find((c) => c.name === seg);
+      if (!leaf) return void 0;
+    }
+    if (i < path.length - 1 && typeof path[i + 1] === "string") {
+      if (leaf?.resolver?.type !== "object") return void 0;
+      children = await objectChildren(
+        leaf.resolver,
+        mergeInput(resolved, leaf.extraInput)
+      );
+    }
+  }
+  return leaf;
+}
+async function arrayInfoAt(ctx, path, resolved) {
+  const leaf = await leafAt(ctx, path, resolved);
+  const resolver = leaf?.resolver;
+  if (resolver?.type !== "array") {
+    throw new Error(`expected an array resolver at "${key(path)}"`);
+  }
+  return {
+    min: resolver.minItems ?? 0,
+    max: resolver.maxItems ?? Infinity,
+    item: { ...arrayItem(resolver), name: String(path[path.length - 1]) }
+  };
+}
+async function firstPage(result) {
+  const page = await result;
+  return {
+    data: Array.isArray(page?.data) ? page.data : [],
+    nextCursor: page?.nextCursor
+  };
+}
+async function resolveContext(leaf, input) {
+  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?.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],
+    cursor: page.nextCursor,
+    search: opts.search,
+    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 (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 resolver = leaf.resolver?.type === "dynamic" ? leaf.resolver : void 0;
+  const config = resolver?.prompt?.({
+    items: listing.items,
+    input: mergeInput(input, leaf.extraInput),
+    context
+  });
+  const multiple = config?.type === "checkbox";
+  return {
+    type: "select",
+    // 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)
+  };
+}
+function toControllerError(error) {
+  if (error instanceof Error) {
+    const code = error.code;
+    return {
+      name: error.name,
+      message: error.message,
+      ...typeof code === "string" ? { code } : {}
+    };
+  }
+  return { name: "Error", message: String(error) };
+}
+function failedResult(state, name, error) {
+  return {
+    state,
+    result: {
+      status: "failed",
+      error: toControllerError(error),
+      question: {
+        type: "select",
+        message: `Could not load options for ${name}.`,
+        choices: [],
+        actions: [AFFORDANCE.retry, AFFORDANCE.cancel]
+      }
+    }
+  };
+}
+async function buildQuestion(leaf, input) {
+  const optional = !leaf.required;
+  const resolver = leaf.resolver;
+  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),
+      listing
+    };
+  }
+  if (leaf.staticChoices) {
+    const actions2 = [AFFORDANCE.choose];
+    if (optional) actions2.push(AFFORDANCE.skip);
+    return {
+      question: {
+        type: "select",
+        message: `Select ${leaf.name}:`,
+        choices: leaf.staticChoices,
+        actions: actions2
+      }
+    };
+  }
+  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",
+      // 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: textSource?.placeholder,
+      actions
+    }
+  };
+}
+function collectionQuestion(t) {
+  const actions = [AFFORDANCE.add];
+  if (t.count >= t.min) actions.push(AFFORDANCE.done);
+  return {
+    type: "collection",
+    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;
+    // omit it so the question round-trips across the wall as plain data.
+    ...Number.isFinite(t.max) ? { max: t.max } : {},
+    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)
+    setAtPath(state.resolved, path, []);
+  if (!state.interactive) {
+    settle(state, path);
+    return null;
+  }
+  const { min, max, item } = await arrayInfoAt(ctx, path, state.resolved);
+  const items = getAtPath(state.resolved, path);
+  const len = items.length;
+  const itemType = item.resolver?.type;
+  if (len > 0 && (itemType === "object" || itemType === "array")) {
+    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 };
+  settle(state, path);
+  return null;
+}
+function seedItemSlot(state, itemPath, item) {
+  const type = item.resolver?.type;
+  if (type === "object") {
+    setAtPath(state.resolved, itemPath, {});
+    return "object";
+  }
+  if (type === "array") {
+    setAtPath(state.resolved, itemPath, []);
+    return "array";
+  }
+  return "leaf";
+}
+async function descendItem(ctx, state, arrayPath, index, item) {
+  const itemPath = [...arrayPath, index];
+  const kind = seedItemSlot(state, itemPath, item);
+  if (kind === "object") return findNext(ctx, state, itemPath);
+  if (kind === "array") return findInArray(ctx, state, itemPath);
+  return { kind: "leaf", path: itemPath, leaf: item };
+}
+async function findNext(ctx, state, path = []) {
+  const container = getAtPath(state.resolved, path) ?? {};
+  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 || 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 (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") {
+      const inner = await findInArray(ctx, state, childPath);
+      if (inner) return inner;
+      continue;
+    }
+    if (container[leaf.name] !== void 0 || isSettled(state, childPath))
+      continue;
+    return { kind: "leaf", path: childPath, leaf };
+  }
+  return null;
+}
+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;
+    return {
+      state,
+      result: {
+        status: "ask",
+        question,
+        ...opts.error ? { error: opts.error } : {}
+      }
+    };
+  } catch (error) {
+    state.listing = { items: [], exhausted: false };
+    return failedResult(state, leaf.name, error);
+  }
+}
+async function advance(ctx, state) {
+  for (; ; ) {
+    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 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);
+      settle(state, path);
+      continue;
+    }
+    if (!state.interactive) {
+      if (!leaf.required) {
+        settle(state, path);
+        continue;
+      }
+    } else if (!leaf.required && !leaf.resolver) {
+      settle(state, path);
+      continue;
+    }
+    return askLeaf(state, path, leaf);
+  }
+}
+async function start(ctx, input = {}, interactive = true) {
+  return advance(ctx, {
+    method: ctx.method,
+    resolved: { ...input },
+    settled: [],
+    interactive
+  });
+}
+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" } };
+  }
+  const path = state.current;
+  if (!path) throw new Error("step called with no outstanding question");
+  const leaf = await leafAt(ctx, path, state.resolved);
+  if (leaf && (action.type === "search" || action.type === "more" || action.type === "retry")) {
+    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];
+    if (seedItemSlot(state, itemPath, item) === "leaf")
+      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) {
+          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,
+        path,
+        leaf ? coerce(leaf, action.value) : action.value
+      );
+      break;
+    }
+    case "skip":
+      settle(state, path);
+      break;
+    default:
+      throw new Error(`action "${action.type}" is not supported here`);
+  }
+  delete state.current;
+  delete state.listing;
+  return advance(ctx, state);
+}
+async function refine(ctx, state, leaf, path, action) {
+  const attempt = action.type === "search" ? { search: action.term, cursor: void 0, priorItems: [] } : {
+    search: state.listing?.search,
+    cursor: state.listing?.cursor,
+    priorItems: state.listing?.items ?? []
+  };
+  try {
+    if (action.type === "search") {
+      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;
+        delete state.listing;
+        return advance(ctx, state);
+      }
+    }
+    const context = await resolveContext(leaf, state.resolved);
+    state.listing = await fetchListing(leaf, state.resolved, {
+      ...attempt,
+      context
+    });
+    return {
+      state,
+      result: {
+        status: "ask",
+        question: selectQuestion(leaf, state.resolved, state.listing, context)
+      }
+    };
+  } catch (error) {
+    state.listing = {
+      items: attempt.priorItems,
+      search: attempt.search,
+      cursor: attempt.cursor,
+      exhausted: false
+    };
+    return failedResult(state, leaf.name, error);
+  }
+}
+
+// src/model/resolution/controller.ts
+function toJsonSchema(schema) {
+  if (!schema) return void 0;
+  try {
+    return z4.toJSONSchema(schema);
+  } catch {
+    return void 0;
+  }
+}
+function projectSummary(entry) {
+  return {
+    name: entry.name,
+    ...entry.description ? { description: entry.description } : {},
+    ...entry.categories?.length ? { categories: entry.categories } : {}
+  };
+}
+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(dynamic),
+      ...dynamic?.inputType === "search" ? { searchable: true } : {},
+      ...inputProperties?.[spec.name] ? { schema: inputProperties[spec.name] } : {},
+      ...spec.staticChoices ? { choices: spec.staticChoices } : {},
+      ...spec.requires.length ? { requireParameters: spec.requires } : {}
+    };
+  }
+  const output = toJsonSchema(entry.outputSchema);
+  return {
+    name: entry.name,
+    ...entry.description ? { description: entry.description } : {},
+    ...entry.categories?.length ? { categories: entry.categories } : {},
+    parameters,
+    ...entry.positional?.length ? { positional: entry.positional } : {},
+    ...output ? { output } : {}
+  };
+}
+function createController(sdk) {
+  function entryFor(method) {
+    const entry = sdk.getRegistry().functions.find((f) => f.name === method);
+    if (!entry) throw new Error(`unknown method "${method}"`);
+    return entry;
+  }
+  function contextFor(method) {
+    const entry = entryFor(method);
+    return {
+      method,
+      schema: entry.inputSchema,
+      parameters: planParameters(entry).parameters
+    };
+  }
+  const start2 = ({ method, input, interactive }) => start(contextFor(method), input, interactive);
+  const step2 = ({ state, action }) => step(contextFor(state.method), state, action);
+  const resolve = async ({
+    method,
+    input,
+    answer,
+    interactive
+  }) => {
+    const ctx = contextFor(method);
+    let { state, result } = await start(ctx, input, interactive);
+    while (result.status === "ask" || result.status === "failed") {
+      const action = await answer({ state, result });
+      ({ state, result } = await step(ctx, state, action));
+    }
+    if (result.status === "done") return result.value;
+    if (result.status === "cancelled") {
+      throw new CoreCancelledSignal(`resolution cancelled for "${method}"`);
+    }
+    const detail = result.issues.map((i) => i.parameter ? `${i.parameter}: ${i.message}` : i.message).join("; ");
+    throw new Error(`invalid input for "${method}": ${detail}`);
+  };
+  const listMethods = () => ({
+    data: sdk.getRegistry().functions.map(projectSummary)
+  });
+  const getMethod = ({ method }) => ({
+    data: projectMethod(entryFor(method))
+  });
+  const listChoices = async ({
+    method,
+    parameter,
+    input = {},
+    search,
+    cursor
+  }) => {
+    const spec = contextFor(method).parameters.find(
+      (p) => p.name === parameter
+    );
+    const dynamic = spec?.resolver?.type === "dynamic" ? spec.resolver : void 0;
+    if (!dynamic) return { data: [] };
+    const context = await dynamic.getContext?.({ input });
+    const page = await firstPage(
+      dynamic.listItems({ input, context, search, cursor })
+    );
+    const config = dynamic.prompt?.({ items: page.data, input, context });
+    const data = (config?.choices ?? []).map(toChoice);
+    return { data, nextCursor: page.nextCursor };
+  };
+  return { resolve, start: start2, step: step2, listMethods, getMethod, listChoices };
+}
+
+// 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
+    }
+  });
+}
+
+// src/utils/schema-utils.ts
+import { z as z5 } from "zod";
+function getOutputSchema(inputSchema) {
+  return inputSchema._zod.def.outputSchema;
+}
+function withOutputSchema(inputSchema, outputSchema) {
+  Object.assign(inputSchema._zod.def, {
+    outputSchema
+  });
+  return inputSchema;
+}
+function withResolver(schema, config) {
+  schema._zod.def.resolverMeta = config;
+  return schema;
+}
+function getSchemaDescription(schema) {
+  return schema.description;
+}
+function getFieldDescriptions(schema) {
+  const descriptions = {};
+  const shape = schema.shape;
+  for (const [key2, fieldSchema] of Object.entries(shape)) {
+    if (fieldSchema instanceof z5.ZodType && fieldSchema.description) {
+      descriptions[key2] = fieldSchema.description;
+    }
+  }
+  return descriptions;
+}
+function withPositional(schema) {
+  Object.assign(schema._zod.def, {
+    positionalMeta: { positional: true }
+  });
+  return schema;
+}
+function schemaHasPositionalMeta(schema) {
+  return "positionalMeta" in schema._zod.def;
+}
+function isPositional(schema) {
+  if (schemaHasPositionalMeta(schema) && schema._zod.def.positionalMeta?.positional) {
+    return true;
+  }
+  if (schema instanceof z5.ZodOptional) {
+    return isPositional(schema._zod.def.innerType);
+  }
+  if (schema instanceof z5.ZodDefault) {
+    return isPositional(schema._zod.def.innerType);
+  }
+  return false;
+}
+function openEnum(values, description) {
+  return z5.union([z5.enum(values), z5.string()]).describe(description);
+}
+export {
+  CONTEXT,
+  CORE_ERROR_SYMBOL,
+  CORE_OPTIONS_ID,
+  CORE_SIGNAL_SYMBOL,
+  CoreCancelledSignal,
+  CoreDisposeError,
+  CoreError,
+  CoreErrorCode,
+  CoreSignal,
+  addPlugin,
+  composePlugins,
+  concatPaginated,
+  coreOptionsPluginRef,
+  createAsyncContext,
+  createController,
+  createCoreError,
+  createCorePlugin,
+  createDeprecationLogger,
+  createFunction,
+  createPaginatedFunction,
+  createPaginatedPluginMethod,
+  createPluginMethod,
+  createPluginStack,
+  createPrefixedCursor,
+  createSdk,
+  createValidator,
+  dangerousContextPlugin,
+  declareMethod,
+  declareOptionalProperty,
+  declarePlugin,
+  declareProperty,
+  decodeIncomingCursor,
+  defaultLogDeprecation,
+  defineFormatter,
+  defineHook,
+  defineLegacyMerge,
+  defineMethod,
+  defineMethodOverride,
+  definePlugin,
+  defineProperty,
+  defineResolver,
+  disposeSdk,
+  fromFunctionPlugin,
+  getContext,
+  getCoreErrorCause,
+  getCoreErrorCode,
+  getCurrentDepth,
+  getCurrentScope,
+  getFieldDescriptions,
+  getOutputSchema,
+  getRegistryPlugin,
+  getSchemaDescription,
+  isCoreError,
+  isCoreSignal,
+  isNestedMethodCall,
+  isPositional,
+  isTelemetryNested,
+  omitExports,
+  openEnum,
+  paginate,
+  paginateBuffered,
+  paginateMaxItems,
+  resolvePlugin,
+  runInMethodScope,
+  runWithTelemetryContext,
+  selectExports,
+  splitPrefixedCursor,
+  toIterable,
+  toSnakeCase,
+  toTitleCase,
+  validateOptions,
+  withOutputSchema,
+  withPositional,
+  withResolver
+};
+//# sourceMappingURL=index.mjs.map