@alan512/experienceengine 0.3.5 → 0.4.0

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

@@ -0,0 +1,302 @@
+import { z } from "zod";
+import { stableId } from "../utils/ids.js";
+import { buildHygieneReviewReport } from "./experience-hygiene.js";
+export const HYGIENE_GOVERNANCE_ACTION_TYPES = [
+    "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"
+];
+const DEFAULT_MAX_FINDINGS = 20;
+const DEFAULT_MAX_NODES = 30;
+const DEFAULT_MAX_CANDIDATES = 30;
+const DEFAULT_MAX_ATTRIBUTIONS = 50;
+const planSchema = z.object({
+    source: z.enum(["llm", "deterministic_fallback"]),
+    scopeId: z.string().min(1),
+    findingHash: z.string().min(1),
+    clusters: z.array(z.object({
+        clusterId: z.string().min(1),
+        type: z.union([
+            z.enum(["stale_shadow"]),
+            z.enum([
+                "stale_experience",
+                "duplicate_guidance",
+                "conflicting_guidance",
+                "over_generalized_guidance",
+                "evidence_drift"
+            ])
+        ]),
+        nodeIds: z.array(z.string()),
+        candidateIds: z.array(z.string()),
+        rationale: z.string().min(1)
+    })),
+    actions: z.array(z.object({
+        actionId: z.string().min(1),
+        actionType: z.enum(HYGIENE_GOVERNANCE_ACTION_TYPES),
+        riskLevel: z.enum(["low", "medium", "high"]),
+        approvalRequired: z.boolean(),
+        affectedNodeIds: z.array(z.string()),
+        affectedCandidateIds: z.array(z.string()),
+        canonicalNodeId: z.string().optional(),
+        expectedEffect: z.string().min(1),
+        rationale: z.string().optional()
+    }))
+});
+const uniqueSorted = (values) => [...new Set(values.filter((value) => Boolean(value)))].sort();
+const summarizeNode = (node) => ({
+    id: node.id,
+    scopeId: node.scope_id,
+    nodeType: node.node_type,
+    taskType: node.task_type,
+    state: node.state,
+    deliveryState: node.delivery_state,
+    triggerPattern: node.trigger_pattern,
+    compactHint: node.compact_hint,
+    recommendedSteps: node.recommended_steps ?? [],
+    avoidSteps: node.avoid_steps ?? [],
+    originRecordIds: node.origin_record_ids,
+    helpedRecordIds: node.helped_record_ids,
+    harmedRecordIds: node.harmed_record_ids,
+    usageCount: node.usage_count,
+    helpedCount: node.helped_count,
+    harmedCount: node.harmed_count,
+    supportCount: node.support_count,
+    updatedAt: node.updated_at
+});
+const summarizeCandidate = (candidate) => ({
+    id: candidate.id,
+    sourceRecordId: candidate.source_record_id,
+    taskType: candidate.task_type,
+    nodeType: candidate.node_type,
+    lifecycleState: candidate.lifecycle_state,
+    triggerPattern: candidate.trigger_pattern,
+    compactHint: candidate.compact_hint,
+    recommendedSteps: candidate.recommended_steps ?? [],
+    avoidSteps: candidate.avoid_steps ?? [],
+    retryCount: candidate.retry_count,
+    updatedAt: candidate.updated_at
+});
+const summarizeAttribution = (record) => ({
+    id: record.id,
+    nodeId: record.node_id,
+    delivered: record.delivered,
+    outcome: record.outcome,
+    verdict: record.attribution_verdict,
+    confidence: record.confidence,
+    evidenceRefs: record.evidence_refs,
+    createdAt: record.created_at
+});
+const normalizeFindingForHash = (finding) => ({
+    type: finding.type,
+    severity: finding.severity,
+    affectedNodeIds: uniqueSorted(finding.affectedNodeIds),
+    affectedCandidateIds: uniqueSorted(finding.affectedCandidateIds),
+    evidenceRefs: uniqueSorted(finding.evidenceRefs)
+});
+const buildFindingHash = (scopeId, findings) => stableId("hygiene_findings", JSON.stringify({
+    scopeId,
+    findings: findings
+        .map(normalizeFindingForHash)
+        .sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)))
+}));
+const compareByRisk = (left, right) => (right.harmed_count - left.harmed_count)
+    || (right.helped_count - left.helped_count)
+    || right.updated_at.localeCompare(left.updated_at);
+const buildExportRiskNotes = (nodes, attributionRecords, enabled) => {
+    if (!enabled) {
+        return [];
+    }
+    const harmfulEvidenceByNode = new Map();
+    for (const record of attributionRecords) {
+        if (record.attribution_verdict !== "strong_harmed" && record.attribution_verdict !== "weak_harmed") {
+            continue;
+        }
+        harmfulEvidenceByNode.set(record.node_id, [
+            ...(harmfulEvidenceByNode.get(record.node_id) ?? []),
+            ...record.evidence_refs
+        ]);
+    }
+    return nodes
+        .filter((node) => node.delivery_state === "eligible" && harmfulEvidenceByNode.has(node.id))
+        .sort(compareByRisk)
+        .map((node) => ({
+        nodeId: node.id,
+        reason: "eligible guidance has recent harmed attribution",
+        evidenceRefs: uniqueSorted([...(harmfulEvidenceByNode.get(node.id) ?? []), ...node.harmed_record_ids])
+    }));
+};
+export const buildHygieneGovernanceInput = (input) => {
+    const maxFindings = input.maxFindings ?? DEFAULT_MAX_FINDINGS;
+    const report = buildHygieneReviewReport({
+        nodes: input.nodes,
+        candidates: input.candidates,
+        attributionRecords: input.attributionRecords,
+        filters: {
+            scopeId: input.scopeId,
+            now: input.now,
+            limit: maxFindings
+        }
+    });
+    const findings = report.findings.slice(0, maxFindings);
+    const findingNodeIds = new Set(findings.flatMap((finding) => finding.affectedNodeIds));
+    const findingCandidateIds = new Set(findings.flatMap((finding) => finding.affectedCandidateIds));
+    const nodes = input.nodes
+        .filter((node) => node.scope_id === input.scopeId && (findingNodeIds.size === 0 || findingNodeIds.has(node.id)))
+        .sort(compareByRisk)
+        .slice(0, input.maxNodes ?? DEFAULT_MAX_NODES)
+        .map(summarizeNode);
+    const candidates = input.candidates
+        .filter((candidate) => candidate.scope_id === input.scopeId && (findingCandidateIds.size === 0 || findingCandidateIds.has(candidate.id)))
+        .sort((left, right) => right.updated_at.localeCompare(left.updated_at))
+        .slice(0, input.maxCandidates ?? DEFAULT_MAX_CANDIDATES)
+        .map(summarizeCandidate);
+    const attributions = input.attributionRecords
+        .filter((record) => !findingNodeIds.size || findingNodeIds.has(record.node_id))
+        .sort((left, right) => right.created_at.localeCompare(left.created_at))
+        .slice(0, input.maxAttributions ?? DEFAULT_MAX_ATTRIBUTIONS)
+        .map(summarizeAttribution);
+    const exportRiskNotes = buildExportRiskNotes(input.nodes, input.attributionRecords, input.exportRiskEnabled ?? false);
+    const evidenceRefs = uniqueSorted([
+        ...findings.flatMap((finding) => finding.evidenceRefs),
+        ...nodes.flatMap((node) => [...node.originRecordIds, ...node.helpedRecordIds, ...node.harmedRecordIds]),
+        ...candidates.map((candidate) => candidate.sourceRecordId),
+        ...attributions.flatMap((record) => record.evidenceRefs),
+        ...exportRiskNotes.flatMap((note) => note.evidenceRefs)
+    ]);
+    return {
+        scope: {
+            scopeId: input.scopeId,
+            scopeName: input.scopeName,
+            scopeType: input.scopeType
+        },
+        generatedAt: report.generatedAt,
+        findingHash: buildFindingHash(input.scopeId, findings),
+        review: report.summary,
+        findings,
+        nodes,
+        candidates,
+        attributions,
+        exportRiskNotes,
+        evidenceRefs
+    };
+};
+const parseStrictJsonPlan = (raw) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Invalid hygiene governance plan JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const result = planSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new Error(`Invalid hygiene governance plan: ${result.error.issues.map((issue) => issue.message).join("; ")}`);
+    }
+    return result.data;
+};
+const chooseCanonicalNode = (nodes) => [...nodes].sort((left, right) => (right.helpedCount - left.helpedCount)
+    || (right.supportCount - left.supportCount)
+    || right.updatedAt.localeCompare(left.updatedAt)
+    || left.id.localeCompare(right.id))[0];
+const exactDuplicateKey = (node) => JSON.stringify({
+    taskType: node.taskType,
+    nodeType: node.nodeType,
+    triggerPattern: node.triggerPattern.trim().toLowerCase(),
+    compactHint: node.compactHint.trim().toLowerCase()
+});
+const buildDeterministicFallbackPlan = (input) => {
+    const clusters = [];
+    const actions = [];
+    const nodesById = new Map(input.nodes.map((node) => [node.id, node]));
+    const duplicateGroups = new Map();
+    for (const node of input.nodes) {
+        if (node.deliveryState === "shadow_only") {
+            continue;
+        }
+        const group = duplicateGroups.get(exactDuplicateKey(node)) ?? [];
+        group.push(node);
+        duplicateGroups.set(exactDuplicateKey(node), group);
+    }
+    for (const nodes of duplicateGroups.values()) {
+        if (nodes.length < 2) {
+            continue;
+        }
+        const sortedIds = uniqueSorted(nodes.map((node) => node.id));
+        const canonical = chooseCanonicalNode(nodes);
+        const clusterId = stableId("hygiene_cluster", `${input.scope.scopeId}:exact:${sortedIds.join(",")}`);
+        clusters.push({
+            clusterId,
+            type: "duplicate_guidance",
+            nodeIds: sortedIds,
+            candidateIds: [],
+            rationale: "Nodes have identical task type, node type, trigger, and compact hint."
+        });
+        actions.push({
+            actionId: stableId("hygiene_action", `${clusterId}:merge_exact_duplicate:${canonical.id}`),
+            actionType: "merge_exact_duplicate",
+            riskLevel: "low",
+            approvalRequired: false,
+            affectedNodeIds: sortedIds,
+            affectedCandidateIds: [],
+            canonicalNodeId: canonical.id,
+            expectedEffect: "Consolidate exact duplicate guidance while preserving evidence on the canonical node.",
+            rationale: "Exact duplicate guidance can be safely proposed for automatic merge subject to validators."
+        });
+    }
+    for (const node of input.nodes) {
+        if ((node.state !== "candidate" && node.state !== "priority_candidate")
+            || node.deliveryState !== "shadow_only"
+            || node.usageCount > 0
+            || node.helpedCount > 0
+            || node.supportCount > 0) {
+            continue;
+        }
+        const clusterId = stableId("hygiene_cluster", `${input.scope.scopeId}:stale_shadow:${node.id}`);
+        if (!nodesById.has(node.id)) {
+            continue;
+        }
+        clusters.push({
+            clusterId,
+            type: "stale_shadow",
+            nodeIds: [node.id],
+            candidateIds: [],
+            rationale: "Shadow-only guidance has no usage, helped, or support evidence."
+        });
+        actions.push({
+            actionId: stableId("hygiene_action", `${clusterId}:retire_stale_shadow`),
+            actionType: "retire_stale_shadow",
+            riskLevel: "low",
+            approvalRequired: false,
+            affectedNodeIds: [node.id],
+            affectedCandidateIds: [],
+            expectedEffect: "Retire stale shadow-only guidance that has no supporting runtime evidence.",
+            rationale: "The action remains subject to stale-retire validators before mutation."
+        });
+    }
+    return {
+        source: "deterministic_fallback",
+        scopeId: input.scope.scopeId,
+        findingHash: input.findingHash,
+        clusters,
+        actions
+    };
+};
+export const planHygieneGovernance = async (input, options = {}) => {
+    if (!options.planner) {
+        return buildDeterministicFallbackPlan(input);
+    }
+    const plan = parseStrictJsonPlan(await options.planner.plan(input));
+    if (plan.scopeId !== input.scope.scopeId || plan.findingHash !== input.findingHash) {
+        throw new Error("Invalid hygiene governance plan: scopeId or findingHash does not match the planner input");
+    }
+    return plan;
+};
+//# sourceMappingURL=hygiene-governance-planner.js.map

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

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

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

@@ -0,0 +1,72 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { HygieneGovernancePlannerProvider } from "./hygiene-governance-planner.js";
+export type GovernanceDrainResult = {
+    status: "completed";
+} | {
+    status: "checkpointed";
+    checkpoint: Record<string, unknown>;
+} | {
+    status: "deferred";
+    reason: "lease_held" | "not_scheduled" | "backoff";
+} | {
+    status: "failed";
+    failureClass: string;
+    message: string;
+};
+export type GovernanceDrainWorker = {
+    drain(input: {
+        scopeId: string;
+        runId?: string;
+        checkpoint?: Record<string, unknown>;
+        now: string;
+        budget: {
+            maxActions: number;
+            maxRuntimeMs: number;
+        };
+    }): Promise<{
+        status: "completed";
+    } | {
+        status: "checkpointed";
+        checkpoint: Record<string, unknown>;
+    }>;
+};
+export type SchedulerOptions = {
+    now?: () => string;
+    intervalMs?: number;
+    leaseTtlMs?: number;
+    backoffMs?: number;
+    maxActions?: number;
+    maxRuntimeMs?: number;
+    hostInstanceId?: string;
+    worker?: GovernanceDrainWorker;
+    planner?: HygieneGovernancePlannerProvider;
+};
+export declare class HygieneGovernanceScheduler {
+    private readonly db;
+    private readonly scheduleRepo;
+    private readonly leaseRepo;
+    private readonly runRepo;
+    private readonly now;
+    private readonly intervalMs;
+    private readonly leaseTtlMs;
+    private readonly backoffMs;
+    private readonly maxActions;
+    private readonly maxRuntimeMs;
+    private readonly hostInstanceId;
+    private readonly worker;
+    constructor(db: DatabaseSync, options?: SchedulerOptions);
+    maybeEnqueue(input: {
+        cwd?: string;
+        scopeId?: string;
+        trigger: string;
+        findingHash?: string;
+    }): {
+        scopeId: string;
+        enqueued: boolean;
+        reason: "due" | "not_due" | "backoff";
+    };
+    drainDueScope(scopeId: string): Promise<GovernanceDrainResult>;
+}
+export declare const drainDueHygieneGovernance: (db: DatabaseSync, options: SchedulerOptions & {
+    scopeId: string;
+}) => Promise<GovernanceDrainResult>;

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

@@ -0,0 +1,206 @@
+import { resolveScope } from "../input/scope-resolver.js";
+import { buildHygieneGovernanceInput, planHygieneGovernance } from "./hygiene-governance-planner.js";
+import { validateHygieneGovernancePlan } from "./hygiene-governance-validator.js";
+import { applyValidatedHygieneGovernanceActions } from "./hygiene-governance-applicator.js";
+import { AttributionRecordRepository } from "../store/sqlite/repositories/attribution-record-repo.js";
+import { CandidateRepository } from "../store/sqlite/repositories/candidate-repo.js";
+import { NodeRepository } from "../store/sqlite/repositories/node-repo.js";
+import { ScopeRepository } from "../store/sqlite/repositories/scope-repo.js";
+import { GovernanceLeaseRepository, GovernancePlanRepository, GovernanceRunRepository, GovernanceScheduleRepository } from "../store/sqlite/repositories/hygiene-governance-repo.js";
+const DEFAULT_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_LEASE_TTL_MS = 5 * 60 * 1000;
+const DEFAULT_BACKOFF_MS = 60 * 60 * 1000;
+const DEFAULT_MAX_ACTIONS = 20;
+const DEFAULT_MAX_RUNTIME_MS = 5_000;
+class DefaultHygieneGovernanceWorker {
+    db;
+    planner;
+    constructor(db, planner) {
+        this.db = db;
+        this.planner = planner;
+    }
+    async drain(input) {
+        const scope = new ScopeRepository(this.db).getById(input.scopeId);
+        const nodes = new NodeRepository(this.db).listByScope(input.scopeId);
+        const candidates = new CandidateRepository(this.db).listByScope(input.scopeId);
+        const attributionRecords = new AttributionRecordRepository(this.db).listRecentByScope(input.scopeId, 50);
+        const governanceInput = buildHygieneGovernanceInput({
+            scopeId: input.scopeId,
+            scopeName: scope?.scope_name,
+            scopeType: scope?.scope_type,
+            nodes,
+            candidates,
+            attributionRecords,
+            now: input.now,
+            maxFindings: input.budget.maxActions,
+            maxNodes: Math.max(input.budget.maxActions * 2, input.budget.maxActions),
+            maxCandidates: input.budget.maxActions,
+            exportRiskEnabled: true
+        });
+        const planRepo = new GovernancePlanRepository(this.db);
+        const reusablePlan = planRepo.findReusableCompletedPlan(input.scopeId, governanceInput.findingHash);
+        if (reusablePlan) {
+            this.db
+                .prepare("UPDATE hygiene_governance_schedules SET last_finding_hash = ?, last_run_status = 'completed', updated_at = ? WHERE scope_id = ?")
+                .run(governanceInput.findingHash, input.now, input.scopeId);
+            return { status: "completed" };
+        }
+        const plan = await planHygieneGovernance(governanceInput, this.planner ? { planner: this.planner } : {});
+        const validation = validateHygieneGovernancePlan(governanceInput, plan);
+        const storedPlan = planRepo.create({
+            run_id: input.runId,
+            scope_id: input.scopeId,
+            status: "proposed",
+            finding_hash: governanceInput.findingHash,
+            risk: plan.actions.some((action) => action.riskLevel === "high") ? "high" : "low",
+            plan: plan,
+            validator_result: validation,
+            created_at: input.now,
+            updated_at: input.now
+        });
+        applyValidatedHygieneGovernanceActions(this.db, {
+            input: governanceInput,
+            plan,
+            validation,
+            runId: input.runId,
+            planId: storedPlan.plan_id,
+            now: input.now,
+            maxActions: input.budget.maxActions
+        });
+        this.db
+            .prepare(`UPDATE hygiene_governance_plans
+         SET status = 'completed', updated_at = ?
+         WHERE plan_id = ?`)
+            .run(input.now, storedPlan.plan_id);
+        this.db
+            .prepare("UPDATE hygiene_governance_schedules SET last_finding_hash = ?, last_run_status = 'completed', updated_at = ? WHERE scope_id = ?")
+            .run(governanceInput.findingHash, input.now, input.scopeId);
+        return { status: "completed" };
+    }
+}
+export class HygieneGovernanceScheduler {
+    db;
+    scheduleRepo;
+    leaseRepo;
+    runRepo;
+    now;
+    intervalMs;
+    leaseTtlMs;
+    backoffMs;
+    maxActions;
+    maxRuntimeMs;
+    hostInstanceId;
+    worker;
+    constructor(db, options = {}) {
+        this.db = db;
+        this.scheduleRepo = new GovernanceScheduleRepository(db);
+        this.leaseRepo = new GovernanceLeaseRepository(db);
+        this.runRepo = new GovernanceRunRepository(db);
+        this.now = options.now ?? (() => new Date().toISOString());
+        this.intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+        this.leaseTtlMs = options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS;
+        this.backoffMs = options.backoffMs ?? DEFAULT_BACKOFF_MS;
+        this.maxActions = options.maxActions ?? DEFAULT_MAX_ACTIONS;
+        this.maxRuntimeMs = options.maxRuntimeMs ?? DEFAULT_MAX_RUNTIME_MS;
+        this.hostInstanceId = options.hostInstanceId ?? "host";
+        this.worker = options.worker ?? new DefaultHygieneGovernanceWorker(db, options.planner);
+    }
+    maybeEnqueue(input) {
+        const scopeId = input.scopeId ?? resolveScope(input.cwd).scope_id;
+        const result = this.scheduleRepo.maybeEnqueue({
+            scopeId,
+            trigger: input.trigger,
+            now: this.now(),
+            intervalMs: this.intervalMs,
+            findingHash: input.findingHash
+        });
+        return {
+            scopeId,
+            ...result
+        };
+    }
+    async drainDueScope(scopeId) {
+        const now = this.now();
+        const schedule = this.scheduleRepo.get(scopeId);
+        if (!schedule) {
+            return { status: "deferred", reason: "not_scheduled" };
+        }
+        if (schedule.backoff_until && schedule.backoff_until > now) {
+            return { status: "deferred", reason: "backoff" };
+        }
+        const lease = this.leaseRepo.acquire({
+            scopeId,
+            owner: this.hostInstanceId,
+            now,
+            ttlMs: this.leaseTtlMs
+        });
+        if (!lease) {
+            return { status: "deferred", reason: "lease_held" };
+        }
+        const pendingRun = this.runRepo.listByScope(scopeId).find((entry) => entry.status === "pending");
+        const run = pendingRun ?? this.runRepo.create({
+            scope_id: scopeId,
+            trigger: schedule.pending_reasons[0] ?? "scheduled",
+            status: "running",
+            started_at: now,
+            created_at: now,
+            updated_at: now
+        });
+        if (pendingRun) {
+            this.db
+                .prepare(`UPDATE hygiene_governance_runs
+           SET status = 'running', started_at = COALESCE(started_at, ?), updated_at = ?
+           WHERE run_id = ?`)
+                .run(now, now, pendingRun.run_id);
+        }
+        try {
+            const result = await this.worker.drain({
+                scopeId,
+                runId: run.run_id,
+                checkpoint: run.checkpoint,
+                now,
+                budget: { maxActions: this.maxActions, maxRuntimeMs: this.maxRuntimeMs }
+            });
+            if (result.status === "checkpointed") {
+                const checkpointedAt = this.now();
+                this.db
+                    .prepare(`UPDATE hygiene_governance_runs
+             SET status = 'pending', checkpoint_json = ?, updated_at = ?
+             WHERE run_id = ?`)
+                    .run(JSON.stringify(result.checkpoint), checkpointedAt, run.run_id);
+                this.leaseRepo.release(scopeId, this.hostInstanceId);
+                return { status: "checkpointed", checkpoint: result.checkpoint };
+            }
+            const completedAt = this.now();
+            this.db
+                .prepare(`UPDATE hygiene_governance_runs
+           SET status = 'completed', finished_at = ?, updated_at = ?
+           WHERE run_id = ?`)
+                .run(completedAt, completedAt, run.run_id);
+            this.leaseRepo.release(scopeId, this.hostInstanceId);
+            return { status: "completed" };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const failedAt = this.now();
+            this.db
+                .prepare(`UPDATE hygiene_governance_runs
+           SET status = 'failed', failure_class = 'worker_error', failure_message = ?, finished_at = ?, updated_at = ?
+           WHERE run_id = ?`)
+                .run(message, failedAt, failedAt, run.run_id);
+            this.scheduleRepo.recordFailure({
+                scopeId,
+                failureClass: "worker_error",
+                now: failedAt,
+                backoffMs: this.backoffMs
+            });
+            this.leaseRepo.release(scopeId, this.hostInstanceId);
+            return { status: "failed", failureClass: "worker_error", message };
+        }
+    }
+}
+export const drainDueHygieneGovernance = async (db, options) => {
+    const scheduler = new HygieneGovernanceScheduler(db, options);
+    return scheduler.drainDueScope(options.scopeId);
+};
+//# sourceMappingURL=hygiene-governance-scheduler.js.map

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

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

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

@@ -0,0 +1,14 @@
+import type { HygieneGovernanceInput, HygieneGovernancePlan, HygieneGovernancePlanAction } from "./hygiene-governance-planner.js";
+export type HygieneGovernanceActionDecision = "accept" | "accept_guarded" | "reject";
+export type HygieneGovernanceValidatedAction = {
+    actionId: string;
+    actionType: HygieneGovernancePlanAction["actionType"];
+    decision: HygieneGovernanceActionDecision;
+    reasonCode: string;
+    affectedNodeIds: string[];
+};
+export type HygieneGovernanceValidationResult = {
+    accepted: boolean;
+    actions: HygieneGovernanceValidatedAction[];
+};
+export declare const validateHygieneGovernancePlan: (input: HygieneGovernanceInput, plan: HygieneGovernancePlan) => HygieneGovernanceValidationResult;