Node Workbench and Editors

The canonical objects shared by every Node editor, Agent submission, version, artifact, release, and deployment in Topoo Cloud.

This page defines the canonical lifecycle objects shared by all Topoo Nodes.

It is a target product model. It does not mean that the current Node editors, version ledger, release controller, or deployment system already implement every object described here.

Read this model together with Project and Node Model, Work Sessions and Local Runtime, and Deployment Control Plan.

Canonical statement

Node is the persistent, permission-scoped code container and attention boundary inside a Project.

Node Workbench is the editing and lifecycle surface for that Node; it is not a separate authority or a separate source of truth.

Project Release is the accepted combination of Node versions that represents the externally unified product.

A Website, service, workflow, component, schema, document, or Agent definition is not a separate lifecycle model. Each is a Node capability expressed through a different editor, validator, builder, preview adapter, or runtime adapter.

Unified objects

Object	Canonical responsibility
Project	Organizes Nodes and owns environments, domains, Production authority, integrated releases, observability, audit, and rollback.
Node	Owns one durable problem and responsibility boundary, including scope, Source, linked Session evidence, Submissions, versions, dependencies, and delivery history.
Node Workbench	Presents the Node's editor, changes, Submissions, versions, Checks, Artifacts, Previews, deployments, and logs in one operating surface.
Source Binding	Connects a Node to one or more GitHub repository roots, packages, or detached uploaded snapshots.
Source Revision	Identifies one immutable source state recorded by Topoo. It maps to an exact GitHub commit or detached imported snapshot.
Agent	Acts under a Node's identity, permissions, prompt, scope, and operating procedure.
Work Session	Provides one temporary Project-scoped work transaction and links to one or more Node scopes. A Session does not create a new Node or carry Production authority.
Submission	Proposes a bounded change against a pinned Base Revision, with actor, intent, affected scope, Diff, summary, and evidence.
Change Summary	Explains what changed, why it changed, who requested and performed it, what may be affected, and which validation was performed.
Check	Records a deterministic validation result against a Submission, Node Version, or integrated Project Release Candidate.
Node Version	Publishes an immutable accepted state for one Node. It pins the accepted Source Revision, Submissions, Checks, dependency versions, and delivery metadata.
Artifact	Stores an immutable build output produced from an exact Node Version and build contract. Nodes without a build capability do not fabricate an Artifact.
Node Preview	Exposes a Node Version or Artifact for isolated evaluation without granting Project Production authority.
Project Release Candidate	Pins the accepted Node Versions being evaluated together, including unchanged versions retained from the current release.
Release Artifact Set	Immutably maps the Release Candidate to its Node Artifacts, configuration fingerprints, routes, and integration evidence.
Deployment	Binds one immutable Release Artifact Set to an Environment. Preview and Production promotion reuse the same accepted outputs.
Approval	Records who or what authorized a specific promotion under Project policy.
Rollback Target	Identifies a previously accepted Release Artifact Set that can replace the current deployment without reconstructing history.

Canonical relationship

Project
├── Nodes
│   └── Node
│       ├── Source Binding
│       ├── Source Revisions
│       ├── linked Session evidence
│       ├── Submissions and Change Summaries
│       ├── Checks
│       ├── Node Versions
│       ├── Artifacts
│       └── Node Previews
└── Work Sessions
    └── Session Node Scopes and isolated Workspaces
 
Accepted Node Versions
→ Project Release Candidate
→ integrated Checks
→ immutable Release Artifact Set
→ Preview Deployment
→ Approval
→ Production promotion of the same accepted outputs
→ Rollback Target

Canonical Source and editor adapters

Every Node has one canonical, versionable Source model. That Source may contain text files, code, structured graphs, schemas, layout metadata, prompts, assets, or configuration.

The Code editor and specialized no-code editors are different projections of the same canonical Source:

Code edit ───────────────┐
Visual edit ─────────────┤
Workflow canvas edit ────┼→ Canonical Source → Diff → Submission
Schema edit ─────────────┤
Prompt and tool edit ────┘

A specialized editor must not maintain a hidden, database-only copy that cannot be reproduced, diffed, versioned, or audited through the Node's Source Revision.

The round trip must remain true:

Visual operation
→ changes canonical structured Source
→ produces a reviewable Diff
 
Direct Source change
→ specialized editor parses the new revision
→ presents the same accepted state

Node Workbench

The current Code Editor direction should evolve into a general Node Workbench.

The common shell belongs to every Node:

Node identity, capability, current version, status, and dependencies
Source, files, Diff, repository, branch, and revision
Agent and Session connection channels
Submissions, change summaries, conflicts, and approvals
Checks, Artifacts, Preview, deployments, logs, and audit history

The primary editor changes by capability:

Capability	Primary editor or view	Typical output
Code or service	Code editor	Worker, service image, function, binary, or package
Website or page	Visual editor with Code view	Web bundle or site Artifact
Component or UI library	Component editor with Code view	Versioned package and optional catalog
Workflow	Workflow canvas with Code view	Executable workflow definition
Data or schema	Schema editor with Source view	Versioned schema or migration set
Document	Document editor with Source view	Document, content package, or site
Agent	Prompt, tool, and policy editor	Versioned Agent definition

These are capabilities and adapters, not separate release systems.

External Agent Session connection

Topoo does not need to own the conversation interface used by every Agent. Codex, Claude, VS Code, and other execution clients may create Sessions outside Topoo while Topoo remains the authority for Project identity, Work Session identity, Node scopes, isolated Workspaces, Source, Submissions, and releases.

The target user outcome is:

After Topoo, the execution client, and Topoo Local Runtime are connected once, the user starts a new Session by stating the task. The user does not repeat the Project, Nodes, repository, Agent prompt, Checks, or deployment policy in every conversation.

For example:

Implement stale-base detection for Agent Submissions.
Do not change the existing Dashboard layout.
Create a Preview when the required Checks pass.

The client resolves the rest from Topoo:

Task
→ identify the connected repository and working directory
→ resolve the Topoo Project
→ create the Project-scoped Work Session
→ resolve or confirm one or more responsible Nodes
→ load the Agent identity and Context Packs
→ issue a scoped Session Grant
→ lock Base Revisions
→ lazily create an isolated Session Workspace through Local Runtime
→ produce Checkpoints, Node Submissions, Checks, and Preview

If one task unambiguously maps to one Node, this resolution is automatic. If the task crosses Nodes, Topoo records several Session Node Scopes. It asks the user only when that expansion requires new authority or the boundary is ambiguous. This is scope confirmation, not a request to restate Project context.

Persistent context and automatic resolution

Topoo persists long-lived context under Project, Node, and Agent objects:

Project identity, environments, resources, current release, and Production policy
Node responsibility, Source Bindings, root paths, dependency scope, and current version
Agent identity, prompt, permissions, tools, and operating procedure
build contracts, required Checks, Artifact contracts, and Preview policy
Submission, audit, retention, and rollback policy

A repository may also carry a non-secret topoo.app.json manifest that identifies its Project binding, Node roots, build contracts, Artifact contracts, and context-discovery address. Git remote identity, current working directory, and this manifest allow an installed Topoo client to resolve the active context without storing credentials in the repository.

The Context Pack returned to an authorized Session contains the minimum structured context required for the task:

Session Context Pack
├── Project and Work Session identity
├── authorized Node identities and Base Revisions
├── responsibility and acceptance framing
├── Agent identity, prompt, permissions, and SOP
├── Source Bindings and Base Revision
├── allowed files, resources, and dependency versions
├── build commands and required Checks
├── Submission and Preview policy
└── current Project Release references

The complete conversation history is not the context contract. A new Session can start with a clean conversational context while reusing the durable Node and Agent identity.

Two entry paths

Topoo should support both directions:

Topoo Project
→ Node
→ Open in Codex or another client
→ start an externally hosted Session already bound to Project, initial Node scope, and Agent

Codex or another client
→ open a connected repository
→ Topoo plugin resolves Git remote, working directory, and topoo.app.json
→ create a Work Session under the matching Project
→ Local Runtime allocates a separate Workspace on first write

The Open in action launches or hands off to the external client. It does not move the chat interface into Topoo and does not make Topoo the owner of the external conversation.

Execution-client adapter and Local Runtime

The distributable Codex integration should be a Topoo Cloud plugin rather than only a prompt template. Its target package may contain:

a Topoo Cloud App backed by a remote Topoo MCP server
OAuth connection and workspace authorization
Project, Node, Source, Submission, Preview, Release, and rollback tools
reusable Skills that teach the Topoo operating procedure
an App Template for enterprise or private Topoo endpoints

Installation and account connection happen once. A workspace may make the plugin available or preinstall it for eligible roles. New Sessions then use the existing account connection and request a new scoped Session Grant.

The plugin is an external entry to the same Topoo control plane. It is not the component that guarantees local filesystem isolation.

Topoo Local Runtime is a separate machine-level service or supervised CLI that:

registers the local machine and available repositories
creates a Git worktree or copy-on-write Session Workspace
launches or binds the Agent process to the exact Workspace cwd
runs authorized commands inside that Workspace
reports heartbeats, Checkpoints, and source state
recovers, freezes, and safely cleans up Session Workspaces

The complete path is:

Codex ──┐
Claude ─┼→ adapter → Topoo MCP and API → Project Work Session
VS Code ┘                                  │
                                          ├→ Node scopes and Session Grant
                                          ├→ Topoo Local Runtime → isolated Workspace
                                          └→ Node Submissions → Integration Controller

Authorization layers

Account connection, Session authority, and Production authority are different grants:

Layer	Purpose	Expected lifetime
Account connection	Connect an execution client to the user's Topoo account through browser authorization.	Persistent until revoked.
Session Grant	Bind one client Session to a Workspace, Project, Agent identity, Node scopes, Base Revisions, local Workspace lease, and allowed actions.	Short-lived and revocable.
Production Approval	Authorize promotion of one exact accepted Release Artifact Set.	Single action.

The primary remote connection should use browser-based OAuth authorization. A one-time device or claim code is a fallback for clients that cannot complete a normal browser redirect, not the default prompt interface. Long-lived API keys must not be pasted into conversations, URLs, manifests, or Change Summaries.

A normal Agent Session may read its Context Pack, create Checkpoints and Submissions, run Checks, and request Preview under policy. It does not inherit Production authority merely because the account connection is valid.

Provider execution skills

A provider-specific capability such as Cloudflare deployment is an upstream execution tool, not the Topoo product model.

Topoo Cloud adapter and control plane
→ resolve Project, Work Session, Node scopes, Submissions, Release Candidate, approval, and audit
→ Topoo Release Controller
→ invokes Cloudflare or another provider adapter
→ records the resulting Artifact, Deployment, and operating evidence

Topoo Cloud may use a Cloudflare deployment Skill internally while operating its own first Project. Customers should not need to install or understand that provider Skill when Topoo owns the upstream account, policy, and runtime relationship.

Common lifecycle

All editor modes feed the same lifecycle:

Edit
→ Diff
→ Submission
→ Review and conflict detection
→ accepted Node Version
→ Checks
→ optional immutable Artifact
→ Node Preview
→ Project Release Candidate
→ integrated Preview
→ Approval
→ Production

Suggested lifecycle states are:

State	Meaning
Editing	A Session is changing isolated working state.
Submitted	A bounded change is proposed against a pinned Base Revision.
Reviewing	Checks, Diff review, conflict detection, and approval are in progress.
Accepted	The Submission is permitted to contribute to a Node Version.
Versioned	An immutable Node Version has been published.
Built	Required immutable Artifacts have been produced and bound to the Node Version.
Preview	The accepted version or Artifact is available for isolated evaluation.
Included	The Node Version is pinned by a Project Release Candidate.
Released	The Project Release containing that Node Version has reached an Environment.
Superseded	A later accepted Node Version or Project Release replaced it.
Rolled back	Deployment returned to a previously accepted Project Release.

Rejected and cancelled Submissions remain in the audit history but do not produce an accepted Node Version.

Node authority and Project authority

Node Workbench may let a user:

edit Source
inspect Diff
create or review a Submission
run Node-level Checks
publish an immutable Node Version
build an Artifact
open a Node Preview

It must not let a Node, Agent, or Session silently replace Project Production.

Project Deployment owns:

selecting accepted Node Versions
dependency and compatibility resolution
integrated Checks
the Release Artifact Set
Environment policy
approval and Production promotion
Project rollback

For a single-Node Project, Topoo may automatically create a Project Release Candidate containing that one Node Version. The interaction can feel like direct publishing while the underlying authority model remains unchanged.

Product invariants

Every editor changes the same canonical, versionable Source model.
Specialized no-code editors are Source adapters, not separate data silos.
A writing Session receives isolated working state; it does not define long-lived responsibility.
A Submission is proposed work and never carries implicit Production authority.
A Node Version is immutable and pins its accepted evidence.
An Artifact is derived from an exact Node Version and build contract.
A Project Release Candidate pins exact Node Versions, including unchanged versions.
Preview and Production promotion use the same accepted Release Artifact Set.
A Node version becoming available does not silently update a Project.
An installed execution-client plugin does not grant implicit Production authority.
Long-lived credentials are never transmitted through a task prompt or repository manifest.
Current UI or database evidence must not be described as a completed lifecycle until the full behavior is verified.

Current implementation boundary

The current Topoo Cloud Node surfaces provide Node browsing, creation, classification, source metadata, repository content, specialized editor entry points, embedded Node Settings, Preview history, and an immutable Node Project Preview.

A ready Preview persists its Base Release and Artifact identity. Approving it creates a persistent Project-scoped Submission, and the Node Workbench can hand the user to the exact Submission in Project Deployments.

This is the first real lifecycle segment. It does not yet provide managed external Session isolation, automatic Drafts and Checkpoints, enforced Agent identity, Base Revision validation, Diff and affected-scope evidence, stale-base and conflict detection, or automatic integration.

The complete Topoo Cloud adapter, Topoo Local Runtime, automatic Project and Node-scope resolution, OAuth-backed MCP access, Session Grant, isolated Session Workspace, immutable Node Version ledger, common Workbench lifecycle panels, Project Release Candidate composition, Release Artifact Set, policy-driven promotion, and unified rollback chain remain target capabilities until independently implemented and accepted.

Work Sessions and Local Runtime Deployment Configuration and Interaction

Topoo documentation system

This board structure now separates desktop docs, work surfaces, and TopooUI references.

Use the top navigation to move between Topoo, toAgent, toWork, toProject, toMemory, and TopooUI.

Open TopooUI