@aletheia-labs/dynamics 0.1.0

package/dist/reconsolidation-planner.js

@@ -0,0 +1,230 @@
+import { AgentIdSchema, IsoTimestampSchema, MemoryAtomSchema, scopeKey } from '@aletheia-labs/core';
+export class ReconsolidationPlanner {
+    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) {
+        this.stores = stores;
+    }
+    /**
+     * 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.
+     */
+    async plan(input) {
+        if (input.permittedVisibilities.length === 0) {
+            return abstain('no_permitted_visibilities', null, [], []);
+        }
+        if (input.sourceEventIds.length === 0) {
+            return abstain('empty_source_events', null, [], []);
+        }
+        const previousAtom = await this.stores.memoryStore.get(input.previousMemoryId, input.permittedVisibilities);
+        if (previousAtom === null) {
+            return abstain('previous_memory_missing_or_invisible', null, [], []);
+        }
+        if (!isReconsolidatableStatus(previousAtom.status)) {
+            return abstain('previous_status_not_reconsolidatable', previousAtom, [], []);
+        }
+        if (scopeKey(previousAtom.scope) !== scopeKey(input.scope)) {
+            return abstain('previous_memory_missing_or_invisible', null, [], []);
+        }
+        const sourceEvents = [];
+        for (const eventId of input.sourceEventIds) {
+            const event = await this.stores.eventLedger.get(eventId, input.permittedVisibilities);
+            if (event === null) {
+                return abstain('source_event_missing_or_invisible', previousAtom, sourceEvents, []);
+            }
+            if (scopeKey(event.scope) !== scopeKey(previousAtom.scope)) {
+                return abstain('source_event_scope_mismatch', previousAtom, sourceEvents, []);
+            }
+            sourceEvents.push(event);
+        }
+        const conflicts = await this.stores.conflictRegistry.query({
+            touchingMemoryIds: [previousAtom.memoryId],
+            statuses: ['unresolved', 'requires_human'],
+            scope: previousAtom.scope,
+            permittedVisibilities: input.permittedVisibilities,
+        });
+        const conflictIds = conflicts.map((conflict) => conflict.conflictId);
+        if (conflictIds.length > 0) {
+            return abstain('unresolved_conflict', previousAtom, sourceEvents, conflictIds);
+        }
+        const successorDraft = {
+            memoryId: input.successorMemoryId,
+            memoryType: input.memoryType,
+            content: input.claim,
+            sourceAgentId: input.proposedBy,
+            sourceEventIds: [...input.sourceEventIds],
+            sourceMemoryIds: [previousAtom.memoryId],
+            scope: previousAtom.scope,
+            visibility: previousAtom.visibility,
+            status: 'candidate',
+            // Conservative planner metadata only. The future apply gate must recompute
+            // or validate scores before insertion; these values never authorize action.
+            scores: {
+                confidence: 0.2,
+                evidence: sourceEvents.length / input.sourceEventIds.length,
+                authority: 0.2,
+                freshness: 0.5,
+                stability: 0.2,
+                consensus: 0.2,
+            },
+            validFrom: input.proposedAt,
+            validUntil: previousAtom.validUntil,
+            lastConfirmedAt: null,
+            links: [{ relation: 'supersedes', targetMemoryId: previousAtom.memoryId }],
+        };
+        const parsed = MemoryAtomSchema.safeParse(successorDraft);
+        if (!parsed.success) {
+            return abstain('invalid_successor_draft', previousAtom, sourceEvents, []);
+        }
+        const plannedTransitions = previousAtom.status === 'deprecated'
+            ? []
+            : [
+                {
+                    memoryId: previousAtom.memoryId,
+                    nextStatus: 'deprecated',
+                    reason: {
+                        actor: input.proposedBy,
+                        rationale: `phase2:reconsolidated_by:${input.successorMemoryId}`,
+                    },
+                },
+            ];
+        return {
+            outcome: 'plan',
+            reasons: [],
+            previousAtom,
+            sourceEvents,
+            successorDraft: parsed.data,
+            plannedTransitions,
+            relatedConflictIds: [],
+        };
+    }
+}
+export class ReconsolidationApplier {
+    stores;
+    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) {
+        this.stores = stores;
+        this.planner = new ReconsolidationPlanner(stores);
+    }
+    /**
+     * 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.
+     */
+    async apply(input) {
+        const plan = await this.planner.plan(input);
+        if (plan.outcome !== 'plan' || plan.successorDraft === null) {
+            return {
+                outcome: 'fetch_abstain',
+                reasons: plan.reasons,
+                plan,
+                successorAtom: null,
+                transitionResults: [],
+            };
+        }
+        if (input.humanConfirmation === undefined) {
+            return {
+                outcome: 'ask_human',
+                reasons: ['human_confirmation_required'],
+                plan,
+                successorAtom: null,
+                transitionResults: [],
+            };
+        }
+        if (!validHumanConfirmation(input.humanConfirmation)) {
+            return {
+                outcome: 'ask_human',
+                reasons: ['invalid_human_confirmation'],
+                plan,
+                successorAtom: null,
+                transitionResults: [],
+            };
+        }
+        let successorAtom;
+        try {
+            successorAtom = await this.stores.memoryStore.insert(plan.successorDraft);
+        }
+        catch {
+            return {
+                outcome: 'rejected',
+                reasons: ['successor_insert_failed'],
+                plan,
+                successorAtom: null,
+                transitionResults: [],
+            };
+        }
+        const transitionResults = [];
+        for (const transition of plan.plannedTransitions) {
+            try {
+                transitionResults.push(await this.stores.memoryStore.transitionStatus(transition.memoryId, transition.nextStatus, confirmationReason(transition.reason, input.humanConfirmation), { at: input.humanConfirmation.confirmedAt }));
+            }
+            catch (err) {
+                transitionResults.push({
+                    kind: 'rejected',
+                    reason: err instanceof Error ? err.message : 'transition threw',
+                });
+            }
+        }
+        const rejected = transitionResults.some((result) => result.kind === 'rejected');
+        return {
+            outcome: rejected ? 'partial_applied' : 'applied',
+            reasons: rejected ? ['transition_rejected'] : [],
+            plan,
+            successorAtom,
+            transitionResults,
+        };
+    }
+}
+function isReconsolidatableStatus(status) {
+    return (status === 'candidate' ||
+        status === 'verified' ||
+        status === 'trusted' ||
+        status === 'deprecated');
+}
+function validHumanConfirmation(confirmation) {
+    return (AgentIdSchema.safeParse(confirmation.confirmedBy).success &&
+        IsoTimestampSchema.safeParse(confirmation.confirmedAt).success &&
+        typeof confirmation.rationale === 'string' &&
+        confirmation.rationale.trim().length > 0);
+}
+function confirmationReason(plannedReason, confirmation) {
+    return {
+        actor: confirmation.confirmedBy,
+        rationale: `${plannedReason.rationale}; human_confirmed: ${confirmation.rationale}`,
+        ...(plannedReason.conflictId !== undefined ? { conflictId: plannedReason.conflictId } : {}),
+    };
+}
+function abstain(reason, previousAtom, sourceEvents, relatedConflictIds) {
+    return {
+        outcome: 'fetch_abstain',
+        reasons: [reason],
+        previousAtom,
+        sourceEvents,
+        successorDraft: null,
+        plannedTransitions: [],
+        relatedConflictIds,
+    };
+}
+//# sourceMappingURL=reconsolidation-planner.js.map

package/dist/reconsolidation-planner.js.map

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

package/dist/sleep-cycle.d.ts

@@ -0,0 +1,70 @@
+import type { MemoryId } from '@aletheia-labs/core';
+import type { DynamicsDecision, DynamicsTickInput, DynamicsTickResult } from './dynamics-engine.js';
+export type SleepCycleMode = 'dry_run' | 'apply';
+export interface SleepCycleInput extends DynamicsTickInput {
+    readonly cycleId?: string;
+}
+export interface SleepCycleReport {
+    readonly cycleId: string;
+    readonly mode: SleepCycleMode;
+    readonly now: DynamicsTickResult['now'];
+    readonly scope: DynamicsTickResult['scope'];
+    readonly scopeKey: string;
+    readonly outcome: DynamicsTickResult['outcome'];
+    readonly reasons: readonly string[];
+    readonly decisions: readonly DynamicsDecision[];
+    readonly appliedMemoryIds: readonly MemoryId[];
+    readonly plannedMemoryIds: readonly MemoryId[];
+    readonly rejectedMemoryIds: readonly MemoryId[];
+    readonly skippedMemoryIds: readonly MemoryId[];
+    readonly appliedCount: number;
+    readonly plannedCount: number;
+    readonly rejectedCount: number;
+    readonly skippedCount: number;
+}
+export interface MultiCycleReport {
+    readonly reports: readonly SleepCycleReport[];
+    readonly appliedMemoryIds: readonly MemoryId[];
+    readonly plannedMemoryIds: readonly MemoryId[];
+    readonly rejectedMemoryIds: readonly MemoryId[];
+    readonly skippedMemoryIds: readonly MemoryId[];
+    readonly appliedCount: number;
+    readonly plannedCount: number;
+    readonly rejectedCount: number;
+    readonly skippedCount: number;
+}
+export interface SleepCycleEngine {
+    /**
+     * Run a lifecycle tick for a single explicit cycle input.
+     */
+    tick(input: DynamicsTickInput): Promise<DynamicsTickResult>;
+}
+export declare class SleepCycleRunner {
+    private readonly engine;
+    /**
+     * Wrap a dynamics-compatible engine with report formatting helpers.
+     *
+     * @remarks
+     * The runner is an orchestrator, not a scheduler. It only runs when the host
+     * calls `run()` or `runMany()`.
+     */
+    constructor(engine: SleepCycleEngine);
+    /**
+     * Run one explicit sleep cycle and return an audit-friendly report.
+     *
+     * @remarks
+     * The report mirrors the underlying `DynamicsEngine.tick()` result while
+     * grouping memory IDs by applied/planned/rejected/skipped outcome for logs,
+     * dashboards, or tests.
+     */
+    run(input: SleepCycleInput): Promise<SleepCycleReport>;
+    /**
+     * Run a host-provided sequence of explicit cycles in order.
+     *
+     * @remarks
+     * This is deterministic orchestration only. It does not retry, schedule,
+     * sleep, or watch the store; hosts decide when each cycle input exists.
+     */
+    runMany(inputs: readonly SleepCycleInput[]): Promise<MultiCycleReport>;
+}
+//# sourceMappingURL=sleep-cycle.d.ts.map

package/dist/sleep-cycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep-cycle.d.ts","sourceRoot":"","sources":["../src/sleep-cycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAEpG,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,OAAO,CAAC;AAEjD,MAAM,WAAW,eAAgB,SAAQ,iBAAiB;IACxD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC,SAAS,CAAC,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAChD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC/C,QAAQ,CAAC,gBAAgB,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC/C,QAAQ,CAAC,iBAAiB,EAAE,SAAS,QAAQ,EAAE,CAAC;IAChD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC/C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,QAAQ,CAAC,gBAAgB,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC/C,QAAQ,CAAC,gBAAgB,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC/C,QAAQ,CAAC,iBAAiB,EAAE,SAAS,QAAQ,EAAE,CAAC;IAChD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC/C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC7D;AAED,qBAAa,gBAAgB;IAQf,OAAO,CAAC,QAAQ,CAAC,MAAM;IAPnC;;;;;;OAMG;gBAC0B,MAAM,EAAE,gBAAgB;IAErD;;;;;;;OAOG;IACG,GAAG,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAwB5D;;;;;;OAMG;IACG,OAAO,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAkB7E"}

package/dist/sleep-cycle.js

@@ -0,0 +1,77 @@
+import { scopeKey } from '@aletheia-labs/core';
+export class SleepCycleRunner {
+    engine;
+    /**
+     * Wrap a dynamics-compatible engine with report formatting helpers.
+     *
+     * @remarks
+     * The runner is an orchestrator, not a scheduler. It only runs when the host
+     * calls `run()` or `runMany()`.
+     */
+    constructor(engine) {
+        this.engine = engine;
+    }
+    /**
+     * Run one explicit sleep cycle and return an audit-friendly report.
+     *
+     * @remarks
+     * The report mirrors the underlying `DynamicsEngine.tick()` result while
+     * grouping memory IDs by applied/planned/rejected/skipped outcome for logs,
+     * dashboards, or tests.
+     */
+    async run(input) {
+        const result = await this.engine.tick(input);
+        const cycleId = input.cycleId ?? `sleep:${input.now}:${scopeKey(input.scope)}`;
+        return {
+            cycleId,
+            mode: input.applyTransitions === true ? 'apply' : 'dry_run',
+            now: result.now,
+            scope: result.scope,
+            scopeKey: scopeKey(result.scope),
+            outcome: result.outcome,
+            reasons: result.reasons,
+            decisions: result.decisions,
+            appliedMemoryIds: idsFor(result.decisions, 'applied'),
+            plannedMemoryIds: idsFor(result.decisions, 'planned'),
+            rejectedMemoryIds: idsFor(result.decisions, 'rejected'),
+            skippedMemoryIds: idsFor(result.decisions, 'skipped'),
+            appliedCount: result.appliedCount,
+            plannedCount: result.plannedCount,
+            rejectedCount: result.rejectedCount,
+            skippedCount: result.skippedCount,
+        };
+    }
+    /**
+     * Run a host-provided sequence of explicit cycles in order.
+     *
+     * @remarks
+     * This is deterministic orchestration only. It does not retry, schedule,
+     * sleep, or watch the store; hosts decide when each cycle input exists.
+     */
+    async runMany(inputs) {
+        const reports = [];
+        for (const input of inputs) {
+            reports.push(await this.run(input));
+        }
+        return {
+            reports,
+            appliedMemoryIds: uniqueFlatMap(reports, (report) => report.appliedMemoryIds),
+            plannedMemoryIds: uniqueFlatMap(reports, (report) => report.plannedMemoryIds),
+            rejectedMemoryIds: uniqueFlatMap(reports, (report) => report.rejectedMemoryIds),
+            skippedMemoryIds: uniqueFlatMap(reports, (report) => report.skippedMemoryIds),
+            appliedCount: reports.reduce((sum, report) => sum + report.appliedCount, 0),
+            plannedCount: reports.reduce((sum, report) => sum + report.plannedCount, 0),
+            rejectedCount: reports.reduce((sum, report) => sum + report.rejectedCount, 0),
+            skippedCount: reports.reduce((sum, report) => sum + report.skippedCount, 0),
+        };
+    }
+}
+function idsFor(decisions, outcome) {
+    return decisions
+        .filter((decision) => decision.outcome === outcome)
+        .map((decision) => decision.memoryId);
+}
+function uniqueFlatMap(reports, getIds) {
+    return [...new Set(reports.flatMap((report) => getIds(report)))];
+}
+//# sourceMappingURL=sleep-cycle.js.map

package/dist/sleep-cycle.js.map

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

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@aletheia-labs/dynamics",
+  "version": "0.1.0",
+  "description": "Deterministic memory dynamics for Aletheia: decay, promotion, and conflict revisits.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@aletheia-labs/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "aletheia",
+    "llm",
+    "memory",
+    "dynamics",
+    "agents"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}