@happyvertical/smrt-core 0.37.8 → 0.37.10

package/dist/vite-plugin/sync-apply-route.js.map

@@ -1 +1 @@
-{"version":3,"file":"sync-apply-route.js","names":[],"sources":["../../src/vite-plugin/sync-apply-route.ts"],"sourcesContent":["/**\n * SvelteKit generator for the sync-apply batch write route (#1759).\n *\n * Emits ONE route — `{routesDir}/sync/apply/+server.ts` — implementing the\n * shared web/mobile write contract for every syncable model in the manifest\n * (models whose API config exposes at least one of create/update/delete). The\n * generated file is deliberately thin: it maps `object` segments to\n * collections plus per-model policy data, and delegates all batch processing\n * to `processSyncApplyBatch` from `@happyvertical/smrt-core` — the same\n * engine the runtime REST generator uses, so the two transports cannot drift.\n *\n * This lives in its own module (rather than sveltekit-generator.ts) so the\n * shared generator file only needs a one-line registration hook; sibling\n * work (#1757, #1758) touches the same generator files in parallel.\n *\n * Contract documentation: docs/content/architecture/sync-apply-contract.md\n */\n\nimport { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';\nimport { join } from 'node:path';\nimport type { ApiConfig } from '../registry/types.js';\nimport type {\n  SmartObjectDefinition,\n  SmartObjectManifest,\n} from '../scanner/types';\nimport type { SvelteKitOptions } from './sveltekit-generator.js';\n\nconst AUTO_GENERATED_ROUTE_HEADER =\n  '// Auto-generated by @smrt/core vite plugin';\n\nconst MUTATING_ACTIONS = ['create', 'update', 'delete'] as const;\n\ntype MutatingAction = (typeof MUTATING_ACTIONS)[number];\n\n/** Per-model data embedded into the generated route. */\ninterface SyncTargetSpec {\n  segment: string;\n  /**\n   * The manifest registry key, passed VERBATIM to `getCollection()` exactly\n   * as the generated CRUD routes do. May be package-qualified\n   * (`@happyvertical/smrt-ledgers:Account`) — collapsing it to a simple class\n   * name would resolve ambiguously when two loaded packages declare the same\n   * simple name.\n   */\n  registryKey: string;\n  ops: MutatingAction[];\n  readonlyFields: string[];\n  writableAllowlist: string[] | null;\n  publicAccess: boolean | 'read';\n  tenantScoped: boolean;\n}\n\nfunction getApiConfigObject(apiConfig: unknown): ApiConfig | null {\n  if (!apiConfig || typeof apiConfig !== 'object') {\n    return null;\n  }\n  return apiConfig as ApiConfig;\n}\n\n/**\n * Mirror of sveltekit-generator.ts `resolveStandardCrudActions`, narrowed to\n * the mutating subset the sync contract can carry. Kept local so this module\n * needs no exports added to the (parallel-edited) shared generator file.\n */\nfunction resolveMutatingActions(apiConfig: unknown): MutatingAction[] {\n  if (apiConfig === false) return [];\n  if (\n    apiConfig === true ||\n    apiConfig === undefined ||\n    typeof apiConfig !== 'object'\n  ) {\n    return [...MUTATING_ACTIONS];\n  }\n\n  const config = apiConfig as { include?: string[]; exclude?: string[] };\n  let actions: MutatingAction[] = Array.isArray(config.include)\n    ? MUTATING_ACTIONS.filter((action) => config.include?.includes(action))\n    : [...MUTATING_ACTIONS];\n  if (Array.isArray(config.exclude)) {\n    const excluded = config.exclude;\n    actions = actions.filter((action) => !excluded.includes(action));\n  }\n  return actions;\n}\n\n/** Mirror of sveltekit-generator.ts `getApiPublicAccess` (fail-closed). */\nfunction getApiPublicAccess(apiConfig: unknown): boolean | 'read' {\n  const config = getApiConfigObject(apiConfig);\n  const value = config?.public;\n  if (value === true || value === 'read') {\n    return value;\n  }\n  return false;\n}\n\n/** Mirror of sveltekit-generator.ts `collectReadonlyFieldNames` (#1540, 2b). */\nfunction collectReadonlyFieldNames(objectDef: SmartObjectDefinition): string[] {\n  const fields = objectDef.fields || {};\n  const names: string[] = [];\n  for (const [name, def] of Object.entries(fields)) {\n    const meta = (def as { _meta?: Record<string, unknown> })._meta;\n    if (\n      (def as { readonly?: boolean }).readonly === true ||\n      meta?.readonly === true\n    ) {\n      names.push(name);\n    }\n  }\n  return names;\n}\n\n/** Mirror of sveltekit-generator.ts `getApiWritableAllowlist`. */\nfunction getApiWritableAllowlist(apiConfig: unknown): string[] | null {\n  const config = getApiConfigObject(apiConfig);\n  return Array.isArray(config?.writable) ? config.writable : null;\n}\n\n/** Mirror of sveltekit-generator.ts `isCollectionClass`. */\nfunction isCollectionClass(objectDef: SmartObjectDefinition): boolean {\n  return objectDef.extends === 'SmrtCollection' || !!objectDef.extendsTypeArg;\n}\n\n/**\n * Collect the syncable targets from a manifest: non-collection objects whose\n * API config is enabled and exposes at least one mutating action.\n */\nexport function collectSyncApplyTargets(\n  manifest: SmartObjectManifest,\n): SyncTargetSpec[] {\n  const targets: SyncTargetSpec[] = [];\n\n  for (const [className, objectDef] of Object.entries(manifest.objects)) {\n    if (isCollectionClass(objectDef)) continue;\n\n    const apiConfig = objectDef.decoratorConfig?.api;\n    if (apiConfig === false) continue;\n\n    const ops = resolveMutatingActions(apiConfig);\n    if (ops.length === 0) continue;\n\n    if (!objectDef.collection) continue;\n\n    targets.push({\n      segment: objectDef.collection,\n      registryKey: className,\n      ops,\n      readonlyFields: collectReadonlyFieldNames(objectDef),\n      writableAllowlist: getApiWritableAllowlist(apiConfig),\n      publicAccess: getApiPublicAccess(apiConfig),\n      tenantScoped: !!objectDef.decoratorConfig?.tenantScoped,\n    });\n  }\n\n  return targets.sort((a, b) => a.segment.localeCompare(b.segment));\n}\n\nfunction serializeTargets(targets: SyncTargetSpec[]): string {\n  const entries = targets.map((target) => {\n    const fields = [\n      `registryKey: ${JSON.stringify(target.registryKey)}`,\n      `ops: ${JSON.stringify(target.ops)}`,\n      `readonlyFields: ${JSON.stringify(target.readonlyFields)}`,\n      `writableAllowlist: ${JSON.stringify(target.writableAllowlist)}`,\n      `publicAccess: ${JSON.stringify(target.publicAccess)}`,\n    ];\n    return `  ${JSON.stringify(target.segment)}: {\\n    ${fields.join(',\\n    ')},\\n  },`;\n  });\n  return `{\\n${entries.join('\\n')}\\n}`;\n}\n\n/**\n * Render the generated `+server.ts` content for the sync-apply route.\n * Exported for tests.\n */\nexport function generateSyncApplyRouteTemplate(\n  targets: SyncTargetSpec[],\n): string {\n  const anyTenantScoped = targets.some((target) => target.tenantScoped);\n\n  const tenantHelper = anyTenantScoped\n    ? `\nimport { enterTenantContext, hasTenantContext } from '@happyvertical/smrt-tenancy';\n\nfunction establishTenantContext(locals: unknown): void {\n  if (hasTenantContext()) return;\n  if (!locals || typeof locals !== 'object') return;\n  const l = locals as Record<string, unknown>;\n  const user = l.user as Record<string, unknown> | undefined;\n  const session = l.session as Record<string, unknown> | undefined;\n  const tenantId = l.tenantId ?? user?.tenantId ?? session?.tenantId;\n  if (typeof tenantId === 'string' && tenantId) {\n    enterTenantContext({ tenantId });\n  }\n}\n`\n    : '';\n\n  return `${AUTO_GENERATED_ROUTE_HEADER}\n// DO NOT EDIT - changes will be overwritten\n//\n// Idempotent sync-apply batch write contract (#1759) — the shared write path\n// for the web offline outbox (#1762) and the KMP mobile write queue (#1739).\n// Contract: docs/content/architecture/sync-apply-contract.md\n\nimport {\n  applySyncWritablePolicy,\n  processSyncApplyBatch,\n  type SyncApplyOp,\n  type SyncApplyTarget,\n} from '@happyvertical/smrt-core';\nimport { json } from '@sveltejs/kit';\nimport { getCollection } from '$lib/server/smrt';\nimport type { RequestHandler } from './$types';\n${tenantHelper}\ninterface SyncTargetConfig {\n  /** Manifest registry key (may be package-qualified), as CRUD routes use. */\n  registryKey: string;\n  ops: SyncApplyOp[];\n  readonlyFields: string[];\n  writableAllowlist: string[] | null;\n  publicAccess: boolean | 'read';\n}\n\n// One entry per syncable model, keyed by the collection route segment its\n// generated CRUD routes use.\nconst SYNC_TARGETS: Record<string, SyncTargetConfig> = ${serializeTargets(targets)};\n\n// Fail-closed authorization (#1540): sync mutations require an authenticated\n// principal on \\`locals\\` unless the target model is \\`api: { public: true }\\`.\nfunction hasAuthenticatedPrincipal(locals: unknown): boolean {\n  if (!locals || typeof locals !== 'object') return false;\n  const l = locals as Record<string, unknown>;\n  const isResolvedPrincipal = (v: unknown) =>\n    typeof v === 'object' && v !== null;\n  return (\n    isResolvedPrincipal(l.user) ||\n    isResolvedPrincipal(l.session) ||\n    l.smrtAuth === true\n  );\n}\n\nexport const POST: RequestHandler = async ({ locals, request }) => {\n  const authenticated = hasAuthenticatedPrincipal(locals);\n${anyTenantScoped ? '  establishTenantContext(locals);\\n' : ''}\n  let body: unknown;\n  try {\n    body = await request.json();\n  } catch {\n    return json(\n      { error: { code: 'invalid_batch', message: 'Invalid JSON body' } },\n      { status: 400 },\n    );\n  }\n\n  const outcome = await processSyncApplyBatch(body, {\n    resolveTarget: async (segment: string): Promise<SyncApplyTarget | null> => {\n      const target = SYNC_TARGETS[segment];\n      if (!target) return null;\n      // The verbatim manifest key, exactly as the generated CRUD routes pass\n      // it — package-qualified keys stay qualified so same-simple-name\n      // classes across packages resolve unambiguously.\n      const collection = await getCollection(target.registryKey);\n      return {\n        objectName: target.registryKey,\n        collection,\n        isOpAllowed: (op: SyncApplyOp) => target.ops.includes(op),\n        authorize: () =>\n          authenticated || target.publicAccess === true\n            ? ('ok' as const)\n            : ('auth_required' as const),\n        prepare: (payload: Record<string, unknown>) =>\n          applySyncWritablePolicy(payload, {\n            readonlyFields: target.readonlyFields,\n            writableAllowlist: target.writableAllowlist,\n          }),\n      };\n    },\n  });\n\n  return json(outcome.body, { status: outcome.status });\n};\n`;\n}\n\n/**\n * Generate `{routesDir}/sync/apply/+server.ts` for the manifest's syncable\n * models. Returns true when a route was written. Skips generation (with a\n * warning) if a non-generated file already occupies the path, and writes\n * nothing when the manifest has no syncable models.\n */\nexport function generateSyncApplyRoute(\n  projectRoot: string,\n  manifest: SmartObjectManifest,\n  options: SvelteKitOptions,\n): boolean {\n  const targets = collectSyncApplyTargets(manifest);\n  if (targets.length === 0) {\n    return false;\n  }\n\n  const routeDir = join(projectRoot, options.routesDir, 'sync', 'apply');\n  const routePath = join(routeDir, '+server.ts');\n\n  if (existsSync(routePath)) {\n    const existing = readFileSync(routePath, 'utf-8');\n    if (!existing.startsWith(AUTO_GENERATED_ROUTE_HEADER)) {\n      console.warn(\n        `[smrt] Skipping sync-apply route - ${routePath} exists and is not generated`,\n      );\n      return false;\n    }\n  }\n\n  if (!existsSync(routeDir)) {\n    mkdirSync(routeDir, { recursive: true });\n  }\n\n  writeFileSync(routePath, generateSyncApplyRouteTemplate(targets), 'utf-8');\n  console.log(`[smrt] Generated: ${routePath}`);\n  return true;\n}\n"],"mappings":"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"}
+{"version":3,"file":"sync-apply-route.js","names":[],"sources":["../../src/vite-plugin/sync-apply-route.ts"],"sourcesContent":["/**\n * SvelteKit generator for the sync-apply batch write route (#1759).\n *\n * Emits ONE route — `{routesDir}/sync/apply/+server.ts` — implementing the\n * shared web/mobile write contract for every syncable model in the manifest\n * (models whose API config exposes at least one of create/update/delete). The\n * generated file is deliberately thin: it maps `object` segments to\n * collections plus per-model policy data, and delegates all batch processing\n * to `processSyncApplyBatch` from `@happyvertical/smrt-core` — the same\n * engine the runtime REST generator uses, so the two transports cannot drift.\n *\n * This lives in its own module (rather than sveltekit-generator.ts) so the\n * shared generator file only needs a one-line registration hook; sibling\n * work (#1757, #1758) touches the same generator files in parallel.\n *\n * Contract documentation: docs/content/architecture/sync-apply-contract.md\n */\n\nimport { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';\nimport { join } from 'node:path';\nimport type { ApiConfig } from '../registry/types.js';\nimport type {\n  SmartObjectDefinition,\n  SmartObjectManifest,\n} from '../scanner/types';\nimport { AUTO_GENERATED_ROUTE_HEADER } from './route-header.js';\nimport type { SvelteKitOptions } from './sveltekit-generator.js';\n\nconst MUTATING_ACTIONS = ['create', 'update', 'delete'] as const;\n\ntype MutatingAction = (typeof MUTATING_ACTIONS)[number];\n\n/** Per-model data embedded into the generated route. */\ninterface SyncTargetSpec {\n  segment: string;\n  /**\n   * The manifest registry key, passed VERBATIM to `getCollection()` exactly\n   * as the generated CRUD routes do. May be package-qualified\n   * (`@happyvertical/smrt-ledgers:Account`) — collapsing it to a simple class\n   * name would resolve ambiguously when two loaded packages declare the same\n   * simple name.\n   */\n  registryKey: string;\n  ops: MutatingAction[];\n  readonlyFields: string[];\n  writableAllowlist: string[] | null;\n  publicAccess: boolean | 'read';\n  tenantScoped: boolean;\n}\n\nfunction getApiConfigObject(apiConfig: unknown): ApiConfig | null {\n  if (!apiConfig || typeof apiConfig !== 'object') {\n    return null;\n  }\n  return apiConfig as ApiConfig;\n}\n\n/**\n * Mirror of sveltekit-generator.ts `resolveStandardCrudActions`, narrowed to\n * the mutating subset the sync contract can carry. Kept local so this module\n * needs no exports added to the (parallel-edited) shared generator file.\n */\nfunction resolveMutatingActions(apiConfig: unknown): MutatingAction[] {\n  if (apiConfig === false) return [];\n  if (\n    apiConfig === true ||\n    apiConfig === undefined ||\n    typeof apiConfig !== 'object'\n  ) {\n    return [...MUTATING_ACTIONS];\n  }\n\n  const config = apiConfig as { include?: string[]; exclude?: string[] };\n  let actions: MutatingAction[] = Array.isArray(config.include)\n    ? MUTATING_ACTIONS.filter((action) => config.include?.includes(action))\n    : [...MUTATING_ACTIONS];\n  if (Array.isArray(config.exclude)) {\n    const excluded = config.exclude;\n    actions = actions.filter((action) => !excluded.includes(action));\n  }\n  return actions;\n}\n\n/** Mirror of sveltekit-generator.ts `getApiPublicAccess` (fail-closed). */\nfunction getApiPublicAccess(apiConfig: unknown): boolean | 'read' {\n  const config = getApiConfigObject(apiConfig);\n  const value = config?.public;\n  if (value === true || value === 'read') {\n    return value;\n  }\n  return false;\n}\n\n/** Mirror of sveltekit-generator.ts `collectReadonlyFieldNames` (#1540, 2b). */\nfunction collectReadonlyFieldNames(objectDef: SmartObjectDefinition): string[] {\n  const fields = objectDef.fields || {};\n  const names: string[] = [];\n  for (const [name, def] of Object.entries(fields)) {\n    const meta = (def as { _meta?: Record<string, unknown> })._meta;\n    if (\n      (def as { readonly?: boolean }).readonly === true ||\n      meta?.readonly === true\n    ) {\n      names.push(name);\n    }\n  }\n  return names;\n}\n\n/** Mirror of sveltekit-generator.ts `getApiWritableAllowlist`. */\nfunction getApiWritableAllowlist(apiConfig: unknown): string[] | null {\n  const config = getApiConfigObject(apiConfig);\n  return Array.isArray(config?.writable) ? config.writable : null;\n}\n\n/** Mirror of sveltekit-generator.ts `isCollectionClass`. */\nfunction isCollectionClass(objectDef: SmartObjectDefinition): boolean {\n  return objectDef.extends === 'SmrtCollection' || !!objectDef.extendsTypeArg;\n}\n\n/**\n * Collect the syncable targets from a manifest: non-collection objects whose\n * API config is enabled and exposes at least one mutating action.\n */\nexport function collectSyncApplyTargets(\n  manifest: SmartObjectManifest,\n): SyncTargetSpec[] {\n  const targets: SyncTargetSpec[] = [];\n\n  for (const [className, objectDef] of Object.entries(manifest.objects)) {\n    if (isCollectionClass(objectDef)) continue;\n\n    const apiConfig = objectDef.decoratorConfig?.api;\n    if (apiConfig === false) continue;\n\n    const ops = resolveMutatingActions(apiConfig);\n    if (ops.length === 0) continue;\n\n    if (!objectDef.collection) continue;\n\n    targets.push({\n      segment: objectDef.collection,\n      registryKey: className,\n      ops,\n      readonlyFields: collectReadonlyFieldNames(objectDef),\n      writableAllowlist: getApiWritableAllowlist(apiConfig),\n      publicAccess: getApiPublicAccess(apiConfig),\n      tenantScoped: !!objectDef.decoratorConfig?.tenantScoped,\n    });\n  }\n\n  return targets.sort((a, b) => a.segment.localeCompare(b.segment));\n}\n\nfunction serializeTargets(targets: SyncTargetSpec[]): string {\n  const entries = targets.map((target) => {\n    const fields = [\n      `registryKey: ${JSON.stringify(target.registryKey)}`,\n      `ops: ${JSON.stringify(target.ops)}`,\n      `readonlyFields: ${JSON.stringify(target.readonlyFields)}`,\n      `writableAllowlist: ${JSON.stringify(target.writableAllowlist)}`,\n      `publicAccess: ${JSON.stringify(target.publicAccess)}`,\n    ];\n    return `  ${JSON.stringify(target.segment)}: {\\n    ${fields.join(',\\n    ')},\\n  },`;\n  });\n  return `{\\n${entries.join('\\n')}\\n}`;\n}\n\n/**\n * Render the generated `+server.ts` content for the sync-apply route.\n * Exported for tests.\n */\nexport function generateSyncApplyRouteTemplate(\n  targets: SyncTargetSpec[],\n): string {\n  const anyTenantScoped = targets.some((target) => target.tenantScoped);\n\n  const tenantHelper = anyTenantScoped\n    ? `\nimport { enterTenantContext, hasTenantContext } from '@happyvertical/smrt-tenancy';\n\nfunction establishTenantContext(locals: unknown): void {\n  if (hasTenantContext()) return;\n  if (!locals || typeof locals !== 'object') return;\n  const l = locals as Record<string, unknown>;\n  const user = l.user as Record<string, unknown> | undefined;\n  const session = l.session as Record<string, unknown> | undefined;\n  const tenantId = l.tenantId ?? user?.tenantId ?? session?.tenantId;\n  if (typeof tenantId === 'string' && tenantId) {\n    enterTenantContext({ tenantId });\n  }\n}\n`\n    : '';\n\n  return `${AUTO_GENERATED_ROUTE_HEADER}\n// DO NOT EDIT - changes will be overwritten\n//\n// Idempotent sync-apply batch write contract (#1759) — the shared write path\n// for the web offline outbox (#1762) and the KMP mobile write queue (#1739).\n// Contract: docs/content/architecture/sync-apply-contract.md\n\nimport {\n  applySyncWritablePolicy,\n  processSyncApplyBatch,\n  type SyncApplyOp,\n  type SyncApplyTarget,\n} from '@happyvertical/smrt-core';\nimport { json } from '@sveltejs/kit';\nimport { getCollection } from '$lib/server/smrt';\nimport type { RequestHandler } from './$types';\n${tenantHelper}\ninterface SyncTargetConfig {\n  /** Manifest registry key (may be package-qualified), as CRUD routes use. */\n  registryKey: string;\n  ops: SyncApplyOp[];\n  readonlyFields: string[];\n  writableAllowlist: string[] | null;\n  publicAccess: boolean | 'read';\n}\n\n// One entry per syncable model, keyed by the collection route segment its\n// generated CRUD routes use.\nconst SYNC_TARGETS: Record<string, SyncTargetConfig> = ${serializeTargets(targets)};\n\n// Fail-closed authorization (#1540): sync mutations require an authenticated\n// principal on \\`locals\\` unless the target model is \\`api: { public: true }\\`.\nfunction hasAuthenticatedPrincipal(locals: unknown): boolean {\n  if (!locals || typeof locals !== 'object') return false;\n  const l = locals as Record<string, unknown>;\n  const isResolvedPrincipal = (v: unknown) =>\n    typeof v === 'object' && v !== null;\n  return (\n    isResolvedPrincipal(l.user) ||\n    isResolvedPrincipal(l.session) ||\n    l.smrtAuth === true\n  );\n}\n\nexport const POST: RequestHandler = async ({ locals, request }) => {\n  const authenticated = hasAuthenticatedPrincipal(locals);\n${anyTenantScoped ? '  establishTenantContext(locals);\\n' : ''}\n  let body: unknown;\n  try {\n    body = await request.json();\n  } catch {\n    return json(\n      { error: { code: 'invalid_batch', message: 'Invalid JSON body' } },\n      { status: 400 },\n    );\n  }\n\n  const outcome = await processSyncApplyBatch(body, {\n    resolveTarget: async (segment: string): Promise<SyncApplyTarget | null> => {\n      const target = SYNC_TARGETS[segment];\n      if (!target) return null;\n      // The verbatim manifest key, exactly as the generated CRUD routes pass\n      // it — package-qualified keys stay qualified so same-simple-name\n      // classes across packages resolve unambiguously.\n      const collection = await getCollection(target.registryKey);\n      return {\n        objectName: target.registryKey,\n        collection,\n        isOpAllowed: (op: SyncApplyOp) => target.ops.includes(op),\n        authorize: () =>\n          authenticated || target.publicAccess === true\n            ? ('ok' as const)\n            : ('auth_required' as const),\n        prepare: (payload: Record<string, unknown>) =>\n          applySyncWritablePolicy(payload, {\n            readonlyFields: target.readonlyFields,\n            writableAllowlist: target.writableAllowlist,\n          }),\n      };\n    },\n  });\n\n  return json(outcome.body, { status: outcome.status });\n};\n`;\n}\n\n/**\n * Generate `{routesDir}/sync/apply/+server.ts` for the manifest's syncable\n * models. Returns true when a route was written. Skips generation (with a\n * warning) if a non-generated file already occupies the path, and writes\n * nothing when the manifest has no syncable models.\n */\nexport function generateSyncApplyRoute(\n  projectRoot: string,\n  manifest: SmartObjectManifest,\n  options: SvelteKitOptions,\n): boolean {\n  const targets = collectSyncApplyTargets(manifest);\n  if (targets.length === 0) {\n    return false;\n  }\n\n  const routeDir = join(projectRoot, options.routesDir, 'sync', 'apply');\n  const routePath = join(routeDir, '+server.ts');\n\n  if (existsSync(routePath)) {\n    const existing = readFileSync(routePath, 'utf-8');\n    if (!existing.startsWith(AUTO_GENERATED_ROUTE_HEADER)) {\n      console.warn(\n        `[smrt] Skipping sync-apply route - ${routePath} exists and is not generated`,\n      );\n      return false;\n    }\n  }\n\n  if (!existsSync(routeDir)) {\n    mkdirSync(routeDir, { recursive: true });\n  }\n\n  writeFileSync(routePath, generateSyncApplyRouteTemplate(targets), 'utf-8');\n  console.log(`[smrt] Generated: ${routePath}`);\n  return true;\n}\n"],"mappings":"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"}

package/dist/vite-plugin/web-collections.d.ts

@@ -0,0 +1,73 @@
+import { FieldDefinition, SmartObjectDefinition, SmartObjectManifest } from '../scanner/types.js';
+/** Informational per-column metadata carried by a collection definition. */
+export interface WebFieldDefinition {
+    type: FieldDefinition['type'];
+    required?: boolean;
+    default?: unknown;
+}
+/** The relationship kinds a web collection edge can describe. */
+export type WebRelationshipKind = 'foreignKey' | 'crossPackageRef' | 'oneToMany' | 'manyToMany';
+/**
+ * One manifest-derived relationship edge from a collection to a sibling REST
+ * collection. Consumed by the browser client-data runtime to invalidate
+ * dependent collection caches when this collection is mutated (#1761) — the
+ * cache-invalidation graph is derived entirely from these edges, never
+ * hand-wired. SMRT-owned data: no client-engine type appears here.
+ */
+export interface WebRelationship {
+    /** The declaring field carrying the relationship (e.g. `groupId`, `items`). */
+    field: string;
+    /** The relationship kind, mirroring the manifest field type. */
+    kind: WebRelationshipKind;
+    /** REST collection name the edge resolves to (e.g. `ad_groups`). */
+    relatedCollection: string;
+}
+/** One selected REST collection and the model that owns its definition. */
+export interface WebCollectionEntry {
+    /** REST collection name (pluralized), e.g. `products`. */
+    collection: string;
+    /** The manifest object that owns this collection's definition. */
+    obj: SmartObjectDefinition;
+    /** Sorted set of exposed CRUD + custom actions. */
+    actions: string[];
+}
+/**
+ * Select the manifest entries that become web collection definitions: one per
+ * REST collection, STI children folding into their base model, collection
+ * classes excluded, and only models that expose `list` (a read surface is
+ * required to materialize a collection). Uses the canonical
+ * {@link resolveApiActionSet} so the exposed-action set matches exactly what
+ * the REST/SvelteKit generators actually emit.
+ */
+export declare function selectWebCollectionEntries(manifest: SmartObjectManifest): WebCollectionEntry[];
+/**
+ * Build the informational per-field metadata for a web collection definition:
+ * the persisted public-DTO columns only. Relationship pseudo-fields, STI meta
+ * internals, transient (unpersisted) and sensitive (wire-stripped) fields are
+ * excluded — they are not columns a client reads back over the REST surface.
+ */
+export declare function buildWebFieldDefinitions(obj: SmartObjectDefinition): Record<string, WebFieldDefinition>;
+/**
+ * Build the manifest-derived relationship edges for a web collection
+ * definition (#1761): one entry per relationship field (`foreignKey`,
+ * `crossPackageRef`, `oneToMany`, `manyToMany`) whose `related` target resolves
+ * to another API-exposed REST collection.
+ *
+ * These edges drive relationship-derived cache invalidation in the browser
+ * client-data runtime: mutating this collection invalidates the caches of the
+ * collections named here. The invalidation graph is thus derived entirely from
+ * the manifest — no hand-wired cache keys.
+ *
+ * An edge is SKIPPED (not emitted) when:
+ *  - `related` is missing, or
+ *  - `related` cannot be resolved to a manifest object (e.g. a cross-package
+ *    target not present in this package's manifest), or
+ *  - the resolved target is not itself an API-exposed web collection (no read
+ *    surface to invalidate — it never appears in {@link selectWebCollectionEntries}).
+ *
+ * Self-referential edges (a collection related to itself) are kept: the runtime
+ * always invalidates the mutated collection anyway, so a self edge is harmless
+ * and keeping it avoids a special case.
+ */
+export declare function buildWebRelationships(obj: SmartObjectDefinition, manifest: SmartObjectManifest): WebRelationship[];
+//# sourceMappingURL=web-collections.d.ts.map

package/dist/vite-plugin/web-collections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-collections.d.ts","sourceRoot":"","sources":["../../src/vite-plugin/web-collections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACpB,MAAM,qBAAqB,CAAC;AAyB7B,4EAA4E;AAC5E,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IAC9B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,iEAAiE;AACjE,MAAM,MAAM,mBAAmB,GAC3B,YAAY,GACZ,iBAAiB,GACjB,WAAW,GACX,YAAY,CAAC;AAEjB;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,IAAI,EAAE,mBAAmB,CAAC;IAC1B,oEAAoE;IACpE,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,GAAG,EAAE,qBAAqB,CAAC;IAC3B,mDAAmD;IACnD,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAiFD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,mBAAmB,GAC5B,kBAAkB,EAAE,CAgCtB;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,qBAAqB,GACzB,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAcpC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,qBAAqB,EAC1B,QAAQ,EAAE,mBAAmB,GAC5B,eAAe,EAAE,CAiCnB"}

package/dist/vite-plugin/web-collections.js

@@ -0,0 +1,174 @@
+import { resolveApiActionSet } from "./sveltekit-generator.js";
+//#region src/vite-plugin/web-collections.ts
+/**
+* Field types that are relationship pseudo-columns rather than persisted
+* public-DTO columns — they never appear on the wire as scalar values.
+*/
+var RELATIONSHIP_FIELD_TYPES = /* @__PURE__ */ new Set(["oneToMany", "manyToMany"]);
+/**
+* Field types that describe a relationship to another model. A superset of
+* {@link RELATIONSHIP_FIELD_TYPES}: `foreignKey`/`crossPackageRef` are persisted
+* scalar id columns (they DO appear on the wire), while `oneToMany`/`manyToMany`
+* are pseudo-columns — but all four carry a `related` edge to a sibling model.
+*/
+var RELATIONSHIP_EDGE_TYPES = /* @__PURE__ */ new Set([
+	"foreignKey",
+	"crossPackageRef",
+	"oneToMany",
+	"manyToMany"
+]);
+/** Resolve a manifest object by qualified name or simple class name. */
+function findByName(manifest, name) {
+	return Object.values(manifest.objects).find((candidate) => candidate.qualifiedName === name || candidate.className === name);
+}
+/**
+* Normalize a relationship field's `related` value to a resolvable class name.
+*
+* Thunk forward-ref decorators — `@foreignKey(() => Scene)`, used heavily in
+* video/voice for models that reference a class declared later — serialize as
+* the RAW arrow-function source string `"() => Scene"` in the manifest, which
+* neither `className` nor `qualifiedName` matches. Extract the target class
+* name from the thunk so the edge resolves. Plain (`"Scene"`) and qualified
+* (`"@happyvertical/smrt-assets:Asset"`) forms contain no `=>` and pass through
+* untouched — the qualified `:` separator is preserved.
+*
+* Kept local to the relationship-edge path on purpose: extends-chain resolution
+* never sees a thunk, so `findByName` and the scanner stay unchanged.
+*/
+function normalizeRelatedName(related) {
+	const thunk = related.match(/=>\s*([A-Za-z_$][\w$]*)/);
+	return thunk ? thunk[1] : related.trim();
+}
+/**
+* True when `obj` is (transitively) a SmrtCollection subclass. Collection
+* classes describe access, not row shapes, so they never become web
+* collection definitions.
+*
+* NOTE: deliberately stronger than sveltekit-generator's private
+* `isCollectionClass`, which only inspects the direct base / a type argument.
+* A deeper subclass (`SpecialWidgetCollection extends WidgetCollection`)
+* carries no type argument of its own; without walking the extends chain it
+* would be mistaken for a model and claim its base model's REST collection.
+*/
+function isWebCollectionClass(manifest, obj, seen = /* @__PURE__ */ new Set()) {
+	if (obj.extends === "SmrtCollection" || !!obj.extendsTypeArg) return true;
+	const parentName = obj.extendsQualified || obj.extends;
+	if (!parentName || seen.has(parentName)) return false;
+	seen.add(parentName);
+	const parent = findByName(manifest, parentName);
+	return parent ? isWebCollectionClass(manifest, parent, seen) : false;
+}
+/**
+* True when some ancestor model maps to the SAME REST collection (a shared STI
+* table). The STI base model owns the shared table's single definition.
+*/
+function isStiChildModel(manifest, obj) {
+	const seen = /* @__PURE__ */ new Set();
+	let parentName = obj.extendsQualified || obj.extends;
+	while (parentName && !seen.has(parentName)) {
+		seen.add(parentName);
+		const parent = findByName(manifest, parentName);
+		if (!parent) return false;
+		if (parent.collection === obj.collection) return true;
+		parentName = parent.extendsQualified || parent.extends;
+	}
+	return false;
+}
+/**
+* Select the manifest entries that become web collection definitions: one per
+* REST collection, STI children folding into their base model, collection
+* classes excluded, and only models that expose `list` (a read surface is
+* required to materialize a collection). Uses the canonical
+* {@link resolveApiActionSet} so the exposed-action set matches exactly what
+* the REST/SvelteKit generators actually emit.
+*/
+function selectWebCollectionEntries(manifest) {
+	const byCollection = /* @__PURE__ */ new Map();
+	for (const obj of Object.values(manifest.objects)) {
+		if (isWebCollectionClass(manifest, obj)) continue;
+		const exposedActions = resolveApiActionSet(obj);
+		if (!exposedActions.has("list")) continue;
+		const isStiChild = isStiChildModel(manifest, obj);
+		const existing = byCollection.get(obj.collection);
+		if (existing && !(existing.isStiChild && !isStiChild)) continue;
+		byCollection.set(obj.collection, {
+			collection: obj.collection,
+			obj,
+			actions: [...exposedActions].sort(),
+			isStiChild
+		});
+	}
+	return [...byCollection.values()].map(({ collection, obj, actions }) => ({
+		collection,
+		obj,
+		actions
+	}));
+}
+/**
+* Build the informational per-field metadata for a web collection definition:
+* the persisted public-DTO columns only. Relationship pseudo-fields, STI meta
+* internals, transient (unpersisted) and sensitive (wire-stripped) fields are
+* excluded — they are not columns a client reads back over the REST surface.
+*/
+function buildWebFieldDefinitions(obj) {
+	const fields = {};
+	for (const [fieldName, field] of Object.entries(obj.fields ?? {})) {
+		if (RELATIONSHIP_FIELD_TYPES.has(field.type)) continue;
+		if (field.type === "meta") continue;
+		if (field.transient) continue;
+		if (field.sensitive) continue;
+		fields[fieldName] = {
+			type: field.type,
+			...field.required !== void 0 ? { required: field.required } : {},
+			...field.default !== void 0 ? { default: field.default } : {}
+		};
+	}
+	return fields;
+}
+/**
+* Build the manifest-derived relationship edges for a web collection
+* definition (#1761): one entry per relationship field (`foreignKey`,
+* `crossPackageRef`, `oneToMany`, `manyToMany`) whose `related` target resolves
+* to another API-exposed REST collection.
+*
+* These edges drive relationship-derived cache invalidation in the browser
+* client-data runtime: mutating this collection invalidates the caches of the
+* collections named here. The invalidation graph is thus derived entirely from
+* the manifest — no hand-wired cache keys.
+*
+* An edge is SKIPPED (not emitted) when:
+*  - `related` is missing, or
+*  - `related` cannot be resolved to a manifest object (e.g. a cross-package
+*    target not present in this package's manifest), or
+*  - the resolved target is not itself an API-exposed web collection (no read
+*    surface to invalidate — it never appears in {@link selectWebCollectionEntries}).
+*
+* Self-referential edges (a collection related to itself) are kept: the runtime
+* always invalidates the mutated collection anyway, so a self edge is harmless
+* and keeping it avoids a special case.
+*/
+function buildWebRelationships(obj, manifest) {
+	const exposedCollections = new Set(selectWebCollectionEntries(manifest).map((entry) => entry.collection));
+	const relationships = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const [fieldName, field] of Object.entries(obj.fields ?? {})) {
+		if (!RELATIONSHIP_EDGE_TYPES.has(field.type)) continue;
+		if (!field.related) continue;
+		const target = findByName(manifest, normalizeRelatedName(field.related));
+		if (!target) continue;
+		if (!exposedCollections.has(target.collection)) continue;
+		const dedupeKey = `${fieldName}:${target.collection}`;
+		if (seen.has(dedupeKey)) continue;
+		seen.add(dedupeKey);
+		relationships.push({
+			field: fieldName,
+			kind: field.type,
+			relatedCollection: target.collection
+		});
+	}
+	return relationships;
+}
+//#endregion
+export { buildWebFieldDefinitions, buildWebRelationships, selectWebCollectionEntries };
+
+//# sourceMappingURL=web-collections.js.map

package/dist/vite-plugin/web-collections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-collections.js","names":[],"sources":["../../src/vite-plugin/web-collections.ts"],"sourcesContent":["/**\n * Manifest → web collection selection (single source of truth).\n *\n * The browser client data runtime (`@happyvertical/smrt-web`, #1761) consumes\n * one typed collection definition per API-exposed REST collection. Three\n * emission sites need the SAME selection and field rules, or the emitted\n * runtime values and their declared types drift apart:\n *\n *  - the `\\0smrt:web` runtime virtual module (JSON literal — {@link generateWebModule})\n *  - the `@happyvertical/smrt-virt-web` ambient d.ts (vite-plugin)\n *  - the physical `@smrt/web` d.ts (prebuild, for `tsc`-only consumers)\n *\n * All three import {@link selectWebCollectionEntries} from here so the value\n * emission and the type emission can never disagree.\n */\n\nimport type {\n  FieldDefinition,\n  SmartObjectDefinition,\n  SmartObjectManifest,\n} from '../scanner/types.js';\nimport { resolveApiActionSet } from './sveltekit-generator.js';\n\n/**\n * Field types that are relationship pseudo-columns rather than persisted\n * public-DTO columns — they never appear on the wire as scalar values.\n */\nconst RELATIONSHIP_FIELD_TYPES: ReadonlySet<FieldDefinition['type']> = new Set([\n  'oneToMany',\n  'manyToMany',\n]);\n\n/**\n * Field types that describe a relationship to another model. A superset of\n * {@link RELATIONSHIP_FIELD_TYPES}: `foreignKey`/`crossPackageRef` are persisted\n * scalar id columns (they DO appear on the wire), while `oneToMany`/`manyToMany`\n * are pseudo-columns — but all four carry a `related` edge to a sibling model.\n */\nconst RELATIONSHIP_EDGE_TYPES: ReadonlySet<FieldDefinition['type']> = new Set([\n  'foreignKey',\n  'crossPackageRef',\n  'oneToMany',\n  'manyToMany',\n]);\n\n/** Informational per-column metadata carried by a collection definition. */\nexport interface WebFieldDefinition {\n  type: FieldDefinition['type'];\n  required?: boolean;\n  default?: unknown;\n}\n\n/** The relationship kinds a web collection edge can describe. */\nexport type WebRelationshipKind =\n  | 'foreignKey'\n  | 'crossPackageRef'\n  | 'oneToMany'\n  | 'manyToMany';\n\n/**\n * One manifest-derived relationship edge from a collection to a sibling REST\n * collection. Consumed by the browser client-data runtime to invalidate\n * dependent collection caches when this collection is mutated (#1761) — the\n * cache-invalidation graph is derived entirely from these edges, never\n * hand-wired. SMRT-owned data: no client-engine type appears here.\n */\nexport interface WebRelationship {\n  /** The declaring field carrying the relationship (e.g. `groupId`, `items`). */\n  field: string;\n  /** The relationship kind, mirroring the manifest field type. */\n  kind: WebRelationshipKind;\n  /** REST collection name the edge resolves to (e.g. `ad_groups`). */\n  relatedCollection: string;\n}\n\n/** One selected REST collection and the model that owns its definition. */\nexport interface WebCollectionEntry {\n  /** REST collection name (pluralized), e.g. `products`. */\n  collection: string;\n  /** The manifest object that owns this collection's definition. */\n  obj: SmartObjectDefinition;\n  /** Sorted set of exposed CRUD + custom actions. */\n  actions: string[];\n}\n\n/** Resolve a manifest object by qualified name or simple class name. */\nfunction findByName(\n  manifest: SmartObjectManifest,\n  name: string,\n): SmartObjectDefinition | undefined {\n  return Object.values(manifest.objects).find(\n    (candidate) =>\n      candidate.qualifiedName === name || candidate.className === name,\n  );\n}\n\n/**\n * Normalize a relationship field's `related` value to a resolvable class name.\n *\n * Thunk forward-ref decorators — `@foreignKey(() => Scene)`, used heavily in\n * video/voice for models that reference a class declared later — serialize as\n * the RAW arrow-function source string `\"() => Scene\"` in the manifest, which\n * neither `className` nor `qualifiedName` matches. Extract the target class\n * name from the thunk so the edge resolves. Plain (`\"Scene\"`) and qualified\n * (`\"@happyvertical/smrt-assets:Asset\"`) forms contain no `=>` and pass through\n * untouched — the qualified `:` separator is preserved.\n *\n * Kept local to the relationship-edge path on purpose: extends-chain resolution\n * never sees a thunk, so `findByName` and the scanner stay unchanged.\n */\nfunction normalizeRelatedName(related: string): string {\n  const thunk = related.match(/=>\\s*([A-Za-z_$][\\w$]*)/);\n  return thunk ? thunk[1] : related.trim();\n}\n\n/**\n * True when `obj` is (transitively) a SmrtCollection subclass. Collection\n * classes describe access, not row shapes, so they never become web\n * collection definitions.\n *\n * NOTE: deliberately stronger than sveltekit-generator's private\n * `isCollectionClass`, which only inspects the direct base / a type argument.\n * A deeper subclass (`SpecialWidgetCollection extends WidgetCollection`)\n * carries no type argument of its own; without walking the extends chain it\n * would be mistaken for a model and claim its base model's REST collection.\n */\nfunction isWebCollectionClass(\n  manifest: SmartObjectManifest,\n  obj: SmartObjectDefinition,\n  seen: Set<string> = new Set(),\n): boolean {\n  // Truthy check (not `!== undefined`) mirrors the scanner's own\n  // manifest-generator: a scanner that emits `extendsTypeArg: null` for a\n  // non-generic base must not be misread as a collection.\n  if (obj.extends === 'SmrtCollection' || !!obj.extendsTypeArg) {\n    return true;\n  }\n  const parentName = obj.extendsQualified || obj.extends;\n  if (!parentName || seen.has(parentName)) return false;\n  seen.add(parentName);\n  const parent = findByName(manifest, parentName);\n  return parent ? isWebCollectionClass(manifest, parent, seen) : false;\n}\n\n/**\n * True when some ancestor model maps to the SAME REST collection (a shared STI\n * table). The STI base model owns the shared table's single definition.\n */\nfunction isStiChildModel(\n  manifest: SmartObjectManifest,\n  obj: SmartObjectDefinition,\n): boolean {\n  const seen = new Set<string>();\n  let parentName = obj.extendsQualified || obj.extends;\n  while (parentName && !seen.has(parentName)) {\n    seen.add(parentName);\n    const parent = findByName(manifest, parentName);\n    if (!parent) return false;\n    if (parent.collection === obj.collection) return true;\n    parentName = parent.extendsQualified || parent.extends;\n  }\n  return false;\n}\n\n/**\n * Select the manifest entries that become web collection definitions: one per\n * REST collection, STI children folding into their base model, collection\n * classes excluded, and only models that expose `list` (a read surface is\n * required to materialize a collection). Uses the canonical\n * {@link resolveApiActionSet} so the exposed-action set matches exactly what\n * the REST/SvelteKit generators actually emit.\n */\nexport function selectWebCollectionEntries(\n  manifest: SmartObjectManifest,\n): WebCollectionEntry[] {\n  const byCollection = new Map<\n    string,\n    WebCollectionEntry & { isStiChild: boolean }\n  >();\n\n  for (const obj of Object.values(manifest.objects)) {\n    if (isWebCollectionClass(manifest, obj)) continue;\n\n    const exposedActions = resolveApiActionSet(obj);\n    if (!exposedActions.has('list')) continue;\n\n    const isStiChild = isStiChildModel(manifest, obj);\n    const existing = byCollection.get(obj.collection);\n    // One definition per REST collection. The STI BASE model owns it: a child\n    // only wins while no base has been recorded yet, so the result is\n    // independent of declaration / scan order.\n    if (existing && !(existing.isStiChild && !isStiChild)) continue;\n\n    byCollection.set(obj.collection, {\n      collection: obj.collection,\n      obj,\n      actions: [...exposedActions].sort(),\n      isStiChild,\n    });\n  }\n\n  return [...byCollection.values()].map(({ collection, obj, actions }) => ({\n    collection,\n    obj,\n    actions,\n  }));\n}\n\n/**\n * Build the informational per-field metadata for a web collection definition:\n * the persisted public-DTO columns only. Relationship pseudo-fields, STI meta\n * internals, transient (unpersisted) and sensitive (wire-stripped) fields are\n * excluded — they are not columns a client reads back over the REST surface.\n */\nexport function buildWebFieldDefinitions(\n  obj: SmartObjectDefinition,\n): Record<string, WebFieldDefinition> {\n  const fields: Record<string, WebFieldDefinition> = {};\n  for (const [fieldName, field] of Object.entries(obj.fields ?? {})) {\n    if (RELATIONSHIP_FIELD_TYPES.has(field.type)) continue;\n    if (field.type === 'meta') continue;\n    if (field.transient) continue;\n    if (field.sensitive) continue;\n    fields[fieldName] = {\n      type: field.type,\n      ...(field.required !== undefined ? { required: field.required } : {}),\n      ...(field.default !== undefined ? { default: field.default } : {}),\n    };\n  }\n  return fields;\n}\n\n/**\n * Build the manifest-derived relationship edges for a web collection\n * definition (#1761): one entry per relationship field (`foreignKey`,\n * `crossPackageRef`, `oneToMany`, `manyToMany`) whose `related` target resolves\n * to another API-exposed REST collection.\n *\n * These edges drive relationship-derived cache invalidation in the browser\n * client-data runtime: mutating this collection invalidates the caches of the\n * collections named here. The invalidation graph is thus derived entirely from\n * the manifest — no hand-wired cache keys.\n *\n * An edge is SKIPPED (not emitted) when:\n *  - `related` is missing, or\n *  - `related` cannot be resolved to a manifest object (e.g. a cross-package\n *    target not present in this package's manifest), or\n *  - the resolved target is not itself an API-exposed web collection (no read\n *    surface to invalidate — it never appears in {@link selectWebCollectionEntries}).\n *\n * Self-referential edges (a collection related to itself) are kept: the runtime\n * always invalidates the mutated collection anyway, so a self edge is harmless\n * and keeping it avoids a special case.\n */\nexport function buildWebRelationships(\n  obj: SmartObjectDefinition,\n  manifest: SmartObjectManifest,\n): WebRelationship[] {\n  // The set of REST collections that are actually materialized as web\n  // collections. An edge to a model outside this set has no client cache to\n  // invalidate, so it is dropped.\n  const exposedCollections = new Set(\n    selectWebCollectionEntries(manifest).map((entry) => entry.collection),\n  );\n\n  const relationships: WebRelationship[] = [];\n  const seen = new Set<string>();\n  for (const [fieldName, field] of Object.entries(obj.fields ?? {})) {\n    if (!RELATIONSHIP_EDGE_TYPES.has(field.type)) continue;\n    if (!field.related) continue;\n\n    // Normalize first: `@foreignKey(() => Scene)` thunks serialize as the raw\n    // \"() => Scene\" source, which findByName cannot match on its own.\n    const target = findByName(manifest, normalizeRelatedName(field.related));\n    if (!target) continue;\n    if (!exposedCollections.has(target.collection)) continue;\n\n    // De-dupe on (field, relatedCollection): a model never declares the same\n    // field twice, but guard anyway so the emitted edge list is stable.\n    const dedupeKey = `${fieldName}:${target.collection}`;\n    if (seen.has(dedupeKey)) continue;\n    seen.add(dedupeKey);\n\n    relationships.push({\n      field: fieldName,\n      kind: field.type as WebRelationshipKind,\n      relatedCollection: target.collection,\n    });\n  }\n  return relationships;\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-core",
-  "version": "0.37.8",
+  "version": "0.37.10",
   "description": "Core AI agent framework with standardized collections, object-relational mapping, and code generators",
   "author": "HappyVertical",
   "type": "module",
@@ -154,9 +154,9 @@
     "tsx": "^4.22.4",
     "typescript": "^5.9.3",
     "yaml": "^2.9.0",
-    "@happyvertical/smrt-config": "0.37.8",
-    "@happyvertical/smrt-scanner": "0.37.8",
-    "@happyvertical/smrt-types": "0.37.8"
+    "@happyvertical/smrt-scanner": "0.37.10",
+    "@happyvertical/smrt-types": "0.37.10",
+    "@happyvertical/smrt-config": "0.37.10"
   },
   "peerDependencies": {
     "@huggingface/transformers": ">=3.0.0 <4.0.0",