Knowledge Requirements

Status: Draft Related Features: auth, organization, workflow, agent-builder, connectors, audit-tracing, llm-credentials, conversation-memory

Purpose

흩어진 사내 문서와 데이터 source item을 자동 또는 수동으로 수집하고, workflow 생성과 실행에서 권한 범위 안의 근거만 검색할 수 있는 통합 RAG 기반을 제공한다. 현재 제품 방향에서는 전역 에이전트 Q&A보다 Workflow Builder가 LLM node의 RAG 옵션을 구성하고, 생성된 workflow가 실행 시점 execution subject 또는 anonymous public-only 기준으로 검색하는 흐름을 우선한다. PRD의 FR-031~FR-033을 담당한다.

Workflow canvas에는 독립형 RAG 실행 노드를 도입하지 않는다. Knowledge retrieval, query rewrite, evidence sufficiency, source tier policy는 LLM node의 RAG 옵션으로 제공한다.

현재 구현은 manual Knowledge Base 생성, 문서 업로드/색인, metadata-aware retrieval, hierarchical RAG, standalone RAG Agent answer 기반을 제공한다. 목표 KB 통합 모델은 ADR-0014에 따라 Knowledge Base를 document/source item 단위 permission/retrieval/sync/lifecycle atom으로 재정의하고, Knowledge Collection을 grouping/routing/UX/ops 단위로 둔다. Knowledge Skill 경계는 ADR-0015를 따른다. MBA-105 구현 baseline은 ADR-0017, ADR-0018, ADR-0020, implementation_baseline.md를 따르고, direct KB와 명시 selected Collection의 Workflow runtime candidate 해석은 ADR-0036을 따른다. Runtime query embedding provider 권한과 비용 경계는 ADR-0071, Organization Detector Provider와 ingestion embedding 전 local masking Target은 ADR-0070을 따른다.

Current Baseline

knowledge_bases와 documents의 물리 schema는 legacy 다중 row를 읽을 수 있도록 one-to-many 관계를 유지하지만, 신규 manual 입력은 빈 KB에 최초 Document 하나만 등록한다. 독립 source item을 추가하려면 별도 KB를 만들고 필요한 검색 묶음은 Knowledge Collection으로 구성한다.
Metadata-aware/hierarchical RAG 경계는 ADR-0012를 따른다.
Standalone RAG Agent answer와 trace/usage correlation 경계는 ADR-0013를 따른다.
Knowledge Skill은 ADR-0015에 따른 provider-neutral target artifact이며, 현재 구현 완료 상태가 아니다.
현재 documents.meta_info는 current metadata convention의 source of truth다.
Workflow LLM node RAG에서 execution_subject가 없으면 현재 MVP는 private KB retrieval을 실패시키는 대신 anonymous public-only로 낮춘다. Public-only 후보는 active Knowledge Collection의 safe_metadata["visibility"] == "public"에 연결된 active KB로 제한하고, source-managed Collection과 source-managed KB는 별도 source/connector public exposure approval도 통과해야 한다. MBA-176 범위에서 이 approval primitive가 구현되어 있지 않으면 source-managed public 후보는 warning이 아니라 source_public_exposure_required blocked로 처리한다.
현재 Gateway KnowledgeCandidateResolver는 Builder recommendation/deployment preview용이다. Collection scope 생략 시 route-safe subset 또는 직접 권한 KB fallback을 사용할 수 있으며 Workflow runtime authorization primitive가 아니다. MBA-232 runtime resolver는 명시 selected Collection만 받고 organization-wide fallback을 금지하며 Workflow Engine application/adapter 경계가 소유한다.
MBA-232 source-managed authenticated candidate는 현재 DB에 materialize된 SourceAuthorizationProvenance만 사용한다. Live connector authorization과 runtime source cache는 이 단계에 구현하지 않는다. Source public exposure primitive가 없으므로 MBA-232 anonymous public-only resolver는 source-managed Collection과 source-managed KB를 모두 fail-closed 제외한다. Source-managed Collection은 manual child KB만 포함해도 anonymous candidate stream을 만들지 않는다.
목표 cutover 전까지 공식 문서는 현재 동작과 목표 모델을 분리해 읽어야 한다.

Target Model

KnowledgeBase: 문서/source item 1개에 대응하는 permission, retrieval, sync, lifecycle atom.
KnowledgeCollection: 여러 document-level KB를 묶는 grouping, routing, UX, operations 단위.
DocumentVersion: document-level KB의 canonical content/index version. 기본 retrieval은 active ready version만 사용한다.
Source-managed KB: 외부 source connector가 생성/관리하는 KB. Retrieval에는 mbased KB use와 fresh source ACL/requester authorization이 모두 필요하다.
Redacted canonical text: target chunk content, embedding input, retrieval-visible text artifact의 기본 원천.
Knowledge Skill: Workflow Builder가 LLM node의 RAG 옵션을 구성할 때 source-of-truth tier 선택, collection/KB routing hint, query template, metadata filter, validation checklist를 제공하는 재사용 artifact. Skill은 권한 source나 최종 근거가 아니다.
Source-of-Truth Tier: 정책 문서, ADR/decision record, semantic definition, curated query corpus 같은 근거 계층. Skill은 이 tier를 선택하는 절차를 제공할 뿐 source of truth가 되지 않는다.
Indexed cache: source item의 redacted canonical chunk, embedding, safe metadata를 저장하고 runtime source authorization을 final evidence gate 전에 다시 확인하는 MVP 기본 mode.
Live-linked: Nodease 내부 chunk/embedding 없이 source ref와 safe metadata만 저장하는 mode. Requester-scoped source-side search 또는 opaque-ref-only search를 통과한 source만 검색 후보가 될 수 있다.
Archived copy: protected raw artifact를 opt-in 보존할 수 있는 mode. Raw artifact는 RAG/embedding/prompt input이 아니며 redacted canonical text만 retrieval-visible하다.

User Stories

빌더로서, 수동 업로드 또는 connector sync로 생성된 지식을 collection 단위로 탐색하고 상태를 확인하고 싶다.
플랫폼 관리자 또는 KB/collection manager로서, collection grouping/routing 권한과 KB content 권한을 분리해 관리하고 싶다.
workflow 생성 권한자로서, 자연어 요청만으로 사내 지식 검색이 필요한 LLM node의 RAG 옵션이 포함된 workflow 초안을 받고 싶다.
workflow 실행 사용자 또는 실행 주체로서, workflow runtime이 내 execution subject 권한 범위 안의 collection/KB 후보에서만 검색하고, 실행 주체가 없는 public 실행은 공개 collection/KB 후보에서만 검색하길 원한다.
감사자로서, 특정 답변이 어떤 KB, document version, chunk에서 나왔는지 redaction-safe summary로 추적하고 싶다.
운영자로서, source sync 실패, source ACL stale, tombstone, 재색인, purge 상태를 raw content 노출 없이 확인하고 싶다.
도메인 오너로서, 반복되는 질문 유형에 맞는 Knowledge Skill의 안전한 절차/context/routing 경계를 정의하고 freshness/evaluation 상태를 관리할 수 있는 목표 기능을 원한다. 구체적인 작성 UI와 승인 UX는 아직 확정하지 않는다.

Functional Requirements

FR-031: Knowledge source item을 document-level KB로 수집·색인하고, 여러 KB를 Knowledge Collection으로 묶는다.
FR-032: Auto collection mode는 collection routing scope와 KB permission helper 결과로 만든 safe candidate set만 router, Workflow Builder, 실행 시점 RAG 경로에 전달한다.
FR-033: Explicit KB mode는 collection routing 권한을 생략할 수 있지만 KB helper, source ACL gate, final evidence policy gate를 생략할 수 없다.
FR-034: Source-managed KB retrieval은 mbased KB use와 fresh source ACL/requester authorization을 모두 통과해야 한다. Stale, unmapped, ambiguous, unverified, revoked source ACL은 fail-closed다.
FR-035: Collection permission은 collection.read, collection.route, collection.manage, collection.sync처럼 grouping/routing/ops 권한으로 다루며, 하위 KB content retrieval을 자동 부여하지 않는다.
FR-035a: 조직 멤버십은 KB permission 평가의 기본 조건일 뿐이며, active organization member라고 해서 모든 KB를 사용할 수 있는 것은 아니다. KB content 접근은 organization manager override, team KB permission, user direct KB permission 중 가장 강한 additive allow와 source ACL/final evidence gate를 모두 통과해야 한다.
FR-035b: 관리자는 active organization 안의 특정 사용자에게 user_knowledge_permissions row로 KB 직접 권한을 부여할 수 있어야 한다. 직접 grant는 viewer, operator, builder, manager만 생성/갱신할 수 있고 none은 grant request 값으로 받지 않는다. 회수는 DELETE로 표현한다.
FR-035c (MBA-231): KB action은 read, use, write, content_read, manage로 통합한다. viewer/operator/builder/manager는 각각 safe read, retrieval use, write+eligible manual content read, resource manage의 최소 권한을 제공한다. knowledge_bases.user_id는 owner bypass가 아니라 생성자/귀속 정보다.
FR-035d (MBA-231): Active organization member가 manual KB를 만들면 KB row, 생성자의 user-direct manager grant, canonical data-change audit를 한 transaction에서 저장한다. Legacy owner backfill은 같은 organization active member만 대상으로 idempotent하게 수행하고 불명확 row는 safe finding으로 격리한다.
FR-035e (MBA-231): Organization manager는 Team/User에게 catalog_manage, permission_delegate, lifecycle_manage, sync_manage Knowledge domain action을 위임할 수 있다. Domain action은 KB content permission이나 Collection route를 자동 부여하지 않으며 만료된 row는 cleanup job 없이도 평가에서 제외한다.
FR-035f (MBA-231): permission_delegate actor는 자신 또는 자신이 active member인 Team에 content-plane permission을 부여해 권한을 상승시킬 수 없다. Organization manager는 recovery authority로 이 제한에서 제외하며, 모든 성공·차단은 raw principal이나 payload 없이 감사한다.
FR-035g (MBA-231): KB는 Collection membership 없이 독립적으로 존재할 수 있고 0개 이상의 Collection에 연결될 수 있다. Domain catalog_manage는 private manual Collection과 검색 grouping/routing용 private membership을 관리할 수 있지만 public Collection link/unlink/reorder와 visibility 전환은 Organization manager acknowledgement를 요구한다. 일반 membership은 Collection privacy policy를 KB에 적용하거나 제거하는 authority가 아니다.
FR-035h (MBA-231): KB/Collection archive·restore는 resource manage 또는 domain lifecycle_manage로 허용하되 system-managed source-owned mutation은 제외한다. KB hard delete와 public exposure는 V1에서 Organization manager 전용이며 명시적 acknowledgement와 retention/source-public gate를 통과해야 한다.
FR-035i (MBA-241): KB detail과 document detail의 read response는 내부 documents.meta_info를 그대로 반환하지 않고 명시된 safe operational metadata만 allowlist projection한다. Encrypted source config, connection/source/connector identifier, DB connection metadata, raw payload와 unknown field는 암호화 여부와 무관하게 응답·오류·audit·log에서 제외한다.
FR-035j (MBA-241): Knowledge domain grant는 같은 organization의 active Team 또는 active member User만 대상으로 하지만, Organization manager는 제거·비활성화된 User 또는 inactive Team에 남은 기존 domain permission row를 회수할 수 있어야 한다. Revoke는 subject 활성화가 아니라 existing permission row를 lock/delete하고, 성공한 delete와 canonical audit를 같은 transaction에서 commit한다.
FR-035k (MBA-241): Domain catalog_manage만 가진 actor의 Collection item/link-candidate projection은 manual KB name을 fallback으로 노출하지 않는다. 유효한 safe_metadata.safe_label 또는 display-policy-approved source safe label을 사용하고, 별도 KB read 판정을 통과한 actor에게만 실제 manual KB name을 반환하며 그 외에는 generic label을 사용한다.
FR-035l (MBA-241): Document 설정 복원은 KB read detail을 넓히지 않고 active organization + KB write 전용 edit-config endpoint를 사용한다. Response는 bounded chunk/process option과 DB selection/opaque connection UUID allowlist만 반환하며 API URL/header/body, encrypted config, credential과 raw connection detail은 포함하지 않는다. Client는 edit configuration hydration이 성공하기 전에 DB/API preview 또는 process request를 전송하지 않는다.
FR-035m (MBA-241): KB detail/direct document response와 progress SSE는 persisted error_message 또는 processing_current_step 원문을 반환하지 않는다. Public status별 fixed message와 generic safe failure만 사용하며 legacy str(exception) 값도 response, SSE, toast input, audit, log로 재노출하지 않는다.
FR-035n (MBA-241): Domain permission revoke는 organization, subject type/id, action을 모두 predicate로 사용하고 existing row를 FOR UPDATE로 직렬화한다. 동일 grant에 대한 동시 revoke는 하나만 delete/audit commit하고 나머지는 idempotent unchanged여야 하며 audit failure는 delete를 rollback하고 다른 organization row에는 영향이 없어야 한다.
FR-036: Source ACL facts는 Source Authorization Provenance로 materialize하고, permission helper가 mbased KB permission gate와 source ACL/requester authorization gate를 분리해 effective result를 반환한다. Router/retrieval은 permission row를 직접 조합하지 않는다.
FR-037: Retrieval과 citation은 citation id, 허용된 KB/document version/chunk identity, optional safe source reference, direct KB-local rank, 최종 병합 결과의 evidence_rank, score, safe metadata summary를 반환할 수 있다. Collection-derived evidence는 child identity와 KB-local rank를 생략하고 정렬·dedupe·top-k 이후의 전역 evidence_rank만 반환한다. Raw source content, raw prompt/completion, credential 원문은 audit/trace/usage metadata에 저장하지 않는다.
FR-038: document_chunks.content, embedding input, retrieval-visible text artifact는 redacted canonical text에서 생성한다. Raw source content는 RAG/embedding/prompt에 사용하지 않으며, organization/source policy가 opt-in한 경우에만 protected raw artifact로 분리 저장할 수 있다 (ADR-0014). Source system이 자체 보유하는 source-of-record object의 opaque protected reference는 raw copy와 다르지만, upload 또는 connector fetch로 Nodease 저장소에 복사한 원문 bytes는 file_path 같은 기존 필드명과 무관하게 protected raw artifact 계약을 따른다. Target enforcement 전에 기존 Nodease-held raw copy는 protected store로 이관하거나 non-readable fence 뒤 물리 삭제해 original-copy absence를 증명해야 하며 raw response 차단만으로 storage disposition을 대체하지 않는다.
FR-039: Server-side URL fetch, connector preview/test, crawler/sitemap/API connector, DB/SSH/SaaS/object-storage probe는 중앙 outbound egress boundary와 protocol adapter safety policy를 통과해야 한다.
FR-040: Partial operational failure는 권한/source ACL failure와 구분한다. 일부 authorized KB retrieval 실패는 safe partial result로 표시할 수 있지만, permission/source ACL/final evidence failure는 evidence 제외 또는 resource-hidden response로 fail-closed한다.
FR-041: PII/secret redaction은 shared privacy/redaction service가 hard baseline을 제공하고, Knowledge ingestion은 이를 사용해 redacted canonical text를 생성한다. Admin policy는 baseline을 약화할 수 없고 organization/collection/source/KB 단위로 더 엄격하게 조정할 수 있다.
FR-042: Workflow runtime에서 RAG retrieval을 실행할 때 execution subject가 있으면 해당 subject 기준으로 KB permission과 source ACL을 평가한다. Execution subject가 없으면 workflow owner, deployment owner, builder, user_id로 조용히 fallback하지 않고 anonymous public-only로 낮춰 active public collection에 연결된 active KB만 후보로 사용한다. Source-managed KB는 valid source/connector public exposure approval도 필요하다. MBA-176 deployment preflight는 subject 없는 활성 배포에서 private KB 후보를 차단한다. Private KB 접근이 필요한 자동 실행용 service account/operator는 후속 기능이다.
FR-042a: internal_chatbot 인증 run은 Gateway 검증을 통과한 current user를 execution_subject로 전달하고 Runtime은 해당 user 기준 KB permission/source ACL을 재평가한다. 공개 chatbot run은 subject 없이 anonymous public-only를 유지한다.
FR-043: 운영 RAG mode는 이름이 general, permission_scoped, task_aware, metadata_aware, hierarchical 중 무엇이든 KB permission/source ACL/final evidence gate를 우회할 수 없다. general RAG는 authorized resource 안에서 넓게 검색하는 broad retrieval이고, task-aware 또는 permission-scoped RAG는 authorized resource 안에서 더 정밀하게 후보를 줄이는 retrieval이다.
FR-044: RAG strategy 비교와 비용 최적화를 위해 retrieval summary는 retrieval_strategy, rag_mode, selected collection/KB count, retrieved chunk count, citation count, context token estimate, retrieval latency, permission filter 여부, policy result, partial result, safe exclusion summary를 redaction-safe 형태로 제공한다.
FR-045: Source-managed KB에서 source ACL authorization은 KB use를 자동 대체하지 않는다. Auto-ingested KB는 normal mbased permission path 또는 organization-approved connector/source policy가 명시 KB use를 provision한 경우에만 retrieval 후보가 된다. Source ACL sync가 생성하는 record는 source authorization provenance로 취급하고 freshness/revocation/audit-safe provenance를 helper가 별도 gate로 평가한다.
FR-046: Knowledge ingestion은 같은 source item 또는 document-level KB에 대해 중복 finalization이 일어나지 않도록 owner-token lock, fencing token, database advisory lock, 또는 동등한 동시성 제어를 사용해야 한다. TTL 만료 뒤 stale worker가 새 worker의 lock이나 active artifact를 삭제/덮어쓰면 안 된다.
FR-047: content_hash, chunking fingerprint, embedding model, active document version pointer, retrieval-visible index state는 실제 chunk/index artifact가 성공적으로 준비되고 finalization transaction이 끝난 뒤에만 committed processed state로 갱신한다. Chunk 저장 전 hash만 먼저 commit해 다음 실행이 stale/empty artifact를 처리 완료로 오판하게 해서는 안 된다.
FR-048: Document/KB/raw artifact 삭제는 DB row와 object storage, vector index, external artifact cleanup을 outbox/reconciler로 조정해야 한다. DB commit 전에 physical object를 먼저 삭제해 orphan reference를 만들거나, cleanup 실패 때문에 hidden artifact가 retrieval-visible해지면 안 된다.
FR-049: RAG answer retention purge와 answer lifecycle/audit/usage 기록은 idempotent하고 복구 가능해야 한다. Purge는 terminal status 대상만 처리하고 row lock, marker, SKIP LOCKED 계열 또는 동등한 방어로 동시 실행 중복과 running row 삭제를 막아야 한다. Audit/usage 강한 일관성이 필요한 경로는 transactional outbox 또는 reconcile 기준을 가져야 한다.
FR-050: Knowledge Skill은 provider-neutral Nodease artifact로 정의한다. Skill은 Workflow Builder가 LLM node의 RAG 옵션을 구성할 때 사용할 source-of-truth 선택 절차, collection/KB routing hint, query template, metadata filter 후보, validation checklist, evaluation reference를 담을 수 있지만 권한을 부여하거나 permission decision을 수행하지 않는다.
FR-051: 빌더 단계에는 organization scope, skill visibility, display policy, freshness/eval gate를 통과한 redaction-safe skill metadata만 workflow 생성 제안에 사용할 수 있다. Skill name/description/tag/source tier도 민감 metadata로 취급한다.
FR-052: Skill이 제안한 collection/KB reference와 LLM node의 RAG 옵션은 실행 시점 권한을 보장하지 않는다. 생성된 workflow의 LLM node의 RAG 옵션은 실행 시점 execution_subject 기준으로 collection route, KB permission, source ACL/requester authorization, final evidence policy를 다시 통과해야 한다.
FR-053: Skill body/resource에는 raw source content, raw source title/path/url, raw source principal, raw ACL fact, restricted document list, hidden KB id, credential value, raw prompt/completion/provider response를 저장하지 않는다. 실제 근거 content는 항상 workflow 실행 또는 테스트 실행의 authorized retrieval로 가져온다.
FR-054: Skill freshness와 evaluation은 운영 workflow 생성 자동 후보와 실행 시점 RAG procedure gate다. freshness_state, last_validated_at, source_version_refs, eval_status, golden question/regression reference를 관리하고, stale 또는 review-required skill은 fail-closed 또는 remediation surface로 제한한다.
FR-055: workflow draft, LLM node의 RAG 옵션, workflow test run, RAG strategy comparison은 skill id/version/freshness/eval status와 safe source-of-truth tier를 provenance summary로 남길 수 있다. Raw skill body나 hidden source reference는 durable audit/trace/usage summary에 저장하지 않는다.
FR-056: Source-of-Truth Tier는 authorized evidence 안에서 ranking, tie-break, conflict resolution hint로만 사용한다. Tier는 KB permission/source ACL/final evidence gate를 대체하지 않으며, Skill이 source of truth로 승격되는 것도 아니다.
FR-057: LLM node의 RAG 옵션은 query_rewrite_mode를 가질 수 있다. MBA-105 runtime은 off를 기본값으로 두고 deterministic/template rewrite를 opt-in으로 구현한다. llm_assisted rewrite는 LLM 호출이므로 execution subject, generation model/credential, credential use, usage/cost 기록, timeout, token/cost budget, 실패 시 fallback 정책이 별도 승인되기 전에는 구현하지 않는다. Rewrite는 user query와 safe skill/template만 사용하고 접근 가능한 collection/KB 범위를 넓히지 않는다.
FR-057a: 새 LLM node, Agent Builder의 LLM node 초안, Knowledge RAG 추천 옵션과 값이 누락된 runtime 호환 경로는 검색 기본값으로 scoreThreshold=0.3, topK=5를 사용한다. 저장된 workflow에 두 값이 명시되어 있으면 해당 값을 보존한다.
FR-058: Workflow Builder용 Knowledge RAG Recommendation Adapter는 Agent Builder가 StructuredRequest에서 파생한 intent_summary, node_purpose_summary, knowledge_requirement, pending_resolution_ref, safe_workflow_context_summary를 받아 safe KB recommendation과 LLM node RAG option 후보를 반환한다. Adapter는 raw natural language 전체를 입력으로 받지 않고 권한을 직접 판단하지 않는다. HTTP 또는 serialized boundary에서는 full safe candidate set 객체를 받지 않고 KnowledgeCandidateResolver가 만든 server-issued reference 또는 server-resolved scope hint만 사용한다. Public HTTP boundary에서 raw KB id 기반 explicit_kb request는 허용하지 않으며, explicit_kb는 safe handle/authorized picker/server-resolved context를 통과한 trusted backend/internal service boundary에서만 사용할 수 있다. 같은 backend 내부 service call에서만 full safe candidate set 객체를 ranking input으로 사용할 수 있다.
FR-058a: Agent Builder Intent LLM 호출 전 Knowledge 도메인은 같은 permission, source ACL, retrieval-visible active version 경계를 사용해 metadata relevance가 0보다 큰 상위 20개 KB를 bounded safe context로 투영할 수 있다. Relevance가 0인 후보는 계층형 사용자 선택 UI에는 표시할 수 있지만 intent planner prompt에는 포함하지 않는다. 허용 field는 opaque candidate handle, safe label, KB safe topics/description, runtime availability, bounded relevance다. Raw KB/collection/source/document/chunk identity, path/URL/title, content, permission row, hidden/denied count는 포함하지 않는다. Intent LLM의 handle 제안은 자동 선택이 아니며 post-intent Recommendation Adapter와 apply/save materialization이 현재 권한을 다시 확인해야 한다.
FR-059: Recommendation item은 KB 후보와 route-authorized Collection/authorized child KB 계층을 함께 반환할 수 있다. Collection 선택은 runtime 동적 routing이고 하위 KB 선택은 직접 binding이다. Collection route 권한만으로 child identity를 노출하지 않으며 child는 독립 KB use와 lifecycle 검사를 통과해야 한다. Agent Builder-facing ID는 raw source/Collection/KB ID가 아니라 server-issued opaque handle이어야 한다. Recommendation item은 score, confidence, reason_category, threshold_result를 포함하고 후보가 1개여도 사용자 확인을 요구한다. 정상 조회 결과에서 후보가 0개이면 Agent Builder는 명시적 no-Knowledge 선택으로 계속할 수 있다. Adapter/runtime 장애 또는 safe fallback 선택지를 제공할 수 없는 상태만 unavailable이나 validation failure로 처리한다.
FR-059d: Agent Builder 화면 응답은 권한/lifecycle 필터와 전체 후보 점수 계산·안정 정렬 뒤 Collection 최대 20개와 고유 KB 최대 20개를 반환한다. 내부 권한·점수 계산 상한은 화면 표시 상한과 분리하며 UI는 약 3개 행 높이의 스크롤 목록으로 표시한다.
FR-059a: Recommendation ranking score는 DB에 저장하지 않고 추천 요청 시점에 KB 단위로 계산한다. Agent Builder가 구조화한 safe_query_topics를 1차 입력으로 사용하고, 모든 후보가 이에 무매칭일 때만 intent/node purpose safe term으로 fallback한다. Score는 kb_relevance=0.70, source_tier=0.10, runtime_availability=0.10, sync_freshness=0.10 비중으로 계산한다. 단, kb_relevance=0이면 운영 신호만으로 추천 점수를 만들지 않고 score를 0으로 둔다. source tier, availability, freshness는 relevance가 있는 후보의 순서와 신뢰도를 보조할 뿐 관련성 없는 후보를 추천하지 않는다. kb_relevance는 KB candidate의 allowlisted safe comparison text인 safe_label, kb_safe_description, kb_safe_topics만 비교 입력으로 사용할 수 있다. collection_safe_label, collection_safe_topics, Collection name/description, collection id/count 같은 Collection metadata는 KB relevance score 입력으로 사용하지 않고 route/permission boundary 또는 source_collection_summary에만 사용한다.
FR-059b: Manual KB는 builder recommendation을 위해 KB name/description을 sanitizer, length cap, secret/url/path removal을 통과한 뒤 safe label/topics comparison text로 자동 생성할 수 있다. Source-managed KB는 display-policy-approved source safe label/description/topics만 사용할 수 있으며, unapproved source-derived title/path/url/name은 safe label/topics 또는 keyword score 입력으로 사용하지 않는다. Safe label/topics 조회·편집은 일반 KB 설정 변경과 분리된 전용 API를 사용하고 KB manage 권한, active organization, sanitizer, audit 기록을 통과해야 한다. 이름·설명·embedding model 같은 일반 KB 설정 변경은 KB write를 요구하며 생성자/owner attribution을 권한 우회로 사용하지 않는다.
FR-059c: Manual KB는 safe_metadata.safe_label과 safe_metadata.kb_safe_topics를 저장할 수 있다. Knowledge detail UI는 각각을 자동 생성하는 별도 버튼을 제공하며, 생성 기준은 KB name/description을 sanitizer, length cap, secret/url/path removal에 통과시킨 값이다. Detail 응답은 can_edit_settings와 can_manage_safe_metadata를 분리해 반환한다. 전자는 effective KB write, 후자는 effective KB manage action으로 계산하며 knowledge_bases.user_id는 어느 capability에도 owner bypass를 제공하지 않는다. UI는 전자 없이 일반 설정·소스 변경 동작을 표시하지 않으며 후자가 있을 때만 safe metadata 편집 surface를 표시한다. 저장된 manual KB safe metadata는 recommendation keyword comparison text에서 자동 생성값보다 우선한다. Source-managed KB는 이 저장값으로 raw source display policy를 우회할 수 없고, display-policy-approved source safe metadata만 recommendation input으로 사용할 수 있다. Safe metadata 변경 audit은 KB 식별자와 변경 필드 경계만 남기고 safe metadata 원문 값은 마스킹한다.
FR-060: Recommendation request의 intent_summary, node_purpose_summary, knowledge_requirement, pending_resolution_ref, safe_workflow_context_summary는 safe structured input이지만 길이 cap, control character normalization, durable raw storage 금지, trace/audit/log allowlist를 적용한다. Validation 실패 응답은 입력 값을 echo하지 않고 sanitized field path/type/message만 반환한다.
FR-061: LLM node의 RAG 옵션은 목표 옵션으로 evidence_sufficiency_policy를 가질 수 있다. 운영 runtime의 초기 기본값은 minimum_evidence이며 off를 허용하지 않는다. Legal, policy, compliance, high-risk flow는 strict_citation 후보를 사용한다. 근거가 부족하면 LLM이 추측 답변을 만들지 않고 safe no-result 또는 insufficient-evidence 응답을 반환해야 한다.
FR-062: Slack 계열 source의 초기 granularity는 channel = Knowledge Collection, thread/huddle recap/canvas/bot-generated meeting summary/pinned-message group = document-level KB다. Channel digest는 opt-in connector policy로만 만들고 DM/raw audio/raw transcript ingestion은 기본 제외한다.
FR-063: RAG/LLM prompt path는 retrieved context, memory summary, upstream node output, 외부 source content를 신뢰할 수 없는 evidence로 취급한다. 이 데이터는 system/developer/user instruction source가 아니며, prompt 구성 시 delimiter와 sanitizer를 적용하고 문서 안의 지시문이 system/developer policy나 사용자의 명시 요청보다 우선하지 못하게 해야 한다.
FR-064: Untrusted context guardrail은 앱/워크플로우 관리자가 편집하는 system prompt가 아니라 플랫폼 최소 보안 경계다. 관리자는 앱별 system prompt를 추가할 수 있지만, retrieved context/upstream output을 instruction source로 취급하지 않는 baseline guardrail을 비활성화하거나 약화할 수 없다.
FR-065: Manual Knowledge Collection 관리 MVP는 Knowledge 관리 영역에서 Collection 목록, 생성, 상세, 수정, archive, item link/unlink/reorder, permission grant/revoke, public visibility 전환을 제공한다. Workflow Builder 안에서 Collection 생성/삭제를 주 기능으로 제공하지 않는다.
FR-066: Manual Collection 생성은 organization manager 또는 domain catalog_manage가 수행한다. Delegated create는 항상 private이며 Collection permission, KB use, organization-wide inherited grant를 자동 생성하지 않는다.
FR-066a (MBA-263): Knowledge Collection 관리 UI에서 새 Manual Collection을 생성하거나 편집 가능한 기존 Manual Collection의 정보를 저장할 때는 관리용 name과 별도의 nonblank 안전 표시명을 명시적으로 입력해야 한다. 안전 표시명은 기존 safe_metadata.safe_label에 저장 전 공통 safe-text sanitizer, 255자 cap, control character·secret-like text·URL·email·path 제거를 적용하고 Workflow Builder route-safe picker의 optional display label로만 사용한다. UI는 raw Collection name을 안전 표시명으로 자동 복사하거나 picker fallback으로 사용하지 않는다. API 호환성을 위해 safe_metadata.safe_label 자체는 optional로 유지하며 label이 없는 기존/API-created Collection은 generic label을 유지하고 관리 권한자가 edit surface에서 명시적으로 보완한다. 이 metadata는 Collection route 또는 child KB use 권한을 만들지 않는다.
FR-067: Private Collection item link/unlink/reorder는 collection.manage와 대상 KB manage, 또는 domain catalog_manage를 요구한다. Public membership 변경은 Organization manager와 explicit acknowledgement를 요구한다. 어느 경로도 하위 KB content use를 부여하지 않는다.
FR-068: Collection permission grant/revoke는 additive allow만 제공하고 action은 read, route, manage, sync로 제한한다. Organization manager, Collection manage, domain permission_delegate가 변경할 수 있으며 domain delegator의 self/own-Team 상승은 차단한다. UI role bundle은 여러 explicit action row를 한 transaction에서 적용하는 편의 기능이지 inherited role storage가 아니다.
FR-069: Public visibility 전환과 public Collection membership 변경은 organization manager와 explicit acknowledgement를 요구한다. safe_metadata["visibility"] == "public"은 anonymous public-only runtime candidate inclusion flag이며, 인증 사용자 KB use 권한이나 source ACL requester authorization을 대체하지 않는다. Source public exposure approval primitive가 없는 동안 source-managed KB의 public 전환/link는 source_public_exposure_required로 차단한다.
FR-070: System-managed Collection은 connector/sync pipeline이 소유하는 Collection으로 취급한다. Manual 관리 UI는 기본적으로 읽기 전용 또는 safe override만 허용하고, connector-driven system-managed Collection 자동 생성과 remediation action은 별도 source sync phase로 분리한다.
FR-071: MCP/API 기반 source connector는 LLM이 임의 tool을 직접 선택하는 경로가 아니다. Knowledge Source Connector 뒤의 server-side adapter만 operation allowlist를 호출하고, raw MCP response/tool error/source id/url/principal/token을 router, prompt, audit, trace, log, user-facing response에 전달하지 않는다 (ADR-0020).
FR-072: Source connector operation allowlist는 source listing, changed item listing, content fetch, ACL change listing, tombstone listing, capture event normalization, runtime source authorization primitive로 제한한다. 새 operation은 input/output field allowlist, timeout, page size, response size, retry, rate limit, safe reason code, raw field 저장 금지 테스트가 정의된 뒤에만 추가한다.
FR-073: Runtime source authorization은 check_access_batch(subject_ref, source_item_refs[])를 우선 사용해야 한다. Batch 미지원 source는 bounded concurrency, per-call timeout, aggregate timeout을 적용한 single check_access fallback만 허용하고, runtime authorization primitive가 없으면 private source-managed KB retrieval은 fail-closed다.
FR-074: Runtime access cache는 short-lived여야 하며 organization, connector, protected source identity, source item 또는 document version, execution subject, mapping epoch, source ACL freshness epoch, operation을 key에 포함해야 한다. Subject-level allowed 결과를 다른 source item에 재사용해서는 안 된다.
FR-075: Live-linked mode는 requester-scoped source-side search API가 있거나 source-side search 결과가 opaque source ref만 반환되고 runtime source authorization 이후에만 title/snippet/count/score 같은 metadata가 노출될 때만 검색 후보가 된다. Broad service account search 결과를 먼저 받고 unauthorized metadata를 사후 제거하는 방식은 기본 구현으로 금지한다.
FR-076: Source-managed Collection 또는 source-managed KB를 anonymous public-only 후보로 포함하려면 collection public visibility approval과 별도 source/connector public exposure approval을 모두 통과해야 한다. Public exposure approval은 bounded approval_scope와 target field consistency를 검증하고, invalid scope/target row는 public-only 후보에서 제외해야 한다. MBA-176에서는 public exposure approval primitive가 구현되지 않은 source-managed 후보를 source_public_exposure_required blocked로 처리한다.
FR-077: 외부 source artifact는 egress guard를 통과해도 trusted content가 아니다. Knowledge ingestion은 지원 file type/content type allowlist, macro/script/embedded object/executable 차단, archive depth/expanded-size/file-count cap, parser sandbox 또는 least-privilege worker, malware/content scan hook을 redacted canonical text 생성 전에 적용해야 한다. Scan failure, timeout, unsupported type, active content detection은 indexing-visible artifact를 만들지 않고 fail-closed 또는 remediation으로 처리한다.
FR-078: Knowledge Base archive/delete lifecycle mutation은 endpoint에서 직접 permission cleanup, storage cleanup, retrieval exclusion, audit orchestration을 조합하지 않고 lifecycle service boundary를 통과해야 한다. Hard delete는 해당 KB를 참조하는 team_knowledge_permissions와 user_knowledge_permissions direct grant row를 같은 transaction에서 먼저 정리해 legacy organization mismatch row를 포함한 orphan permission이나 FK failure를 남기지 않아야 한다. FR-048의 cleanup outbox/reconciler가 구현되기 전 MBA-182 current hard-delete baseline에서는 기존 best-effort physical storage cleanup을 lifecycle service 안에서 유지할 수 있지만, storage path/raw exception을 API나 durable log에 노출하면 안 되며 이 baseline을 target cleanup architecture로 간주하지 않는다. Durable lifecycle audit/outbox, idempotent cleanup retry, dead-letter/redrive cutover는 MBA-184에서 구현한다.
FR-079: Generic resource permission routing에서 resource_type="knowledge_base"는 workflow 또는 LLM credential fallback으로 흐르지 않아야 한다. Gateway registry/service boundary가 resource type별 target model, organization lookup, effective auth resolver, team/user permission table mapping을 소유하고 schema enum과의 contract를 테스트로 고정한다.
FR-080: Storage physical delete adapter는 DB의 file_path 문자열을 직접 신뢰하지 않는다. S3는 configured bucket/region의 승인된 URL 또는 canonical uploads/ key만 decode/normalize한 뒤 삭제하고, Local은 service-owned upload root 내부의 resolved file만 삭제한다. Bucket/host mismatch, root escape, symlink escape, control/dot segment, unsupported scheme은 provider 호출 전에 safe typed error로 거부하며 raw reference를 로그에 남기지 않는다.
FR-081 (Conversation Memory Target Integration): Knowledge authorization adapter는 각 KB/source dependency에 decision, principal_kind, opaque authorization_decision_revision, resource_revision, policy_revision, evaluated_at을 반환해야 한다. KB lifecycle과 source-managed KB의 source ACL revision은 decision revision에 반영해야 한다. Required revision을 만들 수 없거나 일부 bulk result가 누락되면 unknown으로 fail-closed 하며 Memory가 Knowledge revision을 자체 합성하지 않는다.
FR-082 (Conversation Memory Target Integration): Knowledge retrieval adapter는 final evidence에 영향을 준 KB/document version, organization, sensitivity와 authorization-safe reference를 completeness marker가 있는 server-derived RuntimeDataDependencyEnvelope로 반환해야 한다. Raw title/path/URL/content/ACL과 client-provided dependency를 포함하지 않아야 한다.
FR-083 (Conversation Memory Target Integration): KB lifecycle, collection public visibility, team/user direct KB permission, organization membership/manager override, source ACL/public exposure policy가 authorization 결과에 영향을 주면 Knowledge authorization decision revision이 변경되어야 한다.
FR-084 (Conversation Memory Target Integration): Anonymous public audience는 synthetic subject ID/revision 없이 anonymous_public_audience principal kind로 public collection, active KB와 source public exposure gate를 평가해야 한다. Login cookie나 Conversation Access Grant로 private KB 권한을 높이지 않아야 한다.
FR-085 (Conversation Memory Target Integration): V1 Memory dependency는 optional 의미를 지원하지 않는다. Knowledge evidence가 answer에 영향을 주면 해당 dependency는 모두 필수이며 하나라도 current authorization을 잃으면 derived entry 전체를 제외해야 한다.
FR-086 (MBA-232): Workflow runtime candidate request는 server-owned canonical organization과 AuthenticatedAudience(organization_id, user_id) 또는 AnonymousPublicAudience(organization_id) 중 하나, configured direct KB ID, 명시 selected Collection ID와 server candidate budget을 사용한다. Optional user에서 owner/builder/deployment owner/credential principal/service account로 fallback하지 않는다.
FR-087 (MBA-232): Runtime은 명시 selected Collection만 해석한다. Collection ID 생략과 빈 목록은 모두 Collection stream 0개이며 organization-wide discovery/fallback을 수행하지 않는다. Direct KB는 Collection route 없이 KB use와 applicable source gate를 통과하고, Collection child는 Collection route와 독립적인 child KB use/source gate를 모두 통과해야 한다.
FR-088 (MBA-232): Runtime candidate는 direct configured order를 먼저 유지하고 남은 budget을 selected Collection configured order의 round-robin으로 채운다. Collection 내부 tie-break는 item rank, item created time, KB UUID이며 canonical KB UUID로 dedupe하고 첫 provenance를 보존한다. 초기 budget은 최대 20 unique KB이고 budget/scan cap 도달은 fixed safe warning을 가진 성공 결과다. Membership query는 configured Collection별 ordered LATERAL cap을 window ranking 전에 적용해 window 입력을 bounded하게 유지한다.
FR-089 (MBA-232): Runtime resolver PostgreSQL adapter는 invocation마다 fresh transaction을 열고 첫 query 전에 REPEATABLE READ, READ ONLY를 적용한다. Collection, membership, lifecycle/readiness, permission과 materialized source provenance는 같은 snapshot을 사용하고 candidate/authorization 결과를 invocation 사이에 cache하지 않는다. Expiry 판단은 transaction의 timezone-aware evaluation timestamp 하나를 전체 permission helper 호출에 재사용한다.
FR-089a (MBA-351): Workflow RAG query embedding은 authorized candidate가 0개면 model projection, policy, capability, usage와 provider를 호출하지 않는다. 후보가 있으면 distinct canonical embedding model마다 exact query_embedding policy/capability와 durable provider operation을 하나 사용하고 같은 model 후보에만 invocation-local vector를 재사용한다. Knowledge execution subject를 credential principal로 사용하거나 generation/owner/default credential로 fallback하지 않으며 raw query/vector와 KB ID를 usage/audit/trace/task payload에 저장하지 않는다.
FR-090 (MBA-232): Authenticated source-managed KB는 active/fresh/matching materialized SourceAuthorizationProvenance가 필요하다. Missing, inactive, stale, expired, unmapped, ambiguous, unverified, revoked, denied, unknown 또는 organization/requester/KB/source mismatch는 fail-closed다. MBA-232는 connector client, check_access_batch, single check_access 또는 runtime source cache를 호출하지 않는다.
FR-091 (MBA-232): Anonymous public audience는 normal Team/User/domain permission을 소비하지 않는다. Selected Collection child는 active public Collection membership, direct KB는 하나 이상의 active public Collection membership이 필요하다. Public exposure primitive가 없는 현재 schema에서 source-managed KB는 public Collection membership이나 authenticated provenance와 무관하게 모두 제외한다.
FR-092 (MBA-232): KnowledgeCollectionItem은 lifecycle object가 아니다. Present row는 linked, unlink/missing은 membership 없음이며 Collection과 child KB lifecycle/readiness를 독립적으로 평가한다.
FR-093 (MBA-232): Candidate policy exclusion은 identity를 노출하지 않는 safe omission이고 0개는 safe_no_result다. DB/session/snapshot/repository/authorization infrastructure failure는 이미 평가한 후보를 반환하지 않는 whole-resolution retryable safe failure이며 retrieval/provider 호출 전에 끝나야 한다. Partial authorized-KB retrieval timeout은 downstream Retrieval Orchestrator/MBA-233 범위다.
FR-094 (MBA-232): Shared에는 framework/ORM/runtime concrete import가 없는 immutable contract와 pure merge policy만 두고 Workflow Engine runtime_retrieval application use case/port와 PostgreSQL adapter/composition이 concrete resolution을 소유한다. Gateway API, graph schema, Builder/preflight, LLM node와 retrieval wiring은 MBA-233 전까지 변경하지 않는다.
FR-095 (MBA-233): LLM node graph는 기존 knowledgeBases와 additive knowledgeCollections를 함께 저장할 수 있어야 한다. 각 목록은 최대 20개 canonical UUID reference이며 21번째, malformed object, non-canonical UUID, unknown field와 invalid display snapshot을 silent truncation·자동 삭제 없이 저장/실행/배포 전에 거부해야 한다. Collection membership은 graph에 정적 materialize하지 않는다.
FR-096 (MBA-233): Builder Collection picker는 active organization에서 active lifecycle이고 sync_state != source_deleted인 Collection 중 current editor가 route 가능한 항목만 별도 endpoint에서 받아야 한다. Scan/result cap은 effective route authorization을 SQL scope에 적용한 뒤 평가하여 최근 unauthorized row가 오래된 authorized Collection을 밀어내지 않아야 한다. Response는 UUID와 display-policy-approved optional safe label만 포함하고 management read/manage/sync, domain action, raw name/description, child identity/count, source metadata와 Client capability를 authority로 사용하지 않아야 한다.
FR-097 (MBA-233): Editable graph persistence는 current editor 기준으로 direct KB의 active/non-source-deleted/retrieval-selectable/effective use와 applicable source authorization, selected Collection의 active/non-source-deleted route를 server에서 다시 확인해야 한다. source_deleted KB는 과거 ready chunk/version이 남아 있어도 retrieval-selectable이 아니며 source_deleted parent Collection도 남아 있는 route grant/membership과 무관하게 unavailable이다. Knowledge reference가 전혀 없는 legacy graph는 nullable organization context 때문에 저장이 차단되지 않지만 malformed Knowledge field는 계속 구조 검증에서 거부한다. 실패한 reference가 하나라도 있으면 graph와 success audit을 원자적으로 저장하지 않고 generic safe error로 닫아야 하며 Collection child를 save-time에 열거하거나 authorize하지 않아야 한다.
FR-098 (MBA-233): 저장 시 권한 판정 결과는 runtime capability나 lease가 아니다. 권한 read 뒤 동시 revoke가 commit되어 configuration intent가 남아도 다음 invocation은 MBA-232 resolver로 current permission/source state를 다시 평가해야 한다. Picker에서 사라진 saved reference는 Client가 generic unavailable 상태로 보존하되 새 저장은 제거 또는 권한 복구 전까지 차단한다.
FR-099 (MBA-233): Deployment preflight는 direct KB와 selected Collection의 shape/limit, organization/lifecycle/sync eligibility와 server-derived deployment audience를 검증해야 한다. Direct KB에는 save-time과 같은 retrieval-visible completed chunk readiness를 적용하고, direct KB, public membership, Collection candidate aggregate에서 source_deleted 또는 retrieval-invisible KB를 제외하며 source_deleted parent Collection도 제외하여 runtime resolver와 같은 후보 경계를 유지한다. Anonymous surface의 private resource와 source public exposure primitive가 없는 source-managed content는 active deployment를 차단하고, workflow-node inherited audience는 owner/credential fallback 없이 warning 처리한다. Child identity와 exact hidden/denied count는 반환하지 않는다.
FR-100 (MBA-233): Direct-only, Collection-only, mixed LLM invocation은 MBA-232 resolver를 정확히 한 번 호출하고 ordered canonical candidate KB만 기존 bounded retrieval fan-out에 전달해야 한다. Candidate 0개는 embedding/retrieval/provider 호출 없는 safe no-result이며 resolver infrastructure failure는 ragFailurePolicy로 낮추지 않는 sanitized retryable whole-invocation failure다.
FR-101 (MBA-233): LLM node runtime은 Collection membership/permission 또는 child KB permission SQL을 직접 실행하지 않아야 한다. Execution audience는 server-verified organization과 explicit user execution subject 또는 anonymous public audience만 사용하고 workflow owner, builder, deployment owner, app creator, credential principal과 user_id를 Knowledge subject로 fallback하지 않아야 한다.
FR-102 (MBA-233): Agent Builder, cost optimizer, compare/copy/import, model-routing refresh와 deployment snapshot은 명시적으로 Collection selection을 편집하지 않는 한 knowledgeCollections를 보존해야 한다. Agent Builder는 ADR-0061에 따라 Collection과 직접 KB를 별도 opaque handle로 추천·선택·materialize할 수 있으며 선택 뒤 planner를 다시 호출하지 않는다. Pre-execution sync와 runtime은 명시 Collection과 direct KB를 합집합으로 해석하고 KB ID로 중복 제거한다.
FR-103 (MBA-233): Public app/deployment graph projection은 knowledgeBases와 knowledgeCollections를 모두 제거해야 한다. Direct KB evidence는 기존 authorized lineage projection과 KB-local rank를 유지할 수 있다. Collection에서 동적으로 유래한 evidence는 result/durable trace/audit에 child KB/document/chunk ID나 KB-local rank를 저장하지 않으며, result와 품질 trace에는 정렬·dedupe·top-k 이후의 전역 evidence_rank만 저장할 수 있다. Audit은 노드 단위 candidate/result count bucket으로 집계한다. Durable trace/log/audit에는 routing mode, count bucket, limit/failure flag와 fixed safe reason만 허용하고 Collection/hidden KB identity, child structure, raw graph/query/source/credential/provider payload를 추가하지 않아야 한다.
FR-104 (MBA-233): knowledgeCollections는 기존 graph JSONB의 additive field이며 MBA-233에서 새 DB relation, llm_node_versions column 또는 static membership snapshot을 추가하지 않는다. 새 field는 Worker-first 배포와 queue drain 뒤 Gateway write, Client 순서로 노출하고 rollback은 역순으로 수행해야 한다.
FR-105 (MBA-264): Manual Collection lifecycle 관리는 active/archived 목록과 archived-to-active restore를 제공해야 한다. Restore는 Organization manager, effective Collection manage, 또는 Knowledge domain lifecycle_manage만 수행할 수 있고 manual archived Collection에만 적용한다. Active Collection restore는 새 audit 없이 idempotent success이며, system-managed Collection은 source owner가 관리하고 source_deleted Collection은 fail-closed한다. Archive와 restore는 Collection row lock, organization scope, transaction-bound canonical audit를 공유하고 permission이나 Workflow route capability를 새로 만들지 않아야 한다.
FR-106 (MBA-264): Collection item reorder는 empty Collection을 포함한 current 전체 membership set, unique item id, 0..N-1의 unique contiguous rank와 opaque expected_order_revision을 요구한다. Link, unlink, reorder와 visibility mutation은 같은 Collection row lock protocol을 사용해야 하며 stale revision, 누락·추가 item, concurrent membership 변경은 아무 mutation 없이 safe conflict로 닫는다. Legacy link rank는 호환 입력으로만 수용하고 서버가 Collection 끝에 append한 뒤 연속 rank로 정규화한다. Item 조회, link와 reorder 성공 응답은 최신 전체 ordered projection과 revision을 반환하며 mutation caller가 별도 read 없이 유효한 mutation authority만 가진 경우에도 safe management projection을 반환한다. 초기 관리 UI는 500개 이하 Collection만 reorder하고 초과 시 고정 safe reason으로 비활성화한다. Public Collection의 source identity/connector 또는 source-managed child는 public exposure primitive가 없으면 acknowledgement만으로 link/reorder할 수 없다.
FR-107 (MBA-264): Collection 및 Knowledge domain delegation subject 조회는 authorization 이후 current organization의 active Team 또는 active member User를 server-side prefix search와 UUID keyset cursor로 page 처리해야 한다. subject_type은 명시하고 기본 page size는 25, 최대 50이며 total count, email, login principal, raw source identity를 검색하거나 반환하지 않는다. Cursor는 subject type과 정규화된 query에 결합한 opaque transport token일 뿐 permission token이 아니다.
FR-108 (MBA-264): Collection role bundle은 별도 role 또는 grant provenance가 아니라 explicit action 집합이다. Bundle revoke는 현재 존재하는 매핑 action row를 한 transaction에서 제거하고 없는 row는 idempotent unchanged로 처리한다. Bundle이 겹치더라도 저장된 role을 추론하지 않으며, Team/User direct permission source와 action row를 UI에서 그대로 구분한다.
FR-109 (MBA-264): 하나의 Team/User bundle을 1개 이상 50개 이하 Collection에 grant 또는 revoke하는 bulk operation은 Collection UUID 정렬 lock, 모든 target의 organization·authority·last-manage 사전 검증, mutation과 canonical audit의 all-or-nothing transaction을 사용한다. Grant는 active subject만 허용하고 revoke는 inactive subject의 기존 row 정리를 허용한다. Domain delegator self/own-Team grant 차단과 current actor last-manage 보호는 single과 bulk에 동일하게 적용한다. 응답과 오류는 target/subject identity나 정확한 hidden count 대신 operation과 safe count bucket만 포함한다.
FR-110 (MBA-264): MBA-264는 기존 additive allow permission model과 Collection/KB 권한 분리를 유지한다. Explicit deny, per-Collection permission expiry, bundle 전용 저장 row, Collection route에서 child KB use 자동 부여, KC sync 실행 endpoint/job/UI, Workflow graph/runtime resolver 변경은 도입하지 않는다.
FR-111 (MBA-265): Active Manual Collection의 동기화 요청과 상태 조회는 Organization manager, effective Collection sync, domain sync_manage 중 하나를 요구한다. Collection manage만으로는 허용하지 않으며 sync/sync_manage는 child KB read/use/write/manage 또는 Collection route를 부여하지 않는다.
FR-112 (MBA-265): 초기 KC sync 실행 대상은 현재 Workflow Engine에서 안전하게 처리 가능한 active Manual Collection의 active, non-source-managed document-level child KB에 연결된 단일 DB document로 제한한다. DB document가 있는 KB의 legacy documents row가 둘 이상이면 DB+DB, DB+FILE을 포함해 KB-level active version pointer가 sibling content를 숨길 수 있으므로 fail-closed한다. System/source-managed Collection, source-managed child, API connector sync는 승인된 connector adapter가 없는 동안 성공으로 가장하지 않고 fail-closed한다. 별도 FILE-only KB는 외부 sync 대상이 아니다.
FR-113 (MBA-265): Sync request는 canonical UUID idempotency key를 요구하고 원문 대신 hash를 저장한다. 같은 organization/Collection/request key는 기존 job을 반환하며, 같은 Collection의 queued/running job은 PostgreSQL partial unique constraint를 사용하는 single-flight로 하나만 허용한다.
FR-114 (MBA-265): Gateway는 job, deterministic target snapshot, Collection pending, canonical requested audit를 같은 transaction에 저장한 뒤 Celery task를 발행한다. Job target snapshot revision은 ordered membership UUID/KB/document/rank/created time topology를 고정하고, 각 item의 per-target revision은 여기에 document updated time을 포함한다. Worker는 Collection lock 아래 claim과 finalize에서 current canonical target set을 job snapshot과 비교하고, 각 source I/O 전에는 per-target revision을 비교한다. Membership add/remove/reorder, API/source-managed/multi-document 전환은 sync.targets_changed로 닫는다. Item은 live KB/document delete cascade와 분리하며 owning job의 organization/Collection scope만 composite FK로 강제한다. Commit 뒤 publish 실패는 durable queued job으로 남고 Docker Compose와 Helm에서 Worker와 분리된 singleton Celery Beat가 recovery task를 주기적으로 발행한다. Task payload는 job UUID만 포함한다.
FR-115 (MBA-265): Worker는 job claim 시 requester의 current organization scope와 sync/sync_manage authority를 fresh query로 재검사한다. Organization manager 판정은 active/non-active membership row를 우선하고 membership row가 없는 legacy created_by/managed_by만 fallback하는 ADR-0009 helper를 사용하며, manager가 아닌 requester는 active organization membership을 요구한다. Revoke가 이 query 전에 commit되면 job을 cancel하고, query 뒤 commit된 revoke는 이미 시작한 bounded batch를 중간 중단하지 않으며 다음 claim부터 반영한다.
FR-116 (MBA-265): Celery redelivery, worker loss, retry와 continuation은 DB job lease/item state를 source of truth로 사용한다. Unexpired running duplicate는 no-op하고 stale lease는 bounded recovery한다. Child 처리는 deterministic order, 최대 target 100개, delivery당 5개, concurrency 1로 시작하며 partial failure를 성공으로 표시하지 않는다. Item attempt는 succeeded/failed/skipped outcome transaction에서 실제 실행당 정확히 한 번 증가한다. Terminal 집계는 현재 item row와 immutable total_count를 대조해 누락 target을 sync.targets_changed skipped로 포함하고 processed total이 original total과 일치할 때만 success를 허용한다. Job claim 상한은 정상 batch, item retry와 stale recovery budget을 모두 수용하도록 target 수에서 계산하고 overall deadline으로 별도 제한한다.
FR-117 (MBA-265): 사용자 status projection은 job 상태, 범주형 progress, allowlisted safe reason, retryability와 timestamp만 반환한다. Child KB/document/source identity, exact target/success/failure count, raw source config/SQL/credential/payload/exception은 API, UI, Celery argument/result, audit, trace, log에 포함하지 않는다. Terminal job/item은 기본 30일 뒤 bounded cleanup하고 canonical audit retention은 별도로 유지한다.
FR-118 (MBA-265, MBA-281 정렬): Collection management projection은 caller authority인 can_sync와 현재 실행 adapter 지원 여부인 sync_supported를 분리한다. sync_supported와 sync POST는 동일한 organization-scoped canonical child eligibility scan을 사용해 UI/API 지원 판정 drift를 막는다. Worker는 requester의 current organization authority를 fresh 검증하고, DB Connection use는 이와 별도로 Connection.user_id == execution subject user_id인 지원 DB type만 허용한다. Source row limit은 문서당 최대 1,000으로 제한한다. Worker는 저장된 DB 문서의 flat all/range/keyword selection을 기존 ingestion과 같은 helper로 적용한 결과만 새 version에 저장하고 empty selection이면 이전 active ready version을 유지한다. Connection/config 식별자와 processor 원문 오류는 status, audit, task result와 log에 노출하지 않는다.
FR-119 (MBA-265): KC sync와 기존 ingestion의 document write는 shared PostgreSQL transaction advisory lock으로 같은 document에 대해 직렬화한다. 모든 writer는 상태 전이용 선행 commit 직후, source fetch/parsing/embedding과 document/Collection/KB row lock 전에 advisory lock을 획득한다. Organization-scoped KB는 새 DocumentVersion과 version-scoped chunk를 준비한 뒤 chunk 존재를 확인하고 active pointer를 원자 교체하며, 실패·empty result·rollback에서는 이전 active ready version을 유지한다. Legacy unversioned writer는 document_version_id IS NULL인 chunk만 조회·교체하고 active/historical version chunk를 삭제하거나 임베딩 재사용 source로 섞지 않는다. Lock은 apply/item progress transaction과 같은 수명을 가진다. Collection의 source_deleted는 job progress보다 우선하며 queue/finalize/cancel/recovery가 다른 sync state로 덮어쓰지 않는다.
FR-120 (MBA-265): DB source 실행은 stored table/column/JOIN 값을 SQL fragment가 아닌 PostgreSQL 단일 identifier로 인용하고 JOIN edge를 선택된 두 table로 제한해야 한다. LIMIT은 bounded integer로 정규화하며 expression, 추가 table 또는 statement로 해석될 수 있는 변조 설정은 임의 SQL을 실행하지 않고 configuration failure로 닫는다.
FR-121 (MBA-273): Manual Knowledge Base의 신규 document registration은 active organization의 KB write, active lifecycle, source_identity_id IS NULL, sync_state=manual과 빈 document slot을 모두 요구한다. Gateway application service는 KB row를 FOR UPDATE로 잠근 뒤 상태와 무관한 기존 Document 존재를 재검사하고 최초 row 하나만 생성한다. 두 번째 독립 source 또는 동시 race loser는 409 knowledge.document_slot_occupied로 닫으며 Client precheck나 document count만 보안·무결성 근거로 사용하지 않는다. Existing document의 process/retry와 같은 source identity의 version finalization은 append가 아니며 기존 document/version 계약을 유지한다.
FR-122 (MBA-273): KB 상세는 caller 권한과 canonical source/lifecycle/cardinality 상태를 결합한 can_register_initial_document capability를 반환한다. Client는 이 capability가 명시적으로 true인 빈 KB에서만 최초 source 등록 action을 제공하고 stale 409에서는 상세를 갱신한 뒤 별도 KB 생성 및 Knowledge Collection 연결을 안내한다. Manual KB의 유일한 Document를 삭제하면 같은 document write advisory lock과 KB/document row lock 아래 active version pointer를 해제하고 해당 version을 historical superseded로 전환한 뒤 slot을 다시 열어야 한다. 여러 독립 문서를 물리적으로 병합하거나 Collection 권한을 child KB use로 상속하지 않는다. Demo seed가 관리하는 각 KB는 정확히 하나 이하의 fixed Document를 가져야 하며, 여러 문서가 필요한 fixture는 별도 KB와 Collection membership으로 표현한다.
FR-123 (MBA-273): 과거 삭제 경로로 인해 active manual KB에 Document는 없지만 active version pointer만 남은 경우, canonical registration은 KB row lock 아래 version을 다시 읽어 legacy_document_id와 source_identity_id가 모두 제거된 stale version만 superseded로 전환하고 pointer를 해제한 뒤 최초 document를 생성할 수 있다. Version이 live document/source identity를 보유하거나 KB가 source-managed/non-manual 상태이면 자동 복구하지 않고 fail-closed한다.
FR-124 (MBA-273): DB document 설정이 새 connection_id reference를 저장할 때는 owner-scoped Connection row를 FOR UPDATE로 잠그고 document metadata commit까지 유지해야 한다. Connection delete도 같은 row lock 뒤 committed Document reference를 재검사해 저장과 삭제를 직렬화하며, missing/other-owner reference는 hidden, persistence failure는 safe unavailable reason으로 닫는다.
FR-125 (MBA-281): Knowledge DB source의 client-provided connection_id는 authority가 아니다. Upload/process/preview 저장 경계와 Gateway/Workflow Engine background DB dial 직전은 Shared Connection Use Resolver로 현재 execution subject owner 조건을 평가해야 한다. Dial 직전 판정은 작업 시작 시점의 권한 스냅샷이며 runtime row lock이나 실행 도중 revoke 취소를 의미하지 않는다. Document metadata에는 opaque connection_id만 Connection reference로 저장하며 name/type/host/database/username/credential을 복제하지 않는다. Missing, malformed, deleted, owner 변경과 non-owner는 Connection 상세·존재를 드러내지 않는 resource.hidden으로 닫고 adapter를 호출하지 않는다. Resolver 저장소 장애는 safe temporary failure, credential 복호화 실패는 저장값 fallback 없는 configuration failure로 닫는다. Organization-scoped Connection RBAC, 신규 permission table과 migration, runtime transaction/lock protocol은 이 요구사항의 범위가 아니다.
FR-126 (MBA-302): Gateway, Workflow Engine과 KC sync의 DB source runtime은 외부 DB dial 직전 독립된 짧은 session에서 owner 조건과 최소 credential configuration을 immutable snapshot으로 만든 뒤 transaction/session을 종료해야 한다. DbProcessor는 ORM Connection, encrypted storage field와 복호화 형식을 직접 해석하지 않으며 snapshot session 종료 뒤에만 connector를 생성한다. Snapshot은 저장된 PostgreSQL database/username identifier 의미와 기존 passwordless SSH agent/default-key 경로를 보존해야 한다.
FR-127 (MBA-302): Connection reference 저장·교체·삭제만 owner Connection row lock을 사용하고 전역 순서를 Connection -> KnowledgeBase -> Document/DocumentVersion으로 유지해야 한다. Existing Document 설정 writer는 Connection 다음 Document를 fresh lock하고 최초 조회 revision을 재검증해 stale writer를 명시적 non-retryable conflict로 닫아야 한다. Lock wait는 PostgreSQL local 2초로 제한하며 lock 획득 또는 같은 reference UoW의 flush/commit에서 발생한 timeout/deadlock/serialization victim은 전체 rollback 뒤 새 transaction에서만 재시도 가능한 safe transient failure로 처리한다. 외부 DB/storage/provider I/O, chunking과 embedding을 Connection row lock transaction 안에서 수행해서는 안 된다.
FR-128 (MBA-302): Runtime PostgreSQL DB source fetch는 connect/statement timeout, batch·총 row·총 byte 상한을 적용하고 limit 초과를 일부 성공으로 확정하지 않아야 한다. Success, empty, validation/configuration failure, external error와 cancellation에서 snapshot session과 adapter resource를 모두 정리하고 Connection identity, SQL, credential과 raw driver/lock detail을 log/audit/trace에 남기지 않아야 한다.
FR-129 (MBA-288): Document process, sync, approval resume와 KB embedding model reindex는 process-local BackgroundTasks가 아니라 PostgreSQL knowledge_document_ingestion_jobs를 실행 source of truth로 사용한다. Gateway는 current organization/resource authorization과 row lock 뒤 Document 설정·queued projection·job을 같은 transaction에 저장하고 commit 뒤 job UUID만 knowledge queue로 발행한다. Publish 실패는 committed job을 잃거나 request mutation을 rollback하지 않으며 due recovery가 재발행한다. Recovery는 발행 전에 DB clock 기반 bounded dispatch lease를 획득하고 lease가 유효한 동안 같은 job을 다시 발행하지 않는다.
FR-130 (MBA-288): 같은 Document에는 pending/running/retry_scheduled job 하나만 허용한다. 동일 active intent는 기존 job을 재사용하고 다른 intent는 safe conflict로 닫는다. Approval resume의 required status는 신규 job 생성에만 적용하며 첫 admission 뒤 상태가 바뀐 동일 재요청은 기존 job을 재사용한다. Input revision과 idempotency key는 protected digest와 opaque identifier만 사용하며 raw source config/path/content, credential, parser/provider payload를 job, Celery argument/result, log와 status response에 저장하지 않는다.
FR-131 (MBA-288): Knowledge worker는 job claim 직전에 requester의 current organization membership과 KB write 또는 sync authority를 재검사하고, opaque owner/fencing token, PostgreSQL actual wall-clock execution lease와 별도 DB session heartbeat를 사용한다. Transaction 시작 시각에 고정되는 now()는 lease 판정에 사용하지 않는다. Owner/fencing token이 일치하더라도 실제 DB wall-clock 기준 lease가 만료된 heartbeat, worker lock, progress와 success finalization은 거부한다. Valid lease/terminal/future retry duplicate는 실행하지 않고 stale lease는 bounded recovery한다. 최초 claim, recovery와 success/failure transition은 KnowledgeBase -> Document -> job 순서로 잠그고 상태를 다시 확인하며 recovery는 잠긴 KB/Document를 기다리지 않고 건너뛴다. Processor raw error가 아니라 계층 간 보존되는 allowlisted typed source reason을 사용하며 DB/API와 remote FILE egress의 timeout·connection·DNS, API 408/425/429/5xx와 soft time limit만 bounded backoff retry하고 egress policy 차단과 unknown은 safe dead-letter로 닫는다.
FR-132 (MBA-288): Active version finalization, Document completed projection과 ingestion job succeeded는 같은 transaction에서 fencing token과 유효한 execution lease를 확인해 확정한다. Stale attempt는 DB progress, Redis advisory progress, active pointer와 terminal job state를 갱신할 수 없다. Chunk 준비 단계는 별도 짧은 DB 조회로 current lease를 확인한 뒤 Redis progress를 99 이하로 발행하고 canonical 성공 commit 뒤에만 100을 발행한다. Unchanged no-op은 active ready version이 현재 Document를 소유할 때만 허용하며 다른 legacy Document version이면 재색인한다. Redis progress는 advisory projection이며 새 admission과 retry/cancel/dead-letter/recovery commit 뒤 해당 document의 이전 progress key를 삭제하고 DB job/document version을 대신하지 않는다. Lease를 잃은 worker는 cache를 삭제하지 않는다. Manual retry는 retryable dead-letter row를 running으로 되살리지 않고 새 generation을 생성한다.
FR-133 (MBA-288, MBA-359): Status/retry/progress, ingestion mutation과 processing document 상세 reconciliation처럼 ingestion job table을 읽는 API는 resource authorization 뒤 ingestion schema readiness를 확인한다. 필수 table/column/idempotency unique/active partial unique/due·lease index가 준비되지 않으면 raw DB error 대신 503 knowledge.ingestion_schema_not_ready로 fail-closed한다. Compose와 Kubernetes의 전용 Knowledge worker는 migration/schema readiness를 통과하기 전 knowledge queue를 소비하지 않는다. Provider-neutral Helm production reference는 bounded Knowledge worker와 recovery schedule을 소유한 singleton Celery Beat를 함께 활성화하고, worker-only 또는 non-positive replica/concurrency 설정을 render 단계에서 거부해야 한다. 실행 중 readiness는 exact local knowledge@<pod-hostname> Celery pong만 허용하고 다른 replica 응답을 성공으로 보지 않으며, Redis/control path 장애는 raw detail 없이 Unready로 표시하되 liveness restart loop를 만들지 않는다. Helm이 worker ServiceAccount 생성을 소유하는 설정은 worker가 참조하는 동일 리소스를 렌더링하고 외부 ServiceAccount 설정에서는 생성하지 않는다. LOCAL storage에서 worker를 활성화하면 Gateway와 worker는 같은 upload PVC를 사용해야 하며, production CLOUD storage는 shared local volume을 요구하지 않는다.
FR-134 (MBA-178): Knowledge API source, /rag/proxy/preview, remote document fetch와 external document preview는 server-owned operation profile과 address-pinned guarded transport를 사용해야 한다. Profile은 HTTPS/443, method, request/response 상한, content type, timeout과 bounded same-origin redirect를 고정한다. 승인 origin 안의 API query와 서명 URL query는 보존하되 userinfo, fragment, Host authority 위조, private·metadata address, HTTPS downgrade, ambient proxy와 cross-origin redirect는 외부 I/O 전에 거부해야 한다.
FR-135 (MBA-178): Knowledge outbound denial, timeout, oversized/unsupported response와 parser handoff failure는 credential header, body, source URL, resolved IP와 raw exception을 API, log, trace, audit, retry payload에 포함하지 않아야 한다. Fetch 실패는 이전 active ready document version을 대체하거나 retrieval-visible chunk를 생성해서는 안 된다.

MBA-305 Classification, Taxonomy And Processing Policy Target

보호 리소스 완결성 매트릭스는 이 section의 정책 완료와 후속 구현 경계를 구분한다. 문서 계약만으로 management API/UI, 저장, runtime/background, lifecycle 또는 audit 경계를 완료로 판정하지 않는다.

FR-134: Knowledge classification은 security_classification, platform-managed versioned document_type, organization-scoped versioned taxonomy_topic_ids, immutable chunking_profile_ref를 독립된 축으로 관리한다. 기존 documents.meta_info.classification은 ADR-0007의 보안 민감도 compatibility source이며 topic/type/profile 값으로 확대 해석하지 않는다.
FR-135: Platform document type registry는 stable opaque type ID와 immutable published version을 제공한다. Runtime capability는 registry의 allowlisted definition만 사용하고 organization 자유 문자열이나 AI 생성 label을 parser/profile capability로 해석하지 않는다. V1 semantic assignment는 document-level이며 mixed 문서는 registry의 mixed capability와 parser-derived block structure_kind로 표현하고 section/chunk-level semantic assignment는 후속 범위다.
FR-136: Organization taxonomy V1은 stable opaque topic ID를 사용하는 immutable-version single-parent rooted forest다. Publish는 cycle, orphan, duplicate stable ID, invalid parent/replacement와 동일 specificity profile mapping conflict를 거부한다. Published version에 한 번 등장한 topic ID는 Organization 수명 동안 같은 logical identity로만 유지하며 deprecated 또는 published successor에서 제거되어 tombstone이 된 ID를 active topic이나 다른 의미로 재사용할 수 없다.
FR-136a: Organization manager는 taxonomy draft와 published/superseded version의 bounded list 및 exact version detail을 다시 조회할 수 있어야 한다. Draft authoring response를 잃거나 관리 화면을 다시 열어도 기존 draft/history를 복구할 수 있어야 하며, 다른 organization version은 ownership-first safe hiding을 적용한다.
FR-136b: Taxonomy와 profile-policy draft는 별도 optimistic draft_revision을 가진다. PATCH, validate, impact preview와 publish는 exact draft revision을 요구하고 publish는 nullable current published pointer CAS도 함께 검증한다. 최초 publish의 expected current pointer null은 pointer가 실제로 없는 경우만 유효하고 absence-to-candidate 전환을 원자적으로 CAS한다. 두 publish는 같은 Organization-scoped classification-policy coordination row 또는 동등한 shared serializable boundary를 사용해 per-resource nullable CAS의 write skew를 막는다. Catalog lifecycle/reference race를 포함한 전역 lock 순서는 applicable Organization catalog, Platform catalog, coordination, taxonomy current, profile-policy current다. Stale editor 또는 stale validation 결과가 newer draft를 덮어쓰거나 publish할 수 없다.
FR-136c: Topic 0개인 taxonomy version은 valid empty forest로 publish할 수 있고 fake root를 요구하지 않는다. Empty publish는 기존 assignment를 삭제하거나 replacement로 바꾸지 않는다. Non-empty topic assignment는 참조한 stable topic이 candidate empty version에서 missing이므로 review_required다. Empty-topic assignment는 invalid reference가 없으므로 assigned taxonomy가 이전 published version이든 null이든 topic axis만 current_validation_required이며, 여기에는 taxonomy가 없을 때 만든 type-only assignment 뒤 최초 empty taxonomy를 publish한 경우도 포함한다. Document type/general profile path는 유지한다. Current profile policy에 topic rule이 남아 있으면 compatibility validation으로 publish를 거부한다. Taxonomy publish는 current profile-policy/document-type-registry와 Organization/Platform profile-catalog snapshot을, profile-policy publish는 current taxonomy/registry와 두 catalog snapshot을 current pointer 및 draft revision과 함께 CAS해 서로 호환되지 않는 current pair가 commit되지 않게 한다.
FR-136d: Taxonomy version은 Unicode Character Database 14.0.0을 고정한 server-owned unicode_14_0_nfkc_casefold_ws_v1 label normalization contract를 snapshot한다. NFKC, full Unicode case-fold, 재-NFKC와 Unicode whitespace trim/collapse로 만든 comparison key는 같은 direct parent에서 유일해야 하고 root topic은 implicit parent를 공유한다. Runtime Unicode library upgrade가 published version의 key를 바꾸지 않으며 data version 변경은 새 contract/version으로만 도입한다. Empty key는 knowledge.taxonomy_label_invalid, sibling collision은 knowledge.taxonomy_sibling_label_conflict이며 다른 branch의 같은 key는 허용한다. Deprecated topic의 replacement hint는 같은 Organization의 candidate version에서 active인 topic만 가리키고 existing published edge와 candidate edge를 합친 directed graph는 self/cross-organization/missing target, cycle과 8 edge 초과 path를 허용하지 않는다. Invalid replacement는 knowledge.taxonomy_replacement_invalid, 8 edge 초과 path는 knowledge.taxonomy_replacement_depth_exceeded다. Published replacement edge는 identity ledger와 함께 append-only로 보존하고 merge/split hint는 assignment를 자동 변경하지 않는다. Unresolved violation이 있는 publish는 knowledge.taxonomy_publish_validation_failed로 종료하고 published version, current pointer, ledger와 audit를 만들지 않는다.
FR-136e: Taxonomy impact preview는 모든 publish의 필수 precondition이다. Preview는 Organization/actor, candidate version, exact draft revision, nullable current taxonomy/profile-policy, document-type registry, Organization/Platform profile catalog와 server-owned assignment impact snapshot revision을 최대 10분 opaque impact_preview_revision으로 bind하고 bounded impact bucket만 반환한다. Assignment current pointer 또는 canonical content처럼 impact basis를 바꾸는 mutation은 같은 transaction에서 snapshot revision을 전진시키며 async projection lag를 publish 허용 근거로 사용하지 않는다. Publish는 expected_impact_preview_revision과 impact_acknowledged=true를 요구하며 permission, scope, expiry와 전체 snapshot을 transaction 안에서 다시 검증한다. Preview가 없거나 stale이면 knowledge.taxonomy_impact_preview_stale로 version/current pointer/ledger/audit를 변경하지 않는다. Impact 0개와 non-empty taxonomy도 이 절차를 생략하지 않고 hidden KB/document identity와 exact denied count를 preview/audit에 저장하지 않는다.
FR-136f: assignment_impact_snapshot_revision은 normalized no-op을 제외한 assignment current pointer create/replace/delete, manual takeover, suggestion accept, current-validation, lock/unlock, 새 canonical materialization input hash, impact scope를 바꾸는 KB/document lifecycle transition, explicit profile override set/change/clear, current Processing Decision pointer 변경과 active artifact pointer 또는 ready|purging|purged availability 전이에서 authoritative mutation/audit와 같은 Unit of Work로 전진한다. 이 processing 상태는 reindex_candidate_count의 active-ready/current-decision predicate 입력이다. Suggestion create/reject/expire, read/preview, canonical input hash가 같은 source generation, staging build/job/manifest 생성과 current pointer/availability no-op은 전진시키지 않는다. Taxonomy/profile-policy/registry와 Organization/Platform profile-catalog revision은 impact token에 별도 exact snapshot으로 bind한다.
FR-136g: V1 taxonomy version은 complete-tree create/PATCH/detail을 사용하며 topic definition 최대 1,000개, candidate replacement edge 합계 최대 2,000개로 제한한다. Server는 duplicate 제거와 normalization 전에 raw array count와 각 raw label의 UTF-8 512 byte bound를 검사한다. 이어서 pinned normalization을 적용하고 normalized comparison key의 non-empty와 UTF-8 512 byte bound를 sibling uniqueness, graph traversal과 DB/provider/mutation 전에 검사한다. 각 초과 입력은 knowledge.taxonomy_topic_count_limit_exceeded, knowledge.taxonomy_replacement_edge_limit_exceeded 또는 knowledge.taxonomy_label_invalid로 mutation 없이 거부한다. Version detail은 pagination 없이 complete forest를 반환하되 이 bound를 넘지 않는다. Partial topic pagination/editing이나 한도 증가는 별도 versioned API/CAS/recovery 계약 없이는 도입하지 않는다.
FR-136h: Stable taxonomy topic_id는 server만 발급한다. Client는 새 topic마다 allocation request 안에서 unique한 UUID draft_topic_key를 보내고 parent/replacement는 existing topic_id 또는 같은 request의 new key를 discriminated reference로 사용한다. 성공한 transaction은 key-to-ID mapping을 mutable draft의 current complete-tree detail에 보존·반환해 응답 유실 뒤 current draft_revision과 mapping을 다시 조회할 수 있게 한다. Mapping 수는 current topic 수 이하이고 successful allocation 뒤 subsequent mutation은 server ID를 사용하며 current-mapped key 재제출은 409 knowledge.taxonomy_draft_topic_key_conflict다. Mapping은 topic 제거와 같은 CAS transaction에서 제거된다. Removed key를 다시 제출하면 새 stable ID를 발급하고 old ID를 재사용하지 않는다. Missing/invalid/non-unique/out-of-draft key, key와 existing ID 동시 지정 또는 잘못된 reference shape는 422 knowledge.taxonomy_draft_topic_reference_invalid이며 모두 partial mutation 없이 닫는다. Draft key는 assignment/runtime identity가 아니며 published/superseded projection은 stable ID만 반환한다.
FR-136i: Taxonomy impact bucket은 taxonomy_impact_bucket_v1로 versioning하고 independent exact count를 none=0, small=1..10, medium=11..100, large=101+로 변환한다. affected_assignment_count는 같은 Organization의 processing-eligible active KB/document current assignment 중 candidate와 current taxonomy의 topic-axis freshness 또는 resolver-eligible topic ID set/primary가 달라지는 row를 하나씩 센다. Exact taxonomy version ID 차이만 있거나 이미 stale인 assignment가 candidate에서도 같은 tuple을 유지하면 제외한다. reindex_candidate_count는 그 affected subset 중 active-ready artifact가 있는 row만 평가한다. Current Processing Decision의 비교 가능한 materialization_input_fingerprint가 있으면 자동 replacement나 human confirmation 없이 candidate를 적용했을 때 fingerprint가 다른 row만 세고, active-ready legacy artifact는 있지만 current decision 또는 비교 가능한 fingerprint가 없으면 동일 materialization을 증명할 수 없으므로 보수적으로 센다. Resolved scoped profile ref/source/status 차이만 있고 normalized materialization fingerprint가 같음이 증명되면 제외해 새 Decision Manifest와 satisfied_existing으로 처리한다. Assignment 없는 KB, active-ready artifact가 없는 row와 purging|purged artifact는 reindex candidate에서 제외하되 assignment tuple이 달라지는 active·processing-eligible target은 affected에 남는다. Archived/deleted KB/document 또는 processing-ineligible target은 두 count에서 제외하며 lifecycle/availability in-out은 impact snapshot revision을 전진시킨다. Response/publish precondition/token은 contract version을 bind하고 exact count와 hidden identity는 반환·감사하지 않는다.
FR-137: Taxonomy rename/move는 stable topic ID를 보존한다. Organization-lifetime topic identity ledger는 published ID와 terminal tombstone을 append-only로 소유하며 first-published/tombstone write는 taxonomy current pointer와 canonical audit를 확정하는 같은 transaction에 포함한다. Deprecate/merge/split은 기존 assignment를 삭제하거나 replacement에 자동 이관하지 않으며 deprecated/missing topic은 review_required로 보존하되 hard filter, ranking boost와 profile mapping 입력에서 제외한다. Tombstoned ID를 다시 active로 만들거나 다른 logical topic에 붙이지 않고 새 의미에는 새 ID를 발급한다.
FR-138: Document-level KB의 effective classification은 document type 하나, topic ID set, optional primary topic과 document-type/topic axis별 authority source·lock을 하나의 atomic assignment revision으로 갱신한다. Manual PUT은 complete effective set과 non-empty unique manual_axes를 제출한다. 선택한 unlocked axis만 value/manual authority를 replace 또는 takeover하고 선택하지 않은 axis는 request value가 current effective value와 일치해야 하며 server가 value/source/lock과 최초 assigned snapshot을 보존한다. 따라서 omitted topic을 기존 set에 암묵적으로 merge하지 않으면서 locked 반대 axis를 훼손하지 않는다. Current assignment가 없으면 두 axis를 모두 선택해야 하며 empty/duplicate/unknown axis와 incomplete first create는 knowledge.classification_manual_axes_invalid, unselected value mismatch는 knowledge.classification_unselected_axis_conflict, selected locked axis는 knowledge.classification_manual_authority_conflict로 assignment/audit 없이 닫는다. KB current assignment pointer는 nullable exact precondition이며 최초 PUT 또는 suggestion accept는 required expected_assignment_revision=null로 부재를 CAS해 revision 1을 만든다. Sentinel revision이나 read 뒤 무조건 insert를 허용하지 않고 concurrent first mutation은 한 winner만 commit한다. taxonomy_version_id는 nullable이지만 required다. Current taxonomy pointer가 없을 때만 null taxonomy version, empty topic set과 null primary를 허용하고 pointer가 존재하면 empty taxonomy를 포함한 exact current version을 요구한다. Null taxonomy와 non-empty topic/primary 조합은 knowledge.classification_taxonomy_shape_invalid, same-scope nullable current pointer mismatch는 knowledge.classification_taxonomy_snapshot_conflict로 mutation 없이 닫는다. Current expected revision과 normalized set이 같고 selected manual_axes의 source가 모두 이미 manual일 때만 unchanged no-op이다. 선택한 axis가 rule, accepted-suggestion, fallback 등 non-manual이면 동일 value의 명시적 PUT도 해당 axis의 manual takeover를 포함한 complete revision과 canonical audit를 만들고 unselected axis authority는 보존한다. Stale expected revision은 값이 같아도 conflict다.
FR-138a: Manual assignment, rule/AI suggestion candidate와 resulting effective assignment의 topic ID set은 최대 32개다. Client request 배열은 중복 제거 전에 길이를 검사하고 duplicate를 자동 제거하지 않으며 33개 이상은 knowledge.classification_topic_limit_exceeded로 DB/provider/mutation 전에 거부한다. Rule/classifier output은 adapter 결과 직후 같은 bound를 적용해 oversized candidate를 durable suggestion, assignment 또는 audit로 저장하지 않는다. Canonical storage와 fingerprint에서는 unordered set으로 정규화하되 이 bound를 retrieval 결과 수나 chunk recall limit로 해석하지 않는다.
FR-138b: Manual assignment request는 reason_code 또는 free-text reason을 받지 않는다. Server는 first create나 selected value 변경이면 manual_assignment, selected value는 모두 같고 non-manual authority만 manual로 바뀌면 manual_takeover를 파생하며 value와 authority 동시 변경에는 manual_assignment를 우선한다. Unknown request field와 Client reason은 DB 조회·mutation·audit 전에 knowledge.classification_request_invalid로 거부하고 canonical audit에는 이 server-derived bounded reason만 저장한다.
FR-139: Effective assignment는 KB scope에서 유지하되 effective_from_content_revision_ref와 last_validated_content_revision_ref를 구분한다. Current physical DocumentVersion ref는 canonical content revision/hash에 매핑하는 transition bridge일 뿐이며 profile reindex output ID 변경만으로 assignment를 stale 처리하지 않는다. Target cutover 전 legacy multi-document KB는 exact legacy document/version 없이 KB-wide mutation을 허용하지 않고 migration_required로 fail-closed한다.
FR-139a: KB write actor는 expected assignment, current registry/taxonomy와 canonical content revision을 사용해 existing assignment를 명시적으로 current-validation할 수 있다. 성공은 effective set, axis별 source/lock, effective-from과 최초 assigned snapshot을 보존한 채 새 assignment revision의 last_validated_*만 전진시키고 canonical audit와 같은 transaction에서 확정한다. 성공한 validation은 current resolver state와 reindex_required projection을 다시 계산하되 reindex job이나 active pointer 변경을 자동 시작하지 않는다. 이미 current면 unchanged이며 missing/deprecated reference는 assignment를 바꾸지 않고 review_required로 남긴다. Null-taxonomy empty set 뒤 최초 taxonomy publish는 invalid reference가 아니므로 topic axis만 current_validation_required와 resolver-ineligible로 구분하고 document-type axis는 독립적으로 유지한다. Explicit validation은 empty set을 보존한 채 last-validated taxonomy ref를 전진시킨다.
FR-139b: Canonical materialization input hash가 바뀌어 새 canonical content revision이 생기면 assignment provenance를 자동 변경하지 않고 axis별 content freshness를 계산한다. Locked axis는 review_recommended로 resolver/filter/mapping 입력을 유지하고, unlocked manual|rule|accepted_suggestion|fallback axis는 current_validation_required로 표시해 hard filter, ranking, profile mapping과 materialized assignment-derived field에서 제외한다. Resolver는 remaining eligible axis 또는 general profile로 fail-safe fallback하고 stale assignment만으로 새 processing을 전면 차단하지 않되 old active-ready artifact를 replacement ready 전까지 유지한다. Current-validation은 exact content revision과 content_reviewed|combined_review reason으로 manual confirmation provenance를 별도 기록하고 original axis source를 바꾸지 않는다. Taxonomy/registry-only reason은 content mismatch를 clear할 수 없다. Canonical input hash가 같은 source generation 또는 profile-only output 변경은 assignment를 stale 처리하지 않는다.
FR-139c: Unlocked axis의 false -> true lock은 non-null expected assignment revision과 exact current canonical content revision을 요구하고 두 snapshot을 같은 transaction에서 재검증한다. Target axis가 current일 때만 lock할 수 있으며 current_validation_required는 explicit current-validation, review_required는 current option을 사용한 complete assignment replacement를 먼저 수행한다. Invalid axis가 이미 locked이면 KB manage 또는 Organization manager가 unlock한 뒤 KB write 또는 Organization manager가 complete replacement를 수행하며 write-only actor가 lock을 우회하지 않는다. Stale snapshot은 knowledge.classification_lock_snapshot_conflict, non-current target은 knowledge.classification_lock_not_current로 assignment/audit 없이 닫는다. 이미 locked인 exact-state request는 unchanged일 수 있다. Unlock은 stale content 또는 missing/deprecated reference에서도 authority를 낮출 수 있어야 한다. Client content precondition은 받지 않지만 current assignment와 canonical content pointer를 같은 transaction에서 직렬화한 complete revision으로 current freshness/resolver projection을 다시 계산한다.
FR-139d: Current-validation은 server가 계산한 changed dimension set과 fixed reason을 정확히 일치시킨다. content|taxonomy|document_type_registry 중 하나만 바뀌면 각각 content_reviewed|taxonomy_updated|registry_updated, 둘 이상이면 combined_review만 허용한다. Changed dimension이 없으면 reason을 해석·저장하지 않고 unchanged로 종료한다. Content mismatch에 content-confirming reason이 없으면 knowledge.classification_content_confirmation_required, 그 밖의 mismatch는 knowledge.classification_validation_reason_mismatch로 전체 rollback한다. Content-confirming은 server set에 content가 포함된 validation만 뜻하며 KB write와 별도로 effective content_read 및 applicable current display/raw policy를 요구한다. Source-managed KB는 Organization manager도 우회할 수 없는 fresh source authorization/display gate와 commit 직전 revision/watermark 재검증을 통과해야 하며 실패는 source identity를 숨기는 resource.hidden safe 404다. Taxonomy/registry-only validation은 content 확인 provenance를 만들지 않는다.
FR-140: Manual lock, manual assignment, human-accepted AI suggestion, approved deterministic rule, unknown fallback 순서로 authority를 document type과 topic axis마다 적용한다. Effective response, mutation, audit와 UI는 단일 합성 source가 아니라 axis별 source/lock을 사용한다. AI/rule suggestion은 선택한 axis의 lock/manual authority를 해제하거나 security classification, permission, retention, profile activation과 active pointer를 변경할 수 없다. Suggestion accept는 immutable candidate의 non-empty document_type|topics axis subset만 선택하고 선택하지 않은 axis의 value/source/lock을 보존한 complete assignment revision을 원자적으로 만든다. Empty/duplicate/unknown/candidate 밖 axis 또는 absent assignment를 complete하게 만들 수 없는 selection은 fixed validation error로 닫는다. 선택한 axis의 unlocked manual assignment도 덮어쓰지 않으며 blocked candidate를 채택하려면 complete set과 해당 manual_axes를 사용한다. 선택한 axis만 manual authority로 전환하고 unselected locked/non-manual axis는 보존한다. Effective set이 같아도 selected non-manual axis의 manual 전환은 no-op이 아니며 revision/audit와 resolver/reindex-required projection을 확정하되 reindex job을 자동 시작하지 않는다. 이후 명시적 admission에서 materialization input이 같으면 existing artifact satisfaction으로 수렴한다.
FR-140a: Suggestion accept는 같은 expected_assignment_revision과 non-empty accepted_axes를 제출하는 server-owned accept impact preview를 먼저 요구한다. Preview는 candidate를 hypothetically 적용한 axis별 unchanged|value_changed|authority_changed, profile resolution change, reindex_required와 active-ready availability만 safe projection한다. Value 변경은 authority 동시 변경보다 우선해 value_changed, value가 같고 authority만 바뀔 때만 authority_changed이며 unselected axis는 unchanged다. Organization/KB/actor/suggestion/state/accepted axes 및 current content, assignment, taxonomy/registry/profile-policy/catalog/override/resolved-profile, nullable current Processing Decision ref와 resolver/materialization fingerprints, nullable active Artifact Build ref·generation·availability와 materialization/integrity fingerprints를 최대 10분 opaque accept_preview_revision의 server-side validation state에 bind한다. Accept는 expected_accept_preview_revision을 필수로 보내고 fresh source/display gate와 transaction 안에서 전체 snapshot을 재검증한다. Stale token은 assignment/outcome/audit 없이 fixed conflict다. Fresh authorization을 통과하고 terminal outcome의 stored non-reversible request fingerprint가 일치하는 exact retry는 preview expiry·stale 검사보다 먼저 기존 result로 수렴하므로 만료 뒤에도 duplicate assignment/audit/reindex intent를 만들지 않는다. Raw token/digest는 저장·감사하지 않는다.
FR-141: Classification suggestion은 exact canonical content revision/hash, nullable taxonomy pointer/document-type registry, proposed axis와 tagged generator_kind=deterministic_rule|ai_classifier provenance에 묶인다. 두 kind 모두 immutable generator_contract_ref가 필수다. Deterministic kind는 approved rule-set/version만 참조하고 model/prompt/calibration/confidence field는 absent이며, AI kind는 classifier policy, prompt-template contract, model catalog/effective model, calibration revision/state와 bounded confidence bucket이 필수다. Fake 또는 kind와 맞지 않는 non-applicable reference를 저장하지 않는다. Current taxonomy가 없으면 null taxonomy + empty topic set의 type-only candidate만 허용한다. Canonical content 또는 taxonomy/registry가 바뀌면 null-to-version 전환을 포함해 아직 suggested인 candidate만 expired이며 새 content revision에 자동 승계하지 않는다. Accepted/rejected/abstained terminal outcome은 다시 쓰지 않고 accepted assignment의 current-validation 상태와 provenance를 별도로 유지한다. Accept는 nullable current taxonomy pointer와 candidate snapshot, selected axes 및 required nullable assignment revision을 assignment/outcome/audit transaction 안에서 다시 검증한다. Subset accept도 suggestion 전체를 terminal accepted로 전이하고 accepted axes를 provenance에 남기며 선택하지 않은 proposed axis를 child/retry 후보로 유지하지 않는다. Profile-only reindex output ID 변경은 suggestion을 expire시키지 않는다. 상태는 suggested/accepted/rejected/abstained/expired를 구분한다. Review 목록은 기본 limit 25, 최대 50의 opaque keyset cursor와 created_at DESC, suggestion_id DESC tie-break를 사용하고 state filter/scope를 cursor에 bind하며 total/hidden count를 반환하지 않는다. Review window는 생성 후 최대 30일이고 terminal/expired row는 전이 후 최대 30일 뒤 purge하며 assignment/audit retention과 분리한다. Accept transaction은 opaque suggestion ref, accepted outcome, selected axes와 같은 tagged safe provenance를 assignment revision과 canonical audit에 남겨 operational suggestion purge 뒤에도 재현한다. Raw prompt/completion/rationale, raw score와 content는 snapshot하지 않는다.
FR-142: Raw model score는 독립 holdout calibration 전까지 correctness probability가 아니다. Uncalibrated score는 자동 적용, 보안 판단과 정확도 UI에 사용하지 않고 classifier는 out-of-taxonomy, ambiguous와 low-confidence 입력에서 abstain할 수 있어야 한다.
FR-143: Effective classification 조회는 KB read, unlocked type/topic mutation·current-validation·suggestion review·profile preview/reindex는 KB write, lock/unlock과 explicit profile override options/read/set/clear는 KB manage, organization taxonomy/profile catalog/profile policy current/history read·author·publish와 profile deprecate는 Organization manager를 요구한다. Content mismatch를 해소하는 current-validation은 추가로 effective KB content_read와 applicable current display/raw policy를 요구한다. ADR-0034에 따라 같은 active organization의 Organization manager는 각 KB-scoped read/write/manage/content_read 요구사항을 별도 KB grant 없이 충족하는 resource-action override다. 이 override도 source authorization, display/raw policy와 ownership-first hiding을 우회하지 않으며 catalog_manage, permission_delegate, lifecycle_manage, sync_manage 같은 위임된 Knowledge domain action을 Organization manager override로 확대 해석하지 않는다.
FR-143a: Organization 또는 KB 하위 resource ID는 parent ownership을 lifecycle, authority와 semantic state보다 먼저 검증한다. Cross-organization taxonomy/policy version, assignment/suggestion, organization-owned profile/override와 reindex reference는 safe 404로 숨기며 platform registry reference는 current registry visibility/selectability의 fixed error contract를 사용한다.
FR-143b: Source-managed KB의 모든 KB-scoped classification/resolver read와 mutation은 parent ownership과 required KB action을 확인한 뒤 assignment, lock, override 또는 resolver-specific row의 lookup/projection/mutation 전에 fresh requester source authorization과 applicable display policy를 요구한다. Effective classification GET/options, assignment PUT, current-validation, lock/unlock, explicit profile override GET/options/set/clear와 resolve-preview가 포함된다. Missing/revoked/stale/denied gate는 KB read/write/manage grant나 Organization manager override와 무관하게 ADR-0017의 404 resource.hidden으로 닫고 assignment/override 존재, stable ID, axis source/lock, security classification과 resolver 상태를 반환하거나 변경하지 않는다. Mutation은 외부 authorization session을 종료한 뒤 bounded revision/watermark를 transaction으로 전달하고 commit 직전에 current KB authority와 함께 다시 검증한다. Revoke winner는 assignment/lock/override, impact snapshot, audit와 reindex projection을 만들지 않는다. Manual KB에는 이 source gate를 적용하지 않는다.
FR-144: Source-managed content의 classification suggestion 생성, 각 목록 page와 accept-preview/accept/reject 및 모든 current-validation은 KB 권한과 별도로 fresh source authorization 및 display policy를 candidate/content projection 또는 mutation 전에 다시 평가한다. Changed dimension에 content가 포함된 validation만 추가 content_read, current display/raw policy와 content-confirmation provenance를 요구하고 taxonomy/registry-only validation은 content-plane 권한을 요구하지 않지만 source-managed resource hiding gate는 생략하지 않는다. Suggestion 생성은 추가로 raw policy, redaction과 provider egress를 통과해야 한다. Source authorization revision/watermark는 review/validation commit 직전에 다시 검증하고 revoked/stale/denied 상태는 resource.hidden safe 404로 candidate identity/state/count/confidence와 terminal outcome 또는 validation 결과를 숨긴 채 fail-closed한다. Organization manager와 KB manage도 source gate를 우회하지 않고 cursor/suggestion ID는 capability가 아니다. Raw source content, prompt/completion/rationale, credential과 provider raw response는 durable suggestion/audit/trace에 저장하지 않는다.
FR-145: Profile mapping policy는 immutable version이다. Current Organization profile-policy가 존재하면 resolver는 valid explicit override, type+primary, type, primary, optional organization general, required policy platform general 순서로 하나의 exact profile revision을 선택한다. Unknown/unclassified/stale mapping, matching rule 부재 또는 organization general 부재는 다음 유효한 general rule이나 policy platform general fallback을 사용하고 동일 specificity 충돌 및 platform general 부재는 publish 전에 거부한다. Missing/deprecated/incompatible explicit override는 조용히 fallback하지 않고 review-required conflict로 reindex를 차단하며 기존 active ready version을 유지한다. Current profile-policy가 없는 branch는 FR-146e의 exact Platform default를 사용하며 이를 published policy의 platform general과 혼합하지 않는다.
FR-145a: KB manage 또는 같은 active organization의 Organization manager actor는 current selectable profile option과 nullable current override/revision을 조회하고 explicit override를 set 또는 clear할 수 있다. Options, valid override read, resolved profile read와 set target은 profile-policy와 같은 strict profile_revision_ref={catalog_scope: organization|platform, profile_revision_id}를 사용하고 bare revision ID 또는 null/non-object/missing/unknown/non-string/empty/extra-field ref를 허용하지 않는다. Organization scope는 active Organization 소유 published/selectable revision, Platform scope는 approved published/selectable revision만 가리키며 scope가 같은 opaque ID를 결정적으로 구분한다. Override read는 organization/KB/actor, current canonical content, nullable assignment, registry/nullable taxonomy, nullable mapping policy, nullable override, Platform default ref, Organization/Platform profile catalog/selectability와 nullable resolved exact scoped profile ref를 bind한 non-capability opaque resolver revision, nullable current profile-policy version 및 effective_resolution_status=resolved|review_required|platform_default_unavailable을 반환한다. Set/clear는 required nullable expected assignment/profile-policy version, expected override/resolver revision을 요구하고 전체 resolver vector를 같은 transaction에서 lock/CAS 또는 동등한 serializable validation으로 다시 확인한 뒤 canonical audit와 reindex_required projection을 확정한다. Opaque resolver token은 명시적 nullable pointer precondition을 대체하지 않는다. Assignment 또는 current profile-policy가 없는 platform-default fallback resolver에서는 null이 exact absence이며 command 사이에 pointer가 생기거나 Platform default ref/catalog revision이 바뀌면 stale conflict다. 어느 input 또는 scope/actor라도 바뀌면 override/audit/projection 전체를 rollback하며 자동 reindex나 active pointer 변경을 만들지 않는다. 현재 override가 missing/deprecated/incompatible해도 generic state와 clear용 override revision을 조회할 수 있고 recovery path는 target profile 조회에 막히지 않아야 한다. Default-required branch가 unavailable이어도 GET/options는 200 generic state와 resolver revision을 반환해 selectable override set/change를 허용하며 clear는 fixed 503으로 닫는다. Source-managed KB에서는 GET/options가 override/resolver lookup 전에 FR-143b의 fresh source/display gate를 통과해야 하고 set/clear는 같은 gate의 bounded revision/watermark를 commit 직전에 current KB authority와 함께 다시 검증한다. Revoke winner는 override, impact snapshot, audit와 reindex_required projection을 만들지 않는다.
FR-145b: Organization manager는 profile mapping policy draft와 published/superseded version의 bounded list 및 exact version detail을 다시 조회할 수 있어야 한다. List/detail은 stable pagination, ownership-first safe hiding과 authoring-safe projection을 사용한다.
FR-145c: Profile preview는 organization/KB/actor, current canonical content와 내부 resolver/materialization input fingerprints를 bind한 최대 10분 수명의 non-reversible opaque resolution_revision만 Client에 반환한다. Raw content/hash와 내부 fingerprint는 노출하지 않으며 reindex는 current permission과 server recomputation을 다시 검증한다. Existing admission receipt가 없는 fresh request의 scope/expiry/current mismatch는 job이나 decision mutation 없이 stale conflict다.
FR-145d: Reindex admission은 job 생성 여부와 무관하게 organization/KB/actor/operation-scoped idempotency key digest, canonical request digest와 safe result ref를 durable receipt로 저장한다. Parent ownership, current KB write 또는 Organization manager authority와 applicable fresh source authorization을 receipt lookup/result projection 전에 확인한다. Source-managed denied/revoked/stale/unknown은 resource.hidden safe 404로 receipt/decision/satisfaction/job identity를 숨기고 어떤 admission mutation도 만들지 않는다. Manual KB source gate는 not_applicable이다. Gate를 통과한 같은 key/request의 exact replay만 token expiry 검사보다 먼저 기존 result로 수렴하고, 같은 key의 다른 request는 conflict이며, receipt가 없을 때만 token scope/expiry/current input을 검증한다. External source check session은 mutation 전에 종료하고 nullable bounded revision/watermark를 replay return 또는 fresh admission commit 직전에 current permission과 함께 authoritative CAS로 재검증한다. Revoke winner는 replay result를 반환하지 않고 fresh receipt/decision/satisfaction/current-pointer/job 또는 knowledge.processing_reindex.admitted success audit를 만들지 않는다. ADR-0017 target/source 비노출 request-scoped security audit는 admission result audit와 분리해 허용할 수 있다. Receipt actor와 source revision ref는 execution provenance이며 authorization capability가 아니다. Physical job을 처음 만든 job_created actor를 job execution actor로 불변 bind하고 다른 actor의 job_reused receipt가 이를 교체하지 않는다. Physical embedding build가 필요한 fresh job은 LLM Credentials domain의 authoritative port가 exact profile model/provider, Organization과 job actor를 기준으로 active credential, verified relation과 current use를 평가해 eligible credential이 정확히 하나일 때만 safe refs/revisions의 Knowledge processing embedding binding을 발급받아야 한다. 후보 0개/복수는 preference/name/order/owner/default fallback 없이 409 knowledge.processing_embedding_credential_unavailable로 receipt/decision/job/success audit 없이 닫는다. Binding issue와 fresh job commit 사이에는 credential lifecycle/relation/permission/provider-routing revision을 row lock/CAS 또는 동등한 serializable validation으로 다시 확인하고 revoke/change winner도 같은 zero-write로 닫는다. Existing job_reused는 caller credential을 선택하지 않고 original job actor/binding을 그대로 반환하며 다음 worker gate가 validity를 판정한다. Original actor 또는 binding의 authorization loss로 terminal cancel된 job은 다른 actor/credential에게 승계하지 않으며, 현재 authorized actor가 fresh preview와 새 idempotency request로 새 generation을 admission해야 한다. Raw token과 내부 fingerprint는 저장하지 않고 receipt는 연결된 job/result operational retention과 같은 기본 30일 동안 유지한다.
FR-145e: Reindex worker는 claim과 각 source/provider external I/O batch 직전에 짧은 authorization session으로 job execution actor의 current active organization membership, effective KB write 또는 Organization manager authority, applicable source authorization 및 bound embedding credential의 active lifecycle, exact model/provider relation, current use, credential lifecycle/relation/permission/provider-routing revision을 다시 평가하고 session/transaction을 외부 I/O 전에 종료한다. 어느 revoke/change가 gate 전에 commit되면 adapter를 호출하지 않는다. Gate 뒤 commit된 revoke는 이미 시작한 bounded call을 중단시키지 않지만 다음 external batch와 finalization을 차단한다. Finalization 직전 fresh source/credential gate의 외부 호출/session도 종료하고 bounded decision revision/watermark만 finalizer transaction에 전달한다. Finalizer는 permission/source authorization 및 embedding binding revision을 revoke와 직렬화되는 authoritative CAS나 동등한 serializable boundary에서 다시 확인한다. Current fence/lease가 유효한 membership/KB/source authorization loss는 fixed knowledge.processing_execution_not_authorized, embedding binding loss는 fixed knowledge.processing_embedding_credential_unavailable reason의 terminal cancelled와 staging cleanup outbox intent만 확정하고 Decision Satisfaction, current decision/active artifact pointer를 만들지 않는다. Fence/lease를 잃은 worker는 cancellation이나 cleanup intent도 commit하지 않는다. Receipt, job ID, preview token과 admission authorization/binding 결과를 capability로 사용하지 않는다.
FR-145f: 최초 successful reindex admission은 네 public result 모두 canonical knowledge.processing_reindex.admitted, audit_logs.status='success'를 사용하고 safe result_status=unchanged|satisfied_existing|job_created|job_reused로 구분한다. Receipt, result에 필요한 decision/satisfaction/job/current-pointer mutation과 audit은 같은 Unit of Work에서 commit 또는 rollback하며 audit 실패는 admission 전체를 rollback한다. Exact authorized receipt replay는 read-only recovery라 새 audit를 만들지 않는다. Source-hidden/idempotency conflict/embedding credential unavailable은 이 success action을 만들지 않는다. Source-hidden path의 optional request-scoped security audit는 ADR-0017 target/source 비노출 allowlist를 따르고 admission result identity와 분리한다. 모든 failure metadata에는 idempotency key/token digest, internal fingerprint, source/credential identity, credential candidate count와 revoked grant/relation/permission detail을 저장하지 않는다.
FR-145g: Reindex admission idempotency는 body field 없이 required Idempotency-Key header 하나만 사용한다. 값은 lower-case hyphenated canonical UUID 36자와 정확히 같아야 하며 nil, upper-case, whitespace, braces/URN, malformed/다른 길이, comma-joined/duplicate와 missing header는 coercion 없이 knowledge.processing_idempotency_key_invalid로 거부한다. Header name case만 HTTP 규칙에 따라 case-insensitive다. Server는 canonical ASCII bytes의 SHA-256 digest만 organization/KB/actor/operation receipt key로 저장하고 typed body tuple의 canonical request digest와 분리한다. Same key/exact tuple만 replay하며 same key/different tuple은 conflict고 raw key는 response/application-access log/audit/trace에 남기지 않는다.
FR-146: Processing profile revision은 platform 또는 organization scope의 immutable published catalog resource이며 tokenizer/version, chunk unit/size/overlap, boundary, parser, retrieval representation, embedding ref와 algorithm version을 재현 가능하게 고정한다. Policy/override는 active organization 소유 revision 또는 approved platform revision만 참조하고 기존 character 기반 chunk_size/chunk_overlap 값은 token 값으로 조용히 재해석하지 않는다.
FR-146a: Organization profile catalog는 stable opaque profile identity, mutable draft revision, immutable published revision과 monotonic organization_profile_catalog_revision을 제공한다. Organization manager는 bounded list/detail, identity와 first draft 생성, successor draft 생성, draft PATCH/validate/publish 및 published revision deprecate를 수행한다. First-create request는 exact empty JSON object {}만 허용하고 성공 시 identity, base_revision_id=null, draft_revision=0, config=null인 incomplete draft shell 및 canonical create audit를 원자 생성하며 draft-only create는 catalog revision을 전진시키지 않는다. Missing/non-object/extra field는 DB 조회 전 fixed 422 zero-write이고 첫 complete config PATCH 전에는 validate/publish할 수 없다. Successor command는 exact base_revision_id를 요구하고 path의 same-organization profile identity에 속한 immutable published revision의 normalized config만 복제해 새 draft에 immutable lineage로 기록한다. Cross-organization 또는 다른 profile identity의 base는 ownership-first safe 404, same-scope draft/deprecated/non-published base는 409 knowledge.processing_profile_successor_base_invalid로 draft/catalog/audit 없이 닫는다. Draft는 draft_revision, publish/deprecate는 expected Organization catalog revision CAS를 사용하고 lifecycle mutation과 canonical audit를 같은 transaction에서 확정한다. Policy publish와 override mutation도 applicable Organization catalog revision을 검증해 deprecate와 신규 current reference 생성이 동시에 commit되지 않게 한다. Published config는 수정/hard-delete하지 않는다. Current profile policy 또는 current override가 직접 참조하는 revision은 knowledge.processing_profile_in_use로 deprecate를 차단한다. Historical provenance와 active-ready artifact는 유지하지만 deprecated revision은 신규 policy/override option과 existing-artifact satisfaction에서 제외하고 deprecation 자체는 reindex/pointer swap을 시작하지 않는다.
FR-146b: Platform profile catalog는 Organization catalog와 독립된 monotonic platform_profile_catalog_revision과 selectability lifecycle을 가진다. Organization API는 approved published option, catalog revision과 exact Platform default pointer를 read-only로 제공한다. Profile-policy validate/impact preview/publish는 Organization과 Platform catalog revision을 각각 반환하고 publish는 expected_organization_profile_catalog_revision과 expected_platform_profile_catalog_revision을 모두 required exact precondition으로 요구한다. Publish는 Organization catalog, Platform catalog, coordination/current pointer의 전역 순서로 잠그거나 동등한 serializable CAS 아래 모든 rule/general fallback reference를 다시 검증한다. Platform default pointer 변경과 Platform deprecate도 같은 platform catalog serialization boundary를 사용하고 deprecate는 current policy/override reference 및 current default pointer 부재를 확인한다. Deprecate가 먼저 commit되면 stale publish/override/default mutation은 snapshot conflict로 전체 rollback하고, 신규 current reference/default가 먼저 commit되면 deprecate는 knowledge.processing_profile_in_use로 닫혀 deprecated platform revision을 가리키는 current reference와 partial audit를 만들지 않는다.
FR-146c: processing_profile_schema_v1은 boolean이 아닌 strict integer chunk_size_tokens=64..8192 inclusive와 chunk_overlap_tokens=0..floor(chunk_size_tokens / 2) inclusive를 사용한다. String, float, null, 음수와 범위 밖 값은 coercion 없이 거부한다. Selected tokenizer/parser/representation/embedding capability가 더 작은 current published limit를 가지면 그 값을 추가로 적용하며 catalog capability가 V1 envelope을 넓히지 못한다. 이 bound는 품질 최적 기본값이 아니며 변경은 기존 revision 재해석이 아니라 새 schema version이다.
FR-146d: processing_profile_policy_v1 draft는 required policy_schema_version, raw rules, required nullable organization_general_profile과 platform_general_profile을 가진 complete document다. Raw rules는 duplicate 제거 전에 최대 2,000개이고 matcher는 type_primary(document_type_id,primary_topic_id), type(document_type_id), primary(primary_topic_id) discriminated union이다. 각 target은 profile_revision_ref={catalog_scope: organization|platform, profile_revision_id}를 사용한다. Organization general은 organization scope, Platform general은 platform scope만 허용한다. Incomplete draft는 두 general을 null로 저장할 수 있지만 validate/impact-preview/publish는 non-null Platform general을 필수로 요구한다. Create envelope는 required policy만 받아 request document를 draft_revision=0으로 저장하고 PATCH envelope는 required expected_draft_revision과 policy만 받는다. PATCH는 complete replacement이고 omitted merge/partial operation을 허용하지 않는다. Unknown/mismatched wrapper 또는 policy field, normalized duplicate matcher, cross-organization/deprecated/incompatible ref와 raw 2,001번째 rule은 fixed safe validation으로 mutation/audit 없이 거부한다.
FR-146e: Platform catalog는 approved published/selectable exact revision을 가리키는 non-null platform_default_profile_revision을 profile control plane 공개 전에 초기화한다. Pointer 변경은 target selectability를 같은 Platform catalog transaction에서 다시 검증하는 platform registry owner/system actor 전용 command이며 required exact expected Platform catalog revision을 받는다. Pointer, platform_profile_catalog_revision과 canonical knowledge.processing_profile_default.changed audit를 같은 Unit of Work에서 확정하고 stale CAS 또는 audit 실패는 모두 rollback한다. Current default target은 pointer를 먼저 옮기기 전에는 deprecate할 수 없다. Current Organization profile-policy가 null이면 valid explicit override가 먼저이고, override가 없으면 exact Platform default와 platform_default source를 사용한다. 이 default branch가 필요한데 target이 missing/deprecated/incompatible이면 preview, reindex admission과 override clear는 503 knowledge.processing_platform_default_unavailable로 fail-closed하고 기존 active-ready artifact를 유지한다. Selectable explicit override set/change는 recovery path이며 어떤 경로도 mutable latest, environment default 또는 legacy character setting으로 fallback하지 않는다.
FR-146f: Profile-policy impact preview는 모든 publish의 필수 precondition이다. Request는 exact expected_draft_revision을 요구하고 response는 actor/Organization/candidate/draft, nullable current policy, current taxonomy/registry, Organization/Platform profile catalog와 assignment_impact_snapshot_revision을 bind한 최대 10분 opaque token 및 profile_policy_impact_bucket_v1을 반환한다. Contract는 두 internal count를 none=0, small=1..10, medium=11..100, large=101+로 독립 변환한다. Affected count는 processing-eligible active KB/document를 current와 candidate resolver로 같은 snapshot에서 평가해 effective status/source/profile revision이 달라지는 target을 센다. Assignment가 없는 general-fallback target은 포함하고, valid explicit override가 계속 우선하거나 invalid override가 계속 review-required인 target은 제외한다. Reindex candidate는 affected subset 중 current active-ready artifact가 있는 target만 평가한다. Current decision에 비교 가능한 materialization fingerprint가 있으면 candidate fingerprint가 다른 target만 세고, active-ready legacy artifact는 있지만 current decision 또는 비교 가능한 fingerprint가 없으면 동일 materialization을 증명할 수 없으므로 보수적으로 센다. Active-ready artifact가 없는 target과 artifact availability가 purging|purged인 target은 reindex candidate에서 제외하되, KB/document 자체가 active·processing-eligible이고 resolver 결과가 달라지면 affected count에는 포함한다. Archived/deleted KB/document 또는 processing-ineligible target만 두 count에서 모두 제외한다. Publish는 exact compatibility snapshot, expected_impact_bucket_contract_version, expected_impact_preview_revision과 impact_acknowledged=true를 요구한다. assignment_impact_snapshot_revision은 token-bound server-owned precondition이고 별도 publish request field로 받지 않는다. Missing/expired/wrong scope·actor·candidate, changed snapshot 또는 contract mismatch는 knowledge.processing_profile_policy_impact_preview_stale로 policy/current pointer/audit 없이 닫고 exact count, hidden identity와 token 원문을 response/audit에 저장하거나 reindex job을 자동 시작하지 않는다.
FR-147: Canonical content revision은 KB/document scope, canonicalization contract와 redacted canonical bytes/structure/materialization-safe metadata의 canonical_materialization_input_hash를 고정한다. Source sync/document generation은 lineage ref로 분리하고 materialization input이 같으면 새 canonical revision을 만들지 않는다. Resolver input fingerprint는 exact policy/control vector를, materialization input fingerprint는 canonical materialization hash와 실제 output을 결정하는 immutable configuration 및 materialized assignment-derived field를 admission 전에 고정한다. Output ID/result bytes는 input fingerprint에 포함하지 않고 생성 후 artifact integrity hash로 별도 검증한다.
FR-147a: Processing Decision Manifest, Artifact Build Manifest와 append-only Decision Satisfaction을 분리한다. Resolver-only change에서 active build의 materialization input fingerprint와 integrity가 유효하면 새 decision manifest와 satisfied_existing link 및 current decision pointer만 확정하고 physical reindex와 active artifact pointer 변경을 만들지 않는다. Materialization input fingerprint가 다를 때만 새 staging DocumentVersion/index와 durable job을 준비한다. Decision/job identity는 canonical content revision ref와 두 input fingerprint를 함께 사용하고 same-decision retry/concurrency는 unchanged 또는 기존 satisfaction으로 수렴한다.
FR-147b: Finalizer는 FR-145e의 current execution/source authorization과 embedding binding lifecycle/relation/permission/provider-routing revision, canonical content, 전체 resolver input revision vector와 current profile selectability를 짧은 transaction 안에서 다시 resolve하고 두 input fingerprint를 재계산한다. Permission/source/credential authorization revision, pointer/revision row lock, conditional CAS 또는 동등한 serializable validation으로 revoke/input compare와 active swap 사이의 변경을 차단하며, authorization 또는 어느 입력이든 admission snapshot과 다르면 active pointer와 Decision Satisfaction을 commit하지 않는다. 유효한 job fence/lease를 가진 stale/cancelled finalizer는 계약된 terminal transition과 자신이 소유한 staging artifact cleanup outbox intent만 같은 transaction에서 확정하고, fence를 잃은 worker는 commit하지 않으며 reconciler가 orphan을 수습한다. Cleanup handler는 generation/fence와 current reference 부재를 다시 검증하고 idempotent retry한다. Lineage, bounds, artifact integrity, embedding completeness와 retrieval smoke까지 ready를 통과한 current authorized attempt만 immutable build manifest와 satisfied_new link를 만들고 current decision/active artifact pointer를 원자적으로 교체한다. 실패·timeout·stale·cancelled·rollback은 기존 active ready version을 유지한다.
FR-147c: Artifact Build Manifest와 Decision Satisfaction은 immutable provenance이며 그 reference만으로 physical artifact를 영구 pin하지 않는다. Current active/current decision, in-flight build, citation/evidence retention과 legal hold만 blocking Artifact Retention Pin이다. Cleanup은 retention expiry와 pin 부재를 generation/fence 아래 확인하고 pre-delete transaction에서 artifact를 purging으로 전이하며 durable intent와 impact snapshot revision을 확정한 뒤 physical object/vector/index를 idempotent하게 삭제한다. External delete 전 transaction 실패는 전체 rollback한다. Physical deletion 확인 뒤 completion transaction에서 append-only Artifact Availability Tombstone, purged availability, impact snapshot revision과 knowledge.processing_artifact.purged audit를 원자적으로 확정한다. purging|purged artifact는 retrieval, citation과 satisfied_existing에서 제외하지만 manifest/integrity/satisfaction history는 보존한다. Physical delete 뒤 tombstone/audit commit이 실패하면 ready로 rollback하지 않고 purging으로 유지하며 reconciler가 storage absence와 같은 generation을 확인해 tombstone/audit를 exactly-once로 완성한다.
FR-148: Redacted canonical evidence와 contextual prefix, parent summary, late/visual embedding input 같은 retrieval representation은 별도 identity/version/fingerprint로 관리한다. Derived representation은 citation source인 canonical evidence를 덮어쓰지 않는다.
FR-149: Query intent는 document type과 분리된 request-scoped 개념이다. Hierarchical, long-unit, graph/global, late/visual retrieval와 reranking은 문서·질의 track별 독립 후보이며 confirmatory evidence 전에는 전역 production default가 아니다.
FR-150: Assignment mutation과 successful current-validation audit은 organization/KB, safe actor ref, before/after stable IDs와 axis별 authority source/lock, last-validated refs, assignment/taxonomy/profile revision, fixed safe reason과 correlation만 저장한다. Accepted suggestion은 selected axis, generator_kind와 safe generator_contract_ref를 assignment revision 및 canonical audit에 snapshot한다. AI kind에서만 model/prompt-template/calibration safe contract refs와 bounded confidence bucket을 추가하고 deterministic kind에 fake provider provenance를 만들지 않는다. Suggestion reject는 assignment를 바꾸지 않고 rejected outcome, bounded fixed reason과 canonical audit를 한 transaction에서 확정하며 audit 실패와 terminal retry가 outcome 또는 duplicate audit를 만들지 않아야 한다. Raw label 설명, raw score/prompt/rationale, source title/path/URL과 document content를 저장하지 않는다.
FR-150a: Taxonomy publish audit은 impact token 원문 대신 safe digest, acknowledgement, versioned bounded impact bucket과 impact snapshot revision만 저장한다. Organization profile lifecycle audit은 stable profile/revision, before/after state와 catalog revision만 저장하고 raw profile config를 포함하지 않는다. Platform default pointer 변경 audit은 system actor, safe before/after Platform profile revision과 resulting Platform catalog revision만 저장하고 raw profile config를 포함하지 않는다. Override set audit은 새 target의 safe scoped ref만 기록하고, invalid current override clear audit은 KB-owned override revision과 fixed unavailable state만 기록하며 hidden target profile identity를 저장하지 않는다. Reindex admission audit은 FR-145f의 canonical action/result status와 exactly-once receipt transaction을 사용한다. Artifact purge completion audit은 physical deletion 확인 뒤 tombstone과 같은 transaction에서 canonical knowledge.processing_artifact.purged를 사용하고 opaque manifest/artifact ref, generation, fixed reason, pin evaluation과 tombstone ref만 저장한다. Pre-delete purging fence는 이 success action을 만들지 않으며 storage locator, content와 raw provider result를 저장하지 않는다. Reindex execution authorization loss는 safe actor와 opaque job/attempt ref, bounded stage 및 fixed knowledge.processing_execution_not_authorized 또는 knowledge.processing_embedding_credential_unavailable만 기록하고 revoked membership/grant/source ACL detail, credential identity/candidate count/relation·permission detail, source identity, content와 provider payload를 저장하지 않는다.
FR-150b: 이 기능이 문자열까지 확정한 canonical action은 다음 22개다. Taxonomy는 knowledge.taxonomy_draft.created, knowledge.taxonomy_draft.updated, knowledge.taxonomy.published를 사용한다. Classification은 knowledge.classification_assignment.created, knowledge.classification_assignment.updated, knowledge.classification_assignment.locked, knowledge.classification_assignment.unlocked, knowledge.classification.revalidated, knowledge.classification_suggestion.accepted, knowledge.classification_suggestion.rejected를 사용한다. Processing Profile은 knowledge.processing_profile_draft.created, knowledge.processing_profile_draft.updated, knowledge.processing_profile.published, knowledge.processing_profile.deprecated를 사용한다. Profile Policy는 knowledge.processing_profile_policy_draft.created, knowledge.processing_profile_policy_draft.updated, knowledge.processing_profile_policy.published를 사용한다. Control/runtime은 knowledge.processing_profile_default.changed, knowledge.processing_profile_override.set, knowledge.processing_profile_override.clear, knowledge.processing_reindex.admitted를 사용한다. Artifact lifecycle은 knowledge.processing_artifact.purged를 사용한다. 모두 ADR-0008, AuditAction, audit 검색/UI filter와 계약 테스트에 같은 canonical string으로 등록한다. Authoritative DB mutation과 audit은 같은 Unit of Work이며 normalized no-op과 terminal/idempotent replay가 duplicate action을 만들지 않는다. Artifact purge는 physical delete 전 purging fence/intent transaction과 physical delete 확인 뒤 tombstone/purged/audit completion transaction을 분리하고, 후자 실패 시 삭제된 artifact를 ready로 rollback하지 않는다.
FR-150c: Profile-policy publish audit은 raw preview token 대신 safe digest, acknowledged flag, profile_policy_impact_bucket_v1, bounded affected/reindex bucket과 assignment impact snapshot revision만 저장한다. Raw policy/profile config, exact count와 hidden target identity를 저장하지 않으며 audit 실패는 policy version/current pointer를 함께 rollback한다.
FR-151: Processing profile 정책 publish 또는 code merge만으로 기존 KB 전체 reindex를 자동 시작하지 않는다. New profile/representation은 disabled, shadow 또는 explicit opt-in으로 도입하고 privacy migration과 별개인 기존 processing-profile legacy/general path fallback을 유지한다.
FR-152: 문서 유형별 production profile과 retrieval default는 MBA-309의 human-reviewed multi-document-type holdout에서 동일 context-token budget, 사전 등록된 효과/위험/coverage 기준, latency/cost와 rollback gate를 통과한 경우에만 승인한다.
FR-153: Knowledge canonicalization은 actor/active organization/KB 및 applicable source authorization과 content safety를 통과한 입력을 network가 없는 local isolated parser로 처리하는 것을 기본값으로 한다. External parser는 FR-153p의 protected raw parser egress가 명시적으로 승인된 경우에만 예외로 사용한다. 두 parser 결과 모두 ephemeral normalized text에 platform-owned hard baseline을 Organization detector와 embedding보다 먼저 실행한다. Baseline failure/unknown에서는 Organization detector, chunking, embedding/index와 active pointer mutation을 수행하지 않고 raw-free knowledge.privacy_baseline_failed로 닫는다.
FR-153a: Privacy mode는 baseline_only, enterprise_detector_required, manual_review_required만 허용한다. Effective Privacy Policy Resolver는 platform hard baseline, current Organization base, KB에 명시적으로 연결된 모든 active Collection Privacy Policy Binding의 applicable stricter revision, applicable source revision과 KB revision을 모두 합성한다. Collection UUID 정렬은 digest 재현성만 제공하고 우선순위가 아니다. Category action은 block > manual_review > mask의 strongest union, detector/manual-review requirement는 OR이며 하위 scope는 상위를 약화하지 못한다. Distinct non-null provider revision은 0개 또는 정확히 1개여야 하고 복수/cross-Organization/inactive provider와 required-detector null은 fail-closed다. Snapshot은 모든 exact scope revision과 Collection privacy/source/KB binding revision, compiled digest와 derived mode/action/provider를 고정하고 finalization에서 다시 resolve한다. Effective scope/result 변경은 Organization validity epoch을 +1하는 invalidating transition이다. baseline_only provider ref는 null, enterprise_detector_required는 exactly one provider, manual_review_required는 null 또는 exactly one provider만 허용한다. Review-capable 결과는 canonical review management/audit readiness 없이는 활성화하지 않고 provider failure를 baseline-only 또는 mask로 downgrade하지 않는다. Request, graph, source/document metadata의 scope/provider id/endpoint/config/credential은 authority가 아니다.
FR-153b: Provider trust tier는 organization_private|external_approved다. 모든 provider revision은 exact same-Organization immutable Detector Egress Approval Revision을 참조해야 하며 approval은 provider/trust tier, purpose, processor/ownership boundary, endpoint/network boundary, data residency, retention, no-training/no-secondary-use와 active/expiry/revoke 상태를 고정해야 한다. external_approved는 ADR-0067 public-address guard를 완화하지 않고 baseline span을 제거/치환한 provider-safe view만 전송한다. organization_private는 generic guard 예외가 아니라 server-owned exact host/port/CIDR allowlist, all-DNS-result validation, address pinning, peer/Host/TLS SNI 일치, HTTPS+mTLS, no redirect/proxy와 dedicated worker/network isolation을 가진 별도 knowledge.detector.organization_private operation profile을 요구한다. Loopback/link-local/cloud-metadata/multicast/unspecified/public/미승인 private 주소와 profile/network readiness 부재는 call 0회다. Ingestion/runtime request는 endpoint/CIDR/profile을 입력하지 못한다. Organization RBAC 밖의 deployment/change-control operator만 server-owned profile registry와 network isolation revision을 변경할 수 있다. Authorized provider management는 그 registry의 profile만 참조해 immutable provider revision을 bind하며 Organization actor가 endpoint/CIDR/profile/transport를 만들거나 확장할 수 없다. Approval, private IP, DNS, mTLS 또는 dedicated credential 하나만으로 private transport를 활성화하지 않는다. Provider-safe view는 sensitive-free/compliance-pass 보증이나 raw 전송 승인이 아니다. 모든 provider I/O는 session/transaction/lock을 닫은 뒤 tier별 guarded transport와 dedicated credential capability를 통과하고 각 external batch/finalization 전 exact approval revision을 재검증한다.
FR-153c: 초기 privacy text contract privacy_text_unicode_14_0_nfc_lf_v1은 CRLF/CR을 LF로 바꾸고 Unicode 14.0.0 NFC를 적용하며 다른 whitespace/case를 보존한다. 내부 span은 normalized document UTF-8 byte half-open range다. Adapter는 provider offset을 이 좌표로 변환하고 immutable local call context와 실제 전송 bytes에서 계산한 exact request/segment-view fingerprint, complete coverage, UTF-8 boundary, expected detector_contract_ref, bounded server-approved rule_or_model_ref, category/confidence와 platform cap을 검증한다. Provider protocol이 공식 지원하는 correlation field는 승인된 registration contract에서만 최소 전송하며 provider echo만을 무결성 근거로 신뢰하지 않는다. Malformed/partial/unknown-reference/oversized 결과는 유효 부분도 사용하지 않고 knowledge.detector_response_invalid로 전체 실패한다.
FR-153d: Shared Privacy Core는 baseline/provider span을 additive union하고 가장 강한 block > manual_review > mask action을 보존한 뒤 category-neutral fixed replacement로 local deterministic masking을 수행한다. Provider redacted output 또는 LLM rewrite를 canonical source로 사용하지 않으며 redacted canonical content가 확정되기 전 chunk, derived representation, embedding/index를 만들지 않는다.
FR-153e: Effective privacy policy, baseline/provider/detector-approval/raw-parser revision·approval, normalization/masking contract와 action policy는 Canonical Content Revision 및 processing resolver/materialization input의 immutable vector다. V1 Privacy Artifact Validity Vector는 server-owned global platform revision/monotonic validity_epoch과 same-Organization revision/monotonic validity_epoch의 정확한 두 요소이며 candidate-bound manifest는 candidate 생성 당시 두 ref/epoch를 snapshot한다. Finalizer는 approved exact candidate/manifest와 current actor/source/effective policy/provider/approval/parser revision, 두 validity revision/epoch와 fence를 다시 검증하며 manifest를 덮어쓰지 않는다. 하나라도 허용된 current contract와 맞지 않으면 새 generation/review가 필요하다. ready/active pointer와 current privacy validity는 분리하며 retrieval prefilter와 final evidence gate는 manifest의 두 epoch가 current 두 epoch와 모두 같을 때만 evidence를 허용한다. Compatibility validator는 transition을 artifact_preserving|artifact_invalidating으로 분류하고 ambiguous transition은 invalidating으로 닫는다. Credential rotation이나 operational endpoint 변경은 protection 의미가 보존된다고 검증될 때만 preserving이며 해당 scope revision은 전진할 수 있어도 epoch은 유지한다. Baseline security supersession은 platform epoch을, effective scoped policy/binding, required detector, provider/detector-approval/raw-parser security invalidation은 해당 Organization epoch을 정확히 1 증가시킨다. Invalidating activation은 current revision/epoch CAS와 canonical management audit를 원자 확정하고 Organization/client grace 없이 commit 시점부터 old epoch 및 stale cache/vector evidence를 retrieval에서 제외한다. V1 Organization invalidation은 per-manifest 선별 없이 해당 Organization의 모든 privacy-gated artifact에 적용한다. Missing/malformed/stale epoch은 fail-closed다. 실패, review, cancellation 또는 stale generation은 current-valid인 기존 compliant active-ready version만 유지한다. FR-153l~FR-153o의 migration 예외도 wave freeze 당시 exact platform/Organization validity ref/epoch를 snapshot하며 current 두 epoch와 모두 같을 때만 허용한다. Invalidating epoch commit은 related legacy eligibility를 item bulk update나 cleanup 없이 즉시 닫는다. Migration 예외는 compliant active pointer가 한 번도 확정되지 않은 document에만 적용한다. Compliant pointer finalization은 같은 transaction에서 legacy eligibility를 비가역적으로 retire하며 이후 manifest가 stale/invalid가 되어도 legacy로 돌아가지 않는다. Current-valid active artifact가 없으면 retrieval-unavailable을 유지하고 legacy/raw/staging/partial artifact로 fallback하지 않는다.
FR-153f: Raw bytes/text, provider-safe view/map, exact byte-binding fingerprint, exact span/confidence와 parser/provider request/response/exception은 durable attempt/manifest, job/retry/dead-letter, API, audit, trace와 log에 저장하지 않는다. Privacy Decision Manifest는 organization-scoped keyed source/span digest와 key version, effective policy와 safe revision refs, coverage digest, bounded outcome만 저장하고 audit/trace에는 digest 대신 opaque manifest ref만 허용한다. 검출용 source bytes는 isolated ephemeral handle이고, 별도로 보존하는 upload/fetch 원문은 FR-038의 opt-in protected raw artifact다. Pending review body는 missed PII/secret 가능성이 있는 encrypted protected staged artifact이며 monotonic candidate revision, generation-bound expiry, bounded safe outcome과 opaque manifest/generation ref만 사용한다. Successor revision은 최초 generation expiry를 연장하지 않는다. Source-managed candidate의 list/detail projection 직전에는 fresh requester source authorization/display policy를 요구하며 review authority는 raw access나 source display 우회를 포함하지 않는다. 원문 확인은 별도 raw/compliance permission, fresh source ACL, content 반환 전 access audit와 retention/legal-hold/purge를 통과해야 한다.
FR-153g: Process/reprocess는 KB write 또는 same-organization Organization manager, review list/detail/mask/approve/reject는 Organization manager를 요구한다. Source-managed review는 projection 직전과 각 mutation commit 직전에 fresh requester source authorization/display policy를 재검사하고 revoke winner를 404 resource.hidden, candidate/ref/state 비노출, zero mutation/audit로 닫는다. Manual KB는 source gate가 없다. Background sync/reindex는 admission actor를 불변 bind하고 각 external batch/finalize 전 membership, KB authority, source authorization, effective scoped policy/provider/detector-approval/raw-parser revision과 current platform/Organization validity revision/epoch을 재검사한다. Revoke 또는 stale-validity winner는 다른 user/system actor로 승격하지 않고 next external parser/provider/embedding call과 active pointer swap 없이 cancel/quarantine한다.
FR-153h: Non-null provider ref는 effective scoped policy/provider/detector-approval revision, tier-specific operation profile/network isolation, credential capability, revocation, bounded cap/readiness와 canonical management audit 경계가 구현되기 전 production에서 disabled다. manual_review_required 또는 manual_review를 만들 수 있는 action policy는 provider ref 유무와 무관하게 canonical review management/audit readiness 전 disabled다. External parser는 이 readiness와 별개로 FR-153p를 모두 충족해야 한다. Readiness 부재는 provider ref를 제거하거나 review action을 mask로 낮추는 fallback을 허용하지 않는다. Enforcement 전 current global platform validity revision/epoch을 provision한다. 모든 Organization creation path가 policy/validity를 원자 생성하는 writer generation으로 수렴하고 구버전 writer가 drain/fence된 뒤 기존 Organization을 idempotent backfill한다. Bounded rescan의 missing row 0건, writer-generation readiness와 FR-153t의 no-default DB foundation constraint가 모두 확정된 뒤에만 enforcement를 활성화한다. 이후 새 Organization 생성도 policy와 Organization validity를 authoritative creation Unit of Work에 포함한다. Bootstrap 실패는 migration/creation을 fail-closed하고 missing policy/validity를 runtime 암묵적 default로 해석하지 않는다. Enforcement 뒤 dual-write를 모르는 구버전 writer의 startup/rollback과 DB insert를 거부한다. 현재 runtime/provider/persistence/preflight 구현은 MBA-362 전까지 미완료다.
FR-153i: Hard baseline action policy가 terminal block을 결정하면 Organization provider를 호출하지 않고, provider가 terminal block을 추가하면 embedding/finalization을 수행하지 않는다. 두 경우 모두 authorized status reason과 canonical policy.block의 최상위 audit_metadata.policy_reason은 knowledge.sensitive_content_detected다. Terminal attempt safe state와 session-bound generic audit Outbox intent는 같은 Unit of Work이며 audit preparation 실패가 attempt/artifact/pointer partial commit이나 raw fallback을 만들지 않는다. Scope 밖/hidden resource에는 이 reason을 노출하지 않는다. Token-only provider offset은 exact transmitted character boundary와 승인된 versioned tokenizer mapping 없이는 지원하지 않고 readiness 또는 전체 response를 fail-closed한다.
FR-153j: Durable source/span identity는 provider/LLM credential과 분리된 Privacy Digest Key Ring의 privacy_digest_hmac_sha256_v1을 사용한다. Master key version과 Organization UUID로 domain-separated HMAC-SHA-256 Organization key를 파생하고 versioned length-delimited canonical bytes를 digest한다. Key material은 DB/wire/job/audit/trace/log에 없고 current key 부재는 provider/embedding 전에 fail-closed한다. Admission은 key version을 attempt/materialization snapshot에 고정해 같은 retry/recovery가 유지하고 새 admission만 rotation 뒤 current version을 사용한다. Rotation만으로 기존 manifest를 rewrite/reindex/stale 처리하지 않지만 snapshot key revoke/destruction은 next external batch/finalization을 차단한다. Historical key retention/destruction은 in-flight attempt와 manifest retention/legal hold, 영향 preview/audit를 따르고 exact canonical action과 transaction ownership이 승인되기 전 destructive key management는 disabled다.
FR-153k: Provider는 같은 input/revision에 다른 valid span set을 반환할 수 있다. Current fence만 validated spans에서 만든 staged redacted candidate와 Privacy Decision Manifest를 같은 staging transaction에 commit하며 exact span 대신 span-set digest만 저장한다. Candidate commit 이후 retry/recovery는 provider를 다시 호출하거나 여러 response를 union/majority-select하지 않고 committed candidate를 재사용한다. Commit 전 crash/takeover만 bounded 재호출을 허용하고 stale response는 zero commit이다. Determinism은 같은 accepted span set의 candidate bytes에 한정한다.
FR-153l: 무중단 전환용 legacy_unverified는 enforcement 시작 전 public User를 가장하지 않는 deployment-owned typed system migration principal이 change-controlled explicit Organization rollout allowlist에서 확정한 immutable migration inventory/wave의 pre-cutoff Organization/KB/document/nullable-version artifact에만 적용한다. Inventory item의 opaque legacy_artifact_ref는 versioned 또는 document_version_id IS NULL인 unversioned chunk와 vector/keyword/hierarchy generation의 exact frozen set을 결속하고 raw content/content digest를 외부 projection에 노출하지 않는다. Wave header는 freeze 시점의 exact global platform 및 same-Organization validity revision ref/epoch을 함께 고정한다. Allowlist/wave 부재의 기본값은 retrieval-unavailable이다. 각 exact artifact는 최대 한 wave에만 배정되고 later wave로 이동할 수 없다. 이는 privacy mode, compliant version 또는 처리 실패 fallback이 아니며 request/graph/runtime command로 등록·선택하거나 새 ingestion/reprocess artifact를 추가할 수 없다.
FR-153m: admission_deadline_at은 새 reindex admission의 마지막 시각, retrieval_cutoff_at은 legacy retrieval의 마지막 시각이며 전자는 후자보다 늦을 수 없다. V1 code-owned hard maximum은 privacy_legacy_grace_v1 = 30 * 24 hours이고 immutable retrieval_cutoff_at <= enforcement_activated_at + 30 * 24 hours를 요구한다. Deployment rollout은 이 상한을 줄일 수만 있고 늘리거나 Organization별 상한을 만들 수 없다. Supported grace contract와 immutable activation time readiness가 없으면 wave activation은 zero-write다. 두 값은 UTC instant이고 authoritative DB transaction time의 half-open db_now < deadline/cutoff로 평가해 equality부터 닫으며 client가 연장할 수 없다. Retrieval prefilter와 final evidence gate는 frozen membership, current KB/source permission, cutoff 및 wave의 frozen platform/Organization validity epoch와 current 두 epoch equality를 모두 재검증한다. Invalidating epoch commit은 cleanup이나 item state projection을 기다리지 않고 legacy를 즉시 제외하며 delayed scheduler, skewed application/client clock과 stale cache/vector result도 우회하지 못한다.
FR-153n: Bounded inventory staging은 비권위이고 legacy eligibility를 부여하지 않는다. Final freeze/activation은 Organization privacy rollout coordination row를 잠그고 exact current retrieval-visible raw-derived set, staged inventory, legacy_snapshot_revision과 current platform/Organization validity ref/epoch을 대조한 뒤 enforcement epoch/rollout marker, immutable wave header와 knowledge.privacy_migration_wave.created canonical audit를 같은 Unit of Work에 확정한다. Legacy-producing pointer writer는 같은 epoch를 CAS하며 freeze loser는 inventory 또는 validity snapshot을 다시 대조하고 writer loser는 새 privacy gate로 fresh admission한다. Partial staging/freeze 실패는 enforcement나 legacy eligibility를 만들지 않고 aborted/unfrozen staging은 bounded cleanup한다.
FR-153o: Pre-cutoff reindex 실패는 frozen inventory가 고정한 legacy pointer를 변경하지 않지만 cutoff 뒤 current-valid compliant active-ready version이 없으면 retrieval-unavailable이다. Deadline 전에 admitted된 in-flight attempt는 cutoff 뒤에도 fresh actor/source/policy/provider/approval, current platform/Organization validity revision/epoch와 fence를 통과하면 compliant artifact를 finalize할 수 있으나 그 전까지 legacy retrieval을 재개하지 않는다. Legacy cleanup은 exact legacy_artifact_ref를 non-retrievable purging으로 fence하고 durable intent를 commit한 뒤 physical chunk/vector/keyword/hierarchy generation을 삭제한다. Physical absence 확인 뒤 cleanup receipt, append-only tombstone과 knowledge.processing_artifact.purged audit를 같은 completion Unit of Work에 확정한다. Completion 실패는 visible로 rollback하지 않고 same-generation reconciler가 exactly-once로 완성하며 receipt가 확정된 legacy artifact는 rollback이나 새 wave로 재활성화하지 않는다.
FR-153p: External parser는 hard baseline 전 raw bytes egress이므로 detector approval과 분리된 protected resource다. Default는 network-disabled local isolated parser다. External parser는 explicit Organization opt-in과 applicable ingestion-scope opt-in을 모두 요구한다. Source-managed document는 exact source scope, manual document는 exact KB scope를 사용하며 서로의 gate를 합성하지 않는다. Exact same-Organization immutable Raw Parser Egress Approval Revision은 Organization, applicable source 또는 KB, parser revision, purpose/processor/ownership/endpoint/network/residency/retention/no-training/no-secondary-use와 active/expiry/revoke를 고정한다. Server-owned parser revision·credential capability·knowledge.parser.external_approved operation profile, ADR-0067 public-address guarded transport, bounded size/timeout/concurrency와 no-log/no-durable-payload readiness를 모두 요구한다. V1은 approved public HTTPS parser만 지원하고 private raw parser destination은 별도 Accepted ADR과 dedicated isolation profile 전까지 거부한다. Current LlamaParse credential Organization/use 검증만으로는 부족하며 readiness 전 llamaparse와 모든 external parser strategy는 upload 전에 knowledge.raw_parser_egress_unavailable로 fail-closed한다. 승인된 parser output도 local normalization/hard baseline을 우회하지 않는다.
FR-153q: Deployment standalone preflight, active create와 enable/toggle은 runtime과 동일한 retrieval-visible resolver를 사용한다. Current-valid compliant active manifest, 또는 compliant active pointer가 한 번도 확정되지 않았고 아직 retire되지 않은 frozen pre-cutoff legacy artifact가 DB-time cutoff 전이며 frozen platform/Organization validity epoch가 current 두 epoch와 모두 같은 경우만 ready다. Missing/stale/invalid manifest, stale validity epoch legacy, compliant pointer 뒤 남은 legacy, cutoff가 닫힌 legacy와 artifact 부재는 knowledge_privacy_artifact_unavailable과 reprocess_or_remove_unavailable_knowledge로 정규화한다. POST /api/v1/deployments/preflight는 blocked 결과도 200 OK와 status="blocked"로 반환하고 is_active=false에서 inactive 저장이 허용되는 availability blocker만 기존 Deployment 계약에 따라 safe warning으로 낮출 수 있다. Active create/enable/toggle은 같은 unresolved 결과를 409 deployment.preflight.blocked로 차단하며 hidden document/provider/policy identity와 exact count를 노출하지 않는다. 현재 preflight는 이 검사를 구현하지 않았으므로 MBA-362 후속 경계다.
FR-153r: Provider가 null인 manual_review_required는 정식 비LLM 처리 경로다. Organization manager는 exact pending, non-expired generation/candidate revision의 staged redacted candidate에 candidate-relative UTF-8 byte mask range만 추가할 수 있고 replacement text 또는 전체 content를 제출할 수 없다. Server는 정보가 줄어드는 새 immutable candidate revision과 candidate-bound manifest를 deterministic masking/local hard-baseline 재검사로 만들고 pending을 유지하되 최초 generation expiry를 연장하지 않는다. Review command는 candidate를 덮어쓰지 않고 exact actor/action/current policy·binding·validity·source precondition, safe outcome과 optional successor candidate ref만 가진 append-only Privacy Review Decision을 기록하며 submitted range/raw/span/digest는 저장하지 않는다. Decision과 successor candidate 또는 generation review-state, canonical review audit는 한 Unit of Work다. Exact candidate approval은 current effective policy/binding, platform/Organization validity, actor/source authorization, candidate revision과 DB-time expiry를 commit 직전에 재검증한 경우에만 canonical content finalization을 허용하고, embedding은 승인 transaction 밖에서 재개해 finalizer가 같은 fence를 다시 확인한다. 사전 승인은 retrieval-visible finalization 전 exact candidate 승인이고 사후 검토는 pending/quarantine candidate remediation이며 둘 다 최초 KB 사용 전에 완료해야 한다. 업로드 전 업무 승인이나 이미 노출된 artifact의 소급 승인은 privacy approval이 아니다. 보지 않은 미래 content/KB 전체에 대한 blanket pre-approval, stale/expired candidate approval과 terminal block override는 거부한다.
FR-153s: Collection item membership/order와 Collection archive/restore는 검색 grouping/routing 리소스이고 Collection Privacy Policy Binding은 별도 protected revision이다. catalog_manage/collection.manage membership link/reorder와 lifecycle_manage archive/restore는 privacy binding이나 Organization validity epoch을 바꾸지 않는다. Archived Collection의 active binding/referenced published policy도 Organization manager가 explicit unbind할 때까지 effective scope에 남는다. V1 binding create/replace/delete는 active Organization manager, create 시점의 active same-Organization membership, exact published Collection policy revision, bounded impact preview acknowledgement와 expected membership/binding/policy/current Organization validity revision을 요구한다. Mutation과 invalidating Organization epoch +1, canonical management audit는 한 Unit of Work이고 stale/concurrent loser는 zero-write다. Active binding이 남은 membership unlink, Collection hard delete 또는 referenced policy purge는 knowledge_collection_privacy_binding_active로 차단하며 binding을 먼저 별도 제거해야 한다.
FR-153t: Privacy bootstrap rollout은 enforcement-disabled nullable schema/readiness -> 모든 Organization writer dual-write 수렴 -> 구버전 writer drain/fence -> idempotent existing-Organization backfill -> zero-missing bounded rescan과 writer-generation readiness 확정 -> no-default non-null DB foundation-generation/policy/validity constraint -> enforcement activation 순서를 따른다. Backfill scan 사이에 생성된 Organization은 new writer의 원자 Unit of Work 또는 final rescan 중 하나로 반드시 수렴해야 한다. 이 순서를 보장하지 못하는 배포는 maintenance window를 사용한다. Enforcement 뒤 old writer image는 deployment readiness에서 시작을 거부하고, 이를 우회한 insert도 Organization/foundation partial row 없이 DB rollback한다. Exact FK/deferred-constraint shape는 MBA-362가 정하되 old writer를 살리는 server default는 금지한다.
FR-153u: Enforcement cutover는 Nodease storage에 남은 upload/fetch raw copy의 exact frozen inventory를 만들고 각 item을 protected_migrated|purged terminal disposition으로 수렴시킨다. Organization/source opt-in이 유효하고 적용 가능한 retention/legal hold가 보존을 허용하거나 요구하는 item만 encrypted protected raw store로 이관하고 destination integrity와 original-copy physical absence를 검증한다. Protected migration 조건을 충족하지 않고 legal hold가 삭제를 막지 않는 item은 non-readable fence 뒤 물리 삭제하고 durable purge receipt를 확정한다. Opt-in 없이 legal hold가 삭제를 막는 conflict, unknown/partial disposition, duplicate readable copy 또는 absence 미확인은 activation을 차단하며 legal hold만으로 protected storage opt-in을 만들지 않는다. 모든 item 수렴 뒤 Organization별 final readiness marker와 knowledge.raw_copy_cutover.completed Audit Outbox intent를 같은 transaction에서 확정하고 audit 실패 시 readiness를 활성화하지 않는다. Per-item receipt는 AuditLog로 중복 생성하지 않는다. Raw response fail-closed, DB file_path null 처리 또는 legacy retrieval cutoff는 storage disposition을 대신하지 않는다. Receipt/audit에는 safe Organization/opaque cutover ref/state와 bounded count bucket만 허용하고 raw body, object key, content hash, item/document identity와 exact count를 넣지 않는다.
FR-153v: Privacy Review Candidate body는 encrypted protected staging에 두고 V1 code-owned privacy_review_candidate_ttl_v1 = 7 * 24 hours를 최초 candidate 생성 DB time부터 적용한다. Successor revision과 client/Organization 설정은 expiry를 연장하지 않는다. Approve는 candidate를 review projection/mutation에서 닫되 exact immutable body를 TTL 안의 approved_pending_finalization input으로 유지한다. Canonical active artifact finalization이 같은 candidate와 fresh authority/policy/validity/fence를 검증해 commit한 뒤에만 body를 purge_pending으로 전환한다. 그 전의 transient failure는 TTL 안에서만 같은 input으로 재시도한다. TTL equality/경과, reject, canonical finalization commit, successor 확정, generation에 결속된 source/ingestion authority revoke와 stale/abandoned generation은 body를 즉시 non-projectable/non-mutable purge_pending으로 만든다. 개별 reviewer 권한 회수는 그 요청만 hidden zero-write로 닫고 candidate를 purge하지 않는다. Knowledge-owned cleanup reconciler는 current claim/fence, terminal/expiry와 legal hold를 확인해 bounded batch로 24시간 안에 physical body를 purge하고 receipt/tombstone을 확정한다. Legal hold는 물리 삭제만 보류하며 review/approval/TTL을 재개하지 않는다. Append-only Decision, safe audit, manifest provenance와 purge receipt는 body와 분리 보존한다. Protected staging, expiry enforcement, legal-hold 처리, fenced cleanup/reconciliation readiness가 없으면 review-capable mode/action을 활성화하지 않는다.

Privacy Detector 보호 리소스 완결성 매트릭스는 FR-153~FR-153v의 문서 계약, MBA-362가 구현할 admission/runtime/persistence/rollout과 non-null provider path 활성화 전에 MBA-362 또는 별도 관리 이슈가 닫아야 하는 management, lifecycle 및 audit/redaction 경계를 구분한다.

Policies And Edge Cases

Metadata는 permission source가 아니다. Metadata filter는 allowlist 기반 검색 제한이고 KB use/source ACL 판정을 대체하지 않는다.
Collection visibility나 route 권한은 child KB 존재나 content 접근을 증명하지 않는다.
Manual Collection 관리 UI/API는 Collection 권한과 KB content 권한을 분리해 표시해야 한다. can_manage_collection=true가 can_use_kb=true를 뜻하지 않으며, item list에 보이는 KB도 실행 시점 retrieval 가능성을 보장하지 않는다.
User direct KB permission은 team KB permission을 낮추거나 거부하지 못한다. Effective KB auth state는 organization manager override와 team/user direct grant 중 가장 강한 허용값이며, row 없음 또는 none은 허용 없음으로 처리한다.
KB 직접 권한을 부여할 대상 사용자는 같은 active organization member여야 한다. 초대/정지/제거/비회원 사용자에게는 직접 권한을 생성하지 않고, 기존 row가 있더라도 effective permission 평가에서 fail-closed한다.
Knowledge domain permission grant의 active-subject 조건은 revoke에 적용하지 않는다. Revoke는 같은 organization과 subject/action으로 기존 row를 lock해 삭제하며, subject가 inactive/removed 상태여도 stale management capability를 복구 가능하게 제거한다. 존재하지 않는 row는 idempotent unchanged로 처리한다.
Document meta_info response는 allowlist가 source of truth다. 알려진 secret key만 제거하는 denylist나 nested object pass-through를 사용하지 않으며, 미래 field는 별도 계약과 negative test 전까지 기본 비노출이다.
Collection 관리 권한은 manual KB의 raw name 표시 권한이 아니다. Safe label이 없고 KB read도 없는 item/candidate는 generic label로 표시하며, label 비노출이 membership 관리 capability를 막지는 않는다.
KB name은 사용자 표시용 label이며 resource identity가 아니다. 같은 organization 안에서 동일한 name의 KB가 여러 개 존재할 수 있고, 같은 제목의 서로 다른 문서를 이름 충돌로 막지 않는다. 구분은 knowledge_base_id, protected source identity, sync/lifecycle state, safe metadata를 사용한다. 단, 같은 문서의 version은 병렬 검색 노출 대상이 아니다. 내부 문서는 active/head pointer가 가리키는 ready version만 retrieval-visible하며, 외부 source-managed 문서는 정상 sync/finalization 이후 최신 active ready version만 retrieval-visible하다. Sync 실패나 stale 상태에서는 기존 active ready version만 warning과 함께 유지할 수 있고, 이전/superseded/pre-finalized version은 selectable-ready 또는 evidence 후보에 포함하지 않는다.
MVP anonymous public-only runtime에서 public collection은 KnowledgeCollection.safe_metadata["visibility"] == "public"으로 판정한다. 누락 또는 다른 값은 private로 취급한다. 이 visibility는 인증된 subject 기반 retrieval의 KB use 권한을 부여하지 않고, execution subject가 없는 public-only runtime의 candidate inclusion gate로만 사용한다.
Source public ACL은 organization-wide read/use로 자동 materialize하지 않는다. Connector policy와 organization policy가 명시적으로 opt-in하고 approver, expiry/reverification, revocation behavior, audit-safe metadata가 확정된 경우에만 source_policy_kb_use_grants provisioning 후보가 된다. 이 경우에도 Source Authorization Provenance와 requester authorization freshness gate는 별도로 필요하다.
Source-managed KB public exposure는 collection public flag만으로 허용되지 않는다. approval_scope=connector는 broad exposure이므로 organization manager approval, explicit acknowledgement, expiry, reverification cadence, revocation behavior가 모두 있어야 한다.
Source-side search result의 title, snippet, count, score는 content가 아니더라도 resource existence side-channel이 될 수 있다. Authorization 전에는 requester-scoped result 또는 opaque source ref만 취급한다.
Redaction 전 ephemeral content handle은 process/run-scoped short TTL handle이어야 하며 durable DB, retry/dead-letter payload, audit, trace, log, user-facing response에 handle value나 raw content를 저장하지 않는다.
Content safety 실패, unsupported file type, parser exception, malware scan timeout/unknown은 raw file bytes, active content marker, parser raw error를 audit, trace, log, retry/dead-letter payload, user-facing response에 남기지 않고 safe reason code와 remediation state만 남긴다.
Source-derived collection name/description/title/path/url은 민감 metadata일 수 있으므로 redacted, capped, display-policy-approved field로만 user-facing 저장/표시한다.
Raw source content 조회는 Agent answer나 SSE stream과 분리된 future dedicated raw/compliance flow로만 허용한다. 요청은 active organization, KB visibility, raw/compliance permission, source-managed KB의 fresh source ACL, retention/legal hold/purge policy, raw access audit 선기록을 모두 통과해야 한다. Current /api/v1/knowledge/{kb_id}/documents/{document_id}/content route는 이 Target flow가 아니며 해당 gate 없이 review/compliance surface로 재사용하지 않는다. Target enforcement cutover는 Nodease가 보존한 upload/fetch 원문을 exact inventory로 동결해 valid opt-in과 retention/legal-hold 보존 조건을 모두 충족한 item만 protected raw artifact로 이관하고, protected migration 조건을 충족하지 않으며 hold가 삭제를 막지 않는 item은 non-readable fence 뒤 물리 삭제해 original-copy absence와 terminal disposition을 증명해야 한다. No-opt-in legal-hold conflict는 자동 이관하지 않고 activation을 차단한다. Dedicated gate가 준비되지 않은 raw body response는 별도로 fail-closed한다. Response 차단은 storage disposition의 대안이 아니고 raw-derived retrieval 예외는 FR-153l~FR-153o만 따른다.
PII/secret redaction policy는 output target별로 다르게 적용한다. Chunk/embedding/retrieval-visible text는 redacted canonical text, citation preview는 redacted+capped preview, audit/trace/log는 allowlist summary, raw/compliance view는 별도 권한 flow를 사용한다.
Collection list/router metadata는 authorized subset 기준으로만 계산한다. Exact child KB count, denied/hidden count, source distribution, unauthorized child에서 유래한 tag/category aggregate는 omit, bucket, 또는 request-scoped safe aggregate로 낮춘다.
Builder/recommendation auto collection router 입력에는 collection route scope와 KB permission/source ACL helper 결과를 통과한 authorized safe candidate와 safe metadata만 전달한다. 이 Builder 경계에서 missing collection_ids는 organization 전체가 아니라 서버 정책상 route-allowed collection subset에서 시작할 수 있다. MBA-232 Workflow runtime에서는 missing/empty collection_ids가 항상 Collection stream 0개이며 같은 fallback을 사용하지 않는다. Raw source ACL, raw source id/url, exact hidden document count, exact denied count는 전달하지 않는다.
Partial result 표시에는 partial_result=true, bucketed failed candidate count 또는 safe reason summary, retryability만 허용한다. Exact failed KB id/source distribution은 기본 저장하지 않는다.
Explicit KB mode는 collection.route를 생략할 수 있지만 KB helper/source ACL/final evidence gate를 생략할 수 없다. Explicit KB id가 scope 밖, organization mismatch, deleted/archived, requester source authorization denied, source ACL stale/unmapped/ambiguous/unverified/revoked, permission-unverified인 경우의 응답 shape와 answer-run/audit 생성 여부는 ADR-0017 resource hiding baseline을 따른다.
Organization manager remediation/admin view는 읽을 수 없는 source-managed KB에 대해 기본적으로 safe metadata와 remediation reason code만 표시한다. Raw title/path/url/content/source principal 표시에는 별도 display/raw-access policy gate가 필요하다.
Active version finalization은 indexing 성공 전 기존 active version을 비활성화하지 않는다. Crash/recovery/outbox/fencing token 계약은 ADR-0017 baseline에 따라 구현한다.
일반 Builder/recommendation 후보와 일반 Editor 저장은 retrieval-visible active version 경계를 따른다. source_deleted KB, current-valid active ready document version이 없는 KB는 기본적으로 후보에서 제외한다. Current MBA-105 compatibility에서는 active pointer가 없는 completed Document의 legacy unversioned retrieval-visible chunk가 있는 KB를 후보로 유지할 수 있다. ADR-0070 enforcement 뒤 이 호환 fallback은 FR-153l~FR-153o의 frozen legacy_unverified wave membership, frozen/current platform·Organization validity epoch equality, privacy_legacy_grace_v1 hard max와 authoritative DB-time cutoff를 prefilter/final evidence gate 모두에서 통과할 때만 허용하며 allowlist/wave 부재, stale validity epoch, cutoff equality/경과와 stale cache/vector result는 제외한다. Active document version이 있으나 ready가 아니거나 manifest가 current validity를 잃었고 허용된 legacy retrieval-visible artifact도 없는 KB는 selectable ready 후보가 아니며, 일반 surface는 이를 숨겨진 KB나 권한 없음으로 표현하지 않고 safe indexing/not-ready warning 또는 disabled option으로 표시해야 한다. ADR-0045 direct-edit Agent Builder의 server-issued GraphMutation은 use 권한과 source lifecycle을 통과한 KB binding을 readiness와 별개로 저장할 수 있으며, 이 예외는 workflow 실행과 배포 preflight에서 unresolved로 차단한다. 기존 current-valid active ready version은 유지되지만 최신 sync 상태가 stale 또는 failed인 KB는 후보로 남길 수 있으나, safe warning과 score penalty 또는 낮은 confidence를 함께 제공해야 한다.
Builder/recommendation auto mode에서 route-allowed collection link 후보가 없고 client가 collection scope를 명시하지 않은 경우, Gateway resolver는 같은 active organization 안의 직접 권한 확인된 retrieval-visible KB도 safe candidate set으로 평가할 수 있다. 명시적으로 빈 collection scope를 보낸 경우에는 direct KB fallback을 적용하지 않는다. 이 Builder 편의 동작은 MBA-232 Workflow runtime resolver에 적용하지 않는다.
Destructive reset/reindex, legacy multi-document KB split/backfill, existing team_knowledge_permissions/RAG answer reference handling은 G1 data-preservation gate 승인 후에만 진행한다.
A/B 테스트나 비용 최적화 UI에서 general RAG baseline을 보여줄 때도 권한 없는 문서가 prompt, citation, trace, audit에 들어가면 안 된다. 보안상 안전하지 않은 baseline은 운영 실행이 아니라 historical, simulated, admin-only, 또는 이미 execution subject에게 허용된 resource 안의 비교로 제한한다.
일반 사용자와 workflow 작성자 화면에는 권한/정책상 제외된 문서명, KB id, source path/url/title, 정확한 제외 개수를 표시하지 않는다. 필요한 경우 권한/정책상 제외된 내부 문서 일부, bucketed count, safe reason summary 같은 낮은 해상도의 표현만 사용한다.
Trace side panel과 A/B 비교 화면은 RAG mode, retrieval strategy, citation id, 허용된 KB/document version/chunk identity, direct KB-local rank, 최종 evidence rank/score, safe metadata summary, token/cost/latency summary만 표시한다. Collection-derived evidence에는 child identity와 KB-local rank를 표시하지 않는다. Raw chunk content, raw source title/path/url, raw prompt/completion/provider response, 권한 없는 문서명/ID는 표시하지 않는다.
Knowledge/RAG는 collection permission의 action 의미와 retrieval access pattern을 정의한다. MBA-105 임시 baseline은 team_knowledge_collection_permissions와 user_knowledge_collection_permissions를 사용한다. 장기 permission enum integration, inheritance/override behavior, 공통 permission helper 구현은 Auth/RBAC 도메인에서 ADR 또는 RBAC 문서로 확정한다.
Skill은 source of truth가 아니라 source-of-truth 선택 절차다. 최종 citation/evidence는 KB/document version/chunk/ADR/decision record 같은 source-of-truth resource를 가리켜야 한다.
Skill metadata가 먼저 로드되는 Builder UX/API를 만들더라도 전역 metadata 선노출은 금지한다. Builder에는 authorization-scoped safe skill metadata만 전달하고, skill hint는 실행 시점 permission helper 결과와 교집합 처리한다.
Query rewrite 결과 원문은 raw prompt와 유사한 민감 입력으로 취급한다. Durable audit/trace/usage metadata에는 raw rewritten query를 저장하지 않고, rewrite 적용 여부와 전략 같은 safe summary만 저장한다.
Evidence sufficiency 판정은 권한/정책상 제외된 문서의 존재를 암시하면 안 된다. 부족 사유는 no_evidence, low_score, insufficient_citation, policy_filtered, operational_partial 같은 safe reason class로 낮춘다.
Retrieved context, memory summary, upstream node output, external connector content에 포함된 지시문은 untrusted evidence 안의 텍스트로만 처리한다. Prompt injection으로 의심되는 라인은 redaction 또는 delimiter 경계 안에서 무해화하고, LLM system prompt에는 해당 text를 instruction처럼 직접 합치지 않는다.
Workflow LLM node에서 system/assistant prompt에 referenced variable이 쓰이면 해당 upstream value 원문은 privileged role에 직접 렌더링하지 않고 user-role untrusted evidence block으로 분리한다. User prompt 변수는 워크플로우 작성자의 명시 요청 구성 경로이므로 기존 의미를 유지하되, RAG/memory/connector context와 결합될 때 platform guardrail이 우선한다.
Standalone Agent answer와 Workflow LLM node RAG 경로는 classification=pii evidence를 외부 LLM prompt에 넣기 전에 차단한다. 이 차단은 evidence sufficiency보다 우선하며 raw content, hidden KB id, exact denied count를 응답/trace/audit에 저장하지 않는다.
Skill authoring, test, review, publish UI는 아직 확정하지 않는다. Workflow Playground가 별도 실험 공간인지, canvas와 통합되는지, skill binding을 어떤 화면에서 조작하는지는 Workflow/Agent Builder/Knowledge 공동 UX gate에서 결정한다.
Published 전 draft skill을 workflow 실험에서 허용할지 여부도 아직 제품 UX/API 결정 대상이다. 허용하더라도 운영 실행 시점 자동 후보가 될 수 없고, actor의 KB permission/source ACL/redaction/freshness/eval gate를 우회할 수 없다.
임의 코드 실행 skill은 이 feature 범위에서 승인하지 않는다. Code-bearing skill은 sandbox, approval workflow, egress guard, dependency policy, timeout/resource cap, audit gate가 닫힌 뒤 별도 ADR로만 도입한다.
Ingestion lock은 단순 key 존재 여부만으로 release하면 안 된다. Lock release는 owner token을 비교해야 하며, 장기 작업은 TTL renew 또는 fencing token으로 stale worker finalization을 차단해야 한다.
Content identity와 retrieval artifact identity는 같은 finalization boundary에서 움직인다. content_hash 또는 fingerprint가 새 값으로 보이면 해당 값에 대응하는 redacted canonical text, chunks, embeddings, index namespace, active version이 모두 commit된 상태여야 한다.
Storage object, raw artifact, vector/index cleanup은 retry 가능한 outbox 작업으로 다룬다. Cleanup 실패는 safe audit/metric으로 남기고, DB rollback된 resource를 가리키는 scheduler나 storage side effect가 남지 않도록 idempotency key를 사용한다.

Processing Recovery Contract

Document ingestion status must not remain in indexing or processing forever after worker crash, Redis lock unavailable, or background task start failure.
Processing recovery uses processing queue/start timestamps, active fencing token, DB meta_info.progress, processing_progress_updated_at, retrieval-visible chunks, and ready document versions to decide whether work is still alive.
Redis progress and Redis lock are operational helpers, not correctness requirements. If Redis is unavailable, local processing may continue through a fallback lock path, and public status APIs must still eventually return completed or a safe failed state.
Active processing with a recent DB progress heartbeat can remain in progress. Active processing with no recent heartbeat, no retrieval-visible chunk, and no ready document version after the active stall timeout must become failed with a safe retryable message.
DocumentVersion(status=indexing) without chunks or a ready version is not enough to treat processing as alive or completed.

MBA-105 Implementation Baseline

MBA-105는 ADR-0017의 임시 합의 baseline을 구현 기준으로 삼되, Workflow RAG의 execution_subject 부재 처리는 ADR-0018을 따른다. 구현자가 따라야 할 운영 기본값, permission helper contract, active version finalization, resource hiding/no-result/partial result matrix, egress/protocol adapter 기준, 테스트 phase는 implementation_baseline.md에 모은다.

Workflow User Citation Projection

Workflow와 Chatbot의 일반 사용자 화면에 표시하는 Citation은 privileged lineage 저장소의 원본 식별자가 아니라, 최종 LLM prompt에 실제 포함된 authorized evidence의 제한된 표시 projection이다.
citationDisplayMode는 hidden, basic, detailed를 지원한다. 기존 graph에서 값이 없으면 hidden, 새 수동 LLM node와 Agent Builder 생성 node는 detailed를 기본으로 한다.
basic은 승인된 표시 라벨과 가능한 경우 page/section만 제공한다. detailed는 동일 정보와 길이가 제한되고 정제된 prompt evidence preview를 추가한다.
Collection 경유 evidence는 Collection의 승인된 표시 라벨 또는 일반 라벨만 사용하며 child KB/document/chunk 식별자와 child별 rank를 노출하지 않는다. 최종 응답에는 병합 후 전역 evidence rank만 사용한다.
권한·source ACL·public exposure·final evidence gate를 통과하지 않았거나 최종 prompt에 들어가지 않은 후보는 Citation에 포함하지 않는다.
사용자용 Citation은 최종 응답의 일시적인 projection이며 raw chunk, URL/path, credential, source principal, KB/Collection/document/chunk UUID를 포함하거나 durable WorkflowRun output에 중복 저장하지 않는다.

Out Of Scope Until Separate Approval

Destructive production cutover/reset, production data split/backfill without G1 approval.
Raw artifact opt-in storage and raw/compliance permission enum finalization.
Code-bearing Knowledge Skill and sandbox/approval/egress/resource-cap policy.
LLM-assisted query rewrite.
Break-glass source ACL bypass.
Platform-wide Workflow HTTP/GitHub/Mail egress guard.
Workflow Playground/canvas UX, draft skill authoring, submit-for-review, publish/deprecate UI.

FilesExpand file tree

requirements.md

Latest commit

History