프롬프트 검수와 번들 버전

프롬프트 번들

번들은 거버넌스 디스크립터(프롬프트 키, 템플릿 키, 프롬프트 버전, 계약 버전, 릴리스 상태, 롤백 버전 등)와 그 코드가 그리는 사용자 프롬프트 레이아웃을 묶은 것입니다. 프롬프트 버전이 곧 번들 버전이며, 클래스패스의 매니페스트 prompt-bundles/manifests/<promptKey>/<version>.json 을 가리킵니다. 한 빌드는 cortex.security-decision 번들을 정확히 두 개 실행합니다. 빌드 기본(v19 섹션)과 v20 번들(사전 블록)입니다. 이전 매니페스트는 지난 번들의 기록으로 남을 뿐 실행할 수 없습니다.

• 요소 상태 — PRESENT 는 요소 내용을 해시하고, ABSENT·UNVERSIONED·INCLUDED 는 고정 표지를 해시하므로 상태 자체가 식별의 일부가 됩니다. 번들 해시는 모든 요소를 덮습니다. 예를 들어 v19 번들은 B2(사전 없음)와 B5(최소 대응 규칙 없음)를 ABSENT 로 둡니다.
• 읽을 때 검증 — 번들 해시가 요소와 맞지 않는 매니페스트나, 이름은 같고 해시가 다른 매니페스트 두 개가 있으면 바로 실패합니다.
• 매니페스트 필드 — 요소 말고도 골든 입력, 부모 버전, 어휘 버전과 호환 어휘 버전, 롤백 대상, 선언한 모델 프로파일을 적습니다.

요청의 번들 고르기

요청마다 실행할 번들은 선택기 하나가 고르며, 선택기는 contexa.security.tiered.prompt-bundle.selector 로 정합니다. 이벤트의 첫 프롬프트가 이벤트에 번들을 고정하고, 뒤 프롬프트(Layer2 나 2차 분석)는 같은 번들을 씁니다. 이 빌드가 실행하지 않는 번들 버전을 고르면 빌드 기본 번들로 돌아가며, 버전마다 한 번 기록합니다.

레지스트리 상태

PromptBundleState 가 레지스트리의 단일 수명 주기 어휘입니다. 예전에 저장된 값도 이것으로 읽으므로 게이트·조회·화면이 릴리스를 같은 방식으로 분류합니다. 런타임에 집행되는 상태는 ACTIVE 와 CANARY 뿐입니다.

상태 아래의 작은 글자는 예전 릴리스 상태 이름입니다. 전환 API 는 두 이름을 모두 받아 PromptBundleState 로 읽고, 영수증과 화면은 위의 정본 이름으로 적습니다.

릴리스를 ACTIVE 로 옮기면 같은 범위·프롬프트 키·템플릿의 다른 ACTIVE 릴리스가 DEPRECATED 가 되어 활성 릴리스는 하나만 남습니다. DEPRECATED 로는 같은 범위에 다른 활성 릴리스가 있을 때만 옮길 수 있습니다(NO_OTHER_ACTIVE_RELEASE).

릴리스 게이트

모든 상태 전환은 PromptGovernanceReleaseGateService 를 거칩니다. 현재 상태에서 허용되지 않는 전환은 ILLEGAL_STATE_TRANSITION 으로 막히고, 그 밖에는 목표 상태에 필요한 증거를 확인합니다. 막힌 전환은 아무것도 바꾸지 않고 차단 사유와 함께 기록되며, 적용된 전환은 레지스트리 상태를 바꾸고 승인·롤백 상태를 기록한 뒤 런타임 캐시에 알립니다.

EVALUATION_NOT_FOR_BUNDLE_HASH 는 기록된 평가가 이 번들의 해시로 한 것이 아니라는 뜻입니다. 번들의 증거는 그 번들로 한 평가뿐입니다.

POST /contexa/admin/api/prompt-quality/releases/transition
Content-Type: application/json

{
  "registryScope": "PLATFORM_GLOBAL",
  "promptKey": "cortex.security-decision",
  "promptVersion": "<bundle version>",
  "targetReleaseStatus": "EVAL_ONLY",
  "rationale": "Open the shadow run of the candidate bundle"
}

응답은 전환 영수증입니다. 적용되면 200, 막히면 차단 사유와 함께 422 입니다. registryScope 를 비우면 PLATFORM_GLOBAL 입니다.

섀도 실행과 카나리

섀도 실행

섀도 실행은 후보 번들을 실제 요청에 돌려 보되 아무것도 결정하지 않게 합니다. 판정 번들을 어느 선택기가 고르든 레지스트리의 SHADOW 릴리스를 읽으므로, 설정 번들을 쓰는 호스트도 후보를 시험할 수 있습니다.

• 표본 — 이벤트 ID 의 고정 해시가 contexa.security.tiered.prompt-bundle.shadow.sample-percent(0~100, 기본 0 은 실행 안 함)보다 작은 요청이 표본입니다. 섀도 실행기는 이 속성을 설정했을 때만 생깁니다.
• 일일 상한 — UTC 하루에 shadow.daily-call-cap(기본 100)회까지 실행하며, 한 번에 모델 호출 하나입니다.
• 판정과 분리 — 판정 전에 이벤트를 복사하고, 판정 뒤에 별도 실행기에서 분석해 SHADOW 단계로 봉인합니다. 복사본은 집행 처리기에 닿지 않으므로 아무것도 집행·학습되지 않고, 세션 컨텍스트에도 아무것도 더하지 않습니다.
• 실행 가능한 번들만 — 이 빌드가 실행하지 않는 버전의 SHADOW 릴리스는 건너뜁니다.

카나리

selector=registry 일 때 CANARY 릴리스는 비율 안의 요청에 실행되고, 나머지는 최신 ACTIVE 릴리스를 씁니다. 비율은 레지스트리 행의 canary_percent(0~100, 값이 없으면 범위 전체)이며, 요청자(사용자, 없으면 세션, 없으면 이벤트)의 고정 해시에 적용합니다. 선택 항목인 canary_tenants 와 canary_resource_families 는 카나리를 그 테넌트와, 자원 주소가 목록의 계열로 시작하거나 자원 ID 가 같은 요청으로 좁힙니다.

롤백

PromptBundleRollbackService 는 범위에서 실행 중인 번들을 그 매니페스트가 선언한 롤백 대상으로 즉시 바꿉니다. 원래 번들은 DEPRECATED, 대상은 ACTIVE 가 되고, 런타임 캐시에 알린 뒤 확인한 조건과 함께 실행을 기록합니다. 거부된 롤백은 사유와 함께 기록되며 아무것도 바꾸지 않습니다.

POST /contexa/admin/api/prompt-quality/releases/rollback
Content-Type: application/json

{
  "registryScope": "PLATFORM_GLOBAL",
  "promptKey": "cortex.security-decision",
  "fromVersion": "<executing version>",
  "toVersion": "<rollback target>",
  "reason": "Decision quality dropped after the release",
  "emergency": false
}

결과에는 실행 키(RBX-...), 상태, 확인한 조건이 담깁니다. 상태는 EXECUTED 이거나 HTTP 422 와 함께 REFUSED 입니다. 긴급 중지("emergency": true)도 같은 방식으로 실행되고 AWAITING_APPROVAL 로 끝나며, 다른 관리자가 POST .../rollback/{executionKey}/approve 로 승인합니다. 실행한 운영자는 승인할 수 없습니다.

프롬프트 검수기

PromptInspector 는 봉인 증거 묶음에서 모델이 받은 사용자 프롬프트를 읽고, 검사마다 일치한 것·일치하지 않은 것·확인할 수 없는 것을 셉니다. 사람이 검토할 문제를 가리킬 뿐 프롬프트·판정·규칙은 바꾸지 않습니다. 자동 검수는 스케줄러 스레드에서 인스턴스 전체에 걸친 잠금 하나로 돌며, 아직 검수하지 않은 가장 오래된 묶음을 배치 크기만큼 검수합니다. 판정 스레드는 이를 실행하지 않습니다.

• 레이아웃 — v20 검사는 v20-dictionary-blocks 로 그린 묶음에서만 돕니다. 다른 번들의 사전이나 렌더로 그린 v20 묶음은 그 검사들에서 확인 불가로 셉니다.
• 판정 — PASS(모두 일치), FAIL(불일치 하나 이상), INCOMPLETE(불일치는 없고 확인 불가가 있음), NOT_APPLICABLE(사전 프롬프트가 아니어서 레이아웃과 무관한 검사만 돔), ERROR(검수할 수 없음).
• 발견 — MISMATCH 또는 UNVERIFIABLE. 확인 불가는 통과로 세지 않습니다.
• 버전 — 결과마다 검수기 버전(prompt-inspector/N)과 사전 버전(v20@ 와 사전 다이제스트 앞부분)을 남깁니다. 검수기 버전이 바뀌면 묶음을 다시 검수합니다.

봉인 증거 표본과 보관

OSS 설치(contexa.enterprise.enabled 가 true 가 아님)에서 수집이 켜져 있으면(contexa.pqa.oss.sealed-evidence.capture-enabled, 기본 true) 판정을 증거 묶음으로 봉인합니다. 묶음에는 보낸 그대로의 시스템·사용자 프롬프트, 표준 컨텍스트, 실행 메타데이터가 들어갑니다. 엔터프라이즈는 봉인 묶음을 자체 스키마에 두므로, 엔터프라이즈가 켜져 있으면 OSS 검수기 빈은 만들어지지 않습니다.

• 변경 뒤 구간 — 기동 뒤, 또는 실행 중 번들이 바뀐 뒤 첫 full-capture-after-change(기본 1000)건의 판정은 모두 봉인합니다.
• 표본 — 그 구간이 지나면 상관 ID 의 고정 해시로 요청의 sample-percent(기본 1, 1~100)를 봉인합니다.
• 보관 — 묶음은 retention.period(기본 90 일) 동안 보관합니다. 마지막 검수에서 문제가 없었던 묶음은 retention.clean-period(기본 30 일)가 지나면 지웁니다. 검수에서 무언가 찾은 묶음은 기본 보관 기간을 따릅니다.
• 검수 표본 — 묶음 ID 의 고정 해시로 봉인 묶음의 contexa.prompt-inspection.sample-percent(기본 100)를 검수합니다.

콘솔과 API

모든 화면과 엔드포인트는 ADMIN 역할이 필요합니다.

설정

contexa:
  security:
    tiered:
      prompt-bundle:
        selector: registry
        shadow:
          sample-percent: 5
          daily-call-cap: 100
  prompt-inspection:
    batch-size: 50
    sample-percent: 100
  pqa:
    oss:
      sealed-evidence:
        sample-percent: 1
        full-capture-after-change: 1000

최소 대응 규칙과 프롬프트 예산 설정은 AI 엔진 구성에 있습니다.

관련 문서