@principal-ai/subsystems-core 0.51.3 → 0.51.4

package/README.md

@@ -9,6 +9,12 @@ Subsystem model types/schema and agent-session tooling for Principal AI.
 | `@principal-ai/subsystems-core` | Browser-safe subsystem model/topic types, reference links + `isSubsystemModelDocument` |
 | `@principal-ai/subsystems-core/node` | OpenCode store, agent-session list/fetch/normalize, topic store, fixtures |
 | `@principal-ai/subsystems-core/pipeline` | Bun-safe session normalize/accumulate (no `better-sqlite3`) |
+| `@principal-ai/subsystems-core/audit` | Audit-facing Graphify provider contract and per-pass graph-load cache |
+
+The audit entry point deliberately defines a port rather than selecting a
+Graphify transport. A caller can supply local extraction/cache or a future MCP
+adapter. The shared audit engine and its persistence/repository adapters are
+being extracted separately; this entry point alone does not run an audit.
 
 ## Schema
 

package/dist/audit/graphify-provider.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Graphify port used by subsystem-model audits.
+ *
+ * The audit should depend on graph data and freshness semantics, not on how a
+ * graph was produced or served. Implementations may read the local cache, run
+ * Graphify on demand, or call a Graphify MCP service.
+ */
+export interface GraphifyAuditModel {
+    components: Array<{
+        purl?: string;
+        construct?: string;
+    }>;
+}
+export interface GraphifyAuditEnsureResult {
+    ensured: string[];
+    failed: Array<{
+        purl: string;
+        error: string;
+    }>;
+}
+export interface GraphifyAuditPurlReadiness {
+    purl: string;
+    status: 'ready' | 'missing' | 'building' | 'unavailable';
+    repoRoot?: string;
+}
+export interface GraphifyAuditReadiness {
+    status: 'possible' | 'partial' | 'not_ready' | 'running' | 'unavailable';
+    purls: GraphifyAuditPurlReadiness[];
+}
+export interface GraphifyAuditSnapshot {
+    nodes: unknown[];
+    edges: unknown[];
+}
+export interface GraphifyAuditProvider {
+    /** Ensure current-HEAD(+dirty) graphs for the model's local repositories. */
+    ensureCurrent(model: GraphifyAuditModel): Promise<GraphifyAuditEnsureResult>;
+    /** Describe current-HEAD(+dirty) graph availability without building. */
+    readiness(model: GraphifyAuditModel, buildingPurls?: ReadonlySet<string>): Promise<GraphifyAuditReadiness>;
+    /** Resolve a repo PURL to a local checkout, when one is available. */
+    resolveRepoRoot(purl: string): string | null;
+    /** Load the graph for a PURL after ensure/readiness has been checked. */
+    loadGraph(purl: string, options?: {
+        repoRoot?: string;
+    }): Promise<GraphifyAuditSnapshot | null>;
+}
+/**
+ * Keep one Graphify read/parse per repository for a single audit pass.
+ * Rejected reads are evicted so a later attempt can recover.
+ */
+export declare function cacheGraphifyAuditProvider(provider: GraphifyAuditProvider): GraphifyAuditProvider;
+//# sourceMappingURL=graphify-provider.d.ts.map

package/dist/audit/graphify-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphify-provider.d.ts","sourceRoot":"","sources":["../../src/audit/graphify-provider.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,KAAK,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,SAAS,CAAC,EAAE,MAAM,CAAA;KACnB,CAAC,CAAA;CACH;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC/C;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,UAAU,GAAG,aAAa,CAAA;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,aAAa,CAAA;IACxE,KAAK,EAAE,0BAA0B,EAAE,CAAA;CACpC;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,OAAO,EAAE,CAAA;IAChB,KAAK,EAAE,OAAO,EAAE,CAAA;CACjB;AAED,MAAM,WAAW,qBAAqB;IACpC,6EAA6E;IAC7E,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAA;IAC5E,yEAAyE;IACzE,SAAS,CACP,KAAK,EAAE,kBAAkB,EACzB,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAClC,OAAO,CAAC,sBAAsB,CAAC,CAAA;IAClC,sEAAsE;IACtE,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IAC5C,yEAAyE;IACzE,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAC9B,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAA;CACzC;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,qBAAqB,GAC9B,qBAAqB,CAiBvB"}

package/dist/audit/graphify-provider.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Graphify port used by subsystem-model audits.
+ *
+ * The audit should depend on graph data and freshness semantics, not on how a
+ * graph was produced or served. Implementations may read the local cache, run
+ * Graphify on demand, or call a Graphify MCP service.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cacheGraphifyAuditProvider = void 0;
+/**
+ * Keep one Graphify read/parse per repository for a single audit pass.
+ * Rejected reads are evicted so a later attempt can recover.
+ */
+function cacheGraphifyAuditProvider(provider) {
+    const snapshots = new Map();
+    return {
+        ensureCurrent: (model) => provider.ensureCurrent(model),
+        readiness: (model, buildingPurls) => provider.readiness(model, buildingPurls),
+        resolveRepoRoot: (purl) => provider.resolveRepoRoot(purl),
+        loadGraph(purl, options) {
+            const existing = snapshots.get(purl);
+            if (existing)
+                return existing;
+            const pending = provider.loadGraph(purl, options);
+            snapshots.set(purl, pending);
+            void pending.catch(() => {
+                if (snapshots.get(purl) === pending)
+                    snapshots.delete(purl);
+            });
+            return pending;
+        },
+    };
+}
+exports.cacheGraphifyAuditProvider = cacheGraphifyAuditProvider;
+//# sourceMappingURL=graphify-provider.js.map

package/dist/audit/graphify-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphify-provider.js","sourceRoot":"","sources":["../../src/audit/graphify-provider.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AA+CH;;;GAGG;AACH,SAAgB,0BAA0B,CACxC,QAA+B;IAE/B,MAAM,SAAS,GAAG,IAAI,GAAG,EAAiD,CAAA;IAC1E,OAAO;QACL,aAAa,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC;QACvD,SAAS,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,aAAa,CAAC;QAC7E,eAAe,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,CAAC;QACzD,SAAS,CAAC,IAAI,EAAE,OAAO;YACrB,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;YACpC,IAAI,QAAQ;gBAAE,OAAO,QAAQ,CAAA;YAC7B,MAAM,OAAO,GAAG,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;YACjD,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;YAC5B,KAAK,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE;gBACtB,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,OAAO;oBAAE,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;YAC7D,CAAC,CAAC,CAAA;YACF,OAAO,OAAO,CAAA;QAChB,CAAC;KACF,CAAA;AACH,CAAC;AAnBD,gEAmBC"}

package/dist/audit/index.d.ts

@@ -0,0 +1,2 @@
+export { cacheGraphifyAuditProvider, type GraphifyAuditModel, type GraphifyAuditEnsureResult, type GraphifyAuditPurlReadiness, type GraphifyAuditReadiness, type GraphifyAuditSnapshot, type GraphifyAuditProvider, } from './graphify-provider';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,0BAA0B,EAC1B,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAA"}

package/dist/audit/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cacheGraphifyAuditProvider = void 0;
+var graphify_provider_1 = require("./graphify-provider");
+Object.defineProperty(exports, "cacheGraphifyAuditProvider", { enumerable: true, get: function () { return graphify_provider_1.cacheGraphifyAuditProvider; } });
+//# sourceMappingURL=index.js.map

package/dist/audit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":";;;AAAA,yDAQ4B;AAP1B,+HAAA,0BAA0B,OAAA"}

package/dist/index.d.ts

@@ -15,4 +15,5 @@ export type { DraftTopic, TopicAsset, TopicCreator, TopicSubsystemModelRef, Topi
 export { formatTopicReferenceLink, parseTopicReferenceLink } from './storage/topic-reference-links';
 export { validateSubsystemModelCrossField } from './validation';
 export type { SubsystemValidationProblem } from './validation';
+export * from './audit';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,SAAS,CAAC;AAExB,YAAY,EACV,UAAU,EACV,UAAU,EACV,YAAY,EACZ,sBAAsB,EACtB,cAAc,GACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAKpG,OAAO,EAAE,gCAAgC,EAAE,MAAM,cAAc,CAAC;AAChE,YAAY,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,SAAS,CAAC;AAExB,YAAY,EACV,UAAU,EACV,UAAU,EACV,YAAY,EACZ,sBAAsB,EACtB,cAAc,GACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAKpG,OAAO,EAAE,gCAAgC,EAAE,MAAM,cAAc,CAAC;AAChE,YAAY,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAI/D,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -36,4 +36,7 @@ Object.defineProperty(exports, "parseTopicReferenceLink", { enumerable: true, ge
 // `schemas/subsystem-model.schema.json`.
 var validation_1 = require("./validation");
 Object.defineProperty(exports, "validateSubsystemModelCrossField", { enumerable: true, get: function () { return validation_1.validateSubsystemModelCrossField; } });
+// Audit ports and graph-load caching are runtime-neutral; no Node or Graphify
+// dependencies are included here.
+__exportStar(require("./audit"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;;;;;;;;;;;;;;;AAEH,0CAAwB;AASxB,yEAAoG;AAA3F,iIAAA,wBAAwB,OAAA;AAAE,gIAAA,uBAAuB,OAAA;AAE1D,+EAA+E;AAC/E,sDAAsD;AACtD,yCAAyC;AACzC,2CAAgE;AAAvD,8HAAA,gCAAgC,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;;;;;;;;;;;;;;;AAEH,0CAAwB;AASxB,yEAAoG;AAA3F,iIAAA,wBAAwB,OAAA;AAAE,gIAAA,uBAAuB,OAAA;AAE1D,+EAA+E;AAC/E,sDAAsD;AACtD,yCAAyC;AACzC,2CAAgE;AAAvD,8HAAA,gCAAgC,OAAA;AAGzC,8EAA8E;AAC9E,kCAAkC;AAClC,0CAAwB"}

package/dist/node.d.ts

@@ -7,6 +7,7 @@
  * (no better-sqlite3 native binding).
  */
 export * from './types';
+export * from './audit';
 export { TopicStore, PRINCIPAL_DIR, TOPICS_DIR, LEGACY_TOPICS_BLOB, } from './storage/topicStore';
 export type { TopicIndexEntry, TopicCreate, TopicUpdate, MigrationResult, } from './storage/topicStore';
 export type { DraftTopic, TopicAsset, TopicCreator, TopicSubsystemModelRef, TopicReference, } from './storage/topic-types';

package/dist/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,SAAS,CAAC;AAGxB,OAAO,EACL,UAAU,EACV,aAAa,EACb,UAAU,EACV,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,eAAe,EACf,WAAW,EACX,WAAW,EACX,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,UAAU,EACV,UAAU,EACV,YAAY,EACZ,sBAAsB,EACtB,cAAc,GACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAGpG,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAC1F,YAAY,EACV,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,EACpB,cAAc,EACd,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3F,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,uBAAuB,EACvB,0BAA0B,EAC1B,wBAAwB,EACxB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EACL,4BAA4B,EAC5B,eAAe,EACf,0BAA0B,EAC1B,gBAAgB,EAChB,mBAAmB,EACnB,6BAA6B,GAC9B,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AAGxB,OAAO,EACL,UAAU,EACV,aAAa,EACb,UAAU,EACV,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,eAAe,EACf,WAAW,EACX,WAAW,EACX,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,UAAU,EACV,UAAU,EACV,YAAY,EACZ,sBAAsB,EACtB,cAAc,GACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAGpG,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAC1F,YAAY,EACV,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,EACpB,cAAc,EACd,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3F,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,uBAAuB,EACvB,0BAA0B,EAC1B,wBAAwB,EACxB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EACL,4BAA4B,EAC5B,eAAe,EACf,0BAA0B,EAC1B,gBAAgB,EAChB,mBAAmB,EACnB,6BAA6B,GAC9B,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/node.js

@@ -24,6 +24,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.opencodeRowsToUniversalEvents = exports.collectRepositories = exports.accumulateEvents = exports.normalizeEventsWithAdapter = exports.normalizeEvents = exports.NodePathNormalizationAdapter = exports.buildAgentSessionFixture = exports.fetchRawEvents = exports.detectAgent = exports.listAgentSessions = exports.defaultOpenCodeDBPath = exports.OpenCodeEventStore = exports.parseTopicReferenceLink = exports.formatTopicReferenceLink = exports.LEGACY_TOPICS_BLOB = exports.TOPICS_DIR = exports.PRINCIPAL_DIR = exports.TopicStore = void 0;
 __exportStar(require("./types"), exports);
+__exportStar(require("./audit"), exports);
 // File-per-topic store (~/.principal/topics) — node:fs only
 var topicStore_1 = require("./storage/topicStore");
 Object.defineProperty(exports, "TopicStore", { enumerable: true, get: function () { return topicStore_1.TopicStore; } });

package/dist/node.js.map

@@ -1 +1 @@
-{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;;;;;;;;;;;;;;;AAEH,0CAAwB;AAExB,4DAA4D;AAC5D,mDAK8B;AAJ5B,wGAAA,UAAU,OAAA;AACV,2GAAA,aAAa,OAAA;AACb,wGAAA,UAAU,OAAA;AACV,gHAAA,kBAAkB,OAAA;AAepB,yEAAoG;AAA3F,iIAAA,wBAAwB,OAAA;AAAE,gIAAA,uBAAuB,OAAA;AAE1D,mDAAmD;AACnD,oEAA0F;AAAjF,wHAAA,kBAAkB,OAAA;AAAE,2HAAA,qBAAqB,OAAA;AAUlD,iEAAiE;AACjE,4DAA2F;AAAlF,mHAAA,iBAAiB,OAAA;AAAE,6GAAA,WAAW,OAAA;AAAE,gHAAA,cAAc,OAAA;AAOvD,mDAAmD;AACnD,oDAAoE;AAA3D,mHAAA,wBAAwB,OAAA;AAWjC,sEAAsE;AACtE,gDAO6B;AAN3B,wHAAA,4BAA4B,OAAA;AAC5B,2GAAA,eAAe,OAAA;AACf,sHAAA,0BAA0B,OAAA;AAC1B,4GAAA,gBAAgB,OAAA;AAChB,+GAAA,mBAAmB,OAAA;AACnB,yHAAA,6BAA6B,OAAA"}
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;;;;;;;;;;;;;;;AAEH,0CAAwB;AACxB,0CAAwB;AAExB,4DAA4D;AAC5D,mDAK8B;AAJ5B,wGAAA,UAAU,OAAA;AACV,2GAAA,aAAa,OAAA;AACb,wGAAA,UAAU,OAAA;AACV,gHAAA,kBAAkB,OAAA;AAepB,yEAAoG;AAA3F,iIAAA,wBAAwB,OAAA;AAAE,gIAAA,uBAAuB,OAAA;AAE1D,mDAAmD;AACnD,oEAA0F;AAAjF,wHAAA,kBAAkB,OAAA;AAAE,2HAAA,qBAAqB,OAAA;AAUlD,iEAAiE;AACjE,4DAA2F;AAAlF,mHAAA,iBAAiB,OAAA;AAAE,6GAAA,WAAW,OAAA;AAAE,gHAAA,cAAc,OAAA;AAOvD,mDAAmD;AACnD,oDAAoE;AAA3D,mHAAA,wBAAwB,OAAA;AAWjC,sEAAsE;AACtE,gDAO6B;AAN3B,wHAAA,4BAA4B,OAAA;AAC5B,2GAAA,eAAe,OAAA;AACf,sHAAA,0BAA0B,OAAA;AAC1B,4GAAA,gBAAgB,OAAA;AAChB,+GAAA,mBAAmB,OAAA;AACnB,yHAAA,6BAA6B,OAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principal-ai/subsystems-core",
-  "version": "0.51.3",
+  "version": "0.51.4",
   "description": "Subsystem model types and agent-session tooling for Principal AI",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -23,6 +23,12 @@
       "require": "./dist/opencode/pipeline.js",
       "default": "./dist/opencode/pipeline.js"
     },
+    "./audit": {
+      "types": "./dist/audit/index.d.ts",
+      "import": "./dist/audit/index.js",
+      "require": "./dist/audit/index.js",
+      "default": "./dist/audit/index.js"
+    },
     "./schemas/subsystem-model.schema.json": "./schemas/subsystem-model.schema.json"
   },
   "files": [

package/src/audit/graphify-provider.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  cacheGraphifyAuditProvider,
+  type GraphifyAuditProvider,
+  type GraphifyAuditSnapshot,
+} from './graphify-provider'
+
+function provider(loadGraph: GraphifyAuditProvider["loadGraph"]): GraphifyAuditProvider {
+  return {
+    ensureCurrent: async () => ({ ensured: [], failed: [] }),
+    readiness: async () => ({ status: 'possible', purls: [] }),
+    resolveRepoRoot: () => null,
+    loadGraph,
+  }
+}
+
+describe('cacheGraphifyAuditProvider', () => {
+  test('deduplicates concurrent graph loads by PURL', async () => {
+    let loads = 0
+    let resolve!: (graph: GraphifyAuditSnapshot) => void
+    const source = provider(
+      () => {
+        loads++
+        return new Promise((done) => {
+          resolve = done
+        })
+      },
+    )
+    const cached = cacheGraphifyAuditProvider(source)
+    const first = cached.loadGraph('pkg:github/acme/app')
+    const second = cached.loadGraph('pkg:github/acme/app')
+
+    expect(loads).toBe(1)
+    const graph = { nodes: [], edges: [] }
+    resolve(graph)
+    expect(await first).toBe(graph)
+    expect(await second).toBe(graph)
+  })
+
+  test('evicts a rejected load so a later attempt can retry', async () => {
+    let loads = 0
+    const source = provider(async () => {
+      loads++
+      if (loads === 1) throw new Error('temporary read failure')
+      return { nodes: [], edges: [] }
+    })
+    const cached = cacheGraphifyAuditProvider(source)
+
+    await expect(cached.loadGraph('pkg:github/acme/app')).rejects.toThrow(
+      'temporary read failure',
+    )
+    expect(await cached.loadGraph('pkg:github/acme/app')).toEqual({
+      nodes: [],
+      edges: [],
+    })
+    expect(loads).toBe(2)
+  })
+})

package/src/audit/graphify-provider.ts

@@ -0,0 +1,77 @@
+/**
+ * Graphify port used by subsystem-model audits.
+ *
+ * The audit should depend on graph data and freshness semantics, not on how a
+ * graph was produced or served. Implementations may read the local cache, run
+ * Graphify on demand, or call a Graphify MCP service.
+ */
+
+export interface GraphifyAuditModel {
+  components: Array<{
+    purl?: string
+    construct?: string
+  }>
+}
+
+export interface GraphifyAuditEnsureResult {
+  ensured: string[]
+  failed: Array<{ purl: string; error: string }>
+}
+
+export interface GraphifyAuditPurlReadiness {
+  purl: string
+  status: 'ready' | 'missing' | 'building' | 'unavailable'
+  repoRoot?: string
+}
+
+export interface GraphifyAuditReadiness {
+  status: 'possible' | 'partial' | 'not_ready' | 'running' | 'unavailable'
+  purls: GraphifyAuditPurlReadiness[]
+}
+
+export interface GraphifyAuditSnapshot {
+  nodes: unknown[]
+  edges: unknown[]
+}
+
+export interface GraphifyAuditProvider {
+  /** Ensure current-HEAD(+dirty) graphs for the model's local repositories. */
+  ensureCurrent(model: GraphifyAuditModel): Promise<GraphifyAuditEnsureResult>
+  /** Describe current-HEAD(+dirty) graph availability without building. */
+  readiness(
+    model: GraphifyAuditModel,
+    buildingPurls?: ReadonlySet<string>,
+  ): Promise<GraphifyAuditReadiness>
+  /** Resolve a repo PURL to a local checkout, when one is available. */
+  resolveRepoRoot(purl: string): string | null
+  /** Load the graph for a PURL after ensure/readiness has been checked. */
+  loadGraph(
+    purl: string,
+    options?: { repoRoot?: string },
+  ): Promise<GraphifyAuditSnapshot | null>
+}
+
+/**
+ * Keep one Graphify read/parse per repository for a single audit pass.
+ * Rejected reads are evicted so a later attempt can recover.
+ */
+export function cacheGraphifyAuditProvider(
+  provider: GraphifyAuditProvider,
+): GraphifyAuditProvider {
+  const snapshots = new Map<string, Promise<GraphifyAuditSnapshot | null>>()
+  return {
+    ensureCurrent: (model) => provider.ensureCurrent(model),
+    readiness: (model, buildingPurls) => provider.readiness(model, buildingPurls),
+    resolveRepoRoot: (purl) => provider.resolveRepoRoot(purl),
+    loadGraph(purl, options) {
+      const existing = snapshots.get(purl)
+      if (existing) return existing
+      const pending = provider.loadGraph(purl, options)
+      snapshots.set(purl, pending)
+      void pending.catch(() => {
+        if (snapshots.get(purl) === pending) snapshots.delete(purl)
+      })
+      return pending
+    },
+  }
+}

package/src/audit/index.ts

@@ -0,0 +1,9 @@
+export {
+  cacheGraphifyAuditProvider,
+  type GraphifyAuditModel,
+  type GraphifyAuditEnsureResult,
+  type GraphifyAuditPurlReadiness,
+  type GraphifyAuditReadiness,
+  type GraphifyAuditSnapshot,
+  type GraphifyAuditProvider,
+} from './graphify-provider'

package/src/index.ts

@@ -27,3 +27,7 @@ export { formatTopicReferenceLink, parseTopicReferenceLink } from './storage/top
 // `schemas/subsystem-model.schema.json`.
 export { validateSubsystemModelCrossField } from './validation';
 export type { SubsystemValidationProblem } from './validation';
+
+// Audit ports and graph-load caching are runtime-neutral; no Node or Graphify
+// dependencies are included here.
+export * from './audit';

package/src/node.ts

@@ -8,6 +8,7 @@
  */
 
 export * from './types';
+export * from './audit';
 
 // File-per-topic store (~/.principal/topics) — node:fs only
 export {