design(workspace): share environments while keeping process state local

[bwl21]

Context

A ct workspace may contain multiple independently managed processes. A process is identified by its root ct.config.ts. Today, each process also carries its own ct.envs.json, which defines the ChurchTools instances on which that process runs.

This is simple and keeps a process self-contained, but it duplicates host, protection, credential-reference and host-wide metadata when several processes target the same ChurchTools instances. It also leaves the relationship between a workspace-wide environment and process-specific state implicit.

This issue is a design discussion only. It does not request an immediate implementation, migration, or change to the current branches.

Candidate domain model

Model the workspace as containing shared environment identities and portable processes:

Workspace
├── Environments
└── Processes
    └── environment-specific process state

• A workspace is the local coordination scope.
• A process is one portable lifecycle boundary rooted at ct.config.ts.
• An environment identifies a ChurchTools target instance, including its host and protection policy.
• A process explicitly selects the subset of workspace environments it targets.
• State is process-specific and environment-qualified. It belongs in the process directory rather than in a central environment-owned installations/ tree.

The process/environment relationship does not need to become a new first-class object named "installation" in the filesystem or user-facing terminology. Prefer language such as "process state for environment prod" unless implementation requirements demonstrate that a separate installation entity is necessary.

For example, ojbp may target test and prod, while another process targets only prod.

Data ownership and proposed layout direction

Workspace-environment data is shared by every process targeting that ChurchTools host:

• host URL;
• protection policy;
• credential/token reference, never the credential itself;
• host-wide permission catalog and similar host metadata.

Process-specific data remains below the process:

• desired configuration and blueprints;
• state;
• reports;
• backups;
• captured process-specific reference material.

Illustrative only:

workspace/
├── ct.envs.json
├── environments/
│   ├── prod/
│   │   └── permission-catalog.json
│   └── test/
│       └── permission-catalog.json
└── processes/
    └── ojbp/
        ├── ct.config.ts
        ├── blueprint/
        ├── state/
        │   ├── prod/
        │   └── test/
        ├── reports/
        │   ├── prod/
        │   └── test/
        └── backups/
            ├── prod/
            └── test/

This layout is not yet a schema decision. It records the ownership boundary: shared host data belongs to the workspace environment; process lifecycle data stays with the process.

Why consider workspace-wide environments

• One environment name has one unambiguous ChurchTools host throughout the workspace.
• Host, protection and token-reference configuration is not repeated by every process.
• A host-wide permission catalog is captured once rather than copied into each process.
• Cross-process ownership checks can compare process states on the same host reliably.
• REST and UI clients can expose either Workspace → Process → Environment or Workspace → Environment → Process as projections of the same model.
• Keeping state below the process preserves its lifecycle boundary and avoids turning the environment into an owner of process-specific artifacts.

Important trade-off

Process-local ct.envs.json currently makes a process independently executable and portable. Moving shared environment definitions to a workspace manifest could make a process unusable outside its original workspace unless standalone behavior, inheritance, export or an explicit override is defined deliberately.

Alternatives

1. Keep process-local environments

Each process continues to own ct.envs.json. This preserves current standalone behavior but accepts duplicated target configuration and requires ownership analysis to reconcile independently declared hosts.

2. Move environments and all associated data to the workspace

A workspace environment owns both shared host metadata and every process's state, reports and backups. This centralizes the environment-first projection but breaks the process ownership boundary and is not the preferred direction.

3. Workspace environment catalog with process-local environment bindings

The workspace owns shared environment definitions and host-wide metadata. Each process selects its target environments and retains its environment-qualified state, reports and backups locally. A defined compatibility mechanism preserves standalone process use.

This is the preferred direction for discussion, not yet an implementation decision.

Relationship to existing issues

• feat(env): add environments to existing workspaces #153 (ct env add) depends on where the environment catalog ultimately lives and which scope owns mutations to it.
• feat(server): versioned REST API for ChurchTools Extension clients #164 (versioned REST API) may project both process-first and environment-first navigation over the same underlying model.
• feat: support read-only external references across ct projects #143 (external references and ownership) benefits from workspace-wide environment identities when comparing owner and consumer processes on the same ChurchTools host.
• fix(state): snapshot dynamic rulesets for three-way drift detection #167 concerns the missing persisted baseline for dynamic rulesets inside process state.
• design(state): store installation state as one JSON file per resource type #168 discusses a directory-backed process state with one JSON file per canonical resource type.

Decisions required

This design issue is complete when we have agreed on:

• ownership, filename and schema of the workspace environment catalog;
• how a process selects the workspace environments it targets;
• which metadata is host-wide and which remains process-specific;
• the location and stable identity of process state for one environment;
• whether any first-class installation object is necessary, rather than assumed;
• behavior when a process is copied or run outside its original workspace;
• compatibility and migration for existing process-local ct.envs.json files and .ct/permission-catalog.<host>.json captures;
• effects on CLI commands, REST/OpenAPI routes, the ChurchTools Extension and ownership analysis.

Non-goals

• changing the current implementation as part of this issue;
• silently moving or rewriting existing environment, catalog or state files;
• moving process-specific state, reports or backups into a central environment tree;
• coupling acceptance of feat: support read-only external references across ct projects #143, feat(env): add environments to existing workspaces #153, feat(server): versioned REST API for ChurchTools Extension clients #164, fix(state): snapshot dynamic rulesets for three-way drift detection #167 or design(state): store installation state as one JSON file per resource type #168 to an unresolved migration;
• selecting a concrete manifest schema before the model and compatibility behavior are agreed.

Sequencing: consolidate repository tools only after #166 and #168

Consumer repositories may currently carry local helpers for repository validation and plan-report rendering. Do not migrate or remove those tools while the environment owner and state layout are still unresolved: a validator implemented against the interim layout would immediately encode assumptions that #166 and #168 are intended to decide.

After both #166 and #168 have been implemented:

• provide canonical ct-cli validation for the resulting workspace, environment and process-state layout;
• define validation as an application operation and project it consistently through CLI and REST/OpenAPI rather than maintaining a repository-specific script;
• include detection of unregistered fallback states, invalid host/state associations, misplaced generated output and inconsistent environment metadata;
• update ct init and the authoritative documentation to generate and validate the chosen structure;
• only then remove or replace corresponding local tools and duplicated documentation in consumer process repositories;
• remove legacy local plan renderers only as part of the same cleanup, using ct-cli's canonical Markdown plan projection.

Until then, existing repository tools remain compatibility tooling for the current on-disk model. No transitional directory migration should be introduced merely to modernize those scripts.

[bwl21]

Proposal: make process export/import a first-class consequence of the model

Workspace-wide environments should not make a process depend on the source workspace. The model can preserve external portability by separating two meanings that are currently both expressed by an environment name such as prod:

1. a portable process target slot (test, prod), describing the role the process expects; and
2. a concrete workspace environment, carrying the ChurchTools host, protection policy, credential reference and host-wide metadata.

The process keeps the target slots. A workspace-local binding maps each slot to a concrete environment:

source workspace:
  ojbp.prod -> bgk-prod -> https://bgkorntal.church.tools

target workspace:
  ojbp.prod -> new-church-prod -> https://new-church.church.tools

The name prod therefore remains meaningful inside the portable process, while the host and credentials are supplied by the workspace in which it is installed.

Export/import workflow

This separation should support an explicit workflow along these lines:

ct process export ojbp --output ojbp.ct-process
ct process import ojbp.ct-process
ct process bind ojbp prod --environment new-church-prod

If the concrete target does not exist yet, #153 provides the preceding step:

ct env add new-church-prod \
  --host https://new-church.church.tools \
  --protected
ct process bind ojbp prod --environment new-church-prod
ct auth login --environment new-church-prod

The exact command names and archive format remain design questions. The important contract is that importing a process does not silently inherit the source workspace targets.

Portable package boundary

A normal portable process export should include:

• desired config and blueprints;
• portable rulesets and other portable process reference material;
• process metadata;
• the declared target slots and their requirements;
• logical requirements for external prerequisites where they can be represented without host-local IDs.

It should not include active deployment data:

• credentials, tokens or source-workspace tokenEnv names;
• concrete host bindings;
• host-wide permission catalogs;
• active host-bound process state;
• backups and reports;
• numeric external bindings or other ChurchTools IDs.

A --portable validation step should refuse, or at least explicitly report, rulesets with remaining host-specific numeric IDs, absolute local paths and other source-instance coupling. This composes with #143: an imported process may declare that an external prerequisite is required, but its numeric binding must be discovered and explicitly persisted on the target host rather than copied from the source.

State semantics

Importing onto a different ChurchTools instance must create a fresh process-local, host-bound state. Rebinding prod must never activate the old host state under the new host. The existing host check remains the final safety guard, while #168 should give the new binding its own process-local state directory.

Two operations should be deliberately distinct:

• new target / portable import: do not import active state; bind the slots, create fresh host-bound state, then use ct plan to show creates and missing external bindings;
• same target relocation: state may be transferred only through an explicit option and only when the normalized host identity matches exactly.

Copying historical reports or backups can be an archival option, but must not make them active state.

Compatibility and discovery

Existing process-local ct.envs.json can remain a standalone/legacy combined catalog and binding. For the new model, environment-source discovery should be deterministic and must not silently merge competing files. A reasonable precedence is an explicit workspace/environment-catalog selection, then the nearest workspace manifest, then the legacy process-local file. If both new and legacy declarations are applicable and no source is explicit, fail with an actionable ambiguity error.

A copied process whose target slots are not yet bound should remain inspectable but must fail before any host or state access with guidance such as:

Process target "prod" is not bound in this workspace.
Bind it with: ct process bind ojbp prod --environment <workspace-environment>

This makes central environments compatible with both repository-local coordination and genuine transfer of a process to an unrelated ChurchTools installation with entirely different credentials.