73 lines
3.6 KiB
Markdown
73 lines
3.6 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 v3 is the only accepted workspace descriptor. Schema v1 and v2 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 -->
|
|
|
|
## 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-v3 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.
|