@happyvertical/smrt-core 0.50.0 → 0.51.1

package/AGENTS.md

@@ -19,6 +19,7 @@ and repository rules.
 | `src/change-signals.ts` | Signal bus, replica fan-out, SSE | [agents/change-signals.md](agents/change-signals.md) |
 | `src/generators/`, `src/vite-plugin/web-collections.ts` | REST/CLI/MCP generation, manifest hashes, ETags | [agents/generators.md](agents/generators.md) |
 | `src/vite-plugin/`, `src/consumer-plugin/`, `src/knowledge.ts` | Decorator UI hints, knowledge projection, generation snapshots | [agents/build-knowledge.md](agents/build-knowledge.md) |
+| `src/knowledge-graph.ts` | Cross-package knowledge graph merge and freshness check (#2863) — see [standards](../../docs/content/standards.md) | — |
 | `src/object.ts`, `src/collection.ts`, `src/learning/memory.ts` | Context memory and semantic search | [agents/memory.md](agents/memory.md) |
 | `src/system/diagnostics.ts` | SELECT-only `_smrt_*` diagnostics reader behind smrt-dev-mcp runtime tools (#1824) | [agents/system-diagnostics.md](agents/system-diagnostics.md) |
 | `src/system/registry-snapshot.ts` | Sanitized plain-JSON projection of the booted `ObjectRegistry` for the smrt-dev-mcp runtime dev-plane (#1831); never constructors, validators, values, or absolute paths | [agents/registry-snapshot.md](agents/registry-snapshot.md) |

package/dist/index.js

@@ -69,6 +69,7 @@ import "./generators/index.js";
 import { SmrtHierarchical } from "./hierarchical.js";
 import { SmrtJunction } from "./junction.js";
 import { discoverScopedPackageDirectories, readPackageAgentDoc } from "./knowledge-discovery.js";
+import { buildKnowledgeGraph, checkKnowledgeGraphFreshness, discoverKnowledgeArtifactPaths, stableStringify } from "./knowledge-graph.js";
 import { AGENT_SURFACE_HASH_PREFIX, MODULE_DOC_HASH_PREFIX, buildDomainKnowledgeManifest, readAgentModuleDocs, resolveAgentModuleDocPaths } from "./knowledge.js";
 import { getClassConfigResolvers, getConfigResolver, isLazyConfigSentinel, listConfigResolvers, registerConfigResolver, resetConfigResolvers, resolveLazyConfig, unregisterConfigResolver } from "./lazy-config.js";
 import { DEFAULT_LEARNING_CONFIG, LearningMemory } from "./learning/memory.js";
@@ -92,4 +93,4 @@ import "./system/index.js";
 import { getTestDatabase } from "./testing/database.js";
 import "./tools/index.js";
 import { smrtPlugin } from "./vite-plugin/index.js";
-export { AGENT_SURFACE_HASH_PREFIX, AIError, APIGenerator, AiUsageCollector, AiUsagePersistenceHandler, BOOTED_PROVENANCE, CACHE_INVALIDATION_CHANNEL, CHANGE_FEED_INTERCEPTOR_NAME, CHANGE_FEED_TABLE, CHANGE_SIGNAL_CHANNEL, CRUD_OPERATIONS, ConfigurationError, ContentHasher, CosineSimilarity, DEFAULT_AI_COST_RATES, DEFAULT_CHANGES_LIMIT, DEFAULT_DATA_QUERY_PAGE_LIMIT, DEFAULT_DATA_QUERY_RESULT_BYTES, DEFAULT_EMBEDDING_CONFIG, DEFAULT_EVENTS_HEARTBEAT_MS, DEFAULT_EVENTS_MAX_SUBSCRIBERS, DEFAULT_EVENTS_RETRY_AFTER_SECONDS, DEFAULT_FACET_LIMIT, DEFAULT_LEARNING_CONFIG, DEFAULT_LIST_LIMIT, DEFAULT_LIST_ORDER_BY, DEFAULT_POSTGRES_TIMEOUTS, DEFAULT_RETENTION_POLICY, DIAGNOSTICS_DEFAULT_LIMIT, DataQueryValidationError, DatabaseError, Dispatch, DispatchBus, DispatchCollection, DispatchSubscription, DispatchSubscriptionCollection, EmbeddingProvider, EmbeddingStorage, EmbeddingUnavailableError, ErrorUtils, FilesystemError, GlobalInterceptors, LearningMemory, LiveSchemaParityError, MAX_CHANGES_LIMIT, MAX_DATA_QUERY_CURSOR_LENGTH, MAX_DATA_QUERY_FACETS, MAX_DATA_QUERY_FILTERS, MAX_DATA_QUERY_FILTER_DEPTH, MAX_DATA_QUERY_IN_VALUES, MAX_DATA_QUERY_OFFSET, MAX_DATA_QUERY_PAGE_LIMIT, MAX_DATA_QUERY_REQUEST_BYTES, MAX_DATA_QUERY_RESULT_BYTES, MAX_DATA_QUERY_WARNINGS, MAX_FACET_FIELDS, MAX_FACET_LIMIT, MAX_LIST_LIMIT, MAX_STI_READ_SCOPE_TYPES, MAX_SYNC_APPLY_BATCH_SIZE, MCPGenerator, MCP_STABLE_CATALOG_TTL_MS, MODULE_DOC_HASH_PREFIX, ManifestBuilder, ManifestGenerator, ManifestManager, MetricsAdapter, NetworkError, ObjectRegistry, PLAYBOOK_PREFLIGHT_CAPABILITY, PLAYBOOK_PREFLIGHT_ROUTE_SEGMENT, POSTGRES_REVISION_GUARD_EXPRESSION, POSTGRES_TIMEOUT_ENV_VARS, PRIVATE_READ_CACHE_CONTROL, PubSubAdapter, QueryBoundsError, QueryOrderByError, RuntimeError, SMRT_COLLECTION_BASE_NAMES, SMRT_CUSTOM_ACTION_ERROR_METADATA_KEY, SYNC_APPLY_ROUTE_SEGMENTS, SYNC_APPLY_UUID_PATTERN, SYSTEM_DIAGNOSTICS_TABLES, SYSTEM_TABLE_NAMES, SchemaComparer, SignalBus, SignalSanitizer, SmrtClass, SmrtCollection, SmrtError, SmrtHierarchical, SmrtJunction, SmrtMCPServer, SmrtObject, SmrtPolymorphicAssociation, TenantIsolationError, ValidationError, ValidationReport, ValidationUtils, appendChange, appendChanges, applyOneToManyChildAccessors, applyPendingDecoratorRegistrations, applyPostgresPermissions, applyPostgresRuntimeTimeouts, applySyncWritablePolicy, assertPlainJson, assertPostgresSystemTimestampsCurrent, broadcastCacheInvalidation, buildCascadePlan, buildChangeEventStream, buildCustomActionInputSchema, buildCustomActionInvocationArgs, buildDefaultListOrderBy, buildDomainKnowledgeManifest, bumpChangeFeed, canonicalReadRepresentation, canonicalizeDataQuery, cascadeReferencesTo, changeEventSubscribersAtCapacity, checkLiveSchemaParity, childAccessorName, classifyDatabaseError, classifyDialectMessage, classifyMethodWireability, classifyParameterWireability, clearRetentionTasks, clone, coerceCustomActionArgument, collectForeignKeyOrphanCounts, computeBodyEtag, computeRuntimeWebManifestHash, computeTableVersionEtag, conditionalJsonResponse, config, convertTypeToJsonSchema, createClassNamePredicate, createDataQueryFingerprint, createDispatchBus, createFilesystemAdapter, createInterceptorContext, createMCPServer, createManifestClassNamePredicate, createQualifiedName, createRestServer, createSmrtClient, createSmrtServer, crossPackageRef, customActionParameterInputName, declaredTypeAcceptsDate, declaresRuntimeRestRoute, declaresRuntimeRestRouteShape, detectEngine, discoverManifestEntry, discoverScopedPackageDirectories, drainChangeFeed, ensureBootstrapSystemTableCompatibility, ensureCacheInvalidationListener, ensureChangeFeedTable, ensureDeferredSystemTableCompatibility, ensureDispatchSubscriptionsSystemTableCompatibility, ensureDispatchSystemTableCompatibility, ensureJobEventsSystemTableCompatibility, ensureJobsSystemTableCompatibility, ensureLegacySystemTableCompatibility, ensureSystemTables, estimateAiUsageCost, eventStreamCapacityExceededResponse, executeCollectionReadPlan, executeToolCall, executeToolCalls, field, findManifestEntryByQualifiedName, foreignKey, formatToolResults, generateDDLForEngine, generateOpenAPISpec, generateSchemaDiff, generateToolFromMethod, generateToolManifest, getAdapterInfo, getCacheGeneration, getChangesSince, getClassConfigResolvers, getClassName, getConfigResolver, getDatabaseEngine, getManifest, getPackageFromQualifiedName, getRetentionTasks, getSQLFromDiff, getSystemTableShapes, getTableVersion, getTenantScopedChangesSince, getTestDatabase, handlePlaybookPreflightRoute, hasActionableChanges, ifNoneMatchHasConcreteMatch, ifNoneMatchSatisfied, importOptionalDependency, invalidateCollectionCache, isAbortedTransactionError, isAdvisoryOnlyChange, isApiActionEnabledForObject, isCrudOperation, isCrudToolAction, isDatabaseInterface, isDeterministicDatabaseError, isEmbeddedDatabase, isFrameworkBaseClass, isFromPackage, isLazyConfigSentinel, isManualOrAdvisoryChange, isNotNullViolationError, isPostgresDatabase, isQualifiedName, isRestActionRoutable, isRestRoutePublic, isSmrtCollectionExtendsName, isStaleWrite, isTenantScopedClassResolved, isTransientDatabaseError, isType, isUniqueViolationError, isValid, listConfigResolvers, loadExternalManifest, loadExternalManifestSync, loadLocalTestManifestSync, loadManifestFromPathSync, manifest, manyToMany, meta, method, migratePostgresSystemTimestamps, normalizeCustomActionFailure, normalizeDataQueryRequest, normalizeDataQueryResult, normalizeDataQuerySchema, normalizeEventsMaxSubscribers, normalizeOnDelete, normalizeTypedHttpError, oneToMany, parse, parseQualifiedName, parseSyncApplyBatch, payloadMatchesRow, planForeignKeyCreation, planPostgresPermissions, planPostgresSystemTimestampMigrations, postgresRevisionCandidates, postgresRevisionCondition, processSyncApplyBatch, pruneAiUsage, pruneChangeFeed, pruneExpiredContexts, qualifiedNamesEqual, queryStringDecoderFor, readAgentModuleDocs, readDispatchHealth, readJobHealth, readMethodDecoratorConfig, readMigrationStatus, readPackageAgentDoc, readRecentChanges, readRegistryDrift, readScheduleHealth, readSystemDiagnostics, registerChangeFeedWriter, registerCompatibleFieldDecorator, registerCompatibleMethodDecorator, registerConfigResolver, registerFilesystemAdapterFactory, registerOptionalDependency, registerRetentionTask, resetChangeFeedWarnings, resetChangeSignals, resetCollectionCache, resetConfigResolvers, resetVerifiedTables, resolveAgentModuleDocPaths, resolveApiMethodExposure, resolveCustomActionMetadata, resolveDatabase, resolveDbCacheKey, resolveDeclaredScopeMismatch, resolveDispatchTenantId, resolveDispatchTenantScope, resolveEffectiveActionMetadata, resolveGetStringFilter, resolveLazyConfig, resolveListLimit, resolveListOffset, resolveMCPToolListCacheHint, resolvePostgresTimeouts, resolveReadCacheControl, resolveRegisteredObjectName, resolveTenantEtagDiscriminator, restFieldReadPermissions, restMethodForApiAction, runCascadeDelete, runRetentionSweep, runWithTenantGate, safeParse, safeStringify, sanitizeMessagePaths, setDispatchTenantResolver, setTenantEntryPointRunner, setTenantScopedClassResolver, setupSwaggerUI, shouldIncludeMethod, signalVisibleToTenant, smrt, smrtPlugin, smrt as smrtRegistry, snapshotRegistry, sortMCPTools, startRestServer, staticManifest, stopCacheInvalidationListeners, stopChangeSignalListeners, stringify, subscribeToChangeSignals, tableExists, toCustomActionBoolean, toCustomActionDate, toCustomActionNumber, tryReserveChangeEventSubscriberSlot, unregisterChangeFeedWriter, unregisterConfigResolver, unregisterRetentionTask, usesEmbeddedRevisionFallback, validatePostgresPermissionContract, validateSyncApplyItem, validateToolCall, versionConditionalResponse, warnIfSharedCacheNeutralized, withEmbeddedWriteQueue, withEmbeddedWriteTransaction };
+export { AGENT_SURFACE_HASH_PREFIX, AIError, APIGenerator, AiUsageCollector, AiUsagePersistenceHandler, BOOTED_PROVENANCE, CACHE_INVALIDATION_CHANNEL, CHANGE_FEED_INTERCEPTOR_NAME, CHANGE_FEED_TABLE, CHANGE_SIGNAL_CHANNEL, CRUD_OPERATIONS, ConfigurationError, ContentHasher, CosineSimilarity, DEFAULT_AI_COST_RATES, DEFAULT_CHANGES_LIMIT, DEFAULT_DATA_QUERY_PAGE_LIMIT, DEFAULT_DATA_QUERY_RESULT_BYTES, DEFAULT_EMBEDDING_CONFIG, DEFAULT_EVENTS_HEARTBEAT_MS, DEFAULT_EVENTS_MAX_SUBSCRIBERS, DEFAULT_EVENTS_RETRY_AFTER_SECONDS, DEFAULT_FACET_LIMIT, DEFAULT_LEARNING_CONFIG, DEFAULT_LIST_LIMIT, DEFAULT_LIST_ORDER_BY, DEFAULT_POSTGRES_TIMEOUTS, DEFAULT_RETENTION_POLICY, DIAGNOSTICS_DEFAULT_LIMIT, DataQueryValidationError, DatabaseError, Dispatch, DispatchBus, DispatchCollection, DispatchSubscription, DispatchSubscriptionCollection, EmbeddingProvider, EmbeddingStorage, EmbeddingUnavailableError, ErrorUtils, FilesystemError, GlobalInterceptors, LearningMemory, LiveSchemaParityError, MAX_CHANGES_LIMIT, MAX_DATA_QUERY_CURSOR_LENGTH, MAX_DATA_QUERY_FACETS, MAX_DATA_QUERY_FILTERS, MAX_DATA_QUERY_FILTER_DEPTH, MAX_DATA_QUERY_IN_VALUES, MAX_DATA_QUERY_OFFSET, MAX_DATA_QUERY_PAGE_LIMIT, MAX_DATA_QUERY_REQUEST_BYTES, MAX_DATA_QUERY_RESULT_BYTES, MAX_DATA_QUERY_WARNINGS, MAX_FACET_FIELDS, MAX_FACET_LIMIT, MAX_LIST_LIMIT, MAX_STI_READ_SCOPE_TYPES, MAX_SYNC_APPLY_BATCH_SIZE, MCPGenerator, MCP_STABLE_CATALOG_TTL_MS, MODULE_DOC_HASH_PREFIX, ManifestBuilder, ManifestGenerator, ManifestManager, MetricsAdapter, NetworkError, ObjectRegistry, PLAYBOOK_PREFLIGHT_CAPABILITY, PLAYBOOK_PREFLIGHT_ROUTE_SEGMENT, POSTGRES_REVISION_GUARD_EXPRESSION, POSTGRES_TIMEOUT_ENV_VARS, PRIVATE_READ_CACHE_CONTROL, PubSubAdapter, QueryBoundsError, QueryOrderByError, RuntimeError, SMRT_COLLECTION_BASE_NAMES, SMRT_CUSTOM_ACTION_ERROR_METADATA_KEY, SYNC_APPLY_ROUTE_SEGMENTS, SYNC_APPLY_UUID_PATTERN, SYSTEM_DIAGNOSTICS_TABLES, SYSTEM_TABLE_NAMES, SchemaComparer, SignalBus, SignalSanitizer, SmrtClass, SmrtCollection, SmrtError, SmrtHierarchical, SmrtJunction, SmrtMCPServer, SmrtObject, SmrtPolymorphicAssociation, TenantIsolationError, ValidationError, ValidationReport, ValidationUtils, appendChange, appendChanges, applyOneToManyChildAccessors, applyPendingDecoratorRegistrations, applyPostgresPermissions, applyPostgresRuntimeTimeouts, applySyncWritablePolicy, assertPlainJson, assertPostgresSystemTimestampsCurrent, broadcastCacheInvalidation, buildCascadePlan, buildChangeEventStream, buildCustomActionInputSchema, buildCustomActionInvocationArgs, buildDefaultListOrderBy, buildDomainKnowledgeManifest, buildKnowledgeGraph, bumpChangeFeed, canonicalReadRepresentation, canonicalizeDataQuery, cascadeReferencesTo, changeEventSubscribersAtCapacity, checkKnowledgeGraphFreshness, checkLiveSchemaParity, childAccessorName, classifyDatabaseError, classifyDialectMessage, classifyMethodWireability, classifyParameterWireability, clearRetentionTasks, clone, coerceCustomActionArgument, collectForeignKeyOrphanCounts, computeBodyEtag, computeRuntimeWebManifestHash, computeTableVersionEtag, conditionalJsonResponse, config, convertTypeToJsonSchema, createClassNamePredicate, createDataQueryFingerprint, createDispatchBus, createFilesystemAdapter, createInterceptorContext, createMCPServer, createManifestClassNamePredicate, createQualifiedName, createRestServer, createSmrtClient, createSmrtServer, crossPackageRef, customActionParameterInputName, declaredTypeAcceptsDate, declaresRuntimeRestRoute, declaresRuntimeRestRouteShape, detectEngine, discoverKnowledgeArtifactPaths, discoverManifestEntry, discoverScopedPackageDirectories, drainChangeFeed, ensureBootstrapSystemTableCompatibility, ensureCacheInvalidationListener, ensureChangeFeedTable, ensureDeferredSystemTableCompatibility, ensureDispatchSubscriptionsSystemTableCompatibility, ensureDispatchSystemTableCompatibility, ensureJobEventsSystemTableCompatibility, ensureJobsSystemTableCompatibility, ensureLegacySystemTableCompatibility, ensureSystemTables, estimateAiUsageCost, eventStreamCapacityExceededResponse, executeCollectionReadPlan, executeToolCall, executeToolCalls, field, findManifestEntryByQualifiedName, foreignKey, formatToolResults, generateDDLForEngine, generateOpenAPISpec, generateSchemaDiff, generateToolFromMethod, generateToolManifest, getAdapterInfo, getCacheGeneration, getChangesSince, getClassConfigResolvers, getClassName, getConfigResolver, getDatabaseEngine, getManifest, getPackageFromQualifiedName, getRetentionTasks, getSQLFromDiff, getSystemTableShapes, getTableVersion, getTenantScopedChangesSince, getTestDatabase, handlePlaybookPreflightRoute, hasActionableChanges, ifNoneMatchHasConcreteMatch, ifNoneMatchSatisfied, importOptionalDependency, invalidateCollectionCache, isAbortedTransactionError, isAdvisoryOnlyChange, isApiActionEnabledForObject, isCrudOperation, isCrudToolAction, isDatabaseInterface, isDeterministicDatabaseError, isEmbeddedDatabase, isFrameworkBaseClass, isFromPackage, isLazyConfigSentinel, isManualOrAdvisoryChange, isNotNullViolationError, isPostgresDatabase, isQualifiedName, isRestActionRoutable, isRestRoutePublic, isSmrtCollectionExtendsName, isStaleWrite, isTenantScopedClassResolved, isTransientDatabaseError, isType, isUniqueViolationError, isValid, listConfigResolvers, loadExternalManifest, loadExternalManifestSync, loadLocalTestManifestSync, loadManifestFromPathSync, manifest, manyToMany, meta, method, migratePostgresSystemTimestamps, normalizeCustomActionFailure, normalizeDataQueryRequest, normalizeDataQueryResult, normalizeDataQuerySchema, normalizeEventsMaxSubscribers, normalizeOnDelete, normalizeTypedHttpError, oneToMany, parse, parseQualifiedName, parseSyncApplyBatch, payloadMatchesRow, planForeignKeyCreation, planPostgresPermissions, planPostgresSystemTimestampMigrations, postgresRevisionCandidates, postgresRevisionCondition, processSyncApplyBatch, pruneAiUsage, pruneChangeFeed, pruneExpiredContexts, qualifiedNamesEqual, queryStringDecoderFor, readAgentModuleDocs, readDispatchHealth, readJobHealth, readMethodDecoratorConfig, readMigrationStatus, readPackageAgentDoc, readRecentChanges, readRegistryDrift, readScheduleHealth, readSystemDiagnostics, registerChangeFeedWriter, registerCompatibleFieldDecorator, registerCompatibleMethodDecorator, registerConfigResolver, registerFilesystemAdapterFactory, registerOptionalDependency, registerRetentionTask, resetChangeFeedWarnings, resetChangeSignals, resetCollectionCache, resetConfigResolvers, resetVerifiedTables, resolveAgentModuleDocPaths, resolveApiMethodExposure, resolveCustomActionMetadata, resolveDatabase, resolveDbCacheKey, resolveDeclaredScopeMismatch, resolveDispatchTenantId, resolveDispatchTenantScope, resolveEffectiveActionMetadata, resolveGetStringFilter, resolveLazyConfig, resolveListLimit, resolveListOffset, resolveMCPToolListCacheHint, resolvePostgresTimeouts, resolveReadCacheControl, resolveRegisteredObjectName, resolveTenantEtagDiscriminator, restFieldReadPermissions, restMethodForApiAction, runCascadeDelete, runRetentionSweep, runWithTenantGate, safeParse, safeStringify, sanitizeMessagePaths, setDispatchTenantResolver, setTenantEntryPointRunner, setTenantScopedClassResolver, setupSwaggerUI, shouldIncludeMethod, signalVisibleToTenant, smrt, smrtPlugin, smrt as smrtRegistry, snapshotRegistry, sortMCPTools, stableStringify, startRestServer, staticManifest, stopCacheInvalidationListeners, stopChangeSignalListeners, stringify, subscribeToChangeSignals, tableExists, toCustomActionBoolean, toCustomActionDate, toCustomActionNumber, tryReserveChangeEventSubscriberSlot, unregisterChangeFeedWriter, unregisterConfigResolver, unregisterRetentionTask, usesEmbeddedRevisionFallback, validatePostgresPermissionContract, validateSyncApplyItem, validateToolCall, versionConditionalResponse, warnIfSharedCacheNeutralized, withEmbeddedWriteQueue, withEmbeddedWriteTransaction };

package/dist/knowledge-graph.d.ts

@@ -0,0 +1,95 @@
+import { DomainKnowledgeManifest } from '@happyvertical/smrt-types';
+/**
+ * Discovers every currently-buildable per-package artifact path under
+ * `<rootDir>/packages/*`, preferring the published `dist/smrt-knowledge.json`
+ * over the local dev `.smrt/smrt-knowledge.json` when both exist. Shared by
+ * the generator (which needs the manifest content) and the freshness check
+ * (which only needs to know whether the current SET of artifacts matches
+ * what the graph was built from — a newly built package, or a package that
+ * newly started exporting `./smrt-knowledge.json`, must mark the graph stale
+ * even though every artifact the graph already knows about is unchanged).
+ */
+export declare function discoverKnowledgeArtifactPaths(rootDir: string): string[];
+/** One package's `smrt-knowledge.json`, located relative to the graph root. */
+export interface KnowledgeGraphInput {
+    /** Path to the artifact, relative to the repo root, POSIX-separated. */
+    artifactPath: string;
+    manifest: DomainKnowledgeManifest;
+}
+export interface KnowledgeGraphPackageNode {
+    name: string;
+    version?: string;
+    artifactPath: string;
+    tags: string[];
+    risks: string[];
+    summary?: string;
+    objectCount: number;
+}
+export interface KnowledgeGraphObjectNode {
+    /** `<packageName>#<qualifiedName-or-name>`, this graph's stable object id. */
+    id: string;
+    packageName: string;
+    name: string;
+    qualifiedName?: string;
+    collection: string;
+    tableName?: string;
+    tableStrategy?: 'cti' | 'sti';
+    extends?: string;
+}
+export type KnowledgeGraphEdgeType = 'crossPackageRef' | 'sti' | 'junction' | 'hierarchical' | 'polymorphic' | 'systemTable';
+export interface KnowledgeGraphEdge {
+    type: KnowledgeGraphEdgeType;
+    /** Object id (or `<packageName>#<extends>`-style unresolved target) this edge starts from. */
+    from: string;
+    /**
+     * Object id the edge points to when resolvable against a scanned object;
+     * otherwise the raw declared target (e.g. a qualified name this run did
+     * not scan), so the edge is still readable rather than dropped.
+     */
+    to?: string;
+    /** Declaring field name, for `crossPackageRef` edges. */
+    field?: string;
+}
+export interface SmrtKnowledgeGraph {
+    schemaVersion: 1;
+    generatedAt: string;
+    /** `artifactPath -> sha256(content)`, sorted by key; the freshness input. */
+    sourceHashes: Record<string, string>;
+    packages: KnowledgeGraphPackageNode[];
+    objects: KnowledgeGraphObjectNode[];
+    edges: KnowledgeGraphEdge[];
+}
+export interface BuildKnowledgeGraphOptions {
+    /**
+     * The graph currently on disk, when regenerating. `generatedAt` is
+     * preserved from it rather than reset to the clock whenever the rebuilt
+     * graph is otherwise semantically identical — the same pattern
+     * `preserveKnowledgeGeneratedAt` uses for per-package artifacts
+     * (`packages/core/src/vite-plugin/index.ts`) — so re-running the generator
+     * with nothing merged actually changed does not churn the file (#2872
+     * review).
+     */
+    previousGraph?: SmrtKnowledgeGraph;
+}
+/** Builds the merged graph. Deterministic: every array is sorted. */
+export declare function buildKnowledgeGraph(inputs: KnowledgeGraphInput[], options?: BuildKnowledgeGraphOptions): SmrtKnowledgeGraph;
+/** Deterministic `JSON.stringify` — object keys are sorted at every level. */
+export declare function stableStringify(value: unknown): string;
+export interface KnowledgeGraphFreshnessIssue {
+    severity: 'error' | 'warning';
+    code: 'missing-knowledge-graph' | 'stale-knowledge-graph' | 'knowledge-graph-source-missing';
+    message: string;
+    file?: string;
+}
+/**
+ * Checks the merged graph's recorded `sourceHashes` against the current
+ * content of each per-package artifact it was built from — the same pattern
+ * `knowledge.ts`/`smrt-dev-mcp` use for a single package's `sourceHashes`.
+ *
+ * `graphPath` and each `artifactPath` in the graph are resolved relative to
+ * `rootDir` (the repo root).
+ */
+export declare function checkKnowledgeGraphFreshness(rootDir: string, graphPath: string, options?: {
+    requireArtifact?: boolean;
+}): KnowledgeGraphFreshnessIssue[];
+//# sourceMappingURL=knowledge-graph.d.ts.map

package/dist/knowledge-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-graph.d.ts","sourceRoot":"","sources":["../src/knowledge-graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,KAAK,EACV,uBAAuB,EAExB,MAAM,2BAA2B,CAAC;AAEnC;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAexE;AAED,+EAA+E;AAC/E,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,uBAAuB,CAAC;CACnC;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,8EAA8E;IAC9E,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,sBAAsB,GAC9B,iBAAiB,GACjB,KAAK,GACL,UAAU,GACV,cAAc,GACd,aAAa,GACb,aAAa,CAAC;AAElB,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,8FAA8F;IAC9F,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,CAAC,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,QAAQ,EAAE,yBAAyB,EAAE,CAAC;IACtC,OAAO,EAAE,wBAAwB,EAAE,CAAC;IACpC,KAAK,EAAE,kBAAkB,EAAE,CAAC;CAC7B;AAUD,MAAM,WAAW,0BAA0B;IACzC;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAC;CACpC;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,mBAAmB,EAAE,EAC7B,OAAO,GAAE,0BAA+B,GACvC,kBAAkB,CAoKpB;AAOD,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtD;AAoBD,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,IAAI,EACA,yBAAyB,GACzB,uBAAuB,GACvB,gCAAgC,CAAC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IAAE,eAAe,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1C,4BAA4B,EAAE,CA0FhC"}

package/dist/knowledge-graph.js

@@ -0,0 +1,268 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, relative } from "node:path";
+//#region src/knowledge-graph.ts
+/**
+* Cross-package knowledge graph (#2863).
+*
+* Each package's own `smrt-knowledge.json` (see `knowledge.ts`) is a
+* per-package projection. Nothing merges them, so cross-package invariants
+* that the scanner manifest already carries — `@crossPackageRef` targets, STI
+* parent/child pairs, junction/hierarchical/polymorphic base usage, and
+* `_smrt_` system-table ownership — live only as prose in the root
+* `AGENTS.md`. This module builds the merged, deterministic root artifact
+* (`.smrt/smrt-knowledge-graph.json`) from whichever per-package artifacts
+* are present, and checks it for staleness the same way `knowledge.ts` checks
+* a package artifact: by comparing recorded `sourceHashes` against the
+* current file content.
+*
+* This module never invents an edge: every edge is a direct read of a field
+* already emitted into a package's `DomainKnowledgeManifest` (`related`,
+* `tableStrategy`, `extends`, `relationshipFeatures`, `tableName`).
+*/
+/**
+* Discovers every currently-buildable per-package artifact path under
+* `<rootDir>/packages/*`, preferring the published `dist/smrt-knowledge.json`
+* over the local dev `.smrt/smrt-knowledge.json` when both exist. Shared by
+* the generator (which needs the manifest content) and the freshness check
+* (which only needs to know whether the current SET of artifacts matches
+* what the graph was built from — a newly built package, or a package that
+* newly started exporting `./smrt-knowledge.json`, must mark the graph stale
+* even though every artifact the graph already knows about is unchanged).
+*/
+function discoverKnowledgeArtifactPaths(rootDir) {
+	const packagesDir = join(rootDir, "packages");
+	if (!existsSync(packagesDir)) return [];
+	const paths = [];
+	for (const entry of readdirSync(packagesDir, { withFileTypes: true })) {
+		if (!entry.isDirectory()) continue;
+		const packageDir = join(packagesDir, entry.name);
+		const found = [join(packageDir, "dist", "smrt-knowledge.json"), join(packageDir, ".smrt", "smrt-knowledge.json")].find((path) => existsSync(path));
+		if (found) paths.push(relative(rootDir, found).split("\\").join("/"));
+	}
+	return paths.sort();
+}
+function hashContent(content) {
+	return createHash("sha256").update(content).digest("hex");
+}
+function objectId(packageName, object) {
+	return `${packageName}#${object.qualifiedName ?? object.name}`;
+}
+/** Builds the merged graph. Deterministic: every array is sorted. */
+function buildKnowledgeGraph(inputs, options = {}) {
+	const sortedInputs = [...inputs].sort((a, b) => a.artifactPath.localeCompare(b.artifactPath));
+	const sourceHashes = {};
+	const packages = [];
+	const objects = [];
+	const edges = [];
+	const idByQualifiedName = /* @__PURE__ */ new Map();
+	const idBySimpleName = /* @__PURE__ */ new Map();
+	const idBySimpleNamePerPackage = /* @__PURE__ */ new Map();
+	for (const input of sortedInputs) {
+		const manifestPackageName = input.manifest.packageName ?? input.artifactPath;
+		for (const object of input.manifest.objects) {
+			const packageName = object.packageName ?? manifestPackageName;
+			const perPackage = idBySimpleNamePerPackage.get(packageName) ?? /* @__PURE__ */ new Map();
+			const id = objectId(packageName, object);
+			idByQualifiedName.set(object.qualifiedName ?? id, id);
+			const bySimple = idBySimpleName.get(object.name) ?? /* @__PURE__ */ new Set();
+			bySimple.add(id);
+			idBySimpleName.set(object.name, bySimple);
+			perPackage.set(object.name, id);
+			idBySimpleNamePerPackage.set(packageName, perPackage);
+		}
+	}
+	const resolveTarget = (raw, declaringPackageName) => {
+		if (!raw) return void 0;
+		if (idByQualifiedName.has(raw)) return idByQualifiedName.get(raw);
+		if (declaringPackageName) {
+			const sameId = idBySimpleNamePerPackage.get(declaringPackageName)?.get(raw);
+			if (sameId) return sameId;
+		}
+		const bySimple = idBySimpleName.get(raw);
+		if (bySimple && bySimple.size === 1) return [...bySimple][0];
+	};
+	const seenObjectIds = /* @__PURE__ */ new Set();
+	for (const input of sortedInputs) {
+		sourceHashes[input.artifactPath] = hashContent(stableStringify(input.manifest));
+		const packageName = input.manifest.packageName ?? input.artifactPath;
+		packages.push({
+			name: packageName,
+			version: input.manifest.packageVersion,
+			artifactPath: input.artifactPath,
+			tags: [...input.manifest.tags].sort(),
+			risks: [...input.manifest.risks].sort(),
+			summary: input.manifest.summary,
+			objectCount: input.manifest.objects.length
+		});
+		for (const object of input.manifest.objects) {
+			const objectPackageName = object.packageName ?? packageName;
+			const id = objectId(objectPackageName, object);
+			if (!seenObjectIds.has(id)) {
+				seenObjectIds.add(id);
+				objects.push({
+					id,
+					packageName: objectPackageName,
+					name: object.name,
+					qualifiedName: object.qualifiedName,
+					collection: object.collection,
+					tableName: object.tableName,
+					tableStrategy: object.tableStrategy,
+					extends: object.extends
+				});
+			}
+			for (const field of object.relationships) {
+				if (field.type !== "crossPackageRef") continue;
+				edges.push({
+					type: "crossPackageRef",
+					from: id,
+					to: resolveTarget(field.related) ?? field.related,
+					field: field.name
+				});
+			}
+			if (object.tableStrategy === "sti" && object.extends) edges.push({
+				type: "sti",
+				from: id,
+				to: resolveTarget(object.extends, objectPackageName) ?? `${objectPackageName}#${object.extends}`
+			});
+			for (const feature of object.relationshipFeatures) if (feature === "SmrtJunction") edges.push({
+				type: "junction",
+				from: id
+			});
+			else if (feature === "SmrtHierarchical") edges.push({
+				type: "hierarchical",
+				from: id
+			});
+			else if (feature === "SmrtPolymorphicAssociation") edges.push({
+				type: "polymorphic",
+				from: id
+			});
+			if (object.tableName?.startsWith("_smrt_")) edges.push({
+				type: "systemTable",
+				from: id,
+				to: object.tableName
+			});
+		}
+	}
+	packages.sort((a, b) => a.name.localeCompare(b.name));
+	objects.sort((a, b) => a.id.localeCompare(b.id));
+	edges.sort((a, b) => {
+		const key = (edge) => `${edge.type}|${edge.from}|${edge.to ?? ""}|${edge.field ?? ""}`;
+		return key(a).localeCompare(key(b));
+	});
+	const graph = {
+		schemaVersion: 1,
+		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		sourceHashes: sortRecord(sourceHashes),
+		packages,
+		objects,
+		edges
+	};
+	const { previousGraph } = options;
+	if (previousGraph && semanticGraphJson(previousGraph) === semanticGraphJson(graph)) return {
+		...graph,
+		generatedAt: previousGraph.generatedAt
+	};
+	return graph;
+}
+function semanticGraphJson(graph) {
+	const { generatedAt: _generatedAt, ...rest } = graph;
+	return stableStringify(rest);
+}
+/** Deterministic `JSON.stringify` — object keys are sorted at every level. */
+function stableStringify(value) {
+	return JSON.stringify(sortValue(value));
+}
+function sortValue(value) {
+	if (Array.isArray(value)) return value.map(sortValue);
+	if (value && typeof value === "object") {
+		const sorted = {};
+		for (const key of Object.keys(value).sort()) sorted[key] = sortValue(value[key]);
+		return sorted;
+	}
+	return value;
+}
+function sortRecord(record) {
+	const sorted = {};
+	for (const key of Object.keys(record).sort()) sorted[key] = record[key];
+	return sorted;
+}
+/**
+* Checks the merged graph's recorded `sourceHashes` against the current
+* content of each per-package artifact it was built from — the same pattern
+* `knowledge.ts`/`smrt-dev-mcp` use for a single package's `sourceHashes`.
+*
+* `graphPath` and each `artifactPath` in the graph are resolved relative to
+* `rootDir` (the repo root).
+*/
+function checkKnowledgeGraphFreshness(rootDir, graphPath, options = {}) {
+	const issues = [];
+	const absoluteGraphPath = `${rootDir}/${graphPath}`;
+	if (!existsSync(absoluteGraphPath)) {
+		if (!options.requireArtifact) return issues;
+		issues.push({
+			severity: "error",
+			code: "missing-knowledge-graph",
+			message: `${graphPath} does not exist; run \`pnpm knowledge:graph\``,
+			file: graphPath
+		});
+		return issues;
+	}
+	let graph;
+	try {
+		graph = JSON.parse(readFileSync(absoluteGraphPath, "utf8"));
+	} catch (error) {
+		issues.push({
+			severity: "error",
+			code: "stale-knowledge-graph",
+			message: `${graphPath} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+			file: graphPath
+		});
+		return issues;
+	}
+	const recordedPaths = Object.keys(graph.sourceHashes ?? {});
+	for (const [artifactPath, expectedHash] of Object.entries(graph.sourceHashes ?? {})) {
+		const absoluteArtifactPath = `${rootDir}/${artifactPath}`;
+		if (!existsSync(absoluteArtifactPath)) {
+			issues.push({
+				severity: "error",
+				code: "knowledge-graph-source-missing",
+				message: `${artifactPath} used to build ${graphPath} no longer exists`,
+				file: graphPath
+			});
+			continue;
+		}
+		let manifest;
+		try {
+			manifest = JSON.parse(readFileSync(absoluteArtifactPath, "utf8"));
+		} catch (error) {
+			issues.push({
+				severity: "error",
+				code: "stale-knowledge-graph",
+				message: `${artifactPath} is not valid JSON (${error instanceof Error ? error.message : String(error)}); run \`pnpm knowledge:graph\``,
+				file: graphPath
+			});
+			continue;
+		}
+		if (hashContent(stableStringify(manifest)) !== expectedHash) issues.push({
+			severity: "error",
+			code: "stale-knowledge-graph",
+			message: `${artifactPath} changed since ${graphPath} was generated; run \`pnpm knowledge:graph\``,
+			file: graphPath
+		});
+	}
+	const currentPaths = discoverKnowledgeArtifactPaths(rootDir);
+	const recordedSet = new Set(recordedPaths);
+	const newPaths = currentPaths.filter((path) => !recordedSet.has(path));
+	if (newPaths.length > 0) issues.push({
+		severity: "error",
+		code: "stale-knowledge-graph",
+		message: `${newPaths.join(", ")} ${newPaths.length === 1 ? "is a new package artifact" : "are new package artifacts"} not yet merged into ${graphPath}; run \`pnpm knowledge:graph\``,
+		file: graphPath
+	});
+	return issues;
+}
+//#endregion
+export { buildKnowledgeGraph, checkKnowledgeGraphFreshness, discoverKnowledgeArtifactPaths, stableStringify };
+
+//# sourceMappingURL=knowledge-graph.js.map

package/dist/knowledge-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-graph.js","names":[],"sources":["../src/knowledge-graph.ts"],"sourcesContent":["/**\n * Cross-package knowledge graph (#2863).\n *\n * Each package's own `smrt-knowledge.json` (see `knowledge.ts`) is a\n * per-package projection. Nothing merges them, so cross-package invariants\n * that the scanner manifest already carries — `@crossPackageRef` targets, STI\n * parent/child pairs, junction/hierarchical/polymorphic base usage, and\n * `_smrt_` system-table ownership — live only as prose in the root\n * `AGENTS.md`. This module builds the merged, deterministic root artifact\n * (`.smrt/smrt-knowledge-graph.json`) from whichever per-package artifacts\n * are present, and checks it for staleness the same way `knowledge.ts` checks\n * a package artifact: by comparing recorded `sourceHashes` against the\n * current file content.\n *\n * This module never invents an edge: every edge is a direct read of a field\n * already emitted into a package's `DomainKnowledgeManifest` (`related`,\n * `tableStrategy`, `extends`, `relationshipFeatures`, `tableName`).\n */\n\nimport { createHash } from 'node:crypto';\nimport { existsSync, readdirSync, readFileSync } from 'node:fs';\nimport { join, relative } from 'node:path';\nimport type {\n  DomainKnowledgeManifest,\n  DomainKnowledgeObject,\n} from '@happyvertical/smrt-types';\n\n/**\n * Discovers every currently-buildable per-package artifact path under\n * `<rootDir>/packages/*`, preferring the published `dist/smrt-knowledge.json`\n * over the local dev `.smrt/smrt-knowledge.json` when both exist. Shared by\n * the generator (which needs the manifest content) and the freshness check\n * (which only needs to know whether the current SET of artifacts matches\n * what the graph was built from — a newly built package, or a package that\n * newly started exporting `./smrt-knowledge.json`, must mark the graph stale\n * even though every artifact the graph already knows about is unchanged).\n */\nexport function discoverKnowledgeArtifactPaths(rootDir: string): string[] {\n  const packagesDir = join(rootDir, 'packages');\n  if (!existsSync(packagesDir)) return [];\n  const paths: string[] = [];\n  for (const entry of readdirSync(packagesDir, { withFileTypes: true })) {\n    if (!entry.isDirectory()) continue;\n    const packageDir = join(packagesDir, entry.name);\n    const candidates = [\n      join(packageDir, 'dist', 'smrt-knowledge.json'),\n      join(packageDir, '.smrt', 'smrt-knowledge.json'),\n    ];\n    const found = candidates.find((path) => existsSync(path));\n    if (found) paths.push(relative(rootDir, found).split('\\\\').join('/'));\n  }\n  return paths.sort();\n}\n\n/** One package's `smrt-knowledge.json`, located relative to the graph root. */\nexport interface KnowledgeGraphInput {\n  /** Path to the artifact, relative to the repo root, POSIX-separated. */\n  artifactPath: string;\n  manifest: DomainKnowledgeManifest;\n}\n\nexport interface KnowledgeGraphPackageNode {\n  name: string;\n  version?: string;\n  artifactPath: string;\n  tags: string[];\n  risks: string[];\n  summary?: string;\n  objectCount: number;\n}\n\nexport interface KnowledgeGraphObjectNode {\n  /** `<packageName>#<qualifiedName-or-name>`, this graph's stable object id. */\n  id: string;\n  packageName: string;\n  name: string;\n  qualifiedName?: string;\n  collection: string;\n  tableName?: string;\n  tableStrategy?: 'cti' | 'sti';\n  extends?: string;\n}\n\nexport type KnowledgeGraphEdgeType =\n  | 'crossPackageRef'\n  | 'sti'\n  | 'junction'\n  | 'hierarchical'\n  | 'polymorphic'\n  | 'systemTable';\n\nexport interface KnowledgeGraphEdge {\n  type: KnowledgeGraphEdgeType;\n  /** Object id (or `<packageName>#<extends>`-style unresolved target) this edge starts from. */\n  from: string;\n  /**\n   * Object id the edge points to when resolvable against a scanned object;\n   * otherwise the raw declared target (e.g. a qualified name this run did\n   * not scan), so the edge is still readable rather than dropped.\n   */\n  to?: string;\n  /** Declaring field name, for `crossPackageRef` edges. */\n  field?: string;\n}\n\nexport interface SmrtKnowledgeGraph {\n  schemaVersion: 1;\n  generatedAt: string;\n  /** `artifactPath -> sha256(content)`, sorted by key; the freshness input. */\n  sourceHashes: Record<string, string>;\n  packages: KnowledgeGraphPackageNode[];\n  objects: KnowledgeGraphObjectNode[];\n  edges: KnowledgeGraphEdge[];\n}\n\nfunction hashContent(content: string): string {\n  return createHash('sha256').update(content).digest('hex');\n}\n\nfunction objectId(packageName: string, object: DomainKnowledgeObject): string {\n  return `${packageName}#${object.qualifiedName ?? object.name}`;\n}\n\nexport interface BuildKnowledgeGraphOptions {\n  /**\n   * The graph currently on disk, when regenerating. `generatedAt` is\n   * preserved from it rather than reset to the clock whenever the rebuilt\n   * graph is otherwise semantically identical — the same pattern\n   * `preserveKnowledgeGeneratedAt` uses for per-package artifacts\n   * (`packages/core/src/vite-plugin/index.ts`) — so re-running the generator\n   * with nothing merged actually changed does not churn the file (#2872\n   * review).\n   */\n  previousGraph?: SmrtKnowledgeGraph;\n}\n\n/** Builds the merged graph. Deterministic: every array is sorted. */\nexport function buildKnowledgeGraph(\n  inputs: KnowledgeGraphInput[],\n  options: BuildKnowledgeGraphOptions = {},\n): SmrtKnowledgeGraph {\n  const sortedInputs = [...inputs].sort((a, b) =>\n    a.artifactPath.localeCompare(b.artifactPath),\n  );\n\n  const sourceHashes: Record<string, string> = {};\n  const packages: KnowledgeGraphPackageNode[] = [];\n  const objects: KnowledgeGraphObjectNode[] = [];\n  const edges: KnowledgeGraphEdge[] = [];\n\n  // Qualified-name -> object id, so a crossPackageRef/STI target declared in\n  // one package can be resolved to the node emitted by whichever package\n  // scanned it, regardless of scan order.\n  const idByQualifiedName = new Map<string, string>();\n  // Distinct ids per simple name, not a plain array: the same external\n  // object can appear in more than one input (e.g. a package artifact and a\n  // smrtConsumer aggregate that also scanned it), and counting the\n  // duplicate would make resolveTarget's `.length === 1` uniqueness check\n  // see a false ambiguity for an otherwise-unique name (#2872 review).\n  const idBySimpleName = new Map<string, Set<string>>();\n  // A `tableStrategy: 'sti'` object's `extends` is an unqualified simple name\n  // (its own package's base class, never a cross-package reference — STI\n  // shares one table within a package), so a same-package simple-name match\n  // must win over an ambiguous or wrong-package GLOBAL simple-name match:\n  // two packages both declaring `Account` must not point one package's\n  // subclass at the other package's `Account` (#2863 review).\n  const idBySimpleNamePerPackage = new Map<string, Map<string, string>>();\n\n  for (const input of sortedInputs) {\n    const manifestPackageName =\n      input.manifest.packageName ?? input.artifactPath;\n    for (const object of input.manifest.objects) {\n      // A merged consumer manifest (`smrtConsumer`) aggregates objects\n      // scanned from multiple external packages under one local artifact;\n      // each object then carries its own `packageName` and that must own\n      // the id, or every external object misattributes to the local\n      // project and edges resolve to the wrong node (#2872 review).\n      const packageName = object.packageName ?? manifestPackageName;\n      const perPackage =\n        idBySimpleNamePerPackage.get(packageName) ?? new Map<string, string>();\n      const id = objectId(packageName, object);\n      idByQualifiedName.set(object.qualifiedName ?? id, id);\n      const bySimple = idBySimpleName.get(object.name) ?? new Set<string>();\n      bySimple.add(id);\n      idBySimpleName.set(object.name, bySimple);\n      perPackage.set(object.name, id);\n      idBySimpleNamePerPackage.set(packageName, perPackage);\n    }\n  }\n\n  const resolveTarget = (\n    raw: string | undefined,\n    declaringPackageName?: string,\n  ): string | undefined => {\n    if (!raw) return undefined;\n    if (idByQualifiedName.has(raw)) return idByQualifiedName.get(raw);\n    if (declaringPackageName) {\n      const sameId = idBySimpleNamePerPackage\n        .get(declaringPackageName)\n        ?.get(raw);\n      if (sameId) return sameId;\n    }\n    const bySimple = idBySimpleName.get(raw);\n    if (bySimple && bySimple.size === 1) return [...bySimple][0];\n    return undefined;\n  };\n\n  const seenObjectIds = new Set<string>();\n  for (const input of sortedInputs) {\n    sourceHashes[input.artifactPath] = hashContent(\n      stableStringify(input.manifest),\n    );\n    const packageName = input.manifest.packageName ?? input.artifactPath;\n\n    packages.push({\n      name: packageName,\n      version: input.manifest.packageVersion,\n      artifactPath: input.artifactPath,\n      tags: [...input.manifest.tags].sort(),\n      risks: [...input.manifest.risks].sort(),\n      summary: input.manifest.summary,\n      objectCount: input.manifest.objects.length,\n    });\n\n    for (const object of input.manifest.objects) {\n      // See the id-map pass above: an aggregated consumer manifest attributes\n      // each object to its own scanned package, not the local project.\n      const objectPackageName = object.packageName ?? packageName;\n      const id = objectId(objectPackageName, object);\n      if (!seenObjectIds.has(id)) {\n        seenObjectIds.add(id);\n        objects.push({\n          id,\n          packageName: objectPackageName,\n          name: object.name,\n          qualifiedName: object.qualifiedName,\n          collection: object.collection,\n          tableName: object.tableName,\n          tableStrategy: object.tableStrategy,\n          extends: object.extends,\n        });\n      }\n\n      for (const field of object.relationships) {\n        if (field.type !== 'crossPackageRef') continue;\n        edges.push({\n          type: 'crossPackageRef',\n          from: id,\n          to: resolveTarget(field.related) ?? field.related,\n          field: field.name,\n        });\n      }\n\n      if (object.tableStrategy === 'sti' && object.extends) {\n        edges.push({\n          type: 'sti',\n          from: id,\n          to:\n            resolveTarget(object.extends, objectPackageName) ??\n            `${objectPackageName}#${object.extends}`,\n        });\n      }\n\n      for (const feature of object.relationshipFeatures) {\n        if (feature === 'SmrtJunction') {\n          edges.push({ type: 'junction', from: id });\n        } else if (feature === 'SmrtHierarchical') {\n          edges.push({ type: 'hierarchical', from: id });\n        } else if (feature === 'SmrtPolymorphicAssociation') {\n          edges.push({ type: 'polymorphic', from: id });\n        }\n      }\n\n      if (object.tableName?.startsWith('_smrt_')) {\n        edges.push({ type: 'systemTable', from: id, to: object.tableName });\n      }\n    }\n  }\n\n  packages.sort((a, b) => a.name.localeCompare(b.name));\n  objects.sort((a, b) => a.id.localeCompare(b.id));\n  edges.sort((a, b) => {\n    const key = (edge: KnowledgeGraphEdge) =>\n      `${edge.type}|${edge.from}|${edge.to ?? ''}|${edge.field ?? ''}`;\n    return key(a).localeCompare(key(b));\n  });\n\n  const graph: SmrtKnowledgeGraph = {\n    schemaVersion: 1,\n    generatedAt: new Date().toISOString(),\n    sourceHashes: sortRecord(sourceHashes),\n    packages,\n    objects,\n    edges,\n  };\n\n  const { previousGraph } = options;\n  if (\n    previousGraph &&\n    semanticGraphJson(previousGraph) === semanticGraphJson(graph)\n  ) {\n    return { ...graph, generatedAt: previousGraph.generatedAt };\n  }\n  return graph;\n}\n\nfunction semanticGraphJson(graph: SmrtKnowledgeGraph): string {\n  const { generatedAt: _generatedAt, ...rest } = graph;\n  return stableStringify(rest);\n}\n\n/** Deterministic `JSON.stringify` — object keys are sorted at every level. */\nexport function stableStringify(value: unknown): string {\n  return JSON.stringify(sortValue(value));\n}\n\nfunction sortValue(value: unknown): unknown {\n  if (Array.isArray(value)) return value.map(sortValue);\n  if (value && typeof value === 'object') {\n    const sorted: Record<string, unknown> = {};\n    for (const key of Object.keys(value as Record<string, unknown>).sort()) {\n      sorted[key] = sortValue((value as Record<string, unknown>)[key]);\n    }\n    return sorted;\n  }\n  return value;\n}\n\nfunction sortRecord(record: Record<string, string>): Record<string, string> {\n  const sorted: Record<string, string> = {};\n  for (const key of Object.keys(record).sort()) sorted[key] = record[key];\n  return sorted;\n}\n\nexport interface KnowledgeGraphFreshnessIssue {\n  severity: 'error' | 'warning';\n  code:\n    | 'missing-knowledge-graph'\n    | 'stale-knowledge-graph'\n    | 'knowledge-graph-source-missing';\n  message: string;\n  file?: string;\n}\n\n/**\n * Checks the merged graph's recorded `sourceHashes` against the current\n * content of each per-package artifact it was built from — the same pattern\n * `knowledge.ts`/`smrt-dev-mcp` use for a single package's `sourceHashes`.\n *\n * `graphPath` and each `artifactPath` in the graph are resolved relative to\n * `rootDir` (the repo root).\n */\nexport function checkKnowledgeGraphFreshness(\n  rootDir: string,\n  graphPath: string,\n  options: { requireArtifact?: boolean } = {},\n): KnowledgeGraphFreshnessIssue[] {\n  const issues: KnowledgeGraphFreshnessIssue[] = [];\n  const absoluteGraphPath = `${rootDir}/${graphPath}`;\n  if (!existsSync(absoluteGraphPath)) {\n    if (!options.requireArtifact) return issues;\n    issues.push({\n      severity: 'error',\n      code: 'missing-knowledge-graph',\n      message: `${graphPath} does not exist; run \\`pnpm knowledge:graph\\``,\n      file: graphPath,\n    });\n    return issues;\n  }\n\n  let graph: SmrtKnowledgeGraph;\n  try {\n    graph = JSON.parse(readFileSync(absoluteGraphPath, 'utf8'));\n  } catch (error) {\n    issues.push({\n      severity: 'error',\n      code: 'stale-knowledge-graph',\n      message: `${graphPath} is not valid JSON: ${\n        error instanceof Error ? error.message : String(error)\n      }`,\n      file: graphPath,\n    });\n    return issues;\n  }\n\n  const recordedPaths = Object.keys(graph.sourceHashes ?? {});\n  for (const [artifactPath, expectedHash] of Object.entries(\n    graph.sourceHashes ?? {},\n  )) {\n    const absoluteArtifactPath = `${rootDir}/${artifactPath}`;\n    if (!existsSync(absoluteArtifactPath)) {\n      issues.push({\n        severity: 'error',\n        code: 'knowledge-graph-source-missing',\n        message: `${artifactPath} used to build ${graphPath} no longer exists`,\n        file: graphPath,\n      });\n      continue;\n    }\n    let manifest: unknown;\n    try {\n      manifest = JSON.parse(readFileSync(absoluteArtifactPath, 'utf8'));\n    } catch (error) {\n      issues.push({\n        severity: 'error',\n        code: 'stale-knowledge-graph',\n        message: `${artifactPath} is not valid JSON (${\n          error instanceof Error ? error.message : String(error)\n        }); run \\`pnpm knowledge:graph\\``,\n        file: graphPath,\n      });\n      continue;\n    }\n    const actualHash = hashContent(stableStringify(manifest));\n    if (actualHash !== expectedHash) {\n      issues.push({\n        severity: 'error',\n        code: 'stale-knowledge-graph',\n        message: `${artifactPath} changed since ${graphPath} was generated; run \\`pnpm knowledge:graph\\``,\n        file: graphPath,\n      });\n    }\n  }\n\n  // A per-key hash comparison alone cannot see an ADDED artifact: a package\n  // that just finished its first build, or just started exporting\n  // `./smrt-knowledge.json`, contributes a path the graph never recorded, so\n  // every recorded hash still matches. Compare the current discoverable SET\n  // against the recorded set to catch that (#2863 review).\n  const currentPaths = discoverKnowledgeArtifactPaths(rootDir);\n  const recordedSet = new Set(recordedPaths);\n  const newPaths = currentPaths.filter((path) => !recordedSet.has(path));\n  if (newPaths.length > 0) {\n    issues.push({\n      severity: 'error',\n      code: 'stale-knowledge-graph',\n      message: `${newPaths.join(', ')} ${\n        newPaths.length === 1\n          ? 'is a new package artifact'\n          : 'are new package artifacts'\n      } not yet merged into ${graphPath}; run \\`pnpm knowledge:graph\\``,\n      file: graphPath,\n    });\n  }\n\n  return issues;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,SAAgB,+BAA+B,SAA2B;CACxE,MAAM,cAAc,KAAK,SAAS,UAAU;CAC5C,IAAI,CAAC,WAAW,WAAW,GAAG,OAAO,CAAC;CACtC,MAAM,QAAkB,CAAC;CACzB,KAAK,MAAM,SAAS,YAAY,aAAa,EAAE,eAAe,KAAK,CAAC,GAAG;EACrE,IAAI,CAAC,MAAM,YAAY,GAAG;EAC1B,MAAM,aAAa,KAAK,aAAa,MAAM,IAAI;EAK/C,MAAM,QAAQ,CAHZ,KAAK,YAAY,QAAQ,qBAAqB,GAC9C,KAAK,YAAY,SAAS,qBAAqB,CAEnC,CAAA,CAAW,MAAM,SAAS,WAAW,IAAI,CAAC;EACxD,IAAI,OAAO,MAAM,KAAK,SAAS,SAAS,KAAK,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC;CACtE;CACA,OAAO,MAAM,KAAK;AACpB;AA+DA,SAAS,YAAY,SAAyB;CAC5C,OAAO,WAAW,QAAQ,CAAC,CAAC,OAAO,OAAO,CAAC,CAAC,OAAO,KAAK;AAC1D;AAEA,SAAS,SAAS,aAAqB,QAAuC;CAC5E,OAAO,GAAG,YAAY,GAAG,OAAO,iBAAiB,OAAO;AAC1D;;AAgBA,SAAgB,oBACd,QACA,UAAsC,CAAC,GACnB;CACpB,MAAM,eAAe,CAAC,GAAG,MAAM,CAAC,CAAC,MAAM,GAAG,MACxC,EAAE,aAAa,cAAc,EAAE,YAAY,CAC7C;CAEA,MAAM,eAAuC,CAAC;CAC9C,MAAM,WAAwC,CAAC;CAC/C,MAAM,UAAsC,CAAC;CAC7C,MAAM,QAA8B,CAAC;CAKrC,MAAM,oCAAoB,IAAI,IAAoB;CAMlD,MAAM,iCAAiB,IAAI,IAAyB;CAOpD,MAAM,2CAA2B,IAAI,IAAiC;CAEtE,KAAK,MAAM,SAAS,cAAc;EAChC,MAAM,sBACJ,MAAM,SAAS,eAAe,MAAM;EACtC,KAAK,MAAM,UAAU,MAAM,SAAS,SAAS;GAM3C,MAAM,cAAc,OAAO,eAAe;GAC1C,MAAM,aACJ,yBAAyB,IAAI,WAAW,qBAAK,IAAI,IAAoB;GACvE,MAAM,KAAK,SAAS,aAAa,MAAM;GACvC,kBAAkB,IAAI,OAAO,iBAAiB,IAAI,EAAE;GACpD,MAAM,WAAW,eAAe,IAAI,OAAO,IAAI,qBAAK,IAAI,IAAY;GACpE,SAAS,IAAI,EAAE;GACf,eAAe,IAAI,OAAO,MAAM,QAAQ;GACxC,WAAW,IAAI,OAAO,MAAM,EAAE;GAC9B,yBAAyB,IAAI,aAAa,UAAU;EACtD;CACF;CAEA,MAAM,iBACJ,KACA,yBACuB;EACvB,IAAI,CAAC,KAAK,OAAO,KAAA;EACjB,IAAI,kBAAkB,IAAI,GAAG,GAAG,OAAO,kBAAkB,IAAI,GAAG;EAChE,IAAI,sBAAsB;GACxB,MAAM,SAAS,yBACZ,IAAI,oBAAoB,CAAC,EACxB,IAAI,GAAG;GACX,IAAI,QAAQ,OAAO;EACrB;EACA,MAAM,WAAW,eAAe,IAAI,GAAG;EACvC,IAAI,YAAY,SAAS,SAAS,GAAG,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC;CAE5D;CAEA,MAAM,gCAAgB,IAAI,IAAY;CACtC,KAAK,MAAM,SAAS,cAAc;EAChC,aAAa,MAAM,gBAAgB,YACjC,gBAAgB,MAAM,QAAQ,CAChC;EACA,MAAM,cAAc,MAAM,SAAS,eAAe,MAAM;EAExD,SAAS,KAAK;GACZ,MAAM;GACN,SAAS,MAAM,SAAS;GACxB,cAAc,MAAM;GACpB,MAAM,CAAC,GAAG,MAAM,SAAS,IAAI,CAAC,CAAC,KAAK;GACpC,OAAO,CAAC,GAAG,MAAM,SAAS,KAAK,CAAC,CAAC,KAAK;GACtC,SAAS,MAAM,SAAS;GACxB,aAAa,MAAM,SAAS,QAAQ;EACtC,CAAC;EAED,KAAK,MAAM,UAAU,MAAM,SAAS,SAAS;GAG3C,MAAM,oBAAoB,OAAO,eAAe;GAChD,MAAM,KAAK,SAAS,mBAAmB,MAAM;GAC7C,IAAI,CAAC,cAAc,IAAI,EAAE,GAAG;IAC1B,cAAc,IAAI,EAAE;IACpB,QAAQ,KAAK;KACX;KACA,aAAa;KACb,MAAM,OAAO;KACb,eAAe,OAAO;KACtB,YAAY,OAAO;KACnB,WAAW,OAAO;KAClB,eAAe,OAAO;KACtB,SAAS,OAAO;IAClB,CAAC;GACH;GAEA,KAAK,MAAM,SAAS,OAAO,eAAe;IACxC,IAAI,MAAM,SAAS,mBAAmB;IACtC,MAAM,KAAK;KACT,MAAM;KACN,MAAM;KACN,IAAI,cAAc,MAAM,OAAO,KAAK,MAAM;KAC1C,OAAO,MAAM;IACf,CAAC;GACH;GAEA,IAAI,OAAO,kBAAkB,SAAS,OAAO,SAC3C,MAAM,KAAK;IACT,MAAM;IACN,MAAM;IACN,IACE,cAAc,OAAO,SAAS,iBAAiB,KAC/C,GAAG,kBAAkB,GAAG,OAAO;GACnC,CAAC;GAGH,KAAK,MAAM,WAAW,OAAO,sBAC3B,IAAI,YAAY,gBACd,MAAM,KAAK;IAAE,MAAM;IAAY,MAAM;GAAG,CAAC;QACpC,IAAI,YAAY,oBACrB,MAAM,KAAK;IAAE,MAAM;IAAgB,MAAM;GAAG,CAAC;QACxC,IAAI,YAAY,8BACrB,MAAM,KAAK;IAAE,MAAM;IAAe,MAAM;GAAG,CAAC;GAIhD,IAAI,OAAO,WAAW,WAAW,QAAQ,GACvC,MAAM,KAAK;IAAE,MAAM;IAAe,MAAM;IAAI,IAAI,OAAO;GAAU,CAAC;EAEtE;CACF;CAEA,SAAS,MAAM,GAAG,MAAM,EAAE,KAAK,cAAc,EAAE,IAAI,CAAC;CACpD,QAAQ,MAAM,GAAG,MAAM,EAAE,GAAG,cAAc,EAAE,EAAE,CAAC;CAC/C,MAAM,MAAM,GAAG,MAAM;EACnB,MAAM,OAAO,SACX,GAAG,KAAK,KAAK,GAAG,KAAK,KAAK,GAAG,KAAK,MAAM,GAAG,GAAG,KAAK,SAAS;EAC9D,OAAO,IAAI,CAAC,CAAC,CAAC,cAAc,IAAI,CAAC,CAAC;CACpC,CAAC;CAED,MAAM,QAA4B;EAChC,eAAe;EACf,8BAAa,IAAI,KAAK,EAAA,CAAE,YAAY;EACpC,cAAc,WAAW,YAAY;EACrC;EACA;EACA;CACF;CAEA,MAAM,EAAE,kBAAkB;CAC1B,IACE,iBACA,kBAAkB,aAAa,MAAM,kBAAkB,KAAK,GAE5D,OAAO;EAAE,GAAG;EAAO,aAAa,cAAc;CAAY;CAE5D,OAAO;AACT;AAEA,SAAS,kBAAkB,OAAmC;CAC5D,MAAM,EAAE,aAAa,cAAc,GAAG,SAAS;CAC/C,OAAO,gBAAgB,IAAI;AAC7B;;AAGA,SAAgB,gBAAgB,OAAwB;CACtD,OAAO,KAAK,UAAU,UAAU,KAAK,CAAC;AACxC;AAEA,SAAS,UAAU,OAAyB;CAC1C,IAAI,MAAM,QAAQ,KAAK,GAAG,OAAO,MAAM,IAAI,SAAS;CACpD,IAAI,SAAS,OAAO,UAAU,UAAU;EACtC,MAAM,SAAkC,CAAC;EACzC,KAAK,MAAM,OAAO,OAAO,KAAK,KAAgC,CAAC,CAAC,KAAK,GACnE,OAAO,OAAO,UAAW,MAAkC,IAAI;EAEjE,OAAO;CACT;CACA,OAAO;AACT;AAEA,SAAS,WAAW,QAAwD;CAC1E,MAAM,SAAiC,CAAC;CACxC,KAAK,MAAM,OAAO,OAAO,KAAK,MAAM,CAAC,CAAC,KAAK,GAAG,OAAO,OAAO,OAAO;CACnE,OAAO;AACT;;;;;;;;;AAoBA,SAAgB,6BACd,SACA,WACA,UAAyC,CAAC,GACV;CAChC,MAAM,SAAyC,CAAC;CAChD,MAAM,oBAAoB,GAAG,QAAQ,GAAG;CACxC,IAAI,CAAC,WAAW,iBAAiB,GAAG;EAClC,IAAI,CAAC,QAAQ,iBAAiB,OAAO;EACrC,OAAO,KAAK;GACV,UAAU;GACV,MAAM;GACN,SAAS,GAAG,UAAU;GACtB,MAAM;EACR,CAAC;EACD,OAAO;CACT;CAEA,IAAI;CACJ,IAAI;EACF,QAAQ,KAAK,MAAM,aAAa,mBAAmB,MAAM,CAAC;CAC5D,SAAS,OAAO;EACd,OAAO,KAAK;GACV,UAAU;GACV,MAAM;GACN,SAAS,GAAG,UAAU,sBACpB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;GAEvD,MAAM;EACR,CAAC;EACD,OAAO;CACT;CAEA,MAAM,gBAAgB,OAAO,KAAK,MAAM,gBAAgB,CAAC,CAAC;CAC1D,KAAK,MAAM,CAAC,cAAc,iBAAiB,OAAO,QAChD,MAAM,gBAAgB,CAAC,CACzB,GAAG;EACD,MAAM,uBAAuB,GAAG,QAAQ,GAAG;EAC3C,IAAI,CAAC,WAAW,oBAAoB,GAAG;GACrC,OAAO,KAAK;IACV,UAAU;IACV,MAAM;IACN,SAAS,GAAG,aAAa,iBAAiB,UAAU;IACpD,MAAM;GACR,CAAC;GACD;EACF;EACA,IAAI;EACJ,IAAI;GACF,WAAW,KAAK,MAAM,aAAa,sBAAsB,MAAM,CAAC;EAClE,SAAS,OAAO;GACd,OAAO,KAAK;IACV,UAAU;IACV,MAAM;IACN,SAAS,GAAG,aAAa,sBACvB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,EACtD;IACD,MAAM;GACR,CAAC;GACD;EACF;EAEA,IADmB,YAAY,gBAAgB,QAAQ,CACnD,MAAe,cACjB,OAAO,KAAK;GACV,UAAU;GACV,MAAM;GACN,SAAS,GAAG,aAAa,iBAAiB,UAAU;GACpD,MAAM;EACR,CAAC;CAEL;CAOA,MAAM,eAAe,+BAA+B,OAAO;CAC3D,MAAM,cAAc,IAAI,IAAI,aAAa;CACzC,MAAM,WAAW,aAAa,QAAQ,SAAS,CAAC,YAAY,IAAI,IAAI,CAAC;CACrE,IAAI,SAAS,SAAS,GACpB,OAAO,KAAK;EACV,UAAU;EACV,MAAM;EACN,SAAS,GAAG,SAAS,KAAK,IAAI,EAAE,GAC9B,SAAS,WAAW,IAChB,8BACA,4BACL,uBAAuB,UAAU;EAClC,MAAM;CACR,CAAC;CAGH,OAAO;AACT"}

package/dist/knowledge.d.ts

@@ -1,6 +1,7 @@
 import { DomainKnowledgeAgentSurface, DomainKnowledgeConfig, DomainKnowledgeManifest, DomainKnowledgeModuleDoc } from '@happyvertical/smrt-types';
 import { SmartObjectManifest } from './scanner/types.js';
 export { discoverScopedPackageDirectories, readPackageAgentDoc, type ScopedPackageDirectory, } from './knowledge-discovery.js';
+export { buildKnowledgeGraph, checkKnowledgeGraphFreshness, discoverKnowledgeArtifactPaths, type KnowledgeGraphEdge, type KnowledgeGraphEdgeType, type KnowledgeGraphFreshnessIssue, type KnowledgeGraphInput, type KnowledgeGraphObjectNode, type KnowledgeGraphPackageNode, type SmrtKnowledgeGraph, stableStringify, } from './knowledge-graph.js';
 /**
  * Minimal package.json shape consumed by the knowledge builder.
  * `name`/`version` are typed concretely because they flow into the manifest's

package/dist/knowledge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../src/knowledge.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gCAAgC,EAChC,mBAAmB,EACnB,KAAK,sBAAsB,GAC5B,MAAM,0BAA0B,CAAC;AAKlC,OAAO,KAAK,EACV,2BAA2B,EAC3B,qBAAqB,EAGrB,uBAAuB,EAEvB,wBAAwB,EAKzB,MAAM,2BAA2B,CAAC;AAanC,OAAO,KAAK,EAEV,mBAAmB,EACpB,MAAM,oBAAoB,CAAC;AAG5B;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,2BAA2B,CAAC;CAC5C;AAmDD,yFAAyF;AACzF,eAAO,MAAM,sBAAsB,eAAe,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,yBAAyB,kBAAkB,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,MAAM,EAAE,CAgBV;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,wBAAwB,EAAE,CAM5B;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,2BAA2B,GACnC,uBAAuB,CAkFzB"}
+{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../src/knowledge.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gCAAgC,EAChC,mBAAmB,EACnB,KAAK,sBAAsB,GAC5B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,mBAAmB,EACnB,4BAA4B,EAC5B,8BAA8B,EAC9B,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,4BAA4B,EACjC,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,kBAAkB,EACvB,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAK9B,OAAO,KAAK,EACV,2BAA2B,EAC3B,qBAAqB,EAGrB,uBAAuB,EAEvB,wBAAwB,EAKzB,MAAM,2BAA2B,CAAC;AAanC,OAAO,KAAK,EAEV,mBAAmB,EACpB,MAAM,oBAAoB,CAAC;AAG5B;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,2BAA2B,CAAC;CAC5C;AAmDD,yFAAyF;AACzF,eAAO,MAAM,sBAAsB,eAAe,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,yBAAyB,kBAAkB,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,MAAM,EAAE,CAgBV;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,wBAAwB,EAAE,CAM5B;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,2BAA2B,GACnC,uBAAuB,CA0FzB"}

package/dist/knowledge.js

@@ -2,6 +2,7 @@ import { toSnakeCase } from "./utils/naming.js";
 import { CRUD_OPERATIONS, createManifestClassNamePredicate, isCrudOperation, isCrudToolAction, isFrameworkLifecycleMethod, resolveApiMethodExposure, resolveCustomActionMetadata, resolveEffectiveActionMetadata } from "./generators/custom-action.js";
 import { isFrameworkBaseClass } from "./registry/framework-base-classes.js";
 import { discoverScopedPackageDirectories, readPackageAgentDoc } from "./knowledge-discovery.js";
+import { buildKnowledgeGraph, checkKnowledgeGraphFreshness, discoverKnowledgeArtifactPaths, stableStringify } from "./knowledge-graph.js";
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { basename, join, relative, resolve, sep } from "node:path";
@@ -113,6 +114,7 @@ function buildDomainKnowledgeManifest(options) {
 	const surfaces = objects.flatMap((object) => object.surfaces);
 	const manifestJson = stableJson(normalizeManifestForHash(options.manifest));
 	const agentSurface = normalizeAgentSurface(options.agentSurface);
+	const relationshipsV2 = summarizeRelationships(objects, manifestObjects);
 	return {
 		schemaVersion: 1,
 		sensitiveFieldsExcluded: true,
@@ -132,13 +134,17 @@ function buildDomainKnowledgeManifest(options) {
 		dependencies: allDependencies,
 		smrtDependencies: Object.keys(allDependencies).filter((dep) => dep.startsWith("@happyvertical/smrt-")).sort(),
 		sdkDependencies: Object.keys(allDependencies).filter((dep) => SDK_PACKAGE_NAMES.has(dep)).sort(),
-		tags: options.config?.tags ?? [],
+		tags: options.config?.tags ?? deriveDefaultTags(packageJson, allDependencies),
 		summary: options.config?.summary,
-		risks: options.config?.risks ?? [],
+		risks: options.config?.risks ?? deriveDefaultRisks({
+			sensitiveFieldsExcluded: true,
+			relationshipsV2,
+			objects
+		}),
 		objects,
 		surfaces,
 		prompts: options.config?.includePrompts === false ? [] : readPrompts(rootDir),
-		relationshipsV2: summarizeRelationships(objects, manifestObjects),
+		relationshipsV2,
 		agentDoc,
 		moduleDocs: includeDocs && moduleDocPaths.length > 0 ? readAgentModuleDocs(rootDir, agentDocContent) : void 0,
 		agentSurface
@@ -681,6 +687,53 @@ function summarizeRelationships(objects, manifestObjects) {
 		uuidColumns: manifestObjects.reduce((count, object) => count + Object.values(object.schema?.columns ?? {}).filter((column) => column.type === "UUID").length, 0)
 	};
 }
+/**
+* Documented default `tags` derivation for a package's domain-knowledge
+* artifact when `@smrt({ knowledge: { tags } })` is not set (#2863).
+*
+* Never invents taxonomy: tags come only from `package.json#keywords`
+* (authored by the package owner) plus a `cross-package` tag when the
+* package declares a `@happyvertical/smrt-*` dependency. This keeps the
+* derivation deterministic and traceable to an authored source, matching
+* the "populate tags/risks from scanner output where the manifest carries
+* the data" scope — a package that wants richer tags still sets
+* `knowledge.tags` explicitly.
+*/
+function deriveDefaultTags(packageJson, allDependencies) {
+	const tags = /* @__PURE__ */ new Set();
+	const keywords = packageJson.keywords;
+	if (Array.isArray(keywords)) {
+		for (const keyword of keywords) if (typeof keyword === "string" && keyword.trim()) tags.add(keyword.trim());
+	}
+	if (Object.keys(allDependencies).some((dep) => dep.startsWith("@happyvertical/smrt-"))) tags.add("cross-package");
+	return [...tags].sort();
+}
+/**
+* Documented default `risks` derivation (#2863). Each entry names a
+* structural fact the manifest already carries — never freeform prose — so
+* it stays deterministic and regenerable:
+*
+* - `sensitive-fields-excluded`: generation always strips sensitive fields
+*   before projecting objects (`sensitiveFieldsExcluded` is unconditionally
+*   `true`), so a reviewer relying on this artifact must not treat it as a
+*   complete field inventory.
+* - `cross-package-refs:<n>`: the package reads or writes another package's
+*   rows through `@crossPackageRef`; a reviewer must check that package's
+*   tenancy and lifecycle guarantees too.
+* - `sti-inheritance`: at least one object shares a table via
+*   `tableStrategy: 'sti'`; a schema change must consider every sibling.
+* - `polymorphic-associations:<n>`: at least one
+*   `SmrtPolymorphicAssociation`, whose target type is resolved at read time
+*   rather than by a foreign key constraint.
+*/
+function deriveDefaultRisks(options) {
+	const risks = /* @__PURE__ */ new Set();
+	if (options.sensitiveFieldsExcluded) risks.add("sensitive-fields-excluded");
+	if (options.relationshipsV2.crossPackageRefFields > 0) risks.add(`cross-package-refs:${options.relationshipsV2.crossPackageRefFields}`);
+	if (options.objects.some((object) => object.tableStrategy === "sti")) risks.add("sti-inheritance");
+	if (options.relationshipsV2.polymorphicAssociations > 0) risks.add(`polymorphic-associations:${options.relationshipsV2.polymorphicAssociations}`);
+	return [...risks].sort();
+}
 function columnType(object, fieldName) {
 	const columnName = camelToSnake(fieldName);
 	return object.schema?.columns[columnName]?.type;
@@ -757,6 +810,6 @@ function sortJson(value) {
 	return value;
 }
 //#endregion
-export { AGENT_SURFACE_HASH_PREFIX, MODULE_DOC_HASH_PREFIX, buildDomainKnowledgeManifest, discoverScopedPackageDirectories, readAgentModuleDocs, readPackageAgentDoc, resolveAgentModuleDocPaths };
+export { AGENT_SURFACE_HASH_PREFIX, MODULE_DOC_HASH_PREFIX, buildDomainKnowledgeManifest, buildKnowledgeGraph, checkKnowledgeGraphFreshness, discoverKnowledgeArtifactPaths, discoverScopedPackageDirectories, readAgentModuleDocs, readPackageAgentDoc, resolveAgentModuleDocPaths, stableStringify };
 
 //# sourceMappingURL=knowledge.js.map