@qloo/qloo-harness 0.1.18

package/dist/resolution-provider.js

@@ -0,0 +1,1380 @@
+import { createRequire as __qlooCreateRequire } from "node:module";
+const require = __qlooCreateRequire(import.meta.url);
+
+// packages/qloo-tool-schema/dist/upstream.lock.json
+var upstream_lock_default = {
+  lockVersion: 1,
+  source: {
+    documentationUrl: "https://docs.qloo.com",
+    registryUrl: "https://dash.readme.com/api/v1/api-registry/4svkj1svmrti5tfx",
+    registryId: "4svkj1svmrti5tfx",
+    retrievedAt: "2026-08-20",
+    apiTitle: "Qloo API",
+    apiVersion: "2.0",
+    openapiVersion: "3.1.0",
+    sha256: "da8d4b830f2a646815d25afcaa653f81f1ad939707e2e2560d2d0b9f103076f1"
+  },
+  expectations: {
+    productionServer: "https://api.qloo.com",
+    authentication: {
+      scheme: "ApiKey",
+      type: "apiKey",
+      location: "header",
+      header: "X-Api-Key"
+    },
+    getPaths: [
+      "/",
+      "/entities",
+      "/search",
+      "/v2/analysis/compare",
+      "/v2/audiences",
+      "/v2/audiences/types",
+      "/v2/insights",
+      "/v2/tags",
+      "/v2/tags/types",
+      "/v2/trending"
+    ]
+  },
+  documentedExceptions: [
+    {
+      value: "urn:demographics",
+      scope: "/v2/insights filter.type",
+      status: "documented-but-not-enumerated",
+      documentationUrl: "https://docs.qloo.com/reference/demographics-use-case",
+      treatment: "Preserve as an explicit documentation exception; do not synthesize an endpoint payload schema from it."
+    },
+    {
+      value: "urn:tag",
+      scope: "/v2/insights filter.type",
+      status: "documented-but-not-enumerated",
+      documentationUrl: "https://docs.qloo.com/reference/taste-analysis",
+      treatment: "The pinned specification mentions this value in diversify.by documentation but omits it from the filter.type enum; preserve the discrepancy for review."
+    }
+  ]
+};
+
+// packages/qloo-tool-schema/dist/src/catalog.js
+var QLOO_TOOL_CATALOG_VERSION = "1.0.0";
+var QLOO_TOOL_RESULT_SCHEMA_VERSION = "1.0-preview.1";
+var QLOO_WORKFLOW_OPERATION_IDS = [
+  "recommend",
+  "rank",
+  "describe",
+  "where_popular",
+  "compare_audiences",
+  "entity_tags",
+  "audience_demographics",
+  "trends",
+  "find_tags"
+];
+var QLOO_CAPABILITIES_TOOL_NAME = "qloo_capabilities";
+var QLOO_INSIGHTS_ENTITY_TYPES = [
+  { id: "artist", urn: "urn:entity:artist" },
+  { id: "book", urn: "urn:entity:book" },
+  { id: "brand", urn: "urn:entity:brand" },
+  { id: "movie", urn: "urn:entity:movie" },
+  { id: "person", urn: "urn:entity:person" },
+  { id: "place", urn: "urn:entity:place" },
+  { id: "podcast", urn: "urn:entity:podcast" },
+  { id: "tv_show", urn: "urn:entity:tv_show" },
+  { id: "videogame", urn: "urn:entity:videogame" }
+];
+var QLOO_SEARCH_ENTITY_TYPES = [
+  ...QLOO_INSIGHTS_ENTITY_TYPES,
+  { id: "locality", urn: "urn:entity:locality" },
+  { id: "actor", urn: "urn:entity:actor" },
+  { id: "album", urn: "urn:entity:album" },
+  { id: "author", urn: "urn:entity:author" },
+  { id: "director", urn: "urn:entity:director" }
+];
+function buildEntityTypeAliases(entityTypes) {
+  const aliases = /* @__PURE__ */ new Map();
+  const urnById = new Map(entityTypes.map(({ id, urn }) => [id, urn]));
+  for (const entityType2 of entityTypes) {
+    aliases.set(entityType2.id, entityType2.urn);
+    aliases.set(entityType2.urn, entityType2.urn);
+    aliases.set(`${entityType2.id}s`, entityType2.urn);
+  }
+  const addAlias = (alias, id) => {
+    const urn = urnById.get(id);
+    if (urn)
+      aliases.set(alias, urn);
+  };
+  addAlias("people", "person");
+  addAlias("localities", "locality");
+  addAlias("tv", "tv_show");
+  addAlias("show", "tv_show");
+  addAlias("shows", "tv_show");
+  addAlias("tv show", "tv_show");
+  addAlias("tv shows", "tv_show");
+  addAlias("game", "videogame");
+  addAlias("games", "videogame");
+  addAlias("video game", "videogame");
+  addAlias("video games", "videogame");
+  return aliases;
+}
+var insightsEntityTypeByAlias = buildEntityTypeAliases(QLOO_INSIGHTS_ENTITY_TYPES);
+var searchEntityTypeByAlias = buildEntityTypeAliases(QLOO_SEARCH_ENTITY_TYPES);
+var operationSummaries = {
+  recommend: "Find entities for a taste profile, audience, or collection of signals.",
+  rank: "Rank a supplied set of options for signals, location, or audience.",
+  describe: "Resolve and describe one Qloo entity.",
+  where_popular: "Find geographic areas where an entity has comparatively strong affinity.",
+  compare_audiences: "Contrast two signal groups and identify shared or differentiating affinities.",
+  entity_tags: "Retrieve concepts and tags that characterize entities.",
+  audience_demographics: "Retrieve aggregate audience segments associated with an entity.",
+  trends: "Retrieve interest or trend information over a time range.",
+  find_tags: "Search the Qloo tag ontology by natural-language concept."
+};
+var QLOO_WORKFLOW_OPERATIONS = Object.freeze(QLOO_WORKFLOW_OPERATION_IDS.map((id) => Object.freeze({
+  id,
+  toolName: `qloo_${id}`,
+  summary: operationSummaries[id],
+  since: QLOO_TOOL_CATALOG_VERSION
+})));
+var upstreamLock = upstream_lock_default;
+var upstreamGetPaths = Object.freeze([
+  ...upstreamLock.expectations.getPaths
+]);
+var documentedExceptions = Object.freeze(upstreamLock.documentedExceptions.map((exception) => Object.freeze({ ...exception })));
+var QLOO_CAPABILITIES_TOOL = Object.freeze({
+  name: QLOO_CAPABILITIES_TOOL_NAME,
+  description: "Return the versioned Qloo workflow catalog and pinned upstream API contract metadata without making a network request.",
+  inputSchema: Object.freeze({
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "object",
+    additionalProperties: false,
+    properties: Object.freeze({
+      operation_ids: Object.freeze({
+        type: "array",
+        description: "Optional canonical operation IDs to include. Omit for the complete catalog.",
+        uniqueItems: true,
+        items: Object.freeze({
+          type: "string",
+          enum: QLOO_WORKFLOW_OPERATION_IDS
+        })
+      })
+    })
+  })
+});
+var operationIds = new Set(QLOO_WORKFLOW_OPERATION_IDS);
+
+// packages/qloo-tool-schema/dist/src/workflow-contracts.js
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+var QLOO_TOOL_DEFAULT_LIMIT = 10;
+var QLOO_TOOL_MAX_RESULTS = 20;
+var QLOO_TAG_BOOLEAN_OPERATORS = ["union", "intersection"];
+var insightsEntityTypeIds = QLOO_INSIGHTS_ENTITY_TYPES.map(({ id }) => id);
+var searchEntityTypeIds = QLOO_SEARCH_ENTITY_TYPES.map(({ id }) => id);
+var QLOO_INSIGHTS_ENTITY_TYPE_SCHEMA = Type.String({
+  enum: insightsEntityTypeIds,
+  description: `Qloo Insights entity type: ${insightsEntityTypeIds.join(", ")}.`
+});
+var QLOO_SEARCH_ENTITY_TYPE_SCHEMA = Type.String({
+  enum: searchEntityTypeIds,
+  description: `Qloo search entity type: ${searchEntityTypeIds.join(", ")}.`
+});
+var QLOO_TAG_BOOLEAN_OPERATOR_SCHEMA = Type.String({
+  enum: QLOO_TAG_BOOLEAN_OPERATORS,
+  description: "Combine tag values with union (any) or intersection (all)."
+});
+var QLOO_LIMIT_SCHEMA = Type.Optional(Type.Integer({
+  minimum: 1,
+  maximum: QLOO_TOOL_MAX_RESULTS,
+  default: QLOO_TOOL_DEFAULT_LIMIT,
+  description: `Maximum results to return (1-${QLOO_TOOL_MAX_RESULTS}).`
+}));
+var QLOO_ENTITY_INPUTS_SCHEMA = Type.Array(Type.String({ minLength: 1 }), {
+  minItems: 1,
+  maxItems: 10,
+  description: "Entity names or Qloo entity UUIDs. Keep one combined taste profile in one call."
+});
+var QLOO_TAG_INPUTS_SCHEMA = Type.Array(Type.String({ minLength: 1 }), {
+  minItems: 1,
+  maxItems: 10,
+  description: "Natural-language tag concepts or stable Qloo tag URNs."
+});
+var QLOO_DEMOGRAPHIC_SCHEMA = Type.String({
+  minLength: 1,
+  description: "Audience demographic in natural language, such as 'young women', 'men 25-34', or 'millennials'. It is converted to documented Qloo demographic signals.",
+  examples: ["young women", "men 25-34", "millennials"]
+});
+var QLOO_REQUEST_PREVIEW_SCHEMA = Type.Object({
+  method: Type.Literal("GET"),
+  path: Type.String({ minLength: 1 }),
+  query: Type.Unknown()
+}, { additionalProperties: false });
+var QLOO_RESULT_ENVELOPE_SCHEMA = Type.Object({
+  schema_version: Type.Literal(QLOO_TOOL_RESULT_SCHEMA_VERSION),
+  operation: Type.String(),
+  status: Type.Union([
+    Type.Literal("ok"),
+    Type.Literal("empty"),
+    Type.Literal("needs_input"),
+    Type.Literal("partial"),
+    Type.Literal("degraded"),
+    Type.Literal("error")
+  ]),
+  summary: Type.Optional(Type.String()),
+  interpretation: Type.Optional(Type.Unknown()),
+  results: Type.Optional(Type.Unknown()),
+  result_count: Type.Optional(Type.Integer({ minimum: 0 })),
+  warnings: Type.Optional(Type.Array(Type.String())),
+  query_intent: Type.Optional(Type.Unknown()),
+  error: Type.Optional(Type.Object({
+    code: Type.String(),
+    layer: Type.String(),
+    retryable: Type.Boolean(),
+    recovery: Type.String()
+  }, { additionalProperties: false })),
+  execution: Type.Object({
+    transport: Type.String({ enum: ["direct", "cli", "mcp"] }),
+    transport_name: Type.String(),
+    correlation_id: Type.String(),
+    duration_ms: Type.Number({ minimum: 0 })
+  }, { additionalProperties: false }),
+  provenance: Type.Optional(Type.Object({
+    source: Type.String(),
+    endpoint: Type.String(),
+    documentation: Type.String(),
+    transport: Type.Optional(Type.String()),
+    requests: Type.Optional(Type.Array(QLOO_REQUEST_PREVIEW_SCHEMA, {
+      maxItems: 20
+    }))
+  }, { additionalProperties: false }))
+}, { additionalProperties: true });
+var QLOO_WORKFLOW_INPUT_SCHEMAS = {
+  recommend: Type.Object({
+    target_type: QLOO_INSIGHTS_ENTITY_TYPE_SCHEMA,
+    signals: Type.Optional(QLOO_ENTITY_INPUTS_SCHEMA),
+    signal_tags: Type.Optional(QLOO_TAG_INPUTS_SCHEMA),
+    signal_tags_operator: Type.Optional(QLOO_TAG_BOOLEAN_OPERATOR_SCHEMA),
+    signal_location: Type.Optional(Type.String({ minLength: 1 })),
+    demographic: Type.Optional(QLOO_DEMOGRAPHIC_SCHEMA),
+    filter_location: Type.Optional(Type.String({ minLength: 1 })),
+    include_tags: Type.Optional(QLOO_TAG_INPUTS_SCHEMA),
+    include_tags_operator: Type.Optional(QLOO_TAG_BOOLEAN_OPERATOR_SCHEMA),
+    exclude_tags: Type.Optional(QLOO_TAG_INPUTS_SCHEMA),
+    exclude_tags_operator: Type.Optional(QLOO_TAG_BOOLEAN_OPERATOR_SCHEMA),
+    explain: Type.Optional(Type.Boolean({ default: true })),
+    limit: QLOO_LIMIT_SCHEMA
+  }, { additionalProperties: false }),
+  rank: Type.Object({
+    options: QLOO_ENTITY_INPUTS_SCHEMA,
+    option_type: QLOO_INSIGHTS_ENTITY_TYPE_SCHEMA,
+    signals: Type.Optional(QLOO_ENTITY_INPUTS_SCHEMA),
+    signal_location: Type.Optional(Type.String({ minLength: 1 })),
+    demographic: Type.Optional(QLOO_DEMOGRAPHIC_SCHEMA),
+    include_tags: Type.Optional(QLOO_TAG_INPUTS_SCHEMA),
+    exclude_tags: Type.Optional(QLOO_TAG_INPUTS_SCHEMA)
+  }, { additionalProperties: false }),
+  describe: Type.Object({
+    entity: Type.String({ minLength: 1 }),
+    type: Type.Optional(QLOO_SEARCH_ENTITY_TYPE_SCHEMA)
+  }, { additionalProperties: false }),
+  where_popular: Type.Object({
+    entity: Type.String({ minLength: 1 }),
+    entity_type: Type.Optional(QLOO_SEARCH_ENTITY_TYPE_SCHEMA),
+    within: Type.String({
+      minLength: 1,
+      description: "Required geographic area that constrains the heatmap."
+    }),
+    limit: QLOO_LIMIT_SCHEMA
+  }, { additionalProperties: false }),
+  compare_audiences: Type.Object({
+    group_a: QLOO_ENTITY_INPUTS_SCHEMA,
+    group_b: QLOO_ENTITY_INPUTS_SCHEMA,
+    target_type: Type.Optional(QLOO_INSIGHTS_ENTITY_TYPE_SCHEMA),
+    limit: QLOO_LIMIT_SCHEMA
+  }, { additionalProperties: false }),
+  entity_tags: Type.Object({
+    entities: QLOO_ENTITY_INPUTS_SCHEMA,
+    entity_type: Type.Optional(QLOO_SEARCH_ENTITY_TYPE_SCHEMA),
+    limit: QLOO_LIMIT_SCHEMA
+  }, { additionalProperties: false }),
+  audience_demographics: Type.Object({
+    entity: Type.String({ minLength: 1 }),
+    entity_type: Type.Optional(QLOO_SEARCH_ENTITY_TYPE_SCHEMA),
+    limit: QLOO_LIMIT_SCHEMA
+  }, { additionalProperties: false }),
+  trends: Type.Object({
+    entities: Type.Array(Type.String({ minLength: 1 }), { minItems: 1, maxItems: 5 }),
+    entity_type: QLOO_INSIGHTS_ENTITY_TYPE_SCHEMA,
+    start_date: Type.String({
+      pattern: "^\\d{4}-\\d{2}-\\d{2}$",
+      description: "Inclusive start date in YYYY-MM-DD format."
+    }),
+    end_date: Type.String({
+      pattern: "^\\d{4}-\\d{2}-\\d{2}$",
+      description: "Inclusive end date in YYYY-MM-DD format."
+    }),
+    limit: QLOO_LIMIT_SCHEMA
+  }, { additionalProperties: false }),
+  find_tags: Type.Object({
+    query: Type.String({ minLength: 1 }),
+    semantic: Type.Optional(Type.Boolean({ default: true })),
+    limit: QLOO_LIMIT_SCHEMA
+  }, { additionalProperties: false })
+};
+var sharedWorkflowBehavior = Object.freeze({
+  readOnly: true,
+  idempotent: true,
+  mutating: false,
+  destructive: false,
+  openWorld: true,
+  concurrency: "safe_for_independent_inputs",
+  requiredCredential: "qloo_api",
+  defaultResultBudget: QLOO_TOOL_DEFAULT_LIMIT,
+  maximumResultBudget: QLOO_TOOL_MAX_RESULTS,
+  safeRetryClasses: Object.freeze(["dns", "connect", "timeout", "rate_limit", "upstream_5xx"]),
+  supportedTransports: Object.freeze(["direct", "mcp"])
+});
+var mediumLatencyOperations = /* @__PURE__ */ new Set([
+  "recommend",
+  "rank",
+  "compare_audiences",
+  "entity_tags",
+  "audience_demographics",
+  "trends"
+]);
+var QLOO_WORKFLOW_BEHAVIORS = Object.freeze(Object.fromEntries(Object.keys(QLOO_WORKFLOW_INPUT_SCHEMAS).map((operation) => [
+  operation,
+  Object.freeze({
+    ...sharedWorkflowBehavior,
+    expectedLatency: mediumLatencyOperations.has(operation) ? "medium" : "low"
+  })
+])));
+var QLOO_WORKFLOW_METADATA = {
+  recommend: {
+    toolName: "qloo_recommend",
+    label: "Qloo recommendations",
+    description: "Find Qloo entities related to one combined entity, tag, location, and demographic taste profile. Signals influence affinity; filters constrain output.",
+    promptSnippet: "Recommend entities from a combined Qloo taste profile",
+    promptGuidelines: [
+      "Pass every related taste and audience signal together in one qloo_recommend call.",
+      "Use signal_location for audience location and filter_location to constrain result geography.",
+      "Include demographic and location in the same call when both describe the audience."
+    ],
+    documentation: ["https://docs.qloo.com/reference/insights-api-deep-dive"]
+  },
+  rank: {
+    toolName: "qloo_rank",
+    label: "Qloo rank",
+    description: "Rank one supplied option set against one shared entity, location, demographic, and tag profile. Scores from separate calls are not comparable.",
+    promptSnippet: "Rank a caller-supplied shortlist with Qloo",
+    promptGuidelines: ["Pass every option in one qloo_rank call so scores remain comparable."],
+    documentation: ["https://docs.qloo.com/reference/insights-api-deep-dive"]
+  },
+  describe: {
+    toolName: "qloo_describe",
+    label: "Qloo entity",
+    description: "Resolve one named entity or Qloo UUID and return only metadata present in Qloo.",
+    promptSnippet: "Resolve and describe one Qloo entity",
+    documentation: ["https://docs.qloo.com/reference/get-search", "https://docs.qloo.com/reference/get-entities"]
+  },
+  where_popular: {
+    toolName: "qloo_where_popular",
+    label: "Qloo geographic affinity",
+    description: "Find geographic areas where one entity has strong query-relative affinity. This is distinct from filtering recommendations to a place.",
+    promptSnippet: "Find where an entity is comparatively popular",
+    documentation: ["https://docs.qloo.com/reference/heatmaps-use-case"]
+  },
+  compare_audiences: {
+    toolName: "qloo_compare_audiences",
+    label: "Qloo audience comparison",
+    description: "Compare two complete groups of entity signals in one Qloo analysis request.",
+    promptSnippet: "Compare two Qloo taste-signal groups",
+    documentation: ["https://docs.qloo.com/reference/analysis-compare"]
+  },
+  entity_tags: {
+    toolName: "qloo_entity_tags",
+    label: "Qloo entity tags",
+    description: "Retrieve Qloo concepts that jointly characterize one or more entities using the documented urn:tag Insights workflow.",
+    promptSnippet: "Find concepts that characterize Qloo entities",
+    documentation: ["https://docs.qloo.com/reference/taste-analysis"]
+  },
+  audience_demographics: {
+    toolName: "qloo_audience_demographics",
+    label: "Qloo audience demographics",
+    description: "Retrieve aggregate demographic distributions associated with one entity through the documented urn:demographics Insights workflow.",
+    promptSnippet: "Inspect aggregate demographics associated with a Qloo entity",
+    documentation: ["https://docs.qloo.com/reference/demographics-use-case"]
+  },
+  trends: {
+    toolName: "qloo_trends",
+    label: "Qloo trends",
+    description: "Retrieve Qloo time-series popularity metrics for one to five resolved entities over an ISO date range.",
+    promptSnippet: "Track Qloo entity popularity metrics over time",
+    documentation: ["https://docs.qloo.com/reference/get-trending"]
+  },
+  find_tags: {
+    toolName: "qloo_find_tags",
+    label: "Qloo tag search",
+    description: "Search Qloo's tag ontology by natural-language concept and return stable tag URNs.",
+    promptSnippet: "Search the Qloo tag ontology",
+    documentation: ["https://docs.qloo.com/reference/get-tags-1"]
+  }
+};
+var QLOO_WORKFLOW_CONTRACTS = Object.freeze(Object.fromEntries(Object.entries(QLOO_WORKFLOW_METADATA).map(([id, metadata]) => [
+  id,
+  Object.freeze({
+    id,
+    ...metadata,
+    behavior: QLOO_WORKFLOW_BEHAVIORS[id],
+    inputSchema: QLOO_WORKFLOW_INPUT_SCHEMAS[id],
+    resultSchema: QLOO_RESULT_ENVELOPE_SCHEMA
+  })
+])));
+
+// packages/qloo-tool-schema/dist/src/resolution-contracts.js
+import { Type as Type2 } from "typebox";
+var QLOO_RESOLUTION_CONTRACT_VERSION = "1.0-preview.1";
+var QLOO_RESOLUTION_PROVIDER_DESCRIPTOR_SCHEMA = Type2.Object({
+  contract_version: Type2.Literal(QLOO_RESOLUTION_CONTRACT_VERSION),
+  provider_id: Type2.String({ minLength: 1 }),
+  name: Type2.String({ minLength: 1 }),
+  entity_strategy: Type2.String({ minLength: 1 }),
+  tag_strategy: Type2.String({ minLength: 1 }),
+  remote: Type2.Boolean(),
+  uses_model: Type2.Boolean(),
+  fallback: Type2.Literal("none")
+}, { additionalProperties: false });
+var QLOO_RESOLUTION_CANDIDATE_SCHEMA = Type2.Object({
+  id: Type2.String({ minLength: 1 }),
+  name: Type2.String({ minLength: 1 }),
+  type: Type2.Optional(Type2.String({ minLength: 1 })),
+  rank: Type2.Optional(Type2.Integer({ minimum: 1 })),
+  score: Type2.Optional(Type2.Number()),
+  popularity: Type2.Optional(Type2.Number()),
+  parent_types: Type2.Optional(Type2.Array(Type2.String({ minLength: 1 }), {
+    maxItems: 20,
+    uniqueItems: true
+  })),
+  description: Type2.Optional(Type2.String({ minLength: 1, maxLength: 500 })),
+  release_year: Type2.Optional(Type2.Integer()),
+  address: Type2.Optional(Type2.Unknown())
+}, { additionalProperties: false });
+var QLOO_RESOLUTION_PROVENANCE_SCHEMA = Type2.Object({
+  contract_version: Type2.Literal(QLOO_RESOLUTION_CONTRACT_VERSION),
+  provider_id: Type2.String({ minLength: 1 }),
+  provider_name: Type2.String({ minLength: 1 }),
+  endpoint: Type2.String({ minLength: 1 }),
+  strategy: Type2.String({ minLength: 1 }),
+  remote: Type2.Boolean(),
+  uses_model: Type2.Boolean(),
+  provider_version: Type2.Optional(Type2.String({ minLength: 1 })),
+  cache_status: Type2.Optional(Type2.String({ minLength: 1 }))
+}, { additionalProperties: false });
+var QLOO_RESOLUTION_OUTCOME_COMMON_SCHEMA = {
+  input: Type2.String({ minLength: 1 }),
+  provenance: QLOO_RESOLUTION_PROVENANCE_SCHEMA,
+  warnings: Type2.Optional(Type2.Array(Type2.String()))
+};
+var QLOO_RESOLUTION_OUTCOME_SCHEMA = Type2.Union([
+  Type2.Object({
+    ...QLOO_RESOLUTION_OUTCOME_COMMON_SCHEMA,
+    status: Type2.Literal("resolved"),
+    match: Type2.Union([
+      Type2.Literal("identifier"),
+      Type2.Literal("exact"),
+      Type2.Literal("semantic")
+    ]),
+    selected: QLOO_RESOLUTION_CANDIDATE_SCHEMA,
+    alternatives: Type2.Optional(Type2.Array(QLOO_RESOLUTION_CANDIDATE_SCHEMA))
+  }, { additionalProperties: false }),
+  Type2.Object({
+    ...QLOO_RESOLUTION_OUTCOME_COMMON_SCHEMA,
+    status: Type2.Literal("ambiguous"),
+    candidates: Type2.Array(QLOO_RESOLUTION_CANDIDATE_SCHEMA)
+  }, { additionalProperties: false }),
+  Type2.Object({
+    ...QLOO_RESOLUTION_OUTCOME_COMMON_SCHEMA,
+    status: Type2.Literal("not_found"),
+    candidates: Type2.Optional(Type2.Array(QLOO_RESOLUTION_CANDIDATE_SCHEMA))
+  }, { additionalProperties: false })
+]);
+
+// apps/qloo-harness/dist/resolution-provider.js
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+var TAG_URN_PREFIX = "urn:tag:";
+var DEFAULT_RESOLVER_TIMEOUT_MS = 15e3;
+var DEFAULT_MAX_RESOLVER_RESPONSE_BYTES = 1 * 1024 * 1024;
+var DEFAULT_RESOLVER_HEALTH_TIMEOUT_MS = 5e3;
+var DEFAULT_MAX_RESOLVER_HEALTH_RESPONSE_BYTES = 64 * 1024;
+var DEFAULT_MINIMUM_SEMANTIC_SCORE = 0.7;
+var DEFAULT_MINIMUM_SEMANTIC_SCORE_MARGIN = 0.05;
+var DEFAULT_RESOLUTION_CACHE_TTL_MS = 15 * 60 * 1e3;
+var DEFAULT_RESOLUTION_CACHE_MAX_ENTRIES = 256;
+var TASTE_RESOLVER_HEALTH_UPSTREAMS = [
+  "gemma",
+  "postgres",
+  "qloo_search",
+  "redis"
+];
+var QLOO_RESOLUTION_PROVIDER_ENVIRONMENT_VARIABLE = "QLOO_RESOLUTION_PROVIDER";
+var TASTE_RESOLVER_URL_ENVIRONMENT_VARIABLE = "TASTE_RESOLVER_URL";
+var TASTE_RESOLVER_API_KEY_ENVIRONMENT_VARIABLE = "TASTE_RESOLVER_API_KEY";
+var QLOO_TRUSTED_TASTE_RESOLVER_URL_ENVIRONMENT_VARIABLE = "QLOO_TRUSTED_TASTE_RESOLVER_URL";
+var QLOO_TASTE_RESOLVER_TAG_ENDPOINT_ENVIRONMENT_VARIABLE = "QLOO_TASTE_RESOLVER_TAG_ENDPOINT";
+var QLOO_TASTE_RESOLVER_MIN_SCORE_ENVIRONMENT_VARIABLE = "QLOO_TASTE_RESOLVER_MIN_SCORE";
+var QLOO_TASTE_RESOLVER_MIN_MARGIN_ENVIRONMENT_VARIABLE = "QLOO_TASTE_RESOLVER_MIN_MARGIN";
+var QlooResolutionProviderError = class extends Error {
+  code;
+  retryable;
+  recovery;
+  status;
+  constructor(code, message, options) {
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.name = "QlooResolutionProviderError";
+    this.code = code;
+    this.retryable = options.retryable ?? false;
+    this.recovery = options.recovery;
+    if (options.status !== void 0)
+      this.status = options.status;
+  }
+};
+function nonEmptyString(value) {
+  if (typeof value !== "string")
+    return void 0;
+  const trimmed = value.trim();
+  return trimmed || void 0;
+}
+function parseUnitInterval(value, name, defaultValue) {
+  if (value === void 0 || value === null || value === "")
+    return defaultValue;
+  const parsed = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+    throw new QlooResolutionProviderError("RESOLVER_CONFIGURATION", `${name} must be a number from 0 through 1.`, { recovery: `Set ${name} to a decimal from 0 through 1.` });
+  }
+  return parsed;
+}
+function parseTasteResolverTagEndpoint(value) {
+  const endpoint = nonEmptyString(value) ?? "legacy";
+  if (endpoint === "legacy" || endpoint === "structured")
+    return endpoint;
+  throw new QlooResolutionProviderError("RESOLVER_CONFIGURATION", `${QLOO_TASTE_RESOLVER_TAG_ENDPOINT_ENVIRONMENT_VARIABLE} must be legacy or structured.`, {
+    recovery: `Use legacy for POST /v1/resolve or structured for POST /v1/tags/resolve.`
+  });
+}
+function asRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+function resultArray(response, key) {
+  if (Array.isArray(response.results))
+    return response.results;
+  return asArray(asRecord(response.results)?.[key] ?? response.results ?? []);
+}
+function scalar(record, ...keys) {
+  for (const key of keys) {
+    if (record[key] !== void 0 && record[key] !== null)
+      return record[key];
+  }
+  return void 0;
+}
+function normalizeName(value) {
+  return value.normalize("NFKC").trim().toLocaleLowerCase("en-US");
+}
+function requestOptions(context) {
+  return {
+    ...context.signal ? { signal: context.signal } : {},
+    correlationId: context.correlationId
+  };
+}
+function entityType(record) {
+  const directType = scalar(record, "subtype", "type");
+  if (typeof directType === "string" && directType)
+    return directType;
+  const types = asArray(record.types).filter((type) => typeof type === "string" && type.length > 0);
+  return types.find((type) => type.startsWith("urn:entity:")) ?? types[0];
+}
+function entityReleaseYear(properties) {
+  const value = properties?.release_year;
+  if (typeof value === "number" && Number.isInteger(value))
+    return value;
+  if (typeof value === "string" && /^\d{4}$/u.test(value))
+    return Number(value);
+  const releaseDate = properties?.release_date;
+  if (typeof releaseDate !== "string")
+    return void 0;
+  const year = /^(\d{4})(?:-|$)/u.exec(releaseDate)?.[1];
+  return year ? Number(year) : void 0;
+}
+function entityCandidate(value) {
+  const record = asRecord(value);
+  if (!record)
+    return void 0;
+  const id = scalar(record, "entity_id", "id");
+  const name = record.name;
+  if (typeof id !== "string" || !id || typeof name !== "string" || !name)
+    return void 0;
+  const properties = asRecord(record.properties);
+  const type = entityType(record);
+  const description = nonEmptyString(scalar(record, "short_description", "description") ?? scalar(properties ?? {}, "short_description", "description"));
+  const releaseYear = entityReleaseYear(properties);
+  const address = record.address ?? properties?.address;
+  return {
+    id,
+    name,
+    ...type ? { type } : {},
+    ...typeof record.popularity === "number" ? { popularity: record.popularity } : {},
+    ...description ? { description: description.slice(0, 500) } : {},
+    ...releaseYear !== void 0 ? { release_year: releaseYear } : {},
+    ...address !== void 0 ? { address } : {}
+  };
+}
+function tagCandidate(value, rank) {
+  const record = asRecord(value);
+  if (!record)
+    return void 0;
+  const id = scalar(record, "id", "tag_id");
+  const name = record.name;
+  if (typeof id !== "string" || !id || typeof name !== "string" || !name)
+    return void 0;
+  const type = scalar(record, "type", "subtype");
+  const query = asRecord(record.query);
+  const score = typeof record.score === "number" ? record.score : typeof record.affinity === "number" ? record.affinity : typeof query?.affinity === "number" ? query.affinity : void 0;
+  const parentTypes = [...new Set(asArray(record.parents).map(asRecord).map((parent) => parent ? scalar(parent, "type") : void 0).filter((type2) => typeof type2 === "string" && type2.length > 0))].slice(0, 20);
+  return {
+    id,
+    name,
+    ...typeof type === "string" && type ? { type } : {},
+    ...rank !== void 0 ? { rank } : {},
+    ...score !== void 0 ? { score } : {},
+    ...typeof record.popularity === "number" ? { popularity: record.popularity } : {},
+    ...parentTypes.length > 0 ? { parent_types: parentTypes } : {}
+  };
+}
+function provenance(descriptor, endpoint, strategy, extras = {}) {
+  return {
+    contract_version: QLOO_RESOLUTION_CONTRACT_VERSION,
+    provider_id: descriptor.provider_id,
+    provider_name: descriptor.name,
+    endpoint,
+    strategy,
+    remote: descriptor.remote,
+    uses_model: descriptor.uses_model,
+    ...extras.providerVersion ? { provider_version: extras.providerVersion } : {},
+    ...extras.cacheStatus ? { cache_status: extras.cacheStatus } : {}
+  };
+}
+function resolved(input, selected, match, source, options = {}) {
+  return {
+    input,
+    status: "resolved",
+    match,
+    selected,
+    provenance: source,
+    ...options.alternatives && options.alternatives.length > 0 ? { alternatives: [...options.alternatives] } : {},
+    ...options.warnings && options.warnings.length > 0 ? { warnings: [...options.warnings] } : {}
+  };
+}
+function createNativeQlooResolutionProvider(client, options = {}) {
+  const cacheTtlMs = options.cacheTtlMs ?? DEFAULT_RESOLUTION_CACHE_TTL_MS;
+  const cacheMaxEntries = options.cacheMaxEntries ?? DEFAULT_RESOLUTION_CACHE_MAX_ENTRIES;
+  const now = options.now ?? Date.now;
+  if (!Number.isSafeInteger(cacheTtlMs) || cacheTtlMs < 1) {
+    throw new QlooResolutionProviderError("RESOLVER_CONFIGURATION", "Native Qloo resolution cache TTL must be a positive integer.", { recovery: "Configure a positive cache TTL in milliseconds." });
+  }
+  if (!Number.isSafeInteger(cacheMaxEntries) || cacheMaxEntries < 0) {
+    throw new QlooResolutionProviderError("RESOLVER_CONFIGURATION", "Native Qloo resolution cache capacity must be a non-negative integer.", { recovery: "Configure zero to disable caching or a positive entry limit." });
+  }
+  const descriptor = {
+    contract_version: QLOO_RESOLUTION_CONTRACT_VERSION,
+    provider_id: "qloo_api",
+    name: "Qloo native resolution",
+    entity_strategy: "exact_name_or_choice",
+    tag_strategy: "target_scoped_semantic_search_exact_name_or_choice",
+    remote: true,
+    uses_model: false,
+    fallback: "none"
+  };
+  const cache = /* @__PURE__ */ new Map();
+  const cacheKey = (kind, input, scope) => JSON.stringify([
+    QLOO_RESOLUTION_CONTRACT_VERSION,
+    descriptor.provider_id,
+    descriptor.tag_strategy,
+    kind,
+    scope ?? "",
+    normalizeName(input)
+  ]);
+  const cachedOutcome = (kind, input, scope) => {
+    if (cacheMaxEntries === 0)
+      return void 0;
+    const key = cacheKey(kind, input, scope);
+    const entry = cache.get(key);
+    if (!entry)
+      return void 0;
+    if (entry.expiresAt <= now()) {
+      cache.delete(key);
+      return void 0;
+    }
+    cache.delete(key);
+    cache.set(key, entry);
+    return {
+      ...structuredClone(entry.outcome),
+      input,
+      provenance: {
+        ...entry.outcome.provenance,
+        cache_status: "memory_hit"
+      }
+    };
+  };
+  const rememberOutcome = (kind, input, scope, outcome) => {
+    if (cacheMaxEntries === 0)
+      return outcome;
+    const key = cacheKey(kind, input, scope);
+    cache.delete(key);
+    cache.set(key, {
+      expiresAt: now() + cacheTtlMs,
+      outcome: structuredClone(outcome)
+    });
+    while (cache.size > cacheMaxEntries) {
+      const oldest = cache.keys().next().value;
+      if (oldest === void 0)
+        break;
+      cache.delete(oldest);
+    }
+    return outcome;
+  };
+  const resolveEntity = async (input, type, context) => {
+    if (UUID_PATTERN.test(input)) {
+      const source2 = provenance(descriptor, "/entities", "identifier_lookup");
+      const response2 = await client.entities([input], requestOptions(context));
+      const candidates2 = resultArray(response2, "entities").map(entityCandidate).filter((candidate) => candidate !== void 0);
+      const exact2 = candidates2.filter(({ id }) => id.toLocaleLowerCase("en-US") === input.toLocaleLowerCase("en-US"));
+      if (exact2.length === 1 && exact2[0])
+        return resolved(input, exact2[0], "identifier", source2);
+      if (exact2.length > 1)
+        return { input, status: "ambiguous", candidates: exact2.slice(0, 5), provenance: source2 };
+      return { input, status: "not_found", provenance: source2 };
+    }
+    const source = provenance(descriptor, "/search", "exact_name_or_choice");
+    const response = await client.searchEntities({
+      query: input,
+      ...type ? { types: type } : {},
+      take: 5
+    }, requestOptions(context));
+    const candidates = resultArray(response, "entities").map(entityCandidate).filter((candidate) => candidate !== void 0);
+    if (candidates.length === 0)
+      return { input, status: "not_found", provenance: source };
+    const exact = candidates.filter(({ name }) => normalizeName(name) === normalizeName(input));
+    if (exact.length === 1 && exact[0]) {
+      const alternatives = candidates.filter(({ id }) => id !== exact[0]?.id).slice(0, 4);
+      return resolved(input, exact[0], "exact", source, { alternatives });
+    }
+    return {
+      input,
+      status: "ambiguous",
+      candidates: (exact.length > 0 ? exact : candidates).slice(0, 5),
+      provenance: source
+    };
+  };
+  const resolveTag = async (input, targetType, context) => {
+    if (input.startsWith(TAG_URN_PREFIX)) {
+      return resolved(input, { id: input, name: input }, "identifier", provenance(descriptor, "local:tag-urn", "supplied_identifier"));
+    }
+    const source = provenance(descriptor, "/v2/tags", targetType ? "semantic_search_local_parent_scope_exact_name_or_choice" : "semantic_search_exact_name_or_choice");
+    const response = await client.tags({
+      "filter.query": input,
+      "feature.semantic_search": true,
+      take: 20
+    }, requestOptions(context));
+    const rankedCandidates = resultArray(response, "tags").map((value, index) => tagCandidate(value, index + 1)).filter((candidate) => candidate !== void 0);
+    const candidatesWithParentMetadata = rankedCandidates.filter(({ parent_types: parentTypes }) => parentTypes !== void 0 && parentTypes.length > 0);
+    const candidates = targetType && candidatesWithParentMetadata.length > 0 ? rankedCandidates.filter(({ parent_types: parentTypes }) => parentTypes?.includes(targetType)) : rankedCandidates;
+    const scopeWarnings = targetType && candidatesWithParentMetadata.length === 0 && rankedCandidates.length > 0 ? [
+      `Qloo tag candidates did not include parent-type metadata, so the bounded choices could not be scoped to ${targetType}.`
+    ] : [];
+    if (targetType && candidatesWithParentMetadata.length > 0 && candidates.length === 0) {
+      return {
+        input,
+        status: "not_found",
+        provenance: source,
+        warnings: [
+          `No candidate in the first ${rankedCandidates.length} Qloo semantic tag results supports ${targetType}.`
+        ]
+      };
+    }
+    if (candidates.length === 0)
+      return { input, status: "not_found", provenance: source };
+    const exact = candidates.filter(({ name }) => normalizeName(name) === normalizeName(input));
+    if (exact.length === 1 && exact[0]) {
+      const alternatives = candidates.filter(({ id }) => id !== exact[0]?.id).slice(0, 4);
+      return resolved(input, exact[0], "exact", source, {
+        alternatives,
+        warnings: scopeWarnings
+      });
+    }
+    return {
+      input,
+      status: "ambiguous",
+      candidates: (exact.length > 0 ? exact : candidates).slice(0, 5),
+      provenance: source,
+      warnings: [
+        ...scopeWarnings,
+        ...exact.length === 0 ? [
+          "Qloo semantic search returned ranked candidates without a calibrated relevance score; choose one before the workflow continues."
+        ] : []
+      ]
+    };
+  };
+  return {
+    descriptor,
+    async resolveEntities(request, context) {
+      return {
+        outcomes: await Promise.all(request.inputs.map((input) => cachedOutcome("entity", input, request.type) ?? resolveEntity(input, request.type, context).then((outcome) => rememberOutcome("entity", input, request.type, outcome))))
+      };
+    },
+    async resolveTags(request, context) {
+      return {
+        outcomes: await Promise.all(request.inputs.map((input) => input.startsWith(TAG_URN_PREFIX) ? resolveTag(input, request.targetType, context) : cachedOutcome("tag", input, request.targetType) ?? resolveTag(input, request.targetType, context).then((outcome) => rememberOutcome("tag", input, request.targetType, outcome))))
+      };
+    }
+  };
+}
+function createPublicQlooResolutionProvider(client, options = {}) {
+  return createNativeQlooResolutionProvider(client, options);
+}
+function normalizeResolverBaseUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch (cause) {
+    throw new QlooResolutionProviderError("RESOLVER_CONFIGURATION", "Taste-resolver URL is invalid.", {
+      cause,
+      recovery: "Set TASTE_RESOLVER_URL to an absolute HTTPS URL or a loopback HTTP URL."
+    });
+  }
+  const isLoopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopback)) {
+    throw new QlooResolutionProviderError("RESOLVER_CONFIGURATION", "Taste-resolver URL must use HTTPS unless it is a loopback development endpoint.", {
+      recovery: "Use HTTPS or run the resolver on localhost for local development."
+    });
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    throw new QlooResolutionProviderError("RESOLVER_CONFIGURATION", "Taste-resolver URL cannot contain credentials, query parameters, or a fragment.", {
+      recovery: "Move resolver authentication to TASTE_RESOLVER_API_KEY and use a clean base URL."
+    });
+  }
+  url.pathname = url.pathname.replace(/\/+$/u, "") + "/";
+  return url;
+}
+function resolverUrlsMatch(left, right) {
+  try {
+    return normalizeResolverBaseUrl(left).toString() === normalizeResolverBaseUrl(right).toString();
+  } catch {
+    return false;
+  }
+}
+function requireTrustedResolverBaseUrl(baseUrl, trustedBaseUrl) {
+  const normalized = normalizeResolverBaseUrl(baseUrl);
+  const isLoopback = normalized.hostname === "localhost" || normalized.hostname === "127.0.0.1" || normalized.hostname === "[::1]";
+  if (!isLoopback && (!trustedBaseUrl || !resolverUrlsMatch(baseUrl, trustedBaseUrl))) {
+    throw new QlooResolutionProviderError("RESOLVER_CONFIGURATION", "Remote taste-resolver URL is not explicitly trusted.", {
+      recovery: `Set ${QLOO_TRUSTED_TASTE_RESOLVER_URL_ENVIRONMENT_VARIABLE} to the exact resolver base URL.`
+    });
+  }
+  return normalized;
+}
+function inspectQlooResolutionProviderConfiguration(options = {}) {
+  const env = options.env ?? process.env;
+  const selection = nonEmptyString(env[QLOO_RESOLUTION_PROVIDER_ENVIRONMENT_VARIABLE]) ?? "native";
+  if (selection === "native" || selection === "public") {
+    return {
+      selection,
+      valid: true,
+      providerId: "qloo_api",
+      endpoint: "/search and /v2/tags",
+      trusted: true,
+      authenticated: false,
+      usesModel: false,
+      message: selection === "public" ? "Native, server-free Qloo resolution is active through the legacy public alias; semantic tag candidates are target-scoped and material ambiguity requires a choice." : "Native, server-free Qloo resolution is active; semantic tag candidates are target-scoped and material ambiguity requires a choice."
+    };
+  }
+  if (selection !== "taste-resolver") {
+    return {
+      selection,
+      valid: false,
+      trusted: false,
+      authenticated: false,
+      usesModel: false,
+      message: `Unsupported Qloo resolution provider "${selection}".`,
+      recovery: `Set ${QLOO_RESOLUTION_PROVIDER_ENVIRONMENT_VARIABLE} to native or taste-resolver. The value public remains a compatibility alias.`
+    };
+  }
+  const configuredBaseUrl = nonEmptyString(env[TASTE_RESOLVER_URL_ENVIRONMENT_VARIABLE]) ?? nonEmptyString(options.fileConfig?.taste_resolver_url);
+  if (!configuredBaseUrl) {
+    return {
+      selection,
+      valid: false,
+      providerId: "taste_resolver_assisted",
+      trusted: false,
+      authenticated: Boolean(nonEmptyString(env[TASTE_RESOLVER_API_KEY_ENVIRONMENT_VARIABLE])),
+      usesModel: true,
+      message: "Taste-resolver assistance is selected but no resolver URL is configured.",
+      recovery: `Set ${TASTE_RESOLVER_URL_ENVIRONMENT_VARIABLE} and ${QLOO_TRUSTED_TASTE_RESOLVER_URL_ENVIRONMENT_VARIABLE}.`
+    };
+  }
+  const trustedBaseUrl = nonEmptyString(env[QLOO_TRUSTED_TASTE_RESOLVER_URL_ENVIRONMENT_VARIABLE]);
+  try {
+    const endpoint = requireTrustedResolverBaseUrl(configuredBaseUrl, trustedBaseUrl);
+    const tagEndpoint = parseTasteResolverTagEndpoint(env[QLOO_TASTE_RESOLVER_TAG_ENDPOINT_ENVIRONMENT_VARIABLE]);
+    const minimumSemanticScore = parseUnitInterval(env[QLOO_TASTE_RESOLVER_MIN_SCORE_ENVIRONMENT_VARIABLE], QLOO_TASTE_RESOLVER_MIN_SCORE_ENVIRONMENT_VARIABLE, DEFAULT_MINIMUM_SEMANTIC_SCORE);
+    const minimumSemanticScoreMargin = parseUnitInterval(env[QLOO_TASTE_RESOLVER_MIN_MARGIN_ENVIRONMENT_VARIABLE], QLOO_TASTE_RESOLVER_MIN_MARGIN_ENVIRONMENT_VARIABLE, DEFAULT_MINIMUM_SEMANTIC_SCORE_MARGIN);
+    return {
+      selection,
+      valid: true,
+      providerId: "taste_resolver_assisted",
+      endpoint: endpoint.toString().replace(/\/$/u, ""),
+      trusted: true,
+      authenticated: Boolean(nonEmptyString(env[TASTE_RESOLVER_API_KEY_ENVIRONMENT_VARIABLE])),
+      usesModel: true,
+      tagEndpoint,
+      minimumSemanticScore,
+      minimumSemanticScoreMargin,
+      message: `Taste-resolver semantic tag assistance is explicitly selected in ${tagEndpoint} mode with score \u2265 ${minimumSemanticScore} and margin \u2265 ${minimumSemanticScoreMargin}; entity resolution remains on the Qloo API and no fallback is enabled.`
+    };
+  } catch (error) {
+    const providerError = error instanceof QlooResolutionProviderError ? error : void 0;
+    return {
+      selection,
+      valid: false,
+      providerId: "taste_resolver_assisted",
+      trusted: false,
+      authenticated: Boolean(nonEmptyString(env[TASTE_RESOLVER_API_KEY_ENVIRONMENT_VARIABLE])),
+      usesModel: true,
+      message: providerError?.message ?? "Taste-resolver configuration is invalid.",
+      recovery: providerError?.recovery ?? "Correct the taste-resolver endpoint configuration."
+    };
+  }
+}
+async function readBoundedResponse(response, maximumBytes) {
+  const contentLength = response.headers.get("content-length");
+  if (contentLength !== null && Number(contentLength) > maximumBytes) {
+    await response.body?.cancel();
+    throw new QlooResolutionProviderError("RESOLVER_CONTRACT", "Taste-resolver response exceeded the configured size limit.", {
+      recovery: "Inspect the resolver deployment and return only bounded resolution metadata."
+    });
+  }
+  if (!response.body)
+    return {};
+  const reader = response.body.getReader();
+  const chunks = [];
+  let totalBytes = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done)
+      break;
+    if (!value)
+      continue;
+    totalBytes += value.byteLength;
+    if (totalBytes > maximumBytes) {
+      await reader.cancel();
+      throw new QlooResolutionProviderError("RESOLVER_CONTRACT", "Taste-resolver response exceeded the configured size limit.", {
+        recovery: "Inspect the resolver deployment and return only bounded resolution metadata."
+      });
+    }
+    chunks.push(value);
+  }
+  const bytes = new Uint8Array(totalBytes);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  const text = new TextDecoder().decode(bytes);
+  if (!text.trim())
+    return {};
+  try {
+    return JSON.parse(text);
+  } catch (cause) {
+    throw new QlooResolutionProviderError("RESOLVER_CONTRACT", "Taste-resolver returned invalid JSON.", {
+      cause,
+      recovery: "Verify that the configured endpoint implements the taste-resolver v1 contract."
+    });
+  }
+}
+function resolverHealthFailure(kind, message, startedAt, options = {}) {
+  return {
+    ok: false,
+    kind,
+    message,
+    durationMs: Math.max(0, Date.now() - startedAt),
+    retryable: options.retryable ?? false,
+    ...options.status === void 0 ? {} : { status: options.status }
+  };
+}
+async function probeTasteResolverHealth(options) {
+  const startedAt = Date.now();
+  let baseUrl;
+  try {
+    baseUrl = requireTrustedResolverBaseUrl(options.baseUrl, options.trustedBaseUrl);
+  } catch {
+    return resolverHealthFailure("resolver-contract", "Taste-resolver health cannot be checked until its endpoint is valid and explicitly trusted.", startedAt);
+  }
+  const timeoutMs = options.timeoutMs ?? DEFAULT_RESOLVER_HEALTH_TIMEOUT_MS;
+  const maxResponseBytes = options.maxResponseBytes ?? DEFAULT_MAX_RESOLVER_HEALTH_RESPONSE_BYTES;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || !Number.isSafeInteger(maxResponseBytes) || maxResponseBytes < 1) {
+    return resolverHealthFailure("resolver-contract", "Taste-resolver health limits must be positive integers.", startedAt);
+  }
+  const controller = new AbortController();
+  let timedOut = false;
+  const timeout = setTimeout(() => {
+    timedOut = true;
+    controller.abort(new Error("Taste-resolver health check timed out."));
+  }, timeoutMs);
+  timeout.unref?.();
+  const onAbort = () => controller.abort(options.signal?.reason);
+  if (options.signal?.aborted)
+    onAbort();
+  else
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+  const cleanup = () => {
+    clearTimeout(timeout);
+    options.signal?.removeEventListener("abort", onAbort);
+  };
+  try {
+    const response = await (options.fetch ?? globalThis.fetch)(new URL("v1/health", baseUrl), {
+      method: "GET",
+      headers: { Accept: "application/json" },
+      redirect: "error",
+      signal: controller.signal
+    });
+    const body = await readBoundedResponse(response, maxResponseBytes);
+    if (!response.ok) {
+      return resolverHealthFailure("resolver-http", `Taste-resolver health returned HTTP ${response.status}.`, startedAt, { retryable: response.status === 429 || response.status >= 500, status: response.status });
+    }
+    const record = asRecord(body);
+    const status = nonEmptyString(record?.status);
+    const upstreams = asRecord(record?.upstreams);
+    if (status !== "ok" && status !== "degraded" || !upstreams || TASTE_RESOLVER_HEALTH_UPSTREAMS.some((name) => !nonEmptyString(upstreams[name]))) {
+      return resolverHealthFailure("resolver-contract", "Taste-resolver health response does not match the v1 contract.", startedAt);
+    }
+    const unavailable = TASTE_RESOLVER_HEALTH_UPSTREAMS.filter((name) => upstreams[name] !== "ok");
+    if (status === "degraded" || unavailable.length > 0) {
+      return resolverHealthFailure("resolver-degraded", unavailable.length > 0 ? `Taste-resolver is degraded; unavailable upstreams: ${unavailable.join(", ")}.` : "Taste-resolver is degraded.", startedAt, { retryable: true });
+    }
+    return {
+      ok: true,
+      kind: "resolver-healthy",
+      message: "Taste-resolver and its declared upstreams are healthy.",
+      durationMs: Math.max(0, Date.now() - startedAt),
+      retryable: false
+    };
+  } catch (error) {
+    if (timedOut) {
+      return resolverHealthFailure("resolver-timeout", "Taste-resolver health check timed out.", startedAt, { retryable: true });
+    }
+    if (error instanceof QlooResolutionProviderError) {
+      return resolverHealthFailure("resolver-contract", error.message, startedAt);
+    }
+    return resolverHealthFailure("resolver-connect", options.signal?.aborted ? "Taste-resolver health check was cancelled." : "Taste-resolver health endpoint is not reachable.", startedAt, { retryable: !options.signal?.aborted });
+  } finally {
+    cleanup();
+  }
+}
+function createTasteResolverAssistedResolutionProvider(options) {
+  const baseUrl = requireTrustedResolverBaseUrl(options.baseUrl, options.trustedBaseUrl);
+  const fetchImplementation = options.fetch ?? globalThis.fetch;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_RESOLVER_TIMEOUT_MS;
+  const maxResponseBytes = options.maxResponseBytes ?? DEFAULT_MAX_RESOLVER_RESPONSE_BYTES;
+  const tagEndpoint = parseTasteResolverTagEndpoint(options.tagEndpoint);
+  const minimumSemanticScore = parseUnitInterval(options.minimumSemanticScore, "minimumSemanticScore", DEFAULT_MINIMUM_SEMANTIC_SCORE);
+  const minimumSemanticScoreMargin = parseUnitInterval(options.minimumSemanticScoreMargin, "minimumSemanticScoreMargin", DEFAULT_MINIMUM_SEMANTIC_SCORE_MARGIN);
+  const cacheTtlMs = options.cacheTtlMs ?? DEFAULT_RESOLUTION_CACHE_TTL_MS;
+  const cacheMaxEntries = options.cacheMaxEntries ?? DEFAULT_RESOLUTION_CACHE_MAX_ENTRIES;
+  const now = options.now ?? Date.now;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) {
+    throw new QlooResolutionProviderError("RESOLVER_CONFIGURATION", "Taste-resolver timeout must be a positive integer.", { recovery: "Configure a positive resolver timeout in milliseconds." });
+  }
+  if (!Number.isSafeInteger(maxResponseBytes) || maxResponseBytes < 1) {
+    throw new QlooResolutionProviderError("RESOLVER_CONFIGURATION", "Taste-resolver response limit must be a positive integer.", { recovery: "Configure a positive resolver response-size limit." });
+  }
+  if (!Number.isSafeInteger(cacheTtlMs) || cacheTtlMs < 1) {
+    throw new QlooResolutionProviderError("RESOLVER_CONFIGURATION", "Taste-resolver cache TTL must be a positive integer.", { recovery: "Configure a positive cache TTL in milliseconds." });
+  }
+  if (!Number.isSafeInteger(cacheMaxEntries) || cacheMaxEntries < 0) {
+    throw new QlooResolutionProviderError("RESOLVER_CONFIGURATION", "Taste-resolver cache capacity must be a non-negative integer.", { recovery: "Configure zero to disable caching or a positive entry limit." });
+  }
+  const descriptor = {
+    contract_version: QLOO_RESOLUTION_CONTRACT_VERSION,
+    provider_id: "taste_resolver_assisted",
+    name: "Qloo taste-resolver assistance",
+    entity_strategy: "qloo_api_exact_name_or_choice",
+    tag_strategy: tagEndpoint === "structured" ? "taste_resolver_structured_tag_rerank_confidence_gated" : "taste_resolver_semantic_rerank_confidence_gated",
+    remote: true,
+    uses_model: true,
+    fallback: "none"
+  };
+  const cache = /* @__PURE__ */ new Map();
+  const cacheKey = (input, targetType) => JSON.stringify([
+    QLOO_RESOLUTION_CONTRACT_VERSION,
+    descriptor.provider_id,
+    tagEndpoint,
+    targetType ?? "",
+    normalizeName(input)
+  ]);
+  const cachedOutcome = (input, targetType) => {
+    if (cacheMaxEntries === 0)
+      return void 0;
+    const key = cacheKey(input, targetType);
+    const entry = cache.get(key);
+    if (!entry)
+      return void 0;
+    if (entry.expiresAt <= now()) {
+      cache.delete(key);
+      return void 0;
+    }
+    cache.delete(key);
+    cache.set(key, entry);
+    return {
+      ...structuredClone(entry.outcome),
+      input,
+      provenance: {
+        ...entry.outcome.provenance,
+        cache_status: "memory_hit"
+      }
+    };
+  };
+  const rememberOutcome = (input, targetType, outcome) => {
+    if (cacheMaxEntries === 0)
+      return outcome;
+    const key = cacheKey(input, targetType);
+    cache.delete(key);
+    cache.set(key, { expiresAt: now() + cacheTtlMs, outcome: structuredClone(outcome) });
+    while (cache.size > cacheMaxEntries) {
+      const oldest = cache.keys().next().value;
+      if (oldest === void 0)
+        break;
+      cache.delete(oldest);
+    }
+    return outcome;
+  };
+  const resolveSemanticTag = async (input, targetType, context) => {
+    if (input.length > 1e3) {
+      throw new QlooResolutionProviderError("RESOLVER_CONTRACT", "Taste-resolver inputs cannot exceed 1000 characters.", { recovery: "Shorten the tag concept and retry the same structured workflow." });
+    }
+    const controller = new AbortController();
+    let timedOut = false;
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      controller.abort(new Error("Taste-resolver request timed out."));
+    }, timeoutMs);
+    timeout.unref?.();
+    const onAbort = () => controller.abort(context.signal?.reason);
+    if (context.signal?.aborted)
+      onAbort();
+    else
+      context.signal?.addEventListener("abort", onAbort, { once: true });
+    const cleanup = () => {
+      clearTimeout(timeout);
+      context.signal?.removeEventListener("abort", onAbort);
+    };
+    let response;
+    try {
+      response = await fetchImplementation(new URL(tagEndpoint === "structured" ? "v1/tags/resolve" : "v1/resolve", baseUrl), {
+        method: "POST",
+        headers: {
+          Accept: "application/json",
+          "Content-Type": "application/json",
+          "X-Correlation-Id": context.correlationId,
+          ...options.apiKey ? { "X-Api-Key": options.apiKey } : {}
+        },
+        body: JSON.stringify(tagEndpoint === "structured" ? {
+          inputs: [input],
+          ...targetType ? { filter_type: targetType } : {},
+          take: 5
+        } : {
+          input,
+          ...targetType ? { filter_type: targetType } : {},
+          options: { take: 5, explain: true }
+        }),
+        redirect: "error",
+        signal: controller.signal
+      });
+    } catch (cause) {
+      cleanup();
+      if (context.signal?.aborted) {
+        throw new QlooResolutionProviderError("RESOLVER_ABORTED", "Taste-resolver request was cancelled.", {
+          cause,
+          recovery: "Retry only if the workflow was cancelled unintentionally."
+        });
+      }
+      if (timedOut) {
+        throw new QlooResolutionProviderError("RESOLVER_TIMEOUT", "Taste-resolver request timed out.", {
+          cause,
+          retryable: true,
+          recovery: "Check resolver health and retry the same interpreted request once."
+        });
+      }
+      throw new QlooResolutionProviderError("RESOLVER_CONNECT", "Taste-resolver is not reachable.", {
+        cause,
+        retryable: true,
+        recovery: "Verify TASTE_RESOLVER_URL, VPN routing, and resolver health before retrying."
+      });
+    }
+    let body;
+    try {
+      body = await readBoundedResponse(response, maxResponseBytes);
+    } catch (cause) {
+      if (cause instanceof QlooResolutionProviderError)
+        throw cause;
+      if (context.signal?.aborted) {
+        throw new QlooResolutionProviderError("RESOLVER_ABORTED", "Taste-resolver request was cancelled.", {
+          cause,
+          recovery: "Retry only if the workflow was cancelled unintentionally."
+        });
+      }
+      if (timedOut) {
+        throw new QlooResolutionProviderError("RESOLVER_TIMEOUT", "Taste-resolver response timed out.", {
+          cause,
+          retryable: true,
+          recovery: "Check resolver health and retry the same interpreted request once."
+        });
+      }
+      throw new QlooResolutionProviderError("RESOLVER_CONNECT", "Taste-resolver response could not be read completely.", {
+        cause,
+        retryable: true,
+        recovery: "Check resolver health and retry the same interpreted request once."
+      });
+    } finally {
+      cleanup();
+    }
+    if (!response.ok) {
+      const status = response.status;
+      const code = status === 401 || status === 403 ? "RESOLVER_AUTH" : status >= 500 || status === 429 ? "RESOLVER_UPSTREAM" : "RESOLVER_CONTRACT";
+      throw new QlooResolutionProviderError(code, `Taste-resolver returned HTTP ${status}.`, {
+        status,
+        retryable: status >= 500 || status === 429,
+        recovery: status === 401 || status === 403 ? "Configure a valid TASTE_RESOLVER_API_KEY before retrying." : status >= 500 || status === 429 ? "Check resolver health and retry the same interpreted request once." : `Verify that the hosted resolver implements the ${tagEndpoint === "structured" ? "v1 tags/resolve" : "v1 resolve"} contract.`
+      });
+    }
+    const record = asRecord(body);
+    const resolution = asRecord(record?.resolution);
+    const groups = asArray(tagEndpoint === "structured" ? record?.tags : resolution?.tags).map(asRecord).filter((group) => group !== void 0);
+    const matchingGroup = groups.find((group) => {
+      const groupInput = group.input;
+      return typeof groupInput === "string" && normalizeName(groupInput) === normalizeName(input);
+    }) ?? groups[0];
+    const candidates = asArray(matchingGroup?.tags).map((value) => tagCandidate(value)).filter((candidate) => candidate !== void 0).sort((left, right) => (right.score ?? Number.NEGATIVE_INFINITY) - (left.score ?? Number.NEGATIVE_INFINITY)).slice(0, 5);
+    const cacheStatus = nonEmptyString(record?.cache_status);
+    const providerVersion = nonEmptyString(record?.contract_version ?? record?.version);
+    const source = provenance(descriptor, tagEndpoint === "structured" ? "/v1/tags/resolve" : "/v1/resolve", tagEndpoint === "structured" ? "structured_semantic_embedding_taxonomy_rerank" : "semantic_embedding_taxonomy_rerank", {
+      ...cacheStatus ? { cacheStatus } : {},
+      ...providerVersion ? { providerVersion } : {}
+    });
+    const responseWarnings = asArray(record?.warnings).filter((warning) => typeof warning === "string").slice(0, 10);
+    if (candidates.length === 0) {
+      return {
+        input,
+        status: "not_found",
+        provenance: source,
+        ...responseWarnings.length > 0 ? { warnings: responseWarnings } : {}
+      };
+    }
+    const exact = candidates.filter(({ name }) => normalizeName(name) === normalizeName(input));
+    if (exact.length > 1) {
+      return {
+        input,
+        status: "ambiguous",
+        candidates: exact,
+        provenance: source,
+        ...responseWarnings.length > 0 ? { warnings: responseWarnings } : {}
+      };
+    }
+    const selected = exact[0] ?? candidates[0];
+    if (!selected) {
+      return { input, status: "not_found", provenance: source };
+    }
+    const alternatives = candidates.filter(({ id }) => id !== selected.id).slice(0, 4);
+    if (exact.length === 0) {
+      const runnerUp = alternatives[0];
+      const score = selected.score;
+      const margin = score !== void 0 && runnerUp?.score !== void 0 ? score - runnerUp.score : runnerUp === void 0 ? Number.POSITIVE_INFINITY : void 0;
+      const confidenceWarnings = [
+        ...score === void 0 || score < 0 || score > 1 ? ["The top semantic candidate did not provide a valid normalized score."] : score < minimumSemanticScore ? [`The top semantic score ${score.toFixed(3)} is below the required ${minimumSemanticScore.toFixed(3)}.`] : [],
+        ...margin === void 0 ? ["The resolver did not provide enough score information to distinguish the top candidates."] : margin < minimumSemanticScoreMargin ? [`The top semantic candidates are separated by ${margin.toFixed(3)}, below the required ${minimumSemanticScoreMargin.toFixed(3)}.`] : []
+      ];
+      if (confidenceWarnings.length > 0) {
+        return {
+          input,
+          status: "ambiguous",
+          candidates,
+          provenance: source,
+          warnings: [...responseWarnings, ...confidenceWarnings]
+        };
+      }
+    }
+    const semanticWarning = exact.length === 0 ? `Taste-resolver selected "${selected.name}" as the top semantic match for "${input}"; alternatives remain available in resolution provenance.` : void 0;
+    const warnings = [...responseWarnings, ...semanticWarning ? [semanticWarning] : []];
+    return resolved(input, selected, exact.length === 1 ? "exact" : "semantic", source, {
+      alternatives,
+      warnings
+    });
+  };
+  return {
+    descriptor,
+    resolveEntities: (request, context) => options.entityProvider.resolveEntities(request, context),
+    async resolveTags(request, context) {
+      const outcomes = await Promise.all(request.inputs.map((input) => input.startsWith(TAG_URN_PREFIX) ? options.entityProvider.resolveTags({ ...request, inputs: [input] }, context).then((batch) => batch.outcomes[0] ?? {
+        input,
+        status: "not_found",
+        provenance: provenance(descriptor, "local:tag-urn", "supplied_identifier")
+      }) : cachedOutcome(input, request.targetType) ?? resolveSemanticTag(input, request.targetType, context).then((outcome) => rememberOutcome(input, request.targetType, outcome))));
+      return { outcomes };
+    }
+  };
+}
+function createQlooResolutionProviderFromEnvironment(options) {
+  const env = options.env ?? process.env;
+  const selection = nonEmptyString(env[QLOO_RESOLUTION_PROVIDER_ENVIRONMENT_VARIABLE]) ?? "native";
+  const nativeProvider = createNativeQlooResolutionProvider(options.client);
+  if (selection === "native" || selection === "public")
+    return nativeProvider;
+  if (selection !== "taste-resolver") {
+    throw new QlooResolutionProviderError("RESOLVER_CONFIGURATION", `Unsupported Qloo resolution provider "${selection}".`, {
+      recovery: `Set ${QLOO_RESOLUTION_PROVIDER_ENVIRONMENT_VARIABLE} to native or taste-resolver. The value public remains a compatibility alias.`
+    });
+  }
+  const baseUrl = nonEmptyString(env[TASTE_RESOLVER_URL_ENVIRONMENT_VARIABLE]) ?? nonEmptyString(options.fileConfig?.taste_resolver_url);
+  if (!baseUrl) {
+    throw new QlooResolutionProviderError("RESOLVER_CONFIGURATION", "Taste-resolver assistance was selected but no resolver URL is configured.", {
+      recovery: `Set ${TASTE_RESOLVER_URL_ENVIRONMENT_VARIABLE} and ${QLOO_TRUSTED_TASTE_RESOLVER_URL_ENVIRONMENT_VARIABLE}, or select the native provider.`
+    });
+  }
+  const trustedBaseUrl = nonEmptyString(env[QLOO_TRUSTED_TASTE_RESOLVER_URL_ENVIRONMENT_VARIABLE]);
+  const apiKey = nonEmptyString(env[TASTE_RESOLVER_API_KEY_ENVIRONMENT_VARIABLE]);
+  const tagEndpoint = parseTasteResolverTagEndpoint(env[QLOO_TASTE_RESOLVER_TAG_ENDPOINT_ENVIRONMENT_VARIABLE]);
+  const minimumSemanticScore = parseUnitInterval(env[QLOO_TASTE_RESOLVER_MIN_SCORE_ENVIRONMENT_VARIABLE], QLOO_TASTE_RESOLVER_MIN_SCORE_ENVIRONMENT_VARIABLE, DEFAULT_MINIMUM_SEMANTIC_SCORE);
+  const minimumSemanticScoreMargin = parseUnitInterval(env[QLOO_TASTE_RESOLVER_MIN_MARGIN_ENVIRONMENT_VARIABLE], QLOO_TASTE_RESOLVER_MIN_MARGIN_ENVIRONMENT_VARIABLE, DEFAULT_MINIMUM_SEMANTIC_SCORE_MARGIN);
+  return createTasteResolverAssistedResolutionProvider({
+    baseUrl,
+    ...trustedBaseUrl ? { trustedBaseUrl } : {},
+    ...apiKey ? { apiKey } : {},
+    tagEndpoint,
+    minimumSemanticScore,
+    minimumSemanticScoreMargin,
+    entityProvider: nativeProvider,
+    ...options.fetch ? { fetch: options.fetch } : {}
+  });
+}
+export {
+  QLOO_RESOLUTION_PROVIDER_ENVIRONMENT_VARIABLE,
+  QLOO_TASTE_RESOLVER_MIN_MARGIN_ENVIRONMENT_VARIABLE,
+  QLOO_TASTE_RESOLVER_MIN_SCORE_ENVIRONMENT_VARIABLE,
+  QLOO_TASTE_RESOLVER_TAG_ENDPOINT_ENVIRONMENT_VARIABLE,
+  QLOO_TRUSTED_TASTE_RESOLVER_URL_ENVIRONMENT_VARIABLE,
+  QlooResolutionProviderError,
+  TASTE_RESOLVER_API_KEY_ENVIRONMENT_VARIABLE,
+  TASTE_RESOLVER_URL_ENVIRONMENT_VARIABLE,
+  createNativeQlooResolutionProvider,
+  createPublicQlooResolutionProvider,
+  createQlooResolutionProviderFromEnvironment,
+  createTasteResolverAssistedResolutionProvider,
+  inspectQlooResolutionProviderConfiguration,
+  probeTasteResolverHealth
+};