@fortemi/core 2026.6.9 → 2026.7.0

package/README.md

@@ -178,6 +178,55 @@ Unfiltered browse requests fetch only the part files intersecting the requested
 results, but the controller keeps only a bounded part cache and never sets a
 materialized full export in `getIndex()`.
 
+AIWG records can use project-specific string types such as `aiwg.skill`,
+`aiwg.command`, `aiwg.rule`, `aiwg.requirement`, and `research.ref`. Validation
+still enforces required record fields, but it does not require unknown AIWG,
+research, or documentation domains to collapse into `aiwg.artifact`.
+
+For AIWG command-palette parity, opt into discovery ranking instead of the
+default deterministic substring lookup:
+
+```ts
+const ranked = controller.query('address the open issues', {
+  searchProfile: 'aiwg-discovery',
+  rank: true,
+  includeMatches: true,
+})
+```
+
+The discovery profile normalizes hyphen/space variants, strips common stopwords,
+boosts trigger and capability facets, and returns match reasons for UI debugging.
+
+Chunked indexes also support graph navigation without loading a full export:
+
+```ts
+const neighbors = await controller.neighbors('aiwg:requirement:search', {
+  direction: 'both',
+  relationshipType: 'cites',
+})
+
+const graph = await controller.toCommunityGraphChunked()
+```
+
+When scan parts are projected, relationship traversal scans the parts and
+lazy-loads detail records only when relationships are not present in the scan
+projection.
+
+Static semantic search uses an optional sidecar contract:
+
+```ts
+import { queryAiwgHybridIndex } from '@fortemi/core/aiwg-index'
+
+const embeddingSet = await fetch('/search/aiwg-index/embeddings.json').then((res) => res.json())
+const queryEmbedding = await hostEmbed('workspace health check')
+const semanticResults = queryAiwgHybridIndex(index, embeddingSet, 'health check', queryEmbedding)
+```
+
+`aiwg.fortemi.embedding.set.v1` records the model, dimensions, granularity
+(`title-summary`, `body`, `chunked-body`, or a project value), source record IDs,
+and per-vector input hashes. Hosts provide query embeddings; `@fortemi/core` does
+not add a model runtime dependency for static AIWG search.
+
 ## What You Get
 
 | Surface | Description |

package/dist/aiwg-index.d.ts

@@ -1,4 +1,5 @@
-type AiwgFortemiRecordType = 'crm.contact' | 'crm.organization' | 'crm.event' | 'crm.interaction' | 'aiwg.artifact' | 'docs.page';
+type AiwgFortemiKnownRecordType = 'crm.contact' | 'crm.organization' | 'crm.event' | 'crm.interaction' | 'aiwg.artifact' | 'docs.page';
+type AiwgFortemiRecordType = AiwgFortemiKnownRecordType | `aiwg.${string}` | `research.${string}` | `docs.${string}` | string;
 type AiwgPrivacyClassification = 'private' | 'sanitized' | 'public';
 type AiwgProvenanceConfidence = 'source' | 'candidate' | 'reviewed' | 'rejected';
 type AiwgReviewAction = 'accept' | 'reject' | 'defer';
@@ -118,7 +119,7 @@ interface AiwgFortemiChunkPart {
 interface AiwgIndexValidationResult {
     valid: boolean;
     errors: string[];
-    counts: Partial<Record<AiwgFortemiRecordType, number>>;
+    counts: Partial<Record<string, number>>;
 }
 interface AiwgChunkedIndexValidationResult {
     valid: boolean;
@@ -138,16 +139,22 @@ interface AiwgIndexQueryOptions {
     snippetLength?: number;
     weights?: Partial<AiwgIndexQueryWeights>;
     includeMatches?: boolean;
+    searchProfile?: 'default' | 'aiwg-discovery';
 }
 interface AiwgIndexQueryWeights {
     title: number;
     text: number;
     tag: number;
     concept: number;
+    facet: number;
+    id: number;
+    source: number;
 }
 interface AiwgIndexQueryMatch {
-    field: 'title' | 'text' | 'tag' | 'concept';
+    field: 'title' | 'text' | 'tag' | 'concept' | 'facet' | 'id' | 'source';
     value: string;
+    score?: number;
+    reason?: string;
 }
 interface AiwgIndexQueryRankedItem {
     item: AiwgFortemiRecord;
@@ -203,6 +210,83 @@ interface AiwgIndexGraphOptions {
     relationshipWeights?: Record<string, number>;
     includeDanglingRelationships?: boolean;
 }
+type AiwgRelationshipDirection = 'in' | 'out' | 'both';
+type AiwgRelationshipSetOperation = 'intersection' | 'union' | 'difference';
+interface AiwgRelationshipTraversalOptions {
+    direction?: AiwgRelationshipDirection;
+    relationshipType?: string;
+    limit?: number;
+}
+interface AiwgRelationshipQueryOptions extends AiwgRelationshipTraversalOptions {
+    sourceId?: string;
+    targetId?: string;
+    type?: string;
+}
+interface AiwgRelationshipEdgeSummary {
+    source_id: string;
+    target_id: string;
+    type: string;
+    source_path?: string;
+}
+interface AiwgRelationshipNodeSummary {
+    id: string;
+    type: AiwgFortemiRecordType;
+    title: string;
+}
+interface AiwgRelationshipTraversalResult {
+    nodes: AiwgRelationshipNodeSummary[];
+    edges: AiwgRelationshipEdgeSummary[];
+    complete: boolean;
+    scannedParts?: number;
+    fetchedParts?: number;
+}
+interface AiwgRelationshipSetOptions extends AiwgRelationshipTraversalOptions {
+    op: AiwgRelationshipSetOperation;
+    a: string;
+    b: string;
+}
+interface AiwgRelationshipSetResult {
+    ids: string[];
+    op: AiwgRelationshipSetOperation;
+}
+interface AiwgStaticEmbeddingRecord {
+    record_id: string;
+    embedding: number[];
+    embedding_id?: string;
+    granularity?: string;
+    input_hash: string;
+    source_path?: string;
+}
+interface AiwgStaticEmbeddingSet {
+    schema_version: 'aiwg.fortemi.embedding.set.v1';
+    id: string;
+    model: string;
+    dimensions: number;
+    generated_at: string;
+    granularity: 'title-summary' | 'body' | 'chunked-body' | string;
+    metric?: 'cosine' | 'dot' | 'euclidean';
+    input_hash_algorithm?: string;
+    embeddings: AiwgStaticEmbeddingRecord[];
+}
+interface AiwgStaticSemanticQueryOptions {
+    limit?: number;
+    offset?: number;
+    minScore?: number;
+}
+interface AiwgStaticSemanticResult {
+    item: AiwgFortemiRecord;
+    score: number;
+    embedding?: AiwgStaticEmbeddingRecord;
+}
+interface AiwgStaticHybridQueryOptions extends AiwgStaticSemanticQueryOptions, AiwgIndexQueryOptions {
+    lexicalWeight?: number;
+    semanticWeight?: number;
+}
+interface AiwgStaticDuplicatePair {
+    left: AiwgFortemiRecord;
+    right: AiwgFortemiRecord;
+    score: number;
+}
 interface AiwgReviewInput {
     item_id: string;
     action: AiwgReviewAction;
@@ -229,8 +313,14 @@ interface AiwgIndexController {
     query(query?: string, options?: AiwgIndexQueryOptions): AiwgIndexQueryResult;
     queryChunked(query?: string, options?: AiwgChunkedIndexQueryOptions): Promise<AiwgChunkedIndexQueryResult>;
     getRecord(id: string): Promise<AiwgFortemiRecord>;
+    neighbors(id: string, options?: AiwgRelationshipTraversalOptions): Promise<AiwgRelationshipTraversalResult>;
+    relationshipQuery(options?: AiwgRelationshipQueryOptions): Promise<AiwgRelationshipTraversalResult>;
+    relationshipSet(options: AiwgRelationshipSetOptions): Promise<AiwgRelationshipSetResult>;
     clearChunkCache(): void;
     toCommunityGraph(options?: AiwgIndexGraphOptions): ReturnType<typeof aiwgFortemiIndexToCommunityGraph>;
+    toCommunityGraphChunked(options?: AiwgIndexGraphOptions & {
+        onProgress?: (progress: AiwgChunkedIndexProgress) => void;
+    }): Promise<ReturnType<typeof aiwgFortemiIndexToCommunityGraph>>;
     setReviewDecision(input: AiwgReviewInput): AiwgReviewDecision;
     clearReviewDecision(itemId: string): void;
     createReviewDecisionExport(generatedAt?: string): AiwgReviewDecisionExport;
@@ -268,6 +358,11 @@ interface AiwgChunkedIndexBuildResult {
 }
 declare function buildAiwgChunkedIndex(index: AiwgFortemiIndexExport, options?: AiwgChunkedIndexBuildOptions): AiwgChunkedIndexBuildResult;
 declare function queryAiwgFortemiIndex(index: AiwgFortemiIndexExport, query?: string, options?: AiwgIndexQueryOptions): AiwgIndexQueryResult;
+declare function validateAiwgStaticEmbeddingSet(value: unknown): AiwgChunkedIndexValidationResult;
+declare function assertAiwgStaticEmbeddingSet(value: unknown): AiwgStaticEmbeddingSet;
+declare function queryAiwgSemanticIndex(index: AiwgFortemiIndexExport, embeddingSet: AiwgStaticEmbeddingSet, queryEmbedding: number[], options?: AiwgStaticSemanticQueryOptions): AiwgStaticSemanticResult[];
+declare function queryAiwgHybridIndex(index: AiwgFortemiIndexExport, embeddingSet: AiwgStaticEmbeddingSet, query: string, queryEmbedding: number[], options?: AiwgStaticHybridQueryOptions): AiwgStaticSemanticResult[];
+declare function findAiwgStaticDuplicatePairs(index: AiwgFortemiIndexExport, embeddingSet: AiwgStaticEmbeddingSet, threshold?: number): AiwgStaticDuplicatePair[];
 declare function createAiwgReviewDecisionExport(source: Pick<AiwgFortemiIndexExport, 'schema_version'>, decisions: AiwgReviewDecision[], generatedAt?: string): AiwgReviewDecisionExport;
 declare function createAiwgIndexController(initialIndex?: AiwgFortemiIndexExport): AiwgIndexController;
 declare function aiwgFortemiIndexToCommunityGraph(index: AiwgFortemiIndexExport, options?: AiwgIndexGraphOptions): {
@@ -286,4 +381,4 @@ declare function aiwgFortemiIndexToCommunityGraph(index: AiwgFortemiIndexExport,
     }[];
 };
 
-export { AIWG_SCAN_REQUIRED_FIELDS, type AiwgChunkedIndexBuildOptions, type AiwgChunkedIndexBuildResult, type AiwgChunkedIndexDetailLoader, type AiwgChunkedIndexLoadOptions, type AiwgChunkedIndexLoader, type AiwgChunkedIndexProgress, type AiwgChunkedIndexProgressPhase, type AiwgChunkedIndexQueryOptions, type AiwgChunkedIndexQueryResult, type AiwgChunkedIndexValidationResult, type AiwgDetailIdEncoding, type AiwgFortemiChunkDetailRef, type AiwgFortemiChunkManifest, type AiwgFortemiChunkPart, type AiwgFortemiChunkPartRef, type AiwgFortemiIndexExport, type AiwgFortemiProjectedRecord, type AiwgFortemiProvenance, type AiwgFortemiProvenanceEvent, type AiwgFortemiRecord, type AiwgFortemiRecordSource, type AiwgFortemiRecordType, type AiwgFortemiRelationship, type AiwgFortemiSkosConcept, type AiwgFortemiSkosRelation, type AiwgFortemiSkosRelationType, type AiwgIndexController, type AiwgIndexControllerListener, type AiwgIndexControllerSnapshot, type AiwgIndexGraphOptions, type AiwgIndexQueryMatch, type AiwgIndexQueryOptions, type AiwgIndexQueryRankedItem, type AiwgIndexQueryResult, type AiwgIndexQueryWeights, type AiwgIndexValidationResult, type AiwgPrivacyClassification, type AiwgProvenanceConfidence, type AiwgReviewAction, type AiwgReviewDecision, type AiwgReviewDecisionExport, type AiwgReviewInput, aiwgDetailHrefForId, aiwgFortemiIndexToCommunityGraph, assertAiwgFortemiChunkManifest, assertAiwgFortemiChunkPart, assertAiwgFortemiIndexExport, buildAiwgChunkedIndex, createAiwgFetchChunkLoader, createAiwgFetchDetailLoader, createAiwgIndexController, createAiwgReviewDecisionExport, encodeAiwgDetailId, getAiwgFortemiFacets, queryAiwgFortemiIndex, validateAiwgFortemiChunkManifest, validateAiwgFortemiChunkPart, validateAiwgFortemiIndexExport };
+export { AIWG_SCAN_REQUIRED_FIELDS, type AiwgChunkedIndexBuildOptions, type AiwgChunkedIndexBuildResult, type AiwgChunkedIndexDetailLoader, type AiwgChunkedIndexLoadOptions, type AiwgChunkedIndexLoader, type AiwgChunkedIndexProgress, type AiwgChunkedIndexProgressPhase, type AiwgChunkedIndexQueryOptions, type AiwgChunkedIndexQueryResult, type AiwgChunkedIndexValidationResult, type AiwgDetailIdEncoding, type AiwgFortemiChunkDetailRef, type AiwgFortemiChunkManifest, type AiwgFortemiChunkPart, type AiwgFortemiChunkPartRef, type AiwgFortemiIndexExport, type AiwgFortemiKnownRecordType, type AiwgFortemiProjectedRecord, type AiwgFortemiProvenance, type AiwgFortemiProvenanceEvent, type AiwgFortemiRecord, type AiwgFortemiRecordSource, type AiwgFortemiRecordType, type AiwgFortemiRelationship, type AiwgFortemiSkosConcept, type AiwgFortemiSkosRelation, type AiwgFortemiSkosRelationType, type AiwgIndexController, type AiwgIndexControllerListener, type AiwgIndexControllerSnapshot, type AiwgIndexGraphOptions, type AiwgIndexQueryMatch, type AiwgIndexQueryOptions, type AiwgIndexQueryRankedItem, type AiwgIndexQueryResult, type AiwgIndexQueryWeights, type AiwgIndexValidationResult, type AiwgPrivacyClassification, type AiwgProvenanceConfidence, type AiwgRelationshipDirection, type AiwgRelationshipEdgeSummary, type AiwgRelationshipNodeSummary, type AiwgRelationshipQueryOptions, type AiwgRelationshipSetOperation, type AiwgRelationshipSetOptions, type AiwgRelationshipSetResult, type AiwgRelationshipTraversalOptions, type AiwgRelationshipTraversalResult, type AiwgReviewAction, type AiwgReviewDecision, type AiwgReviewDecisionExport, type AiwgReviewInput, type AiwgStaticDuplicatePair, type AiwgStaticEmbeddingRecord, type AiwgStaticEmbeddingSet, type AiwgStaticHybridQueryOptions, type AiwgStaticSemanticQueryOptions, type AiwgStaticSemanticResult, aiwgDetailHrefForId, aiwgFortemiIndexToCommunityGraph, assertAiwgFortemiChunkManifest, assertAiwgFortemiChunkPart, assertAiwgFortemiIndexExport, assertAiwgStaticEmbeddingSet, buildAiwgChunkedIndex, createAiwgFetchChunkLoader, createAiwgFetchDetailLoader, createAiwgIndexController, createAiwgReviewDecisionExport, encodeAiwgDetailId, findAiwgStaticDuplicatePairs, getAiwgFortemiFacets, queryAiwgFortemiIndex, queryAiwgHybridIndex, queryAiwgSemanticIndex, validateAiwgFortemiChunkManifest, validateAiwgFortemiChunkPart, validateAiwgFortemiIndexExport, validateAiwgStaticEmbeddingSet };

package/dist/aiwg-index.js

@@ -25,19 +25,14 @@ var REQUIRED_RECORD_FIELDS = [
   "privacy",
   "updated_at"
 ];
-var VALID_TYPES = /* @__PURE__ */ new Set([
-  "crm.contact",
-  "crm.organization",
-  "crm.event",
-  "crm.interaction",
-  "aiwg.artifact",
-  "docs.page"
-]);
 var DEFAULT_QUERY_WEIGHTS = {
   title: 4,
   tag: 3,
   concept: 2,
-  text: 1
+  text: 1,
+  facet: 2,
+  id: 1,
+  source: 0.25
 };
 function hasString(value) {
   return typeof value === "string" && value.length > 0;
@@ -138,7 +133,7 @@ function validateAiwgFortemiIndexExport(value) {
       errors.push("items must be sorted by id: " + previousId + " before " + item.id);
     }
     if (hasString(item.id)) previousId = item.id;
-    if (!VALID_TYPES.has(item.type)) errors.push("items[" + index + "].type is invalid");
+    if (!hasString(item.type)) errors.push("items[" + index + "].type must be a non-empty string");
     else counts[item.type] = (counts[item.type] ?? 0) + 1;
     if (!hasString(item.source?.path)) errors.push("items[" + index + "].source.path is required");
     if (!hasString(item.source?.repo_relative_path)) errors.push("items[" + index + "].source.repo_relative_path is required");
@@ -233,7 +228,7 @@ function validateProjectedRecords(items) {
       errors.push("items must be sorted by id: " + previousId + " before " + item.id);
     }
     if (hasString(item.id)) previousId = item.id;
-    if (!item.type || !VALID_TYPES.has(item.type)) errors.push("items[" + index + "].type is invalid");
+    if (!hasString(item.type)) errors.push("items[" + index + "].type must be a non-empty string");
     if (!hasString(item.title)) errors.push("items[" + index + "].title is required");
     if (typeof item.text !== "string") errors.push("items[" + index + "].text is required");
     if (!item.facets || typeof item.facets !== "object" || Array.isArray(item.facets)) {
@@ -398,8 +393,99 @@ function queryMatches(item, q) {
   }
   return matches;
 }
+var DISCOVERY_STOPWORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "and",
+  "are",
+  "as",
+  "for",
+  "from",
+  "how",
+  "i",
+  "in",
+  "is",
+  "me",
+  "of",
+  "on",
+  "or",
+  "please",
+  "the",
+  "to",
+  "use",
+  "with"
+]);
+function normalizeDiscoveryText(value) {
+  return value.toLowerCase().replace(/[_/]+/g, " ").replace(/[^a-z0-9.-]+/g, " ").trim();
+}
+function canonicalDiscoveryName(value) {
+  return normalizeDiscoveryText(value).replace(/[\s.-]+/g, "");
+}
+function discoveryTokens(value) {
+  return normalizeDiscoveryText(value).split(/\s+/).filter((token) => token.length > 1 && !DISCOVERY_STOPWORDS.has(token));
+}
+function facetValues(item, names) {
+  return names.flatMap((name) => item.facets[name] ?? []);
+}
+function addDiscoveryMatch(matches, match) {
+  if (!matches.some((existing) => existing.field === match.field && existing.value === match.value && existing.reason === match.reason)) {
+    matches.push(match);
+  }
+}
+function tokenOverlapScore(tokens, value) {
+  if (tokens.length === 0 || !value) return 0;
+  const normalized = normalizeDiscoveryText(value);
+  const hits = tokens.filter((token) => normalized.includes(token)).length;
+  return hits / tokens.length;
+}
+function discoveryMatches(item, query) {
+  if (!query) return [];
+  const matches = [];
+  const tokens = discoveryTokens(query);
+  const canonicalQuery = canonicalDiscoveryName(query);
+  const idParts = item.id.split(/[:/]/);
+  const names = [
+    item.id,
+    item.title,
+    ...idParts,
+    ...facetValues(item, ["name", "canonical_name", "command", "skill", "agent", "rule"])
+  ].filter(Boolean);
+  const triggers = facetValues(item, ["trigger", "triggers", "trigger_phrase", "trigger_phrases"]);
+  const capabilities = [
+    ...facetValues(item, ["capability", "capabilities", "summary", "description"]),
+    ...item.concepts,
+    ...item.tags
+  ];
+  const sourceValues = [item.source?.path, item.source?.repo_relative_path, item.source?.locator].filter(Boolean);
+  for (const name of names) {
+    const canonicalName = canonicalDiscoveryName(name);
+    if (!canonicalName) continue;
+    if (canonicalName === canonicalQuery) {
+      addDiscoveryMatch(matches, { field: "id", value: name, score: 80, reason: "exact canonical name" });
+    } else if (canonicalName.includes(canonicalQuery) || canonicalQuery.includes(canonicalName)) {
+      addDiscoveryMatch(matches, { field: "id", value: name, score: 48, reason: "near canonical name" });
+    }
+  }
+  const titleOverlap = tokenOverlapScore(tokens, item.title);
+  if (titleOverlap > 0) addDiscoveryMatch(matches, { field: "title", value: item.title, score: 18 * titleOverlap, reason: "title token overlap" });
+  for (const trigger of triggers) {
+    const overlap = tokenOverlapScore(tokens, trigger);
+    if (overlap > 0) addDiscoveryMatch(matches, { field: "facet", value: trigger, score: 34 * overlap, reason: "trigger phrase" });
+  }
+  for (const capability of capabilities) {
+    const overlap = tokenOverlapScore(tokens, capability);
+    if (overlap > 0) addDiscoveryMatch(matches, { field: "concept", value: capability, score: 22 * overlap, reason: "capability overlap" });
+  }
+  const textOverlap = tokenOverlapScore(tokens, item.text);
+  if (textOverlap > 0) addDiscoveryMatch(matches, { field: "text", value: item.text, score: 8 * textOverlap, reason: "body token overlap" });
+  for (const source of sourceValues) {
+    const overlap = tokenOverlapScore(tokens, source);
+    if (overlap > 0) addDiscoveryMatch(matches, { field: "source", value: source, score: 2 * overlap, reason: "path overlap" });
+  }
+  return matches;
+}
 function rankMatches(matches, weights) {
-  return matches.reduce((total, match) => total + weights[match.field], 0);
+  return matches.reduce((total, match) => total + (match.score ?? weights[match.field]), 0);
 }
 function clipSnippet(value, q, maxLength) {
   const normalizedLength = Math.max(20, maxLength);
@@ -423,7 +509,12 @@ function createSnippet(item, matches, q, maxLength) {
 }
 function createRankedEntries(items, q, options, ordinalBase = 0) {
   const weights = { ...DEFAULT_QUERY_WEIGHTS, ...options.weights };
-  return items.map((item, ordinal) => ({ item, ordinal: ordinalBase + ordinal, matches: queryMatches(item, q) })).filter(({ item, matches }) => {
+  const profile = options.searchProfile ?? "default";
+  return items.map((item, ordinal) => ({
+    item,
+    ordinal: ordinalBase + ordinal,
+    matches: profile === "aiwg-discovery" ? discoveryMatches(item, q) : queryMatches(item, q)
+  })).filter(({ item, matches }) => {
     if (q && matches.length === 0) return false;
     if (options.types && !options.types.includes(item.type)) return false;
     if (options.privacy && !options.privacy.includes(item.privacy.classification)) return false;
@@ -470,7 +561,106 @@ function createQueryResultFromRankedEntries(entries, query, options) {
 }
 function queryAiwgFortemiIndex(index, query = "", options = {}) {
   const q = query.trim().toLowerCase();
-  return createQueryResultFromRankedEntries(createRankedEntries(index.items, q, options), q, options);
+  const entries = createRankedEntries(index.items, q, options);
+  if (entries.length === 0 && q && options.searchProfile === "aiwg-discovery") {
+    const relaxed = discoveryTokens(q).join(" ");
+    return createQueryResultFromRankedEntries(createRankedEntries(index.items, relaxed, options), relaxed, options);
+  }
+  return createQueryResultFromRankedEntries(entries, q, options);
+}
+function cosineSimilarity(left, right) {
+  if (left.length !== right.length || left.length === 0) return 0;
+  let dot = 0;
+  let leftMag = 0;
+  let rightMag = 0;
+  for (let i = 0; i < left.length; i += 1) {
+    const l = left[i];
+    const r = right[i];
+    dot += l * r;
+    leftMag += l * l;
+    rightMag += r * r;
+  }
+  if (leftMag === 0 || rightMag === 0) return 0;
+  return dot / (Math.sqrt(leftMag) * Math.sqrt(rightMag));
+}
+function validateAiwgStaticEmbeddingSet(value) {
+  const errors = [];
+  const data = value;
+  if (data?.schema_version !== "aiwg.fortemi.embedding.set.v1") errors.push("schema_version must be aiwg.fortemi.embedding.set.v1");
+  if (!hasString(data?.id)) errors.push("id is required");
+  if (!hasString(data?.model)) errors.push("model is required");
+  if (!hasPositiveInteger(data?.dimensions)) errors.push("dimensions must be a positive integer");
+  if (!hasString(data?.generated_at)) errors.push("generated_at is required");
+  if (!hasString(data?.granularity)) errors.push("granularity is required");
+  if (!Array.isArray(data?.embeddings)) errors.push("embeddings must be an array");
+  for (const [index, embedding] of (data.embeddings ?? []).entries()) {
+    if (!hasString(embedding.record_id)) errors.push("embeddings[" + index + "].record_id is required");
+    if (!hasString(embedding.input_hash)) errors.push("embeddings[" + index + "].input_hash is required");
+    if (!Array.isArray(embedding.embedding)) errors.push("embeddings[" + index + "].embedding must be an array");
+    else if (hasPositiveInteger(data?.dimensions) && embedding.embedding.length !== data.dimensions) {
+      errors.push("embeddings[" + index + "].embedding length must match dimensions");
+    } else if (!embedding.embedding.every((number) => typeof number === "number" && Number.isFinite(number))) {
+      errors.push("embeddings[" + index + "].embedding must contain finite numbers");
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+function assertAiwgStaticEmbeddingSet(value) {
+  const result = validateAiwgStaticEmbeddingSet(value);
+  if (!result.valid) throw new Error("Invalid AIWG Fortemi embedding set:\n" + result.errors.join("\n"));
+  return value;
+}
+function queryAiwgSemanticIndex(index, embeddingSet, queryEmbedding, options = {}) {
+  assertAiwgStaticEmbeddingSet(embeddingSet);
+  if (queryEmbedding.length !== embeddingSet.dimensions) throw new Error("query embedding length must match embedding set dimensions");
+  const byId = new Map(index.items.map((item) => [item.id, item]));
+  const offset = options.offset ?? 0;
+  const limit = options.limit ?? 20;
+  return embeddingSet.embeddings.map((embedding) => {
+    const item = byId.get(embedding.record_id);
+    if (!item) return null;
+    return { item, embedding, score: cosineSimilarity(queryEmbedding, embedding.embedding) };
+  }).filter((result) => result !== null && result.score >= (options.minScore ?? -1)).sort((left, right) => right.score - left.score || left.item.id.localeCompare(right.item.id)).slice(offset, offset + limit);
+}
+function queryAiwgHybridIndex(index, embeddingSet, query, queryEmbedding, options = {}) {
+  const lexical = queryAiwgFortemiIndex(index, query, { ...options, rank: true });
+  const semantic = queryAiwgSemanticIndex(index, embeddingSet, queryEmbedding, { limit: index.items.length });
+  const lexicalWeight = options.lexicalWeight ?? 0.5;
+  const semanticWeight = options.semanticWeight ?? 0.5;
+  const lexicalScores = new Map(lexical.rankedItems?.map((entry) => [entry.item.id, entry.rank]) ?? []);
+  const maxLexical = Math.max(1, ...lexicalScores.values());
+  const embeddingById = new Map(semantic.flatMap((entry) => entry.embedding ? [[entry.item.id, entry.embedding]] : []));
+  const semanticScores = new Map(semantic.map((entry) => [entry.item.id, entry.score]));
+  const ids = /* @__PURE__ */ new Set([...lexicalScores.keys(), ...semanticScores.keys()]);
+  const offset = options.offset ?? 0;
+  const limit = options.limit ?? 20;
+  return [...ids].map((id) => {
+    const item = index.items.find((candidate) => candidate.id === id);
+    const embedding = embeddingById.get(id);
+    if (!item) return null;
+    return {
+      item,
+      ...embedding ? { embedding } : {},
+      score: (lexicalScores.get(id) ?? 0) / maxLexical * lexicalWeight + (semanticScores.get(id) ?? 0) * semanticWeight
+    };
+  }).filter((result) => result !== null && result.score >= (options.minScore ?? -1)).sort((left, right) => right.score - left.score || left.item.id.localeCompare(right.item.id)).slice(offset, offset + limit);
+}
+function findAiwgStaticDuplicatePairs(index, embeddingSet, threshold = 0.9) {
+  assertAiwgStaticEmbeddingSet(embeddingSet);
+  const byId = new Map(index.items.map((item) => [item.id, item]));
+  const pairs = [];
+  for (let leftIndex = 0; leftIndex < embeddingSet.embeddings.length; leftIndex += 1) {
+    for (let rightIndex = leftIndex + 1; rightIndex < embeddingSet.embeddings.length; rightIndex += 1) {
+      const leftEmbedding = embeddingSet.embeddings[leftIndex];
+      const rightEmbedding = embeddingSet.embeddings[rightIndex];
+      const left = byId.get(leftEmbedding.record_id);
+      const right = byId.get(rightEmbedding.record_id);
+      if (!left || !right) continue;
+      const score = cosineSimilarity(leftEmbedding.embedding, rightEmbedding.embedding);
+      if (score >= threshold) pairs.push({ left, right, score });
+    }
+  }
+  return pairs.sort((left, right) => right.score - left.score || left.left.id.localeCompare(right.left.id));
 }
 function chunkPartCacheKey(part) {
   return `${part.offset}:${part.href}`;
@@ -569,6 +759,104 @@ async function getChunkRecord(runtime, id) {
   }
   return record;
 }
+function relationshipTypeFilter(options) {
+  return options?.relationshipType ?? options?.type;
+}
+function edgeFromRelationship(sourceId, relationship) {
+  return {
+    source_id: sourceId,
+    target_id: relationship.target_id,
+    type: relationship.type,
+    ...relationship.source_path ? { source_path: relationship.source_path } : {}
+  };
+}
+function relationshipMatches(edge, options = {}) {
+  const type = relationshipTypeFilter(options);
+  const direction = options.direction ?? "both";
+  if (type && edge.type !== type) return false;
+  if (options.sourceId && edge.source_id !== options.sourceId) return false;
+  if (options.targetId && edge.target_id !== options.targetId) return false;
+  if (direction === "out" && options.targetId && edge.target_id !== options.targetId) return false;
+  if (direction === "in" && options.sourceId && edge.source_id !== options.sourceId) return false;
+  return true;
+}
+function nodeSummary(item) {
+  return { id: item.id, type: item.type, title: item.title };
+}
+function addNode(nodes, item) {
+  if (item) nodes.set(item.id, nodeSummary(item));
+}
+function relationshipResultFromRecords(records, options = {}) {
+  const byId = new Map(records.map((record) => [record.id, record]));
+  const edges = [];
+  for (const record of records) {
+    for (const relationship of record.relationships ?? []) {
+      const edge = edgeFromRelationship(record.id, relationship);
+      if (!relationshipMatches(edge, options)) continue;
+      edges.push(edge);
+    }
+  }
+  const limitedEdges = (options.limit ? edges.slice(0, options.limit) : edges).sort((left, right) => left.source_id.localeCompare(right.source_id) || left.target_id.localeCompare(right.target_id) || left.type.localeCompare(right.type));
+  const nodes = /* @__PURE__ */ new Map();
+  for (const edge of limitedEdges) {
+    addNode(nodes, byId.get(edge.source_id));
+    addNode(nodes, byId.get(edge.target_id));
+  }
+  return {
+    nodes: [...nodes.values()].sort((left, right) => left.id.localeCompare(right.id)),
+    edges: limitedEdges,
+    complete: true
+  };
+}
+function neighborQueryOptions(id, options = {}) {
+  const direction = options.direction ?? "both";
+  return {
+    ...options,
+    ...direction === "out" ? { sourceId: id } : {},
+    ...direction === "in" ? { targetId: id } : {}
+  };
+}
+function filterNeighborResult(id, result, options = {}) {
+  const direction = options.direction ?? "both";
+  const edges = result.edges.filter((edge) => {
+    if (direction === "out") return edge.source_id === id;
+    if (direction === "in") return edge.target_id === id;
+    return edge.source_id === id || edge.target_id === id;
+  });
+  const ids = /* @__PURE__ */ new Set();
+  for (const edge of edges) {
+    ids.add(edge.source_id);
+    ids.add(edge.target_id);
+  }
+  return {
+    ...result,
+    edges,
+    nodes: result.nodes.filter((node) => ids.has(node.id))
+  };
+}
+async function recordsFromChunkedRuntime(runtime, onProgress) {
+  let scannedParts = 0;
+  let fetchedParts = 0;
+  const records = [];
+  for (const partRef of runtime.manifest.parts) {
+    const loaded = await loadChunkPart(runtime, partRef);
+    if (loaded.fetched) fetchedParts += 1;
+    scannedParts += 1;
+    onProgress?.({ phase: "part", done: scannedParts, total: runtime.manifest.parts.length, href: partRef.href });
+    for (const item of loaded.part.items) {
+      records.push(item.relationships ? item : await getChunkRecord(runtime, item.id));
+    }
+  }
+  return { records, scannedParts, fetchedParts };
+}
+async function relationshipResultFromChunkedRuntime(runtime, options = {}) {
+  const loaded = await recordsFromChunkedRuntime(runtime);
+  return {
+    ...relationshipResultFromRecords(loaded.records, options),
+    scannedParts: loaded.scannedParts,
+    fetchedParts: loaded.fetchedParts
+  };
+}
 async function queryChunkedAiwgFortemiIndex(runtime, query = "", options = {}) {
   const q = query.trim().toLowerCase();
   let scannedParts = 0;
@@ -749,6 +1037,39 @@ function createAiwgIndexController(initialIndex) {
       if (!found) throw new Error("Record not found: " + id);
       return found;
     },
+    async neighbors(id, options) {
+      try {
+        const queryOptions = neighborQueryOptions(id, options);
+        const result = chunked ? await relationshipResultFromChunkedRuntime(chunked, queryOptions) : relationshipResultFromRecords(requireIndex().items, queryOptions);
+        return filterNeighborResult(id, result, options);
+      } catch (err) {
+        error = err instanceof Error ? err : new Error(String(err));
+        notify();
+        throw error;
+      }
+    },
+    async relationshipQuery(options) {
+      try {
+        return chunked ? await relationshipResultFromChunkedRuntime(chunked, options) : relationshipResultFromRecords(requireIndex().items, options);
+      } catch (err) {
+        error = err instanceof Error ? err : new Error(String(err));
+        notify();
+        throw error;
+      }
+    },
+    async relationshipSet(options) {
+      const [left, right] = await Promise.all([
+        this.neighbors(options.a, options),
+        this.neighbors(options.b, options)
+      ]);
+      const leftIds = new Set(left.nodes.map((node) => node.id).filter((id) => id !== options.a));
+      const rightIds = new Set(right.nodes.map((node) => node.id).filter((id) => id !== options.b));
+      let ids;
+      if (options.op === "intersection") ids = [...leftIds].filter((id) => rightIds.has(id));
+      else if (options.op === "difference") ids = [...leftIds].filter((id) => !rightIds.has(id));
+      else ids = [.../* @__PURE__ */ new Set([...leftIds, ...rightIds])];
+      return { op: options.op, ids: ids.sort() };
+    },
     clearChunkCache() {
       chunked?.partCache.clear();
       chunked?.detailCache.clear();
@@ -759,6 +1080,15 @@ function createAiwgIndexController(initialIndex) {
     toCommunityGraph(options) {
       return aiwgFortemiIndexToCommunityGraph(requireIndex(), options);
     },
+    async toCommunityGraphChunked(options) {
+      if (!chunked) return aiwgFortemiIndexToCommunityGraph(requireIndex(), options);
+      const loaded = await recordsFromChunkedRuntime(chunked, options?.onProgress);
+      return aiwgFortemiIndexToCommunityGraph({
+        generated_at: chunked.manifest.generated_at,
+        source: chunked.manifest.source,
+        items: loaded.records
+      }, options);
+    },
     setReviewDecision(input) {
       const decision = {
         ...input,
@@ -834,6 +1164,6 @@ function communityIdsFor(item, options) {
   return [`type:${item.type}`];
 }
 
-export { AIWG_SCAN_REQUIRED_FIELDS, aiwgDetailHrefForId, aiwgFortemiIndexToCommunityGraph, assertAiwgFortemiChunkManifest, assertAiwgFortemiChunkPart, assertAiwgFortemiIndexExport, buildAiwgChunkedIndex, createAiwgFetchChunkLoader, createAiwgFetchDetailLoader, createAiwgIndexController, createAiwgReviewDecisionExport, encodeAiwgDetailId, getAiwgFortemiFacets, queryAiwgFortemiIndex, validateAiwgFortemiChunkManifest, validateAiwgFortemiChunkPart, validateAiwgFortemiIndexExport };
+export { AIWG_SCAN_REQUIRED_FIELDS, aiwgDetailHrefForId, aiwgFortemiIndexToCommunityGraph, assertAiwgFortemiChunkManifest, assertAiwgFortemiChunkPart, assertAiwgFortemiIndexExport, assertAiwgStaticEmbeddingSet, buildAiwgChunkedIndex, createAiwgFetchChunkLoader, createAiwgFetchDetailLoader, createAiwgIndexController, createAiwgReviewDecisionExport, encodeAiwgDetailId, findAiwgStaticDuplicatePairs, getAiwgFortemiFacets, queryAiwgFortemiIndex, queryAiwgHybridIndex, queryAiwgSemanticIndex, validateAiwgFortemiChunkManifest, validateAiwgFortemiChunkPart, validateAiwgFortemiIndexExport, validateAiwgStaticEmbeddingSet };
 //# sourceMappingURL=aiwg-index.js.map
 //# sourceMappingURL=aiwg-index.js.map