@alan512/experienceengine 0.3.5 → 0.4.0

package/dist/maintenance/hygiene-governance-approvals.js

@@ -0,0 +1,143 @@
+import { createHash } from "node:crypto";
+import { GovernanceActionRepository, GovernanceApprovalRepository } from "../store/sqlite/repositories/hygiene-governance-repo.js";
+import { createId } from "../utils/ids.js";
+const TOKEN_TTL_MS = 10 * 60 * 1000;
+const hashValue = (value) => createHash("sha256").update(value, "utf8").digest("hex");
+const stableRowHash = (row) => createHash("sha256").update(JSON.stringify(row, Object.keys(row).sort()), "utf8").digest("hex");
+const parseRowRef = (ref) => {
+    const parts = ref.split(":");
+    if (parts.length !== 3) {
+        throw new Error(`Invalid governance row ref: ${ref}`);
+    }
+    return {
+        table: parts[0],
+        primaryKeyColumn: parts[1],
+        primaryKeyValue: parts[2]
+    };
+};
+const assertIdentifier = (value) => {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+        throw new Error(`Unsafe SQLite identifier: ${value}`);
+    }
+};
+const currentAffectedRowHashes = (db, refs) => {
+    const hashes = {};
+    for (const key of Object.keys(refs)) {
+        const ref = parseRowRef(key);
+        assertIdentifier(ref.table);
+        assertIdentifier(ref.primaryKeyColumn);
+        const row = db.prepare(`SELECT * FROM ${ref.table} WHERE ${ref.primaryKeyColumn} = ? LIMIT 1`).get(ref.primaryKeyValue);
+        if (!row) {
+            hashes[key] = "missing";
+            continue;
+        }
+        hashes[key] = stableRowHash(row);
+    }
+    return hashes;
+};
+const hashesMatch = (left, right) => {
+    const keys = Object.keys(left).sort();
+    if (keys.length !== Object.keys(right).length) {
+        return false;
+    }
+    return keys.every((key) => left[key] === right[key]);
+};
+export class HygieneGovernanceApprovalService {
+    db;
+    now;
+    constructor(db, now = () => new Date().toISOString()) {
+        this.db = db;
+        this.now = now;
+    }
+    planApproval(approvalId) {
+        const approval = new GovernanceApprovalRepository(this.db).get(approvalId);
+        if (!approval) {
+            throw new Error(`Governance approval not found: ${approvalId}`);
+        }
+        if (approval.status !== "pending") {
+            throw new Error(`Governance approval is not pending: ${approval.status}`);
+        }
+        const token = createId("governance_confirm");
+        const expiresAt = new Date(new Date(this.now()).getTime() + TOKEN_TTL_MS).toISOString();
+        this.db
+            .prepare(`UPDATE hygiene_governance_approvals
+         SET confirmation_token_hash = ?, token_expires_at = ?, updated_at = ?
+         WHERE approval_id = ? AND status = 'pending'`)
+            .run(hashValue(token), expiresAt, this.now(), approvalId);
+        return {
+            approvalId: approval.approval_id,
+            actionId: approval.action_id,
+            planId: approval.plan_id,
+            scopeId: approval.scope_id,
+            diffSummary: approval.diff_summary,
+            affectedRowHashes: approval.affected_row_hashes,
+            confirmationToken: token,
+            tokenExpiresAt: expiresAt
+        };
+    }
+    executeApproval(input) {
+        const approvalRepo = new GovernanceApprovalRepository(this.db);
+        const approval = approvalRepo.get(input.approvalId);
+        if (!approval) {
+            throw new Error(`Governance approval not found: ${input.approvalId}`);
+        }
+        if (approval.status === "approved") {
+            return { approvalId: approval.approval_id, actionId: approval.action_id, status: "already_approved" };
+        }
+        this.assertToken(approval, input.confirmationToken);
+        const currentHashes = currentAffectedRowHashes(this.db, approval.affected_row_hashes);
+        if (!hashesMatch(currentHashes, approval.affected_row_hashes)) {
+            this.db
+                .prepare("UPDATE hygiene_governance_approvals SET status = 'stale', updated_at = ? WHERE approval_id = ?")
+                .run(this.now(), approval.approval_id);
+            return {
+                approvalId: approval.approval_id,
+                actionId: approval.action_id,
+                status: "stale_replan_required",
+                reason: "affected_rows_changed"
+            };
+        }
+        this.db
+            .prepare(`UPDATE hygiene_governance_approvals
+         SET status = 'approved', decided_at = ?, updated_at = ?
+         WHERE approval_id = ? AND status = 'pending'`)
+            .run(this.now(), this.now(), approval.approval_id);
+        const action = new GovernanceActionRepository(this.db).get(approval.action_id);
+        if (action) {
+            this.db
+                .prepare("UPDATE hygiene_governance_actions SET status = 'applied', applied_at = ?, updated_at = ? WHERE action_id = ? AND status != 'applied'")
+                .run(this.now(), this.now(), action.action_id);
+        }
+        return { approvalId: approval.approval_id, actionId: approval.action_id, status: "approved" };
+    }
+    rejectApproval(approvalId) {
+        const approval = new GovernanceApprovalRepository(this.db).get(approvalId);
+        if (!approval) {
+            throw new Error(`Governance approval not found: ${approvalId}`);
+        }
+        if (approval.status === "rejected") {
+            return { approvalId: approval.approval_id, actionId: approval.action_id, status: "already_rejected" };
+        }
+        this.db
+            .prepare(`UPDATE hygiene_governance_approvals
+         SET status = 'rejected', decided_at = ?, updated_at = ?
+         WHERE approval_id = ?`)
+            .run(this.now(), this.now(), approval.approval_id);
+        this.db
+            .prepare("UPDATE hygiene_governance_actions SET status = 'rejected', updated_at = ? WHERE action_id = ? AND status != 'applied'")
+            .run(this.now(), approval.action_id);
+        return { approvalId: approval.approval_id, actionId: approval.action_id, status: "rejected" };
+    }
+    assertToken(approval, token) {
+        if (approval.status !== "pending") {
+            throw new Error(`Governance approval is not pending: ${approval.status}`);
+        }
+        if (!approval.confirmation_token_hash || approval.confirmation_token_hash !== hashValue(token)) {
+            throw new Error("Invalid or expired governance approval confirmation token.");
+        }
+        if (approval.token_expires_at && approval.token_expires_at <= this.now()) {
+            throw new Error("Invalid or expired governance approval confirmation token.");
+        }
+    }
+}
+//# sourceMappingURL=hygiene-governance-approvals.js.map

package/dist/maintenance/hygiene-governance-approvals.js.map

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

package/dist/maintenance/hygiene-governance-llm-planner.d.ts

@@ -0,0 +1,26 @@
+import type { DistillerEndpoint } from "../distillation/providers/types.js";
+import type { ExperienceEngineConfig } from "../config/config-schema.js";
+import type { HygieneGovernanceInput, HygieneGovernancePlannerProvider } from "./hygiene-governance-planner.js";
+type LlmHygieneGovernancePlannerConfig = Pick<ExperienceEngineConfig, "distillerProvider" | "distillerModel" | "distillationAuthMode">;
+export type LlmHygieneGovernancePlannerOptions = {
+    config: LlmHygieneGovernancePlannerConfig;
+    env?: NodeJS.ProcessEnv;
+    homeDir?: string;
+    fetchImpl?: typeof fetch;
+    maxRetries?: number;
+    retryDelayMs?: number;
+    resolveEndpoint?: (options?: {
+        env?: NodeJS.ProcessEnv;
+        homeDir?: string;
+        configProvider?: ExperienceEngineConfig["distillerProvider"];
+        configAuthMode?: string;
+        configModel?: string;
+    }) => DistillerEndpoint | null;
+};
+export declare class LlmHygieneGovernancePlanner implements HygieneGovernancePlannerProvider {
+    private readonly options;
+    constructor(options: LlmHygieneGovernancePlannerOptions);
+    hasEndpoint(): boolean;
+    plan(input: HygieneGovernanceInput): Promise<string>;
+}
+export {};

package/dist/maintenance/hygiene-governance-llm-planner.js

@@ -0,0 +1,169 @@
+import { resolveDistillerEndpoint } from "../distillation/host-llm.js";
+const SYSTEM_PROMPT = [
+    "You are the autonomous hygiene governance planner for ExperienceEngine.",
+    "Return strict JSON only with shape {\"source\":\"llm\",\"scopeId\":\"...\",\"findingHash\":\"...\",\"clusters\":[],\"actions\":[]}.",
+    "Use only ids present in the input. Do not invent node ids, candidate ids, evidence refs, action types, or scope ids.",
+    "Cluster semantic duplicates, overlapping applicability, and conflicting guidance.",
+    "For every high or medium severity conflict cluster, include at least one governance action.",
+    "When the safe mutation is uncertain, still propose a high-risk guarded action instead of leaving the cluster actionless.",
+    "Prefer safe, evidence-preserving actions: merge_exact_duplicate, merge_near_duplicate, retire_stale_shadow, downgrade_delivery, quarantine.",
+    "Mark uncertain semantic merges, conflicted helped/harmed merges, promotion, and soft deletion as high risk; ExperienceEngine will apply accepted high-risk experience-node actions conservatively with rollback snapshots.",
+    "Do not propose export writing, repo policy changes, restore, or broad rewrite unless the input includes an explicit replacement contract.",
+    "For merge actions choose a canonical node with stronger helped/support evidence or newer evidence.",
+    "Do not broaden applicability. Preserve narrower triggers, avoid steps, and evidence references in the rationale.",
+    "If no safe action is supported, return clusters explaining the conflict and no actions."
+].join(" ");
+const buildPrompt = (input) => JSON.stringify({
+    task: "Plan hygiene governance actions for this ExperienceEngine scope.",
+    outputContract: {
+        source: "llm",
+        scopeId: input.scope.scopeId,
+        findingHash: input.findingHash,
+        clusters: [
+            {
+                clusterId: "stable descriptive id",
+                type: "duplicate_guidance | conflicting_guidance | over_generalized_guidance | evidence_drift | stale_experience | stale_shadow",
+                nodeIds: ["existing node ids only"],
+                candidateIds: ["existing candidate ids only"],
+                rationale: "why these entries belong together"
+            }
+        ],
+        actions: [
+            {
+                actionId: "stable descriptive id",
+                actionType: "merge_exact_duplicate | merge_near_duplicate | retire_stale_shadow | downgrade_delivery | quarantine | promote_delivery | delete_record | export_guidance | change_repo_policy | restore_guidance | rewrite_guidance",
+                riskLevel: "low | medium | high",
+                approvalRequired: false,
+                affectedNodeIds: ["existing node ids only"],
+                affectedCandidateIds: ["existing candidate ids only"],
+                canonicalNodeId: "required for merge actions",
+                expectedEffect: "specific risk reduction",
+                rationale: "evidence-preserving reason"
+            }
+        ]
+    },
+    input
+}, null, 2);
+const buildRequestUrl = (endpoint) => {
+    if (endpoint.kind === "anthropic" || endpoint.kind === "gemini" || endpoint.kind === "bedrock") {
+        return endpoint.baseUrl;
+    }
+    if (/\/chat\/completions(?:\?.*)?$/.test(endpoint.baseUrl)) {
+        return endpoint.baseUrl;
+    }
+    if (/\/v1\/?$/.test(endpoint.baseUrl)) {
+        return `${endpoint.baseUrl.replace(/\/$/, "")}/chat/completions`;
+    }
+    return `${endpoint.baseUrl.replace(/\/$/, "")}/v1/chat/completions`;
+};
+const buildRequestBody = (endpoint, prompt) => {
+    if (endpoint.kind === "anthropic") {
+        return {
+            model: endpoint.model,
+            max_tokens: 4096,
+            system: SYSTEM_PROMPT,
+            messages: [{ role: "user", content: prompt }],
+            temperature: 0
+        };
+    }
+    if (endpoint.kind === "gemini") {
+        return {
+            system_instruction: { parts: [{ text: SYSTEM_PROMPT }] },
+            contents: [{ role: "user", parts: [{ text: prompt }] }],
+            generationConfig: {
+                temperature: 0,
+                responseMimeType: "application/json"
+            }
+        };
+    }
+    if (endpoint.kind === "bedrock") {
+        return {
+            system: [{ text: SYSTEM_PROMPT }],
+            messages: [{ role: "user", content: [{ text: prompt }] }],
+            inferenceConfig: {
+                maxTokens: 4096,
+                temperature: 0
+            }
+        };
+    }
+    return {
+        model: endpoint.model,
+        response_format: { type: "json_object" },
+        temperature: 0,
+        messages: [
+            { role: "system", content: SYSTEM_PROMPT },
+            { role: "user", content: prompt }
+        ]
+    };
+};
+const extractTextPayload = async (endpoint, response) => {
+    if (endpoint.kind === "anthropic") {
+        const payload = (await response.json());
+        return payload.content?.find((entry) => entry.type === "text" && typeof entry.text === "string")?.text ?? "";
+    }
+    if (endpoint.kind === "gemini") {
+        const payload = (await response.json());
+        return payload.candidates?.[0]?.content?.parts?.find((entry) => typeof entry.text === "string")?.text ?? "";
+    }
+    if (endpoint.kind === "bedrock") {
+        const payload = (await response.json());
+        return payload.output?.message?.content?.find((entry) => typeof entry.text === "string")?.text ?? "";
+    }
+    const payload = (await response.json());
+    return payload.choices?.[0]?.message?.content ?? "";
+};
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const shouldRetry = (status) => status === 429 || status >= 500;
+export class LlmHygieneGovernancePlanner {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    hasEndpoint() {
+        return Boolean((this.options.resolveEndpoint ?? resolveDistillerEndpoint)({
+            env: this.options.env,
+            homeDir: this.options.homeDir,
+            configProvider: this.options.config.distillerProvider,
+            configAuthMode: this.options.config.distillationAuthMode,
+            configModel: this.options.config.distillerModel
+        }));
+    }
+    async plan(input) {
+        const endpoint = (this.options.resolveEndpoint ?? resolveDistillerEndpoint)({
+            env: this.options.env,
+            homeDir: this.options.homeDir,
+            configProvider: this.options.config.distillerProvider,
+            configAuthMode: this.options.config.distillationAuthMode,
+            configModel: this.options.config.distillerModel
+        });
+        if (!endpoint) {
+            throw new Error("No configured ExperienceEngine distiller endpoint is available for hygiene governance planning.");
+        }
+        const request = {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                ...endpoint.headers
+            },
+            body: JSON.stringify(buildRequestBody(endpoint, buildPrompt(input)))
+        };
+        const maxRetries = this.options.maxRetries ?? 2;
+        let response;
+        for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+            response = await (this.options.fetchImpl ?? fetch)(buildRequestUrl(endpoint), request);
+            if (response.ok || !shouldRetry(response.status) || attempt === maxRetries) {
+                break;
+            }
+            await sleep((this.options.retryDelayMs ?? 500) * (attempt + 1));
+        }
+        if (!response?.ok) {
+            throw new Error(`Hygiene governance LLM planner failed with HTTP ${response?.status ?? "unknown"}.`);
+        }
+        const text = await extractTextPayload(endpoint, response);
+        if (!text.trim()) {
+            throw new Error("Hygiene governance LLM planner returned an empty response.");
+        }
+        return text;
+    }
+}
+//# sourceMappingURL=hygiene-governance-llm-planner.js.map

package/dist/maintenance/hygiene-governance-llm-planner.js.map

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

package/dist/maintenance/hygiene-governance-planner.d.ts

@@ -0,0 +1,113 @@
+import type { AttributionRecord, ExperienceCandidate, ExperienceNode, Scope } from "../types/domain.js";
+import { type HygieneFinding, type HygieneReviewReport } from "./experience-hygiene.js";
+export type HygieneGovernanceScopeInput = {
+    scopeId: string;
+    scopeName?: string;
+    scopeType?: Scope["scope_type"];
+};
+export type HygieneGovernanceNodeSummary = {
+    id: string;
+    scopeId: string;
+    nodeType: ExperienceNode["node_type"];
+    taskType: ExperienceNode["task_type"];
+    state: ExperienceNode["state"];
+    deliveryState?: ExperienceNode["delivery_state"];
+    triggerPattern: string;
+    compactHint: string;
+    recommendedSteps: string[];
+    avoidSteps: string[];
+    originRecordIds: string[];
+    helpedRecordIds: string[];
+    harmedRecordIds: string[];
+    usageCount: number;
+    helpedCount: number;
+    harmedCount: number;
+    supportCount: number;
+    updatedAt: string;
+};
+export type HygieneGovernanceCandidateSummary = {
+    id: string;
+    sourceRecordId: string;
+    taskType: ExperienceCandidate["task_type"];
+    nodeType: ExperienceCandidate["node_type"];
+    lifecycleState: ExperienceCandidate["lifecycle_state"];
+    triggerPattern: string;
+    compactHint: string;
+    recommendedSteps: string[];
+    avoidSteps: string[];
+    retryCount: number;
+    updatedAt: string;
+};
+export type HygieneGovernanceAttributionSummary = {
+    id: string;
+    nodeId: string;
+    delivered: boolean;
+    outcome: AttributionRecord["outcome"];
+    verdict: AttributionRecord["attribution_verdict"];
+    confidence: AttributionRecord["confidence"];
+    evidenceRefs: string[];
+    createdAt: string;
+};
+export type HygieneGovernanceExportRiskNote = {
+    nodeId: string;
+    reason: string;
+    evidenceRefs: string[];
+};
+export type BuildHygieneGovernanceInput = HygieneGovernanceScopeInput & {
+    nodes: ExperienceNode[];
+    candidates: ExperienceCandidate[];
+    attributionRecords: AttributionRecord[];
+    now?: string;
+    maxFindings?: number;
+    maxNodes?: number;
+    maxCandidates?: number;
+    maxAttributions?: number;
+    exportRiskEnabled?: boolean;
+};
+export type HygieneGovernanceInput = {
+    scope: HygieneGovernanceScopeInput;
+    generatedAt: string;
+    findingHash: string;
+    review: HygieneReviewReport["summary"];
+    findings: HygieneFinding[];
+    nodes: HygieneGovernanceNodeSummary[];
+    candidates: HygieneGovernanceCandidateSummary[];
+    attributions: HygieneGovernanceAttributionSummary[];
+    exportRiskNotes: HygieneGovernanceExportRiskNote[];
+    evidenceRefs: string[];
+};
+export declare const HYGIENE_GOVERNANCE_ACTION_TYPES: readonly ["merge_exact_duplicate", "merge_near_duplicate", "retire_stale_shadow", "downgrade_delivery", "quarantine", "promote_delivery", "delete_record", "export_guidance", "change_repo_policy", "restore_guidance", "rewrite_guidance"];
+export type HygieneGovernanceActionType = (typeof HYGIENE_GOVERNANCE_ACTION_TYPES)[number];
+export type HygieneGovernanceRiskLevel = "low" | "medium" | "high";
+export type HygieneGovernancePlanAction = {
+    actionId: string;
+    actionType: HygieneGovernanceActionType;
+    riskLevel: HygieneGovernanceRiskLevel;
+    approvalRequired: boolean;
+    affectedNodeIds: string[];
+    affectedCandidateIds: string[];
+    canonicalNodeId?: string;
+    expectedEffect: string;
+    rationale?: string;
+};
+export type HygieneGovernancePlanCluster = {
+    clusterId: string;
+    type: HygieneFinding["type"] | "stale_shadow";
+    nodeIds: string[];
+    candidateIds: string[];
+    rationale: string;
+};
+export type HygieneGovernancePlan = {
+    source: "llm" | "deterministic_fallback";
+    scopeId: string;
+    findingHash: string;
+    clusters: HygieneGovernancePlanCluster[];
+    actions: HygieneGovernancePlanAction[];
+};
+export type HygieneGovernancePlannerProvider = {
+    plan(input: HygieneGovernanceInput): Promise<string>;
+};
+export declare const buildHygieneGovernanceInput: (input: BuildHygieneGovernanceInput) => HygieneGovernanceInput;
+export declare const planHygieneGovernance: (input: HygieneGovernanceInput, options?: {
+    planner?: HygieneGovernancePlannerProvider;
+}) => Promise<HygieneGovernancePlan>;