@happyvertical/smrt-core 0.40.22 → 0.40.24

package/AGENTS.md

@@ -3,8 +3,20 @@
 ORM, code generation, AI integration, and the DispatchBus. Everything else builds on this.
 
 Key surfaces are `SmrtObject`, `SmrtCollection`, `ObjectRegistry`,
-`DispatchBus`, `GlobalInterceptors`, and `LearningMemory`; the sections below
-document their invariants and source locations.
+`DispatchBus`, `GlobalInterceptors`, and `LearningMemory`; this file documents
+their invariants and source locations, and the module docs below cover the
+per-subsystem semantics.
+
+## Modules
+
+Subsystem semantics live in sibling module docs — read the one for the
+subsystem you are editing. This file keeps what holds across all of them.
+
+| Module | Scope | Module doc |
+|---|---|---|
+| `src/change-feed.ts` | the adapter-agnostic change-observation spine — `_smrt_changes`, cursors, table versions, generated `_changes` routes, retention | [agents/change-feed.md](agents/change-feed.md) |
+| `src/change-signals.ts` + the generated `_events` SSE route | the push companion to the change feed — the signal bus, cross-replica fan-out, the SSE route, and its documented gaps | [agents/change-signals.md](agents/change-signals.md) |
+| `src/generators/` + `src/vite-plugin/web-collections.ts` | REST/CLI/MCP/web-collection generation, the `manifestHash` emission sites, and generated conditional-GET / ETag v2 semantics | [agents/generators.md](agents/generators.md) |
 
 ## SmrtObject Lifecycle
 
@@ -96,26 +108,6 @@ admin auth.
 - Tables: `_smrt_dispatch`, `_smrt_dispatch_subscriptions`
 - Status: `pending → processing → completed` (or `failed`)
 
-## Change Feed (#1758)
-
-Adapter-agnostic change-observation spine (`src/change-feed.ts`) — the server half of the client/mobile sync contract (PRD #1755):
-
-- `_smrt_changes` system table: one append per framework save/delete via a GlobalInterceptors writer registered at framework init. Deletes are tombstones (`operation: 'delete'`). `_smrt_*` tables are skipped. Feed-append failures log and never fail the user's write. On PostgreSQL, `_smrt_append_change` catches the INSERT in an exception subtransaction and returns SQLSTATE as data, so swallowing/retrying a best-effort failure cannot leave a caller-managed transaction aborted with `25P02` (#2026); the feed row still commits or rolls back with the caller transaction. Raw-handle/read initialization checks for both the table and helper before issuing any DDL; a cold schema/helper install acquires the same transaction-scoped `('smrt', 'system-tables')` advisory lock as bootstrap before its first DDL and rechecks inside one server-side statement, while schema migration/bootstrap remains the authoritative replace path. No dirty-check: a field-unchanged `.save()` appends a spurious `update` entry (diff-aware paths like `getOrUpsert`/sync-apply short-circuit before `save()` and append nothing); subscribers must tolerate spurious entries — they are convergent.
-- Sequences: allocated as `MAX(seq)+1` inside the INSERT with conflict retry — committed rows stay contiguous, so commit order == seq order on SQLite/Postgres/DuckDB (deliberately NOT identity/serial: those allocate before commit and break the cursor guarantee under concurrent writers).
-- `getChangesSince(db, { since, tables?, tenantId?, limit? }) → { changes, cursor, resyncRequired?, resyncCursor? }`: strictly monotonic cursor; polling with returned cursors misses no committed change and never repeats one. A cursor that cannot be served incrementally — pruned below the retained `[floor..horizon]` run, or foreign/ahead of the horizon — gets `resyncRequired: true` with empty `changes`, an unadvanced `cursor`, and `resyncCursor` set to the current horizon so clients can full-refetch then resume incrementally; detection runs on the UNFILTERED log so `tables`/`tenantId` filters never trigger or mask it. `getTenantScopedChangesSince()` resolves tenant via the DispatchBus resolver hook (fail-closed: tenancy on + no context → global rows only; tenant `T` sees `T` + global rows, never another tenant).
-- `getTableVersion(db, table) → number`: the per-table change version (`MAX(seq)` for the table, replica-stable — no per-process divergence), the ETag source for zero-query conditional GETs (#1765). Advances on any framework write to the table (CRUD and sync-apply, which all `save()`/`delete()`). A table with no retained entry of its own falls back to the global horizon (never a resettable low value) so an all-pruned table cannot false-304 a stale client; only 0 when the feed is empty.
-- Generated `_changes` routes: REST (`GET {basePath}/_changes`, requires `authMiddleware`, otherwise 401 — per-model `api.public` does NOT apply) and SvelteKit (`{routesDir}/_changes/+server.ts`, requires an authenticated principal on `locals`; opt out via `sveltekit.changesRoute.enabled: false`). Query params: `since`, `tables` (comma-separated), `limit`. Responses stay HTTP 200 in the resync state — `resyncRequired` is protocol state, not an error, and `resyncCursor` is the resume cursor after the client completes a full refetch.
-- Retention: `pruneChangeFeed(db, { maxAgeMs?, maxRows? })` — schedule it. Pruning deletes oldest-first and always retains the newest entry (a non-empty feed is never emptied), which is what makes pruned-cursor detection provable and keeps caught-up consumers polling normally. Raw-SQL writes are invisible to the feed (same documented gap as the #1499 cache); `bumpChangeFeed(db, { table, rowId? })` is the manual escape hatch.
-
-## Live Events / Change Signals (#1763, server half)
-
-The push companion to the change feed (`src/change-signals.ts` + the generated `_events` SSE route) — the server half of live cache invalidation (PRD #1755). The client subscriber (two-client/reconnect/polling-fallback ACs) is a separate later slice.
-
-- **Change-signal bus** (`src/change-signals.ts`): every framework save/delete that appends a durable feed row also publishes a coarse `ChangeSignal` `{ table, operation, rowId, tenantId, seq }` — **never a row payload** (authorization stays on the read path). Structurally mirrors the collection cache's notify/listen path. `subscribeToChangeSignals(db, listener) → unsubscribe`; `publishChangeSignal`/`broadcastChangeSignal`/the listener loop stay internal. `appendChange` now returns the allocated `seq` (was `void`); the signal carries it as a coarse resume cursor (`bumpChangeFeed` ignores the return). The publish runs only after the append SUCCEEDS (no signal without a durable feed row) and in its own log-and-swallow try/catch, so a signal problem never fails the user's write. `_smrt_*` writes never signal (the writer skips them). Delivery is synchronous per-listener with per-listener try/catch (one throwing SSE controller never blocks others); no per-subscriber queue — backpressure rides the platform `ReadableStream`.
-- **In-process + cross-replica**: locally-published and peer-received signals go through the SAME `deliverLocally` path. Cross-replica fan-out rides the db adapter's optional notification capability (`db.notifications`, a NEW `smrt_change_signals` channel distinct from the cache channel) with echo-avoidance by `PROCESS_ID`. No capability → in-process only, warn-once, **never an error, never blocks the write** (subscribers on other replicas fall back to cursor polling).
-- **Generated `_events` SSE route**: REST (`GET {basePath}/_events`, requires `authMiddleware`, otherwise 401 — fail-closed, per-model `api.public` does NOT apply; 405 non-GET; 503 no db or subscriber capacity reached) and SvelteKit (`{routesDir}/_events/+server.ts`, requires an authenticated principal on `locals`; opt out via `sveltekit.eventsRoute.enabled: false`; cap via `sveltekit.eventsRoute.maxSubscribers`, where `0` means unlimited). Tenant scope is captured ONCE at connection open (`resolveDispatchTenantScope`) and filtered server-side per signal via `signalVisibleToTenant` (same rule as `getChangesSince`'s tenant filter) before any byte hits the wire — delivery runs outside any tenant ALS context, so it must use the captured value. The stream lifecycle lives in `buildChangeEventStream(db, { cursor, tenantScope, heartbeatMs?, manifestHash? })` (exported; the SvelteKit route imports it so it stays thin): subscribe-before-catch-up (closes the gap window; overlap is deduped by the SSE `id:`/seq client-side), `retry: 3000`, optional connection-open `event: manifest` carrying `{ manifestHash }` for live contract detection, cursor catch-up via `getChangesSince` filtered by the CAPTURED scope (not re-resolved from ALS, so it matches the live-signal filter exactly and can't replay another tenant's rows) (`Last-Event-ID` header beats `?since=`; default = live-forward only; `resyncRequired` → `event: resync`), heartbeat (`DEFAULT_EVENTS_HEARTBEAT_MS` = 15s), and `cancel()` teardown (clears heartbeat + unsubscribes). SSE change frame: `id: <seq>\nevent: change\ndata: {table,operation,rowId,tenantId}\n\n` — seq is ONLY in the `id:` line, never the data JSON. Subscriber cap default is `DEFAULT_EVENTS_MAX_SUBSCRIBERS` = 1000; over-cap connections return retryable 503 + `Retry-After`, and existing subscribers are unaffected. **Cross-origin is opt-in and fail-closed (#1861)**: same-origin only by default. REST wraps `_events` in its CORS layer — set `enableCors` + an explicit `allowedOrigins` allowlist + `allowCredentials: true` and an allow-listed browser can subscribe with a credentialed `EventSource` (`withCredentials: true`); the response echoes the specific `Origin` (never `*`) plus `Access-Control-Allow-Credentials: true`. SvelteKit mirrors this via `sveltekit.eventsRoute.allowedOrigins` + `allowCredentials` (the generated route bakes the allowlist into a `Set`, echoes only a member origin, and answers a credentialed `OPTIONS` preflight). CORS never authorizes — the fail-closed auth guard and captured tenant scope are unchanged, so the read posture holds identically across origins; it only lets an allow-listed browser's cookies reach the guard. Client disconnect through the Node `createServer` bridge now cancels the response reader (was a teardown leak) so `cancel()` fires and the subscription is released.
-- **Known gaps** (documented in the module): raw-SQL writes don't signal (same gap as the feed); live signals for caller-managed-transaction writes are best-effort (the append + signal fire pre-commit, so a rolled-back write may emit a signal and its freed seq is later reused) — the autocommit default path is exact, and clients reconcile via full catch-up/resync (inherits the change feed's transaction caveat).
-
 ## Single Table Inheritance (STI)
 
 - Base: `@smrt({ tableStrategy: 'sti' })` — children inherit, share one table
@@ -124,29 +116,6 @@ The push companion to the change feed (`src/change-signals.ts` + the generated `
 - Polymorphic queries: collection loads `_meta_type`, creates correct subclass dynamically
 - Validation: fail-fast on save if `_meta_type` missing or mismatched
 
-## Code Generators
-
-| Generator | Location | Output |
-|-----------|----------|--------|
-| REST API | `src/generators/rest.ts` | OpenAPI-compliant CRUD endpoints |
-| CLI | `src/generators/cli.ts` | `objectname:action` admin commands — writable allowlist, exhaustive-include, `--from-file`, fail-closed tenant context |
-| MCP Server | `src/generators/mcp.ts` | Model Context Protocol tools |
-| 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` |
-
-Generated API clients share `selectApiClientEntries()` across the runtime Vite
-module, its ambient declaration, and physical prebuild declarations. When a
-collection class and its populated model share an endpoint, the model owns the
-canonical collection key and row payload schema; the collection class remains
-available under a deterministic class-derived secondary key. Selection and
-collision suffixes must not depend on manifest insertion order (#2027).
-For aggregated manifests, inheritance and item-type references resolve exact
-qualified names first, then package-local simple names, then a stable identity
-fallback so duplicate class names across packages cannot reintroduce ordering.
-
-The 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. Three emission sites must not drift: the runtime value (`generateWebModule`), the `@happyvertical/smrt-virt-web` ambient d.ts (`vite-plugin/index.ts`), and the physical `@smrt/web` d.ts (`prebuild/index.ts`).
-
-Generated 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.
-
 ## Child Accessors (R10)
 
 `src/child-accessors.ts` installs a consistent `get<FieldName>()` instance method for every `@oneToMany` field at `@smrt()` registration time (e.g. `@oneToMany('OrderItem') items` → `order.getItems()`), delegating to `loadRelatedMany`. Two invariants:

package/agents/change-feed.md

@@ -0,0 +1,16 @@
+# smrt-core/change feed
+
+Module semantics for `src/change-feed.ts`. Package orientation, the cross-module
+invariants, and the traps that apply before editing anything live in
+[../AGENTS.md](../AGENTS.md) — read that first.
+
+## Change Feed (#1758)
+
+Adapter-agnostic change-observation spine (`src/change-feed.ts`) — the server half of the client/mobile sync contract (PRD #1755):
+
+- `_smrt_changes` system table: one append per framework save/delete via a GlobalInterceptors writer registered at framework init. Deletes are tombstones (`operation: 'delete'`). `_smrt_*` tables are skipped. Feed-append failures log and never fail the user's write. On PostgreSQL, `_smrt_append_change` catches the INSERT in an exception subtransaction and returns SQLSTATE as data, so swallowing/retrying a best-effort failure cannot leave a caller-managed transaction aborted with `25P02` (#2026); the feed row still commits or rolls back with the caller transaction. Raw-handle/read initialization checks for both the table and helper before issuing any DDL; a cold schema/helper install acquires the same transaction-scoped `('smrt', 'system-tables')` advisory lock as bootstrap before its first DDL and rechecks inside one server-side statement, while schema migration/bootstrap remains the authoritative replace path. No dirty-check: a field-unchanged `.save()` appends a spurious `update` entry (diff-aware paths like `getOrUpsert`/sync-apply short-circuit before `save()` and append nothing); subscribers must tolerate spurious entries — they are convergent.
+- Sequences: allocated as `MAX(seq)+1` inside the INSERT with conflict retry — committed rows stay contiguous, so commit order == seq order on SQLite/Postgres/DuckDB (deliberately NOT identity/serial: those allocate before commit and break the cursor guarantee under concurrent writers).
+- `getChangesSince(db, { since, tables?, tenantId?, limit? }) → { changes, cursor, resyncRequired?, resyncCursor? }`: strictly monotonic cursor; polling with returned cursors misses no committed change and never repeats one. A cursor that cannot be served incrementally — pruned below the retained `[floor..horizon]` run, or foreign/ahead of the horizon — gets `resyncRequired: true` with empty `changes`, an unadvanced `cursor`, and `resyncCursor` set to the current horizon so clients can full-refetch then resume incrementally; detection runs on the UNFILTERED log so `tables`/`tenantId` filters never trigger or mask it. `getTenantScopedChangesSince()` resolves tenant via the DispatchBus resolver hook (fail-closed: tenancy on + no context → global rows only; tenant `T` sees `T` + global rows, never another tenant).
+- `getTableVersion(db, table) → number`: the per-table change version (`MAX(seq)` for the table, replica-stable — no per-process divergence), the ETag source for zero-query conditional GETs (#1765). Advances on any framework write to the table (CRUD and sync-apply, which all `save()`/`delete()`). A table with no retained entry of its own falls back to the global horizon (never a resettable low value) so an all-pruned table cannot false-304 a stale client; only 0 when the feed is empty.
+- Generated `_changes` routes: REST (`GET {basePath}/_changes`, requires `authMiddleware`, otherwise 401 — per-model `api.public` does NOT apply) and SvelteKit (`{routesDir}/_changes/+server.ts`, requires an authenticated principal on `locals`; opt out via `sveltekit.changesRoute.enabled: false`). Query params: `since`, `tables` (comma-separated), `limit`. Responses stay HTTP 200 in the resync state — `resyncRequired` is protocol state, not an error, and `resyncCursor` is the resume cursor after the client completes a full refetch.
+- Retention: `pruneChangeFeed(db, { maxAgeMs?, maxRows? })` — schedule it. Pruning deletes oldest-first and always retains the newest entry (a non-empty feed is never emptied), which is what makes pruned-cursor detection provable and keeps caught-up consumers polling normally. Raw-SQL writes are invisible to the feed (same documented gap as the #1499 cache); `bumpChangeFeed(db, { table, rowId? })` is the manual escape hatch.

package/agents/change-signals.md

@@ -0,0 +1,14 @@
+# smrt-core/change signals / live events
+
+Module semantics for `src/change-signals.ts` + the generated `_events` SSE route. Package orientation, the cross-module
+invariants, and the traps that apply before editing anything live in
+[../AGENTS.md](../AGENTS.md) — read that first.
+
+## Live Events / Change Signals (#1763, server half)
+
+The push companion to the change feed (`src/change-signals.ts` + the generated `_events` SSE route) — the server half of live cache invalidation (PRD #1755). The client subscriber (two-client/reconnect/polling-fallback ACs) is a separate later slice.
+
+- **Change-signal bus** (`src/change-signals.ts`): every framework save/delete that appends a durable feed row also publishes a coarse `ChangeSignal` `{ table, operation, rowId, tenantId, seq }` — **never a row payload** (authorization stays on the read path). Structurally mirrors the collection cache's notify/listen path. `subscribeToChangeSignals(db, listener) → unsubscribe`; `publishChangeSignal`/`broadcastChangeSignal`/the listener loop stay internal. `appendChange` now returns the allocated `seq` (was `void`); the signal carries it as a coarse resume cursor (`bumpChangeFeed` ignores the return). The publish runs only after the append SUCCEEDS (no signal without a durable feed row) and in its own log-and-swallow try/catch, so a signal problem never fails the user's write. `_smrt_*` writes never signal (the writer skips them). Delivery is synchronous per-listener with per-listener try/catch (one throwing SSE controller never blocks others); no per-subscriber queue — backpressure rides the platform `ReadableStream`.
+- **In-process + cross-replica**: locally-published and peer-received signals go through the SAME `deliverLocally` path. Cross-replica fan-out rides the db adapter's optional notification capability (`db.notifications`, a NEW `smrt_change_signals` channel distinct from the cache channel) with echo-avoidance by `PROCESS_ID`. No capability → in-process only, warn-once, **never an error, never blocks the write** (subscribers on other replicas fall back to cursor polling).
+- **Generated `_events` SSE route**: REST (`GET {basePath}/_events`, requires `authMiddleware`, otherwise 401 — fail-closed, per-model `api.public` does NOT apply; 405 non-GET; 503 no db or subscriber capacity reached) and SvelteKit (`{routesDir}/_events/+server.ts`, requires an authenticated principal on `locals`; opt out via `sveltekit.eventsRoute.enabled: false`; cap via `sveltekit.eventsRoute.maxSubscribers`, where `0` means unlimited). Tenant scope is captured ONCE at connection open (`resolveDispatchTenantScope`) and filtered server-side per signal via `signalVisibleToTenant` (same rule as `getChangesSince`'s tenant filter) before any byte hits the wire — delivery runs outside any tenant ALS context, so it must use the captured value. The stream lifecycle lives in `buildChangeEventStream(db, { cursor, tenantScope, heartbeatMs?, manifestHash? })` (exported; the SvelteKit route imports it so it stays thin): subscribe-before-catch-up (closes the gap window; overlap is deduped by the SSE `id:`/seq client-side), `retry: 3000`, optional connection-open `event: manifest` carrying `{ manifestHash }` for live contract detection, cursor catch-up via `getChangesSince` filtered by the CAPTURED scope (not re-resolved from ALS, so it matches the live-signal filter exactly and can't replay another tenant's rows) (`Last-Event-ID` header beats `?since=`; default = live-forward only; `resyncRequired` → `event: resync`), heartbeat (`DEFAULT_EVENTS_HEARTBEAT_MS` = 15s), and `cancel()` teardown (clears heartbeat + unsubscribes). SSE change frame: `id: <seq>\nevent: change\ndata: {table,operation,rowId,tenantId}\n\n` — seq is ONLY in the `id:` line, never the data JSON. Subscriber cap default is `DEFAULT_EVENTS_MAX_SUBSCRIBERS` = 1000; over-cap connections return retryable 503 + `Retry-After`, and existing subscribers are unaffected. **Cross-origin is opt-in and fail-closed (#1861)**: same-origin only by default. REST wraps `_events` in its CORS layer — set `enableCors` + an explicit `allowedOrigins` allowlist + `allowCredentials: true` and an allow-listed browser can subscribe with a credentialed `EventSource` (`withCredentials: true`); the response echoes the specific `Origin` (never `*`) plus `Access-Control-Allow-Credentials: true`. SvelteKit mirrors this via `sveltekit.eventsRoute.allowedOrigins` + `allowCredentials` (the generated route bakes the allowlist into a `Set`, echoes only a member origin, and answers a credentialed `OPTIONS` preflight). CORS never authorizes — the fail-closed auth guard and captured tenant scope are unchanged, so the read posture holds identically across origins; it only lets an allow-listed browser's cookies reach the guard. Client disconnect through the Node `createServer` bridge now cancels the response reader (was a teardown leak) so `cancel()` fires and the subscription is released.
+- **Known gaps** (documented in the module): raw-SQL writes don't signal (same gap as the feed); live signals for caller-managed-transaction writes are best-effort (the append + signal fire pre-commit, so a rolled-back write may emit a signal and its freed seq is later reused) — the autocommit default path is exact, and clients reconcile via full catch-up/resync (inherits the change feed's transaction caveat).

package/agents/generators.md

@@ -0,0 +1,28 @@
+# smrt-core/code generators
+
+Module semantics for `src/generators/` + `src/vite-plugin/`. Package orientation, the cross-module
+invariants, and the traps that apply before editing anything live in
+[../AGENTS.md](../AGENTS.md) — read that first.
+
+## Code Generators
+
+| Generator | Location | Output |
+|-----------|----------|--------|
+| REST API | `src/generators/rest.ts` | OpenAPI-compliant CRUD endpoints |
+| CLI | `src/generators/cli.ts` | `objectname:action` admin commands — writable allowlist, exhaustive-include, `--from-file`, fail-closed tenant context |
+| MCP Server | `src/generators/mcp.ts` | Model Context Protocol tools |
+| 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` |
+
+Generated API clients share `selectApiClientEntries()` across the runtime Vite
+module, its ambient declaration, and physical prebuild declarations. When a
+collection class and its populated model share an endpoint, the model owns the
+canonical collection key and row payload schema; the collection class remains
+available under a deterministic class-derived secondary key. Selection and
+collision suffixes must not depend on manifest insertion order (#2027).
+For aggregated manifests, inheritance and item-type references resolve exact
+qualified names first, then package-local simple names, then a stable identity
+fallback so duplicate class names across packages cannot reintroduce ordering.
+
+The 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. Three emission sites must not drift: the runtime value (`generateWebModule`), the `@happyvertical/smrt-virt-web` ambient d.ts (`vite-plugin/index.ts`), and the physical `@smrt/web` d.ts (`prebuild/index.ts`).
+
+Generated 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.

package/dist/index.js

@@ -55,7 +55,7 @@ import { generateOpenAPISpec, setupSwaggerUI } from "./generators/swagger.js";
 import "./generators/index.js";
 import { SmrtHierarchical } from "./hierarchical.js";
 import { SmrtJunction } from "./junction.js";
-import { buildDomainKnowledgeManifest } from "./knowledge.js";
+import { MODULE_DOC_HASH_PREFIX, buildDomainKnowledgeManifest, readAgentModuleDocs, resolveAgentModuleDocPaths } from "./knowledge.js";
 import { getClassConfigResolvers, getConfigResolver, isLazyConfigSentinel, listConfigResolvers, registerConfigResolver, resetConfigResolvers, resolveLazyConfig, unregisterConfigResolver } from "./lazy-config.js";
 import { DEFAULT_LEARNING_CONFIG, LearningMemory } from "./learning/memory.js";
 import { ManifestBuilder } from "./manifest/generator.js";
@@ -71,4 +71,4 @@ import "./system/index.js";
 import { getTestDatabase } from "./testing/database.js";
 import "./tools/index.js";
 import { smrtPlugin } from "./vite-plugin/index.js";
-export { AIError, APIGenerator, AiUsageCollector, AiUsagePersistenceHandler, CACHE_INVALIDATION_CHANNEL, CHANGE_FEED_INTERCEPTOR_NAME, CHANGE_FEED_TABLE, CHANGE_SIGNAL_CHANNEL, CLIGenerator, ConfigurationError, ContentHasher, CosineSimilarity, DEFAULT_AI_COST_RATES, DEFAULT_CHANGES_LIMIT, DEFAULT_EMBEDDING_CONFIG, DEFAULT_EVENTS_HEARTBEAT_MS, DEFAULT_EVENTS_MAX_SUBSCRIBERS, DEFAULT_EVENTS_RETRY_AFTER_SECONDS, DEFAULT_LEARNING_CONFIG, DatabaseError, Dispatch, DispatchBus, DispatchCollection, DispatchSubscription, DispatchSubscriptionCollection, EmbeddingProvider, EmbeddingStorage, ErrorUtils, FilesystemError, GlobalInterceptors, LearningMemory, MAX_CHANGES_LIMIT, MAX_SYNC_APPLY_BATCH_SIZE, MCPGenerator, ManifestBuilder, ManifestGenerator, ManifestManager, MetricsAdapter, NetworkError, ObjectRegistry, PRIVATE_READ_CACHE_CONTROL, PubSubAdapter, RuntimeError, SMRT_COLLECTION_BASE_NAMES, SYNC_APPLY_ROUTE_SEGMENTS, SYNC_APPLY_UUID_PATTERN, SchemaComparer, SignalBus, SignalSanitizer, SmrtClass, SmrtCollection, SmrtError, SmrtHierarchical, SmrtJunction, SmrtMCPServer, SmrtObject, SmrtPolymorphicAssociation, TenantIsolationError, ValidationError, ValidationReport, ValidationUtils, appendChange, applyOneToManyChildAccessors, applyPendingDecoratorRegistrations, applySyncWritablePolicy, assertPostgresSystemTimestampsCurrent, broadcastCacheInvalidation, buildChangeEventStream, buildDomainKnowledgeManifest, bumpChangeFeed, canonicalReadRepresentation, changeEventSubscribersAtCapacity, childAccessorName, clone, computeBodyEtag, computeRuntimeWebManifestHash, computeTableVersionEtag, conditionalJsonResponse, config, convertTypeToJsonSchema, createDispatchBus, createFilesystemAdapter, createInterceptorContext, createMCPServer, createQualifiedName, createRestServer, createSmrtClient, createSmrtServer, crossPackageRef, detectEngine, discoverManifestEntry, ensureCacheInvalidationListener, ensureChangeFeedTable, ensureDispatchSubscriptionsSystemTableCompatibility, ensureDispatchSystemTableCompatibility, ensureJobEventsSystemTableCompatibility, ensureJobsSystemTableCompatibility, ensureLegacySystemTableCompatibility, estimateAiUsageCost, eventStreamCapacityExceededResponse, executeToolCall, executeToolCalls, field, findManifestEntryByQualifiedName, foreignKey, formatToolResults, generateDDLForEngine, generateOpenAPISpec, generateSchemaDiff, generateToolFromMethod, generateToolManifest, getAdapterInfo, getCLIHandler, getCacheGeneration, getChangesSince, getClassConfigResolvers, getClassName, getConfigResolver, getDatabaseEngine, getManifest, getPackageFromQualifiedName, getSQLFromDiff, getTableVersion, getTenantScopedChangesSince, getTestDatabase, hasActionableChanges, ifNoneMatchHasConcreteMatch, ifNoneMatchSatisfied, importOptionalDependency, invalidateCollectionCache, isDatabaseInterface, isFromPackage, isLazyConfigSentinel, isQualifiedName, isSmrtCollectionExtendsName, isStaleWrite, isTenantScopedClassResolved, isType, isValid, listConfigResolvers, loadExternalManifest, loadExternalManifestSync, loadLocalTestManifestSync, loadManifestFromPathSync, manifest, manyToMany, meta, migratePostgresSystemTimestamps, normalizeEventsMaxSubscribers, oneToMany, parse, parseQualifiedName, parseSyncApplyBatch, payloadMatchesRow, processSyncApplyBatch, pruneChangeFeed, qualifiedNamesEqual, registerChangeFeedWriter, registerCompatibleFieldDecorator, registerConfigResolver, registerFilesystemAdapterFactory, registerOptionalDependency, resetChangeFeedWarnings, resetChangeSignals, resetCollectionCache, resetConfigResolvers, resetVerifiedTables, resolveDatabase, resolveDbCacheKey, resolveDispatchTenantId, resolveDispatchTenantScope, resolveLazyConfig, resolveReadCacheControl, resolveTenantEtagDiscriminator, runWithTenantGate, safeParse, safeStringify, setDispatchTenantResolver, setTenantEntryPointRunner, setTenantScopedClassResolver, setupCLI, setupSwaggerUI, shouldIncludeMethod, signalVisibleToTenant, smrt, smrtPlugin, smrt as smrtRegistry, startRestServer, staticManifest, stopCacheInvalidationListeners, stopChangeSignalListeners, stringify, subscribeToChangeSignals, tableExists, tryReserveChangeEventSubscriberSlot, unregisterChangeFeedWriter, unregisterConfigResolver, validateSyncApplyItem, validateToolCall, versionConditionalResponse, warnIfSharedCacheNeutralized };
+export { AIError, APIGenerator, AiUsageCollector, AiUsagePersistenceHandler, CACHE_INVALIDATION_CHANNEL, CHANGE_FEED_INTERCEPTOR_NAME, CHANGE_FEED_TABLE, CHANGE_SIGNAL_CHANNEL, CLIGenerator, ConfigurationError, ContentHasher, CosineSimilarity, DEFAULT_AI_COST_RATES, DEFAULT_CHANGES_LIMIT, DEFAULT_EMBEDDING_CONFIG, DEFAULT_EVENTS_HEARTBEAT_MS, DEFAULT_EVENTS_MAX_SUBSCRIBERS, DEFAULT_EVENTS_RETRY_AFTER_SECONDS, DEFAULT_LEARNING_CONFIG, DatabaseError, Dispatch, DispatchBus, DispatchCollection, DispatchSubscription, DispatchSubscriptionCollection, EmbeddingProvider, EmbeddingStorage, ErrorUtils, FilesystemError, GlobalInterceptors, LearningMemory, MAX_CHANGES_LIMIT, MAX_SYNC_APPLY_BATCH_SIZE, MCPGenerator, MODULE_DOC_HASH_PREFIX, ManifestBuilder, ManifestGenerator, ManifestManager, MetricsAdapter, NetworkError, ObjectRegistry, PRIVATE_READ_CACHE_CONTROL, PubSubAdapter, RuntimeError, SMRT_COLLECTION_BASE_NAMES, SYNC_APPLY_ROUTE_SEGMENTS, SYNC_APPLY_UUID_PATTERN, SchemaComparer, SignalBus, SignalSanitizer, SmrtClass, SmrtCollection, SmrtError, SmrtHierarchical, SmrtJunction, SmrtMCPServer, SmrtObject, SmrtPolymorphicAssociation, TenantIsolationError, ValidationError, ValidationReport, ValidationUtils, appendChange, applyOneToManyChildAccessors, applyPendingDecoratorRegistrations, applySyncWritablePolicy, assertPostgresSystemTimestampsCurrent, broadcastCacheInvalidation, buildChangeEventStream, buildDomainKnowledgeManifest, bumpChangeFeed, canonicalReadRepresentation, changeEventSubscribersAtCapacity, childAccessorName, clone, computeBodyEtag, computeRuntimeWebManifestHash, computeTableVersionEtag, conditionalJsonResponse, config, convertTypeToJsonSchema, createDispatchBus, createFilesystemAdapter, createInterceptorContext, createMCPServer, createQualifiedName, createRestServer, createSmrtClient, createSmrtServer, crossPackageRef, detectEngine, discoverManifestEntry, ensureCacheInvalidationListener, ensureChangeFeedTable, ensureDispatchSubscriptionsSystemTableCompatibility, ensureDispatchSystemTableCompatibility, ensureJobEventsSystemTableCompatibility, ensureJobsSystemTableCompatibility, ensureLegacySystemTableCompatibility, estimateAiUsageCost, eventStreamCapacityExceededResponse, executeToolCall, executeToolCalls, field, findManifestEntryByQualifiedName, foreignKey, formatToolResults, generateDDLForEngine, generateOpenAPISpec, generateSchemaDiff, generateToolFromMethod, generateToolManifest, getAdapterInfo, getCLIHandler, getCacheGeneration, getChangesSince, getClassConfigResolvers, getClassName, getConfigResolver, getDatabaseEngine, getManifest, getPackageFromQualifiedName, getSQLFromDiff, getTableVersion, getTenantScopedChangesSince, getTestDatabase, hasActionableChanges, ifNoneMatchHasConcreteMatch, ifNoneMatchSatisfied, importOptionalDependency, invalidateCollectionCache, isDatabaseInterface, isFromPackage, isLazyConfigSentinel, isQualifiedName, isSmrtCollectionExtendsName, isStaleWrite, isTenantScopedClassResolved, isType, isValid, listConfigResolvers, loadExternalManifest, loadExternalManifestSync, loadLocalTestManifestSync, loadManifestFromPathSync, manifest, manyToMany, meta, migratePostgresSystemTimestamps, normalizeEventsMaxSubscribers, oneToMany, parse, parseQualifiedName, parseSyncApplyBatch, payloadMatchesRow, processSyncApplyBatch, pruneChangeFeed, qualifiedNamesEqual, readAgentModuleDocs, registerChangeFeedWriter, registerCompatibleFieldDecorator, registerConfigResolver, registerFilesystemAdapterFactory, registerOptionalDependency, resetChangeFeedWarnings, resetChangeSignals, resetCollectionCache, resetConfigResolvers, resetVerifiedTables, resolveAgentModuleDocPaths, resolveDatabase, resolveDbCacheKey, resolveDispatchTenantId, resolveDispatchTenantScope, resolveLazyConfig, resolveReadCacheControl, resolveTenantEtagDiscriminator, runWithTenantGate, safeParse, safeStringify, setDispatchTenantResolver, setTenantEntryPointRunner, setTenantScopedClassResolver, setupCLI, setupSwaggerUI, shouldIncludeMethod, signalVisibleToTenant, smrt, smrtPlugin, smrt as smrtRegistry, startRestServer, staticManifest, stopCacheInvalidationListeners, stopChangeSignalListeners, stringify, subscribeToChangeSignals, tableExists, tryReserveChangeEventSubscriberSlot, unregisterChangeFeedWriter, unregisterConfigResolver, validateSyncApplyItem, validateToolCall, versionConditionalResponse, warnIfSharedCacheNeutralized };

package/dist/knowledge.d.ts

@@ -1,4 +1,4 @@
-import { DomainKnowledgeConfig, DomainKnowledgeManifest } from '@happyvertical/smrt-types';
+import { DomainKnowledgeConfig, DomainKnowledgeManifest, DomainKnowledgeModuleDoc } from '@happyvertical/smrt-types';
 import { SmartObjectManifest } from './scanner/types.js';
 /**
  * Minimal package.json shape consumed by the knowledge builder.
@@ -18,5 +18,21 @@ export interface BuildDomainKnowledgeOptions {
     manifestPath?: string;
     config?: DomainKnowledgeConfig;
 }
+/** `sourceHashes` key prefix for a linked module doc, e.g. `moduleDoc:agents/crm.md`. */
+export declare const MODULE_DOC_HASH_PREFIX = "moduleDoc:";
+/**
+ * Module doc paths linked from a package's `AGENTS.md`, relative to the package
+ * root and in document order.
+ *
+ * Instruction chains are additive (see `scripts/check-agents-chain.mjs`), so an
+ * oversized package doc is split into `packages/<pkg>/agents/<module>.md` siblings
+ * instead of nested `AGENTS.md` files. Only links resolving to an existing file
+ * INSIDE the package are accepted — a cross-package reference such as
+ * `packages/affiliates/MIGRATION.md` belongs to that package's own chain and is
+ * ignored here.
+ */
+export declare function resolveAgentModuleDocPaths(rootDir: string, agentDoc: string | undefined): string[];
+/** {@link resolveAgentModuleDocPaths}, with each doc's contents read. */
+export declare function readAgentModuleDocs(rootDir: string, agentDoc: string | undefined): DomainKnowledgeModuleDoc[];
 export declare function buildDomainKnowledgeManifest(options: BuildDomainKnowledgeOptions): DomainKnowledgeManifest;
 //# sourceMappingURL=knowledge.d.ts.map

package/dist/knowledge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../src/knowledge.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,qBAAqB,EACrB,uBAAuB,EAGxB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAEV,mBAAmB,EACpB,MAAM,oBAAoB,CAAC;AAE5B;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,qBAAqB,CAAC;CAChC;AAkCD,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,2BAA2B,GACnC,uBAAuB,CAsDzB"}
+{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../src/knowledge.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,qBAAqB,EACrB,uBAAuB,EACvB,wBAAwB,EAGzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAEV,mBAAmB,EACpB,MAAM,oBAAoB,CAAC;AAE5B;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,qBAAqB,CAAC;CAChC;AA2CD,yFAAyF;AACzF,eAAO,MAAM,sBAAsB,eAAe,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,MAAM,EAAE,CAgBV;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,wBAAwB,EAAE,CAM5B;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,2BAA2B,GACnC,uBAAuB,CAoEzB"}

package/dist/knowledge.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { join, relative } from "node:path";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, join, relative, resolve, sep } from "node:path";
 //#region src/knowledge.ts
 var SDK_PACKAGE_NAMES = /* @__PURE__ */ new Set([
 	"@happyvertical/ai",
@@ -37,13 +37,61 @@ var STANDARD_OPERATIONS = [
 	"update",
 	"delete"
 ];
+/**
+* Markdown inline links whose target is a `.md` file — `[label](agents/x.md)`,
+* tolerating an `#anchor` and a `"title"`. This is how a package registers a
+* sibling module doc (#2108): the link in `AGENTS.md` IS the registration, so
+* there is no separate index to drift out of sync.
+*/
+var MARKDOWN_MD_LINK = /\[[^\]]*\]\(\s*([^)\s#]+\.md)(?:#[^)\s]*)?(?:\s+"[^"]*")?\s*\)/g;
+/** `sourceHashes` key prefix for a linked module doc, e.g. `moduleDoc:agents/crm.md`. */
+var MODULE_DOC_HASH_PREFIX = "moduleDoc:";
+/**
+* Module doc paths linked from a package's `AGENTS.md`, relative to the package
+* root and in document order.
+*
+* Instruction chains are additive (see `scripts/check-agents-chain.mjs`), so an
+* oversized package doc is split into `packages/<pkg>/agents/<module>.md` siblings
+* instead of nested `AGENTS.md` files. Only links resolving to an existing file
+* INSIDE the package are accepted — a cross-package reference such as
+* `packages/affiliates/MIGRATION.md` belongs to that package's own chain and is
+* ignored here.
+*/
+function resolveAgentModuleDocPaths(rootDir, agentDoc) {
+	if (!agentDoc) return [];
+	const root = resolve(rootDir);
+	const paths = [];
+	for (const match of agentDoc.matchAll(MARKDOWN_MD_LINK)) {
+		const target = match[1];
+		if (target.includes("://")) continue;
+		const absolute = resolve(root, target);
+		if (absolute !== root && !absolute.startsWith(root + sep)) continue;
+		const relativePath = relative(root, absolute).split(sep).join("/");
+		if (relativePath === "AGENTS.md" || relativePath === "CLAUDE.md") continue;
+		if (paths.includes(relativePath)) continue;
+		if (!existsSync(absolute) || !statSync(absolute).isFile()) continue;
+		paths.push(relativePath);
+	}
+	return paths;
+}
+/** {@link resolveAgentModuleDocPaths}, with each doc's contents read. */
+function readAgentModuleDocs(rootDir, agentDoc) {
+	return resolveAgentModuleDocPaths(rootDir, agentDoc).map((path) => ({
+		path,
+		module: basename(path, ".md"),
+		content: readFileSync(join(rootDir, path), "utf8")
+	}));
+}
 function buildDomainKnowledgeManifest(options) {
 	const rootDir = options.rootDir;
 	const packageJson = options.packageJson ?? readPackageJson(rootDir) ?? {};
 	const packageName = options.manifest.packageName ?? packageJson.name;
 	const packageVersion = options.manifest.packageVersion ?? packageJson.version;
 	const agentDocPath = existingPath(rootDir, "AGENTS.md");
-	const agentDoc = options.config?.includeDocs === false || !agentDocPath ? void 0 : readFileSync(agentDocPath, "utf8");
+	const agentDocContent = agentDocPath ? readFileSync(agentDocPath, "utf8") : void 0;
+	const includeDocs = options.config?.includeDocs !== false;
+	const agentDoc = includeDocs ? agentDocContent : void 0;
+	const moduleDocPaths = resolveAgentModuleDocPaths(rootDir, agentDocContent);
 	const allDependencies = {
 		...record(packageJson.dependencies),
 		...record(packageJson.devDependencies),
@@ -63,7 +111,8 @@ function buildDomainKnowledgeManifest(options) {
 		sourceHashes: sourceHashes({
 			manifest: { content: manifestJson },
 			packageJson: fileHashSource(existingPath(rootDir, "package.json")),
-			agents: fileHashSource(agentDocPath)
+			agents: fileHashSource(agentDocPath),
+			...Object.fromEntries(moduleDocPaths.map((path) => [`${MODULE_DOC_HASH_PREFIX}${path}`, fileHashSource(join(rootDir, path))]))
 		}),
 		exports: exportKeys(packageJson.exports),
 		dependencies: allDependencies,
@@ -76,7 +125,8 @@ function buildDomainKnowledgeManifest(options) {
 		surfaces,
 		prompts: options.config?.includePrompts === false ? [] : readPrompts(rootDir),
 		relationshipsV2: summarizeRelationships(objects, manifestObjects),
-		agentDoc
+		agentDoc,
+		moduleDocs: includeDocs && moduleDocPaths.length > 0 ? readAgentModuleDocs(rootDir, agentDocContent) : void 0
 	};
 }
 function buildKnowledgeObject(object) {
@@ -268,6 +318,6 @@ function sortJson(value) {
 	return value;
 }
 //#endregion
-export { buildDomainKnowledgeManifest };
+export { MODULE_DOC_HASH_PREFIX, buildDomainKnowledgeManifest, readAgentModuleDocs, resolveAgentModuleDocPaths };
 
 //# sourceMappingURL=knowledge.js.map

package/dist/knowledge.js.map

@@ -1 +1 @@
-{"version":3,"file":"knowledge.js","names":[],"sources":["../src/knowledge.ts"],"sourcesContent":["import { createHash } from 'node:crypto';\nimport { existsSync, readdirSync, readFileSync } from 'node:fs';\nimport { join, relative } from 'node:path';\nimport type {\n  DomainKnowledgeConfig,\n  DomainKnowledgeManifest,\n  DomainKnowledgeObject,\n  DomainKnowledgeSurface,\n} from '@happyvertical/smrt-types';\nimport type {\n  SmartObjectDefinition,\n  SmartObjectManifest,\n} from './scanner/types.js';\n\n/**\n * Minimal package.json shape consumed by the knowledge builder.\n * `name`/`version` are typed concretely because they flow into the manifest's\n * string-typed metadata fields; everything else is read via `unknown`-accepting\n * helpers (`record()`, `exportKeys()`), so an index signature is sufficient.\n */\nexport interface PackageJsonLike {\n  name?: string;\n  version?: string;\n  [key: string]: unknown;\n}\n\nexport interface BuildDomainKnowledgeOptions {\n  manifest: SmartObjectManifest;\n  rootDir: string;\n  packageJson?: PackageJsonLike;\n  manifestPath?: string;\n  config?: DomainKnowledgeConfig;\n}\n\nconst SDK_PACKAGE_NAMES = new Set([\n  '@happyvertical/ai',\n  '@happyvertical/cache',\n  '@happyvertical/documents',\n  '@happyvertical/email',\n  '@happyvertical/encryption',\n  '@happyvertical/files',\n  '@happyvertical/geo',\n  '@happyvertical/images',\n  '@happyvertical/jobs',\n  '@happyvertical/json',\n  '@happyvertical/logger',\n  '@happyvertical/messages',\n  '@happyvertical/ocr',\n  '@happyvertical/pdf',\n  '@happyvertical/projects',\n  '@happyvertical/repos',\n  '@happyvertical/secrets',\n  '@happyvertical/spider',\n  '@happyvertical/sql',\n  '@happyvertical/utils',\n]);\n\nconst RELATIONSHIP_FIELD_TYPES = new Set([\n  'foreignKey',\n  'crossPackageRef',\n  'oneToMany',\n  'manyToMany',\n]);\n\nconst STANDARD_OPERATIONS = ['list', 'get', 'create', 'update', 'delete'];\n\nexport function buildDomainKnowledgeManifest(\n  options: BuildDomainKnowledgeOptions,\n): DomainKnowledgeManifest {\n  const rootDir = options.rootDir;\n  const packageJson = options.packageJson ?? readPackageJson(rootDir) ?? {};\n  const packageName = options.manifest.packageName ?? packageJson.name;\n  const packageVersion = options.manifest.packageVersion ?? packageJson.version;\n  const agentDocPath = existingPath(rootDir, 'AGENTS.md');\n  const agentDoc =\n    options.config?.includeDocs === false || !agentDocPath\n      ? undefined\n      : readFileSync(agentDocPath, 'utf8');\n  const allDependencies = {\n    ...record(packageJson.dependencies),\n    ...record(packageJson.devDependencies),\n    ...record(packageJson.peerDependencies),\n  };\n  const manifestObjects = Object.values(options.manifest.objects).filter(\n    (object) => object.decoratorConfig?.knowledge !== false,\n  );\n  const objects = manifestObjects.map((object) => buildKnowledgeObject(object));\n  const surfaces = objects.flatMap((object) => object.surfaces);\n  const manifestJson = stableJson(normalizeManifestForHash(options.manifest));\n\n  return {\n    schemaVersion: 1,\n    generatedAt: new Date().toISOString(),\n    packageName,\n    packageVersion,\n    sourceManifestPath: options.manifestPath\n      ? relative(rootDir, options.manifestPath)\n      : undefined,\n    agentDocPath: agentDocPath ? relative(rootDir, agentDocPath) : undefined,\n    sourceHashes: sourceHashes({\n      manifest: { content: manifestJson },\n      packageJson: fileHashSource(existingPath(rootDir, 'package.json')),\n      agents: fileHashSource(agentDocPath),\n    }),\n    exports: exportKeys(packageJson.exports),\n    dependencies: allDependencies,\n    smrtDependencies: Object.keys(allDependencies)\n      .filter((dep) => dep.startsWith('@happyvertical/smrt-'))\n      .sort(),\n    sdkDependencies: Object.keys(allDependencies)\n      .filter((dep) => SDK_PACKAGE_NAMES.has(dep))\n      .sort(),\n    tags: options.config?.tags ?? [],\n    summary: options.config?.summary,\n    risks: options.config?.risks ?? [],\n    objects,\n    surfaces,\n    prompts:\n      options.config?.includePrompts === false ? [] : readPrompts(rootDir),\n    relationshipsV2: summarizeRelationships(objects, manifestObjects),\n    agentDoc,\n  };\n}\n\nfunction buildKnowledgeObject(\n  object: SmartObjectDefinition,\n): DomainKnowledgeObject {\n  const knowledge =\n    typeof object.decoratorConfig?.knowledge === 'object'\n      ? object.decoratorConfig.knowledge\n      : {};\n  const fields = Object.entries(object.fields).map(([name, field]) => ({\n    name,\n    type: field.type,\n    required: field.required,\n    related: field.related,\n    columnType: columnType(object, name),\n  }));\n  const relationships = fields\n    .filter((field) => RELATIONSHIP_FIELD_TYPES.has(field.type))\n    .map((field) => ({\n      name: field.name,\n      type: field.type,\n      required: field.required,\n      related: field.related,\n      columnType: field.columnType,\n    }));\n\n  return {\n    name: object.className,\n    qualifiedName: object.qualifiedName,\n    collection: object.collection,\n    tableName: object.schema?.tableName,\n    packageName: object.packageName,\n    extends: object.extends,\n    visibility: object.visibility,\n    fields,\n    relationships,\n    methods: Object.keys(object.methods).sort(),\n    surfaces: objectSurfaces(object),\n    relationshipFeatures: relationshipFeatures(object),\n    tags: knowledge.tags ?? [],\n    summary: knowledge.summary,\n    risks: knowledge.risks ?? [],\n  };\n}\n\nfunction objectSurfaces(\n  object: SmartObjectDefinition,\n): DomainKnowledgeSurface[] {\n  return [\n    ...configuredSurfaces('api', object),\n    ...configuredSurfaces('cli', object),\n    ...configuredSurfaces('mcp', object),\n    ...aiSurfaces(object),\n  ];\n}\n\nfunction configuredSurfaces(\n  kind: 'api' | 'cli' | 'mcp',\n  object: SmartObjectDefinition,\n): DomainKnowledgeSurface[] {\n  const config = object.decoratorConfig?.[kind];\n  if (!config) return [];\n  const operations = configuredOperations(config);\n  return operations.map((operation) => ({\n    kind,\n    name:\n      kind === 'api'\n        ? `${object.collection}.${operation}`\n        : `${object.className.toLowerCase()}_${operation}`,\n    operation,\n    objectName: object.qualifiedName ?? object.className,\n    path: kind === 'api' ? apiPath(object, operation) : undefined,\n    method: kind === 'api' ? apiMethod(operation) : undefined,\n  }));\n}\n\nfunction configuredOperations(config: unknown): string[] {\n  if (config === true) return [...STANDARD_OPERATIONS];\n  if (!config || typeof config !== 'object' || Array.isArray(config)) {\n    return [];\n  }\n  const recordConfig = config as { include?: string[]; exclude?: string[] };\n  const base = Array.isArray(recordConfig.include)\n    ? recordConfig.include\n    : STANDARD_OPERATIONS;\n  const excluded = new Set(recordConfig.exclude ?? []);\n  return [...new Set(base.filter((operation) => !excluded.has(operation)))];\n}\n\nfunction aiSurfaces(object: SmartObjectDefinition): DomainKnowledgeSurface[] {\n  return (object.tools ?? []).map((tool) => ({\n    kind: 'ai',\n    name: tool.function.name,\n    operation: tool.function.name,\n    description: tool.function.description,\n    objectName: object.qualifiedName ?? object.className,\n  }));\n}\n\nfunction apiPath(object: SmartObjectDefinition, operation: string): string {\n  const collection = object.decoratorConfig?.api;\n  const configuredPath =\n    typeof collection === 'object' && typeof collection.path === 'string'\n      ? collection.path\n      : object.collection.replaceAll('_', '-');\n  if (operation === 'list' || operation === 'create') {\n    return `/${configuredPath}`;\n  }\n  if (STANDARD_OPERATIONS.includes(operation)) {\n    return `/${configuredPath}/[id]`;\n  }\n  return `/${configuredPath}/${operation}`;\n}\n\nfunction apiMethod(operation: string): string {\n  switch (operation) {\n    case 'list':\n    case 'get':\n      return 'GET';\n    case 'create':\n      return 'POST';\n    case 'update':\n      return 'PATCH';\n    case 'delete':\n      return 'DELETE';\n    default:\n      return 'POST';\n  }\n}\n\nfunction relationshipFeatures(object: SmartObjectDefinition): string[] {\n  const features = new Set<string>();\n  for (const field of Object.values(object.fields)) {\n    if (field.type === 'foreignKey') features.add('foreignKey');\n    if (field.type === 'crossPackageRef') features.add('crossPackageRef');\n    if (field.type === 'oneToMany') features.add('oneToMany');\n    if (field.type === 'manyToMany') features.add('manyToMany');\n  }\n  if (object.extends === 'SmrtJunction') features.add('SmrtJunction');\n  if (object.extends === 'SmrtHierarchical') features.add('SmrtHierarchical');\n  if (\n    object.extends === 'SmrtPolymorphicAssociation' ||\n    object.fields.metaType ||\n    object.fields.metaId\n  ) {\n    features.add('SmrtPolymorphicAssociation');\n  }\n  if (\n    Object.keys(object.schema?.columns ?? {}).some(\n      (name) => object.schema?.columns[name]?.type === 'UUID',\n    )\n  ) {\n    features.add('uuidColumns');\n  }\n  return [...features].sort();\n}\n\nfunction summarizeRelationships(\n  objects: DomainKnowledgeObject[],\n  manifestObjects: SmartObjectDefinition[],\n) {\n  const fields = objects.flatMap((object) => object.fields);\n  return {\n    foreignKeyFields: fields.filter((field) => field.type === 'foreignKey')\n      .length,\n    crossPackageRefFields: fields.filter(\n      (field) => field.type === 'crossPackageRef',\n    ).length,\n    junctionCollections: objects.filter((object) =>\n      object.relationshipFeatures.includes('SmrtJunction'),\n    ).length,\n    hierarchicalObjects: objects.filter((object) =>\n      object.relationshipFeatures.includes('SmrtHierarchical'),\n    ).length,\n    polymorphicAssociations: objects.filter((object) =>\n      object.relationshipFeatures.includes('SmrtPolymorphicAssociation'),\n    ).length,\n    uuidColumns: manifestObjects.reduce(\n      (count, object) =>\n        count +\n        Object.values(object.schema?.columns ?? {}).filter(\n          (column) => column.type === 'UUID',\n        ).length,\n      0,\n    ),\n  };\n}\n\nfunction columnType(\n  object: SmartObjectDefinition,\n  fieldName: string,\n): string | undefined {\n  const columnName = camelToSnake(fieldName);\n  return object.schema?.columns[columnName]?.type;\n}\n\nfunction readPrompts(\n  rootDir: string,\n): Array<{ filePath: string; key?: string }> {\n  const srcDir = join(rootDir, 'src');\n  if (!existsSync(srcDir)) return [];\n  const prompts: Array<{ filePath: string; key?: string }> = [];\n  for (const filePath of walkFiles(srcDir)) {\n    if (!filePath.endsWith('.ts')) continue;\n    const content = readFileSync(filePath, 'utf8');\n    if (!content.includes('definePrompt')) continue;\n    const keyMatch = content.match(/definePrompt\\s*\\(\\s*['\"`]([^'\"`]+)['\"`]/);\n    prompts.push({\n      filePath: relative(rootDir, filePath),\n      key: keyMatch?.[1],\n    });\n  }\n  return prompts;\n}\n\nfunction walkFiles(dir: string): string[] {\n  const files: string[] = [];\n  for (const entry of readdirSync(dir, { withFileTypes: true })) {\n    if (\n      entry.name === 'node_modules' ||\n      entry.name === 'dist' ||\n      entry.name === '.svelte-kit'\n    ) {\n      continue;\n    }\n    const fullPath = join(dir, entry.name);\n    if (entry.isDirectory()) {\n      files.push(...walkFiles(fullPath));\n    } else if (entry.isFile()) {\n      files.push(fullPath);\n    }\n  }\n  return files;\n}\n\nfunction sourceHashes(sources: Record<string, HashSource | undefined>) {\n  const hashes: Record<string, string> = {};\n  for (const [name, source] of Object.entries(sources)) {\n    if (!source) continue;\n    const content =\n      'content' in source ? source.content : readFileSync(source.path, 'utf8');\n    hashes[name] = createHash('sha256').update(content).digest('hex');\n  }\n  return hashes;\n}\n\ntype HashSource = { content: string } | { path: string };\n\nfunction fileHashSource(path: string | undefined): HashSource | undefined {\n  return path ? { path } : undefined;\n}\n\nfunction existingPath(rootDir: string, path: string): string | undefined {\n  const fullPath = join(rootDir, path);\n  return existsSync(fullPath) ? fullPath : undefined;\n}\n\nfunction readPackageJson(rootDir: string): PackageJsonLike | null {\n  const path = join(rootDir, 'package.json');\n  if (!existsSync(path)) return null;\n  return JSON.parse(readFileSync(path, 'utf8'));\n}\n\nfunction record(value: unknown): Record<string, string> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value)\n    ? (value as Record<string, string>)\n    : {};\n}\n\nfunction exportKeys(exportsField: unknown): string[] {\n  if (typeof exportsField === 'string') return ['.'];\n  if (\n    typeof exportsField !== 'object' ||\n    exportsField === null ||\n    Array.isArray(exportsField)\n  ) {\n    return [];\n  }\n  return Object.keys(exportsField).sort();\n}\n\nfunction camelToSnake(value: string): string {\n  return value\n    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')\n    .replace(/[-\\s]+/g, '_')\n    .toLowerCase();\n}\n\nfunction normalizeManifestForHash(manifest: SmartObjectManifest): unknown {\n  const normalized = JSON.parse(JSON.stringify(manifest)) as Record<\n    string,\n    unknown\n  >;\n  delete normalized.timestamp;\n  return normalized;\n}\n\nfunction stableJson(value: unknown): string {\n  return JSON.stringify(sortJson(value), null, 2);\n}\n\nfunction sortJson(value: unknown): unknown {\n  if (Array.isArray(value)) return value.map(sortJson);\n  if (value && typeof value === 'object') {\n    return Object.fromEntries(\n      Object.entries(value as Record<string, unknown>)\n        .sort(([a], [b]) => a.localeCompare(b))\n        .map(([key, entry]) => [key, sortJson(entry)]),\n    );\n  }\n  return value;\n}\n"],"mappings":"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"}
+{"version":3,"file":"knowledge.js","names":[],"sources":["../src/knowledge.ts"],"sourcesContent":["import { createHash } from 'node:crypto';\nimport { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';\nimport { basename, join, relative, resolve, sep } from 'node:path';\nimport type {\n  DomainKnowledgeConfig,\n  DomainKnowledgeManifest,\n  DomainKnowledgeModuleDoc,\n  DomainKnowledgeObject,\n  DomainKnowledgeSurface,\n} from '@happyvertical/smrt-types';\nimport type {\n  SmartObjectDefinition,\n  SmartObjectManifest,\n} from './scanner/types.js';\n\n/**\n * Minimal package.json shape consumed by the knowledge builder.\n * `name`/`version` are typed concretely because they flow into the manifest's\n * string-typed metadata fields; everything else is read via `unknown`-accepting\n * helpers (`record()`, `exportKeys()`), so an index signature is sufficient.\n */\nexport interface PackageJsonLike {\n  name?: string;\n  version?: string;\n  [key: string]: unknown;\n}\n\nexport interface BuildDomainKnowledgeOptions {\n  manifest: SmartObjectManifest;\n  rootDir: string;\n  packageJson?: PackageJsonLike;\n  manifestPath?: string;\n  config?: DomainKnowledgeConfig;\n}\n\nconst SDK_PACKAGE_NAMES = new Set([\n  '@happyvertical/ai',\n  '@happyvertical/cache',\n  '@happyvertical/documents',\n  '@happyvertical/email',\n  '@happyvertical/encryption',\n  '@happyvertical/files',\n  '@happyvertical/geo',\n  '@happyvertical/images',\n  '@happyvertical/jobs',\n  '@happyvertical/json',\n  '@happyvertical/logger',\n  '@happyvertical/messages',\n  '@happyvertical/ocr',\n  '@happyvertical/pdf',\n  '@happyvertical/projects',\n  '@happyvertical/repos',\n  '@happyvertical/secrets',\n  '@happyvertical/spider',\n  '@happyvertical/sql',\n  '@happyvertical/utils',\n]);\n\nconst RELATIONSHIP_FIELD_TYPES = new Set([\n  'foreignKey',\n  'crossPackageRef',\n  'oneToMany',\n  'manyToMany',\n]);\n\nconst STANDARD_OPERATIONS = ['list', 'get', 'create', 'update', 'delete'];\n\n/**\n * Markdown inline links whose target is a `.md` file — `[label](agents/x.md)`,\n * tolerating an `#anchor` and a `\"title\"`. This is how a package registers a\n * sibling module doc (#2108): the link in `AGENTS.md` IS the registration, so\n * there is no separate index to drift out of sync.\n */\nconst MARKDOWN_MD_LINK =\n  /\\[[^\\]]*\\]\\(\\s*([^)\\s#]+\\.md)(?:#[^)\\s]*)?(?:\\s+\"[^\"]*\")?\\s*\\)/g;\n\n/** `sourceHashes` key prefix for a linked module doc, e.g. `moduleDoc:agents/crm.md`. */\nexport const MODULE_DOC_HASH_PREFIX = 'moduleDoc:';\n\n/**\n * Module doc paths linked from a package's `AGENTS.md`, relative to the package\n * root and in document order.\n *\n * Instruction chains are additive (see `scripts/check-agents-chain.mjs`), so an\n * oversized package doc is split into `packages/<pkg>/agents/<module>.md` siblings\n * instead of nested `AGENTS.md` files. Only links resolving to an existing file\n * INSIDE the package are accepted — a cross-package reference such as\n * `packages/affiliates/MIGRATION.md` belongs to that package's own chain and is\n * ignored here.\n */\nexport function resolveAgentModuleDocPaths(\n  rootDir: string,\n  agentDoc: string | undefined,\n): string[] {\n  if (!agentDoc) return [];\n  const root = resolve(rootDir);\n  const paths: string[] = [];\n  for (const match of agentDoc.matchAll(MARKDOWN_MD_LINK)) {\n    const target = match[1];\n    if (target.includes('://')) continue;\n    const absolute = resolve(root, target);\n    if (absolute !== root && !absolute.startsWith(root + sep)) continue;\n    const relativePath = relative(root, absolute).split(sep).join('/');\n    if (relativePath === 'AGENTS.md' || relativePath === 'CLAUDE.md') continue;\n    if (paths.includes(relativePath)) continue;\n    if (!existsSync(absolute) || !statSync(absolute).isFile()) continue;\n    paths.push(relativePath);\n  }\n  return paths;\n}\n\n/** {@link resolveAgentModuleDocPaths}, with each doc's contents read. */\nexport function readAgentModuleDocs(\n  rootDir: string,\n  agentDoc: string | undefined,\n): DomainKnowledgeModuleDoc[] {\n  return resolveAgentModuleDocPaths(rootDir, agentDoc).map((path) => ({\n    path,\n    module: basename(path, '.md'),\n    content: readFileSync(join(rootDir, path), 'utf8'),\n  }));\n}\n\nexport function buildDomainKnowledgeManifest(\n  options: BuildDomainKnowledgeOptions,\n): DomainKnowledgeManifest {\n  const rootDir = options.rootDir;\n  const packageJson = options.packageJson ?? readPackageJson(rootDir) ?? {};\n  const packageName = options.manifest.packageName ?? packageJson.name;\n  const packageVersion = options.manifest.packageVersion ?? packageJson.version;\n  const agentDocPath = existingPath(rootDir, 'AGENTS.md');\n  const agentDocContent = agentDocPath\n    ? readFileSync(agentDocPath, 'utf8')\n    : undefined;\n  const includeDocs = options.config?.includeDocs !== false;\n  const agentDoc = includeDocs ? agentDocContent : undefined;\n  // Module doc PATHS are always resolved so their hashes gate freshness even\n  // when doc bodies are excluded from the artifact — same stance as `agents`.\n  const moduleDocPaths = resolveAgentModuleDocPaths(rootDir, agentDocContent);\n  const allDependencies = {\n    ...record(packageJson.dependencies),\n    ...record(packageJson.devDependencies),\n    ...record(packageJson.peerDependencies),\n  };\n  const manifestObjects = Object.values(options.manifest.objects).filter(\n    (object) => object.decoratorConfig?.knowledge !== false,\n  );\n  const objects = manifestObjects.map((object) => buildKnowledgeObject(object));\n  const surfaces = objects.flatMap((object) => object.surfaces);\n  const manifestJson = stableJson(normalizeManifestForHash(options.manifest));\n\n  return {\n    schemaVersion: 1,\n    generatedAt: new Date().toISOString(),\n    packageName,\n    packageVersion,\n    sourceManifestPath: options.manifestPath\n      ? relative(rootDir, options.manifestPath)\n      : undefined,\n    agentDocPath: agentDocPath ? relative(rootDir, agentDocPath) : undefined,\n    sourceHashes: sourceHashes({\n      manifest: { content: manifestJson },\n      packageJson: fileHashSource(existingPath(rootDir, 'package.json')),\n      agents: fileHashSource(agentDocPath),\n      ...Object.fromEntries(\n        moduleDocPaths.map((path) => [\n          `${MODULE_DOC_HASH_PREFIX}${path}`,\n          fileHashSource(join(rootDir, path)),\n        ]),\n      ),\n    }),\n    exports: exportKeys(packageJson.exports),\n    dependencies: allDependencies,\n    smrtDependencies: Object.keys(allDependencies)\n      .filter((dep) => dep.startsWith('@happyvertical/smrt-'))\n      .sort(),\n    sdkDependencies: Object.keys(allDependencies)\n      .filter((dep) => SDK_PACKAGE_NAMES.has(dep))\n      .sort(),\n    tags: options.config?.tags ?? [],\n    summary: options.config?.summary,\n    risks: options.config?.risks ?? [],\n    objects,\n    surfaces,\n    prompts:\n      options.config?.includePrompts === false ? [] : readPrompts(rootDir),\n    relationshipsV2: summarizeRelationships(objects, manifestObjects),\n    agentDoc,\n    moduleDocs:\n      includeDocs && moduleDocPaths.length > 0\n        ? readAgentModuleDocs(rootDir, agentDocContent)\n        : undefined,\n  };\n}\n\nfunction buildKnowledgeObject(\n  object: SmartObjectDefinition,\n): DomainKnowledgeObject {\n  const knowledge =\n    typeof object.decoratorConfig?.knowledge === 'object'\n      ? object.decoratorConfig.knowledge\n      : {};\n  const fields = Object.entries(object.fields).map(([name, field]) => ({\n    name,\n    type: field.type,\n    required: field.required,\n    related: field.related,\n    columnType: columnType(object, name),\n  }));\n  const relationships = fields\n    .filter((field) => RELATIONSHIP_FIELD_TYPES.has(field.type))\n    .map((field) => ({\n      name: field.name,\n      type: field.type,\n      required: field.required,\n      related: field.related,\n      columnType: field.columnType,\n    }));\n\n  return {\n    name: object.className,\n    qualifiedName: object.qualifiedName,\n    collection: object.collection,\n    tableName: object.schema?.tableName,\n    packageName: object.packageName,\n    extends: object.extends,\n    visibility: object.visibility,\n    fields,\n    relationships,\n    methods: Object.keys(object.methods).sort(),\n    surfaces: objectSurfaces(object),\n    relationshipFeatures: relationshipFeatures(object),\n    tags: knowledge.tags ?? [],\n    summary: knowledge.summary,\n    risks: knowledge.risks ?? [],\n  };\n}\n\nfunction objectSurfaces(\n  object: SmartObjectDefinition,\n): DomainKnowledgeSurface[] {\n  return [\n    ...configuredSurfaces('api', object),\n    ...configuredSurfaces('cli', object),\n    ...configuredSurfaces('mcp', object),\n    ...aiSurfaces(object),\n  ];\n}\n\nfunction configuredSurfaces(\n  kind: 'api' | 'cli' | 'mcp',\n  object: SmartObjectDefinition,\n): DomainKnowledgeSurface[] {\n  const config = object.decoratorConfig?.[kind];\n  if (!config) return [];\n  const operations = configuredOperations(config);\n  return operations.map((operation) => ({\n    kind,\n    name:\n      kind === 'api'\n        ? `${object.collection}.${operation}`\n        : `${object.className.toLowerCase()}_${operation}`,\n    operation,\n    objectName: object.qualifiedName ?? object.className,\n    path: kind === 'api' ? apiPath(object, operation) : undefined,\n    method: kind === 'api' ? apiMethod(operation) : undefined,\n  }));\n}\n\nfunction configuredOperations(config: unknown): string[] {\n  if (config === true) return [...STANDARD_OPERATIONS];\n  if (!config || typeof config !== 'object' || Array.isArray(config)) {\n    return [];\n  }\n  const recordConfig = config as { include?: string[]; exclude?: string[] };\n  const base = Array.isArray(recordConfig.include)\n    ? recordConfig.include\n    : STANDARD_OPERATIONS;\n  const excluded = new Set(recordConfig.exclude ?? []);\n  return [...new Set(base.filter((operation) => !excluded.has(operation)))];\n}\n\nfunction aiSurfaces(object: SmartObjectDefinition): DomainKnowledgeSurface[] {\n  return (object.tools ?? []).map((tool) => ({\n    kind: 'ai',\n    name: tool.function.name,\n    operation: tool.function.name,\n    description: tool.function.description,\n    objectName: object.qualifiedName ?? object.className,\n  }));\n}\n\nfunction apiPath(object: SmartObjectDefinition, operation: string): string {\n  const collection = object.decoratorConfig?.api;\n  const configuredPath =\n    typeof collection === 'object' && typeof collection.path === 'string'\n      ? collection.path\n      : object.collection.replaceAll('_', '-');\n  if (operation === 'list' || operation === 'create') {\n    return `/${configuredPath}`;\n  }\n  if (STANDARD_OPERATIONS.includes(operation)) {\n    return `/${configuredPath}/[id]`;\n  }\n  return `/${configuredPath}/${operation}`;\n}\n\nfunction apiMethod(operation: string): string {\n  switch (operation) {\n    case 'list':\n    case 'get':\n      return 'GET';\n    case 'create':\n      return 'POST';\n    case 'update':\n      return 'PATCH';\n    case 'delete':\n      return 'DELETE';\n    default:\n      return 'POST';\n  }\n}\n\nfunction relationshipFeatures(object: SmartObjectDefinition): string[] {\n  const features = new Set<string>();\n  for (const field of Object.values(object.fields)) {\n    if (field.type === 'foreignKey') features.add('foreignKey');\n    if (field.type === 'crossPackageRef') features.add('crossPackageRef');\n    if (field.type === 'oneToMany') features.add('oneToMany');\n    if (field.type === 'manyToMany') features.add('manyToMany');\n  }\n  if (object.extends === 'SmrtJunction') features.add('SmrtJunction');\n  if (object.extends === 'SmrtHierarchical') features.add('SmrtHierarchical');\n  if (\n    object.extends === 'SmrtPolymorphicAssociation' ||\n    object.fields.metaType ||\n    object.fields.metaId\n  ) {\n    features.add('SmrtPolymorphicAssociation');\n  }\n  if (\n    Object.keys(object.schema?.columns ?? {}).some(\n      (name) => object.schema?.columns[name]?.type === 'UUID',\n    )\n  ) {\n    features.add('uuidColumns');\n  }\n  return [...features].sort();\n}\n\nfunction summarizeRelationships(\n  objects: DomainKnowledgeObject[],\n  manifestObjects: SmartObjectDefinition[],\n) {\n  const fields = objects.flatMap((object) => object.fields);\n  return {\n    foreignKeyFields: fields.filter((field) => field.type === 'foreignKey')\n      .length,\n    crossPackageRefFields: fields.filter(\n      (field) => field.type === 'crossPackageRef',\n    ).length,\n    junctionCollections: objects.filter((object) =>\n      object.relationshipFeatures.includes('SmrtJunction'),\n    ).length,\n    hierarchicalObjects: objects.filter((object) =>\n      object.relationshipFeatures.includes('SmrtHierarchical'),\n    ).length,\n    polymorphicAssociations: objects.filter((object) =>\n      object.relationshipFeatures.includes('SmrtPolymorphicAssociation'),\n    ).length,\n    uuidColumns: manifestObjects.reduce(\n      (count, object) =>\n        count +\n        Object.values(object.schema?.columns ?? {}).filter(\n          (column) => column.type === 'UUID',\n        ).length,\n      0,\n    ),\n  };\n}\n\nfunction columnType(\n  object: SmartObjectDefinition,\n  fieldName: string,\n): string | undefined {\n  const columnName = camelToSnake(fieldName);\n  return object.schema?.columns[columnName]?.type;\n}\n\nfunction readPrompts(\n  rootDir: string,\n): Array<{ filePath: string; key?: string }> {\n  const srcDir = join(rootDir, 'src');\n  if (!existsSync(srcDir)) return [];\n  const prompts: Array<{ filePath: string; key?: string }> = [];\n  for (const filePath of walkFiles(srcDir)) {\n    if (!filePath.endsWith('.ts')) continue;\n    const content = readFileSync(filePath, 'utf8');\n    if (!content.includes('definePrompt')) continue;\n    const keyMatch = content.match(/definePrompt\\s*\\(\\s*['\"`]([^'\"`]+)['\"`]/);\n    prompts.push({\n      filePath: relative(rootDir, filePath),\n      key: keyMatch?.[1],\n    });\n  }\n  return prompts;\n}\n\nfunction walkFiles(dir: string): string[] {\n  const files: string[] = [];\n  for (const entry of readdirSync(dir, { withFileTypes: true })) {\n    if (\n      entry.name === 'node_modules' ||\n      entry.name === 'dist' ||\n      entry.name === '.svelte-kit'\n    ) {\n      continue;\n    }\n    const fullPath = join(dir, entry.name);\n    if (entry.isDirectory()) {\n      files.push(...walkFiles(fullPath));\n    } else if (entry.isFile()) {\n      files.push(fullPath);\n    }\n  }\n  return files;\n}\n\nfunction sourceHashes(sources: Record<string, HashSource | undefined>) {\n  const hashes: Record<string, string> = {};\n  for (const [name, source] of Object.entries(sources)) {\n    if (!source) continue;\n    const content =\n      'content' in source ? source.content : readFileSync(source.path, 'utf8');\n    hashes[name] = createHash('sha256').update(content).digest('hex');\n  }\n  return hashes;\n}\n\ntype HashSource = { content: string } | { path: string };\n\nfunction fileHashSource(path: string | undefined): HashSource | undefined {\n  return path ? { path } : undefined;\n}\n\nfunction existingPath(rootDir: string, path: string): string | undefined {\n  const fullPath = join(rootDir, path);\n  return existsSync(fullPath) ? fullPath : undefined;\n}\n\nfunction readPackageJson(rootDir: string): PackageJsonLike | null {\n  const path = join(rootDir, 'package.json');\n  if (!existsSync(path)) return null;\n  return JSON.parse(readFileSync(path, 'utf8'));\n}\n\nfunction record(value: unknown): Record<string, string> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value)\n    ? (value as Record<string, string>)\n    : {};\n}\n\nfunction exportKeys(exportsField: unknown): string[] {\n  if (typeof exportsField === 'string') return ['.'];\n  if (\n    typeof exportsField !== 'object' ||\n    exportsField === null ||\n    Array.isArray(exportsField)\n  ) {\n    return [];\n  }\n  return Object.keys(exportsField).sort();\n}\n\nfunction camelToSnake(value: string): string {\n  return value\n    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')\n    .replace(/[-\\s]+/g, '_')\n    .toLowerCase();\n}\n\nfunction normalizeManifestForHash(manifest: SmartObjectManifest): unknown {\n  const normalized = JSON.parse(JSON.stringify(manifest)) as Record<\n    string,\n    unknown\n  >;\n  delete normalized.timestamp;\n  return normalized;\n}\n\nfunction stableJson(value: unknown): string {\n  return JSON.stringify(sortJson(value), null, 2);\n}\n\nfunction sortJson(value: unknown): unknown {\n  if (Array.isArray(value)) return value.map(sortJson);\n  if (value && typeof value === 'object') {\n    return Object.fromEntries(\n      Object.entries(value as Record<string, unknown>)\n        .sort(([a], [b]) => a.localeCompare(b))\n        .map(([key, entry]) => [key, sortJson(entry)]),\n    );\n  }\n  return value;\n}\n"],"mappings":";;;;AAmCA,IAAM,oCAAoB,IAAI,IAAI;CAChC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;AAED,IAAM,2CAA2B,IAAI,IAAI;CACvC;CACA;CACA;CACA;AACF,CAAC;AAED,IAAM,sBAAsB;CAAC;CAAQ;CAAO;CAAU;CAAU;AAAQ;;;;;;;AAQxE,IAAM,mBACJ;;AAGF,IAAa,yBAAyB;;;;;;;;;;;;AAatC,SAAgB,2BACd,SACA,UACU;CACV,IAAI,CAAC,UAAU,OAAO,CAAC;CACvB,MAAM,OAAO,QAAQ,OAAO;CAC5B,MAAM,QAAkB,CAAC;CACzB,KAAK,MAAM,SAAS,SAAS,SAAS,gBAAgB,GAAG;EACvD,MAAM,SAAS,MAAM;EACrB,IAAI,OAAO,SAAS,KAAK,GAAG;EAC5B,MAAM,WAAW,QAAQ,MAAM,MAAM;EACrC,IAAI,aAAa,QAAQ,CAAC,SAAS,WAAW,OAAO,GAAG,GAAG;EAC3D,MAAM,eAAe,SAAS,MAAM,QAAQ,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,GAAG;EACjE,IAAI,iBAAiB,eAAe,iBAAiB,aAAa;EAClE,IAAI,MAAM,SAAS,YAAY,GAAG;EAClC,IAAI,CAAC,WAAW,QAAQ,KAAK,CAAC,SAAS,QAAQ,CAAC,CAAC,OAAO,GAAG;EAC3D,MAAM,KAAK,YAAY;CACzB;CACA,OAAO;AACT;;AAGA,SAAgB,oBACd,SACA,UAC4B;CAC5B,OAAO,2BAA2B,SAAS,QAAQ,CAAC,CAAC,KAAK,UAAU;EAClE;EACA,QAAQ,SAAS,MAAM,KAAK;EAC5B,SAAS,aAAa,KAAK,SAAS,IAAI,GAAG,MAAM;CACnD,EAAE;AACJ;AAEA,SAAgB,6BACd,SACyB;CACzB,MAAM,UAAU,QAAQ;CACxB,MAAM,cAAc,QAAQ,eAAe,gBAAgB,OAAO,KAAK,CAAC;CACxE,MAAM,cAAc,QAAQ,SAAS,eAAe,YAAY;CAChE,MAAM,iBAAiB,QAAQ,SAAS,kBAAkB,YAAY;CACtE,MAAM,eAAe,aAAa,SAAS,WAAW;CACtD,MAAM,kBAAkB,eACpB,aAAa,cAAc,MAAM,IACjC,KAAA;CACJ,MAAM,cAAc,QAAQ,QAAQ,gBAAgB;CACpD,MAAM,WAAW,cAAc,kBAAkB,KAAA;CAGjD,MAAM,iBAAiB,2BAA2B,SAAS,eAAe;CAC1E,MAAM,kBAAkB;EACtB,GAAG,OAAO,YAAY,YAAY;EAClC,GAAG,OAAO,YAAY,eAAe;EACrC,GAAG,OAAO,YAAY,gBAAgB;CACxC;CACA,MAAM,kBAAkB,OAAO,OAAO,QAAQ,SAAS,OAAO,CAAC,CAAC,QAC7D,WAAW,OAAO,iBAAiB,cAAc,KACpD;CACA,MAAM,UAAU,gBAAgB,KAAK,WAAW,qBAAqB,MAAM,CAAC;CAC5E,MAAM,WAAW,QAAQ,SAAS,WAAW,OAAO,QAAQ;CAC5D,MAAM,eAAe,WAAW,yBAAyB,QAAQ,QAAQ,CAAC;CAE1E,OAAO;EACL,eAAe;EACf,8BAAa,IAAI,KAAK,EAAA,CAAE,YAAY;EACpC;EACA;EACA,oBAAoB,QAAQ,eACxB,SAAS,SAAS,QAAQ,YAAY,IACtC,KAAA;EACJ,cAAc,eAAe,SAAS,SAAS,YAAY,IAAI,KAAA;EAC/D,cAAc,aAAa;GACzB,UAAU,EAAE,SAAS,aAAa;GAClC,aAAa,eAAe,aAAa,SAAS,cAAc,CAAC;GACjE,QAAQ,eAAe,YAAY;GACnC,GAAG,OAAO,YACR,eAAe,KAAK,SAAS,CAC3B,GAAG,yBAAyB,QAC5B,eAAe,KAAK,SAAS,IAAI,CAAC,CACpC,CAAC,CACH;EACF,CAAC;EACD,SAAS,WAAW,YAAY,OAAO;EACvC,cAAc;EACd,kBAAkB,OAAO,KAAK,eAAe,CAAC,CAC3C,QAAQ,QAAQ,IAAI,WAAW,sBAAsB,CAAC,CAAC,CACvD,KAAK;EACR,iBAAiB,OAAO,KAAK,eAAe,CAAC,CAC1C,QAAQ,QAAQ,kBAAkB,IAAI,GAAG,CAAC,CAAC,CAC3C,KAAK;EACR,MAAM,QAAQ,QAAQ,QAAQ,CAAC;EAC/B,SAAS,QAAQ,QAAQ;EACzB,OAAO,QAAQ,QAAQ,SAAS,CAAC;EACjC;EACA;EACA,SACE,QAAQ,QAAQ,mBAAmB,QAAQ,CAAC,IAAI,YAAY,OAAO;EACrE,iBAAiB,uBAAuB,SAAS,eAAe;EAChE;EACA,YACE,eAAe,eAAe,SAAS,IACnC,oBAAoB,SAAS,eAAe,IAC5C,KAAA;CACR;AACF;AAEA,SAAS,qBACP,QACuB;CACvB,MAAM,YACJ,OAAO,OAAO,iBAAiB,cAAc,WACzC,OAAO,gBAAgB,YACvB,CAAC;CACP,MAAM,SAAS,OAAO,QAAQ,OAAO,MAAM,CAAC,CAAC,KAAK,CAAC,MAAM,YAAY;EACnE;EACA,MAAM,MAAM;EACZ,UAAU,MAAM;EAChB,SAAS,MAAM;EACf,YAAY,WAAW,QAAQ,IAAI;CACrC,EAAE;CACF,MAAM,gBAAgB,OACnB,QAAQ,UAAU,yBAAyB,IAAI,MAAM,IAAI,CAAC,CAAC,CAC3D,KAAK,WAAW;EACf,MAAM,MAAM;EACZ,MAAM,MAAM;EACZ,UAAU,MAAM;EAChB,SAAS,MAAM;EACf,YAAY,MAAM;CACpB,EAAE;CAEJ,OAAO;EACL,MAAM,OAAO;EACb,eAAe,OAAO;EACtB,YAAY,OAAO;EACnB,WAAW,OAAO,QAAQ;EAC1B,aAAa,OAAO;EACpB,SAAS,OAAO;EAChB,YAAY,OAAO;EACnB;EACA;EACA,SAAS,OAAO,KAAK,OAAO,OAAO,CAAC,CAAC,KAAK;EAC1C,UAAU,eAAe,MAAM;EAC/B,sBAAsB,qBAAqB,MAAM;EACjD,MAAM,UAAU,QAAQ,CAAC;EACzB,SAAS,UAAU;EACnB,OAAO,UAAU,SAAS,CAAC;CAC7B;AACF;AAEA,SAAS,eACP,QAC0B;CAC1B,OAAO;EACL,GAAG,mBAAmB,OAAO,MAAM;EACnC,GAAG,mBAAmB,OAAO,MAAM;EACnC,GAAG,mBAAmB,OAAO,MAAM;EACnC,GAAG,WAAW,MAAM;CACtB;AACF;AAEA,SAAS,mBACP,MACA,QAC0B;CAC1B,MAAM,SAAS,OAAO,kBAAkB;CACxC,IAAI,CAAC,QAAQ,OAAO,CAAC;CAErB,OADmB,qBAAqB,MACjC,CAAA,CAAW,KAAK,eAAe;EACpC;EACA,MACE,SAAS,QACL,GAAG,OAAO,WAAW,GAAG,cACxB,GAAG,OAAO,UAAU,YAAY,EAAE,GAAG;EAC3C;EACA,YAAY,OAAO,iBAAiB,OAAO;EAC3C,MAAM,SAAS,QAAQ,QAAQ,QAAQ,SAAS,IAAI,KAAA;EACpD,QAAQ,SAAS,QAAQ,UAAU,SAAS,IAAI,KAAA;CAClD,EAAE;AACJ;AAEA,SAAS,qBAAqB,QAA2B;CACvD,IAAI,WAAW,MAAM,OAAO,CAAC,GAAG,mBAAmB;CACnD,IAAI,CAAC,UAAU,OAAO,WAAW,YAAY,MAAM,QAAQ,MAAM,GAC/D,OAAO,CAAC;CAEV,MAAM,eAAe;CACrB,MAAM,OAAO,MAAM,QAAQ,aAAa,OAAO,IAC3C,aAAa,UACb;CACJ,MAAM,WAAW,IAAI,IAAI,aAAa,WAAW,CAAC,CAAC;CACnD,OAAO,CAAC,GAAG,IAAI,IAAI,KAAK,QAAQ,cAAc,CAAC,SAAS,IAAI,SAAS,CAAC,CAAC,CAAC;AAC1E;AAEA,SAAS,WAAW,QAAyD;CAC3E,QAAQ,OAAO,SAAS,CAAC,EAAA,CAAG,KAAK,UAAU;EACzC,MAAM;EACN,MAAM,KAAK,SAAS;EACpB,WAAW,KAAK,SAAS;EACzB,aAAa,KAAK,SAAS;EAC3B,YAAY,OAAO,iBAAiB,OAAO;CAC7C,EAAE;AACJ;AAEA,SAAS,QAAQ,QAA+B,WAA2B;CACzE,MAAM,aAAa,OAAO,iBAAiB;CAC3C,MAAM,iBACJ,OAAO,eAAe,YAAY,OAAO,WAAW,SAAS,WACzD,WAAW,OACX,OAAO,WAAW,WAAW,KAAK,GAAG;CAC3C,IAAI,cAAc,UAAU,cAAc,UACxC,OAAO,IAAI;CAEb,IAAI,oBAAoB,SAAS,SAAS,GACxC,OAAO,IAAI,eAAe;CAE5B,OAAO,IAAI,eAAe,GAAG;AAC/B;AAEA,SAAS,UAAU,WAA2B;CAC5C,QAAQ,WAAR;EACE,KAAK;EACL,KAAK,OACH,OAAO;EACT,KAAK,UACH,OAAO;EACT,KAAK,UACH,OAAO;EACT,KAAK,UACH,OAAO;EACT,SACE,OAAO;CACX;AACF;AAEA,SAAS,qBAAqB,QAAyC;CACrE,MAAM,2BAAW,IAAI,IAAY;CACjC,KAAK,MAAM,SAAS,OAAO,OAAO,OAAO,MAAM,GAAG;EAChD,IAAI,MAAM,SAAS,cAAc,SAAS,IAAI,YAAY;EAC1D,IAAI,MAAM,SAAS,mBAAmB,SAAS,IAAI,iBAAiB;EACpE,IAAI,MAAM,SAAS,aAAa,SAAS,IAAI,WAAW;EACxD,IAAI,MAAM,SAAS,cAAc,SAAS,IAAI,YAAY;CAC5D;CACA,IAAI,OAAO,YAAY,gBAAgB,SAAS,IAAI,cAAc;CAClE,IAAI,OAAO,YAAY,oBAAoB,SAAS,IAAI,kBAAkB;CAC1E,IACE,OAAO,YAAY,gCACnB,OAAO,OAAO,YACd,OAAO,OAAO,QAEd,SAAS,IAAI,4BAA4B;CAE3C,IACE,OAAO,KAAK,OAAO,QAAQ,WAAW,CAAC,CAAC,CAAC,CAAC,MACvC,SAAS,OAAO,QAAQ,QAAQ,KAAK,EAAE,SAAS,MACnD,GAEA,SAAS,IAAI,aAAa;CAE5B,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC,KAAK;AAC5B;AAEA,SAAS,uBACP,SACA,iBACA;CACA,MAAM,SAAS,QAAQ,SAAS,WAAW,OAAO,MAAM;CACxD,OAAO;EACL,kBAAkB,OAAO,QAAQ,UAAU,MAAM,SAAS,YAAY,CAAC,CACpE;EACH,uBAAuB,OAAO,QAC3B,UAAU,MAAM,SAAS,iBAC5B,CAAC,CAAC;EACF,qBAAqB,QAAQ,QAAQ,WACnC,OAAO,qBAAqB,SAAS,cAAc,CACrD,CAAC,CAAC;EACF,qBAAqB,QAAQ,QAAQ,WACnC,OAAO,qBAAqB,SAAS,kBAAkB,CACzD,CAAC,CAAC;EACF,yBAAyB,QAAQ,QAAQ,WACvC,OAAO,qBAAqB,SAAS,4BAA4B,CACnE,CAAC,CAAC;EACF,aAAa,gBAAgB,QAC1B,OAAO,WACN,QACA,OAAO,OAAO,OAAO,QAAQ,WAAW,CAAC,CAAC,CAAC,CAAC,QACzC,WAAW,OAAO,SAAS,MAC9B,CAAC,CAAC,QACJ,CACF;CACF;AACF;AAEA,SAAS,WACP,QACA,WACoB;CACpB,MAAM,aAAa,aAAa,SAAS;CACzC,OAAO,OAAO,QAAQ,QAAQ,WAAW,EAAE;AAC7C;AAEA,SAAS,YACP,SAC2C;CAC3C,MAAM,SAAS,KAAK,SAAS,KAAK;CAClC,IAAI,CAAC,WAAW,MAAM,GAAG,OAAO,CAAC;CACjC,MAAM,UAAqD,CAAC;CAC5D,KAAK,MAAM,YAAY,UAAU,MAAM,GAAG;EACxC,IAAI,CAAC,SAAS,SAAS,KAAK,GAAG;EAC/B,MAAM,UAAU,aAAa,UAAU,MAAM;EAC7C,IAAI,CAAC,QAAQ,SAAS,cAAc,GAAG;EACvC,MAAM,WAAW,QAAQ,MAAM,yCAAyC;EACxE,QAAQ,KAAK;GACX,UAAU,SAAS,SAAS,QAAQ;GACpC,KAAK,WAAW;EAClB,CAAC;CACH;CACA,OAAO;AACT;AAEA,SAAS,UAAU,KAAuB;CACxC,MAAM,QAAkB,CAAC;CACzB,KAAK,MAAM,SAAS,YAAY,KAAK,EAAE,eAAe,KAAK,CAAC,GAAG;EAC7D,IACE,MAAM,SAAS,kBACf,MAAM,SAAS,UACf,MAAM,SAAS,eAEf;EAEF,MAAM,WAAW,KAAK,KAAK,MAAM,IAAI;EACrC,IAAI,MAAM,YAAY,GACpB,MAAM,KAAK,GAAG,UAAU,QAAQ,CAAC;OAC5B,IAAI,MAAM,OAAO,GACtB,MAAM,KAAK,QAAQ;CAEvB;CACA,OAAO;AACT;AAEA,SAAS,aAAa,SAAiD;CACrE,MAAM,SAAiC,CAAC;CACxC,KAAK,MAAM,CAAC,MAAM,WAAW,OAAO,QAAQ,OAAO,GAAG;EACpD,IAAI,CAAC,QAAQ;EACb,MAAM,UACJ,aAAa,SAAS,OAAO,UAAU,aAAa,OAAO,MAAM,MAAM;EACzE,OAAO,QAAQ,WAAW,QAAQ,CAAC,CAAC,OAAO,OAAO,CAAC,CAAC,OAAO,KAAK;CAClE;CACA,OAAO;AACT;AAIA,SAAS,eAAe,MAAkD;CACxE,OAAO,OAAO,EAAE,KAAK,IAAI,KAAA;AAC3B;AAEA,SAAS,aAAa,SAAiB,MAAkC;CACvE,MAAM,WAAW,KAAK,SAAS,IAAI;CACnC,OAAO,WAAW,QAAQ,IAAI,WAAW,KAAA;AAC3C;AAEA,SAAS,gBAAgB,SAAyC;CAChE,MAAM,OAAO,KAAK,SAAS,cAAc;CACzC,IAAI,CAAC,WAAW,IAAI,GAAG,OAAO;CAC9B,OAAO,KAAK,MAAM,aAAa,MAAM,MAAM,CAAC;AAC9C;AAEA,SAAS,OAAO,OAAwC;CACtD,OAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK,IACrE,QACD,CAAC;AACP;AAEA,SAAS,WAAW,cAAiC;CACnD,IAAI,OAAO,iBAAiB,UAAU,OAAO,CAAC,GAAG;CACjD,IACE,OAAO,iBAAiB,YACxB,iBAAiB,QACjB,MAAM,QAAQ,YAAY,GAE1B,OAAO,CAAC;CAEV,OAAO,OAAO,KAAK,YAAY,CAAC,CAAC,KAAK;AACxC;AAEA,SAAS,aAAa,OAAuB;CAC3C,OAAO,MACJ,QAAQ,sBAAsB,OAAO,CAAC,CACtC,QAAQ,WAAW,GAAG,CAAC,CACvB,YAAY;AACjB;AAEA,SAAS,yBAAyB,UAAwC;CACxE,MAAM,aAAa,KAAK,MAAM,KAAK,UAAU,QAAQ,CAAC;CAItD,OAAO,WAAW;CAClB,OAAO;AACT;AAEA,SAAS,WAAW,OAAwB;CAC1C,OAAO,KAAK,UAAU,SAAS,KAAK,GAAG,MAAM,CAAC;AAChD;AAEA,SAAS,SAAS,OAAyB;CACzC,IAAI,MAAM,QAAQ,KAAK,GAAG,OAAO,MAAM,IAAI,QAAQ;CACnD,IAAI,SAAS,OAAO,UAAU,UAC5B,OAAO,OAAO,YACZ,OAAO,QAAQ,KAAgC,CAAC,CAC7C,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,CACtC,KAAK,CAAC,KAAK,WAAW,CAAC,KAAK,SAAS,KAAK,CAAC,CAAC,CACjD;CAEF,OAAO;AACT"}

package/dist/manifest/static-manifest.js

@@ -1,9 +1,9 @@
 //#region src/manifest/static-manifest.ts
 var staticManifest = {
 	"version": "1.0.0",
-	"timestamp": 1785022559936,
+	"timestamp": 1785029944237,
 	"packageName": "@happyvertical/smrt-core",
-	"packageVersion": "0.40.22",
+	"packageVersion": "0.40.24",
 	"objects": {
 		"@happyvertical/smrt-core:SmrtClass": {
 			"name": "smrtclass",