@happyvertical/smrt-core 0.55.0 → 0.55.2

package/dist/smrt-knowledge.json

@@ -3,13 +3,13 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-core",
-  "packageVersion": "0.55.0",
+  "packageVersion": "0.55.2",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "38ecb3aaf66f5eacf4fbccdd3398efc603c1eb7a2c8164f607ddf8655d9b5148",
-    "packageJson": "915ce056ef41ac7d92eee3a5a9a8b9d99b15ec49408de1a3a13459cb43136182",
-    "agents": "a8d1918713f35e101c7d937403eff481bd89e51657c77474afe0343270338d64",
+    "manifest": "e73abc58c7f470eaf362cbe6c226d78155b82926c60cbdc8215492bd4c15b3df",
+    "packageJson": "42b1b4b740965693dfaceb4c2e053ef3aaafb0b8cdae6a0712d0eb2acb78e688",
+    "agents": "18be0a7299730add4b09bf14144ab217f7f1fb60dd68afbe08be775266ead19f",
     "moduleDoc:agents/object-runtime.md": "652352cdf1eddd0dcc91f6589b8241d9d99581f54bcc2318520a3ff97cd22cf5",
     "moduleDoc:agents/revision-guard.md": "aa6b1ddb5b6b49fa27ebbe575ec7fcd6d5ceb35ee25acc702f877a226eb9a99a",
     "moduleDoc:agents/collection-reads.md": "e5bb79b59c17e79a85a71580a019e6b0b641e498ac4d850073fd5ad634b57cb7",
@@ -18,13 +18,14 @@
     "moduleDoc:agents/schema-paths.md": "e56af17a7e32d0529b47bcdd268ce4787405bf1a16b37142846ba2db4e415bf2",
     "moduleDoc:agents/change-feed.md": "c3d6206758dd1d2e0475177e1938fb7d7b6cfe8a6c4d3c3b56ef62bc7bc7739d",
     "moduleDoc:agents/change-signals.md": "a2dbe7077483b5a19bd5ea9589b5a08fe847377c8e05d01d57f813c6d9cbc28b",
-    "moduleDoc:agents/generators.md": "569b81ab72a1b6eeae6b595ae7992f552b553ebc31309c2962074d54d8048e8c",
-    "moduleDoc:agents/build-knowledge.md": "8426577f7abe55cdc0c966606e528dcba60540f1e925b4e4cc14cfdd26980314",
+    "moduleDoc:agents/generators.md": "55244a454c2ab8937143600eb785f069d949d75fc4da8bfdf78fb801a59facc8",
+    "moduleDoc:agents/build-knowledge.md": "6bb922abe9c634c3722b7d33ed819673d20596562f2f53adcf76c9d2c13307c0",
     "moduleDoc:agents/memory.md": "a86bdf370403d08ecad3be86e341eb322dfe6e6b7a4e8806a6f8be9bf3421da5",
     "moduleDoc:agents/system-diagnostics.md": "b7ccae18ee312bf788d5470f95fa78d3535f1789247d5372e40ca86538290772",
     "moduleDoc:agents/registry-snapshot.md": "6234aa540427396d1dda1825a4641b1072e247187d5ddf413ae46c691344ee30",
     "moduleDoc:agents/model-moves.md": "c64147fee1b7ec242fd1c178e7aea7cc90cafc704dee2738141c7a6d61403cd8",
     "moduleDoc:agents/run-once.md": "0b858c18c78eca5050257a2af06f16de99327e05e0bf9fee9e6277242e7707ef",
+    "moduleDoc:agents/recipes.md": "06b63f309ad7d4d33901b6c6fd974f6535855d7aaab4e99e0a032ffae0fb84aa",
     "moduleDoc:agents/test-types.md": "37c009ae2bd21001d83bba6cfab2047465fe32d5443de12661e24ba7d4e2d613"
   },
   "exports": [
@@ -52,6 +53,7 @@
     "./smrt-knowledge.json",
     "./table-cache",
     "./testing",
+    "./ui-metadata",
     "./utils",
     "./utils/database-url",
     "./utils/import-workspace-module",
@@ -1120,7 +1122,7 @@
     "polymorphicAssociations": 1,
     "uuidColumns": 3
   },
-  "agentDoc": "# @happyvertical/smrt-core\n\nFoundation ORM, registry, schema/code generation, AI integration, and DispatchBus.\nRead the module for the subsystem being edited; root AGENTS covers shared model\nand repository rules.\n\n## Modules\n\n| Source | Scope | Module doc |\n|---|---|---|\n| `src/object.ts`, `src/collection.ts`, `src/child-accessors.ts` | Lifecycle, hydration, operators, STI, child accessors, dispatch | [agents/object-runtime.md](agents/object-runtime.md) |\n| `src/revision-guard.ts` | Guarded writes and PostgreSQL revision precision | [agents/revision-guard.md](agents/revision-guard.md) |\n| `src/collection.ts` | Projections, latest-related, facets, counts, read plans | [agents/collection-reads.md](agents/collection-reads.md) |\n| `src/collection.ts` | Limits, sort whitelist, generated list order | [agents/query-bounds.md](agents/query-bounds.md) |\n| `src/data-query.ts` | Transport-neutral bounded query normalization | [agents/data-query.md](agents/data-query.md) |\n| `src/schema/`, `src/migrations/`, `src/cascade.ts`, `src/system/` | DDL parity, indexes, migrations, delete integrity, retention | [agents/schema-paths.md](agents/schema-paths.md) |\n| `src/postgres-permissions.ts` | Explicit PostgreSQL ACL plans and atomic reconciliation | [deployment permission contract](../../docs/content/postgres-permissions.md) |\n| `src/change-feed.ts` | Durable changes, cursors, table versions, retention | [agents/change-feed.md](agents/change-feed.md) |\n| `src/change-feed-authz.ts` | Consumer table/row change-feed authorization hooks (#3020) | [agents/change-feed.md](agents/change-feed.md) |\n| `src/change-signals.ts` | Signal bus, replica fan-out, SSE | [agents/change-signals.md](agents/change-signals.md) |\n| `src/generators/`, `src/vite-plugin/web-collections.ts` | REST/CLI/MCP generation, manifest hashes, ETags | [agents/generators.md](agents/generators.md) |\n| `src/vite-plugin/`, `src/consumer-plugin/`, `src/knowledge.ts` | Decorator UI hints, knowledge projection, generation snapshots | [agents/build-knowledge.md](agents/build-knowledge.md) |\n| `src/knowledge-graph.ts` | Cross-package knowledge graph merge and freshness check (#2863) — see [standards](../../docs/content/standards.md) | — |\n| `src/object.ts`, `src/collection.ts`, `src/learning/memory.ts` | Context memory and semantic search | [agents/memory.md](agents/memory.md) |\n| `src/system/diagnostics.ts` | SELECT-only `_smrt_*` diagnostics reader behind smrt-dev-mcp runtime tools (#1824) | [agents/system-diagnostics.md](agents/system-diagnostics.md) |\n| `src/system/registry-snapshot.ts` | Sanitized plain-JSON projection of the booted `ObjectRegistry` for the smrt-dev-mcp runtime dev-plane (#1831); never constructors, validators, values, or absolute paths | [agents/registry-snapshot.md](agents/registry-snapshot.md) |\n| `src/registry/qualified-name-aliases.ts`, `src/migrations/qualified-name-aliases.ts` | Model moves: `previousQualifiedNames` aliases, deprecation, doctor counts, opt-in backfill (#3338) | [agents/model-moves.md](agents/model-moves.md) |\n| `src/run-once.ts` | Shared idempotency seam: insert-only claim + caller work in one transaction, replay on retry, typed in-flight/unknown-outcome answers (#3080) | [agents/run-once.md](agents/run-once.md) |\n\n## Cross-module invariants\n\n- `ObjectRegistry` is a `globalThis` singleton so registration survives HMR.\n- Any output that names a database URL (CLI banners, logs, errors) renders it\n  with `redactDatabaseUrl` / `redactDatabaseUrlsInText`\n  (`src/utils/database-url.ts`, #3527): never the password or query string,\n  and never the raw string when it cannot be parsed.\n- Per-class registry work on the hydration path (manifest reconciliation in\n  `ensureManifestLoaded()`, the simple-name index behind `findClass()`) is\n  memoized per registry generation (`src/registry/generation.ts`, #3047). Any\n  new writer of registered classes, their field/method metadata, or loaded\n  manifests must go through the tracked maps or call\n  `bumpRegistryGeneration()`; `issue-3047-hydration-registry-work.test.ts`\n  guards that hydration does not repeat this work per row.\n\n- Production DDL uses manifest generators; `getTestDatabase()` uses registry\n  generators. Keep columns, indexes, FK actions, and runtime conflict targets in\n  parity (`src/schema/schema-path-parity.test.ts`). Every new query predicate\n  needs its index or an explicit reason none is needed.\n- Tenant scoping covers every read and every unique/conflict key. Explicit\n  conflict columns are not rewritten; their author must include tenant scope.\n  A `tenantId` field makes rows tenant-OWNED without any tenancy declaration:\n  the default key leads with `tenant_id`. A new object's natural-key save reads\n  the row its upsert would hit and refuses a different owner\n  (`TENANT_ISOLATION_VIOLATION`) or adopts a same-owner row's id, so\n  `DO UPDATE` never rewrites a primary key or owner. Only an explicit natural\n  key adopts: a slug `getSlug()` derived from `name`/`title`/`label` moves to\n  a free `-2`, `-3`, … slug and INSERTs. See `agents/schema-paths.md`\n  (\"Tenant OWNERSHIP\").\n- Persisted saves use `id` and loaded `updated_at`; new saves use natural keys.\n  Preserve revision compare-and-swap ordering through public `save()`,\n  `claimRevision()`, and transaction APIs. Embedded saves, deletes, and complete\n  `withTransaction()` callbacks share a process-local write queue.\n- Collection model hydration is serial in result order: initialization may query\n  the same transaction-bound PostgreSQL client. Use projections for plain rows.\n- Native DuckDB UUIDs must be cast coherently on read before identity reuse;\n  custom embedded revision paths use `getCanonicalPersistedRow()`. Never replay\n  a mutation to discover result types.\n- `withDatabase(db, callback)` restores only database bindings (including public\n  `options.db`); `withTransaction(callback)` also restores identity/revision\n  metadata after rollback. Do not use a bound instance concurrently.\n- `runOnce({ db, tenantId, actor, token, content }, work)` (`src/run-once.ts`,\n  #3080) claims a key derived from all four inputs — never the token alone,\n  which collapses distinct submissions — via `INSERT ... ON CONFLICT\n  (claim_key) DO NOTHING RETURNING claim_key` into the hand-DDL\n  `_smrt_run_once_claims` system table, and runs `work` in the SAME\n  transaction; a completed claim replays its stored result instead of\n  re-running, a failed `work` rolls the claim back with the transaction, and\n  an unresolved claim raises typed `RunOnceClaimError`\n  (`RUN_ONCE_IN_FLIGHT` / `RUN_ONCE_OUTCOME_UNKNOWN`) rather than guessing.\n  The claim insert must never raise on conflict: PostgreSQL aborts the whole\n  transaction on any raised error, which would take the recovery `SELECT`\n  down with it too — this is why it is `DO NOTHING`, not a plain `INSERT`\n  caught for `isUniqueViolationError`. Completed claims are bounded by\n  `runRetentionSweep()`'s `run-once-claims` task (`system/retention.ts`,\n  `DEFAULT_RETENTION_POLICY.runOnceClaims`, default 30 days on\n  `completed_at`; `in_progress` rows are never matched) — the window is a\n  replay deadline, not just disk hygiene: a token replayed after its claim\n  is swept runs `work()` again. See `agents/run-once.md`.\n- `ensureSystemTables(db, typeHint?)` provisions framework tables idempotently;\n  call it on a base PostgreSQL connection before caller-owned transactions.\n  Bootstrap uses a transaction-scoped advisory lock, taken only when the\n  PostgreSQL schema version is not yet stamped: inside a caller's transaction it\n  is held until that transaction ends (#2868). Application tables still require migrations;\n  runtime table verification checks existence only.\n- Manifest generation fails closed on scanner errors, including unresolved\n  decorator spreads. Never emit partial, default-open registration.\n- Generated registration repairs bundled class identity using the exact imported\n  constructor, explicit package, and isolated one-object manifest. Never infer\n  ownership from paths, simple names, or table names; packages can share names.\n  Consumer regression gate: `packages/bundle-gate/src/__tests__/registry-identity.spec.ts`.\n- Decorator registration trusts a class's stack-derived package only when that\n  package declares the class (stub, own manifest entry, or explicit\n  `packageName`); it then matches the qualified key and never adopts another\n  package's same-named registration. Otherwise a loaded (or the cwd project's)\n  manifest entry describing the declaring file supplies the identity — apps\n  scan workspace-package sources under the app's name (#3110). A class of\n  another known package coexists under its qualified key\n  (`decorator-different-packages-qualified-coexist`); bundled output needs\n  a resolved table that differs first (#3106). Stack\n  attribution skips smrt-core (including source-mapped installed\n  `smrt-core/src` frames, #3109), decorator-helper, and module-runner frames,\n  and drops a frame's Vite `?v=` query (#3490). Library builds stamp each\n  decorated class with `static __smrtPackage__` (own property, read at\n  decoration as its explicit package) and publish `stampsConstructors`; an\n  unstamped class never takes a stamping package's entry by name and table,\n  in either order (#3490, `issue-3490-*.test.ts`, `package-stamp.test.ts`).\n  Qualified names are `@scope/pkg:Class`; the scope is a deliberate\n  discriminator, so manifest generation (`generateManifest`,\n  `applyGenerationPasses`, hence `pnpm build`) throws\n  `CONFIG_UNSCOPED_PACKAGE_NAME` for an unscoped `package.json` name (#3408).\n  Instance and collection registry lookups pass the qualified name. The schema\n  planner rejects a table claimed by two unrelated classes\n  (`CONFIG_TABLE_NAME_COLLISION`): only one STI family shares a table (#3098);\n  collections (including `SmrtReportCollection`) never claim one. Consumer\n  gates: `registry/__tests__/issue-3110-*.test.ts`, `issue-3109-*.test.ts`,\n  `packages/bundle-gate/src/__tests__/consumer-same-name.spec.ts`.\n- API custom-action eligibility has ONE resolver, `resolveApiMethodExposure()`\n  in `generators/custom-action.ts`: both SvelteKit route emitters,\n  `resolveApiActionSet`, and `knowledge.ts` read it, and a new consumer must too\n  — a local mirror is how a method gets reported unavailable while its route\n  file is still written. A public method routes by default only when every\n  parameter is JSON-shaped; `@method({ expose })` overrides in both directions,\n  `expose: true` bypasses the heuristic ALONE, and an explicit `api.include` or\n  `api.routes` entry keeps its pre-#2686 route. Fail closed on scanner\n  uncertainty: read `parameters[].typeUnresolved`, never the `'any'` it\n  substitutes. Accepting `Date` as wire-able and hydrating it\n  (`toCustomActionDate`) are one decision — changing either breaks the other.\n  The runtime `APIGenerator` transport stays declaration-gated: `rest.ts`\n  dispatch and `preflight-route.ts` prediction both read\n  `declaresRuntimeRestRoute()`, which must accept every `ApiCustomRouteConfig`\n  option so a sweep moving one onto its method cannot delete the endpoint. Its\n  twin `declaresRuntimeRestRouteShape()` deliberately ignores `expose: false`:\n  the dispatcher must still SEE a withheld declaration to answer 404, because\n  `POST /<collection>/<segment>` resolves to `create` when nothing claims the\n  segment. Split unions and type arguments with `splitTopLevel()` — a naive\n  `split('|')` truncates `Record<string, Asset | null>` into fragments that\n  match no rule and are then accepted, widening the gate. `extractTypeName`\n  returns `null` for a generic with an unresolvable ARGUMENT or a union with an\n  unresolvable BRANCH so those reach that fail-closed path instead of arriving\n  as a bare `'Array'`. Runtime transports read\n  `ObjectRegistry.resolveRuntimeMethod()`, which tries the item class's manifest\n  entry, then the COLLECTION class's (where a collection-hosted action's\n  parameters live), then the live `@method()` store — keyed by CONSTRUCTOR,\n  never by simple name (`Account` exists in two packages), and recording\n  `isStatic` because an unscanned runtime has no manifest to recover the\n  receiver from. `isRestActionRoutable` ANDs \"declared\" with that receiver, so\n  it never predicts `allow` for an action dispatch refuses. A declared action\n  with no receiver is refused (501 collection-scoped, 404 item-scoped), never\n  allowed to fall through into `create`. All eight consumers read the resolver,\n  including `packages/smrt-workbench/src/discovery.ts`; it imports the\n  `./generators/custom-action` LEAF subpath, not `./generators`, because that\n  barrel value-re-exports `MCPGenerator` and so drags `@happyvertical/ai` and\n  `@happyvertical/sql` into a build-time helper (2 modules vs 109). Keep\n  `custom-action.ts` free of value imports outside `tools/tool-generator`.\n\n## Gotchas\n\n- Optional filesystem support stays lazy: use `createFilesystemAdapter()` in\n  `src/filesystem-loader.ts`, not a static files-SDK import. Fully bundled apps\n  import `@happyvertical/smrt-core/filesystem` at startup. Use\n  `importOptionalDependency()` for similarly heavy optional dependencies.\n- Database retries are transient-only, four attempts total for `get`/`upsert`.\n  Use `src/db-errors.ts` classifiers through the cause chain, never message\n  matching (SDK driver text can live in `context.originalError`). Constraints,\n  bad input, missing tables, and aborted PostgreSQL transactions fail immediately.\n  Unique/PK violations become `VALIDATION_UNIQUE_CONSTRAINT`, NOT NULL becomes\n  `VALIDATION_REQUIRED_FIELD`; other failures keep the driver error as `cause`.\n- Property initializers precede option values; options win. Arrays/objects are\n  shallow-cloned. Collection creation caches fields; table verification caches\n  by DB URL and table. Preserve these scopes when changing initialization.\n- The Vite plugin loads scanner/schema code from `dist/` when present. Rebuild\n  core after editing those sources before testing consumer manifest generation.\n  Vite 8 requires `oxc.decorator: { legacy: true, emitDecoratorMetadata: true }`.\n\n## Validation\n\n`typecheck` checks production source first, then the test project in\n`tsconfig.test.json`. Test coverage and the shared relaxed config\ncontract are documented in [agents/test-types.md](agents/test-types.md).\n\nRun focused tests first, then applicable package checks:\n\n```bash\npnpm --filter @happyvertical/smrt-core test\npnpm --filter @happyvertical/smrt-core typecheck\npnpm --filter @happyvertical/smrt-core build\npnpm --filter @happyvertical/smrt-core test:postgres\npnpm check:agents-chain\npnpm smrt dev:knowledge-check\n```\n\nThe PostgreSQL lane is required for numeric types, UUID casts, conflict targets,\ntimestamps, and migrations. Tests generate their manifest before Vitest; restart\nwatch mode after adding decorated classes. Documentation-only changes need\ninstruction-chain and knowledge freshness checks, not the runtime test suite.\n",
+  "agentDoc": "# @happyvertical/smrt-core\n\nFoundation ORM, registry, schema/code generation, AI integration, and DispatchBus.\nRead the module for the subsystem being edited; root AGENTS covers shared model\nand repository rules.\n\n## Modules\n\n| Source | Scope | Module doc |\n|---|---|---|\n| `src/object.ts`, `src/collection.ts`, `src/child-accessors.ts` | Lifecycle, hydration, operators, STI, child accessors, dispatch | [agents/object-runtime.md](agents/object-runtime.md) |\n| `src/revision-guard.ts` | Guarded writes and PostgreSQL revision precision | [agents/revision-guard.md](agents/revision-guard.md) |\n| `src/collection.ts` | Projections, latest-related, facets, counts, read plans | [agents/collection-reads.md](agents/collection-reads.md) |\n| `src/collection.ts` | Limits, sort whitelist, generated list order | [agents/query-bounds.md](agents/query-bounds.md) |\n| `src/data-query.ts` | Transport-neutral bounded query normalization | [agents/data-query.md](agents/data-query.md) |\n| `src/schema/`, `src/migrations/`, `src/cascade.ts`, `src/system/` | DDL parity, indexes, migrations, delete integrity, retention | [agents/schema-paths.md](agents/schema-paths.md) |\n| `src/postgres-permissions.ts` | Explicit PostgreSQL ACL plans and atomic reconciliation | [deployment permission contract](../../docs/content/postgres-permissions.md) |\n| `src/change-feed.ts` | Durable changes, cursors, table versions, retention | [agents/change-feed.md](agents/change-feed.md) |\n| `src/change-feed-authz.ts` | Consumer table/row change-feed authorization hooks (#3020) | [agents/change-feed.md](agents/change-feed.md) |\n| `src/change-signals.ts` | Signal bus, replica fan-out, SSE | [agents/change-signals.md](agents/change-signals.md) |\n| `src/generators/`, `src/vite-plugin/web-collections.ts` | REST/CLI/MCP generation, manifest hashes, ETags | [agents/generators.md](agents/generators.md) |\n| `src/vite-plugin/`, `src/consumer-plugin/`, `src/knowledge.ts` | Decorator UI hints, knowledge projection, generation snapshots | [agents/build-knowledge.md](agents/build-knowledge.md) |\n| `src/knowledge-graph.ts` | Cross-package knowledge graph merge and freshness check (#2863) — see [standards](../../docs/content/standards.md) | — |\n| `src/object.ts`, `src/collection.ts`, `src/learning/memory.ts` | Context memory and semantic search | [agents/memory.md](agents/memory.md) |\n| `src/system/diagnostics.ts` | SELECT-only `_smrt_*` diagnostics reader behind smrt-dev-mcp runtime tools (#1824) | [agents/system-diagnostics.md](agents/system-diagnostics.md) |\n| `src/system/registry-snapshot.ts` | Sanitized plain-JSON projection of the booted `ObjectRegistry` for the smrt-dev-mcp runtime dev-plane (#1831); never constructors, validators, values, or absolute paths | [agents/registry-snapshot.md](agents/registry-snapshot.md) |\n| `src/registry/qualified-name-aliases.ts`, `src/migrations/qualified-name-aliases.ts` | Model moves: `previousQualifiedNames` aliases, deprecation, doctor counts, opt-in backfill (#3338) | [agents/model-moves.md](agents/model-moves.md) |\n| `src/run-once.ts` | Shared idempotency seam: insert-only claim + caller work in one transaction, replay on retry, typed in-flight/unknown-outcome answers (#3080) | [agents/run-once.md](agents/run-once.md) |\n| `src/recipe.ts`, `../scanner/src/recipes.ts` | `SmrtRecipe`: declared user-facing units (models, nav, `requires`, curation `options`) collected into manifest and knowledge `recipes` (#3590) | [agents/recipes.md](agents/recipes.md) |\n\n## Cross-module invariants\n\n- `ObjectRegistry` is a `globalThis` singleton so registration survives HMR.\n- Any output that names a database URL (CLI banners, logs, errors) renders it\n  with `redactDatabaseUrl` / `redactDatabaseUrlsInText`\n  (`src/utils/database-url.ts`, #3527): never the password or query string,\n  and never the raw string when it cannot be parsed.\n- Per-class registry work on the hydration path (manifest reconciliation in\n  `ensureManifestLoaded()`, the simple-name index behind `findClass()`) is\n  memoized per registry generation (`src/registry/generation.ts`, #3047). Any\n  new writer of registered classes, their field/method metadata, or loaded\n  manifests must go through the tracked maps or call\n  `bumpRegistryGeneration()`; `issue-3047-hydration-registry-work.test.ts`\n  guards that hydration does not repeat this work per row.\n\n- Production DDL uses manifest generators; `getTestDatabase()` uses registry\n  generators. Keep columns, indexes, FK actions, and runtime conflict targets in\n  parity (`src/schema/schema-path-parity.test.ts`). Every new query predicate\n  needs its index or an explicit reason none is needed.\n- Tenant scoping covers every read and every unique/conflict key. Explicit\n  conflict columns are not rewritten; their author must include tenant scope.\n  A `tenantId` field makes rows tenant-OWNED without any tenancy declaration:\n  the default key leads with `tenant_id`. A new object's natural-key save reads\n  the row its upsert would hit and refuses a different owner\n  (`TENANT_ISOLATION_VIOLATION`) or adopts a same-owner row's id, so\n  `DO UPDATE` never rewrites a primary key or owner. Only an explicit natural\n  key adopts: a slug `getSlug()` derived from `name`/`title`/`label` moves to\n  a free `-2`, `-3`, … slug and INSERTs. See `agents/schema-paths.md`\n  (\"Tenant OWNERSHIP\").\n- Persisted saves use `id` and loaded `updated_at`; new saves use natural keys.\n  Preserve revision compare-and-swap ordering through public `save()`,\n  `claimRevision()`, and transaction APIs. Embedded saves, deletes, and complete\n  `withTransaction()` callbacks share a process-local write queue.\n- Collection model hydration is serial in result order: initialization may query\n  the same transaction-bound PostgreSQL client. Use projections for plain rows.\n- Native DuckDB UUIDs must be cast coherently on read before identity reuse;\n  custom embedded revision paths use `getCanonicalPersistedRow()`. Never replay\n  a mutation to discover result types.\n- `withDatabase(db, callback)` restores only database bindings (including public\n  `options.db`); `withTransaction(callback)` also restores identity/revision\n  metadata after rollback. Do not use a bound instance concurrently.\n- `runOnce({ db, tenantId, actor, token, content }, work)` (`src/run-once.ts`,\n  #3080) claims a key derived from all four inputs — never the token alone,\n  which collapses distinct submissions — via `INSERT ... ON CONFLICT\n  (claim_key) DO NOTHING RETURNING claim_key` into the hand-DDL\n  `_smrt_run_once_claims` system table, and runs `work` in the SAME\n  transaction; a completed claim replays its stored result instead of\n  re-running, a failed `work` rolls the claim back with the transaction, and\n  an unresolved claim raises typed `RunOnceClaimError`\n  (`RUN_ONCE_IN_FLIGHT` / `RUN_ONCE_OUTCOME_UNKNOWN`) rather than guessing.\n  The claim insert must never raise on conflict: PostgreSQL aborts the whole\n  transaction on any raised error, which would take the recovery `SELECT`\n  down with it too — this is why it is `DO NOTHING`, not a plain `INSERT`\n  caught for `isUniqueViolationError`. Completed claims are bounded by\n  `runRetentionSweep()`'s `run-once-claims` task (`system/retention.ts`,\n  `DEFAULT_RETENTION_POLICY.runOnceClaims`, default 30 days on\n  `completed_at`; `in_progress` rows are never matched) — the window is a\n  replay deadline, not just disk hygiene: a token replayed after its claim\n  is swept runs `work()` again. See `agents/run-once.md`.\n- `ensureSystemTables(db, typeHint?)` provisions framework tables idempotently;\n  call it on a base PostgreSQL connection before caller-owned transactions.\n  Bootstrap uses a transaction-scoped advisory lock, taken only when the\n  PostgreSQL schema version is not yet stamped: inside a caller's transaction it\n  is held until that transaction ends (#2868). Application tables still require migrations;\n  runtime table verification checks existence only.\n- Manifest generation fails closed on scanner errors, including unresolved\n  decorator spreads. Never emit partial, default-open registration.\n- Generated registration repairs bundled class identity using the exact imported\n  constructor, explicit package, and isolated one-object manifest. Never infer\n  ownership from paths, simple names, or table names; packages can share names.\n  Consumer regression gate: `packages/bundle-gate/src/__tests__/registry-identity.spec.ts`.\n- Decorator registration trusts a class's stack-derived package only when that\n  package declares the class (stub, own manifest entry, or explicit\n  `packageName`); it then matches the qualified key and never adopts another\n  package's same-named registration. Otherwise a loaded (or the cwd project's)\n  manifest entry describing the declaring file supplies the identity — apps\n  scan workspace-package sources under the app's name (#3110). A class of\n  another known package coexists under its qualified key\n  (`decorator-different-packages-qualified-coexist`); bundled output needs\n  a resolved table that differs first (#3106). Stack\n  attribution skips smrt-core (including source-mapped installed\n  `smrt-core/src` frames, #3109), decorator-helper, and module-runner frames,\n  and drops a frame's Vite `?v=` query (#3490). Library builds stamp each\n  decorated class with `static __smrtPackage__` (own property, read at\n  decoration as its explicit package) and publish `stampsConstructors`; an\n  unstamped class never takes a stamping package's entry by name and table,\n  in either order (#3490, `issue-3490-*.test.ts`, `package-stamp.test.ts`).\n  Qualified names are `@scope/pkg:Class`; the scope is a deliberate\n  discriminator, so manifest generation (`generateManifest`,\n  `applyGenerationPasses`, hence `pnpm build`) throws\n  `CONFIG_UNSCOPED_PACKAGE_NAME` for an unscoped `package.json` name (#3408).\n  Instance and collection registry lookups pass the qualified name. The schema\n  planner rejects a table claimed by two unrelated classes\n  (`CONFIG_TABLE_NAME_COLLISION`): only one STI family shares a table (#3098);\n  collections (including `SmrtReportCollection`) never claim one. Consumer\n  gates: `registry/__tests__/issue-3110-*.test.ts`, `issue-3109-*.test.ts`,\n  `packages/bundle-gate/src/__tests__/consumer-same-name.spec.ts`.\n- API custom-action eligibility has ONE resolver, `resolveApiMethodExposure()`\n  in `generators/custom-action.ts`: both SvelteKit route emitters,\n  `resolveApiActionSet`, and `knowledge.ts` read it, and a new consumer must too\n  — a local mirror is how a method gets reported unavailable while its route\n  file is still written. A public method routes by default only when every\n  parameter is JSON-shaped; `@method({ expose })` overrides in both directions,\n  `expose: true` bypasses the heuristic ALONE, and an explicit `api.include` or\n  `api.routes` entry keeps its pre-#2686 route. Fail closed on scanner\n  uncertainty: read `parameters[].typeUnresolved`, never the `'any'` it\n  substitutes. Accepting `Date` as wire-able and hydrating it\n  (`toCustomActionDate`) are one decision — changing either breaks the other.\n  The runtime `APIGenerator` transport stays declaration-gated: `rest.ts`\n  dispatch and `preflight-route.ts` prediction both read\n  `declaresRuntimeRestRoute()`, which must accept every `ApiCustomRouteConfig`\n  option so a sweep moving one onto its method cannot delete the endpoint. Its\n  twin `declaresRuntimeRestRouteShape()` deliberately ignores `expose: false`:\n  the dispatcher must still SEE a withheld declaration to answer 404, because\n  `POST /<collection>/<segment>` resolves to `create` when nothing claims the\n  segment. Split unions and type arguments with `splitTopLevel()` — a naive\n  `split('|')` truncates `Record<string, Asset | null>` into fragments that\n  match no rule and are then accepted, widening the gate. `extractTypeName`\n  returns `null` for a generic with an unresolvable ARGUMENT or a union with an\n  unresolvable BRANCH so those reach that fail-closed path instead of arriving\n  as a bare `'Array'`. Runtime transports read\n  `ObjectRegistry.resolveRuntimeMethod()`, which tries the item class's manifest\n  entry, then the COLLECTION class's (where a collection-hosted action's\n  parameters live), then the live `@method()` store — keyed by CONSTRUCTOR,\n  never by simple name (`Account` exists in two packages), and recording\n  `isStatic` because an unscanned runtime has no manifest to recover the\n  receiver from. `isRestActionRoutable` ANDs \"declared\" with that receiver, so\n  it never predicts `allow` for an action dispatch refuses. A declared action\n  with no receiver is refused (501 collection-scoped, 404 item-scoped), never\n  allowed to fall through into `create`. All eight consumers read the resolver,\n  including `packages/smrt-workbench/src/discovery.ts`; it imports the\n  `./generators/custom-action` LEAF subpath, not `./generators`, because that\n  barrel value-re-exports `MCPGenerator` and so drags `@happyvertical/ai` and\n  `@happyvertical/sql` into a build-time helper (2 modules vs 109). Keep\n  `custom-action.ts` free of value imports outside `tools/tool-generator`.\n\n## Gotchas\n\n- Optional filesystem support stays lazy: use `createFilesystemAdapter()` in\n  `src/filesystem-loader.ts`, not a static files-SDK import. Fully bundled apps\n  import `@happyvertical/smrt-core/filesystem` at startup. Use\n  `importOptionalDependency()` for similarly heavy optional dependencies.\n- `exports['.'].browser` (`dist/browser.js`) is the browser surface. Model\n  package roots are bundled for browsers by the bundle-gate browser fixture\n  (#3621): anything a model root imports from core must be exported by the\n  browser entry and must not reach `node:` built-ins, `pg`, `cosmiconfig`, or\n  `jiti`. Keep Node-only code behind a subpath or a lazy import; when a fix\n  makes a package pass, delete its entry in\n  `packages/bundle-gate/src/browser-gate/expected-failures.ts`.\n- Database retries are transient-only, four attempts total for `get`/`upsert`.\n  Use `src/db-errors.ts` classifiers through the cause chain, never message\n  matching (SDK driver text can live in `context.originalError`). Constraints,\n  bad input, missing tables, and aborted PostgreSQL transactions fail immediately.\n  Unique/PK violations become `VALIDATION_UNIQUE_CONSTRAINT`, NOT NULL becomes\n  `VALIDATION_REQUIRED_FIELD`; other failures keep the driver error as `cause`.\n- Property initializers precede option values; options win. Arrays/objects are\n  shallow-cloned. Collection creation caches fields; table verification caches\n  by DB URL and table. Preserve these scopes when changing initialization.\n- The Vite plugin loads scanner/schema code from `dist/` when present. Rebuild\n  core after editing those sources before testing consumer manifest generation.\n  Vite 8 requires `oxc.decorator: { legacy: true, emitDecoratorMetadata: true }`.\n\n## Validation\n\n`typecheck` checks production source first, then the test project in\n`tsconfig.test.json`. Test coverage and the shared relaxed config\ncontract are documented in [agents/test-types.md](agents/test-types.md).\n\nRun focused tests first, then applicable package checks:\n\n```bash\npnpm --filter @happyvertical/smrt-core test\npnpm --filter @happyvertical/smrt-core typecheck\npnpm --filter @happyvertical/smrt-core build\npnpm --filter @happyvertical/smrt-core test:postgres\npnpm check:agents-chain\npnpm smrt dev:knowledge-check\n```\n\nThe PostgreSQL lane is required for numeric types, UUID casts, conflict targets,\ntimestamps, and migrations. Tests generate their manifest before Vitest; restart\nwatch mode after adding decorated classes. Documentation-only changes need\ninstruction-chain and knowledge freshness checks, not the runtime test suite.\n",
   "moduleDocs": [
     {
       "path": "agents/object-runtime.md",
@@ -1165,12 +1167,12 @@
     {
       "path": "agents/generators.md",
       "module": "generators",
-      "content": "# smrt-core/code generators\n\nModule semantics for `src/generators/` + `src/vite-plugin/`. Package orientation, the cross-module\ninvariants, and the traps that apply before editing anything live in\n[../AGENTS.md](../AGENTS.md) — read that first.\n\n## Code Generators\n\n| Generator | Location | Output |\n|-----------|----------|--------|\n| REST API | `src/generators/rest.ts` | OpenAPI-compliant CRUD endpoints |\n| MCP Server | `src/generators/mcp.ts` | Model Context Protocol tools |\n| Web collections | `src/vite-plugin/web-collections.ts` (selectors) + `generateWebModule` | `@happyvertical/smrt-virt-web` — one typed collection definition per API-exposed REST collection (#1761), consumed by `@happyvertical/smrt-web` |\n\nThe same web virtual module exports `webMcpToolDefinitions` (#2518), a\ncanonical per-tool array selected independently of list materialization. Every\nnon-empty canonical API action set contributes tools, so get-only and\ncustom-action-only models are discoverable; custom actions declared on a\n`SmrtCollection` merge into the owning row collection. Each definition carries\ncomplete route and invalidation metadata. `collectionDefinitions` and its\nembedded descriptor copy remain unchanged for existing cache-backed consumers.\n\nGenerated API clients share `selectApiClientEntries()` across the runtime Vite\nmodule, its ambient declaration, and physical prebuild declarations. When a\ncollection class and its populated model share an endpoint, the model owns the\ncanonical collection key and row payload schema; the collection class remains\navailable under a deterministic class-derived secondary key. Selection and\ncollision suffixes must not depend on manifest insertion order (#2027).\nRoute emission iterates manifest objects in the same deterministic\nqualified-identity order (`orderedManifestObjectEntries`), so when two models\nshare one collection the last writer of each route file — and therefore the\nCRUD method set `resolveGeneratedEndpointCrudMethods` mirrors into\n`smrt-client.d.ts` — is stable across scan orders (#2754).\nFor aggregated manifests, inheritance and item-type references resolve exact\nqualified names first, then package-local simple names, then a stable identity\nfallback so duplicate class names across packages cannot reintroduce ordering.\n\nThe web module also emits a build-time **`manifestHash`** constant (#1764): `computeWebManifestHash(manifest)` is a deterministic, replica-stable digest of the emitted web-collection SHAPE (name/className/endpoint/idField/actions/fields/relationships), canonicalized (recursive key sort) before `sha256 → base64url`, truncated to 16 chars — so the same schema always hashes the same, and a field add/remove/type-change/edge-change changes it. A change means old persisted client rows may mis-hydrate, so smrt-web keys its durable persistence namespace on it and its `updateAvailable` contract signal compares against it. Four co-managed emission sites must not drift: the runtime value (`generateWebModule`), the `@happyvertical/smrt-virt-web` ambient d.ts (`vite-plugin/index.ts`), the physical `@smrt/web` d.ts (`prebuild/index.ts`), and the hand-written type mirror in `@happyvertical/smrt-web` (`packages/smrt-web/src/index.ts` — dependency-free, so textual sync only).\n\n`webMcpToolDefinitions` is deliberately outside that digest: tool-only route,\nidentifier, or annotation changes cannot alter persisted row hydration.\n\nPer-field web emission (#2046): `buildWebFieldDefinitions` carries `description` (from `@field({ description })`) and sanitized `ui` hints (from `@field({ ui: { basic, group, order, locked } })`, read off the manifest `_meta.ui` bag through per-key type guards) into each emitted field definition, and `buildWebToolDescriptors` threads the same `description` into browser MCP tool schemas. `sensitive`/`transient` fields are excluded from emission entirely, so their descriptions never ship. Both keys are conditional, so hint-less schemas emit byte-identical definitions (and hashes) as before; adding a description/ui hint changes the manifest hash — deliberate over-invalidation, harmless per the #1764 contract.\n\n## Generated MCP server output language\n\n`MCPGenerator` builds every file as TypeScript, so the requested `outputPath`\nextension decides what is written (#2279). `.ts`/`.mts` targets keep the source\nverbatim for `tsx` or Node type stripping — which is why the generated source\nmust stay erasable-syntax-only (no parameter properties, enums, or namespaces).\nEvery other target (`.smrt/mcp-server/index.js` by default) is transpiled to\nJavaScript with lazily loaded `oxc-transform` before writing, because the\nprinted run script and the generated `claude-config.example.json` both invoke\nit with plain `node`. Ordinary core imports and `.ts`/`.mts` output therefore\ndo not load OXC's native bindings.\nThis keeps `typescript` dev-only in `@happyvertical/smrt-core`; generated MCP\nsource must remain erasable-syntax-only. A `.cjs`/`.cts` target is rejected\noutright: generated servers are ES modules. `src/generators/mcp-emit.ts` owns\nthose decisions — do not reintroduce a bare `writeFile` of generated source.\n\nModular output writes `config`, `tools/index`, and `handlers/index` with the\nentry point's own extension, and emits the entry's relative import specifiers\nwith that same extension, so the files it imports both exist and load with the\nsame module semantics — an `.mjs` entry gets `.mjs` siblings, not `.js` ones a\nCommonJS package would then parse as CommonJS. The entry is written at the\nrequested path rather than a hardcoded `index.js`.\nGenerated code also has to be valid in an ES module: `arguments` is not a legal\nbinding name there, however convenient it reads.\n\n## Browser-plane playbook preflight route (#2590)\n\n`GET {basePath}/_preflight?key=<playbook key>` (`src/generators/preflight-route.ts`)\nis an advisory, read-effect, idempotent report of what a caller's playbook would\nbe allowed to do — capability *selection*, never authorization. Resolution and\nverdict shaping live in `@happyvertical/smrt-playbooks`, which depends on this\npackage, so core takes the evaluator as the `APIConfig.playbookPreflight` seam and\nthe dependency stays one-way. Without a provider the route 404s.\n\n**`authMiddleware` is never invoked by preflight**, and that is enforced\nstructurally rather than by discipline: `PlaybookPreflightRouteOptions` has no\nauth member of any kind, and `rest.ts` passes the boolean `appAuthConfigured`\ninstead — so there is no handle in the module to invoke by mistake. A synthetic-\n`Request` dry run is explicitly not an option: the middleware is request-bound,\nreturns a `Response` rather than a boolean, and may consult session stores,\nrate-limit, or audit. The app-auth layer therefore reports `unknown`, which is the\nhonest answer, and a future `authPredicate` seam can fill it in without changing\nthe contract.\n\nThe static layers preflight predicts against are exported from the same module —\n`isApiActionEnabledForObject`, `isRestActionRoutable`, `isRestRoutePublic`,\n`restFieldReadPermissions`, `restMethodForApiAction`,\n`resolveRegisteredObjectName` — and `APIGenerator`'s own\n`isApiActionEnabled` / `isRoutePublic` now delegate to them, so the route and the\nprediction of the route cannot drift. Exposure and existence are separate\nquestions: `include`/`exclude` gate a route, they do not conjure one, so\n`isRestActionRoutable` additionally requires a custom action to be declared in\n`api.routes` — the only map `dispatchCustomCollectionAction` iterates. A custom\naction is predicted against the verb its own route config declares, so a\n`public: 'read'` opt-out neither silently covers a `POST` action nor falsely\ndenies a declared `GET` one. Every unresolvable key returns the provider's single uniform\n\"unavailable\" body with an unconditional 200: unknown and unauthorized keys are\nindistinguishable at the HTTP layer too.\n\n## Emitted agent surface (#2591)\n\nGenerated model tools have always been build-time artifacts — virtual module,\nmanifest, knowledge graph. View intents (#2588) and playbooks (#2589) existed\nonly once something mounted, so \"what can an agent do in this app\" had no answer\nshort of enumerating every route. This closes that.\n\nThe same OXC scan that builds the manifest also runs the scanner's\nagent-surface matcher (`ScanResults.agentSurface`). `smrtPlugin()` captures it\nin `scanWithOxc`, projects it with `toKnowledgeAgentSurface`, and passes it to\n`buildDomainKnowledgeManifest` as `agentSurface`. Note that declaration\ndiscovery is NOT bound to the plugin's `include` glob — an app that scans\n`src/lib/objects/**` for models still has its `src/lib/agent/*.intents.ts`\nsidecars found (see `packages/scanner/AGENTS.md`). Two more consequences worth\nholding onto:\n\n- **It never touches `manifest.json`.** The runtime manifest stays\n  runtime-focused; the agent-addressable surface is an agent/developer contract,\n  so it lands in `.smrt/smrt-knowledge.json` and `dist/smrt-knowledge.json`\n  only, under `agentSurface: { intents, playbooks, diagnostics }`.\n- **It is passed in, not scanned in `knowledge.ts`.** The scanner carries a\n  native parser binary and `smrt-core`'s main entry is browser-reachable, so\n  core's sync knowledge builder must not import it. The Vite plugin already\n  imports the scanner lazily on the Node side and is the only caller that writes\n  this artifact.\n\nThe field is **omitted entirely** when a package declares nothing, which is what\nmakes it additive in practice rather than only on paper: every existing\npackage's checked-in artifact stays byte-identical.\n\nEach declaring module gets a `sourceHashes` entry under the\n`agentSurface:<package-relative path>` prefix (`AGENT_SURFACE_HASH_PREFIX`), so\nEDITING an intent sidecar marks the artifact stale exactly like editing\n`AGENTS.md` does (`stale-domain-knowledge`).\n\nHashes alone cannot see an **added** declaration, though: a brand-new sidecar\nhas no recorded hash to mismatch, the runtime manifest never carries intents,\nand `AGENTS.md` is untouched — so every other signal stays green while the\nartifact omits a real operation. `dev:knowledge-check` therefore also re-derives\nthe declaration SET from source and compares it to the artifact by identity,\nreporting either direction as `stale-agent-surface`. The scan is bounded like\nthe numeric-precision lint: `src` only, behind the scanner's token pre-filter.\n\nThat re-derivation must model what the EMITTER sees, not merely what is on\ndisk, or it reports drift no rebuild can clear. Which files count is decided by\nthe scanner's exported `isAgentSurfaceSourcePath` — the same predicate the\nemitter itself uses, never a list copied into the checker — and the per-file\nresults run through `mergeAgentSurfaces` before comparing, because the merge is\nwhere a duplicate identity and a derived tool-name collision are resolved and\nthe artifact is the merged result.\nDiagnostics are compared alongside identities: a sidecar containing only a\ncomputed declaration adds no identity and has no prior hash, so without that,\n\"a diagnostic, never silence\" would quietly become \"a diagnostic, until the\nartifact goes stale\". The walk covers `<pkg>/src` while the emitter globs the\nwhole project root, so an emitted entry from outside `src` is not reported as\nmissing — this check did not look there, and claiming otherwise would be an\nerror nothing could clear.\n\nBoth `stale-*` codes are warnings by default and errors under `--strict`, which\nis what CI runs. Alongside them: `agent-surface-missing-identity`,\n`agent-surface-duplicate-identity`, and `agent-surface-empty-playbook` are\nerrors, and `agent-surface-not-static` and `agent-surface-tool-name-collision`\nare warnings. A cross-file duplicate arrives as a *diagnostic* rather than two\nentries — the scanner's merge already dropped the loser — so that diagnostic\nmaps to the duplicate error rather than the not-static warning; otherwise the\nerror would be unreachable for the case it exists to catch.\n\nA `tool-name-collision` diagnostic (#2725) is derived from the MANIFEST, not\nfrom the declaration: the plugin compares each emitted intent against\n`buildWebMcpToolDefinitions` for the same build, which is already filtered by\nthe exposure policy, and appends the result to the surface. So it is excluded\nfrom the drift comparison above — that pass re-derives declarations from source\nalone and has no manifest, so counting one as \"declared\" would report every\ncollision as drift no rebuild could clear. The check is advisory and drops\nnothing: `defineIntent` accepts the id, so the intent is emitted, and the\ndocument-global tool-name lock (#2613) rejects whichever registers second — the\nbuild-time notice is the earlier, cheaper form of the same answer. A build\ncannot see the provider's WebMCP `namespace` or `effects` policy, either of\nwhich separates the pair outright, so the message states that precondition\nrather than asserting the collision.\n\n`smrt doctor` prints the whole surface — model tools, intents, playbooks — from\nthese artifacts alone, with no application running.\n\n## Custom-action contract\n\n`resolveCustomActionMetadata()` is the common discovery and invocation contract\nfor generated REST routes and API clients, MCP, CLI, WebMCP, and simple\nREST-resource discovery. Receiver scope comes from the executable method, never a\nconfiguration-only `api.routes[name].scope` override: instance model methods\nare item-scoped and require `id`; static model methods and recognized\n`SmrtCollection` methods are collection-scoped and do not accept `id`. Route\nconfiguration may still choose its path and HTTP verb, but it cannot turn an\ninstance call into `ClassRef.action` or vice versa.\n\nWhen scanner method metadata exists, discovery projects each named parameter\nand its JSON-schema type, and invokers pass the values positionally in declared\norder. The legacy single `options` bag remains compatible when metadata is\nabsent (or the declared method takes `options`). Do not infer this from runtime\nfunction arity. An omitted typed `options` parameter remains `undefined`, so a\nmethod's JavaScript default initializer continues to apply; an explicit `null`\nremains `null`. Flat tool and CLI inputs reserve `id` for receiver parsing. If\nan action declares an `id` parameter, its flat MCP/WebMCP field is `actionId`\n(and CLI uses `--action-id`); REST keeps its independent path/body\nnamespaces. Typed CLI actions may use standard flag names such as `limit`,\n`offset`, `where`, and `format` without those values being stripped as CRUD\nflags.\n\nCustom actions may return an explicit, domain-neutral failure object with\n`ok: false`, `code`, and `message` plus optional `status`, `details`,\n`retryable`, and `correlationId`. `normalizeCustomActionFailure()` redacts it;\ngenerated REST returns `{ error: failure }` with the non-2xx status, while MCP\nreturns `isError: true` and `_meta['io.happyvertical/smrt']`. Opaque successful\nobjects (including `{ code, message }`) remain untouched; thrown exceptions are\nnot reclassified as domain failures.\n\nCustom route metadata also classifies browser-tool effects. Set `effect` to\n`read`, `write`, or `destructive`, with truthful `idempotent` and `openWorld`\nflags. CRUD classification is fixed: list/get are read, create/update are write,\nand delete is destructive. An undeclared custom action deliberately defaults to\ndestructive, non-idempotent, and open-world so a browser capability policy never\nfails open.\n\nGenerated reads (`list`/`get`) on the REST and SvelteKit generators support conditional GET (helpers in `src/generators/conditional-get.ts`). ETag v2 (#1765): the validator is the table's change-feed version (`getTableVersion`) keyed by the request representation, so a **concrete** `If-None-Match` short-circuits into a 304 with an empty body **before** the collection query runs — an unchanged table revalidates with zero table scan. A wildcard `If-None-Match: *` is deferred until the payload builds (existence confirmed), so a missing item still returns 404, not a false 304. Tenant-scoped reads fold the active tenant into the representation (`resolveTenantEtagDiscriminator`) so one tenant's cached validator never satisfies another's read of the same URL. Routes whose GET renders via a **custom serializer** (which can load related tables the base-table version can't observe) keep the v1 body-hash ETag (`#1757`, query-first but correct); the default `toPublicJSON` path — all REST reads and non-serializer SvelteKit reads — uses v2. v2 is weakly consistent by design (the cost of not reading the data): a revalidation in the sub-statement window between a committed write and its feed append can return a stale 304 that self-heals on the next revalidation. The other v2 window — a deploy that changes the response shape WITHOUT a table write — is closed by the **#1764 ETag salt**: `computeTableVersionEtag(version, representation, manifestHash?)` folds the build's web-collection shape digest into the digest, so a shape-only redeploy busts every read validator (`undefined` reproduces the pre-#1764 unsalted value byte-for-byte for direct helper callers). The generated SvelteKit route bakes the digest in as a `MANIFEST_HASH` constant (via `generateConditionalGetRouteHelper`'s `manifestHash` option, sourced from `computeWebManifestHash(manifest)`) — automatic for the SvelteKit transport. The runtime `APIGenerator` auto-populates the same salt from the runtime registry with `computeRuntimeWebManifestHash()` when `APIConfig.manifestHash` is omitted; explicit `APIConfig.manifestHash` still wins for custom setups. The digest scope is get-OR-list (`selectWebEtagSaltEntries`), so **get-only** routes are salted too. Strong consistency still requires the v1 body-hash path. Cache-Control policy (unchanged from #1757): `private, no-cache` by default; public models may opt into shared caching via `@smrt({ api: { public: true | 'read', cache: { sMaxage } } })` → `public, max-age=0, s-maxage=<n>`; non-public models never emit shared-cache headers. Tenant-scoped models (any mode) never emit them either — bodies vary with session-cookie tenant context that URL-keyed shared caches cannot see; `sMaxage` is neutralized to `private, no-cache` with a one-time warning.\n\n## Generated dev-plane route (#2782)\n\n`src/vite-plugin/dev-plane-route.ts` emits `<routesDir>/_dev/[...tool]/+server.ts`\nonly when `svelteKit.devPlaneRoute.enabled === true` and\n`@happyvertical/smrt-dev-mcp/dev-plane` resolves from the consumer (same\nresolvability guard as `_resources`). The route is dev-only (`$app/environment`\n`dev`, else 404), refuses to start without `SMRT_DEV_MCP_TOKEN` (503), and\ndelegates everything else to `createDevPlane`, passing `getSmrtConfig(...).db`\nfrom the embedded access prelude (below) so the plane shares the app's\nconnection.\nCore never imports smrt-dev-mcp; only the generated file does, at consumer\nruntime. The route carries the auto-generated header so the sweep owns it.\n\nGenerated SvelteKit write routes (#2977) call `requireRoutePermission(locals, action)` after `requireRouteAuth`: CRUD writes need `<collection>.create|update|delete` and mutating custom actions `<collection>.<method>` in the session permission snapshot on `locals`, else 403 (fail-closed; `api.public: true` stays open, `tenantContext.superAdminBypass` skips). See `packages/users/agents/permissions.md`.\n\n## MCP protocol identifiers (#3219)\n\nMCP discovery preserves existing names matching `[A-Za-z0-9_.-]{1,64}`.\nPreviously invalid names use their first 31 sanitized ASCII characters, `_`,\nand the first 32 hex characters of SHA-256 over the JSON tuple\n`[original class name, lowercased action name, original raw tool name]`.\nThis makes long or punctuation-bearing identifiers deterministic without\ncollapsing common prefixes. Discovery reserves compliant names first and fails\nclosed on any duplicate raw name or final alias collision instead of advertising\nambiguous dispatch (including class names differing only by case across packages).\nConsumers must use the advertised name rather than constructing one.\n\nThe generator retains a separate class/action binding for each descriptor and\nemits that mapping for generated runtimes. Dispatch, task eligibility, tenant\nscoping, ordering, and STI metadata use this binding; protocol aliases are not\nexecution identities. The advertised catalog still gates execution. The direct\nruntime-template API accepts `toolTargets`; omitting it retains the legacy\n`object_action` convention for existing direct callers. Supply explicit targets\nfor canonicalized names or class names containing underscores. This contract\ndoes not change CLI, REST, or WebMCP identifiers.\n\n`MCPGenerator.getToolIdentity(tool)` exposes the generator-validated original\nclass, action, and raw generated name to in-process catalog composers. App MCP\nuses it for class allow-lists, tenant checks, and compatible workflow guards;\nthose consumers must not reverse protocol aliases. The alias remains the sole\nwire tool name and is still the key for public patterns and generic tool policy.\n\n`MCPConfig.classNames` scopes generation (simple names, case-insensitive, or\nqualified `@scope/pkg:Class`); omitted, every registered class is a candidate.\nA simple name matching more than one registered class throws (scope it by\nqualified name). Each tool keeps its class's registry key, and configuration,\nfields, methods, dispatch, tasks and collections resolve through that key —\nnever through the first same-named class. Generated servers (single-file and\nmodular) carry it as `registryKey` in their tool targets and task actions and\nuse it for every emitted collection, policy, class and STI-base lookup;\n`objectName` stays the wire/display name.\nA host with an allow-list passes it so the duplicate-name check runs over the\npublished set only: an unrelated collision among classes it never lists must\nnot fail its catalog or calls (#3490). App MCP always scopes its generators.\n\n## Generated route collection access (#3416)\n\nThere is no generated route-access module. Every generated SvelteKit route\nthat needs collections (CRUD, custom actions, `_changes`, `_events`,\n`sync/apply`, `_dev`) embeds the prelude from\n`generateCollectionAccessImports()` (`sveltekit-config-import.ts`): it imports\nthe generated `smrt-register` module, then the app's config module\n(`$lib/server/smrt` by default) as `* as smrtApplication`, and destructures\n`getCollection`/`getSmrtConfig` from `createGeneratedCollectionAccess()`\n(`src/generated-collection-access.ts`). Generation fails before writing\nanything when `configFileName` resolves to the registration module\n(`smrt-register` with any script extension or case).\nThat helper resolves per call, never caching: a legacy `getCollection` /\n`getSmrtConfig` export wins (deprecated, warned once per module, for one\nrelease), else the exported app-runtime `runtime.getCollection()` /\n`classOptions()`, else it fails with an error naming the module. `_resources`\nand static collection-scoped actions only need registration, so they import\n`smrt-register` and then the config module. When the config module is missing\nand `@happyvertical/smrt-app-runtime/sveltekit` resolves from the consumer, the\ngenerator writes a runtime-shaped default instead of the legacy\n`getCollection` file.\n"
+      "content": "# smrt-core/code generators\n\nModule semantics for `src/generators/` + `src/vite-plugin/`. Package orientation, the cross-module\ninvariants, and the traps that apply before editing anything live in\n[../AGENTS.md](../AGENTS.md) — read that first.\n\n## Code Generators\n\n| Generator | Location | Output |\n|-----------|----------|--------|\n| REST API | `src/generators/rest.ts` | OpenAPI-compliant CRUD endpoints |\n| MCP Server | `src/generators/mcp.ts` | Model Context Protocol tools |\n| Web collections | `src/vite-plugin/web-collections.ts` (selectors) + `generateWebModule` | `@happyvertical/smrt-virt-web` — one typed collection definition per API-exposed REST collection (#1761), consumed by `@happyvertical/smrt-web` |\n\nThe same web virtual module exports `webMcpToolDefinitions` (#2518), a\ncanonical per-tool array selected independently of list materialization. Every\nnon-empty canonical API action set contributes tools, so get-only and\ncustom-action-only models are discoverable; custom actions declared on a\n`SmrtCollection` merge into the owning row collection. Each definition carries\ncomplete route and invalidation metadata. `collectionDefinitions` and its\nembedded descriptor copy remain unchanged for existing cache-backed consumers.\n\nGenerated API clients share `selectApiClientEntries()` across the runtime Vite\nmodule, its ambient declaration, and physical prebuild declarations. When a\ncollection class and its populated model share an endpoint, the model owns the\ncanonical collection key and row payload schema; the collection class remains\navailable under a deterministic class-derived secondary key. Selection and\ncollision suffixes must not depend on manifest insertion order (#2027).\nRoute emission iterates manifest objects in the same deterministic\nqualified-identity order (`orderedManifestObjectEntries`), so when two models\nshare one collection the last writer of each route file — and therefore the\nCRUD method set `resolveGeneratedEndpointCrudMethods` mirrors into\n`smrt-client.d.ts` — is stable across scan orders (#2754).\nFor aggregated manifests, inheritance and item-type references resolve exact\nqualified names first, then package-local simple names, then a stable identity\nfallback so duplicate class names across packages cannot reintroduce ordering.\n\nThe web module also emits a build-time **`manifestHash`** constant (#1764): `computeWebManifestHash(manifest)` is a deterministic, replica-stable digest of the emitted web-collection SHAPE (name/className/endpoint/idField/actions/fields/relationships), canonicalized (recursive key sort) before `sha256 → base64url`, truncated to 16 chars — so the same schema always hashes the same, and a field add/remove/type-change/edge-change changes it. A change means old persisted client rows may mis-hydrate, so smrt-web keys its durable persistence namespace on it and its `updateAvailable` contract signal compares against it. Four co-managed emission sites must not drift: the runtime value (`generateWebModule`), the `@happyvertical/smrt-virt-web` ambient d.ts (`vite-plugin/index.ts`), the physical `@smrt/web` d.ts (`prebuild/index.ts`), and the hand-written type mirror in `@happyvertical/smrt-web` (`packages/smrt-web/src/index.ts` — dependency-free, so textual sync only).\n\n`webMcpToolDefinitions` is deliberately outside that digest: tool-only route,\nidentifier, or annotation changes cannot alter persisted row hydration.\n\nPer-field web emission (#2046): `buildWebFieldDefinitions` carries `description` (from `@field({ description })`) and sanitized `ui` hints (from `@field({ ui: { basic, group, order, locked } })`, read off the manifest `_meta.ui` bag through per-key type guards) into each emitted field definition, and `buildWebToolDescriptors` threads the same `description` into browser MCP tool schemas. `sensitive`/`transient` fields are excluded from emission entirely, so their descriptions never ship. Both keys are conditional, so hint-less schemas emit byte-identical definitions (and hashes) as before; adding a description/ui hint changes the manifest hash — deliberate over-invalidation, harmless per the #1764 contract.\n\n## Generated MCP server output language\n\n`MCPGenerator` builds every file as TypeScript, so the requested `outputPath`\nextension decides what is written (#2279). `.ts`/`.mts` targets keep the source\nverbatim for `tsx` or Node type stripping — which is why the generated source\nmust stay erasable-syntax-only (no parameter properties, enums, or namespaces).\nEvery other target (`.smrt/mcp-server/index.js` by default) is transpiled to\nJavaScript with lazily loaded `oxc-transform` before writing, because the\nprinted run script and the generated `claude-config.example.json` both invoke\nit with plain `node`. Ordinary core imports and `.ts`/`.mts` output therefore\ndo not load OXC's native bindings.\nThis keeps `typescript` dev-only in `@happyvertical/smrt-core`; generated MCP\nsource must remain erasable-syntax-only. A `.cjs`/`.cts` target is rejected\noutright: generated servers are ES modules. `src/generators/mcp-emit.ts` owns\nthose decisions — do not reintroduce a bare `writeFile` of generated source.\n\nModular output writes `config`, `tools/index`, and `handlers/index` with the\nentry point's own extension, and emits the entry's relative import specifiers\nwith that same extension, so the files it imports both exist and load with the\nsame module semantics — an `.mjs` entry gets `.mjs` siblings, not `.js` ones a\nCommonJS package would then parse as CommonJS. The entry is written at the\nrequested path rather than a hardcoded `index.js`.\nGenerated code also has to be valid in an ES module: `arguments` is not a legal\nbinding name there, however convenient it reads.\n\n## Browser-plane playbook preflight route (#2590)\n\n`GET {basePath}/_preflight?key=<playbook key>` (`src/generators/preflight-route.ts`)\nis an advisory, read-effect, idempotent report of what a caller's playbook would\nbe allowed to do — capability *selection*, never authorization. Resolution and\nverdict shaping live in `@happyvertical/smrt-playbooks`, which depends on this\npackage, so core takes the evaluator as the `APIConfig.playbookPreflight` seam and\nthe dependency stays one-way. Without a provider the route 404s.\n\n**`authMiddleware` is never invoked by preflight**, and that is enforced\nstructurally rather than by discipline: `PlaybookPreflightRouteOptions` has no\nauth member of any kind, and `rest.ts` passes the boolean `appAuthConfigured`\ninstead — so there is no handle in the module to invoke by mistake. A synthetic-\n`Request` dry run is explicitly not an option: the middleware is request-bound,\nreturns a `Response` rather than a boolean, and may consult session stores,\nrate-limit, or audit. The app-auth layer therefore reports `unknown`, which is the\nhonest answer, and a future `authPredicate` seam can fill it in without changing\nthe contract.\n\nThe static layers preflight predicts against are exported from the same module —\n`isApiActionEnabledForObject`, `isRestActionRoutable`, `isRestRoutePublic`,\n`restFieldReadPermissions`, `restMethodForApiAction`,\n`resolveRegisteredObjectName` — and `APIGenerator`'s own\n`isApiActionEnabled` / `isRoutePublic` now delegate to them, so the route and the\nprediction of the route cannot drift. Exposure and existence are separate\nquestions: `include`/`exclude` gate a route, they do not conjure one, so\n`isRestActionRoutable` additionally requires a custom action to be declared in\n`api.routes` — the only map `dispatchCustomCollectionAction` iterates. A custom\naction is predicted against the verb its own route config declares, so a\n`public: 'read'` opt-out neither silently covers a `POST` action nor falsely\ndenies a declared `GET` one. Every unresolvable key returns the provider's single uniform\n\"unavailable\" body with an unconditional 200: unknown and unauthorized keys are\nindistinguishable at the HTTP layer too.\n\n## Emitted agent surface (#2591)\n\nGenerated model tools have always been build-time artifacts — virtual module,\nmanifest, knowledge graph. View intents (#2588) and playbooks (#2589) existed\nonly once something mounted, so \"what can an agent do in this app\" had no answer\nshort of enumerating every route. This closes that.\n\nThe same OXC scan that builds the manifest also runs the scanner's\nagent-surface matcher (`ScanResults.agentSurface`). `smrtPlugin()` captures it\nin `scanWithOxc`, projects it with `toKnowledgeAgentSurface`, and passes it to\n`buildDomainKnowledgeManifest` as `agentSurface`. Note that declaration\ndiscovery is NOT bound to the plugin's `include` glob — an app that scans\n`src/lib/objects/**` for models still has its `src/lib/agent/*.intents.ts`\nsidecars found (see `packages/scanner/AGENTS.md`). Two more consequences worth\nholding onto:\n\n- **It never touches `manifest.json`.** The runtime manifest stays\n  runtime-focused; the agent-addressable surface is an agent/developer contract,\n  so it lands in `.smrt/smrt-knowledge.json` and `dist/smrt-knowledge.json`\n  only, under `agentSurface: { intents, playbooks, diagnostics }`.\n- **It is passed in, not scanned in `knowledge.ts`.** The scanner carries a\n  native parser binary and `smrt-core`'s main entry is browser-reachable, so\n  core's sync knowledge builder must not import it. The Vite plugin already\n  imports the scanner lazily on the Node side and is the only caller that writes\n  this artifact.\n\nThe field is **omitted entirely** when a package declares nothing, which is what\nmakes it additive in practice rather than only on paper: every existing\npackage's checked-in artifact stays byte-identical.\n\nEach declaring module gets a `sourceHashes` entry under the\n`agentSurface:<package-relative path>` prefix (`AGENT_SURFACE_HASH_PREFIX`), so\nEDITING an intent sidecar marks the artifact stale exactly like editing\n`AGENTS.md` does (`stale-domain-knowledge`).\n\nHashes alone cannot see an **added** declaration, though: a brand-new sidecar\nhas no recorded hash to mismatch, the runtime manifest never carries intents,\nand `AGENTS.md` is untouched — so every other signal stays green while the\nartifact omits a real operation. `dev:knowledge-check` therefore also re-derives\nthe declaration SET from source and compares it to the artifact by identity,\nreporting either direction as `stale-agent-surface`. The scan is bounded like\nthe numeric-precision lint: `src` only, behind the scanner's token pre-filter.\n\nThat re-derivation must model what the EMITTER sees, not merely what is on\ndisk, or it reports drift no rebuild can clear. Which files count is decided by\nthe scanner's exported `isAgentSurfaceSourcePath` — the same predicate the\nemitter itself uses, never a list copied into the checker — and the per-file\nresults run through `mergeAgentSurfaces` before comparing, because the merge is\nwhere a duplicate identity and a derived tool-name collision are resolved and\nthe artifact is the merged result.\nDiagnostics are compared alongside identities: a sidecar containing only a\ncomputed declaration adds no identity and has no prior hash, so without that,\n\"a diagnostic, never silence\" would quietly become \"a diagnostic, until the\nartifact goes stale\". The walk covers `<pkg>/src` while the emitter globs the\nwhole project root, so an emitted entry from outside `src` is not reported as\nmissing — this check did not look there, and claiming otherwise would be an\nerror nothing could clear.\n\nBoth `stale-*` codes are warnings by default and errors under `--strict`, which\nis what CI runs. Alongside them: `agent-surface-missing-identity`,\n`agent-surface-duplicate-identity`, and `agent-surface-empty-playbook` are\nerrors, and `agent-surface-not-static` and `agent-surface-tool-name-collision`\nare warnings. A cross-file duplicate arrives as a *diagnostic* rather than two\nentries — the scanner's merge already dropped the loser — so that diagnostic\nmaps to the duplicate error rather than the not-static warning; otherwise the\nerror would be unreachable for the case it exists to catch.\n\nA `tool-name-collision` diagnostic (#2725) is derived from the MANIFEST, not\nfrom the declaration: the plugin compares each emitted intent against\n`buildWebMcpToolDefinitions` for the same build, which is already filtered by\nthe exposure policy, and appends the result to the surface. So it is excluded\nfrom the drift comparison above — that pass re-derives declarations from source\nalone and has no manifest, so counting one as \"declared\" would report every\ncollision as drift no rebuild could clear. The check is advisory and drops\nnothing: `defineIntent` accepts the id, so the intent is emitted, and the\ndocument-global tool-name lock (#2613) rejects whichever registers second — the\nbuild-time notice is the earlier, cheaper form of the same answer. A build\ncannot see the provider's WebMCP `namespace` or `effects` policy, either of\nwhich separates the pair outright, so the message states that precondition\nrather than asserting the collision.\n\n`smrt doctor` prints the whole surface — model tools, intents, playbooks — from\nthese artifacts alone, with no application running.\n\n## Custom-action contract\n\n`resolveCustomActionMetadata()` is the common discovery and invocation contract\nfor generated REST routes and API clients, MCP, CLI, WebMCP, and simple\nREST-resource discovery. Receiver scope comes from the executable method, never a\nconfiguration-only `api.routes[name].scope` override: instance model methods\nare item-scoped and require `id`; static model methods and recognized\n`SmrtCollection` methods are collection-scoped and do not accept `id`. Route\nconfiguration may still choose its path and HTTP verb, but it cannot turn an\ninstance call into `ClassRef.action` or vice versa.\n\nWhen scanner method metadata exists, discovery projects each named parameter\nand its JSON-schema type, and invokers pass the values positionally in declared\norder. The legacy single `options` bag remains compatible when metadata is\nabsent (or the declared method takes `options`). Do not infer this from runtime\nfunction arity. An omitted typed `options` parameter remains `undefined`, so a\nmethod's JavaScript default initializer continues to apply; an explicit `null`\nremains `null`. Flat tool and CLI inputs reserve `id` for receiver parsing. If\nan action declares an `id` parameter, its flat MCP/WebMCP field is `actionId`\n(and CLI uses `--action-id`); REST keeps its independent path/body\nnamespaces. Typed CLI actions may use standard flag names such as `limit`,\n`offset`, `where`, and `format` without those values being stripped as CRUD\nflags.\n\nCustom actions may return an explicit, domain-neutral failure object with\n`ok: false`, `code`, and `message` plus optional `status`, `details`,\n`retryable`, and `correlationId`. `normalizeCustomActionFailure()` redacts it;\ngenerated REST returns `{ error: failure }` with the non-2xx status, while MCP\nreturns `isError: true` and `_meta['io.happyvertical/smrt']`. Opaque successful\nobjects (including `{ code, message }`) remain untouched; thrown exceptions are\nnot reclassified as domain failures.\n\nCustom route metadata also classifies browser-tool effects. Set `effect` to\n`read`, `write`, or `destructive`, with truthful `idempotent` and `openWorld`\nflags. CRUD classification is fixed: list/get are read, create/update are write,\nand delete is destructive. An undeclared custom action deliberately defaults to\ndestructive, non-idempotent, and open-world so a browser capability policy never\nfails open.\n\nGenerated reads (`list`/`get`) on the REST and SvelteKit generators support conditional GET (helpers in `src/generators/conditional-get.ts`). ETag v2 (#1765): the validator is the table's change-feed version (`getTableVersion`) keyed by the request representation, so a **concrete** `If-None-Match` short-circuits into a 304 with an empty body **before** the collection query runs — an unchanged table revalidates with zero table scan. A wildcard `If-None-Match: *` is deferred until the payload builds (existence confirmed), so a missing item still returns 404, not a false 304. Tenant-scoped reads fold the active tenant into the representation (`resolveTenantEtagDiscriminator`) so one tenant's cached validator never satisfies another's read of the same URL. Routes whose GET renders via a **custom serializer** (which can load related tables the base-table version can't observe) keep the v1 body-hash ETag (`#1757`, query-first but correct); the default `toPublicJSON` path — all REST reads and non-serializer SvelteKit reads — uses v2. v2 is weakly consistent by design (the cost of not reading the data): a revalidation in the sub-statement window between a committed write and its feed append can return a stale 304 that self-heals on the next revalidation. The other v2 window — a deploy that changes the response shape WITHOUT a table write — is closed by the **#1764 ETag salt**: `computeTableVersionEtag(version, representation, manifestHash?)` folds the build's web-collection shape digest into the digest, so a shape-only redeploy busts every read validator (`undefined` reproduces the pre-#1764 unsalted value byte-for-byte for direct helper callers). The generated SvelteKit route bakes the digest in as a `MANIFEST_HASH` constant (via `generateConditionalGetRouteHelper`'s `manifestHash` option, sourced from `computeWebManifestHash(manifest)`) — automatic for the SvelteKit transport. The runtime `APIGenerator` auto-populates the same salt from the runtime registry with `computeRuntimeWebManifestHash()` when `APIConfig.manifestHash` is omitted; explicit `APIConfig.manifestHash` still wins for custom setups. The digest scope is get-OR-list (`selectWebEtagSaltEntries`), so **get-only** routes are salted too. Strong consistency still requires the v1 body-hash path. Cache-Control policy (unchanged from #1757): `private, no-cache` by default; public models may opt into shared caching via `@smrt({ api: { public: true | 'read', cache: { sMaxage } } })` → `public, max-age=0, s-maxage=<n>`; non-public models never emit shared-cache headers. Tenant-scoped models (any mode) never emit them either — bodies vary with session-cookie tenant context that URL-keyed shared caches cannot see; `sMaxage` is neutralized to `private, no-cache` with a one-time warning.\n\n## Generated dev-plane route (#2782)\n\n`src/vite-plugin/dev-plane-route.ts` emits `<routesDir>/_dev/[...tool]/+server.ts`\nonly when `svelteKit.devPlaneRoute.enabled === true` and\n`@happyvertical/smrt-dev-mcp/dev-plane` resolves from the consumer (same\nresolvability guard as `_resources`). The route is dev-only (`$app/environment`\n`dev`, else 404), refuses to start without `SMRT_DEV_MCP_TOKEN` (503), and\ndelegates everything else to `createDevPlane`, passing `getSmrtConfig(...).db`\nfrom the embedded access prelude (below) so the plane shares the app's\nconnection.\nCore never imports smrt-dev-mcp; only the generated file does, at consumer\nruntime. The route carries the auto-generated header so the sweep owns it.\n\nGenerated SvelteKit write routes (#2977) call `requireRoutePermission(locals, action)` after `requireRouteAuth`: CRUD writes need `<collection>.create|update|delete` and mutating custom actions `<collection>.<method>` in the session permission snapshot on `locals`, else 403 (fail-closed; `api.public: true` stays open, `tenantContext.superAdminBypass` skips). See `packages/users/agents/permissions.md`.\n\n## MCP protocol identifiers (#3219)\n\nMCP discovery preserves existing names matching `[A-Za-z0-9_.-]{1,64}`.\nPreviously invalid names use their first 31 sanitized ASCII characters, `_`,\nand the first 32 hex characters of SHA-256 over the JSON tuple\n`[original class name, lowercased action name, original raw tool name]`.\nThis makes long or punctuation-bearing identifiers deterministic without\ncollapsing common prefixes. Discovery reserves compliant names first and fails\nclosed on any duplicate raw name or final alias collision instead of advertising\nambiguous dispatch (including class names differing only by case across packages).\nConsumers must use the advertised name rather than constructing one.\n\nThe generator retains a separate class/action binding for each descriptor and\nemits that mapping for generated runtimes. Dispatch, task eligibility, tenant\nscoping, ordering, and STI metadata use this binding; protocol aliases are not\nexecution identities. The advertised catalog still gates execution. The direct\nruntime-template API accepts `toolTargets`; omitting it retains the legacy\n`object_action` convention for existing direct callers. Supply explicit targets\nfor canonicalized names or class names containing underscores. This contract\ndoes not change CLI, REST, or WebMCP identifiers.\n\n`MCPGenerator.getToolIdentity(tool)` exposes the generator-validated original\nclass, action, and raw generated name to in-process catalog composers. App MCP\nuses it for class allow-lists, tenant checks, and compatible workflow guards;\nthose consumers must not reverse protocol aliases. The alias remains the sole\nwire tool name and is still the key for public patterns and generic tool policy.\n\n`MCPConfig.classNames` scopes generation (simple names, case-insensitive, or\nqualified `@scope/pkg:Class`); omitted, every registered class is a candidate.\nA simple name matching more than one registered class throws (scope it by\nqualified name). Each tool keeps its class's registry key, and configuration,\nfields, methods, dispatch, tasks and collections resolve through that key —\nnever through the first same-named class. Generated servers (single-file and\nmodular) carry it as `registryKey` in their tool targets and task actions and\nuse it for every emitted collection, policy, class and STI-base lookup;\n`objectName` stays the wire/display name.\nA host with an allow-list passes it so the duplicate-name check runs over the\npublished set only: an unrelated collision among classes it never lists must\nnot fail its catalog or calls (#3490). App MCP always scopes its generators.\n\n## Generated route collection access (#3416)\n\nThere is no generated route-access module. Every generated SvelteKit route\nthat needs collections (CRUD, custom actions, `_changes`, `_events`,\n`sync/apply`, `_dev`) embeds the prelude from\n`generateCollectionAccessImports()` (`sveltekit-config-import.ts`): it imports\nthe generated `smrt-register` module, then the app's config module\n(`$lib/server/smrt` by default) as `* as smrtApplication`, and destructures\n`getCollection`/`getSmrtConfig` from `createGeneratedCollectionAccess()`\n(`src/generated-collection-access.ts`). Generation fails before writing\nanything when `configFileName` resolves to the registration module\n(`smrt-register` with any script extension or case).\nThat helper resolves per call, never caching: a legacy `getCollection` /\n`getSmrtConfig` export wins (deprecated, warned once per module, for one\nrelease), else the exported app-runtime `runtime.getCollection()` /\n`classOptions()`, else it fails with an error naming the module. `_resources`\nand static collection-scoped actions only need registration, so they import\n`smrt-register` and then the config module. When the config module is missing\nand `@happyvertical/smrt-app-runtime/sveltekit` resolves from the consumer, the\ngenerator writes a runtime-shaped default instead of the legacy\n`getCollection` file.\n\n## Enum-constrained fields (#3598)\n\nThe scanner emits `enum: [...]` on a manifest field typed as a TS enum or\nstring/number literal union. Registry-sourced fields mirror it into\n`_meta.enum` (`createFieldFromManifest` / `mergeManifestField`); read it with\n`readFieldEnum()` (top level first, then `_meta`), never directly. Generated\ntool schemas (`fieldTypeToJsonSchema`, so MCP and WebMCP descriptors), OpenAPI\n(`swagger.ts`) and the legacy `generateSchemaProperties` emit JSON Schema\n`enum` for `text`/`integer`/`decimal` fields only; a nullable field appends\n`null` to the list so `type: [.., 'null']` still validates. The client web\ncollection `fields` map does not carry `enum` yet (it feeds the shape digest and\nthree hand-mirrored d.ts files); tool inputs read it from the manifest field.\n"
     },
     {
       "path": "agents/build-knowledge.md",
       "module": "build-knowledge",
-      "content": "# Decorators, build integration, and knowledge\n\nKey options: `tableName`, `tableStrategy` ('cti'|'sti'), `conflictColumns`, `indexes` (declared multi-column indexes; see [schema-paths.md](schema-paths.md)), `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## Worker registration artifact (#3117)\n\nWith `svelteKit.enabled`, a production `vite build` compiles the generated\n`smrt-register.ts` into `.smrt/runtime/register.js` after the server build\n(`src/vite-plugin/worker-registration.ts`, called once from `closeBundle`).\nadapter-node re-bundles the server from its own entries, so the web bundle is\nnever importable by a separate Node process; this artifact is how a deployed\ntask/schedule worker registers the app's local objects (and, through the\n`.smrt/register.js` it imports, consumed packages' objects) with the same\nqualified identities and isolated manifests as the web server. It is a nested\nSSR build with no consumer plugins: only aliases pointing into the project\nsources (e.g. `$lib`) apply, and every other bare import stays external so the\nworker shares the installed `@happyvertical/smrt-core` registry. SvelteKit\nvirtual modules (`$env/*`, `$app/*`) are not available to a worker; an object\nimporting one fails at worker startup. A failure fails the build.\n\n## Lightweight discovery\n\nFilesystem-only discovery, module-doc parsing, and graph freshness are owned by\n`@happyvertical/smrt-scanner/knowledge`. Core's knowledge exports remain compatible\nreexports. Runtime manifest projection and custom-action semantics stay in core.\n\n`src/knowledge-discovery.ts`, exported through `smrt-core/knowledge`, enumerates\ninstalled scope directories and reads canonical AGENTS/legacy CLAUDE docs without\nloading package code, artifacts, or scanning objects. CLI snapshots and MCP share\nthese primitives. Callers retain selection policy: snapshots resolve links and\nfall back to `packages/*` only when no installed SMRT package loads; MCP preserves\nnode_modules paths, deduplicates realpaths, excludes authored workspace links,\nand then enriches the selected packages. Workspace-root/glob discovery remains\nowned by each consumer.\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 CLI's schema-command gate reads that same merged file: a pure-consumer\nproject (0 local objects) qualifies on the consumed packages its manifest\nrecords, so a clobbered `objects` map is what made `smrt db:migrate` report\n`missing_local_manifest` (#2925).\n\n`.smrt/manifest.json` has two writers and neither owns all of it: `smrtPlugin()`\ncontributes the project's scanned objects and `smrtConsumer()` the consumed\npackages' entries. Both writes are merge-preserving, keyed on each entry's\nrecorded `packageName` — a plain overwrite in either direction silently drops\nthe other's objects, and the last pass of a multi-environment build is not\nreliably the aggregating one (#1760, #2925). `dist/manifest.json` stays\nlocal-only: a published package must not carry its dependencies' objects.\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\nTest generation uses that same effective configuration and publishes knowledge\nmatching the manifest it generated. Disabling knowledge removes a previous local\nknowledge artifact, so consumers cannot mistake it for current enabled output.\n`new ManifestBuilder(projectRoot)` keeps discovery, package identity, and output\nat that explicit root, including installed providers and external base classes;\nomitting the argument retains the current-working-directory\nbehavior. Both manifest writers retain declared package dependencies when merging\ntheir local and consumed-object projections.\n\nTest manifests carry optional `artifactPurpose: 'test'`; dependency discovery\nskips those artifacts, including `.smrt` fallbacks. Unmarked runtime manifests,\nempty published providers, and source-only development providers remain eligible.\n`ManifestBuilder` accepts explicit `outputMode: 'dev' | 'build'`; omitted mode\nretains legacy filename inference. Vitest selects dev mode explicitly, so tests\nnever replace a production `dist/manifest.json`. Relative output directories are\nresolved against the builder's project root.\n\nWith `svelteKit.enabled`, `smrtPlugin()`'s transform prepends\n`import './smrt-register.js';` to the configured config module\n(`<configPath>/<configFileName>`, `src/vite-plugin/sveltekit-register-injection.ts`)\nonce the register module exists, on the same first line so line numbers hold.\nApps therefore never hand-write the guarded registration import (#3416); a\nconfig module that still has it imports the same module twice, harmlessly.\n\nTracked `src/lib/server/smrt-register.ts` belongs to SvelteKit config/type\ngeneration. Generic library builds consume it but do not cache or restore it\nas an output; otherwise a concurrent config producer's bytes can be replayed\nover a newer registration after dependency eligibility changes.\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\n## Vite Plugin\n\n`src/vite-preset/` (`@happyvertical/smrt-core/vite`, `smrt()`) composes the Oxc\ndecorator block, `smrtConsumer`, then `smrtPlugin` with the template path\nconventions. Its package list comes only from the `smrt({ packages })` option, or\n`smrt.config` `consumer.packages` (smrt-config schema); it never sniffs\n`package.json`, and a missing or malformed list throws. Keep its output\nbyte-identical to the two-plugin form (`src/vite-preset/index.test.ts`). It\nalso dedupes `@sveltejs/kit` (`smrt:shared-runtime`): SvelteKit matches\n`redirect()`/`fail()` by class, and a linked/workspace SMRT SvelteKit entry\nwould otherwise import its own copy and turn redirects into 500s.\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\nFor independent CI invocations, both `smrtPlugin()` and `smrtConsumer()` accept\nthe same `generationSnapshot: { path, sha256, provenance, sourceRoot }`. The\nschema-v1 snapshot produced by `serializeSmrtGenerationSnapshot()` contains the\nmerged project/dependency manifest, portable source paths, and source-file\ndigests; each plugin selects its own view. Reuse mode fails closed on\nbyte/provenance/path/content drift, skips scans and manifest writes, and still\ngenerates routes, types, registration, and virtual modules. Omit it for normal\nlocal development and watch mode.\n\n## Clean consumer type checks (TypeScript 6)\n\nThe consumer config hook writes `.smrt/register.js` alongside generated types\nafter route preflight succeeds. Generated SvelteKit registration imports that\nmodule, so it must exist during `svelte-kit sync`, before Vite's `buildStart`.\nBoth hosted routes and the legacy `svelteKit: true` mode follow this order.\nThe clean-consumer regression fixture ships real provider declarations and\nchecks the generated imports with `svelte-check`.\nCore's `generate:test` task depends on its own `build`: both publish the local\n`.smrt` manifest/knowledge pair, so Turbo must serialize production before test\ngeneration instead of caching an interleaved pair.\n"
+      "content": "# Decorators, build integration, and knowledge\n\nKey options: `tableName`, `tableStrategy` ('cti'|'sti'), `conflictColumns`, `indexes` (declared multi-column indexes; see [schema-paths.md](schema-paths.md)), `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`ui.widget` (#3599) adds a presentation widget hint:\n`'textarea' | 'currency' | 'email' | 'url' | 'phone'`. It rides the same\n`_meta.ui` channel and is also emitted (sanitized) into web-collection\ndefinitions. The manifest generator validates it against the field type and\nfails the build otherwise: every widget needs a `text` field (`currency` is a\ncurrency-CODE picker for an ISO 4217 string such as `currency = 'USD'`, not a\nmoney amount; amounts are integer minor units and take no widget); an unknown\nvalue or a non-text field is an error. `ui.widget` is a hint only — it never changes\nthe column type or validation.\n\n## Presentation metadata (#3599)\n\nPure helpers live in `src/ui-metadata.ts`, published browser-safe as\n`@happyvertical/smrt-core/ui-metadata` (also re-exported from the package\nroot). `ManifestGenerator.applyUiMetadata()` runs in `applyGenerationPasses`\nafter inheritance, so every producer (Vite plugin, `ManifestBuilder`,\n`generateManifest`) validates the same way.\n\n- **Display label.** `@smrt({ display: { label: '<field>' } })` names the own\n  field generic pickers and assistants use to label a record. Own fields only —\n  no paths into other packages; a model whose label lives elsewhere ships a\n  selector. Undeclared, it defaults to the first of `name`, `title`, `label`,\n  `code` that is a usable own field. Build fails when the declared field is\n  missing, `sensitive`, `transient`, or a relationship/json field. The resolved\n  field is emitted as `displayLabelField` on the manifest object and in the\n  knowledge artifact, and generated MCP/WebMCP `list`/`get`/`update`/`delete`\n  descriptions end with ``Records are identified by their `<field>` field.``\n  (`describeAction` in `generators/tool-schema.ts`; nothing is added when the\n  model has no label field).\n- **Selector slots.** `ModuleUISlot.selects: '@scope/pkg:Model'`\n  (`@happyvertical/smrt-types`) marks a package component as THE selector for a\n  model. The scanner reads such slots statically from `src/**/ui.ts`\n  (`parseUiSelectorsFile`, independent of the class glob) and the manifest\n  carries them as `uiSelectors` keyed by slot id. `selects` must be a string\n  literal; a duplicate slot id, two selectors for one model, or an own-package\n  target that does not exist fails the build. Hosts call\n  `findSelectorFor(manifests, qualifiedName)`; generic forms use the selector\n  for any `@foreignKey`/`@crossPackageRef` field targeting that model and fall\n  back to a generic picker labelled by `displayLabelField`. `display` is read\n  per class: an STI subclass that declares none uses the default lookup rather\n  than its base's declaration, and a CTI child cannot name a parent's field.\n\n## Worker registration artifact (#3117)\n\nWith `svelteKit.enabled`, a production `vite build` compiles the generated\n`smrt-register.ts` into `.smrt/runtime/register.js` after the server build\n(`src/vite-plugin/worker-registration.ts`, called once from `closeBundle`).\nadapter-node re-bundles the server from its own entries, so the web bundle is\nnever importable by a separate Node process; this artifact is how a deployed\ntask/schedule worker registers the app's local objects (and, through the\n`.smrt/register.js` it imports, consumed packages' objects) with the same\nqualified identities and isolated manifests as the web server. It is a nested\nSSR build with no consumer plugins: only aliases pointing into the project\nsources (e.g. `$lib`) apply, and every other bare import stays external so the\nworker shares the installed `@happyvertical/smrt-core` registry. SvelteKit\nvirtual modules (`$env/*`, `$app/*`) are not available to a worker; an object\nimporting one fails at worker startup. A failure fails the build.\n\n## Lightweight discovery\n\nFilesystem-only discovery, module-doc parsing, and graph freshness are owned by\n`@happyvertical/smrt-scanner/knowledge`. Core's knowledge exports remain compatible\nreexports. Runtime manifest projection and custom-action semantics stay in core.\n\n`src/knowledge-discovery.ts`, exported through `smrt-core/knowledge`, enumerates\ninstalled scope directories and reads canonical AGENTS/legacy CLAUDE docs without\nloading package code, artifacts, or scanning objects. CLI snapshots and MCP share\nthese primitives. Callers retain selection policy: snapshots resolve links and\nfall back to `packages/*` only when no installed SMRT package loads; MCP preserves\nnode_modules paths, deduplicates realpaths, excludes authored workspace links,\nand then enriches the selected packages. Workspace-root/glob discovery remains\nowned by each consumer.\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 CLI's schema-command gate reads that same merged file: a pure-consumer\nproject (0 local objects) qualifies on the consumed packages its manifest\nrecords, so a clobbered `objects` map is what made `smrt db:migrate` report\n`missing_local_manifest` (#2925).\n\n`.smrt/manifest.json` has two writers and neither owns all of it: `smrtPlugin()`\ncontributes the project's scanned objects and `smrtConsumer()` the consumed\npackages' entries. Both writes are merge-preserving, keyed on each entry's\nrecorded `packageName` — a plain overwrite in either direction silently drops\nthe other's objects, and the last pass of a multi-environment build is not\nreliably the aggregating one (#1760, #2925). `dist/manifest.json` stays\nlocal-only: a published package must not carry its dependencies' objects.\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\nTest generation uses that same effective configuration and publishes knowledge\nmatching the manifest it generated. Disabling knowledge removes a previous local\nknowledge artifact, so consumers cannot mistake it for current enabled output.\n`new ManifestBuilder(projectRoot)` keeps discovery, package identity, and output\nat that explicit root, including installed providers and external base classes;\nomitting the argument retains the current-working-directory\nbehavior. Both manifest writers retain declared package dependencies when merging\ntheir local and consumed-object projections.\n\nTest manifests carry optional `artifactPurpose: 'test'`; dependency discovery\nskips those artifacts, including `.smrt` fallbacks. Unmarked runtime manifests,\nempty published providers, and source-only development providers remain eligible.\n`ManifestBuilder` accepts explicit `outputMode: 'dev' | 'build'`; omitted mode\nretains legacy filename inference. Vitest selects dev mode explicitly, so tests\nnever replace a production `dist/manifest.json`. Relative output directories are\nresolved against the builder's project root.\n\nWith `svelteKit.enabled`, `smrtPlugin()`'s transform prepends\n`import './smrt-register.js';` to the configured config module\n(`<configPath>/<configFileName>`, `src/vite-plugin/sveltekit-register-injection.ts`)\nonce the register module exists, on the same first line so line numbers hold.\nApps therefore never hand-write the guarded registration import (#3416); a\nconfig module that still has it imports the same module twice, harmlessly.\n\nTracked `src/lib/server/smrt-register.ts` belongs to SvelteKit config/type\ngeneration. Generic library builds consume it but do not cache or restore it\nas an output; otherwise a concurrent config producer's bytes can be replayed\nover a newer registration after dependency eligibility changes.\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\n## Vite Plugin\n\n`src/vite-preset/` (`@happyvertical/smrt-core/vite`, `smrt()`) composes the Oxc\ndecorator block, `smrtConsumer`, then `smrtPlugin` with the template path\nconventions. Its package list comes only from the `smrt({ packages })` option, or\n`smrt.config` `consumer.packages` (smrt-config schema); it never sniffs\n`package.json`, and a missing or malformed list throws. Keep its output\nbyte-identical to the two-plugin form (`src/vite-preset/index.test.ts`). It\nalso dedupes `@sveltejs/kit` (`smrt:shared-runtime`): SvelteKit matches\n`redirect()`/`fail()` by class, and a linked/workspace SMRT SvelteKit entry\nwould otherwise import its own copy and turn redirects into 500s.\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\nFor independent CI invocations, both `smrtPlugin()` and `smrtConsumer()` accept\nthe same `generationSnapshot: { path, sha256, provenance, sourceRoot }`. The\nschema-v1 snapshot produced by `serializeSmrtGenerationSnapshot()` contains the\nmerged project/dependency manifest, portable source paths, and source-file\ndigests; each plugin selects its own view. Reuse mode fails closed on\nbyte/provenance/path/content drift, skips scans and manifest writes, and still\ngenerates routes, types, registration, and virtual modules. Omit it for normal\nlocal development and watch mode.\n\n## Clean consumer type checks (TypeScript 6)\n\nThe consumer config hook writes `.smrt/register.js` alongside generated types\nafter route preflight succeeds. Generated SvelteKit registration imports that\nmodule, so it must exist during `svelte-kit sync`, before Vite's `buildStart`.\nBoth hosted routes and the legacy `svelteKit: true` mode follow this order.\nThe clean-consumer regression fixture ships real provider declarations and\nchecks the generated imports with `svelte-check`.\nCore's `generate:test` task depends on its own `build`: both publish the local\n`.smrt` manifest/knowledge pair, so Turbo must serialize production before test\ngeneration instead of caching an interleaved pair.\n"
     },
     {
       "path": "agents/memory.md",
@@ -1197,6 +1199,11 @@
       "module": "run-once",
       "content": "# runOnce: shared idempotency seam (#3080)\n\n`src/run-once.ts`. A DB/transaction-level primitive — it takes a\n`DatabaseInterface`, not a `SmrtObject`/`SmrtCollection` — so it works outside\nSvelteKit and outside the ORM. Any caller with a database handle and a\nJSON-serializable work result can use it.\n\n## Why this exists, and why it is not the token alone\n\nEvery consumer with a form, a retried request, or a double-tapped button\nneeds the same guard, and a first hand-rolled attempt at it (reported against\nthis issue) keyed the claim on the per-form token alone. That silently\ncollapsed two genuinely different submissions that happened to reuse one\nform's token — the exact bug this primitive exists to prevent everyone from\nre-introducing.\n\n## Key derivation\n\n```\nnormalized    = normalizeRunOnceContent(content)   // one pass; FormData captured as a node\ncontentDigest = containsFormData(normalized)\n  ? sha256(\"\\u0001run-once-formdata-v1\\n\" + stableStringify(toFormDataDomain(normalized)))\n  : sha256(stableStringify(normalized))              // plain JSON: unchanged since #3080\nclaimKey      = sha256(stableStringify([tenantId, actor, token, contentDigest]))\n```\n\n`stableStringify` (`../src/knowledge-graph.ts`) is sorted-key JSON: property\ninsertion order never changes the digest. Content is normalized first, following\nJSON serialization exactly: `toJSON(key)` is called with the property name or\narray index (a `Date` digests as its ISO string, not `{}`), and `undefined`,\nfunction and symbol values are omitted from objects and written as `null` in\narrays. A `FormData` has no enumerable properties, so\nJSON would reduce every form to `{}`; it digests as its ordered entry list\ninstead (repeated fields are significant; a `File` digests by name, type and\nsize), hashed in a separate domain (the input is prefixed with a byte sorted-key\nJSON never starts with, and user keys starting with NUL are escaped) so no plain\nobject can forge it and plain-JSON digests are unchanged. `Map`, `Set`,\n`RegExp`, any other non-plain object without `toJSON()`, and `bigint` throw a\n`TypeError` rather than silently hashing as `{}` (#3136). Folding in `tenantId`\nand `actor`\nmeans two tenants or two actors can never collide on the same claim even if a\ntoken were somehow shared between them; folding in `contentDigest` means a\nretry of the SAME submission (same token, same content) replays, while a\nDIFFERENT submission through the same token (edited content before a\nresubmit) runs as its own claim.\n\nNeither the raw token nor the raw content is ever persisted — only their\ndigests — so `_smrt_run_once_claims` cannot leak submitted business data.\n\n## Placement: `smrt-core`, not `smrt-svelte`\n\nThe issue posed this as a judgement call. `runOnce()` lives in `smrt-core`\nbeside the other write primitives (`object.ts`, `collection.ts`) because:\n\n- It is DB/transaction-level, not SvelteKit-specific — any caller with a\n  `DatabaseInterface` can use it, including CLI jobs, MCP tool handlers, and\n  non-web callers.\n- The claim table must exist for every `smrt-core` consumer, not only ones\n  that also depend on `smrt-svelte`.\n\nThe browser half did not ship with it; it now lives in\n`@happyvertical/smrt-ui/form-retry` (`createFormRetry()`, #3291): a per-tab,\nper-form submission key in `sessionStorage` with an in-memory fallback,\nrotated only on a confirmed write that cleared the form, refused while a\nsubmit is in flight, kept with the typed values across a transport error, and\noptional restore-after-reload so the retry carries byte-identical content. It\nis in `smrt-ui` rather than `smrt-svelte` because smrt-ui is the dependency\nleaf that both `smrt-svelte` and plain SvelteKit apps can use, and its `Form`\ntakes `enhance` and the retry attachment directly (smrt#3265: attach\n`fromAction(enhance, () => retry.enhance())` and `retry.attach`). It is typed\nstructurally against SvelteKit's `SubmitFunction`, so smrt-ui takes no\n`@sveltejs/kit` dependency. Its `digestSubmissionContent()` is a Web Crypto port of\n`digestRunOnceContent()`; `src/__tests__/issue-3291-digest-vectors.test.ts`\npins vectors shared with the port, so change both together (and remember a\ndigest change re-keys every stored claim). Guide:\n[form retry](../../../docs/content/form-retry.md).\n\n## Schema: a hand-DDL system table, not an `@smrt()` model\n\n`_smrt_run_once_claims` is declared in `src/system/schema.ts`\n(`CREATE_SMRT_RUN_ONCE_CLAIMS_TABLE`), added to `ALL_SYSTEM_TABLES`, and\ncreated by `ensureSystemTables()` / `bootstrapSystemTables()`\n(`src/system/bootstrap.ts`) — the same mechanism that creates\n`_smrt_migrations` and `_smrt_contexts`. This is \"Mechanism A\" in the\n`_smrt_` prefix classification ([schema-paths.md](schema-paths.md)), not\n\"Mechanism B\" (an `@smrt()`-decorated model migrated via `db:migrate`, like\n`_smrt_jobs`).\n\nThis was a deliberate choice, not the default: `runOnce()` must work for any\n`smrt-core` consumer without that consumer registering a class and running a\nmigration for a table they've never heard of. A Mechanism-B table only exists\nonce an app imports and registers its owning class; a Mechanism-A table\nexists for every `smrt-core` database unconditionally, which is what a\nframework-wide primitive needs.\n\nAdding the table required:\n\n- A new DDL constant in `ALL_SYSTEM_TABLES`.\n- Bumping `SMRT_SCHEMA_VERSION` (1.10.1 → 1.11.0) — `CREATE TABLE IF NOT\n  EXISTS` is a no-op on an existing database, so nothing upgrades without the\n  bump.\n- A new `SMRT_SCHEMA_DDL_CHECKSUMS` entry — `system-schema-evolution.test.ts`\n  recomputes the DDL hash and fails the build if it does not match the\n  recorded value for the current version.\n\nNo new column was added to an existing system table, so no\n`addColumnIfMissing()` entry in `system/compatibility.ts` was needed. Live\nschema parity (`checkLiveSchemaParity`, `smrt doctor --db` /\n`db:status --parity`) picks the table up automatically: system-table shape\nparsing (`schema/system-table-shapes.ts`) derives its expectation from the\nsame DDL rather than a hand-maintained list.\n\n## Table shape\n\n```sql\nCREATE TABLE IF NOT EXISTS _smrt_run_once_claims (\n  claim_key TEXT PRIMARY KEY,       -- the derived key above\n  tenant_id TEXT NOT NULL,          -- redundant with claim_key; kept for admin queries and a defense-in-depth tenant filter on lookup\n  actor TEXT NOT NULL,              -- same\n  content_digest TEXT NOT NULL,     -- same, plus lets an operator distinguish \"same token, different content\" incidents\n  status TEXT NOT NULL DEFAULT 'in_progress',  -- 'in_progress' | 'completed'\n  result TEXT,                      -- JSON-serialized work() return value, set only when status = 'completed'\n  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,\n  completed_at TIMESTAMP\n);\n```\n\n`claim_key` is the PRIMARY KEY — the \"insert-only against a UNIQUE column\"\nthe issue asked for. A second `INSERT` for the same key never adopts the\nexisting row.\n\n**Why the claim insert is raw SQL (`INSERT ... ON CONFLICT (claim_key) DO\nNOTHING RETURNING claim_key`), not a plain `INSERT` caught for a classified\n`unique_violation`:** on PostgreSQL, a statement that raises an error aborts\nthe WHOLE transaction (\"current transaction is aborted, commands ignored\nuntil end of transaction block\") — every later statement in that same\ntransaction fails too, including the `SELECT` `runOnce()` needs to read the\nwinner's stored result back. A first version of this primitive did exactly\nthat (plain `INSERT` + catch classified via `isUniqueViolationError`,\n`../src/db-errors.ts`) and every replay/double-submit on PostgreSQL broke:\nreview caught it before merge. `DO NOTHING` never raises — it reports zero\nrows via `RETURNING` instead — so the transaction's error state is never\ntouched. SQLite and DuckDB support the identical `ON CONFLICT ... DO\nNOTHING` / `RETURNING` syntax (already used elsewhere in this codebase for\n`_smrt_migrations`, `system/bootstrap.ts`), so one query is portable across\nevery adapter without engine branching.\n\n## Atomicity and rollback\n\n`runOnce()` opens `db.transaction()` (or nests under a caller-supplied\ntransaction, per `@happyvertical/sql`'s own SAVEPOINT /\n`NestedTransactionError` rules) and, inside it: inserts the claim\n(`in_progress`), runs `work(tx)` with that SAME transaction-bound handle, then\nupdates the claim to `completed` with the JSON-serialized result — all one\ntransaction.\n\nIf `work()` throws, the callback throws, and `db.transaction()`'s own\ncommit-on-success/rollback-on-error contract undoes the claim insert along\nwith whatever `work()` partially wrote. A claim is never stranded\n`in_progress` by a failed attempt; a retry with the same key can always run\nagain. No compensating delete is needed — this falls out of using one\ntransaction for the whole claim+work+completion sequence, not a special case\nin `runOnce()`'s own code.\n\n## Concurrency\n\n`@happyvertical/sql`'s single-connection adapters (SQLite, DuckDB, JSON)\nserialize `transaction()` calls on one connection: a second, concurrent\n`runOnce()` call does not begin its own transaction until the first ends.\nPostgreSQL pools, but the claim insert's arbiter still has to check the\nunique index against another transaction's uncommitted row of the same\nPRIMARY KEY, and blocks until that transaction resolves, then either no-ops\n(committed — `DO NOTHING` fires, zero rows) or inserts (rolled back). On\nevery adapter, two concurrent callers with the same key never both run\n`work()`, and the loser never sees a PostgreSQL error for it — only zero\nrows back, at which point it reads the now-committed, now-`completed` claim\nrow and replays its stored result.\n\nThis is also why the \"in flight\" and \"unknown outcome\" branches below are\nnormally unreachable through `runOnce()`-to-`runOnce()` races alone on a\nsingle connection — the losing transaction can only ever observe a\nCOMMITTED row, and this module only ever commits a row once it is\n`completed`. They are kept as defined answers (not assumptions) for a claim\nrow that reached that state some other way, and are exercised in\n`src/__tests__/issue-3080-run-once.test.ts` by seeding the table directly and\nby unit-testing the pure resolver (`resolveExistingRunOnceClaim`).\n\n## Typed answers: refused vs. unknown outcome (mirrors #2990)\n\nA conflict on insert is a *definite* decision — the row exists — but whether\nit is safe to hand back a result depends on `status`:\n\n| Row state after conflict | Result |\n|---|---|\n| `status: 'completed'` | Replay the stored `result`. No error. |\n| exists, not completed | `RunOnceClaimError.inFlight()` — `code: 'RUN_ONCE_IN_FLIGHT'`. Some execution holds this key right now; retry later with the SAME token and content. |\n| conflict reported, no row readable | `RunOnceClaimError.outcomeUnknown()` — `code: 'RUN_ONCE_OUTCOME_UNKNOWN'`. Genuinely indeterminate; retrying with the SAME token and content is still safe. |\n\nBoth error codes live on one `RunOnceClaimError` class (`src/errors.ts`),\nfollowing this codebase's existing error-hierarchy convention (one class,\nmultiple codes via static factories — see `TenantIsolationError`,\n`DatabaseError`) rather than a bespoke class hierarchy. Neither is retried\nautomatically by `runOnce()` itself: only the caller knows whether retrying\ninline is appropriate for its own request.\n\n## Retention: completed claims are pruned; the window is a replay deadline\n\n`_smrt_run_once_claims` is append-only in normal operation — every submission\nadds a row and nothing else ever deletes one — so, like `_smrt_changes`,\n`_smrt_ai_usage`, and `_smrt_dispatch`, it is wired into\n`system/retention.ts`'s `runRetentionSweep()` as a built-in task\n(`'run-once-claims'`), covered by `DEFAULT_RETENTION_POLICY.runOnceClaims`\n(default `{ maxAgeDays: 30 }`, overridable per policy or disabled with\n`runOnceClaims: false`). `pruneRunOnceClaims()` deletes only rows with\n`status = 'completed'` AND `completed_at` older than the window; an\n`'in_progress'` row has no `completed_at` and can never match this predicate,\nso a claim held by a live (or abandoned) transaction is never pruned by age\nalone. The predicate is covered by\n`idx_smrt_run_once_claims_status_completed` (`status, completed_at`), added\nin `SMRT_SCHEMA_VERSION` 1.11.1.\n\n**The window is a replay deadline, not just disk hygiene.** `runOnce()`'s\nentire contract — a retry or double-submit with the SAME token and content\nreplays the first attempt's stored result instead of running `work()` again\n— depends on the claim row still existing. Once retention sweeps a completed\nclaim, a client that replays that exact request (same `tenantId`, `actor`,\n`token`, and content) no longer collides with anything: `runOnce()` sees no\nexisting row, wins the insert, and runs `work()` a second time. This is\nsilent — there is no error, just a second execution of whatever `work()`\ndoes. The default 30-day window is chosen to be comfortably longer than any\nrealistic client retry window (a browser tab left open, a queued mobile\nrequest, a webhook redelivery schedule) for the same reason the other\ndefault windows in `DEFAULT_RETENTION_POLICY` are generous relative to their\nconsumers (see `system/retention.ts`'s module doc). A consumer with a\nlonger-lived retry/replay window (e.g. an at-least-once delivery queue with a\nmulti-week redelivery tail) must raise `runOnceClaims.maxAgeDays` to exceed\nit, not rely on the default.\n\nTests: `src/__tests__/issue-2375-retention.test.ts` covers\n`pruneRunOnceClaims()` end-to-end through `runRetentionSweep()` — an old\ncompleted claim is removed, a recent completed claim and an old\n`in_progress` claim both survive.\n\n## Tests\n\n`src/__tests__/issue-3080-run-once.test.ts` (real in-memory SQLite via\n`getTestDatabase({ classes: [] })` — no `@smrt()` model is needed, only the\nsystem table):\n\n- Runs work once; returns its result.\n- Retry after completion replays the stored result without re-running.\n- Concurrent double submit (`Promise.all`) produces one claim row and the\n  same result for both callers.\n- Same token, different content → two separate claims (guards the\n  token-alone regression this issue was filed against).\n- Same token/content, different actor → separate claim.\n- Same token/content, different tenant → separate claim.\n- Work throws → claim rolls back; a subsequent retry with the same key runs.\n- A claim seeded directly as `in_progress` → `RunOnceClaimError.inFlight()`,\n  `work()` never called.\n- Content-digest stability (key order) and sensitivity (value change) are\n  unit-tested directly.\n- `resolveExistingRunOnceClaim` (pure resolver) is unit-tested for all three\n  branches, including the otherwise-unreachable `outcomeUnknown` case.\n\n`src/__tests__/issue-3080-run-once-postgres.optional.test.ts` (real\nPostgreSQL, `SMRT_TEST_POSTGRES_URL`, `describe.skipIf`, following\n`change-feed-concurrency.optional.test.ts`'s established pattern: distinct\n`dbid`s for two genuinely concurrent connections, `getTestDatabase({ db,\nclasses: [] })` to bootstrap system tables): replay after completion, and\nconcurrent double submit across the two real connections — both would\nreject with a PostgreSQL `DatabaseError` (\"Failed to retrieve record from\ntable\", the driver's wrapping of 25P02 \"current transaction is aborted\")\nagainst the pre-fix plain-`INSERT`-and-catch version; verified locally\nagainst a disposable `postgres:18-alpine` container (revert via patch file,\nconfirmed both tests red, restored, confirmed both green) since the SQLite\nsuite cannot reach this PostgreSQL-specific failure mode at all.\n"
     },
+    {
+      "path": "agents/recipes.md",
+      "module": "recipes",
+      "content": "# SmrtRecipe: declared units of app functionality (#3590)\n\nA **recipe** is a small, named, user-facing unit (\"Sales\", \"Customers\"),\nsmaller than a package. An app or agent adds a recipe and gets that section:\nnavigation, list and create/edit views, and its prerequisites, without every\nmodel in the owning package. Source: `src/recipe.ts` (authoring base class),\n`packages/scanner/src/recipes.ts` (matcher and validation), types in\n`@happyvertical/smrt-types` (`RecipeDefinition`).\n\n## Authoring\n\n`SmrtRecipe` is an abstract, **non-persisted, non-`@smrt()`** base class\nexported from both core entries (`index.ts` and `browser.ts`). A recipe is a\nsubclass with static properties, in the package that owns its models:\n\n```ts\nexport class SalesRecipe extends SmrtRecipe {\n  static id = 'commerce.sales';          // dotted lowercase, unique\n  static label = 'Sales';\n  static summary = 'Take customer orders and track them.';\n  static synonyms = ['sales orders', 'orders'];\n  static models = [Order];               // class references\n  static nav = [{ label: 'Sales Orders', model: Order }];\n  static requires = ['commerce.customers']; // recipe ids, any package\n  static options = { Order: { fields: { status: { default: 'draft' } } } };\n}\n```\n\nStatics are read **structurally** (nothing is evaluated), so each must be\nspelled literally; `models` and `nav[].model` take identifiers. Write\n`static options = { ... } as const` so `visibility` stays a literal type.\nThe emitted `options` are keyed by qualified model name.\n\n## How the scanner collects it\n\nThe scanner class pass finds classes by decorator, which a recipe lacks, so\n`recipes.ts` is a second matcher in the style of the agent-surface one: a class\nwhose `extends` resolves to the `SmrtRecipe` import binding from\n`@happyvertical/smrt-core` (named, aliased `SmrtRecipe as R`, or namespace\n`Core.SmrtRecipe`; any core subpath such as `/browser`). A same-named local\nclass or an import from another library is not a recipe. A recipe must extend\n`SmrtRecipe` **directly**. Within one file, extending another recipe or declaring\none as a class expression or inside a block is a scan error rather than a silent\ndrop. Across files it is not detected: a module that never names `SmrtRecipe`\nis not read, so a recipe extending a recipe or intermediate base imported from\nanother module is unsupported and would be missing from the artifacts.\n\nClass references resolve to qualified names (`@scope/pkg:Class`) through the\nimport binding: a relative specifier picks the scanned class by file, then by\nclass name (barrel re-exports keep the name); an aliased import follows the\n*imported* name; `Ns.Class` namespace members and same-file classes work; a\nbare package specifier is rejected (models must belong to this package). When\nthe imported file declares no such class, the barrel fallback binds a same-named\nscanned class, so keep model class names unique within a package. This\nwas chosen over qualified-name strings because it type-checks and survives\nrenames; strings were not needed.\n\nRecipe discovery is independent of the model `include` glob (like intents; it is\nnot gated by the `agentSurface` option), and\n`ScanResults.recipes` is populated by `resolve()`. Every error is a scan error,\nso every producer that reads `scanAndResolve()` (`smrtPlugin`, `ManifestBuilder`)\nfails the build. (The legacy `ManifestGenerator.generateManifest()` path takes\npre-scanned results and never sees recipes.) The adapter qualifies names and emits a top-level `recipes` array in\n`manifest.json`; `buildDomainKnowledgeManifest` projects the same array into\n`smrt-knowledge.json`. A package with no recipe emits no key.\n\n## Build-time validation\n\nIds are dotted lowercase and unique; `models` is non-empty, resolvable, and\nduplicate-free; every `nav` model is in `models`; `requires` are well-formed,\nnot self-referential or duplicated, and acyclic within the package (ids in other\npackages cannot be checked at scan time); `options` name only listed models and\nand only the keys below. Field names are checked in core\n(`ManifestGenerator.assertRecipeOptions`, after inherited fields merge) against\nthe merged manifest, so STI-merged, tenant, and framework-base fields such as\n`parentId` are accepted along with the universal `id`, `slug`, `context`,\n`created_at`, `updated_at`; anything else fails the build.\n\n## options: curation hints, never a second schema\n\nKeyed by model class name. `fields.<name>` accepts the smrt-fields policy\nvocabulary: `default`, `label`, `help`, `order`, `visibility`\n(`basic | advanced | hidden`), `locked`; applying a recipe produces\nfield-policy rows. `exposure.<api|mcp|cli>` accepts only `false` or\nnon-empty `{ exclude: [...] }` naming a CRUD verb (`list`, `get`, `create`,\n`update`, `delete`) or a public instance method the model declares or inherits: `true` and `include` are\nrejected because they can widen what the model already declares. Custom fields are out of scope.\n\n## User-facing help (#3591)\n\nHelp is documentation for the people using the app, not developers. It lives\nbeside the recipe as Markdown and is pointed to by `static help`:\n\n```ts\nexport class SalesRecipe extends SmrtRecipe {\n  // ...\n  static help = './sales.recipe.md'; // relative to the recipe file, .md only\n}\n```\n\nThe file holds an **Overview** and **Tasks** (short how-tos). A step names a\nfield as `{field:<fieldName>}` or `{field:<Model>.<fieldName>}`; the Markdown\nblock (heading, paragraph, or list item) containing a reference is **tied to\nthat field**. Keep prose in the separate file rather than the recipe class.\nField text itself comes from `@field({ description })`, the user-facing seed\nsmrt-fields uses for form help; every field a recipe shows should carry one.\n\n**Emission.** The scanner reads the file (a missing, empty, non-`.md`, absolute\nor `..`-climbing path is a scan error) and emits\n`help: { markdown, fieldRefs }` on the recipe entry in `manifest.json` and\n`smrt-knowledge.json`, so a static host needs no further request.\n`fieldRefs` (distinct references as written, sorted) is **derived**, never\nauthored. Knowledge fields also carry `description` (sensitive fields stay\nexcluded). `ManifestGenerator.assertRecipeHelp` fails the build on a reference\nto a field the recipe's models do not declare, and on a `fieldRefs` list that\ndisagrees with the Markdown. The scanner has its own copy of the reference\ngrammar (`deriveHelpFieldRefs`; it cannot import core), so that comparison also\nkeeps the two from drifting. A reference to a **sensitive** or universal (`id`,\n`slug`, ...) field also fails the build: neither reaches the knowledge artifact,\nso a host building its field list from it would silently drop the step naming\none; describe such a field in prose without a reference.\n\nKnown limitation: the help file is a generator input, but editing only it does\nnot trigger a dev-server rescan (the watch matches source globs) and generation\nsnapshots do not digest it, so rebuild (or touch a `.ts` source) after editing.\n\n**Rendering.** `src/recipe-help.ts` is pure and browser-safe (exported from\nboth core entries). `renderHelp(help, models, options?)` takes the recipe's\nhelp plus the app's effective field policies (`HelpModel[]`; label, help,\nvisibility, disabled in smrt-fields vocabulary, with `@field` descriptions) and\nreturns `{ blocks, glossary, connect? }`:\n\n- `{field:x}` becomes the effective label;\n- a block tied to a hidden, disabled, undeclared, or **advanced** field (unless\n  `showAdvanced`) is dropped; a list item drops alone; a heading whose section\n  had content that was all dropped is pruned (a heading that never had content\n  stays);\n- the glossary lists each shown field with its effective help, else its\n  description. A shown field with neither is **skipped**, not listed blank;\n- `connect` is the collapsed \"Connect other tools\" section: the recipe's\n  generated REST routes, MCP tools and CLI commands (`options.surfaces`, from\n  the knowledge artifact), minus the recipe's `exposure` narrowing\n  (`options.exposure`). Hosts render it last.\n\nThe result is an AST of text nodes (`text`, `code`, `strong`, `em`), never HTML,\nso authored markup stays inert text and nothing needs sanitizing. Only\n`##`-`####` headings, paragraphs, flat lists and bold/italic/code are\nunderstood. `helpToMarkdown(rendered)` flattens it for hosts with their own\nrenderer; render that with raw HTML disabled. `validateHelp(help, models)`\nreturns the build-failure problems for hand-built entries.\n"
+    },
     {
       "path": "agents/test-types.md",
       "module": "test-types",

package/dist/ui-metadata.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Presentation metadata helpers (#3599): `@field({ ui: { widget } })` hints,
+ * the own-field display label, and selector-slot lookup.
+ *
+ * Pure and dependency-free so it is safe in browser bundles
+ * (`@happyvertical/smrt-core/ui-metadata`). The manifest generator, the MCP /
+ * WebMCP tool descriptors, the knowledge projection and host UIs all read the
+ * same rules from here.
+ */
+import type { ManifestUISelector, QualifiedClassName, SmartObjectManifest } from './scanner/types.js';
+/** Widget hints a field may declare via `@field({ ui: { widget } })`. */
+export declare const FIELD_UI_WIDGETS: readonly ["textarea", "currency", "email", "url", "phone"];
+export type FieldUIWidget = (typeof FIELD_UI_WIDGETS)[number];
+/** Manifest field types each widget may be applied to. */
+export declare const FIELD_UI_WIDGET_TYPES: Readonly<Record<FieldUIWidget, readonly string[]>>;
+export declare function isFieldUIWidget(value: unknown): value is FieldUIWidget;
+/**
+ * Fields tried, in order, when a model declares no
+ * `@smrt({ display: { label } })`.
+ */
+export declare const DEFAULT_DISPLAY_LABEL_FIELDS: readonly ["name", "title", "label", "code"];
+interface LabelCandidate {
+    type?: string;
+    sensitive?: boolean;
+    transient?: boolean;
+    _meta?: {
+        sensitive?: unknown;
+        transient?: unknown;
+    } | undefined;
+}
+/**
+ * Why `fieldName` cannot label a record of this model, or `null` when it can.
+ * Used both to validate an explicit declaration and to filter the default
+ * candidates.
+ */
+export declare function displayLabelFieldProblem(fields: Record<string, LabelCandidate>, fieldName: string): string | null;
+/**
+ * The own field generic pickers and assistants use to label a record: the
+ * declared `display.label` when present, otherwise the first of
+ * {@link DEFAULT_DISPLAY_LABEL_FIELDS} that is a usable own field. `undefined`
+ * when the model has none (it should then ship a selector).
+ */
+export declare function resolveDisplayLabelField(fields: Record<string, LabelCandidate>, declared?: string): string | undefined;
+/**
+ * Sentence appended to generated tool descriptions (#3599), including its
+ * leading separator; empty when the model has no label field.
+ */
+export declare function describeDisplayLabel(labelField: string | undefined): string;
+type SelectorHost = Pick<SmartObjectManifest, 'uiSelectors'>;
+/**
+ * The selector slot registered for a model, or `undefined`. Hosts render the
+ * package-owned component registered under `slot.slotId` for any
+ * `@foreignKey` / `@crossPackageRef` field whose target is `qualifiedName`, and
+ * fall back to a generic picker labelled by the model's display label field.
+ *
+ * Pass every manifest in scope; the first selector found wins.
+ */
+export declare function findSelectorFor(manifests: SelectorHost | readonly SelectorHost[], qualifiedName: QualifiedClassName | string): ManifestUISelector | undefined;
+export {};
+//# sourceMappingURL=ui-metadata.d.ts.map

package/dist/ui-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-metadata.d.ts","sourceRoot":"","sources":["../src/ui-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,oBAAoB,CAAC;AAE5B,yEAAyE;AACzE,eAAO,MAAM,gBAAgB,4DAMnB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D,0DAA0D;AAC1D,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAC1C,MAAM,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC,CASzC,CAAC;AAEF,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAKtE;AAED;;;GAGG;AACH,eAAO,MAAM,4BAA4B,6CAK/B,CAAC;AAYX,UAAU,cAAc;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS,CAAC;CAClE;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,EACtC,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAaf;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,EACtC,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CASpB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAI3E;AAED,KAAK,YAAY,GAAG,IAAI,CAAC,mBAAmB,EAAE,aAAa,CAAC,CAAC;AAE7D;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,YAAY,GAAG,SAAS,YAAY,EAAE,EACjD,aAAa,EAAE,kBAAkB,GAAG,MAAM,GACzC,kBAAkB,GAAG,SAAS,CAUhC"}

package/dist/ui-metadata.js

@@ -0,0 +1,85 @@
+//#region src/ui-metadata.ts
+/** Widget hints a field may declare via `@field({ ui: { widget } })`. */
+var FIELD_UI_WIDGETS = [
+	"textarea",
+	"currency",
+	"email",
+	"url",
+	"phone"
+];
+/** Manifest field types each widget may be applied to. */
+var FIELD_UI_WIDGET_TYPES = {
+	textarea: ["text"],
+	email: ["text"],
+	url: ["text"],
+	phone: ["text"],
+	currency: ["text"]
+};
+function isFieldUIWidget(value) {
+	return typeof value === "string" && FIELD_UI_WIDGETS.includes(value);
+}
+/**
+* Fields tried, in order, when a model declares no
+* `@smrt({ display: { label } })`.
+*/
+var DEFAULT_DISPLAY_LABEL_FIELDS = [
+	"name",
+	"title",
+	"label",
+	"code"
+];
+/** Field kinds that can never be a record's label (they are not its own value). */
+var NON_LABEL_FIELD_TYPES = /* @__PURE__ */ new Set([
+	"foreignKey",
+	"crossPackageRef",
+	"oneToMany",
+	"manyToMany",
+	"json",
+	"meta"
+]);
+/**
+* Why `fieldName` cannot label a record of this model, or `null` when it can.
+* Used both to validate an explicit declaration and to filter the default
+* candidates.
+*/
+function displayLabelFieldProblem(fields, fieldName) {
+	const field = fields[fieldName];
+	if (!field) return `it is not a field of this model`;
+	if (field.sensitive === true || field._meta?.sensitive === true) return `it is a sensitive field`;
+	if (field.transient === true || field._meta?.transient === true) return `it is a transient field`;
+	if (field.type && NON_LABEL_FIELD_TYPES.has(field.type)) return `a ${field.type} field is not the record's own value`;
+	return null;
+}
+/**
+* The own field generic pickers and assistants use to label a record: the
+* declared `display.label` when present, otherwise the first of
+* {@link DEFAULT_DISPLAY_LABEL_FIELDS} that is a usable own field. `undefined`
+* when the model has none (it should then ship a selector).
+*/
+function resolveDisplayLabelField(fields, declared) {
+	if (declared !== void 0) return displayLabelFieldProblem(fields, declared) === null ? declared : void 0;
+	return DEFAULT_DISPLAY_LABEL_FIELDS.find((name) => displayLabelFieldProblem(fields, name) === null);
+}
+/**
+* Sentence appended to generated tool descriptions (#3599), including its
+* leading separator; empty when the model has no label field.
+*/
+function describeDisplayLabel(labelField) {
+	return labelField ? `. Records are identified by their \`${labelField}\` field.` : "";
+}
+/**
+* The selector slot registered for a model, or `undefined`. Hosts render the
+* package-owned component registered under `slot.slotId` for any
+* `@foreignKey` / `@crossPackageRef` field whose target is `qualifiedName`, and
+* fall back to a generic picker labelled by the model's display label field.
+*
+* Pass every manifest in scope; the first selector found wins.
+*/
+function findSelectorFor(manifests, qualifiedName) {
+	const list = Array.isArray(manifests) ? manifests : [manifests];
+	for (const manifest of list) for (const selector of Object.values(manifest.uiSelectors ?? {})) if (selector.selects === qualifiedName) return selector;
+}
+//#endregion
+export { DEFAULT_DISPLAY_LABEL_FIELDS, FIELD_UI_WIDGETS, FIELD_UI_WIDGET_TYPES, describeDisplayLabel, displayLabelFieldProblem, findSelectorFor, isFieldUIWidget, resolveDisplayLabelField };
+
+//# sourceMappingURL=ui-metadata.js.map

package/dist/ui-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-metadata.js","names":[],"sources":["../src/ui-metadata.ts"],"sourcesContent":["/**\n * Presentation metadata helpers (#3599): `@field({ ui: { widget } })` hints,\n * the own-field display label, and selector-slot lookup.\n *\n * Pure and dependency-free so it is safe in browser bundles\n * (`@happyvertical/smrt-core/ui-metadata`). The manifest generator, the MCP /\n * WebMCP tool descriptors, the knowledge projection and host UIs all read the\n * same rules from here.\n */\n\nimport type {\n  ManifestUISelector,\n  QualifiedClassName,\n  SmartObjectManifest,\n} from './scanner/types.js';\n\n/** Widget hints a field may declare via `@field({ ui: { widget } })`. */\nexport const FIELD_UI_WIDGETS = [\n  'textarea',\n  'currency',\n  'email',\n  'url',\n  'phone',\n] as const;\n\nexport type FieldUIWidget = (typeof FIELD_UI_WIDGETS)[number];\n\n/** Manifest field types each widget may be applied to. */\nexport const FIELD_UI_WIDGET_TYPES: Readonly<\n  Record<FieldUIWidget, readonly string[]>\n> = {\n  textarea: ['text'],\n  email: ['text'],\n  url: ['text'],\n  phone: ['text'],\n  // A currency CODE (ISO 4217, e.g. `currency: string = 'USD'`) picker, not an\n  // amount: amounts are integer minor units and need no widget hint.\n  currency: ['text'],\n};\n\nexport function isFieldUIWidget(value: unknown): value is FieldUIWidget {\n  return (\n    typeof value === 'string' &&\n    (FIELD_UI_WIDGETS as readonly string[]).includes(value)\n  );\n}\n\n/**\n * Fields tried, in order, when a model declares no\n * `@smrt({ display: { label } })`.\n */\nexport const DEFAULT_DISPLAY_LABEL_FIELDS = [\n  'name',\n  'title',\n  'label',\n  'code',\n] as const;\n\n/** Field kinds that can never be a record's label (they are not its own value). */\nconst NON_LABEL_FIELD_TYPES = new Set([\n  'foreignKey',\n  'crossPackageRef',\n  'oneToMany',\n  'manyToMany',\n  'json',\n  'meta',\n]);\n\ninterface LabelCandidate {\n  type?: string;\n  sensitive?: boolean;\n  transient?: boolean;\n  _meta?: { sensitive?: unknown; transient?: unknown } | undefined;\n}\n\n/**\n * Why `fieldName` cannot label a record of this model, or `null` when it can.\n * Used both to validate an explicit declaration and to filter the default\n * candidates.\n */\nexport function displayLabelFieldProblem(\n  fields: Record<string, LabelCandidate>,\n  fieldName: string,\n): string | null {\n  const field = fields[fieldName];\n  if (!field) return `it is not a field of this model`;\n  if (field.sensitive === true || field._meta?.sensitive === true) {\n    return `it is a sensitive field`;\n  }\n  if (field.transient === true || field._meta?.transient === true) {\n    return `it is a transient field`;\n  }\n  if (field.type && NON_LABEL_FIELD_TYPES.has(field.type)) {\n    return `a ${field.type} field is not the record's own value`;\n  }\n  return null;\n}\n\n/**\n * The own field generic pickers and assistants use to label a record: the\n * declared `display.label` when present, otherwise the first of\n * {@link DEFAULT_DISPLAY_LABEL_FIELDS} that is a usable own field. `undefined`\n * when the model has none (it should then ship a selector).\n */\nexport function resolveDisplayLabelField(\n  fields: Record<string, LabelCandidate>,\n  declared?: string,\n): string | undefined {\n  if (declared !== undefined) {\n    return displayLabelFieldProblem(fields, declared) === null\n      ? declared\n      : undefined;\n  }\n  return DEFAULT_DISPLAY_LABEL_FIELDS.find(\n    (name) => displayLabelFieldProblem(fields, name) === null,\n  );\n}\n\n/**\n * Sentence appended to generated tool descriptions (#3599), including its\n * leading separator; empty when the model has no label field.\n */\nexport function describeDisplayLabel(labelField: string | undefined): string {\n  return labelField\n    ? `. Records are identified by their \\`${labelField}\\` field.`\n    : '';\n}\n\ntype SelectorHost = Pick<SmartObjectManifest, 'uiSelectors'>;\n\n/**\n * The selector slot registered for a model, or `undefined`. Hosts render the\n * package-owned component registered under `slot.slotId` for any\n * `@foreignKey` / `@crossPackageRef` field whose target is `qualifiedName`, and\n * fall back to a generic picker labelled by the model's display label field.\n *\n * Pass every manifest in scope; the first selector found wins.\n */\nexport function findSelectorFor(\n  manifests: SelectorHost | readonly SelectorHost[],\n  qualifiedName: QualifiedClassName | string,\n): ManifestUISelector | undefined {\n  const list = Array.isArray(manifests)\n    ? (manifests as readonly SelectorHost[])\n    : [manifests as SelectorHost];\n  for (const manifest of list) {\n    for (const selector of Object.values(manifest.uiSelectors ?? {})) {\n      if (selector.selects === qualifiedName) return selector;\n    }\n  }\n  return undefined;\n}\n"],"mappings":";;AAiBA,IAAa,mBAAmB;CAC9B;CACA;CACA;CACA;CACA;AACF;;AAKA,IAAa,wBAET;CACF,UAAU,CAAC,MAAM;CACjB,OAAO,CAAC,MAAM;CACd,KAAK,CAAC,MAAM;CACZ,OAAO,CAAC,MAAM;CAGd,UAAU,CAAC,MAAM;AACnB;AAEA,SAAgB,gBAAgB,OAAwC;CACtE,OACE,OAAO,UAAU,YAChB,iBAAuC,SAAS,KAAK;AAE1D;;;;;AAMA,IAAa,+BAA+B;CAC1C;CACA;CACA;CACA;AACF;;AAGA,IAAM,wCAAwB,IAAI,IAAI;CACpC;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;;;;;;AAcD,SAAgB,yBACd,QACA,WACe;CACf,MAAM,QAAQ,OAAO;CACrB,IAAI,CAAC,OAAO,OAAO;CACnB,IAAI,MAAM,cAAc,QAAQ,MAAM,OAAO,cAAc,MACzD,OAAO;CAET,IAAI,MAAM,cAAc,QAAQ,MAAM,OAAO,cAAc,MACzD,OAAO;CAET,IAAI,MAAM,QAAQ,sBAAsB,IAAI,MAAM,IAAI,GACpD,OAAO,KAAK,MAAM,KAAK;CAEzB,OAAO;AACT;;;;;;;AAQA,SAAgB,yBACd,QACA,UACoB;CACpB,IAAI,aAAa,KAAA,GACf,OAAO,yBAAyB,QAAQ,QAAQ,MAAM,OAClD,WACA,KAAA;CAEN,OAAO,6BAA6B,MACjC,SAAS,yBAAyB,QAAQ,IAAI,MAAM,IACvD;AACF;;;;;AAMA,SAAgB,qBAAqB,YAAwC;CAC3E,OAAO,aACH,uCAAuC,WAAW,aAClD;AACN;;;;;;;;;AAYA,SAAgB,gBACd,WACA,eACgC;CAChC,MAAM,OAAO,MAAM,QAAQ,SAAS,IAC/B,YACD,CAAC,SAAyB;CAC9B,KAAK,MAAM,YAAY,MACrB,KAAK,MAAM,YAAY,OAAO,OAAO,SAAS,eAAe,CAAC,CAAC,GAC7D,IAAI,SAAS,YAAY,eAAe,OAAO;AAIrD"}

package/dist/utils/scanner-module.d.ts

@@ -1,4 +1,4 @@
-import type { CapabilityClassification, DomainKnowledgePlaybookStep } from '@happyvertical/smrt-types';
+import type { CapabilityClassification, DomainKnowledgePlaybookStep, RecipeDefinition } from '@happyvertical/smrt-types';
 import type { SmartObjectManifest } from '../scanner/types.js';
 /**
  * The scanner's declared agent surface (#2591), mirrored structurally like the
@@ -53,6 +53,15 @@ export interface OxcScannerLike {
                 severity: 'error' | 'warning';
             }>;
             agentSurface?: ScannerAgentSurface;
+            recipes?: RecipeDefinition[];
+            /** Selector slots keyed by slot id (#3599). */
+            uiSelectors?: Record<string, {
+                slotId: string;
+                selects: `${string}:${string}`;
+                label?: string;
+                description?: string;
+                filePath: string;
+            }>;
         };
         resolved: unknown[];
     }>;
@@ -74,6 +83,14 @@ export interface ManifestAdapterLike {
         packageName?: string;
         packageVersion?: string;
         typeAliases: Record<string, string>;
+        recipes?: RecipeDefinition[];
+        uiSelectors?: Record<string, {
+            slotId: string;
+            selects: `${string}:${string}`;
+            label?: string;
+            description?: string;
+            filePath: string;
+        }>;
     }): SmartObjectManifest;
 }
 export interface ScannerModule {

package/dist/utils/scanner-module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scanner-module.d.ts","sourceRoot":"","sources":["../../src/utils/scanner-module.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,2BAA2B,EAC5B,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,QAAQ,CAAC;QACf,EAAE,EAAE,MAAM,CAAC;QACX,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,wBAAwB,CAAC;QACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAChC,cAAc,EAAE,OAAO,CAAC;QACxB,4EAA4E;QAC5E,MAAM,EAAE,CAAC,SAAS,CAAC,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,SAAS,EAAE,KAAK,CAAC;QACf,IAAI,EAAE,UAAU,CAAC;QACjB,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,2BAA2B,EAAE,CAAC;QACrC,MAAM,EAAE,KAAK,CAAC,SAAS,GAAG,QAAQ,CAAC,CAAC;QACpC,cAAc,EAAE,OAAO,CAAC;QACxB,aAAa,EAAE,OAAO,GAAG,UAAU,CAAC;QACpC,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,WAAW,EAAE,KAAK,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,cAAc,GAAG,gBAAgB,CAAC;QAC1C,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,cAAc;IAC7B,cAAc,IAAI,OAAO,CAAC;QACxB,OAAO,EAAE;YACP,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YACpC,MAAM,EAAE,KAAK,CAAC;gBACZ,QAAQ,EAAE,MAAM,CAAC;gBACjB,OAAO,EAAE,MAAM,CAAC;gBAChB,IAAI,CAAC,EAAE,MAAM,CAAC;gBACd,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;aAC/B,CAAC,CAAC;YACH,YAAY,CAAC,EAAE,mBAAmB,CAAC;SACpC,CAAC;QACF,QAAQ,EAAE,OAAO,EAAE,CAAC;KACrB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,OAAO,EAAE;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QACvB,qBAAqB,CAAC,EAAE,OAAO,CAAC;QAChC,oBAAoB,CAAC,EAAE,OAAO,CAAC;QAC/B,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,mBAAmB,CAAC,EAAE,OAAO,CAAC;KAC/B,GAAG,cAAc,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,CACR,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,EAAE;QACP,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACrC,GACA,mBAAmB,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,qBAAqB,CAAC;IAClC,eAAe,EAAE,UAAU,mBAAmB,CAAC;IAC/C,mBAAmB,CAAC,OAAO,EAAE;QAC3B,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,mBAAmB,CAAC,EAAE,OAAO,CAAC;KAC/B,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACtB;;;;;;;;OAQG;IACH,0BAA0B,CACxB,OAAO,EAAE,mBAAmB,EAC5B,OAAO,EAAE;QACP,kBAAkB,CAAC,EAAE,aAAa,CAAC;YACjC,IAAI,EAAE,MAAM,CAAC;YACb,UAAU,CAAC,EAAE,MAAM,CAAC;SACrB,CAAC,CAAC;QACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KACpC,GACA,mBAAmB,CAAC,aAAa,CAAC,CAAC;IACtC,2EAA2E;IAC3E,WAAW,CACT,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB;QACD,OAAO,EAAE,KAAK,CAAC;YACb,SAAS,EAAE,MAAM,CAAC;YAClB,SAAS,EAAE,MAAM,CAAC;YAClB,SAAS,CAAC,EAAE,MAAM,CAAC;YACnB,iBAAiB,EAAE,OAAO,CAAC;SAC5B,CAAC,CAAC;KACJ,CAAC;CACH"}
+{"version":3,"file":"scanner-module.d.ts","sourceRoot":"","sources":["../../src/utils/scanner-module.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,2BAA2B,EAC3B,gBAAgB,EACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,QAAQ,CAAC;QACf,EAAE,EAAE,MAAM,CAAC;QACX,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,wBAAwB,CAAC;QACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAChC,cAAc,EAAE,OAAO,CAAC;QACxB,4EAA4E;QAC5E,MAAM,EAAE,CAAC,SAAS,CAAC,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,SAAS,EAAE,KAAK,CAAC;QACf,IAAI,EAAE,UAAU,CAAC;QACjB,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,2BAA2B,EAAE,CAAC;QACrC,MAAM,EAAE,KAAK,CAAC,SAAS,GAAG,QAAQ,CAAC,CAAC;QACpC,cAAc,EAAE,OAAO,CAAC;QACxB,aAAa,EAAE,OAAO,GAAG,UAAU,CAAC;QACpC,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,WAAW,EAAE,KAAK,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,cAAc,GAAG,gBAAgB,CAAC;QAC1C,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,cAAc;IAC7B,cAAc,IAAI,OAAO,CAAC;QACxB,OAAO,EAAE;YACP,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YACpC,MAAM,EAAE,KAAK,CAAC;gBACZ,QAAQ,EAAE,MAAM,CAAC;gBACjB,OAAO,EAAE,MAAM,CAAC;gBAChB,IAAI,CAAC,EAAE,MAAM,CAAC;gBACd,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;aAC/B,CAAC,CAAC;YACH,YAAY,CAAC,EAAE,mBAAmB,CAAC;YACnC,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;YAC7B,+CAA+C;YAC/C,WAAW,CAAC,EAAE,MAAM,CAClB,MAAM,EACN;gBACE,MAAM,EAAE,MAAM,CAAC;gBACf,OAAO,EAAE,GAAG,MAAM,IAAI,MAAM,EAAE,CAAC;gBAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;gBACf,WAAW,CAAC,EAAE,MAAM,CAAC;gBACrB,QAAQ,EAAE,MAAM,CAAC;aAClB,CACF,CAAC;SACH,CAAC;QACF,QAAQ,EAAE,OAAO,EAAE,CAAC;KACrB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,OAAO,EAAE;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QACvB,qBAAqB,CAAC,EAAE,OAAO,CAAC;QAChC,oBAAoB,CAAC,EAAE,OAAO,CAAC;QAC/B,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,mBAAmB,CAAC,EAAE,OAAO,CAAC;KAC/B,GAAG,cAAc,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,CACR,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,EAAE;QACP,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACpC,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;QAC7B,WAAW,CAAC,EAAE,MAAM,CAClB,MAAM,EACN;YACE,MAAM,EAAE,MAAM,CAAC;YACf,OAAO,EAAE,GAAG,MAAM,IAAI,MAAM,EAAE,CAAC;YAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;YACf,WAAW,CAAC,EAAE,MAAM,CAAC;YACrB,QAAQ,EAAE,MAAM,CAAC;SAClB,CACF,CAAC;KACH,GACA,mBAAmB,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,qBAAqB,CAAC;IAClC,eAAe,EAAE,UAAU,mBAAmB,CAAC;IAC/C,mBAAmB,CAAC,OAAO,EAAE;QAC3B,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,mBAAmB,CAAC,EAAE,OAAO,CAAC;KAC/B,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACtB;;;;;;;;OAQG;IACH,0BAA0B,CACxB,OAAO,EAAE,mBAAmB,EAC5B,OAAO,EAAE;QACP,kBAAkB,CAAC,EAAE,aAAa,CAAC;YACjC,IAAI,EAAE,MAAM,CAAC;YACb,UAAU,CAAC,EAAE,MAAM,CAAC;SACrB,CAAC,CAAC;QACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KACpC,GACA,mBAAmB,CAAC,aAAa,CAAC,CAAC;IACtC,2EAA2E;IAC3E,WAAW,CACT,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB;QACD,OAAO,EAAE,KAAK,CAAC;YACb,SAAS,EAAE,MAAM,CAAC;YAClB,SAAS,EAAE,MAAM,CAAC;YAClB,SAAS,CAAC,EAAE,MAAM,CAAC;YACnB,iBAAiB,EAAE,OAAO,CAAC;SAC5B,CAAC,CAAC;KACJ,CAAC;CACH"}