@svashevchenko/ez-know 0.1.0

package/dist/rest/server.js

@@ -0,0 +1,3237 @@
+// src/rest-server.ts
+import { existsSync as existsSync3 } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+// packages/rest/src/app.ts
+import { access } from "node:fs/promises";
+import { resolve as resolve5 } from "node:path";
+import fastifyStatic from "@fastify/static";
+import Fastify from "fastify";
+
+// packages/core/src/knowledge/schema.ts
+import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
+import { z } from "zod/v4";
+extendZodWithOpenApi(z);
+var confidenceSchema = z.object({
+  score: z.number().min(0).max(1),
+  level: z.enum(["Low", "Medium", "High"]),
+  reason: z.string().optional()
+});
+var certaintySchema = z.enum([
+  "confirmed",
+  "direct_evidence",
+  "inferred",
+  "weak_inference",
+  "unknown"
+]);
+var withConfidenceSchema = z.object({
+  certainty: certaintySchema,
+  confidence: confidenceSchema,
+  evidence_ids: z.array(z.string()),
+  questions: z.array(z.string())
+});
+var evidenceSchema = z.object({
+  id: z.string(),
+  source_type: z.enum([
+    "code",
+    "test",
+    "ui_text",
+    "translation",
+    "api",
+    "route",
+    "schema",
+    "comment",
+    "documentation",
+    "repowise_search",
+    "human",
+    "increment_description",
+    "git_diff"
+  ]),
+  description: z.string(),
+  location: z.object({
+    path: z.string().optional(),
+    symbol: z.string().optional(),
+    route: z.string().optional(),
+    api: z.string().optional(),
+    query: z.string().optional()
+  }).optional(),
+  supports: z.array(z.string()),
+  excerpt: z.string().optional(),
+  confidence: confidenceSchema
+});
+var domainSchema = withConfidenceSchema.extend({
+  id: z.string(),
+  name: z.string(),
+  purpose: z.string(),
+  why_it_exists: z.string().optional(),
+  entity_ids: z.array(z.string()),
+  capability_ids: z.array(z.string())
+});
+var entityTechnicalRepresentationSchema = z.object({
+  kind: z.enum([
+    "type",
+    "api",
+    "route",
+    "database",
+    "ui_label",
+    "translation",
+    "unknown"
+  ]),
+  name: z.string(),
+  location_hint: z.string().optional()
+});
+var entitySchema = withConfidenceSchema.extend({
+  id: z.string(),
+  name: z.string(),
+  business_definition: z.string(),
+  description: z.string(),
+  purpose: z.string().optional(),
+  aliases: z.array(z.string()),
+  ambiguous_terms: z.array(z.string()),
+  technical_representations: z.array(entityTechnicalRepresentationSchema),
+  domain_ids: z.array(z.string()),
+  state_values: z.array(z.string()).optional(),
+  relationship_ids: z.array(z.string()),
+  capability_ids: z.array(z.string()),
+  feature_ids: z.array(z.string()),
+  rule_ids: z.array(z.string())
+});
+var relationshipSchema = withConfidenceSchema.extend({
+  id: z.string(),
+  from_entity_id: z.string(),
+  to_entity_id: z.string(),
+  relationship_type: z.enum([
+    "has_many",
+    "has_one",
+    "belongs_to",
+    "depends_on",
+    "references",
+    "transitions_to",
+    "unknown"
+  ]),
+  description: z.string()
+});
+var capabilitySchema = withConfidenceSchema.extend({
+  id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  why_it_exists: z.string().optional(),
+  domain_ids: z.array(z.string()),
+  entity_ids: z.array(z.string()),
+  parent_capability_ids: z.array(z.string()),
+  child_capability_ids: z.array(z.string()),
+  feature_ids: z.array(z.string())
+});
+var featureSchema = withConfidenceSchema.extend({
+  id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  purpose: z.string().optional(),
+  why_it_exists: z.string().optional(),
+  domain_ids: z.array(z.string()),
+  capability_ids: z.array(z.string()),
+  entity_ids: z.array(z.string()),
+  rule_ids: z.array(z.string()),
+  constraint_ids: z.array(z.string())
+});
+var ruleConditionSchema = z.object({
+  subject: z.string(),
+  field: z.string().optional(),
+  operator: z.enum([
+    "equals",
+    "not_equals",
+    "contains",
+    "not_contains",
+    "exists",
+    "not_exists",
+    "greater_than",
+    "less_than",
+    "succeeds",
+    "fails",
+    "unknown"
+  ]),
+  value: z.unknown().optional()
+});
+var ruleTriggerSchema = z.object({
+  actor: z.string(),
+  action: z.string(),
+  subject: z.string().optional(),
+  field: z.string().optional(),
+  operator: z.enum([
+    "equals",
+    "not_equals",
+    "contains",
+    "not_contains",
+    "exists",
+    "not_exists",
+    "greater_than",
+    "less_than",
+    "succeeds",
+    "fails",
+    "unknown"
+  ]).optional(),
+  value: z.unknown().optional()
+});
+var ruleEffectSchema = z.object({
+  effect: z.enum([
+    "allow_action",
+    "disallow_action",
+    "hide_action",
+    "disable_action",
+    "require_action",
+    "show_message",
+    "change_state",
+    "calculate_value",
+    "unknown"
+  ]),
+  action: z.string().optional(),
+  message: z.string().optional(),
+  target_state: z.string().optional(),
+  value: z.unknown().optional()
+});
+var businessRuleSchema = withConfidenceSchema.extend({
+  id: z.string(),
+  name: z.string(),
+  statement: z.string(),
+  rule_type: z.enum([
+    "validation",
+    "permission",
+    "state_transition",
+    "visibility",
+    "workflow",
+    "calculation",
+    "integration",
+    "integration_behavior",
+    "data_consistency",
+    "acceptance_criterion",
+    "unknown"
+  ]),
+  behavior_type: z.enum([
+    "allow",
+    "disallow",
+    "require",
+    "calculate",
+    "show",
+    "hide",
+    "transition",
+    "notify",
+    "block",
+    "default",
+    "unknown"
+  ]),
+  applies_to: z.object({
+    domain_ids: z.array(z.string()).optional(),
+    entity_ids: z.array(z.string()).optional(),
+    capability_ids: z.array(z.string()).optional(),
+    feature_ids: z.array(z.string()).optional()
+  }),
+  condition: z.object({
+    given: z.array(ruleConditionSchema),
+    when: z.array(ruleTriggerSchema),
+    then: z.array(ruleEffectSchema)
+  }).optional(),
+  enforcement: z.object({
+    level: z.enum([
+      "ui",
+      "api",
+      "backend",
+      "database",
+      "external_system",
+      "unknown"
+    ]),
+    description: z.string().optional()
+  }).optional(),
+  related_constraint_ids: z.array(z.string()),
+  rationale_ids: z.array(z.string())
+});
+var constraintSchema = withConfidenceSchema.extend({
+  id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  constraint_type: z.enum([
+    "business",
+    "technical",
+    "regulatory",
+    "compliance",
+    "integration",
+    "legacy",
+    "architecture",
+    "infrastructure",
+    "performance",
+    "security",
+    "operational",
+    "data_model",
+    "unknown"
+  ]),
+  cause: z.object({
+    source: z.string(),
+    source_type: z.enum([
+      "external_system",
+      "database",
+      "framework",
+      "infrastructure",
+      "architecture",
+      "policy",
+      "regulation",
+      "business_process",
+      "legacy_code",
+      "unknown"
+    ]),
+    description: z.string()
+  }).optional(),
+  impact: z.object({
+    affected_change_types: z.array(z.string()),
+    severity: z.enum(["low", "medium", "high", "critical", "unknown"]),
+    description: z.string()
+  }).optional(),
+  applies_to: z.object({
+    domain_ids: z.array(z.string()).optional(),
+    entity_ids: z.array(z.string()).optional(),
+    capability_ids: z.array(z.string()).optional(),
+    feature_ids: z.array(z.string()).optional(),
+    business_rule_ids: z.array(z.string()).optional()
+  }),
+  workaround: z.object({
+    exists: z.enum(["yes", "no", "unknown"]),
+    description: z.string().optional()
+  }).optional(),
+  removability: z.object({
+    can_be_removed_by_refactor: z.enum(["yes", "no", "partially", "unknown"]),
+    requires: z.array(z.string()),
+    risk: z.enum(["low", "medium", "high", "critical", "unknown"])
+  }).optional()
+});
+var rationaleSchema = withConfidenceSchema.extend({
+  id: z.string(),
+  statement: z.string(),
+  explains: z.array(z.string())
+});
+var questionSchema = z.object({
+  id: z.string(),
+  question: z.string(),
+  category: z.enum([
+    "rationale",
+    "business_rule",
+    "constraint",
+    "terminology",
+    "domain_boundary",
+    "lifecycle",
+    "permission",
+    "legacy",
+    "ownership",
+    "enforcement"
+  ]),
+  reason: z.string(),
+  impact: z.string().optional(),
+  related_ids: z.array(z.string()),
+  evidence_ids: z.array(z.string()),
+  priority: z.enum(["low", "medium", "high"]),
+  status: z.enum(["open", "answered", "obsolete"]),
+  answer: z.string().nullable().optional(),
+  answered_by: z.string().nullable().optional(),
+  answered_at: z.string().nullable().optional()
+});
+var conflictSchema = z.object({
+  id: z.string(),
+  type: z.enum([
+    "domain_boundary",
+    "terminology",
+    "rule_conflict",
+    "rationale_conflict",
+    "entity_duplicate",
+    "relationship_conflict"
+  ]),
+  description: z.string(),
+  related_ids: z.array(z.string()),
+  evidence_ids: z.array(z.string()),
+  status: z.enum(["needs_human_input", "resolved", "obsolete"]),
+  questions: z.array(z.string()),
+  resolution: z.string().optional(),
+  resolved_by_evidence_id: z.string().optional()
+});
+var knowledgeCollectionSchemas = {
+  domains: z.array(domainSchema),
+  entities: z.array(entitySchema),
+  relationships: z.array(relationshipSchema),
+  capabilities: z.array(capabilitySchema),
+  features: z.array(featureSchema),
+  business_rules: z.array(businessRuleSchema),
+  constraints: z.array(constraintSchema),
+  rationales: z.array(rationaleSchema),
+  evidence: z.array(evidenceSchema),
+  questions: z.array(questionSchema),
+  conflicts: z.array(conflictSchema)
+};
+
+// packages/core/src/knowledge/extraction-registry.ts
+var KNOWLEDGE_EXTRACTION_TYPE_REGISTRY = {
+  domains: {
+    collection: "domains",
+    title: "Domains",
+    storageFile: "domain.json",
+    idConvention: {
+      pattern: "domain.<domain-slug>",
+      prefix: "domain",
+      example: "domain.orders"
+    },
+    schemaName: "Domain",
+    schema: domainSchema,
+    guideFilePath: "packages/core/src/knowledge/guides/domains.md",
+    aliases: []
+  },
+  entities: {
+    collection: "entities",
+    title: "Entities",
+    storageFile: "entities.json",
+    idConvention: {
+      pattern: "entity.<domain-slug>.<entity-slug>",
+      prefix: "entity",
+      example: "entity.orders.order"
+    },
+    schemaName: "Entity",
+    schema: entitySchema,
+    guideFilePath: "packages/core/src/knowledge/guides/entities.md",
+    aliases: []
+  },
+  relationships: {
+    collection: "relationships",
+    title: "Relationships",
+    storageFile: "relationships.json",
+    idConvention: {
+      pattern: "rel.<domain-slug>.<relationship-slug>",
+      prefix: "rel",
+      example: "rel.orders.order-has-items"
+    },
+    schemaName: "EntityRelationship",
+    schema: relationshipSchema,
+    guideFilePath: "packages/core/src/knowledge/guides/relationships.md",
+    aliases: ["entity-relationships"]
+  },
+  capabilities: {
+    collection: "capabilities",
+    title: "Capabilities",
+    storageFile: "capabilities.json",
+    idConvention: {
+      pattern: "cap.<domain-slug>.<capability-slug>",
+      prefix: "cap",
+      example: "cap.orders.order-lifecycle"
+    },
+    schemaName: "Capability",
+    schema: capabilitySchema,
+    guideFilePath: "packages/core/src/knowledge/guides/capabilities.md",
+    aliases: []
+  },
+  features: {
+    collection: "features",
+    title: "Features",
+    storageFile: "features.json",
+    idConvention: {
+      pattern: "feature.<domain-slug>.<feature-slug>",
+      prefix: "feature",
+      example: "feature.orders.cancel-order"
+    },
+    schemaName: "Feature",
+    schema: featureSchema,
+    guideFilePath: "packages/core/src/knowledge/guides/features.md",
+    aliases: []
+  },
+  business_rules: {
+    collection: "business_rules",
+    title: "Business Rules",
+    storageFile: "business-rules.json",
+    idConvention: {
+      pattern: "rule.<domain-slug>.<rule-slug>",
+      prefix: "rule",
+      example: "rule.orders.no-direct-cancel-paid-order"
+    },
+    schemaName: "BusinessRule",
+    schema: businessRuleSchema,
+    guideFilePath: "packages/core/src/knowledge/guides/business-rules.md",
+    aliases: ["business-rules"]
+  },
+  constraints: {
+    collection: "constraints",
+    title: "Constraints",
+    storageFile: "constraints.json",
+    idConvention: {
+      pattern: "constraint.<domain-slug>.<constraint-slug>",
+      prefix: "constraint",
+      example: "constraint.orders.erp-sync-one-way"
+    },
+    schemaName: "Constraint",
+    schema: constraintSchema,
+    guideFilePath: "packages/core/src/knowledge/guides/constraints.md",
+    aliases: []
+  },
+  rationales: {
+    collection: "rationales",
+    title: "Rationales",
+    storageFile: "rationales.json",
+    idConvention: {
+      pattern: "why.<domain-slug>.<rationale-slug>",
+      prefix: "why",
+      example: "why.orders.refund-required-for-paid-order"
+    },
+    schemaName: "Rationale",
+    schema: rationaleSchema,
+    guideFilePath: "packages/core/src/knowledge/guides/rationales.md",
+    aliases: []
+  },
+  evidence: {
+    collection: "evidence",
+    title: "Evidence",
+    storageFile: "evidence.json",
+    idConvention: {
+      pattern: "ev.<domain-slug>.<evidence-slug>",
+      prefix: "ev",
+      example: "ev.orders.cancel-disabled-paid"
+    },
+    schemaName: "Evidence",
+    schema: evidenceSchema,
+    guideFilePath: "packages/core/src/knowledge/guides/evidence.md",
+    aliases: []
+  },
+  questions: {
+    collection: "questions",
+    title: "Questions",
+    storageFile: "questions.json",
+    idConvention: {
+      pattern: "q.<domain-slug>.<question-slug>",
+      prefix: "q",
+      example: "q.orders.paid-cancel-rationale"
+    },
+    schemaName: "Question",
+    schema: questionSchema,
+    guideFilePath: "packages/core/src/knowledge/guides/questions.md",
+    aliases: []
+  },
+  conflicts: {
+    collection: "conflicts",
+    title: "Conflicts",
+    storageFile: "conflicts.json",
+    idConvention: {
+      pattern: "conflict.<domain-slug>.<conflict-slug>",
+      prefix: "conflict",
+      example: "conflict.invoice-domain"
+    },
+    schemaName: "Conflict",
+    schema: conflictSchema,
+    guideFilePath: "packages/core/src/knowledge/guides/conflicts.md",
+    aliases: []
+  }
+};
+var KNOWLEDGE_EXTRACTION_TYPES = Object.values(
+  KNOWLEDGE_EXTRACTION_TYPE_REGISTRY
+);
+var KNOWLEDGE_EXTRACTION_TYPE_LOOKUP = new Map(
+  KNOWLEDGE_EXTRACTION_TYPES.flatMap((definition) => [
+    [definition.collection, definition],
+    ...definition.aliases.map((alias) => [alias, definition])
+  ])
+);
+
+// packages/core/src/knowledge/extraction-resources.ts
+import { z as z2 } from "zod/v4";
+
+// packages/core/src/knowledge/loader.ts
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { z as z3 } from "zod/v4";
+
+// packages/core/src/knowledge/root.ts
+import { resolve } from "node:path";
+function resolveKnowledgeRootFromEnv(envValue, cwd = process.cwd()) {
+  return envValue ? resolve(cwd, envValue) : resolve(cwd, "ez-know");
+}
+
+// packages/core/src/knowledge/loader.ts
+var COLLECTION_SCHEMAS = {
+  domains: z3.array(domainSchema),
+  entities: z3.array(entitySchema),
+  relationships: z3.array(relationshipSchema),
+  capabilities: z3.array(capabilitySchema),
+  features: z3.array(featureSchema),
+  business_rules: z3.array(businessRuleSchema),
+  constraints: z3.array(constraintSchema),
+  rationales: z3.array(rationaleSchema),
+  evidence: z3.array(evidenceSchema),
+  questions: z3.array(questionSchema),
+  conflicts: z3.array(conflictSchema)
+};
+var COLLECTION_DEFINITIONS = KNOWLEDGE_EXTRACTION_TYPE_REGISTRY;
+var KnowledgeStoreLoadError = class extends Error {
+  diagnostics;
+  constructor(message, diagnostics) {
+    super(message);
+    this.name = "KnowledgeStoreLoadError";
+    this.diagnostics = diagnostics;
+  }
+};
+function resolveKnowledgeRoot(envValue, cwd = process.cwd()) {
+  return resolveKnowledgeRootFromEnv(envValue, cwd);
+}
+async function discoverDomainFolders(rootDir) {
+  const { readdir: readdir2 } = await import("node:fs/promises");
+  const discovered = [];
+  const entries = await readdir2(rootDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory() && !entry.name.startsWith(".")) {
+      discovered.push(join(rootDir, entry.name));
+    }
+  }
+  discovered.sort((left, right) => left.localeCompare(right));
+  return discovered;
+}
+function readDiagnostic(kind, path, message, id) {
+  return {
+    kind,
+    path,
+    id,
+    message
+  };
+}
+async function readCanonicalFile(filePath, schema) {
+  let raw;
+  try {
+    raw = await readFile(filePath, "utf8");
+  } catch (error) {
+    throw new KnowledgeStoreLoadError(
+      `Failed to read canonical knowledge file: ${filePath}`,
+      [
+        readDiagnostic(
+          "missing_domain_file",
+          filePath,
+          `Unable to read canonical file: ${filePath}`
+        )
+      ]
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new KnowledgeStoreLoadError(
+      `Invalid JSON in canonical knowledge file: ${filePath}`,
+      [readDiagnostic("invalid_json", filePath, `Invalid JSON in ${filePath}`)]
+    );
+  }
+  try {
+    return schema.parse(parsed);
+  } catch (error) {
+    throw new KnowledgeStoreLoadError(
+      `Invalid knowledge schema in canonical file: ${filePath}`,
+      [
+        readDiagnostic(
+          "invalid_shape",
+          filePath,
+          `Invalid canonical file shape in ${filePath}`
+        )
+      ]
+    );
+  }
+}
+function validateIdPrefix(collection, id, domainSlug) {
+  const definition = COLLECTION_DEFINITIONS[collection];
+  if (collection === "domains") {
+    const expectedId = `domain.${domainSlug}`;
+    if (id !== expectedId) {
+      return `Expected ${id} to equal ${expectedId}`;
+    }
+    return void 0;
+  }
+  const expectedPrefix = `${definition.idConvention.prefix}.${domainSlug}.`;
+  if (!id.startsWith(expectedPrefix)) {
+    return `Expected ${id} to start with ${expectedPrefix}`;
+  }
+  return void 0;
+}
+function getDomainId(domainSlug) {
+  return `domain.${domainSlug}`;
+}
+function emptyStore(rootDir) {
+  return {
+    rootDir,
+    sourceFiles: [],
+    domains: [],
+    entities: [],
+    relationships: [],
+    capabilities: [],
+    features: [],
+    business_rules: [],
+    constraints: [],
+    rationales: [],
+    evidence: [],
+    questions: [],
+    conflicts: [],
+    byCollection: {
+      domains: /* @__PURE__ */ new Map(),
+      entities: /* @__PURE__ */ new Map(),
+      relationships: /* @__PURE__ */ new Map(),
+      capabilities: /* @__PURE__ */ new Map(),
+      features: /* @__PURE__ */ new Map(),
+      business_rules: /* @__PURE__ */ new Map(),
+      constraints: /* @__PURE__ */ new Map(),
+      rationales: /* @__PURE__ */ new Map(),
+      evidence: /* @__PURE__ */ new Map(),
+      questions: /* @__PURE__ */ new Map(),
+      conflicts: /* @__PURE__ */ new Map()
+    },
+    byId: /* @__PURE__ */ new Map(),
+    reverseReferences: /* @__PURE__ */ new Map(),
+    diagnostics: []
+  };
+}
+function addRecord(store, collection, record, diagnostics) {
+  if (store.byId.has(record.id)) {
+    diagnostics.push(
+      readDiagnostic(
+        "duplicate_id",
+        void 0,
+        `Duplicate knowledge id detected: ${record.id}`,
+        record.id
+      )
+    );
+    return;
+  }
+  store.byId.set(record.id, record);
+  store.byCollection[collection].set(record.id, record);
+  store[collection].push(record);
+}
+function validateFolderRecordIds(collection, records, domainSlug, diagnostics) {
+  for (const record of records) {
+    const message = validateIdPrefix(collection, record.id, domainSlug);
+    if (message) {
+      diagnostics.push(
+        readDiagnostic("invalid_domain_id", void 0, message, record.id)
+      );
+    }
+  }
+}
+function collectReferenceIds(record) {
+  if ("relationship_type" in record) {
+    return [
+      record.from_entity_id,
+      record.to_entity_id
+    ];
+  }
+  if ("business_definition" in record) {
+    const entity = record;
+    return [
+      ...entity.domain_ids,
+      ...entity.relationship_ids,
+      ...entity.capability_ids,
+      ...entity.feature_ids,
+      ...entity.rule_ids
+    ];
+  }
+  if ("behavior_type" in record) {
+    const rule = record;
+    return [
+      ...rule.applies_to.domain_ids ?? [],
+      ...rule.applies_to.entity_ids ?? [],
+      ...rule.applies_to.capability_ids ?? [],
+      ...rule.applies_to.feature_ids ?? [],
+      ...rule.related_constraint_ids,
+      ...rule.rationale_ids
+    ];
+  }
+  if ("constraint_type" in record) {
+    const constraint = record;
+    return [
+      ...constraint.applies_to.domain_ids ?? [],
+      ...constraint.applies_to.entity_ids ?? [],
+      ...constraint.applies_to.capability_ids ?? [],
+      ...constraint.applies_to.feature_ids ?? [],
+      ...constraint.applies_to.business_rule_ids ?? []
+    ];
+  }
+  if ("parent_capability_ids" in record) {
+    const capability = record;
+    return [
+      ...capability.domain_ids,
+      ...capability.entity_ids,
+      ...capability.parent_capability_ids,
+      ...capability.child_capability_ids,
+      ...capability.feature_ids
+    ];
+  }
+  if ("rule_ids" in record && "constraint_ids" in record) {
+    const feature = record;
+    return [
+      ...feature.domain_ids,
+      ...feature.capability_ids,
+      ...feature.entity_ids,
+      ...feature.rule_ids,
+      ...feature.constraint_ids
+    ];
+  }
+  if ("entity_ids" in record && "capability_ids" in record && "why_it_exists" in record && !("business_definition" in record) && !("parent_capability_ids" in record) && !("constraint_ids" in record) && !("rule_ids" in record)) {
+    const domain = record;
+    return [...domain.entity_ids, ...domain.capability_ids];
+  }
+  if ("explains" in record) {
+    return record.explains;
+  }
+  if ("source_type" in record) {
+    return record.supports;
+  }
+  if ("priority" in record) {
+    const question = record;
+    return [...question.related_ids, ...question.evidence_ids];
+  }
+  const conflict = record;
+  return [
+    ...conflict.related_ids,
+    ...conflict.evidence_ids,
+    ...conflict.questions
+  ];
+}
+function buildReverseReferences(store) {
+  for (const record of store.byId.values()) {
+    const references = collectReferenceIds(record);
+    for (const referenceId of references) {
+      const reverse = store.reverseReferences.get(referenceId) ?? [];
+      reverse.push(record.id);
+      store.reverseReferences.set(referenceId, reverse);
+    }
+  }
+}
+function validateReferences(store, diagnostics) {
+  for (const record of store.byId.values()) {
+    for (const referenceId of collectReferenceIds(record)) {
+      if (!store.byId.has(referenceId)) {
+        diagnostics.push(
+          readDiagnostic(
+            "invalid_reference",
+            void 0,
+            `Unknown reference id "${referenceId}" from record "${record.id}"`,
+            record.id
+          )
+        );
+      }
+    }
+  }
+}
+function finalizeStore(store, diagnostics) {
+  store.diagnostics = diagnostics;
+  if (diagnostics.length > 0) {
+    throw new KnowledgeStoreLoadError(
+      diagnostics.map((diagnostic) => diagnostic.message).join("; "),
+      diagnostics
+    );
+  }
+  return store;
+}
+async function loadKnowledgeStoreFromRoot(rootDir) {
+  if (!existsSync(rootDir)) {
+    throw new KnowledgeStoreLoadError(
+      `Knowledge root does not exist: ${rootDir}`,
+      [
+        readDiagnostic(
+          "missing_root",
+          rootDir,
+          `Knowledge root does not exist: ${rootDir}`
+        )
+      ]
+    );
+  }
+  const diagnostics = [];
+  const store = emptyStore(rootDir);
+  const domainFolders = await discoverDomainFolders(rootDir);
+  const sourceFiles = [];
+  for (const domainFolder of domainFolders) {
+    const domainSlug = basename(domainFolder);
+    const domainFile = join(
+      domainFolder,
+      COLLECTION_DEFINITIONS.domains.storageFile
+    );
+    if (!existsSync(domainFile)) {
+      diagnostics.push(
+        readDiagnostic(
+          "missing_domain_file",
+          domainFile,
+          `Missing canonical domain file: ${domainFile}`
+        )
+      );
+      continue;
+    }
+    const domain = await readCanonicalFile(
+      domainFile,
+      domainSchema
+    );
+    sourceFiles.push(domainFile);
+    validateFolderRecordIds("domains", [domain], domainSlug, diagnostics);
+    const domainId = getDomainId(domainSlug);
+    if (domain.id !== domainId) {
+      diagnostics.push(
+        readDiagnostic(
+          "invalid_domain_id",
+          domainFile,
+          `Domain id "${domain.id}" must match folder slug "${domainSlug}"`,
+          domain.id
+        )
+      );
+    }
+    addRecord(store, "domains", domain, diagnostics);
+    for (const collection of Object.keys(
+      COLLECTION_DEFINITIONS
+    )) {
+      if (collection === "domains") {
+        continue;
+      }
+      const fileName = COLLECTION_DEFINITIONS[collection].storageFile;
+      const filePath = join(domainFolder, fileName);
+      if (!existsSync(filePath)) {
+        continue;
+      }
+      const parsed = await readCanonicalFile(
+        filePath,
+        COLLECTION_SCHEMAS[collection]
+      );
+      sourceFiles.push(filePath);
+      validateFolderRecordIds(
+        collection,
+        parsed,
+        domainSlug,
+        diagnostics
+      );
+      for (const record of parsed) {
+        addRecord(store, collection, record, diagnostics);
+      }
+    }
+  }
+  store.sourceFiles = sourceFiles.sort(
+    (left, right) => left.localeCompare(right)
+  );
+  buildReverseReferences(store);
+  validateReferences(store, diagnostics);
+  return finalizeStore(store, diagnostics);
+}
+async function loadKnowledgeStoreFromEnv(envValue, cwd = process.cwd()) {
+  const rootDir = resolveKnowledgeRoot(envValue, cwd);
+  if (!rootDir || !existsSync(rootDir)) {
+    return void 0;
+  }
+  return loadKnowledgeStoreFromRoot(rootDir);
+}
+
+// packages/core/src/knowledge/patch/storage.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { mkdir, readFile as readFile2, readdir, writeFile } from "node:fs/promises";
+import { isAbsolute, join as join3, normalize, resolve as resolve4, sep } from "node:path";
+import "zod/v4";
+
+// packages/core/src/knowledge/patch/constants.ts
+var KNOWLEDGE_PATCH_SCHEMA_VERSION = 1;
+var KNOWLEDGE_PATCH_FOLDER_NAME = ".patches";
+var SUPPORTED_OPERATION_TYPES = Object.keys(
+  KNOWLEDGE_EXTRACTION_TYPE_REGISTRY
+);
+var supportedOperationTypeSet = new Set(
+  SUPPORTED_OPERATION_TYPES
+);
+
+// packages/core/src/knowledge/patch/paths.ts
+import { join as join2 } from "node:path";
+function getKnowledgeRoot(envValue, cwd = process.cwd()) {
+  return resolveKnowledgeRootFromEnv(envValue, cwd);
+}
+function resolveKnowledgePatchRoot(envValue, cwd = process.cwd()) {
+  return join2(getKnowledgeRoot(envValue, cwd), KNOWLEDGE_PATCH_FOLDER_NAME);
+}
+function resolveKnowledgePatchDirectory(envValue, patchId, cwd = process.cwd()) {
+  return join2(resolveKnowledgePatchRoot(envValue, cwd), patchId);
+}
+function patchMetadataPath(patchDir) {
+  return join2(patchDir, "patch.json");
+}
+function patchOperationsPath(patchDir) {
+  return join2(patchDir, "operations.json");
+}
+
+// packages/core/src/knowledge/patch/schemas.ts
+import { z as z4 } from "zod/v4";
+var patchStatusSchema = z4.enum(["draft", "closed"]);
+var canonicalOperationTypeSchema = z4.string().trim().min(1).superRefine((value, ctx) => {
+  if (!supportedOperationTypeSet.has(value)) {
+    ctx.addIssue({
+      code: "custom",
+      message: `Unsupported patch operation type "${value}". Supported types: ${SUPPORTED_OPERATION_TYPES.join(
+        ", "
+      )}`
+    });
+  }
+}).transform((value) => value);
+var knowledgePatchMetadataSchema = z4.object({
+  id: z4.string().min(1),
+  title: z4.string().trim().min(1),
+  description: z4.string().trim().min(1).optional(),
+  status: patchStatusSchema,
+  rootFolder: z4.string().trim().min(1),
+  omittedFiles: z4.array(
+    z4.object({
+      path: z4.string().trim().min(1),
+      reason: z4.string().trim().min(1)
+    })
+  ),
+  schemaVersion: z4.literal(KNOWLEDGE_PATCH_SCHEMA_VERSION),
+  createdAt: z4.string().datetime({ offset: true }),
+  updatedAt: z4.string().datetime({ offset: true }),
+  closedAt: z4.string().datetime({ offset: true }).optional()
+});
+var operationBaseSchema = z4.object({
+  id: z4.string().min(1),
+  type: canonicalOperationTypeSchema,
+  domain: z4.string().trim().min(1)
+});
+var knowledgePatchCreateOperationSchema = operationBaseSchema.extend({
+  kind: z4.literal("create"),
+  payload: z4.record(z4.string(), z4.unknown())
+});
+var knowledgePatchUpdateOperationSchema = operationBaseSchema.extend({
+  kind: z4.literal("update"),
+  targetId: z4.string().min(1),
+  payload: z4.record(z4.string(), z4.unknown())
+});
+var knowledgePatchDeleteOperationSchema = operationBaseSchema.extend({
+  kind: z4.literal("delete"),
+  targetId: z4.string().min(1),
+  reason: z4.string().trim().min(1)
+});
+var knowledgePatchOperationSchema = z4.discriminatedUnion("kind", [
+  knowledgePatchCreateOperationSchema,
+  knowledgePatchUpdateOperationSchema,
+  knowledgePatchDeleteOperationSchema
+]);
+var knowledgePatchOperationsEnvelopeSchema = z4.object({
+  schemaVersion: z4.literal(KNOWLEDGE_PATCH_SCHEMA_VERSION),
+  operations: z4.array(knowledgePatchOperationSchema)
+});
+var knowledgePatchDiagnosticSchema = z4.object({
+  severity: z4.enum(["error", "critical"]),
+  code: z4.string(),
+  message: z4.string(),
+  patchId: z4.string().optional(),
+  operationId: z4.string().optional(),
+  targetId: z4.string().optional(),
+  path: z4.array(z4.union([z4.string(), z4.number()])).optional(),
+  supportedTypes: z4.array(z4.string()).optional()
+});
+var knowledgePatchValidationResultSchema = z4.object({
+  valid: z4.boolean(),
+  fingerprint: z4.string().optional(),
+  diagnostics: z4.array(knowledgePatchDiagnosticSchema),
+  operationCount: z4.number().int().nonnegative(),
+  appliedOperationIds: z4.array(z4.string()),
+  affectedFiles: z4.array(z4.string())
+});
+var knowledgePatchApplyApprovalSchema = z4.object({
+  approved: z4.boolean(),
+  validationFingerprint: z4.string().min(1)
+});
+var createPatchInputSchema = z4.object({
+  title: z4.string().trim().min(1),
+  description: z4.string().trim().min(1).optional(),
+  rootFolder: z4.string().trim().min(1),
+  omittedFiles: z4.array(
+    z4.object({
+      path: z4.string().trim().min(1),
+      reason: z4.string().trim().min(1)
+    })
+  ).optional()
+});
+var addOperationInputSchema = z4.discriminatedUnion("kind", [
+  knowledgePatchCreateOperationSchema.omit({ id: true }).extend({
+    id: z4.string().min(1).optional()
+  }),
+  knowledgePatchUpdateOperationSchema.omit({ id: true }).extend({
+    id: z4.string().min(1).optional()
+  }),
+  knowledgePatchDeleteOperationSchema.omit({ id: true }).extend({
+    id: z4.string().min(1).optional()
+  })
+]);
+var updateOperationInputSchema = z4.object({
+  operationId: z4.string().min(1),
+  operation: addOperationInputSchema
+});
+var updatePatchMetadataInputSchema = z4.object({
+  rootFolder: z4.string().trim().min(1).optional(),
+  omittedFiles: z4.array(
+    z4.object({
+      path: z4.string().trim().min(1),
+      reason: z4.string().trim().min(1)
+    })
+  )
+});
+var knowledgePatchToolInputSchema = z4.discriminatedUnion("action", [
+  z4.object({
+    action: z4.literal("create"),
+    patch: createPatchInputSchema
+  }),
+  z4.object({
+    action: z4.literal("list")
+  }),
+  z4.object({
+    action: z4.literal("get"),
+    patchId: z4.string().min(1)
+  }),
+  z4.object({
+    action: z4.literal("add_operation"),
+    patchId: z4.string().min(1),
+    operation: addOperationInputSchema
+  }),
+  z4.object({
+    action: z4.literal("update_operation"),
+    patchId: z4.string().min(1),
+    update: updateOperationInputSchema
+  }),
+  z4.object({
+    action: z4.literal("update_metadata"),
+    patchId: z4.string().min(1),
+    metadata: updatePatchMetadataInputSchema
+  }),
+  z4.object({
+    action: z4.literal("delete_operation"),
+    patchId: z4.string().min(1),
+    operationId: z4.string().min(1)
+  }),
+  z4.object({
+    action: z4.literal("validate"),
+    patchId: z4.string().min(1)
+  }),
+  z4.object({
+    action: z4.literal("close"),
+    patchId: z4.string().min(1)
+  })
+]);
+var knowledgePatchApplyToolInputSchema = z4.object({
+  patchId: z4.string().min(1),
+  approval: knowledgePatchApplyApprovalSchema
+});
+
+// packages/core/src/knowledge/patch/utils.ts
+function buildDiagnostic(diagnostic) {
+  return knowledgePatchDiagnosticSchema.parse(diagnostic);
+}
+
+// packages/core/src/knowledge/patch/storage.ts
+async function readJsonFile(filePath, schema) {
+  const raw = await readFile2(filePath, "utf8");
+  const parsed = JSON.parse(raw);
+  return schema.parse(parsed);
+}
+async function loadPatchStateByDir(patchDir) {
+  const patch = await readJsonFile(
+    patchMetadataPath(patchDir),
+    knowledgePatchMetadataSchema
+  );
+  const envelope = await readJsonFile(
+    patchOperationsPath(patchDir),
+    knowledgePatchOperationsEnvelopeSchema
+  );
+  return {
+    patch,
+    operations: envelope.operations
+  };
+}
+async function readKnowledgePatch(envValue, patchId, cwd = process.cwd()) {
+  const patchDir = resolveKnowledgePatchDirectory(envValue, patchId, cwd);
+  return loadPatchStateByDir(patchDir);
+}
+async function listKnowledgePatches(envValue, cwd = process.cwd()) {
+  const patchRoot = resolveKnowledgePatchRoot(envValue, cwd);
+  if (!existsSync2(patchRoot)) {
+    return [];
+  }
+  const entries = await readdir(patchRoot, { withFileTypes: true });
+  const summaries = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const patchDir = join3(patchRoot, entry.name);
+    const state = await loadPatchStateByDir(patchDir);
+    summaries.push({
+      id: state.patch.id,
+      status: state.patch.status,
+      title: state.patch.title,
+      description: state.patch.description,
+      rootFolder: state.patch.rootFolder,
+      omittedFiles: state.patch.omittedFiles,
+      operationCount: state.operations.length,
+      createdAt: state.patch.createdAt,
+      updatedAt: state.patch.updatedAt
+    });
+  }
+  summaries.sort(
+    (left, right) => left.createdAt === right.createdAt ? left.id.localeCompare(right.id) : left.createdAt.localeCompare(right.createdAt)
+  );
+  return summaries;
+}
+
+// packages/core/src/knowledge/patch/simulation.ts
+function cloneStoreState(store) {
+  const byCollection = Object.fromEntries(
+    SUPPORTED_OPERATION_TYPES.map((collection) => [
+      collection,
+      new Map(store.byCollection[collection])
+    ])
+  );
+  return {
+    byCollection,
+    byId: new Map(store.byId)
+  };
+}
+function validateRecordIdForDomain(type, id, domain) {
+  const definition = KNOWLEDGE_EXTRACTION_TYPE_REGISTRY[type];
+  if (type === "domains") {
+    const expectedId = `domain.${domain}`;
+    return id === expectedId ? void 0 : `Expected domain record id "${id}" to equal "${expectedId}".`;
+  }
+  const expectedPrefix = `${definition.idConvention.prefix}.${domain}.`;
+  return id.startsWith(expectedPrefix) ? void 0 : `Expected record id "${id}" to start with "${expectedPrefix}".`;
+}
+function collectReferenceIds2(record) {
+  if ("relationship_type" in record) {
+    return [
+      record.from_entity_id,
+      record.to_entity_id
+    ];
+  }
+  if ("business_definition" in record) {
+    const entity = record;
+    return [
+      ...entity.domain_ids,
+      ...entity.relationship_ids,
+      ...entity.capability_ids,
+      ...entity.feature_ids,
+      ...entity.rule_ids
+    ];
+  }
+  if ("behavior_type" in record) {
+    const rule = record;
+    return [
+      ...rule.applies_to.domain_ids ?? [],
+      ...rule.applies_to.entity_ids ?? [],
+      ...rule.applies_to.capability_ids ?? [],
+      ...rule.applies_to.feature_ids ?? [],
+      ...rule.related_constraint_ids,
+      ...rule.rationale_ids
+    ];
+  }
+  if ("constraint_type" in record) {
+    const constraint = record;
+    return [
+      ...constraint.applies_to.domain_ids ?? [],
+      ...constraint.applies_to.entity_ids ?? [],
+      ...constraint.applies_to.capability_ids ?? [],
+      ...constraint.applies_to.feature_ids ?? [],
+      ...constraint.applies_to.business_rule_ids ?? []
+    ];
+  }
+  if ("parent_capability_ids" in record) {
+    const capability = record;
+    return [
+      ...capability.domain_ids,
+      ...capability.entity_ids,
+      ...capability.parent_capability_ids,
+      ...capability.child_capability_ids,
+      ...capability.feature_ids
+    ];
+  }
+  if ("rule_ids" in record && "constraint_ids" in record) {
+    const feature = record;
+    return [
+      ...feature.domain_ids,
+      ...feature.capability_ids,
+      ...feature.entity_ids,
+      ...feature.rule_ids,
+      ...feature.constraint_ids
+    ];
+  }
+  if ("entity_ids" in record && "capability_ids" in record && "why_it_exists" in record && !("business_definition" in record) && !("parent_capability_ids" in record) && !("constraint_ids" in record) && !("rule_ids" in record)) {
+    const domain = record;
+    return [...domain.entity_ids, ...domain.capability_ids];
+  }
+  if ("explains" in record) {
+    return record.explains;
+  }
+  if ("source_type" in record) {
+    return record.supports;
+  }
+  if ("priority" in record) {
+    const question = record;
+    return [...question.related_ids, ...question.evidence_ids];
+  }
+  const conflict = record;
+  return [
+    ...conflict.related_ids,
+    ...conflict.evidence_ids,
+    ...conflict.questions,
+    ...conflict.resolved_by_evidence_id ? [conflict.resolved_by_evidence_id] : []
+  ];
+}
+function parsePatchRecord(operation, diagnostics) {
+  const definition = KNOWLEDGE_EXTRACTION_TYPE_REGISTRY[operation.type];
+  if (operation.kind === "delete") {
+    return void 0;
+  }
+  const parsed = definition.schema.safeParse(operation.payload);
+  if (!parsed.success) {
+    diagnostics.push(
+      buildDiagnostic({
+        severity: "error",
+        code: "invalid_payload",
+        message: `Operation "${operation.id}" payload is invalid for type "${operation.type}".`,
+        operationId: operation.id,
+        path: ["operations", operation.id, "payload"]
+      })
+    );
+    return void 0;
+  }
+  return parsed.data;
+}
+function simulateKnowledgePatch(store, operations, patchId) {
+  const state = cloneStoreState(store);
+  const diagnostics = [];
+  const deleteTargets = [];
+  const appliedOperationIds = [];
+  for (const operation of operations) {
+    if (!supportedOperationTypeSet.has(operation.type)) {
+      diagnostics.push(
+        buildDiagnostic({
+          severity: "error",
+          code: "invalid_type",
+          message: `Unsupported patch operation type "${operation.type}".`,
+          patchId,
+          operationId: operation.id,
+          supportedTypes: SUPPORTED_OPERATION_TYPES
+        })
+      );
+      continue;
+    }
+    if (operation.kind === "delete") {
+      const existing = state.byCollection[operation.type].get(
+        operation.targetId
+      );
+      if (!existing) {
+        diagnostics.push(
+          buildDiagnostic({
+            severity: "error",
+            code: "missing_target",
+            message: `Delete target "${operation.targetId}" does not exist in "${operation.type}".`,
+            patchId,
+            operationId: operation.id,
+            targetId: operation.targetId
+          })
+        );
+        continue;
+      }
+      state.byCollection[operation.type].delete(operation.targetId);
+      state.byId.delete(operation.targetId);
+      deleteTargets.push(operation.targetId);
+      appliedOperationIds.push(operation.id);
+      continue;
+    }
+    const parsedRecord = parsePatchRecord(operation, diagnostics);
+    if (!parsedRecord) {
+      continue;
+    }
+    const idMessage = validateRecordIdForDomain(
+      operation.type,
+      parsedRecord.id,
+      operation.domain
+    );
+    if (idMessage) {
+      diagnostics.push(
+        buildDiagnostic({
+          severity: "error",
+          code: "invalid_id_convention",
+          message: idMessage,
+          patchId,
+          operationId: operation.id,
+          targetId: parsedRecord.id
+        })
+      );
+      continue;
+    }
+    if (operation.kind === "create" && state.byId.has(parsedRecord.id)) {
+      diagnostics.push(
+        buildDiagnostic({
+          severity: "error",
+          code: "duplicate_id",
+          message: `Create operation would duplicate existing id "${parsedRecord.id}".`,
+          patchId,
+          operationId: operation.id,
+          targetId: parsedRecord.id
+        })
+      );
+      continue;
+    }
+    if (operation.kind === "update") {
+      if (parsedRecord.id !== operation.targetId) {
+        diagnostics.push(
+          buildDiagnostic({
+            severity: "error",
+            code: "update_target_mismatch",
+            message: `Update payload id "${parsedRecord.id}" must match target "${operation.targetId}".`,
+            patchId,
+            operationId: operation.id,
+            targetId: operation.targetId
+          })
+        );
+        continue;
+      }
+      if (!state.byCollection[operation.type].has(operation.targetId)) {
+        diagnostics.push(
+          buildDiagnostic({
+            severity: "error",
+            code: "missing_target",
+            message: `Update target "${operation.targetId}" does not exist in "${operation.type}".`,
+            patchId,
+            operationId: operation.id,
+            targetId: operation.targetId
+          })
+        );
+        continue;
+      }
+    }
+    state.byCollection[operation.type].set(parsedRecord.id, parsedRecord);
+    state.byId.set(parsedRecord.id, parsedRecord);
+    appliedOperationIds.push(operation.id);
+  }
+  for (const record of state.byId.values()) {
+    for (const referenceId of collectReferenceIds2(record)) {
+      if (!state.byId.has(referenceId)) {
+        diagnostics.push(
+          buildDiagnostic({
+            severity: "error",
+            code: "invalid_reference",
+            message: `Record "${record.id}" references unknown id "${referenceId}".`,
+            patchId,
+            targetId: record.id
+          })
+        );
+      }
+    }
+  }
+  const inboundReferenceMap = /* @__PURE__ */ new Map();
+  for (const record of state.byId.values()) {
+    for (const referenceId of collectReferenceIds2(record)) {
+      const inbound = inboundReferenceMap.get(referenceId) ?? [];
+      inbound.push(record.id);
+      inboundReferenceMap.set(referenceId, inbound);
+    }
+  }
+  for (const deleteTarget of deleteTargets) {
+    const inbound = inboundReferenceMap.get(deleteTarget) ?? [];
+    if (inbound.length > 0) {
+      diagnostics.push(
+        buildDiagnostic({
+          severity: "error",
+          code: "delete_has_inbound_references",
+          message: `Delete target "${deleteTarget}" still has inbound references from: ${inbound.join(
+            ", "
+          )}`,
+          patchId,
+          targetId: deleteTarget
+        })
+      );
+    }
+  }
+  return {
+    state,
+    diagnostics,
+    appliedOperationIds,
+    deleteTargets
+  };
+}
+
+// packages/core/src/knowledge/effective-state.ts
+function toSimulationStore(rootDir, sourceFiles, state) {
+  const store = {
+    rootDir,
+    sourceFiles,
+    domains: [...state.byCollection.domains.values()],
+    entities: [...state.byCollection.entities.values()],
+    relationships: [...state.byCollection.relationships.values()],
+    capabilities: [...state.byCollection.capabilities.values()],
+    features: [...state.byCollection.features.values()],
+    business_rules: [...state.byCollection.business_rules.values()],
+    constraints: [...state.byCollection.constraints.values()],
+    rationales: [...state.byCollection.rationales.values()],
+    evidence: [...state.byCollection.evidence.values()],
+    questions: [...state.byCollection.questions.values()],
+    conflicts: [...state.byCollection.conflicts.values()],
+    byCollection: state.byCollection,
+    byId: state.byId,
+    reverseReferences: /* @__PURE__ */ new Map(),
+    diagnostics: []
+  };
+  for (const record of store.byId.values()) {
+    for (const referenceId of collectReferenceIds2(record)) {
+      const reverse = store.reverseReferences.get(referenceId) ?? [];
+      reverse.push(record.id);
+      store.reverseReferences.set(referenceId, reverse);
+    }
+  }
+  return store;
+}
+function selectOrderedPatches(patches, options) {
+  const visiblePatches = options.includeAllStatuses ? patches : patches.filter((patch) => patch.status === "draft");
+  if (!options.selectedPatchId) {
+    return visiblePatches;
+  }
+  const selectedIndex = visiblePatches.findIndex(
+    (patch) => patch.id === options.selectedPatchId
+  );
+  if (selectedIndex === -1) {
+    throw new Error(`Patch "${options.selectedPatchId}" was not found.`);
+  }
+  const endIndex = options.includeSelectedPatch === false ? selectedIndex : selectedIndex + 1;
+  return visiblePatches.slice(0, endIndex);
+}
+async function composeEffectiveKnowledgeState(store, envValue, options = {}, cwd = process.cwd()) {
+  const orderedPatches = selectOrderedPatches(
+    await listKnowledgePatches(envValue, cwd),
+    options
+  );
+  let currentState = store;
+  const provenance = /* @__PURE__ */ new Map();
+  const diagnostics = [];
+  for (const patch of orderedPatches) {
+    const patchState = await readKnowledgePatch(envValue, patch.id, cwd);
+    const simulation = simulateKnowledgePatch(
+      currentState,
+      patchState.operations,
+      patch.id
+    );
+    diagnostics.push(...simulation.diagnostics);
+    for (const operationId of simulation.appliedOperationIds) {
+      const operation = patchState.operations.find(
+        (entry) => entry.id === operationId
+      );
+      if (!operation || operation.kind === "delete") {
+        continue;
+      }
+      const recordId = operation.kind === "update" ? operation.targetId : operation.payload.id;
+      const existing = provenance.get(recordId);
+      const patchIds = new Set(existing?.patchIds ?? []);
+      patchIds.add(patch.id);
+      provenance.set(recordId, {
+        patchIds: [...patchIds],
+        patched: true
+      });
+    }
+    currentState = toSimulationStore(
+      store.rootDir,
+      store.sourceFiles,
+      simulation.state
+    );
+  }
+  return {
+    store: currentState,
+    patches: orderedPatches,
+    patchIds: orderedPatches.map((patch) => patch.id),
+    provenance,
+    diagnostics
+  };
+}
+async function loadEffectiveKnowledgeStoreFromRoot(rootDir, options = {}) {
+  const store = await loadKnowledgeStoreFromRoot(rootDir);
+  return composeEffectiveKnowledgeState(store, rootDir, options);
+}
+
+// packages/core/src/knowledge/graphql.ts
+import {
+  GraphQLBoolean,
+  GraphQLFloat,
+  GraphQLID,
+  GraphQLList,
+  GraphQLObjectType,
+  GraphQLSchema,
+  GraphQLString,
+  graphql
+} from "graphql";
+function stringifyValue(value) {
+  if (value === void 0 || value === null) {
+    return null;
+  }
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
+var confidenceType = new GraphQLObjectType({
+  name: "Confidence",
+  fields: {
+    score: { type: GraphQLFloat },
+    level: { type: GraphQLString },
+    reason: { type: GraphQLString }
+  }
+});
+var locationType = new GraphQLObjectType({
+  name: "EvidenceLocation",
+  fields: {
+    path: { type: GraphQLString },
+    symbol: { type: GraphQLString },
+    route: { type: GraphQLString },
+    api: { type: GraphQLString },
+    query: { type: GraphQLString }
+  }
+});
+var evidenceType = new GraphQLObjectType({
+  name: "Evidence",
+  fields: () => ({
+    id: { type: GraphQLID },
+    source_type: { type: GraphQLString },
+    description: { type: GraphQLString },
+    location: { type: locationType },
+    supports: { type: new GraphQLList(GraphQLID) },
+    excerpt: { type: GraphQLString },
+    confidence: { type: confidenceType }
+  })
+});
+var entityTechnicalRepresentationType = new GraphQLObjectType({
+  name: "EntityTechnicalRepresentation",
+  fields: {
+    kind: { type: GraphQLString },
+    name: { type: GraphQLString },
+    location_hint: { type: GraphQLString }
+  }
+});
+var entityType = new GraphQLObjectType({
+  name: "Entity",
+  fields: () => ({
+    id: { type: GraphQLID },
+    name: { type: GraphQLString },
+    business_definition: { type: GraphQLString },
+    description: { type: GraphQLString },
+    purpose: { type: GraphQLString },
+    aliases: { type: new GraphQLList(GraphQLString) },
+    ambiguous_terms: { type: new GraphQLList(GraphQLString) },
+    technical_representations: {
+      type: new GraphQLList(entityTechnicalRepresentationType)
+    },
+    domain_ids: { type: new GraphQLList(GraphQLID) },
+    state_values: { type: new GraphQLList(GraphQLString) },
+    relationship_ids: { type: new GraphQLList(GraphQLID) },
+    capability_ids: { type: new GraphQLList(GraphQLID) },
+    feature_ids: { type: new GraphQLList(GraphQLID) },
+    rule_ids: { type: new GraphQLList(GraphQLID) },
+    domains: {
+      type: new GraphQLList(domainType),
+      resolve: (entity, _args, context) => resolveByIds(context, "domains", entity.domain_ids)
+    },
+    relationships: {
+      type: new GraphQLList(entityRelationshipType),
+      resolve: (entity, _args, context) => resolveByIds(context, "relationships", entity.relationship_ids)
+    },
+    capabilities: {
+      type: new GraphQLList(capabilityType),
+      resolve: (entity, _args, context) => resolveByIds(context, "capabilities", entity.capability_ids)
+    },
+    features: {
+      type: new GraphQLList(featureType),
+      resolve: (entity, _args, context) => resolveByIds(context, "features", entity.feature_ids)
+    },
+    business_rules: {
+      type: new GraphQLList(businessRuleType),
+      resolve: (entity, _args, context) => resolveByIds(context, "business_rules", entity.rule_ids)
+    },
+    certainty: { type: GraphQLString },
+    confidence: { type: confidenceType }
+  })
+});
+var ruleConditionType = new GraphQLObjectType({
+  name: "RuleCondition",
+  fields: {
+    subject: { type: GraphQLString },
+    field: { type: GraphQLString },
+    operator: { type: GraphQLString },
+    value: {
+      type: GraphQLString,
+      resolve: (condition) => stringifyValue(condition.value)
+    }
+  }
+});
+var ruleTriggerType = new GraphQLObjectType({
+  name: "RuleTrigger",
+  fields: {
+    actor: { type: GraphQLString },
+    action: { type: GraphQLString },
+    subject: { type: GraphQLString },
+    field: { type: GraphQLString },
+    operator: { type: GraphQLString },
+    value: {
+      type: GraphQLString,
+      resolve: (trigger) => stringifyValue(trigger.value)
+    }
+  }
+});
+var ruleEffectType = new GraphQLObjectType({
+  name: "RuleEffect",
+  fields: {
+    effect: { type: GraphQLString },
+    action: { type: GraphQLString },
+    message: { type: GraphQLString },
+    target_state: { type: GraphQLString },
+    value: {
+      type: GraphQLString,
+      resolve: (effect) => stringifyValue(effect.value)
+    }
+  }
+});
+var businessRuleConditionType = new GraphQLObjectType({
+  name: "BusinessRuleCondition",
+  fields: {
+    given: { type: new GraphQLList(ruleConditionType) },
+    when: { type: new GraphQLList(ruleTriggerType) },
+    then: { type: new GraphQLList(ruleEffectType) }
+  }
+});
+var businessRuleAppliesToType = new GraphQLObjectType({
+  name: "BusinessRuleAppliesTo",
+  fields: {
+    domain_ids: { type: new GraphQLList(GraphQLID) },
+    entity_ids: { type: new GraphQLList(GraphQLID) },
+    capability_ids: { type: new GraphQLList(GraphQLID) },
+    feature_ids: { type: new GraphQLList(GraphQLID) }
+  }
+});
+var businessRuleEnforcementType = new GraphQLObjectType({
+  name: "BusinessRuleEnforcement",
+  fields: {
+    level: { type: GraphQLString },
+    description: { type: GraphQLString }
+  }
+});
+var businessRuleType = new GraphQLObjectType({
+  name: "BusinessRule",
+  fields: () => ({
+    id: { type: GraphQLID },
+    name: { type: GraphQLString },
+    statement: { type: GraphQLString },
+    rule_type: { type: GraphQLString },
+    behavior_type: { type: GraphQLString },
+    applies_to: { type: businessRuleAppliesToType },
+    condition: { type: businessRuleConditionType },
+    enforcement: { type: businessRuleEnforcementType },
+    related_constraint_ids: { type: new GraphQLList(GraphQLID) },
+    rationale_ids: { type: new GraphQLList(GraphQLID) },
+    certainty: { type: GraphQLString },
+    confidence: { type: confidenceType }
+  })
+});
+var constraintCauseType = new GraphQLObjectType({
+  name: "ConstraintCause",
+  fields: {
+    source: { type: GraphQLString },
+    source_type: { type: GraphQLString },
+    description: { type: GraphQLString }
+  }
+});
+var constraintImpactType = new GraphQLObjectType({
+  name: "ConstraintImpact",
+  fields: {
+    affected_change_types: { type: new GraphQLList(GraphQLString) },
+    severity: { type: GraphQLString },
+    description: { type: GraphQLString }
+  }
+});
+var constraintAppliesToType = new GraphQLObjectType({
+  name: "ConstraintAppliesTo",
+  fields: {
+    domain_ids: { type: new GraphQLList(GraphQLID) },
+    entity_ids: { type: new GraphQLList(GraphQLID) },
+    capability_ids: { type: new GraphQLList(GraphQLID) },
+    feature_ids: { type: new GraphQLList(GraphQLID) },
+    business_rule_ids: { type: new GraphQLList(GraphQLID) }
+  }
+});
+var constraintWorkaroundType = new GraphQLObjectType({
+  name: "ConstraintWorkaround",
+  fields: {
+    exists: { type: GraphQLString },
+    description: { type: GraphQLString }
+  }
+});
+var constraintRemovabilityType = new GraphQLObjectType({
+  name: "ConstraintRemovability",
+  fields: {
+    can_be_removed_by_refactor: { type: GraphQLString },
+    requires: { type: new GraphQLList(GraphQLString) },
+    risk: { type: GraphQLString }
+  }
+});
+var constraintType = new GraphQLObjectType({
+  name: "Constraint",
+  fields: () => ({
+    id: { type: GraphQLID },
+    name: { type: GraphQLString },
+    description: { type: GraphQLString },
+    constraint_type: { type: GraphQLString },
+    cause: { type: constraintCauseType },
+    impact: { type: constraintImpactType },
+    applies_to: { type: constraintAppliesToType },
+    workaround: { type: constraintWorkaroundType },
+    removability: { type: constraintRemovabilityType },
+    certainty: { type: GraphQLString },
+    confidence: { type: confidenceType }
+  })
+});
+var rationaleType = new GraphQLObjectType({
+  name: "Rationale",
+  fields: () => ({
+    id: { type: GraphQLID },
+    statement: { type: GraphQLString },
+    explains: { type: new GraphQLList(GraphQLID) },
+    certainty: { type: GraphQLString },
+    confidence: { type: confidenceType }
+  })
+});
+var questionType = new GraphQLObjectType({
+  name: "Question",
+  fields: () => ({
+    id: { type: GraphQLID },
+    question: { type: GraphQLString },
+    category: { type: GraphQLString },
+    reason: { type: GraphQLString },
+    impact: { type: GraphQLString },
+    related_ids: { type: new GraphQLList(GraphQLID) },
+    evidence_ids: { type: new GraphQLList(GraphQLID) },
+    priority: { type: GraphQLString },
+    status: { type: GraphQLString },
+    answer: { type: GraphQLString },
+    answered_by: { type: GraphQLString },
+    answered_at: { type: GraphQLString }
+  })
+});
+var conflictType = new GraphQLObjectType({
+  name: "Conflict",
+  fields: () => ({
+    id: { type: GraphQLID },
+    type: { type: GraphQLString },
+    description: { type: GraphQLString },
+    related_ids: { type: new GraphQLList(GraphQLID) },
+    evidence_ids: { type: new GraphQLList(GraphQLID) },
+    status: { type: GraphQLString },
+    questions: { type: new GraphQLList(GraphQLID) },
+    resolution: { type: GraphQLString },
+    resolved_by_evidence_id: { type: GraphQLID }
+  })
+});
+var domainType = new GraphQLObjectType({
+  name: "Domain",
+  fields: () => ({
+    id: { type: GraphQLID },
+    name: { type: GraphQLString },
+    purpose: { type: GraphQLString },
+    why_it_exists: { type: GraphQLString },
+    entity_ids: { type: new GraphQLList(GraphQLID) },
+    capability_ids: { type: new GraphQLList(GraphQLID) },
+    entities: {
+      type: new GraphQLList(entityType),
+      resolve: (domain, _args, context) => resolveByIds(context, "entities", domain.entity_ids)
+    },
+    capabilities: {
+      type: new GraphQLList(capabilityType),
+      resolve: (domain, _args, context) => resolveByIds(context, "capabilities", domain.capability_ids)
+    },
+    certainty: { type: GraphQLString },
+    confidence: { type: confidenceType }
+  })
+});
+var entityRelationshipType = new GraphQLObjectType({
+  name: "EntityRelationship",
+  fields: () => ({
+    id: { type: GraphQLID },
+    from_entity_id: { type: GraphQLID },
+    to_entity_id: { type: GraphQLID },
+    relationship_type: { type: GraphQLString },
+    description: { type: GraphQLString },
+    from_entity: {
+      type: entityType,
+      resolve: (relationship, _args, context) => resolveByIds(context, "entities", [relationship.from_entity_id])[0] ?? null
+    },
+    to_entity: {
+      type: entityType,
+      resolve: (relationship, _args, context) => resolveByIds(context, "entities", [relationship.to_entity_id])[0] ?? null
+    },
+    certainty: { type: GraphQLString },
+    confidence: { type: confidenceType }
+  })
+});
+var capabilityType = new GraphQLObjectType({
+  name: "Capability",
+  fields: () => ({
+    id: { type: GraphQLID },
+    name: { type: GraphQLString },
+    description: { type: GraphQLString },
+    why_it_exists: { type: GraphQLString },
+    domain_ids: { type: new GraphQLList(GraphQLID) },
+    entity_ids: { type: new GraphQLList(GraphQLID) },
+    parent_capability_ids: { type: new GraphQLList(GraphQLID) },
+    child_capability_ids: { type: new GraphQLList(GraphQLID) },
+    feature_ids: { type: new GraphQLList(GraphQLID) },
+    domains: {
+      type: new GraphQLList(domainType),
+      resolve: (capability, _args, context) => resolveByIds(context, "domains", capability.domain_ids)
+    },
+    entities: {
+      type: new GraphQLList(entityType),
+      resolve: (capability, _args, context) => resolveByIds(context, "entities", capability.entity_ids)
+    },
+    parent_capabilities: {
+      type: new GraphQLList(capabilityType),
+      resolve: (capability, _args, context) => resolveByIds(context, "capabilities", capability.parent_capability_ids)
+    },
+    child_capabilities: {
+      type: new GraphQLList(capabilityType),
+      resolve: (capability, _args, context) => resolveByIds(context, "capabilities", capability.child_capability_ids)
+    },
+    features: {
+      type: new GraphQLList(featureType),
+      resolve: (capability, _args, context) => resolveByIds(context, "features", capability.feature_ids)
+    },
+    certainty: { type: GraphQLString },
+    confidence: { type: confidenceType }
+  })
+});
+var featureType = new GraphQLObjectType({
+  name: "Feature",
+  fields: () => ({
+    id: { type: GraphQLID },
+    name: { type: GraphQLString },
+    description: { type: GraphQLString },
+    purpose: { type: GraphQLString },
+    why_it_exists: { type: GraphQLString },
+    domain_ids: { type: new GraphQLList(GraphQLID) },
+    capability_ids: { type: new GraphQLList(GraphQLID) },
+    entity_ids: { type: new GraphQLList(GraphQLID) },
+    rule_ids: { type: new GraphQLList(GraphQLID) },
+    constraint_ids: { type: new GraphQLList(GraphQLID) },
+    domains: {
+      type: new GraphQLList(domainType),
+      resolve: (feature, _args, context) => resolveByIds(context, "domains", feature.domain_ids)
+    },
+    capabilities: {
+      type: new GraphQLList(capabilityType),
+      resolve: (feature, _args, context) => resolveByIds(context, "capabilities", feature.capability_ids)
+    },
+    entities: {
+      type: new GraphQLList(entityType),
+      resolve: (feature, _args, context) => resolveByIds(context, "entities", feature.entity_ids)
+    },
+    business_rules: {
+      type: new GraphQLList(businessRuleType),
+      resolve: (feature, _args, context) => resolveByIds(context, "business_rules", feature.rule_ids)
+    },
+    constraints: {
+      type: new GraphQLList(constraintType),
+      resolve: (feature, _args, context) => resolveByIds(context, "constraints", feature.constraint_ids)
+    },
+    certainty: { type: GraphQLString },
+    confidence: { type: confidenceType }
+  })
+});
+function resolveCollection(store, collection) {
+  if (!store) {
+    return [];
+  }
+  return store[collection];
+}
+function resolveByIds(store, collection, ids) {
+  if (!store || !ids?.length) {
+    return [];
+  }
+  const typedCollection = store.byCollection[collection];
+  return ids.map((id) => typedCollection.get(id)).filter((item) => item !== void 0);
+}
+var queryType = new GraphQLObjectType({
+  name: "Query",
+  fields: () => ({
+    store_available: {
+      type: GraphQLBoolean,
+      resolve: (_source, _args, context) => Boolean(context)
+    },
+    domains: {
+      type: new GraphQLList(domainType),
+      resolve: (_source, _args, context) => resolveCollection(context, "domains")
+    },
+    domain: {
+      type: domainType,
+      args: {
+        id: { type: GraphQLID }
+      },
+      resolve: (_source, args, context) => context?.byCollection.domains.get(args.id) ?? null
+    },
+    entities: {
+      type: new GraphQLList(entityType),
+      resolve: (_source, _args, context) => resolveCollection(context, "entities")
+    },
+    entity: {
+      type: entityType,
+      args: {
+        id: { type: GraphQLID }
+      },
+      resolve: (_source, args, context) => context?.byCollection.entities.get(args.id) ?? null
+    },
+    relationships: {
+      type: new GraphQLList(entityRelationshipType),
+      resolve: (_source, _args, context) => resolveCollection(context, "relationships")
+    },
+    capabilities: {
+      type: new GraphQLList(capabilityType),
+      resolve: (_source, _args, context) => resolveCollection(context, "capabilities")
+    },
+    capability: {
+      type: capabilityType,
+      args: {
+        id: { type: GraphQLID }
+      },
+      resolve: (_source, args, context) => context?.byCollection.capabilities.get(args.id) ?? null
+    },
+    features: {
+      type: new GraphQLList(featureType),
+      resolve: (_source, _args, context) => resolveCollection(context, "features")
+    },
+    feature: {
+      type: featureType,
+      args: {
+        id: { type: GraphQLID }
+      },
+      resolve: (_source, args, context) => context?.byCollection.features.get(args.id) ?? null
+    },
+    business_rules: {
+      type: new GraphQLList(businessRuleType),
+      resolve: (_source, _args, context) => resolveCollection(context, "business_rules")
+    },
+    business_rule: {
+      type: businessRuleType,
+      args: {
+        id: { type: GraphQLID }
+      },
+      resolve: (_source, args, context) => context?.byCollection.business_rules.get(args.id) ?? null
+    },
+    constraints: {
+      type: new GraphQLList(constraintType),
+      resolve: (_source, _args, context) => resolveCollection(context, "constraints")
+    },
+    constraint: {
+      type: constraintType,
+      args: {
+        id: { type: GraphQLID }
+      },
+      resolve: (_source, args, context) => context?.byCollection.constraints.get(args.id) ?? null
+    },
+    rationales: {
+      type: new GraphQLList(rationaleType),
+      resolve: (_source, _args, context) => resolveCollection(context, "rationales")
+    },
+    rationale: {
+      type: rationaleType,
+      args: {
+        id: { type: GraphQLID }
+      },
+      resolve: (_source, args, context) => context?.byCollection.rationales.get(args.id) ?? null
+    },
+    evidence: {
+      type: new GraphQLList(evidenceType),
+      resolve: (_source, _args, context) => resolveCollection(context, "evidence")
+    },
+    question: {
+      type: questionType,
+      args: {
+        id: { type: GraphQLID }
+      },
+      resolve: (_source, args, context) => context?.byCollection.questions.get(args.id) ?? null
+    },
+    questions: {
+      type: new GraphQLList(questionType),
+      resolve: (_source, _args, context) => resolveCollection(context, "questions")
+    },
+    conflict: {
+      type: conflictType,
+      args: {
+        id: { type: GraphQLID }
+      },
+      resolve: (_source, args, context) => context?.byCollection.conflicts.get(args.id) ?? null
+    },
+    conflicts: {
+      type: new GraphQLList(conflictType),
+      resolve: (_source, _args, context) => resolveCollection(context, "conflicts")
+    }
+  })
+});
+var knowledgeGraphSchema = new GraphQLSchema({
+  query: queryType
+});
+
+// packages/core/src/knowledge/patch/scope-audit.ts
+import { z as z6 } from "zod/v4";
+var compareScopeWithEvidenceInputSchema = z6.object({
+  patchId: z6.string().min(1),
+  rootFolder: z6.string().trim().min(1).optional()
+});
+var compareScopeWithEvidenceResultSchema = z6.object({
+  patchId: z6.string().min(1),
+  rootFolder: z6.string().min(1),
+  scopeFiles: z6.array(z6.string()),
+  coveredFiles: z6.array(z6.string()),
+  omittedFiles: z6.array(
+    z6.object({
+      path: z6.string(),
+      reason: z6.string()
+    })
+  ),
+  uncoveredFiles: z6.array(z6.string()),
+  outOfRootEvidenceFiles: z6.array(z6.string()),
+  message: z6.string()
+});
+
+// packages/core/src/knowledge/schema-discovery.ts
+import {
+  isAbstractType,
+  isCompositeType,
+  isListType,
+  isNonNullType,
+  isObjectType,
+  isScalarType,
+  isUnionType
+} from "graphql";
+
+// packages/rest/src/constants.ts
+var REST_SERVICE_NAME = "ez-know-rest";
+var REST_V1_PREFIX = "/api/v1";
+var REST_OPENAPI_PATH = "/api/openapi.json";
+var REST_DOCS_PATH = "/api/docs";
+var REST_HEALTH_PATH = "/api/health";
+var REST_PATCHES_ROUTE = "patches";
+var REST_PATCH_PREVIEW_ROUTE = "patches/:patchId/preview";
+var REST_PATCH_PREVIEW_PATH = "patches/{patchId}/preview";
+var REST_COLLECTIONS = [
+  { route: "domains", collection: "domains", label: "Domains" },
+  { route: "entities", collection: "entities", label: "Entities" },
+  {
+    route: "relationships",
+    collection: "relationships",
+    label: "Relationships"
+  },
+  {
+    route: "capabilities",
+    collection: "capabilities",
+    label: "Capabilities"
+  },
+  { route: "features", collection: "features", label: "Features" },
+  {
+    route: "business-rules",
+    collection: "business_rules",
+    label: "Business rules"
+  },
+  { route: "constraints", collection: "constraints", label: "Constraints" },
+  { route: "rationales", collection: "rationales", label: "Rationales" },
+  { route: "evidence", collection: "evidence", label: "Evidence" },
+  { route: "questions", collection: "questions", label: "Questions" },
+  { route: "conflicts", collection: "conflicts", label: "Conflicts" }
+];
+var REST_COLLECTION_ROUTE_LOOKUP = new Map(
+  REST_COLLECTIONS.map((definition) => [definition.route, definition])
+);
+
+// packages/rest/src/docs.ts
+function buildSwaggerUiHtml(openApiPath = REST_OPENAPI_PATH) {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>ez-know REST API</title>
+    <link
+      rel="stylesheet"
+      href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css"
+    />
+    <style>
+      html,
+      body {
+        margin: 0;
+        padding: 0;
+        background: #0f172a;
+      }
+
+      #swagger-ui {
+        background: #fff;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js" crossorigin="anonymous"></script>
+    <script>
+      window.ui = SwaggerUIBundle({
+        url: '${openApiPath}',
+        dom_id: '#swagger-ui',
+        deepLinking: true,
+        presets: [SwaggerUIBundle.presets.apis],
+      });
+    </script>
+  </body>
+</html>`;
+}
+
+// packages/rest/src/openapi.ts
+import {
+  extendZodWithOpenApi as extendZodWithOpenApi2,
+  OpenAPIRegistry,
+  OpenApiGeneratorV3
+} from "@asteasolutions/zod-to-openapi";
+import { z as z7 } from "zod/v4";
+
+// packages/rest/src/schema-registry.ts
+var REST_COLLECTION_SCHEMA_REGISTRY = {
+  domains: {
+    itemName: "Domain",
+    itemSchema: domainSchema,
+    collectionResponseName: "DomainCollectionResponse",
+    itemResponseName: "DomainItemResponse"
+  },
+  entities: {
+    itemName: "Entity",
+    itemSchema: entitySchema,
+    collectionResponseName: "EntityCollectionResponse",
+    itemResponseName: "EntityItemResponse"
+  },
+  relationships: {
+    itemName: "EntityRelationship",
+    itemSchema: relationshipSchema,
+    collectionResponseName: "EntityRelationshipCollectionResponse",
+    itemResponseName: "EntityRelationshipItemResponse"
+  },
+  capabilities: {
+    itemName: "Capability",
+    itemSchema: capabilitySchema,
+    collectionResponseName: "CapabilityCollectionResponse",
+    itemResponseName: "CapabilityItemResponse"
+  },
+  features: {
+    itemName: "Feature",
+    itemSchema: featureSchema,
+    collectionResponseName: "FeatureCollectionResponse",
+    itemResponseName: "FeatureItemResponse"
+  },
+  business_rules: {
+    itemName: "BusinessRule",
+    itemSchema: businessRuleSchema,
+    collectionResponseName: "BusinessRuleCollectionResponse",
+    itemResponseName: "BusinessRuleItemResponse"
+  },
+  constraints: {
+    itemName: "Constraint",
+    itemSchema: constraintSchema,
+    collectionResponseName: "ConstraintCollectionResponse",
+    itemResponseName: "ConstraintItemResponse"
+  },
+  rationales: {
+    itemName: "Rationale",
+    itemSchema: rationaleSchema,
+    collectionResponseName: "RationaleCollectionResponse",
+    itemResponseName: "RationaleItemResponse"
+  },
+  evidence: {
+    itemName: "Evidence",
+    itemSchema: evidenceSchema,
+    collectionResponseName: "EvidenceCollectionResponse",
+    itemResponseName: "EvidenceItemResponse"
+  },
+  questions: {
+    itemName: "Question",
+    itemSchema: questionSchema,
+    collectionResponseName: "QuestionCollectionResponse",
+    itemResponseName: "QuestionItemResponse"
+  },
+  conflicts: {
+    itemName: "Conflict",
+    itemSchema: conflictSchema,
+    collectionResponseName: "ConflictCollectionResponse",
+    itemResponseName: "ConflictItemResponse"
+  }
+};
+function getRestCollectionSchemaDefinition(collection) {
+  return REST_COLLECTION_SCHEMA_REGISTRY[collection];
+}
+var REST_CONFIDENCE_SCHEMA = confidenceSchema;
+var REST_CERTAINTY_SCHEMA = certaintySchema;
+
+// packages/rest/src/openapi.ts
+extendZodWithOpenApi2(z7);
+var openApiRegistry = new OpenAPIRegistry();
+var restErrorResponseSchema = openApiRegistry.register(
+  "RestErrorResponse",
+  z7.object({
+    error: z7.object({
+      code: z7.string(),
+      message: z7.string()
+    })
+  }).openapi({
+    description: "Standard REST error envelope."
+  })
+);
+var restHealthResponseSchema = openApiRegistry.register(
+  "RestHealthResponse",
+  z7.object({
+    service: z7.string(),
+    status: z7.literal("ok"),
+    storeAvailable: z7.boolean()
+  }).openapi({
+    description: "Service health payload."
+  })
+);
+var restPatchSummarySchema = openApiRegistry.register(
+  "RestPatchSummary",
+  z7.object({
+    id: z7.string(),
+    status: z7.string(),
+    title: z7.string(),
+    description: z7.string().optional(),
+    rootFolder: z7.string(),
+    omittedFiles: z7.array(
+      z7.object({
+        path: z7.string(),
+        reason: z7.string()
+      })
+    ),
+    operationCount: z7.number().int().min(0),
+    createdAt: z7.string(),
+    updatedAt: z7.string()
+  }).openapi({
+    description: "Patch inventory summary."
+  })
+);
+var restPatchProvenanceEntrySchema = openApiRegistry.register(
+  "RestPatchProvenanceEntry",
+  z7.object({
+    patchIds: z7.array(z7.string()),
+    patched: z7.boolean()
+  }).openapi({
+    description: "Patch provenance for a previewed record."
+  })
+);
+var restPatchFacetItemSchema = openApiRegistry.register(
+  "RestPatchFacetItem",
+  z7.object({
+    id: z7.string(),
+    label: z7.string(),
+    patched: z7.boolean(),
+    provenancePatchIds: z7.array(z7.string())
+  }).openapi({
+    description: "Patch-aware facet option."
+  })
+);
+var confidenceRef = openApiRegistry.register(
+  "Confidence",
+  REST_CONFIDENCE_SCHEMA
+);
+var certaintyRef = openApiRegistry.register(
+  "Certainty",
+  REST_CERTAINTY_SCHEMA
+);
+var restOpenApiDocumentSchema = openApiRegistry.register(
+  "RestOpenApiDocument",
+  z7.record(z7.string(), z7.unknown())
+);
+var previewCollectionResponseSchemas = /* @__PURE__ */ new Map();
+for (const collection of REST_COLLECTIONS) {
+  const schemaDefinition = getRestCollectionSchemaDefinition(
+    collection.collection
+  );
+  const schemaShape = schemaDefinition.itemSchema.shape;
+  const itemSchemaSource = schemaShape && "certainty" in schemaShape && "confidence" in schemaShape ? schemaDefinition.itemSchema.extend({
+    certainty: certaintyRef,
+    confidence: confidenceRef
+  }) : schemaShape && "confidence" in schemaShape ? schemaDefinition.itemSchema.extend({
+    confidence: confidenceRef
+  }) : schemaDefinition.itemSchema;
+  const itemSchema = openApiRegistry.register(
+    schemaDefinition.itemName,
+    itemSchemaSource
+  );
+  const previewItemSchema = openApiRegistry.register(
+    `${schemaDefinition.itemName}PreviewRecord`,
+    itemSchemaSource.extend({
+      patched: z7.boolean(),
+      provenancePatchIds: z7.array(z7.string())
+    })
+  );
+  const collectionResponseSchema = openApiRegistry.register(
+    schemaDefinition.collectionResponseName,
+    z7.object({
+      items: z7.array(itemSchema),
+      count: z7.number().int().min(0)
+    }).openapi({
+      description: `${schemaDefinition.itemName} collection response.`
+    })
+  );
+  const previewCollectionResponseSchema = openApiRegistry.register(
+    `${schemaDefinition.itemName}PreviewCollectionResponse`,
+    z7.object({
+      items: z7.array(previewItemSchema),
+      count: z7.number().int().min(0)
+    }).openapi({
+      description: `${schemaDefinition.itemName} preview collection response.`
+    })
+  );
+  previewCollectionResponseSchemas.set(
+    collection.collection,
+    previewCollectionResponseSchema
+  );
+  const itemResponseSchema = openApiRegistry.register(
+    schemaDefinition.itemResponseName,
+    z7.object({
+      item: itemSchema
+    }).openapi({
+      description: `${schemaDefinition.itemName} item response.`
+    })
+  );
+  openApiRegistry.registerPath({
+    method: "get",
+    path: `${REST_V1_PREFIX}/${collection.route}`,
+    summary: `List ${collection.label.toLowerCase()}`,
+    responses: {
+      200: {
+        description: "Default Response",
+        content: {
+          "application/json": {
+            schema: collectionResponseSchema
+          }
+        }
+      },
+      404: {
+        description: "Default Response",
+        content: {
+          "application/json": {
+            schema: restErrorResponseSchema
+          }
+        }
+      },
+      503: {
+        description: "Default Response",
+        content: {
+          "application/json": {
+            schema: restErrorResponseSchema
+          }
+        }
+      }
+    }
+  });
+  openApiRegistry.registerPath({
+    method: "get",
+    path: `${REST_V1_PREFIX}/${collection.route}/{id}`,
+    summary: `Get ${collection.label.toLowerCase()} by id`,
+    request: {
+      params: z7.object({
+        id: z7.string()
+      })
+    },
+    responses: {
+      200: {
+        description: "Default Response",
+        content: {
+          "application/json": {
+            schema: itemResponseSchema
+          }
+        }
+      },
+      404: {
+        description: "Default Response",
+        content: {
+          "application/json": {
+            schema: restErrorResponseSchema
+          }
+        }
+      },
+      503: {
+        description: "Default Response",
+        content: {
+          "application/json": {
+            schema: restErrorResponseSchema
+          }
+        }
+      }
+    }
+  });
+}
+var restPatchInventoryResponseSchema = openApiRegistry.register(
+  "RestPatchInventoryResponse",
+  z7.object({
+    items: z7.array(restPatchSummarySchema),
+    count: z7.number().int().min(0)
+  }).openapi({
+    description: "Patch inventory response."
+  })
+);
+var restPatchPreviewResponseSchema = openApiRegistry.register(
+  "RestPatchPreviewResponse",
+  z7.object({
+    selectedPatchId: z7.string(),
+    prefixPatchIds: z7.array(z7.string()),
+    patches: z7.array(restPatchSummarySchema),
+    provenance: z7.record(z7.string(), restPatchProvenanceEntrySchema),
+    facets: z7.object({
+      domains: z7.array(restPatchFacetItemSchema),
+      entities: z7.array(restPatchFacetItemSchema)
+    }).strict(),
+    collections: z7.object({
+      domains: previewCollectionResponseSchemas.get("domains"),
+      entities: previewCollectionResponseSchemas.get("entities"),
+      relationships: previewCollectionResponseSchemas.get("relationships"),
+      capabilities: previewCollectionResponseSchemas.get("capabilities"),
+      features: previewCollectionResponseSchemas.get("features"),
+      business_rules: previewCollectionResponseSchemas.get("business_rules"),
+      constraints: previewCollectionResponseSchemas.get("constraints"),
+      rationales: previewCollectionResponseSchemas.get("rationales"),
+      evidence: previewCollectionResponseSchemas.get("evidence"),
+      questions: previewCollectionResponseSchemas.get("questions"),
+      conflicts: previewCollectionResponseSchemas.get("conflicts")
+    }).strict()
+  }).openapi({
+    description: "Patch-aware preview snapshot response."
+  })
+);
+openApiRegistry.registerPath({
+  method: "get",
+  path: `${REST_V1_PREFIX}/${REST_PATCHES_ROUTE}`,
+  summary: "List patch inventory",
+  responses: {
+    200: {
+      description: "Default Response",
+      content: {
+        "application/json": {
+          schema: restPatchInventoryResponseSchema
+        }
+      }
+    },
+    404: {
+      description: "Default Response",
+      content: {
+        "application/json": {
+          schema: restErrorResponseSchema
+        }
+      }
+    }
+  }
+});
+openApiRegistry.registerPath({
+  method: "get",
+  path: `${REST_V1_PREFIX}/${REST_PATCH_PREVIEW_PATH}`,
+  summary: "Preview a patch prefix",
+  request: {
+    params: z7.object({
+      patchId: z7.string()
+    })
+  },
+  responses: {
+    200: {
+      description: "Default Response",
+      content: {
+        "application/json": {
+          schema: restPatchPreviewResponseSchema
+        }
+      }
+    },
+    404: {
+      description: "Default Response",
+      content: {
+        "application/json": {
+          schema: restErrorResponseSchema
+        }
+      }
+    },
+    503: {
+      description: "Default Response",
+      content: {
+        "application/json": {
+          schema: restErrorResponseSchema
+        }
+      }
+    }
+  }
+});
+openApiRegistry.registerPath({
+  method: "get",
+  path: REST_HEALTH_PATH,
+  summary: "Service health",
+  responses: {
+    200: {
+      description: "Default Response",
+      content: {
+        "application/json": {
+          schema: restHealthResponseSchema
+        }
+      }
+    }
+  }
+});
+openApiRegistry.registerPath({
+  method: "get",
+  path: REST_OPENAPI_PATH,
+  summary: "OpenAPI document",
+  responses: {
+    200: {
+      description: "Default Response",
+      content: {
+        "application/json": {
+          schema: restOpenApiDocumentSchema
+        }
+      }
+    }
+  }
+});
+openApiRegistry.registerPath({
+  method: "get",
+  path: REST_DOCS_PATH,
+  summary: "Swagger UI",
+  responses: {
+    200: {
+      description: "Default Response",
+      content: {
+        "text/html": {
+          schema: z7.string()
+        }
+      }
+    }
+  }
+});
+function buildRestOpenApiDocument() {
+  return new OpenApiGeneratorV3(openApiRegistry.definitions).generateDocument({
+    openapi: "3.1.0",
+    info: {
+      title: "ez-know REST API",
+      version: "0.1.0",
+      description: "Read-only HTTP interface for loaded ez-know knowledge collections."
+    },
+    servers: [{ url: "/" }]
+  });
+}
+var REST_OPENAPI_DOCUMENT = buildRestOpenApiDocument();
+
+// packages/rest/src/preview.ts
+function buildPreviewRecord(record, provenance) {
+  return {
+    ...structuredClone(record),
+    patched: Boolean(provenance?.patched),
+    provenancePatchIds: provenance?.patchIds ?? []
+  };
+}
+function buildFacetItem(record, provenance) {
+  const label = "name" in record && typeof record.name === "string" ? record.name : "question" in record && typeof record.question === "string" ? record.question : record.description ?? "";
+  return {
+    id: record.id,
+    label,
+    patched: Boolean(provenance?.patched),
+    provenancePatchIds: provenance?.patchIds ?? []
+  };
+}
+function buildCollectionPreview(records, provenance) {
+  const items = records.map(
+    (record) => buildPreviewRecord(record, provenance.get(record.id))
+  );
+  return {
+    items,
+    count: items.length
+  };
+}
+async function buildPatchInventory(envValue, cwd = process.cwd()) {
+  return listKnowledgePatches(envValue, cwd);
+}
+function getCollectionNames() {
+  return [
+    "domains",
+    "entities",
+    "relationships",
+    "capabilities",
+    "features",
+    "business_rules",
+    "constraints",
+    "rationales",
+    "evidence",
+    "questions",
+    "conflicts"
+  ];
+}
+function emptyPreviewCollections() {
+  const emptyCollection = { items: [], count: 0 };
+  return {
+    domains: structuredClone(emptyCollection),
+    entities: structuredClone(emptyCollection),
+    relationships: structuredClone(emptyCollection),
+    capabilities: structuredClone(emptyCollection),
+    features: structuredClone(emptyCollection),
+    business_rules: structuredClone(emptyCollection),
+    constraints: structuredClone(emptyCollection),
+    rationales: structuredClone(emptyCollection),
+    evidence: structuredClone(emptyCollection),
+    questions: structuredClone(emptyCollection),
+    conflicts: structuredClone(emptyCollection)
+  };
+}
+async function buildPatchPreview(selectedPatchId, knowledgeRoot) {
+  const patches = await listKnowledgePatches(knowledgeRoot);
+  const selectedIndex = patches.findIndex(
+    (patch) => patch.id === selectedPatchId
+  );
+  if (selectedIndex === -1) {
+    throw new Error(`Patch "${selectedPatchId}" was not found.`);
+  }
+  const prefixPatches = patches.slice(0, selectedIndex + 1);
+  const effectiveState = await loadEffectiveKnowledgeStoreFromRoot(
+    knowledgeRoot,
+    { selectedPatchId }
+  );
+  const currentState = effectiveState.store;
+  const provenanceMap = new Map(
+    effectiveState.provenance.entries()
+  );
+  const collections = emptyPreviewCollections();
+  const provenanceObject = Object.fromEntries(provenanceMap.entries());
+  for (const collection of getCollectionNames()) {
+    const records = currentState[collection];
+    const previewCollection = buildCollectionPreview(records, provenanceMap);
+    collections[collection] = previewCollection;
+  }
+  const domainItems = currentState.domains.map(
+    (record) => buildFacetItem(record, provenanceMap.get(record.id))
+  );
+  const entityItems = currentState.entities.map(
+    (record) => buildFacetItem(record, provenanceMap.get(record.id))
+  );
+  return {
+    selectedPatchId,
+    prefixPatchIds: effectiveState.patchIds,
+    patches: prefixPatches,
+    provenance: provenanceObject,
+    facets: {
+      domains: domainItems,
+      entities: entityItems
+    },
+    collections
+  };
+}
+
+// packages/rest/src/payloads.ts
+function buildHealthPayload(serviceName, store) {
+  return {
+    service: serviceName,
+    status: "ok",
+    storeAvailable: store !== void 0
+  };
+}
+function buildErrorPayload(code, message) {
+  return {
+    error: {
+      code,
+      message
+    }
+  };
+}
+function buildCollectionPayload(items) {
+  return {
+    items,
+    count: items.length
+  };
+}
+function buildItemPayload(item) {
+  return {
+    item
+  };
+}
+
+// packages/rest/src/schemas.ts
+var restObjectSchema = {
+  type: "object",
+  required: ["id"],
+  properties: {
+    id: {
+      type: "string"
+    }
+  },
+  additionalProperties: true
+};
+var restErrorResponseSchema2 = {
+  type: "object",
+  required: ["error"],
+  properties: {
+    error: {
+      type: "object",
+      required: ["code", "message"],
+      properties: {
+        code: { type: "string" },
+        message: { type: "string" }
+      },
+      additionalProperties: false
+    }
+  },
+  additionalProperties: false
+};
+var restHealthResponseSchema2 = {
+  type: "object",
+  required: ["service", "status", "storeAvailable"],
+  properties: {
+    service: { type: "string" },
+    status: { type: "string", const: "ok" },
+    storeAvailable: { type: "boolean" }
+  },
+  additionalProperties: false
+};
+var restCollectionResponseSchema = {
+  type: "object",
+  required: ["items", "count"],
+  properties: {
+    items: {
+      type: "array",
+      items: restObjectSchema
+    },
+    count: {
+      type: "integer",
+      minimum: 0
+    }
+  },
+  additionalProperties: false
+};
+var restPatchSummarySchema2 = {
+  type: "object",
+  required: [
+    "id",
+    "status",
+    "title",
+    "rootFolder",
+    "omittedFiles",
+    "operationCount",
+    "createdAt",
+    "updatedAt"
+  ],
+  properties: {
+    id: { type: "string" },
+    status: { type: "string" },
+    title: { type: "string" },
+    description: { type: "string" },
+    rootFolder: { type: "string" },
+    omittedFiles: {
+      type: "array",
+      items: {
+        type: "object",
+        required: ["path", "reason"],
+        properties: {
+          path: { type: "string" },
+          reason: { type: "string" }
+        },
+        additionalProperties: false
+      }
+    },
+    operationCount: { type: "integer", minimum: 0 },
+    createdAt: { type: "string" },
+    updatedAt: { type: "string" }
+  },
+  additionalProperties: false
+};
+var restPatchProvenanceEntrySchema2 = {
+  type: "object",
+  required: ["patchIds", "patched"],
+  properties: {
+    patchIds: {
+      type: "array",
+      items: { type: "string" }
+    },
+    patched: { type: "boolean" }
+  },
+  additionalProperties: false
+};
+var restPatchFacetItemSchema2 = {
+  type: "object",
+  required: ["id", "label", "patched", "provenancePatchIds"],
+  properties: {
+    id: { type: "string" },
+    label: { type: "string" },
+    patched: { type: "boolean" },
+    provenancePatchIds: {
+      type: "array",
+      items: { type: "string" }
+    }
+  },
+  additionalProperties: false
+};
+var restPatchPreviewRecordSchema = {
+  type: "object",
+  required: ["patched", "provenancePatchIds"],
+  properties: {
+    patched: { type: "boolean" },
+    provenancePatchIds: {
+      type: "array",
+      items: { type: "string" }
+    }
+  },
+  additionalProperties: true
+};
+var restPatchPreviewCollectionSchema = {
+  type: "object",
+  required: ["items", "count"],
+  properties: {
+    items: {
+      type: "array",
+      items: restPatchPreviewRecordSchema
+    },
+    count: {
+      type: "integer",
+      minimum: 0
+    }
+  },
+  additionalProperties: false
+};
+var restPatchInventoryResponseSchema2 = {
+  type: "object",
+  required: ["items", "count"],
+  properties: {
+    items: {
+      type: "array",
+      items: restPatchSummarySchema2
+    },
+    count: {
+      type: "integer",
+      minimum: 0
+    }
+  },
+  additionalProperties: false
+};
+var restPatchPreviewResponseSchema2 = {
+  type: "object",
+  required: [
+    "selectedPatchId",
+    "prefixPatchIds",
+    "patches",
+    "provenance",
+    "facets",
+    "collections"
+  ],
+  properties: {
+    selectedPatchId: { type: "string" },
+    prefixPatchIds: {
+      type: "array",
+      items: { type: "string" }
+    },
+    patches: {
+      type: "array",
+      items: restPatchSummarySchema2
+    },
+    provenance: {
+      type: "object",
+      additionalProperties: restPatchProvenanceEntrySchema2
+    },
+    facets: {
+      type: "object",
+      required: ["domains", "entities"],
+      properties: {
+        domains: {
+          type: "array",
+          items: restPatchFacetItemSchema2
+        },
+        entities: {
+          type: "array",
+          items: restPatchFacetItemSchema2
+        }
+      },
+      additionalProperties: false
+    },
+    collections: {
+      type: "object",
+      required: [
+        "domains",
+        "entities",
+        "relationships",
+        "capabilities",
+        "features",
+        "business_rules",
+        "constraints",
+        "rationales",
+        "evidence",
+        "questions",
+        "conflicts"
+      ],
+      properties: {
+        domains: restPatchPreviewCollectionSchema,
+        entities: restPatchPreviewCollectionSchema,
+        relationships: restPatchPreviewCollectionSchema,
+        capabilities: restPatchPreviewCollectionSchema,
+        features: restPatchPreviewCollectionSchema,
+        business_rules: restPatchPreviewCollectionSchema,
+        constraints: restPatchPreviewCollectionSchema,
+        rationales: restPatchPreviewCollectionSchema,
+        evidence: restPatchPreviewCollectionSchema,
+        questions: restPatchPreviewCollectionSchema,
+        conflicts: restPatchPreviewCollectionSchema
+      },
+      additionalProperties: false
+    }
+  },
+  additionalProperties: false
+};
+var restItemResponseSchema = {
+  type: "object",
+  required: ["item"],
+  properties: {
+    item: restObjectSchema
+  },
+  additionalProperties: false
+};
+var restOpenApiDocumentSchema2 = {
+  type: "object",
+  additionalProperties: true
+};
+
+// packages/rest/src/routes.ts
+function getCollectionRecords(store, collection) {
+  return store[collection];
+}
+function getCollectionRecordById(store, collection, id) {
+  return store.byCollection[collection].get(id);
+}
+function buildItemParamsSchema() {
+  return {
+    type: "object",
+    required: ["id"],
+    properties: {
+      id: { type: "string" }
+    },
+    additionalProperties: false
+  };
+}
+function getPatchRoot(store) {
+  return store?.rootDir ?? process.env.EZ_KNOW_ROOT;
+}
+async function loadEffectiveRestStore(store) {
+  if (!store) {
+    return void 0;
+  }
+  const effectiveState = await loadEffectiveKnowledgeStoreFromRoot(
+    store.rootDir
+  );
+  return effectiveState.store;
+}
+function registerCollectionRoutes(app, store, collection) {
+  app.get(
+    `${REST_V1_PREFIX}/${collection.route}`,
+    {
+      schema: {
+        response: {
+          200: restCollectionResponseSchema,
+          404: restErrorResponseSchema2,
+          503: restErrorResponseSchema2
+        }
+      }
+    },
+    async (_request, reply) => {
+      const effectiveStore = await loadEffectiveRestStore(store);
+      if (!effectiveStore) {
+        reply.code(503);
+        return buildErrorPayload(
+          "missing_store",
+          "Knowledge store is unavailable."
+        );
+      }
+      return buildCollectionPayload(
+        getCollectionRecords(effectiveStore, collection.collection)
+      );
+    }
+  );
+  app.get(
+    `${REST_V1_PREFIX}/${collection.route}/:id`,
+    {
+      schema: {
+        params: buildItemParamsSchema(),
+        response: {
+          200: restItemResponseSchema,
+          404: restErrorResponseSchema2,
+          503: restErrorResponseSchema2
+        }
+      }
+    },
+    async (request, reply) => {
+      const effectiveStore = await loadEffectiveRestStore(store);
+      if (!effectiveStore) {
+        reply.code(503);
+        return buildErrorPayload(
+          "missing_store",
+          "Knowledge store is unavailable."
+        );
+      }
+      const item = getCollectionRecordById(
+        effectiveStore,
+        collection.collection,
+        request.params.id
+      );
+      if (!item) {
+        reply.code(404);
+        return buildErrorPayload(
+          "unknown_item",
+          `No item with id "${request.params.id}" exists in ${collection.collection}.`
+        );
+      }
+      return buildItemPayload(item);
+    }
+  );
+}
+async function registerRestRoutes(app, store) {
+  app.get(
+    REST_HEALTH_PATH,
+    {
+      schema: {
+        response: {
+          200: restHealthResponseSchema2
+        }
+      }
+    },
+    async () => buildHealthPayload(REST_SERVICE_NAME, store)
+  );
+  app.get(
+    REST_OPENAPI_PATH,
+    {
+      schema: {
+        response: {
+          200: restOpenApiDocumentSchema2
+        }
+      }
+    },
+    async () => REST_OPENAPI_DOCUMENT
+  );
+  app.get(
+    REST_DOCS_PATH,
+    {
+      schema: {
+        response: {
+          200: {
+            type: "string"
+          }
+        }
+      }
+    },
+    async (_request, reply) => {
+      reply.type("text/html; charset=utf-8");
+      return buildSwaggerUiHtml(REST_OPENAPI_PATH);
+    }
+  );
+  app.get(
+    `${REST_V1_PREFIX}/${REST_PATCHES_ROUTE}`,
+    {
+      schema: {
+        response: {
+          200: restPatchInventoryResponseSchema2,
+          404: restErrorResponseSchema2
+        }
+      }
+    },
+    async () => buildCollectionPayload(await buildPatchInventory(getPatchRoot(store)))
+  );
+  app.get(
+    `${REST_V1_PREFIX}/${REST_PATCH_PREVIEW_ROUTE}`,
+    {
+      schema: {
+        params: {
+          type: "object",
+          required: ["patchId"],
+          properties: {
+            patchId: { type: "string" }
+          },
+          additionalProperties: false
+        },
+        response: {
+          200: restPatchPreviewResponseSchema2,
+          404: restErrorResponseSchema2,
+          503: restErrorResponseSchema2
+        }
+      }
+    },
+    async (request, reply) => {
+      if (!store) {
+        reply.code(503);
+        return buildErrorPayload(
+          "missing_store",
+          "Knowledge store is unavailable."
+        );
+      }
+      try {
+        return await buildPatchPreview(request.params.patchId, store.rootDir);
+      } catch (error) {
+        reply.code(404);
+        return buildErrorPayload(
+          "unknown_patch",
+          error instanceof Error ? error.message : "Patch not found."
+        );
+      }
+    }
+  );
+  for (const collection of REST_COLLECTIONS) {
+    registerCollectionRoutes(app, store, collection);
+  }
+}
+
+// packages/rest/src/app.ts
+async function buildRestApp(store, options = {}) {
+  const app = Fastify({
+    logger: false
+  });
+  await registerRestRoutes(app, store);
+  if (options.staticRoot) {
+    try {
+      const staticRoot = resolve5(options.staticRoot);
+      await access(staticRoot);
+      await app.register(fastifyStatic, {
+        root: staticRoot,
+        prefix: "/"
+      });
+    } catch {
+    }
+  }
+  await app.ready();
+  return app;
+}
+
+// packages/rest/src/run.ts
+function parsePort(value, fallback) {
+  if (!value) {
+    return fallback;
+  }
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`Invalid REST port: ${value}`);
+  }
+  return parsed;
+}
+async function startRestServer(options = {}) {
+  const host = options.host ?? process.env.EZ_KNOW_REST_HOST ?? "127.0.0.1";
+  const port = options.port ?? parsePort(process.env.EZ_KNOW_REST_PORT ?? process.env.PORT, 3e3);
+  const knowledgeStore = await loadKnowledgeStoreFromEnv(
+    process.env.EZ_KNOW_ROOT
+  );
+  const app = await buildRestApp(knowledgeStore, {
+    staticRoot: options.staticRoot
+  });
+  await app.listen({ port, host });
+  console.log(`ez-know REST service listening on http://${host}:${port}`);
+  return app;
+}
+
+// src/rest-server.ts
+function resolveRestStaticRoot() {
+  const distPublicRoot = fileURLToPath(new URL("../public", import.meta.url));
+  if (existsSync3(distPublicRoot)) {
+    return distPublicRoot;
+  }
+  const webDistRoot = fileURLToPath(
+    new URL("../packages/web/dist", import.meta.url)
+  );
+  if (existsSync3(webDistRoot)) {
+    return webDistRoot;
+  }
+  return void 0;
+}
+await startRestServer({
+  staticRoot: resolveRestStaticRoot()
+});
+//# sourceMappingURL=server.js.map