@de-otio/trellis 0.7.1 → 0.10.0

package/dist/lib/graph/postgres/discovery.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Discovery + recommendation operations on Postgres.
+ *
+ * Phase 1 · B4 (long pole). PORT from neo4j-graph-service.ts.
+ * `discoverByGraph` is the ≤2-hop undirected recursive CTE (sketch in the graph-DB
+ * revisit doc, "The one query that needs proving"); `getRecommendations`'
+ * shared-connections signal is the same shape; `discoverNearby` delegates to
+ * Postgres/PostGIS via EntityGeoLookup and re-homes the read-time coarsening.
+ *
+ * SEMANTIC NOTES (port fidelity):
+ *  - Edges live in `entity_relationships` (undirected: either column may hold the
+ *    near/far end). Confirmed edges only (`status = 'CONFIRMED'`), restricted to
+ *    the traversal label set.
+ *  - The Neo4j nodes only ever stored entityType/name/breed/lifeStage (see
+ *    syncEntity); `discoverable` was never written, so Cypher's
+ *    "discoverable IS NULL OR = true" was always true. In Postgres `breed` lives
+ *    in `entities.metadata->>'breed'`, `lifeStage` in `entities.life_stage`,
+ *    `entityType` in `entities.entity_type`. There is NO `discoverable` column, so
+ *    the faithful equivalent reads it out of metadata and defaults to true:
+ *    `COALESCE((metadata->>'discoverable')::boolean, true) = true` — a no-op when
+ *    the key is absent, exactly like the graph. See report for the schema note.
+ *  - Tenant scoping: every graph-shaped table carries `tenant_id`. The Neo4j
+ *    discovery path returned [] with no tenant in context for the geo signals;
+ *    the Postgres path makes that uniform — all three methods resolve the ambient
+ *    tenant up front and return [] when absent, and every table touch is
+ *    `tenant_id = $tenant` scoped (defence in depth; the graph DB had no
+ *    tenant labels at all).
+ */
+import type { PrismaClient } from "@prisma/client";
+import type { EntityGeoLookup } from "../../geo/entity-geo-repository.js";
+import type { DiscoveryFilters, DiscoveryResult, NearbyFilters, Recommendation } from "../types.js";
+/**
+ * Discovery ranking version — increment whenever the recommendation signals,
+ * their weights, the merge/dedup semantics, or the diversity cap change.
+ *
+ * Mirrors `FEED_RANKING_VERSION` (feed-pagination.ts): a version change is a new
+ * experimental condition for `/api/discovery/recommendations` and must be
+ * audited accordingly. The discovery surface is engagement-adjacent (signals are
+ * derived from the relationship graph), so the same provenance discipline applies.
+ *
+ * Current version 1: shared-connections (count/10) + same-breed (0.6 fixed) +
+ * nearby ((1 − d/10 000) × 0.5, 5 km) signals, dedup-by-entity-keep-highest, and
+ * the per-owner diversity cap (`MAX_RECOMMENDATIONS_PER_OWNER`) with a single
+ * relaxation pass. Version 1 is the FIRST version ever served, so the cap is part
+ * of it — not a bump from an uncapped predecessor (no recommendation has been
+ * served without the cap).
+ */
+export declare const DISCOVERY_RANKING_VERSION: 1;
+/**
+ * Maximum recommendations a single owner may contribute to one page. The cap is
+ * per-OWNER (entity dedup is handled separately): a multi-owner entity counts
+ * against EVERY active owner and is admitted only if all its owners are under the
+ * cap. Ownerless candidates (empty `ownerIds`) are exempt. See SCORING-CODEBOOK.md
+ * "Discovery Recommendation Signals".
+ */
+export declare const MAX_RECOMMENDATIONS_PER_OWNER = 2;
+/**
+ * A merged recommendation candidate carried through the diversity-cap merge.
+ * `ownerIds` are the candidate's ACTIVE owners (same tenant), surfaced by each
+ * signal query so the merge can enforce the per-owner cap without an extra query.
+ */
+interface RecommendationCandidate {
+    entityId: string;
+    name: string;
+    entityType: string;
+    score: number;
+    reason: string;
+    ownerIds: string[];
+}
+/**
+ * Pure merge for the recommendation signals (no I/O — business logic isolated for
+ * verification). Three bounded steps, no loop on external state:
+ *
+ *  1. Dedup by entity, keeping the highest-scoring entry per entity (preserves the
+ *     pre-cap semantics the tests pin).
+ *  2. Capped round-robin fill across the signal sources IN ORDER (shared → breed →
+ *     nearby), each source pre-sorted by score desc. A candidate is admitted iff
+ *     every owner in `ownerIds` is below `MAX_RECOMMENDATIONS_PER_OWNER`; on admit
+ *     all its owners' counts increment. Ownerless candidates are always admissible.
+ *     One full cycle over all candidates.
+ *  3. Relaxation: if still under `limit` after the capped pass, admit the remaining
+ *     skipped candidates by GLOBAL score desc, ignoring the cap (fill beats starve).
+ *
+ * Hard bound: exactly two passes (capped, then relaxation). The dedup map and the
+ * cap-count map are the only mutable state; neither can grow unbounded.
+ *
+ * @param signals per-source candidate arrays in fill order: [shared, breed, nearby]
+ * @param limit   maximum page size
+ */
+export declare function mergeRecommendations(signals: RecommendationCandidate[][], limit: number): RecommendationCandidate[];
+export declare class DiscoveryOps {
+    private readonly prisma;
+    private readonly geoLookup?;
+    constructor(prisma: PrismaClient, geoLookup?: EntityGeoLookup | undefined);
+    /**
+     * Discover entities through ≤2-hop UNDIRECTED entity-to-entity traversal.
+     *
+     * Starts from the user's owned entities, walks CONFIRMED typed edges (the fixed
+     * label set), and returns entities the user does NOT already relate to and that
+     * are discoverable. Recursive CTE bounded at the (server-clamped) hop count.
+     *
+     * SECURITY: hops are hard-capped at 2 regardless of input — a 3-hop traversal
+     * can visit 100^3 nodes on a popular entity (graph DoS). The hop cap is a
+     * numeric literal derived from clamped input; all other values are bound
+     * parameters ($queryRawUnsafe with positional $n). Tenant-scoped on every table.
+     */
+    discoverByGraph(userId: string, hops: number, filters?: DiscoveryFilters): Promise<DiscoveryResult[]>;
+    /**
+     * Discover entities by geographic proximity.
+     *
+     * Proximity + ranking come from Postgres/PostGIS (`this.geoLookup`); this method
+     * supplies entity fields and filters to discoverable entities the user does NOT
+     * already relate to.
+     *
+     * SECURITY: only a coarse distance band is returned (never exact distance) to
+     * prevent location triangulation (Finding 15). Already-related entities are
+     * excluded, so exact distance is never needed here.
+     */
+    discoverNearby(userId: string, lat: number, lng: number, radiusMeters: number, filters?: NearbyFilters): Promise<DiscoveryResult[]>;
+    /**
+     * Entity recommendations merging four signals: shared-connections (≤2-hop
+     * traversal), same-breed, nearby, and owner-proximity. Dedup by entity, keeping
+     * the highest-scoring reason, then a per-owner DIVERSITY CAP
+     * (`MAX_RECOMMENDATIONS_PER_OWNER`) applied via round-robin fill with a single
+     * relaxation pass (see `mergeRecommendations`). The cap is part of
+     * `DISCOVERY_RANKING_VERSION` 1 — see SCORING-CODEBOOK.md.
+     *
+     * SECURITY: owner_proximity is never surfaced as a client-facing reason — it is
+     * folded into the shared-connections signal and always mapped to
+     * "shared_connections" (exposing it would leak graph topology). See the
+     * RecommendationReason doc comment.
+     */
+    getRecommendations(userId: string, limit: number): Promise<Recommendation[]>;
+    /**
+     * Shared-connections signal: same ≤2-hop traversal shape as discoverByGraph,
+     * but anchored from the user's OWNED and RELATED entities, counting distinct
+     * source entities per candidate. score = sharedCount / 10. Excludes entities the
+     * user already owns or relates to, and non-discoverable ones.
+     */
+    private computeSharedConnections;
+    /**
+     * Same-breed signal: candidates whose breed matches any breed of the user's
+     * owned entities. Fixed score 0.6. Excludes already-owned / already-related /
+     * non-discoverable entities. Breed lives in `entities.metadata->>'breed'`.
+     */
+    private computeSameBreed;
+    /**
+     * Nearby signal: anchors are the user's owned entities; proximity + ranking come
+     * from PostGIS (`findNearAnchors`). Candidates are filtered against graph facts
+     * (not already related/owned, discoverable). score = (1 - minDist/10000) * 0.5,
+     * nearest first. Empty when geo is unavailable or the user owns no located
+     * entities.
+     */
+    private computeNearbyRecommendations;
+    /**
+     * Fetch name/entityType/breed for a PostGIS candidate set, restricted to
+     * discoverable entities the user does NOT already relate to (and, by the
+     * caller's convention, that pass optional entityType/breed equality filters).
+     * The PostGIS candidate ids are the proximity-ranked set; this is the graph-fact
+     * filter that the Neo4j path expressed as a `MATCH … WHERE id IN $ids …` query.
+     */
+    private fetchDiscoverableFields;
+}
+export {};
+//# sourceMappingURL=discovery.d.ts.map

package/dist/lib/graph/postgres/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../../src/lib/graph/postgres/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,cAAc,EAEf,MAAM,aAAa,CAAC;AAmBrB;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,yBAAyB,EAAG,CAAU,CAAC;AAEpD;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAE/C;;;;GAIG;AACH,UAAU,uBAAuB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,uBAAuB,EAAE,EAAE,EACpC,KAAK,EAAE,MAAM,GACZ,uBAAuB,EAAE,CAiF3B;AAkBD,qBAAa,YAAY;IAErB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;gBADV,MAAM,EAAE,YAAY,EACpB,SAAS,CAAC,EAAE,eAAe,YAAA;IAG9C;;;;;;;;;;;OAWG;IACG,eAAe,CACnB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,eAAe,EAAE,CAAC;IA8F7B;;;;;;;;;;OAUG;IACG,cAAc,CAClB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,eAAe,EAAE,CAAC;IA2C7B;;;;;;;;;;;;OAYG;IACG,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IA6BlF;;;;;OAKG;YACW,wBAAwB;IA6EtC;;;;OAIG;YACW,gBAAgB;IAkD9B;;;;;;OAMG;YACW,4BAA4B;IAmD1C;;;;;;OAMG;YACW,uBAAuB;CAsDtC"}