아키텍처 결정 누적 기록

다음 두 SSOT 파일에 결정이 누적되어 있고, 본 페이지는 그 요약입니다. 변경 발생 시 그쪽 파일이 우선이고 본 페이지는 후행 정리:

• /Users/axe/multi-tenant-platform-plan.md  — 마스터 플랫폼 plan + D 결정 + 함정
• /Users/axe/frame/DECISIONS.md  — frame 측 D-ops-1 ~ 15

D — 플랫폼 결정

D-ops — frame 운영 결정

D-bp-mcp-1 — Blueprint MCP standalone (양파껍질 lesson)

Blueprint 자신의 read-only MCP 서버 launch (axe.axelabs.ai/blueprint/mcp, 9 tools). 의도: frame 의 auth_oidc.py + mcp/http_server.py 를 byte-by-byte 미러. 실제: “비슷하게” 작성 → claude.ai 등록 시 5 단계 순차 차단 (PR #331~#335, 약 1.5 h 소비):

결정: 새 MCP 서버는 /architecture/mcp-server-checklist 의 9·5·5·14 체크포인트 (azure manifest 9 · python 코드 5 · compose 5 · 운영 14) 를 1:1 통과 후 production. 시작은 cp -R frame/src/frame /tmp/NEW_SERVICE 부터, 그 다음 service-specific edits.

D-bp-mcp-2 — Blueprint MCP blue/green pair

D-bp-mcp-1 launch 직후 진단으로 발견: Blueprint MCP 는 frame/hive 의 docker compose 패턴 (&frame-mcp-blue anchor + green sibling) 을 미러하지 않은 단일 replica 였음. docker compose up -d --build mcp 시 build + recreate 5-10s 다운 발생 — D-config-13 의 “다운타임 0 frame deploy” 원칙에 어긋남.

결정: docker/docker-compose.yml 의 mcp: 블록을 mcp-blue: &blueprint-mcp-blue + mcp-green 으로 분리. blue 가 docker network alias blueprint-mcp 보유 (active), green 은 alias 없이 가동 (passive). swap = docker network connect/disconnect --alias + caddy reload, sub-second. cloudflared 비건드림 (D-config-13 §3 frame 패턴과 동일).

host port: blueprint-mcp-blue:3152, blueprint-mcp-green:3153 (디버그용, 외부 path 는 여전히 :3151 Caddy proxy).

D-bp-entity-1 — Blueprint entity 개념 도입 (PARA × entity)

진단 (2026-05-21 5분야 멀티 에이전트): Blueprint 의 Organization 모델이 single-row stub (prisma/schema.prisma:689), Workspace/UsageLog/Agent 에 organization FK 부재 (line 688 “별도 PR” 주석). 동시 customers.yaml 의 axe.entities: ["axec","axev"] (frame/hive 와 정합) 은 이미 회계/HR 차원에서 격리 운영 중. Blueprint 의 PARA 폴더 컨벤션 (/Ventures · /Corporation · /General × 1. Project · 2. Area · 3. Resource · 4. Archive) 도 entity 차원의 격리를 함의.

결정:

Implementation (PR #339 , 2026-05-22, 단일 PR 4 commit):

1. Prisma migration: Entity 모델 + ParaLayer enum + Workspace.entityId/paraLayer + D-bp-entity-2 provenance 3필드 + User.entityScopes. Idempotent SQL + axec/axev seed. Postgres baseline 부재 → scripts/apply-entity-para-migration.ts 운영자 1회 적용 후 매 boot seed-entities.ts 가 idempotent upsert.
2. drivePath 기반 backfill (scripts/backfill-workspace-entity-para.ts): /Ventures/... → entityId=axev, /Corporation/... → entityId=axec, paraLayer = 1_Project/2_Area/3_Resource/4_Archive segment match. dry-run + apply 분리.
3. src/lib/entity-scopes.ts (resolve/hydrate/get/require + entityScopeWhereFilter) + src/lib/auth.ts signIn hydration + src/lib/workspace.ts listWorkspaces opt 확장 + /api/workspaces/* 게이트.
4. UI: /axe/projects entity dropdown + 항상 paraLayer=PROJECT fetch / /axe/ara stub → ARAClient 3-tab + fork badge.

사용자 결정 (2026-05-22): Workspace ↔ Entity = scalar 1:N (OneDrive /Ventures/ /Corporation/ 폴더 분리가 SOT, cross-entity 는 User.entityScopes 로 처리). frame fund 회계 N:M 권고는 reject.

Production hotfix (PR #341 , 2026-05-22): verification 중 발견한 3 drift — (a) docker-compose.yml app-green block 에 customers.yaml mount + CUSTOMERS_YAML_PATH env 누락 (blue 만 있던 mount 가 cutover 시 옮겨지지 않아 entityScopes hydration 항상 admin-fallback), (b) scripts/apply-entity-para-migration.ts 의 header comment 안 $$ 가 splitter inDollar flag 오염 → P2010, (c) backfill regex [.\s] 에 underscore 추가 (1_Project 매치).

Production 결과: Entity 2 row (axec/axev seed) · Workspace 18 row 중 16 backfill 적용 (PROJECT × axec: 1 / PROJECT × axev: 14 / PROJECT × null: 2 / AREA × axev: 1 [HR]) · 5 user entityScopes hydrate · Chrome MCP /axe/projects + /axe/ara 검증 PASS.

D-bp-entity-2 — PARA dispatch flow sub-consensus

D-bp-entity-1 머지 후 Project 종결 → Area/Resource 이관 (dispatch) 흐름. 본 결정은 dispatch UI (PR #339  의 schema 까지만 포함, UI 는 PR 5 예정) 의 4 합의:

미해결 (dispatch UI PR 직전 결정): (a) Dispatch unit (file vs semantic chunk), (b) Area instance 정의 권한 (org-admin vs free), (c) 정비 트리거 우선순위 (manual / periodic / LLM-detected staleness). 권고 경로: Path B Spike (DB 변경 없이 단일 workspace 로 흐름 검증 3-5일) → Path A 본구현 (Area/Resource UI + dispatch modal + archive search separation).

관련 진단: /Users/axe/.claude/projects/-Users-axe-blueprint/memory/feedback_multi_agent_diagnosis_2026_05_21.md

D-bp-para-1 — PARA 범용 재구조화 (조직론 + 집(link) 모델 + governance + 죽은 딜 본질)

D-bp-entity-1/D-bp-entity-2 의 AXE-shaped 초기 설계(copy-with-provenance · Area=workspace)를 범용 AI OS 관점으로 재구조화 (2026-06-06 설계 세션). 상세·철학 = /architecture/para-os. 미구현 dispatch/UX zone 한정 — 저장층(Artifact/ArtifactLink/McpSchema, PR #339 ) schema 는 유효.

확정 결정:

1. PARA = 조직론 — Area=영속 기능(정적 조직, MCP=물질화), Project=cross-functional TFT(동적 조직). Resource·Archive 는 각 Area 안, Project 만 가로지름.
2. dispatch = “집(home)” 모델 — move/copy/link 3지선다는 폴더-thinking 증상. artifact 몸통 1 + 집 N(link). link=기본(다중 Area 참조), move=소모성 working→Archive→폐기, copy-curate=재사용본 저작→Resource. → D-bp-entity-2 의 copy-with-provenance default 를 link-default 로 revise (copy 는 method→Resource 큐레이션 예외만).
3. Blueprint = 도메인 서비스가 안 덮는 것의 substrate (미졸업·무서비스 Area live + 그 R/A + cross-service 종합물 + 가로 결정로그 mirror). 졸업 서비스(frame/hive/index/gate)는 자기 도메인 지식(죽은 딜·섹터 프레임 등 R/A 포함)을 가져감 — moat(죽은 딜 복리) = index. Area 졸업 트리거 = 도메인 로직/AI 상호작용(저장 아님). [정정 2026-06-06: 원안 “모든 R/A → Blueprint” 를 졸업 기준으로 좁힘 (사용자 확정), 상세 para-os §4]
4. substrate 3분 — typed Area=쿼리 / Resource=SoR+벡터 index(hot) / Archive=cold·폐기가능(추출 지식만 영구·queryable). 벡터=저장소 아닌 index.
5. Governance 분리 — 결정로그(record: Blueprint core, append-only, supersede, 모든 Area cite) vs 결재워크플로(process: 전자결재, policy-driven·agent-assisted layer). 서명 한 종류(내부=외부 e-sign). Area 서비스=결정 actuator. 통합 구현=B-bp-decision-pipeline-esign.
6. 본질 = 죽은 딜 저장·harvest — VC 지식의 대부분이 dead deal(judgment “왜 패스” + 섹터지식)에. Archive raw=폐기 가능하되 추출 지식=영구. index 가 passed/dead 딜을 1급 저장해야 하는 근거.

열린 질문 (확정 시 후속 D 등재): (a) 2-level scope(personal+shared), (b) governance servicization(Blueprint core vs 독립 서비스 — 부족함 진단 저장/로직/AI 로 가름), (c) Project staffing, (d) Rust 적용 범위(기존 Python 서비스 확장 언어).

제약: 신규 코드 = Rust (사용자 지침). SoT 메모 = project_para_ai_os_philosophy.md (Blueprint global memory).

D-bp-rust-1 — Blueprint 점진 Rust 전환 (strangler-fig) · substrate = 첫 organ

D-bp-para-1 의 열린 질문 (a)/(c)/(d) 를 확정하고, “신규 코드 = Rust” 지침을 Blueprint 토폴로지에 정착 (2026-06-06 세션). 사용자 발화: “점차 blueprint 도 rust 로 전환할 계획입니다 … 점진적 대체로 하려고 합니다.”

전략 — strangler-fig (점진 대체):

1. 프론트엔드(React/Next.js UI) = 당분간 TS 유지. “Blueprint→Rust” = 백엔드 전환이지 UI 재작성이 아님. WASM 프론트(Leptos/Dioxus) 전면 재작성은 별개·먼 결정 (현재 scope 아님). → 열린질문 (d) 확정: Rust 범위 = 신규 백엔드 organ, 프론트 제외.
2. 백엔드(API routes + src/lib/* 로직) = 도메인별 Rust(axum) organ 으로 점진 추출. Next.js 는 점점 얇은 frontend-of-record 로 후퇴, Rust 를 내부 HTTP 호출.
3. 데이터 공존 = Postgres schema-split 소유권 (“두 ORM 한 DB” 를 안전하게): Prisma=public(Workspace/Entity/User/Session/Issue…), Rust/sqlx=substrate(artifact/artifact_link/mcp_schema). 한 blueprint-postgres 인스턴스, 교차쓰기 금지 (substrate 는 Workspace 미접근, Prisma 는 artifact 미접근 → 마이그레이션 도구 충돌 0). public 이 시간에 따라 줄어드는 게 strangler.

→ D-bp-artifact-4 refine (모순 아님): “monolith first / 별도 KnowledgeStore service 분리 안 함 / 신규 인프라 0” 의 인프라 정신은 보존 (동일 blueprint-postgres · 동일 compose · 동일 axe ship blueprint). 바뀐 것은 언어 뿐 — knowledge substrate 를 Rust 프로세스로 구현 (언어 마이그레이션 목적의 프로세스 분리). frame/hive/gate 식 독립 product-service 가 아님 (cloudflared·공개 MCP·blue/green pair·customers.yaml service·pre-push guard 등재 전부 없음).

첫 organ = PARA substrate:

• 경계 = Artifact-scoped (사용자 확정): substrate 가 artifact / artifact_link(+annotation) / mcp_schema 소유. workspace_id · entity_id 는 OneDrive citation 처럼 opaque 외부 ref(FK 없음, 데이터 중복 0). Workspace + paraLayer SoR = Blueprint/Prisma 잔류. Workspace lifecycle 변경(reclassify/close) → 내부 신호(pg_notify 또는 webhook)로 substrate 의 cached paraLayer 동기화 (D-bp-artifact-6 “Re-sync on paraLayer change” 의 cross-process 판).
• 모델은 처음부터 옳게: D-bp-para-1 home/link(“집”) 1급 — artifact_link (artifact_id, workspace_id) = home 멤버십 본체 + annotation(Area 별 해석 레이어), dispatch mode link(기본)/copy_curate(method→Resource)/move(working→Archive), parent_artifact_id → derived_from_id(진짜 파생 lineage 만). 2-level scope(personal/shared) = artifact scope 컬럼 → 열린질문 (a) 확정. citation = D-bp-artifact-3 6종 + D-index-6 index.* + D-gate-2 gate.decision = 8종 처음부터.
• 배포 = blueprint compose 내 sidecar blueprint-substrate (Rust+axum, 내부 포트). 위치 = blueprint/substrate/ (레포 내부 Cargo — polyglot 레포 = 점진 전환의 정상태). axe ship blueprint 한 경로 안에서 빌드.
• Next→Rust 인증 = 기존 BLUEPRINT_INTERNAL_API_KEY Bearer (/api/internal/* 패턴) + caller identity·entity scope 헤더. 동일 compose 망 내부 호출 신뢰.
• 첫 organ 이 재사용 패턴 확립 (schema-split · 내부 auth 브릿지 · typed TS client · compose-service) → 이후 organ 들이 복제.

열린 질문 처리 (D-bp-para-1):

• (a) 2-level scope → 확정: personal + shared (artifact scope 컬럼, 기본 personal → 승급 shared).
• (b) governance servicization → 별 트랙 gate 서비스가 흡수 (D-gate-1/D-gate-2). substrate 와 무관.
• (c) Project staffing(“던지면 emerge”) → 후속 defer (이번 substrate scope 아님; Project=컨테이너 + 기존 WorkspaceMember).
• (d) Rust 범위 → 확정: 신규 백엔드 organ = Rust, 프론트 = TS 유지, 점진 대체.

시퀀싱 (중요): 첫 scaffold 는 기존 M6 Stage-1 TS Artifact 테이블(Prisma public)을 건드리지 않고 병행 신설. cutover(Prisma Artifact 제거 + /api/artifact/propose → substrate client repoint)는 Rust 경로 동작 검증 후 별 stage — 기존 propose route 안 깨짐.

정직한 비용: polyglot 레포 + 두 마이그레이션 도구(schema-split 로 관리), Workspace↔artifact 교차 트랜잭션 상실(Artifact-scoped 라 수용 — workspace 생성 후 artifact propose 분리). 상세 ADR = docs/adr/blueprint-rust-migration.md. SoT 메모 = project_para_ai_os_philosophy.md.

D-bp-ui-1 — Blueprint @axe/ui 채택 + Tailwind 4 패치

D-axe-ui-1 (SSOT 단일 배포 채널 결정) 의 Blueprint 측 implementation. 첫 SSOT 소비자 중 Tailwind 4 + Turbopack 스택을 가진 곳 — Nextra (axelabs-docs) 와 다른 CSS 파이프라인 거동 때문에 sync 단계 패치 필요.

채택 범위 (2026-05-22):

Blueprint 전용 패치 1 — fonts.css @import url() strip:

axelabs SSOT 의 src/lib/tokens/fonts.css 는 Pretendard + D2Coding 을 @import url("https://cdn.jsdelivr.net/...") 로 로드. 이는 Nextra (axelabs-docs) 에서 정상 동작. 그러나 Blueprint 의 Tailwind 4 + Turbopack 파이프라인 은 globals.css 가 import 한 4 토큰 파일 (colors.css · spacing.css · typography.css · fonts.css) 을 globals.css 본문 안으로 inline 한 뒤 컴파일. 결과 CSS 의 구조:

[colors.css :root 블록] ...
[spacing.css :root 블록] ...
[typography.css body { ... } html { ... }] ...
[fonts.css 의 @import url(pretendard) ← 다른 rule 뒤로 밀림!]
[fonts.css @font-face { Sarasa } :root { --font-* }]

CSS spec: @import 은 @charset / @layer 만 선행 가능. 다른 rule 뒤의 @import 는 브라우저가 silent drop. 결과: Pretendard 미로드, body 폰트가 system sans-serif 로 fallback (검증 안 했으면 모르고 지나갈 수 있음). 빌드 단계에서 @import rules must precede all rules aside from @charset and @layer statements 경고 발생.

회피: SSOT 미변경. sync 스크립트가 fonts.css 복사 시 content.replace(/^@import url\([^)]*\);\s*\n/gm, "") 로 @import url(...) 두 줄만 strip. Pretendard + D2Coding 은 src/app/layout.tsx 의 <link rel="stylesheet"> 로 로드 — 이는 SSOT 자체가 Clash Display 에 대해 fonts.css 주석에서 명시한 회피 패턴 (“Fontshare URL 의 f[]= 대괄호가 Next.js CSS @import 파이프라인에서 떨궈지는 이슈 회피”) 의 확장. 후속 axelabs SSOT 의 모든 @import url() 도 동일 strip 적용 (sync 스크립트의 정적 규칙).

Blueprint 전용 패치 2 — Legacy var alias bridge:

35+ tsx 가 기존 토큰 (var(--navy) var(--white) var(--gray-ax) var(--gray-light-ax) var(--dark-border) var(--accent-glow) var(--green) var(--red) var(--navy-light) var(--navy-mid)) 직접 사용. 비파괴 채택을 위해 src/app/globals.css 의 @layer base :root { } 에서 alias:

--navy: var(--bg-base);            /* dark: #1a0610 (legacy 동일) */
--navy-light: var(--gray-2);
--navy-mid: var(--gray-3);
--white: var(--text-primary);      /* dark: #f2e8ee (≈ legacy #f0f2f5) */
--gray: var(--text-muted);
--gray-light: var(--text-tertiary);
--dark-border: var(--border-subtle);
--accent-glow: rgb(227 255 102 / 0.15);
--green: var(--success);
--red: var(--danger);

--accent 는 legacy 값 (#E3FF66) 을 제거 — colors.css 가 모드별로 자동 주입 (var(--brand-claret) light / var(--brand-neon) dark). dark 모드에서 --accent = #e3ff66 는 legacy hex (#E3FF66) 와 byte-equivalent. 즉 data-theme="dark" 기본인 한 모든 컴포넌트 무수정 작동, light 토글 시 일관성 있게 claret 톤으로 전환.

검증 (deployed @ 2026-05-22 PR 머지 시):

• curl https://blueprint.axellc.com/_next/static/chunks/0bd4439~8glcs.css | grep -oE '\[data-theme="dark"\],\.dark' — lightningcss optimizer 가 selector list 보존
• --gray-1: #1a0610 (dark block), --brand-neon: #e3ff66, --navy: var(--bg-base) 확인
• Pretendard CDN 200, /api/health localhost + edge 200
• next build 컴파일 ~8s, @import rules must precede 경고 0

후속 (별도 PR):

• 8+ tsx 의 inline fontFamily: "'Space Grotesk', ..." → var(--font-sans) 토큰화 (SVG 텍스트). 완료되면 Space Grotesk <link> 제거 가능.
• 35+ tsx 의 var(--navy)/var(--white)/var(--gray-ax) 직접 사용 → 새 토큰명 (var(--bg-base)/var(--text-primary)/var(--text-muted)) 점진 마이그레이션. alias bridge 는 그 동안 보존.
• Light mode 토글 UI (인프라는 준비 — data-theme attribute, persistence 만 별도).

관련 진단: /Users/axe/.claude/projects/-Users-axe-blueprint/memory/architecture_blueprint_axe_ui_adoption.md

D-matrix-1 — Matrix: Rust + native MCP (no Python SDK)

AXE Labs 첫 Rust 서비스. MCP Streamable HTTP 를 JSON-RPC 2.0 + axum 으로 직접 구현 (Python FastMCP 미사용). 모니터링 서비스 특성상 저메모리 (~15 MB), 단일 바이너리, tokio 기반 concurrent health check 가 핵심 이점.

기존 결정과의 관계: D-bp-mcp-1 (Python + FastMCP 기반 MCP 서버 표준) 은 기존 Python 서비스에 그대로 유효. 본 결정은 infrastructure tooling 의 새 precedent — Rust 의 장점 (메모리, 바이너리 크기, 동시성) 이 Python SDK lock-in 보다 우선하는 경우에 한정.

Rust 마이그레이션 적합성 평가 (2026-05-21): 기존 8개 프로젝트 (frame, blueprint, magnet, stream, artemis, cortex, mysrt, tether) 의 Rust 전환은 모두 No 판정 (mcp Python SDK + anthropic SDK + 한글 PDF 파싱 lock-in). 새 컴포넌트에서 시작하는 것이 미래 후보 — matrix 가 그 첫 사례. 2026-05-26: cortex 가 두번째 Rust 서비스 — 기존 file-based recall 폐기 후 artifact-first 재출발 (D-cortex 참조).

D-matrix-2 — Matrix: WAN/인터넷 가용성 모니터링 + ISP 귀책 판별 (2026-06-03)

운영자의 댁내 Wi-Fi/인터넷 장애를 통신사에 민원 제출하려 macmini 시스템 로그 (/var/log/wifi.log 11일치 + 통합로그) 를 분석한 데서 출발. 단말 로그는 “이 기기가 해당 시각 인터넷 도달 실패” 는 증명하나 ISP vs 댁내 (공유기/Wi-Fi) 귀책을 단독 확정 못 함 (6/3 장애는 DNS 실패 + IPv4 경로 99회 상실 = upstream 정합이나 동시에 Wi-Fi 펌웨어 트랩 1회 → 100% 단정 불가). matrix 가 상시 가동 인프라 모니터링 MCP 이므로 “인터넷 회선 가용성” 을 종합 모니터링 항목으로 흡수 — 향후 장애를 분 단위로 자동 기록 + 귀책 자동 판별.

기존 결정 정합: D-matrix-1 (collector 제네릭 설계) 위에 프로브 추가만으로 성립 — 새 테이블/도구 불요가 핵심. multi-tenant — wan-* 는 노드별 자기 회선 모니터라 customer sovereignty 와 자연 정합.

D-matrix-4 — netheal: 호스트 인터넷 자가치유 데몬 (2026-06-04)

D-matrix-2 가 WAN 끊김을 감지·귀책 하면, netheal 은 치유 — 6/3 운영자가 손으로 한 WiFi off/on 6회 → 재부팅을 자동화. matrix 는 Docker (Linux VM) 안이라 macOS en1 을 제어할 수 없어 치유는 호스트로 분리.

기존 결정 정합: D-matrix-2 의 gateway-vs-internet 귀책 로직을 그대로 재사용 (감지→치유). multi-tenant — 노드별 자기 회선 치유라 customer sovereignty 와 직교.

D-cortex — Cortex (AI-native relationship CRM, 2026-05-26)

7 개 결정의 묶음. 강수훈 개인이 Windows + OneDrive 의 단일 Network_CRM.xlsx 로 운영해온 1인용 투자 네트워크 CRM 을 platform 안으로 끌어들임 — frame 이 회계 자산을, hive 가 HR 자산을 platform 안으로 끌어들인 것과 동일 패턴. 도구는 개인용이었지만 데이터 (HPE 딜 / AXEV 파이프라인 / LP·SI·FI·Portfolio·Talent 관계) 는 회사가 의존하는 자산이라 한 사람의 OneDrive 에 잠겨있는 게 본질적 위험.

기존 /Users/axe/cortex (2026-03 시작한 file-based “VC 심사역 AI 기억 시스템” — 186 markdown topic tree + 16 entity profile + 3,394 keyword DB + 45,903 connection edge) 은 도메인이 유사했지만 모델 (파일 기반 / 단일 사용자 / 자체 router LLM) 이 새 설계와 완전히 다름 → .legacy.20260526/ 으로 rename 보존 (623 MB, 추후 enrichment migration 참조용).

부수 효과:

• /Users/axe/cortex 폴더 폐기 (cortex.legacy.20260526/), cortex.axellc.com 도메인 라우트 삭제 (cloudflared ~/.cloudflared/config.yml 정리, mysrt.axellc.com 만 보존)
• 32xx 포트 재할당: 3200 postgres / 3210 mcp-blue / 3211 mcp-green / 3212 proxy (frame 3700/3710/3711/3712 패턴)
• customers.yaml: sso.apps.cortex_mcp (appId=60d04ea8-5d7b-453e-a4c0-af421b4689f5, az cli 등록 2026-05-26) + services.cortex (5 secrets: DB_PASSWORD, PII_PASSPHRASE_AXEC, JWT_SECRET, AZURE_CORTEX_MCP_CLIENT_SECRET, GOOGLE_OAUTH_CLIENT_SECRET)
• Entra app: frame_mcp / hive_mcp / blueprint_mcp 와 동형 (signInAudience=AzureADMyOrg, requestedAccessTokenVersion=2, identifierUris=https://axe.axelabs.ai/cortex/mcp, scope mcp.access, webRedirectUris=claude.ai+claude.com /api/mcp/auth_callback)
• Postgres 5 테이블 (artifact / citation / artifact_event / mcp_schema / google_oauth_token), GIN+btree+partial index, append-only trigger, 4 RLS policy (owner_only USING+WITH CHECK)
• 10 MCP tools — auth middleware (Entra ID JWKS 1h TTL cache + RS256 + audience-issuer-exp 검증) 통과 후 Extension<AuthContext> 로 owner_id 사용
• Google OAuth Web flow + People API client + per-user sync loop (600s 간격, system:google-sync actor 로 artifact_event 기록)

운영자 작업 — 2026-05-28 production live 완료:

1. ✅ 5 secret vault push (cortex/axe/{db-password, pii-passphrase-axec, jwt-secret, oauth-client-secret, google-oauth-client-secret}) — 모두 stdin pipe (jq -Rsc) 로 shell history·context 미경유
2. ✅ Google OAuth Web client — 신규 GCP 프로젝트 Cortex (id cortex-497605, 옛 Gemini/Network Manager 폐기 예정). People API enable + consent screen External/Testing + client (135512942819-...apps.googleusercontent.com)
3. ✅ Cloudflare ingress — axelabs 터널은 Cloudflare Dashboard remote-managed (로컬 config.yml 무시 — Updated to new configuration version=N 이 증거). axe 의 기존 CF API token (vault Cloudflare API - axelabs) 으로 PUT /accounts/.../cfd_tunnel/.../configurations 하여 axe.axelabs.ai path=cortex(/.*)? → host.docker.internal:3212 추가
4. ✅ docker compose up -d --build (postgres 3200 + mcp-blue 3210 + mcp-green 3211 + proxy 3212). cortex migrate (2 migration: artifact schema + oauth_authorization_codes)
5. ✅ claude.ai connector 등록 (URL + client_id + client_secret) → Microsoft OAuth → 12 tools 노출 + whoami 검증
6. ✅ connect_google → 브라우저 consent ([email protected], Test users 등록 필요) → ”✓ Google 연결 완료”
7. 🔧 (잔여) cortex import-xlsx 660 행 enrichment 1회 마이그 + axe mcp publish catalog 등재 — B-cortex-xlsx-import-run, B-cortex-mcp-catalog-publish

시행착오 (전부 known-gaps 등재): DB password 의 base64 / 가 URL port 파싱 깨뜨림 (PgConnectOptions builder 로 회피) · docker compose env_file 가 따옴표 literal (axe secret pull quote 가 postgres auth 깨뜨림) · resource-level RFC 9728 path 누락 · RFC 8414 path-insertion · MCP tool property key 한글 (메모) 이 tools/list 전체 거부 · Cloudflare remote-managed tunnel · Docker image 가 옛 코드라 cargo build 만으론 부족 (--build 필수).

상세: services/cortex, /Users/axe/cortex/docs/operator-setup.md , /Users/axe/cortex/CLAUDE.md .

D-vault-mcp-catalog — MCP Connectors catalog view (Vaultwarden org collection)

axelabs 자체 운영 MCP (frame, hive, blueprint, …) 의 OAuth 등록 정보 4 조각 (이름, MCP URL, client_id, client_secret) 을 사용자가 claude.ai/customize/connectors 등 MCP host 에 등록할 때마다 4 곳에서 찾는 비효율 해소. catalog view = Vaultwarden 의 MCP Connectors organization collection (org-wide read access). 사용자는 Bitwarden 브라우저 확장만 열면 URI 매칭으로 자동 suggest.

함정 (도입 직후 발견): customers.yaml customers.axe.sso.apps.frame_mcp.client_secret_env 가 5/21 hive_mcp 등재 후에도 D-ops-15.5 의 “proxy path only” 주석 형태로 stale 처리되어 있었음 (실제 vault item 존재 + claude.ai 가 confidential client 요구). 본 D 도입 시 정정 — frame_mcp 도 secret 포함하여 catalog publish. 같은 함정 = 미래 새 MCP 추가 시 client_secret_env 누락 시 catalog item 이 (public) 으로 잘못 publish 됨. axe mcp list 출력의 “vault item” 칸이 (public) 이면 점검 신호.

D-ops-42 — 배포 SSOT 아키텍처 (origin/main SHA = 배포 진실원천)

다중 동시 Claude Code 세션이 repo 당 1 working tree + 1 main 을 공유하던 구조가 만든 배포 엉킴을 근본 해소. 원칙 한 줄: origin/main 의 commit SHA = 배포의 SSOT. working tree·로컬 main·실행 중 컨테이너는 전부 그 SHA 의 파생·일회용 투영. AXE 가 docs·backlog(matrix-postgres, D-matrix-3)에 이미 적용 중인 SSOT 규율을 배포로 확장한 것. 전체 본문 = /ops/runbook/deploy-ssot.

동기 (실측 incident, 2026-06-04): 공유 tree + 공유 main 이 세 가지 고장을 동시에 발생:

구체 사례: 이미 배포까지 끝난 blueprint fix (commit b4067504) 가 main diverge + 타 세션 WIP 로 수 시간 push 불가 → 운영자가 수동 reconcile (stash→rebase→push). 추가 발견 = 운영자 axe CLI (364KB) 자체가 버전 미관리 + in-place 편집 = 같은 병의 가장 깊은 사례 (CLI 가 배포 도구인데 자기 자신은 SHA 추적 밖).

컴포넌트 — 각자 제거하는 고장:

스테이지 상태기계 (blue/green 이 이미 3스테이지 제공):

built → canary(passive color, 트래픽 0) → [migration-validation 게이트] → live(active flip) → previous(직전 active = 즉시 롤백)

migration-validation (안전 척추): 스키마 마이그레이션 포함 릴리스는 flip 전에 prod DB 의 ephemeral clone 에 마이그레이션을 적용·검증 (axe drill/backup 스냅샷 기계 재사용). 본질적 이유 = blue 와 green 이 DB 를 공유하므로 깨지는 스키마 변경은 blue/green 으로 카나리가 불가능 (green 용 마이그레이션이 blue 도 즉시 오염). 이 게이트가 blue/green 이 못 막는 유일한 위험을 덮음. 대상 = blueprint 대기 migration 2개 (add_user_entra_oid, add_entity_legal_name), hive alembic.

rollout (additive → canary → cutover): 전부 기존 동작과 공존 (additive) → --dry-run + passive-color 카나리 (flip 안 함) 검증 → cutover (기본값 flip + 가드 활성화, escape hatch 포함) 는 게이트됨 → 되돌림 가능. 진행 중 WIP 보존.

채택 안 함:

• 별도 staging 환경 (staging.axelabs.ai + 독립 DB/터널) — 단일 Mac mini 호스트에서 새 실패유형은 안 잡으면서 비용·parity 만 증가. canary + migration-validation 이 실위험을 이미 커버.
• 작업추적에 새 “스테이지” 축 — roadmap/backlog/updates 가 이미 작업 스테이지 파이프라인 (D-matrix-3). 배포 스테이지와 작업 스테이지를 혼동하지 않음.

정합: D-ops-16 (docs drift = release-gate axe ship) 의 release-gate 를 배포 진실원천까지 확장 · D-matrix-3 (matrix-postgres SSOT) 의 SSOT 규율을 배포로 확장 · Blue/green deploy 의 alias swap 메커니즘 재사용.

D-ops-44 — Vault 비밀 주입 = SSH 환경 raw-bw keychain-free (axe vault unlock 금지)

이 머신은 AXE 의 Mac mini 이고 Claude Code 세션은 SSH(loopback) 위에서 돈다. 운영자는 Windows 에서 ssh [email protected] (Tailscale) 로 들어온다. macOS 는 SSH 세션이 GUI login keychain 에 쓰는 것을 거부한다 (“User interaction is not allowed”). 그 결과 vault 비밀을 넣는 통상 경로 (keychain 세션 의존) 가 SSH 컨텍스트에서 전부 막힌다. 본 결정 = SSH 환경에서 비밀을 vault 에 넣는 정답 경로를 keychain-free raw-bw 로 고정하고, 이를 /Users/axe/CLAUDE.md 에 강제 규칙으로 박제한 것. 운영자-facing how-to = /architecture/secrets#ssh-환경에서-vault-비밀-주입-keychain-free-raw-bw.

금지 (SSH 에서 전부 실패):

정답 = keychain-free raw-bw (운영자가 자기 인터랙티브 셸 — Windows ssh [email protected] 또는 Mac 터미널 — 에서 직접 실행). 에이전트는 스크립트를 ASCII-only · 주석 없음 · bw unlock 을 단독 한 줄로 공급한다 (한 블록으로 붙여넣으면 unlock 프롬프트가 바로 다음 줄을 비밀번호로 삼켜버림). 단계:

1. export NODE_EXTRA_CA_CERTS=/Users/axe/.axe/vault/certs/rootCA.pem — Vaultwarden private CA, 필수.
2. 자기 단독 줄에서 export BW_SESSION="$(bw unlock --raw)" — master-pw 프롬프트. TTY-flaky 폴백: read -rs PW; export BW_SESSION="$(BW_PASSWORD="$PW" bw unlock --passwordenv BW_PASSWORD --raw)"; unset PW.
3. raw bw create / bw edit 로 Login item 생성·갱신 — name = customers.yaml 의 services.<svc>.secrets[].vault 경로 (예 gate/axe/jwt-secret), username = env var 이름, password = 스크립트 안에서 생성/읽은 값 ($(openssl rand -hex 32) / $(cat key.pem) / 상수 — echo·history·argv·agent-context 어디에도 안 남김) → bw sync → unset BW_SESSION.

검증 (에이전트는 검증 불가): BW_SESSION 이 운영자 셸 안에만 살아 있으므로 에이전트는 결과를 직접 확인할 수 없다. 운영자의 created/updated + synced 출력이 곧 확인이다. axe secret check 호출 금지 (keychain 필요).

keychain 세션이 필요한 곳 = deploy/ship 시점 한정: axe ship/axe secret pull 은 그때 keychain 세션을 읽는다. SSH 에서 GUI 없이 그 세션을 채우는 법 = read -rs KCPW; security unlock-keychain -p "$KCPW" ~/Library/Keychains/login.keychain-db; unset KCPW (headless unlock) → axe vault unlock → axe ship. 비밀을 넣는 작업은 이 단계가 불요 — raw-bw 가 keychain 없이 vault 에 직접 쓴다.

정합: D-ops-17 (vault = canonical SoT, manifest 매핑) · D-ops-40 (osascript hidden-dialog 패턴 — GUI 세션 전제라 SSH 컨텍스트에선 본 raw-bw 가 대체). 더 깊은 잔여 격차 (=_vault_env 가 keychain 만 읽고 env-session 폴백이 없는 것) 는 /ops/known-gaps 에 분석 기록.

⚠️ 함정 — 회피 필수

결정 변경 절차

새 결정 또는 기존 결정 변경 시:

1. multi-tenant-platform-plan.md 또는 frame/DECISIONS.md 에 추가 (해당하는 곳)
2. 본 페이지의 표 갱신
3. 영향 받는 다른 docs 페이지 수정
4. customer admin / 직원에게 통지 (영향 받는 경우)

회고 주기

분기마다 (Jan/Apr/Jul/Oct 15) DECISIONS 회고:

• 채택한 결정 중 후회 있는 것
• 함정에 빠진 사례
• 새로 발견된 함정
• D-ops 회수번호 (deprecate 결정)

참고

• /Users/axe/multi-tenant-platform-plan.md — 마스터 plan + D-config-N
• /Users/axe/frame/DECISIONS.md — frame D-ops-1~15
• /Users/axe/hive/DECISIONS.md — hive D-hive-1~25
• /Users/axe/blueprint/docs/project-blueprint.md — blueprint 마스터 (5 분과)
• /Users/axe/CLAUDE.md — 포트 · launchd 인벤토리