@massa-ai/core 1.2.1

package/dist/services/hooks/co-retrieval-hook.js

@@ -0,0 +1,145 @@
+/**
+ * CoRetrievalHook — Hebbian co-retrieval reinforcement
+ *
+ * When two session memories are stored in the same search session, they
+ * co-occur semantically. This hook creates or strengthens a RELATES_TO
+ * edge between them in the GraphStore, making those memories surface
+ * together in future neighborhood queries (optimized_context).
+ *
+ * Architecture decisions vs. the original spec:
+ *  - Uses GraphStore (PostgreSQL) not Prisma — edges already live there.
+ *  - Uses MemoryRelationType.RELATES_TO — no new edge type/migration.
+ *  - Weights in [0, 1] — consistent with GraphStore design.
+ *  - Only the "retrieved" signal — richer signals (used_in_answer,
+ *    task_succeeded) have no emitter in the current system.
+ *  - No decay job — out of scope for MVP; edges are bounded by the
+ *    saturation cap instead.
+ *  - Opt-in via MASSA_AI_CO_RETRIEVAL_HOOK=true — safe rollout.
+ *
+ * Timing:
+ *  SearchSessionHook stores Memory(B), then emits "memory:session-stored".
+ *  At that point Memory(B) is already in the DB. This hook receives the
+ *  event, queries recent session memories → finds Memory(A), links A↔B.
+ */
+import { logger, MemoryRelationType } from "@massa-ai/shared";
+import { eventBus } from "../events/event-bus.js";
+import { getGraphStore } from "../graph/graph-store-factory.js";
+import { getMemoryRepository } from "../../data/memory/memory-repository-factory.js";
+const INITIAL_WEIGHT = 0.15;
+const DELTA = 0.1;
+const MAX_WEIGHT = 0.85;
+const SESSION_WINDOW_MS = 10 * 60 * 1000; // 10-minute co-session window
+const MAX_PEERS = 5; // limit combinatorial pairs
+const AUTO_SEARCH_TAG = "auto:search-session";
+export class CoRetrievalHook {
+    static instance = null;
+    unsubscribe = null;
+    graphStore;
+    constructor(graphStore) {
+        // Route through the factory so the PG store is used when DATABASE_URL
+        // points at PostgreSQL (structural gap #14). The factory returns an
+        // IGraphStore, which satisfies IGraphStoreEdges structurally.
+        this.graphStore = graphStore ?? getGraphStore();
+    }
+    static getInstance() {
+        if (!CoRetrievalHook.instance) {
+            CoRetrievalHook.instance = new CoRetrievalHook();
+        }
+        return CoRetrievalHook.instance;
+    }
+    /** Create an isolated instance with injected dependencies — for testing only. */
+    static createForTest(graphStore, repo) {
+        const hook = new CoRetrievalHook(graphStore);
+        if (repo)
+            hook._testRepo = repo;
+        return hook;
+    }
+    /** Register the hook. Safe to call multiple times — only registers once. */
+    register() {
+        if (this.unsubscribe)
+            return;
+        this.unsubscribe = eventBus.subscribe("memory:session-stored", (payload) => {
+            void this.handleMemoryStored(payload);
+        });
+        logger.debug("CoRetrievalHook registered");
+    }
+    /** Unregister the hook (useful in tests). */
+    unregisterHook() {
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+        logger.debug("CoRetrievalHook unregistered");
+    }
+    /** Reset singleton (test utility). */
+    static reset() {
+        CoRetrievalHook.instance?.unregisterHook();
+        CoRetrievalHook.instance = null;
+    }
+    async handleMemoryStored(payload) {
+        // Feature flag — opt-in only; any value other than "true" keeps it off
+        if (process.env.MASSA_AI_CO_RETRIEVAL_HOOK !== "true")
+            return;
+        const { memoryId, projectId, sessionId } = payload;
+        let peers;
+        try {
+            peers = await this.findPeers(memoryId, projectId, sessionId);
+        }
+        catch (err) {
+            logger.warn("CoRetrievalHook: peer lookup failed", {
+                error: err.message,
+                memoryId,
+            });
+            return;
+        }
+        if (peers.length === 0)
+            return;
+        let created = 0;
+        let reinforced = 0;
+        for (const peer of peers.slice(0, MAX_PEERS)) {
+            // Deterministic pair ordering prevents duplicate edges (A↔B == B↔A)
+            const [from, to] = [memoryId, peer.id].sort();
+            const existing = await this.graphStore.getEdge(from, to, MemoryRelationType.RELATES_TO);
+            if (existing) {
+                const ok = await this.graphStore.incrementEdgeWeight(from, to, MemoryRelationType.RELATES_TO, DELTA, MAX_WEIGHT);
+                if (ok)
+                    reinforced++;
+            }
+            else {
+                const edge = await this.graphStore.createEdge({
+                    sourceId: from,
+                    targetId: to,
+                    relationType: MemoryRelationType.RELATES_TO,
+                    weight: INITIAL_WEIGHT,
+                    evidence: "co-retrieved in session",
+                    autoExtracted: true,
+                });
+                if (edge)
+                    created++;
+            }
+        }
+        if (created > 0 || reinforced > 0) {
+            logger.debug("CoRetrievalHook: edges updated", {
+                memoryId,
+                created,
+                reinforced,
+                peers: peers.length,
+            });
+        }
+    }
+    async findPeers(memoryId, projectId, sessionId) {
+        // Allow test injection via createForTest
+        const repo = this._testRepo ?? getMemoryRepository();
+        // The method is only available on the Pg implementation.
+        // If running against PostgreSQL repo in tests, skip gracefully.
+        if (typeof repo.findRecentByTag !== "function")
+            return [];
+        return repo.findRecentByTag(AUTO_SEARCH_TAG, {
+            sessionId,
+            projectId,
+            excludeId: memoryId,
+            sinceMs: Date.now() - SESSION_WINDOW_MS,
+            limit: MAX_PEERS,
+        });
+    }
+}
+export const coRetrievalHook = CoRetrievalHook.getInstance();
+//# sourceMappingURL=co-retrieval-hook.js.map

package/dist/services/hooks/co-retrieval-hook.js.map

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

package/dist/services/hooks/compaction-snapshot-service.d.ts

@@ -0,0 +1,81 @@
+/**
+ * CompactionSnapshotService — builds a reference-based compaction snapshot.
+ *
+ * Ported fresh (NOT copied) from context-mode's snapshot.ts approach.
+ *
+ * This preserves SESSION continuity (what happened in the conversation), NOT
+ * index/task state. It is the complement of `CheckpointManager`
+ * (packages/core/src/services/checkpoint/checkpoint-manager.ts), which versions
+ * TASK execution state (progress, decisions, files) in PostgreSQL memories table. See
+ * `packages/core/src/services/SESSION-STATE.md` for the full reconciliation.
+ *
+ * Design contract:
+ *  - The snapshot is a TABLE OF CONTENTS, not inlined data. Each section
+ *    contains a brief summary + a runnable search/recall/read_file call that
+ *    re-fetches the full raw events from the observation store on demand.
+ *  - Zero truncation, zero information loss: raw events stay in the store; the
+ *    snapshot just points to them by id + provides the exact retrieval call.
+ *  - Bounded size (<~2KB): structural limits per section (last-N items, dedup,
+ *    short summaries), not a byte budget that drops data.
+ *  - XML format (portable, LLM-friendly, matches context-mode convention).
+ *
+ * The snapshot is emitted on /compact (or PreCompact hook) so the resuming
+ * agent can reconstruct session continuity without re-reading truncated inline
+ * payloads — it follows the references to fetch full detail on demand.
+ */
+import { type ObservationStore, type ObservationCategory } from "../../data/memory/observation-repository.js";
+export interface SnapshotSection {
+    category: ObservationCategory;
+    label: string;
+    count: number;
+    /** Brief summary line(s) — NOT the raw data. */
+    summary: string;
+    /** Runnable retrieval call to re-fetch the full raw events. */
+    retrievalCall: string;
+    /** Observation ids referenced by this section (for round-trip verification). */
+    observationIds: string[];
+}
+export interface CompactionSnapshot {
+    sessionId: string;
+    projectId: string;
+    eventCount: number;
+    compactCount: number;
+    generatedAt: string;
+    sections: SnapshotSection[];
+    /** The serialized XML payload (bounded <~2KB). */
+    xml: string;
+    /** Byte size of the XML payload (for the bounded-size contract). */
+    bytes: number;
+}
+export interface SnapshotBuildOptions {
+    sessionId: string;
+    projectId: string;
+    compactCount?: number;
+    /** Max observations to scan per session (default 200 — plenty for a session). */
+    maxEvents?: number;
+    /** Max items to summarize per section (default 5 — keeps the TOC bounded). */
+    maxItemsPerSection?: number;
+    /** Max summary line length in chars (default 120). */
+    maxSummaryLineLength?: number;
+}
+export declare class CompactionSnapshotService {
+    private store;
+    constructor(store: ObservationStore);
+    /**
+     * Build a bounded, reference-based compaction snapshot for a session.
+     *
+     * The snapshot is a table-of-contents: each section summarizes a category
+     * of observations and provides a runnable retrieval call to re-fetch the
+     * full raw events. Zero inlined data, zero information loss.
+     */
+    build(options: SnapshotBuildOptions): CompactionSnapshot;
+    /**
+     * Serialize sections to a bounded XML string.
+     * Format matches context-mode's session_resume XML convention.
+     */
+    private serializeXml;
+}
+export declare function getCompactionSnapshotService(store?: ObservationStore): CompactionSnapshotService;
+/** Test hook: reset the cached service. */
+export declare function resetCompactionSnapshotService(): void;
+//# sourceMappingURL=compaction-snapshot-service.d.ts.map

package/dist/services/hooks/compaction-snapshot-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction-snapshot-service.d.ts","sourceRoot":"","sources":["../../../src/services/hooks/compaction-snapshot-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAEL,KAAK,gBAAgB,EAErB,KAAK,mBAAmB,EACzB,MAAM,6CAA6C,CAAC;AAKrD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,sDAAsD;IACtD,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAiLD,qBAAa,yBAAyB;IACxB,OAAO,CAAC,KAAK;gBAAL,KAAK,EAAE,gBAAgB;IAE3C;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,EAAE,oBAAoB,GAAG,kBAAkB;IAoFxD;;;OAGG;IACH,OAAO,CAAC,YAAY;CA0BrB;AAeD,wBAAgB,4BAA4B,CAAC,KAAK,CAAC,EAAE,gBAAgB,GAAG,yBAAyB,CAKhG;AAED,2CAA2C;AAC3C,wBAAgB,8BAA8B,IAAI,IAAI,CAErD"}

package/dist/services/hooks/compaction-snapshot-service.js

@@ -0,0 +1,308 @@
+/**
+ * CompactionSnapshotService — builds a reference-based compaction snapshot.
+ *
+ * Ported fresh (NOT copied) from context-mode's snapshot.ts approach.
+ *
+ * This preserves SESSION continuity (what happened in the conversation), NOT
+ * index/task state. It is the complement of `CheckpointManager`
+ * (packages/core/src/services/checkpoint/checkpoint-manager.ts), which versions
+ * TASK execution state (progress, decisions, files) in PostgreSQL memories table. See
+ * `packages/core/src/services/SESSION-STATE.md` for the full reconciliation.
+ *
+ * Design contract:
+ *  - The snapshot is a TABLE OF CONTENTS, not inlined data. Each section
+ *    contains a brief summary + a runnable search/recall/read_file call that
+ *    re-fetches the full raw events from the observation store on demand.
+ *  - Zero truncation, zero information loss: raw events stay in the store; the
+ *    snapshot just points to them by id + provides the exact retrieval call.
+ *  - Bounded size (<~2KB): structural limits per section (last-N items, dedup,
+ *    short summaries), not a byte budget that drops data.
+ *  - XML format (portable, LLM-friendly, matches context-mode convention).
+ *
+ * The snapshot is emitted on /compact (or PreCompact hook) so the resuming
+ * agent can reconstruct session continuity without re-reading truncated inline
+ * payloads — it follows the references to fetch full detail on demand.
+ */
+import { getObservationStore, } from "../../data/memory/observation-repository.js";
+import { CATEGORY_LABELS } from "./observation-extractor.js";
+// ── Constants (structural size bounds) ──────────────────────────────────────
+const DEFAULT_MAX_EVENTS = 200;
+const DEFAULT_MAX_ITEMS_PER_SECTION = 5;
+const DEFAULT_MAX_SUMMARY_LINE = 120;
+/** Hard ceiling on the serialized XML. If exceeded, sections are trimmed. */
+const MAX_XML_BYTES = 2048;
+// ── Helpers ─────────────────────────────────────────────────────────────────
+/**
+ * Truncate a string to `max` Unicode codepoints (codepoint-safe, like
+ * context-mode's truncateForSnapshot).
+ */
+function truncate(value, max) {
+    if (!value)
+        return "";
+    const chars = [...value];
+    if (chars.length <= max)
+        return value;
+    return chars.slice(0, max).join("") + "…";
+}
+/**
+ * Build a short summary token from an observation's payload, suitable for
+ * inclusion in the TOC. Extracts the most relevant single field per category.
+ */
+function summarizeObservation(obs, maxLen) {
+    let payload;
+    try {
+        payload = JSON.parse(obs.payloadJson);
+    }
+    catch {
+        return truncate(`[${obs.id}]`, maxLen);
+    }
+    const cat = obs.category ?? "lifecycle-raw";
+    let token = "";
+    switch (cat) {
+        case "files-read":
+        case "files-written": {
+            const toolInput = payload.tool_input;
+            const fp = payload.file_path ?? payload.path ??
+                (toolInput && typeof toolInput === "object"
+                    ? toolInput.file_path
+                    : undefined) ??
+                payload.filePath;
+            token = str(fp) || JSON.stringify(payload).slice(0, 60);
+            break;
+        }
+        case "git-changes": {
+            const toolInput = payload.tool_input;
+            const cmd = payload.command ??
+                (toolInput && typeof toolInput === "object"
+                    ? toolInput.command
+                    : undefined);
+            token = str(cmd).split(" ").slice(0, 4).join(" ") || "git op";
+            break;
+        }
+        case "user-prompts":
+        case "goal":
+        case "intent":
+        case "decisions":
+        case "constraints":
+        case "rejected-approaches": {
+            const msg = payload.prompt ?? payload.message ?? payload.text;
+            token = str(msg);
+            break;
+        }
+        case "errors": {
+            const toolResponse = payload.tool_response;
+            const err = payload.error ??
+                (toolResponse && typeof toolResponse === "object"
+                    ? toolResponse.error
+                    : undefined) ??
+                payload.stderr;
+            token = str(err) || "error";
+            break;
+        }
+        case "tasks": {
+            const tasks = payload.todos ?? payload.tasks;
+            if (Array.isArray(tasks)) {
+                token = `${tasks.length} task(s)`;
+            }
+            else {
+                token = str(payload.content) || "task update";
+            }
+            break;
+        }
+        case "rules": {
+            const fp = payload.file_path ?? payload.path;
+            token = str(fp) || "rule";
+            break;
+        }
+        case "searches": {
+            const toolInput = payload.tool_input;
+            const q = payload.query ?? payload.queries ??
+                (toolInput && typeof toolInput === "object"
+                    ? toolInput.query
+                    : undefined);
+            token = Array.isArray(q) ? q.join(", ") : str(q) || "search";
+            break;
+        }
+        case "memories-stored": {
+            const content = payload.content;
+            token = (typeof content === "string" ? content.slice(0, 60) : "") || str(payload.type) || "memory";
+            break;
+        }
+        case "subagents-spawned": {
+            token = str(payload.subagent_type) || str(payload.description) || "subagent";
+            break;
+        }
+        case "compaction-snapshots": {
+            const cc = payload.compactCount ?? payload.compact_count;
+            token = `compact #${typeof cc === "number" ? cc : "?"}`;
+            break;
+        }
+        default: {
+            // Generic: try common fields, then fallback to id.
+            token =
+                str(payload.tool_name) ||
+                    str(payload.event) ||
+                    str(payload.description) ||
+                    `[${obs.id}]`;
+        }
+    }
+    return truncate(token, maxLen);
+}
+function str(val) {
+    return typeof val === "string" ? val : "";
+}
+/**
+ * Build the runnable retrieval call for a section. This is the key mechanism:
+ * instead of inlining data, we provide the exact MCP tool call to re-fetch it.
+ *
+ * We use `recall` (semantic memory search) as the primary retrieval tool since
+ * observations are consolidated into memories, plus a fallback `search` call
+ * for code-scoped events. The query is derived from the section's category +
+ * the session id.
+ */
+function buildRetrievalCall(category, sessionId, _projectId, summaryTokens) {
+    // Build a query from the category label + up to 3 summary tokens (deduped,
+    // short) so the retrieval call is specific enough to find the right events.
+    const queries = [CATEGORY_LABELS[category]];
+    const seen = new Set();
+    for (const token of summaryTokens) {
+        const short = token.slice(0, 60).trim();
+        if (short && !seen.has(short.toLowerCase()) && queries.length < 4) {
+            seen.add(short.toLowerCase());
+            queries.push(short);
+        }
+    }
+    // The retrieval call references the session so the resuming agent can scope
+    // its search. We provide BOTH a recall call (semantic) and a search call
+    // (keyword) so the agent has options depending on what's available.
+    const queryArr = queries.map((q) => `"${q.replace(/"/g, '\\"')}"`).join(", ");
+    return `recall(query: ${queries[0] ? `"${queries[0].replace(/"/g, '\\"')}"` : '""'}, projectId: "${_projectId}", limit: 10)
+  // or: search(query: ${queries[0] ? `"${queries[0].replace(/"/g, '\\"')}"` : '""'}, projectId: "${_projectId}", maxResults: 5)
+  // queries: [${queryArr}]
+  // sessionId: "${sessionId}"`;
+}
+// ── Service ─────────────────────────────────────────────────────────────────
+export class CompactionSnapshotService {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    /**
+     * Build a bounded, reference-based compaction snapshot for a session.
+     *
+     * The snapshot is a table-of-contents: each section summarizes a category
+     * of observations and provides a runnable retrieval call to re-fetch the
+     * full raw events. Zero inlined data, zero information loss.
+     */
+    build(options) {
+        const { sessionId, projectId, compactCount = 0, maxEvents = DEFAULT_MAX_EVENTS, maxItemsPerSection = DEFAULT_MAX_ITEMS_PER_SECTION, maxSummaryLineLength = DEFAULT_MAX_SUMMARY_LINE, } = options;
+        // Fetch the session's observations (newest-first).
+        const observations = this.store.listBySession(sessionId, maxEvents);
+        // Group by category.
+        const byCategory = new Map();
+        for (const obs of observations) {
+            const cat = obs.category ?? "lifecycle-raw";
+            const arr = byCategory.get(cat) ?? [];
+            arr.push(obs);
+            byCategory.set(cat, arr);
+        }
+        // Build sections (ordered by observation count descending — most active first).
+        const sections = [];
+        for (const [category, obsList] of byCategory) {
+            // Take the most recent N observations for the summary.
+            const recent = obsList.slice(0, maxItemsPerSection);
+            const summaryTokens = recent.map((o) => summarizeObservation(o, maxSummaryLineLength));
+            const label = CATEGORY_LABELS[category] ?? category;
+            const count = obsList.length;
+            // Build a compact summary: "N items" + up to maxItemsPerSection short tokens.
+            const summaryLines = [`${count} event(s)`];
+            for (const token of summaryTokens) {
+                if (token)
+                    summaryLines.push(`  - ${truncate(token, maxSummaryLineLength)}`);
+            }
+            sections.push({
+                category,
+                label,
+                count,
+                summary: summaryLines.join("\n"),
+                retrievalCall: buildRetrievalCall(category, sessionId, projectId, summaryTokens),
+                observationIds: recent.map((o) => o.id),
+            });
+        }
+        // Sort sections by count descending (most active categories first).
+        sections.sort((a, b) => b.count - a.count);
+        // Serialize to XML.
+        let xml = this.serializeXml(sections, {
+            sessionId,
+            projectId,
+            eventCount: observations.length,
+            compactCount,
+        });
+        // Enforce the hard byte ceiling: trim sections from the bottom (least active)
+        // until under the limit. This never drops the raw data — it just omits a TOC
+        // entry; the events are still in the store and retrievable.
+        let trimmedSections = sections;
+        while (xml.length > MAX_XML_BYTES && trimmedSections.length > 1) {
+            trimmedSections = trimmedSections.slice(0, -1);
+            xml = this.serializeXml(trimmedSections, {
+                sessionId,
+                projectId,
+                eventCount: observations.length,
+                compactCount,
+            });
+        }
+        return {
+            sessionId,
+            projectId,
+            eventCount: observations.length,
+            compactCount,
+            generatedAt: new Date().toISOString(),
+            sections: trimmedSections,
+            xml,
+            bytes: Buffer.byteLength(xml, "utf8"),
+        };
+    }
+    /**
+     * Serialize sections to a bounded XML string.
+     * Format matches context-mode's session_resume XML convention.
+     */
+    serializeXml(sections, meta) {
+        const lines = [];
+        lines.push(`<session_resume events="${meta.eventCount}" compact_count="${meta.compactCount}" generated_at="${new Date().toISOString()}" session_id="${meta.sessionId}" project_id="${meta.projectId}">`);
+        lines.push(`  <how_to_search>This is a TABLE OF CONTENTS. Each section has a runnable recall/search call to re-fetch full event detail. Do NOT invent queries — use the ones provided. Raw events stay in the observation store; this snapshot only points to them.</how_to_search>`);
+        for (const section of sections) {
+            lines.push(`  <${section.category} count="${section.count}">`);
+            // Summary lines (indented).
+            for (const line of section.summary.split("\n")) {
+                lines.push(`    ${escapeXml(line)}`);
+            }
+            lines.push(`    For full details:`);
+            lines.push(`    ${escapeXml(section.retrievalCall)}`);
+            lines.push(`  </${section.category}>`);
+        }
+        lines.push(`</session_resume>`);
+        return lines.join("\n");
+    }
+}
+function escapeXml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+// ── Factory ─────────────────────────────────────────────────────────────────
+let cachedService = null;
+export function getCompactionSnapshotService(store) {
+    if (cachedService && !store)
+        return cachedService;
+    const resolvedStore = store ?? getObservationStore();
+    cachedService = new CompactionSnapshotService(resolvedStore);
+    return cachedService;
+}
+/** Test hook: reset the cached service. */
+export function resetCompactionSnapshotService() {
+    cachedService = null;
+}
+//# sourceMappingURL=compaction-snapshot-service.js.map

package/dist/services/hooks/compaction-snapshot-service.js.map

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

package/dist/services/hooks/hook-service.d.ts

@@ -0,0 +1,100 @@
+/**
+ * HookService — passive lifecycle-event ingestion (Phase 3, G1).
+ *
+ * Accepts six lifecycle event kinds, validates/normalizes them, persists each
+ * as an Observation via the single-writer WriterQueue, emits
+ * `observation:ingested`, and (debounce) triggers the consolidation bridge.
+ *
+ * Contract (spec.md):
+ *  - Fire-and-forget: a validated+admitted event returns 202 with its id; the
+ *    actual persist runs on the writer turn.
+ *  - 429 on saturation: when `WriterQueue.saturated`, `ingestOne`/`ingestBatch`
+ *    throw QueueSaturatedError and the route maps to HTTP 429 (no admission).
+ *  - 400/413 on validation failure (before admission).
+ *  - LLM-free: ingestion has no LLM dependency; the bridge is the only
+ *    LLM-touching stage and it silent-degrades.
+ */
+import { type LifecycleEventKind, type ObservationStore } from "../../data/memory/observation-repository.js";
+import { WriterQueue } from "./writer-queue.js";
+import { type AttributionResolverLike } from "./attribution-resolver.js";
+/** Incoming wire shape (before normalization). `event` validated case-insensitively. */
+export interface IncomingEvent {
+    event: string;
+    projectId: string;
+    sessionId?: string;
+    payload: Record<string, unknown>;
+    importance?: number;
+    agentId?: string;
+    ts?: number;
+}
+/** Normalized event ready to persist. */
+export interface NormalizedEvent {
+    event: LifecycleEventKind;
+    projectId: string;
+    sessionId: string | null;
+    payload: Record<string, unknown>;
+    importance: number;
+    agentId: string | null;
+    ts: number;
+}
+export type ValidationResult = {
+    ok: true;
+    event: NormalizedEvent;
+} | {
+    ok: false;
+    code: 400 | 413;
+    error: string;
+};
+/** Bridge seam — implemented by ObservationConsolidationJob. Injected for tests. */
+export interface BridgeTrigger {
+    maybeRun(projectId: string): void;
+}
+/**
+ * Validate + normalize a single incoming event. Pure (no IO). Returns a
+ * discriminated union; `{ok:false}` carries the HTTP-ish code.
+ */
+export declare function validateEvent(raw: IncomingEvent, maxPayloadBytes: number): ValidationResult;
+export interface HookServiceOptions {
+    store?: ObservationStore;
+    maxPending?: number;
+    maxPayloadBytes?: number;
+    bridge?: BridgeTrigger;
+    /** Override id factory (deterministic tests). */
+    idFactory?: () => string;
+    /** Override attribution resolver (deterministic tests). */
+    resolver?: AttributionResolverLike;
+}
+export declare class HookService {
+    readonly store: ObservationStore;
+    readonly queue: WriterQueue;
+    readonly bridge: BridgeTrigger;
+    readonly resolver: AttributionResolverLike;
+    private readonly maxPayloadBytes;
+    private readonly idFactory;
+    constructor(opts?: HookServiceOptions);
+    validate(raw: IncomingEvent): ValidationResult;
+    /**
+     * Validate, admit, and enqueue a single event. Resolves with the observation
+     * id (the persist itself runs on the writer turn — fire-and-forget from the
+     * caller's perspective, but the id is returned synchronously on admission).
+     *
+     * Throws QueueSaturatedError → route maps to 429.
+     */
+    ingestOne(raw: IncomingEvent): Promise<string>;
+    /**
+     * Validate the whole batch atomically, then admit all. Returns the array of
+     * ids in input order. Throws ValidationError (400/413) if ANY event is bad,
+     * before persisting anything; throws QueueSaturatedError if the queue cannot
+     * admit the full batch.
+     */
+    ingestBatch(raws: IncomingEvent[]): Promise<string[]>;
+    private ingestOneNormalized;
+}
+export declare class ValidationError extends Error {
+    readonly code: 400 | 413;
+    constructor(code: 400 | 413, message: string);
+}
+export declare function getHookService(): HookService;
+/** Test hook: reset the cached service (and the underlying observation store). */
+export declare function resetHookService(): void;
+//# sourceMappingURL=hook-service.d.ts.map