90 lines
5.4 KiB
Markdown
90 lines
5.4 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`, and Evidence | database metadata, 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. A v4 descriptor contains only workspace identity and optional Evidence configuration; it
|
|
does not contain a database or database metadata.
|
|
<!-- workspace-descriptor-contract:end -->
|
|
|
|
<!-- non-workspace-migration:start -->
|
|
Create a clean v4 descriptor with `workspace` and optional `evidence`. Do not import the old DWH,
|
|
diagnostics, annotation, `llm_policy`, or `semantic_index` blocks. Configure the database in
|
|
Database Management. 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. Expand **Administration** in the right sidebar and run **Preprocessing**. The button is available
|
|
when all prerequisites are satisfied: it shows **Run** when preprocessing is required,
|
|
**Run again** when the workspace is already current, and **Retry** after a failure. The same
|
|
operation is available from the host CLI for unattended administration. **Clear**, immediately
|
|
to the left, removes only replaceable Schema/Evidence vectors, LSH, corpus, and checkpoints after
|
|
an inline confirmation; it preserves Memory and solved questions. `--json` keeps CLI 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 run --workspace "$WORKSPACE" --json
|
|
tht --installation "$INSTALLATION" workspace preprocess clear --workspace "$WORKSPACE" --json
|
|
```
|
|
|
|
The command snapshots tables, columns, descriptions, sensitivity, and active relationships from
|
|
PostgreSQL, samples eligible DWH values for LSH, and replaces the schema/Evidence vector slices.
|
|
It is rerunnable but not resumable and has no rollback. Catalog sync and description generation
|
|
remain separate operations and must already be complete.
|
|
|
|
After clear, the sidebar reports **Required** and the core rejects new sessions until a complete run
|
|
succeeds. Clear can be repeated safely: an already absent reference collection or derived path is a
|
|
no-op, and the separate Memory collection is never a cleanup target.
|
|
|
|
The sidebar retains no run history. If the current prerequisite blocks a start, it explains what
|
|
must be completed and correctly reports that there is no run log. If the last run failed, it shows
|
|
only that run's safe stage, error code, and finish time; use `docker compose logs core` for the
|
|
corresponding service log.
|
|
|
|
The contract gives exact validation, exit code, and JSON rules in
|
|
[Workspace preprocessing CLI](https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/docs/contracts/workspace-preprocessing-cli.md). For Evidence source
|
|
forms and the schema-v4 descriptor contract, see
|
|
[Workspace Evidence v3](https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/docs/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.
|