Release Control

Topoo Cloud needs one controlled path from source change to production.

The plan is not to let every Agent become an independent deployment system. Agents contribute changes. A deterministic release program integrates, validates, builds, and promotes them.

Product purpose

Topoo should make version management automatic rather than turn Git operations into repeated user decisions.

After the Workspace, Project, Node, Agent, source connection, Checks, and release policy are configured once, a user should be able to open a new Codex, Claude, VS Code, or other execution-client Session and state only the task.

Topoo resolves the durable context and records each meaningful stage:

Edit
→ automatic Draft
→ automatic Checkpoint
→ automatic source Commit and Change Summary
→ Submission
→ immutable Node Version
→ Project Release
→ Deployment record

This does not mean creating a Git Commit for every keystroke.

GitHub remains the connected source-history provider. It stores repositories, branches, commits, and compatible collaboration history. Topoo owns the higher-level Agent, Session, intent, integration, Preview, Production, audit, and rollback model.

Users should not need to manually create branches, write Commit messages, open Pull Requests, or approve every clean integration. Topoo may perform those provider operations in the background.

The normal path is automatic. User attention is reserved for exceptions such as:

• a conflict that cannot be resolved deterministically
• an Agent requesting authority outside its configured Node or Resource scope
• a failed required Check that policy does not allow Topoo to repair automatically
• a destructive schema, secret, security, or critical-resource change
• a Production promotion whose configured policy requires explicit approval

Version recording and safe integration are complementary:

automatic version records
+ isolated Session working state
+ stale-base detection
+ file and Resource conflict detection
+ deterministic integration
= multi-Agent work that is traceable without silently overwriting accepted results

This plan uses the canonical Project and Node Model, Work Sessions and Local Runtime, Node Workbench and Lifecycle Model, and Deployment Configuration and Interaction Model:

• Project is the externally unified product and Production authority.
• Node is the persistent, permission-scoped code container and attention boundary inside a Project.
• Agent is an actor operating under explicit Node and Resource scopes.
• Work Session is a temporary Project-scoped transaction linked to one or more Nodes and an isolated Workspace.
• Submission is proposed work, not release authority.
• Node Version is an immutable accepted Node state.
• Artifact is an immutable output produced from an exact Node Version and build contract.
• Project Release Candidate is the exact set of accepted Node Versions evaluated together.
• Deployment binds the accepted Release Artifact Set to an Environment.

The problem

Several Agents may work on different parts of the same product at the same time.

If every Agent builds from its own local state and deploys directly, a later deployment can silently replace work that another Agent already released. Git history alone does not prevent this because source contribution and production authority are different responsibilities.

The current platform already contains useful source, snapshot, check, and deployment components, but they do not yet form one accepted release-control system.

Large Projects use Nodes to prevent every problem domain from sharing one undifferentiated context. A UI Agent, Deployment Agent, Billing Agent, and Domain Agent may operate through different Nodes, while several Sessions may divide smaller tasks inside the same Node.

What this plan must solve

• prevent one Agent from overwriting another Agent's accepted work
• distinguish a proposed change from permission to deploy
• combine multiple accepted changes into one known release state
• ensure Preview and Production refer to the same immutable artifact
• preserve source, checks, approvals, deployments, and rollback as one traceable record
• keep GitHub source history and Topoo release authority separate without creating a second Git repository authority

Product direction

GitHub remains the canonical source and document history provider.

Topoo does not expose GitHub as the customer product model. It maps GitHub repositories, branches, commits, Pull Requests, and Checks into Topoo Projects, Nodes, Change Requests, document revisions, and Releases. Topoo-originated edits are delivered back through an authorized GitHub branch or Pull Request rather than written to a second Topoo Git history.

Provider-specific branches, worktrees, Pull Requests, rebases, and merge operations are implementation details when Topoo can operate them safely. They remain available for interoperability and expert inspection, but they are not the normal customer workflow.

A Work Session may create one or more bounded Node Submissions against known Base Revisions. It does not deploy merely because it changed files.

One Project release controller:

1. receives bounded Node submissions
2. detects stale bases and overlapping changes
3. produces accepted Node revisions or delivery versions
4. integrates accepted Node versions into one Project Release Candidate
5. runs checks against the integrated candidate
6. creates one immutable Release Artifact Set that pins all required Node Artifacts and configuration fingerprints
7. publishes that exact candidate to Preview
8. promotes the same candidate to Production after approval
9. records a rollback target

Control-plane model

Git provider → Topoo Source Revision → Project Work Session → Node Submission(s) → Node Version(s) → optional Node Artifacts → Project Release Candidate → Release Artifact Set → Preview → Approval → Production → Rollback

Target release controller flow

Receive Node Submission
→ Verify identity and permissions
→ Lock Base Revision
→ Detect stale revisions
→ Detect file and resource conflicts
→ Integrate in dependency order
→ Publish an immutable Node version
→ Create the single Project Release Candidate
→ Run full Checks
→ Build or resolve immutable Node Artifacts
→ Seal the immutable Release Artifact Set
→ Deploy to Preview
→ Await approval
→ Promote the same Release Artifact Set to Production
→ Preserve the audit trail and rollback target

This is the target control path, not a statement that every stage is already implemented. Agent intelligence can explain changes and identify risk, while the fixed release controller owns integration order, required checks, approval gates, artifact promotion, and rollback.

Each object answers a different question:

Node Workbench and Deployment surfaces

The lifecycle is one system presented at two levels.

Node Workbench may expose:

• Source and editor modes
• Diff and working state
• Agent and Session connection
• Submissions and Change Summaries
• Node Versions and dependency versions
• Node-level Checks
• Artifacts and isolated Node Preview
• the Project Releases that consume each Node Version

Project Deployments expose:

• the accepted Node Versions in one Release Candidate
• integrated Checks and conflicts
• the immutable Release Artifact Set
• Environments, Preview, approval, Production, and rollback
• the complete Project audit chain

Node Workbench must not become an alternate Production path. Project Deployment remains the final release authority even when a single-Node Project presents a simplified editor-centered Publish interaction.

Delivery direction

Establish the connected-source path

Complete the GitHub connection and synchronization lifecycle so repository, branch, commit, Pull Request, and Check state are reliable inputs.

Establish immutable releases

Every build and deployment must point to exact Source Revisions, immutable Node Versions, and an immutable Release Artifact Set. A mutable branch name is not a release identity.

Establish Agent submissions

Represent Agent work as a proposed change with identity, base revision, affected scope, checks, and authority. Submitting work and deploying work remain separate actions.

Establish external Agent connections and local isolation

Publish execution-client adapters backed by a remote Topoo MCP or API service and browser-based OAuth. A Codex plugin is the first adapter, not the complete isolation system. Persist Project, Node, Agent, and Work Session context in Topoo so a new Codex, Claude, or VS Code Session can begin from the user's task rather than a repeated context prompt.

Add Topoo Local Runtime to allocate one Git worktree, snapshot, or copy-on-write Workspace for each writing Session and bind the Agent process to that exact cwd.

Resolve repository, topoo.app.json, Project, Agent identity, Node scopes, Base Revisions, and the local Workspace lease into a scoped Session Grant. Treat one-time claim codes as a compatibility path for clients without a browser redirect, not as long-lived credentials or the primary task interface.

Establish deterministic integration

Integrate accepted submissions through one queue and one candidate state. Detect stale bases and overlapping ownership before building.

Establish release channels

Draft, Review, Integration, Preview, and Production express different authority. Production only accepts an approved Release Artifact Set already evaluated in Preview.

Complete GitHub change delivery

After the provider-independent release model is stable, Topoo must complete authorized GitHub branch, commit, Pull Request, Check, webhook, replay, and reconciliation workflows. A detached uploaded snapshot may build and deploy, but continued versioned editing requires binding or explicitly creating a GitHub repository.

Ownership boundary

The Deployment system owns source connection, Work Sessions, Session Grants, local Workspace contracts, synchronization, Submissions, Node Version integration, candidates, Artifacts, Release Artifact Sets, promotion, and rollback.

Topoo Local Runtime owns supervised filesystem and process execution on the registered development machine. It follows Cloud policy but does not own integration or Production authority.

The Dashboard owns the presentation of those real states. It must consume stable read-only contracts and must not infer success from placeholders.

The documentation records the product model and acceptance boundary. It does not substitute planning text for implemented capability.

What not to do

• do not let Agents deploy directly from uncommitted local files
• do not let two writing Sessions use the same mutable checkout
• do not treat a Codex plugin as the component that guarantees local filesystem isolation
• do not rebuild when promoting an accepted Preview Release Artifact Set to Production
• do not treat a Branch as an immutable release
• do not create a separate release path for every source provider
• do not require users to restate durable Project, Node, Agent, and deployment context in every external Session
• do not paste long-lived API keys or deployment credentials into Agent prompts
• do not treat installing or authenticating a Topoo plugin as Production approval
• do not let a provider-specific deployment Skill bypass Topoo Submission and Release Control
• do not introduce a second Topoo Git authority or describe immutable source snapshots as hosted Git
• do not label a feature complete because some endpoints or database tables exist

Completion principle

A capability is complete only when its full user outcome has been verified.

Existing components inside an unfinished capability should be recorded as implementation evidence, but the capability itself remains not completed until all required behavior is accepted.