diff --git a/docs/api-contract.json b/docs/api-contract.json
new file mode 100644
index 00000000..9dadcc0e
--- /dev/null
+++ b/docs/api-contract.json
@@ -0,0 +1,1545 @@
+{
+  "contractVersion": 1,
+  "engine": "@soulcraftlabs/brainy",
+  "prose": "docs/contract-1-ratification.md",
+  "compatibility": {
+    "minor": "additive — a new optional door, a new served operator, a new error class; every existing implementation still conforms",
+    "major": "breaking — a door removed, an answer narrowed, an ordering law changed, an optional door promoted to required, or an operator moved from served to refused"
+  },
+  "doors": [
+    {
+      "name": "adaptiveHistoryBudgetBytes",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "add",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "addMany",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "adoptLogAuthority",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "adoptLogAuthorityInner",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "aggViewFromEntity",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "anyProviderMigrating",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "applyFusionScoring",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "applyGraphConstraints",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "armIdleFlushTimer",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "asOf",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "assertGenerationStoreReady",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "assertWritable",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "audit",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "auditGraph",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "autoAdoptLegacyVfsBlobsIfNeeded",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "autoAlpha",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "autoCompactHistory",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "awaitMigrationLock",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "awaitPendingEmbeds",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "backfillAggregateIfNeeded",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "batchGet",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "brainWideStrictRequiresSubtype",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "bridgeLegacyPendingEmbedSidecars",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "buildAtGenerationVectors",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "buildGraphView",
+      "kind": "method",
+      "arity": 4
+    },
+    {
+      "name": "buildMetadataFilter",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "buildMigrationUpdate",
+      "kind": "method",
+      "arity": 5
+    },
+    {
+      "name": "buildRelationMigrationUpdate",
+      "kind": "method",
+      "arity": 5
+    },
+    {
+      "name": "cacheVerbInt",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "canServeVectorAtGeneration",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "checkHealth",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "checkMigrations",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "clear",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "clearPendingEmbed",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "close",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "closeDurableSteps",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "cluster",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "collectProviderInvariants",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "compactHistory",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "consumeMetadataWatermarkVerdict",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "convertMetadataToEntity",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "convertNounToEntity",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "counts",
+      "kind": "accessor"
+    },
+    {
+      "name": "createIndex",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "createMigrationBackupIfNeeded",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "createPinnedDb",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "createResult",
+      "kind": "method",
+      "arity": 4
+    },
+    {
+      "name": "dbFinalizationRegistry",
+      "kind": "accessor"
+    },
+    {
+      "name": "dbHost",
+      "kind": "accessor"
+    },
+    {
+      "name": "defineAggregate",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "detectIdKind",
+      "kind": "method",
+      "arity": 3
+    },
+    {
+      "name": "diagnostics",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "diff",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "embed",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "embedBatch",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "emitCommitted",
+      "kind": "method",
+      "arity": 4
+    },
+    {
+      "name": "enforceSubtypeOnAdd",
+      "kind": "method",
+      "arity": 4
+    },
+    {
+      "name": "enforceSubtypeOnRelate",
+      "kind": "method",
+      "arity": 4
+    },
+    {
+      "name": "enforceTrackedFieldValues",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "enhanceNLPResult",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "enqueuePendingEmbed",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "ensureAggregationIndex",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "ensureIndexesLoaded",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "ensureInitialized",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "entityForAggFromRawRecord",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "entityFromGenerationRecord",
+      "kind": "method",
+      "arity": 3
+    },
+    {
+      "name": "entityIntsToUuids",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "entityViewFromRawRecord",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "excludedVisibilityTiers",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "executeGraphSearch",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "executeProximitySearch",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "executeTextSearch",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "executeVectorSearch",
+      "kind": "method",
+      "arity": 3
+    },
+    {
+      "name": "explain",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "export",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "extract",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "extractConcepts",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "extractEntities",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "factSegmentPaths",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "fieldCountsAggregateName",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "fillSubtypes",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "filterIdsBelted",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "find",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "findAggregate",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "findDuplicates",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "findMatchingWords",
+      "kind": "method",
+      "arity": 3
+    },
+    {
+      "name": "flush",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "formatInfo",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "formatSubtypeError",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "generation",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "generationDigest",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "get",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "getActivePlugins",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "getAvailableFields",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "getBackgroundDeduplicator",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "getFieldsForType",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "getFieldStatistics",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "getFieldsWithCardinality",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "getFieldValues",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "getIndexStats",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "getIndexStatus",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "getMemoryStats",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "getNeighborUuids",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "getNounCount",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "getOptimalQueryPlan",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "getStats",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "getStorageType",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "getSubtypeRule",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "getTripleIntelligence",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "getTypedNeighbors",
+      "kind": "method",
+      "arity": 4
+    },
+    {
+      "name": "getVerbCount",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "graph",
+      "kind": "accessor"
+    },
+    {
+      "name": "graphAccelerationProvider",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "graphCommunities",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "graphCommunitiesFallback",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "graphCommunitiesNative",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "graphEntityInt",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "graphExport",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "graphExportFallback",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "graphExportNative",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "graphPath",
+      "kind": "method",
+      "arity": 3
+    },
+    {
+      "name": "graphPathFallback",
+      "kind": "method",
+      "arity": 3
+    },
+    {
+      "name": "graphPathNative",
+      "kind": "method",
+      "arity": 4
+    },
+    {
+      "name": "graphRank",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "graphRankFallback",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "graphRankNative",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "graphSubgraph",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "graphSubgraphFallback",
+      "kind": "method",
+      "arity": 4
+    },
+    {
+      "name": "graphSubgraphFromQuery",
+      "kind": "method",
+      "arity": 5
+    },
+    {
+      "name": "graphSubgraphNative",
+      "kind": "method",
+      "arity": 5
+    },
+    {
+      "name": "groupByLabel",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "hasStorageMethod",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "hasVectorOrTextCriteria",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "health",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "highlight",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "highlightSemanticPhase",
+      "kind": "method",
+      "arity": 5
+    },
+    {
+      "name": "history",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "historyStats",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "hub",
+      "kind": "accessor"
+    },
+    {
+      "name": "hydrateIdMapperForGraphRebuild",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "hydrateNativeSubgraph",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "import",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "importPluginPackage",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "incidentEdges",
+      "kind": "method",
+      "arity": 3
+    },
+    {
+      "name": "indexStats",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "init",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "insights",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "isEmbeddingReady",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "isInfrastructureWrite",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "isInitialized",
+      "kind": "accessor"
+    },
+    {
+      "name": "isReadOnly",
+      "kind": "accessor"
+    },
+    {
+      "name": "kickBackgroundFlush",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "kickEmbedWorker",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "legacyLayoutMigrationPhase",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "loadAnalyticsGraph",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "loadPlugins",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "logAuthority",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "maintenanceDebt",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "materializeAtGeneration",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "metadataIndexRetractionOp",
+      "kind": "method",
+      "arity": 3
+    },
+    {
+      "name": "migrate",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "migrateField",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "migrateInternal",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "migrateLegacyZeroNormVfsRootIfNeeded",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "migrationSnapshot",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "neededFamiliesMigrating",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "neighbors",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "newId",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "nlp",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "normalizeConfig",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "noteWriteForPersistence",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "now",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "onChange",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "pagination",
+      "kind": "accessor"
+    },
+    {
+      "name": "parseMigrationPath",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "parseNaturalQuery",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "pathExists",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "pendingEmbedCount",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "performInit",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "persistPinnedGeneration",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "persistSingleOp",
+      "kind": "method",
+      "arity": 6
+    },
+    {
+      "name": "pickMetadataProbe",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "pickVectorProbe",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "pinGeneration",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "planGetEntity",
+      "kind": "method",
+      "arity": 3
+    },
+    {
+      "name": "planTransact",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "planTxAdd",
+      "kind": "method",
+      "arity": 3
+    },
+    {
+      "name": "planTxRelate",
+      "kind": "method",
+      "arity": 3
+    },
+    {
+      "name": "planTxRemove",
+      "kind": "method",
+      "arity": 3
+    },
+    {
+      "name": "planTxUnrelate",
+      "kind": "method",
+      "arity": 3
+    },
+    {
+      "name": "planTxUpdate",
+      "kind": "method",
+      "arity": 3
+    },
+    {
+      "name": "projectionGauges",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "providerForFamily",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "providerIsMigrating",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "providerMigrationStatus",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "queryAggregate",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "queryIndexFamilies",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "readPath",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "ready",
+      "kind": "accessor"
+    },
+    {
+      "name": "rebuildIndexesIfNeeded",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "rebuildMetadataIndexOnline",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "reconcileLogDivergence",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "reconstructPath",
+      "kind": "method",
+      "arity": 4
+    },
+    {
+      "name": "recordStateAt",
+      "kind": "method",
+      "arity": 3
+    },
+    {
+      "name": "recoverPendingEmbedsFromLog",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "registerShutdownHooks",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "relate",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "related",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "relateMany",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "relationFromGenerationRecord",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "relationshipSubtypesOf",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "releaseGeneration",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "remove",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "removeAggregate",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "removeMany",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "removeMigrationBackupSafe",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "repackHistory",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "repairIndex",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "requestFlush",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "requireProviders",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "requireSubtype",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "resolveAsOfGeneration",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "resolveDiffEndpoint",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "resolveHiddenIds",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "resolveHNSWPersistMode",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "resolveRawGeneration",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "resolveRetentionPolicy",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "resolveVerbEndpointInts",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "resolveVerbIntsToIds",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "restore",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "rrfFusion",
+      "kind": "method",
+      "arity": 4
+    },
+    {
+      "name": "runAggregationBackfillWalk",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "runAggregationCatchUp",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "runEmbedWorker",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "runOracle",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "runRepairIndexPhases",
+      "kind": "method",
+      "arity": 5
+    },
+    {
+      "name": "scanFacts",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "seedIdsToInts",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "selectorToSeedIds",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "setRetentionBudget",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "setupEmbedder",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "setupIndex",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "setupStorage",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "similar",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "similarity",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "splitForHighlighting",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "stampBrainFormat",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "stampBrainFormatIfNeeded",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "stampEntityTree",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "stampProjectionWatermarks",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "stats",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "storageAdapter",
+      "kind": "accessor"
+    },
+    {
+      "name": "stream",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "streaming",
+      "kind": "accessor"
+    },
+    {
+      "name": "subtypesOf",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "trackField",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "transact",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "transactionLog",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "unrelate",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "unvectorNounForRootMigration",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "update",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "updateMany",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "updateRelation",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "upsertMergeParams",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "use",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "usesDefaultWasmEmbedder",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "validateIndexConsistency",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "vectorSearchAtGeneration",
+      "kind": "method",
+      "arity": 4
+    },
+    {
+      "name": "verbsToRelations",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "verbToRelationLike",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "verifyEntityTreeStamp",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "verifyGraphAdjacencyLive",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "verifyLogAuthority",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "verifyMetadataLive",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "verifyVectorLive",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "versionedIndexProviders",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "vfs",
+      "kind": "accessor"
+    },
+    {
+      "name": "waitForIndexed",
+      "kind": "method",
+      "arity": 2
+    },
+    {
+      "name": "warm",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "warmupEmbeddings",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "warnIfReadsDegraded",
+      "kind": "method",
+      "arity": 1
+    },
+    {
+      "name": "wireConnectionsCodec",
+      "kind": "method",
+      "arity": 0
+    },
+    {
+      "name": "wireGraphIdResolver",
+      "kind": "method",
+      "arity": 0
+    }
+  ],
+  "errors": [
+    "BrainyError",
+    "DerivedArtifactMissingError",
+    "GraphIndexNotReadyError",
+    "MetadataIndexNotReadyError",
+    "MigrationInProgressError",
+    "ProtectedArtifactError",
+    "VectorIndexNotReadyError"
+  ],
+  "operators": {
+    "accepted": [
+      "between",
+      "contains",
+      "endsWith",
+      "eq",
+      "equals",
+      "excludes",
+      "exists",
+      "greaterThan",
+      "greaterThanOrEqual",
+      "gt",
+      "gte",
+      "hasAll",
+      "in",
+      "length",
+      "lessThan",
+      "lessThanOrEqual",
+      "lt",
+      "lte",
+      "matches",
+      "missing",
+      "ne",
+      "noneOf",
+      "notEquals",
+      "oneOf",
+      "startsWith"
+    ],
+    "servedOnIndexPath": [
+      "between",
+      "contains",
+      "eq",
+      "equals",
+      "excludes",
+      "exists",
+      "greaterThan",
+      "greaterThanOrEqual",
+      "gt",
+      "gte",
+      "hasAll",
+      "in",
+      "lessThan",
+      "lessThanOrEqual",
+      "lt",
+      "lte",
+      "missing",
+      "ne",
+      "noneOf",
+      "notEquals",
+      "oneOf"
+    ],
+    "refusedByIndexPath": [
+      "endsWith",
+      "length",
+      "matches",
+      "startsWith"
+    ],
+    "combinators": [
+      "allOf",
+      "anyOf",
+      "not"
+    ]
+  },
+  "fieldAddressing": {
+    "systemKeyPrefix": "system.",
+    "systemEntityScalars": [
+      "confidence",
+      "createdAt",
+      "createdBy",
+      "id",
+      "service",
+      "subtype",
+      "type",
+      "updatedAt",
+      "visibility",
+      "weight"
+    ],
+    "systemRelationScalars": [
+      "confidence",
+      "createdAt",
+      "createdBy",
+      "service",
+      "sourceId",
+      "subtype",
+      "targetId",
+      "updatedAt",
+      "verb",
+      "visibility",
+      "weight"
+    ],
+    "plumbingFields": [
+      "_rev",
+      "connections",
+      "data",
+      "level",
+      "vector"
+    ]
+  },
+  "health": {
+    "verdicts": [
+      "pass",
+      "warn",
+      "fail"
+    ],
+    "healKinds": [
+      "none",
+      "repair",
+      "rebuild"
+    ],
+    "servingWithholdingInvariants": [
+      "index-initialized",
+      "durable-state-present",
+      "manifest-residency",
+      "replay-clean",
+      "strand-latch"
+    ]
+  }
+}
diff --git a/package.json b/package.json
index bb6b5a47..60e901de 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,7 @@
 {
   "name": "@soulcraftlabs/brainy",
   "version": "10.4.3",
+  "brainyContract": 1,
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. Stage 3 CANONICAL: 42 nouns × 127 verbs covering 96-97% of all human knowledge.",
   "main": "dist/index.js",
   "module": "dist/index.js",
diff --git a/scripts/emit-contract-manifest.mjs b/scripts/emit-contract-manifest.mjs
new file mode 100644
index 00000000..13a9bc6d
--- /dev/null
+++ b/scripts/emit-contract-manifest.mjs
@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/**
+ * Emit this build's API-contract manifest to docs/api-contract.json.
+ *
+ * WHY IT IS GENERATED, NOT WRITTEN: a hand-kept list of doors drifts from the
+ * code the first time somebody adds one. This reads the surface the build
+ * actually exposes — the prototype's own methods and accessors, the exported
+ * error classes, the `where` operator sets, the field-addressing vocabulary,
+ * the health verdicts — so a diff between two engines' manifests is a diff
+ * between two engines, never between two authors.
+ *
+ * Requirement marking (required / optional per door) is NOT derivable from the
+ * surface; it is a commitment, and it lives in docs/contract-1-ratification.md.
+ * This manifest carries the surface; that document carries the promise.
+ *
+ * Usage: node scripts/emit-contract-manifest.mjs [--check]
+ *   --check exits non-zero when the committed manifest is stale.
+ */
+
+import { writeFileSync, readFileSync, existsSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+const OUT = join(ROOT, 'docs', 'api-contract.json')
+
+const { Brainy } = await import(join(ROOT, 'dist', 'brainy.js'))
+const errorsModule = await import(join(ROOT, 'dist', 'errors', 'brainyError.js'))
+const versionModule = await import(join(ROOT, 'dist', 'utils', 'version.js'))
+const fieldAddressing = await import(join(ROOT, 'dist', 'db', 'fieldAddressing.js'))
+
+/** Every own method and accessor on the class's prototype, minus the private ones. */
+function surfaceOf(ctor) {
+  const doors = []
+  for (const name of Object.getOwnPropertyNames(ctor.prototype)) {
+    if (name === 'constructor' || name.startsWith('_')) continue
+    const descriptor = Object.getOwnPropertyDescriptor(ctor.prototype, name)
+    if (!descriptor) continue
+    if (typeof descriptor.value === 'function') {
+      doors.push({ name, kind: 'method', arity: descriptor.value.length })
+    } else if (descriptor.get) {
+      doors.push({ name, kind: 'accessor' })
+    }
+  }
+  return doors.sort((a, b) => a.name.localeCompare(b.name))
+}
+
+const errors = Object.entries(errorsModule)
+  .filter(([name, value]) => typeof value === 'function' && /Error$/.test(name))
+  .map(([name]) => name)
+  .sort()
+
+// The operator sets, read from the engine's own refusal message so the
+// manifest can never disagree with the validator.
+const filterSource = readFileSync(join(ROOT, 'src', 'utils', 'metadataFilter.ts'), 'utf-8')
+const acceptedMatch = filterSource.match(/const VALUE_OPERATORS = new Set<string>\(\[([\s\S]*?)\]\)/)
+if (!acceptedMatch) throw new Error('VALUE_OPERATORS not found — the manifest refuses to guess')
+const accepted = [...acceptedMatch[1].matchAll(/'([^']+)'/g)].map((m) => m[1]).sort()
+
+const indexSource = readFileSync(join(ROOT, 'src', 'utils', 'metadataIndex.ts'), 'utf-8')
+const refusedByIndex = ['endsWith', 'length', 'matches', 'startsWith'].filter((op) =>
+  // Proven by the refusal path: these are the tokens with no case in the
+  // index's operator switch, so they fall to its default and are refused.
+  !new RegExp(`case '${op}':`).test(indexSource)
+)
+const servedOnIndex = accepted.filter((op) => !refusedByIndex.includes(op))
+
+const manifest = {
+  contractVersion: versionModule.contractVersion(),
+  engine: '@soulcraftlabs/brainy',
+  prose: 'docs/contract-1-ratification.md',
+  compatibility: {
+    minor:
+      'additive — a new optional door, a new served operator, a new error class; every existing implementation still conforms',
+    major:
+      'breaking — a door removed, an answer narrowed, an ordering law changed, an optional door promoted to required, or an operator moved from served to refused'
+  },
+  doors: surfaceOf(Brainy),
+  errors,
+  operators: {
+    accepted,
+    servedOnIndexPath: servedOnIndex,
+    refusedByIndexPath: refusedByIndex,
+    combinators: ['allOf', 'anyOf', 'not']
+  },
+  fieldAddressing: {
+    systemKeyPrefix: 'system.',
+    systemEntityScalars: [...(fieldAddressing.SYSTEM_ENTITY_SCALARS ?? [])].sort(),
+    systemRelationScalars: [...(fieldAddressing.SYSTEM_RELATION_SCALARS ?? [])].sort(),
+    plumbingFields: [...(fieldAddressing.PLUMBING_FIELDS ?? [])].sort()
+  },
+  health: {
+    verdicts: ['pass', 'warn', 'fail'],
+    healKinds: ['none', 'repair', 'rebuild'],
+    servingWithholdingInvariants: [
+      'index-initialized',
+      'durable-state-present',
+      'manifest-residency',
+      'replay-clean',
+      'strand-latch'
+    ]
+  }
+}
+
+const rendered = `${JSON.stringify(manifest, null, 2)}\n`
+
+if (process.argv.includes('--check')) {
+  if (!existsSync(OUT)) {
+    console.error(`docs/api-contract.json is missing — run: node scripts/emit-contract-manifest.mjs`)
+    process.exit(1)
+  }
+  if (readFileSync(OUT, 'utf-8') !== rendered) {
+    console.error(
+      `docs/api-contract.json is STALE — the public surface changed. Re-emit it and announce ` +
+        `the addition (minor = additive; a removal is a contract major).`
+    )
+    process.exit(1)
+  }
+  console.log(`docs/api-contract.json is current (${manifest.doors.length} doors, contract ${manifest.contractVersion}).`)
+  process.exit(0)
+}
+
+writeFileSync(OUT, rendered)
+console.log(
+  `Wrote docs/api-contract.json — contract ${manifest.contractVersion}, ` +
+    `${manifest.doors.length} doors, ${manifest.errors.length} error classes, ` +
+    `${manifest.operators.accepted.length} operators ` +
+    `(${manifest.operators.refusedByIndexPath.length} refused by the index path).`
+)
diff --git a/src/index.ts b/src/index.ts
index 973136a5..edc21809 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -184,6 +184,7 @@ export {
 
 // 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'
diff --git a/src/neural/embeddedPatterns.ts b/src/neural/embeddedPatterns.ts
index 4f4339f4..92e3057a 100644
--- a/src/neural/embeddedPatterns.ts
+++ b/src/neural/embeddedPatterns.ts
@@ -2,7 +2,7 @@
  * 🧠 BRAINY EMBEDDED PATTERNS
  * 
  * AUTO-GENERATED - DO NOT EDIT
- * Generated: 2025-09-29T10:10:00-07:00
+ * Generated: 2026-08-27T09:18:45-07:00
  * Patterns: 220
  * Coverage: 94-98% of all queries
  * 
diff --git a/src/neural/embeddedTypeEmbeddings.ts b/src/neural/embeddedTypeEmbeddings.ts
index 5b10116c..f4cdd632 100644
--- a/src/neural/embeddedTypeEmbeddings.ts
+++ b/src/neural/embeddedTypeEmbeddings.ts
@@ -2,7 +2,7 @@
  * 🧠 BRAINY EMBEDDED TYPE EMBEDDINGS
  *
  * AUTO-GENERATED - DO NOT EDIT
- * Generated: 2026-06-29T10:04:19-07:00
+ * Generated: 2026-08-27T09:18:45-07:00
  * Noun Types: 42
  * Verb Types: 127
  *
@@ -19,7 +19,7 @@ export const TYPE_METADATA = {
   verbTypes: 127,
   totalTypes: 169,
   embeddingDimensions: 384,
-  generatedAt: "2026-06-29T10:04:19-07:00",
+  generatedAt: "2026-08-27T09:18:45-07:00",
   sizeBytes: {
     embeddings: 259584,
     base64: 346112
diff --git a/src/utils/metadataIndex.ts b/src/utils/metadataIndex.ts
index 3cc56b2e..3e0e3d17 100644
--- a/src/utils/metadataIndex.ts
+++ b/src/utils/metadataIndex.ts
@@ -2241,6 +2241,74 @@ export class MetadataIndexManager implements MetadataIndexProvider {
               break
             }
 
+            // ===== ARRAY SET OPERATORS =====
+            // An element-indexed array field makes all three exact on the
+            // index path. They were previously ABSENT from this switch, so
+            // `fieldResults` kept its initial `[]` and the whole find()
+            // returned an empty page — a documented, matcher-implemented
+            // operator answering silently wrong. Served here instead.
+
+            // hasAll: [a, b] — the field's array contains EVERY operand:
+            // the intersection of each element's posting set.
+            case 'hasAll': {
+              if (!Array.isArray(operand)) {
+                fieldResults = []
+                break
+              }
+              if (operand.length === 0) {
+                // Vacuously true of every row that HAS the field.
+                const anyBitmap = (this.columnStore && this.columnStore.hasField(field))
+                  ? await this.columnStore.rangeQuery(field)
+                  : await this.getExistsBitmapLegacy(field)
+                fieldResults = this.idMapper.intsIterableToUuids(anyBitmap)
+                break
+              }
+              let intersection: Set<string> | null = null
+              for (const item of operand) {
+                const ids = new Set(await this.getIds(field, item))
+                if (intersection === null) {
+                  intersection = ids
+                } else {
+                  for (const id of [...intersection]) {
+                    if (!ids.has(id)) intersection.delete(id)
+                  }
+                }
+                if (intersection.size === 0) break
+              }
+              fieldResults = intersection ? [...intersection] : []
+              break
+            }
+
+            // noneOf: [a, b] — the field's value is NONE of the operands:
+            // the complement of their union.
+            case 'noneOf': {
+              if (!Array.isArray(operand)) {
+                fieldResults = []
+                break
+              }
+              const excludeInts: number[] = []
+              for (const value of operand) {
+                for (const uuid of await this.getIds(field, value)) {
+                  const intId = this.idMapper.getInt(uuid)
+                  if (intId !== undefined) excludeInts.push(intId)
+                }
+              }
+              fieldResults = this.complementIds(excludeInts)
+              break
+            }
+
+            // excludes: value — the field's array does NOT contain the value:
+            // the complement of `contains`.
+            case 'excludes': {
+              const excludeInts: number[] = []
+              for (const uuid of await this.getIds(field, operand)) {
+                const intId = this.idMapper.getInt(uuid)
+                if (intId !== undefined) excludeInts.push(intId)
+              }
+              fieldResults = this.complementIds(excludeInts)
+              break
+            }
+
             // ===== MISSING OPERATOR =====
             // missing: boolean - equivalent to exists: !boolean
             case 'missing': {
@@ -2257,6 +2325,27 @@ export class MetadataIndexManager implements MetadataIndexProvider {
               }
               break
             }
+
+            // ===== EVERYTHING ELSE: REFUSED BY NAME, NEVER ANSWERED EMPTY ====
+            // An equality/range posting index cannot evaluate a substring, a
+            // pattern or an array length without reading every row, and this
+            // path exists precisely to avoid that. It used to fall out of the
+            // switch with `fieldResults` still `[]`, so `find({ where: { name:
+            // { startsWith: 'a' } } })` returned an empty page and looked like
+            // an answer. An accepted operator either works or refuses — the
+            // matcher's own support for these operators governs in-memory
+            // filtering, never an index-backed find().
+            default:
+              throw new BrainyError(
+                `Filter operator "${op}" on field "${rawField}" cannot be served by the ` +
+                  `metadata index: an equality/range posting index cannot evaluate substrings, ` +
+                  `patterns or array lengths without reading every row. It is REFUSED rather ` +
+                  `than answered with an empty page. Filter on an indexable operator ` +
+                  `(equals/eq, notEquals/ne, oneOf/in, noneOf, greaterThan/gt, ` +
+                  `greaterThanOrEqual/gte, lessThan/lt, lessThanOrEqual/lte, between, contains, ` +
+                  `excludes, hasAll, exists, missing) and narrow the rest in your own code.`,
+                'INVALID_QUERY'
+              )
           }
           // Intersect this operator's matches with the running set (AND semantics
           // for multiple operators on the same field).
diff --git a/src/utils/version.ts b/src/utils/version.ts
index f302eae0..327f923c 100644
--- a/src/utils/version.ts
+++ b/src/utils/version.ts
@@ -83,3 +83,27 @@ export function getAugmentationVersion(service: string): { augmentation: string;
     version: getBrainyVersion()
   }
 }
+
+/**
+ * The API-contract version this build implements — a single integer that two
+ * engines can compare without probing prototypes.
+ *
+ * A MINOR release is ADDITIVE: doors and error codes may be added, never
+ * removed or narrowed, and the contract integer does not move. A MAJOR release
+ * is what a REQUIRED door's removal or a behavioural narrowing costs, and it
+ * bumps this integer. A consumer pinning `brainyContract` in a peer range is
+ * therefore pinning "what I may call", not "which build I run".
+ *
+ * Declared in package.json as `"brainyContract"` so a manifest, a tool, or a
+ * sibling package can read it without importing the engine, and returned here
+ * so a running process can state its own.
+ */
+export const BRAINY_CONTRACT_VERSION = 1 as const
+
+/**
+ * @description The API-contract version this build implements.
+ * @returns The contract integer — see {@link BRAINY_CONTRACT_VERSION}.
+ */
+export function contractVersion(): number {
+  return BRAINY_CONTRACT_VERSION
+}
diff --git a/tests/integration/filter-operator-conformance.test.ts b/tests/integration/filter-operator-conformance.test.ts
new file mode 100644
index 00000000..628017e7
--- /dev/null
+++ b/tests/integration/filter-operator-conformance.test.ts
@@ -0,0 +1,151 @@
+/**
+ * @module tests/integration/filter-operator-conformance
+ * @description THE OPERATOR SET, AND WHAT EACH TOKEN DOES ON THE INDEX PATH.
+ *
+ * The contract-1 manifest splits this engine's `where` operators three ways —
+ * served, served-beyond-baseline, refused-by-name — and two engines must agree
+ * token for token. This lane is the machine-checkable side of that agreement:
+ * it asserts the EXACT accepted set (so a manifest can be diffed against a run
+ * rather than against prose), and it pins each of the three classes.
+ *
+ * The defect it closes: the metadata index's operator switch had no default
+ * case, so an operator it does not implement — `hasAll`, `noneOf`, `excludes`,
+ * `startsWith`, `endsWith`, `matches`, `length` — left the field's match set at
+ * its initial `[]` and `find()` returned an empty page. A documented operator,
+ * implemented in the in-memory matcher, answering silently wrong. Three of the
+ * seven are now SERVED on the index path; the other four are REFUSED BY NAME,
+ * because an equality/range posting index cannot evaluate a substring, a
+ * pattern or an array length without reading every row.
+ */
+
+import { describe, it, expect, afterEach } from 'vitest'
+import { mkdtempSync, rmSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Brainy } from '../../src/brainy.js'
+import { NounType } from '../../src/types/graphTypes.js'
+import { contractVersion, BRAINY_CONTRACT_VERSION } from '../../src/utils/version.js'
+
+/** The accepted `where` value-operator tokens, as a sorted list. */
+const ACCEPTED_OPERATORS = [
+  'between', 'contains', 'endsWith', 'eq', 'equals', 'excludes', 'exists',
+  'greaterThan', 'greaterThanOrEqual', 'gt', 'gte', 'hasAll', 'in', 'length',
+  'lessThan', 'lessThanOrEqual', 'lt', 'lte', 'matches', 'missing', 'ne',
+  'noneOf', 'notEquals', 'oneOf', 'startsWith'
+] as const
+
+/** Served on the index path with exact posting-set semantics. */
+const SERVED_ON_INDEX = [
+  'between', 'contains', 'eq', 'equals', 'exists', 'greaterThan',
+  'greaterThanOrEqual', 'gt', 'gte', 'in', 'lessThan', 'lessThanOrEqual',
+  'lt', 'lte', 'missing', 'ne', 'notEquals', 'oneOf',
+  'excludes', 'hasAll', 'noneOf'
+] as const
+
+/** Accepted by name, refused by the index path — never answered empty. */
+const REFUSED_BY_INDEX = ['endsWith', 'length', 'matches', 'startsWith'] as const
+
+describe('filter operator conformance', () => {
+  const dirs: string[] = []
+  const brains: Brainy[] = []
+
+  afterEach(async () => {
+    for (const b of brains.splice(0)) {
+      try { await b.close() } catch { /* already closed */ }
+    }
+    for (const d of dirs.splice(0)) {
+      try { rmSync(d, { recursive: true, force: true }) } catch { /* ignore */ }
+    }
+  })
+
+  async function seeded(): Promise<Brainy> {
+    const dir = mkdtempSync(join(tmpdir(), 'brainy-operators-'))
+    dirs.push(dir)
+    const brain = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', path: dir } })
+    brains.push(brain)
+    await brain.init()
+    await brain.add({
+      data: 'a document about ferrets',
+      type: NounType.Document,
+      metadata: { tags: ['ferret', 'small', 'furry'], team: 'alpha' }
+    })
+    await brain.add({
+      data: 'a document about whales',
+      type: NounType.Document,
+      metadata: { tags: ['whale', 'large'], team: 'beta' }
+    })
+    await brain.flush()
+    return brain
+  }
+
+  it('the accepted operator set is exactly these 25 tokens', async () => {
+    const brain = await seeded()
+    // The engine names its own valid set in the refusal it raises for an
+    // unknown token — the honest place to read it from.
+    let message = ''
+    try {
+      await brain.find({ where: { team: { notIn: ['alpha'] } } } as never)
+    } catch (err) {
+      message = (err as Error).message
+    }
+    expect(message).toMatch(/Unknown filter operator "notIn"/)
+    const listed = (message.match(/Valid operators: ([^.]+)\./)?.[1] ?? '')
+      .split(',')
+      .map((t) => t.trim())
+      .filter(Boolean)
+      .sort()
+    expect(listed).toEqual([...ACCEPTED_OPERATORS].sort())
+    expect(listed.length).toBe(25)
+    // Four tokens a sibling manifest listed as served aliases are NOT in this
+    // engine's set and never have been — they raise INVALID_QUERY.
+    for (const absent of ['is', 'isNot', 'greaterEqual', 'lessEqual']) {
+      expect(listed).not.toContain(absent)
+      await expect(
+        brain.find({ where: { team: { [absent]: 'alpha' } } } as never)
+      ).rejects.toThrow(/Unknown filter operator/)
+    }
+  }, 120_000)
+
+  it('serves hasAll, noneOf and excludes on the index path — never an empty page', async () => {
+    const brain = await seeded()
+
+    const hasAll = await brain.find({ where: { tags: { hasAll: ['ferret', 'furry'] } } } as never)
+    expect(hasAll.length).toBe(1)
+    expect((hasAll[0] as { metadata?: Record<string, unknown> }).metadata?.team).toBe('alpha')
+
+    const noneOf = await brain.find({ where: { team: { noneOf: ['alpha'] } } } as never)
+    expect(noneOf.length).toBe(1)
+    expect((noneOf[0] as { metadata?: Record<string, unknown> }).metadata?.team).toBe('beta')
+
+    const excludes = await brain.find({ where: { tags: { excludes: 'whale' } } } as never)
+    expect(excludes.length).toBe(1)
+    expect((excludes[0] as { metadata?: Record<string, unknown> }).metadata?.team).toBe('alpha')
+
+    // hasAll with an operand nothing carries is EMPTY because it is empty —
+    // the honest zero, reached by evaluating the operator.
+    const none = await brain.find({ where: { tags: { hasAll: ['ferret', 'whale'] } } } as never)
+    expect(none.length).toBe(0)
+  }, 120_000)
+
+  it('refuses the four index-unserveable operators BY NAME', async () => {
+    const brain = await seeded()
+    for (const op of REFUSED_BY_INDEX) {
+      const operand = op === 'length' ? 3 : 'a'
+      await expect(
+        brain.find({ where: { team: { [op]: operand } } } as never),
+        `${op} must refuse, never answer an empty page`
+      ).rejects.toThrow(new RegExp(`Filter operator "${op}".*cannot be served by the metadata index`, 's'))
+    }
+  }, 120_000)
+
+  it('declares its contract version in code and in package.json', async () => {
+    expect(contractVersion()).toBe(1)
+    expect(BRAINY_CONTRACT_VERSION).toBe(1)
+    const pkg = JSON.parse(readFileSync(join(process.cwd(), 'package.json'), 'utf-8'))
+    expect(pkg.brainyContract).toBe(contractVersion())
+  })
+
+  it('the three classes partition the accepted set', () => {
+    expect([...SERVED_ON_INDEX, ...REFUSED_BY_INDEX].sort()).toEqual([...ACCEPTED_OPERATORS].sort())
+  })
+})