2.8 KiB
Workspace preprocessing CLI contract
thothctl workspace is a closed native host interface. Only the seven paths below are representable; there is no passthrough, shell, arbitrary child argv, or host-selected bootstrap run ID.
workspace inspect --workspace ID [--json]
workspace preprocess dwh --workspace ID [--resume RUN] [--json]
workspace schema suggest-fks --workspace ID [--from-sql FILE]... [--assume COLUMN=TABLE]... [--output FILE] [--json]
workspace schema check --workspace ID --resume RUN [--annotations FILE --reviewed-candidates sha256:HEX] [--json]
workspace index-schema --workspace ID [--json]
workspace preprocess evidence --workspace ID [--dry-run] [--resume RUN] [--json]
workspace preprocess run --workspace ID [--resume RUN] [--json]
IDs are lowercase [a-z][a-z0-9-]{2,62} and outer run IDs are exactly 32 lowercase hexadecimal characters. --from-sql accepts at most 32 canonical regular non-symlink files, each at most 1 MiB and 16 MiB total. --assume accepts at most 256 values of 256 bytes, each matching column=table. Annotations are one canonical UTF-8 file at most 16 MiB. Existing output, links, hardlinks, directories, replacement races, and reparse points are refused with a generic unsafe-file error.
The bounded schema-v1 stdin request contains only operation-appropriate fields. SQL and annotations are represented by a logical basename, base64 bytes, and a declared sha256:<hex> digest; no host path or raw content enters the request. The complete request is at most 1 MiB, has exactly one JSON value, and cannot replace command-derived fields. Candidate responses may carry the internal hostExport (mediaType, sha256, contentBase64) only for suggest-fks; it is verified (UTF-8 YAML, digest, and 700 KiB maximum), removed from the public result, and written exclusively only after result/run/identity validation.
The public result has schema version 1 and only these fields: status, code, workspace/revision/descriptor/operation identities, optional run and child run IDs, completed stages, counts, artifact identities, and warnings. Revisions/descriptors are 40-hex; run IDs are 32-hex; artifact digests are sha256:<hex>. A nonzero child exit is accepted only for the matching blocked (3) or failed (1) result. Stdout is capped at 1 MiB and stderr at 64 KiB. Compose is invoked only as compose run --rm --no-deps --no-TTY workspace-maintenance ...; output never includes child stderr or secrets.
Exit 0 means succeeded, unchanged, or dry-run; exit 3 means an expected operator checkpoint/block; exit 2 means grammar or unsafe local-file failure; exit 1 means operational failure. Human mode prints only allowlisted identity/status fields. For registry_bootstrap_recovery_conflict it prints exactly: Bootstrap recovery is ambiguous or corrupt; inspect the installation registry jobs.