@qloo/qloo-harness 0.1.18

package/dist/integration-plan.js

@@ -0,0 +1,1097 @@
+import { createRequire as __qlooCreateRequire } from "node:module";
+const require = __qlooCreateRequire(import.meta.url);
+
+// apps/qloo-harness/dist/integration-plan.js
+import { createHash as createHash2, randomUUID } from "node:crypto";
+import { lstat, mkdir, readFile, realpath, rename, unlink, writeFile } from "node:fs/promises";
+import { isAbsolute, join, posix, relative, resolve } from "node:path";
+
+// 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 entityType of entityTypes) {
+    aliases.set(entityType.id, entityType.urn);
+    aliases.set(entityType.urn, entityType.urn);
+    aliases.set(`${entityType.id}s`, entityType.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);
+function getQlooCapabilities(input = {}) {
+  const selected = input.operation_ids ? new Set(input.operation_ids) : void 0;
+  return {
+    contract_version: QLOO_TOOL_CATALOG_VERSION,
+    introspection_tool: QLOO_CAPABILITIES_TOOL_NAME,
+    operations: selected ? QLOO_WORKFLOW_OPERATIONS.filter(({ id }) => selected.has(id)) : QLOO_WORKFLOW_OPERATIONS,
+    upstream: {
+      documentation_url: upstreamLock.source.documentationUrl,
+      api_version: upstreamLock.source.apiVersion,
+      openapi_version: upstreamLock.source.openapiVersion,
+      production_server: upstreamLock.expectations.productionServer,
+      lock_sha256: upstreamLock.source.sha256,
+      get_paths: upstreamGetPaths,
+      documented_exceptions: documentedExceptions
+    }
+  };
+}
+
+// packages/qloo-tool-schema/dist/src/workflow-contracts.js
+import { createHash } from "node:crypto";
+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((operation2) => [
+  operation2,
+  Object.freeze({
+    ...sharedWorkflowBehavior,
+    expectedLatency: mediumLatencyOperations.has(operation2) ? "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
+  })
+])));
+var QLOO_ADAPTER_CONTRACT_MANIFEST_SCHEMA_VERSION = "1.1";
+function getQlooExecutableCapabilities(input = {}) {
+  const capabilities = getQlooCapabilities(input);
+  return {
+    ...capabilities,
+    result_schema_version: QLOO_TOOL_RESULT_SCHEMA_VERSION,
+    operations: capabilities.operations.map((operation2) => {
+      const contract = QLOO_WORKFLOW_CONTRACTS[operation2.id];
+      return {
+        ...operation2,
+        input_schema: contract.inputSchema,
+        result_schema: contract.resultSchema,
+        documentation: contract.documentation,
+        behavior: contract.behavior
+      };
+    })
+  };
+}
+function getQlooAdapterContractManifest() {
+  const capabilities = getQlooExecutableCapabilities();
+  const contract = {
+    manifest_schema_version: QLOO_ADAPTER_CONTRACT_MANIFEST_SCHEMA_VERSION,
+    contract_version: capabilities.contract_version,
+    capabilities_tool: QLOO_CAPABILITIES_TOOL_NAME,
+    result_schema_version: capabilities.result_schema_version,
+    result_schema: QLOO_RESULT_ENVELOPE_SCHEMA,
+    operations: capabilities.operations.map((operation2) => {
+      const contract2 = QLOO_WORKFLOW_CONTRACTS[operation2.id];
+      return {
+        id: operation2.id,
+        shared_tool_name: operation2.toolName,
+        summary: operation2.summary,
+        description: contract2.description,
+        input_schema: contract2.inputSchema,
+        behavior: contract2.behavior,
+        documentation: contract2.documentation
+      };
+    }),
+    upstream: capabilities.upstream
+  };
+  return {
+    ...contract,
+    contract_checksum: `sha256:${createHash("sha256").update(JSON.stringify(contract)).digest("hex")}`
+  };
+}
+
+// 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/integration-plan.js
+import { Type as Type3 } from "typebox";
+import { Value as Value2 } from "typebox/value";
+import { inspectProjectContext, QLOO_PROJECT_CONTEXT_SCHEMA_VERSION } from "./project-context.js";
+var QLOO_INTEGRATION_PLAN_SCHEMA_VERSION = "1.0";
+var QLOO_INTEGRATION_PLAN_MAX_BYTES = 64 * 1024;
+var QLOO_INTEGRATION_PLAN_MAX_GOAL_BYTES = 8 * 1024;
+var QLOO_INTEGRATION_PLAN_MAX_EVIDENCE_BYTES = 1024 * 1024;
+var QLOO_INTEGRATION_PLAN_ID_PATTERN = /^qplan_[a-f0-9]{24}$/u;
+var shortText = Type3.String({ minLength: 1, maxLength: 500 });
+var longText = Type3.String({ minLength: 1, maxLength: 2e3 });
+var relativePath = Type3.String({ minLength: 1, maxLength: 500 });
+var operation = Type3.Union([
+  Type3.Literal("recommend"),
+  Type3.Literal("rank"),
+  Type3.Literal("describe"),
+  Type3.Literal("where_popular"),
+  Type3.Literal("compare_audiences"),
+  Type3.Literal("entity_tags"),
+  Type3.Literal("audience_demographics"),
+  Type3.Literal("trends"),
+  Type3.Literal("find_tags")
+]);
+var fieldMapping = Type3.Object({
+  local_field: shortText,
+  qloo_role: Type3.Union([
+    Type3.Literal("signal"),
+    Type3.Literal("filter"),
+    Type3.Literal("output")
+  ]),
+  qloo_field: shortText,
+  normalized_result_field: Type3.Union([shortText, Type3.Null()]),
+  owning_boundary: shortText,
+  transformation: longText
+}, { additionalProperties: false });
+var boundaries = Type3.Object({
+  http_client: longText,
+  configuration: longText,
+  data_model: longText,
+  error_boundary: longText
+}, { additionalProperties: false });
+var errorHandling = Type3.Object({
+  condition: shortText,
+  behavior: longText
+}, { additionalProperties: false });
+var change = Type3.Object({
+  path: relativePath,
+  action: Type3.Union([Type3.Literal("create"), Type3.Literal("modify")]),
+  purpose: longText,
+  verification: longText
+}, { additionalProperties: false });
+var verification = Type3.Object({
+  command: Type3.String({ minLength: 1, maxLength: 1e3 }),
+  purpose: longText
+}, { additionalProperties: false });
+var draftEvidence = Type3.Object({
+  path: relativePath,
+  relevance: longText
+}, { additionalProperties: false });
+var hashedEvidence = Type3.Object({
+  path: relativePath,
+  relevance: longText,
+  sha256: Type3.String({ pattern: "^[a-f0-9]{64}$" })
+}, { additionalProperties: false });
+var QLOO_INTEGRATION_PLAN_DRAFT_SCHEMA = Type3.Object({
+  status: Type3.Union([Type3.Literal("ready"), Type3.Literal("needs_input")]),
+  summary: longText,
+  operation,
+  transport: Type3.Union([Type3.Literal("direct"), Type3.Literal("mcp")]),
+  field_mapping: Type3.Array(fieldMapping, { minItems: 1, maxItems: 32 }),
+  boundaries,
+  error_handling: Type3.Array(errorHandling, { minItems: 1, maxItems: 16 }),
+  privacy_constraints: Type3.Array(longText, { minItems: 1, maxItems: 16 }),
+  changes: Type3.Array(change, { minItems: 1, maxItems: 32 }),
+  verification: Type3.Array(verification, { minItems: 1, maxItems: 16 }),
+  rollout: Type3.Array(longText, { minItems: 1, maxItems: 16 }),
+  rollback: Type3.Array(longText, { minItems: 1, maxItems: 16 }),
+  assumptions: Type3.Array(longText, { maxItems: 24 }),
+  unresolved_decisions: Type3.Array(longText, { maxItems: 16 }),
+  evidence: Type3.Array(draftEvidence, { minItems: 1, maxItems: 32 })
+}, { additionalProperties: false });
+var projectIdentity = Type3.Object({
+  name: shortText,
+  fingerprint: Type3.String({ pattern: "^[a-f0-9]{64}$" }),
+  context_schema_version: Type3.Literal(QLOO_PROJECT_CONTEXT_SCHEMA_VERSION),
+  languages: Type3.Array(shortText, { maxItems: 16 }),
+  package_managers: Type3.Array(shortText, { maxItems: 16 }),
+  frameworks: Type3.Array(shortText, { maxItems: 32 }),
+  source_roots: Type3.Array(relativePath, { maxItems: 32 }),
+  http_clients: Type3.Array(shortText, { maxItems: 16 }),
+  data_modeling: Type3.Array(shortText, { maxItems: 16 }),
+  configuration: Type3.Array(shortText, { maxItems: 16 }),
+  test_frameworks: Type3.Array(shortText, { maxItems: 16 }),
+  verification_scripts: Type3.Array(shortText, { maxItems: 32 })
+}, { additionalProperties: false });
+var qlooContract = Type3.Object({
+  operation,
+  tool_name: Type3.String({ pattern: "^qloo_[a-z_]+$" }),
+  transport: Type3.Union([Type3.Literal("direct"), Type3.Literal("mcp")]),
+  manifest_schema_version: shortText,
+  contract_version: shortText,
+  contract_checksum: Type3.String({ pattern: "^sha256:[a-f0-9]{64}$" }),
+  result_schema_version: shortText
+}, { additionalProperties: false });
+var QLOO_INTEGRATION_PLAN_SCHEMA = Type3.Object({
+  schema_version: Type3.Literal(QLOO_INTEGRATION_PLAN_SCHEMA_VERSION),
+  plan_id: Type3.String({ pattern: "^qplan_[a-f0-9]{24}$" }),
+  generated_at: Type3.String({ minLength: 20, maxLength: 40 }),
+  goal: Type3.String({ minLength: 1, maxLength: QLOO_INTEGRATION_PLAN_MAX_GOAL_BYTES }),
+  status: Type3.Union([Type3.Literal("ready"), Type3.Literal("needs_input")]),
+  summary: longText,
+  project: projectIdentity,
+  qloo: qlooContract,
+  field_mapping: Type3.Array(fieldMapping, { minItems: 1, maxItems: 32 }),
+  boundaries,
+  error_handling: Type3.Array(errorHandling, { minItems: 1, maxItems: 16 }),
+  privacy_constraints: Type3.Array(longText, { minItems: 1, maxItems: 16 }),
+  changes: Type3.Array(change, { minItems: 1, maxItems: 32 }),
+  verification: Type3.Array(verification, { minItems: 1, maxItems: 16 }),
+  rollout: Type3.Array(longText, { minItems: 1, maxItems: 16 }),
+  rollback: Type3.Array(longText, { minItems: 1, maxItems: 16 }),
+  assumptions: Type3.Array(longText, { maxItems: 24 }),
+  unresolved_decisions: Type3.Array(longText, { maxItems: 16 }),
+  evidence: Type3.Array(hashedEvidence, { minItems: 1, maxItems: 32 })
+}, { additionalProperties: false });
+var QlooIntegrationPlanError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "QlooIntegrationPlanError";
+  }
+};
+function validationMessage(schema, value) {
+  return [...Value2.Errors(schema, value)].slice(0, 8).map((issue) => `${issue.instancePath || "/"}: ${issue.message}`).join("; ");
+}
+function parseDraft(value) {
+  if (!Value2.Check(QLOO_INTEGRATION_PLAN_DRAFT_SCHEMA, value)) {
+    throw new QlooIntegrationPlanError("PLAN_INVALID", `submitted plan does not match schema: ${validationMessage(QLOO_INTEGRATION_PLAN_DRAFT_SCHEMA, value)}`);
+  }
+  return structuredClone(value);
+}
+function rejectUnsafeText(value, location = "/") {
+  if (typeof value === "string") {
+    if (/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/u.test(value)) {
+      throw new QlooIntegrationPlanError("PLAN_INVALID", `${location} contains an unsafe control character`);
+    }
+    const assignment = value.match(/(?:api[_-]?key|password|secret|access[_-]?token|refresh[_-]?token)\s*[:=]\s*["']?([A-Za-z0-9+/_.=-]{12,})/iu);
+    const assignedValue = assignment?.[1];
+    const looksLikePlaceholder = assignedValue === void 0 || /^(?:configured|environment|placeholder|redacted|unknown)$/iu.test(assignedValue) || /^[A-Z][A-Z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD)$/u.test(assignedValue);
+    if (/-----BEGIN [A-Z ]*PRIVATE KEY-----/iu.test(value) || /authorization\s*[:=]\s*bearer\s+[A-Za-z0-9+/_.=-]{8,}/iu.test(value) || !looksLikePlaceholder) {
+      throw new QlooIntegrationPlanError("PLAN_INVALID", `${location} appears to contain a credential value`);
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => rejectUnsafeText(item, `${location}${index}/`));
+    return;
+  }
+  if (value !== null && typeof value === "object") {
+    for (const [key, item] of Object.entries(value)) {
+      rejectUnsafeText(item, `${location}${key}/`);
+    }
+  }
+}
+function canonicalRelativePath(value) {
+  const candidate = value.trim();
+  const normalized = posix.normalize(candidate.replace(/^\.\//u, ""));
+  if (candidate.length === 0 || candidate.includes("\\") || /[\u0000-\u001f\u007f]/u.test(candidate) || isAbsolute(candidate) || /^[A-Za-z]:/u.test(candidate) || normalized === "." || normalized === ".." || normalized.startsWith("../") || normalized.startsWith("/")) {
+    throw new QlooIntegrationPlanError("PLAN_INVALID", `plan path must stay project-relative: ${JSON.stringify(value)}`);
+  }
+  const segments = normalized.split("/");
+  const fileName = segments.at(-1)?.toLocaleLowerCase("en-US") ?? "";
+  const safeEnvironmentTemplate = /^\.env\.(?:example|sample|template)$/u.test(fileName);
+  if (segments.some((segment) => [".git", ".qloo", ".ssh", "node_modules"].includes(segment.toLocaleLowerCase("en-US"))) || /^\.env(?:\..+)?$/u.test(fileName) && !safeEnvironmentTemplate || [".npmrc", ".pypirc", "id_rsa", "id_ed25519"].includes(fileName)) {
+    throw new QlooIntegrationPlanError("PLAN_INVALID", `plan path targets protected or credential-bearing state: ${JSON.stringify(value)}`);
+  }
+  return normalized;
+}
+function canonicalizeDraft(draft) {
+  const changes = draft.changes.map((item) => ({
+    ...item,
+    path: canonicalRelativePath(item.path)
+  }));
+  const evidence = draft.evidence.map((item) => ({
+    ...item,
+    path: canonicalRelativePath(item.path)
+  }));
+  for (const [label, paths] of [
+    ["change", changes.map(({ path }) => path)],
+    ["evidence", evidence.map(({ path }) => path)]
+  ]) {
+    if (new Set(paths).size !== paths.length) {
+      throw new QlooIntegrationPlanError("PLAN_INVALID", `plan contains duplicate ${label} paths`);
+    }
+  }
+  if (draft.status === "ready" && draft.unresolved_decisions.length > 0) {
+    throw new QlooIntegrationPlanError("PLAN_INVALID", "a ready plan cannot contain unresolved decisions; use status needs_input");
+  }
+  if (draft.status === "needs_input" && draft.unresolved_decisions.length === 0) {
+    throw new QlooIntegrationPlanError("PLAN_INVALID", "a needs_input plan must identify at least one unresolved decision");
+  }
+  const evidencePaths = new Set(evidence.map(({ path }) => path));
+  for (const item of changes) {
+    if (item.action === "modify" && !evidencePaths.has(item.path)) {
+      throw new QlooIntegrationPlanError("PLAN_INVALID", `every modified file must also be cited as evidence: ${item.path}`);
+    }
+  }
+  for (const item of draft.verification) {
+    if (/\r|\n|[;&|`$<>]/u.test(item.command)) {
+      throw new QlooIntegrationPlanError("PLAN_INVALID", `verification command must be one non-composed command: ${JSON.stringify(item.command)}`);
+    }
+  }
+  return { ...draft, changes, evidence };
+}
+function schemaProperties(schema) {
+  if (schema === null || typeof schema !== "object" || Array.isArray(schema))
+    return /* @__PURE__ */ new Set();
+  const properties = Reflect.get(schema, "properties");
+  return properties !== null && typeof properties === "object" && !Array.isArray(properties) ? new Set(Object.keys(properties)) : /* @__PURE__ */ new Set();
+}
+function qlooFieldRoot(value) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*(?:\[\])?(?:\.[A-Za-z_][A-Za-z0-9_]*(?:\[\])?)*$/u.test(value)) {
+    return void 0;
+  }
+  return value.match(/^[A-Za-z_][A-Za-z0-9_]*/u)?.[0];
+}
+function validateFieldMapping(mapping, inputSchema, resultSchema) {
+  const inputFields = schemaProperties(inputSchema);
+  const resultFields = schemaProperties(resultSchema);
+  let inputCount = 0;
+  let outputCount = 0;
+  mapping.forEach((item, index) => {
+    const root = qlooFieldRoot(item.qloo_field);
+    if (item.qloo_role === "output") {
+      outputCount += 1;
+      if (!root || !resultFields.has(root)) {
+        throw new QlooIntegrationPlanError("PLAN_INVALID", `/field_mapping/${index}/qloo_field is not in the normalized Qloo result schema: ${item.qloo_field}`);
+      }
+      if (item.normalized_result_field === null) {
+        throw new QlooIntegrationPlanError("PLAN_INVALID", `/field_mapping/${index}/normalized_result_field is required for an output mapping`);
+      }
+      return;
+    }
+    inputCount += 1;
+    if (!root || !inputFields.has(root)) {
+      throw new QlooIntegrationPlanError("PLAN_INVALID", `/field_mapping/${index}/qloo_field is not in the selected Qloo input schema: ${item.qloo_field}`);
+    }
+    if (item.normalized_result_field !== null) {
+      throw new QlooIntegrationPlanError("PLAN_INVALID", `/field_mapping/${index}/normalized_result_field must be null for a signal or filter mapping`);
+    }
+  });
+  if (inputCount === 0 || outputCount === 0) {
+    throw new QlooIntegrationPlanError("PLAN_INVALID", "field_mapping must contain at least one Qloo input and one normalized output");
+  }
+}
+function projectIdentityFromContext(context) {
+  return {
+    name: context.project_name,
+    fingerprint: context.fingerprint,
+    context_schema_version: context.schema_version,
+    languages: [...context.languages],
+    package_managers: [...context.package_managers],
+    frameworks: [...context.frameworks],
+    source_roots: [...context.source_roots],
+    http_clients: [...context.http_clients],
+    data_modeling: [...context.data_modeling],
+    configuration: [...context.configuration],
+    test_frameworks: [...context.test_frameworks],
+    verification_scripts: [...context.verification_scripts]
+  };
+}
+function isInside(root, target) {
+  const pathFromRoot = relative(root, target);
+  return pathFromRoot === "" || !pathFromRoot.startsWith("..") && !isAbsolute(pathFromRoot);
+}
+async function hashEvidenceFile(cwd, path) {
+  const projectRoot = await realpath(resolve(cwd));
+  const target = resolve(projectRoot, path);
+  let metadata;
+  try {
+    metadata = await lstat(target);
+  } catch {
+    throw new QlooIntegrationPlanError("PLAN_INVALID", `evidence file does not exist: ${path}`);
+  }
+  if (!metadata.isFile() || metadata.isSymbolicLink()) {
+    throw new QlooIntegrationPlanError("PLAN_INVALID", `evidence must be a regular file: ${path}`);
+  }
+  const realTarget = await realpath(target);
+  if (!isInside(projectRoot, realTarget)) {
+    throw new QlooIntegrationPlanError("PLAN_INVALID", `evidence escapes the project: ${path}`);
+  }
+  if (metadata.size > QLOO_INTEGRATION_PLAN_MAX_EVIDENCE_BYTES) {
+    throw new QlooIntegrationPlanError("PLAN_INVALID", `evidence file exceeds the ${QLOO_INTEGRATION_PLAN_MAX_EVIDENCE_BYTES}-byte limit: ${path}`);
+  }
+  return createHash2("sha256").update(await readFile(realTarget)).digest("hex");
+}
+function planId(unsigned) {
+  return `qplan_${createHash2("sha256").update(JSON.stringify(unsigned)).digest("hex").slice(0, 24)}`;
+}
+function validateGoal(goal) {
+  const normalized = goal.trim();
+  if (normalized.length === 0) {
+    throw new QlooIntegrationPlanError("PLAN_INVALID", "the integration goal must not be empty");
+  }
+  if (Buffer.byteLength(normalized) > QLOO_INTEGRATION_PLAN_MAX_GOAL_BYTES) {
+    throw new QlooIntegrationPlanError("PLAN_INVALID", `the integration goal exceeds the ${QLOO_INTEGRATION_PLAN_MAX_GOAL_BYTES}-byte limit`);
+  }
+  rejectUnsafeText(normalized, "/goal/");
+  return normalized;
+}
+async function createIntegrationPlanArtifact(options) {
+  const goal = validateGoal(options.goal);
+  const draft = canonicalizeDraft(parseDraft(options.draft));
+  rejectUnsafeText(draft);
+  const { context } = await inspectProjectContext({
+    cwd: options.cwd,
+    paths: options.paths,
+    refresh: true,
+    ...options.now === void 0 ? {} : { now: options.now }
+  });
+  const manifest = getQlooAdapterContractManifest();
+  const operationContract = manifest.operations.find(({ id }) => id === draft.operation);
+  if (!operationContract) {
+    throw new QlooIntegrationPlanError("PLAN_INVALID", `unsupported Qloo operation: ${draft.operation}`);
+  }
+  validateFieldMapping(draft.field_mapping, operationContract.input_schema, manifest.result_schema);
+  const evidence = await Promise.all(draft.evidence.map(async (item) => ({
+    ...item,
+    sha256: await hashEvidenceFile(options.cwd, item.path)
+  })));
+  const { operation: selectedOperation, transport, evidence: _draftEvidence, ...implementation } = draft;
+  const unsigned = {
+    schema_version: QLOO_INTEGRATION_PLAN_SCHEMA_VERSION,
+    generated_at: (options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString(),
+    goal,
+    ...implementation,
+    project: projectIdentityFromContext(context),
+    qloo: {
+      operation: selectedOperation,
+      tool_name: operationContract.shared_tool_name,
+      transport,
+      manifest_schema_version: manifest.manifest_schema_version,
+      contract_version: manifest.contract_version,
+      contract_checksum: manifest.contract_checksum,
+      result_schema_version: manifest.result_schema_version
+    },
+    evidence
+  };
+  const artifact = { ...unsigned, plan_id: planId(unsigned) };
+  if (!Value2.Check(QLOO_INTEGRATION_PLAN_SCHEMA, artifact)) {
+    throw new QlooIntegrationPlanError("PLAN_INVALID", `finalized plan does not match schema: ${validationMessage(QLOO_INTEGRATION_PLAN_SCHEMA, artifact)}`);
+  }
+  if (Buffer.byteLength(JSON.stringify(artifact)) > QLOO_INTEGRATION_PLAN_MAX_BYTES) {
+    throw new QlooIntegrationPlanError("PLAN_INVALID", `finalized plan exceeds the ${QLOO_INTEGRATION_PLAN_MAX_BYTES}-byte limit`);
+  }
+  return artifact;
+}
+async function saveIntegrationPlanArtifact(plan, paths) {
+  const validated = parseArtifact(plan);
+  await mkdir(paths.plansDir, { recursive: true, mode: 448 });
+  const target = join(paths.plansDir, `${validated.plan_id}.json`);
+  const temporary = join(paths.plansDir, `.${validated.plan_id}.${randomUUID()}.tmp`);
+  try {
+    await writeFile(temporary, `${JSON.stringify(validated, null, 2)}
+`, {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 384
+    });
+    await rename(temporary, target);
+  } catch (error) {
+    await unlink(temporary).catch(() => void 0);
+    throw error;
+  }
+  return target;
+}
+function parseArtifact(value) {
+  if (!Value2.Check(QLOO_INTEGRATION_PLAN_SCHEMA, value)) {
+    throw new QlooIntegrationPlanError("PLAN_INVALID", `stored plan does not match schema: ${validationMessage(QLOO_INTEGRATION_PLAN_SCHEMA, value)}`);
+  }
+  const artifact = structuredClone(value);
+  if (validateGoal(artifact.goal) !== artifact.goal) {
+    throw new QlooIntegrationPlanError("PLAN_INVALID", "stored integration goal is not canonical");
+  }
+  const { plan_id: storedId, ...unsigned } = artifact;
+  if (storedId !== planId(unsigned)) {
+    throw new QlooIntegrationPlanError("PLAN_INVALID", "stored plan integrity check failed");
+  }
+  if (!Number.isFinite(Date.parse(artifact.generated_at))) {
+    throw new QlooIntegrationPlanError("PLAN_INVALID", "stored plan has an invalid generation time");
+  }
+  rejectUnsafeText(artifact);
+  canonicalizeDraft({
+    status: artifact.status,
+    summary: artifact.summary,
+    operation: artifact.qloo.operation,
+    transport: artifact.qloo.transport,
+    field_mapping: artifact.field_mapping,
+    boundaries: artifact.boundaries,
+    error_handling: artifact.error_handling,
+    privacy_constraints: artifact.privacy_constraints,
+    changes: artifact.changes,
+    verification: artifact.verification,
+    rollout: artifact.rollout,
+    rollback: artifact.rollback,
+    assumptions: artifact.assumptions,
+    unresolved_decisions: artifact.unresolved_decisions,
+    evidence: artifact.evidence.map(({ path, relevance }) => ({ path, relevance }))
+  });
+  for (const item of [...artifact.changes, ...artifact.evidence]) {
+    if (canonicalRelativePath(item.path) !== item.path) {
+      throw new QlooIntegrationPlanError("PLAN_INVALID", `stored plan path is not canonical: ${item.path}`);
+    }
+  }
+  return artifact;
+}
+async function loadIntegrationPlanArtifact(options) {
+  if (!QLOO_INTEGRATION_PLAN_ID_PATTERN.test(options.planId)) {
+    throw new QlooIntegrationPlanError("PLAN_INVALID", "--plan must be a Qloo plan ID");
+  }
+  const path = join(options.paths.plansDir, `${options.planId}.json`);
+  let metadata;
+  try {
+    metadata = await lstat(path);
+  } catch {
+    throw new QlooIntegrationPlanError("PLAN_NOT_FOUND", `integration plan not found: ${options.planId}`);
+  }
+  if (!metadata.isFile() || metadata.isSymbolicLink()) {
+    throw new QlooIntegrationPlanError("PLAN_INVALID", "stored integration plan is not a regular file");
+  }
+  if (metadata.size > QLOO_INTEGRATION_PLAN_MAX_BYTES) {
+    throw new QlooIntegrationPlanError("PLAN_INVALID", "stored integration plan exceeds its size limit");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    throw new QlooIntegrationPlanError("PLAN_INVALID", "stored integration plan is not valid JSON");
+  }
+  const artifact = parseArtifact(parsed);
+  if (artifact.plan_id !== options.planId) {
+    throw new QlooIntegrationPlanError("PLAN_INVALID", "stored plan ID does not match its filename");
+  }
+  if ((options.requireReady ?? true) && artifact.status !== "ready") {
+    throw new QlooIntegrationPlanError("PLAN_NOT_READY", `integration plan ${artifact.plan_id} still needs input: ${artifact.unresolved_decisions.join("; ")}`);
+  }
+  const manifest = getQlooAdapterContractManifest();
+  const operationContract = manifest.operations.find(({ id }) => id === artifact.qloo.operation);
+  if (artifact.qloo.contract_checksum !== manifest.contract_checksum || artifact.qloo.contract_version !== manifest.contract_version || artifact.qloo.manifest_schema_version !== manifest.manifest_schema_version || artifact.qloo.result_schema_version !== manifest.result_schema_version || !QLOO_WORKFLOW_OPERATION_IDS.includes(artifact.qloo.operation) || operationContract?.shared_tool_name !== artifact.qloo.tool_name) {
+    throw new QlooIntegrationPlanError("PLAN_STALE", "the Qloo workflow contract changed after this plan was generated; create a new plan");
+  }
+  validateFieldMapping(artifact.field_mapping, operationContract.input_schema, manifest.result_schema);
+  const { context } = await inspectProjectContext({
+    cwd: options.cwd,
+    paths: options.paths,
+    refresh: true
+  });
+  if (artifact.project.name !== context.project_name || artifact.project.fingerprint !== context.fingerprint) {
+    throw new QlooIntegrationPlanError("PLAN_STALE", "the project manifest or structure changed after this plan was generated; create a new plan");
+  }
+  for (const item of artifact.evidence) {
+    let currentHash;
+    try {
+      currentHash = await hashEvidenceFile(options.cwd, item.path);
+    } catch {
+      throw new QlooIntegrationPlanError("PLAN_STALE", `plan evidence is no longer available: ${item.path}`);
+    }
+    if (currentHash !== item.sha256) {
+      throw new QlooIntegrationPlanError("PLAN_STALE", `plan evidence changed after generation: ${item.path}`);
+    }
+  }
+  return artifact;
+}
+function createIntegrationPlanSubmissionTool(options) {
+  let artifact;
+  const tool = {
+    name: "qloo_submit_integration_plan",
+    label: "Submit Qloo integration plan",
+    description: "Finalize one typed, evidence-backed Qloo integration plan. Call exactly once after inspecting project context, relevant source files, and the selected Qloo workflow contract.",
+    promptSnippet: "Submit the final typed Qloo integration plan",
+    promptGuidelines: [
+      "Call only after all read-only planning work is complete.",
+      "Use project-relative regular files as evidence and include only implementation files that the build should create or modify.",
+      "Set status to needs_input when a material decision remains; a ready plan cannot contain unresolved decisions."
+    ],
+    parameters: QLOO_INTEGRATION_PLAN_DRAFT_SCHEMA,
+    async execute(_toolCallId, params) {
+      if (artifact) {
+        throw new QlooIntegrationPlanError("PLAN_INVALID", "an integration plan was already submitted");
+      }
+      artifact = await createIntegrationPlanArtifact({
+        ...options,
+        draft: params
+      });
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            accepted: true,
+            plan_id: artifact.plan_id,
+            status: artifact.status
+          })
+        }],
+        details: {
+          schema_version: artifact.schema_version,
+          plan_id: artifact.plan_id,
+          status: artifact.status
+        },
+        terminate: true
+      };
+    }
+  };
+  return {
+    tool,
+    getArtifact: () => artifact
+  };
+}
+export {
+  QLOO_INTEGRATION_PLAN_DRAFT_SCHEMA,
+  QLOO_INTEGRATION_PLAN_ID_PATTERN,
+  QLOO_INTEGRATION_PLAN_MAX_BYTES,
+  QLOO_INTEGRATION_PLAN_MAX_EVIDENCE_BYTES,
+  QLOO_INTEGRATION_PLAN_MAX_GOAL_BYTES,
+  QLOO_INTEGRATION_PLAN_SCHEMA,
+  QLOO_INTEGRATION_PLAN_SCHEMA_VERSION,
+  QlooIntegrationPlanError,
+  createIntegrationPlanArtifact,
+  createIntegrationPlanSubmissionTool,
+  loadIntegrationPlanArtifact,
+  saveIntegrationPlanArtifact
+};