@fortemi/core 2026.6.1 → 2026.6.3

package/README.md

@@ -15,6 +15,7 @@ pnpm add @fortemi/core
 [![License: AGPL-3.0-only](https://img.shields.io/badge/License-AGPL--3.0--only-blue.svg?style=flat-square)](https://github.com/Fortemi/fortemi-react/blob/main/LICENSE)
 [![Node Version](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen?style=flat-square&logo=node.js)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org)
+[![Built with aiwg](https://img.shields.io/npm/v/aiwg?label=built%20with%20aiwg&color=CB3837&logo=npm&style=flat-square)](https://www.npmjs.com/package/aiwg)
 
 [**Install**](#installation) · [**Why Fortemi**](#why-fortemi-core) · [**Quick Start**](#quick-start) · [**Surface**](#what-you-get) · [**Tools**](#tool-surface) · [**Docs**](#documentation) · [**License**](#license)
 
@@ -102,6 +103,62 @@ const results = await search.search('hello')
 await registerServiceWorker()
 ```
 
+## Static AIWG Index Search
+
+Static documentation hosts can import the AIWG index helpers without pulling in
+PGlite, workers, shards, or browser storage:
+
+```ts
+import { createAiwgIndexController } from '@fortemi/core/aiwg-index'
+
+const controller = createAiwgIndexController()
+controller.loadIndex(await fetch('/aiwg-index.json').then((res) => res.json()))
+
+const results = controller.query('deployment', {
+  types: ['docs.page'],
+  rank: true,
+  snippets: true,
+  limit: 10,
+})
+```
+
+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.
+
+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
+files:
+
+```text
+/search/aiwg-index/manifest.json
+/search/aiwg-index/part-0000.json
+/search/aiwg-index/part-0001.json
+```
+
+```ts
+import {
+  createAiwgFetchChunkLoader,
+  createAiwgIndexController,
+} from '@fortemi/core/aiwg-index'
+
+const controller = createAiwgIndexController()
+const manifest = await fetch('/search/aiwg-index/manifest.json').then((res) => res.json())
+
+controller.loadChunkedIndex(
+  manifest,
+  createAiwgFetchChunkLoader('/search/aiwg-index/'),
+  { maxCachedParts: 3 },
+)
+
+const page = await controller.queryChunked('', { offset: 100, limit: 25 })
+```
+
+Unfiltered browse requests fetch only the part files intersecting the requested
+`offset` and `limit`. Filtered or ranked searches scan part files to compute exact
+results, but the controller keeps only a bounded part cache and never sets a
+materialized full export in `getIndex()`.
+
 ## What You Get
 
 | Surface | Description |

package/dist/aiwg-index.d.ts

@@ -0,0 +1,242 @@
+type AiwgFortemiRecordType = 'crm.contact' | 'crm.organization' | 'crm.event' | 'crm.interaction' | 'aiwg.artifact' | 'docs.page';
+type AiwgPrivacyClassification = 'private' | 'sanitized' | 'public';
+type AiwgProvenanceConfidence = 'source' | 'candidate' | 'reviewed' | 'rejected';
+type AiwgReviewAction = 'accept' | 'reject' | 'defer';
+interface AiwgFortemiRecordSource {
+    path: string;
+    repo_relative_path: string;
+    locator: string;
+}
+interface AiwgFortemiRelationship {
+    type: string;
+    target_id: string;
+    source_path?: string;
+}
+interface AiwgFortemiProvenance {
+    field: string;
+    source: string;
+    path: string;
+    confidence: AiwgProvenanceConfidence;
+    privacy: AiwgPrivacyClassification;
+}
+interface AiwgFortemiRecord {
+    schema_version: 'aiwg.fortemi.index.record.v1';
+    id: string;
+    type: AiwgFortemiRecordType;
+    source: AiwgFortemiRecordSource;
+    title: string;
+    text: string;
+    facets: Record<string, string[]>;
+    tags: string[];
+    concepts: string[];
+    relationships: AiwgFortemiRelationship[];
+    provenance: AiwgFortemiProvenance[];
+    privacy: {
+        classification: AiwgPrivacyClassification;
+        pii: boolean;
+    };
+    updated_at: string;
+}
+interface AiwgFortemiIndexExport {
+    schema_version: 'aiwg.fortemi.index.export.v1';
+    generated_at: string;
+    source: {
+        repo: string;
+        privacy: AiwgPrivacyClassification;
+    };
+    items: AiwgFortemiRecord[];
+}
+interface AiwgFortemiChunkPartRef {
+    href: string;
+    offset: number;
+    count: number;
+}
+declare const AIWG_SCAN_REQUIRED_FIELDS: Array<keyof AiwgFortemiRecord>;
+type AiwgFortemiProjectedRecord = Pick<AiwgFortemiRecord, 'schema_version' | 'id' | 'type' | 'title' | 'text' | 'facets' | 'tags' | 'concepts' | 'privacy'> & Partial<AiwgFortemiRecord>;
+interface AiwgFortemiChunkDetailRef {
+    href: string;
+}
+interface AiwgFortemiChunkManifest {
+    schema_version: 'aiwg.fortemi.index.chunk-manifest.v1';
+    generated_at: string;
+    source: AiwgFortemiIndexExport['source'];
+    total: number;
+    part_size: number;
+    facets?: Record<string, Record<string, number>>;
+    projection?: Array<keyof AiwgFortemiRecord>;
+    detail?: AiwgFortemiChunkDetailRef;
+    parts: AiwgFortemiChunkPartRef[];
+}
+interface AiwgFortemiChunkPart {
+    schema_version: 'aiwg.fortemi.index.chunk.v1';
+    manifest_schema_version: 'aiwg.fortemi.index.chunk-manifest.v1';
+    offset: number;
+    items: AiwgFortemiRecord[];
+}
+interface AiwgIndexValidationResult {
+    valid: boolean;
+    errors: string[];
+    counts: Partial<Record<AiwgFortemiRecordType, number>>;
+}
+interface AiwgChunkedIndexValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+interface AiwgIndexQueryOptions {
+    types?: AiwgFortemiRecordType[];
+    facets?: Record<string, string[]>;
+    tags?: string[];
+    concepts?: string[];
+    privacy?: AiwgPrivacyClassification[];
+    relationshipTargetId?: string;
+    limit?: number;
+    offset?: number;
+    rank?: boolean;
+    snippets?: boolean;
+    snippetLength?: number;
+    weights?: Partial<AiwgIndexQueryWeights>;
+    includeMatches?: boolean;
+}
+interface AiwgIndexQueryWeights {
+    title: number;
+    text: number;
+    tag: number;
+    concept: number;
+}
+interface AiwgIndexQueryMatch {
+    field: 'title' | 'text' | 'tag' | 'concept';
+    value: string;
+}
+interface AiwgIndexQueryRankedItem {
+    item: AiwgFortemiRecord;
+    rank: number;
+    snippet?: string;
+    matches?: AiwgIndexQueryMatch[];
+}
+interface AiwgIndexQueryResult {
+    items: AiwgFortemiRecord[];
+    total: number;
+    facets: Record<string, Record<string, number>>;
+    rankedItems?: AiwgIndexQueryRankedItem[];
+}
+type AiwgChunkedIndexLoader = (part: AiwgFortemiChunkPartRef, manifest: AiwgFortemiChunkManifest) => Promise<unknown>;
+type AiwgChunkedIndexDetailLoader = (id: string, manifest: AiwgFortemiChunkManifest) => Promise<unknown>;
+interface AiwgChunkedIndexLoadOptions {
+    maxCachedParts?: number;
+    detailLoader?: AiwgChunkedIndexDetailLoader;
+    maxCachedDetails?: number;
+}
+type AiwgChunkedIndexProgressPhase = 'part' | 'query';
+interface AiwgChunkedIndexProgress {
+    phase: AiwgChunkedIndexProgressPhase;
+    done: number;
+    total: number;
+    href?: string;
+}
+interface AiwgChunkedIndexQueryOptions extends AiwgIndexQueryOptions {
+    onProgress?: (progress: AiwgChunkedIndexProgress) => void;
+}
+interface AiwgChunkedIndexQueryResult extends AiwgIndexQueryResult {
+    manifestTotal: number;
+    scannedParts: number;
+    fetchedParts: number;
+    complete: boolean;
+}
+interface AiwgReviewDecision {
+    item_id: string;
+    action: AiwgReviewAction;
+    reason?: string;
+    updated_at: string;
+}
+interface AiwgReviewDecisionExport {
+    schema_version: 'aiwg.fortemi.review-decisions.v1';
+    generated_at: string;
+    source_export_schema_version: string;
+    decisions: AiwgReviewDecision[];
+}
+interface AiwgIndexGraphOptions {
+    communityFacet?: string;
+    communityTagPrefix?: string;
+    relationshipWeights?: Record<string, number>;
+    includeDanglingRelationships?: boolean;
+}
+interface AiwgReviewInput {
+    item_id: string;
+    action: AiwgReviewAction;
+    reason?: string;
+}
+interface AiwgIndexControllerSnapshot {
+    index: AiwgFortemiIndexExport | null;
+    chunked: {
+        manifest: AiwgFortemiChunkManifest;
+        cachedParts: number;
+        maxCachedParts: number;
+    } | null;
+    data: AiwgIndexQueryResult | null;
+    error: Error | null;
+    reviewDecisions: AiwgReviewDecision[];
+}
+type AiwgIndexControllerListener = (snapshot: AiwgIndexControllerSnapshot) => void;
+interface AiwgIndexController {
+    loadIndex(value: unknown): AiwgFortemiIndexExport;
+    loadChunkedIndex(manifest: unknown, loader: AiwgChunkedIndexLoader, options?: AiwgChunkedIndexLoadOptions): AiwgFortemiChunkManifest;
+    getIndex(): AiwgFortemiIndexExport | null;
+    getChunkedManifest(): AiwgFortemiChunkManifest | null;
+    getSnapshot(): AiwgIndexControllerSnapshot;
+    query(query?: string, options?: AiwgIndexQueryOptions): AiwgIndexQueryResult;
+    queryChunked(query?: string, options?: AiwgChunkedIndexQueryOptions): Promise<AiwgChunkedIndexQueryResult>;
+    getRecord(id: string): Promise<AiwgFortemiRecord>;
+    clearChunkCache(): void;
+    toCommunityGraph(options?: AiwgIndexGraphOptions): ReturnType<typeof aiwgFortemiIndexToCommunityGraph>;
+    setReviewDecision(input: AiwgReviewInput): AiwgReviewDecision;
+    clearReviewDecision(itemId: string): void;
+    createReviewDecisionExport(generatedAt?: string): AiwgReviewDecisionExport;
+    subscribe(listener: AiwgIndexControllerListener): () => void;
+}
+declare function validateAiwgFortemiIndexExport(value: unknown): AiwgIndexValidationResult;
+declare function assertAiwgFortemiIndexExport(value: unknown): AiwgFortemiIndexExport;
+declare function validateAiwgFortemiChunkManifest(value: unknown): AiwgChunkedIndexValidationResult;
+declare function assertAiwgFortemiChunkManifest(value: unknown): AiwgFortemiChunkManifest;
+declare function validateAiwgFortemiChunkPart(value: unknown, partRef?: AiwgFortemiChunkPartRef, manifest?: AiwgFortemiChunkManifest): AiwgChunkedIndexValidationResult;
+declare function assertAiwgFortemiChunkPart(value: unknown, partRef?: AiwgFortemiChunkPartRef, manifest?: AiwgFortemiChunkManifest): AiwgFortemiChunkPart;
+declare function createAiwgFetchChunkLoader(baseUrl?: string | URL): AiwgChunkedIndexLoader;
+declare function createAiwgFetchDetailLoader(baseUrl?: string | URL): AiwgChunkedIndexDetailLoader;
+declare function getAiwgFortemiFacets(items: AiwgFortemiRecord[]): Record<string, Record<string, number>>;
+interface AiwgChunkedIndexBuildOptions {
+    partSize?: number;
+    projection?: Array<keyof AiwgFortemiRecord>;
+    detailHref?: string;
+    generatedAt?: string;
+}
+interface AiwgChunkedIndexBuildResult {
+    manifest: AiwgFortemiChunkManifest;
+    parts: Array<{
+        href: string;
+        part: AiwgFortemiChunkPart;
+    }>;
+    details: Array<{
+        id: string;
+        record: AiwgFortemiRecord;
+    }>;
+}
+declare function buildAiwgChunkedIndex(index: AiwgFortemiIndexExport, options?: AiwgChunkedIndexBuildOptions): AiwgChunkedIndexBuildResult;
+declare function queryAiwgFortemiIndex(index: AiwgFortemiIndexExport, query?: string, options?: AiwgIndexQueryOptions): AiwgIndexQueryResult;
+declare function createAiwgReviewDecisionExport(source: AiwgFortemiIndexExport, decisions: AiwgReviewDecision[], generatedAt?: string): AiwgReviewDecisionExport;
+declare function createAiwgIndexController(initialIndex?: AiwgFortemiIndexExport): AiwgIndexController;
+declare function aiwgFortemiIndexToCommunityGraph(index: AiwgFortemiIndexExport, options?: AiwgIndexGraphOptions): {
+    nodes: {
+        id: string;
+    }[];
+    edges: {
+        source: string;
+        target: string;
+        kind: string;
+        weight: number;
+    }[];
+    communities: {
+        id: string;
+        nodes: string[];
+    }[];
+};
+
+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 AiwgFortemiChunkDetailRef, type AiwgFortemiChunkManifest, type AiwgFortemiChunkPart, type AiwgFortemiChunkPartRef, type AiwgFortemiIndexExport, type AiwgFortemiProjectedRecord, type AiwgFortemiProvenance, type AiwgFortemiRecord, type AiwgFortemiRecordSource, type AiwgFortemiRecordType, type AiwgFortemiRelationship, 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, aiwgFortemiIndexToCommunityGraph, assertAiwgFortemiChunkManifest, assertAiwgFortemiChunkPart, assertAiwgFortemiIndexExport, buildAiwgChunkedIndex, createAiwgFetchChunkLoader, createAiwgFetchDetailLoader, createAiwgIndexController, createAiwgReviewDecisionExport, getAiwgFortemiFacets, queryAiwgFortemiIndex, validateAiwgFortemiChunkManifest, validateAiwgFortemiChunkPart, validateAiwgFortemiIndexExport };