@kortyx/prompts 0.0.0-stage → 0.2.0

package/dist/index.js

@@ -0,0 +1,840 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PROMPT_PROTOCOL_VERSION: () => PROMPT_PROTOCOL_VERSION,
+  PromptContentSchema: () => PromptContentSchema,
+  PromptError: () => PromptError,
+  PromptKeySchema: () => PromptKeySchema,
+  PromptMessageSchema: () => PromptMessageSchema,
+  PromptSnapshotSchema: () => PromptSnapshotSchema,
+  PromptTagSchema: () => PromptTagSchema,
+  PromptVersionSchema: () => PromptVersionSchema,
+  canonicalPromptJson: () => canonicalPromptJson,
+  compilePrompt: () => compilePrompt,
+  createPrompts: () => createPrompts,
+  definePrompt: () => definePrompt,
+  expandPromptMessages: () => expandPromptMessages,
+  isCompiledPrompt: () => isCompiledPrompt,
+  isPromptUsageMetadata: () => isPromptUsageMetadata,
+  localPromptSource: () => localPromptSource,
+  promptHash: () => promptHash,
+  promptReferencePattern: () => promptReferencePattern,
+  promptReferenceToken: () => promptReferenceToken,
+  promptReferences: () => promptReferences,
+  promptUsageMetadata: () => promptUsageMetadata,
+  promptVariables: () => promptVariables,
+  studioPromptSource: () => studioPromptSource,
+  validatePromptContent: () => validatePromptContent,
+  validatePromptValue: () => validatePromptValue,
+  verifyPromptSnapshot: () => verifyPromptSnapshot
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/compiler.ts
+var import__ = __toESM(require("ajv/dist/2020"));
+
+// src/contracts.ts
+var import_zod = require("zod");
+var PROMPT_PROTOCOL_VERSION = 1;
+var PromptKeySchema = import_zod.z.string().min(1).max(200).regex(/^[a-zA-Z0-9][a-zA-Z0-9_./-]*$/);
+var PromptTagSchema = import_zod.z.string().trim().min(1).max(64).regex(/^[a-z0-9][a-z0-9_-]*$/);
+var PromptMessageSchema = import_zod.z.object({
+  role: import_zod.z.enum(["system", "user", "assistant"]),
+  content: import_zod.z.string().max(2e5)
+}).strict();
+var PromptContentSchema = import_zod.z.object({
+  format: import_zod.z.enum(["system-user", "chat"]),
+  messages: import_zod.z.array(PromptMessageSchema).min(1).max(100),
+  variablesSchema: import_zod.z.record(import_zod.z.string(), import_zod.z.json()),
+  configSchema: import_zod.z.record(import_zod.z.string(), import_zod.z.json()),
+  config: import_zod.z.record(import_zod.z.string(), import_zod.z.json()),
+  dependencies: import_zod.z.array(
+    import_zod.z.object({
+      id: PromptKeySchema,
+      version: import_zod.z.number().int().positive(),
+      hash: import_zod.z.string().regex(/^[a-f0-9]{64}$/)
+    }).strict()
+  ).max(100).default([])
+}).strict().superRefine((value, ctx) => {
+  if (value.format === "system-user" && (value.messages.length !== 2 || value.messages[0]?.role !== "system" || value.messages[1]?.role !== "user"))
+    ctx.addIssue({
+      code: "custom",
+      message: "system-user requires exactly one system message followed by one user message.",
+      path: ["messages"]
+    });
+});
+var PromptVersionSchema = import_zod.z.object({
+  id: PromptKeySchema,
+  version: import_zod.z.number().int().positive(),
+  hash: import_zod.z.string().regex(/^[a-f0-9]{64}$/),
+  content: PromptContentSchema
+});
+var PromptSnapshotSchema = import_zod.z.object({
+  schemaVersion: import_zod.z.literal(PROMPT_PROTOCOL_VERSION),
+  environment: import_zod.z.string().min(1).max(128),
+  tag: PromptTagSchema.optional(),
+  revision: import_zod.z.string().min(1),
+  versions: import_zod.z.record(import_zod.z.string(), PromptVersionSchema),
+  source: import_zod.z.enum(["studio", "local", "cache", "fallback", "eval"]),
+  resolvedAt: import_zod.z.iso.datetime(),
+  requestedIds: import_zod.z.array(PromptKeySchema).max(100).optional()
+}).strict();
+var PromptError = class extends Error {
+  constructor(code, message, status = 400) {
+    super(message);
+    this.code = code;
+    this.status = status;
+  }
+  code;
+  status;
+  name = "PromptError";
+};
+function canonicalPromptJson(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value))
+    return `[${value.map(canonicalPromptJson).join(",")}]`;
+  return `{${Object.keys(value).sort().map(
+    (key) => `${JSON.stringify(key)}:${canonicalPromptJson(value[key])}`
+  ).join(",")}}`;
+}
+async function promptHash(content) {
+  const bytes = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(canonicalPromptJson(content))
+  );
+  return Array.from(
+    new Uint8Array(bytes),
+    (b) => b.toString(16).padStart(2, "0")
+  ).join("");
+}
+async function verifyPromptSnapshot(value) {
+  const parsed = PromptSnapshotSchema.safeParse(value);
+  if (!parsed.success)
+    throw new PromptError(
+      "PROMPT_SNAPSHOT_INVALID",
+      "The prompt snapshot does not match the serving contract."
+    );
+  const snapshot = parsed.data;
+  if (Object.keys(snapshot.versions).length > 200)
+    throw new PromptError(
+      "PROMPT_SNAPSHOT_LIMIT",
+      "A snapshot supports at most 200 versions."
+    );
+  for (const [key, version] of Object.entries(snapshot.versions)) {
+    if (key !== version.id || await promptHash(version.content) !== version.hash)
+      throw new PromptError(
+        "PROMPT_HASH_MISMATCH",
+        `Prompt ${key} did not match its immutable hash.`
+      );
+    for (const dependency of version.content.dependencies) {
+      const actual = snapshot.versions[dependency.id];
+      if (!actual || actual.version !== dependency.version || actual.hash !== dependency.hash)
+        throw new PromptError(
+          "PROMPT_DEPENDENCY_MISMATCH",
+          `Missing exact dependency ${dependency.id}@${dependency.version}.`
+        );
+    }
+  }
+  const visit = (key, active, done2) => {
+    if (active.has(key))
+      throw new PromptError(
+        "PROMPT_DEPENDENCY_CYCLE",
+        `Prompt dependency cycle at ${key}.`
+      );
+    if (done2.has(key)) return;
+    active.add(key);
+    for (const dep of snapshot.versions[key]?.content.dependencies ?? [])
+      visit(dep.id, active, done2);
+    active.delete(key);
+    done2.add(key);
+  };
+  const done = /* @__PURE__ */ new Set();
+  for (const key of Object.keys(snapshot.versions)) visit(key, /* @__PURE__ */ new Set(), done);
+  const freeze = (value2) => {
+    if (value2 && typeof value2 === "object" && !Object.isFrozen(value2)) {
+      for (const nested of Object.values(value2)) freeze(nested);
+      Object.freeze(value2);
+    }
+  };
+  freeze(snapshot);
+  return snapshot;
+}
+
+// src/references.ts
+var promptReferencePattern = /\[\[prompt:([a-zA-Z0-9][a-zA-Z0-9_./-]*)\]\]/g;
+function promptReferenceToken(id) {
+  return `[[prompt:${id}]]`;
+}
+function promptReferences(content) {
+  return [
+    ...new Set(
+      content.messages.flatMap(
+        (message) => [...message.content.matchAll(promptReferencePattern)].map(
+          (match) => match[1]
+        )
+      )
+    )
+  ];
+}
+function expandPromptMessages(root, versions = {}) {
+  const used = /* @__PURE__ */ new Map();
+  const cache = /* @__PURE__ */ new Map();
+  const expand = (owner, text, role, active) => {
+    const parts = [];
+    let size = 0, position = 0;
+    const append = (part) => {
+      size += part.length;
+      if (size > 2e5)
+        throw new PromptError(
+          "PROMPT_REFERENCE_LIMIT",
+          "An expanded message cannot exceed 200,000 characters."
+        );
+      parts.push(part);
+    };
+    for (const match of text.matchAll(promptReferencePattern)) {
+      append(text.slice(position, match.index));
+      position = match.index + match[0].length;
+      const id = match[1];
+      const dependency = owner.content.dependencies.find(
+        (item) => item.id === id
+      );
+      const child = versions[id];
+      if (!dependency || !child || child.version !== dependency.version || child.hash !== dependency.hash)
+        throw new PromptError(
+          "PROMPT_REFERENCE_MISSING",
+          `Include an exact dependency for referenced prompt ${id}.`
+        );
+      if (active.has(id) || active.size >= 200)
+        throw new PromptError(
+          "PROMPT_DEPENDENCY_CYCLE",
+          `Prompt reference cycle at ${id}.`
+        );
+      const messages = child.content.messages.filter(
+        (message) => message.role === role
+      );
+      if (!messages.length)
+        throw new PromptError(
+          "PROMPT_REFERENCE_ROLE",
+          `${id} has no ${role} message to include.`
+        );
+      used.set(id, child);
+      const cacheKey = `${id}@${child.version}:${role}`;
+      let included = cache.get(cacheKey);
+      if (included === void 0) {
+        const next = new Set(active).add(id);
+        const chunks = [];
+        let length = 0;
+        for (const message of messages) {
+          const chunk = expand(child, message.content, role, next);
+          length += chunk.length + (chunks.length ? 2 : 0);
+          if (length > 2e5)
+            throw new PromptError(
+              "PROMPT_REFERENCE_LIMIT",
+              "An expanded message cannot exceed 200,000 characters."
+            );
+          chunks.push(chunk);
+        }
+        included = chunks.join("\n\n");
+        cache.set(cacheKey, included);
+      }
+      append(included);
+    }
+    append(text.slice(position));
+    return parts.join("");
+  };
+  return {
+    messages: root.content.messages.map((message) => ({
+      ...message,
+      content: expand(root, message.content, message.role, /* @__PURE__ */ new Set([root.id]))
+    })),
+    used: [...used.values()]
+  };
+}
+
+// src/compiler.ts
+var ajv = new import__.default({
+  strict: false,
+  allErrors: true,
+  validateFormats: false,
+  ownProperties: true
+});
+var validators = /* @__PURE__ */ new Map();
+var compiledPrompts = /* @__PURE__ */ new WeakSet();
+var usageMetadata = /* @__PURE__ */ new WeakSet();
+function isCompiledPrompt(value) {
+  return Boolean(
+    value && typeof value === "object" && compiledPrompts.has(value)
+  );
+}
+function promptUsageMetadata(prompt) {
+  if (!isCompiledPrompt(prompt))
+    throw new PromptError(
+      "PROMPT_REASON_INVALID",
+      "Use a compiled prompt returned by usePrompt."
+    );
+  const metadata = Object.freeze({
+    id: prompt.ref.id,
+    version: prompt.ref.version,
+    hash: prompt.ref.hash,
+    environment: prompt.ref.environment,
+    snapshotRevision: prompt.ref.snapshotRevision,
+    ...prompt.dependencies?.length ? { dependencies: prompt.dependencies } : {}
+  });
+  usageMetadata.add(metadata);
+  return metadata;
+}
+function isPromptUsageMetadata(value) {
+  return Boolean(
+    value && typeof value === "object" && usageMetadata.has(value)
+  );
+}
+function freezeValue(value, seen = /* @__PURE__ */ new WeakSet()) {
+  if (value && typeof value === "object" && !seen.has(value)) {
+    seen.add(value);
+    for (const item of Object.values(value)) freezeValue(item, seen);
+    Object.freeze(value);
+  }
+  return value;
+}
+function validatePromptValue(schema, value, label) {
+  const key = canonicalPromptJson(schema);
+  let validator = validators.get(key);
+  if (!validator) {
+    if (validators.size >= 256) validators.clear();
+    try {
+      validator = ajv.compile(schema);
+    } catch {
+      throw new PromptError(
+        "PROMPT_SCHEMA_INVALID",
+        `${label} schema is invalid.`
+      );
+    }
+    validators.set(key, validator);
+  }
+  if (!validator(value))
+    throw new PromptError(
+      "PROMPT_CONTRACT_MISMATCH",
+      `${label}: ${ajv.errorsText(validator.errors)}.`
+    );
+}
+var placeholder = /\{\{\s*([A-Za-z_][A-Za-z0-9_.]*)\s*\}\}/g;
+function promptVariables(content) {
+  return [
+    ...new Set(
+      content.messages.flatMap(
+        (message) => [...message.content.matchAll(placeholder)].map(
+          (match) => match[1]
+        )
+      )
+    )
+  ];
+}
+function validatePromptContent(content) {
+  validatePromptValue(content.configSchema, content.config, "Configuration");
+  try {
+    ajv.compile(content.variablesSchema);
+  } catch {
+    throw new PromptError(
+      "PROMPT_SCHEMA_INVALID",
+      "Template input schema is invalid."
+    );
+  }
+  const inputs = content.variablesSchema.properties;
+  for (const variable of promptVariables(content)) {
+    const top = variable.split(".")[0];
+    if (!inputs || !Object.hasOwn(inputs, top))
+      throw new PromptError(
+        "PROMPT_VARIABLE_UNKNOWN",
+        `Declare template input ${top} in the input schema.`
+      );
+    if (Object.hasOwn(content.config, top))
+      throw new PromptError(
+        "PROMPT_VARIABLE_CONFIG_OVERLAP",
+        `${top} cannot be both a template input and saved configuration.`
+      );
+  }
+}
+function definePrompt(reference) {
+  if (!reference.id || !reference.variables || !reference.config)
+    throw new PromptError(
+      "PROMPT_REFERENCE_INVALID",
+      "A prompt reference needs id, variables and config schemas."
+    );
+  return Object.freeze({ ...reference });
+}
+function compilePrompt(ref, version, variables, identity, versions) {
+  if (version.id !== ref.id || version.content.format !== ref.format)
+    throw new PromptError(
+      "PROMPT_CONTRACT_MISMATCH",
+      `Prompt ${ref.id} format or identity differs from the application contract.`
+    );
+  const values = ref.variables.parse(variables);
+  validatePromptValue(
+    version.content.variablesSchema,
+    values,
+    "Template inputs"
+  );
+  validatePromptValue(
+    version.content.configSchema,
+    version.content.config,
+    "Configuration"
+  );
+  const config = ref.config.parse(structuredClone(version.content.config));
+  const expanded = expandPromptMessages(version, versions);
+  if (expanded.used.length)
+    validatePromptContent({ ...version.content, messages: expanded.messages });
+  for (const child of expanded.used) {
+    const properties = child.content.variablesSchema.properties;
+    const childValues = properties && typeof properties === "object" && !Array.isArray(properties) ? Object.fromEntries(
+      Object.keys(properties).filter((key) => Object.hasOwn(values, key)).map((key) => [key, values[key]])
+    ) : values;
+    validatePromptValue(
+      child.content.variablesSchema,
+      childValues,
+      `Inputs for ${child.id}`
+    );
+  }
+  const messages = expanded.messages.map((message) => ({
+    role: message.role,
+    content: message.content.replace(placeholder, (_, path) => {
+      let value = values;
+      for (const key of path.split(".")) {
+        if (["__proto__", "constructor", "prototype"].includes(key) || !value || typeof value !== "object" || !Object.hasOwn(value, key))
+          throw new PromptError(
+            "PROMPT_VARIABLE_MISSING",
+            `Missing template input ${path}.`
+          );
+        value = value[key];
+      }
+      if (value === void 0)
+        throw new PromptError(
+          "PROMPT_VARIABLE_MISSING",
+          `Missing template input ${path}.`
+        );
+      return typeof value === "string" ? value : canonicalPromptJson(value);
+    })
+  }));
+  const compiled = freezeValue({
+    format: ref.format,
+    messages,
+    config,
+    ...expanded.used.length ? {
+      dependencies: expanded.used.map(({ id, version: version2, hash }) => ({
+        id,
+        version: version2,
+        hash
+      }))
+    } : {},
+    ...ref.format === "system-user" ? { system: messages[0]?.content, user: messages[1]?.content } : {},
+    ref: {
+      id: ref.id,
+      version: version.version,
+      hash: version.hash,
+      ...identity
+    }
+  });
+  compiledPrompts.add(compiled);
+  return compiled;
+}
+
+// src/usage.ts
+var import_node = require("@kortyx/usage-telemetry/node");
+
+// package.json
+var package_default = {
+  name: "@kortyx/prompts",
+  version: "0.2.0",
+  description: "Typed, versioned prompts and portable Studio serving for Kortyx.",
+  license: "Apache-2.0",
+  main: "./dist/index.js",
+  types: "./dist/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      default: "./dist/index.js"
+    },
+    "./browser": {
+      types: "./dist/browser.d.ts",
+      default: "./dist/browser.js"
+    }
+  },
+  files: [
+    "dist/**",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  scripts: {
+    build: "tsup",
+    dev: "tsc --watch",
+    "type-check": "tsc --noEmit -p tsconfig.test.json",
+    test: "vitest run && pnpm -s type-check",
+    coverage: "vitest run --coverage && pnpm -s type-check",
+    lint: "biome check src test"
+  },
+  dependencies: {
+    ajv: "8.18.0",
+    zod: "catalog:",
+    "@kortyx/usage-telemetry": "workspace:*"
+  },
+  devDependencies: {
+    tsup: "catalog:",
+    typescript: "catalog:",
+    vitest: "catalog:",
+    "@vitest/coverage-v8": "catalog:",
+    "@types/node": "catalog:"
+  },
+  sideEffects: false,
+  publishConfig: {
+    access: "public"
+  },
+  repository: {
+    type: "git",
+    url: "https://github.com/kortyx-io/kortyx.git",
+    directory: "packages/prompts"
+  }
+};
+
+// src/usage.ts
+var client = () => (0, import_node.getUsageTelemetry)("prompts", package_default.version);
+var usage = {
+  start: (...args) => client().start(...args),
+  feature: (...args) => client().feature(...args),
+  measure: (...args) => client().measure(...args),
+  flush: () => client().flush()
+};
+
+// src/source.ts
+function createPrompts(options) {
+  const ids = options.definitions.map((ref) => ref.id), tag = PromptTagSchema.parse(options.source.tag ?? "live"), environment = options.environment ?? options.source.environment ?? "production";
+  if (options.maxStaleMs !== void 0 && (!Number.isFinite(options.maxStaleMs) || options.maxStaleMs < 0))
+    throw new PromptError(
+      "PROMPT_CACHE_INVALID",
+      "maxStaleMs must be a finite, nonnegative duration."
+    );
+  if (options.source.environment && options.source.environment !== environment)
+    throw new PromptError(
+      "PROMPT_ENVIRONMENT_MISMATCH",
+      "Source and manager environments must match."
+    );
+  if (new Set(ids).size !== ids.length)
+    throw new PromptError(
+      "PROMPT_REFERENCE_DUPLICATE",
+      "Registered prompt IDs must be unique."
+    );
+  let lastGood;
+  const cacheKey = `${options.source.identity}:${environment}:${tag}:${JSON.stringify([...ids].sort())}`;
+  const fresh = async (signal) => {
+    const pending = options.source.resolve(ids, { environment, tag, ...signal ? { signal } : {} }).then(verifyPromptSnapshot).then(async (value) => {
+      for (const id of ids)
+        if (!value.versions[id])
+          throw new PromptError(
+            "PROMPT_NOT_ASSIGNED",
+            `No ${tag} tag for ${id}.`,
+            404
+          );
+      if (value.environment !== environment)
+        throw new PromptError(
+          "PROMPT_ENVIRONMENT_MISMATCH",
+          "Source returned a different environment."
+        );
+      if ((value.tag ?? "live") !== tag)
+        throw new PromptError(
+          "PROMPT_TAG_MISMATCH",
+          "Source returned a different prompt tag."
+        );
+      lastGood = value;
+      await options.cache?.set(cacheKey, value);
+      return value;
+    });
+    try {
+      return await pending;
+    } catch (error) {
+      if (signal?.aborted || options.fallback !== "last-known-good" || error instanceof PromptError && error.status < 500 && error.status !== 429)
+        throw error;
+      const cached = lastGood ?? await options.cache?.get(cacheKey);
+      if (!cached || cached.environment !== environment || (cached.tag ?? "live") !== tag || Date.parse(cached.resolvedAt) > Date.now() + 3e4 || Date.now() - Date.parse(cached.resolvedAt) > (options.maxStaleMs ?? 3e5))
+        throw error;
+      return {
+        ...await verifyPromptSnapshot(cached),
+        source: "fallback"
+      };
+    }
+  };
+  return {
+    definitions: options.definitions,
+    start(start = {}) {
+      let snapshotPromise;
+      const snapshot = (stored) => {
+        if (snapshotPromise) return snapshotPromise;
+        snapshotPromise = stored ? verifyPromptSnapshot(stored).then((value) => {
+          if (value.environment !== environment)
+            throw new PromptError(
+              "PROMPT_ENVIRONMENT_MISMATCH",
+              "Stored snapshot belongs to another environment."
+            );
+          return value;
+        }) : start.snapshot ? verifyPromptSnapshot(start.snapshot).then((value) => {
+          if (value.source !== "eval" || value.environment !== environment)
+            throw new PromptError(
+              "PROMPT_EVAL_SNAPSHOT_INVALID",
+              "An eval snapshot must match the configured environment."
+            );
+          return value;
+        }) : fresh(start.signal);
+        return snapshotPromise;
+      };
+      const pins = /* @__PURE__ */ new Map();
+      const pin = async (id, version, stored) => {
+        const baseline = await snapshot();
+        if (baseline.source === "eval" && baseline.versions[id]?.version !== version)
+          throw new PromptError(
+            "PROMPT_EVAL_PIN_CONFLICT",
+            `Pinned ${id}@${version} conflicts with the eval snapshot.`
+          );
+        const key = `${id}@${version}`;
+        let pendingPin = pins.get(key);
+        if (!pendingPin) {
+          pendingPin = (stored ? verifyPromptSnapshot(stored) : baseline.versions[id]?.version === version ? Promise.resolve(baseline) : options.source.resolve([id], {
+            environment,
+            tag,
+            versions: { [id]: version },
+            ...start.signal ? { signal: start.signal } : {}
+          }).then(verifyPromptSnapshot)).then((value) => {
+            if (value.environment !== environment || value.versions[id]?.version !== version)
+              throw new PromptError(
+                "PROMPT_PIN_MISMATCH",
+                `Source returned a different pin for ${id}.`
+              );
+            return value;
+          });
+          pins.set(key, pendingPin);
+        }
+        return pendingPin;
+      };
+      return {
+        snapshot,
+        pin,
+        recordUsage(usage2) {
+          start.onUsage?.(usage2);
+        },
+        async resolve(ref, args) {
+          const scope = usage.start("sdk.prompt.resolve");
+          try {
+            if (!ids.includes(ref.id))
+              throw new PromptError(
+                "PROMPT_NOT_REGISTERED",
+                `Register ${ref.id} with createPrompts.`
+              );
+            const resolved = await snapshot(args.stored);
+            let selectedSnapshot = resolved;
+            let selected = resolved.versions[ref.id];
+            if (args.version !== void 0 && selected?.version !== args.version) {
+              const pinned = await pin(ref.id, args.version, args.pin);
+              selectedSnapshot = pinned;
+              selected = pinned.versions[ref.id];
+              if (selected?.version !== args.version)
+                throw new PromptError(
+                  "PROMPT_PIN_MISMATCH",
+                  `Source returned a different version of ${ref.id}.`
+                );
+            }
+            if (!selected)
+              throw new PromptError(
+                "PROMPT_NOT_ASSIGNED",
+                `No version resolved for ${ref.id}.`,
+                404
+              );
+            const compiled = compilePrompt(
+              ref,
+              selected,
+              args.variables,
+              {
+                source: selectedSnapshot.source,
+                environment: selectedSnapshot.environment,
+                snapshotRevision: selectedSnapshot.revision
+              },
+              selectedSnapshot.versions
+            );
+            scope.end("success", { source: selectedSnapshot.source });
+            return compiled;
+          } catch (error) {
+            scope.fail(error);
+            throw error;
+          }
+        }
+      };
+    }
+  };
+}
+function studioPromptSource(options) {
+  const url = new URL(options.apiUrl);
+  if (!/^https?:$/.test(url.protocol) || url.username || url.password)
+    throw new PromptError(
+      "PROMPT_SOURCE_INVALID",
+      "Use an HTTP API origin without embedded credentials."
+    );
+  const request = options.fetch ?? fetch;
+  const publicKeyId = /^ktyx_(?:test|live)_([^_]+)_/.exec(options.apiKey)?.[1] ?? crypto.randomUUID();
+  return {
+    identity: `${url.origin}${url.pathname}:${options.projectId ?? ""}:${publicKeyId}:${options.environmentId ?? ""}`,
+    tag: PromptTagSchema.parse(options.tag ?? "live"),
+    ...options.environment ? { environment: options.environment } : {},
+    async resolve(ids, args) {
+      for (let attempt = 0; ; attempt++) {
+        try {
+          const signal = AbortSignal.any([
+            AbortSignal.timeout(options.timeoutMs ?? 5e3),
+            ...args.signal ? [args.signal] : []
+          ]);
+          const response = await request(
+            `${options.apiUrl.replace(/\/$/, "")}/v1/prompts/resolve`,
+            {
+              method: "POST",
+              signal,
+              headers: {
+                authorization: `Bearer ${options.apiKey}`,
+                "content-type": "application/json",
+                ...options.projectId ? { "x-kortyx-project-id": options.projectId } : {},
+                ...options.environmentId ? { "x-kortyx-environment-id": options.environmentId } : {}
+              },
+              body: JSON.stringify({
+                schemaVersion: 1,
+                ids,
+                tag: options.tag ?? args.tag ?? "live",
+                environment: options.environment ?? args.environment,
+                ...args.versions ? { versions: args.versions } : {}
+              })
+            }
+          );
+          if (!response.ok)
+            throw new PromptError(
+              "PROMPT_SOURCE_HTTP",
+              `Prompt serving failed (HTTP ${response.status}).`,
+              response.status
+            );
+          const reader = response.body?.getReader();
+          if (!reader)
+            throw new PromptError(
+              "PROMPT_SNAPSHOT_INVALID",
+              "Prompt serving returned an empty response."
+            );
+          const decoder = new TextDecoder();
+          let body = "", bytes = 0;
+          try {
+            for (; ; ) {
+              const chunk = await reader.read();
+              if (chunk.done) break;
+              bytes += chunk.value.byteLength;
+              if (bytes > 20 * 1024 * 1024)
+                throw new PromptError(
+                  "PROMPT_SNAPSHOT_LIMIT",
+                  "Prompt serving exceeded the 20 MiB response limit."
+                );
+              body += decoder.decode(chunk.value, { stream: true });
+            }
+            body += decoder.decode();
+            let value;
+            try {
+              value = JSON.parse(body);
+            } catch {
+              throw new PromptError(
+                "PROMPT_SNAPSHOT_INVALID",
+                "Prompt serving returned invalid JSON."
+              );
+            }
+            return await verifyPromptSnapshot(value);
+          } finally {
+            await reader.cancel().catch(() => {
+            });
+            reader.releaseLock();
+          }
+        } catch (error) {
+          if (args.signal?.aborted || attempt >= (options.retries ?? 1) || error instanceof PromptError && error.status < 500 && error.status !== 429)
+            throw error;
+        }
+      }
+    }
+  };
+}
+function localPromptSource(snapshot) {
+  return {
+    identity: `local:${snapshot.revision}`,
+    environment: snapshot.environment,
+    tag: snapshot.tag ?? "live",
+    async resolve(ids, args) {
+      const verified = await verifyPromptSnapshot(snapshot);
+      if (args.environment !== verified.environment)
+        throw new PromptError(
+          "PROMPT_ENVIRONMENT_MISMATCH",
+          "Local snapshot environment differs from the requested environment."
+        );
+      for (const id of ids)
+        if (!verified.versions[id] || args.versions?.[id] && verified.versions[id]?.version !== args.versions[id])
+          throw new PromptError(
+            "PROMPT_NOT_FOUND",
+            `Local snapshot does not contain ${id}.`,
+            404
+          );
+      return { ...verified, source: "local" };
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PROMPT_PROTOCOL_VERSION,
+  PromptContentSchema,
+  PromptError,
+  PromptKeySchema,
+  PromptMessageSchema,
+  PromptSnapshotSchema,
+  PromptTagSchema,
+  PromptVersionSchema,
+  canonicalPromptJson,
+  compilePrompt,
+  createPrompts,
+  definePrompt,
+  expandPromptMessages,
+  isCompiledPrompt,
+  isPromptUsageMetadata,
+  localPromptSource,
+  promptHash,
+  promptReferencePattern,
+  promptReferenceToken,
+  promptReferences,
+  promptUsageMetadata,
+  promptVariables,
+  studioPromptSource,
+  validatePromptContent,
+  validatePromptValue,
+  verifyPromptSnapshot
+});
+//# sourceMappingURL=index.js.map