Branching & publications

Vadyl treats your product model like source code: there is one persistent branching DAG per project, with immutable commits, mutable workspaces, isolated sandboxes, typed proposals, and three-way merge. Schema, policies, workflows, handlers, scheduled tasks, webhooks, connections, runtime configuration, deployment intent — all of it lives on the DAG.

The DAG

• Branch — a named lineage. Like a git branch but for your product model.
• Commit — an immutable snapshot of the contract at a point in time. Content-addressed via SHA-256 of canonical-serialized manifest. Identical content always produces the same commit hash.
• Workspace — your in-progress overlay on a branch. Optimistic concurrency with version tokens (CAS-protected). Multiple workspaces can fork from the same branch head.
• Sandbox — an isolated, disposable database (and runtime) for testing risky changes against real-shaped data.
• Proposal — a typed pull-request analog. Carries a diff between two branches plus approvals, validation results, and policies.
• Deployment — explicit intent to apply a branch to an environment. Drives DDL execution, runtime publication, and progressive rollout.

Manifest domains

Vadyl's branching substrate covers 19 typed manifest domains as of SnapshotManifest.CurrentFormatVersion = 15. Each domain has its own diff analyzer that produces typed semantic operations (not text diffs). Examples:

• Schema (entities, fields, relations, indexes, constraints)
• ProviderBindings (which providers a project is bound to)
• Federation (cross-project data contracts)
• Seeds (declarative seed data)
• RuntimeConfig (capability binding configuration)
• DeploymentIntent (target environments, ramp policies)
• Scheduling (task definitions, triggers)
• Webhooks (endpoints, event filters)
• SourceAssets (authored code modules)
• Connections (governed external integrations)
• Handlers, Workflows, DatabaseSources, VersionGovernance, Automations, Agents, …

Three-way merge

Merging branches uses semantic three-way merge against the common ancestor. The merge engine produces typed conflict reports — not line-by-line diffs. A conflict on an entity field is described as "Order.total: precision=10 vs precision=12", not as a string diff. You resolve at the semantic level, then commit the merge.

Path-aware conflict detection means renaming an entity on one branch and adding a field to it on another doesn't conflict — the merger understands rename intent.

Validation pipeline

Every commit and merge runs through the validation pipeline. Built-in rules include schema integrity (no orphan FKs, no duplicate keys), migration safety (would this break a deployed environment?), and destructive change detection. You can register custom validation rules for project-specific invariants.

Validation is fail-closed at the proposal layer — a proposal cannot be merged if validation fails or if the branch's protection policy requires it.

Publications

A ProjectRuntimePublication is a versioned, atomic snapshot of the compiled runtime: schema, handlers, workflows, scheduled tasks, agents, webhooks, capability bindings — everything that participates in serving requests. Publications are monotonic per project and form an auditable history.

Atomic transition: at any moment, a project serves traffic from exactly one publication. The runtime swap is instantaneous. Rollback is a publication-pointer change.

Sandbox isolation

A sandbox is a real database (not a mock) with the branch's DDL applied and optionally pre-seeded from a snapshot. You can fork sandboxes, checkpoint operation logs, undo/redo at the operation level, and merge sandbox-derived changes back into the workspace.

Environments and deployments

An environment (dev, staging, production) is a binding from a branch to a runtime location with its own infrastructure. A deployment is the explicit operation that promotes a branch's commit to an environment, runs DDL through the schema-transition pipeline, advances the publication pointer, and progressively shifts traffic per the ramp policy.

See your first deploy for the end-to-end flow.