테스트와 배포
현재 구현과 목표 release gate를 구분합니다
현재 구현된 Component 경로는 annotation 기반 ComponentDescriptor 등록, 미리 작성한 V1 content/component.json container의 local install, exact release resolve와 executor 실행입니다. decorator metadata에서 declaration/executor를 만드는 packaging bridge, live package UI와 App Surface host는 아직 없습니다. production Flow reader는 Component를 read-only unsupported로 표시하며 exact target/settings와 연결 사용처에서 유도한 일부 port만 투영합니다. 후속 V2 Canvas는 package UI를 마운트하지 않고 host-owned component.declarative@2만 사용하며 settings를 component-declared-settings@1로 선언당 최대 8개까지 받고 host control registry가 그립니다. rich surface는 RFC-016이 소유하는 component-rich-surface-declaration@1 범위이고, bridge는 Node context 읽기와 settings 제안까지만 허용합니다. 이 문서에서 그 밖의 UI·격리 검사를 요구하는 항목은 구현 완료 전 통과시켜야 할 계약 전용 release gate입니다. exact ProjectScope data-path isolation은 구현됐지만 현재 third-party Component activation은 Project authorization과 execution-trust closure가 닫힐 때까지 차단합니다. inactive quarantine install state도 없으므로 current V1 installer는 third-party container의 production admission 절차가 아니라 internal/test 감사 경로로만 다룹니다.
먼저 unit test를 실행합니다. 아래 pxlab package check/build는 목표 CLI이며 현재 배포된 명령이 아닙니다. 현재 package folder는 python -m pipelinexlab install ... 과정에서 결정적으로 pack되고 safe reader와 installer가 contract를 검사합니다.
python -m pytest
# 계획된 CLI — 현재 미구현
pxlab package check .
pxlab package build . --output dist/release배포 후보는 계산 결과뿐 아니라 SDK에서 작성한 key, type, unit과 version이 현재 PXFLOW와 AI에서도 같아야 합니다. V2는 host-owned declaration projection과 선언된 settings만 검사하며, rich editor parity는 RFC-016의 component-rich-surface-declaration@1이 소유합니다. 아래 순서로 같은 입력이 같은 revision을 실행하는지 확인합니다.
먼저 기록할 version
배포할 때는 다음 version을 구분해 기록합니다.
- package version: 설치·배포 묶음
- Function version: public input/result와 계산 의미
- Component identity: package version과 stable
componentKey로 고정한 reusable definition - Extension template version: 선택한 Extension의 문서 semantic 구조와 calculation 의미
- App Surface category contract와 format contract version: standalone
pxflow_app·streamlit같은 화면의 lifecycle - SDK schema version: descriptor와
.pxflow구조 - Runtime compatibility range: 실행 가능한 worker/runtime 범위
Function의 key, version과 description은 모든 @px.function에 필수입니다. 배포 빌드에서 누락된 값, 잘못된 SemVer 또는 중복 functionKey + version이 발견되면 배포를 중단합니다.
@px.component(key=..., label=..., description=...) definition은 stable componentKey를 등록합니다. exact 실행 identity는 installer가 측정한 package release와 componentContractVersion까지 결합합니다. decorator는 definition metadata만 등록하며 Node placement, nodeKey, layout, connection과 Run을 소유하지 않고 현재 declaration/executor를 생성하지도 않습니다. 관측된 local package의 signature state는 absent 또는 present-unverified일 수 있지만 두 상태의 admission 결과는 다릅니다. local user-accepted admission은 signature verified 또는 absent만 후보로 보고, 모든 local install에 explicit acceptance와 audit를 요구하며 absent에는 local warning도 요구합니다. present-unverified, invalid, revoked, stale/unavailable verification evidence는 모든 channel에서 reject합니다. Marketplace admission에서 signature와 revocation을 실제 검증한 release만 verified라고 부릅니다.
Function version 변경 기준
| 변경 | 권장 SemVer | 이유 |
|---|---|---|
| 설명 오탈자, 계산 의미 불변 | patch | input/result와 계산 의미 불변 |
| optional input 추가, 새 result 추가 | minor | 기존 caller 유지 가능 여부를 fixture로 검증 |
| required input 추가 | major | 기존 Flow가 invalid가 됨 |
| port key 삭제·rename | major | Flow/Component editor/MCP 연결 주소가 깨짐 |
| type, shape, unit 또는 nullability 변경 | major | 직렬화·실행 의미 변경 |
| 계산 기준·공식 변경 | 의미 영향에 따라 minor 또는 major | result provenance가 다른 의미를 가짐 |
| 성능 개선, 같은 결과 허용오차 | patch | 수치 회귀 검사 통과 필요 |
result 추가가 기존 사용자의 고정된 schema 처리에 영향을 주는 경우 major로 올립니다. Function identity와 의미의 version은 @px.function(key=..., version=..., description=...)에 명시합니다.
배포 전 테스트
1. Function unit test
- 정상 입력과 expected result
- 최소·최대·경계값
- invalid type, null과 constraint
- unit normalization
- deterministic 허용오차
- 예상 가능한 업무 오류 code/path
- timeout과 cancellation cleanup
2. Public target descriptor test
functionKey와 decorator version- Function/port description
- input/result key와 지원되는 정확한 type
- required, nullable와 default의 type·marker 파생
- unit과 constraints
connection기본True와 explicitFalse- exact policy(
side_effect,retry,cache,parallel_safe, timeout)와 capability - public Python module, Function/result/record symbols와 generated
.pyi일치 - generated SDK import/usage가 실제 type check를 통과하는지 확인
@px.component의 stable component key, label, description, Category/Subcategory와 annotation-derived input/result- public
@px.componentsymbol의 descriptor port key set과 별도로 작성한 installed declaration의 input/result key set 일치 - V2 settings가
component-declared-settings@1의 closed kind와 선언당 8개 상한을 지키는지 확인 - 계약 전용: admitted declaration의 exact identity·Port를 host-owned
component.declarative@2이 투영하고 package body/modal/renderer가 없는지 확인
descriptor test는 SDK declaration에서 생성한 하나의 canonical descriptor를 기준으로 수행합니다.
3. SDK와 PXFLOW 저장·열기
저장·열기 round-trip 뒤 다음 값이 정확히 같아야 합니다.
- Node key
- port type, unit과 description
- 이름 있는 다중 result target
- default와 nullability
- Function version
- source에 명시한 stable Node ID
4. PXFLOW 일치 확인
- 실제 Canvas Node 하나가
flow.node(...)placement 하나에 대응 - decorator 없는 일반 Python
def를flow.node(...)target으로 전달하면 validation이 실패하고 Function 또는 Component target을 사용하도록 안내함 @px.function은 read-only Function Reference Node로 배치되고 Definitions에서 관리됨- imported
@px.component는 exact installed target으로 배치되지만 현재 reader에서는 read-onlyunsupported이고, target/settings와 usage-derived partial ports 외에 renderer/modal·label·full contract snapshot을 만들지 않음 - Project-owned Function 변경 전 모든 사용 중인 Node와 contract diff가 표시되고, 전체 갱신 또는 특정 Node용 Clone / branch가 새 Function·Flow revision으로 저장됨
- decorator 선언과 import만으로 Canvas 객체나 Run이 생기지 않음
- repeated reusable target placement가 서로 다른 explicit Node key를 유지
- 모든 input relationship이
flow.connect(...)에 명시되고 arbitrary placement keyword가 없음 - 모든 public result가
flow.result(...)에 명시됨 - same-Flow
flow.group(...)은 presentation membership만 바꿈 - imported exported Flow object는
flow.subflow(...)로 배치되고 caller에서 read-only임 - Flow 연결 cycle과 required port 진단 일치
- 지원하는 모든 실행 환경의 같은 validation 결과
- SDK-linked edit의 source diff → Apply → source를 다시 읽은 Flow 연결 구조 일치
- source-safe하지 않은 변경의 detach 차단
- 계약 전용: package 제거 뒤 saved exact
ComponentRef보존; original package bytes는 package artifact owner가 실제 retained한 경우에만 recovery evidence로 사용하고 Flow 저장값에서 추론하지 않음; full last-verified port-contract snapshot은 저장하거나 약속하지 않음 - 계약 전용: package 재설치 뒤 contract diff 검토와 Validate 전에는 실행 차단
- 계약 전용: Unknown Component는 exact source·dependency·lock 복구 또는 명시적 replacement preview로만 해결
5. V2 host Component 연결 확인
이 절은 host-owned component.declarative@2 bridge에 적용하는 UI gate입니다. 현재는 .pxflow의 exact target과 기존 V1 settings 보존, Runtime executor 연결만 검증할 수 있습니다.
- upstream result → exact Component input port
- admitted declaration → host Node의 exact Port projection
connection=False가 host discovery와 AI discovery에서 제외- V2 settings member가 선언된 setting key와 closed kind만 담는지 검사
- package executable UI, renderer, modal, iframe과 raw HTML/CSS가 0인지 검사
- rich surface 선언이
component-rich-surface-declaration@1의 closed shape를 지키는지 검사
5.1 문서 template을 제공하는 Extension 확인
다음 항목은 @px.paper template과 document editor를 제공하는 Extension의 계약 전용 gate입니다.
- Extension이 공개하기로 한 Canvas Component 수와 실제 registry entry 수가 일치함
- public document Component definition이 exact ComponentDescriptor와 일치함
@px.papersource를 materialize한 template의 paper·block·table·calculation·equation·plot·reference key 일치- builder key 하나에서 파생한
blockKey + fieldKey/tableKey/calculationKey/equationKey/plotKey가 갈라지지 않음 - referenceEquation, EngineeringCalculation과 current Node input mapping 종류 구분
- scalar·whole Table·CalculationTrace·plot series가 Extension schema의 typed document value로 materialize됨
- FormulaExpression의 모든 discriminant payload round-trip, type, unit, scalar·vector·matrix shape와 dependency validation
- piecewise coverage·overlap, calculus bound variable와 solver setting 진단
- solve·iteration의 method, tolerance, maximum iteration과 convergence 기록
- 화면과 Document/PDF artifact의 수식·대입값·rounding projection 일치
- SDK-linked source diff → Apply → rematerialized template semantic diff 0
- 같은 source closure·dependency lock의 반복 materialization semantic digest 일치와 network/time/random/secret 접근 거부
- source-safe template 변경은 source round-trip, Node instance draft는 Flow revision에 저장
- raw executable Python, HTML, JavaScript와 expression string이 Extension document calculation으로 저장되지 않음
px.CalculationTrace가 immutable ResultSnapshot에서 calculationProjection으로 표시됨- Canvas result → document Component Node input → editor mapping이 같은 exact port를 유지
- editor mapping이 별도 Invocation이나 Run을 만들지 않음
5.2 Adapter category·format 확인
이 절은 App Surface/Adapter host 활성화 전의 계약 전용 gate입니다.
- 모든 descriptor가 library 이름이 아니라 closed
adapterCategory + formatKey조합을 사용 app_surface + pxflow_app이 generated Flow input/result reference만 사용하고.pxflow.appSurfaces와 SDK source가 round-trip됨- 배치된 Component Node의 host-declarative Canvas body가 exact ComponentDescriptor presentation과 host renderer registry에서 resolve됨
- settings editor는 별도 versioned settings 계약, rich editor/viewer는 RFC-014 후속 계약을 통과한 surface에서만 resolve됨
app_surface + streamlit이 package-definedsurfaceKey, import 가능한 entry와 typed Flow target만 선언- App Surface descriptor가 semantic target reference와 허용된 closed-schema field만 포함
- Local과 SaaS에서 같은 descriptor bytes와 category·format version을 사용하고 Host Adapter·placement만 달라짐
- unknown category·format, unknown payload field와 허용하지 않은 host capability를 거부
adapter_search → adapter_describe가 source parsing 없이 같은 semantic target을 반환- Extension document 변경은 verified package command, Streamlit target 실행은 PXFLOW command를 사용하며 generic Adapter execute가 없음
- marketplace-verified release가 package-defined App Surface descriptor digest와 format module closure를 pin함
6. Table·row 반복 확인
최소 fixture:
| 선택 shape | port shape | 기대 실행 |
|---|---|---|
| 1×1 | scalar | 1회 |
| N×1 | scalar | shape mismatch; 명시적 batch Run 또는 Table port 필요 |
| N×1 | list | 1회 |
| N×M | typed table | 1회 |
추가 검증:
- arbitrary start cell selection
- stable domain row key와 source order
- input/result/document-only 영역 구분
- shared input
- 다중 result projection
- 행 추가·삭제·재정렬 후 semantic selector 유지
- source 값과 destination port shape가 정확히 일치하고 scalar에 table을 연결하면 명시적 오류가 발생
- 일부 행 실패 시 성공 행 유지
- 다른 Flow로 이어지는 result→input dependency
- unbounded fan-out 방지
7. MCP·AI 확인
- search → describe → resolve → validate/plan → apply/run 순서
- generated input/result schema 사용
- semantic key로 exact target resolve
- label·path·UUID·좌표 fallback 없음
- stale generation은 conflict로 표시하고 원본 revision을 유지
- 큰 result는 summary + resource link
- error code/path/params/action 일치
- write/run에 사용자 승인과 server-side authorization 재검사
- SDK-linked 변경이 source-safe update 경계를 지킴
8. 보안·실행 환경 테스트
Component data path의 exact ProjectScope 격리와 별개로 authenticated-principal authorization과 production execution-trust gate는 미구현입니다. 아래 첫 항목은 구현 사실이 아니라 release 차단 조건입니다.
- user/project별 worker isolation
- filesystem mount allowlist
- outbound network policy
- secret 최소 주입과 log redaction
- CPU, memory, file descriptor, timeout과 result-size limit
- cancellation 후 late result가 Run 상태를 되돌리지 않음
commandId중복 요청과 retry storm 방지parallel_safe와 quota를 모두 만족할 때만 병렬 실행- resource link dereference마다 ACL 재검사
Package 준비 체크리스트
- [ ] package 이름과 version이 고정되어 있습니다.
- [ ] 모든 public
@px.function이 explicit stable key, version과 description을 가집니다. - [ ] 모든 public
@px.component가 explicit stable component key, label·description과 typed input/result를 가집니다. setting contract는 구현 전까지 별도 계획 항목입니다. - [ ] dependency lock과 지원 runtime 범위가 있습니다.
- [ ] FunctionDescriptor를 SDK declaration에서 한 번 생성합니다.
- [ ]
public-module의 import와.pyi가 FunctionDescriptor의sdkprojection과 일치합니다. - [ ] public
@px.componentsymbol과 별도로 작성한 V1 declaration이 같은 component key·port key set을 가리킵니다..pyi·renderer bridge는 계약 전용입니다. - [ ] required capability가 최소 권한으로 선언되어 있습니다.
- [ ] Function/Component semantic key와 runtime capability key가 분리되어 있습니다.
- [ ] native code가 있으면 서명·allowlist·플랫폼 matrix가 있습니다.
- [ ]
PaperContributionDescriptor가 있으면 command transaction, block schema, screen/export와 missing-extension placeholder를 시험했습니다. - [ ]
@px.paper가 있으면 FormulaExpression·unit·solver·projection과 screen/PDF 일치를 시험했습니다. 별도 승인된 output adapter가 있으면 그 versioned conformance도 추가했습니다. - [ ] App Surface host가 구현된 뒤 category·format contract, descriptor digest, semantic target와 Local/SaaS lifecycle을 시험했습니다.
- [ ] package manual이 목적·절차·완료 상태·취소·복구를 설명하고 contribution key와 diagnostic link가 유효합니다.
- [ ] Python 실행 환경이 application service와 격리됩니다.
- [ ] large result가 bounded object reference를 사용합니다.
- [ ] license, notice와 third-party dependency 검사가 통과합니다.
배포 전 최종 확인
다음은 목표 release gate입니다. 현재 local user-accepted install과 marketplace 공개를 같은 trust 상태로 취급하지 않습니다.
- source lint/type check와 unit test
- descriptor schema와 version policy
- SDK 저장·열기 golden fixture
- 지원하는 모든 실행 환경의 validator 결과 일치
- PXFLOW canvas round-trip
- scalar/list/Table port shape와 명시적 batch Run scenario
- MCP
function_search/function_describe의 exact descriptor·SDK usage와 generated schema adapter_search/adapter_describe의 category·format descriptor와 semantic target 일치- sandbox, capability와 ACL negative test
- cancellation, timeout, partial result와 recovery test
- representative benchmark와 regression budget
- user-facing description·example 검토
- 다른 소비자 package에서 public import,
flow.node(...)와 IDE type check PaperContributionDescriptor와 package manual의 schema·링크·locale·sandbox 검사- marketplace 공개라면 verified signature·fresh revocation, provenance와 rollback 정보; local
user-acceptedinstall이라면verified또는absent만 허용하고 explicit acceptance와 audit를 기록하며absent에는 local warning 추가;present-unverified,invalid,revoked, stale/unavailable verification evidence는 모든 channel에서 reject - missing package에서 exact target 보존, 설치·version 복구, contract diff 검토와 Validate
검증 하나라도 실패하면 release를 중단하고 실패한 화면·실행 환경과 diagnostic을 기록합니다. catalog에는 이전 정상 version을 유지합니다.
전체 사용 흐름 확인
배포 후보는 최소 다음 흐름을 실행합니다.
현재 SDK, PXFLOW reader와 MCP는 같은 flowKey, nodeKey, portKey, Function version, Flow revision과 Run provenance를 가리켜야 합니다. Component editor와 standalone App Surface parity는 각 bridge가 구현된 뒤 같은 semantic Flow target을 참조해야 하는 계약 전용 gate입니다.
배포 후 확인
- 오류율, latency, memory, cancellation과 partial failure를 version별로 관찰합니다.
- 기본 telemetry에는 상태, latency와 bounded diagnostic metadata만 저장합니다.
- 문제가 있는 Function version은 새 Node 배치에서 차단할 수 있으나 기존 Run provenance는 유지합니다.
- rollback은 이전 package와 Function version을 명시적으로 pin합니다.
- semantic key rename은 alias를 영구 유지하지 않고 종료 version과 시점을 공지합니다.
- Report와 Flow에 연결된 Function을 제거하기 전 impact 목록을 제공합니다.
배포 기록
배포 기록에는 최소 다음을 남깁니다.
- package와 Function version 목록
- descriptor/schema digest
- test command와 결과
- golden fixture digest
- benchmark 비교
- capability와 security review
- 알려진 제한과 rollback 절차
- SDK, PXFLOW, MCP와 optional Component·artifact compatibility 결과