d365fo-mcp 1.0.0

package/dist/database/download.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Azure Blob Storage Database Download Utility
+ * Downloads SQLite database from Azure Blob Storage on startup
+ */
+interface DownloadOptions {
+    connectionString?: string;
+    containerName?: string;
+    blobName?: string;
+    localPath?: string;
+    maxRetries?: number;
+    timeoutMs?: number;
+}
+export declare function downloadDatabaseFromBlob(options?: DownloadOptions): Promise<string>;
+/**
+ * Check local database version against blob storage
+ */
+export declare function checkDatabaseVersion(localPath: string, options?: DownloadOptions): Promise<{
+    needsUpdate: boolean;
+    localModified?: Date;
+    remoteModified?: Date;
+}>;
+/**
+ * Initialize database (download if needed)
+ */
+export declare function initializeDatabase(options?: DownloadOptions): Promise<string>;
+export {};
+//# sourceMappingURL=download.d.ts.map

package/dist/database/download.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../../src/database/download.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,UAAU,eAAe;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAyCD,wBAAsB,wBAAwB,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CA0JzF;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC;IAChG,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,IAAI,CAAC;IACrB,cAAc,CAAC,EAAE,IAAI,CAAC;CACvB,CAAC,CAsCD;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBnF"}

package/dist/database/download.js

@@ -0,0 +1,241 @@
+/**
+ * Azure Blob Storage Database Download Utility
+ * Downloads SQLite database from Azure Blob Storage on startup
+ */
+import { BlobServiceClient } from '@azure/storage-blob';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import Database from 'better-sqlite3';
+/**
+ * Validate SQLite database integrity
+ */
+async function validateDatabase(filePath) {
+    try {
+        const db = new Database(filePath, { readonly: true });
+        // quick_check is much faster than integrity_check and sufficient here.
+        const result = db.pragma('quick_check');
+        db.close();
+        return result.length === 1 && result[0].quick_check === 'ok';
+    }
+    catch (error) {
+        console.error(`   Database validation failed:`, error);
+        return false;
+    }
+}
+/**
+ * Sleep helper for retries
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Remove a SQLite temp file together with its companion -shm/-wal files, so a
+ * stale WAL is never replayed against a later temp file of the same name.
+ */
+async function cleanupTempFiles(tmpPath) {
+    for (const suffix of ['', '-shm', '-wal']) {
+        try {
+            await fs.unlink(`${tmpPath}${suffix}`);
+        }
+        catch {
+            // Ignore if file does not exist
+        }
+    }
+}
+export async function downloadDatabaseFromBlob(options) {
+    const connectionString = options?.connectionString || process.env.AZURE_STORAGE_CONNECTION_STRING;
+    const containerName = options?.containerName || process.env.BLOB_CONTAINER_NAME || 'xpp-metadata';
+    const blobName = options?.blobName || process.env.BLOB_DATABASE_NAME || 'databases/xpp-metadata-latest.db';
+    const localPath = options?.localPath || process.env.DB_PATH || './data/xpp-metadata.db';
+    const labelsDbPath = localPath.replace('.db', '-labels.db');
+    const maxRetries = options?.maxRetries || 3;
+    const timeoutMs = options?.timeoutMs || 300000;
+    if (!connectionString) {
+        throw new Error('Azure Storage connection string not configured');
+    }
+    console.log(`📥 Downloading databases from blob storage...`);
+    console.log(`   Container: ${containerName}`);
+    console.log(`   Symbols blob: ${blobName}`);
+    console.log(`   Symbols path: ${localPath}`);
+    console.log(`   Labels path: ${labelsDbPath}`);
+    console.log(`   Timeout: ${timeoutMs / 1000}s`);
+    const dir = path.dirname(localPath);
+    await fs.mkdir(dir, { recursive: true });
+    const tmpPath = `${localPath}.tmp`;
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        try {
+            console.log(`   Attempt ${attempt}/${maxRetries}...`);
+            await cleanupTempFiles(tmpPath);
+            const blobServiceClient = BlobServiceClient.fromConnectionString(connectionString);
+            const containerClient = blobServiceClient.getContainerClient(containerName);
+            const blobClient = containerClient.getBlobClient(blobName);
+            const exists = await blobClient.exists();
+            if (!exists) {
+                throw new Error(`Blob "${blobName}" not found in container "${containerName}"`);
+            }
+            const properties = await blobClient.getProperties();
+            const sizeInMB = ((properties.contentLength || 0) / (1024 * 1024)).toFixed(2);
+            console.log(`   Size: ${sizeInMB} MB`);
+            // AbortController stops the stream from writing past the deadline
+            // (Promise.race would leave it running and produce a corrupted temp file).
+            const startTime = Date.now();
+            const abortCtrl = new AbortController();
+            const timeoutId = setTimeout(() => abortCtrl.abort(), timeoutMs);
+            try {
+                await blobClient.downloadToFile(tmpPath, 0, undefined, {
+                    maxRetryRequests: 5,
+                    abortSignal: abortCtrl.signal,
+                });
+            }
+            catch (err) {
+                if (err.name === 'AbortError' || err.code === 'ERR_ABORTED') {
+                    throw new Error(`Download timeout after ${timeoutMs / 1000}s`);
+                }
+                throw err;
+            }
+            finally {
+                clearTimeout(timeoutId);
+            }
+            const duration = ((Date.now() - startTime) / 1000).toFixed(2);
+            console.log(`   Downloaded in ${duration}s`);
+            // Validate database integrity
+            console.log(`   Validating symbols database integrity...`);
+            const isValid = await validateDatabase(tmpPath);
+            if (!isValid) {
+                throw new Error('Downloaded symbols database is corrupted (failed integrity check)');
+            }
+            console.log(`   ✅ Symbols database validation passed`);
+            // Atomic move: rename temp to final
+            await fs.rename(tmpPath, localPath);
+            // Download labels database (separate file)
+            const labelsBlobName = blobName.replace('.db', '-labels.db').replace('xpp-metadata-latest', 'xpp-metadata-labels-latest');
+            const labelsBlobClient = containerClient.getBlobClient(labelsBlobName);
+            const labelsTmpPath = `${labelsDbPath}.tmp`;
+            console.log(`   📥 Downloading labels database...`);
+            try {
+                const labelsExists = await labelsBlobClient.exists();
+                if (labelsExists) {
+                    const labelsProperties = await labelsBlobClient.getProperties();
+                    const labelsSizeInMB = ((labelsProperties.contentLength || 0) / (1024 * 1024)).toFixed(2);
+                    console.log(`   Labels size: ${labelsSizeInMB} MB`);
+                    const labelsAbortCtrl = new AbortController();
+                    const labelsTimeoutId = setTimeout(() => labelsAbortCtrl.abort(), timeoutMs);
+                    try {
+                        await labelsBlobClient.downloadToFile(labelsTmpPath, 0, undefined, {
+                            abortSignal: labelsAbortCtrl.signal,
+                        });
+                    }
+                    catch (err) {
+                        if (err.name === 'AbortError' || err.code === 'ERR_ABORTED') {
+                            throw new Error(`Labels download timeout after ${timeoutMs / 1000}s`);
+                        }
+                        throw err;
+                    }
+                    finally {
+                        clearTimeout(labelsTimeoutId);
+                    }
+                    // Validate labels database
+                    console.log(`   Validating labels database integrity...`);
+                    const labelsIsValid = await validateDatabase(labelsTmpPath);
+                    if (!labelsIsValid) {
+                        throw new Error('Downloaded labels database is corrupted');
+                    }
+                    console.log(`   ✅ Labels database validation passed`);
+                    // Move to final location
+                    await fs.rename(labelsTmpPath, labelsDbPath);
+                    console.log(`   ✅ Labels database downloaded`);
+                }
+                else {
+                    console.log(`   ⚠️  Labels database not found (may be old single-DB format)`);
+                }
+            }
+            catch (labelsError) {
+                console.warn(`   ⚠️  Failed to download labels database: ${labelsError.message}`);
+                console.warn(`   Continuing with symbols database only (labels will not be available)`);
+                // Clean up labels temp file + companion SQLite WAL files
+                await cleanupTempFiles(labelsTmpPath);
+            }
+            console.log(`✅ Database download complete`);
+            return localPath;
+        }
+        catch (error) {
+            console.error(`   ❌ Attempt ${attempt} failed:`, error);
+            // Clean up temp file + companion SQLite WAL files.
+            // NEVER touch localPath here: the download writes only to tmpPath and
+            // renames after validation, so on any failure the previous database at
+            // localPath is still the last known-good copy — deleting it would turn a
+            // transient network outage into total data loss.
+            await cleanupTempFiles(tmpPath);
+            if (attempt === maxRetries) {
+                throw error;
+            }
+            // Wait before retry with exponential backoff
+            const backoffMs = Math.min(1000 * Math.pow(2, attempt - 1), 10000);
+            console.log(`   ⏳ Retrying in ${backoffMs / 1000}s...`);
+            await sleep(backoffMs);
+        }
+    }
+    throw new Error('Download failed after all retries');
+}
+/**
+ * Check local database version against blob storage
+ */
+export async function checkDatabaseVersion(localPath, options) {
+    const connectionString = options?.connectionString || process.env.AZURE_STORAGE_CONNECTION_STRING;
+    const containerName = options?.containerName || process.env.BLOB_CONTAINER_NAME || 'xpp-metadata';
+    const blobName = options?.blobName || process.env.BLOB_DATABASE_NAME || 'databases/xpp-metadata-latest.db';
+    if (!connectionString) {
+        return { needsUpdate: false };
+    }
+    try {
+        // Check local file
+        const localStats = await fs.stat(localPath);
+        const localModified = localStats.mtime;
+        // Check remote blob
+        const blobServiceClient = BlobServiceClient.fromConnectionString(connectionString);
+        const containerClient = blobServiceClient.getContainerClient(containerName);
+        const blobClient = containerClient.getBlobClient(blobName);
+        const properties = await blobClient.getProperties();
+        const remoteModified = properties.lastModified;
+        if (!remoteModified) {
+            return { needsUpdate: false, localModified };
+        }
+        // Compare timestamps
+        const needsUpdate = remoteModified > localModified;
+        return {
+            needsUpdate,
+            localModified,
+            remoteModified,
+        };
+    }
+    catch (error) {
+        // If local file doesn't exist, needs download
+        return { needsUpdate: true };
+    }
+}
+/**
+ * Initialize database (download if needed)
+ */
+export async function initializeDatabase(options) {
+    const localPath = options?.localPath || process.env.DB_PATH || './data/xpp-metadata.db';
+    // Check if we should use blob storage
+    const useBlob = !!process.env.AZURE_STORAGE_CONNECTION_STRING;
+    if (!useBlob) {
+        console.log('ℹ️  No Azure Storage connection configured, using local database');
+        return localPath;
+    }
+    // Check if update is needed
+    const versionCheck = await checkDatabaseVersion(localPath, options);
+    if (versionCheck.needsUpdate) {
+        console.log('🔄 Database update available or local file missing');
+        await downloadDatabaseFromBlob(options);
+    }
+    else {
+        console.log('✅ Local database is up to date');
+        if (versionCheck.localModified) {
+            console.log(`   Last modified: ${versionCheck.localModified.toISOString()}`);
+        }
+    }
+    return localPath;
+}
+//# sourceMappingURL=download.js.map

package/dist/database/download.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"download.js","sourceRoot":"","sources":["../../src/database/download.ts"],"names":[],"mappings":"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"}

package/dist/eval/audit/knowledgeAudit.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Knowledge-base audit (ROADMAP P1) — resolve every AOT reference extracted
+ * from KNOWLEDGE_BASE against the real symbol index, so knowledge content is
+ * gated the same fail-closed way generated code is.
+ *
+ * Split from the CLI on purpose: this module is pure (takes a `SymbolLookup`),
+ * so it unit-tests VM-free with a fake index, while the CLI supplies either
+ * the real 2 GB SQLite index (VM, `--capture`) or the committed snapshot
+ * (CI, `--verify`).
+ */
+import type { KnowledgeRef } from './knowledgeRefs.js';
+/** Minimal view of the symbol index the audit needs. */
+export interface SymbolLookup {
+    /** Case-insensitive element lookup; null when the name is not in the AOT. */
+    resolve(name: string): {
+        canonical: string;
+        types: string[];
+    } | null;
+    /**
+     * Weaker proof of existence: the name is not an indexed element of its own,
+     * but real AOT elements declare it as a base class / implemented interface
+     * (e.g. `IFeatureMetadata`). Real, just not indexable on its own.
+     */
+    isReferencedBase(name: string): boolean;
+    /** Does `canonical` declare a method named `member` (case-insensitive)? */
+    hasMember(canonical: string, member: string): boolean;
+}
+export type FindingStatus = 'unknown-type' | 'unknown-member' | 'casing';
+export interface AuditFinding {
+    ref: KnowledgeRef;
+    status: FindingStatus;
+    detail: string;
+}
+export interface AuditResult {
+    checked: number;
+    resolved: number;
+    allowed: number;
+    findings: AuditFinding[];
+}
+/**
+ * Names that legitimately never appear in the symbol index — .NET BCL types
+ * reachable from X++, macro/pseudo identifiers, and platform constructs the
+ * metadata parser does not index. Kept as data (not code) in
+ * eval/knowledge-audit.allow.json so an exception is always a reviewed,
+ * justified entry rather than a silent skip.
+ */
+export type Allowlist = Record<string, string>;
+export declare function auditRefs(refs: KnowledgeRef[], lookup: SymbolLookup, allow?: Allowlist): AuditResult;
+export declare function renderFindings(result: AuditResult): string;
+export interface AuditSnapshot {
+    /** ISO timestamp of the capture run. */
+    capturedAt: string;
+    /** `last_indexed_at` of the symbol index the capture ran against. */
+    indexedAt: string;
+    /** Every reference key that resolved cleanly on the VM. */
+    ok: string[];
+}
+export declare function buildSnapshot(refs: KnowledgeRef[], result: AuditResult, indexedAt: string): AuditSnapshot;
+/**
+ * CI half of the gate: no symbol index available, so every reference must be
+ * covered by the committed snapshot. Editing knowledge content therefore
+ * requires re-capturing the audit on the VM — knowledge cannot silently drift
+ * back to unverified.
+ */
+export declare function verifyAgainstSnapshot(refs: KnowledgeRef[], snapshot: AuditSnapshot): KnowledgeRef[];
+//# sourceMappingURL=knowledgeAudit.d.ts.map

package/dist/eval/audit/knowledgeAudit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledgeAudit.d.ts","sourceRoot":"","sources":["../../../src/eval/audit/knowledgeAudit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,wDAAwD;AACxD,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,IAAI,CAAC;IACrE;;;;OAIG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACxC,2EAA2E;IAC3E,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;CACvD;AAED,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,gBAAgB,GAAG,QAAQ,CAAC;AAEzE,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,YAAY,CAAC;IAClB,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAe/C,wBAAgB,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,GAAE,SAAc,GAAG,WAAW,CAwDxG;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAuB1D;AAID,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,EAAE,EAAE,MAAM,EAAE,CAAC;CACd;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,aAAa,CAOzG;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,QAAQ,EAAE,aAAa,GAAG,YAAY,EAAE,CAGnG"}

package/dist/eval/audit/knowledgeAudit.js

@@ -0,0 +1,117 @@
+/**
+ * Knowledge-base audit (ROADMAP P1) — resolve every AOT reference extracted
+ * from KNOWLEDGE_BASE against the real symbol index, so knowledge content is
+ * gated the same fail-closed way generated code is.
+ *
+ * Split from the CLI on purpose: this module is pure (takes a `SymbolLookup`),
+ * so it unit-tests VM-free with a fake index, while the CLI supplies either
+ * the real 2 GB SQLite index (VM, `--capture`) or the committed snapshot
+ * (CI, `--verify`).
+ */
+function isAllowed(name, allow) {
+    if (Object.prototype.hasOwnProperty.call(allow, name))
+        return true;
+    // Fully-qualified .NET types are recognised by namespace prefix.
+    return name.startsWith('System.') || name.startsWith('Microsoft.');
+}
+/**
+ * Member checks only make sense for element types that own methods. A
+ * `Foo::bar()` where Foo is an enum/EDT is a *type-shaped* reference (e.g.
+ * `NoYes::Yes`), not a call — those are accepted on the type alone.
+ */
+const MEMBER_BEARING = new Set(['class', 'table', 'interface', 'map', 'view', 'data-entity', 'form']);
+export function auditRefs(refs, lookup, allow = {}) {
+    const findings = [];
+    let resolved = 0;
+    let allowed = 0;
+    for (const ref of refs) {
+        if (isAllowed(ref.name, allow)) {
+            allowed++;
+            continue;
+        }
+        // X++ lets an attribute be written without its `Attribute` suffix
+        // ([DataContract] == [DataContractAttribute]), so both spellings resolve.
+        const suffixed = ref.kind === 'attribute' ? `${ref.name}Attribute` : null;
+        let written = ref.name;
+        let hit = lookup.resolve(ref.name);
+        if (!hit && suffixed) {
+            hit = lookup.resolve(suffixed);
+            if (hit)
+                written = suffixed;
+        }
+        if (!hit) {
+            if (lookup.isReferencedBase(ref.name) || (suffixed && lookup.isReferencedBase(suffixed))) {
+                resolved++;
+                continue;
+            }
+            findings.push({
+                ref,
+                status: 'unknown-type',
+                detail: `"${ref.name}" does not exist in the symbol index`,
+            });
+            continue;
+        }
+        if (hit.canonical !== written) {
+            findings.push({
+                ref,
+                status: 'casing',
+                detail: `"${written}" is spelled "${hit.canonical}" in the AOT`,
+            });
+            // Casing is a defect but the type is real — keep checking the member.
+        }
+        else {
+            resolved++;
+        }
+        if (ref.member && hit.types.some(t => MEMBER_BEARING.has(t))) {
+            if (!lookup.hasMember(hit.canonical, ref.member)) {
+                findings.push({
+                    ref,
+                    status: 'unknown-member',
+                    detail: `${hit.canonical} has no method "${ref.member}"`,
+                });
+            }
+        }
+    }
+    return { checked: refs.length, resolved, allowed, findings };
+}
+export function renderFindings(result) {
+    const lines = [];
+    lines.push(`Knowledge audit: ${result.checked} reference(s) · ${result.resolved} resolved · ` +
+        `${result.allowed} allowlisted · ${result.findings.length} defect(s)`);
+    if (result.findings.length === 0) {
+        lines.push('✅ every named API/type in KNOWLEDGE_BASE resolves against the symbol index.');
+        return lines.join('\n');
+    }
+    const byEntry = new Map();
+    for (const f of result.findings) {
+        const list = byEntry.get(f.ref.entryId) ?? [];
+        list.push(f);
+        byEntry.set(f.ref.entryId, list);
+    }
+    for (const [entryId, list] of [...byEntry].sort((a, b) => b[1].length - a[1].length)) {
+        lines.push(`\n▸ ${entryId} (${list.length})`);
+        for (const f of list) {
+            lines.push(`   [${f.status}] ${f.ref.field} · ${f.ref.kind} · ${f.detail}`);
+        }
+    }
+    return lines.join('\n');
+}
+export function buildSnapshot(refs, result, indexedAt) {
+    const bad = new Set(result.findings.map(f => f.ref.key));
+    return {
+        capturedAt: new Date().toISOString(),
+        indexedAt,
+        ok: refs.map(r => r.key).filter(k => !bad.has(k)).sort(),
+    };
+}
+/**
+ * CI half of the gate: no symbol index available, so every reference must be
+ * covered by the committed snapshot. Editing knowledge content therefore
+ * requires re-capturing the audit on the VM — knowledge cannot silently drift
+ * back to unverified.
+ */
+export function verifyAgainstSnapshot(refs, snapshot) {
+    const ok = new Set(snapshot.ok);
+    return refs.filter(r => !ok.has(r.key));
+}
+//# sourceMappingURL=knowledgeAudit.js.map

package/dist/eval/audit/knowledgeAudit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledgeAudit.js","sourceRoot":"","sources":["../../../src/eval/audit/knowledgeAudit.ts"],"names":[],"mappings":"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"}

package/dist/eval/audit/knowledgeAuditCli.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Knowledge-audit CLI (ROADMAP P1).
+ *
+ *   npm run eval:knowledge-audit            # verify against the committed snapshot (CI, VM-free)
+ *   npm run eval:knowledge-audit -- --capture   # re-audit against the real symbol index (VM only)
+ *   npm run eval:knowledge-audit -- --json
+ *
+ * --capture opens data/xpp-metadata.db (override with DB_PATH), resolves every
+ * reference, prints the defect list and rewrites eval/knowledge-audit.snapshot.json.
+ * The default (verify) mode needs no DB: it recomputes the reference set from
+ * KNOWLEDGE_BASE and fails when any reference is missing from the snapshot —
+ * so a knowledge edit cannot ship without being re-audited on the VM.
+ *
+ * Exit code 1 on any defect, so it drops straight into the eval-gate workflow.
+ */
+export {};
+//# sourceMappingURL=knowledgeAuditCli.d.ts.map

package/dist/eval/audit/knowledgeAuditCli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledgeAuditCli.d.ts","sourceRoot":"","sources":["../../../src/eval/audit/knowledgeAuditCli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/eval/audit/knowledgeAuditCli.js

@@ -0,0 +1,83 @@
+/**
+ * Knowledge-audit CLI (ROADMAP P1).
+ *
+ *   npm run eval:knowledge-audit            # verify against the committed snapshot (CI, VM-free)
+ *   npm run eval:knowledge-audit -- --capture   # re-audit against the real symbol index (VM only)
+ *   npm run eval:knowledge-audit -- --json
+ *
+ * --capture opens data/xpp-metadata.db (override with DB_PATH), resolves every
+ * reference, prints the defect list and rewrites eval/knowledge-audit.snapshot.json.
+ * The default (verify) mode needs no DB: it recomputes the reference set from
+ * KNOWLEDGE_BASE and fails when any reference is missing from the snapshot —
+ * so a knowledge edit cannot ship without being re-audited on the VM.
+ *
+ * Exit code 1 on any defect, so it drops straight into the eval-gate workflow.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { KNOWLEDGE_BASE } from '../../tools/xppKnowledge.js';
+import { extractKnowledgeRefs } from './knowledgeRefs.js';
+import { openSymbolLookup } from './symbolLookup.js';
+import { auditRefs, renderFindings, buildSnapshot, verifyAgainstSnapshot, } from './knowledgeAudit.js';
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, '..', '..', '..');
+const SNAPSHOT_PATH = path.join(REPO_ROOT, 'eval', 'knowledge-audit.snapshot.json');
+const ALLOW_PATH = path.join(REPO_ROOT, 'eval', 'knowledge-audit.allow.json');
+function readJson(file, fallback) {
+    if (!fs.existsSync(file))
+        return fallback;
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+function resolveDbPath() {
+    return process.env.DB_PATH ?? path.join(REPO_ROOT, 'data', 'xpp-metadata.db');
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const capture = argv.includes('--capture');
+    const asJson = argv.includes('--json');
+    const refs = extractKnowledgeRefs(KNOWLEDGE_BASE);
+    const allow = readJson(ALLOW_PATH, {});
+    if (!capture) {
+        const snapshot = readJson(SNAPSHOT_PATH, null);
+        if (!snapshot) {
+            console.error(`❌ no snapshot at ${SNAPSHOT_PATH}. Run with --capture on the VM first.`);
+            return 1;
+        }
+        const missing = verifyAgainstSnapshot(refs, snapshot);
+        if (asJson) {
+            console.log(JSON.stringify({ mode: 'verify', checked: refs.length, missing }, null, 2));
+        }
+        else {
+            console.log(`Knowledge audit (verify) — ${refs.length} reference(s) vs snapshot captured ` +
+                `${snapshot.capturedAt} against index ${snapshot.indexedAt}.`);
+            if (missing.length === 0) {
+                console.log('✅ every reference in KNOWLEDGE_BASE is covered by an audited snapshot entry.');
+            }
+            else {
+                console.log(`❌ ${missing.length} reference(s) not audited — re-run with --capture on the VM:`);
+                for (const m of missing)
+                    console.log(`   ${m.entryId} · ${m.field} · ${m.kind} · ${m.name}${m.member ? `::${m.member}` : ''}`);
+            }
+        }
+        return missing.length === 0 ? 0 : 1;
+    }
+    const { lookup, indexedAt } = await openSymbolLookup(resolveDbPath());
+    const result = auditRefs(refs, lookup, allow);
+    if (asJson) {
+        console.log(JSON.stringify({ mode: 'capture', indexedAt, ...result }, null, 2));
+    }
+    else {
+        console.log(renderFindings(result));
+    }
+    const snapshot = buildSnapshot(refs, result, indexedAt);
+    fs.writeFileSync(SNAPSHOT_PATH, `${JSON.stringify(snapshot, null, 2)}\n`, 'utf8');
+    if (!asJson)
+        console.log(`\nSnapshot written: ${path.relative(REPO_ROOT, SNAPSHOT_PATH)} (${snapshot.ok.length} clean reference(s)).`);
+    return result.findings.length === 0 ? 0 : 1;
+}
+main().then(code => process.exit(code), err => {
+    console.error(`❌ knowledge audit failed: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+});
+//# sourceMappingURL=knowledgeAuditCli.js.map

package/dist/eval/audit/knowledgeAuditCli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledgeAuditCli.js","sourceRoot":"","sources":["../../../src/eval/audit/knowledgeAuditCli.ts"],"names":[],"mappings":"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"}

package/dist/eval/audit/knowledgeRefs.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Knowledge-base reference extraction (ROADMAP P1).
+ *
+ * Pulls every *named AOT type / API* out of the embedded KNOWLEDGE_BASE
+ * (src/tools/xppKnowledge.ts) so it can be resolved against the real symbol
+ * index. Rationale: generated code is gated fail-closed by validate_code and
+ * the build, but knowledge content shipped to the model was never gated at
+ * all — that asymmetry is what the public review of the part-4 article
+ * exposed (a `SysRunnable::run()` that does not exist in the AOT).
+ *
+ * Extraction is deliberately *conservative*: only shapes where a PascalCase
+ * token is unambiguously an AOT element reference are emitted, so an
+ * unresolved reference is a real defect rather than prose noise. Everything
+ * this module does is pure string work — no DB, no VM — so it is unit
+ * testable and runs anywhere.
+ */
+import type { KnowledgeEntry } from '../../tools/xppKnowledge.js';
+/** How a reference was recognised — drives the resolver's expectations. */
+export type RefKind = 'static-call' | 'extends' | 'new' | 'attribute' | 'intrinsic' | 'declaration';
+export interface KnowledgeRef {
+    /** Knowledge entry id the reference came from. */
+    entryId: string;
+    /** The AOT element name as written in the knowledge content. */
+    name: string;
+    /** For 'static-call': the method after `::`. */
+    member?: string;
+    kind: RefKind;
+    /** Which field of the entry it was found in (for defect reporting). */
+    field: string;
+    /** Stable key used by the snapshot: entryId|kind|name[::member]. */
+    key: string;
+}
+/** Extract every AOT reference from one knowledge entry. */
+export declare function extractEntryRefs(entry: KnowledgeEntry): KnowledgeRef[];
+/** Extract references from the whole knowledge base, in entry order. */
+export declare function extractKnowledgeRefs(base: KnowledgeEntry[]): KnowledgeRef[];
+//# sourceMappingURL=knowledgeRefs.d.ts.map

package/dist/eval/audit/knowledgeRefs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledgeRefs.d.ts","sourceRoot":"","sources":["../../../src/eval/audit/knowledgeRefs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAElE,2EAA2E;AAC3E,MAAM,MAAM,OAAO,GACf,aAAa,GACb,SAAS,GACT,KAAK,GACL,WAAW,GACX,WAAW,GACX,aAAa,CAAC;AAElB,MAAM,WAAW,YAAY;IAC3B,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;CACb;AA2FD,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,YAAY,EAAE,CAsDtE;AAED,wEAAwE;AACxE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,cAAc,EAAE,GAAG,YAAY,EAAE,CAE3E"}