infra: Add Neptune cluster for the relationship graph

[ottlseo]

Sub-issue of #1.

Goal

Replace data/world.json as the system of record for the relationship graph with an Amazon Neptune cluster, provisioned as code in the existing CDK app under infra/.

This issue covers infrastructure and the access path only. Rewriting the inference engine and the probe queries against Neptune is tracked separately.

Why Neptune instead of the JSON file

The in-memory triple store was written so the concepts map 1:1 to a graph database. It stops being viable at three points:

• Inference is a full join over every triple. Rules like allied_by_faction and shared_past produce O(n^2) edges, so the whole graph has to be materialized in memory on every load.
• There is no concurrent write path. Story writeback rewrites the entire file, so two generation rounds cannot run at once.
• khop() and shortest_path() are hand-rolled BFS. Neptune does this natively and keeps working past a few hundred nodes.

Graph model decision

Neptune supports both a property graph (openCypher / Gremlin) and RDF (SPARQL). The two are stored separately and cannot be queried across.

Recommendation: property graph, queried with openCypher.

• Edges in the current model carry properties (tension, cause, derived_by, hidden_role). In RDF a triple cannot hold properties without reification, which would roughly triple the statement count and make every query harder to read.
• Triple(s, p, o, props) maps directly to (:Node)-[:P {props}]->(:Node).
• The inference rules are shaped like SPARQL basic graph patterns, but each one translates mechanically to a Cypher MATCH plus MERGE, so the SPARQL resemblance is not a reason to pick RDF.

Open question: if OWL/RDFS reasoning is wanted later, RDF is the only option. Neptune has no built-in inference engine in either mode, so this is not a strong argument today.

Instance sizing decision

Provisioned instances, not serverless.

Neptune Serverless never pauses. The configured minimum capacity is billed continuously, so a cluster idling at 1.0 NCU costs more per month than a burstable provisioned instance. This workload is queried in bursts during demos and development with long idle stretches in between, which is the case where provisioned wins.

• Writer: db.t4g.medium, single instance, no reader
• Add a reader in a second AZ only when read load or availability requires it
• Resizing is a modify-db-instance plus reboot, acceptable at this stage

Consequence to plan around: a burstable class earns CPU credits. The inference pass is a sustained join, so a full re-materialization of derived edges can exhaust credits and throttle. If that shows up, the fix is db.r6g.large, not serverless.

Verify the class is orderable in the target region before merging. Neptune has only two burstable classes and db.t4g.medium is missing in some regions:

aws neptune describe-orderable-db-instance-options \
  --engine neptune --region <region> \
  --query "OrderableDBInstanceOptions[?starts_with(DBInstanceClass,'db.t')].DBInstanceClass" \
  --output text | tr '\t' '\n' | sort -u

Access path

Neptune has no public endpoint and lives only inside a VPC. This has one consequence that shapes the whole change: AppSync JS resolvers cannot reach it. Resolvers run inside the AppSync service, and AppSync HTTP data sources have no VPC attachment.

So the graph has to be fronted by a Lambda function placed in the VPC, exposed to AppSync as a Lambda data source. Today every data source in infra/lib/storyboard-stack.js is a JS resolver over DynamoDB or Bedrock, so this adds the first VPC and the first Lambda to the stack. That is the main cost and complexity increase in this issue, and it is unavoidable if the graph moves to Neptune.

Scope

Infrastructure as code, CDK in JavaScript, in the existing infra/ app:

• VPC with two private isolated subnets across two AZs, plus one public subnet for the bastion. The Neptune subnet group needs two AZs even though only one instance is created.
• Neptune cluster
  • Engine version 1.3.x or later
  • One writer instance, class db.t4g.medium
  • Instance class exposed as a CDK context value so it can be raised without editing the stack
  • Backup retention 1 day for the PoC, deletionProtection: false
• Encryption at rest with a customer managed KMS key, TLS enforced in transit
• IAM database authentication enabled, so no password is stored anywhere. Callers sign requests with SigV4 against neptune-db:* actions scoped to the cluster resource id.
• Security group allowing port 8182 only from the Lambda security group and the bastion security group
• Graph query Lambda in the private subnets, with an execution role granting neptune-db:ReadDataViaQuery and neptune-db:WriteDataViaQuery
• Register the Lambda as an AppSync data source and add the corresponding field to infra/schema.graphql
• S3 gateway VPC endpoint. The Neptune bulk loader pulls from S3 over the VPC, and without the endpoint the load fails since there is no NAT gateway.
• IAM role attached to the cluster granting read on the load bucket
• Parameter group with neptune_enable_audit_log = 1
• CloudWatch alarms on CPUUtilization, CPUCreditBalance (burstable class), and MainRequestQueuePendingRequests
• Outputs: writer endpoint, reader endpoint, port, cluster resource id, VPC id, Lambda security group id

Local development access:

• Bastion host with SSM Session Manager, no SSH key and no inbound rule. Port forward 8182 with aws ssm start-session --document-name AWS-StartPortForwardingSessionToRemoteHost.
• Document the tunnel command in the repo README

Cost control:

• scripts/stop.sh and scripts/start.sh wrapping stop-db-cluster and start-db-cluster. Stopping halts instance billing while storage keeps accruing.
• Note in the README that a stopped Neptune cluster restarts automatically after 7 days, so stopping is not a substitute for teardown
• Avoid a NAT gateway. Use gateway and interface VPC endpoints for the services the Lambda needs, since a NAT gateway would cost more than the database instance.

Loading:

• Converter from data/world.json to openCypher bulk load CSV (:ID, :LABEL for nodes; :START_ID, :END_ID, :TYPE for edges)
• scripts/load.sh that uploads to S3 and calls the loader endpoint
• Decide whether derived edges are loaded or recomputed. Proposal: load asserted edges only and recompute derived edges in Neptune, so derived_by provenance stays trustworthy.

Out of scope

Tracked as follow-up issues:

• Replace WorldGraph with an openCypher client, keeping match(), khop(), shortest_path(), and apply_writeback() as the interface
• Translate the JSON inference rules to Cypher MERGE statements, deciding per rule whether it materializes on write or expands at query time
• Multi-world tenancy: a world property on every node, or one database per world

Acceptance criteria

• cdk deploy produces a reachable cluster with no manual console steps
• data/world.json loads with node and edge counts matching the source file (27 nodes and 52 asserted edges in the current PoC), verified by a count query through the SSM tunnel
• The graph query Lambda returns the same result as the in-memory store for at least one khop() and one shortest_path() case
• scripts/stop.sh drops instance billing to zero, confirmed in Cost Explorer
• cdk destroy leaves no billable resources behind

[ottlseo]

한국어 요약

#1 의 하위 이슈입니다.

목표

관계 그래프의 정본을 data/world.json 에서 Amazon Neptune 클러스터로 옮기고, infra/ 의 기존 CDK 앱에 코드로 프로비저닝합니다.

이 이슈는 인프라와 접근 경로까지만 다룹니다. 추론 엔진과 탐지기 쿼리를 Neptune 기준으로 다시 쓰는 작업은 별도 이슈로 관리합니다.

JSON 파일이 아니라 Neptune을 쓰는 이유

인메모리 트리플 스토어는 개념이 그래프DB와 1:1로 대응되도록 만들었습니다. 세 지점에서 한계가 옵니다.

• 추론이 전체 트리플에 대한 전수 조인입니다. allied_by_faction, shared_past 같은 규칙이 O(n^2) 엣지를 만들어서, 적재할 때마다 그래프 전체를 메모리에 펼쳐야 합니다.
• 동시 쓰기 경로가 없습니다. 스토리 역기입이 파일 전체를 다시 쓰기 때문에 생성 회차 두 개를 같이 돌릴 수 없습니다.
• khop() 과 shortest_path() 가 직접 구현한 BFS입니다. Neptune은 이걸 기본으로 제공하고 노드 수백 개를 넘겨도 동작합니다.

그래프 모델 결정

Neptune은 프로퍼티 그래프(openCypher / Gremlin)와 RDF(SPARQL)를 모두 지원합니다. 두 저장소는 분리되어 있고 서로 교차 쿼리가 되지 않습니다.

권고: 프로퍼티 그래프, openCypher로 쿼리.

• 현재 모델의 엣지가 속성을 들고 있습니다 (tension, cause, derived_by, hidden_role). RDF에서는 리이피케이션 없이 트리플에 속성을 붙일 수 없고, 그러면 스테이트먼트 수가 대략 세 배가 되면서 모든 쿼리가 읽기 어려워집니다.
• Triple(s, p, o, props) 가 (:Node)-[:P {props}]->(:Node) 로 그대로 대응됩니다.
• 추론 규칙이 SPARQL 기본 그래프 패턴 형태이긴 하지만, 각 규칙이 Cypher MATCH + MERGE 로 기계적으로 번역됩니다. 형태가 닮았다는 게 RDF를 고를 근거는 아닙니다.

열린 질문: 나중에 OWL/RDFS 추론이 필요해지면 RDF만이 선택지입니다. 다만 Neptune은 두 모드 모두 내장 추론 엔진이 없어서 지금은 강한 근거가 아닙니다.

인스턴스 사이징 결정

서버리스가 아니라 프로비저닝 인스턴스로 갑니다.

Neptune 서버리스는 정지하지 않습니다. 설정한 최소 용량이 계속 과금되므로, 1.0 NCU로 유휴 상태인 클러스터가 버스터블 프로비저닝 인스턴스보다 월 비용이 큽니다. 이 워크로드는 데모와 개발 중에 몰아서 쿼리되고 사이사이 유휴 구간이 길어서, 프로비저닝이 유리한 경우입니다.

• 라이터: db.t4g.medium 단일 인스턴스, 리더 없음
• 읽기 부하나 가용성 요구가 생길 때만 두 번째 AZ에 리더 추가
• 리사이즈는 modify-db-instance + 리부트. 현 단계에서는 감당 가능

감안할 점: 버스터블 클래스는 CPU 크레딧을 적립합니다. 추론 패스는 지속적인 조인이라 파생 엣지를 전면 재계산하면 크레딧이 소진되어 스로틀될 수 있습니다. 그 상황이 오면 해법은 db.r6g.large 이고, 서버리스가 아닙니다.

머지 전에 대상 리전에서 해당 클래스가 주문 가능한지 확인해야 합니다. Neptune 버스터블 클래스는 두 개뿐이고 일부 리전에는 db.t4g.medium 이 없습니다.

aws neptune describe-orderable-db-instance-options \
  --engine neptune --region <region> \
  --query "OrderableDBInstanceOptions[?starts_with(DBInstanceClass,'db.t')].DBInstanceClass" \
  --output text | tr '\t' '\n' | sort -u

접근 경로

Neptune은 퍼블릭 엔드포인트가 없고 VPC 안에만 존재합니다. 여기서 이 변경 전체의 모양을 결정하는 결과가 하나 나옵니다. AppSync JS 리졸버로는 닿을 수 없습니다. 리졸버는 AppSync 서비스 내부에서 실행되고, AppSync HTTP 데이터소스에는 VPC 연결이 없습니다.

따라서 그래프 앞에 VPC 안에 배치된 Lambda를 두고, 그것을 AppSync에 Lambda 데이터소스로 노출해야 합니다. 현재 infra/lib/storyboard-stack.js 의 데이터소스는 전부 DynamoDB나 Bedrock 위의 JS 리졸버라서, 이 작업으로 스택에 첫 VPC와 첫 Lambda가 들어옵니다. 이 이슈에서 비용과 복잡도가 늘어나는 주된 지점이고, 그래프를 Neptune으로 옮기는 한 피할 수 없습니다.

작업 범위

infra/ 기존 앱 안, CDK JavaScript:

• 2개 AZ에 걸친 프라이빗 격리 서브넷 2개, 배스천용 퍼블릭 서브넷 1개로 VPC 구성. 인스턴스는 하나만 만들더라도 Neptune 서브넷 그룹에는 AZ 2개가 필요합니다.
• Neptune 클러스터
  • 엔진 버전 1.3.x 이상
  • 라이터 인스턴스 1개, 클래스 db.t4g.medium
  • 인스턴스 클래스를 CDK 컨텍스트 값으로 노출해서 스택 수정 없이 올릴 수 있게
  • PoC용 백업 보존 1일, deletionProtection: false
• 고객 관리형 KMS 키로 저장 시 암호화, 전송 구간 TLS 강제
• IAM 데이터베이스 인증 활성화. 비밀번호를 어디에도 저장하지 않습니다. 호출자는 클러스터 리소스 id로 범위가 좁혀진 neptune-db:* 액션에 SigV4로 서명합니다.
• 8182 포트를 Lambda 보안 그룹과 배스천 보안 그룹에서만 허용하는 보안 그룹
• 프라이빗 서브넷에 그래프 쿼리 Lambda 배치. 실행 역할에 neptune-db:ReadDataViaQuery 와 neptune-db:WriteDataViaQuery 부여
• Lambda를 AppSync 데이터소스로 등록하고 infra/schema.graphql 에 해당 필드 추가
• S3 게이트웨이 VPC 엔드포인트. Neptune 벌크 로더가 VPC를 통해 S3에서 당겨오는데, NAT 게이트웨이가 없으므로 엔드포인트가 없으면 적재가 실패합니다.
• 로드 버킷 읽기 권한을 가진 IAM 역할을 클러스터에 연결
• neptune_enable_audit_log = 1 파라미터 그룹
• CPUUtilization, CPUCreditBalance(버스터블 클래스), MainRequestQueuePendingRequests 에 CloudWatch 알람
• 출력값: 라이터 엔드포인트, 리더 엔드포인트, 포트, 클러스터 리소스 id, VPC id, Lambda 보안 그룹 id

로컬 개발 접근:

• SSM Session Manager 배스천. SSH 키 없음, 인바운드 룰 없음. aws ssm start-session --document-name AWS-StartPortForwardingSessionToRemoteHost 로 8182 포워딩
• 터널 커맨드를 레포 README에 문서화

비용 통제:

• stop-db-cluster / start-db-cluster 를 감싼 scripts/stop.sh, scripts/start.sh. 정지하면 인스턴스 과금이 멈추고 스토리지는 계속 쌓입니다.
• 정지된 Neptune 클러스터는 7일 후 자동으로 재시작되므로 정지가 철거의 대체가 아니라는 점을 README에 명시
• NAT 게이트웨이를 쓰지 않습니다. Lambda가 필요한 서비스에는 게이트웨이/인터페이스 VPC 엔드포인트를 씁니다. NAT 게이트웨이는 DB 인스턴스보다 비쌉니다.

적재:

• data/world.json 을 openCypher 벌크 로드 CSV로 변환 (노드는 :ID, :LABEL, 엣지는 :START_ID, :END_ID, :TYPE)
• S3에 올리고 로더 엔드포인트를 호출하는 scripts/load.sh
• 파생 엣지를 적재할지 재계산할지 결정. 제안: 명시 엣지만 적재하고 파생 엣지는 Neptune에서 재계산해서 derived_by 프로버넌스의 신뢰성을 유지

범위 밖

후속 이슈로 관리:

• WorldGraph 를 openCypher 클라이언트로 교체하되 match(), khop(), shortest_path(), apply_writeback() 인터페이스는 유지
• JSON 추론 규칙을 Cypher MERGE 문으로 번역. 규칙별로 쓰기 시 머티리얼라이즈할지 쿼리 시 확장할지 결정
• 멀티 월드 테넌시: 모든 노드에 world 속성을 두거나 월드당 데이터베이스 하나

완료 조건

• cdk deploy 로 콘솔 수동 작업 없이 접근 가능한 클러스터가 생성됨
• data/world.json 이 원본 파일과 같은 노드/엣지 수로 적재됨 (현 PoC 기준 노드 27개, 명시 엣지 52개). SSM 터널을 통한 카운트 쿼리로 확인
• 그래프 쿼리 Lambda가 khop() 1건, shortest_path() 1건 이상에서 인메모리 스토어와 같은 결과를 반환
• scripts/stop.sh 로 인스턴스 과금이 0이 되는 것을 Cost Explorer에서 확인
• cdk destroy 후 남는 과금 리소스가 없음