@lsctech/polaris 0.1.0

package/dist/cognition/index.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * Route-local cognition delta — public API.
+ *
+ * Exposes delta logic for POLARIS.md and SUMMARY.md updates, validation,
+ * and seed-draft generation used by map update and Smart Docs ingest.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAndApplyLibrarianResult = exports.dispatchCognitionLibrarian = exports.validateCognitionLibrarianResult = exports.archiveCognitionNotes = exports.looksLikePolarisChurn = exports.getSummaryFileSize = exports.validateSummaryFile = exports.validateCognitionSurfaces = exports.SUMMARY_MAX_BYTES = exports.readSummarymd = exports.hasDoctrineBled = exports.isSummaryOversized = exports.detectMissingSummaries = exports.findNearestSummarymd = exports.detectPrecedenceLevel = exports.detectSummaryReasons = exports.applySummaryDelta = exports.assessRouteHealth = exports.readRoutePolarismd = exports.POLARIS_OWNED_COGNITION_FOLDERS = exports.isUserCreatedCognitionSurface = exports.isPolarisOwnedFolder = exports.isCognitionSkippedFolder = exports.findNearestRoutePolarismd = exports.detectOperationalReasons = exports.applyRouteCognitionDelta = void 0;
+var route_cognition_delta_js_1 = require("./route-cognition-delta.js");
+Object.defineProperty(exports, "applyRouteCognitionDelta", { enumerable: true, get: function () { return route_cognition_delta_js_1.applyRouteCognitionDelta; } });
+Object.defineProperty(exports, "detectOperationalReasons", { enumerable: true, get: function () { return route_cognition_delta_js_1.detectOperationalReasons; } });
+Object.defineProperty(exports, "findNearestRoutePolarismd", { enumerable: true, get: function () { return route_cognition_delta_js_1.findNearestRoutePolarismd; } });
+Object.defineProperty(exports, "isCognitionSkippedFolder", { enumerable: true, get: function () { return route_cognition_delta_js_1.isCognitionSkippedFolder; } });
+Object.defineProperty(exports, "isPolarisOwnedFolder", { enumerable: true, get: function () { return route_cognition_delta_js_1.isPolarisOwnedFolder; } });
+Object.defineProperty(exports, "isUserCreatedCognitionSurface", { enumerable: true, get: function () { return route_cognition_delta_js_1.isUserCreatedCognitionSurface; } });
+Object.defineProperty(exports, "POLARIS_OWNED_COGNITION_FOLDERS", { enumerable: true, get: function () { return route_cognition_delta_js_1.POLARIS_OWNED_COGNITION_FOLDERS; } });
+Object.defineProperty(exports, "readRoutePolarismd", { enumerable: true, get: function () { return route_cognition_delta_js_1.readRoutePolarismd; } });
+Object.defineProperty(exports, "assessRouteHealth", { enumerable: true, get: function () { return route_cognition_delta_js_1.assessRouteHealth; } });
+var summary_delta_js_1 = require("./summary-delta.js");
+Object.defineProperty(exports, "applySummaryDelta", { enumerable: true, get: function () { return summary_delta_js_1.applySummaryDelta; } });
+Object.defineProperty(exports, "detectSummaryReasons", { enumerable: true, get: function () { return summary_delta_js_1.detectSummaryReasons; } });
+Object.defineProperty(exports, "detectPrecedenceLevel", { enumerable: true, get: function () { return summary_delta_js_1.detectPrecedenceLevel; } });
+Object.defineProperty(exports, "findNearestSummarymd", { enumerable: true, get: function () { return summary_delta_js_1.findNearestSummarymd; } });
+Object.defineProperty(exports, "detectMissingSummaries", { enumerable: true, get: function () { return summary_delta_js_1.detectMissingSummaries; } });
+Object.defineProperty(exports, "isSummaryOversized", { enumerable: true, get: function () { return summary_delta_js_1.isSummaryOversized; } });
+Object.defineProperty(exports, "hasDoctrineBled", { enumerable: true, get: function () { return summary_delta_js_1.hasDoctrineBled; } });
+Object.defineProperty(exports, "readSummarymd", { enumerable: true, get: function () { return summary_delta_js_1.readSummarymd; } });
+Object.defineProperty(exports, "SUMMARY_MAX_BYTES", { enumerable: true, get: function () { return summary_delta_js_1.SUMMARY_MAX_BYTES; } });
+var validate_js_1 = require("./validate.js");
+Object.defineProperty(exports, "validateCognitionSurfaces", { enumerable: true, get: function () { return validate_js_1.validateCognitionSurfaces; } });
+Object.defineProperty(exports, "validateSummaryFile", { enumerable: true, get: function () { return validate_js_1.validateSummaryFile; } });
+Object.defineProperty(exports, "getSummaryFileSize", { enumerable: true, get: function () { return validate_js_1.getSummaryFileSize; } });
+Object.defineProperty(exports, "looksLikePolarisChurn", { enumerable: true, get: function () { return validate_js_1.looksLikePolarisChurn; } });
+var archive_js_1 = require("./archive.js");
+Object.defineProperty(exports, "archiveCognitionNotes", { enumerable: true, get: function () { return archive_js_1.archiveCognitionNotes; } });
+var librarian_types_js_1 = require("./librarian-types.js");
+Object.defineProperty(exports, "validateCognitionLibrarianResult", { enumerable: true, get: function () { return librarian_types_js_1.validateCognitionLibrarianResult; } });
+var librarian_dispatch_js_1 = require("./librarian-dispatch.js");
+Object.defineProperty(exports, "dispatchCognitionLibrarian", { enumerable: true, get: function () { return librarian_dispatch_js_1.dispatchCognitionLibrarian; } });
+Object.defineProperty(exports, "validateAndApplyLibrarianResult", { enumerable: true, get: function () { return librarian_dispatch_js_1.validateAndApplyLibrarianResult; } });

package/dist/cognition/librarian-dispatch.js

@@ -0,0 +1,391 @@
+"use strict";
+/**
+ * Foreman-side cognition-librarian dispatch and patch validation.
+ *
+ * dispatchCognitionLibrarian — groups pending work notes by folder, dispatches
+ * a cognition-librarian session per folder, waits for the sealed result, and
+ * calls validateAndApplyLibrarianResult on each.
+ *
+ * validateAndApplyLibrarianResult — enforces the 5 validation rules from spec
+ * §6 and writes approved patches to disk.
+ *
+ * Spec: smartdocs/specs/active/folder-cognition-staging-librarian.md §6
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatchCognitionLibrarian = dispatchCognitionLibrarian;
+exports.validateAndApplyLibrarianResult = validateAndApplyLibrarianResult;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_crypto_1 = require("node:crypto");
+const summary_delta_js_1 = require("./summary-delta.js");
+const route_cognition_delta_js_1 = require("./route-cognition-delta.js");
+const librarian_types_js_1 = require("./librarian-types.js");
+const DEFAULT_TIMEOUT_MS = 120_000;
+const POLL_INTERVAL_MS = 500;
+// ── Internal helpers ─────────────────────────────────────────────────────────
+/** Extract key–value pairs from a YAML frontmatter block. */
+function parseNoteFrontmatter(content) {
+    const match = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---/m.exec(content);
+    if (!match?.[1])
+        return null;
+    const result = {};
+    for (const line of match[1].split(/\r?\n/)) {
+        const colonIdx = line.indexOf(":");
+        if (colonIdx < 1)
+            continue;
+        const key = line.slice(0, colonIdx).trim();
+        const value = line.slice(colonIdx + 1).trim();
+        if (key)
+            result[key] = value;
+    }
+    return result;
+}
+function appendTelemetry(telemetryFile, event) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(telemetryFile), { recursive: true });
+    (0, node_fs_1.appendFileSync)(telemetryFile, JSON.stringify(event) + "\n", "utf-8");
+}
+/** Poll until result file appears or timeout expires. */
+async function waitForResultFile(resultPath, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    do {
+        if ((0, node_fs_1.existsSync)(resultPath))
+            return true;
+        await new Promise((res) => setTimeout(res, POLL_INTERVAL_MS));
+    } while (Date.now() < deadline);
+    return (0, node_fs_1.existsSync)(resultPath);
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Dispatch a cognition-librarian session for each folder that has pending work
+ * notes with docs_impact ≠ "none". Non-blocking to cluster execution — a
+ * librarian failure does not halt the cluster.
+ */
+async function dispatchCognitionLibrarian(options) {
+    const { runId, clusterId, workNotePaths, repoRoot, adapter, provider, telemetryFile, timeoutMs = DEFAULT_TIMEOUT_MS, dryRun = false, } = options;
+    const groups = new Map();
+    for (const notePath of workNotePaths) {
+        const absPath = (0, node_path_1.resolve)(repoRoot, notePath);
+        let content;
+        try {
+            content = (0, node_fs_1.readFileSync)(absPath, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const meta = parseNoteFrontmatter(content);
+        if (!meta)
+            continue;
+        const folderSlug = meta["folder_slug"] ?? "";
+        const folder = meta["folder"] ?? "";
+        const docsImpact = meta["docs_impact"] ?? "none";
+        if (!folderSlug || docsImpact === "none")
+            continue;
+        if (!groups.has(folderSlug)) {
+            groups.set(folderSlug, { folder, folder_slug: folderSlug, note_paths: [] });
+        }
+        groups.get(folderSlug).note_paths.push(notePath);
+    }
+    if (groups.size === 0) {
+        return { dispatched: 0, outcomes: [] };
+    }
+    const outcomes = [];
+    let dispatched = 0;
+    for (const group of groups.values()) {
+        const dispatchId = (0, node_crypto_1.randomUUID)();
+        const cognitionDir = (0, node_path_1.join)(repoRoot, ".polaris", "cognition");
+        const packetPath = (0, node_path_1.join)(cognitionDir, "packets", `${dispatchId}.json`);
+        const resultPath = (0, node_path_1.join)(cognitionDir, "results", `${dispatchId}.json`);
+        const polarisMdPath = (0, node_path_1.join)(group.folder, "POLARIS.md");
+        const summaryMdAbsPath = (0, node_path_1.join)(repoRoot, group.folder, "SUMMARY.md");
+        const summaryMdPath = (0, node_fs_1.existsSync)(summaryMdAbsPath)
+            ? (0, node_path_1.join)(group.folder, "SUMMARY.md")
+            : null;
+        const cognitionIndexPath = (0, node_path_1.join)(".polaris", "cognition", "archive", group.folder_slug, "cognition-index.json");
+        const allowedFiles = [polarisMdPath];
+        if (summaryMdPath)
+            allowedFiles.push(summaryMdPath);
+        const packet = {
+            run_id: runId,
+            dispatch_id: dispatchId,
+            role: "cognition-librarian",
+            folder: group.folder,
+            folder_slug: group.folder_slug,
+            note_paths: group.note_paths,
+            polaris_md_path: polarisMdPath,
+            summary_md_path: summaryMdPath,
+            cognition_index_path: cognitionIndexPath,
+            result_path: resultPath,
+            constraints: {
+                max_polaris_addition_lines: 20,
+                max_summary_addition_lines: 30,
+                require_confidence_threshold: 0.80,
+                allowed_files: allowedFiles,
+            },
+        };
+        if (!dryRun) {
+            (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(packetPath), { recursive: true });
+            (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(resultPath), { recursive: true });
+            (0, node_fs_1.writeFileSync)(packetPath, JSON.stringify(packet, null, 2), "utf-8");
+            appendTelemetry(telemetryFile, {
+                event: "cognition-librarian-dispatched",
+                run_id: runId,
+                cluster_id: clusterId,
+                dispatch_id: dispatchId,
+                folder: group.folder,
+                folder_slug: group.folder_slug,
+                note_count: group.note_paths.length,
+                packet_path: packetPath,
+                result_path: resultPath,
+                timestamp: new Date().toISOString(),
+            });
+        }
+        try {
+            await adapter.dispatch({
+                schema_version: "2.1",
+                run_id: runId,
+                cluster_id: clusterId,
+                active_child: `cognition-librarian:${group.folder_slug}`,
+                state_file: packetPath,
+                telemetry_file: telemetryFile,
+                dispatch_id: dispatchId,
+                context: {
+                    role: "cognition-librarian",
+                    cognition_librarian_packet_path: packetPath,
+                },
+            }, { provider, dryRun });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (!dryRun) {
+                appendTelemetry(telemetryFile, {
+                    event: "cognition-librarian-patch-rejected",
+                    run_id: runId,
+                    dispatch_id: dispatchId,
+                    folder: group.folder,
+                    folder_slug: group.folder_slug,
+                    reason: "dispatch-error",
+                    error: msg,
+                    timestamp: new Date().toISOString(),
+                });
+            }
+            outcomes.push({
+                folder: group.folder,
+                folder_slug: group.folder_slug,
+                outcome: null,
+                error: msg,
+            });
+            continue;
+        }
+        dispatched += 1;
+        if (dryRun) {
+            outcomes.push({ folder: group.folder, folder_slug: group.folder_slug, outcome: null });
+            continue;
+        }
+        // Wait for result file — dispatch should have written it, poll as safety net.
+        const resultExists = await waitForResultFile(resultPath, timeoutMs);
+        if (!resultExists) {
+            const errMsg = `Cognition librarian result not found at ${resultPath} after ${timeoutMs}ms`;
+            appendTelemetry(telemetryFile, {
+                event: "cognition-librarian-patch-rejected",
+                run_id: runId,
+                dispatch_id: dispatchId,
+                folder: group.folder,
+                folder_slug: group.folder_slug,
+                reason: "result-timeout",
+                timestamp: new Date().toISOString(),
+            });
+            outcomes.push({
+                folder: group.folder,
+                folder_slug: group.folder_slug,
+                outcome: null,
+                error: errMsg,
+            });
+            continue;
+        }
+        let result;
+        try {
+            result = JSON.parse((0, node_fs_1.readFileSync)(resultPath, "utf-8"));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            outcomes.push({
+                folder: group.folder,
+                folder_slug: group.folder_slug,
+                outcome: null,
+                error: `Failed to parse librarian result: ${msg}`,
+            });
+            continue;
+        }
+        appendTelemetry(telemetryFile, {
+            event: "cognition-librarian-result-received",
+            run_id: runId,
+            dispatch_id: dispatchId,
+            folder: group.folder,
+            folder_slug: group.folder_slug,
+            status: result.status,
+            confidence: result.confidence,
+            notes_reconciled_count: result.notes_reconciled?.length ?? 0,
+            timestamp: new Date().toISOString(),
+        });
+        const outcome = validateAndApplyLibrarianResult(result, repoRoot, packet);
+        for (const rejected of outcome.patches_rejected) {
+            if (!rejected.reason.startsWith("COGNITION_USER_SURFACE_PROTECTED"))
+                continue;
+            appendTelemetry(telemetryFile, {
+                event: "cognition-user-surface-protected",
+                run_id: runId,
+                dispatch_id: dispatchId,
+                folder: group.folder,
+                folder_slug: group.folder_slug,
+                file: rejected.patch.file,
+                reason: rejected.reason,
+                timestamp: new Date().toISOString(),
+            });
+        }
+        if (outcome.approved) {
+            appendTelemetry(telemetryFile, {
+                event: "cognition-librarian-patch-applied",
+                run_id: runId,
+                dispatch_id: dispatchId,
+                folder: group.folder,
+                folder_slug: group.folder_slug,
+                files_written: outcome.files_written,
+                patches_applied_count: outcome.patches_applied.length,
+                timestamp: new Date().toISOString(),
+            });
+        }
+        else {
+            appendTelemetry(telemetryFile, {
+                event: "cognition-librarian-patch-rejected",
+                run_id: runId,
+                dispatch_id: dispatchId,
+                folder: group.folder,
+                folder_slug: group.folder_slug,
+                reason: outcome.rejection_reason,
+                timestamp: new Date().toISOString(),
+            });
+        }
+        outcomes.push({ folder: group.folder, folder_slug: group.folder_slug, outcome });
+    }
+    return { dispatched, outcomes };
+}
+/**
+ * Validate a cognition-librarian result against all 5 foreman safety rules
+ * (spec §6) and write approved patches to disk.
+ *
+ * Rules that reject the ENTIRE result (approved: false, no writes):
+ *   - Invalid schema
+ *   - Confidence below packet threshold (§6.4)
+ *   - Any patch targets a file outside allowed_files (§6.1)
+ *
+ * Rules that reject a SPECIFIC PATCH only (other patches still applied):
+ *   - SUMMARY.md patch contains doctrine bleed patterns (§6.2)
+ *   - Proposed content exceeds size constraints (§6.3)
+ */
+function validateAndApplyLibrarianResult(result, repoRoot, packet) {
+    // Rule: Schema validation — reject entire result on failure.
+    const schemaErrors = (0, librarian_types_js_1.validateCognitionLibrarianResult)(result);
+    if (schemaErrors.length > 0) {
+        return {
+            approved: false,
+            rejection_reason: `SCHEMA_INVALID: ${schemaErrors.join("; ")}`,
+            files_written: [],
+            patches_applied: [],
+            patches_rejected: [],
+        };
+    }
+    // Rule §6.4: Confidence threshold — reject entire result if below threshold.
+    if (result.confidence < packet.constraints.require_confidence_threshold) {
+        return {
+            approved: false,
+            rejection_reason: `COGNITION_LOW_CONFIDENCE: confidence ${result.confidence} below threshold ${packet.constraints.require_confidence_threshold}`,
+            files_written: [],
+            patches_applied: [],
+            patches_rejected: [],
+        };
+    }
+    // Rule §6.1: File scope check — reject entire result if any patch targets an out-of-scope file.
+    for (const patch of result.proposed_patches) {
+        if (!packet.constraints.allowed_files.includes(patch.file)) {
+            return {
+                approved: false,
+                rejection_reason: `COGNITION_SCOPE_VIOLATION: file "${patch.file}" not in allowed_files`,
+                files_written: [],
+                patches_applied: [],
+                patches_rejected: result.proposed_patches.map((p) => ({
+                    patch: p,
+                    reason: "result rejected due to scope violation",
+                })),
+            };
+        }
+    }
+    // No patches proposed — approved as no-change, notes can be archived.
+    if (result.proposed_patches.length === 0) {
+        return {
+            approved: true,
+            files_written: [],
+            patches_applied: [],
+            patches_rejected: [],
+        };
+    }
+    // Per-patch checks (doctrine bleed §6.2 and size guard §6.3).
+    // These reject the individual patch and continue applying the rest.
+    const patchesApplied = [];
+    const patchesRejected = [];
+    const filesWritten = [];
+    for (const patch of result.proposed_patches) {
+        const isSummaryPatch = patch.file === packet.summary_md_path;
+        const isPolarisPath = patch.file === packet.polaris_md_path;
+        if ((0, route_cognition_delta_js_1.isUserCreatedCognitionSurface)(patch.file, repoRoot)) {
+            patchesRejected.push({
+                patch,
+                reason: `COGNITION_USER_SURFACE_PROTECTED: "${patch.file}" is protected as user-created cognition surface`,
+            });
+            continue;
+        }
+        // Rule §6.2: Doctrine bleed — SUMMARY.md must not contain operational imperatives.
+        if (isSummaryPatch && (0, summary_delta_js_1.hasDoctrineBled)(patch.proposed_content)) {
+            patchesRejected.push({
+                patch,
+                reason: "COGNITION_DOCTRINE_BLEED: SUMMARY.md patch contains operational doctrine patterns",
+            });
+            continue;
+        }
+        // Rule §6.3: Size guard.
+        if (isPolarisPath) {
+            const lineCount = patch.proposed_content.split("\n").length;
+            if (lineCount > packet.constraints.max_polaris_addition_lines) {
+                patchesRejected.push({
+                    patch,
+                    reason: `COGNITION_SIZE_GUARD: POLARIS.md has ${lineCount} lines, max ${packet.constraints.max_polaris_addition_lines}`,
+                });
+                continue;
+            }
+        }
+        else if (isSummaryPatch && (0, summary_delta_js_1.isSummaryOversized)(patch.proposed_content)) {
+            patchesRejected.push({
+                patch,
+                reason: "COGNITION_SIZE_GUARD: SUMMARY.md patch exceeds SUMMARY_MAX_BYTES",
+            });
+            continue;
+        }
+        // All checks passed — write proposed content.
+        const absPath = (0, node_path_1.resolve)(repoRoot, patch.file);
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(absPath), { recursive: true });
+        (0, node_fs_1.writeFileSync)(absPath, patch.proposed_content, "utf-8");
+        filesWritten.push(patch.file);
+        patchesApplied.push(patch);
+    }
+    // approved = true when at least one patch was applied, or when there were no
+    // rejections (all patches passed — even if empty after early-return guard).
+    const approved = patchesApplied.length > 0 || patchesRejected.length === 0;
+    return {
+        approved,
+        ...(patchesApplied.length === 0 && patchesRejected.length > 0
+            ? { rejection_reason: "all patches rejected" }
+            : {}),
+        files_written: filesWritten,
+        patches_applied: patchesApplied,
+        patches_rejected: patchesRejected,
+    };
+}