@fortemi/core 2026.6.9 → 2026.7.1

package/README.md

@@ -126,10 +126,11 @@ Use this subpath for Pagenary-style command palettes, static docs search, and
 vanilla JavaScript review surfaces. The top-level `@fortemi/core` export remains
 available for full archive/runtime integrations.
 
-The record contract keeps the existing flat fields for filtering and search:
-`facets`, `tags`, `concepts`, `relationships`, and `provenance`. Static
-consumers that render metadata tabs can also read optional rich fields from full
-records:
+The AIWG index adapter accepts both `aiwg.fortemi.index.export.v1` and
+`aiwg.fortemi.index.export.v2` envelopes. The v1 record contract keeps the
+existing flat fields for filtering and search: `facets`, `tags`, `concepts`,
+`relationships`, and `provenance`. Static consumers that render metadata tabs
+can also read optional rich fields from full records:
 
 - `skos_concepts`: concept ids plus labels, definitions, schemes, notation, URIs,
   alternate labels, and metadata.
@@ -140,10 +141,14 @@ records:
 - `relationships[*].metadata`: optional relationship labels, confidence,
   privacy, and structured metadata.
 
-These fields are additive to `aiwg.fortemi.index.record.v1`. Existing consumers
-can ignore them and continue querying the flat fields. Chunked indexes with a
-projection keep rich metadata in detail records; call `getRecord(id)` before
-rendering a metadata panel.
+These fields are additive to `aiwg.fortemi.index.record.v1`. Version 2 records
+can also carry AIWG migration fields such as `search`, `chunks`, `embeddings`,
+`source.origin`, `source.generated`, `source.checksum`, `source.updated_at`,
+`privacy.locality`, and compatibility metadata. Query helpers use v2 `search`
+and `chunks` text when the old top-level `title`/`text` fields are absent.
+Existing consumers can ignore the v2 fields and continue querying the flat
+fields. Chunked indexes with a projection keep rich metadata in detail records;
+call `getRecord(id)` before rendering a metadata panel.
 
 Large static indexes can use the chunked browser path instead of downloading one
 full `aiwg.fortemi.index.export.v1` file. Host a manifest plus deterministic part
@@ -178,6 +183,62 @@ 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.agent`, `aiwg.command`, `aiwg.rule`, `aiwg.flow`, `aiwg.bundle`,
+`aiwg.kb.page`, `aiwg.memory.entry`, `aiwg.issue`, `research.ref`, and
+`aiwg.research.profile`. Validation still enforces required record fields, but
+it does not require unknown AIWG, research, KB, memory, issue, 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',
+  relationshipDirection: 'downstream',
+})
+
+const graph = await controller.toCommunityGraphChunked()
+```
+
+Relationship edges preserve v2 `source_path`, `target_path`, and
+`direction: 'upstream' | 'downstream' | 'related'` values. Use
+`direction: 'in' | 'out' | 'both'` for graph orientation around a node and
+`relationshipDirection` for AIWG dependency/citation/profile/KB direction
+semantics. 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 |
@@ -232,11 +293,11 @@ pnpm add @fortemi/react @fortemi/core react
 
 ## Documentation
 
-- [Repository API](https://github.com/Fortemi/fortemi-react/blob/main/docs/api-reference.md#repositories)
-- [Integration guide](https://github.com/Fortemi/fortemi-react/blob/main/docs/integration.md)
-- [Search guide](https://github.com/Fortemi/fortemi-react/blob/main/docs/search.md)
-- [Extending Fortemi](https://github.com/Fortemi/fortemi-react/blob/main/docs/extending.md)
-- [Supply-chain controls](https://github.com/Fortemi/fortemi-react/blob/main/docs/security/supply-chain.md)
+- [Repository API](https://github.com/Fortemi/fortemi-react/blob/main/docs/content/api-reference.md#repositories)
+- [Integration guide](https://github.com/Fortemi/fortemi-react/blob/main/docs/content/guides/integration.md)
+- [Search guide](https://github.com/Fortemi/fortemi-react/blob/main/docs/content/guides/search.md)
+- [Extending Fortemi](https://github.com/Fortemi/fortemi-react/blob/main/docs/content/advanced/extending.md)
+- [Supply-chain controls](https://github.com/Fortemi/fortemi-react/blob/main/docs/content/security/supply-chain.md)
 
 ## License
 

package/dist/aiwg-index.d.ts

@@ -1,16 +1,26 @@
-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 AiwgFortemiRecordSchemaVersion = 'aiwg.fortemi.index.record.v1' | 'aiwg.fortemi.index.record.v2';
+type AiwgFortemiIndexExportSchemaVersion = 'aiwg.fortemi.index.export.v1' | 'aiwg.fortemi.index.export.v2';
 type AiwgPrivacyClassification = 'private' | 'sanitized' | 'public';
 type AiwgProvenanceConfidence = 'source' | 'candidate' | 'reviewed' | 'rejected';
 type AiwgReviewAction = 'accept' | 'reject' | 'defer';
+type AiwgFortemiRelationshipDirection = 'upstream' | 'downstream' | 'related';
 interface AiwgFortemiRecordSource {
     path: string;
     repo_relative_path: string;
     locator: string;
+    origin?: string;
+    generated?: boolean;
+    checksum?: string;
+    updated_at?: string;
 }
 interface AiwgFortemiRelationship {
     type: string;
     target_id: string;
     source_path?: string;
+    target_path?: string;
+    direction?: AiwgFortemiRelationshipDirection;
     label?: string;
     confidence?: number;
     privacy?: AiwgPrivacyClassification;
@@ -53,18 +63,53 @@ interface AiwgFortemiProvenanceEvent {
     privacy?: AiwgPrivacyClassification;
     attributes?: Record<string, unknown>;
 }
+interface AiwgFortemiSearchProjection {
+    title?: string;
+    name?: string;
+    summary?: string;
+    body?: string;
+    triggers?: string[];
+    aliases?: string[];
+    capability?: string;
+    tags?: string[];
+    phase?: string;
+    type?: string;
+    frontmatter?: Record<string, unknown>;
+}
+interface AiwgFortemiChunk {
+    id?: string;
+    text?: string;
+    body?: string;
+    summary?: string;
+    source_path?: string;
+    metadata?: Record<string, unknown>;
+}
+interface AiwgFortemiRecordEmbedding {
+    id?: string;
+    embedding?: number[];
+    vector?: number[];
+    model?: string;
+    granularity?: string;
+    input_hash?: string;
+    source_path?: string;
+    metadata?: Record<string, unknown>;
+}
 interface AiwgFortemiRecord {
-    schema_version: 'aiwg.fortemi.index.record.v1';
+    schema_version: AiwgFortemiRecordSchemaVersion;
     id: string;
     type: AiwgFortemiRecordType;
     source: AiwgFortemiRecordSource;
-    title: string;
-    text: string;
+    title?: string;
+    text?: string;
     facets: Record<string, string[]>;
     tags: string[];
     concepts: string[];
     relationships: AiwgFortemiRelationship[];
     provenance: AiwgFortemiProvenance[];
+    search?: AiwgFortemiSearchProjection;
+    chunks?: AiwgFortemiChunk[];
+    embeddings?: AiwgFortemiRecordEmbedding[];
+    compatibility?: Record<string, unknown>;
     /** Optional rich SKOS metadata for static consumers that need labels/definitions without opening a shard. */
     skos_concepts?: AiwgFortemiSkosConcept[];
     /** Optional SKOS relationship edges among concepts referenced by this record. */
@@ -74,17 +119,23 @@ interface AiwgFortemiRecord {
     privacy: {
         classification: AiwgPrivacyClassification;
         pii: boolean;
+        locality?: string;
     };
     updated_at: string;
 }
 interface AiwgFortemiIndexExport {
-    schema_version: 'aiwg.fortemi.index.export.v1';
+    schema_version: AiwgFortemiIndexExportSchemaVersion;
     generated_at: string;
     source: {
         repo: string;
         privacy: AiwgPrivacyClassification;
+        origin?: string;
+        generated?: boolean;
+        checksum?: string;
+        updated_at?: string;
     };
     items: AiwgFortemiRecord[];
+    compatibility?: Record<string, unknown>;
 }
 interface AiwgFortemiChunkPartRef {
     href: string;
@@ -118,7 +169,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 +189,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 +260,86 @@ interface AiwgIndexGraphOptions {
     relationshipWeights?: Record<string, number>;
     includeDanglingRelationships?: boolean;
 }
+type AiwgRelationshipDirection = 'in' | 'out' | 'both';
+type AiwgRelationshipSetOperation = 'intersection' | 'union' | 'difference';
+interface AiwgRelationshipTraversalOptions {
+    direction?: AiwgRelationshipDirection;
+    relationshipType?: string;
+    relationshipDirection?: AiwgFortemiRelationshipDirection;
+    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;
+    target_path?: string;
+    direction?: AiwgFortemiRelationshipDirection;
+}
+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 +366,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 +411,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 +434,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 AiwgFortemiChunk, type AiwgFortemiChunkDetailRef, type AiwgFortemiChunkManifest, type AiwgFortemiChunkPart, type AiwgFortemiChunkPartRef, type AiwgFortemiIndexExport, type AiwgFortemiIndexExportSchemaVersion, type AiwgFortemiKnownRecordType, type AiwgFortemiProjectedRecord, type AiwgFortemiProvenance, type AiwgFortemiProvenanceEvent, type AiwgFortemiRecord, type AiwgFortemiRecordEmbedding, type AiwgFortemiRecordSchemaVersion, type AiwgFortemiRecordSource, type AiwgFortemiRecordType, type AiwgFortemiRelationship, type AiwgFortemiRelationshipDirection, type AiwgFortemiSearchProjection, 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 };