@de-otio/trellis 0.4.0

package/dist/lib/graph/neo4j-graph-service.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Neo4j GraphService Implementation
+ *
+ * Implements the GraphService interface using the Neo4j JavaScript driver.
+ * Used for local development and the AuraDB production/dev instances —
+ * same Cypher dialect.
+ *
+ * Connection management, schema initialization, and health checks are fully
+ * implemented. Business methods are stubbed (Phase 2).
+ *
+ * SECURITY: All queries use parameterized queries ($paramName) — never
+ * string concatenation.
+ *
+ * @see /analysis/redesign/07-graph-database/04-graph-schema.md
+ */
+import { type QueryResult, type Session } from "neo4j-driver";
+import type { GraphConnection, GraphService } from "./graph-service";
+import type { CircleEntityStatus, CircleMember, CircleTier, CircleTierStatus, CreateEntityRelationshipInput, CreateRelationshipInput, DiscoveryFilters, DiscoveryResult, EntityRelationship, EntityRelationshipStatus, GlanceItem, GraphConnectionConfig, GraphData, GraphHealthStatus, GraphNodeType, NearbyFilters, PaginatedResult, PaginationInput, Recommendation, RecordInteractionInput, Relationship, ScoreUpdate, SyncEntityInput, SyncOwnershipInput, SyncPostInput, SyncPostSubjectsInput, SyncUserInput, UpdateRelationshipScoreInput, VisiblePostResult } from "./types";
+export declare class Neo4jGraphService implements GraphService, GraphConnection {
+    private driver;
+    private connected;
+    private schemaInitialized;
+    connect(config: GraphConnectionConfig): Promise<void>;
+    close(): Promise<void>;
+    isConnected(): boolean;
+    healthCheck(): Promise<GraphHealthStatus>;
+    createRelationship(input: CreateRelationshipInput): Promise<Relationship>;
+    removeRelationship(userId: string, targetType: GraphNodeType, targetId: string): Promise<void>;
+    updateRelationshipScore(input: UpdateRelationshipScoreInput): Promise<Relationship>;
+    getRelationship(userId: string, targetType: GraphNodeType, targetId: string): Promise<Relationship | null>;
+    getRelationships(userId: string, options?: {
+        tier?: CircleTier;
+        targetType?: GraphNodeType;
+        pagination?: PaginationInput;
+    }): Promise<PaginatedResult<Relationship>>;
+    getRelationshipGraph(userId: string): Promise<GraphData>;
+    /** Default circle config thresholds from circle-queries.md. */
+    static readonly CIRCLE_THRESHOLDS: {
+        innerThreshold: number;
+        closeFriendThreshold: number;
+        communityThreshold: number;
+    };
+    private static readonly TIER_NAMES;
+    /** Score threshold bounds for a tier (from circle-queries.md). */
+    getCircleTierBounds(tier: CircleTier, thresholds?: {
+        innerThreshold: number;
+        closeFriendThreshold: number;
+        communityThreshold: number;
+    }): {
+        lower: number;
+        upper: number;
+    };
+    private decodeCircleCursor;
+    encodeCircleCursor(createdAt: string, postId: string): string;
+    getCircleMembers(userId: string, tier: CircleTier): Promise<CircleMember[]>;
+    getVisiblePostIds(userId: string, tier: CircleTier, since: Date, pagination: PaginationInput): Promise<PaginatedResult<VisiblePostResult>>;
+    getGlanceItems(userId: string, tier: CircleTier, limit: number): Promise<GlanceItem[]>;
+    getDepthPostIds(userId: string, targetType: GraphNodeType, targetId: string, since: Date, limit: number): Promise<string[]>;
+    /**
+     * Get circle status for all tiers. Uses four parallel count queries
+     * (recommended by circle-queries.md). lastReadTimestamps come from
+     * Postgres CircleReadState.
+     */
+    getCircleStatus(userId: string, lastReadTimestamps?: Record<CircleTier, Date | null>): Promise<CircleTierStatus[]>;
+    /**
+     * Get per-entity unseen counts within a tier. Uses circle-queries.md Query 5.
+     * lastReadAt comes from Postgres CircleReadState.
+     */
+    getCircleEntityStatus(userId: string, tier: CircleTier, lastReadAt?: Date): Promise<CircleEntityStatus[]>;
+    /**
+     * Mark a circle tier as read. The canonical read state lives in Postgres
+     * (CircleReadState). This stores it on the User node as graph-side fallback.
+     */
+    markCircleRead(userId: string, tier: CircleTier, readAt?: Date): Promise<void>;
+    createEntityRelationship(input: CreateEntityRelationshipInput): Promise<EntityRelationship>;
+    confirmEntityRelationship(entityId: string, relatedEntityId: string, confirmingUserId: string): Promise<EntityRelationship>;
+    rejectEntityRelationship(entityId: string, relatedEntityId: string, rejectingUserId: string): Promise<void>;
+    removeEntityRelationship(entityId: string, relatedEntityId: string, removingUserId: string): Promise<void>;
+    getEntityRelationships(entityId: string, options?: {
+        type?: string;
+        status?: EntityRelationshipStatus;
+    }): Promise<EntityRelationship[]>;
+    getPendingEntityRelationships(userId: string): Promise<EntityRelationship[]>;
+    /**
+     * Discover entities through multi-hop entity-to-entity relationship traversal.
+     *
+     * Traverses PLAYMATE|PACK_MATE|SIBLING|PARENT|OFFSPRING|WALK_BUDDY edges
+     * starting from the user's owned entities. Returns only entities the user
+     * does NOT already have a relationship with, and where discoverable != false.
+     *
+     * SECURITY: Hops are hard-capped at 2 regardless of input. 3-hop traversals
+     * can visit 100^3 nodes on popular entities (graph DoS vector). All query
+     * values are parameterized — the hop range is a safe numeric literal derived
+     * from server-side clamped input, never user-supplied string data.
+     */
+    discoverByGraph(userId: string, hops: number, filters?: DiscoveryFilters): Promise<DiscoveryResult[]>;
+    /**
+     * Discover entities by geographic proximity using point.distance().
+     *
+     * Only returns entities where discoverable is not false, and entities the
+     * user does NOT already have a relationship with.
+     *
+     * SECURITY: Exact distances are withheld for all results — only a coarse
+     * distance band is returned to prevent location triangulation (security
+     * review Finding 15). Coordinates are pre-coarsened to ~1km precision at
+     * sync time for additional protection. Entities with existing relationships
+     * are excluded so exact distance is never needed here.
+     */
+    discoverNearby(userId: string, lat: number, lng: number, radiusMeters: number, filters?: NearbyFilters): Promise<DiscoveryResult[]>;
+    /**
+     * Get entity recommendations based on shared connections, breed similarity,
+     * and geographic proximity.
+     *
+     * Runs three parallel queries (signals) and merges results, deduplicated by
+     * entity ID, keeping the highest-scoring reason per entity.
+     *
+     * SECURITY: `owner_proximity` is never exposed as a RecommendationReason.
+     * Exposing it would allow the viewer to infer a close relationship with the
+     * entity's owner from a visible recommendation, leaking graph topology.
+     * Owner proximity is used internally to boost shared-connection scoring but
+     * always surfaced as "shared_connections" in the response.
+     */
+    getRecommendations(userId: string, limit: number): Promise<Recommendation[]>;
+    /**
+     * Convert an exact distance in meters to a coarse distance band string.
+     *
+     * SECURITY: Used by discoverNearby() to prevent location triangulation.
+     * Values match the DiscoveryResult.distanceBand union type exactly.
+     */
+    private static toDistanceBand;
+    /**
+     * Record a user interaction on a RELATES_TO edge.
+     *
+     * Updates interaction count, last interaction timestamp, and per-type
+     * interaction counters. No-op if the relationship does not exist.
+     *
+     * SECURITY: All queries parameterized.
+     */
+    recordInteraction(input: RecordInteractionInput): Promise<void>;
+    /**
+     * Recompute scores for ALL relationships of a user.
+     *
+     * Batch-processes all RELATES_TO edges in a single query pass per target type,
+     * avoiding N+1 patterns. Returns only relationships where the tier changed.
+     *
+     * SECURITY: All queries parameterized.
+     */
+    recomputeScores(userId: string): Promise<ScoreUpdate[]>;
+    /**
+     * Apply time-based decay to all of a user's relationship scores.
+     *
+     * - User->User: 50% decay after 60 days of no interaction
+     * - User->Entity: 50% decay after 120 days of no interaction
+     * - Owned entities (:OWNS edge) are exempt — always pinned at 1.0
+     *
+     * SECURITY: All queries parameterized.
+     */
+    applyDecay(userId: string): Promise<ScoreUpdate[]>;
+    syncUser(input: SyncUserInput): Promise<void>;
+    removeUser(userId: string): Promise<void>;
+    syncEntity(input: SyncEntityInput): Promise<void>;
+    removeEntity(entityId: string): Promise<void>;
+    syncPost(input: SyncPostInput): Promise<void>;
+    removePost(postId: string): Promise<void>;
+    syncPostSubjects(input: SyncPostSubjectsInput): Promise<void>;
+    syncOwnership(input: SyncOwnershipInput): Promise<void>;
+    removeOwnership(entityId: string, userId: string): Promise<void>;
+    /**
+     * Get a new session from the driver. Throws if not connected.
+     * Callers are responsible for closing the session.
+     */
+    getSession(): Session;
+    /**
+     * Execute a parameterized Cypher query and return the result.
+     * Sessions are opened and closed automatically.
+     *
+     * SECURITY: Always use parameters — never interpolate values into the query.
+     */
+    executeQuery(query: string, parameters?: Record<string, unknown>): Promise<QueryResult>;
+    /**
+     * Initialize the graph schema (constraints and indexes).
+     * Called once on first connect.
+     */
+    private initializeSchema;
+}
+//# sourceMappingURL=neo4j-graph-service.d.ts.map

package/dist/lib/graph/neo4j-graph-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"neo4j-graph-service.d.ts","sourceRoot":"","sources":["../../../src/lib/graph/neo4j-graph-service.ts"],"names":[],"mappings":"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"}