open-brainy/src/index.ts
David Snelling 48802ba385 feat(contract): declare contract 1, serve three operators, refuse four by name
Open Brainy's side of the API contract the accelerated engine published.

DECLARED: package.json carries "brainyContract": 1 and the engine states its
own via contractVersion() / BRAINY_CONTRACT_VERSION — two engines compare an
integer instead of probing prototypes, and a tool reads the package field
without importing the engine. Pinned so the two can never drift apart.

SERVED: hasAll, noneOf and excludes now work on the index path. The defect
underneath was worse than the reported divergence — the metadata index's
operator switch had NO DEFAULT CASE, so any operator without a case left the
field's match set at its initial [] and find() returned an empty page.
Documented, validator-accepted, matcher-implemented operators answering
silently wrong. hasAll intersects each element's posting set (an empty operand
is vacuously true of every row that has the field), noneOf complements their
union, excludes complements contains.

REFUSED BY NAME: startsWith, endsWith, matches and length raise
INVALID_QUERY naming the operator, the field and the reason. An equality/range
posting index cannot evaluate a substring, a pattern or an array length without
reading every row — which is the cost this path exists to avoid — so it refuses
rather than answering an empty page. Both engines now agree on all 25 tokens
and contract 1 has no remaining operator divergence. This is a visible change
for a consumer calling those four through find({ where }): an empty page
becomes a typed refusal.

EMITTED: scripts/emit-contract-manifest.mjs generates docs/api-contract.json
from the BUILT surface — prototype doors, exported error classes, the operator
sets read out of their single definitions, the field-addressing vocabulary, the
health verdicts. Nothing hand-maintained, so a diff between two manifests is a
diff between two engines. `--check` fails on a stale manifest, which makes the
announce-every-addition duty mechanical rather than remembered.

RATIFIED in docs/contract-1-ratification.md: the 41-of-57 required split with
the promise spelled out (a refusal is part of a door; deprecation is not
removal), the serving-withholding list confirmed exhaustive and identical, the
minor/major rule adopted with the announcement duty, the 30 storage seam
methods committed as supported surface until Stage 2, and a finding filed
against the spec — is / isNot / greaterEqual / lessEqual are listed there as
served aliases and have never existed in this engine, which throws
INVALID_QUERY on all four.
2026-08-28 10:57:43 -07:00

652 lines
17 KiB
TypeScript

/**
* Brainy 8.0 - Your AI-Powered Second Brain
* 🧠⚛️ A multi-dimensional database with vector, graph, and relational storage
*
* Core Components:
* - Brainy: The unified database with Triple Intelligence
* - Triple Intelligence: Seamless fusion of vector + graph + field search
* - Db: Immutable, generation-pinned database values (now/transact/asOf/with)
* - Plugins: Extensible plugin system (cor, storage adapters)
* - Neural Import: AI-powered entity extraction & smart data import
*/
// Export main Brainy class
import { Brainy } from './brainy.js'
export { Brainy }
// The in-process change feed (brain.onChange) — event + listener types.
export type {
BrainyChangeEvent,
ChangeEventEntity,
ChangeEventRelation,
ChangeListener
} from './events/changeFeed.js'
// Temporal VFS — a file version entry (vfs.history / readFile({ asOf })).
export type { FileVersion } from './vfs/types.js'
// Export diagnostics result type
export type { DiagnosticsResult } from './brainy.js'
// brain.warm() — eager index/storage readiness report (per-surface honest
// outcome + timing). See the WarmReport JSDoc in brainy.ts.
export type { WarmReport, WarmOutcome } from './brainy.js'
// brain.maintenanceDebt() — per-surface passthrough of each active
// provider's self-reported background maintenance debt. See the
// MaintenanceDebtReport JSDoc in brainy.ts and ProviderMaintenanceDebt in
// plugin.ts for the measure-only-what-you-track contract.
export type { MaintenanceDebtReport, MaintenanceDebtOutcome } from './brainy.js'
export type {
GraphAuditReport,
GraphAuditDiscrepancy
} from './graph/graphAudit.js'
export {
checkOsLimits,
NOFILE_POOL_FLOOR,
MAX_MAP_COUNT_POOL_FLOOR
} from './utils/osLimits.js'
export type { OsLimitsReport } from './utils/osLimits.js'
// Export Brainy configuration and types
export type {
BrainyConfig,
Entity,
Relation,
Result,
AddParams,
UpdateParams,
RelateParams,
UpdateRelationParams,
FindParams,
SimilarParams,
GetOptions,
RelatedParams,
AddManyParams,
UpdateManyParams,
RemoveManyParams,
RelateManyParams,
BatchResult,
SubtypeRegistry,
FillSubtypeRule,
FillSubtypeRules,
FillSubtypesResult,
AggregateDefinition,
AggregateMetricDef,
AggregateSource,
AggregateQueryParams,
AggregateResult,
AggregateGroupState,
MetricState,
AggregationOp,
TimeWindowGranularity,
GroupByDimension,
AggregationProvider,
RepairReport,
RepairFamilyReport,
} from './types/brainy.types.js'
// Read-barrier contract (waitForIndexed): the leg names, the options, and
// the typed timeout error (a value export — consumers catch it by instanceof)
export type {
IndexedProjectionPath,
WaitForIndexedOptions
} from './types/brainy.types.js'
export { WaitForIndexedTimeoutError } from './types/brainy.types.js'
// Reserved-field contract — the canonical list of Brainy-owned field names
// that may never appear inside a `metadata` bag (see docs/concepts/consistency-model.md)
export {
RESERVED_ENTITY_FIELDS,
RESERVED_RELATION_FIELDS,
splitNounMetadataRecord,
splitVerbMetadataRecord,
buildNounMetadataRecord,
buildVerbMetadataRecord,
isNestedBagRecord,
METADATA_RECORD_FORMAT_KEY,
NESTED_BAG_FORMAT
} from './types/reservedFields.js'
export type {
ReservedEntityField,
ReservedRelationField,
EntityMetadataInput,
EntityMetadataPatch,
RelationMetadataInput,
RelationMetadataPatch,
NoReservedEntityKeys,
NoReservedRelationKeys,
SplitMetadataRecord
} from './types/reservedFields.js'
// Export Aggregation Engine
export { AggregationIndex, AggregateMaterializer, bucketTimestamp, parseBucketRange } from './aggregation/index.js'
// THE ONE FIELD-ADDRESSING LAW (sealed 2026-08-03) — the arming surface both
// engines' conformance suites detect: bare names = user metadata, system.* =
// the ten ruled scalars, plumbing invisible, refusals typed with the fix in
// the message. See docs/concepts/field-addressing.md.
export {
FIELD_ADDRESSING_CAPABILITY,
SYSTEM_ENTITY_SCALARS,
SYSTEM_RELATION_SCALARS,
PLUMBING_FIELDS,
parseFieldAddress,
readEntityFieldAddress,
readRelationFieldAddress,
buildUnresolvableMessage,
InvalidFieldAddressError,
UnresolvableFieldError,
UnsupportedFindOptionError
} from './db/fieldAddressing.js'
export type { FieldAddress, FieldAddressKind } from './db/fieldAddressing.js'
// Export Neural Import (AI data understanding)
export { NeuralImport } from './neural/neuralImport.js'
export type {
NeuralAnalysisResult,
DetectedEntity,
DetectedRelationship,
NeuralInsight,
NeuralImportOptions
} from './neural/neuralImport.js'
// Export Neural Entity Extraction
export { NeuralEntityExtractor } from './neural/entityExtractor.js'
export { SmartExtractor } from './neural/SmartExtractor.js'
export { SmartRelationshipExtractor } from './neural/SmartRelationshipExtractor.js'
export type {
ExtractedEntity
} from './neural/entityExtractor.js'
export type {
ExtractionResult,
SmartExtractorOptions,
FormatContext
} from './neural/SmartExtractor.js'
export type {
RelationshipExtractionResult,
SmartRelationshipExtractorOptions
} from './neural/SmartRelationshipExtractor.js'
// Export distance functions for convenience
import {
euclideanDistance,
cosineDistance,
manhattanDistance,
dotProductDistance
} from './utils/index.js'
export {
euclideanDistance,
cosineDistance,
manhattanDistance,
dotProductDistance
}
// Export version utilities
export { getBrainyVersion } from './utils/version.js'
export { contractVersion, BRAINY_CONTRACT_VERSION } from './utils/version.js'
// Export plugin system
export type { BrainyPlugin, BrainyPluginContext, StorageAdapterFactory } from './plugin.js'
export { PluginRegistry } from './plugin.js'
// Export migration system
export { MigrationRunner, MIGRATIONS } from './migration/index.js'
export type { Migration, MigrationState, MigrationPreview, MigrationResult, MigrateOptions, MigrationError } from './migration/index.js'
// Export optimistic-concurrency types (7.31.0)
export { RevisionConflictError } from './transaction/RevisionConflictError.js'
// Named not-found errors — thrown by update/relate/updateRelation/similar/
// transact/with() when a referenced entity or relation does not exist.
export { EntityNotFoundError, RelationNotFoundError } from './errors/notFound.js'
// Base error + typed migration-lock error — thrown by any data-plane call while a
// brain runs its one-time 7.x→8.0 upgrade; catch to answer HTTP 503 + Retry-After.
export { BrainyError, MigrationInProgressError, GraphIndexNotReadyError, MetadataIndexNotReadyError, VectorIndexNotReadyError, ProtectedArtifactError, DerivedArtifactMissingError } from './errors/brainyError.js'
export type { BrainyErrorType } from './errors/brainyError.js'
// ============= 8.0 Db API — generational MVCC =============
// Immutable database values: brain.now() / brain.transact() / brain.asOf() /
// db.with() / db.persist() / Brainy.load(). See src/db/ for the record layer.
export { Db } from './db/db.js'
// Portable graph export/import — db.export() / brain.export() / brain.import()
// (PortableGraph v1; identical wire format to the 7.x line).
export { isPortableGraph, validatePortableGraph } from './db/portableGraph.js'
export type {
PortableGraph,
PortableGraphEntity,
PortableGraphRelation,
ExportSelector,
ExportOptions,
ExportIndexDrift,
ImportOptions,
ImportResult,
PortableGraphValidation
} from './db/portableGraph.js'
export {
GenerationConflictError,
SpeculativeOverlayError,
GenerationCompactedError,
StoreInconsistentError,
PendingFlushDurabilityError,
CanonicalEnumerationUnavailableError
} from './db/errors.js'
export type { UnreconciledRecord } from './db/errors.js'
export type {
TxOperation,
TxAddOperation,
TxUpdateOperation,
TxRemoveOperation,
TxRelateOperation,
TxUnrelateOperation,
TransactOptions,
TransactReceipt,
TxLogEntry,
CompactHistoryOptions,
CompactHistoryResult,
HistoryStats,
ChangedIds,
DiffResult,
HistoryVersion,
EntityHistory
} from './db/types.js'
// The generation fact log — sequential after-image scan surface
// (brain.scanFacts / brain.factSegmentPaths) for index heals and replays.
export type {
CommitFact,
FactOp,
FactScanBatch,
SCANFACTS_FIRST_BATCH_MS,
FactScanHandle
} from './db/factLog.js'
// The generalized family stamp — which source generation a projection
// reflects + the surface that verifies it whole; one verifier, both member
// modes (enumerated byte-exact / rollup invariants).
export { readFamilyStamp, verifyFamilyStamp, ENTITY_TREE_STAMP_PATH } from './db/familyStamp.js'
export type { FamilyStamp, StampMembers, StampVerdict } from './db/familyStamp.js'
// Optional provider capability for generation-aware native indexes
export { isVersionedIndexProvider } from './plugin.js'
export type { VersionedIndexProvider } from './plugin.js'
export type { ProviderInvariantReport, InvariantResult, InvariantHeal } from './plugin.js'
// The named, synchronous, O(1) health-report contract (the read gate's ONLY
// source of truth for "can I serve right now") — see HealthReport's
// derivation laws in plugin.ts.
export type { HealthReport, LedgerInvariantResult, InvariantSource } from './plugin.js'
// Optional provider self-report of outstanding background maintenance work
// (compaction, deferred writes, etc.) — the payload type for
// brain.maintenanceDebt(). See the measure-only-what-you-track contract on
// ProviderMaintenanceDebt in plugin.ts.
export type { ProviderMaintenanceDebt } from './plugin.js'
// Optional native graph-acceleration engine (cor 3.0) — the published provider
// contract + its columnar wire types. Brainy feature-detects an implementation
// and falls back to its pure-TS adjacency when absent.
export type {
GraphAccelerationProvider,
Subgraph,
OpaqueIdSet,
GraphTraversalDirection,
TraverseOptions,
EdgesForNodeOptions,
GraphCursorHandle,
GraphCursorOptions,
GraphCursorChunk,
GraphScores,
GraphCommunities,
GraphPath,
RankOptions,
CommunitiesOptions,
PathOptions,
SampleOptions,
MostConnectedOptions
} from './plugin.js'
// Export embedding functionality
import {
UniversalSentenceEncoder,
TransformerEmbedding,
createEmbeddingFunction,
defaultEmbeddingFunction,
batchEmbed,
embeddingFunctions
} from './utils/embedding.js'
// Export logging utilities
import {
logger,
LogLevel,
configureLogger,
createModuleLogger
} from './utils/logger.js'
// Chat system removed - was returning fake responses
// Export performance and optimization utilities
import {
getGlobalBackpressure,
AdaptiveBackpressure
} from './utils/adaptiveBackpressure.js'
import {
getGlobalPerformanceMonitor,
PerformanceMonitor
} from './utils/performanceMonitor.js'
// Export environment utilities
import { isNode } from './utils/environment.js'
export {
UniversalSentenceEncoder,
TransformerEmbedding,
createEmbeddingFunction,
defaultEmbeddingFunction,
batchEmbed,
embeddingFunctions,
// Environment utilities
isNode,
// Logging utilities
logger,
LogLevel,
configureLogger,
createModuleLogger,
// Performance and optimization utilities
getGlobalBackpressure,
AdaptiveBackpressure,
getGlobalPerformanceMonitor,
PerformanceMonitor
}
// Export storage adapters (Brainy 8.0 — filesystem + memory only).
import { MemoryStorage, createStorage } from './storage/storageFactory.js'
export { MemoryStorage, createStorage }
// FileSystemStorage is exported separately to avoid browser build issues.
export { FileSystemStorage } from './storage/adapters/fileSystemStorage.js'
// Torn-record surface: a stored file that EXISTS but cannot be decoded throws
// a typed, catchable error on entity reads (never a silent "not found"), and
// every encounter is counted on a per-process gauge.
export {
TornRecordError,
isTornRecordError,
getTornRecordGauge
} from './storage/tornRecordError.js'
// Export types
import type {
Vector,
VectorDocument,
SearchResult,
DistanceFunction,
EmbeddingFunction,
EmbeddingModel,
HNSWNoun,
HNSWVerb,
HNSWConfig,
StorageAdapter,
DerivedFamilyDeclaration,
// The canonical count ledger a storage adapter maintains (counted + ALL-visibility
// scalars per family, the coverage-ledger denominators) — see StorageAdapter.getCanonicalCounts.
CanonicalCounts
} from './coreTypes.js'
// Export vector index implementation (the JS HNSW path)
import { JsHnswVectorIndex } from './hnsw/hnswIndex.js'
export { JsHnswVectorIndex }
export type {
Vector,
VectorDocument,
SearchResult,
DistanceFunction,
EmbeddingFunction,
EmbeddingModel,
HNSWNoun,
HNSWVerb,
HNSWConfig,
StorageAdapter,
DerivedFamilyDeclaration
}
// Export graph types
import type {
GraphNoun,
GraphVerb,
EmbeddedGraphVerb,
Person,
Organization,
Location,
Thing,
Concept,
Event,
Agent,
Organism,
Substance,
Quality,
TimeInterval,
Function,
Proposition,
Document,
Media,
File,
Message,
Collection,
Dataset,
Product,
Service,
Task,
Project,
Process,
State,
Role,
Language,
Currency,
Measurement,
Hypothesis,
Experiment,
Contract,
Regulation,
Interface,
Resource,
Custom,
SocialGroup,
Institution,
Norm,
InformationContent,
InformationBearer,
Relationship
} from './types/graphTypes.js'
import { NounType, VerbType } from './types/graphTypes.js'
export type {
GraphNoun,
GraphVerb,
EmbeddedGraphVerb,
Person,
Organization,
Location,
Thing,
Concept,
Event,
Agent,
Organism,
Substance,
Quality,
TimeInterval,
Function,
Proposition,
Document,
Media,
File,
Message,
Collection,
Dataset,
Product,
Service,
Task,
Project,
Process,
State,
Role,
Language,
Currency,
Measurement,
Hypothesis,
Experiment,
Contract,
Regulation,
Interface,
Resource,
Custom,
SocialGroup,
Institution,
Norm,
InformationContent,
InformationBearer,
Relationship
}
// Export type utility functions
import { getNounTypes, getVerbTypes, getNounTypeMap, getVerbTypeMap } from './utils/typeUtils.js'
// Export BrainyTypes for type validation and lookup
import { BrainyTypes } from './utils/brainyTypes.js'
export {
NounType,
VerbType,
getNounTypes,
getVerbTypes,
getNounTypeMap,
getVerbTypeMap,
// BrainyTypes - type validation and lookup
BrainyTypes
}
// Export MCP (Model Control Protocol) components
import {
BrainyMCPAdapter,
BrainyMCPService
} from './mcp/index.js' // Import from mcp/index.js
import {
MCPRequest,
MCPResponse,
MCPDataAccessRequest,
MCPToolExecutionRequest,
MCPSystemInfoRequest,
MCPAuthenticationRequest,
MCPRequestType,
MCPServiceOptions,
MCPTool,
MCP_VERSION
} from './types/mcpTypes.js'
export {
// MCP classes
BrainyMCPAdapter,
BrainyMCPService,
// MCP types
MCPRequestType,
MCP_VERSION
}
export type {
MCPRequest,
MCPResponse,
MCPDataAccessRequest,
MCPToolExecutionRequest,
MCPSystemInfoRequest,
MCPAuthenticationRequest,
MCPServiceOptions,
MCPTool
}
// ============= Integration Hub =============
// Connect Brainy to Excel, Power BI, Google Sheets, and more
// Enable with: new Brainy({ integrations: true })
// Hub class (used internally by brain.hub, also available for advanced use)
export {
IntegrationHub,
createIntegrationHub
} from './integrations/index.js'
export type {
IntegrationHubConfig,
IntegrationRequest,
IntegrationResponse
} from './integrations/index.js'
// Re-export IntegrationsConfig from types (for TypeScript users)
export type { IntegrationsConfig } from './types/brainy.types.js'
// Core infrastructure
export {
EventBus,
TabularExporter,
IntegrationBase,
IntegrationLoader,
createIntegrationLoader,
detectEnvironment,
INTEGRATION_CATALOG
} from './integrations/index.js'
// Integration types
export type {
BrainyEvent,
EventFilter,
EventHandler,
EventSubscription,
TabularRow,
RelationTabularRow,
TabularExporterConfig,
IntegrationConfig,
IntegrationHealthStatus,
HTTPIntegration,
StreamingIntegration,
IntegrationType,
RuntimeEnvironment,
IntegrationInfo,
IntegrationLoaderConfig,
ODataQueryOptions,
WebhookRegistration,
WebhookDeliveryResult
} from './integrations/index.js'
// Concrete integrations
export {
GoogleSheetsIntegration,
ODataIntegration,
SSEIntegration,
WebhookIntegration
} from './integrations/index.js'
export type {
GoogleSheetsConfig,
ODataConfig,
SSEConfig,
WebhookConfig
} from './integrations/index.js'
// OData utilities (advanced)
export {
parseODataQuery,
parseFilter,
parseOrderBy,
parseSelect,
odataToFindParams,
applyFilter,
applySelect,
applyOrderBy,
applyPagination,
generateEdmx,
generateMetadataJson,
generateServiceDocument
} from './integrations/index.js'