@astragenie/astramemory-local 0.7.2

package/dist/entity/extract-entities.js

@@ -0,0 +1,86 @@
+/**
+ * Entity-only LLM extraction (FEAT-402 AC-7) — used by the `entity-backfill`
+ * command to extract entities from ALREADY-DISTILLED memory text, without
+ * re-running the full 8-stage distill pipeline (no re-chunking, no atom
+ * re-extraction, memory text and hash untouched). Distill-time extraction
+ * (stage 5, src/distill/stages/05-extract.ts) instead emits entities inline
+ * on each atom in the SAME LLM call — this module exists only for the
+ * backfill's one-shot pass over pre-existing rows that predate that stage.
+ *
+ * Deliberately lenient: unlike stage 5's extractChunk (which throws
+ * DeterministicError on parse failure and poisons the job), a bad response
+ * here just returns [] and lets the caller log + move on. The corpus is
+ * scanned by "not yet linked" (src/entity/backfill.ts), so a memory that got
+ * an empty/failed extraction this run remains a valid candidate on the next
+ * run — the backfill is naturally resumable without a checkpoint table.
+ */
+import { z } from 'zod';
+import { AtomEntitySchema } from '../distill/prompts/extract.js';
+import { BudgetTracker } from '../budget/tracker.js';
+const LenientEntitiesSchema = z.object({ entities: z.array(z.unknown()) });
+export const ENTITY_ONLY_SYSTEM_PROMPT = `You identify named things mentioned in a short piece of durable knowledge extracted from an AI coding agent transcript.
+
+Output STRICT JSON matching:
+{
+  "entities": [
+    { "name": "<named thing mentioned>", "kind": "product" | "tech" | "person" | "org" | "repo" | "concept" }
+  ]
+}
+
+kind is one of:
+- product: a named product or app (e.g. "AstraMemory", "GitHub Copilot")
+- tech: a language/framework/library/tool/protocol (e.g. "Postgres", "TypeScript", "sqlite-vec")
+- person: a named individual
+- org: a company or organization
+- repo: a named git repository or codebase
+- concept: a named pattern, architecture, or idea (e.g. "bitemporal model", "CRDT")
+
+List every specific named thing the text is ABOUT — not every word. If nothing specific is named, return {"entities": []}.`;
+/**
+ * Extract entities from one piece of already-distilled memory text.
+ * Returns [] (never throws) on budget-exceeded, transport, or parse failure
+ * — callers decide whether/how to surface that (the backfill CLI counts it
+ * as "skipped", not "failed").
+ */
+export async function extractEntitiesForText(text, provider, budget, capUsd) {
+    if (!text.trim())
+        return [];
+    const promptChars = ENTITY_ONLY_SYSTEM_PROMPT.length + text.length;
+    const estimateUsd = BudgetTracker.estimateUsd(promptChars, 0.000002, 0.000002);
+    if (!budget.canSpend(estimateUsd, capUsd))
+        return [];
+    let raw;
+    let usageUsd;
+    try {
+        const result = await provider.chat([
+            { role: 'system', content: ENTITY_ONLY_SYSTEM_PROMPT },
+            { role: 'user', content: `Identify entities in this text:\n\n${text}` },
+        ], { temperature: 0.1, json: true, maxTokens: 400 });
+        raw = result.text;
+        usageUsd = result.usage.usd;
+    }
+    catch {
+        return [];
+    }
+    budget.record(usageUsd);
+    return tryParseEntities(raw);
+}
+function tryParseEntities(raw) {
+    try {
+        let text = raw.trim();
+        text = text.replace(/^```(?:json)?\n?/i, '').replace(/\n?```\s*$/i, '').trim();
+        const start = text.indexOf('{');
+        const end = text.lastIndexOf('}');
+        if (start === -1 || end === -1)
+            return [];
+        const parsed = JSON.parse(text.slice(start, end + 1));
+        const wrapper = LenientEntitiesSchema.safeParse(parsed);
+        if (!wrapper.success)
+            return [];
+        return wrapper.data.entities.filter((e) => AtomEntitySchema.safeParse(e).success);
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=extract-entities.js.map

package/dist/entity/extract-entities.js.map

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

package/dist/entity/normalize.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Entity name normalization — the single seam AC-9 requires.
+ *
+ * Every caller that resolves an entity name to an `entities.id` (distill-time
+ * extraction in stage 8, the entity-backfill command, and — in slice 2 — the
+ * search `entity=` filter) MUST go through this function first. Today it is
+ * lowercase + trim + whitespace-collapse only, so "Postgres" / "postgres" /
+ * "  Postgres  " collapse to the same normalized name and therefore the same
+ * `entities.id` via the UNIQUE constraint on `entities.name`.
+ *
+ * An alias table ("pg" -> "postgres", "postgres flexible" -> "postgres") is
+ * explicitly deferred (FEAT-402 AC-9, roadmap W4.x) but this function is
+ * where it plugs in later — swap the body for a dictionary/DB lookup and
+ * every call site (extraction, backfill, future query filter) inherits it
+ * without a single call-site edit.
+ */
+export declare function normalizeEntityName(raw: string): string;

package/dist/entity/normalize.js

@@ -0,0 +1,20 @@
+/**
+ * Entity name normalization — the single seam AC-9 requires.
+ *
+ * Every caller that resolves an entity name to an `entities.id` (distill-time
+ * extraction in stage 8, the entity-backfill command, and — in slice 2 — the
+ * search `entity=` filter) MUST go through this function first. Today it is
+ * lowercase + trim + whitespace-collapse only, so "Postgres" / "postgres" /
+ * "  Postgres  " collapse to the same normalized name and therefore the same
+ * `entities.id` via the UNIQUE constraint on `entities.name`.
+ *
+ * An alias table ("pg" -> "postgres", "postgres flexible" -> "postgres") is
+ * explicitly deferred (FEAT-402 AC-9, roadmap W4.x) but this function is
+ * where it plugs in later — swap the body for a dictionary/DB lookup and
+ * every call site (extraction, backfill, future query filter) inherits it
+ * without a single call-site edit.
+ */
+export function normalizeEntityName(raw) {
+    return raw.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+//# sourceMappingURL=normalize.js.map

package/dist/entity/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../src/entity/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC7C,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AACvD,CAAC"}

package/dist/eval/harness.d.ts

@@ -0,0 +1,96 @@
+/**
+ * ADR-005 retrieval eval harness.
+ *
+ * Seeds the shared eval corpus (contracts/fixtures/eval/corpus.json) into a
+ * live database, runs the shared query set through the local search engine,
+ * and scores recall@k / NDCG@k against the graded relevance judgments.
+ *
+ * Known v1 engine gaps, handled explicitly rather than silently:
+ *  - per-query `mode` (keyword|semantic|hybrid) is advisory only; the local
+ *    engine always runs its hybrid FTS+vector path. The mode is echoed in
+ *    the per-query report so a future mode-routing engine can be compared.
+ *
+ * FEAT-401: `as_of` (bitemporal time-travel) is now supported end-to-end —
+ * seedEvalCorpus backfills each atom's declared valid_from (in addition to
+ * valid_to) so corpus atoms carry their fixture-declared validity windows
+ * rather than the insert-time "now", and runRetrievalEval forwards
+ * `filters.as_of` straight into search() instead of skipping the query.
+ *
+ * FEAT-402 slice 2 (AC-8): each corpus atom may declare an `entities: string[]`
+ * array (already present on every fixture atom since slice 1). seedEvalCorpus
+ * links them via EntityRepo the same way distill-time extraction does, and a
+ * query may declare `filters.entity` to exercise the AC-4 pre-fusion
+ * intersection end-to-end. Fixture entities have no `kind` — seeded with the
+ * generic 'concept' kind, which is irrelevant to filtering (name-only lookup).
+ */
+import type { DB } from '../storage/db.js';
+import type { EmbedProvider } from '../contracts/index.js';
+import { type GradedRelevance } from './metrics.js';
+export interface EvalAtom {
+    id: string;
+    type: string;
+    text: string;
+    evidence: string | string[] | null;
+    confidence: number;
+    importance: number;
+    provenance: {
+        session_id: string;
+        repo: string;
+        project: string;
+    };
+    /** Bitemporal valid-time start (ADR-001). Optional for pre-FEAT-401 fixtures. */
+    valid_from?: string;
+    valid_to: string | null;
+    scope: string;
+    content_hash: string;
+    /** FEAT-402 slice 2 AC-8: entity names linked to this atom (kind-less — seeded as 'concept'). */
+    entities?: string[];
+}
+export interface EvalQuery {
+    id: string;
+    text: string;
+    mode: string;
+    filters: {
+        type?: string[];
+        as_of?: string;
+        entity?: string;
+    };
+    graded_relevant: GradedRelevance[];
+}
+export interface EvalCorpus {
+    atoms: EvalAtom[];
+}
+export interface EvalQuerySet {
+    queries: EvalQuery[];
+}
+export interface QueryResult {
+    id: string;
+    mode: string;
+    skipped: string | null;
+    recall: number | null;
+    ndcg: number | null;
+    rankedAtomIds: string[];
+}
+export interface EvalReport {
+    k: number;
+    perQuery: QueryResult[];
+    evaluated: number;
+    skipped: number;
+    meanRecall: number;
+    meanNdcg: number;
+}
+/**
+ * Insert every corpus atom into the DB (memories + FTS via trigger + vector
+ * index). Returns memory-id → atom-id so engine hits can be scored against
+ * the corpus judgments. Atoms with a non-null valid_to are marked
+ * invalidated after insert, matching their bitemporal state.
+ */
+export declare function seedEvalCorpus(db: DB, embed: EmbedProvider, corpus: EvalCorpus): Promise<Map<string, string>>;
+export declare function runRetrievalEval(db: DB, embed: EmbedProvider, weights: {
+    alpha: number;
+    beta: number;
+    gamma: number;
+    delta: number;
+    epsilon: number;
+    zeta?: number;
+}, corpus: EvalCorpus, querySet: EvalQuerySet, k?: number): Promise<EvalReport>;

package/dist/eval/harness.js

@@ -0,0 +1,119 @@
+/**
+ * ADR-005 retrieval eval harness.
+ *
+ * Seeds the shared eval corpus (contracts/fixtures/eval/corpus.json) into a
+ * live database, runs the shared query set through the local search engine,
+ * and scores recall@k / NDCG@k against the graded relevance judgments.
+ *
+ * Known v1 engine gaps, handled explicitly rather than silently:
+ *  - per-query `mode` (keyword|semantic|hybrid) is advisory only; the local
+ *    engine always runs its hybrid FTS+vector path. The mode is echoed in
+ *    the per-query report so a future mode-routing engine can be compared.
+ *
+ * FEAT-401: `as_of` (bitemporal time-travel) is now supported end-to-end —
+ * seedEvalCorpus backfills each atom's declared valid_from (in addition to
+ * valid_to) so corpus atoms carry their fixture-declared validity windows
+ * rather than the insert-time "now", and runRetrievalEval forwards
+ * `filters.as_of` straight into search() instead of skipping the query.
+ *
+ * FEAT-402 slice 2 (AC-8): each corpus atom may declare an `entities: string[]`
+ * array (already present on every fixture atom since slice 1). seedEvalCorpus
+ * links them via EntityRepo the same way distill-time extraction does, and a
+ * query may declare `filters.entity` to exercise the AC-4 pre-fusion
+ * intersection end-to-end. Fixture entities have no `kind` — seeded with the
+ * generic 'concept' kind, which is irrelevant to filtering (name-only lookup).
+ */
+import { MemoryRepo } from '../storage/memories.js';
+import { EntityRepo } from '../storage/entities.js';
+import { SqliteVecStore } from '../vector/sqlite-vec.js';
+import { search, parseAsOf } from '../search/search.js';
+import { recallAtK, ndcgAtK } from './metrics.js';
+/**
+ * Insert every corpus atom into the DB (memories + FTS via trigger + vector
+ * index). Returns memory-id → atom-id so engine hits can be scored against
+ * the corpus judgments. Atoms with a non-null valid_to are marked
+ * invalidated after insert, matching their bitemporal state.
+ */
+export async function seedEvalCorpus(db, embed, corpus) {
+    const repo = new MemoryRepo(db);
+    const entityRepo = new EntityRepo(db);
+    const vecStore = new SqliteVecStore(db, embed.dim);
+    const memToAtom = new Map();
+    for (const atom of corpus.atoms) {
+        const memId = repo.insert({
+            type: atom.type,
+            text: atom.text,
+            normalized_text: atom.text.toLowerCase(),
+            repo: atom.provenance.repo,
+            project: atom.provenance.project,
+            branch: null,
+            agent: null,
+            // corpus session ids don't exist in the sessions table (FK) — seed detached
+            session_id: null,
+            hash: atom.content_hash,
+            source_hash: null,
+            importance: atom.importance,
+            confidence: atom.confidence,
+            evidence: Array.isArray(atom.evidence) ? atom.evidence.join('; ') : atom.evidence,
+            scope: atom.scope,
+        });
+        // FEAT-401: backfill the fixture-declared valid_from/valid_to so corpus
+        // atoms carry their real bitemporal windows instead of insert-time "now"
+        // — required for as_of queries (q6) to resolve against the right
+        // generation. valid_from mirrors created_at on a fresh insert, so only
+        // rewrite it when the fixture declares a different instant.
+        if (atom.valid_from !== undefined) {
+            db.prepare('UPDATE memories SET valid_from = ? WHERE id = ?')
+                .run(Date.parse(atom.valid_from), memId);
+        }
+        if (atom.valid_to !== null) {
+            db.prepare('UPDATE memories SET valid_to = ? WHERE id = ?')
+                .run(Date.parse(atom.valid_to), memId);
+        }
+        const [vec] = await embed.embed([atom.text]);
+        if (!vec)
+            throw new Error(`embed returned no vector for atom ${atom.id}`);
+        await vecStore.upsert(memId, vec);
+        memToAtom.set(memId, atom.id);
+        // FEAT-402 slice 2 AC-8: link fixture-declared entities the same way
+        // distill-time extraction does, so the `entity=` filter (AC-4) has real
+        // memory_entities rows to intersect against in the eval gate.
+        if (atom.entities && atom.entities.length > 0) {
+            entityRepo.linkEntitiesForMemory(memId, atom.entities.map(name => ({ name, kind: 'concept' })));
+        }
+    }
+    return memToAtom;
+}
+export async function runRetrievalEval(db, embed, 
+// epsilon (ADR-010 usefulness component) and zeta (FEAT-402 AC-6 entity
+// bonus) are part of the fused score — the eval must exercise the same
+// weight set production search uses, not a narrower structural subset
+// that only works by accident.
+weights, corpus, querySet, k = 10) {
+    const memToAtom = await seedEvalCorpus(db, embed, corpus);
+    const perQuery = [];
+    for (const q of querySet.queries) {
+        const as_of = q.filters.as_of !== undefined ? parseAsOf(q.filters.as_of) : undefined;
+        const hits = await search(q.text, { type: q.filters.type, as_of, entity: q.filters.entity }, k, { db, embed, weights });
+        const rankedAtomIds = hits
+            .map(h => memToAtom.get(h.id))
+            .filter((id) => id !== undefined);
+        perQuery.push({
+            id: q.id, mode: q.mode, skipped: null,
+            recall: recallAtK(rankedAtomIds, q.graded_relevant, k),
+            ndcg: ndcgAtK(rankedAtomIds, q.graded_relevant, k),
+            rankedAtomIds,
+        });
+    }
+    const evaluated = perQuery.filter(r => r.skipped === null);
+    const mean = (xs) => xs.length === 0 ? 0 : xs.reduce((a, b) => a + b, 0) / xs.length;
+    return {
+        k,
+        perQuery,
+        evaluated: evaluated.length,
+        skipped: perQuery.length - evaluated.length,
+        meanRecall: mean(evaluated.map(r => r.recall)),
+        meanNdcg: mean(evaluated.map(r => r.ndcg)),
+    };
+}
+//# sourceMappingURL=harness.js.map

package/dist/eval/harness.js.map

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

package/dist/eval/metrics.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Retrieval quality metrics — ADR-005 eval harness.
+ *
+ * Both metrics operate on a ranked list of atom ids (engine output order)
+ * against a graded relevance list (0 = not relevant .. 3 = highly relevant).
+ */
+export interface GradedRelevance {
+    atom_id: string;
+    grade: number;
+}
+/**
+ * recall@k — fraction of relevant atoms (grade > 0) that appear in the
+ * top-k ranked list. Returns 1 when the query has no relevant atoms
+ * (nothing to miss).
+ */
+export declare function recallAtK(ranked: string[], graded: GradedRelevance[], k: number): number;
+/**
+ * NDCG@k with exponential gain (2^grade - 1) and log2(rank+1) discount.
+ * Ideal DCG is computed from the graded list sorted descending, so a
+ * grade-0 entry contributes nothing to either side. Returns 1 when the
+ * query has no relevant atoms.
+ */
+export declare function ndcgAtK(ranked: string[], graded: GradedRelevance[], k: number): number;

package/dist/eval/metrics.js

@@ -0,0 +1,44 @@
+/**
+ * Retrieval quality metrics — ADR-005 eval harness.
+ *
+ * Both metrics operate on a ranked list of atom ids (engine output order)
+ * against a graded relevance list (0 = not relevant .. 3 = highly relevant).
+ */
+/**
+ * recall@k — fraction of relevant atoms (grade > 0) that appear in the
+ * top-k ranked list. Returns 1 when the query has no relevant atoms
+ * (nothing to miss).
+ */
+export function recallAtK(ranked, graded, k) {
+    const relevant = new Set(graded.filter(g => g.grade > 0).map(g => g.atom_id));
+    if (relevant.size === 0)
+        return 1;
+    const topK = ranked.slice(0, k);
+    let found = 0;
+    for (const id of topK) {
+        if (relevant.has(id))
+            found++;
+    }
+    return found / relevant.size;
+}
+/**
+ * NDCG@k with exponential gain (2^grade - 1) and log2(rank+1) discount.
+ * Ideal DCG is computed from the graded list sorted descending, so a
+ * grade-0 entry contributes nothing to either side. Returns 1 when the
+ * query has no relevant atoms.
+ */
+export function ndcgAtK(ranked, graded, k) {
+    const gradeMap = new Map(graded.map(g => [g.atom_id, g.grade]));
+    const gain = (grade) => Math.pow(2, grade) - 1;
+    let dcg = 0;
+    ranked.slice(0, k).forEach((id, i) => {
+        dcg += gain(gradeMap.get(id) ?? 0) / Math.log2(i + 2);
+    });
+    const idealGrades = graded.map(g => g.grade).sort((a, b) => b - a).slice(0, k);
+    let idcg = 0;
+    idealGrades.forEach((grade, i) => {
+        idcg += gain(grade) / Math.log2(i + 2);
+    });
+    return idcg === 0 ? 1 : dcg / idcg;
+}
+//# sourceMappingURL=metrics.js.map

package/dist/eval/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/eval/metrics.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,MAAgB,EAAE,MAAyB,EAAE,CAAS;IAC9E,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9E,IAAI,QAAQ,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAChC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC;QACtB,IAAI,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,KAAK,EAAE,CAAC;IAChC,CAAC;IACD,OAAO,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC;AAC/B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,MAAgB,EAAE,MAAyB,EAAE,CAAS;IAC5E,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAChE,MAAM,IAAI,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAE/D,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE;QACnC,GAAG,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;IAEH,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/E,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,WAAW,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;QAC/B,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IAEH,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC;AACrC,CAAC"}

package/dist/log/correlation.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Correlation ID — request_id propagation via AsyncLocalStorage.
+ *
+ * Usage:
+ *   - On each incoming HTTP request: call runWithRequestId(uuid, fn)
+ *   - Anywhere in the call stack: call getRequestId() to retrieve the current ID
+ *   - child loggers can bind it via logger.child({ request_id: getRequestId() })
+ */
+import { randomUUID } from 'node:crypto';
+export { randomUUID };
+/**
+ * Run fn inside a context that has request_id set.
+ * Callers that do not call this will see undefined from getRequestId().
+ */
+export declare function runWithRequestId<T>(requestId: string, fn: () => T): T;
+/**
+ * Retrieve the current request_id from the async context.
+ * Returns undefined when called outside a runWithRequestId scope.
+ */
+export declare function getRequestId(): string | undefined;
+/**
+ * Generate a new RFC 4122 v4 UUID suitable for use as a request_id.
+ */
+export declare function newRequestId(): string;

package/dist/log/correlation.js

@@ -0,0 +1,33 @@
+/**
+ * Correlation ID — request_id propagation via AsyncLocalStorage.
+ *
+ * Usage:
+ *   - On each incoming HTTP request: call runWithRequestId(uuid, fn)
+ *   - Anywhere in the call stack: call getRequestId() to retrieve the current ID
+ *   - child loggers can bind it via logger.child({ request_id: getRequestId() })
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+export { randomUUID };
+const storage = new AsyncLocalStorage();
+/**
+ * Run fn inside a context that has request_id set.
+ * Callers that do not call this will see undefined from getRequestId().
+ */
+export function runWithRequestId(requestId, fn) {
+    return storage.run(requestId, fn);
+}
+/**
+ * Retrieve the current request_id from the async context.
+ * Returns undefined when called outside a runWithRequestId scope.
+ */
+export function getRequestId() {
+    return storage.getStore();
+}
+/**
+ * Generate a new RFC 4122 v4 UUID suitable for use as a request_id.
+ */
+export function newRequestId() {
+    return randomUUID();
+}
+//# sourceMappingURL=correlation.js.map

package/dist/log/correlation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation.js","sourceRoot":"","sources":["../../src/log/correlation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAU,CAAC;AAEhD;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAI,SAAiB,EAAE,EAAW;IAChE,OAAO,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;AAC5B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,UAAU,EAAE,CAAC;AACtB,CAAC"}

package/dist/log/logger.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Structured pino logger for AstraMemory Local.
+ *
+ * - Default level: info. Override with LOG_LEVEL env.
+ * - JSON emit (service mode). pino-pretty auto-activated when LOG_PRETTY=1 and
+ *   pino-pretty is installed (optional dev dep).
+ * - Secret scrubber applied via pino's built-in redact OR serializer fallback.
+ *
+ * Usage:
+ *   import { logger, childLogger } from '../log/logger.js';
+ *
+ *   // root logger — use in top-level server code
+ *   logger.info({ event: 'server.start', port: 7777 }, 'daemon started');
+ *
+ *   // child logger — bind fields for a request / job / stage
+ *   const log = childLogger({ request_id, session_id });
+ *   log.info({ status: 200, duration_ms: 12 }, 'request complete');
+ */
+import pino from 'pino';
+/**
+ * Root logger instance. Long-lived singleton shared across the process.
+ */
+export declare const logger: pino.Logger;
+/**
+ * Create a child logger with bound fields.
+ * All subsequent log calls on the child will include those fields.
+ *
+ * Common patterns:
+ *   childLogger({ request_id, method, path })          // HTTP layer
+ *   childLogger({ request_id, session_id, transcript_id })  // ingest route
+ *   childLogger({ job_id, job_kind, attempt })          // worker
+ *   childLogger({ job_id, stage })                      // distill stage
+ *   childLogger({ provider, model })                    // LLM/embed provider
+ *
+ * Sensitive fields in bindings are filtered by isSensitiveKey.
+ */
+export declare function childLogger(bindings: Record<string, unknown>): pino.Logger;
+export type { pino };

package/dist/log/logger.js

@@ -0,0 +1,129 @@
+/**
+ * Structured pino logger for AstraMemory Local.
+ *
+ * - Default level: info. Override with LOG_LEVEL env.
+ * - JSON emit (service mode). pino-pretty auto-activated when LOG_PRETTY=1 and
+ *   pino-pretty is installed (optional dev dep).
+ * - Secret scrubber applied via pino's built-in redact OR serializer fallback.
+ *
+ * Usage:
+ *   import { logger, childLogger } from '../log/logger.js';
+ *
+ *   // root logger — use in top-level server code
+ *   logger.info({ event: 'server.start', port: 7777 }, 'daemon started');
+ *
+ *   // child logger — bind fields for a request / job / stage
+ *   const log = childLogger({ request_id, session_id });
+ *   log.info({ status: 200, duration_ms: 12 }, 'request complete');
+ */
+import pino from 'pino';
+import { isSensitiveKey } from './scrub.js';
+const level = process.env['LOG_LEVEL'] ?? 'info';
+/**
+ * Pino redactPaths — catches known sensitive field names at top-level and
+ * nested under 'req', 'res', 'headers', 'body'. Supplements scrubObj for
+ * log-line objects we control.
+ */
+const redactPaths = [
+    'authorization',
+    'api_key',
+    'apiKey',
+    'token',
+    'bearer',
+    'password',
+    'secret',
+    'MEMORY_BEARER',
+    'azure_api_key',
+    // Nested in HTTP context objects
+    'req.headers.authorization',
+    'headers.authorization',
+    'headers.api-key',
+    'headers["api-key"]',
+];
+/**
+ * Custom serializer for Error objects: captures message + kind, no stack-with-payload.
+ * Stack is emitted only at debug level by the caller if needed.
+ */
+function serializeError(err) {
+    if (err instanceof Error) {
+        return {
+            error_message: err.message,
+            error_kind: err.name ?? 'Error',
+        };
+    }
+    return { error_message: String(err), error_kind: 'Unknown' };
+}
+let transport;
+// Service mode (ASTRA_LOG_DIR set by the shim launcher): rotate JSON logs to
+// <ASTRA_LOG_DIR>/daemon.log, 10MB per file, 5 files retained. Without this,
+// a scheduler-supervised daemon's stdout either vanishes or grows unbounded
+// under redirection. Foreground runs keep stdout.
+const logDir = process.env['ASTRA_LOG_DIR'];
+if (logDir) {
+    transport = {
+        target: 'pino-roll',
+        options: {
+            file: `${logDir.replace(/[\\/]+$/, '')}/daemon.log`,
+            size: '10m',
+            limit: { count: 5 },
+            mkdir: true,
+        },
+    };
+}
+else if (process.env['LOG_PRETTY'] === '1') {
+    // pino-pretty transport: activated via LOG_PRETTY=1 (foreground dev mode).
+    try {
+        transport = {
+            target: 'pino-pretty',
+            options: {
+                colorize: true,
+                translateTime: 'SYS:standard',
+                ignore: 'pid,hostname',
+            },
+        };
+    }
+    catch {
+        // pino-pretty not installed — fall back to JSON
+    }
+}
+const pinoOpts = {
+    level,
+    redact: {
+        paths: redactPaths,
+        censor: '[REDACTED]',
+    },
+    serializers: {
+        err: serializeError,
+        error: serializeError,
+    },
+};
+/**
+ * Root logger instance. Long-lived singleton shared across the process.
+ */
+export const logger = transport
+    ? pino(pinoOpts, pino.transport(transport))
+    : pino(pinoOpts);
+/**
+ * Create a child logger with bound fields.
+ * All subsequent log calls on the child will include those fields.
+ *
+ * Common patterns:
+ *   childLogger({ request_id, method, path })          // HTTP layer
+ *   childLogger({ request_id, session_id, transcript_id })  // ingest route
+ *   childLogger({ job_id, job_kind, attempt })          // worker
+ *   childLogger({ job_id, stage })                      // distill stage
+ *   childLogger({ provider, model })                    // LLM/embed provider
+ *
+ * Sensitive fields in bindings are filtered by isSensitiveKey.
+ */
+export function childLogger(bindings) {
+    // Strip any accidentally-passed sensitive keys from bound fields
+    const safe = {};
+    for (const [key, val] of Object.entries(bindings)) {
+        if (!isSensitiveKey(key)) {
+            safe[key] = val;
+        }
+    }
+    return logger.child(safe);
+}
+//# sourceMappingURL=logger.js.map