ThothII/docs/operations/workspaces.md

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

The root catalog has schema_version: 1 and an ordered list of workspace identities.

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.

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.

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.

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:

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. For Evidence source forms and the schema-v4 descriptor contract, see Workspace Evidence v3.

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.