progmune-runtime 2.1.6 → 3.2.0

package/dist/decision-engine.js

@@ -0,0 +1,388 @@
+"use strict";
+/**
+ * P7.5: Unified Decision Engine — the "operating system kernel" of Progmune.
+ *
+ * All decisions in the system — verification, promotion, repair, policy —
+ * are driven by ONE engine with ONE consistent model.
+ *
+ * The three core concepts:
+ *   1. Verification Asset — the data (knowledge, rules, benchmarks, protocols)
+ *   2. Promotion Pipeline — the lifecycle (evidence → candidate → ... → stable)
+ *   3. Decision Engine   — the kernel (this file)
+ *
+ * Everything else is just an Asset Type.
+ *
+ * Decision model:
+ *   Input:  Asset + Context → Decision { action, confidence, reason, provenance }
+ *   Output: BLOCK/WARN/ALLOW | promote/demote/hold | fix/retry/rollback | accept/reject
+ *
+ * Importance is COMPUTED, not configured:
+ *   Importance = Impact × Universality × Criticality
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DecisionEngine = void 0;
+exports.computeImportance = computeImportance;
+exports.classifyCodeContext = classifyCodeContext;
+exports.getDecisionEngine = getDecisionEngine;
+// ═══════════════════════════════════════════════════════════════
+// Importance Computation
+// ═══════════════════════════════════════════════════════════════
+/**
+ * Impact: how severe are the consequences of getting this wrong?
+ *
+ *   1.0 = security/critical (TLS Finished, password verify)
+ *   0.7 = resource management (file close, memory free)
+ *   0.4 = correctness (data validation, type checking)
+ *   0.1 = informational (logging, formatting)
+ */
+function computeImpact(asset) {
+    const domain = asset.domain.toLowerCase();
+    const name = asset.name.toLowerCase();
+    // Security-critical
+    if (domain === "tls" || domain === "ssl" || domain === "auth" ||
+        /tls|ssl|auth|encrypt|decrypt|verify|cert|key|token|password/i.test(name)) {
+        return 1.0;
+    }
+    // Resource management
+    if (/close|free|destroy|release|cleanup|disconnect|logout/i.test(name)) {
+        return 0.7;
+    }
+    // Correctness
+    if (/validate|check|assert|verify|compare|match/i.test(name)) {
+        return 0.4;
+    }
+    // Informational
+    return 0.1;
+}
+/**
+ * Universality: how broadly does this apply across codebases?
+ *
+ *   1.0 = universal (memory management, error handling)
+ *   0.7 = common (HTTP, file I/O, auth)
+ *   0.4 = domain-specific (TLS, SSH, DB protocols)
+ *   0.1 = repo-specific (custom internal patterns)
+ */
+function computeUniversality(asset) {
+    const crossRepo = asset.evidence.crossRepoCount;
+    if (crossRepo >= 5)
+        return 1.0;
+    if (crossRepo >= 3)
+        return 0.7;
+    if (crossRepo >= 2)
+        return 0.4;
+    return 0.1;
+}
+/**
+ * Criticality: how essential is this to correct program behavior?
+ *
+ *   1.0 = program fails without this (init, close, free)
+ *   0.7 = security/privacy risk (auth, encrypt)
+ *   0.4 = correctness risk (validate, check)
+ *   0.1 = quality risk (style, format)
+ */
+function computeCriticality(asset) {
+    const name = asset.name.toLowerCase();
+    // Program fails without this
+    if (/^(init_|create_|open_|close_|free_|destroy_)/i.test(name) ||
+        /_(init|cleanup|setup|teardown)$/i.test(name)) {
+        return 1.0;
+    }
+    // Security risk
+    if (/auth|encrypt|decrypt|token|password|verify|ssl|tls/i.test(name)) {
+        return 0.7;
+    }
+    // Correctness risk
+    if (/validate|check|assert|enforce|policy/i.test(name)) {
+        return 0.4;
+    }
+    return 0.1;
+}
+/**
+ * Compute Importance from Impact × Universality × Criticality.
+ * This is NOT configured — it's derived from evidence and semantics.
+ */
+function computeImportance(asset) {
+    const impact = computeImpact(asset);
+    const universality = computeUniversality(asset);
+    const criticality = computeCriticality(asset);
+    // Weighted product: Impact is most important, Universality is secondary
+    return Math.round((impact * 0.4 + universality * 0.25 + criticality * 0.35) * 100);
+}
+/**
+ * Sprint 14: Classify code context from function names and patterns.
+ *
+ * Production code gets strict thresholds.
+ * Test/example/benchmark code gets relaxed thresholds.
+ * Enterprises only care about Production FP.
+ */
+function classifyCodeContext(functions) {
+    const all = functions.join(" ").toLowerCase();
+    // Test patterns
+    if (/test|_test|testing|mock|stub|fake|assert|expect/i.test(all))
+        return "test";
+    // Example patterns
+    if (/example|demo|sample|tutorial|showcase/i.test(all))
+        return "example";
+    // Benchmark patterns
+    if (/bench|benchmark|perf|performance|stress|soak|load/i.test(all))
+        return "benchmark";
+    // Init/setup patterns
+    if (/^(init_|setup|config|bootstrap|startup)/i.test(all))
+        return "init";
+    return "production";
+}
+/** Sprint 14: Per-context confidence thresholds. */
+const CONTEXT_THRESHOLDS = {
+    production: { block: 0.80, warn: 0.60, allow: 0.40 },
+    test: { block: 0.95, warn: 0.85, allow: 0.70 },
+    example: { block: 0.95, warn: 0.85, allow: 0.70 },
+    benchmark: { block: 0.90, warn: 0.80, allow: 0.60 },
+    init: { block: 0.85, warn: 0.70, allow: 0.50 },
+    unknown: { block: 0.80, warn: 0.60, allow: 0.40 },
+};
+class DecisionEngine {
+    constructor() {
+        this.history = [];
+    }
+    /**
+     * Make a verification decision: should we alert?
+     */
+    decideVerification(asset, context = {}) {
+        const importance = computeImportance(asset);
+        const fpRate = (context.recentFPs || 0) / Math.max(1, (context.recentFPs || 0) + (context.recentTPs || 0));
+        // Confidence = asset confidence × (1 - FP rate) × environment factor
+        let envFactor = 1.0;
+        if (context.environment === "production")
+            envFactor = 0.7; // More conservative in prod
+        if (context.environment === "test")
+            envFactor = 1.0;
+        const confidence = asset.confidence * (1 - fpRate) * envFactor;
+        // Sprint 14: Context-aware thresholds
+        const ctx = context.codeContext || "production";
+        const thresholds = CONTEXT_THRESHOLDS[ctx];
+        let action;
+        if (confidence >= thresholds.block)
+            action = "BLOCK";
+        else if (confidence >= thresholds.warn)
+            action = "WARN";
+        else if (confidence >= thresholds.allow)
+            action = "ALLOW";
+        else
+            action = "SUPPRESS";
+        // Importance override: high-importance assets alert even at lower confidence
+        if (importance >= 70 && action === "ALLOW")
+            action = "WARN";
+        if (importance >= 85 && action === "WARN")
+            action = "BLOCK";
+        return this.recordDecision({
+            kind: "verification",
+            action,
+            confidence,
+            reason: action === "BLOCK"
+                ? `High-confidence violation (${(confidence * 100).toFixed(0)}%, importance ${importance})`
+                : action === "SUPPRESS"
+                    ? `Low confidence (${(confidence * 100).toFixed(0)}%), ${context.recentFPs || 0} recent FPs`
+                    : `Moderate confidence (${(confidence * 100).toFixed(0)}%) — ${action}`,
+            provenance: {
+                assets: [asset.id],
+                evidence: [
+                    ...asset.evidence.rfcRefs.map(r => `RFC ${r}`),
+                    ...asset.evidence.repos,
+                    `importance=${importance}`,
+                ],
+                chain: [],
+                decider: "system",
+                timestamp: new Date().toISOString(),
+            },
+            recommendations: action === "SUPPRESS"
+                ? ["Add RFC reference to increase confidence", "Validate across more repos"]
+                : action === "WARN"
+                    ? ["Review manually before blocking", "Check deployment observations"]
+                    : [],
+        });
+    }
+    /**
+     * Make a promotion decision: should this asset move to the next stage?
+     */
+    decidePromotion(asset, context = {}) {
+        const importance = computeImportance(asset);
+        const hasDeployment = (context.deploymentObservations || 0) > 0;
+        // Promotion confidence depends on:
+        // 1. Asset evidence strength (cross-repo, RFC, sequence count)
+        // 2. Importance (high-importance assets are promoted faster)
+        // 3. Deployment observations (real-world validation)
+        let confidence = asset.confidence;
+        // Deployment bonus: real-world observation significantly boosts confidence
+        if (hasDeployment)
+            confidence = Math.min(1.0, confidence + 0.15);
+        // Importance bonus: high-importance assets get promotion priority
+        if (importance >= 70)
+            confidence = Math.min(1.0, confidence + 0.05);
+        let action;
+        if (confidence >= 0.80 && hasDeployment)
+            action = "promote";
+        else if (confidence >= 0.60)
+            action = "promote";
+        else if (confidence >= 0.30)
+            action = "hold";
+        else
+            action = "demote";
+        return this.recordDecision({
+            kind: "promotion",
+            action,
+            confidence,
+            reason: action === "promote"
+                ? `Ready for promotion: ${asset.evidence.crossRepoCount} repos, importance ${importance}${hasDeployment ? ", deployment-validated" : ""}`
+                : action === "hold"
+                    ? `Holding at ${asset.stage}: need more evidence${!hasDeployment ? " (no deployment data)" : ""}`
+                    : `Demoting: confidence ${(confidence * 100).toFixed(0)}% below threshold`,
+            provenance: {
+                assets: [asset.id],
+                evidence: [
+                    `${asset.evidence.crossRepoCount} repos`,
+                    `${asset.evidence.sequenceCount} sequences`,
+                    ...asset.evidence.rfcRefs.map(r => `RFC ${r}`),
+                    hasDeployment ? `${context.deploymentObservations} deployments` : "no deployment data",
+                ],
+                chain: asset.history.map(h => `${h.from}→${h.to}: ${h.reason}`),
+                decider: "system",
+                timestamp: new Date().toISOString(),
+            },
+            recommendations: !hasDeployment
+                ? ["Deploy to staging for real-world validation", "Collect production observations"]
+                : action === "hold"
+                    ? ["Add cross-repo evidence", "Seek human review"]
+                    : [],
+        });
+    }
+    /**
+     * Make a repair decision: should we fix this, retry, or rollback?
+     */
+    decideRepair(asset, context = {}) {
+        const importance = computeImportance(asset);
+        // Repair is only worth attempting for high-importance assets
+        // AND when confidence is high enough
+        let action;
+        let confidence = asset.confidence;
+        if (importance >= 70 && confidence >= 0.60) {
+            action = "fix";
+        }
+        else if (importance >= 50 && confidence >= 0.40) {
+            action = "retry";
+        }
+        else if (context.environment === "production") {
+            action = "rollback";
+        }
+        else {
+            action = "report";
+        }
+        if (context.humanOverride) {
+            action = context.humanOverride;
+        }
+        return this.recordDecision({
+            kind: "repair",
+            action,
+            confidence,
+            reason: action === "fix"
+                ? `Auto-repair recommended: importance ${importance}, confidence ${(confidence * 100).toFixed(0)}%`
+                : action === "rollback"
+                    ? `Rollback: too risky for production (importance ${importance}, confidence ${(confidence * 100).toFixed(0)}%)`
+                    : `Report-only: insufficient confidence for auto-repair`,
+            provenance: {
+                assets: [asset.id],
+                evidence: [`importance=${importance}`, `confidence=${(confidence * 100).toFixed(0)}%`],
+                chain: [],
+                decider: context.humanOverride ? "human" : "system",
+                timestamp: new Date().toISOString(),
+            },
+            recommendations: action === "fix"
+                ? ["Apply fix and re-verify", "Record outcome for learning"]
+                : action === "report"
+                    ? ["Flag for human review", "Collect more evidence before auto-repair"]
+                    : [],
+        });
+    }
+    /**
+     * Make a deployment decision: is this asset ready for production?
+     */
+    decideDeployment(asset, context = {}) {
+        const importance = computeImportance(asset);
+        // Deployment requires:
+        // 1. Asset at "validated" stage or higher
+        // 2. Deployment observations (staging OK)
+        // 3. Acceptable FP rate (< 30% in staging)
+        const stageOk = ["validated", "stable"].includes(asset.stage);
+        const hasDeployment = (context.deploymentObservations || 0) > 0;
+        const fpRate = (context.recentFPs || 0) / Math.max(1, (context.recentFPs || 0) + (context.recentTPs || 0));
+        const fpOk = fpRate < 0.30;
+        let action;
+        let confidence = asset.confidence;
+        if (stageOk && hasDeployment && fpOk) {
+            action = "deploy";
+            confidence = Math.min(1.0, confidence + 0.1);
+        }
+        else if (stageOk && !hasDeployment) {
+            action = "hold";
+        }
+        else if (!fpOk) {
+            action = "rollback";
+        }
+        else {
+            action = "hold";
+        }
+        return this.recordDecision({
+            kind: "deployment",
+            action,
+            confidence,
+            reason: action === "deploy"
+                ? `Production-ready: stage=${asset.stage}, ${context.deploymentObservations} deployments, FP rate ${(fpRate * 100).toFixed(0)}%`
+                : action === "hold"
+                    ? !hasDeployment ? "Needs staging deployment first" : "Not ready for production"
+                    : `Rollback: FP rate ${(fpRate * 100).toFixed(0)}% exceeds 30% threshold`,
+            provenance: {
+                assets: [asset.id],
+                evidence: [
+                    `stage=${asset.stage}`,
+                    `deployments=${context.deploymentObservations || 0}`,
+                    `FP rate=${(fpRate * 100).toFixed(0)}%`,
+                ],
+                chain: asset.history.map(h => `${h.from}→${h.to}`),
+                decider: "system",
+                timestamp: new Date().toISOString(),
+            },
+            recommendations: !hasDeployment
+                ? ["Deploy to staging environment", "Collect FP/TP metrics"]
+                : !fpOk
+                    ? ["Investigate FP sources", "Suppress noisy rules before re-deploying"]
+                    : [],
+        });
+    }
+    /**
+     * Get full decision history for provenance tracking.
+     */
+    getHistory() {
+        return [...this.history];
+    }
+    /**
+     * Get decision history for a specific asset.
+     */
+    getAssetDecisions(assetId) {
+        return this.history.filter(d => d.provenance.assets.includes(assetId));
+    }
+    recordDecision(partial) {
+        const id = `DEC-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+        const decision = { id, ...partial };
+        this.history.push(decision);
+        return decision;
+    }
+}
+exports.DecisionEngine = DecisionEngine;
+// ═══════════════════════════════════════════════════════════════
+// Singleton
+// ═══════════════════════════════════════════════════════════════
+let _decisionEngine = null;
+function getDecisionEngine() {
+    if (!_decisionEngine)
+        _decisionEngine = new DecisionEngine();
+    return _decisionEngine;
+}

package/dist/derive-metadata.js

@@ -0,0 +1,250 @@
+"use strict";
+/**
+ * Auto-derive capability metadata (@requires, @produces, @purpose, @tags)
+ * from existing code patterns:
+ *   1. @protocol pre_states → @requires, post_states → @produces
+ *   2. Function name → @purpose (humanized)
+ *   3. File path → @tags
+ *   4. Import chain → @requires (dependency)
+ *
+ * This bridges the gap from 30% → 80% metadata coverage without
+ * requiring manual annotation of every function.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveMetadata = deriveMetadata;
+exports.applyDerivedMetadata = applyDerivedMetadata;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Humanize a camelCase/PascalCase function name into a readable purpose.
+ */
+function humanize(name) {
+    return name
+        .replace(/([A-Z])/g, " $1")
+        .replace(/_/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .toLowerCase();
+}
+/**
+ * Infer tags from file path.
+ */
+function inferTags(filePath) {
+    const dir = path.dirname(filePath).replace(/^src\//, "");
+    const parts = dir.split("/").filter(Boolean);
+    return parts.length > 0 ? parts : ["core"];
+}
+/**
+ * Parse @protocol annotations from raw source text.
+ */
+function parseProtocolAnnotation(source) {
+    const match = source.match(/@protocol\s+.*?pre_states\s*=\s*\[(.*?)\]\s*.*?post_states\s*=\s*\[(.*?)\]/s);
+    if (!match)
+        return null;
+    const pre = match[1].split(",").map(s => s.replace(/["'\s]/g, "")).filter(Boolean);
+    const post = match[2].split(",").map(s => s.replace(/["'\s]/g, "")).filter(Boolean);
+    return { pre, post };
+}
+/**
+ * Scan source files and auto-derive capability metadata for functions that lack it.
+ */
+function deriveMetadata(srcDir = "src") {
+    const results = [];
+    function walk(dir) {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === "node_modules" || entry.name === "dist" || entry.name.startsWith("."))
+                    continue;
+                walk(fullPath);
+            }
+            else if (entry.name.endsWith(".ts") && !entry.name.endsWith(".test.ts")) {
+                const source = fs.readFileSync(fullPath, "utf-8");
+                processFile(fullPath, source, results);
+            }
+        }
+    }
+    walk(srcDir);
+    return results;
+}
+function processFile(filePath, source, results) {
+    // Match: export function name | export async function name
+    const funcRegex = /\/\*\*[\s\S]*?\*\/\s*(?:export\s+)?(?:async\s+)?function\s+(\w+)/g;
+    const protocolRegex = /@protocol\s+.*?pre_states\s*=\s*\[([^\]]*)\].*?post_states\s*=\s*\[([^\]]*)\]/g;
+    let match;
+    // Strategy 1: Extract from @protocol annotations
+    // Reset regex
+    while ((match = protocolRegex.exec(source)) !== null) {
+        // Find the nearest function name before or after this annotation
+        const before = source.slice(0, match.index);
+        const after = source.slice(match.index);
+        const funcMatch = after.match(/function\s+(\w+)/);
+        if (!funcMatch)
+            continue;
+        const name = funcMatch[1];
+        const pre = match[1].split(",").map(s => s.replace(/["'\s]/g, "")).filter(Boolean);
+        const post = match[2].split(",").map(s => s.replace(/["'\s]/g, "")).filter(Boolean);
+        // Don't overwrite existing metadata
+        const existing = results.find(r => r.function === name);
+        if (existing) {
+            if (existing.requires.length === 0)
+                existing.requires = pre;
+            if (existing.produces.length === 0)
+                existing.produces = post;
+        }
+        else {
+            results.push({
+                function: name,
+                file: filePath,
+                requires: pre,
+                produces: post,
+                purpose: humanize(name),
+                tags: inferTags(filePath),
+            });
+        }
+    }
+    // Strategy 2: Extract from @requires/@produces tags in JSDoc
+    while ((match = funcRegex.exec(source)) !== null) {
+        const name = match[1];
+        const jsdoc = match[0];
+        // Skip if already covered by Strategy 1
+        const existing = results.find(r => r.function === name);
+        const requires = existing?.requires || [];
+        const produces = existing?.produces || [];
+        // Parse @requires tag
+        const reqMatch = jsdoc.match(/@requires\s+(\S+)/g);
+        if (reqMatch) {
+            for (const r of reqMatch) {
+                const val = r.replace("@requires ", "").trim();
+                if (val && !requires.includes(val))
+                    requires.push(val);
+            }
+        }
+        // Parse @produces tag
+        const prodMatch = jsdoc.match(/@produces\s+(\S+)/g);
+        if (prodMatch) {
+            for (const p of prodMatch) {
+                const val = p.replace("@produces ", "").trim();
+                if (val && !produces.includes(val))
+                    produces.push(val);
+            }
+        }
+        // Parse @purpose
+        const purposeMatch = jsdoc.match(/@purpose\s+(.+?)(?:\n|\*\/)/);
+        const purpose = purposeMatch
+            ? purposeMatch[1].trim()
+            : humanize(name);
+        // Parse @tags
+        const tagsMatch = jsdoc.match(/@tags?\s+(.+?)(?:\n|\*\/)/);
+        const tags = tagsMatch
+            ? tagsMatch[1].split(/[,\s]+/).map(s => s.trim()).filter(Boolean)
+            : inferTags(filePath);
+        if (existing) {
+            if (existing.requires.length === 0)
+                existing.requires = requires;
+            if (existing.produces.length === 0)
+                existing.produces = produces;
+            if (!existing.purpose || existing.purpose === humanize(name))
+                existing.purpose = purpose;
+        }
+        else {
+            results.push({ function: name, file: filePath, requires, produces, purpose, tags });
+        }
+    }
+}
+/**
+ * Apply derived metadata back to source files.
+ * Inserts @requires/@produces/@purpose/@tags tags into existing JSDoc comments.
+ */
+function applyDerivedMetadata(dryRun = true) {
+    const derived = deriveMetadata();
+    let updated = 0;
+    let skipped = 0;
+    for (const meta of derived) {
+        const filePath = meta.file;
+        if (!fs.existsSync(filePath))
+            continue;
+        let source = fs.readFileSync(filePath, "utf-8");
+        // Find the function's JSDoc block
+        const funcPattern = new RegExp(`(\\/\\*\\*[\\s\\S]*?\\*\\/)\\s*(?:export\\s+)?(?:async\\s+)?function\\s+${meta.function}\\b`);
+        const match = funcPattern.exec(source);
+        if (!match) {
+            skipped++;
+            continue;
+        }
+        const existingJSDoc = match[1];
+        let newJSDoc = existingJSDoc;
+        // Add missing tags
+        if (!existingJSDoc.includes("@requires") && meta.requires.length > 0) {
+            newJSDoc = newJSDoc.replace(/\*\/$/, ` * @requires ${meta.requires.join(" ")}\n */`);
+        }
+        if (!existingJSDoc.includes("@produces") && meta.produces.length > 0) {
+            newJSDoc = newJSDoc.replace(/\*\/$/, ` * @produces ${meta.produces.join(" ")}\n */`);
+        }
+        if (!existingJSDoc.includes("@purpose") && meta.purpose) {
+            newJSDoc = newJSDoc.replace(/\*\/$/, ` * @purpose ${meta.purpose}\n */`);
+        }
+        if (!existingJSDoc.includes("@tags") && meta.tags.length > 0) {
+            newJSDoc = newJSDoc.replace(/\*\/$/, ` * @tags ${meta.tags.join(", ")}\n */`);
+        }
+        if (newJSDoc !== existingJSDoc) {
+            if (!dryRun) {
+                source = source.replace(existingJSDoc, newJSDoc);
+                fs.writeFileSync(filePath, source, "utf-8");
+            }
+            updated++;
+        }
+        else {
+            skipped++;
+        }
+    }
+    return { updated, skipped };
+}
+/** CLI: preview derivable metadata */
+if (require.main === module) {
+    const derived = deriveMetadata();
+    console.log(`Derived metadata for ${derived.length} functions:\n`);
+    const withR = derived.filter(d => d.requires.length > 0);
+    const withP = derived.filter(d => d.produces.length > 0);
+    const withPurpose = derived.filter(d => d.purpose && d.purpose !== humanize(d.function));
+    console.log(`  requires: ${withR.length}  produces: ${withP.length}  purpose: ${withPurpose.length}`);
+    // Show sample
+    console.log("\nSample derived metadata:");
+    for (const d of derived.filter(d => d.requires.length > 0 && d.produces.length > 0).slice(0, 5)) {
+        console.log(`  ${d.function}: ${d.requires.join(",")} → ${d.produces.join(",")}`);
+        console.log(`    purpose: ${d.purpose}  tags: [${d.tags.join(", ")}]`);
+    }
+}