@happyvertical/smrt-core 0.40.65 → 0.40.66

package/dist/smrt-knowledge.json

@@ -1,14 +1,15 @@
 {
   "schemaVersion": 1,
+  "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-core",
-  "packageVersion": "0.40.65",
+  "packageVersion": "0.40.66",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "4d0e58155f69cc66603247579db7bee2f3d0c9e990a73bdcecdd3fa0603ede12",
-    "packageJson": "797eccce370558c4b11c5154e731c272598e3610b32ac2b6aefe93ad26301924",
-    "agents": "a04c59dc48f441ef935727feb3f85c7487a11dd6a0c6e8e85899aa4c777ee36c",
+    "manifest": "c5f3ddda3643e02b19c6cf026d0a26ec5b59c6f5f8b791bd26b198c8a96a3036",
+    "packageJson": "c8b73d99ef3b13b6372e4096e18e2cea009583d3a2e80e33e270664304ef93e1",
+    "agents": "cd549496058522b65d18c2f2bc3492e56eee57b14fefd0d8eea5329a3b0de004",
     "moduleDoc:agents/change-feed.md": "5278797d6c049ea21071b011182a9fcd79d17f9d74e0f90a93caa4c05c25294f",
     "moduleDoc:agents/change-signals.md": "d9cb6a5541728ffea46607a6b1d4fa61d4621849f2b4ea86a0645fbb0af892e9",
     "moduleDoc:agents/generators.md": "2b6ccd5ff557293f2ce84d25cc254ceb518f4c274d93b7e3175985b18f36f564"
@@ -103,6 +104,36 @@
         "resetAiUsage",
         "summarizeAiUsage"
       ],
+      "methodSignatures": [
+        {
+          "name": "destroy",
+          "returns": "void"
+        },
+        {
+          "name": "getAiUsageSnapshot",
+          "returns": "AiUsageSnapshot | undefined"
+        },
+        {
+          "name": "listAiUsage",
+          "async": true,
+          "params": [
+            "options?: AiUsageListOptions"
+          ],
+          "returns": "Promise<SmrtAiUsageRecord[]>"
+        },
+        {
+          "name": "resetAiUsage",
+          "returns": "void"
+        },
+        {
+          "name": "summarizeAiUsage",
+          "async": true,
+          "params": [
+            "options?: AiUsageSummaryOptions"
+          ],
+          "returns": "Promise<Record<string, AiUsageStats>>"
+        }
+      ],
       "surfaces": [],
       "relationshipFeatures": [
         "uuidColumns"
@@ -151,6 +182,225 @@
         "semanticSearch",
         "validate"
       ],
+      "methodSignatures": [
+        {
+          "name": "count",
+          "async": true,
+          "params": [
+            "options?: object"
+          ],
+          "returns": "any"
+        },
+        {
+          "name": "create",
+          "async": true,
+          "params": [
+            "options: SmrtCreateInput<ModelType>"
+          ],
+          "returns": "any"
+        },
+        {
+          "name": "delete",
+          "async": true,
+          "params": [
+            "id: string"
+          ],
+          "returns": "Promise<boolean>"
+        },
+        {
+          "name": "ensureStorageReady",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "findAll",
+          "async": true,
+          "params": [
+            "options?: object"
+          ],
+          "returns": "Promise<ModelType[]>"
+        },
+        {
+          "name": "findById",
+          "async": true,
+          "params": [
+            "id: string"
+          ],
+          "returns": "Promise<ModelType | null>"
+        },
+        {
+          "name": "findOne",
+          "async": true,
+          "params": [
+            "options: object"
+          ],
+          "returns": "Promise<ModelType | null>"
+        },
+        {
+          "name": "findSimilar",
+          "async": true,
+          "params": [
+            "object: ModelType | string",
+            "options?: object"
+          ],
+          "returns": "Promise<Array>"
+        },
+        {
+          "name": "findSimilarToEmbedding",
+          "async": true,
+          "params": [
+            "embedding: number[]",
+            "options?: object"
+          ],
+          "returns": "Promise<Array>"
+        },
+        {
+          "name": "forget",
+          "async": true,
+          "params": [
+            "options: object"
+          ],
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "forgetScope",
+          "async": true,
+          "params": [
+            "options: object"
+          ],
+          "returns": "Promise<number>"
+        },
+        {
+          "name": "generateMissingEmbeddings",
+          "async": true,
+          "params": [
+            "options?: object"
+          ],
+          "returns": "Promise<object>"
+        },
+        {
+          "name": "generateSchema",
+          "async": true,
+          "returns": "any"
+        },
+        {
+          "name": "generateTableName",
+          "returns": "any"
+        },
+        {
+          "name": "get",
+          "async": true,
+          "params": [
+            "filter: string | SmrtWhereClause<ModelType>",
+            "options?: object"
+          ],
+          "returns": "Promise<ModelType | null>"
+        },
+        {
+          "name": "getDiff",
+          "async": true,
+          "params": [
+            "existing: SmrtObject | Record<string>",
+            "data: Record<string>"
+          ],
+          "returns": "Promise<Record<string> | null>"
+        },
+        {
+          "name": "getFields",
+          "async": true,
+          "returns": "Promise<Record<string, CollectionFieldDefinition>>"
+        },
+        {
+          "name": "getFieldsSync",
+          "returns": "Record<string, CollectionFieldDefinition>"
+        },
+        {
+          "name": "getItemClass",
+          "returns": "SmrtCollectionItemClass<ModelType>"
+        },
+        {
+          "name": "getOrUpsert",
+          "async": true,
+          "params": [
+            "data: Record<string>",
+            "defaults?: Record<string>"
+          ],
+          "returns": "any"
+        },
+        {
+          "name": "getStiChildMetaType",
+          "returns": "string | null"
+        },
+        {
+          "name": "initialize",
+          "async": true,
+          "returns": "Promise"
+        },
+        {
+          "name": "list",
+          "async": true,
+          "params": [
+            "options?: SmrtListOptions<ModelType>"
+          ],
+          "returns": "Promise<ModelType[] | Record<string>[]>"
+        },
+        {
+          "name": "listByIds",
+          "async": true,
+          "params": [
+            "ids: string[]"
+          ],
+          "returns": "Promise<ModelType[]>"
+        },
+        {
+          "name": "query",
+          "async": true,
+          "params": [
+            "sql: string",
+            "params?: any",
+            "options?: object"
+          ],
+          "returns": "Promise<ModelType[]>"
+        },
+        {
+          "name": "recall",
+          "async": true,
+          "params": [
+            "options: object"
+          ],
+          "returns": "Promise"
+        },
+        {
+          "name": "recallAll",
+          "async": true,
+          "params": [
+            "options?: object"
+          ],
+          "returns": "Promise<Map<string>>"
+        },
+        {
+          "name": "remember",
+          "async": true,
+          "params": [
+            "options: object"
+          ],
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "semanticSearch",
+          "async": true,
+          "params": [
+            "query: string",
+            "options?: object"
+          ],
+          "returns": "Promise<Array>"
+        },
+        {
+          "name": "validate",
+          "static": true,
+          "returns": "void"
+        }
+      ],
       "surfaces": [],
       "relationshipFeatures": [
         "uuidColumns"
@@ -180,6 +430,41 @@
         "getParent",
         "moveTo"
       ],
+      "methodSignatures": [
+        {
+          "name": "getAncestors",
+          "async": true,
+          "returns": "Promise"
+        },
+        {
+          "name": "getChildren",
+          "async": true,
+          "returns": "Promise"
+        },
+        {
+          "name": "getDescendants",
+          "async": true,
+          "returns": "Promise"
+        },
+        {
+          "name": "getHierarchy",
+          "async": true,
+          "returns": "Promise<HierarchyView>"
+        },
+        {
+          "name": "getParent",
+          "async": true,
+          "returns": "Promise<null>"
+        },
+        {
+          "name": "moveTo",
+          "async": true,
+          "params": [
+            "newParent: string | null"
+          ],
+          "returns": "Promise<void>"
+        }
+      ],
       "surfaces": [],
       "relationshipFeatures": [],
       "tags": [],
@@ -200,6 +485,56 @@
         "detach",
         "setLinks"
       ],
+      "methodSignatures": [
+        {
+          "name": "attach",
+          "async": true,
+          "params": [
+            "leftId: string",
+            "rightId: string",
+            "opts?: JunctionAttachOptions"
+          ],
+          "returns": "Promise<TItem>"
+        },
+        {
+          "name": "byLeft",
+          "async": true,
+          "params": [
+            "leftId: string",
+            "opts?: JunctionFilterOptions"
+          ],
+          "returns": "Promise<TItem[]>"
+        },
+        {
+          "name": "byRight",
+          "async": true,
+          "params": [
+            "rightId: string",
+            "opts?: JunctionFilterOptions"
+          ],
+          "returns": "Promise<TItem[]>"
+        },
+        {
+          "name": "detach",
+          "async": true,
+          "params": [
+            "leftId: string",
+            "rightId: string",
+            "opts?: JunctionFilterOptions"
+          ],
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "setLinks",
+          "async": true,
+          "params": [
+            "leftId: string",
+            "rightIds: string[]",
+            "opts?: JunctionAttachOptions"
+          ],
+          "returns": "Promise<void>"
+        }
+      ],
       "surfaces": [],
       "relationshipFeatures": [],
       "tags": [],
@@ -265,6 +600,244 @@
         "toPlainObject",
         "toPublicJSON"
       ],
+      "methodSignatures": [
+        {
+          "name": "_setLoadedRelationship",
+          "params": [
+            "fieldName: string",
+            "value: any"
+          ],
+          "returns": "void"
+        },
+        {
+          "name": "classifyConstraintError",
+          "static": true,
+          "params": [
+            "message: string"
+          ],
+          "returns": "'unique' | 'not_null' | null"
+        },
+        {
+          "name": "clearEmbeddings",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "describe",
+          "async": true,
+          "params": [
+            "options?: AiOperationOptions"
+          ],
+          "returns": "any"
+        },
+        {
+          "name": "do",
+          "async": true,
+          "params": [
+            "instructions: string",
+            "options?: AiOperationOptions"
+          ],
+          "returns": "any"
+        },
+        {
+          "name": "executeToolCall",
+          "async": true,
+          "params": [
+            "toolCall: ToolCall"
+          ],
+          "returns": "Promise<ToolCallResult>"
+        },
+        {
+          "name": "forget",
+          "async": true,
+          "params": [
+            "options: object"
+          ],
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "forgetScope",
+          "async": true,
+          "params": [
+            "options: object"
+          ],
+          "returns": "Promise<number>"
+        },
+        {
+          "name": "generateEmbeddings",
+          "async": true,
+          "params": [
+            "options?: GenerateEmbeddingsOptions"
+          ],
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "getAvailableTools",
+          "returns": "AITool[]"
+        },
+        {
+          "name": "getEmbedding",
+          "async": true,
+          "params": [
+            "fieldName: string",
+            "model?: string"
+          ],
+          "returns": "Promise<number[] | null>"
+        },
+        {
+          "name": "getFields",
+          "async": true,
+          "returns": "Promise<any>"
+        },
+        {
+          "name": "getId",
+          "async": true,
+          "returns": "any"
+        },
+        {
+          "name": "getRelated",
+          "async": true,
+          "params": [
+            "fieldName: string",
+            "opts?: LoadRelatedOptions"
+          ],
+          "returns": "Promise<any>"
+        },
+        {
+          "name": "getSavedId",
+          "async": true,
+          "returns": "any"
+        },
+        {
+          "name": "getSlug",
+          "async": true,
+          "returns": "any"
+        },
+        {
+          "name": "hasStaleEmbeddings",
+          "async": true,
+          "returns": "Promise<boolean>"
+        },
+        {
+          "name": "initialize",
+          "async": true,
+          "returns": "Promise"
+        },
+        {
+          "name": "is",
+          "async": true,
+          "params": [
+            "criteria: string",
+            "options?: AiOperationOptions"
+          ],
+          "returns": "any"
+        },
+        {
+          "name": "isRelatedLoaded",
+          "params": [
+            "fieldName: string"
+          ],
+          "returns": "boolean"
+        },
+        {
+          "name": "isSaved",
+          "async": true,
+          "returns": "any"
+        },
+        {
+          "name": "loadDataFromDb",
+          "async": true,
+          "params": [
+            "data: Record<string>"
+          ],
+          "returns": "any"
+        },
+        {
+          "name": "loadFromId",
+          "async": true,
+          "returns": "any"
+        },
+        {
+          "name": "loadFromSlug",
+          "async": true,
+          "returns": "any"
+        },
+        {
+          "name": "loadRelated",
+          "async": true,
+          "params": [
+            "fieldName: string",
+            "opts?: LoadRelatedOptions"
+          ],
+          "returns": "Promise<any>"
+        },
+        {
+          "name": "loadRelatedMany",
+          "async": true,
+          "params": [
+            "fieldName: string",
+            "opts?: LoadRelatedOptions"
+          ],
+          "returns": "Promise<any[]>"
+        },
+        {
+          "name": "markAsPersisted",
+          "returns": "void"
+        },
+        {
+          "name": "recall",
+          "async": true,
+          "params": [
+            "options: object"
+          ],
+          "returns": "Promise"
+        },
+        {
+          "name": "recallAll",
+          "async": true,
+          "params": [
+            "options?: object"
+          ],
+          "returns": "Promise<Map<string>>"
+        },
+        {
+          "name": "remember",
+          "async": true,
+          "params": [
+            "options: object"
+          ],
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "requireInsertOnSave",
+          "returns": "void"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "returns": "any"
+        },
+        {
+          "name": "toJSON",
+          "returns": "any"
+        },
+        {
+          "name": "toPlainObject",
+          "returns": "Record<string>"
+        },
+        {
+          "name": "toPublicJSON",
+          "params": [
+            "options?: PublicJsonOptions"
+          ],
+          "returns": "Record<string>"
+        }
+      ],
       "surfaces": [],
       "relationshipFeatures": [
         "uuidColumns"
@@ -297,13 +870,21 @@
         {
           "name": "sortOrder",
           "type": "integer",
-          "required": false
+          "required": false,
+          "default": 0
         }
       ],
       "relationships": [],
       "methods": [
         "hydrate"
       ],
+      "methodSignatures": [
+        {
+          "name": "hydrate",
+          "async": true,
+          "returns": "Promise<T | null>"
+        }
+      ],
       "surfaces": [],
       "relationshipFeatures": [
         "SmrtPolymorphicAssociation"
@@ -330,7 +911,7 @@
     "polymorphicAssociations": 1,
     "uuidColumns": 3
   },
-  "agentDoc": "# @happyvertical/smrt-core\n\nORM, code generation, AI integration, and the DispatchBus. Everything else builds on this.\n\nKey surfaces are `SmrtObject`, `SmrtCollection`, `ObjectRegistry`,\n`DispatchBus`, `GlobalInterceptors`, and `LearningMemory`; this file documents\ntheir invariants and source locations, and the module docs below cover the\nper-subsystem semantics.\n\n## Modules\n\nSubsystem semantics live in sibling module docs — read the one for the\nsubsystem you are editing. This file keeps what holds across all of them.\n\n| Module | Scope | Module doc |\n|---|---|---|\n| `src/change-feed.ts` | the adapter-agnostic change-observation spine — `_smrt_changes`, cursors, table versions, generated `_changes` routes, retention | [agents/change-feed.md](agents/change-feed.md) |\n| `src/change-signals.ts` + the generated `_events` SSE route | the push companion to the change feed — the signal bus, cross-replica fan-out, the SSE route, and its documented gaps | [agents/change-signals.md](agents/change-signals.md) |\n| `src/generators/` + `src/vite-plugin/web-collections.ts` | REST/CLI/MCP/web-collection generation, the `manifestHash` emission sites, and generated conditional-GET / ETag v2 semantics | [agents/generators.md](agents/generators.md) |\n\n## SmrtObject Lifecycle\n\n`constructor(options)` → `initialize()` → ready for `save()`/`delete()`/`loadFromId()`\n\n- `initialize()`: loads field initializers, applies option values (options override initializers), loads from DB if id/slug provided\n- `save()`: upsert with STI validation, interceptor execution, auto-embeddings. Persisted objects (`isPersisted` — set by DB hydration and successful saves) upsert on `['id']` so natural-key edits (e.g. slug renames) update in place; new objects upsert on the natural-key conflict columns for ingestion-style dedup (#1472)\n- `is(criteria)` / `do(instructions)` / `describe()`: AI operations via function calling. They inject the object's own `toPublicJSON()` (sensitive fields stripped) as a \"content body\" so the model reasons over the instance. Options: `includeData: false` skips injection (for callers that already curate the relevant fields into the instruction); `maxDataLength` overrides the truncation budget. Neither key is forwarded to `ai.message()`. (#1567)\n- `getSlug()`: auto-generates from name → title → label → id\n- `loadRelated(fieldName)`: lazy-loads relationships (cached in `_loadedRelationships` Map)\n\n## LearningMemory (#1886)\n\n`LearningMemory` provides tenant-isolated, confidence-scored recall over\n`_smrt_contexts` plus optional injected semantic search. `capture()` reinforces\nsuccesses and decays failures while updating outcome counters; `recall()`\napplies confidence, expiry, time-decay, and hierarchical-scope filters and\nrefreshes `last_used_at`. Keep semantic search behind the\n`SmrtCollection.semanticSearch`-compatible injection boundary.\n\n## SmrtCollection Query\n\n```typescript\nawait collection.list({\n  where: { status: 'active', 'price >': 10 },\n  limit: 50, offset: 0, orderBy: 'created_at DESC'\n});\n```\n\nProjection primitive (#1902): pass `select: ['id', 'title', 'tenantId']` to\n`list()` when an admin/list workflow needs compact rows. `select` uses SMRT\nfield names, maps them to DB columns internally, and returns plain objects keyed\nby the same SMRT field names without hydrating `SmrtObject` instances. It\ncomposes with `where`, `orderBy`, `limit`, and `offset`; `beforeList`\ninterceptors still run. It is for column-backed fields only and cannot combine\nwith `include`/relationship eager loading.\n\n`list()` and `query()` hydrate model instances serially in result order because\nan `initialize()` hook may query through the same transaction-bound PostgreSQL\nclient. Keep this serialization invariant; use `select` when callers need plain\nrows without model hydration.\n\n**WHERE operators**: `=`, `>`, `<`, `>=`, `<=`, `!=`, `in`, `not in`, `like`.\nArrays auto-detect `IN`. NULL is a value, not an operator: `{ deletedAt: null }`\nrenders `IS NULL` and `{ 'deletedAt !=': null }` renders `IS NOT NULL`.\n\nThis list is the set `@happyvertical/sql`'s `buildWhere` can execute, and\n`convertWhereKeys` accepts nothing outside it — an operator accepted here but\nunknown there fails inside the query builder, after the API said the query was\nvalid (#2276). Two entries were removed for that reason and now reject at the\nAPI boundary: `contains` (never existed in the SQL layer; use `like` with\nexplicit wildcards) and dot-notation JSON paths such as `metadata.userId` (never\nrewritten into an extraction expression, so they reached SQL as qualified column\nreferences). Re-adding either requires the query builder to support it first;\n`src/__tests__/issue-2276-where-contract.test.ts` executes every accepted\noperator against a database to keep the two in step.\n\nSTI child collections auto-filter by `_meta_type`.\n\n## Bounded Collection Read Plans\n\nUse `executeCollectionReadPlan()` when one operation needs several independent\ncollections. It bounds top-level `collection.list()` concurrency while keeping\nall reads on the normal registry/collection path. Callers must choose an\nexplicit positive `maxConcurrency` and pass their normal shared\n`collectionOptions` when database or tenant context matters.\n\nThe executor deliberately does not compose SQL, cache the plan, or change pool\ndefaults. On failure it stops starting queued entries, drains operations already\nin flight, and rethrows the first error.\n\n## Object Memory & Semantic Search\n\nTwo persistence primitives every `SmrtObject`/`SmrtCollection` inherits — load-bearing for learning agents, usable by any object. Full guide: `docs/content/core.md` → \"Context Memory System\".\n\n- **Context memory** (`remember`/`recall`/`recallAll`/`forget`/`forgetScope`, table `_smrt_contexts`): stores any JSON value keyed by `(owner_class, owner_id, scope, key, version)` with a `confidence` score (0–1) and a stored `expiresAt` (metadata — `recall()` does **not** filter expired rows; expiry is caller-managed). `recall()` returns the highest-confidence match with an optional `minConfidence` floor and **opt-in** hierarchical scope fallback (`includeAncestors: true` → `'a/b/c' → 'a/b' → 'a' → 'global'`; default off); `recallAll()` returns a `Map`. Typical use: cache a learned strategy (e.g. a working selector per host) and reuse it across sessions. `success_count`/`failure_count` columns exist for outcome-weighting: `SmrtObject.remember()` leaves them untouched, `SmrtCollection.remember()` resets them to zero, and neither recall path updates them. `LearningMemory` is the layer that maintains them (and that does filter expired rows).\n- **Semantic search** (on `SmrtCollection`, table `_smrt_embeddings`): `semanticSearch(query)`, `findSimilar(object)`, `findSimilarToEmbedding(vector)` — cosine ranking over embeddings of the fields declared in `@smrt({ embeddings })`. Native pgvector/HNSW when configured, in-memory `CosineSimilarity` fallback otherwise; default local model `Xenova/bge-base-en-v1.5` (768-dim) or AI `text-embedding-3-small`. Hits hydrate via `list({ 'id in': … })`, so `@TenantScoped` isolation applies to results.\n\n## @smrt() Decorator Options\n\nKey options: `tableName`, `tableStrategy` ('cti'|'sti'), `conflictColumns`, `api`/`mcp`/`cli` (generation config), `ai` (callable methods), `hooks` (beforeSave/afterSave/beforeDelete/afterDelete), `embeddings` (auto-generate), `tenantScoped`, `agent`, `ui` (`{ icon, label, description }` — nav/help hints round-tripped through the manifest as plain data; `description` is the object-level seed for form-level help, #2046).\n\nRegistration sets `SMRT_TABLE_NAME` static property (survives minification).\n\n## @field() UI hints (#2046)\n\n`@field({ ui: { basic, group, order, locked } })` — a static, presentation-only\nseed for the field-policy rail (epic #2045). Carried in the manifest under the\nfield's `_meta.ui` (never a top-level `FieldDefinition` key), readable at\nruntime via `getAllFields()` at `field._meta.ui`, and emitted (sanitized) with\n`description` into generated web-collection definitions and browser MCP tool\nschemas. No schema/persistence/security effect — `sensitive`/`readPermission`\nstay the security rail, and `sensitive`/`transient` fields never emit to the\nclient at all.\n\n## Domain Knowledge Artifacts\n\n`smrtPlugin()` writes runtime manifests and agent/developer knowledge artifacts:\n\n- local dev/build: `.smrt/manifest.json` and `.smrt/smrt-knowledge.json`\n- package build: `dist/manifest.json` and `dist/smrt-knowledge.json`\n\nKeep `manifest.json` runtime-focused. `smrt-knowledge.json` is the deterministic\nagent contract for downstream review and architecture tools.\n\nConfig precedence for knowledge is defaults → top-level `knowledge` in\n`smrt.config.ts` → `packages[packageName].knowledge` → plugin option →\nobject-level `@smrt({ knowledge })`.\n\nObject-level `knowledge: false` excludes an object from authored context only;\nit must not change runtime manifest registration. Use\n`knowledge: { tags, summary, risks }` for review-sensitive domain objects.\n\nHTTP knowledge routes are disabled by default. If `knowledge.api.enabled` is\ntrue, generated SvelteKit routes must stay GET-only and guarded by dev mode or\nadmin auth.\n\n## DispatchBus\n\n- `emit(signalType, payload, metadata)` → creates persistent Dispatch record\n- `on(pattern, handler)` → in-memory handler (immediate)\n- `subscribe({ signalType, subscriber })` → persistent subscription (survives restarts)\n- `process(subscriberName, handler)` → process pending dispatches\n- Wildcards: `campaign.*` matches `campaign.completed` (single segment only)\n- Tables: `_smrt_dispatch`, `_smrt_dispatch_subscriptions`\n- Status: `pending → processing → completed` (or `failed`)\n\n## Single Table Inheritance (STI)\n\n- Base: `@smrt({ tableStrategy: 'sti' })` — children inherit, share one table\n- Discriminator: `_meta_type` column with qualified names (`@happyvertical/smrt-content:Article`)\n- Child fields: `@meta()` decorator → stored in `_meta_data` JSONB (not as columns)\n- Polymorphic queries: collection loads `_meta_type`, creates correct subclass dynamically\n- Validation: fail-fast on save if `_meta_type` missing or mismatched\n\n## Child Accessors (R10)\n\n`src/child-accessors.ts` installs a consistent `get<FieldName>()` instance method for every `@oneToMany` field at `@smrt()` registration time (e.g. `@oneToMany('OrderItem') items` → `order.getItems()`), delegating to `loadRelatedMany`. Two invariants:\n\n- **Additive** — never overwrites a hand-rolled method of the same name (checks the whole prototype chain). `Profile.getMetadata()` (key-value) and `ProfileRelationship.getTerms()` are preserved.\n- **Runtime-only** — attached to the prototype, invisible to the build-time manifest, so it never leaks into the REST/CLI/MCP surface.\n\nWhen the target declares multiple FKs back to the parent, annotate `@oneToMany(Target, { foreignKey: '<inverseField>' })`; `loadRelatedMany` and the eager `include:` loader both honor it (else first-match).\n\n## Vite Plugin\n\n```typescript\n// vite.config.ts — required for @smrt() decorators (Vite 8+, oxc transform)\nexport default defineConfig({\n  oxc: {\n    decorator: {\n      legacy: true,\n      emitDecoratorMetadata: true,\n    },\n  },\n});\n```\n\nUnder Vite 8 the oxc transform does not honor the pre-Vite-8 `esbuild.tsconfigRaw`\nrecipe (or tsconfig `experimentalDecorators` reached through SvelteKit's\n`extends \"./.svelte-kit/tsconfig.json\"` chain), so that recipe throws\n`SyntaxError: Invalid or unexpected token` on the first SSR request. Configure\ndecorators through `oxc.decorator` instead. Consumers still pinned on vite<8 need\nthe legacy `esbuild.tsconfigRaw` form with `experimentalDecorators: true,\nemitDecoratorMetadata: true`.\n\n## Gotchas\n\n- **Filesystem support is a lazy boundary (#1979)**: `SmrtClass` acquires `options.fs` adapters via `createFilesystemAdapter()` (`src/filesystem-loader.ts`), never a static `@happyvertical/files` import — the files SDK statically pulls @aws-sdk/client-s3 and reaches googleapis, and a static edge here would land it in every downstream SSR bundle. Node/tsx/vite-dev runtimes resolve it on first use; fully-bundled deployments import `@happyvertical/smrt-core/filesystem` at startup. Use `importOptionalDependency()` (`src/lazy-external.ts`) for any similar optional heavyweight dependency.\n- **Never override toJSON()** — handles STI discriminator + meta field extraction. Use `transformJSON()`\n- **Property init order**: TypeScript initializers run first, then `initialize()` applies option values (options win)\n- **No runtime schema creation**: application tables must be prepared explicitly via migrations/tooling; runtime only verifies and fails clearly\n- **Retry logic**: `db.get()` (3 retries, 250ms) and `db.upsert()` (3 retries, 500ms) have built-in retry\n- **Field caching**: `_cachedFields` populated during `Collection.create()` — eliminates async `getFields()` per query\n- **Smart cloning**: arrays/objects shallow-cloned in property init to prevent aliasing (Issue #22)\n- **Table verification cache**: `isTableVerified(dbUrl, tableName)` avoids redundant `tableExists()` calls\n- **Manifest required**: build-time AST scanning creates manifest. Without vitest plugin → \"No field metadata\"\n- **ManifestBuilder fails on scanner errors**: every production manifest path\n  must abort before adapting partial scan results. A syntax error or unresolved\n  `@smrt()` config spread cannot be allowed to emit a default-open manifest.\n- **Vite plugin loads scanner from `dist/` first**: `src/vite-plugin/import-build-aware.ts` prefers `dist/` when it exists on disk; it only falls back to `src/` on fresh clones. So if you edit `src/scanner/*.ts` or `src/schema/generator.ts` and want those edits reflected in consumer manifest generation, you must rebuild (`pnpm build` or have `pnpm dev` / `pnpm build:watch` running in core). This is intentional — sniffing `.ts` vs `.js` via `import.meta.url` was non-deterministic under tsx and broke 12–13 publishes (#1139).\n- **Bundled registry ownership**: flattened production bundles can rewrite constructor names and make decorator-time stack inference attribute provider code to the consumer. Generated registration repairs identity only from the exact imported constructor plus an explicit package and isolated one-object manifest; never infer ownership from output paths, simple names, or table names. Distinct packages may export the same simple name under qualified keys. The production-consumer gate lives in `packages/bundle-gate/src/__tests__/registry-identity.spec.ts` (#2308).\n",
+  "agentDoc": "# @happyvertical/smrt-core\n\nORM, code generation, AI integration, and the DispatchBus. Everything else builds on this.\n\nKey surfaces are `SmrtObject`, `SmrtCollection`, `ObjectRegistry`,\n`DispatchBus`, `GlobalInterceptors`, and `LearningMemory`; this file documents\ntheir invariants and source locations, and the module docs below cover the\nper-subsystem semantics.\n\n## Modules\n\nSubsystem semantics live in sibling module docs — read the one for the\nsubsystem you are editing. This file keeps what holds across all of them.\n\n| Module | Scope | Module doc |\n|---|---|---|\n| `src/change-feed.ts` | the adapter-agnostic change-observation spine — `_smrt_changes`, cursors, table versions, generated `_changes` routes, retention | [agents/change-feed.md](agents/change-feed.md) |\n| `src/change-signals.ts` + the generated `_events` SSE route | the push companion to the change feed — the signal bus, cross-replica fan-out, the SSE route, and its documented gaps | [agents/change-signals.md](agents/change-signals.md) |\n| `src/generators/` + `src/vite-plugin/web-collections.ts` | REST/CLI/MCP/web-collection generation, the `manifestHash` emission sites, and generated conditional-GET / ETag v2 semantics | [agents/generators.md](agents/generators.md) |\n\n## SmrtObject Lifecycle\n\n`constructor(options)` → `initialize()` → ready for `save()`/`delete()`/`loadFromId()`\n\n- `initialize()`: loads field initializers, applies option values (options override initializers), loads from DB if id/slug provided\n- `save()`: upsert with STI validation, interceptor execution, auto-embeddings. Persisted objects (`isPersisted` — set by DB hydration and successful saves) upsert on `['id']` so natural-key edits (e.g. slug renames) update in place; new objects upsert on the natural-key conflict columns for ingestion-style dedup (#1472)\n- `is(criteria)` / `do(instructions)` / `describe()`: AI operations via function calling. They inject the object's own `toPublicJSON()` (sensitive fields stripped) as a \"content body\" so the model reasons over the instance. Options: `includeData: false` skips injection (for callers that already curate the relevant fields into the instruction); `maxDataLength` overrides the truncation budget. Neither key is forwarded to `ai.message()`. (#1567)\n- `getSlug()`: auto-generates from name → title → label → id\n- `loadRelated(fieldName)`: lazy-loads relationships (cached in `_loadedRelationships` Map)\n\n## LearningMemory (#1886)\n\n`LearningMemory` provides tenant-isolated, confidence-scored recall over\n`_smrt_contexts` plus optional injected semantic search. `capture()` reinforces\nsuccesses and decays failures while updating outcome counters; `recall()`\napplies confidence, expiry, time-decay, and hierarchical-scope filters and\nrefreshes `last_used_at`. Keep semantic search behind the\n`SmrtCollection.semanticSearch`-compatible injection boundary.\n\n## SmrtCollection Query\n\n```typescript\nawait collection.list({\n  where: { status: 'active', 'price >': 10 },\n  limit: 50, offset: 0, orderBy: 'created_at DESC'\n});\n```\n\nProjection primitive (#1902): pass `select: ['id', 'title', 'tenantId']` to\n`list()` when an admin/list workflow needs compact rows. `select` uses SMRT\nfield names, maps them to DB columns internally, and returns plain objects keyed\nby the same SMRT field names without hydrating `SmrtObject` instances. It\ncomposes with `where`, `orderBy`, `limit`, and `offset`; `beforeList`\ninterceptors still run. It is for column-backed fields only and cannot combine\nwith `include`/relationship eager loading.\n\n`list()` and `query()` hydrate model instances serially in result order because\nan `initialize()` hook may query through the same transaction-bound PostgreSQL\nclient. Keep this serialization invariant; use `select` when callers need plain\nrows without model hydration.\n\n**WHERE operators**: `=`, `>`, `<`, `>=`, `<=`, `!=`, `in`, `not in`, `like`.\nArrays auto-detect `IN`. NULL is a value, not an operator: `{ deletedAt: null }`\nrenders `IS NULL` and `{ 'deletedAt !=': null }` renders `IS NOT NULL`.\n\nThis list is the set `@happyvertical/sql`'s `buildWhere` can execute, and\n`convertWhereKeys` accepts nothing outside it — an operator accepted here but\nunknown there fails inside the query builder, after the API said the query was\nvalid (#2276). Two entries were removed for that reason and now reject at the\nAPI boundary: `contains` (never existed in the SQL layer; use `like` with\nexplicit wildcards) and dot-notation JSON paths such as `metadata.userId` (never\nrewritten into an extraction expression, so they reached SQL as qualified column\nreferences). Re-adding either requires the query builder to support it first;\n`src/__tests__/issue-2276-where-contract.test.ts` executes every accepted\noperator against a database to keep the two in step.\n\nSTI child collections auto-filter by `_meta_type`.\n\n## Bounded Collection Read Plans\n\nUse `executeCollectionReadPlan()` when one operation needs several independent\ncollections. It bounds top-level `collection.list()` concurrency while keeping\nall reads on the normal registry/collection path. Callers must choose an\nexplicit positive `maxConcurrency` and pass their normal shared\n`collectionOptions` when database or tenant context matters.\n\nThe executor deliberately does not compose SQL, cache the plan, or change pool\ndefaults. On failure it stops starting queued entries, drains operations already\nin flight, and rethrows the first error.\n\n## Object Memory & Semantic Search\n\nTwo persistence primitives every `SmrtObject`/`SmrtCollection` inherits — load-bearing for learning agents, usable by any object. Full guide: `docs/content/core.md` → \"Context Memory System\".\n\n- **Context memory** (`remember`/`recall`/`recallAll`/`forget`/`forgetScope`, table `_smrt_contexts`): stores any JSON value keyed by `(owner_class, owner_id, scope, key, version)` with a `confidence` score (0–1) and a stored `expiresAt` (metadata — `recall()` does **not** filter expired rows; expiry is caller-managed). `recall()` returns the highest-confidence match with an optional `minConfidence` floor and **opt-in** hierarchical scope fallback (`includeAncestors: true` → `'a/b/c' → 'a/b' → 'a' → 'global'`; default off); `recallAll()` returns a `Map`. Typical use: cache a learned strategy (e.g. a working selector per host) and reuse it across sessions. `success_count`/`failure_count` columns exist for outcome-weighting: `SmrtObject.remember()` leaves them untouched, `SmrtCollection.remember()` resets them to zero, and neither recall path updates them. `LearningMemory` is the layer that maintains them (and that does filter expired rows).\n- **Semantic search** (on `SmrtCollection`, table `_smrt_embeddings`): `semanticSearch(query)`, `findSimilar(object)`, `findSimilarToEmbedding(vector)` — cosine ranking over embeddings of the fields declared in `@smrt({ embeddings })`. Native pgvector/HNSW when configured, in-memory `CosineSimilarity` fallback otherwise; default local model `Xenova/bge-base-en-v1.5` (768-dim) or AI `text-embedding-3-small`. Hits hydrate via `list({ 'id in': … })`, so `@TenantScoped` isolation applies to results.\n\n## @smrt() Decorator Options\n\nKey options: `tableName`, `tableStrategy` ('cti'|'sti'), `conflictColumns`, `api`/`mcp`/`cli` (generation config), `ai` (callable methods), `hooks` (beforeSave/afterSave/beforeDelete/afterDelete), `embeddings` (auto-generate), `tenantScoped`, `agent`, `ui` (`{ icon, label, description }` — nav/help hints round-tripped through the manifest as plain data; `description` is the object-level seed for form-level help, #2046).\n\nRegistration sets `SMRT_TABLE_NAME` static property (survives minification).\n\n## @field() UI hints (#2046)\n\n`@field({ ui: { basic, group, order, locked } })` — a static, presentation-only\nseed for the field-policy rail (epic #2045). Carried in the manifest under the\nfield's `_meta.ui` (never a top-level `FieldDefinition` key), readable at\nruntime via `getAllFields()` at `field._meta.ui`, and emitted (sanitized) with\n`description` into generated web-collection definitions and browser MCP tool\nschemas. No schema/persistence/security effect — `sensitive`/`readPermission`\nstay the security rail, and `sensitive`/`transient` fields never emit to the\nclient at all.\n\n## Domain Knowledge Artifacts\n\n`smrtPlugin()` writes runtime manifests and agent/developer knowledge artifacts:\n\n- local dev/build: `.smrt/manifest.json` and `.smrt/smrt-knowledge.json`\n- package build: `dist/manifest.json` and `dist/smrt-knowledge.json`\n\nKeep `manifest.json` runtime-focused. `smrt-knowledge.json` is the deterministic\nagent contract for downstream review and architecture tools.\n\nThe schema-version-1 object projection is additive and high-signal: it retains\nnormalized tenant mode/field, explicit `cti`/`sti` strategy, conflict columns,\nmethod signatures, and field defaults/constraints/readonly/transient flags.\nSensitive fields are removed before both `fields` and `relationships` are\nderived, including legacy flags stored under `_meta`; matching field and\nsnake-case column names are also removed from projected conflict columns, and a\nsensitive custom tenant field is omitted while retaining scope and mode.\nGenerated artifacts assert this boundary with `sensitiveFieldsExcluded: true`;\nthe optional marker keeps schema version 1 additive while letting readers\nidentify older artifacts that require raw-manifest corroboration.\n\nConfig precedence for knowledge is defaults → top-level `knowledge` in\n`smrt.config.ts` → `packages[packageName].knowledge` → plugin option →\nobject-level `@smrt({ knowledge })`.\n\nObject-level `knowledge: false` excludes an object from authored context only;\nit must not change runtime manifest registration. Use\n`knowledge: { tags, summary, risks }` for review-sensitive domain objects.\n\nHTTP knowledge routes are disabled by default. If `knowledge.api.enabled` is\ntrue, generated SvelteKit routes must stay GET-only and guarded by dev mode or\nadmin auth.\n\n## DispatchBus\n\n- `emit(signalType, payload, metadata)` → creates persistent Dispatch record\n- `on(pattern, handler)` → in-memory handler (immediate)\n- `subscribe({ signalType, subscriber })` → persistent subscription (survives restarts)\n- `process(subscriberName, handler)` → process pending dispatches\n- Wildcards: `campaign.*` matches `campaign.completed` (single segment only)\n- Tables: `_smrt_dispatch`, `_smrt_dispatch_subscriptions`\n- Status: `pending → processing → completed` (or `failed`)\n\n## Single Table Inheritance (STI)\n\n- Base: `@smrt({ tableStrategy: 'sti' })` — children inherit, share one table\n- Discriminator: `_meta_type` column with qualified names (`@happyvertical/smrt-content:Article`)\n- Child fields: `@meta()` decorator → stored in `_meta_data` JSONB (not as columns)\n- Polymorphic queries: collection loads `_meta_type`, creates correct subclass dynamically\n- Validation: fail-fast on save if `_meta_type` missing or mismatched\n\n## Child Accessors (R10)\n\n`src/child-accessors.ts` installs a consistent `get<FieldName>()` instance method for every `@oneToMany` field at `@smrt()` registration time (e.g. `@oneToMany('OrderItem') items` → `order.getItems()`), delegating to `loadRelatedMany`. Two invariants:\n\n- **Additive** — never overwrites a hand-rolled method of the same name (checks the whole prototype chain). `Profile.getMetadata()` (key-value) and `ProfileRelationship.getTerms()` are preserved.\n- **Runtime-only** — attached to the prototype, invisible to the build-time manifest, so it never leaks into the REST/CLI/MCP surface.\n\nWhen the target declares multiple FKs back to the parent, annotate `@oneToMany(Target, { foreignKey: '<inverseField>' })`; `loadRelatedMany` and the eager `include:` loader both honor it (else first-match).\n\n## Vite Plugin\n\n```typescript\n// vite.config.ts — required for @smrt() decorators (Vite 8+, oxc transform)\nexport default defineConfig({\n  oxc: {\n    decorator: {\n      legacy: true,\n      emitDecoratorMetadata: true,\n    },\n  },\n});\n```\n\nUnder Vite 8 the oxc transform does not honor the pre-Vite-8 `esbuild.tsconfigRaw`\nrecipe (or tsconfig `experimentalDecorators` reached through SvelteKit's\n`extends \"./.svelte-kit/tsconfig.json\"` chain), so that recipe throws\n`SyntaxError: Invalid or unexpected token` on the first SSR request. Configure\ndecorators through `oxc.decorator` instead. Consumers still pinned on vite<8 need\nthe legacy `esbuild.tsconfigRaw` form with `experimentalDecorators: true,\nemitDecoratorMetadata: true`.\n\n## Gotchas\n\n- **Filesystem support is a lazy boundary (#1979)**: `SmrtClass` acquires `options.fs` adapters via `createFilesystemAdapter()` (`src/filesystem-loader.ts`), never a static `@happyvertical/files` import — the files SDK statically pulls @aws-sdk/client-s3 and reaches googleapis, and a static edge here would land it in every downstream SSR bundle. Node/tsx/vite-dev runtimes resolve it on first use; fully-bundled deployments import `@happyvertical/smrt-core/filesystem` at startup. Use `importOptionalDependency()` (`src/lazy-external.ts`) for any similar optional heavyweight dependency.\n- **Never override toJSON()** — handles STI discriminator + meta field extraction. Use `transformJSON()`\n- **Property init order**: TypeScript initializers run first, then `initialize()` applies option values (options win)\n- **No runtime schema creation**: application tables must be prepared explicitly via migrations/tooling; runtime only verifies and fails clearly\n- **Retry logic**: `db.get()` (3 retries, 250ms) and `db.upsert()` (3 retries, 500ms) have built-in retry\n- **Field caching**: `_cachedFields` populated during `Collection.create()` — eliminates async `getFields()` per query\n- **Smart cloning**: arrays/objects shallow-cloned in property init to prevent aliasing (Issue #22)\n- **Table verification cache**: `isTableVerified(dbUrl, tableName)` avoids redundant `tableExists()` calls\n- **Manifest required**: build-time AST scanning creates manifest. Without vitest plugin → \"No field metadata\"\n- **ManifestBuilder fails on scanner errors**: every production manifest path\n  must abort before adapting partial scan results. A syntax error or unresolved\n  `@smrt()` config spread cannot be allowed to emit a default-open manifest.\n- **Vite plugin loads scanner from `dist/` first**: `src/vite-plugin/import-build-aware.ts` prefers `dist/` when it exists on disk; it only falls back to `src/` on fresh clones. So if you edit `src/scanner/*.ts` or `src/schema/generator.ts` and want those edits reflected in consumer manifest generation, you must rebuild (`pnpm build` or have `pnpm dev` / `pnpm build:watch` running in core). This is intentional — sniffing `.ts` vs `.js` via `import.meta.url` was non-deterministic under tsx and broke 12–13 publishes (#1139).\n- **Bundled registry ownership**: flattened production bundles can rewrite constructor names and make decorator-time stack inference attribute provider code to the consumer. Generated registration repairs identity only from the exact imported constructor plus an explicit package and isolated one-object manifest; never infer ownership from output paths, simple names, or table names. Distinct packages may export the same simple name under qualified keys. The production-consumer gate lives in `packages/bundle-gate/src/__tests__/registry-identity.spec.ts` (#2308).\n",
   "moduleDocs": [
     {
       "path": "agents/change-feed.md",