@de-otio/trellis 0.4.0

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

@@ -0,0 +1,479 @@
+/**
+ * GraphService Interface
+ *
+ * The abstraction layer between API handlers and the graph database.
+ * Implementations exist for:
+ * - Neo4j Community Edition (local development, bolt:// protocol)
+ * - Neo4j AuraDB (bolt+s:// over the Bolt protocol with password auth)
+ *
+ * Both backends support the Cypher query language. This interface
+ * exposes high-level operations — implementations translate them to
+ * Cypher queries internally.
+ *
+ * Handlers never execute raw graph queries. They call GraphService methods
+ * that return IDs, which are then used to fetch content from Postgres via Prisma.
+ *
+ * @see /analysis/redesign/07-graph-database/02-hybrid-architecture.md
+ * @see /analysis/redesign/07-graph-database/04-graph-schema.md
+ */
+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";
+/**
+ * Abstract connection to the graph database.
+ *
+ * Implementations manage driver lifecycle, connection pooling, and
+ * authentication. The connection is created once at application startup
+ * and shared across all requests.
+ */
+export interface GraphConnection {
+    /**
+     * Initialize the connection (create driver, verify reachability).
+     * Must be called before any queries. Idempotent — calling multiple
+     * times is safe.
+     *
+     * @param config - Connection configuration (endpoint, auth, pool settings)
+     * @throws GraphConnectionError if the database is unreachable
+     */
+    connect(config: GraphConnectionConfig): Promise<void>;
+    /**
+     * Gracefully close the connection and release all pooled resources.
+     * Should be called on application shutdown.
+     */
+    close(): Promise<void>;
+    /**
+     * Check whether the connection is currently open and healthy.
+     */
+    isConnected(): boolean;
+}
+/**
+ * High-level graph operations for the Trellis API.
+ *
+ * All methods are async (graph operations are I/O-bound).
+ * All methods throw GraphError subclasses on failure.
+ *
+ * Handlers consume this interface — they never know which backend
+ * (local Neo4j or AuraDB) is being used.
+ */
+export interface GraphService {
+    /**
+     * Check graph database health.
+     *
+     * Executes a lightweight query (e.g., `RETURN 1`) and measures latency.
+     * Used by the /health endpoint and readiness probes.
+     *
+     * @returns Health status including latency and backend type
+     */
+    healthCheck(): Promise<GraphHealthStatus>;
+    /**
+     * Create a new scored relationship from a user to a target (user or entity).
+     *
+     * The initial score is determined by the connection method:
+     * - "code": 0.7 (close friends tier)
+     * - "import": 0.5 (close friends tier)
+     * - "suggestion": 0.3 (community tier)
+     * - "discovery": 0.3 (community tier)
+     *
+     * If the target already has a relationship back to this user (user->user),
+     * both edges are marked as reciprocated.
+     *
+     * @param input - Relationship creation parameters
+     * @returns The newly created relationship
+     * @throws GraphNotFoundError if the target node does not exist in the graph
+     * @throws GraphConflictError if the relationship already exists
+     */
+    createRelationship(input: CreateRelationshipInput): Promise<Relationship>;
+    /**
+     * Remove a relationship.
+     *
+     * Deletes the RELATES_TO edge. If the relationship was reciprocated
+     * (user->user), the reverse edge's `reciprocated` flag is set to false.
+     *
+     * @param userId - Source user ID
+     * @param targetType - Type of the target node
+     * @param targetId - Target node ID
+     * @throws GraphNotFoundError if the relationship does not exist
+     */
+    removeRelationship(userId: string, targetType: GraphNodeType, targetId: string): Promise<void>;
+    /**
+     * Update the manual score override on a relationship.
+     *
+     * When manualScore is set, it overrides the computed score for tier
+     * resolution. When cleared (set to null), the computed score is used again.
+     *
+     * @param input - Score update parameters
+     * @returns The updated relationship
+     * @throws GraphNotFoundError if the relationship does not exist
+     */
+    updateRelationshipScore(input: UpdateRelationshipScoreInput): Promise<Relationship>;
+    /**
+     * Get a specific relationship by source user and target.
+     *
+     * @param userId - Source user ID
+     * @param targetType - Type of the target node
+     * @param targetId - Target node ID
+     * @returns The relationship, or null if it does not exist
+     */
+    getRelationship(userId: string, targetType: GraphNodeType, targetId: string): Promise<Relationship | null>;
+    /**
+     * List all relationships for a user, with optional filtering and pagination.
+     *
+     * Results are ordered by score descending (closest relationships first).
+     *
+     * @param userId - Source user ID
+     * @param options - Optional filters and pagination
+     * @returns Paginated list of relationships
+     */
+    getRelationships(userId: string, options?: {
+        /** Filter to a specific tier */
+        tier?: CircleTier;
+        /** Filter to user or entity targets */
+        targetType?: GraphNodeType;
+        /** Pagination */
+        pagination?: PaginationInput;
+    }): Promise<PaginatedResult<Relationship>>;
+    /**
+     * Get the full relationship graph for visualization.
+     *
+     * Returns all relationship targets as nodes with coarse closeness
+     * indicators and tiers, plus tier summary statistics. This is a heavier
+     * query intended for the graph view UI, not for feed queries.
+     *
+     * SECURITY: This endpoint requires recent authentication (session age
+     * < 15 minutes). Raw scores are NOT returned — only tier and a coarse
+     * closeness value (0-100, bucketed to nearest 10). All access is
+     * audit-logged. Rate limit: 10 requests/minute.
+     *
+     * @param userId - The viewer's user ID
+     * @returns Graph data with nodes (coarse closeness, no raw scores) and tier summaries
+     */
+    getRelationshipGraph(userId: string): Promise<GraphData>;
+    /**
+     * Get members (users and entities) in a specific circle tier.
+     *
+     * Members are sorted by score descending within the tier. Owned entities
+     * are always included at tier 0 (auto-pinned at score 1.0).
+     *
+     * @param userId - The viewer's user ID
+     * @param tier - Circle tier (0-3)
+     * @returns List of circle members in the tier
+     */
+    getCircleMembers(userId: string, tier: CircleTier): Promise<CircleMember[]>;
+    /**
+     * Get post IDs visible to the user in a specific circle tier.
+     *
+     * Uses dual-gated visibility:
+     * 1. Posts where the viewer has a relationship with ANY subject entity,
+     *    and the closest such relationship falls within the post's radius
+     * 2. Posts where the viewer has a relationship with the author,
+     *    and the author's posting radius reaches the viewer's tier
+     *
+     * For multi-entity posts, the resolved tier is the minimum (closest)
+     * tier across all matching subject entity relationships.
+     *
+     * @param userId - The viewer's user ID
+     * @param tier - Circle tier to query
+     * @param since - Only return posts created after this timestamp
+     * @param pagination - Pagination parameters
+     * @returns Paginated post IDs with creation timestamps and resolved tiers
+     */
+    getVisiblePostIds(userId: string, tier: CircleTier, since: Date, pagination: PaginationInput): Promise<PaginatedResult<VisiblePostResult>>;
+    /**
+     * Get glance mode data for a circle tier.
+     *
+     * Returns one recent item per entity/user in the tier, prioritized by
+     * recency. This provides a finite, entity-organized snapshot instead
+     * of a chronological feed.
+     *
+     * @param userId - The viewer's user ID
+     * @param tier - Circle tier
+     * @param limit - Maximum number of glance items (one per entity/user)
+     * @returns List of glance items, one per member with new content
+     */
+    getGlanceItems(userId: string, tier: CircleTier, limit: number): Promise<GlanceItem[]>;
+    /**
+     * Get depth mode data: recent post IDs from/about a specific target.
+     *
+     * Used when a user taps on a specific entity or user in their circle
+     * to see that target's recent content.
+     *
+     * @param userId - The viewer's user ID
+     * @param targetType - Whether the target is a user or entity
+     * @param targetId - The target user or entity ID
+     * @param since - Only return posts created after this timestamp
+     * @param limit - Maximum number of post IDs to return
+     * @returns Post IDs ordered by creation time descending
+     */
+    getDepthPostIds(userId: string, targetType: GraphNodeType, targetId: string, since: Date, limit: number): Promise<string[]>;
+    /**
+     * Get the read status for all circle tiers.
+     *
+     * Returns whether each tier is "caught up" (no unseen content),
+     * the count of unseen posts, and the last-read timestamp.
+     *
+     * @param userId - The viewer's user ID
+     * @returns Status for all four tiers
+     */
+    getCircleStatus(userId: string): Promise<CircleTierStatus[]>;
+    /**
+     * Get per-entity status within a circle tier.
+     *
+     * Shows which entities have new content and how many unseen posts each has.
+     * Used for the entity-level "caught up" indicators in the circle view.
+     *
+     * @param userId - The viewer's user ID
+     * @param tier - Circle tier
+     * @returns Per-entity status list, sorted by unseen count descending
+     */
+    getCircleEntityStatus(userId: string, tier: CircleTier): Promise<CircleEntityStatus[]>;
+    /**
+     * Mark a circle tier as read up to the current time.
+     *
+     * Updates the lastReadAt timestamp used for "caught up" computation.
+     * After this call, `getCircleStatus` will reflect the updated read state.
+     *
+     * @param userId - The viewer's user ID
+     * @param tier - Circle tier to mark as read
+     * @param readAt - Timestamp to mark as read up to (defaults to now)
+     */
+    markCircleRead(userId: string, tier: CircleTier, readAt?: Date): Promise<void>;
+    /**
+     * Create a typed relationship between two entities.
+     *
+     * The relationship starts in PENDING status. It must be confirmed by an
+     * owner of the related entity before it becomes CONFIRMED and visible
+     * in the graph.
+     *
+     * @param input - Entity relationship creation parameters
+     * @returns The newly created entity relationship
+     * @throws GraphNotFoundError if either entity does not exist in the graph
+     * @throws GraphConflictError if the relationship already exists
+     * @throws GraphAuthorizationError if the proposing user does not own the source entity
+     */
+    createEntityRelationship(input: CreateEntityRelationshipInput): Promise<EntityRelationship>;
+    /**
+     * Confirm a pending entity relationship.
+     *
+     * Only an owner of the target entity can confirm. Once confirmed, the
+     * relationship edge becomes visible for traversal queries (discovery,
+     * recommendations).
+     *
+     * @param entityId - Source entity ID
+     * @param relatedEntityId - Target entity ID
+     * @param confirmingUserId - User confirming (must own relatedEntityId)
+     * @returns The confirmed entity relationship
+     * @throws GraphNotFoundError if the relationship does not exist
+     * @throws GraphConflictError if already confirmed or rejected
+     * @throws GraphAuthorizationError if the user does not own the target entity
+     */
+    confirmEntityRelationship(entityId: string, relatedEntityId: string, confirmingUserId: string): Promise<EntityRelationship>;
+    /**
+     * Reject a pending entity relationship.
+     *
+     * @param entityId - Source entity ID
+     * @param relatedEntityId - Target entity ID
+     * @param rejectingUserId - User rejecting (must own relatedEntityId)
+     * @throws GraphNotFoundError if the relationship does not exist
+     * @throws GraphAuthorizationError if the user does not own the target entity
+     */
+    rejectEntityRelationship(entityId: string, relatedEntityId: string, rejectingUserId: string): Promise<void>;
+    /**
+     * Remove an entity relationship.
+     *
+     * Either owner (of source or target entity) can remove the relationship.
+     *
+     * @param entityId - Source entity ID
+     * @param relatedEntityId - Target entity ID
+     * @param removingUserId - User removing (must own either entity)
+     * @throws GraphNotFoundError if the relationship does not exist
+     * @throws GraphAuthorizationError if the user does not own either entity
+     */
+    removeEntityRelationship(entityId: string, relatedEntityId: string, removingUserId: string): Promise<void>;
+    /**
+     * Get all relationships for an entity, optionally filtered by type and status.
+     *
+     * @param entityId - Entity ID
+     * @param options - Optional filters
+     * @returns List of entity relationships
+     */
+    getEntityRelationships(entityId: string, options?: {
+        type?: string;
+        status?: EntityRelationshipStatus;
+    }): Promise<EntityRelationship[]>;
+    /**
+     * Get pending entity relationship requests that need confirmation.
+     *
+     * Returns relationships where the given user owns the target entity
+     * and the relationship is in PENDING status.
+     *
+     * @param userId - User who owns target entities
+     * @returns List of pending entity relationships
+     */
+    getPendingEntityRelationships(userId: string): Promise<EntityRelationship[]>;
+    /**
+     * Discover entities through multi-hop graph traversal.
+     *
+     * Starts from the user's owned entities and traverses entity-to-entity
+     * relationships (PLAYMATE, PACK_MATE, SIBLING, etc.) up to the specified
+     * number of hops. Only returns entities the user does NOT already have
+     * a relationship with.
+     *
+     * @param userId - The discovering user's ID
+     * @param hops - Maximum traversal depth (1-3, clamped)
+     * @param filters - Optional filters (entity type, breed, life stage)
+     * @returns List of discovered entities
+     */
+    discoverByGraph(userId: string, hops: number, filters?: DiscoveryFilters): Promise<DiscoveryResult[]>;
+    /**
+     * Discover entities by geographic proximity.
+     *
+     * Uses spatial indexing to find entities near the given coordinates.
+     * Only returns entities the user does NOT already have a relationship with.
+     *
+     * @param userId - The discovering user's ID (to exclude existing relationships)
+     * @param lat - Latitude
+     * @param lng - Longitude
+     * @param radiusMeters - Search radius in meters
+     * @param filters - Optional filters (entity type, breed)
+     * @returns List of discovered entities, sorted by distance ascending
+     */
+    discoverNearby(userId: string, lat: number, lng: number, radiusMeters: number, filters?: NearbyFilters): Promise<DiscoveryResult[]>;
+    /**
+     * Get entity recommendations based on graph analysis.
+     *
+     * Combines multiple signals: shared connections, breed similarity,
+     * geographic proximity, and owner proximity to generate a ranked
+     * list of entities the user might want to follow.
+     *
+     * @param userId - The user to generate recommendations for
+     * @param limit - Maximum number of recommendations
+     * @returns Ranked list of recommendations with reasons
+     */
+    getRecommendations(userId: string, limit: number): Promise<Recommendation[]>;
+    /**
+     * Record a user interaction for relationship scoring.
+     *
+     * Updates the interaction count, recency, and engagement depth signals
+     * on the RELATES_TO edge. Does NOT immediately recompute the score —
+     * that happens in `recomputeScores`.
+     *
+     * If no relationship exists between the user and target, this is a no-op
+     * (interactions only affect existing relationships).
+     *
+     * @param input - Interaction details
+     */
+    recordInteraction(input: RecordInteractionInput): Promise<void>;
+    /**
+     * Recompute scores for all of a user's relationships.
+     *
+     * Applies the scoring formula (target-type-aware: reciprocity-weighted
+     * for user targets, engagement-depth-weighted for entity targets) and
+     * updates the computedScore and tier on each RELATES_TO edge.
+     *
+     * This is typically run as a background job, not inline with requests.
+     *
+     * @param userId - User whose relationship scores to recompute
+     * @returns List of relationships where the tier changed
+     */
+    recomputeScores(userId: string): Promise<ScoreUpdate[]>;
+    /**
+     * Apply time-based decay to all of a user's relationship scores.
+     *
+     * Decay rates differ by target type:
+     * - User->User: 50% decay after 60 days of no interaction
+     * - User->Entity: 50% decay after 120 days of no interaction
+     *
+     * Owned entities (OWNS edges) are exempt from decay — they are always
+     * pinned at score 1.0 in tier 0.
+     *
+     * This is typically run as a scheduled job (e.g., daily cron).
+     *
+     * @param userId - User whose relationships to apply decay to
+     * @returns List of relationships where the tier changed due to decay
+     */
+    applyDecay(userId: string): Promise<ScoreUpdate[]>;
+    /**
+     * Sync a User node to the graph.
+     *
+     * Creates the node if it doesn't exist, or updates properties if it does.
+     * Called after Postgres user create/update.
+     *
+     * @param input - User data to sync
+     */
+    syncUser(input: SyncUserInput): Promise<void>;
+    /**
+     * Remove a User node and all its edges from the graph.
+     *
+     * Called after Postgres user deletion. Removes the User node and all
+     * connected RELATES_TO, OWNS, and reverse RELATES_TO edges.
+     *
+     * @param userId - User ID to remove
+     */
+    removeUser(userId: string): Promise<void>;
+    /**
+     * Sync an Entity node to the graph.
+     *
+     * Creates the node if it doesn't exist, or updates properties if it does.
+     * Called after Postgres entity create/update.
+     *
+     * @param input - Entity data to sync
+     */
+    syncEntity(input: SyncEntityInput): Promise<void>;
+    /**
+     * Remove an Entity node and all its edges from the graph.
+     *
+     * Called after Postgres entity deletion. Removes the Entity node and all
+     * connected edges (RELATES_TO pointing to it, OWNS, ABOUT, and
+     * entity-to-entity relationships).
+     *
+     * @param entityId - Entity ID to remove
+     */
+    removeEntity(entityId: string): Promise<void>;
+    /**
+     * Sync a Post node to the graph.
+     *
+     * Creates the node if it doesn't exist. Post nodes are reference-only —
+     * content stays in Postgres. The graph uses post nodes for visibility
+     * queries (matching post radius against viewer tier).
+     *
+     * @param input - Post data to sync
+     */
+    syncPost(input: SyncPostInput): Promise<void>;
+    /**
+     * Remove a Post node and its ABOUT edges from the graph.
+     *
+     * Called after Postgres post deletion.
+     *
+     * @param postId - Post ID to remove
+     */
+    removePost(postId: string): Promise<void>;
+    /**
+     * Sync PostSubject edges (Post -[:ABOUT]-> Entity).
+     *
+     * Replaces all existing ABOUT edges for the post with the given set.
+     * This is an idempotent "set" operation, not an incremental add.
+     *
+     * @param input - Post subject data to sync
+     */
+    syncPostSubjects(input: SyncPostSubjectsInput): Promise<void>;
+    /**
+     * Sync an EntityOwnership edge (User -[:OWNS]-> Entity).
+     *
+     * Creates or updates the OWNS edge with the given role.
+     * Also ensures the user has a RELATES_TO edge to the entity at score 1.0
+     * (auto-pinned to inner circle), since owned entities are always tier 0.
+     *
+     * @param input - Ownership data to sync
+     */
+    syncOwnership(input: SyncOwnershipInput): Promise<void>;
+    /**
+     * Remove an EntityOwnership edge.
+     *
+     * Called when ownership is revoked. Removes the OWNS edge but does NOT
+     * remove the RELATES_TO edge — the user may still want to follow the entity.
+     * The auto-pin at score 1.0 is removed; the computed score takes over.
+     *
+     * @param entityId - Entity ID
+     * @param userId - User ID
+     */
+    removeOwnership(entityId: string, userId: string): Promise<void>;
+}
+//# sourceMappingURL=graph-service.d.ts.map

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

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

package/dist/lib/graph/graph-service.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * GraphService Interface
+ *
+ * The abstraction layer between API handlers and the graph database.
+ * Implementations exist for:
+ * - Neo4j Community Edition (local development, bolt:// protocol)
+ * - Neo4j AuraDB (bolt+s:// over the Bolt protocol with password auth)
+ *
+ * Both backends support the Cypher query language. This interface
+ * exposes high-level operations — implementations translate them to
+ * Cypher queries internally.
+ *
+ * Handlers never execute raw graph queries. They call GraphService methods
+ * that return IDs, which are then used to fetch content from Postgres via Prisma.
+ *
+ * @see /analysis/redesign/07-graph-database/02-hybrid-architecture.md
+ * @see /analysis/redesign/07-graph-database/04-graph-schema.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=graph-service.js.map

package/dist/lib/graph/graph-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-service.js","sourceRoot":"","sources":["../../../src/lib/graph/graph-service.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/lib/graph/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Graph Service
+ *
+ * Abstraction layer between API handlers and the graph database
+ * (Neo4j AuraDB in dev/prod, Neo4j Community via Docker in local dev
+ * and integration tests).
+ *
+ * @example
+ * ```typescript
+ * import type { GraphService } from "./graph";
+ * import { GraphConnectionError } from "./graph";
+ *
+ * async function handleRequest(graphService: GraphService) {
+ *   try {
+ *     const relationship = await graphService.createRelationship({
+ *       userId: "user-123",
+ *       targetType: "entity",
+ *       targetId: "entity-456",
+ *       connectionMethod: "discovery",
+ *     });
+ *   } catch (error) {
+ *     if (error instanceof GraphConnectionError) {
+ *       // Graph database is down — return 503
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export type { GraphService, GraphConnection } from "./graph-service";
+export { Neo4jGraphService } from "./neo4j-graph-service";
+export { createGraphService, createGraphServiceFromEnv, type GraphServiceEnvConfig, } from "./graph-factory";
+export { initGraphSchema, verifyGraphSchema } from "./graph-schema-init";
+export type { DualWriteService, DualWriteConfig, DualWriteFailure, DualWriteOperation, DualWritePayload, DualWriteSyncResult, ReconciliationProgress, ReconciliationResult, ConsistencyCheckResult, } from "./dual-write";
+export { GraphSyncError } from "./dual-write";
+export { DualWriteServiceImpl } from "./dual-write-service";
+export { ReconciliationService } from "./reconciliation-service";
+export type { ConnectionMethod, PostRadius, CircleTier, TierName, GraphNodeType, EntityRelationshipType, OwnershipRole, InteractionType, EntityRelationshipStatus, RecommendationReason, GraphUser, GraphEntity, GraphPost, Relationship, CreateRelationshipInput, UpdateRelationshipScoreInput, CircleMember, CircleTierStatus, CircleEntityStatus, GlanceItem, VisiblePostResult, EntityRelationship, CreateEntityRelationshipInput, DiscoveryFilters, NearbyFilters, DiscoveryResult, Recommendation, RecordInteractionInput, ScoringWeights, ScoreUpdate, GraphData, GraphNode, TierSummary, SyncUserInput, SyncEntityInput, SyncPostInput, SyncPostSubjectsInput, SyncOwnershipInput, GraphConnectionConfig, GraphAuthConfig, GraphPoolConfig, GraphHealthStatus, PaginationInput, PaginatedResult, } from "./types";
+export { computeScore, effectiveScore, scoreToTier, computeDecay, computeEngagementDepth, computeFrequencySignal, connectionBonus, computeContentCreationSignal, computeOwnerProximity, USER_WEIGHTS, ENTITY_WEIGHTS, USER_DECAY_HALF_LIFE_DAYS, ENTITY_DECAY_HALF_LIFE_DAYS, ENGAGEMENT_SCORES, CONNECTION_BONUSES, TIER_THRESHOLDS, type InteractionCounts, type ScoringInput, } from "./scoring-engine";
+export { GraphError, GraphConnectionError, GraphQueryError, GraphNotFoundError, GraphConflictError, GraphAuthorizationError, GraphTimeoutError, } from "./errors";
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/graph/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/graph/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGzE,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAGjE,YAAY,EAEV,gBAAgB,EAChB,UAAU,EACV,UAAU,EACV,QAAQ,EACR,aAAa,EACb,sBAAsB,EACtB,aAAa,EACb,eAAe,EACf,wBAAwB,EACxB,oBAAoB,EAEpB,SAAS,EACT,WAAW,EACX,SAAS,EAET,YAAY,EACZ,uBAAuB,EACvB,4BAA4B,EAE5B,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,UAAU,EACV,iBAAiB,EAEjB,kBAAkB,EAClB,6BAA6B,EAE7B,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,cAAc,EAEd,sBAAsB,EACtB,cAAc,EACd,WAAW,EAEX,SAAS,EACT,SAAS,EACT,WAAW,EAEX,aAAa,EACb,eAAe,EACf,aAAa,EACb,qBAAqB,EACrB,kBAAkB,EAElB,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,iBAAiB,EAEjB,eAAe,EACf,eAAe,GAChB,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,YAAY,EACZ,cAAc,EACd,WAAW,EACX,YAAY,EACZ,sBAAsB,EACtB,sBAAsB,EACtB,eAAe,EACf,4BAA4B,EAC5B,qBAAqB,EACrB,YAAY,EACZ,cAAc,EACd,yBAAyB,EACzB,2BAA2B,EAC3B,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,KAAK,iBAAiB,EACtB,KAAK,YAAY,GAClB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,UAAU,EACV,oBAAoB,EACpB,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,UAAU,CAAC"}

package/dist/lib/graph/index.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Graph Service
+ *
+ * Abstraction layer between API handlers and the graph database
+ * (Neo4j AuraDB in dev/prod, Neo4j Community via Docker in local dev
+ * and integration tests).
+ *
+ * @example
+ * ```typescript
+ * import type { GraphService } from "./graph";
+ * import { GraphConnectionError } from "./graph";
+ *
+ * async function handleRequest(graphService: GraphService) {
+ *   try {
+ *     const relationship = await graphService.createRelationship({
+ *       userId: "user-123",
+ *       targetType: "entity",
+ *       targetId: "entity-456",
+ *       connectionMethod: "discovery",
+ *     });
+ *   } catch (error) {
+ *     if (error instanceof GraphConnectionError) {
+ *       // Graph database is down — return 503
+ *     }
+ *   }
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GraphTimeoutError = exports.GraphAuthorizationError = exports.GraphConflictError = exports.GraphNotFoundError = exports.GraphQueryError = exports.GraphConnectionError = exports.GraphError = exports.TIER_THRESHOLDS = exports.CONNECTION_BONUSES = exports.ENGAGEMENT_SCORES = exports.ENTITY_DECAY_HALF_LIFE_DAYS = exports.USER_DECAY_HALF_LIFE_DAYS = exports.ENTITY_WEIGHTS = exports.USER_WEIGHTS = exports.computeOwnerProximity = exports.computeContentCreationSignal = exports.connectionBonus = exports.computeFrequencySignal = exports.computeEngagementDepth = exports.computeDecay = exports.scoreToTier = exports.effectiveScore = exports.computeScore = exports.ReconciliationService = exports.DualWriteServiceImpl = exports.GraphSyncError = exports.verifyGraphSchema = exports.initGraphSchema = exports.createGraphServiceFromEnv = exports.createGraphService = exports.Neo4jGraphService = void 0;
+// Implementations
+var neo4j_graph_service_1 = require("./neo4j-graph-service");
+Object.defineProperty(exports, "Neo4jGraphService", { enumerable: true, get: function () { return neo4j_graph_service_1.Neo4jGraphService; } });
+var graph_factory_1 = require("./graph-factory");
+Object.defineProperty(exports, "createGraphService", { enumerable: true, get: function () { return graph_factory_1.createGraphService; } });
+Object.defineProperty(exports, "createGraphServiceFromEnv", { enumerable: true, get: function () { return graph_factory_1.createGraphServiceFromEnv; } });
+var graph_schema_init_1 = require("./graph-schema-init");
+Object.defineProperty(exports, "initGraphSchema", { enumerable: true, get: function () { return graph_schema_init_1.initGraphSchema; } });
+Object.defineProperty(exports, "verifyGraphSchema", { enumerable: true, get: function () { return graph_schema_init_1.verifyGraphSchema; } });
+var dual_write_1 = require("./dual-write");
+Object.defineProperty(exports, "GraphSyncError", { enumerable: true, get: function () { return dual_write_1.GraphSyncError; } });
+var dual_write_service_1 = require("./dual-write-service");
+Object.defineProperty(exports, "DualWriteServiceImpl", { enumerable: true, get: function () { return dual_write_service_1.DualWriteServiceImpl; } });
+var reconciliation_service_1 = require("./reconciliation-service");
+Object.defineProperty(exports, "ReconciliationService", { enumerable: true, get: function () { return reconciliation_service_1.ReconciliationService; } });
+// Scoring engine
+var scoring_engine_1 = require("./scoring-engine");
+Object.defineProperty(exports, "computeScore", { enumerable: true, get: function () { return scoring_engine_1.computeScore; } });
+Object.defineProperty(exports, "effectiveScore", { enumerable: true, get: function () { return scoring_engine_1.effectiveScore; } });
+Object.defineProperty(exports, "scoreToTier", { enumerable: true, get: function () { return scoring_engine_1.scoreToTier; } });
+Object.defineProperty(exports, "computeDecay", { enumerable: true, get: function () { return scoring_engine_1.computeDecay; } });
+Object.defineProperty(exports, "computeEngagementDepth", { enumerable: true, get: function () { return scoring_engine_1.computeEngagementDepth; } });
+Object.defineProperty(exports, "computeFrequencySignal", { enumerable: true, get: function () { return scoring_engine_1.computeFrequencySignal; } });
+Object.defineProperty(exports, "connectionBonus", { enumerable: true, get: function () { return scoring_engine_1.connectionBonus; } });
+Object.defineProperty(exports, "computeContentCreationSignal", { enumerable: true, get: function () { return scoring_engine_1.computeContentCreationSignal; } });
+Object.defineProperty(exports, "computeOwnerProximity", { enumerable: true, get: function () { return scoring_engine_1.computeOwnerProximity; } });
+Object.defineProperty(exports, "USER_WEIGHTS", { enumerable: true, get: function () { return scoring_engine_1.USER_WEIGHTS; } });
+Object.defineProperty(exports, "ENTITY_WEIGHTS", { enumerable: true, get: function () { return scoring_engine_1.ENTITY_WEIGHTS; } });
+Object.defineProperty(exports, "USER_DECAY_HALF_LIFE_DAYS", { enumerable: true, get: function () { return scoring_engine_1.USER_DECAY_HALF_LIFE_DAYS; } });
+Object.defineProperty(exports, "ENTITY_DECAY_HALF_LIFE_DAYS", { enumerable: true, get: function () { return scoring_engine_1.ENTITY_DECAY_HALF_LIFE_DAYS; } });
+Object.defineProperty(exports, "ENGAGEMENT_SCORES", { enumerable: true, get: function () { return scoring_engine_1.ENGAGEMENT_SCORES; } });
+Object.defineProperty(exports, "CONNECTION_BONUSES", { enumerable: true, get: function () { return scoring_engine_1.CONNECTION_BONUSES; } });
+Object.defineProperty(exports, "TIER_THRESHOLDS", { enumerable: true, get: function () { return scoring_engine_1.TIER_THRESHOLDS; } });
+// Errors
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "GraphError", { enumerable: true, get: function () { return errors_1.GraphError; } });
+Object.defineProperty(exports, "GraphConnectionError", { enumerable: true, get: function () { return errors_1.GraphConnectionError; } });
+Object.defineProperty(exports, "GraphQueryError", { enumerable: true, get: function () { return errors_1.GraphQueryError; } });
+Object.defineProperty(exports, "GraphNotFoundError", { enumerable: true, get: function () { return errors_1.GraphNotFoundError; } });
+Object.defineProperty(exports, "GraphConflictError", { enumerable: true, get: function () { return errors_1.GraphConflictError; } });
+Object.defineProperty(exports, "GraphAuthorizationError", { enumerable: true, get: function () { return errors_1.GraphAuthorizationError; } });
+Object.defineProperty(exports, "GraphTimeoutError", { enumerable: true, get: function () { return errors_1.GraphTimeoutError; } });
+//# sourceMappingURL=index.js.map

package/dist/lib/graph/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/graph/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;;;AAKH,kBAAkB;AAClB,6DAA0D;AAAjD,wHAAA,iBAAiB,OAAA;AAC1B,iDAIyB;AAHvB,mHAAA,kBAAkB,OAAA;AAClB,0HAAA,yBAAyB,OAAA;AAG3B,yDAAyE;AAAhE,oHAAA,eAAe,OAAA;AAAE,sHAAA,iBAAiB,OAAA;AAc3C,2CAA8C;AAArC,4GAAA,cAAc,OAAA;AACvB,2DAA4D;AAAnD,0HAAA,oBAAoB,OAAA;AAC7B,mEAAiE;AAAxD,+HAAA,qBAAqB,OAAA;AA6D9B,iBAAiB;AACjB,mDAmB0B;AAlBxB,8GAAA,YAAY,OAAA;AACZ,gHAAA,cAAc,OAAA;AACd,6GAAA,WAAW,OAAA;AACX,8GAAA,YAAY,OAAA;AACZ,wHAAA,sBAAsB,OAAA;AACtB,wHAAA,sBAAsB,OAAA;AACtB,iHAAA,eAAe,OAAA;AACf,8HAAA,4BAA4B,OAAA;AAC5B,uHAAA,qBAAqB,OAAA;AACrB,8GAAA,YAAY,OAAA;AACZ,gHAAA,cAAc,OAAA;AACd,2HAAA,yBAAyB,OAAA;AACzB,6HAAA,2BAA2B,OAAA;AAC3B,mHAAA,iBAAiB,OAAA;AACjB,oHAAA,kBAAkB,OAAA;AAClB,iHAAA,eAAe,OAAA;AAKjB,SAAS;AACT,mCAQkB;AAPhB,oGAAA,UAAU,OAAA;AACV,8GAAA,oBAAoB,OAAA;AACpB,yGAAA,eAAe,OAAA;AACf,4GAAA,kBAAkB,OAAA;AAClB,4GAAA,kBAAkB,OAAA;AAClB,iHAAA,uBAAuB,OAAA;AACvB,2GAAA,iBAAiB,OAAA"}