@aletheia-labs/dynamics 0.1.0

package/dist/dynamics-engine.js

@@ -0,0 +1,216 @@
+const DEFAULT_STATUSES = ['candidate', 'verified', 'trusted'];
+const NO_EVIDENCE_PROVIDER = {
+    async evidenceFor() {
+        return { sourceConsistentRecalls: 0 };
+    },
+};
+export class DynamicsEngine {
+    memoryStore;
+    conflictRegistry;
+    policy;
+    evidenceProvider;
+    /**
+     * Create a deterministic lifecycle engine over explicit stores and policy.
+     *
+     * @remarks
+     * The engine owns no scheduler and starts no background work. Hosts trigger
+     * lifecycle passes by calling `tick()` or by wrapping it with `SleepCycleRunner`.
+     */
+    constructor(options) {
+        this.memoryStore = options.stores.memoryStore;
+        this.conflictRegistry = options.stores.conflictRegistry;
+        this.policy = options.policy;
+        this.evidenceProvider = options.evidenceProvider ?? NO_EVIDENCE_PROVIDER;
+    }
+    /**
+     * Plan or apply one lifecycle pass over visible atoms in a scope.
+     *
+     * @remarks
+     * The implementation first validates the logical clock and permitted
+     * visibilities. It then queries by permission/scope/status but intentionally
+     * does not pass `validAt`, because expired or malformed validity windows must
+     * remain visible to the lifecycle pass so they can be deprecated. Mutations
+     * happen only when `applyTransitions` is true, and only via
+     * `MemoryStore.transitionStatus()`.
+     */
+    async tick(input) {
+        const nowMs = timestampMs(input.now);
+        if (nowMs === null) {
+            return this.emptyResult(input, 'invalid_now');
+        }
+        if (input.permittedVisibilities.length === 0) {
+            return this.emptyResult(input, 'no_permitted_visibilities');
+        }
+        // Dynamics is a lifecycle scan: it must be able to see expired or corrupt
+        // validity windows in order to deprecate them. Permission/scope/status still
+        // happen in the store before any semantic decision; validity is evaluated
+        // deterministically below against `input.now`.
+        const atoms = await this.memoryStore.query({
+            scope: input.scope,
+            permittedVisibilities: input.permittedVisibilities,
+            statuses: input.statuses ?? DEFAULT_STATUSES,
+            ...(input.limit !== undefined ? { limit: input.limit } : {}),
+        });
+        const limitedAtoms = this.policy.maxAtomsPerTick !== undefined
+            ? atoms.slice(0, this.policy.maxAtomsPerTick)
+            : atoms;
+        const decisions = [];
+        for (const atom of limitedAtoms) {
+            decisions.push(await this.evaluateAtom(atom, input, nowMs));
+        }
+        return summarize(input, 'ok', [], decisions);
+    }
+    emptyResult(input, reason) {
+        return summarize(input, 'fetch_abstain', [reason], []);
+    }
+    async evaluateAtom(atom, input, nowMs) {
+        if (atom.status !== 'candidate' && atom.status !== 'verified' && atom.status !== 'trusted') {
+            return skipped(atom, 'status_not_processable', []);
+        }
+        const validFromMs = timestampMs(atom.validFrom);
+        if (validFromMs === null) {
+            return this.transition(atom, 'deprecated', 'invalid_clock', [], input.now, input.applyTransitions === true);
+        }
+        if (validFromMs > nowMs) {
+            return skipped(atom, 'not_yet_valid', []);
+        }
+        if (atom.validUntil !== null) {
+            const validUntilMs = timestampMs(atom.validUntil);
+            if (validUntilMs === null) {
+                return this.transition(atom, 'deprecated', 'invalid_clock', [], input.now, input.applyTransitions === true);
+            }
+            if (validUntilMs < nowMs) {
+                return this.transition(atom, 'deprecated', 'expired', [], input.now, input.applyTransitions === true);
+            }
+        }
+        const unresolvedConflicts = await this.unresolvedConflicts(atom, input);
+        if (unresolvedConflicts.length > 0) {
+            if (atom.status === 'candidate') {
+                return skipped(atom, 'unresolved_conflict', conflictIds(unresolvedConflicts));
+            }
+            return this.transition(atom, 'deprecated', 'unresolved_conflict', conflictIds(unresolvedConflicts), input.now, input.applyTransitions === true);
+        }
+        const evidence = await this.evidenceProvider.evidenceFor(atom, {
+            now: input.now,
+            scope: input.scope,
+            permittedVisibilities: input.permittedVisibilities,
+        });
+        if (atom.status === 'candidate') {
+            if (this.canPromoteCandidate(atom, evidence)) {
+                return this.transition(atom, 'verified', 'promotion_evidence_satisfied', [], input.now, input.applyTransitions === true);
+            }
+            const staleDecision = this.staleDecision(atom, nowMs, evidence);
+            if (staleDecision !== null) {
+                return this.transition(atom, 'deprecated', staleDecision, [], input.now, input.applyTransitions === true);
+            }
+            return skipped(atom, 'insufficient_promotion_evidence', []);
+        }
+        const staleDecision = this.staleDecision(atom, nowMs, evidence);
+        if (staleDecision !== null) {
+            return this.transition(atom, 'deprecated', staleDecision, [], input.now, input.applyTransitions === true);
+        }
+        return skipped(atom, 'not_due', []);
+    }
+    async unresolvedConflicts(atom, input) {
+        return this.conflictRegistry.query({
+            touchingMemoryIds: [atom.memoryId],
+            statuses: ['unresolved', 'requires_human'],
+            scope: input.scope,
+            permittedVisibilities: input.permittedVisibilities,
+        });
+    }
+    staleDecision(atom, nowMs, evidence) {
+        const anchorMs = latestAnchorMs(atom, evidence);
+        if (anchorMs === null) {
+            return 'stale_by_policy';
+        }
+        const ageMs = nowMs - anchorMs;
+        if (ageMs < 0)
+            return null;
+        const threshold = statusThresholdMs(atom.status, this.policy);
+        if (threshold === null)
+            return null;
+        return ageMs > threshold ? 'stale_by_policy' : null;
+    }
+    canPromoteCandidate(atom, evidence) {
+        // These scores are gate-produced metadata thresholds. They are never
+        // authority by themselves; explicit source-consistent recall evidence is
+        // required before any candidate can become verified.
+        return (evidence.sourceConsistentRecalls >= this.policy.promotion.minSourceConsistentRecalls &&
+            atom.scores.evidence >= this.policy.promotion.minEvidenceScore &&
+            atom.scores.authority >= this.policy.promotion.minAuthorityScore &&
+            atom.scores.stability >= this.policy.promotion.minStabilityScore);
+    }
+    async transition(atom, recommendedStatus, reason, conflicts, at, apply) {
+        if (!apply) {
+            return {
+                memoryId: atom.memoryId,
+                fromStatus: atom.status,
+                outcome: 'planned',
+                reason,
+                recommendedStatus,
+                conflicts,
+            };
+        }
+        const transition = await this.memoryStore.transitionStatus(atom.memoryId, recommendedStatus, {
+            actor: this.policy.actor,
+            rationale: `phase2:${reason}`,
+            ...(conflicts[0] !== undefined ? { conflictId: conflicts[0] } : {}),
+        }, { at });
+        return {
+            memoryId: atom.memoryId,
+            fromStatus: atom.status,
+            outcome: transition.kind === 'applied' ? 'applied' : 'rejected',
+            reason,
+            recommendedStatus,
+            conflicts,
+            transition,
+        };
+    }
+}
+function statusThresholdMs(status, policy) {
+    if (status === 'candidate')
+        return policy.decay.candidateAfterMs;
+    if (status === 'verified')
+        return policy.decay.verifiedAfterMs;
+    if (status === 'trusted')
+        return policy.decay.trustedAfterMs;
+    return null;
+}
+function timestampMs(timestamp) {
+    const parsed = Date.parse(timestamp);
+    return Number.isNaN(parsed) ? null : parsed;
+}
+function latestAnchorMs(atom, evidence) {
+    const anchors = [atom.validFrom, atom.lastConfirmedAt, evidence.lastUsedAt].filter((timestamp) => timestamp !== null && timestamp !== undefined);
+    const parsed = anchors.map(timestampMs);
+    if (parsed.some((value) => value === null))
+        return null;
+    return Math.max(...parsed);
+}
+function skipped(atom, reason, conflicts) {
+    return {
+        memoryId: atom.memoryId,
+        fromStatus: atom.status,
+        outcome: 'skipped',
+        reason,
+        conflicts,
+    };
+}
+function conflictIds(conflicts) {
+    return conflicts.map((conflict) => conflict.conflictId);
+}
+function summarize(input, outcome, reasons, decisions) {
+    return {
+        outcome,
+        now: input.now,
+        scope: input.scope,
+        reasons,
+        decisions,
+        appliedCount: decisions.filter((decision) => decision.outcome === 'applied').length,
+        plannedCount: decisions.filter((decision) => decision.outcome === 'planned').length,
+        rejectedCount: decisions.filter((decision) => decision.outcome === 'rejected').length,
+        skippedCount: decisions.filter((decision) => decision.outcome === 'skipped').length,
+    };
+}
+//# sourceMappingURL=dynamics-engine.js.map

package/dist/dynamics-engine.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './policy.js';
+export * from './authority-decay.js';
+export * from './recall-evidence.js';
+export * from './dynamics-engine.js';
+export * from './sleep-cycle.js';
+export * from './reconsolidation-planner.js';
+export * from './lineage.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from './policy.js';
+export * from './authority-decay.js';
+export * from './recall-evidence.js';
+export * from './dynamics-engine.js';
+export * from './sleep-cycle.js';
+export * from './reconsolidation-planner.js';
+export * from './lineage.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,cAAc,CAAC"}

package/dist/lineage.d.ts

@@ -0,0 +1,35 @@
+import type { MemoryAtom, MemoryId, MemoryStore, Visibility } from '@aletheia-labs/core';
+export type LineageTraceOutcome = 'ok' | 'fetch_abstain';
+export type LineageTraceReason = 'cycle_detected' | 'max_depth_exceeded' | 'memory_missing_or_invisible';
+export interface LineageTraceInput {
+    readonly memoryId: MemoryId;
+    readonly permittedVisibilities: readonly Visibility[];
+    readonly maxDepth?: number;
+}
+export interface LineageTraceResult {
+    readonly outcome: LineageTraceOutcome;
+    readonly reasons: readonly LineageTraceReason[];
+    readonly atoms: readonly MemoryAtom[];
+}
+export interface LineageTracerOptions {
+    readonly memoryStore: MemoryStore;
+}
+export declare class LineageTracer {
+    private readonly options;
+    /**
+     * Create a permission-guarded lineage tracer over a memory store.
+     *
+     * @remarks
+     * The tracer reads only through `MemoryStore.get()`, so invisible ancestors
+     * are treated the same as missing ancestors. It reconstructs `supersedes`
+     * chains without mutating atoms or status history.
+     */
+    constructor(options: LineageTracerOptions);
+    /**
+     * Trace from a successor atom backwards through `supersedes` links.
+     *
+     * @returns Atoms in newest-to-oldest order when every ancestor is visible.
+     */
+    traceBack(input: LineageTraceInput): Promise<LineageTraceResult>;
+}
+//# sourceMappingURL=lineage.d.ts.map

package/dist/lineage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lineage.d.ts","sourceRoot":"","sources":["../src/lineage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEzF,MAAM,MAAM,mBAAmB,GAAG,IAAI,GAAG,eAAe,CAAC;AACzD,MAAM,MAAM,kBAAkB,GAC1B,gBAAgB,GAChB,oBAAoB,GACpB,6BAA6B,CAAC;AAElC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,qBAAqB,EAAE,SAAS,UAAU,EAAE,CAAC;IACtD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAChD,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACnC;AAED,qBAAa,aAAa;IASZ,OAAO,CAAC,QAAQ,CAAC,OAAO;IARpC;;;;;;;OAOG;gBAC0B,OAAO,EAAE,oBAAoB;IAE1D;;;;OAIG;IACG,SAAS,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAyBvE"}

package/dist/lineage.js

@@ -0,0 +1,45 @@
+export class LineageTracer {
+    options;
+    /**
+     * Create a permission-guarded lineage tracer over a memory store.
+     *
+     * @remarks
+     * The tracer reads only through `MemoryStore.get()`, so invisible ancestors
+     * are treated the same as missing ancestors. It reconstructs `supersedes`
+     * chains without mutating atoms or status history.
+     */
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * Trace from a successor atom backwards through `supersedes` links.
+     *
+     * @returns Atoms in newest-to-oldest order when every ancestor is visible.
+     */
+    async traceBack(input) {
+        const maxDepth = input.maxDepth ?? 128;
+        const atoms = [];
+        const visited = new Set();
+        let currentId = input.memoryId;
+        while (currentId !== null) {
+            if (atoms.length >= maxDepth) {
+                return { outcome: 'fetch_abstain', reasons: ['max_depth_exceeded'], atoms };
+            }
+            if (visited.has(currentId)) {
+                return { outcome: 'fetch_abstain', reasons: ['cycle_detected'], atoms };
+            }
+            visited.add(currentId);
+            const atom = await this.options.memoryStore.get(currentId, input.permittedVisibilities);
+            if (atom === null) {
+                return { outcome: 'fetch_abstain', reasons: ['memory_missing_or_invisible'], atoms };
+            }
+            atoms.push(atom);
+            currentId = supersededMemoryId(atom);
+        }
+        return { outcome: 'ok', reasons: [], atoms };
+    }
+}
+function supersededMemoryId(atom) {
+    return atom.links.find((link) => link.relation === 'supersedes')?.targetMemoryId ?? null;
+}
+//# sourceMappingURL=lineage.js.map

package/dist/lineage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lineage.js","sourceRoot":"","sources":["../src/lineage.ts"],"names":[],"mappings":"AAwBA,MAAM,OAAO,aAAa;IASK;IAR7B;;;;;;;OAOG;IACH,YAA6B,OAA6B;QAA7B,YAAO,GAAP,OAAO,CAAsB;IAAG,CAAC;IAE9D;;;;OAIG;IACH,KAAK,CAAC,SAAS,CAAC,KAAwB;QACtC,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,GAAG,CAAC;QACvC,MAAM,KAAK,GAAiB,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAY,CAAC;QACpC,IAAI,SAAS,GAAoB,KAAK,CAAC,QAAQ,CAAC;QAEhD,OAAO,SAAS,KAAK,IAAI,EAAE,CAAC;YAC1B,IAAI,KAAK,CAAC,MAAM,IAAI,QAAQ,EAAE,CAAC;gBAC7B,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC,oBAAoB,CAAC,EAAE,KAAK,EAAE,CAAC;YAC9E,CAAC;YACD,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC3B,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC,gBAAgB,CAAC,EAAE,KAAK,EAAE,CAAC;YAC1E,CAAC;YACD,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAEvB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,qBAAqB,CAAC,CAAC;YACxF,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;gBAClB,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC,6BAA6B,CAAC,EAAE,KAAK,EAAE,CAAC;YACvF,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjB,SAAS,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;QACvC,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;IAC/C,CAAC;CACF;AAED,SAAS,kBAAkB,CAAC,IAAgB;IAC1C,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,KAAK,YAAY,CAAC,EAAE,cAAc,IAAI,IAAI,CAAC;AAC3F,CAAC"}

package/dist/policy.d.ts

@@ -0,0 +1,35 @@
+import type { AgentId } from '@aletheia-labs/core';
+export interface DecayPolicy {
+    readonly candidateAfterMs: number;
+    readonly verifiedAfterMs: number;
+    readonly trustedAfterMs: number;
+}
+export interface PromotionPolicy {
+    readonly minSourceConsistentRecalls: number;
+    readonly minEvidenceScore: number;
+    readonly minAuthorityScore: number;
+    readonly minStabilityScore: number;
+}
+export interface DynamicsPolicy {
+    readonly actor: AgentId;
+    readonly decay: DecayPolicy;
+    readonly promotion: PromotionPolicy;
+    readonly maxAtomsPerTick?: number;
+}
+export interface DynamicsPolicyOverrides {
+    readonly decay?: Partial<DecayPolicy>;
+    readonly promotion?: Partial<PromotionPolicy>;
+    readonly maxAtomsPerTick?: number;
+}
+export declare const DEFAULT_DECAY_POLICY: DecayPolicy;
+export declare const DEFAULT_PROMOTION_POLICY: PromotionPolicy;
+/**
+ * Build a dynamics policy from defaults plus host overrides.
+ *
+ * @remarks
+ * Use this helper instead of hand-copying defaults in hosts. The `actor` is
+ * written into transition audit reasons when the dynamics engine applies
+ * status changes.
+ */
+export declare function createDynamicsPolicy(actor: AgentId, overrides?: DynamicsPolicyOverrides): DynamicsPolicy;
+//# sourceMappingURL=policy.d.ts.map

package/dist/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,0BAA0B,EAAE,MAAM,CAAC;IAC5C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAC9C,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAID,eAAO,MAAM,oBAAoB,EAAE,WAIlC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAKtC,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,SAAS,GAAE,uBAA4B,GACtC,cAAc,CAShB"}

package/dist/policy.js

@@ -0,0 +1,31 @@
+const DAY_MS = 24 * 60 * 60 * 1000;
+export const DEFAULT_DECAY_POLICY = {
+    candidateAfterMs: 7 * DAY_MS,
+    verifiedAfterMs: 30 * DAY_MS,
+    trustedAfterMs: 180 * DAY_MS,
+};
+export const DEFAULT_PROMOTION_POLICY = {
+    minSourceConsistentRecalls: 2,
+    minEvidenceScore: 0.7,
+    minAuthorityScore: 0.6,
+    minStabilityScore: 0.5,
+};
+/**
+ * Build a dynamics policy from defaults plus host overrides.
+ *
+ * @remarks
+ * Use this helper instead of hand-copying defaults in hosts. The `actor` is
+ * written into transition audit reasons when the dynamics engine applies
+ * status changes.
+ */
+export function createDynamicsPolicy(actor, overrides = {}) {
+    return {
+        actor,
+        decay: { ...DEFAULT_DECAY_POLICY, ...overrides.decay },
+        promotion: { ...DEFAULT_PROMOTION_POLICY, ...overrides.promotion },
+        ...(overrides.maxAtomsPerTick !== undefined
+            ? { maxAtomsPerTick: overrides.maxAtomsPerTick }
+            : {}),
+    };
+}
+//# sourceMappingURL=policy.js.map

package/dist/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AA4BA,MAAM,MAAM,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEnC,MAAM,CAAC,MAAM,oBAAoB,GAAgB;IAC/C,gBAAgB,EAAE,CAAC,GAAG,MAAM;IAC5B,eAAe,EAAE,EAAE,GAAG,MAAM;IAC5B,cAAc,EAAE,GAAG,GAAG,MAAM;CAC7B,CAAC;AAEF,MAAM,CAAC,MAAM,wBAAwB,GAAoB;IACvD,0BAA0B,EAAE,CAAC;IAC7B,gBAAgB,EAAE,GAAG;IACrB,iBAAiB,EAAE,GAAG;IACtB,iBAAiB,EAAE,GAAG;CACvB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAc,EACd,YAAqC,EAAE;IAEvC,OAAO;QACL,KAAK;QACL,KAAK,EAAE,EAAE,GAAG,oBAAoB,EAAE,GAAG,SAAS,CAAC,KAAK,EAAE;QACtD,SAAS,EAAE,EAAE,GAAG,wBAAwB,EAAE,GAAG,SAAS,CAAC,SAAS,EAAE;QAClE,GAAG,CAAC,SAAS,CAAC,eAAe,KAAK,SAAS;YACzC,CAAC,CAAC,EAAE,eAAe,EAAE,SAAS,CAAC,eAAe,EAAE;YAChD,CAAC,CAAC,EAAE,CAAC;KACR,CAAC;AACJ,CAAC"}

package/dist/recall-evidence.d.ts

@@ -0,0 +1,38 @@
+import type { EventId, EventLedger, JsonValue, MemoryAtom, MemoryId } from '@aletheia-labs/core';
+import type { DynamicsEvidence, DynamicsEvidenceContext, DynamicsEvidenceProvider } from './dynamics-engine.js';
+export declare const SOURCE_CONSISTENT_RECALL_EVENT = "aletheia.source_consistent_recall";
+export interface SourceConsistentRecallPayload {
+    readonly [key: string]: JsonValue;
+    readonly aletheiaEvent: typeof SOURCE_CONSISTENT_RECALL_EVENT;
+    readonly memoryId: MemoryId;
+    readonly sourceEventIds: readonly EventId[];
+}
+export interface LedgerRecallEvidenceProviderOptions {
+    readonly eventLedger: EventLedger;
+}
+export declare class LedgerRecallEvidenceProvider implements DynamicsEvidenceProvider {
+    private readonly options;
+    /**
+     * Create a recall evidence provider backed by append-only events.
+     *
+     * @remarks
+     * The provider treats ledger events as evidence, not authority. Only events
+     * with the explicit `SOURCE_CONSISTENT_RECALL_EVENT` payload and matching
+     * source-event coverage count toward promotion or last-used freshness.
+     */
+    constructor(options: LedgerRecallEvidenceProviderOptions);
+    /**
+     * Count source-consistent recall events for one atom.
+     *
+     * @remarks
+     * Permission and scope filtering are delegated to `EventLedger.query()` before
+     * payload inspection. The result is deterministic for a fixed ledger and
+     * context clock.
+     */
+    evidenceFor(atom: MemoryAtom, context: DynamicsEvidenceContext): Promise<DynamicsEvidence>;
+}
+/**
+ * Build the canonical payload hosts should append after a source-consistent recall.
+ */
+export declare function sourceConsistentRecallPayload(atom: MemoryAtom): SourceConsistentRecallPayload;
+//# sourceMappingURL=recall-evidence.d.ts.map

package/dist/recall-evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall-evidence.d.ts","sourceRoot":"","sources":["../src/recall-evidence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,OAAO,EACP,WAAW,EACX,SAAS,EACT,UAAU,EACV,QAAQ,EACT,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EACV,gBAAgB,EAChB,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,sBAAsB,CAAC;AAE9B,eAAO,MAAM,8BAA8B,sCAAsC,CAAC;AAElF,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,OAAO,8BAA8B,CAAC;IAC9D,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,SAAS,OAAO,EAAE,CAAC;CAC7C;AAED,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACnC;AAED,qBAAa,4BAA6B,YAAW,wBAAwB;IAS/D,OAAO,CAAC,QAAQ,CAAC,OAAO;IARpC;;;;;;;OAOG;gBAC0B,OAAO,EAAE,mCAAmC;IAEzE;;;;;;;OAOG;IACG,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAmBjG;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,UAAU,GAAG,6BAA6B,CAM7F"}

package/dist/recall-evidence.js

@@ -0,0 +1,67 @@
+export const SOURCE_CONSISTENT_RECALL_EVENT = 'aletheia.source_consistent_recall';
+export class LedgerRecallEvidenceProvider {
+    options;
+    /**
+     * Create a recall evidence provider backed by append-only events.
+     *
+     * @remarks
+     * The provider treats ledger events as evidence, not authority. Only events
+     * with the explicit `SOURCE_CONSISTENT_RECALL_EVENT` payload and matching
+     * source-event coverage count toward promotion or last-used freshness.
+     */
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * Count source-consistent recall events for one atom.
+     *
+     * @remarks
+     * Permission and scope filtering are delegated to `EventLedger.query()` before
+     * payload inspection. The result is deterministic for a fixed ledger and
+     * context clock.
+     */
+    async evidenceFor(atom, context) {
+        const events = await this.options.eventLedger.query({
+            scope: context.scope,
+            permittedVisibilities: context.permittedVisibilities,
+            since: atom.validFrom,
+            until: context.now,
+        });
+        const matching = events.filter((event) => isSourceConsistentRecallEvent(event, atom));
+        const timestamps = matching.map((event) => event.occurredAt).sort();
+        const first = timestamps[0];
+        const last = timestamps.at(-1);
+        return {
+            sourceConsistentRecalls: matching.length,
+            ...(last !== undefined ? { lastUsedAt: last } : {}),
+            ...(first !== undefined ? { sourceConsistentSince: first } : {}),
+        };
+    }
+}
+/**
+ * Build the canonical payload hosts should append after a source-consistent recall.
+ */
+export function sourceConsistentRecallPayload(atom) {
+    return {
+        aletheiaEvent: SOURCE_CONSISTENT_RECALL_EVENT,
+        memoryId: atom.memoryId,
+        sourceEventIds: [...atom.sourceEventIds],
+    };
+}
+function isSourceConsistentRecallEvent(event, atom) {
+    const payload = event.payload;
+    if (!isRecallPayload(payload))
+        return false;
+    if (payload.aletheiaEvent !== SOURCE_CONSISTENT_RECALL_EVENT)
+        return false;
+    if (payload.memoryId !== atom.memoryId)
+        return false;
+    if (!Array.isArray(payload.sourceEventIds))
+        return false;
+    const recalledSources = new Set(payload.sourceEventIds.filter((value) => typeof value === 'string'));
+    return atom.sourceEventIds.every((eventId) => recalledSources.has(eventId));
+}
+function isRecallPayload(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=recall-evidence.js.map

package/dist/recall-evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall-evidence.js","sourceRoot":"","sources":["../src/recall-evidence.ts"],"names":[],"mappings":"AAcA,MAAM,CAAC,MAAM,8BAA8B,GAAG,mCAAmC,CAAC;AAalF,MAAM,OAAO,4BAA4B;IASV;IAR7B;;;;;;;OAOG;IACH,YAA6B,OAA4C;QAA5C,YAAO,GAAP,OAAO,CAAqC;IAAG,CAAC;IAE7E;;;;;;;OAOG;IACH,KAAK,CAAC,WAAW,CAAC,IAAgB,EAAE,OAAgC;QAClE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC;YAClD,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,qBAAqB,EAAE,OAAO,CAAC,qBAAqB;YACpD,KAAK,EAAE,IAAI,CAAC,SAAS;YACrB,KAAK,EAAE,OAAO,CAAC,GAAG;SACnB,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,6BAA6B,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;QACtF,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE,CAAC;QACpE,MAAM,KAAK,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;QAC5B,MAAM,IAAI,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAE/B,OAAO;YACL,uBAAuB,EAAE,QAAQ,CAAC,MAAM;YACxC,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnD,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,qBAAqB,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACjE,CAAC;IACJ,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,6BAA6B,CAAC,IAAgB;IAC5D,OAAO;QACL,aAAa,EAAE,8BAA8B;QAC7C,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,cAAc,EAAE,CAAC,GAAG,IAAI,CAAC,cAAc,CAAC;KACzC,CAAC;AACJ,CAAC;AAED,SAAS,6BAA6B,CAAC,KAAY,EAAE,IAAgB;IACnE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC9B,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,OAAO,CAAC,aAAa,KAAK,8BAA8B;QAAE,OAAO,KAAK,CAAC;IAC3E,IAAI,OAAO,CAAC,QAAQ,KAAK,IAAI,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IACrD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC;QAAE,OAAO,KAAK,CAAC;IAEzD,MAAM,eAAe,GAAG,IAAI,GAAG,CAC7B,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CACrF,CAAC;IACF,OAAO,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,eAAe,CAAC,KAAc;IAKrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}

package/dist/reconsolidation-planner.d.ts

@@ -0,0 +1,93 @@
+import type { AgentId, ConflictId, ConflictRegistry, Event, EventId, EventLedger, IsoTimestamp, MemoryAtom, MemoryId, MemoryStore, MemoryType, Scope, StatusTransitionReason, StatusTransitionResult, Visibility } from '@aletheia-labs/core';
+export type ReconsolidationOutcome = 'plan' | 'fetch_abstain';
+export type ReconsolidationApplyOutcome = 'applied' | 'ask_human' | 'fetch_abstain' | 'partial_applied' | 'rejected';
+export type ReconsolidationReason = 'empty_source_events' | 'invalid_successor_draft' | 'no_permitted_visibilities' | 'previous_memory_missing_or_invisible' | 'previous_status_not_reconsolidatable' | 'source_event_missing_or_invisible' | 'source_event_scope_mismatch' | 'successor_insert_failed' | 'transition_rejected' | 'human_confirmation_required' | 'invalid_human_confirmation' | 'unresolved_conflict';
+export interface ReconsolidationPlannerStores {
+    readonly eventLedger: EventLedger;
+    readonly memoryStore: MemoryStore;
+    readonly conflictRegistry: ConflictRegistry;
+}
+export interface ReconsolidationPlanInput {
+    readonly previousMemoryId: MemoryId;
+    readonly successorMemoryId: MemoryId;
+    readonly proposedBy: AgentId;
+    readonly proposedAt: IsoTimestamp;
+    readonly memoryType: MemoryType;
+    readonly claim: string;
+    readonly sourceEventIds: readonly EventId[];
+    readonly scope: Scope;
+    readonly permittedVisibilities: readonly Visibility[];
+}
+export interface PlannedStatusTransition {
+    readonly memoryId: MemoryId;
+    readonly nextStatus: 'deprecated';
+    readonly reason: StatusTransitionReason;
+}
+export interface ReconsolidationPlan {
+    readonly outcome: ReconsolidationOutcome;
+    readonly reasons: readonly ReconsolidationReason[];
+    readonly previousAtom: MemoryAtom | null;
+    readonly sourceEvents: readonly Event[];
+    readonly successorDraft: MemoryAtom | null;
+    readonly plannedTransitions: readonly PlannedStatusTransition[];
+    readonly relatedConflictIds: readonly ConflictId[];
+}
+export interface ReconsolidationHumanConfirmation {
+    readonly confirmedBy: AgentId;
+    readonly confirmedAt: IsoTimestamp;
+    readonly rationale: string;
+}
+export interface ReconsolidationApplyInput extends ReconsolidationPlanInput {
+    readonly humanConfirmation?: ReconsolidationHumanConfirmation;
+}
+export interface ReconsolidationApplyResult {
+    readonly outcome: ReconsolidationApplyOutcome;
+    readonly reasons: readonly ReconsolidationReason[];
+    readonly plan: ReconsolidationPlan;
+    readonly successorAtom: MemoryAtom | null;
+    readonly transitionResults: readonly StatusTransitionResult[];
+}
+export declare class ReconsolidationPlanner {
+    private readonly stores;
+    /**
+     * Create a reconsolidation planner over existing authority stores.
+     *
+     * @remarks
+     * The planner is read-only. It validates visibility, source events, scope,
+     * status, and conflict state before producing a successor draft.
+     */
+    constructor(stores: ReconsolidationPlannerStores);
+    /**
+     * Plan a candidate successor atom and prior-atom deprecation.
+     *
+     * @remarks
+     * Use this when new evidence should update the meaning of an existing atom.
+     * The plan never mutates storage and never upgrades authority: successor
+     * drafts start as `candidate` and carry `supersedes` lineage back to the
+     * previous atom.
+     */
+    plan(input: ReconsolidationPlanInput): Promise<ReconsolidationPlan>;
+}
+export declare class ReconsolidationApplier {
+    private readonly stores;
+    private readonly planner;
+    /**
+     * Create a human-confirmed reconsolidation applier.
+     *
+     * @remarks
+     * This wraps `ReconsolidationPlanner` and adds the explicit mutation path.
+     * Hosts should call `plan()` directly when they only need a preview.
+     */
+    constructor(stores: ReconsolidationPlannerStores);
+    /**
+     * Apply a reconsolidation plan after human confirmation.
+     *
+     * @remarks
+     * The method fails closed with `ask_human` without valid confirmation. When
+     * confirmed, it inserts the successor candidate first and then applies
+     * planned deprecations through `MemoryStore.transitionStatus()`. If successor
+     * insertion fails, no prior atom is deprecated.
+     */
+    apply(input: ReconsolidationApplyInput): Promise<ReconsolidationApplyResult>;
+}
+//# sourceMappingURL=reconsolidation-planner.d.ts.map

package/dist/reconsolidation-planner.d.ts.map

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