cogmem 3.6.2

package/dist/governance/CandidateReviewService.d.ts

@@ -0,0 +1,33 @@
+import type Database from 'bun:sqlite';
+import type { DeepWritePromotionDecision, DeepWritePromotionPolicy } from '../engine/DeepWritePromotionPolicy.js';
+import type { MemoryEvent } from '../types/index.js';
+import type { CandidateReviewAction, CandidateReviewRecord, CandidateReviewStore } from '../store/CandidateReviewStore.js';
+import type { DeepWriteCandidateRecord, DeepWriteCandidateStore } from '../store/DeepWriteCandidateStore.js';
+export interface CandidateReviewInput {
+    candidateId: string;
+    projectId: string;
+    action: CandidateReviewAction;
+    actor: string;
+    reason: string;
+    confirmationEventId?: string;
+    targetBeliefId?: string;
+    replacementCandidateId?: string;
+    reviewAfter?: number;
+}
+export interface CandidateReviewResult {
+    review: CandidateReviewRecord;
+    candidate: DeepWriteCandidateRecord;
+    decision?: DeepWritePromotionDecision;
+}
+export declare class CandidateReviewService {
+    private readonly db;
+    private readonly candidates;
+    private readonly reviews;
+    private readonly promotion;
+    private readonly eventLookup;
+    constructor(db: Database, candidates: DeepWriteCandidateStore, reviews: CandidateReviewStore, promotion: DeepWritePromotionPolicy, eventLookup: (eventId: string) => MemoryEvent | null);
+    review(input: CandidateReviewInput): CandidateReviewResult;
+    private requireUserConfirmation;
+    private requireReplacement;
+}
+//# sourceMappingURL=CandidateReviewService.d.ts.map

package/dist/governance/CandidateReviewService.js

@@ -0,0 +1,126 @@
+export class CandidateReviewService {
+    db;
+    candidates;
+    reviews;
+    promotion;
+    eventLookup;
+    constructor(db, candidates, reviews, promotion, eventLookup) {
+        this.db = db;
+        this.candidates = candidates;
+        this.reviews = reviews;
+        this.promotion = promotion;
+        this.eventLookup = eventLookup;
+    }
+    review(input) {
+        return this.db.transaction(() => {
+            const actor = required(input.actor, 'actor');
+            const reason = required(input.reason, 'reason');
+            const candidate = this.candidates.getCandidate(required(input.candidateId, 'candidateId'));
+            if (!candidate)
+                throw new Error('candidate_not_found');
+            const run = this.candidates.getRun(candidate.runId);
+            if (!run || run.projectId !== input.projectId)
+                throw new Error('candidate_project_mismatch');
+            if (candidate.status !== 'needs_confirmation')
+                throw new Error('candidate_not_awaiting_confirmation');
+            const fromStatus = candidate.status;
+            let decision;
+            if (input.action === 'reject') {
+                this.candidates.updateCandidateStatus(candidate.candidateId, 'rejected', { reason: `manual_review_rejected:${reason}` });
+            }
+            else if (input.action === 'defer') {
+                if (!Number.isFinite(input.reviewAfter) || Number(input.reviewAfter) <= Date.now()) {
+                    throw new Error('review_after_must_be_in_the_future');
+                }
+                this.candidates.updateCandidateStatus(candidate.candidateId, 'needs_confirmation', {
+                    reason: `manual_review_deferred:${reason}`,
+                    reviewAfter: input.reviewAfter,
+                });
+            }
+            else if (input.action === 'supersede') {
+                if (input.replacementCandidateId)
+                    this.requireReplacement(input.replacementCandidateId, input.projectId);
+                this.candidates.updateCandidateStatus(candidate.candidateId, 'superseded', {
+                    type: input.replacementCandidateId ? 'replacement_candidate' : 'manual_review',
+                    id: input.replacementCandidateId || candidate.candidateId,
+                    reason: `manual_review_superseded:${reason}`,
+                });
+            }
+            else {
+                const confirmation = this.requireUserConfirmation(input.confirmationEventId, input.projectId);
+                let content = asObject(candidate.content);
+                let targetType = candidate.promotionTargetType;
+                let targetId = candidate.promotionTargetId;
+                if (input.action === 'relink') {
+                    if (candidate.candidateType !== 'correction')
+                        throw new Error('relink_requires_correction_candidate');
+                    const belief = this.db.prepare(`SELECT id, canonical_key, project_id, status FROM beliefs WHERE id=?`).get(input.targetBeliefId || '');
+                    if (!belief || belief.project_id !== input.projectId || belief.status !== 'active') {
+                        throw new Error('target_belief_not_active_in_project');
+                    }
+                    content = { ...content, targetBeliefId: belief.id, correctedClaimKey: belief.canonical_key };
+                    targetType = 'belief';
+                    targetId = belief.id;
+                }
+                const evidence = appendConfirmationEvidence(candidate.evidence, confirmation.eventId);
+                this.candidates.updateCandidateReviewData(candidate.candidateId, {
+                    content,
+                    evidence,
+                    promotionTargetType: targetType,
+                    promotionTargetId: targetId,
+                    status: 'candidate',
+                    statusReason: `manual_review_${input.action}:${reason}`,
+                });
+                decision = this.promotion.evaluateAndApply(this.candidates.getCandidate(candidate.candidateId), { reviewConfirmed: true });
+            }
+            const reviewed = this.candidates.getCandidate(candidate.candidateId);
+            const review = this.reviews.insert({
+                candidateId: candidate.candidateId,
+                projectId: input.projectId,
+                action: input.action,
+                actor,
+                reason,
+                fromStatus,
+                toStatus: reviewed.status,
+                confirmationEventId: input.confirmationEventId,
+                targetBeliefId: input.targetBeliefId,
+                replacementCandidateId: input.replacementCandidateId,
+                reviewAfter: input.reviewAfter,
+                decision: decision ? { ...decision } : {},
+            });
+            return { review, candidate: reviewed, decision };
+        })();
+    }
+    requireUserConfirmation(eventId, projectId) {
+        if (!eventId)
+            throw new Error('confirmation_event_required');
+        const event = this.eventLookup(eventId);
+        if (!event)
+            throw new Error('confirmation_event_not_found');
+        if (event.projectId !== projectId)
+            throw new Error('confirmation_event_project_mismatch');
+        if (event.role !== 'user')
+            throw new Error('confirmation_event_must_be_user');
+        return event;
+    }
+    requireReplacement(candidateId, projectId) {
+        const replacement = this.candidates.getCandidate(candidateId);
+        const run = replacement ? this.candidates.getRun(replacement.runId) : null;
+        if (!replacement || run?.projectId !== projectId)
+            throw new Error('replacement_candidate_project_mismatch');
+    }
+}
+function appendConfirmationEvidence(value, eventId) {
+    const evidence = Array.isArray(value) ? [...value] : [];
+    if (!evidence.some((item) => asObject(item).eventId === eventId))
+        evidence.push({ eventId, role: 'user', source: 'manual_review_confirmation' });
+    return evidence;
+}
+function asObject(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function required(value, field) {
+    if (!value?.trim())
+        throw new Error(`${field}_required`);
+    return value.trim();
+}

package/dist/governance/ContradictionResolver.d.ts

@@ -0,0 +1,22 @@
+import { CredibilityScorer } from './CredibilityScorer.js';
+export type ContradictionVerdict = 'new_wins' | 'old_wins' | 'contradiction_pending';
+export type ContradictionStrategy = 'credibility_wins' | 'recency_wins' | 'evidence_wins';
+type FactLike = {
+    sourceType?: string;
+    evidenceCount?: number;
+    createdAt: number;
+    predicateValue: string;
+};
+export declare class ContradictionResolver {
+    private scorer;
+    private readonly defaultStrategy;
+    constructor(scorer: CredibilityScorer, defaultStrategy?: ContradictionStrategy);
+    resolve(params: {
+        newFact: FactLike;
+        existingFact: FactLike;
+        strategy?: ContradictionStrategy;
+    }): ContradictionVerdict;
+}
+export declare function assertContradictionStrategy(value: unknown): asserts value is ContradictionStrategy;
+export {};
+//# sourceMappingURL=ContradictionResolver.d.ts.map

package/dist/governance/ContradictionResolver.js

@@ -0,0 +1,54 @@
+export class ContradictionResolver {
+    scorer;
+    defaultStrategy;
+    constructor(scorer, defaultStrategy = 'credibility_wins') {
+        this.scorer = scorer;
+        this.defaultStrategy = defaultStrategy;
+        assertContradictionStrategy(defaultStrategy);
+    }
+    resolve(params) {
+        const strategy = params.strategy ?? this.defaultStrategy;
+        assertContradictionStrategy(strategy);
+        if (params.newFact.predicateValue === params.existingFact.predicateValue) {
+            return 'contradiction_pending';
+        }
+        if (strategy === 'recency_wins') {
+            if (params.newFact.createdAt > params.existingFact.createdAt)
+                return 'new_wins';
+            if (params.existingFact.createdAt > params.newFact.createdAt)
+                return 'old_wins';
+            return 'contradiction_pending';
+        }
+        if (strategy === 'evidence_wins') {
+            const newEvidence = params.newFact.evidenceCount ?? 0;
+            const oldEvidence = params.existingFact.evidenceCount ?? 0;
+            if (newEvidence > oldEvidence)
+                return 'new_wins';
+            if (oldEvidence > newEvidence)
+                return 'old_wins';
+            return 'contradiction_pending';
+        }
+        const now = Date.now();
+        const newScore = this.scorer.scoreForFact({
+            sourceType: params.newFact.sourceType,
+            evidenceCount: params.newFact.evidenceCount,
+            recencyMs: Math.max(0, now - params.newFact.createdAt)
+        });
+        const oldScore = this.scorer.scoreForFact({
+            sourceType: params.existingFact.sourceType,
+            evidenceCount: params.existingFact.evidenceCount,
+            recencyMs: Math.max(0, now - params.existingFact.createdAt)
+        });
+        if (newScore > oldScore + 0.05)
+            return 'new_wins';
+        if (oldScore > newScore + 0.05)
+            return 'old_wins';
+        return 'contradiction_pending';
+    }
+}
+export function assertContradictionStrategy(value) {
+    if (value === 'credibility_wins' || value === 'recency_wins' || value === 'evidence_wins') {
+        return;
+    }
+    throw new Error(`Invalid contradictionStrategy: ${String(value)}. Expected credibility_wins, recency_wins, or evidence_wins.`);
+}

package/dist/governance/CredibilityScorer.d.ts

@@ -0,0 +1,10 @@
+export declare const SOURCE_CREDIBILITY: Record<string, number>;
+export declare class CredibilityScorer {
+    score(sourceType: string): number;
+    scoreForFact(fact: {
+        sourceType?: string;
+        evidenceCount?: number;
+        recencyMs?: number;
+    }): number;
+}
+//# sourceMappingURL=CredibilityScorer.d.ts.map

package/dist/governance/CredibilityScorer.js

@@ -0,0 +1,29 @@
+const DAY_MS = 24 * 60 * 60 * 1000;
+export const SOURCE_CREDIBILITY = {
+    user_direct: 1.0,
+    agent_finding: 0.8,
+    web_fetch_official: 0.7,
+    file_read: 0.6,
+    web_fetch_general: 0.5,
+    agent_observation: 0.4,
+    shell_exec_output: 0.3
+};
+export class CredibilityScorer {
+    score(sourceType) {
+        return SOURCE_CREDIBILITY[sourceType] ?? 0.5;
+    }
+    scoreForFact(fact) {
+        const baseCredibility = this.score(fact.sourceType || '');
+        const evidenceCount = Math.max(0, fact.evidenceCount ?? 0);
+        const evidenceMultiplier = Math.min(1 + evidenceCount * 0.05, 1.5);
+        const recencyMs = Math.max(0, fact.recencyMs ?? Number.MAX_SAFE_INTEGER);
+        const recencyFactor = recencyMs < DAY_MS
+            ? 1.0
+            : recencyMs < 7 * DAY_MS
+                ? 0.95
+                : recencyMs < 30 * DAY_MS
+                    ? 0.85
+                    : 0.7;
+        return baseCredibility * evidenceMultiplier * recencyFactor;
+    }
+}

package/dist/governance/DecayPolicy.d.ts

@@ -0,0 +1,18 @@
+export declare class DecayPolicy {
+    private options;
+    private readonly decayThresholdDays;
+    private readonly decayFactor;
+    private readonly minWeight;
+    constructor(options?: {
+        decayThresholdDays?: number;
+        decayFactor?: number;
+        minWeight?: number;
+    });
+    computeWeight(params: {
+        baseWeight?: number;
+        lastAccessedAt: number;
+        now?: number;
+    }): number;
+    isExcluded(weight: number): boolean;
+}
+//# sourceMappingURL=DecayPolicy.d.ts.map

package/dist/governance/DecayPolicy.js

@@ -0,0 +1,28 @@
+const DAY_MS = 24 * 60 * 60 * 1000;
+export class DecayPolicy {
+    options;
+    decayThresholdDays;
+    decayFactor;
+    minWeight;
+    constructor(options = {}) {
+        this.options = options;
+        this.decayThresholdDays = options.decayThresholdDays ?? 30;
+        this.decayFactor = options.decayFactor ?? 0.8;
+        this.minWeight = options.minWeight ?? 0.1;
+    }
+    computeWeight(params) {
+        const now = params.now ?? Date.now();
+        const baseWeight = params.baseWeight ?? 1.0;
+        const elapsedMs = Math.max(0, now - params.lastAccessedAt);
+        if (elapsedMs < DAY_MS) {
+            return Math.max(baseWeight, this.minWeight);
+        }
+        const elapsedDays = elapsedMs / DAY_MS;
+        const periods = elapsedDays / this.decayThresholdDays;
+        const weight = baseWeight * (this.decayFactor ** periods);
+        return Math.max(weight, this.minWeight);
+    }
+    isExcluded(weight) {
+        return weight < this.minWeight;
+    }
+}

package/dist/governance/MemoryExplain.d.ts

@@ -0,0 +1,46 @@
+import type Database from 'bun:sqlite';
+import { CredibilityScorer } from './CredibilityScorer.js';
+import { DecayPolicy } from './DecayPolicy.js';
+import { type SupersedeRecord } from './SupersedeChain.js';
+export declare class MemoryExplain {
+    private db;
+    private scorer;
+    private decay;
+    private readonly chain;
+    constructor(db: Database, scorer: CredibilityScorer, decay: DecayPolicy);
+    explainRecall(params: {
+        query: string;
+        recalled: Array<{
+            factId: string;
+            content: string;
+            sourceType?: string;
+            lastAccessedAt?: number;
+        }>;
+        excluded: Array<{
+            factId: string;
+            content: string;
+            reason: 'decayed' | 'superseded' | 'low_credibility';
+        }>;
+    }): {
+        included: Array<{
+            factId: string;
+            reason: string;
+            credibilityScore: number;
+            weight: number;
+        }>;
+        excluded: Array<{
+            factId: string;
+            reason: string;
+        }>;
+    };
+    explainFact(factId: string): {
+        factId: string;
+        credibilityScore: number;
+        currentWeight: number;
+        status: string;
+        supersedeChain: SupersedeRecord[];
+        lastAccessedAt?: number;
+        sourceType?: string;
+    } | null;
+}
+//# sourceMappingURL=MemoryExplain.d.ts.map

package/dist/governance/MemoryExplain.js

@@ -0,0 +1,62 @@
+import { SupersedeChain } from './SupersedeChain.js';
+export class MemoryExplain {
+    db;
+    scorer;
+    decay;
+    chain;
+    constructor(db, scorer, decay) {
+        this.db = db;
+        this.scorer = scorer;
+        this.decay = decay;
+        this.chain = new SupersedeChain(db);
+    }
+    explainRecall(params) {
+        return {
+            included: params.recalled.map((fact) => {
+                const credibilityScore = this.scorer.score(fact.sourceType || '');
+                const lastAccessedAt = fact.lastAccessedAt ?? Date.now();
+                const weight = this.decay.computeWeight({ lastAccessedAt, now: Date.now() });
+                return {
+                    factId: fact.factId,
+                    reason: `matched query "${params.query}" and passed governance filters`,
+                    credibilityScore,
+                    weight
+                };
+            }),
+            excluded: params.excluded.map((fact) => ({
+                factId: fact.factId,
+                reason: fact.reason
+            }))
+        };
+    }
+    explainFact(factId) {
+        const row = this.db.prepare(`
+      SELECT fact_id, valid_from, metadata_json
+      FROM facts
+      WHERE fact_id = ?
+    `).get(factId);
+        if (!row)
+            return null;
+        const metadata = row.metadata_json ? JSON.parse(row.metadata_json) : {};
+        const sourceType = typeof metadata.sourceType === 'string' ? metadata.sourceType : undefined;
+        const evidenceCount = typeof metadata.evidenceCount === 'number' ? metadata.evidenceCount : undefined;
+        const lastAccessedAt = this.chain.getLastAccessedAt(factId);
+        const status = this.chain.getStatus(factId)?.status ?? 'canonical';
+        return {
+            factId,
+            credibilityScore: this.scorer.scoreForFact({
+                sourceType,
+                evidenceCount,
+                recencyMs: Math.max(0, Date.now() - row.valid_from)
+            }),
+            currentWeight: this.decay.computeWeight({
+                lastAccessedAt: lastAccessedAt ?? row.valid_from,
+                now: Date.now()
+            }),
+            status,
+            supersedeChain: this.chain.getChain(factId),
+            lastAccessedAt,
+            sourceType
+        };
+    }
+}

package/dist/governance/MemoryGovernanceExecutor.d.ts

@@ -0,0 +1,18 @@
+import Database from 'bun:sqlite';
+import { MemoryGovernanceStore } from '../store/MemoryGovernanceStore.js';
+import type { MemoryGovernanceExecutionResult, MemoryGovernanceOperation, MemoryGovernanceOperationType, MemoryGovernancePlan } from './MemoryGovernancePlan.js';
+import { MemoryGovernanceValidator } from './MemoryGovernanceValidator.js';
+export interface MemoryGovernanceExecutionContext {
+    db: Database;
+    plan: MemoryGovernancePlan;
+}
+export type MemoryGovernanceOperationHandler = (operation: MemoryGovernanceOperation, context: MemoryGovernanceExecutionContext) => void;
+export declare class MemoryGovernanceExecutor {
+    private readonly db;
+    private readonly store;
+    private readonly validator;
+    private readonly handlers;
+    constructor(db: Database, store: MemoryGovernanceStore, validator: MemoryGovernanceValidator, handlers?: Partial<Record<MemoryGovernanceOperationType, MemoryGovernanceOperationHandler>>);
+    execute(plan: MemoryGovernancePlan): MemoryGovernanceExecutionResult;
+}
+//# sourceMappingURL=MemoryGovernanceExecutor.d.ts.map

package/dist/governance/MemoryGovernanceExecutor.js

@@ -0,0 +1,37 @@
+export class MemoryGovernanceExecutor {
+    db;
+    store;
+    validator;
+    handlers;
+    constructor(db, store, validator, handlers = {}) {
+        this.db = db;
+        this.store = store;
+        this.validator = validator;
+        this.handlers = handlers;
+    }
+    execute(plan) {
+        if (this.store.isPlanApplied(plan.planId)) {
+            return { planId: plan.planId, status: 'already_applied', appliedOperationIds: this.store.listAppliedOperations(plan.planId) };
+        }
+        const validation = this.validator.validate(plan);
+        if (!validation.valid) {
+            throw new Error(`Memory governance plan rejected: ${validation.issues.map((issue) => issue.code).join(', ')}`);
+        }
+        const appliedOperationIds = [];
+        const transaction = this.db.transaction(() => {
+            for (const operation of plan.operations) {
+                if (this.store.isOperationApplied(operation.idempotencyKey))
+                    continue;
+                const handler = this.handlers[operation.type];
+                if (!handler)
+                    throw new Error(`unsupported_governance_operation:${operation.type}`);
+                handler(operation, { db: this.db, plan });
+                this.store.recordOperation(plan, operation);
+                appliedOperationIds.push(operation.operationId);
+            }
+            this.store.recordPlan(plan);
+        });
+        transaction();
+        return { planId: plan.planId, status: 'applied', appliedOperationIds };
+    }
+}

package/dist/governance/MemoryGovernancePlan.d.ts

@@ -0,0 +1,36 @@
+export type MemoryGovernanceOperationType = 'BIND_EVENT' | 'RECLASSIFY_TOPIC' | 'MERGE_CLUSTER' | 'SPLIT_CLUSTER' | 'LINK_ENTITY_ALIAS' | 'MERGE_ENTITY' | 'CREATE_BELIEF' | 'REINFORCE_BELIEF' | 'SUPERSEDE_BELIEF' | 'REJECT_BELIEF' | 'CREATE_TIME_ANCHOR' | 'EXPIRE_TIME_ANCHOR' | 'CREATE_PROSPECTIVE_MEMORY' | 'RESOLVE_PROSPECTIVE_MEMORY';
+export type MemoryEvidenceRole = 'user' | 'assistant' | 'tool' | 'system';
+export type MemoryOwnership = 'user' | 'project' | 'system';
+export interface MemoryGovernanceOperation {
+    operationId: string;
+    type: MemoryGovernanceOperationType;
+    projectId?: string;
+    evidenceEventIds: string[];
+    sourceRole: MemoryEvidenceRole;
+    ownership: MemoryOwnership;
+    expectedVersion?: number;
+    idempotencyKey: string;
+    payload: Record<string, unknown>;
+}
+export interface MemoryGovernancePlan {
+    planId: string;
+    projectId?: string;
+    proposedBy: 'deterministic' | 'model_candidate' | 'operator';
+    createdAt: number;
+    operations: MemoryGovernanceOperation[];
+}
+export interface MemoryGovernanceIssue {
+    code: string;
+    message: string;
+    operationId?: string;
+}
+export interface MemoryGovernanceValidationResult {
+    valid: boolean;
+    issues: MemoryGovernanceIssue[];
+}
+export interface MemoryGovernanceExecutionResult {
+    planId: string;
+    status: 'applied' | 'already_applied';
+    appliedOperationIds: string[];
+}
+//# sourceMappingURL=MemoryGovernancePlan.d.ts.map

package/dist/governance/MemoryGovernancePlan.js

@@ -0,0 +1 @@
+export {};

package/dist/governance/MemoryGovernanceValidator.d.ts

@@ -0,0 +1,13 @@
+import type { MemoryEvidenceRole, MemoryGovernancePlan, MemoryGovernanceValidationResult } from './MemoryGovernancePlan.js';
+export interface GovernanceEvidenceRecord {
+    eventId: string;
+    projectId?: string;
+    role?: MemoryEvidenceRole | string;
+}
+export type GovernanceEvidenceLookup = (eventId: string) => GovernanceEvidenceRecord | undefined;
+export declare class MemoryGovernanceValidator {
+    private readonly findEvidence;
+    constructor(findEvidence: GovernanceEvidenceLookup);
+    validate(plan: MemoryGovernancePlan): MemoryGovernanceValidationResult;
+}
+//# sourceMappingURL=MemoryGovernanceValidator.d.ts.map

package/dist/governance/MemoryGovernanceValidator.js

@@ -0,0 +1,53 @@
+export class MemoryGovernanceValidator {
+    findEvidence;
+    constructor(findEvidence) {
+        this.findEvidence = findEvidence;
+    }
+    validate(plan) {
+        const issues = [];
+        const operationIds = new Set();
+        const idempotencyKeys = new Set();
+        if (!plan.planId.trim())
+            issues.push({ code: 'missing_plan_id', message: 'planId is required.' });
+        if (plan.operations.length === 0)
+            issues.push({ code: 'empty_plan', message: 'At least one operation is required.' });
+        for (const operation of plan.operations) {
+            if (!operation.operationId.trim()) {
+                issues.push({ code: 'missing_operation_id', message: 'operationId is required.' });
+            }
+            else if (operationIds.has(operation.operationId)) {
+                issues.push({ code: 'duplicate_operation_id', message: 'operationId must be unique.', operationId: operation.operationId });
+            }
+            operationIds.add(operation.operationId);
+            if (!operation.idempotencyKey.trim()) {
+                issues.push({ code: 'missing_idempotency_key', message: 'idempotencyKey is required.', operationId: operation.operationId });
+            }
+            else if (idempotencyKeys.has(operation.idempotencyKey)) {
+                issues.push({ code: 'duplicate_idempotency_key', message: 'idempotencyKey must be unique inside a plan.', operationId: operation.operationId });
+            }
+            idempotencyKeys.add(operation.idempotencyKey);
+            if (operation.evidenceEventIds.length === 0) {
+                issues.push({ code: 'missing_evidence', message: 'Durable operations require raw event evidence.', operationId: operation.operationId });
+                continue;
+            }
+            const evidence = operation.evidenceEventIds.map((eventId) => this.findEvidence(eventId));
+            if (evidence.some((record) => !record)) {
+                issues.push({ code: 'unknown_evidence', message: 'Every evidence event must exist in the Raw Ledger.', operationId: operation.operationId });
+            }
+            if (operation.projectId && evidence.some((record) => record?.projectId && record.projectId !== operation.projectId)) {
+                issues.push({ code: 'project_boundary_violation', message: 'Evidence must remain inside the operation project.', operationId: operation.operationId });
+            }
+            if (operation.ownership === 'user' && !evidence.some((record) => record?.role === 'user')) {
+                issues.push({
+                    code: 'user_ownership_requires_user_evidence',
+                    message: 'User-owned memory requires at least one explicit user event.',
+                    operationId: operation.operationId,
+                });
+            }
+            if (operation.expectedVersion !== undefined && (!Number.isInteger(operation.expectedVersion) || operation.expectedVersion < 0)) {
+                issues.push({ code: 'invalid_expected_version', message: 'expectedVersion must be a non-negative integer.', operationId: operation.operationId });
+            }
+        }
+        return { valid: issues.length === 0, issues };
+    }
+}

package/dist/governance/ObservationHygieneRules.d.ts

@@ -0,0 +1,17 @@
+export interface HygieneRule {
+    id: string;
+    description: string;
+    check(content: string, meta: {
+        sourceType?: string;
+        url?: string;
+    }): boolean;
+}
+export declare const HYGIENE_RULES: HygieneRule[];
+export declare function applyHygieneRules(content: string, meta: {
+    sourceType?: string;
+    url?: string;
+}, rules?: HygieneRule[]): {
+    shouldFilter: boolean;
+    triggeredRule?: string;
+};
+//# sourceMappingURL=ObservationHygieneRules.d.ts.map

package/dist/governance/ObservationHygieneRules.js

@@ -0,0 +1,28 @@
+export const HYGIENE_RULES = [
+    {
+        id: 'empty_content',
+        description: 'Filter empty or whitespace-only content',
+        check: (content) => content.trim().length === 0
+    },
+    {
+        id: 'duplicate_noise',
+        description: 'Filter content that is only repeated characters',
+        check: (content) => /^(.)\1{9,}$/.test(content.trim())
+    },
+    {
+        id: 'shell_noise',
+        description: 'Filter shell outputs that are only exit codes or prompts',
+        check: (content, meta) => meta.sourceType === 'shell_exec_output' && /^(\$\s*|>\s*|exit\s*\d*\s*)$/.test(content.trim())
+    },
+    {
+        id: 'low_information_web',
+        description: 'Filter web content shorter than 20 chars that is likely a redirect or error page',
+        check: (content, meta) => meta.sourceType === 'web_fetch_general' && content.trim().length < 20
+    }
+];
+export function applyHygieneRules(content, meta, rules = HYGIENE_RULES) {
+    const triggered = rules.find((rule) => rule.check(content, meta));
+    return triggered
+        ? { shouldFilter: true, triggeredRule: triggered.id }
+        : { shouldFilter: false };
+}