Product Journey Import, Export, and Portability

Product Journey Import, Export, and Portability means a Journey can cross repository, API, CLI, non-developer, storage, and publication boundaries without silently changing its outcome, identity, ownership, protected source, evidence, or release history.

Portability is not “we can export visible steps.” A trustworthy round trip preserves semantics and reports every unsupported or lossy field.

Canonical identity

Keep Journey ID stable. Every immutable Journey Version has its own identity and parent/base relationship. Observations, Runs, Decisions, Renditions, Publications, and Release Books retain the exact version they reference.

Do not create a new Journey merely because data entered through another channel. Bind or branch under explicit policy.

Canonical authoring model

The authoring model records:

• Journey and version identity;
• field path, value, ownership, and last revision;
• attributed initial and later revisions;
• Observation, upload, Rendition, and readiness references;
• protected advanced code and source location;
• unsupported source and reason;
• semantic hash.

TypeScript, JSON, and JSON-shaped YAML representations use the same model.

Native Playwright import

Playwright import preserves repository, config, suites, fixture imports, authentication and storage-state references, locators, assertions, traces, visual checks, command, and source hashes. Native execution remains unrewritten.

Imported results are candidates until exact native execution passes and the source binds to canonical authoring. Unsupported hooks or constructs stay protected.

Procedure and media imports

Scribe/Tango outward procedures can be imported as attributed candidates, but remain unverified and ineligible for release gating until bound to exact-session Observation evidence. Screenshots, videos, guides, and documentation URLs remain Rendition or Publication candidates; visual plausibility cannot promote them.

This prevents a polished outward artifact from becoming product truth.

Ownership metadata

CSV or API metadata can import Journey ID, owner, and criticality only when the source supplies them. It cannot infer Journey identity from a page title or URL. Preserve adapter and source provenance.

Public and preview discovery

Discovery can cluster public or authorized preview candidates by route/structure. Public discovery must not claim authenticated surfaces. Every cluster remains unverified until human or supported deterministic binding.

Export formats

The CLI supports TypeScript, JSON, and YAML format identifiers. Current YAML uses deterministic JSON syntax compatible with YAML 1.2. The API can expose explicit open-export contracts.

Every export identifies contract and schema version. Local-cache export requires an explicit offline confirmation so it is not mistaken for server-current state.

Semantic comparison

Compare normalized semantic hashes and field-level diffs, not formatting. Object key order, whitespace, or YAML style should not create a new Journey meaning. A changed protected field, outcome, or state contract should.

Round-trip validation exports, imports, and ensures semantic diff is empty.

Three-way editing

Repository and non-developer edits can diverge. Merge against a shared base, retain both authors, surface same-field conflict, and prohibit hidden overwrite. Presentation-owned fields cannot replace protected code. Code changes cannot erase approved visual explanation silently.

Idempotent synchronization

Offline capture synchronization uses idempotency keys and content identities. Repeated delivery creates no duplicate Journey Version, Observation, upload, or Publication. Reusing an idempotency key with different content fails. Same identity with different bytes fails rather than overwriting.

Stable outward URLs

Publications preserve one stable URL for the continuing intent and immutable URLs for versions when the Channel supports them. Migration maps historical Reshot URLs to canonical Publication identity and requires review when visual truth is unknown.

One-hop redirects preserve retired public search intent. Do not point historical versions to unrelated content.

Evidence portability

Portable evidence bundles include signed manifest, evidence pack, and artifacts. Offline verification checks schema, pack and manifest hashes, signature, artifact presence, media type, size, checksum, and capture linkage.

Release Books separately provide a signed outcome-to-release record. Use the Release Book Verifier and independently trusted key identity.

Storage portability

Artifact metadata identifies content hash, media type, size, and storage path. Moving between R2, S3-compatible storage, or supported local/private systems must verify downloaded bytes before updating the durable locator. Never turn a private object into public content during migration.

Import quality report

Every import should report:

• source adapter and retrieval time;
• input count and mapped count;
• review-required count;
• unsupported constructs;
• rewritten source count, expected to remain zero for native execution;
• semantic hash and validation;
• stable URL dispositions;
• verification and release-gating eligibility;
• next action.

Version negotiation

Exchange contract name, schema version, client surface, and supported capabilities before transferring data. Reject an incompatible major version or negotiate a documented supported subset. Do not assume that a newer producer can safely down-convert protected source or evidence.

The Open Product Journey Contract publishes capability-negotiation request and response schemas for this boundary.

Deletion and revocation

Portability includes exit, not only import. Document what can be deleted, tombstoned, disconnected, or retained under release/audit policy. Revoke credentials and subscriptions, stop deliveries, remove private storage when eligible, and preserve only allowed signed history.

Portability test

1. create a Journey with protected and visual-editable fields;
2. export TypeScript, JSON, and YAML;
3. import each and assert identical semantic hash;
4. run native Playwright before and after;
5. attach an Observation and Decision;
6. create a Rendition and Publication;
7. export a signed Release Book;
8. verify offline;
9. introduce a conflicting edit and confirm no hidden overwrite;
10. remove the source system and prove open exports remain readable.

Boundaries

Do not claim portability for a provider or format until its real importer/exporter and destructive/rollback path work. Package code, a reference capability, or a generated file without re-import verification is insufficient.

Continue with Product Journey YAML, Reshot CLI, Product Journey API, and the Open Product Journey Contract.