@astragenie/astramemory-local 0.7.2

package/dist/server/routes/search.js

@@ -0,0 +1,203 @@
+/**
+ * Search routes:
+ *   GET  /search?q=&type=&repo=&project=&agent=&since=&as_of=&entity=&limit=
+ *   POST /recall  { query, k, filters? }  filters.as_of: ISO-8601 date-time,
+ *                                          filters.entity: FEAT-402 AC-4
+ *   POST /remember { text, type, metadata? }
+ */
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { MemoryRepo } from '../../storage/memories.js';
+import { MemoryEventRepo } from '../../storage/memory-events.js';
+import { recordRecallServed } from '../../storage/usefulness.js';
+import { SqliteVecStore } from '../../vector/sqlite-vec.js';
+import { search, parseAsOf } from '../../search/search.js';
+import { defaultConfig } from '../../config/config.js';
+import { childLogger } from '../../log/logger.js';
+import { redactIfEnabled } from '../../redact/index.js';
+import { recordRedactionEvents } from '../../storage/redaction-log.js';
+import { clampScores } from '../lib/score-contract.js';
+const MemoryTypeEnum = z.enum(['decision', 'fact', 'lesson', 'command', 'todo', 'note', 'event']);
+/**
+ * FEAT-423: normalize a comma-separated query-param value into the
+ * SearchFilters shape — a single string stays a string (`col = ?`), multiple
+ * comma-separated values become a string[] (`col IN (...)`). Empty/whitespace
+ * segments are dropped; an all-empty value yields undefined (no filter).
+ */
+function csvFilter(raw) {
+    const parts = raw.split(',').map(s => s.trim()).filter(Boolean);
+    if (parts.length === 0)
+        return undefined;
+    return parts.length === 1 ? parts[0] : parts;
+}
+const RecallBodySchema = z.object({
+    query: z.string().min(1),
+    k: z.number().int().positive().default(5),
+    filters: z.object({
+        type: z.array(z.string()).optional(),
+        repo: z.string().optional(),
+        /** FEAT-423: single project or a list (OR-semantics). */
+        project: z.union([z.string(), z.array(z.string())]).optional(),
+        /** FEAT-423: single agent or a list; exact match on provenance agent/agent_type. */
+        agent: z.union([z.string(), z.array(z.string())]).optional(),
+        since: z.number().optional(),
+        /** FEAT-401: ISO-8601 date-time — bitemporal time-travel (ADR-001/ADR-005). */
+        as_of: z.string().optional(),
+        /** FEAT-402 slice 2 AC-4: entity name — resolved via the AC-9 normalize seam. */
+        entity: z.string().optional()
+    }).optional()
+});
+const RememberBodySchema = z.object({
+    text: z.string().min(1),
+    type: MemoryTypeEnum,
+    metadata: z.object({
+        repo: z.string().optional(),
+        project: z.string().optional(),
+        branch: z.string().optional(),
+        agent: z.string().optional(),
+        importance: z.number().min(0).max(1).optional(),
+        confidence: z.number().min(0).max(1).optional()
+    }).optional()
+});
+export function searchRoute(db, embed, config = defaultConfig()) {
+    const cfg = defaultConfig();
+    const weights = cfg.search;
+    return async (app) => {
+        // GET /search
+        app.get('/search', async (req, reply) => {
+            const params = req.query;
+            if (!params.q && params.q !== '') {
+                return reply.code(400).send({ error: 'q parameter is required' });
+            }
+            const q = params.q ?? '';
+            const limit = params.limit ? Math.max(1, Math.min(100, Number(params.limit))) : 10;
+            const filters = {};
+            if (params.type)
+                filters.type = params.type.split(',').map(t => t.trim());
+            if (params.repo)
+                filters.repo = params.repo;
+            if (params.project)
+                filters.project = csvFilter(params.project);
+            if (params.agent)
+                filters.agent = csvFilter(params.agent);
+            if (params.since) {
+                // Accept epoch ms directly or duration strings like "7d", "24h"
+                const sinceNum = Number(params.since);
+                if (!isNaN(sinceNum)) {
+                    filters.since = sinceNum;
+                }
+            }
+            if (params.as_of) {
+                try {
+                    filters.as_of = parseAsOf(params.as_of);
+                }
+                catch (err) {
+                    return reply.code(400).send({ error: err instanceof Error ? err.message : 'invalid as_of' });
+                }
+            }
+            if (params.entity)
+                filters.entity = params.entity;
+            const hits = await search(q, filters, limit, { db, embed, weights });
+            // ADR-010: recall-usefulness capture — measure only, does not feed ranking (v1).
+            recordRecallServed(db, {
+                query: q,
+                atomIds: hits.map(h => h.id),
+                scores: hits.map(h => h.score),
+                surface: 'rest',
+                mode: 'search',
+            });
+            // SLICE-411: enforce the [0,1] wire score contract at serialization,
+            // independent of fuseScores() internal math.
+            return { hits: clampScores(hits, 'GET /search') };
+        });
+        // POST /recall
+        app.post('/recall', async (req, reply) => {
+            const parsed = RecallBodySchema.safeParse(req.body);
+            if (!parsed.success) {
+                return reply.code(400).send({ error: 'invalid', details: parsed.error.flatten() });
+            }
+            const { query, k, filters: rawFilters } = parsed.data;
+            const filters = {};
+            if (rawFilters?.type)
+                filters.type = rawFilters.type;
+            if (rawFilters?.repo)
+                filters.repo = rawFilters.repo;
+            if (rawFilters?.project)
+                filters.project = rawFilters.project;
+            if (rawFilters?.agent)
+                filters.agent = rawFilters.agent;
+            if (rawFilters?.since !== undefined)
+                filters.since = rawFilters.since;
+            if (rawFilters?.as_of !== undefined) {
+                try {
+                    filters.as_of = parseAsOf(rawFilters.as_of);
+                }
+                catch (err) {
+                    return reply.code(400).send({ error: err instanceof Error ? err.message : 'invalid as_of' });
+                }
+            }
+            if (rawFilters?.entity !== undefined)
+                filters.entity = rawFilters.entity;
+            const hits = await search(query, filters, k, { db, embed, weights });
+            // ADR-010: recall-usefulness capture — measure only, does not feed ranking (v1).
+            recordRecallServed(db, {
+                query,
+                atomIds: hits.map(h => h.id),
+                scores: hits.map(h => h.score),
+                surface: 'rest',
+                mode: 'recall',
+            });
+            // SLICE-411: enforce the [0,1] wire score contract at serialization,
+            // independent of fuseScores() internal math.
+            return { hits: clampScores(hits, 'POST /recall') };
+        });
+        // POST /remember — direct insert bypassing distillation pipeline
+        app.post('/remember', async (req, reply) => {
+            const parsed = RememberBodySchema.safeParse(req.body);
+            if (!parsed.success) {
+                return reply.code(400).send({ error: 'invalid', details: parsed.error.flatten() });
+            }
+            const { type, metadata } = parsed.data;
+            // Stage-0 secret redaction (SEC-3/5, OQ-2) — same choke point as ingest,
+            // applied before persistence AND before the embed call (SEC-4: no
+            // un-redacted content reaches a cloud embed provider).
+            const { text, events: redactionEvents } = redactIfEnabled(parsed.data.text, config);
+            recordRedactionEvents(db, redactionEvents, null);
+            // Compute hash for dedup
+            const hash = createHash('sha256').update(text).digest('hex').slice(0, 32);
+            const repo = new MemoryRepo(db);
+            const events = new MemoryEventRepo(db);
+            const { id } = repo.insertWithCreateEvent({
+                type,
+                text,
+                normalized_text: text.toLowerCase(),
+                repo: metadata?.repo ?? null,
+                project: metadata?.project ?? null,
+                branch: metadata?.branch ?? null,
+                agent: metadata?.agent ?? null,
+                session_id: null,
+                hash,
+                source_hash: null,
+                importance: metadata?.importance ?? 0.5,
+                confidence: metadata?.confidence ?? 0.5,
+                embedding_provider: embed.name,
+                embedding_model: embed.model,
+                embedding_dim: embed.dim
+            }, events);
+            // Embed + upsert into vec store
+            try {
+                const vecs = await embed.embed([text]);
+                const vecStore = new SqliteVecStore(db, embed.dim);
+                if (!vecs[0])
+                    throw new Error('embed provider returned empty result');
+                await vecStore.upsert(id, vecs[0]);
+            }
+            catch (err) {
+                // Non-fatal: FTS still works; vec will be populated on reembed
+                childLogger({}).warn({ error_message: err instanceof Error ? err.message : String(err), id }, 'remember: embed/vec upsert failed');
+            }
+            return { id, ok: true };
+        });
+    };
+}
+//# sourceMappingURL=search.js.map

package/dist/server/routes/search.js.map

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

package/dist/server/routes/version.d.ts

@@ -0,0 +1,2 @@
+import type { FastifyInstance } from 'fastify';
+export declare function versionRoute(app: FastifyInstance): Promise<void>;

package/dist/server/routes/version.js

@@ -0,0 +1,11 @@
+import { PKG_VERSION, WIRE_VERSIONS_SUPPORTED, SCHEMA_VERSION } from '../lib/wire-meta.js';
+export async function versionRoute(app) {
+    app.get('/version', async () => ({
+        name: 'astramemory-local',
+        version: PKG_VERSION,
+        wire_versions_supported: WIRE_VERSIONS_SUPPORTED,
+        schema_version: SCHEMA_VERSION,
+        ts: Date.now(),
+    }));
+}
+//# sourceMappingURL=version.js.map

package/dist/server/routes/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../../src/server/routes/version.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE3F,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,GAAoB;IACrD,GAAG,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QAC/B,IAAI,EAAE,mBAAmB;QACzB,OAAO,EAAE,WAAW;QACpB,uBAAuB,EAAE,uBAAuB;QAChD,cAAc,EAAE,cAAc;QAC9B,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE;KACf,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/server/routes/why.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Provenance receipt route (KF-A):
+ *   GET /memory/:id/why — memory + evidence + source session + transcript ref.
+ * `history` is the memory_events lifecycle log for this atom (ADR-002,
+ * Wave 2b) — empty for atoms that predate any lifecycle events.
+ */
+import type { FastifyInstance } from 'fastify';
+import type { DB } from '../../storage/db.js';
+export declare function whyRoute(db: DB): (app: FastifyInstance) => Promise<void>;

package/dist/server/routes/why.js

@@ -0,0 +1,38 @@
+/**
+ * Provenance receipt route (KF-A):
+ *   GET /memory/:id/why — memory + evidence + source session + transcript ref.
+ * `history` is the memory_events lifecycle log for this atom (ADR-002,
+ * Wave 2b) — empty for atoms that predate any lifecycle events.
+ */
+import { MemoryRepo } from '../../storage/memories.js';
+import { MemoryEventRepo } from '../../storage/memory-events.js';
+export function whyRoute(db) {
+    return async (app) => {
+        app.get('/memory/:id/why', async (req, reply) => {
+            const { id } = req.params;
+            const memory = new MemoryRepo(db).get(id);
+            if (!memory) {
+                return reply.code(404).send({ error: 'not found', id });
+            }
+            let session = null;
+            if (memory.session_id) {
+                session = db
+                    .prepare('SELECT id, repo, branch, agent, started_at FROM sessions WHERE id = ?')
+                    .get(memory.session_id) ?? null;
+            }
+            return {
+                id: memory.id,
+                type: memory.type,
+                text: memory.text,
+                importance: memory.importance,
+                confidence: memory.confidence,
+                evidence: memory.evidence,
+                session,
+                transcript_ref: memory.source_hash,
+                created_at: memory.created_at,
+                history: new MemoryEventRepo(db).listForAtom(id),
+            };
+        });
+    };
+}
+//# sourceMappingURL=why.js.map

package/dist/server/routes/why.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"why.js","sourceRoot":"","sources":["../../../src/server/routes/why.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAUjE,MAAM,UAAU,QAAQ,CAAC,EAAM;IAC7B,OAAO,KAAK,EAAE,GAAoB,EAAE,EAAE;QACpC,GAAG,CAAC,GAAG,CAAC,iBAAiB,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE;YAC9C,MAAM,EAAE,EAAE,EAAE,GAAG,GAAG,CAAC,MAAwB,CAAC;YAC5C,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC1C,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC,CAAC;YAC1D,CAAC;YAED,IAAI,OAAO,GAAwB,IAAI,CAAC;YACxC,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;gBACtB,OAAO,GAAI,EAAE;qBACV,OAAO,CAAC,uEAAuE,CAAC;qBAChF,GAAG,CAAC,MAAM,CAAC,UAAU,CAA8B,IAAI,IAAI,CAAC;YACjE,CAAC;YAED,OAAO;gBACL,EAAE,EAAE,MAAM,CAAC,EAAE;gBACb,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,OAAO;gBACP,cAAc,EAAE,MAAM,CAAC,WAAW;gBAClC,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,OAAO,EAAE,IAAI,eAAe,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC;aACjD,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}

package/dist/service/index.d.ts

@@ -0,0 +1,10 @@
+import type { ServiceAdapter } from './types.js';
+export { type ServiceAdapter, type ServiceStatus, type InstallResult } from './types.js';
+export { SystemdAdapter } from './systemd.js';
+export { LaunchdAdapter } from './launchd.js';
+export { SchtasksAdapter } from './schtasks.js';
+/**
+ * Returns the ServiceAdapter appropriate for the current OS.
+ * @param overridePlatform - inject for testing without needing to mock ESM live bindings
+ */
+export declare function getServiceAdapter(overridePlatform?: string): ServiceAdapter;

package/dist/service/index.js

@@ -0,0 +1,25 @@
+import { platform } from 'node:os';
+import { SystemdAdapter } from './systemd.js';
+import { LaunchdAdapter } from './launchd.js';
+import { SchtasksAdapter } from './schtasks.js';
+export { SystemdAdapter } from './systemd.js';
+export { LaunchdAdapter } from './launchd.js';
+export { SchtasksAdapter } from './schtasks.js';
+/**
+ * Returns the ServiceAdapter appropriate for the current OS.
+ * @param overridePlatform - inject for testing without needing to mock ESM live bindings
+ */
+export function getServiceAdapter(overridePlatform) {
+    const p = overridePlatform ?? platform();
+    switch (p) {
+        case 'linux':
+            return new SystemdAdapter();
+        case 'darwin':
+            return new LaunchdAdapter();
+        case 'win32':
+            return new SchtasksAdapter();
+        default:
+            throw new Error(`Unsupported platform: ${p}. AstraMemory service install supports linux, darwin, win32.`);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/service/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/service/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAIhD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,gBAAyB;IACzD,MAAM,CAAC,GAAG,gBAAgB,IAAI,QAAQ,EAAE,CAAC;IACzC,QAAQ,CAAC,EAAE,CAAC;QACV,KAAK,OAAO;YACV,OAAO,IAAI,cAAc,EAAE,CAAC;QAC9B,KAAK,QAAQ;YACX,OAAO,IAAI,cAAc,EAAE,CAAC;QAC9B,KAAK,OAAO;YACV,OAAO,IAAI,eAAe,EAAE,CAAC;QAC/B;YACE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,8DAA8D,CAAC,CAAC;IAC9G,CAAC;AACH,CAAC"}

package/dist/service/install-flow.d.ts

@@ -0,0 +1,18 @@
+import type { InstallResult, ServiceAdapter } from './types.js';
+export interface ResolvedBuild {
+    nodeBin: string;
+    entryJs: string;
+    /** `"<node>" "<entryJs>"` — for direct (non-shim) execution, e.g. the
+     *  backup timer task which must run `backup --keep N`, not the daemon. */
+    rawExecPath: string;
+}
+/** Resolve the running build's CLI entry from this module's own location. */
+export declare function resolveBuild(): ResolvedBuild;
+export interface InstallFlowOutcome {
+    result: InstallResult;
+    adapter: ServiceAdapter;
+    build: ResolvedBuild;
+    /** What the scheduler actually points at (shim on Windows). */
+    taskExecPath: string;
+}
+export declare function installServiceFlow(port: number): Promise<InstallFlowOutcome>;

package/dist/service/install-flow.js

@@ -0,0 +1,47 @@
+/**
+ * install-flow.ts — the ONE service-install code path (D4).
+ *
+ * Used by `service install`, `init`, and `reinstall` so there is exactly one
+ * implementation of: resolve the current build → (Windows) write the stable
+ * shim → register with the OS scheduler.
+ *
+ * On Windows the scheduler is pointed at the STABLE shim path, never at the
+ * build directly — upgrades only rewrite the shim pointer (see shim.ts).
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { getServiceAdapter } from './index.js';
+import { writeShim, shimPaths } from './shim.js';
+import { resolveRuntimeConfig } from '../config/resolve-runtime.js';
+/** Resolve the running build's CLI entry from this module's own location. */
+export function resolveBuild() {
+    const nodeBin = process.execPath;
+    const thisFile = new URL(import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1');
+    // dist/service/install-flow.js → dist/cli/index.js (URL paths are /-separated)
+    const entryJs = thisFile.replace(/service\/install-flow\.(js|ts)$/, 'cli/index.js');
+    return { nodeBin, entryJs, rawExecPath: `"${nodeBin}" "${entryJs}"` };
+}
+export async function installServiceFlow(port) {
+    const adapter = getServiceAdapter();
+    const build = resolveBuild();
+    if (!existsSync(build.entryJs)) {
+        throw new Error(`CLI entry not found at ${build.entryJs} — the build is missing or partial.\n` +
+            `Run: bun install && bun run build`);
+    }
+    let taskExecPath;
+    if (adapter.platform === 'win32') {
+        // Service logs rotate under the data dir (see logger.ts ASTRA_LOG_DIR).
+        const { dataDir } = resolveRuntimeConfig({ port });
+        const logDir = join(dataDir, 'logs');
+        const paths = writeShim({ nodeBin: build.nodeBin, entryJs: build.entryJs, port, logDir }, shimPaths());
+        console.log(`  · shim written: ${paths.cmdPath}`);
+        console.log(`  · pointer     : ${paths.pointerPath} → ${build.entryJs}`);
+        taskExecPath = `"${paths.cmdPath}"`;
+    }
+    else {
+        taskExecPath = build.rawExecPath;
+    }
+    const result = await adapter.install(taskExecPath, port);
+    return { result, adapter, build, taskExecPath };
+}
+//# sourceMappingURL=install-flow.js.map

package/dist/service/install-flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-flow.js","sourceRoot":"","sources":["../../src/service/install-flow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAWpE,6EAA6E;AAC7E,MAAM,UAAU,YAAY;IAC1B,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;IACjC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,gBAAgB,EAAE,IAAI,CAAC,CAAC;IACnF,+EAA+E;IAC/E,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,iCAAiC,EAAE,cAAc,CAAC,CAAC;IACpF,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,OAAO,MAAM,OAAO,GAAG,EAAE,CAAC;AACxE,CAAC;AAUD,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAAY;IACnD,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAC;IACpC,MAAM,KAAK,GAAG,YAAY,EAAE,CAAC;IAE7B,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CACb,0BAA0B,KAAK,CAAC,OAAO,uCAAuC;YAC9E,mCAAmC,CACpC,CAAC;IACJ,CAAC;IAED,IAAI,YAAoB,CAAC;IACzB,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,wEAAwE;QACxE,MAAM,EAAE,OAAO,EAAE,GAAG,oBAAoB,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;QACnD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACrC,MAAM,KAAK,GAAG,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;QACvG,OAAO,CAAC,GAAG,CAAC,qBAAqB,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAClD,OAAO,CAAC,GAAG,CAAC,qBAAqB,KAAK,CAAC,WAAW,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACzE,YAAY,GAAG,IAAI,KAAK,CAAC,OAAO,GAAG,CAAC;IACtC,CAAC;SAAM,CAAC;QACN,YAAY,GAAG,KAAK,CAAC,WAAW,CAAC;IACnC,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IACzD,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC;AAClD,CAAC"}

package/dist/service/instance-lock.d.ts

@@ -0,0 +1,26 @@
+export interface LockInfo {
+    pid: number;
+    startedAt: string;
+    port: number;
+    version: string;
+}
+export interface InstanceLock {
+    path: string;
+    release(): void;
+}
+export declare class AlreadyRunningError extends Error {
+    readonly holder: LockInfo;
+    constructor(holder: LockInfo);
+}
+export declare function lockPath(dataDir: string): string;
+/** Read the current lock holder for a data dir (null when absent/corrupt). */
+export declare function readLockInfo(dataDir: string): LockInfo | null;
+/**
+ * Acquire the single-instance lock for `dataDir`.
+ *
+ * Throws AlreadyRunningError when a healthy daemon already holds it.
+ * Returns a handle whose release() is idempotent and safe from crash handlers.
+ */
+export declare function acquireInstanceLock(dataDir: string, port: number, version: string, opts?: {
+    healthProbe?: (port: number) => Promise<boolean>;
+}): Promise<InstanceLock>;

package/dist/service/instance-lock.js

@@ -0,0 +1,150 @@
+/**
+ * instance-lock.ts — single-instance protection for the daemon (D2).
+ *
+ * The lock protects the DATA DIRECTORY (the real single-writer invariant),
+ * not just the TCP port: a second daemon on a different port pointed at the
+ * same memory.sqlite would race the job queue and contend for writes.
+ *
+ * Lock file: <dataDir>/daemon.lock — JSON { pid, startedAt, port, version }.
+ *
+ * Acquisition:
+ *  1. Exclusive create ('wx') succeeds → we own the lock.
+ *  2. Exists → read holder. Dead PID → stale, steal.
+ *  3. Holder PID alive → probe its /health (2s timeout, 3 attempts). Healthy
+ *     → AlreadyRunningError (caller exits 0 — this makes schtasks keepalive
+ *     re-runs cheap no-ops). Unhealthy 3× → zombie (hung process or a
+ *     foreign PID that recycled the id) → steal loudly.
+ *
+ * Steal = atomic tmp+rename overwrite, same pattern as migrate-encrypt.ts.
+ */
+import { openSync, closeSync, writeSync, readFileSync, writeFileSync, renameSync, unlinkSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+export class AlreadyRunningError extends Error {
+    holder;
+    constructor(holder) {
+        super(`astramem-local already running (pid ${holder.pid}, port ${holder.port}, since ${holder.startedAt})`);
+        this.holder = holder;
+        this.name = 'AlreadyRunningError';
+    }
+}
+export function lockPath(dataDir) {
+    return join(dataDir, 'daemon.lock');
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function healthOk(port, timeoutMs = 2000) {
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}/health`, {
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+function writeLock(path, info, exclusive) {
+    const body = JSON.stringify(info);
+    if (exclusive) {
+        const fd = openSync(path, 'wx');
+        try {
+            writeSync(fd, body);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    else {
+        // Steal: atomic tmp+rename so a concurrent reader never sees a torn file.
+        const tmp = `${path}.tmp`;
+        writeFileSync(tmp, body);
+        renameSync(tmp, path);
+    }
+}
+/** Read the current lock holder for a data dir (null when absent/corrupt). */
+export function readLockInfo(dataDir) {
+    return readLock(lockPath(dataDir));
+}
+function readLock(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (typeof parsed.pid !== 'number' || typeof parsed.port !== 'number')
+            return null;
+        return {
+            pid: parsed.pid,
+            port: parsed.port,
+            startedAt: typeof parsed.startedAt === 'string' ? parsed.startedAt : '',
+            version: typeof parsed.version === 'string' ? parsed.version : '',
+        };
+    }
+    catch {
+        // Unreadable/corrupt lock → treat as stale.
+        return null;
+    }
+}
+/**
+ * Acquire the single-instance lock for `dataDir`.
+ *
+ * Throws AlreadyRunningError when a healthy daemon already holds it.
+ * Returns a handle whose release() is idempotent and safe from crash handlers.
+ */
+export async function acquireInstanceLock(dataDir, port, version, opts = {}) {
+    const path = lockPath(dataDir);
+    const probe = opts.healthProbe ?? healthOk;
+    const mine = { pid: process.pid, startedAt: new Date().toISOString(), port, version };
+    let exclusive = true;
+    if (existsSync(path)) {
+        const holder = readLock(path);
+        if (holder && pidAlive(holder.pid) && holder.pid !== process.pid) {
+            // PID alive — is it actually serving?
+            let healthy = false;
+            for (let i = 0; i < 3 && !healthy; i++) {
+                healthy = await probe(holder.port);
+            }
+            if (healthy)
+                throw new AlreadyRunningError(holder);
+            console.warn(`[astramem-local] daemon.lock held by pid ${holder.pid} but /health on port ${holder.port} ` +
+                `is unresponsive (3 probes) — treating as zombie and taking over the lock.`);
+        }
+        exclusive = false; // stale/zombie/corrupt → steal via tmp+rename
+    }
+    try {
+        writeLock(path, mine, exclusive);
+    }
+    catch (err) {
+        if (err.code === 'EEXIST') {
+            // Raced another starting daemon between existsSync and open('wx') —
+            // the other process won; defer to it.
+            const holder = readLock(path);
+            throw new AlreadyRunningError(holder ?? { pid: -1, port, startedAt: '', version: '' });
+        }
+        throw err;
+    }
+    let released = false;
+    return {
+        path,
+        release() {
+            if (released)
+                return;
+            released = true;
+            try {
+                // Only remove the lock if we still own it (a zombie-steal by a newer
+                // process must not be deleted by the old holder on its way out).
+                const current = readLock(path);
+                if (current && current.pid === process.pid)
+                    unlinkSync(path);
+            }
+            catch {
+                /* best-effort — lock steal handles leftovers */
+            }
+        },
+    };
+}
+//# sourceMappingURL=instance-lock.js.map

package/dist/service/instance-lock.js.map

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

package/dist/service/launchd.d.ts

@@ -0,0 +1,11 @@
+import type { ServiceAdapter, ServiceStatus, InstallResult } from './types.js';
+export declare class LaunchdAdapter implements ServiceAdapter {
+    readonly platform: "darwin";
+    install(execPath: string, port: number): Promise<InstallResult>;
+    uninstall(): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    status(): Promise<ServiceStatus>;
+    installBackupTimer(execPath: string, keep: number): Promise<void>;
+    uninstallBackupTimer(): Promise<void>;
+}