Run retained workflows entirely in the browser playground

[taras]

Story

As a playground user, I want to author or select an immutable workflow and run it entirely in the browser, so I can experience retained execution, interruption and resumption without installing XMD or sending the Workspace to an XMD host.

Product direction

The browser is another workflow host behind the existing provider-neutral boundaries. It does not introduce browser behavior into shared production modules.

The initial topology should preserve the SQLite/DOFS architecture rather than porting the storage layer to PostgreSQL solely to reach the browser:

Browser UI
  ↕ messages and streamed output
Dedicated workflow Worker
  ├── XMD engine
  ├── SQLite WASM
  ├── DOFS
  └── browser capability providers

The engine, SQLite and DOFS run together in the Worker. The UI never participates in an effect transaction. SQLite may begin in memory for a focused proof and use OPFS for retained runs.

PGlite remains a possible future provider if a concrete PostgreSQL-only benefit justifies a PostgreSQL storage and filesystem implementation. It is not a drop-in replacement for the current SQLite schema or vendored DOFS source and is not selected by this issue.

Both workflow-definition paths

The playground supports two ways to create an immutable workflow definition.

Authored in the playground

The editor is mutable until the user starts a run. Starting freezes the current project as a canonical, content-addressed definition snapshot containing the root Markdown document and its local component files. Later edits do not mutate that run's definition: they start a new run or a history fork under a new definition identity.

The working descriptor shape is a version-1 bundle definition whose object ID is the domain-separated SHA-256 of the canonical project tree. The exact term, canonical tree encoding, admitted file types, path rules and size limits must be settled in architecture and specification before implementation.

The retained definition bytes live in the WorkflowRun database, so an exported ad-hoc run is self-contained.

Selected from Git

The user supplies authorized retrieval information, a revision and a repository-relative root document. The browser resolves the revision once and retains the existing immutable Git definition identity. The credential-free repository locator remains replaceable retrieval metadata rather than identity.

The provider may cache verified definition material for offline use, but the initial contract does not require embedding an entire Git repository in every run. Resuming an uncached Git-backed run may require reauthorization and retrieval of the pinned commit.

User-visible exports

Keep three operations distinct:

• Download workflow exports the authored Markdown project.
• Download Workspace exports the current logical files in a conventional interchange format such as ZIP.
• Export run exports one .xmdrun file containing the WorkflowRun SQLite database: immutable identity and props, filtered journal, execution records, status, current and historical Workspace roots, DOFS content and later run-owned metadata.

Import verifies the database, definition identity, roots and retained content before making the run addressable. A self-contained bundled run can resume without retrieval. A Git-backed run follows its pinned retrieval contract.

A run export can contain arbitrary Workspace files that journal filtering never inspected. Export is explicit and warns that the file may contain sensitive Workspace content.

Browser capability boundary

The browser host installs only capabilities it can enforce. Unsupported capabilities fail closed and never delegate to an ambient host:

• declarative filesystem effects use the browser Workspace;
• durable replay, interruption and resumption preserve the same contracts as the local host;
• native processes and the Git CLI are unavailable;
• Git definition retrieval uses an explicit browser provider rather than native Git;
• Agent, Prompt, service and Worker Shell support require separately authorized browser-capable providers and are not implied by filesystem support.

Completed replay attaches no Worker database, Workspace or provider. Partial replay reconstructs the ephemeral browser attachment and continues against the retained frontier.

Acceptance

• A dedicated Worker runs the XMD engine, SQLite WASM and DOFS without blocking the UI thread.
• Shared production APIs and documents remain host-neutral.
• An ad-hoc project freezes to a deterministic immutable definition; the same project produces the same identity and a changed file produces a different one.
• A Git-backed project pins a commit without making its locator part of identity.
• One declarative file effect publishes its mutation, Workspace root and filtered journal result atomically.
• Interruption before commit publishes nothing; interruption after commit resumes at the following journal frontier.
• OPFS persistence restores a run after page reload in the supported browser matrix.
• Completed replay starts no Worker attachment or live provider.
• .xmdrun export/import preserves and validates the run; an embedded-definition run resumes in the CLI without external retrieval.
• Workflow, Workspace and run exports remain distinct and have explicit sensitive-content behavior.
• Unsupported browser capabilities fail before work and never reach an inherited or native fallback.
• Bundle size, initialization time, effect latency and retained-storage growth are measured on the supported browser matrix.

First proof

Build the smallest discriminating POC after the local filesystem vertical slice exists:

1. Run one ad-hoc <File> workflow in a dedicated Worker using in-memory SQLite WASM.
2. Preserve the existing schema, DOFS and effect-transaction semantics through a browser adapter.
3. Add OPFS persistence and resume after a page reload.
4. Export the .xmdrun database, import it through the local CLI provider and verify the same current root and journal frontier.
5. Add the Git-backed definition path only after the embedded path proves the browser host boundary.

Dependencies

• Commit Workspace mutations and journal results atomically #365 supplies atomic Workspace mutation/root/journal publication.
• Contain filesystem access at the provider boundary #227 supplies the provider-neutral API.Files boundary and retained filesystem adapter.
• Add the xmd workflow start/resume filesystem vertical slice #366 supplies the first public workflow start/resume filesystem vertical slice.
• Implement retained Workflow Workspace restoration #218 remains the retained Workspace implementation umbrella.

Intentionally excluded from the first proof

• Replacing SQLite with PGlite or another PostgreSQL implementation.
• Multi-tab execution of the same run.
• Native subprocesses, native Git, FUSE, workerd or Containers.
• Public remote-host selection or an XMD cloud service.
• Browser Agent, service, external-forge or Worker Shell providers.
• Automatic publication, sharing or training ingestion of exported runs.

Primary implementation evidence to revisit

• SQLite WASM persistence and OPFS VFS: https://sqlite.org/wasm/doc/trunk/persistence.md
• PGlite browser persistence and single-connection topology: https://pglite.dev/docs/filesystems