@happyvertical/smrt-core 0.38.6 → 0.38.8

package/dist/manifest.json

@@ -1,8 +1,8 @@
 {
   "version": "1.0.0",
-  "timestamp": 1783283654651,
+  "timestamp": 1783351308817,
   "packageName": "@happyvertical/smrt-core",
-  "packageVersion": "0.38.6",
+  "packageVersion": "0.38.8",
   "objects": {
     "@happyvertical/smrt-core:SmrtClass": {
       "name": "smrtclass",

package/dist/prebuild/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prebuild/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAG5D,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CAAC;IACvC,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,sCAAsC;IACtC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,IAAI,CAAC,CAkCf;AA8TD;;GAEG;AACH,wBAAsB,2BAA2B,CAC/C,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,IAAI,CAAC,CAkBf"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prebuild/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAG5D,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CAAC;IACvC,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,sCAAsC;IACtC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,IAAI,CAAC,CAkCf;AAiVD;;GAEG;AACH,wBAAsB,2BAA2B,CAC/C,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,IAAI,CAAC,CAkBf"}

package/dist/prebuild/index.js

@@ -215,6 +215,15 @@ declare module '@smrt/web' {
     relatedCollection: string;
   }
 
+  /** A WebMCP/MCP tool descriptor for one collection action (#1812). */
+  export interface WebToolDescriptor {
+    action: string;
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    readOnly: boolean;
+  }
+
   export interface SmrtWebCollectionDefinition<TData = Record<string, unknown>> {
     name: string;
     className: string;
@@ -224,6 +233,8 @@ declare module '@smrt/web' {
     fields: Record<string, SmrtWebFieldDefinition>;
     /** Manifest-derived relationship edges to sibling REST collections. */
     relationships: SmrtWebRelationship[];
+    /** WebMCP/MCP tool descriptors for the exposed actions (#1812). */
+    toolDescriptors: WebToolDescriptor[];
     /** Phantom row-type carrier for inference — never present at runtime. */
     _row?: TData;
   }
@@ -236,6 +247,14 @@ ${selectWebCollectionEntries(manifest).map(({ collection, obj }) => `    ${colle
   export function getCollectionDefinition<
     K extends keyof SmrtWebCollectionDefinitions,
   >(name: K): SmrtWebCollectionDefinitions[K];
+  /**
+   * Build-time web-collection shape digest (#1764). A deterministic,
+   * replica-stable hash of the emitted collection definitions; a change means
+   * old persisted client rows may mis-hydrate. Consumers fold it into the
+   * durable persistence namespace and the version-awareness updateAvailable
+   * contract signal.
+   */
+  export const manifestHash: string;
   export default collectionDefinitions;
 }`;
 	fs.writeFileSync(path.join(outDir, "smrt-manifest.d.ts"), manifestDeclaration);

package/dist/prebuild/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/prebuild/index.ts"],"sourcesContent":["/**\n * Pre-build utilities for generating TypeScript declarations\n * Solves virtual module resolution by creating physical .d.ts files\n */\n\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\nimport type { SmartObjectManifest } from '../scanner/types';\nimport { selectWebCollectionEntries } from '../vite-plugin/web-collections.js';\n\nexport interface PrebuildOptions {\n  /** Path to manifest file or manifest object */\n  manifest: string | SmartObjectManifest;\n  /** Output directory for generated types */\n  outDir: string;\n  /** Include virtual module declarations */\n  includeVirtualModules?: boolean;\n  /** Include object type definitions */\n  includeObjectTypes?: boolean;\n  /** Project root path for resolving relative paths */\n  projectRoot?: string;\n}\n\n/**\n * Generate TypeScript declaration files from SMRT manifest\n */\nexport async function generateDeclarations(\n  options: PrebuildOptions,\n): Promise<void> {\n  const {\n    manifest: manifestInput,\n    outDir,\n    includeVirtualModules = true,\n    includeObjectTypes = true,\n    projectRoot = process.cwd(),\n  } = options;\n\n  // Load manifest\n  const manifest: SmartObjectManifest =\n    typeof manifestInput === 'string'\n      ? JSON.parse(fs.readFileSync(manifestInput, 'utf-8'))\n      : manifestInput;\n\n  // Ensure output directory exists\n  const fullOutDir = path.isAbsolute(outDir)\n    ? outDir\n    : path.join(projectRoot, outDir);\n  fs.mkdirSync(fullOutDir, { recursive: true });\n\n  console.log(`[smrt:prebuild] Generating declarations to ${fullOutDir}`);\n\n  if (includeObjectTypes) {\n    await generateObjectTypeDeclarations(manifest, fullOutDir);\n  }\n\n  if (includeVirtualModules) {\n    await generateVirtualModuleDeclarations(manifest, fullOutDir);\n  }\n\n  console.log(\n    `[smrt:prebuild] Generated declarations for ${Object.keys(manifest.objects).length} SMRT objects`,\n  );\n}\n\n/**\n * Generate TypeScript interfaces for SMRT objects\n */\nasync function generateObjectTypeDeclarations(\n  manifest: SmartObjectManifest,\n  outDir: string,\n): Promise<void> {\n  const interfaces: string[] = [];\n\n  // Generate interfaces for each discovered SMRT object\n  for (const [_objectName, objectMeta] of Object.entries(manifest.objects)) {\n    const fields = objectMeta.fields || {};\n    const propertyLines: string[] = [];\n\n    // Add standard SmrtObject properties\n    propertyLines.push('  id?: string;');\n    propertyLines.push('  created_at?: string;');\n    propertyLines.push('  updated_at?: string;');\n\n    // Add object-specific properties\n    for (const [fieldName, fieldDef] of Object.entries(fields)) {\n      const type = mapFieldTypeToTypeScript(fieldDef.type);\n      const optional = !fieldDef.required ? '?' : '';\n      propertyLines.push(`  ${fieldName}${optional}: ${type};`);\n    }\n\n    const interfaceDef = `export interface ${objectMeta.className}Data {\n${propertyLines.join('\\n')}\n}`;\n    interfaces.push(interfaceDef);\n  }\n\n  // Write object types file\n  const objectTypesContent = `/**\n * Auto-generated TypeScript interfaces for SMRT objects\n * Generated at build time from @smrt() decorated classes\n *\n * DO NOT EDIT THIS FILE MANUALLY\n */\n\n${interfaces.join('\\n\\n')}\n`;\n\n  fs.writeFileSync(path.join(outDir, 'smrt-objects.d.ts'), objectTypesContent);\n}\n\n/**\n * Generate virtual module declarations\n */\nasync function generateVirtualModuleDeclarations(\n  manifest: SmartObjectManifest,\n  outDir: string,\n): Promise<void> {\n  // Generate manifest module declaration\n  const manifestDeclaration = `/**\n * Auto-generated manifest module declaration\n */\ndeclare module '@smrt/manifest' {\n  export interface SmrtObjectField {\n    type: string;\n    required?: boolean;\n    default?: any;\n  }\n\n  export interface SmrtObjectMethod {\n    name: string;\n    parameters: Array<{\n      name: string;\n      type: string;\n      optional?: boolean;\n      default?: any;\n    }>;\n    returnType: string;\n    async: boolean;\n    isStatic: boolean;\n    isPublic: boolean;\n  }\n\n  export interface SmrtObjectDefinition {\n    name: string;\n    className: string;\n    collection: string;\n    filePath: string;\n    fields: Record<string, SmrtObjectField>;\n    methods: Record<string, SmrtObjectMethod>;\n    decoratorConfig: any;\n    extends?: string;\n  }\n\n  export interface SmrtManifest {\n    version: string;\n    timestamp: number;\n    objects: Record<string, SmrtObjectDefinition>;\n  }\n\n  export const manifest: SmrtManifest;\n  export default manifest;\n}`;\n\n  // Generate client module declaration\n  const collectionNames = [\n    ...new Set(Object.values(manifest.objects).map((obj) => obj.collection)),\n  ];\n\n  const apiClientInterface = collectionNames\n    .map((collection) => {\n      const dataType = Object.entries(manifest.objects).find(\n        ([, obj]) => obj.collection === collection,\n      )?.[1].className;\n      const interfaceName = dataType ? `${dataType}Data` : 'any';\n      return `    ${collection}: CrudOperations<${interfaceName}>;`;\n    })\n    .join('\\n');\n\n  // Wire-shape policy (#1797): the server returns BARE JSON — a bare array for\n  // list/search, a bare object for get/create/update — with snake_case field\n  // names (created_at, updated_at). These declarations match that shape (no\n  // envelope, no camelCase) and are byte-identical to the vite-plugin client\n  // declaration. Fetchers reject on non-2xx with a SmrtClientError (#1796).\n  const clientDeclaration = `/**\n * Auto-generated API client module declaration\n */\ndeclare module '@smrt/client' {\n  /** Shape of a JSON error body carried by a rejected request (SmrtClientError.body). */\n  export interface ApiError {\n    error?: string;\n    message?: string;\n  }\n\n  /** Typed error thrown by every fetcher on a non-2xx response (#1796). */\n  export interface SmrtClientError extends Error {\n    name: 'SmrtClientError';\n    status: number;\n    body?: ApiError | string;\n  }\n\n  export interface CrudOperations<T = any> {\n    list(params?: Record<string, any>): Promise<T[]>;\n    get(id: string): Promise<T>;\n    create(data: Partial<T>): Promise<T>;\n    update(id: string, data: Partial<T>): Promise<T>;\n    delete(id: string): Promise<boolean>;\n    search(query: string): Promise<T[]>;\n  }\n\n  export interface ApiClient {\n${apiClientInterface}\n  }\n\n  export function createClient(basePath?: string): ApiClient;\n  export default createClient;\n}`;\n\n  // Generate routes module declaration\n  const routesDeclaration = `/**\n * Auto-generated routes module declaration\n */\ndeclare module '@smrt/routes' {\n  export interface RouteApp {\n    get(path: string, handler: (req: any, res: any) => void): void;\n    post(path: string, handler: (req: any, res: any) => void): void;\n    put(path: string, handler: (req: any, res: any) => void): void;\n    delete(path: string, handler: (req: any, res: any) => void): void;\n  }\n\n  export function setupRoutes(app: RouteApp): void;\n  export default setupRoutes;\n}`;\n\n  // Generate MCP module declaration\n  const mcpDeclaration = `/**\n * Auto-generated MCP module declaration\n */\ndeclare module '@smrt/mcp' {\n  export interface McpTool {\n    name: string;\n    description: string;\n    inputSchema: {\n      type: string;\n      properties: Record<string, any>;\n      required?: string[];\n    };\n  }\n\n  export const tools: McpTool[];\n  export function createMCPServer(): {\n    name: string;\n    version: string;\n    tools: McpTool[]\n  };\n  export default createMCPServer;\n}`;\n\n  // Generate types module declaration with object imports\n  const objectImports = Object.values(manifest.objects)\n    .map(\n      (obj) =>\n        `  export type ${obj.className}Data = import('./smrt-objects').${obj.className}Data;`,\n    )\n    .join('\\n');\n\n  const typesDeclaration = `/**\n * Auto-generated types module declaration\n */\ndeclare module '@smrt/types' {\n${objectImports}\n\n  export interface Request {\n    params: Record<string, string>;\n    query: Record<string, any>;\n    json(): Promise<any>;\n  }\n\n  export interface Response {\n    json(data: any, init?: { status?: number }): Response;\n    status(code: number): Response;\n  }\n}`;\n\n  // Generate web collection-definition module declaration (#1761). Selection\n  // shares selectWebCollectionEntries with the vite-plugin runtime module and\n  // its virt-web d.ts, so this `tsc`-only consumer declaration cannot drift\n  // from the emitted values.\n  const webCollectionEntries = selectWebCollectionEntries(manifest)\n    .map(\n      ({ collection, obj }) =>\n        `    ${collection}: SmrtWebCollectionDefinition<import('./smrt-objects').${obj.className}Data>;`,\n    )\n    .join('\\n');\n\n  const webDeclaration = `/**\n * Auto-generated web collection-definition module declaration (#1761)\n */\ndeclare module '@smrt/web' {\n  export interface SmrtWebFieldDefinition {\n    type: string;\n    required?: boolean;\n    default?: unknown;\n  }\n\n  export type SmrtWebRelationshipKind =\n    | 'foreignKey'\n    | 'crossPackageRef'\n    | 'oneToMany'\n    | 'manyToMany';\n\n  /**\n   * A manifest-derived edge to a sibling REST collection. Mutating this\n   * collection invalidates the caches of the collections named by these edges\n   * (#1761 relationship-derived invalidation).\n   */\n  export interface SmrtWebRelationship {\n    field: string;\n    kind: SmrtWebRelationshipKind;\n    relatedCollection: string;\n  }\n\n  export interface SmrtWebCollectionDefinition<TData = Record<string, unknown>> {\n    name: string;\n    className: string;\n    endpoint: string;\n    idField: string;\n    actions: string[];\n    fields: Record<string, SmrtWebFieldDefinition>;\n    /** Manifest-derived relationship edges to sibling REST collections. */\n    relationships: SmrtWebRelationship[];\n    /** Phantom row-type carrier for inference — never present at runtime. */\n    _row?: TData;\n  }\n\n  export interface SmrtWebCollectionDefinitions {\n${webCollectionEntries}\n  }\n\n  export const collectionDefinitions: SmrtWebCollectionDefinitions;\n  export function getCollectionDefinition<\n    K extends keyof SmrtWebCollectionDefinitions,\n  >(name: K): SmrtWebCollectionDefinitions[K];\n  export default collectionDefinitions;\n}`;\n\n  // Write all virtual module declarations\n  fs.writeFileSync(\n    path.join(outDir, 'smrt-manifest.d.ts'),\n    manifestDeclaration,\n  );\n  fs.writeFileSync(path.join(outDir, 'smrt-client.d.ts'), clientDeclaration);\n  fs.writeFileSync(path.join(outDir, 'smrt-routes.d.ts'), routesDeclaration);\n  fs.writeFileSync(path.join(outDir, 'smrt-mcp.d.ts'), mcpDeclaration);\n  fs.writeFileSync(path.join(outDir, 'smrt-types.d.ts'), typesDeclaration);\n  fs.writeFileSync(path.join(outDir, 'smrt-web.d.ts'), webDeclaration);\n}\n\n/**\n * Map SMRT field types to TypeScript types\n */\nfunction mapFieldTypeToTypeScript(smrtType: string): string {\n  switch (smrtType) {\n    case 'text':\n      return 'string';\n    case 'decimal':\n    case 'integer':\n      return 'number';\n    case 'boolean':\n      return 'boolean';\n    case 'datetime':\n      return 'string | Date';\n    case 'json':\n      return 'any';\n    case 'foreignKey':\n      return 'string';\n    default:\n      return 'any';\n  }\n}\n\n/**\n * CLI command for generating declarations\n */\nexport async function generateDeclarationsFromCLI(\n  args: string[],\n): Promise<void> {\n  const manifestPath = args[0];\n  const outDir = args[1] || 'src/types/generated';\n\n  if (!manifestPath) {\n    console.error('Usage: generate-declarations <manifest-path> [output-dir]');\n    process.exit(1);\n  }\n\n  if (!fs.existsSync(manifestPath)) {\n    console.error(`Manifest file not found: ${manifestPath}`);\n    process.exit(1);\n  }\n\n  await generateDeclarations({\n    manifest: manifestPath,\n    outDir,\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/prebuild/index.ts"],"sourcesContent":["/**\n * Pre-build utilities for generating TypeScript declarations\n * Solves virtual module resolution by creating physical .d.ts files\n */\n\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\nimport type { SmartObjectManifest } from '../scanner/types';\nimport { selectWebCollectionEntries } from '../vite-plugin/web-collections.js';\n\nexport interface PrebuildOptions {\n  /** Path to manifest file or manifest object */\n  manifest: string | SmartObjectManifest;\n  /** Output directory for generated types */\n  outDir: string;\n  /** Include virtual module declarations */\n  includeVirtualModules?: boolean;\n  /** Include object type definitions */\n  includeObjectTypes?: boolean;\n  /** Project root path for resolving relative paths */\n  projectRoot?: string;\n}\n\n/**\n * Generate TypeScript declaration files from SMRT manifest\n */\nexport async function generateDeclarations(\n  options: PrebuildOptions,\n): Promise<void> {\n  const {\n    manifest: manifestInput,\n    outDir,\n    includeVirtualModules = true,\n    includeObjectTypes = true,\n    projectRoot = process.cwd(),\n  } = options;\n\n  // Load manifest\n  const manifest: SmartObjectManifest =\n    typeof manifestInput === 'string'\n      ? JSON.parse(fs.readFileSync(manifestInput, 'utf-8'))\n      : manifestInput;\n\n  // Ensure output directory exists\n  const fullOutDir = path.isAbsolute(outDir)\n    ? outDir\n    : path.join(projectRoot, outDir);\n  fs.mkdirSync(fullOutDir, { recursive: true });\n\n  console.log(`[smrt:prebuild] Generating declarations to ${fullOutDir}`);\n\n  if (includeObjectTypes) {\n    await generateObjectTypeDeclarations(manifest, fullOutDir);\n  }\n\n  if (includeVirtualModules) {\n    await generateVirtualModuleDeclarations(manifest, fullOutDir);\n  }\n\n  console.log(\n    `[smrt:prebuild] Generated declarations for ${Object.keys(manifest.objects).length} SMRT objects`,\n  );\n}\n\n/**\n * Generate TypeScript interfaces for SMRT objects\n */\nasync function generateObjectTypeDeclarations(\n  manifest: SmartObjectManifest,\n  outDir: string,\n): Promise<void> {\n  const interfaces: string[] = [];\n\n  // Generate interfaces for each discovered SMRT object\n  for (const [_objectName, objectMeta] of Object.entries(manifest.objects)) {\n    const fields = objectMeta.fields || {};\n    const propertyLines: string[] = [];\n\n    // Add standard SmrtObject properties\n    propertyLines.push('  id?: string;');\n    propertyLines.push('  created_at?: string;');\n    propertyLines.push('  updated_at?: string;');\n\n    // Add object-specific properties\n    for (const [fieldName, fieldDef] of Object.entries(fields)) {\n      const type = mapFieldTypeToTypeScript(fieldDef.type);\n      const optional = !fieldDef.required ? '?' : '';\n      propertyLines.push(`  ${fieldName}${optional}: ${type};`);\n    }\n\n    const interfaceDef = `export interface ${objectMeta.className}Data {\n${propertyLines.join('\\n')}\n}`;\n    interfaces.push(interfaceDef);\n  }\n\n  // Write object types file\n  const objectTypesContent = `/**\n * Auto-generated TypeScript interfaces for SMRT objects\n * Generated at build time from @smrt() decorated classes\n *\n * DO NOT EDIT THIS FILE MANUALLY\n */\n\n${interfaces.join('\\n\\n')}\n`;\n\n  fs.writeFileSync(path.join(outDir, 'smrt-objects.d.ts'), objectTypesContent);\n}\n\n/**\n * Generate virtual module declarations\n */\nasync function generateVirtualModuleDeclarations(\n  manifest: SmartObjectManifest,\n  outDir: string,\n): Promise<void> {\n  // Generate manifest module declaration\n  const manifestDeclaration = `/**\n * Auto-generated manifest module declaration\n */\ndeclare module '@smrt/manifest' {\n  export interface SmrtObjectField {\n    type: string;\n    required?: boolean;\n    default?: any;\n  }\n\n  export interface SmrtObjectMethod {\n    name: string;\n    parameters: Array<{\n      name: string;\n      type: string;\n      optional?: boolean;\n      default?: any;\n    }>;\n    returnType: string;\n    async: boolean;\n    isStatic: boolean;\n    isPublic: boolean;\n  }\n\n  export interface SmrtObjectDefinition {\n    name: string;\n    className: string;\n    collection: string;\n    filePath: string;\n    fields: Record<string, SmrtObjectField>;\n    methods: Record<string, SmrtObjectMethod>;\n    decoratorConfig: any;\n    extends?: string;\n  }\n\n  export interface SmrtManifest {\n    version: string;\n    timestamp: number;\n    objects: Record<string, SmrtObjectDefinition>;\n  }\n\n  export const manifest: SmrtManifest;\n  export default manifest;\n}`;\n\n  // Generate client module declaration\n  const collectionNames = [\n    ...new Set(Object.values(manifest.objects).map((obj) => obj.collection)),\n  ];\n\n  const apiClientInterface = collectionNames\n    .map((collection) => {\n      const dataType = Object.entries(manifest.objects).find(\n        ([, obj]) => obj.collection === collection,\n      )?.[1].className;\n      const interfaceName = dataType ? `${dataType}Data` : 'any';\n      return `    ${collection}: CrudOperations<${interfaceName}>;`;\n    })\n    .join('\\n');\n\n  // Wire-shape policy (#1797): the server returns BARE JSON — a bare array for\n  // list/search, a bare object for get/create/update — with snake_case field\n  // names (created_at, updated_at). These declarations match that shape (no\n  // envelope, no camelCase) and are byte-identical to the vite-plugin client\n  // declaration. Fetchers reject on non-2xx with a SmrtClientError (#1796).\n  const clientDeclaration = `/**\n * Auto-generated API client module declaration\n */\ndeclare module '@smrt/client' {\n  /** Shape of a JSON error body carried by a rejected request (SmrtClientError.body). */\n  export interface ApiError {\n    error?: string;\n    message?: string;\n  }\n\n  /** Typed error thrown by every fetcher on a non-2xx response (#1796). */\n  export interface SmrtClientError extends Error {\n    name: 'SmrtClientError';\n    status: number;\n    body?: ApiError | string;\n  }\n\n  export interface CrudOperations<T = any> {\n    list(params?: Record<string, any>): Promise<T[]>;\n    get(id: string): Promise<T>;\n    create(data: Partial<T>): Promise<T>;\n    update(id: string, data: Partial<T>): Promise<T>;\n    delete(id: string): Promise<boolean>;\n    search(query: string): Promise<T[]>;\n  }\n\n  export interface ApiClient {\n${apiClientInterface}\n  }\n\n  export function createClient(basePath?: string): ApiClient;\n  export default createClient;\n}`;\n\n  // Generate routes module declaration\n  const routesDeclaration = `/**\n * Auto-generated routes module declaration\n */\ndeclare module '@smrt/routes' {\n  export interface RouteApp {\n    get(path: string, handler: (req: any, res: any) => void): void;\n    post(path: string, handler: (req: any, res: any) => void): void;\n    put(path: string, handler: (req: any, res: any) => void): void;\n    delete(path: string, handler: (req: any, res: any) => void): void;\n  }\n\n  export function setupRoutes(app: RouteApp): void;\n  export default setupRoutes;\n}`;\n\n  // Generate MCP module declaration\n  const mcpDeclaration = `/**\n * Auto-generated MCP module declaration\n */\ndeclare module '@smrt/mcp' {\n  export interface McpTool {\n    name: string;\n    description: string;\n    inputSchema: {\n      type: string;\n      properties: Record<string, any>;\n      required?: string[];\n    };\n  }\n\n  export const tools: McpTool[];\n  export function createMCPServer(): {\n    name: string;\n    version: string;\n    tools: McpTool[]\n  };\n  export default createMCPServer;\n}`;\n\n  // Generate types module declaration with object imports\n  const objectImports = Object.values(manifest.objects)\n    .map(\n      (obj) =>\n        `  export type ${obj.className}Data = import('./smrt-objects').${obj.className}Data;`,\n    )\n    .join('\\n');\n\n  const typesDeclaration = `/**\n * Auto-generated types module declaration\n */\ndeclare module '@smrt/types' {\n${objectImports}\n\n  export interface Request {\n    params: Record<string, string>;\n    query: Record<string, any>;\n    json(): Promise<any>;\n  }\n\n  export interface Response {\n    json(data: any, init?: { status?: number }): Response;\n    status(code: number): Response;\n  }\n}`;\n\n  // Generate web collection-definition module declaration (#1761). Selection\n  // shares selectWebCollectionEntries with the vite-plugin runtime module and\n  // its virt-web d.ts, so this `tsc`-only consumer declaration cannot drift\n  // from the emitted values.\n  const webCollectionEntries = selectWebCollectionEntries(manifest)\n    .map(\n      ({ collection, obj }) =>\n        `    ${collection}: SmrtWebCollectionDefinition<import('./smrt-objects').${obj.className}Data>;`,\n    )\n    .join('\\n');\n\n  const webDeclaration = `/**\n * Auto-generated web collection-definition module declaration (#1761)\n */\ndeclare module '@smrt/web' {\n  export interface SmrtWebFieldDefinition {\n    type: string;\n    required?: boolean;\n    default?: unknown;\n  }\n\n  export type SmrtWebRelationshipKind =\n    | 'foreignKey'\n    | 'crossPackageRef'\n    | 'oneToMany'\n    | 'manyToMany';\n\n  /**\n   * A manifest-derived edge to a sibling REST collection. Mutating this\n   * collection invalidates the caches of the collections named by these edges\n   * (#1761 relationship-derived invalidation).\n   */\n  export interface SmrtWebRelationship {\n    field: string;\n    kind: SmrtWebRelationshipKind;\n    relatedCollection: string;\n  }\n\n  /** A WebMCP/MCP tool descriptor for one collection action (#1812). */\n  export interface WebToolDescriptor {\n    action: string;\n    name: string;\n    description: string;\n    inputSchema: Record<string, unknown>;\n    readOnly: boolean;\n  }\n\n  export interface SmrtWebCollectionDefinition<TData = Record<string, unknown>> {\n    name: string;\n    className: string;\n    endpoint: string;\n    idField: string;\n    actions: string[];\n    fields: Record<string, SmrtWebFieldDefinition>;\n    /** Manifest-derived relationship edges to sibling REST collections. */\n    relationships: SmrtWebRelationship[];\n    /** WebMCP/MCP tool descriptors for the exposed actions (#1812). */\n    toolDescriptors: WebToolDescriptor[];\n    /** Phantom row-type carrier for inference — never present at runtime. */\n    _row?: TData;\n  }\n\n  export interface SmrtWebCollectionDefinitions {\n${webCollectionEntries}\n  }\n\n  export const collectionDefinitions: SmrtWebCollectionDefinitions;\n  export function getCollectionDefinition<\n    K extends keyof SmrtWebCollectionDefinitions,\n  >(name: K): SmrtWebCollectionDefinitions[K];\n  /**\n   * Build-time web-collection shape digest (#1764). A deterministic,\n   * replica-stable hash of the emitted collection definitions; a change means\n   * old persisted client rows may mis-hydrate. Consumers fold it into the\n   * durable persistence namespace and the version-awareness updateAvailable\n   * contract signal.\n   */\n  export const manifestHash: string;\n  export default collectionDefinitions;\n}`;\n\n  // Write all virtual module declarations\n  fs.writeFileSync(\n    path.join(outDir, 'smrt-manifest.d.ts'),\n    manifestDeclaration,\n  );\n  fs.writeFileSync(path.join(outDir, 'smrt-client.d.ts'), clientDeclaration);\n  fs.writeFileSync(path.join(outDir, 'smrt-routes.d.ts'), routesDeclaration);\n  fs.writeFileSync(path.join(outDir, 'smrt-mcp.d.ts'), mcpDeclaration);\n  fs.writeFileSync(path.join(outDir, 'smrt-types.d.ts'), typesDeclaration);\n  fs.writeFileSync(path.join(outDir, 'smrt-web.d.ts'), webDeclaration);\n}\n\n/**\n * Map SMRT field types to TypeScript types\n */\nfunction mapFieldTypeToTypeScript(smrtType: string): string {\n  switch (smrtType) {\n    case 'text':\n      return 'string';\n    case 'decimal':\n    case 'integer':\n      return 'number';\n    case 'boolean':\n      return 'boolean';\n    case 'datetime':\n      return 'string | Date';\n    case 'json':\n      return 'any';\n    case 'foreignKey':\n      return 'string';\n    default:\n      return 'any';\n  }\n}\n\n/**\n * CLI command for generating declarations\n */\nexport async function generateDeclarationsFromCLI(\n  args: string[],\n): Promise<void> {\n  const manifestPath = args[0];\n  const outDir = args[1] || 'src/types/generated';\n\n  if (!manifestPath) {\n    console.error('Usage: generate-declarations <manifest-path> [output-dir]');\n    process.exit(1);\n  }\n\n  if (!fs.existsSync(manifestPath)) {\n    console.error(`Manifest file not found: ${manifestPath}`);\n    process.exit(1);\n  }\n\n  await generateDeclarations({\n    manifest: manifestPath,\n    outDir,\n  });\n}\n"],"mappings":"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"}

package/dist/smrt-knowledge.json

@@ -1,14 +1,14 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-07-05T20:34:07.713Z",
+  "generatedAt": "2026-07-06T15:21:45.813Z",
   "packageName": "@happyvertical/smrt-core",
-  "packageVersion": "0.38.6",
+  "packageVersion": "0.38.8",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "671d238201fcdf9a9608f9e73aa0eb5d0748d24b0026e6056b9762400e198523",
-    "packageJson": "39b0eea38491228ef8b9fa3025f69ad1a342876a97120261b6ee8c6e0df6de3f",
-    "agents": "3d4ecc60503af2e37272cfc4ea8315344a84b2c74c10f5c6a83cac1dcd67e0ef"
+    "manifest": "d8d04e2434816051845b1a2f992fbe038dae3ced1ac7adb69c8f564b73f0e8cb",
+    "packageJson": "a98e5a9fe8bb4dbf84dc72ac2c647b294dce8e94b535f24832ec264a2fd3d228",
+    "agents": "800af20a3d9cf7e4bf236318a822699cf64554a242fdfe0f6da1237226809a2c"
   },
   "exports": [
     ".",
@@ -323,5 +323,5 @@
     "polymorphicAssociations": 1,
     "uuidColumns": 3
   },
-  "agentDoc": "# @happyvertical/smrt-core\n\nORM, code generation, AI integration, and the DispatchBus. Everything else builds on this.\n\n## Key Classes\n\n| Class | File | Purpose |\n|-------|------|---------|\n| SmrtObject | `src/object.ts` | Base persistent object — save, delete, is(), do(), loadFromId/Slug |\n| SmrtCollection | `src/collection.ts` | CRUD collection — list, get, create, delete, getOrUpsert |\n| ObjectRegistry | `src/registry.ts` | Global singleton (globalThis) — class metadata, fields, STI chains, manifests |\n| DispatchBus | `src/dispatch/bus.ts` | Inter-agent messaging — emit, subscribe (persistent), process |\n| GlobalInterceptors | `src/interceptors.ts` | Plugin system — beforeList/Get/Save/Delete hooks (used by tenancy) |\n\n## SmrtObject Lifecycle\n\n`constructor(options)` → `initialize()` → ready for `save()`/`delete()`/`loadFromId()`\n\n- `initialize()`: loads field initializers, applies option values (options override initializers), loads from DB if id/slug provided\n- `save()`: upsert with STI validation, interceptor execution, auto-embeddings. Persisted objects (`isPersisted` — set by DB hydration and successful saves) upsert on `['id']` so natural-key edits (e.g. slug renames) update in place; new objects upsert on the natural-key conflict columns for ingestion-style dedup (#1472)\n- `is(criteria)` / `do(instructions)` / `describe()`: AI operations via function calling. They inject the object's own `toPublicJSON()` (sensitive fields stripped) as a \"content body\" so the model reasons over the instance. Options: `includeData: false` skips injection (for callers that already curate the relevant fields into the instruction); `maxDataLength` overrides the truncation budget. Neither key is forwarded to `ai.message()`. (#1567)\n- `getSlug()`: auto-generates from name → title → label → id\n- `loadRelated(fieldName)`: lazy-loads relationships (cached in `_loadedRelationships` Map)\n\n## SmrtCollection Query\n\n```typescript\nawait collection.list({\n  where: { status: 'active', price: { op: '>', value: 10 } },\n  limit: 50, offset: 0, orderBy: 'created_at DESC'\n});\n```\n\n**WHERE operators**: `=`, `>`, `<`, `>=`, `<=`, `!=`, `in`, `not in`, `like`, `is null`, `is not null`. Arrays auto-detect `IN`. Dot notation for JSON paths: `metadata.userId`.\n\nSTI child collections auto-filter by `_meta_type`.\n\n## @smrt() Decorator Options\n\nKey options: `tableName`, `tableStrategy` ('cti'|'sti'), `conflictColumns`, `api`/`mcp`/`cli` (generation config), `ai` (callable methods), `hooks` (beforeSave/afterSave/beforeDelete/afterDelete), `embeddings` (auto-generate), `tenantScoped`, `agent`.\n\nRegistration sets `SMRT_TABLE_NAME` static property (survives minification).\n\n## Domain Knowledge Artifacts\n\n`smrtPlugin()` writes runtime manifests and agent/developer knowledge artifacts:\n\n- local dev/build: `.smrt/manifest.json` and `.smrt/smrt-knowledge.json`\n- package build: `dist/manifest.json` and `dist/smrt-knowledge.json`\n\nKeep `manifest.json` runtime-focused. `smrt-knowledge.json` is the deterministic\nagent contract for downstream review and architecture tools.\n\nConfig precedence for knowledge is defaults → top-level `knowledge` in\n`smrt.config.ts` → `packages[packageName].knowledge` → plugin option →\nobject-level `@smrt({ knowledge })`.\n\nObject-level `knowledge: false` excludes an object from authored context only;\nit must not change runtime manifest registration. Use\n`knowledge: { tags, summary, risks }` for review-sensitive domain objects.\n\nHTTP knowledge routes are disabled by default. If `knowledge.api.enabled` is\ntrue, generated SvelteKit routes must stay GET-only and guarded by dev mode or\nadmin auth.\n\n## DispatchBus\n\n- `emit(signalType, payload, metadata)` → creates persistent Dispatch record\n- `on(pattern, handler)` → in-memory handler (immediate)\n- `subscribe({ signalType, subscriber })` → persistent subscription (survives restarts)\n- `process(subscriberName, handler)` → process pending dispatches\n- Wildcards: `campaign.*` matches `campaign.completed` (single segment only)\n- Tables: `_smrt_dispatch`, `_smrt_dispatch_subscriptions`\n- Status: `pending → processing → completed` (or `failed`)\n\n## Change Feed (#1758)\n\nAdapter-agnostic change-observation spine (`src/change-feed.ts`) — the server half of the client/mobile sync contract (PRD #1755):\n\n- `_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. 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.\n- 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).\n- `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).\n- `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.\n- 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.\n- 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.\n\n## Live Events / Change Signals (#1763, server half)\n\nThe 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.\n\n- **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`.\n- **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).\n- **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) and SvelteKit (`{routesDir}/_events/+server.ts`, requires an authenticated principal on `locals`; opt out via `sveltekit.eventsRoute.enabled: false`). 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? })` (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`, 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 frame: `id: <seq>\\nevent: change\\ndata: {table,operation,rowId,tenantId}\\n\\n` — seq is ONLY in the `id:` line, never the data JSON. **Same-origin only** (not CORS-wrapped): `EventSource` can't set headers and credentialed cross-origin needs Allow-Credentials the CORS helper doesn't emit — cross-origin SSE is a follow-up. Client disconnect through the Node `createServer` bridge now cancels the response reader (was a teardown leak) so `cancel()` fires and the subscription is released.\n- **Known gaps** (documented in the module): no max-connections cap (bound SSE connections at the edge); 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).\n\n## Single Table Inheritance (STI)\n\n- Base: `@smrt({ tableStrategy: 'sti' })` — children inherit, share one table\n- Discriminator: `_meta_type` column with qualified names (`@happyvertical/smrt-content:Article`)\n- Child fields: `@meta()` decorator → stored in `_meta_data` JSONB (not as columns)\n- Polymorphic queries: collection loads `_meta_type`, creates correct subclass dynamically\n- Validation: fail-fast on save if `_meta_type` missing or mismatched\n\n## Code Generators\n\n| Generator | Location | Output |\n|-----------|----------|--------|\n| REST API | `src/generators/rest.ts` | OpenAPI-compliant CRUD endpoints |\n| CLI | `src/generators/cli.ts` | `objectname:action` admin commands — writable allowlist, exhaustive-include, `--from-file`, fail-closed tenant context |\n| MCP Server | `src/generators/mcp.ts` | Model Context Protocol tools |\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, and a deploy that changes the response shape without a table write leaves ETags unchanged until the next write (deploy-time ETag invalidation via the manifest hash is #1764's domain). Strong consistency 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## Child Accessors (R10)\n\n`src/child-accessors.ts` installs a consistent `get<FieldName>()` instance method for every `@oneToMany` field at `@smrt()` registration time (e.g. `@oneToMany('OrderItem') items` → `order.getItems()`), delegating to `loadRelatedMany`. Two invariants:\n\n- **Additive** — never overwrites a hand-rolled method of the same name (checks the whole prototype chain). `Profile.getMetadata()` (key-value) and `ProfileRelationship.getTerms()` are preserved.\n- **Runtime-only** — attached to the prototype, invisible to the build-time manifest, so it never leaks into the REST/CLI/MCP surface.\n\nWhen the target declares multiple FKs back to the parent, annotate `@oneToMany(Target, { foreignKey: '<inverseField>' })`; `loadRelatedMany` and the eager `include:` loader both honor it (else first-match).\n\n## Vite Plugin\n\n```typescript\n// vite.config.ts — required for @smrt() decorators (Vite 8+, oxc transform)\nexport default defineConfig({\n  oxc: {\n    decorator: {\n      legacy: true,\n      emitDecoratorMetadata: true,\n    },\n  },\n});\n```\n\nUnder Vite 8 the oxc transform does not honor the pre-Vite-8 `esbuild.tsconfigRaw`\nrecipe (or tsconfig `experimentalDecorators` reached through SvelteKit's\n`extends \"./.svelte-kit/tsconfig.json\"` chain), so that recipe throws\n`SyntaxError: Invalid or unexpected token` on the first SSR request. Configure\ndecorators through `oxc.decorator` instead. Consumers still pinned on vite<8 need\nthe legacy `esbuild.tsconfigRaw` form with `experimentalDecorators: true,\nemitDecoratorMetadata: true`.\n\n## Gotchas\n\n- **Never override toJSON()** — handles STI discriminator + meta field extraction. Use `transformJSON()`\n- **Property init order**: TypeScript initializers run first, then `initialize()` applies option values (options win)\n- **No runtime schema creation**: application tables must be prepared explicitly via migrations/tooling; runtime only verifies and fails clearly\n- **Retry logic**: `db.get()` (3 retries, 250ms) and `db.upsert()` (3 retries, 500ms) have built-in retry\n- **Field caching**: `_cachedFields` populated during `Collection.create()` — eliminates async `getFields()` per query\n- **Smart cloning**: arrays/objects shallow-cloned in property init to prevent aliasing (Issue #22)\n- **Table verification cache**: `isTableVerified(dbUrl, tableName)` avoids redundant `tableExists()` calls\n- **Manifest required**: build-time AST scanning creates manifest. Without vitest plugin → \"No field metadata\"\n- **Vite plugin loads scanner from `dist/` first**: `src/vite-plugin/import-build-aware.ts` prefers `dist/` when it exists on disk; it only falls back to `src/` on fresh clones. So if you edit `src/scanner/*.ts` or `src/schema/generator.ts` and want those edits reflected in consumer manifest generation, you must rebuild (`pnpm build` or have `pnpm dev` / `pnpm build:watch` running in core). This is intentional — sniffing `.ts` vs `.js` via `import.meta.url` was non-deterministic under tsx and broke 12–13 publishes (#1139).\n"
+  "agentDoc": "# @happyvertical/smrt-core\n\nORM, code generation, AI integration, and the DispatchBus. Everything else builds on this.\n\n## Key Classes\n\n| Class | File | Purpose |\n|-------|------|---------|\n| SmrtObject | `src/object.ts` | Base persistent object — save, delete, is(), do(), loadFromId/Slug |\n| SmrtCollection | `src/collection.ts` | CRUD collection — list, get, create, delete, getOrUpsert |\n| ObjectRegistry | `src/registry.ts` | Global singleton (globalThis) — class metadata, fields, STI chains, manifests |\n| DispatchBus | `src/dispatch/bus.ts` | Inter-agent messaging — emit, subscribe (persistent), process |\n| GlobalInterceptors | `src/interceptors.ts` | Plugin system — beforeList/Get/Save/Delete hooks (used by tenancy) |\n\n## SmrtObject Lifecycle\n\n`constructor(options)` → `initialize()` → ready for `save()`/`delete()`/`loadFromId()`\n\n- `initialize()`: loads field initializers, applies option values (options override initializers), loads from DB if id/slug provided\n- `save()`: upsert with STI validation, interceptor execution, auto-embeddings. Persisted objects (`isPersisted` — set by DB hydration and successful saves) upsert on `['id']` so natural-key edits (e.g. slug renames) update in place; new objects upsert on the natural-key conflict columns for ingestion-style dedup (#1472)\n- `is(criteria)` / `do(instructions)` / `describe()`: AI operations via function calling. They inject the object's own `toPublicJSON()` (sensitive fields stripped) as a \"content body\" so the model reasons over the instance. Options: `includeData: false` skips injection (for callers that already curate the relevant fields into the instruction); `maxDataLength` overrides the truncation budget. Neither key is forwarded to `ai.message()`. (#1567)\n- `getSlug()`: auto-generates from name → title → label → id\n- `loadRelated(fieldName)`: lazy-loads relationships (cached in `_loadedRelationships` Map)\n\n## SmrtCollection Query\n\n```typescript\nawait collection.list({\n  where: { status: 'active', price: { op: '>', value: 10 } },\n  limit: 50, offset: 0, orderBy: 'created_at DESC'\n});\n```\n\n**WHERE operators**: `=`, `>`, `<`, `>=`, `<=`, `!=`, `in`, `not in`, `like`, `is null`, `is not null`. Arrays auto-detect `IN`. Dot notation for JSON paths: `metadata.userId`.\n\nSTI child collections auto-filter by `_meta_type`.\n\n## @smrt() Decorator Options\n\nKey options: `tableName`, `tableStrategy` ('cti'|'sti'), `conflictColumns`, `api`/`mcp`/`cli` (generation config), `ai` (callable methods), `hooks` (beforeSave/afterSave/beforeDelete/afterDelete), `embeddings` (auto-generate), `tenantScoped`, `agent`.\n\nRegistration sets `SMRT_TABLE_NAME` static property (survives minification).\n\n## Domain Knowledge Artifacts\n\n`smrtPlugin()` writes runtime manifests and agent/developer knowledge artifacts:\n\n- local dev/build: `.smrt/manifest.json` and `.smrt/smrt-knowledge.json`\n- package build: `dist/manifest.json` and `dist/smrt-knowledge.json`\n\nKeep `manifest.json` runtime-focused. `smrt-knowledge.json` is the deterministic\nagent contract for downstream review and architecture tools.\n\nConfig precedence for knowledge is defaults → top-level `knowledge` in\n`smrt.config.ts` → `packages[packageName].knowledge` → plugin option →\nobject-level `@smrt({ knowledge })`.\n\nObject-level `knowledge: false` excludes an object from authored context only;\nit must not change runtime manifest registration. Use\n`knowledge: { tags, summary, risks }` for review-sensitive domain objects.\n\nHTTP knowledge routes are disabled by default. If `knowledge.api.enabled` is\ntrue, generated SvelteKit routes must stay GET-only and guarded by dev mode or\nadmin auth.\n\n## DispatchBus\n\n- `emit(signalType, payload, metadata)` → creates persistent Dispatch record\n- `on(pattern, handler)` → in-memory handler (immediate)\n- `subscribe({ signalType, subscriber })` → persistent subscription (survives restarts)\n- `process(subscriberName, handler)` → process pending dispatches\n- Wildcards: `campaign.*` matches `campaign.completed` (single segment only)\n- Tables: `_smrt_dispatch`, `_smrt_dispatch_subscriptions`\n- Status: `pending → processing → completed` (or `failed`)\n\n## Change Feed (#1758)\n\nAdapter-agnostic change-observation spine (`src/change-feed.ts`) — the server half of the client/mobile sync contract (PRD #1755):\n\n- `_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. 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.\n- 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).\n- `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).\n- `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.\n- 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.\n- 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.\n\n## Live Events / Change Signals (#1763, server half)\n\nThe 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.\n\n- **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`.\n- **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).\n- **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) and SvelteKit (`{routesDir}/_events/+server.ts`, requires an authenticated principal on `locals`; opt out via `sveltekit.eventsRoute.enabled: false`). 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? })` (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`, 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 frame: `id: <seq>\\nevent: change\\ndata: {table,operation,rowId,tenantId}\\n\\n` — seq is ONLY in the `id:` line, never the data JSON. **Same-origin only** (not CORS-wrapped): `EventSource` can't set headers and credentialed cross-origin needs Allow-Credentials the CORS helper doesn't emit — cross-origin SSE is a follow-up. Client disconnect through the Node `createServer` bridge now cancels the response reader (was a teardown leak) so `cancel()` fires and the subscription is released.\n- **Known gaps** (documented in the module): no max-connections cap (bound SSE connections at the edge); 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).\n\n## Single Table Inheritance (STI)\n\n- Base: `@smrt({ tableStrategy: 'sti' })` — children inherit, share one table\n- Discriminator: `_meta_type` column with qualified names (`@happyvertical/smrt-content:Article`)\n- Child fields: `@meta()` decorator → stored in `_meta_data` JSONB (not as columns)\n- Polymorphic queries: collection loads `_meta_type`, creates correct subclass dynamically\n- Validation: fail-fast on save if `_meta_type` missing or mismatched\n\n## Code Generators\n\n| Generator | Location | Output |\n|-----------|----------|--------|\n| REST API | `src/generators/rest.ts` | OpenAPI-compliant CRUD endpoints |\n| CLI | `src/generators/cli.ts` | `objectname:action` admin commands — writable allowlist, exhaustive-include, `--from-file`, fail-closed tenant context |\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 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`).\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, so existing callers/tests are unaffected). 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` reads `APIConfig.manifestHash`, but it is **NOT auto-populated**: a non-SvelteKit runtime-REST deployment that wants the shape-only-deploy guard must pass `manifestHash` (imported from `@happyvertical/smrt-virt-web`) into its `APIConfig` — a deliberate consumer responsibility; left unset, that path's read ETags stay unsalted (equivalent to pre-#1764). 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## Child Accessors (R10)\n\n`src/child-accessors.ts` installs a consistent `get<FieldName>()` instance method for every `@oneToMany` field at `@smrt()` registration time (e.g. `@oneToMany('OrderItem') items` → `order.getItems()`), delegating to `loadRelatedMany`. Two invariants:\n\n- **Additive** — never overwrites a hand-rolled method of the same name (checks the whole prototype chain). `Profile.getMetadata()` (key-value) and `ProfileRelationship.getTerms()` are preserved.\n- **Runtime-only** — attached to the prototype, invisible to the build-time manifest, so it never leaks into the REST/CLI/MCP surface.\n\nWhen the target declares multiple FKs back to the parent, annotate `@oneToMany(Target, { foreignKey: '<inverseField>' })`; `loadRelatedMany` and the eager `include:` loader both honor it (else first-match).\n\n## Vite Plugin\n\n```typescript\n// vite.config.ts — required for @smrt() decorators (Vite 8+, oxc transform)\nexport default defineConfig({\n  oxc: {\n    decorator: {\n      legacy: true,\n      emitDecoratorMetadata: true,\n    },\n  },\n});\n```\n\nUnder Vite 8 the oxc transform does not honor the pre-Vite-8 `esbuild.tsconfigRaw`\nrecipe (or tsconfig `experimentalDecorators` reached through SvelteKit's\n`extends \"./.svelte-kit/tsconfig.json\"` chain), so that recipe throws\n`SyntaxError: Invalid or unexpected token` on the first SSR request. Configure\ndecorators through `oxc.decorator` instead. Consumers still pinned on vite<8 need\nthe legacy `esbuild.tsconfigRaw` form with `experimentalDecorators: true,\nemitDecoratorMetadata: true`.\n\n## Gotchas\n\n- **Never override toJSON()** — handles STI discriminator + meta field extraction. Use `transformJSON()`\n- **Property init order**: TypeScript initializers run first, then `initialize()` applies option values (options win)\n- **No runtime schema creation**: application tables must be prepared explicitly via migrations/tooling; runtime only verifies and fails clearly\n- **Retry logic**: `db.get()` (3 retries, 250ms) and `db.upsert()` (3 retries, 500ms) have built-in retry\n- **Field caching**: `_cachedFields` populated during `Collection.create()` — eliminates async `getFields()` per query\n- **Smart cloning**: arrays/objects shallow-cloned in property init to prevent aliasing (Issue #22)\n- **Table verification cache**: `isTableVerified(dbUrl, tableName)` avoids redundant `tableExists()` calls\n- **Manifest required**: build-time AST scanning creates manifest. Without vitest plugin → \"No field metadata\"\n- **Vite plugin loads scanner from `dist/` first**: `src/vite-plugin/import-build-aware.ts` prefers `dist/` when it exists on disk; it only falls back to `src/` on fresh clones. So if you edit `src/scanner/*.ts` or `src/schema/generator.ts` and want those edits reflected in consumer manifest generation, you must rebuild (`pnpm build` or have `pnpm dev` / `pnpm build:watch` running in core). This is intentional — sniffing `.ts` vs `.js` via `import.meta.url` was non-deterministic under tsx and broke 12–13 publishes (#1139).\n"
 }

package/dist/vite-plugin/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vite-plugin/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EACV,qBAAqB,EAEtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,MAAM,EAAiC,MAAM,MAAM,CAAC;AAIlE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAkB5D,YAAY,EACV,wBAAwB,EACxB,gBAAgB,GACjB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,6BAA6B,EAC7B,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,EACnB,4BAA4B,GAC7B,MAAM,0BAA0B,CAAC;AAalC,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,0BAA0B;IAC1B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,6BAA6B;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qBAAqB;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,kFAAkF;IAClF,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,4EAA4E;IAC5E,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,wEAAwE;IACxE,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;IACpC;;OAEG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,8CAA8C;IAC9C,SAAS,CAAC,EAAE;QACV,yDAAyD;QACzD,OAAO,EAAE,OAAO,CAAC;QACjB,wEAAwE;QACxE,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,qEAAqE;QACrE,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,mEAAmE;QACnE,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,mDAAmD;QACnD,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB;;;;WAIG;QACH,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB;;;WAGG;QACH,YAAY,CAAC,EAAE;YAAE,OAAO,CAAC,EAAE,OAAO,CAAA;SAAE,CAAC;QACrC;;;;WAIG;QACH,WAAW,CAAC,EAAE;YAAE,OAAO,CAAC,EAAE,OAAO,CAAA;SAAE,CAAC;KACrC,CAAC;IACF,mEAAmE;IACnE,SAAS,CAAC,EAAE,qBAAqB,GAAG,KAAK,CAAC;IAC1C;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AA+BD,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAG1D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,mBAAmB,GAC5B,MAAM,CAaR;AAED,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,MAAM,CAu5BlE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vite-plugin/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EACV,qBAAqB,EAEtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,MAAM,EAAiC,MAAM,MAAM,CAAC;AAIlE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAmB5D,YAAY,EACV,wBAAwB,EACxB,gBAAgB,GACjB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,6BAA6B,EAC7B,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,EACnB,4BAA4B,GAC7B,MAAM,0BAA0B,CAAC;AAalC,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,0BAA0B;IAC1B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,6BAA6B;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qBAAqB;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,kFAAkF;IAClF,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,4EAA4E;IAC5E,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,wEAAwE;IACxE,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;IACpC;;OAEG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,8CAA8C;IAC9C,SAAS,CAAC,EAAE;QACV,yDAAyD;QACzD,OAAO,EAAE,OAAO,CAAC;QACjB,wEAAwE;QACxE,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,qEAAqE;QACrE,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,mEAAmE;QACnE,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,mDAAmD;QACnD,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB;;;;WAIG;QACH,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB;;;WAGG;QACH,YAAY,CAAC,EAAE;YAAE,OAAO,CAAC,EAAE,OAAO,CAAA;SAAE,CAAC;QACrC;;;;WAIG;QACH,WAAW,CAAC,EAAE;YAAE,OAAO,CAAC,EAAE,OAAO,CAAA;SAAE,CAAC;KACrC,CAAC;IACF,mEAAmE;IACnE,SAAS,CAAC,EAAE,qBAAqB,GAAG,KAAK,CAAC;IAC1C;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AA+BD,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAG1D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,mBAAmB,GAC5B,MAAM,CAaR;AAED,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,MAAM,CAu5BlE"}

package/dist/vite-plugin/index.js

@@ -3,8 +3,8 @@ import { importWorkspaceModule } from "../utils/import-workspace-module.js";
 import { discoverSmrtPackages } from "../manifest/discover-smrt-packages.js";
 import { CLIENT_FETCH_RUNTIME } from "../generated-client-runtime.js";
 import { importBuildAwareModule } from "./import-build-aware.js";
+import { buildWebCollectionDefinition, buildWebToolDescriptors, computeWebManifestHash, selectWebCollectionEntries } from "./web-collections.js";
 import { findCliApiCoherenceViolations, generateSvelteKitRoutes, methodNameToKebab, resolveApiActionSet, validateCliIncludeAgainstApi } from "./sveltekit-generator.js";
-import { buildWebFieldDefinitions, buildWebRelationships, selectWebCollectionEntries } from "./web-collections.js";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -688,28 +688,29 @@ export { createClient as default };
 * API-exposed model in the manifest. This is the codegen contract consumed by
 * `@happyvertical/smrt-web` to construct client collections over the generated
 * REST surface. Deliberately data-only: no fetch code is emitted here, so the
-* runtime wrapper owns all HTTP/error semantics in one place. Selection and
-* field rules live in {@link selectWebCollectionEntries} /
-* {@link buildWebFieldDefinitions} so this value emission and the matching
-* d.ts type emission cannot drift.
+* runtime wrapper owns all HTTP/error semantics in one place. Selection and the
+* per-collection shape live in {@link selectWebCollectionEntries} /
+* {@link buildWebCollectionDefinition} so this value emission, the matching d.ts
+* type emission, and the #1764 shape digest cannot drift.
 */
 function generateWebModule(manifest) {
 	const definitions = {};
-	for (const { collection, obj, actions } of selectWebCollectionEntries(manifest)) definitions[collection] = {
-		name: collection,
-		className: obj.className,
-		endpoint: `/${collection}`,
-		idField: "id",
-		actions,
-		fields: buildWebFieldDefinitions(obj),
-		relationships: buildWebRelationships(obj, manifest)
+	for (const entry of selectWebCollectionEntries(manifest)) definitions[entry.collection] = {
+		...buildWebCollectionDefinition(entry, manifest),
+		toolDescriptors: buildWebToolDescriptors(entry)
 	};
+	const manifestHash = computeWebManifestHash(manifest);
 	return `
 // Auto-generated web collection definitions from SMRT objects (#1761)
 // This file is generated automatically - do not edit
 
 export const collectionDefinitions = ${JSON.stringify(definitions, null, 2)};
 
+// Build-time inject of the web-collection shape digest (#1764) — see
+// computeWebManifestHash. A change here means old persisted client rows may
+// mis-hydrate, so persistence namespaces and read ETags key on it.
+export const manifestHash = ${JSON.stringify(manifestHash)};
+
 export function getCollectionDefinition(name) {
   const definition = collectionDefinitions[name];
   if (!definition) {
@@ -1086,6 +1087,15 @@ declare module '@happyvertical/smrt-virt-web' {
     relatedCollection: string;
   }
 
+  /** A WebMCP/MCP tool descriptor for one collection action (#1812). */
+  export interface WebToolDescriptor {
+    action: string;
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    readOnly: boolean;
+  }
+
   export interface SmrtWebCollectionDefinition<TData = Record<string, unknown>> {
     name: string;
     className: string;
@@ -1095,6 +1105,8 @@ declare module '@happyvertical/smrt-virt-web' {
     fields: Record<string, SmrtWebFieldDefinition>;
     /** Manifest-derived relationship edges to sibling REST collections. */
     relationships: SmrtWebRelationship[];
+    /** WebMCP/MCP tool descriptors for the exposed actions (#1812). */
+    toolDescriptors: WebToolDescriptor[];
     /** Phantom row-type carrier for inference — never present at runtime. */
     _row?: TData;
   }
@@ -1107,6 +1119,15 @@ ${webCollectionInterface}
   export function getCollectionDefinition<
     K extends keyof SmrtWebCollectionDefinitions,
   >(name: K): SmrtWebCollectionDefinitions[K];
+  /**
+   * Build-time web-collection shape digest (#1764). A deterministic,
+   * replica-stable hash of the emitted collection definitions; a change means
+   * old persisted client rows may mis-hydrate. Consumers fold it into the
+   * durable persistence namespace and the version-awareness updateAvailable
+   * contract signal. One of three emission sites that must not drift — the
+   * runtime value, this ambient d.ts, and the physical @smrt/web d.ts.
+   */
+  export const manifestHash: string;
   export default collectionDefinitions;
 }