83 lines
4.3 KiB
Markdown
83 lines
4.3 KiB
Markdown
# 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 Evidence runtime secrets, configure its
|
|
database in **Database Management**, then run **Validate workspace source** and **Test workspace
|
|
connections**. The workspace connection test uses that same current database configuration for
|
|
DWH connectivity and also checks the workspace Evidence and installation semantic services.
|
|
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 and **Test
|
|
workspace connections** share the current database binding, including its strict known-host SSH
|
|
path; the remaining workspace diagnostics cover Evidence and installation semantic services.
|
|
|
|
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.
|