@sembl/core 0.1.0

package/dist/index.js

@@ -0,0 +1,1059 @@
+// src/schema/json-schema.ts
+var CONSTRAINT_KEYWORDS = [
+  "maxLength",
+  "minLength",
+  "minimum",
+  "maximum",
+  "minItems",
+  "maxItems",
+  "pattern"
+];
+var ARRAY_KEYWORDS = ["minItems", "maxItems"];
+function constraintsToJsonSchema(constraints, dialect) {
+  if (!constraints || dialect === "openai-strict") {
+    return {};
+  }
+  const out = {};
+  for (const keyword of CONSTRAINT_KEYWORDS) {
+    const value = constraints[keyword];
+    if (value !== void 0) {
+      out[keyword] = value;
+    }
+  }
+  return out;
+}
+function fieldTypeToJsonSchema(fieldType, bundle, options, visiting) {
+  switch (fieldType.kind) {
+    case "string":
+      return { type: "string" };
+    case "number":
+      return { type: "number" };
+    case "boolean":
+      return { type: "boolean" };
+    case "array":
+      return {
+        type: "array",
+        items: fieldTypeToJsonSchema(fieldType.items, bundle, options, visiting)
+      };
+    case "enum":
+      return { type: "string", enum: fieldType.values };
+    case "dynamicEnum": {
+      const values = options.resolvedEnums?.[fieldType.sourceId];
+      return values && values.length > 0 ? { type: "string", enum: [...values] } : { type: "string" };
+    }
+    case "object": {
+      const nested = bundle?.schemas[fieldType.nestedSchemaId];
+      if (nested && !visiting.has(nested.id)) {
+        return buildObjectSchema(nested, bundle, options, visiting);
+      }
+      return { type: "object", additionalProperties: false };
+    }
+  }
+}
+function fieldToJsonSchema(field, bundle, options, visiting) {
+  const base = fieldTypeToJsonSchema(field.type, bundle, options, visiting);
+  const dialect = options.dialect ?? "openai-strict";
+  const constraints = constraintsToJsonSchema(field.constraints, dialect);
+  if (base.type !== "array") {
+    return { ...base, ...constraints, description: field.description };
+  }
+  const arrayLevel = {};
+  const itemLevel = {};
+  for (const [keyword, value] of Object.entries(constraints)) {
+    (ARRAY_KEYWORDS.includes(keyword) ? arrayLevel : itemLevel)[keyword] = value;
+  }
+  return {
+    ...base,
+    ...arrayLevel,
+    items: { ...base.items, ...itemLevel },
+    description: field.description
+  };
+}
+function buildObjectSchema(schema, bundle, options, visiting) {
+  const properties = {};
+  const required = [];
+  const dialect = options.dialect ?? "openai-strict";
+  visiting.add(schema.id);
+  for (const field of schema.fields) {
+    const fieldSchema = fieldToJsonSchema(field, bundle, options, visiting);
+    if (dialect === "openai-strict") {
+      properties[field.name] = field.required ? fieldSchema : { anyOf: [fieldSchema, { type: "null" }] };
+      required.push(field.name);
+    } else {
+      properties[field.name] = fieldSchema;
+      if (field.required) {
+        required.push(field.name);
+      }
+    }
+  }
+  visiting.delete(schema.id);
+  return {
+    type: "object",
+    description: schema.description,
+    properties,
+    required,
+    additionalProperties: false
+  };
+}
+function runtimeSchemaToJsonSchema(schema, bundle, options = {}) {
+  return buildObjectSchema(schema, bundle, options, /* @__PURE__ */ new Set());
+}
+function toOpenAIJsonSchema(schema, bundle, options = {}) {
+  return {
+    name: schema.id,
+    strict: true,
+    schema: runtimeSchemaToJsonSchema(schema, bundle, {
+      ...options,
+      dialect: "openai-strict"
+    })
+  };
+}
+
+// src/schema/resolve-enum-sources.ts
+function collectFromType(type, path, required, bundle, visiting, usages) {
+  switch (type.kind) {
+    case "dynamicEnum": {
+      const existing = usages.get(type.sourceId);
+      if (existing) {
+        existing.required ||= required;
+        existing.paths.push(path);
+      } else {
+        usages.set(type.sourceId, { required, paths: [path] });
+      }
+      break;
+    }
+    case "array":
+      collectFromType(type.items, `${path}[]`, required, bundle, visiting, usages);
+      break;
+    case "object": {
+      const nested = bundle?.schemas[type.nestedSchemaId];
+      if (nested && !visiting.has(nested.id)) {
+        collectFromSchema(nested, path, required, bundle, visiting, usages);
+      }
+      break;
+    }
+    default:
+      break;
+  }
+}
+function collectFromSchema(schema, parentPath, parentRequired, bundle, visiting, usages) {
+  visiting.add(schema.id);
+  for (const field of schema.fields) {
+    const path = parentPath ? `${parentPath}.${field.name}` : field.name;
+    collectFromType(
+      field.type,
+      path,
+      parentRequired && field.required,
+      bundle,
+      visiting,
+      usages
+    );
+  }
+  visiting.delete(schema.id);
+}
+function collectEnumSources(schema, bundle) {
+  const usages = /* @__PURE__ */ new Map();
+  collectFromSchema(schema, "", true, bundle, /* @__PURE__ */ new Set(), usages);
+  return usages;
+}
+async function resolveEnumSources(schema, resolver, bundle) {
+  const usages = collectEnumSources(schema, bundle);
+  const enums = {};
+  const failures = [];
+  await Promise.all(
+    [...usages].map(async ([sourceId, usage]) => {
+      try {
+        const values = await resolver(sourceId);
+        if (!values || values.length === 0) {
+          failures.push({ sourceId, reason: "empty", ...usage });
+          return;
+        }
+        enums[sourceId] = values;
+      } catch (cause) {
+        failures.push({ sourceId, reason: "threw", cause, ...usage });
+      }
+    })
+  );
+  failures.sort((a, b) => a.sourceId.localeCompare(b.sourceId));
+  return { enums, failures };
+}
+
+// src/schema/registry.ts
+var SchemaRegistry = class {
+  schemas = /* @__PURE__ */ new Map();
+  /**
+   * Register a single schema.
+   */
+  register(schema) {
+    this.schemas.set(schema.id, schema);
+  }
+  /**
+   * Register all schemas from a bundle.
+   */
+  registerBundle(bundle) {
+    for (const schema of Object.values(bundle.schemas)) {
+      this.register(schema);
+    }
+  }
+  /**
+   * Look up a schema by ID.
+   */
+  get(id) {
+    return this.schemas.get(id);
+  }
+  /**
+   * Get a schema by ID, throwing if not found.
+   */
+  require(id) {
+    const schema = this.schemas.get(id);
+    if (!schema) {
+      throw new Error(`Schema "${id}" not found in registry`);
+    }
+    return schema;
+  }
+  /**
+   * Get a SchemaBundle of all registered schemas.
+   */
+  toBundle() {
+    const schemas = {};
+    for (const [id, schema] of this.schemas) {
+      schemas[id] = schema;
+    }
+    return { schemas };
+  }
+  /**
+   * Get all registered schema IDs.
+   */
+  ids() {
+    return [...this.schemas.keys()];
+  }
+};
+
+// src/decorators.ts
+function Schema(description) {
+  return function(target) {
+    return target;
+  };
+}
+function Describe(description) {
+  return function(_target, _propertyKey) {
+  };
+}
+function Constrain(constraints) {
+  return function(_target, _propertyKey) {
+  };
+}
+function ValuesFrom(sourceId) {
+  return function(_target, _propertyKey) {
+  };
+}
+
+// src/errors/coerce-error.ts
+var CoerceError = class extends Error {
+  issues;
+  constructor(issues) {
+    const summary = issues.map((i) => `  ${i.path}: ${i.message}`).join("\n");
+    super(`Coercion validation failed:
+${summary}`);
+    this.name = "CoerceError";
+    this.issues = issues;
+  }
+};
+
+// src/errors/enum-resolution-error.ts
+var EnumResolutionError = class extends Error {
+  failures;
+  constructor(failures) {
+    const summary = failures.map((f) => {
+      const why = f.reason === "empty" ? "resolved to no values" : `threw: ${f.cause instanceof Error ? f.cause.message : String(f.cause)}`;
+      return `  ${f.sourceId} (${f.paths.join(", ")}): ${why}`;
+    }).join("\n");
+    super(`Enum source resolution failed for required fields:
+${summary}`);
+    this.name = "EnumResolutionError";
+    this.failures = failures;
+  }
+};
+
+// src/coerce/prompt-builder.ts
+function describeConstraints(constraints) {
+  if (!constraints) {
+    return [];
+  }
+  const phrases = [];
+  const { minLength, maxLength, minimum, maximum, minItems, maxItems, pattern } = constraints;
+  if (minLength !== void 0 && maxLength !== void 0) {
+    phrases.push(`between ${minLength} and ${maxLength} characters`);
+  } else if (maxLength !== void 0) {
+    phrases.push(`at most ${maxLength} characters`);
+  } else if (minLength !== void 0) {
+    phrases.push(`at least ${minLength} characters`);
+  }
+  if (minimum !== void 0 && maximum !== void 0) {
+    phrases.push(`between ${minimum} and ${maximum}`);
+  } else if (minimum !== void 0) {
+    phrases.push(`at least ${minimum}`);
+  } else if (maximum !== void 0) {
+    phrases.push(`at most ${maximum}`);
+  }
+  if (minItems !== void 0 && maxItems !== void 0) {
+    phrases.push(`between ${minItems} and ${maxItems} entries`);
+  } else if (maxItems !== void 0) {
+    phrases.push(`at most ${maxItems} entries`);
+  } else if (minItems !== void 0) {
+    phrases.push(`at least ${minItems} entries`);
+  }
+  if (pattern !== void 0) {
+    phrases.push(`matching the pattern /${pattern}/`);
+  }
+  return phrases;
+}
+function describeDynamicEnum(sourceId, resolvedEnums) {
+  const values = resolvedEnums?.[sourceId];
+  if (!values || values.length === 0) {
+    return void 0;
+  }
+  return `exactly one of the ${values.length} allowed "${sourceId}" values enumerated in the JSON schema for this field (never invent a value)`;
+}
+function buildFieldContext(field, parentPath, bundle, depth, options, visiting) {
+  const lines = [];
+  const indent = "  ".repeat(depth);
+  const fieldPath = parentPath ? `${parentPath}.${field.name}` : field.name;
+  lines.push(
+    `${indent}- ${fieldPath} (${field.required ? "required" : "optional"}): ${field.description}`
+  );
+  const rules = describeConstraints(field.constraints);
+  const dynamicSourceId = field.type.kind === "dynamicEnum" ? field.type.sourceId : field.type.kind === "array" && field.type.items.kind === "dynamicEnum" ? field.type.items.sourceId : void 0;
+  if (dynamicSourceId) {
+    const allowed = describeDynamicEnum(dynamicSourceId, options.resolvedEnums);
+    if (allowed) {
+      rules.push(allowed);
+    }
+  }
+  if (rules.length > 0) {
+    lines.push(`${indent}  Limits: ${rules.join("; ")}.`);
+  }
+  if (field.type.kind === "object" && bundle) {
+    const nested = bundle.schemas[field.type.nestedSchemaId];
+    if (nested && !visiting.has(nested.id)) {
+      visiting.add(nested.id);
+      lines.push(`${indent}  [${nested.id}: ${nested.description}]`);
+      for (const nestedField of nested.fields) {
+        lines.push(
+          ...buildFieldContext(
+            nestedField,
+            fieldPath,
+            bundle,
+            depth + 1,
+            options,
+            visiting
+          )
+        );
+      }
+      visiting.delete(nested.id);
+    }
+  }
+  if (field.type.kind === "array" && field.type.items.kind === "object" && bundle) {
+    const nested = bundle.schemas[field.type.items.nestedSchemaId];
+    if (nested && !visiting.has(nested.id)) {
+      visiting.add(nested.id);
+      lines.push(`${indent}  [Array of ${nested.id}: ${nested.description}]`);
+      for (const nestedField of nested.fields) {
+        lines.push(
+          ...buildFieldContext(
+            nestedField,
+            `${fieldPath}[]`,
+            bundle,
+            depth + 1,
+            options,
+            visiting
+          )
+        );
+      }
+      visiting.delete(nested.id);
+    }
+  }
+  return lines;
+}
+function buildPrompt(schema, bundle, options = {}) {
+  const lines = [
+    "You are a semantic coercion engine. Your task is to extract structured data from the user's input.",
+    "",
+    `Target schema: ${schema.id}`,
+    `Description: ${schema.description}`,
+    "",
+    "Fields:"
+  ];
+  const visiting = /* @__PURE__ */ new Set([schema.id]);
+  for (const field of schema.fields) {
+    lines.push(...buildFieldContext(field, "", bundle, 0, options, visiting));
+  }
+  lines.push("");
+  lines.push("Instructions:");
+  lines.push("- Extract values from the user's input that match the schema fields.");
+  lines.push("- Use null for optional fields that cannot be determined from the input.");
+  lines.push("- Required fields must always have a valid, non-null value.");
+  lines.push("- Interpret the user's input semantically \u2014 infer meaning, don't just pattern match.");
+  lines.push("- Respect every stated limit exactly; truncate or drop lower-priority content to stay within it.");
+  lines.push("- Return only the structured JSON output matching the schema.");
+  return lines.join("\n");
+}
+
+// src/coerce/repair.ts
+var MAX_RECEIVED_LENGTH = 200;
+function renderReceived(received) {
+  if (received === void 0) {
+    return "(missing)";
+  }
+  const text = JSON.stringify(received) ?? String(received);
+  return text.length > MAX_RECEIVED_LENGTH ? `${text.slice(0, MAX_RECEIVED_LENGTH)}\u2026 (truncated)` : text;
+}
+function buildRepairInput(originalInput, rejected, issues) {
+  const lines = [
+    originalInput,
+    "",
+    "---",
+    "",
+    "A previous attempt at this extraction produced:",
+    "",
+    JSON.stringify(rejected, null, 2),
+    "",
+    "It was rejected because:",
+    ""
+  ];
+  for (const issue of issues) {
+    lines.push(`- ${issue.path}: ${issue.message} (received: ${renderReceived(issue.received)})`);
+  }
+  lines.push(
+    "",
+    "Return a corrected object addressing every point above. Keep the values that were already right \u2014 only the listed fields are wrong. If the input genuinely does not support a value, leave the field out rather than inventing one."
+  );
+  return lines.join("\n");
+}
+
+// src/coerce/provenance.ts
+var WRAPPER_SUFFIX = "__WithProvenance";
+var ANNOTATION_SUFFIX = "__Annotated";
+var CONFIDENCE_VALUES = ["high", "medium", "low"];
+var PROVENANCE_INSTRUCTIONS = [
+  "",
+  "Provenance:",
+  "- Every field is wrapped as an object: put the extracted value in `value`.",
+  "- Set `confidence` to how well the input supports that value:",
+  '  "high" \u2014 stated outright in the input;',
+  '  "medium" \u2014 strongly implied, but not stated;',
+  '  "low" \u2014 a guess from weak or indirect signals.',
+  "- Set `evidence` to the shortest quote from the input the value came from.",
+  "  Leave `evidence` out when you inferred the value rather than reading it \u2014",
+  "  do not quote text that does not actually contain it.",
+  "- Judge each field on its own. A confident value next to a guessed one is",
+  "  normal, and marking the guess honestly is more useful than looking sure."
+].join("\n");
+function annotationSchema(parentId, field) {
+  const valueField = {
+    name: "value",
+    description: field.description,
+    type: field.type,
+    required: true,
+    ...field.constraints !== void 0 ? { constraints: field.constraints } : {}
+  };
+  return {
+    id: `${parentId}__${field.name}${ANNOTATION_SUFFIX}`,
+    description: `The extracted value for "${field.name}", with where it came from.`,
+    fields: [
+      valueField,
+      {
+        name: "confidence",
+        description: "How well the input supported this value.",
+        type: { kind: "enum", values: [...CONFIDENCE_VALUES] },
+        required: true
+      },
+      {
+        name: "evidence",
+        description: "The shortest quote from the input this value was read from. Omit when the value was inferred rather than read.",
+        type: { kind: "string" },
+        required: false
+      }
+    ]
+  };
+}
+function toProvenanceSchema(schema, bundle) {
+  const schemas = { ...bundle?.schemas ?? {} };
+  const fields = [];
+  for (const field of schema.fields) {
+    const annotation = annotationSchema(schema.id, field);
+    schemas[annotation.id] = annotation;
+    fields.push({
+      name: field.name,
+      description: field.description,
+      type: { kind: "object", nestedSchemaId: annotation.id },
+      required: field.required
+    });
+  }
+  const wrapper = {
+    id: `${schema.id}${WRAPPER_SUFFIX}`,
+    description: schema.description,
+    fields
+  };
+  schemas[wrapper.id] = wrapper;
+  return { schema: wrapper, bundle: { schemas } };
+}
+function isConfidence(value) {
+  return CONFIDENCE_VALUES.includes(value);
+}
+function splitProvenance(response, schema) {
+  const data = {};
+  const provenance = {};
+  for (const field of schema.fields) {
+    const annotated = response[field.name];
+    if (annotated === void 0 || annotated === null) {
+      data[field.name] = annotated ?? null;
+      continue;
+    }
+    if (typeof annotated !== "object" || Array.isArray(annotated) || !("value" in annotated)) {
+      data[field.name] = annotated;
+      continue;
+    }
+    const record = annotated;
+    data[field.name] = record.value ?? null;
+    if (isConfidence(record.confidence)) {
+      const evidence = record.evidence;
+      provenance[field.name] = {
+        confidence: record.confidence,
+        ...typeof evidence === "string" && evidence.length > 0 ? { evidence } : {}
+      };
+    }
+  }
+  return { data, provenance };
+}
+
+// src/coerce/validator.ts
+var MAX_LISTED_VALUES = 10;
+function summarizeValues(values) {
+  if (values.length <= MAX_LISTED_VALUES) {
+    return values.join(", ");
+  }
+  const shown = values.slice(0, MAX_LISTED_VALUES).join(", ");
+  return `${shown}, \u2026 (+${values.length - MAX_LISTED_VALUES} more)`;
+}
+function entries(count) {
+  return `${count} ${count === 1 ? "entry" : "entries"}`;
+}
+function validateConstraints(value, constraints, path, issues) {
+  const { minLength, maxLength, minimum, maximum, minItems, maxItems, pattern } = constraints;
+  if (Array.isArray(value)) {
+    if (minItems !== void 0 && value.length < minItems) {
+      issues.push({
+        path,
+        message: `Expected at least ${entries(minItems)}, got ${value.length}`,
+        received: value
+      });
+    }
+    if (maxItems !== void 0 && value.length > maxItems) {
+      issues.push({
+        path,
+        message: `Expected at most ${entries(maxItems)}, got ${value.length}`,
+        received: value
+      });
+    }
+    const { minItems: _min, maxItems: _max, ...itemConstraints } = constraints;
+    for (let i = 0; i < value.length; i++) {
+      validateConstraints(value[i], itemConstraints, `${path}[${i}]`, issues);
+    }
+    return;
+  }
+  if (typeof value === "string") {
+    if (minLength !== void 0 && value.length < minLength) {
+      issues.push({
+        path,
+        message: `Expected at least ${minLength} characters, got ${value.length}`,
+        received: value
+      });
+    }
+    if (maxLength !== void 0 && value.length > maxLength) {
+      issues.push({
+        path,
+        message: `Expected at most ${maxLength} characters, got ${value.length}`,
+        received: value
+      });
+    }
+    if (pattern !== void 0 && !new RegExp(pattern).test(value)) {
+      issues.push({
+        path,
+        message: `Expected a value matching /${pattern}/, got ${JSON.stringify(value)}`,
+        received: value
+      });
+    }
+    return;
+  }
+  if (typeof value === "number") {
+    if (minimum !== void 0 && value < minimum) {
+      issues.push({
+        path,
+        message: `Expected a value >= ${minimum}, got ${value}`,
+        received: value
+      });
+    }
+    if (maximum !== void 0 && value > maximum) {
+      issues.push({
+        path,
+        message: `Expected a value <= ${maximum}, got ${value}`,
+        received: value
+      });
+    }
+  }
+}
+function validateType(value, fieldType, path, bundle, options, issues) {
+  if (value === null || value === void 0) {
+    return;
+  }
+  switch (fieldType.kind) {
+    case "string":
+      if (typeof value !== "string") {
+        issues.push({
+          path,
+          message: `Expected string, got ${typeof value}`,
+          received: value
+        });
+      }
+      break;
+    case "number":
+      if (typeof value !== "number") {
+        issues.push({
+          path,
+          message: `Expected number, got ${typeof value}`,
+          received: value
+        });
+      }
+      break;
+    case "boolean":
+      if (typeof value !== "boolean") {
+        issues.push({
+          path,
+          message: `Expected boolean, got ${typeof value}`,
+          received: value
+        });
+      }
+      break;
+    case "enum":
+      if (typeof value !== "string" || !fieldType.values.includes(value)) {
+        issues.push({
+          path,
+          message: `Expected one of [${fieldType.values.join(", ")}], got ${JSON.stringify(value)}`,
+          received: value
+        });
+      }
+      break;
+    case "dynamicEnum": {
+      const values = options.resolvedEnums?.[fieldType.sourceId];
+      if (!values || values.length === 0) {
+        if (typeof value !== "string") {
+          issues.push({
+            path,
+            message: `Expected string, got ${typeof value}`,
+            received: value
+          });
+        }
+      } else if (typeof value !== "string" || !values.includes(value)) {
+        issues.push({
+          path,
+          message: `Expected one of the ${values.length} allowed "${fieldType.sourceId}" values [${summarizeValues(values)}], got ${JSON.stringify(value)}`,
+          received: value
+        });
+      }
+      break;
+    }
+    case "array":
+      if (!Array.isArray(value)) {
+        issues.push({
+          path,
+          message: `Expected array, got ${typeof value}`,
+          received: value
+        });
+      } else {
+        for (let i = 0; i < value.length; i++) {
+          validateType(
+            value[i],
+            fieldType.items,
+            `${path}[${i}]`,
+            bundle,
+            options,
+            issues
+          );
+        }
+      }
+      break;
+    case "object": {
+      if (typeof value !== "object" || Array.isArray(value)) {
+        issues.push({
+          path,
+          message: `Expected object, got ${Array.isArray(value) ? "array" : typeof value}`,
+          received: value
+        });
+      } else if (bundle) {
+        const nested = bundle.schemas[fieldType.nestedSchemaId];
+        if (nested) {
+          validateFields(
+            value,
+            nested,
+            path,
+            bundle,
+            true,
+            // strict for nested objects in strict mode
+            options,
+            issues
+          );
+        }
+      }
+      break;
+    }
+  }
+}
+function validateFields(data, schema, parentPath, bundle, strict, options, issues) {
+  for (const field of schema.fields) {
+    const path = parentPath ? `${parentPath}.${field.name}` : field.name;
+    const value = data[field.name];
+    if (value === null || value === void 0) {
+      if (strict && field.required) {
+        issues.push({
+          path,
+          message: "Required field is missing",
+          received: value
+        });
+      }
+      continue;
+    }
+    validateType(value, field.type, path, bundle, options, issues);
+    if (field.constraints) {
+      validateConstraints(value, field.constraints, path, issues);
+    }
+  }
+}
+function validateStrict(data, schema, bundle, options = {}) {
+  const issues = [];
+  validateFields(data, schema, "", bundle, true, options, issues);
+  return issues;
+}
+function validatePartial(data, schema, bundle, options = {}) {
+  const issues = [];
+  validateFields(data, schema, "", bundle, false, options, issues);
+  return issues;
+}
+
+// src/tracing/tracer.ts
+var spanCounter = 0;
+function generateSpanId() {
+  return `span_${++spanCounter}_${Date.now()}`;
+}
+var Tracer = class {
+  sinks;
+  constructor(sinks) {
+    this.sinks = sinks ?? [];
+  }
+  startSpan(name, attributes, parent) {
+    return {
+      id: generateSpanId(),
+      name,
+      startTime: Date.now(),
+      events: [],
+      attributes,
+      parentId: parent?.id
+    };
+  }
+  endSpan(span) {
+    span.endTime = Date.now();
+    for (const sink of this.sinks) {
+      sink.write(span);
+    }
+  }
+  addEvent(span, name, attributes) {
+    span.events.push({
+      name,
+      timestamp: Date.now(),
+      attributes
+    });
+  }
+};
+
+// src/coerce/coerce.ts
+async function resolveEnums(schema, bundle, enumResolver, tracer, parent) {
+  if (!enumResolver) {
+    return void 0;
+  }
+  const span = tracer.startSpan("resolveEnums", {}, parent);
+  try {
+    const { enums, failures } = await resolveEnumSources(
+      schema,
+      enumResolver,
+      bundle
+    );
+    tracer.addEvent(span, "enumsResolved", {
+      sourceIds: Object.keys(enums),
+      valueCounts: Object.fromEntries(
+        Object.entries(enums).map(([id, values]) => [id, values.length])
+      )
+    });
+    for (const failure of failures) {
+      tracer.addEvent(span, "enumSourceFailed", {
+        sourceId: failure.sourceId,
+        reason: failure.reason,
+        required: failure.required,
+        paths: failure.paths
+      });
+    }
+    const fatal = failures.filter((f) => f.required);
+    if (fatal.length > 0) {
+      throw new EnumResolutionError(fatal);
+    }
+    return enums;
+  } finally {
+    tracer.endSpan(span);
+  }
+}
+async function runCoercion(input, options, { mode, provenance }) {
+  const { provider, schema, bundle, enumResolver, traceSinks } = options;
+  const maxRepairAttempts = options.maxRepairAttempts ?? 0;
+  if (!Number.isInteger(maxRepairAttempts) || maxRepairAttempts < 0) {
+    throw new RangeError(
+      `maxRepairAttempts must be a non-negative integer, got ${String(options.maxRepairAttempts)}`
+    );
+  }
+  const tracer = new Tracer(traceSinks);
+  const rootSpan = tracer.startSpan(mode, { schemaId: schema.id, provenance });
+  try {
+    const resolvedEnums = await resolveEnums(
+      schema,
+      bundle,
+      enumResolver,
+      tracer,
+      rootSpan
+    );
+    const promptSpan = tracer.startSpan("buildPrompt", {}, rootSpan);
+    const basePrompt = buildPrompt(schema, bundle, { resolvedEnums });
+    const systemPrompt = provenance ? `${basePrompt}
+${PROVENANCE_INSTRUCTIONS}` : basePrompt;
+    tracer.addEvent(promptSpan, "promptBuilt", {
+      promptLength: systemPrompt.length
+    });
+    tracer.endSpan(promptSpan);
+    const request = provenance ? toProvenanceSchema(schema, bundle) : { schema, bundle };
+    const schemaSpan = tracer.startSpan("buildJsonSchema", {}, rootSpan);
+    const jsonSchema = runtimeSchemaToJsonSchema(request.schema, request.bundle, {
+      resolvedEnums
+    });
+    tracer.endSpan(schemaSpan);
+    const validate = mode === "coerce" ? validateStrict : validatePartial;
+    let userInput = input;
+    let issues = [];
+    let run = { data: {}, provenance: {} };
+    for (let attempt = 0; attempt <= maxRepairAttempts; attempt++) {
+      const llmSpan = tracer.startSpan("llmCall", { attempt }, rootSpan);
+      const response = await provider.complete({
+        systemPrompt,
+        userInput,
+        jsonSchema,
+        schema: request.schema,
+        bundle: request.bundle,
+        resolvedEnums
+      });
+      tracer.addEvent(llmSpan, "responseReceived", { usage: response.usage });
+      tracer.endSpan(llmSpan);
+      run = provenance ? splitProvenance(response.data, schema) : { data: response.data, provenance: {} };
+      const validationSpan = tracer.startSpan("validate", { attempt }, rootSpan);
+      issues = validate(run.data, schema, bundle, { resolvedEnums });
+      tracer.addEvent(validationSpan, "validated", { issueCount: issues.length });
+      tracer.endSpan(validationSpan);
+      if (issues.length === 0) {
+        return run;
+      }
+      if (attempt < maxRepairAttempts) {
+        tracer.addEvent(rootSpan, "repairAttempt", {
+          attempt: attempt + 1,
+          issueCount: issues.length,
+          paths: issues.map((issue) => issue.path)
+        });
+        userInput = buildRepairInput(input, run.data, issues);
+      }
+    }
+    throw new CoerceError(issues);
+  } finally {
+    tracer.endSpan(rootSpan);
+  }
+}
+function stripNulls(data) {
+  const result = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (value !== null) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+async function coerce(input, options) {
+  const { data } = await runCoercion(input, options, {
+    mode: "coerce",
+    provenance: false
+  });
+  return data;
+}
+async function partialCoerce(input, options) {
+  const { data } = await runCoercion(input, options, {
+    mode: "partialCoerce",
+    provenance: false
+  });
+  return stripNulls(data);
+}
+async function coerceWithProvenance(input, options) {
+  const { data, provenance } = await runCoercion(input, options, {
+    mode: "coerce",
+    provenance: true
+  });
+  return { data, provenance };
+}
+async function partialCoerceWithProvenance(input, options) {
+  const { data, provenance } = await runCoercion(input, options, {
+    mode: "partialCoerce",
+    provenance: true
+  });
+  return { data: stripNulls(data), provenance };
+}
+
+// src/coerce/config.ts
+var SemblConfig = class _SemblConfig {
+  static _config = {};
+  /** Set global defaults. */
+  static configure(config) {
+    _SemblConfig._config = { ...config };
+  }
+  /** Reset global config to empty (useful in tests). */
+  static reset() {
+    _SemblConfig._config = {};
+  }
+  /** Read-only access to the current global config. */
+  static get current() {
+    return _SemblConfig._config;
+  }
+};
+function resolveConfig(callConfig) {
+  const global = SemblConfig.current;
+  const provider = callConfig?.provider ?? global.provider;
+  if (!provider) {
+    throw new Error(
+      "No provider configured. Call SemblConfig.configure({ provider }) or pass { provider } to sembl()."
+    );
+  }
+  return {
+    provider,
+    bundle: callConfig?.bundle ?? global.bundle,
+    enumResolver: callConfig?.enumResolver ?? global.enumResolver,
+    traceSinks: callConfig?.traceSinks ?? global.traceSinks,
+    maxRepairAttempts: callConfig?.maxRepairAttempts ?? global.maxRepairAttempts
+  };
+}
+
+// src/coerce/coercible.ts
+function serialize(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  return JSON.stringify(value);
+}
+var Coercible = class _Coercible {
+  constructor(_promise, _config) {
+    this._promise = _promise;
+    this._config = _config;
+  }
+  /** The per-call options every link in the chain shares. */
+  _optionsFor(schema) {
+    return {
+      provider: this._config.provider,
+      schema,
+      bundle: this._config.bundle,
+      enumResolver: this._config.enumResolver,
+      traceSinks: this._config.traceSinks,
+      maxRepairAttempts: this._config.maxRepairAttempts
+    };
+  }
+  /**
+   * Chain a full coercion to a new schema.
+   * The current value is serialized and used as input for the next LLM call.
+   */
+  coerceTo(schema) {
+    const next = this._promise.then(
+      (value) => coerce(serialize(value), this._optionsFor(schema))
+    );
+    return new _Coercible(next, this._config);
+  }
+  /**
+   * Chain a partial coercion to a new schema.
+   * The current value is serialized and used as input for the next LLM call.
+   */
+  partialCoerceTo(schema) {
+    const next = this._promise.then(
+      (value) => partialCoerce(serialize(value), this._optionsFor(schema))
+    );
+    return new _Coercible(next, this._config);
+  }
+  then(onfulfilled, onrejected) {
+    return this._promise.then(onfulfilled, onrejected);
+  }
+  catch(onrejected) {
+    return this._promise.catch(onrejected);
+  }
+  finally(onfinally) {
+    return this._promise.finally(onfinally);
+  }
+};
+function sembl(input, config) {
+  const resolved = resolveConfig(config);
+  const serialized = serialize(input);
+  return new Coercible(Promise.resolve(serialized), resolved);
+}
+
+// src/tracing/console-sink.ts
+var ConsoleSink = class {
+  write(span) {
+    const duration = span.endTime ? span.endTime - span.startTime : "?";
+    const prefix = span.parentId ? "  " : "";
+    console.log(
+      `${prefix}[trace] ${span.name} (${duration}ms)`,
+      span.attributes ?? ""
+    );
+    for (const event of span.events) {
+      console.log(
+        `${prefix}  [event] ${event.name}`,
+        event.attributes ?? ""
+      );
+    }
+  }
+};
+export {
+  CoerceError,
+  Coercible,
+  ConsoleSink,
+  Constrain,
+  Describe,
+  EnumResolutionError,
+  PROVENANCE_INSTRUCTIONS,
+  Schema,
+  SchemaRegistry,
+  SemblConfig,
+  Tracer,
+  ValuesFrom,
+  buildPrompt,
+  buildRepairInput,
+  coerce,
+  coerceWithProvenance,
+  collectEnumSources,
+  partialCoerce,
+  partialCoerceWithProvenance,
+  resolveEnumSources,
+  runtimeSchemaToJsonSchema,
+  sembl,
+  splitProvenance,
+  toOpenAIJsonSchema,
+  toProvenanceSchema,
+  validatePartial,
+  validateStrict
+};
+//# sourceMappingURL=index.js.map