@massa-ai/core 1.2.1

package/dist/services/project-identity/alias-resolver.js

@@ -0,0 +1,129 @@
+/**
+ * alias-resolver — application-layer canonical project-ID resolution (spec
+ * req 3, design "Concurrency and Caches"). The DB trigger resolves aliases on
+ * INSERT/UPDATE of a guarded identity column, but it cannot rewrite:
+ *
+ *  - statements FILTERED by a retired id (`UPDATE/DELETE ... WHERE project_id
+ *    = 'retired'` matches 0 rows post-rename — a silent write loss), or
+ *  - payload-embedded ids (scheduled_jobs.payload JSON — no identity column).
+ *
+ * Writers therefore resolve the canonical ID at their write-entry seam before
+ * persistence. Resolution reuses the server-side `project_identity_resolve`
+ * function (alias-chain flattening, cycle guard) in one round trip.
+ *
+ * Caching: positive/negative results cached with a short TTL. The post-commit
+ * invalidator registry clears BOTH source and target entries after every
+ * committed rename/merge, so staleness is bounded by the invalidation
+ * latency, not the TTL; the TTL only covers processes that never see an
+ * identity change.
+ *
+ * Failure mode: FAIL-OPEN with a warn. If the alias lookup fails, the writer
+ * proceeds with the original ID — the DB trigger remains the backstop for
+ * guarded identity columns, and an alias-DB outage would fail the write
+ * anyway. Resolution NEVER throws.
+ */
+import { logger } from "@massa-ai/shared";
+import { getPgPool } from "../../data/db-connection.js";
+const DEFAULT_TTL_MS = 30_000;
+const DEFAULT_RESOLVE_TIMEOUT_MS = 250;
+export class ProjectIdentityAliasResolver {
+    ttlMs;
+    resolveTimeoutMs;
+    cache = new Map();
+    querier;
+    now;
+    constructor(options = {}) {
+        this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+        this.resolveTimeoutMs = options.resolveTimeoutMs ?? DEFAULT_RESOLVE_TIMEOUT_MS;
+        this.querier = options.querier;
+        this.now = options.now ?? Date.now;
+    }
+    /**
+     * Resolve `projectId` to its canonical target. Live IDs resolve to
+     * themselves; retired IDs flatten to the current target. NEVER throws —
+     * on any lookup failure the input ID is returned (fail-open, see header).
+     *
+     * The lookup is raced against `resolveTimeoutMs`: a sick-but-hanging DB
+     * (connect timeout is 5s on the shared pool) must not stall every write
+     * seam for seconds. Successful resolutions are cached, so the steady-state
+     * cost is one fast query per id per TTL.
+     */
+    async resolve(projectId) {
+        if (!projectId)
+            return projectId;
+        const cached = this.cache.get(projectId);
+        if (cached && cached.expiresAt > this.now()) {
+            return cached.canonical;
+        }
+        try {
+            const canonical = await this.resolveWithTimeout(projectId);
+            this.cache.set(projectId, { canonical, expiresAt: this.now() + this.ttlMs });
+            return canonical;
+        }
+        catch (error) {
+            // Fail-open: proceed with the original ID. No negative-cache write, so
+            // the next writer retries the lookup instead of riding a transient.
+            logger.warn("[project-identity] alias resolution failed; using original id (sanitized)", {
+                name: error instanceof Error ? error.name : "unknown",
+            });
+            return projectId;
+        }
+    }
+    async resolveWithTimeout(projectId) {
+        let timer;
+        try {
+            const lookup = (async () => {
+                const querier = await this.getQuerier();
+                const { rows } = await querier.query(`SELECT project_identity_resolve($1)`, [projectId]);
+                const resolved = rows[0]?.project_identity_resolve;
+                return typeof resolved === "string" && resolved.length > 0 ? resolved : projectId;
+            })();
+            const timeout = new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error("project_identity_resolve_timeout")), this.resolveTimeoutMs);
+            });
+            return await Promise.race([lookup, timeout]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    /**
+     * Post-commit invalidator hook: drop the cached mapping for this ID. Apply
+     * invokes it for BOTH source and target via the invalidator registry.
+     */
+    invalidateProject(projectId) {
+        this.cache.delete(projectId);
+    }
+    /** Test/maintenance escape hatch. */
+    clearCache() {
+        this.cache.clear();
+    }
+    /** @internal — exposed for tests. */
+    get cacheSize() {
+        return this.cache.size;
+    }
+    async getQuerier() {
+        if (!this.querier) {
+            this.querier = await getPgPool();
+        }
+        return this.querier;
+    }
+}
+/** Process-wide resolver (production singleton). */
+let sharedResolver = null;
+export function getProjectIdentityAliasResolver() {
+    if (!sharedResolver) {
+        sharedResolver = new ProjectIdentityAliasResolver();
+    }
+    return sharedResolver;
+}
+/** @internal — reset the singleton (tests only). */
+export function resetProjectIdentityAliasResolver() {
+    sharedResolver = null;
+}
+/** @internal — swap the singleton with a stubbed resolver (tests only). */
+export function setProjectIdentityAliasResolverForTests(resolver) {
+    sharedResolver = resolver;
+}
+//# sourceMappingURL=alias-resolver.js.map

package/dist/services/project-identity/alias-resolver.js.map

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

package/dist/services/project-identity/apply.d.ts

@@ -0,0 +1,89 @@
+import { type ProjectIdentityApplyInput, type ProjectIdentityApplyResult, type ProjectIdentityTransactionClient } from "./contracts.js";
+import { ProjectIdentityInvalidatorRegistry } from "./invalidator-registry.js";
+/**
+ * Runner owns acquisition and release of a transaction-backed client.
+ *
+ * Production wires this to the shared pg pool (`pool.connect()`); tests
+ * substitute a fake that stages BEGIN/COMMIT/ROLLBACK against in-memory rows.
+ * The runner MUST return a client whose `rollbackTransaction` is safe to call
+ * even after `commitTransaction` (used by the finally clause below).
+ */
+export interface ProjectIdentityTransactionRunner {
+    withTransaction<T>(body: (client: ProjectIdentityTransactionClient) => Promise<T>): Promise<T>;
+}
+/**
+ * Best-effort publisher for the `project-identity:changed` event. Production
+ * wires this to the shared EventBus singleton; tests substitute a recorder.
+ * Publish failures MUST be swallowed by the caller (spec req 8) — the publisher
+ * itself does not throw.
+ */
+export interface ProjectIdentityChangedPublisher {
+    publish(payload: ProjectIdentityChangedPayload): void;
+}
+export interface ProjectIdentityChangedPayload {
+    mode: "rename" | "merge";
+    sourceProjectId: string;
+    targetProjectId: string;
+    operationId: string;
+    committedAt: string;
+}
+/**
+ * Project identity apply service.
+ *
+ * Locks source and target in lexical order, recomputes the authoritative plan
+ * inside the same transaction, gates on conflicts/unknown storage/plan-hash,
+ * rewrites direct + payload stores, repairs the graph active pointer (merge),
+ * creates the alias, and writes exactly one operation row.
+ *
+ * Failure boundaries (T6 injects faults here):
+ *   - FIRST MUTATION: any write in `rewriteDirectStores` / payload / graph.
+ *     A throw past this point rolls back the entire transaction via the
+ *     `withTransaction` finally clause.
+ *   - PRE-COMMIT: after the operation row insert, before COMMIT. A throw here
+ *     also rolls back; the operation row never becomes durable.
+ */
+export declare class ProjectIdentityApplyService {
+    private readonly runner;
+    private readonly invalidators;
+    private readonly publisher;
+    private readonly schema;
+    constructor(runner: ProjectIdentityTransactionRunner, invalidators?: ProjectIdentityInvalidatorRegistry, publisher?: ProjectIdentityChangedPublisher, schema?: string);
+    apply(input: ProjectIdentityApplyInput): Promise<ProjectIdentityApplyResult>;
+    /**
+     * Run every registered in-memory cache invalidator for source + target.
+     * NEVER throws — a rejection here is captured as a sanitized report and the
+     * committed result is returned with `invalidation.failures` populated.
+     */
+    private runPostCommitInvalidation;
+    /**
+     * Best-effort `project-identity:changed` notification. Any throw is swallowed
+     * — listeners cannot roll back a committed operation (spec req 8).
+     */
+    private publishChangedEvent;
+    private applyInTransaction;
+    /**
+     * Idempotency read for project_identity_operations. Returns the stored
+     * result when the operation row exists and its request_hash matches; returns
+     * undefined when absent; throws PROJECT_IDENTITY_OPERATION_REUSED when the
+     * same operationId was recorded under different request material.
+     */
+    private storedResultFor;
+    private rewriteDirectStore;
+    private rewritePayloadStore;
+    private tableHasColumn;
+    private repairGraphForMerge;
+    private verifyRenameGraphPointers;
+}
+/**
+ * Build a ProjectIdentityApplyService backed by a function that yields a
+ * pg-style transaction client. Production passes the shared pool's connect.
+ *
+ * The invalidator registry and event publisher default to no-op so existing
+ * callers (and T1–T3 tests) stay byte-identical; production wires real ones.
+ */
+export declare function createProjectIdentityApplyService(acquireClient: () => Promise<ProjectIdentityTransactionClient>, releaseClient: (client: ProjectIdentityTransactionClient) => Promise<void>, options?: {
+    invalidators?: ProjectIdentityInvalidatorRegistry;
+    publisher?: ProjectIdentityChangedPublisher;
+    schema?: string;
+}): ProjectIdentityApplyService;
+//# sourceMappingURL=apply.d.ts.map

package/dist/services/project-identity/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/services/project-identity/apply.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAC/B,KAAK,gCAAgC,EACtC,MAAM,gBAAgB,CAAC;AAcxB,OAAO,EAEL,kCAAkC,EAEnC,MAAM,2BAA2B,CAAC;AAEnC;;;;;;;GAOG;AACH,MAAM,WAAW,gCAAgC;IAC/C,eAAe,CAAC,CAAC,EACf,IAAI,EAAE,CAAC,MAAM,EAAE,gCAAgC,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7D,OAAO,CAAC,CAAC,CAAC,CAAC;CACf;AAiCD;;;;;GAKG;AACH,MAAM,WAAW,+BAA+B;IAC9C,OAAO,CAAC,OAAO,EAAE,6BAA6B,GAAG,IAAI,CAAC;CACvD;AAED,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AA4ID;;;;;;;;;;;;;;GAcG;AACH,qBAAa,2BAA2B;IAEpC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAHN,MAAM,EAAE,gCAAgC,EACxC,YAAY,GAAE,kCAA6E,EAC3F,SAAS,GAAE,+BAAgD,EAC3D,MAAM,SAAW;IAG9B,KAAK,CAAC,KAAK,EAAE,yBAAyB,GAAG,OAAO,CAAC,0BAA0B,CAAC;IAkClF;;;;OAIG;YACW,yBAAyB;IAiBvC;;;OAGG;IACH,OAAO,CAAC,mBAAmB;YAiBb,kBAAkB;IAyLhC;;;;;OAKG;YACW,eAAe;YAkBf,kBAAkB;YAmDlB,mBAAmB;YAgEnB,cAAc;YAed,mBAAmB;YAiJnB,yBAAyB;CAmBxC;AAED;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAC/C,aAAa,EAAE,MAAM,OAAO,CAAC,gCAAgC,CAAC,EAC9D,aAAa,EAAE,CAAC,MAAM,EAAE,gCAAgC,KAAK,OAAO,CAAC,IAAI,CAAC,EAC1E,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,kCAAkC,CAAC;IAClD,SAAS,CAAC,EAAE,+BAA+B,CAAC;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;CACZ,GACL,2BAA2B,CAQ7B"}