@massa-ai/core 1.2.1

package/dist/services/health/local-health-checker.js

@@ -0,0 +1,82 @@
+/** PostgreSQL/pgvector health checks used by local system status endpoints. */
+import { config } from "@massa-ai/shared";
+import { requirePostgresDatabaseUrl } from "@massa-ai/shared/config";
+import { getPgPool } from "../../data/db-connection.js";
+import fs from "fs/promises";
+import { existsSync } from "fs";
+import path from "path";
+import { getSearchDiagnostics, } from "../search/search-diagnostics.js";
+export class LocalHealthChecker {
+    ollamaBaseUrl = process.env.OLLAMA_BASE_URL || "http://localhost:11434";
+    dataDir = config.get("dataDir");
+    async checkAll() {
+        const [ollama, dataDirectory, database] = await Promise.all([this.checkOllama(), this.checkDataDirectory(), this.checkPostgres()]);
+        const services = { ollama, dataDirectory, vectorStore: database, keywordSearch: database, cache: database, embeddingCache: database };
+        const unique = [ollama, dataDirectory, database];
+        const healthy = unique.filter((status) => status.available).length;
+        const failed = unique.length - healthy;
+        const status = failed === 0 ? "healthy" : healthy > failed ? "degraded" : "unhealthy";
+        return { status, mode: "postgresql", timestamp: new Date().toISOString(), services, diagnostics: { search: getSearchDiagnostics() }, summary: { total: unique.length, healthy, degraded: 0, failed }, recommendations: this.generateRecommendations(services) };
+    }
+    async checkOllama() {
+        const start = Date.now();
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 3_000);
+            const response = await fetch(`${this.ollamaBaseUrl}/api/tags`, { signal: controller.signal });
+            clearTimeout(timeout);
+            if (!response.ok)
+                return { available: false, latency: Date.now() - start, error: `Ollama responded with HTTP ${response.status}` };
+            const models = (await response.json()).models || [];
+            const embeddingModel = process.env.OLLAMA_EMBEDDING_MODEL || config.getAll()?.embedding?.model || "nomic-embed-text:latest";
+            return { available: true, latency: Date.now() - start, details: { url: this.ollamaBaseUrl, modelsAvailable: models.length, models: models.map((model) => model.name), embeddingModel, hasEmbeddingModel: models.some((model) => model.name === embeddingModel || model.name.startsWith(embeddingModel.split(":")[0])) } };
+        }
+        catch (error) {
+            return { available: false, latency: Date.now() - start, error: `Ollama unreachable: ${error.message}` };
+        }
+    }
+    async checkDataDirectory() {
+        const start = Date.now();
+        try {
+            if (!existsSync(this.dataDir))
+                await fs.mkdir(this.dataDir, { recursive: true });
+            const probe = path.join(this.dataDir, ".health-check-test");
+            await fs.writeFile(probe, "ok");
+            await fs.unlink(probe);
+            return { available: true, latency: Date.now() - start, details: { path: this.dataDir, writable: true } };
+        }
+        catch (error) {
+            return { available: false, latency: Date.now() - start, error: `Data directory error: ${error.message}` };
+        }
+    }
+    async checkPostgres() {
+        const start = Date.now();
+        try {
+            const url = new URL(requirePostgresDatabaseUrl());
+            const pool = await getPgPool();
+            const result = await pool.query("SELECT EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'vector') AS extension_installed, pg_database_size(current_database())::text AS size_bytes");
+            const details = { backend: "postgres", database: decodeURIComponent(url.pathname.slice(1)), host: url.hostname, port: Number(url.port || 5432), sizeBytes: Number(result.rows[0]?.size_bytes || 0), pgvector: result.rows[0]?.extension_installed === true };
+            if (!details.pgvector)
+                return { available: false, latency: Date.now() - start, error: "pgvector extension is not installed", details };
+            return { available: true, latency: Date.now() - start, details };
+        }
+        catch (error) {
+            return { available: false, latency: Date.now() - start, error: `PostgreSQL health check failed: ${error.message}` };
+        }
+    }
+    async isOllamaReady() { return (await this.checkOllama()).available; }
+    async getOllamaModels() { const result = await this.checkOllama(); return result.details?.models || []; }
+    generateRecommendations(services) {
+        const recommendations = [];
+        if (!services.vectorStore.available)
+            recommendations.push("Configure a reachable PostgreSQL DATABASE_URL with pgvector, then deploy Prisma migrations.");
+        if (!services.ollama.available)
+            recommendations.push("Install and start Ollama, then pull the configured embedding model.");
+        if (!services.dataDirectory.available)
+            recommendations.push(`Create writable data directory: mkdir -p ${this.dataDir}`);
+        return recommendations.length ? recommendations : ["PostgreSQL, pgvector, Ollama, and local artifacts are healthy."];
+    }
+}
+let healthCheckerInstance = null;
+export function getHealthChecker() { return healthCheckerInstance ??= new LocalHealthChecker(); }
+//# sourceMappingURL=local-health-checker.js.map

package/dist/services/health/local-health-checker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-health-checker.js","sourceRoot":"","sources":["../../../src/services/health/local-health-checker.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,OAAO,EAAE,MAAM,EAAU,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACxD,OAAO,EAAE,MAAM,aAAa,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAChC,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EACL,oBAAoB,GAErB,MAAM,iCAAiC,CAAC;AAWzC,MAAM,OAAO,kBAAkB;IACZ,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,wBAAwB,CAAC;IACxE,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAW,CAAC;IAE3D,KAAK,CAAC,QAAQ;QACZ,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,IAAI,CAAC,kBAAkB,EAAE,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC;QACnI,MAAM,QAAQ,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,WAAW,EAAE,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAC;QACtI,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,CAAC,CAAC;QACjD,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC;QACnE,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,GAAG,OAAO,CAAC;QACvC,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC;QACtF,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,EAAE,MAAM,EAAE,oBAAoB,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,eAAe,EAAE,IAAI,CAAC,uBAAuB,CAAC,QAAQ,CAAC,EAAE,CAAC;IAClQ,CAAC;IAED,KAAK,CAAC,WAAW;QACf,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;YAAC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,KAAK,CAAC,CAAC;YACtG,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,aAAa,WAAW,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;YAAC,YAAY,CAAC,OAAO,CAAC,CAAC;YACrH,IAAI,CAAC,QAAQ,CAAC,EAAE;gBAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,8BAA8B,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;YACnI,MAAM,MAAM,GAAI,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAoC,CAAC,MAAM,IAAI,EAAE,CAAC;YACxF,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAK,MAAM,CAAC,MAAM,EAAU,EAAE,SAAS,EAAE,KAAK,IAAI,yBAAyB,CAAC;YACrI,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,aAAa,EAAE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,cAAc,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QAC5T,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAAC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,uBAAwB,KAAe,CAAC,OAAO,EAAE,EAAE,CAAC;QAAC,CAAC;IACzI,CAAC;IAED,KAAK,CAAC,kBAAkB;QACtB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC;gBAAE,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACjF,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC;YAAC,MAAM,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAAC,MAAM,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACrH,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAC;QAC3G,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAAC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,yBAA0B,KAAe,CAAC,OAAO,EAAE,EAAE,CAAC;QAAC,CAAC;IAC3I,CAAC;IAED,KAAK,CAAC,aAAa;QACjB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,0BAA0B,EAAE,CAAC,CAAC;YAClD,MAAM,IAAI,GAAG,MAAM,SAAS,EAAE,CAAC;YAC/B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAuD,sJAAsJ,CAAC,CAAC;YAC9O,MAAM,OAAO,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,IAAI,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,UAAU,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,mBAAmB,KAAK,IAAI,EAAE,CAAC;YAC7P,IAAI,CAAC,OAAO,CAAC,QAAQ;gBAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,qCAAqC,EAAE,OAAO,EAAE,CAAC;YACvI,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,CAAC;QACnE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAAC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,mCAAoC,KAAe,CAAC,OAAO,EAAE,EAAE,CAAC;QAAC,CAAC;IACrJ,CAAC;IAED,KAAK,CAAC,aAAa,KAAuB,OAAO,CAAC,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IACxF,KAAK,CAAC,eAAe,KAAwB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,OAAO,MAAM,CAAC,OAAO,EAAE,MAAkB,IAAI,EAAE,CAAC,CAAC,CAAC;IAChI,uBAAuB,CAAC,QAAuC;QACrE,MAAM,eAAe,GAAa,EAAE,CAAC;QACrC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,SAAS;YAAE,eAAe,CAAC,IAAI,CAAC,6FAA6F,CAAC,CAAC;QACzJ,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS;YAAE,eAAe,CAAC,IAAI,CAAC,qEAAqE,CAAC,CAAC;QAC5H,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,SAAS;YAAE,eAAe,CAAC,IAAI,CAAC,4CAA4C,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QACxH,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,gEAAgE,CAAC,CAAC;IACvH,CAAC;CACF;AACD,IAAI,qBAAqB,GAA8B,IAAI,CAAC;AAC5D,MAAM,UAAU,gBAAgB,KAAyB,OAAO,qBAAqB,KAAK,IAAI,kBAAkB,EAAE,CAAC,CAAC,CAAC"}

package/dist/services/hooks/attribution-resolver.d.ts

@@ -0,0 +1,113 @@
+/**
+ * attribution-resolver — application-layer hook attribution (M45/HAR-01..03,
+ * HAR-09). Resolves the durable project id for one hook event before enqueue,
+ * in strict order:
+ *
+ *  1. explicit    — caller id is a live workspace id, alias-resolves to one,
+ *                   or self-matches inside a path-sharing id set.
+ *  2. sticky      — session pin hit (first resolved id of the session wins
+ *                   for later events with unregistered caller ids).
+ *  3. containment — canonicalized payload cwd inside exactly one deduped,
+ *                   non-broad workspace root; longest path wins.
+ *  4. verbatim    — fail-open: caller id unchanged.
+ *
+ * Roots are DEDUPLICATED BY PATH (plan-critic C1): identical `project_path`
+ * values collapse to one candidate root carrying its live id set; a matched
+ * shared path resolves only via caller self-match, else it is ambiguous.
+ * Broad roots (filesystem root, user home) never participate in containment
+ * (HAR-03).
+ *
+ * Failure mode: FAIL-OPEN with a sanitized warn. Attribution failure NEVER
+ * rejects or delays an event beyond bounded lookups; any internal error
+ * degrades to `verbatim` (HAR-09). Never throws.
+ */
+import type { AttributionSource } from "../../data/memory/observation-contract.js";
+import { SessionPinStore } from "./session-pin-store.js";
+export interface WorkspaceRoot {
+    readonly projectId: string;
+    readonly projectPath: string;
+}
+/** Source of registered workspace roots. Injectable for DB-free tests. */
+export interface WorkspaceRootProvider {
+    listRoots(): Promise<WorkspaceRoot[]>;
+}
+export interface AttributionInput {
+    readonly callerProjectId: string;
+    readonly sessionId?: string | null;
+    readonly cwd?: string | null;
+}
+export interface AttributionResult {
+    readonly projectId: string;
+    readonly source: AttributionSource;
+}
+/** Minimal resolver surface for injection (HookService, CompactSnapshotTool, tests). */
+export interface AttributionResolverLike {
+    resolve(input: AttributionInput): Promise<AttributionResult>;
+    /**
+     * Record a winning resolution for future sticky hits. Callers MUST call this
+     * AFTER admission survives (never before a QueueSaturatedError check) so a
+     * rejected event leaves no pin behind.
+     */
+    pinSession(sessionId: string | null | undefined, projectId: string, source: AttributionSource): void;
+}
+/** Minimal alias-resolution surface (satisfied by ProjectIdentityAliasResolver). */
+export interface AttributionAliasResolver {
+    resolve(projectId: string): Promise<string>;
+}
+export interface AttributionResolverOptions {
+    readonly roots?: WorkspaceRootProvider;
+    readonly aliasResolver?: AttributionAliasResolver;
+    readonly pins?: SessionPinStore;
+    /** Injectable canonicalizer for tests. Return undefined when unresolvable. */
+    readonly canonicalize?: (cwd: string) => string | undefined;
+    /** Injectable home dir for tests (broad-root exclusion). */
+    readonly homedir?: () => string;
+    /** Injectable fs-root detector for tests (broad-root exclusion). */
+    readonly fsRoot?: () => string;
+}
+/**
+ * Cached workspaces reader. Mirrors the alias-resolver cache/timeout pattern:
+ * a sick-but-hanging DB must not stall hook admission; failures fail open to
+ * an EMPTY root list (containment/explicit simply never match) with a
+ * sanitized warn.
+ */
+export declare class PgWorkspaceRootProvider implements WorkspaceRootProvider {
+    private cache;
+    private readonly now;
+    constructor(options?: {
+        now?: () => number;
+    });
+    listRoots(): Promise<WorkspaceRoot[]>;
+    /** Test/maintenance escape hatch. */
+    clearCache(): void;
+}
+export declare class AttributionResolver implements AttributionResolverLike {
+    private readonly roots;
+    private readonly aliasResolver;
+    private readonly pins;
+    private readonly canonicalize;
+    private readonly homedir;
+    private readonly fsRoot;
+    constructor(options?: AttributionResolverOptions);
+    /**
+     * Resolve one event's durable project id. NEVER throws; any internal
+     * failure degrades to `{ projectId: caller, source: "verbatim" }`.
+     */
+    resolve(input: AttributionInput): Promise<AttributionResult>;
+    /**
+     * Record a winning resolution for future sticky hits. No-op for verbatim
+     * results (a fail-open outcome carries no signal worth pinning) and when no
+     * sessionId is present. Sticky hits refresh expiry via SessionPinStore.get.
+     */
+    pinSession(sessionId: string | null | undefined, projectId: string, source: AttributionSource): void;
+    private resolveContainment;
+    private isBroadRoot;
+    /** Strip trailing separators (except the fs root itself); empty stays empty. */
+    private normalizeRootPath;
+}
+export declare function getAttributionResolver(): AttributionResolver;
+/** @internal — reset the singleton (tests only). */
+export declare function resetAttributionResolver(): void;
+/** @internal — swap the singleton with a stubbed resolver (tests only). */
+export declare function setAttributionResolverForTests(resolver: AttributionResolverLike | null): void;
+//# sourceMappingURL=attribution-resolver.d.ts.map

package/dist/services/hooks/attribution-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution-resolver.d.ts","sourceRoot":"","sources":["../../../src/services/hooks/attribution-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAOH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2CAA2C,CAAC;AAKnF,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAIzD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,0EAA0E;AAC1E,MAAM,WAAW,qBAAqB;IACpC,SAAS,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACpC;AAED,wFAAwF;AACxF,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC7D;;;;OAIG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;CACtG;AAED,oFAAoF;AACpF,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,aAAa,CAAC,EAAE,wBAAwB,CAAC;IAClD,QAAQ,CAAC,IAAI,CAAC,EAAE,eAAe,CAAC;IAChC,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC5D,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;IAChC,oEAAoE;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CAChC;AAOD;;;;;GAKG;AACH,qBAAa,uBAAwB,YAAW,qBAAqB;IACnE,OAAO,CAAC,KAAK,CAA8D;IAC3E,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEvB,OAAO,GAAE;QAAE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;KAAO;IAI1C,SAAS,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IA4B3C,qCAAqC;IACrC,UAAU,IAAI,IAAI;CAGnB;AAID,qBAAa,mBAAoB,YAAW,uBAAuB;IACjE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwB;IAC9C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2B;IACzD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkB;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsC;IACnE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;gBAE1B,OAAO,GAAE,0BAA+B;IASpD;;;OAGG;IACG,OAAO,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAsClE;;;;OAIG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAMpG,OAAO,CAAC,kBAAkB;IAwC1B,OAAO,CAAC,WAAW;IAInB,gFAAgF;IAChF,OAAO,CAAC,iBAAiB;CAS1B;AAmBD,wBAAgB,sBAAsB,IAAI,mBAAmB,CAG5D;AAED,oDAAoD;AACpD,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAED,2EAA2E;AAC3E,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,uBAAuB,GAAG,IAAI,GACvC,IAAI,CAEN"}

package/dist/services/hooks/attribution-resolver.js

@@ -0,0 +1,227 @@
+/**
+ * attribution-resolver — application-layer hook attribution (M45/HAR-01..03,
+ * HAR-09). Resolves the durable project id for one hook event before enqueue,
+ * in strict order:
+ *
+ *  1. explicit    — caller id is a live workspace id, alias-resolves to one,
+ *                   or self-matches inside a path-sharing id set.
+ *  2. sticky      — session pin hit (first resolved id of the session wins
+ *                   for later events with unregistered caller ids).
+ *  3. containment — canonicalized payload cwd inside exactly one deduped,
+ *                   non-broad workspace root; longest path wins.
+ *  4. verbatim    — fail-open: caller id unchanged.
+ *
+ * Roots are DEDUPLICATED BY PATH (plan-critic C1): identical `project_path`
+ * values collapse to one candidate root carrying its live id set; a matched
+ * shared path resolves only via caller self-match, else it is ambiguous.
+ * Broad roots (filesystem root, user home) never participate in containment
+ * (HAR-03).
+ *
+ * Failure mode: FAIL-OPEN with a sanitized warn. Attribution failure NEVER
+ * rejects or delays an event beyond bounded lookups; any internal error
+ * degrades to `verbatim` (HAR-09). Never throws.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { logger } from "@massa-ai/shared";
+import { getPgPool } from "../../data/db-connection.js";
+import { getProjectIdentityAliasResolver, } from "../project-identity/alias-resolver.js";
+import { SessionPinStore } from "./session-pin-store.js";
+// ── PG provider (cached, bounded, fail-open) ────────────────────────────────
+const PROVIDER_TTL_MS = 30_000;
+const PROVIDER_TIMEOUT_MS = 250;
+/**
+ * Cached workspaces reader. Mirrors the alias-resolver cache/timeout pattern:
+ * a sick-but-hanging DB must not stall hook admission; failures fail open to
+ * an EMPTY root list (containment/explicit simply never match) with a
+ * sanitized warn.
+ */
+export class PgWorkspaceRootProvider {
+    cache = null;
+    now;
+    constructor(options = {}) {
+        this.now = options.now ?? Date.now;
+    }
+    async listRoots() {
+        if (this.cache && this.cache.expiresAt > this.now())
+            return this.cache.roots;
+        let timer;
+        try {
+            const lookup = (async () => {
+                const pool = await getPgPool();
+                const { rows } = await pool.query(`SELECT project_id, project_path FROM workspaces`);
+                return rows.map((r) => ({ projectId: r.project_id, projectPath: r.project_path }));
+            })();
+            const timeout = new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error("workspace_roots_timeout")), PROVIDER_TIMEOUT_MS);
+            });
+            const roots = await Promise.race([lookup, timeout]);
+            // Positive cache only: a transient failure must not pin an empty list.
+            this.cache = { roots, expiresAt: this.now() + PROVIDER_TTL_MS };
+            return roots;
+        }
+        catch (error) {
+            logger.warn("[hook-attribution] workspace roots lookup failed; containment disabled (sanitized)", {
+                name: error instanceof Error ? error.name : "unknown",
+            });
+            return [];
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    /** Test/maintenance escape hatch. */
+    clearCache() {
+        this.cache = null;
+    }
+}
+// ── Resolver ────────────────────────────────────────────────────────────────
+export class AttributionResolver {
+    roots;
+    aliasResolver;
+    pins;
+    canonicalize;
+    homedir;
+    fsRoot;
+    constructor(options = {}) {
+        this.roots = options.roots ?? new PgWorkspaceRootProvider();
+        this.aliasResolver = options.aliasResolver ?? getProjectIdentityAliasResolver();
+        this.pins = options.pins ?? new SessionPinStore();
+        this.canonicalize = options.canonicalize ?? defaultCanonicalize;
+        this.homedir = options.homedir ?? os.homedir;
+        this.fsRoot = options.fsRoot ?? (() => path.parse(path.sep).root);
+    }
+    /**
+     * Resolve one event's durable project id. NEVER throws; any internal
+     * failure degrades to `{ projectId: caller, source: "verbatim" }`.
+     */
+    async resolve(input) {
+        const caller = input.callerProjectId;
+        try {
+            const roots = await this.roots.listRoots();
+            const liveIds = new Set(roots.map((r) => r.projectId));
+            // 1. explicit — caller id is live, or alias-resolves to a live id.
+            const canonicalCaller = await this.aliasResolver.resolve(caller);
+            if (liveIds.has(canonicalCaller) || liveIds.has(caller)) {
+                const winner = liveIds.has(canonicalCaller) ? canonicalCaller : caller;
+                return { projectId: winner, source: "explicit" };
+            }
+            // 2. sticky — session pin hit. Read-only; pinning is the caller's job
+            // after admission survives (see pinSession).
+            if (input.sessionId) {
+                const pinned = this.pins.get(input.sessionId);
+                if (pinned) {
+                    return { projectId: pinned, source: "sticky" };
+                }
+            }
+            // 3. containment — canonical cwd inside exactly one deduped non-broad root.
+            if (input.cwd) {
+                const result = this.resolveContainment(input, roots);
+                if (result)
+                    return result;
+            }
+            // 4. verbatim — fail-open.
+            return { projectId: caller, source: "verbatim" };
+        }
+        catch (error) {
+            logger.warn("[hook-attribution] resolution failed; using caller id (sanitized)", {
+                name: error instanceof Error ? error.name : "unknown",
+            });
+            return { projectId: caller, source: "verbatim" };
+        }
+    }
+    /**
+     * Record a winning resolution for future sticky hits. No-op for verbatim
+     * results (a fail-open outcome carries no signal worth pinning) and when no
+     * sessionId is present. Sticky hits refresh expiry via SessionPinStore.get.
+     */
+    pinSession(sessionId, projectId, source) {
+        if (!sessionId)
+            return;
+        if (source === "verbatim")
+            return;
+        this.pins.set(sessionId, projectId);
+    }
+    resolveContainment(input, roots) {
+        const canonicalCwd = this.canonicalize(input.cwd);
+        if (!canonicalCwd)
+            return null;
+        // Dedupe roots by path (C1): identical paths collapse to one candidate.
+        // Empty paths are junk rows — excluded ("" + sep would match every cwd).
+        const byPath = new Map();
+        for (const root of roots) {
+            const normalized = this.normalizeRootPath(root.projectPath);
+            if (!normalized || this.isBroadRoot(normalized))
+                continue;
+            const set = byPath.get(normalized) ?? new Set();
+            set.add(root.projectId);
+            byPath.set(normalized, set);
+        }
+        // Longest containing path wins.
+        let bestPath = null;
+        for (const candidate of byPath.keys()) {
+            if (canonicalCwd === candidate || canonicalCwd.startsWith(candidate.endsWith(path.sep) ? candidate : candidate + path.sep)) {
+                if (bestPath === null || candidate.length > bestPath.length) {
+                    bestPath = candidate;
+                }
+            }
+        }
+        if (bestPath === null)
+            return null;
+        const idSet = byPath.get(bestPath);
+        if (idSet.size === 1) {
+            const [only] = idSet;
+            return { projectId: only, source: "containment" };
+        }
+        // Shared path (multiple live ids): ambiguous at this tier. Caller/alias
+        // self-match already won at the explicit tier (raw + canonical live check),
+        // so reaching here means the caller is not part of the sharing set.
+        return null;
+    }
+    isBroadRoot(projectPath) {
+        return projectPath === this.fsRoot() || projectPath === this.normalizeRootPath(this.homedir());
+    }
+    /** Strip trailing separators (except the fs root itself); empty stays empty. */
+    normalizeRootPath(projectPath) {
+        if (!projectPath)
+            return projectPath;
+        const fsRoot = this.fsRoot();
+        let normalized = projectPath;
+        while (normalized.length > fsRoot.length && normalized.endsWith(path.sep)) {
+            normalized = normalized.slice(0, -1);
+        }
+        return normalized;
+    }
+}
+/** realpath with resolve fallback; undefined when the path cannot be resolved at all. */
+function defaultCanonicalize(cwd) {
+    try {
+        return fs.realpathSync(cwd);
+    }
+    catch {
+        try {
+            return path.resolve(cwd);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+// ── Singleton ───────────────────────────────────────────────────────────────
+let sharedResolver = null;
+export function getAttributionResolver() {
+    if (!sharedResolver)
+        sharedResolver = new AttributionResolver();
+    return sharedResolver;
+}
+/** @internal — reset the singleton (tests only). */
+export function resetAttributionResolver() {
+    sharedResolver = null;
+}
+/** @internal — swap the singleton with a stubbed resolver (tests only). */
+export function setAttributionResolverForTests(resolver) {
+    sharedResolver = resolver;
+}
+//# sourceMappingURL=attribution-resolver.js.map

package/dist/services/hooks/attribution-resolver.js.map

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

package/dist/services/hooks/co-retrieval-hook.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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 { MemoryRelationType } from "@massa-ai/shared";
+import type { MemoryRepositoryPg } from "../../data/memory/memory-repository-pg.js";
+/**
+ * Subset of `IGraphStore` used by CoRetrievalHook — injectable for testing.
+ * All methods are async to match the backend-agnostic `IGraphStore` contract
+ * (structural gap #14).
+ */
+export interface IGraphStoreEdges {
+    getEdge(sourceId: string, targetId: string, relationType: MemoryRelationType): Promise<any>;
+    createEdge(edge: {
+        sourceId: string;
+        targetId: string;
+        relationType: MemoryRelationType;
+        weight?: number;
+        evidence?: string;
+        autoExtracted?: boolean;
+    }): Promise<any>;
+    incrementEdgeWeight(sourceId: string, targetId: string, relationType: MemoryRelationType, delta: number, maxWeight?: number): Promise<boolean>;
+}
+export declare class CoRetrievalHook {
+    private static instance;
+    private unsubscribe;
+    private readonly graphStore;
+    private constructor();
+    static getInstance(): CoRetrievalHook;
+    /** Create an isolated instance with injected dependencies — for testing only. */
+    static createForTest(graphStore: IGraphStoreEdges, repo?: {
+        findRecentByTag: MemoryRepositoryPg["findRecentByTag"];
+    }): CoRetrievalHook;
+    /** Register the hook. Safe to call multiple times — only registers once. */
+    register(): void;
+    /** Unregister the hook (useful in tests). */
+    unregisterHook(): void;
+    /** Reset singleton (test utility). */
+    static reset(): void;
+    private handleMemoryStored;
+    private findPeers;
+}
+export declare const coRetrievalHook: CoRetrievalHook;
+//# sourceMappingURL=co-retrieval-hook.d.ts.map

package/dist/services/hooks/co-retrieval-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"co-retrieval-hook.d.ts","sourceRoot":"","sources":["../../../src/services/hooks/co-retrieval-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAU,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAM9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2CAA2C,CAAC;AASpF;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,kBAAkB,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC5F,UAAU,CAAC,IAAI,EAAE;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,kBAAkB,CAAC;QACjC,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,aAAa,CAAC,EAAE,OAAO,CAAC;KACzB,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACjB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAChJ;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAgC;IACvD,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmB;IAE9C,OAAO;IAOP,MAAM,CAAC,WAAW,IAAI,eAAe;IAOrC,iFAAiF;IACjF,MAAM,CAAC,aAAa,CAClB,UAAU,EAAE,gBAAgB,EAC5B,IAAI,CAAC,EAAE;QAAE,eAAe,EAAE,kBAAkB,CAAC,iBAAiB,CAAC,CAAA;KAAE,GAChE,eAAe;IAMlB,4EAA4E;IAC5E,QAAQ,IAAI,IAAI;IAQhB,6CAA6C;IAC7C,cAAc,IAAI,IAAI;IAMtB,sCAAsC;IACtC,MAAM,CAAC,KAAK,IAAI,IAAI;YAKN,kBAAkB;YA8DlB,SAAS;CAoBxB;AAED,eAAO,MAAM,eAAe,iBAAgC,CAAC"}