# Workspace operations

A workspace is curator-owned Git content plus installation-local runtime bindings. It is the
boundary between what can be published and what can be used by an installation.

## Roles and ownership

| Role | Owns | Does not own |
| --- | --- | --- |
| Curator | `thoth-workspaces.yaml`, `<id>/workspace.yaml`, Evidence, and curated schema annotations | installation secrets or active runtime bindings |
| Installation operator | Git source, selected workspace, write-only runtime secrets, validation, connectivity, and preprocessing | commits or pushes to the workspace repository |
| Reviewer | NL→SQL decisions in a pinned session | workspace publication or preprocessing |

<!-- non-workspace-migration:start -->
The root catalog has `schema_version: 1` and an ordered list of workspace identities.
<!-- non-workspace-migration:end -->

<!-- workspace-descriptor-contract:start -->
Schema v4 is the only accepted workspace descriptor. Schema v1, v2, and v3 workspace descriptors
are rejected before activation. Each catalog entry must have a matching descriptor at
`<id>/workspace.yaml` in the same Git commit. The application validates a complete candidate
revision and activates it atomically; invalid content leaves the preceding active revision in
place.
<!-- workspace-descriptor-contract:end -->

<!-- non-workspace-migration:start -->
To convert a v3 descriptor before committing it, set `workspace.schema_version` to `4`, remove
`llm_policy`, and remove `semantic_index`. Database, Evidence, diagnostics, and binding data remain
unchanged. Validate the resulting v4 repository revision before activation; ThothII never rewrites
the curator-owned repository during pull.
<!-- non-workspace-migration:end -->

## Operator sequence

1. Curate and push a complete repository revision. Do not put DWH passwords, API keys, private
   keys, or signed URLs in this repository.
2. In the application, update the workspace repository. This fetches and validates the candidate;
   it never edits the remote repository.
3. Select the workspace. Supply or replace its write-only runtime secrets, then run **Validate
   workspace source** and **Test workspace connections**.
4. Select it as the installation workspace before creating sessions.
5. Use the host CLI for preprocessing. It dispatches a profile-gated maintenance service and
   returns a single structured result; `--json` keeps stdout machine-readable.

```sh
INSTALLATION=/absolute/path/thothii-installation.yaml
WORKSPACE=example-workspace

tht --installation "$INSTALLATION" workspace inspect --workspace "$WORKSPACE" --json
tht --installation "$INSTALLATION" workspace preprocess dwh --workspace "$WORKSPACE" --json
tht --installation "$INSTALLATION" workspace preprocess evidence --workspace "$WORKSPACE" --json
```

For the full DWH → review → schema-index → Evidence chain, run
`workspace preprocess run`. It may stop with `manual_review_required` when FK candidates need a
curator decision. Publish the reviewed annotations, update the repository, then accept that exact
run and resume it:

```sh
tht --installation "$INSTALLATION" workspace schema accept \
  --workspace "$WORKSPACE" --run <run-id> --yes --json
tht --installation "$INSTALLATION" workspace preprocess run \
  --workspace "$WORKSPACE" --resume <run-id> --json
```

The contract gives exact validation, exit code, and JSON rules in
[Workspace preprocessing CLI](../contracts/workspace-preprocessing-cli.md). For Evidence source
forms and the schema-v4 descriptor contract, see
[Workspace Evidence v3](../contracts/workspace-evidence-v3.md).

## Transport and revision rules

Runtime sessions support direct PostgreSQL and REST bindings. SSH tunnel bindings are diagnostic
only for this path, so they cannot admit an NL→SQL session. Database Management has its own
strict known-host SSH path for connection tests and schema synchronization.

Every new session pins the active Git revision. Snapshot cleanup retains revisions still
referenced by unarchived sessions. A later pull can prepare a future session but cannot alter a
resume.