@fortemi/core 2026.7.0 → 2026.7.2

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
@@ -179,9 +184,11 @@ 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`.
+`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:
@@ -203,29 +210,48 @@ Chunked indexes also support graph navigation without loading a full export:
 const neighbors = await controller.neighbors('aiwg:requirement:search', {
   direction: 'both',
   relationshipType: 'cites',
+  relationshipDirection: 'downstream',
 })
 
 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.
+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'
+import { buildAiwgStaticEmbeddingSet, 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)
+
+// Node/CLI generation path. Supply any Node-safe model backend; @fortemi/core
+// only writes the shared embedding-set graph format and does not require DOM or WebGL.
+const cliEmbeddingSet = await buildAiwgStaticEmbeddingSet(index, {
+  id: 'aiwg-cli-embeddings',
+  backend: {
+    model: 'local-node-embedder',
+    dimensions: 384,
+    embed: async (input) => nodeEmbed(input),
+  },
+})
 ```
 
 `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.
+not add a model runtime dependency for static AIWG search. The builder uses the
+same record text projection as static search, including attachment
+`extracted_text`, and records only attachment metadata references, never raw blob
+bytes.
 
 ## What You Get
 
@@ -281,11 +307,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,17 +1,26 @@
 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;
@@ -54,18 +63,65 @@ 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 AiwgFortemiAttachmentReference {
+    id: string;
+    path: string;
+    mime: string | null;
+    checksum: string;
+    bytes: number;
+}
+interface AiwgFortemiBinarySource {
+    extracted_text: string;
+    attachment: AiwgFortemiAttachmentReference;
+}
 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[];
+    binary_sources?: AiwgFortemiBinarySource[];
+    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. */
@@ -75,17 +131,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;
@@ -215,6 +277,7 @@ type AiwgRelationshipSetOperation = 'intersection' | 'union' | 'difference';
 interface AiwgRelationshipTraversalOptions {
     direction?: AiwgRelationshipDirection;
     relationshipType?: string;
+    relationshipDirection?: AiwgFortemiRelationshipDirection;
     limit?: number;
 }
 interface AiwgRelationshipQueryOptions extends AiwgRelationshipTraversalOptions {
@@ -227,6 +290,8 @@ interface AiwgRelationshipEdgeSummary {
     target_id: string;
     type: string;
     source_path?: string;
+    target_path?: string;
+    direction?: AiwgFortemiRelationshipDirection;
 }
 interface AiwgRelationshipNodeSummary {
     id: string;
@@ -268,6 +333,20 @@ interface AiwgStaticEmbeddingSet {
     input_hash_algorithm?: string;
     embeddings: AiwgStaticEmbeddingRecord[];
 }
+interface AiwgHeadlessEmbeddingBackend {
+    model: string;
+    dimensions: number;
+    embed(input: string, record: AiwgFortemiRecord): number[] | Promise<number[]>;
+}
+interface BuildAiwgStaticEmbeddingSetOptions {
+    id: string;
+    backend: AiwgHeadlessEmbeddingBackend;
+    records?: AiwgFortemiRecord[];
+    generatedAt?: string | Date;
+    granularity?: AiwgStaticEmbeddingSet['granularity'];
+    metric?: AiwgStaticEmbeddingSet['metric'];
+    textForRecord?: (record: AiwgFortemiRecord) => string;
+}
 interface AiwgStaticSemanticQueryOptions {
     limit?: number;
     offset?: number;
@@ -337,6 +416,7 @@ declare function encodeAiwgDetailId(id: string, encoding?: AiwgDetailIdEncoding)
 declare function aiwgDetailHrefForId(detail: AiwgFortemiChunkDetailRef, id: string): string;
 declare function createAiwgFetchDetailLoader(baseUrl?: string | URL): AiwgChunkedIndexDetailLoader;
 declare function getAiwgFortemiFacets(items: AiwgFortemiRecord[]): Record<string, Record<string, number>>;
+declare function buildAiwgStaticEmbeddingSet(index: AiwgFortemiIndexExport, options: BuildAiwgStaticEmbeddingSetOptions): Promise<AiwgStaticEmbeddingSet>;
 interface AiwgChunkedIndexBuildOptions {
     partSize?: number;
     projection?: Array<keyof AiwgFortemiRecord>;
@@ -381,4 +461,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 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 };
+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 AiwgFortemiAttachmentReference, type AiwgFortemiBinarySource, 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 AiwgHeadlessEmbeddingBackend, 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, type BuildAiwgStaticEmbeddingSetOptions, aiwgDetailHrefForId, aiwgFortemiIndexToCommunityGraph, assertAiwgFortemiChunkManifest, assertAiwgFortemiChunkPart, assertAiwgFortemiIndexExport, assertAiwgStaticEmbeddingSet, buildAiwgChunkedIndex, buildAiwgStaticEmbeddingSet, createAiwgFetchChunkLoader, createAiwgFetchDetailLoader, createAiwgIndexController, createAiwgReviewDecisionExport, encodeAiwgDetailId, findAiwgStaticDuplicatePairs, getAiwgFortemiFacets, queryAiwgFortemiIndex, queryAiwgHybridIndex, queryAiwgSemanticIndex, validateAiwgFortemiChunkManifest, validateAiwgFortemiChunkPart, validateAiwgFortemiIndexExport, validateAiwgStaticEmbeddingSet };