Publication과 EmbedDelivery

이 문서는 PXFLOW를 읽기 전용으로 전달하거나 외부 HTML에 삽입할 때 사용하는 정식 계약을 정의합니다. 사용자 작업 순서는 PXFLOW 공유·게시·HTML 삽입을 따릅니다.

핵심 원칙은 다음과 같습니다.

1. Share, Publication, App Deployment와 EmbedDelivery는 서로 다른 객체입니다.
2. 읽기 전용 Flow Viewer는 immutable Publication Version을 사용합니다.
3. 실행 가능한 PXFLOW App Embed는 생성할 때 Active인 immutable Deployment Revision을 고정합니다. 새 배포 뒤에도 기존 Embed가 고정한 servable revision은 사용자가 바꿀 때까지 유지됩니다.
4. 외부 페이지가 이동 중인 Project head나 편집 session을 직접 열지 않습니다.
5. URL, token, ACL, 게시·임베드 상태와 허용 origin을 .pxflow에 저장하지 않습니다.
6. .pxflow, SDK와 control plane 사이에 YAML manifest나 sidecar를 만들지 않습니다.

사용자 의도와 시스템 객체

사용자 의도	authoritative object	target	실행 가능 여부
같은 원본을 사람에게 계속 공유	AccessGrant 또는 ShareLink	current head 또는 명시적 pinned revision	capability에 따름
고정된 Flow를 읽기 전용으로 게시	Publication + PublicationVersion	exact PXFLOW revision	금지
읽기 전용 Flow를 HTML에 삽입	EmbedDelivery의 publicationVersion target	exact Publication Version	금지
입력 가능한 앱 주소 활성화	Deployment + DeploymentRevision	exact App Candidate	허용된 policy에 따름
실행 가능한 앱을 HTML에 삽입	EmbedDelivery의 deploymentRevision target	생성 시 Active인 exact Deployment Revision	run.execute가 있을 때만 허용

Deployment.status == active는 Publication이나 EmbedDelivery가 있다는 뜻이 아닙니다. Publication.status == published도 App Runtime이 있다는 뜻이 아닙니다.

Marketplace의 CatalogListing이 읽기 전용 Publication을 가리킬 때는 stable Publication이나 현재 activeVersionRef를 암묵 추종하지 않고 exact immutable PublicationVersion을 pin합니다. Template listing과 사용 권리는 Template Marketplace와 Organization Library가 소유합니다.

저장 경계

.pxflow가 저장하는 것

• Flow의 Node 연결과 public input·result
• 선택적인 appSurfaces
• App Builder에서 사용할 page와 responsive layout
• 배포 화면의 기본 선택인 accessPreference

control plane이 저장하는 것

• ShareLink와 AccessGrant
• Publication과 immutable Publication Version
• Deployment와 immutable Deployment Revision
• EmbedDelivery, 허용 parent origin과 lifecycle
• audit event, authorization generation과 revoke 상태

저장하지 않는 것

다음 값은 .pxflow, SDK source, .pxproject와 배포 candidate source에 기록하지 않습니다.

• 공개 URL과 iframe URL
• raw share/embed token
• 사용자·조직 ACL
• Publication, Deployment 또는 EmbedDelivery status
• 허용 parent origin
• browser session, runtime port와 process path
• CSP header 문자열이나 iframe sandbox 문자열

HTML snippet은 EmbedDelivery query에서 생성하는 projection입니다. authoritative source가 아닙니다.

공개 key와 내부 ref

• publicationKey는 workspace 안에서 고유한 semantic key입니다.
• embedKey는 publication 또는 deployment delivery scope 안에서 고유한 semantic key입니다.
• 사용자와 LLM은 publicationKey, embedKey, flowKey, surfaceKey와 version number를 사용합니다.
• repository, CAS, authorization과 audit은 opaque publicationRef, publicationVersionRef, embedRef와 기존 revision ref를 사용합니다.
• public URL segment, title, slug, hostname과 iframe 위치를 identity로 사용하지 않습니다.

semantic key grammar는 다른 public key와 같은 ^[a-z][a-z0-9_]{0,62}$입니다.

Publication

stable Publication record

Publication은 사용자가 관리하는 안정적인 게시 단위입니다. 실제 전달 bytes와 source pin은 immutable Publication Version이 소유합니다.

{
  "publicationKey": "girder_design_review",
  "title": "Girder design review",
  "audience": "unlisted",
  "activeVersionRef": "<immutable publication version ref>",
  "status": "published",
  "generation": 4
}

field	required	의미
publicationKey	예	사용자가 읽고 AI가 지목하는 stable key
title	예	표시 이름이며 identity가 아님
audience	예	workspace, unlisted, public 중 하나
activeVersionRef	status가 published/suspended이면 예	현재 전달하는 immutable version
status	예	Publication lifecycle state
generation	예	compare-and-swap과 revoke 동시성에 쓰는 증가 정수

Publication은 항상 읽기 전용입니다. 실행 가능한 전달본은 Publication variant를 추가하지 않고 App Candidate와 Deployment Revision으로 만듭니다.

immutable Publication Version

{
  "publicationVersionRef": "<immutable publication version ref>",
  "publicationKey": "girder_design_review",
  "version": 3,
  "source": {
    "kind": "pxflowRevision",
    "workspaceKey": "structural_team",
    "projectKey": "bridge_package",
    "artifactKey": "girder_design_flow",
    "flowKey": "girder_design",
    "revisionRef": "<immutable PXFLOW revision ref>",
    "semanticDigest": "sha256:4d2a..."
  },
  "closureRef": "<immutable public-safe closure ref>",
  "closureDigest": "sha256:91bf...",
  "resultSnapshotRefs": [
    "<explicitly included immutable result snapshot ref>"
  ],
  "publishedAt": "2026-07-21T09:00:00Z"
}

Publication Version은 생성 뒤 수정하지 않습니다.

• source는 exact PXFLOW revision과 semantic digest를 모두 pin합니다.
• closureRef는 viewer render에 필요한 public-safe dependency·asset·descriptor manifest를 가리킵니다.
• resultSnapshotRefs는 사용자가 포함하기로 선택하고 policy 검사를 통과한 결과만 가집니다. 결과가 없으면 빈 array입니다.
• private dependency, secret, host path, editor session과 mutable selector가 남아 있으면 생성하지 않습니다.
• 새 Flow revision을 게시하면 새 version을 만들고 성공한 뒤 activeVersionRef만 원자적으로 바꿉니다.
• 새 version 생성이 실패해도 기존 active version은 계속 제공됩니다.

source는 다음 closed union입니다.

source.kind	필수 semantic selector와 pin	이 문서에서 정의하는 전달 화면
pxflowRevision	workspaceKey, projectKey, artifactKey, flowKey, revisionRef, semanticDigest	PXFLOW Viewer와 View Embed
reportRevision	workspaceKey, projectKey, artifactKey, reportKey, revisionRef, semanticDigest	Report 출력과 외부 전달의 Report Publication profile
projectSnapshot	workspaceKey, projectKey, snapshotRef, snapshotDigest	Project Publication profile이 별도로 정의

이 문서의 publicationVersion Embed target은 source.kind=pxflowRevision인 version만 받습니다. Report는 같은 Publication aggregate를 사용하지만 Report Publication profile이 소유한 읽기 전용 Viewer와 PDF 전달 규칙을 따릅니다. Report HTML Embed를 PXFLOW Viewer 규칙으로 추측해 만들지 않습니다. Project Viewer profile도 별도 규격이 소유합니다.

읽기 전용 PXFLOW Viewer

Viewer는 Publication Version에서 결정적으로 생성하는 projection입니다. editor application을 read-only flag로 실행하지 않습니다.

포함하는 기능

• 전체 Flow fit view, pan과 zoom
• Node·connection 선택과 연결 강조
• flowKey, nodeKey, Function label, input·result의 type·unit·description 표시
• semantic key 기반 검색
• 키보드와 screen reader를 위한 Node/connection 목록 보기
• Publication에 포함된 ResultSnapshot과 evidence의 sanitized projection
• 새 탭 열기와 허용된 전체 화면

포함하지 않는 기능

• Node drag, add, remove와 reconnect
• Save, undo/redo, clipboard paste와 generic patch
• Run, Live execution과 AI edit
• source download, secret, host path와 internal ref 표시
• editor WebSocket write channel과 collaboration mutation
• 임의 HTML, plugin code 또는 Function source execution

Viewer DOM을 조작해 숨긴 편집 command를 호출하는 방식에 의존하지 않습니다. viewer ticket으로 mutation endpoint, Run endpoint와 write WebSocket에 접근하면 server가 거부해야 합니다.

EmbedDelivery

EmbedDelivery는 외부 parent page가 exact viewer 또는 app revision을 iframe으로 열 수 있게 하는 control-plane record입니다.

읽기 전용 View Embed

{
  "embedKey": "girder_design_view",
  "target": {
    "kind": "publicationVersion",
    "publicationKey": "girder_design_review",
    "publicationVersionRef": "<immutable publication version ref>",
    "closureDigest": "sha256:91bf..."
  },
  "accessMode": "unlisted",
  "parentOriginPolicy": {
    "kind": "allowlist",
    "origins": ["https://docs.example.com"]
  },
  "presentation": {
    "theme": "system",
    "initialView": "fit",
    "toolbar": "compact",
    "allowFullscreen": true
  },
  "expiresAt": null,
  "status": "active",
  "generation": 2
}

실행 가능한 App Embed

{
  "embedKey": "girder_design_app",
  "target": {
    "kind": "deploymentRevision",
    "workspaceKey": "structural_team",
    "projectKey": "bridge_package",
    "flowKey": "girder_design",
    "surfaceKey": "girder_design_app",
    "environmentKey": "production",
    "deploymentRevision": 4,
    "deploymentRevisionRef": "<immutable deployment revision ref>",
    "candidateDigest": "sha256:48ab..."
  },
  "accessMode": "authenticated",
  "parentOriginPolicy": {
    "kind": "allowlist",
    "origins": ["https://engineering.example.com"]
  },
  "presentation": {
    "theme": "system",
    "initialView": "fit",
    "toolbar": "compact",
    "allowFullscreen": true
  },
  "expiresAt": "2027-01-01T00:00:00Z",
  "status": "active",
  "generation": 7
}

field 규칙

field	규칙
embedKey	stable semantic key; URL slug에서 복원하지 않음
target	publicationVersion 또는 deploymentRevision closed union 한 개
accessMode	public, unlisted, authenticated
parentOriginPolicy	exact allowlist 또는 제한된 public-any-origin variant
presentation.theme	system, light, dark
presentation.initialView	fit, center
presentation.toolbar	compact, hidden
presentation.allowFullscreen	boolean
expiresAt	RFC 3339 timestamp 또는 null
status	EmbedDelivery lifecycle state
generation	모든 policy/target 변경에서 증가

별도 mode, readOnly 또는 runnable boolean을 저장하지 않습니다. target.kind=publicationVersion이면 항상 읽기 전용 Viewer이고, target.kind=deploymentRevision이면 실행 가능한 PXFLOW App입니다. target kind를 바꾸려면 기존 delivery를 withdraw하고 새 embedKey를 만듭니다.

App target의 workspaceKey + projectKey + flowKey + surfaceKey + environmentKey + deploymentRevision이 사용자가 읽고 CLI·MCP가 검색하는 semantic selector입니다. deploymentRevision은 해당 배포 안에서 증가하는 표시용 정수이고, deploymentRevisionRef는 이 selector에서 resolve한 exact 내부 pin이며 단독 사용자 입력으로 사용하지 않습니다.

새 App Embed는 현재 Active Deployment Revision만 선택할 수 있습니다. 새 revision이 Active가 되면 이전 revision은 superseded가 되지만, 이미 그 exact revision을 고정한 non-withdrawn EmbedDelivery가 있으면 servable로 유지됩니다. revision retention reference에는 active와 suspended delivery가 모두 포함되며 만료된 delivery도 명시적으로 target을 바꾸거나 withdraw할 때까지 configuration 복구를 위해 보존합니다.

servable은 별도 저장 boolean이 아니라 active | superseded, Deployment 철회·revision retire 여부와 non-withdrawn Embed reference로 계산합니다. 실제 Run 허용은 이와 별도로 EmbedDelivery.status=active, now < expiresAt, authorization과 runtime policy를 모두 만족해야 합니다. 따라서 suspended/expired Embed는 실행하지 않지만 resume 또는 기간 변경을 위해 exact revision 보존은 유지합니다.

superseded revision으로 새 Embed를 만들 수 없습니다. 기존 Embed는 Use this version으로 명시적으로 전환할 때까지 이전 revision을 계속 사용합니다. deployment.revision_retire는 영향받는 active/suspended/expired Embed를 Plan에 모두 표시하고, 같은 승인 transaction에서 새 target으로 promote하거나 해당 delivery를 withdraw하지 않으면 거부합니다. Suspend만으로는 revision reference가 남으므로 retire 조건을 충족하지 않습니다.

parent origin 규칙

allowlist origin은 표준 URL origin serialization 결과와 정확히 같아야 합니다.

• production은 https만 허용합니다.
• Local development profile에서만 loopback http origin을 허용할 수 있습니다.
• path, query, fragment, user info와 wildcard host를 받지 않습니다.
• default port는 normalize하고 Unicode hostname은 표준 IDNA form으로 비교합니다.
• request의 Origin, fetch metadata와 embed session이 모두 일치해야 합니다.
• target.kind=deploymentRevision은 non-empty allowlist가 필수입니다.
• target.kind=publicationVersion + accessMode=public만 { "kind": "anyPublicOrigin" }을 명시적으로 선택할 수 있습니다.
• anyPublicOrigin은 빈 allowlist의 fallback이 아닙니다.

Embed 응답은 effective allowlist에 맞는 CSP frame-ancestors를 반환합니다. 관리 UI의 일반 app shell과 embed delivery origin은 분리합니다. X-Frame-Options를 제거하는 것만으로 embed를 허용하지 않습니다.

접근 범위

Publication audience

값	의미
workspace	로그인하고 target workspace의 유효한 grant가 있는 사용자
unlisted	revocable delivery handle 또는 교환된 viewer session이 있는 사용자
public	인증 없이 public-safe version 읽기 가능

Embed access mode

값	의미
public	익명 접근 가능; target도 public 범위를 허용해야 함
unlisted	snippet의 revocable public delivery handle로 접근; 관리 credential이 아님
authenticated	로그인 session과 effective capability를 모두 확인

EmbedDelivery는 target의 effective audience보다 넓어질 수 없습니다. 예를 들어 workspace-only Publication을 public Embed로 만들 수 없습니다.

읽기 전용 viewer의 최소 capability는 artifact.read입니다. 포함 결과는 result.read, evidence는 evidence.read를 별도로 확인합니다. Publication Version target에는 run.execute, artifact.write, source.download를 부여하지 않습니다. Deployment Revision target도 artifact.write를 부여하지 않으며 Run마다 run.execute, quota, entitlement, egress와 secret policy를 다시 검사합니다.

생성되는 HTML snippet

embed.snippet query는 현재 generation과 target profile에 맞는 HTML을 반환합니다. snippet bytes는 저장 권위가 아니며 management token이나 내부 ref를 포함하지 않습니다.

<iframe
  src="https://embed.pipelinexlab.com/e/ed_7Km2pQ9vR4"
  title="Girder design PXFLOW"
  loading="lazy"
  style="width:100%;min-height:520px;border:0"
  sandbox="allow-scripts allow-same-origin"
  referrerpolicy="strict-origin-when-cross-origin"
  allowfullscreen>
</iframe>

• title은 필수이며 UI에서 편집할 수 있습니다.
• URL의 ed_7Km2pQ9vR4는 예시용 opaque·revocable delivery handle입니다. 관리용 embedKey를 URL path나 credential로 사용하지 않습니다.
• view와 app은 서로 다른 고정 sandbox profile을 사용합니다. 사용자가 보안 attribute를 임의로 완화하는 setting은 제공하지 않습니다.
• unlisted URL에는 회전 가능한 delivery handle만 포함할 수 있습니다. share management token, account token과 deployment credential을 포함하지 않습니다.
• authenticated embed는 snippet에 bearer credential을 넣지 않습니다.
• parent가 iframe을 지원하지 않거나 차단한 경우 동일 version의 top-level viewer 링크를 제공합니다.

postMessage protocol

기본 iframe은 parent JavaScript 없이 동작해야 합니다. 자동 높이와 host theme 동기화를 사용할 때만 versioned message protocol을 사용합니다.

{
  "protocol": "pxlab.embed.v1",
  "embedKey": "girder_design_view",
  "event": "ready",
  "generation": 2,
  "data": {}
}

child가 보낼 수 있는 event는 다음으로 제한합니다.

• ready
• heightChanged — bounded integer CSS pixel height만 포함
• viewStateChanged — loading, ready, blocked, error 중 하나
• runStateChanged — Deployment Revision target에서 durable Run 상태 요약만 포함

parent가 보낼 수 있는 command는 다음으로 제한합니다.

• setTheme — system, light, dark
• fitView
• focusViewer

message에 input value, Result payload, token, source, host path와 arbitrary command를 넣지 않습니다. 양쪽 모두 event.origin, event.source, protocol version, embedKey와 generation을 확인하고 unknown event/field는 무시하며 audit-safe diagnostic만 남깁니다.

버전과 갱신

• Share current-head link만 moving head를 따를 수 있습니다.
• Publication Version은 항상 exact source revision을 pin합니다.
• EmbedDelivery는 항상 exact Publication Version 또는 Deployment Revision을 pin합니다.
• 원본 Save, Publication 새 version 생성과 Embed target 전환은 각각 별도 transaction입니다.
• Use this version은 새 target을 완전히 검증한 뒤 EmbedDelivery target과 generation을 원자적으로 바꿉니다.
• 방문자는 한 document load 동안 같은 generation의 shell, Flow 구조와 asset을 함께 받습니다.
• 이전 version은 retention policy 동안 rollback 후보로 남지만 active delivery query는 현재 target 하나만 반환합니다.

UI는 다음 값을 server projection으로 계산해 표시합니다. artifact에 boolean으로 저장하지 않습니다.

• matchesCurrentSource
• changesNotPublished
• changesNotDeployed
• embedUsesActivePublicationVersion
• embedUsesCurrentDeploymentRevision
• embedTargetIsServable

lifecycle

Publication

draft → published ⇄ suspended
  │         │           │
  └─────────┴───────────→ withdrawn

• Publication은 stable delivery lifecycle만 가집니다. 새 version의 준비 상태를 Publication status에 덮어쓰지 않습니다.
• suspended는 복구 가능한 정책·관리 상태입니다.
• withdrawn은 terminal입니다. 같은 key를 재사용해 이전 delivery를 되살리지 않습니다.

PublicationVersionBuild

preparing → pending → ready
     ├──────────────→ failed
     └──────────────→ cancelled

• ready가 된 build만 immutable Publication Version을 만들고 activeVersionRef를 원자적으로 전환합니다.
• 기존 active version이 있으면 build가 preparing, pending, failed 또는 cancelled여도 stable Publication은 published 상태와 기존 delivery를 유지합니다.
• 첫 version build 전 Publication은 draft입니다.

EmbedDelivery

draft → active ⇄ suspended
  │       │          │
  └───────┴──────────→ withdrawn

• draft는 외부 route를 제공하지 않습니다.
• active만 viewer/app bytes를 전달합니다.
• suspended는 같은 configuration을 보존하지만 access를 거부합니다.
• withdrawn은 terminal이며 delivery handle과 기존 session generation을 폐기합니다.
• status에 저장하는 값은 draft, active, suspended, withdrawn뿐입니다.
• 모든 요청에서 now >= expiresAt이면 저장 status와 scheduler 실행 여부에 관계없이 즉시 거부합니다.
• 화면의 Expired와 audit용 만료 event는 expiresAt에서 계산하는 projection이며 접근 허용의 원본이 아닙니다. 만료일을 바꿔 다시 활성화할 때는 새 generation과 승인이 필요합니다.

Deployment lifecycle은 PXFLOW 앱 화면 만들고 배포하기의 별도 상태를 유지합니다. Embed 상태와 합치지 않습니다.

application command와 query

UI와 CLI는 같은 application service를 사용합니다. Publication·Embed의 개별 application command를 MCP Tool로 하나씩 노출하지 않습니다.

MCP의 public 이름은 application command를 동적으로 노출하지 않고 publication_describe, publication_plan_change, publication_apply_change, embed_describe, embed_plan_change, embed_apply_change 여섯 개로 고정합니다. 각 plan/apply tool은 아래 command closed union을 사용하며 AI와 MCP 연결의 공통 envelope와 승인 규칙을 따릅니다.

query

• publication.status
• publication.versions
• publication.viewer
• embed.status
• embed.preview
• embed.snippet

command

• publication.plan
• publication.create
• publication.publish_version
• publication.update_policy
• publication.suspend
• publication.resume
• publication.withdraw
• embed.plan
• embed.create
• embed.update_policy
• embed.promote_target
• embed.suspend
• embed.resume
• embed.withdraw

모든 effectful command는 먼저 exact source/target, dependency closure, audience, capability, origin policy, license와 예상 영향을 반환하는 Plan을 만듭니다. Apply는 planDigest, expectedGeneration과 명시적 사용자 승인을 요구합니다.

publication.update_policy는 publication.update_policy capability를 요구하며 stable Publication의 audience만 바꿉니다. immutable Publication Version bytes를 다시 쓰지 않습니다. 범위를 넓히거나 줄일 때 active closure를 새 범위에서 다시 검사하고 generation을 증가시킵니다. 새 범위에 안전하지 않은 dependency나 결과가 있으면 변경 전체를 거부합니다.

Plan은 해당 Publication Version을 가리키는 모든 EmbedDelivery를 함께 검사합니다. audience를 줄여 기존 Embed의 accessMode가 더 넓어지면 사용자는 같은 Plan에서 각 Embed를 호환 범위로 좁히거나 suspend해야 합니다. 해결되지 않은 dependent Embed가 하나라도 있으면 Publication 변경 전체를 거부합니다. audience를 넓혀도 기존 Embed accessMode는 자동으로 넓히지 않습니다.

동일한 idempotency key와 digest를 재전송해 Publication Version이나 EmbedDelivery를 중복 생성하지 않습니다. timeout으로 결과가 불명확하면 성공을 추정하지 않고 status query로 확정합니다.

Local과 Cloud

• Local .pxflow의 open/edit/save/run은 외부 게시 없이 동작합니다.
• 일반 Desktop 사용자의 외부 Share/Publication/Embed는 사용자가 승인한 immutable 사본을 Cloud Workspace에 올린 뒤 생성합니다.
• 업로드는 원본 Local 파일의 owner나 저장 위치를 바꾸지 않습니다.
• Local 변경을 Cloud Publication 또는 Embed에 자동 반영하지 않습니다.
• server-local과 aws-cloud는 같은 PublicationVersion·EmbedDelivery schema와 conformance fixture를 사용합니다.
• host adapter가 URL, session과 process placement를 해결하며 domain object에 AWS resource, host path와 port를 넣지 않습니다.

보안 header와 session

Embed route는 일반 Studio/editor route와 분리된 최소 shell을 사용합니다.

• CSP는 exact script/style asset hash와 effective frame-ancestors를 사용합니다.
• public immutable version asset만 content digest 기반 shared cache를 허용합니다.
• authenticated/unlisted HTML과 API는 private, no-store 또는 delivery-scoped cache를 사용합니다.
• Referrer-Policy, Permissions-Policy, MIME type, nosniff와 cross-origin resource policy를 route profile에 고정합니다.
• viewer/embed session은 짧은 TTL과 authorization generation을 가지며 revoke·withdraw·origin 변경 시 재검증합니다.
• iframe 안에서 password를 수집하지 않습니다. 필요한 로그인은 제품의 top-level OIDC 흐름을 사용하고 완료 뒤 제한된 viewer session을 교환합니다.
• browser가 third-party cookie를 막아도 private content를 public fallback으로 열지 않습니다. 새 탭 로그인 또는 접근 불가 안내를 제공합니다.
• telemetry, analytics, referrer와 support bundle에 raw delivery handle, 문서 본문, input/result payload와 token을 넣지 않습니다.

성능과 복구

• Publication Version target은 Runtime worker와 Python process를 시작하지 않습니다.
• viewer shell, Flow projection과 필요한 asset을 분리해 shell을 먼저 표시합니다.
• public immutable Flow projection과 asset은 digest 기반으로 cache하고 Publication withdraw/suspend 시 delivery manifest를 즉시 무효화합니다.
• iframe은 loading="lazy"를 기본으로 사용하되 viewport 진입 전에 작은 shell asset을 preload할 수 있습니다.
• Deployment Revision target의 Runtime은 iframe load와 분리해 준비하며 skeleton, progress, retry와 top-level fallback을 제공합니다.
• network가 끊기면 마지막 private HTML을 새로운 사용자에게 offline 공개하지 않습니다. 이미 authorized된 session도 expiry와 offline policy를 따릅니다.
• target promotion 중 실패하면 이전 active target을 유지합니다.

접근성과 반응형

• snippet의 title은 필수입니다.
• 320px 폭과 200% zoom에서도 pan·zoom·검색·새 탭 열기에 접근할 수 있어야 합니다.
• Flow canvas에는 같은 내용을 탐색할 수 있는 keyboard list view가 있어야 합니다.
• focus가 iframe으로 들어가고 나오는 위치를 식별할 수 있어야 하며 keyboard trap을 만들지 않습니다.
• status를 색상만으로 전달하지 않습니다.
• reduced motion에서 transition과 animated edge를 줄입니다.
• resize message가 없어도 width 100%와 configured minimum height로 핵심 기능을 사용할 수 있어야 합니다.

diagnostic

code	의미	사용자 조치
PX_PUBLICATION_SOURCE_CHANGED	Plan 뒤 source revision이 바뀜	변경 내용을 확인하고 Plan 다시 생성
PX_PUBLICATION_CLOSURE_NOT_PUBLIC_SAFE	dependency, result 또는 asset을 안전하게 전달할 수 없음	문제 항목 제외·허용 사본 생성·권한 해결
PX_PUBLICATION_PERMISSION_DENIED	게시 capability 없음	Workspace 관리자에게 권한 요청
PX_EMBED_TARGET_NOT_SERVABLE	target Publication/Deployment revision을 더 이상 제공할 수 없음	Publication Version 또는 현재 Active Deployment Revision 선택
PX_EMBED_ORIGIN_REQUIRED	App Embed에 허용 origin이 없음	exact HTTPS origin 추가
PX_EMBED_ORIGIN_NOT_ALLOWED	parent page origin이 allowlist와 다름	Embed 설정 또는 게시 사이트 주소 확인
PX_EMBED_ACCESS_TOO_BROAD	Embed access가 target audience보다 넓음	같은 범위 또는 더 좁은 접근 방식 선택
PX_EMBED_RUN_NOT_ALLOWED	app Run capability, quota 또는 policy 부족	실행 권한·이용권·Deployment 확인
PX_EMBED_VERSION_STALE	target promotion 중 expected generation 불일치	최신 상태를 다시 열고 영향 확인
PX_DEPLOYMENT_REVISION_IN_USE	종료하려는 App revision을 non-withdrawn Embed가 참조함	각 Embed를 새 version으로 전환하거나 withdraw한 Plan 승인
PX_EMBED_SUSPENDED	delivery가 일시 중지됨	관리자 사유 확인 후 resume
PX_EMBED_WITHDRAWN	delivery가 종료됨	새 delivery를 명시적으로 생성
PX_EMBED_PROTOCOL_INVALID	허용되지 않은 message protocol 또는 origin	parent integration과 version 확인

권한이 없는 source, dependency와 result의 존재를 diagnostic detail로 누출하지 않습니다.

conformance gate

정식 구현은 다음 fixture와 브라우저 검증을 모두 통과해야 합니다.

1. view delivery에서 모든 Flow/Report/Run/MCP mutation route가 거부됩니다.
2. Deployment Revision delivery도 artifact mutation과 source download가 거부됩니다.
3. Publication과 Embed target이 mutable current head를 직접 참조하지 않습니다.
4. 새 version 실패 시 기존 active viewer가 유지됩니다.
5. Embed promote가 Flow projection, asset과 metadata를 한 generation으로 전환합니다.
6. origin allowlist가 scheme·host·port를 정확히 비교하고 path/wildcard 우회를 거부합니다.
7. CSP frame-ancestors, iframe sandbox와 postMessage source/origin 검증이 negative fixture를 통과합니다.
8. revoke, suspend, withdraw와 expiry 뒤 기존 HTTP, WebSocket, viewer ticket과 cache가 재검증됩니다.
9. unlisted/authenticated content가 shared CDN cache, referrer, log와 telemetry에 남지 않습니다.
10. public-safe closure가 private dependency, secret, forbidden redistribution과 personal data를 fail closed합니다.
11. 320px, 200% zoom, keyboard-only, screen reader와 reduced-motion Viewer가 핵심 정보를 제공합니다.
12. .pxflow, .pxproject, SDK source와 generated candidate 어디에도 URL, token, ACL, origin, status와 YAML sidecar가 생기지 않습니다.
13. embed URL의 opaque delivery handle이 embedKey, Flow key, title 또는 내부 ref에서 유도되지 않으며 rotate 뒤 이전 handle과 session이 거부됩니다.
14. 새 Deployment Revision 활성화가 기존 App Embed의 pinned servable revision을 자동 변경하거나 중단하지 않습니다.
15. superseded revision으로 새 Embed를 만들 수 없고, 이전 revision withdraw 전에 영향받는 Embed가 Plan에 표시됩니다.
16. expiresAt이 지난 요청은 scheduler가 stored status를 갱신하지 않았어도 HTTP, API, WebSocket과 Run 모두 거부됩니다.
17. suspended/expired Embed도 withdraw 또는 target 변경 전까지 pinned superseded revision의 retention reference를 유지하지만 Run은 거부됩니다.
18. revision retire는 dependent Embed를 원자적으로 해결하지 않으면 PX_DEPLOYMENT_REVISION_IN_USE로 거부됩니다.

V2 control-plane activation이 V1 sharing history를 기록할 때 clearance는 AtomicHistoryBatch.mutation.entry의 historyRef, artifactRef, revisionId에서 유도합니다. 같은 SQLite IMMEDIATE transaction 안에서 persisted V1 pin을 먼저 읽고 additive after-pin을 측정한 뒤, 그 exact write에만 한 번 쓰는 clearance로 history·outbox·audit을 함께 기록합니다.

관련 문서

• PXFLOW 공유·게시·HTML 삽입
• PXFLOW 앱 화면 만들고 배포하기
• 파일 형식과 저장
• 이름·ID·참조
• 보안·권한·승인
• 기능별 사용 위치