149 lines
6.9 KiB
Markdown
149 lines
6.9 KiB
Markdown
# P2–P6 Manual Verification Walkthrough
|
||
|
||
> Living document. Each section is completed with exact released commands and artifacts during its
|
||
> corresponding plan. Automated integration and manual acceptance use separate clean state.
|
||
|
||
## Global rules
|
||
|
||
- Use a new temporary operator root and a new private fixture Git remote for each Px.
|
||
- Never use production PSD credentials in a retained report or screenshot.
|
||
- Keep descriptor/content in Git; keep endpoints, bindings, credentials, and certificates in the
|
||
installation-local protected directory.
|
||
- Do not print secret files, rendered signed URLs, Compose environments, or unbounded logs.
|
||
- Record the ThothII commit, workspace commit, installation descriptor path, Compose project name,
|
||
command exit status, and report path.
|
||
- A focused manual PASS does not replace the automated process goal.
|
||
|
||
## P2 — Host preprocessing CLI
|
||
|
||
**Status:** P2 implementation complete; automated integration PASS; manual acceptance PENDING.
|
||
|
||
Manual goal: from a clean local installation, use only `thothctl` on the host to inspect one
|
||
registry workspace and execute the controlled REST-DWH/HTTP-Evidence preprocessing path without a
|
||
host Python or Node runtime. Use a fresh operator root and a fresh fixture Git remote; never reuse
|
||
the automated `.artifacts/p2-integration/**` state.
|
||
|
||
Commands (contract: `docs/contracts/workspace-preprocessing-cli.md`):
|
||
|
||
```bash
|
||
thothctl --installation <abs>/thothii-installation.yaml workspace inspect --workspace <id> --json
|
||
thothctl --installation <abs>/thothii-installation.yaml workspace preprocess dwh --workspace <id> --json
|
||
thothctl --installation <abs>/thothii-installation.yaml workspace preprocess dwh --workspace <id> --resume <run-id> --json
|
||
thothctl --installation <abs>/thothii-installation.yaml workspace schema suggest-fks --workspace <id> --from-sql <file>.sql --output <candidates>.yaml --json
|
||
thothctl --installation <abs>/thothii-installation.yaml workspace schema check --workspace <id> --annotations <reviewed>.yaml --reviewed-candidates <sha256:hex> --json
|
||
thothctl --installation <abs>/thothii-installation.yaml workspace index-schema --workspace <id> --json
|
||
thothctl --installation <abs>/thothii-installation.yaml workspace preprocess evidence --workspace <id> --dry-run --json
|
||
thothctl --installation <abs>/thothii-installation.yaml workspace preprocess evidence --workspace <id> --json
|
||
thothctl --installation <abs>/thothii-installation.yaml workspace preprocess run --workspace <id> --json
|
||
```
|
||
|
||
Checks:
|
||
|
||
1. installation/render preflight (`inspect` returns exact revision + catalog/descriptor digests);
|
||
2. DWH introspection+LSH succeeds, rerun is `unchanged`, `--resume <run-id>` is `unchanged`/`succeeded`;
|
||
3. `schema suggest-fks` returns pristine JSON with `suggestedFksYaml` and a `manual_review_required`
|
||
block (exit 3) when candidates exist; the suggested YAML digest equals the reported digest;
|
||
4. `schema check --annotations <reviewed> --reviewed-candidates <digest>` succeeds after review;
|
||
5. `index-schema` counts against a pre-provisioned compatible collection and rerun is `unchanged`;
|
||
6. HTTP Evidence `--dry-run` returns `dry_run`, the real run publishes, rerun is `unchanged`, an input
|
||
mutation produces a new generation/ACTIVE;
|
||
7. filesystem Evidence returns a stable `evidence_materialization_required` block with no partial
|
||
corpus/vector publication;
|
||
8. negatives: missing workspace (`workspace_not_activatable`), resume of a nonexistent run
|
||
(`preprocessing_resume_mismatch`), invalid annotations digest (`annotation_invalid`), no-Evidence
|
||
skip warning, no collection creation, no backend/Pi/frontend listener;
|
||
9. secret scan over retained artifacts and exact owned-resource cleanup.
|
||
|
||
Decision: **PENDING** (independent manual gate; automation never records PASS).
|
||
|
||
## P3 — Effective config and `.tht-dwh`
|
||
|
||
**Status:** instructions to be finalized by P3 implementation; not yet runnable.
|
||
|
||
Manual goal: compare operator and session effective DWH identities, inspect `OWNER.json` and
|
||
`ACTIVE` without exposing secrets, prove safe reuse after a content-only revision, and prove
|
||
fail-closed behavior after a DWH-affecting change.
|
||
|
||
Checks to fill during P3:
|
||
|
||
1. canonical fingerprint comparison;
|
||
2. stable logical config-source identity;
|
||
3. schema-v1 ownership compatibility/migration;
|
||
4. DWH cache reuse across equivalent revisions;
|
||
5. revision-scoped schema/Evidence state;
|
||
6. mismatch rejection and recovery.
|
||
|
||
Decision: **PENDING**.
|
||
|
||
## P4 — Qdrant bootstrap and guarded rebuild
|
||
|
||
**Status:** instructions to be finalized by P4 implementation; not yet runnable.
|
||
|
||
Manual goal: prove admission creates a missing compatible collection and indexes, refuses an
|
||
incompatible collection, and permits destructive rebuild only under durable maintenance with no
|
||
active readers/jobs and exact repeated confirmation.
|
||
|
||
Checks to fill during P4:
|
||
|
||
1. missing-collection self-heal;
|
||
2. missing-index self-heal;
|
||
3. dimensions/distance/index-type refusal;
|
||
4. confirmation mismatch refusal;
|
||
5. active-reader/job refusal;
|
||
6. successful drained rebuild;
|
||
7. interrupted rebuild recovery with maintenance retained.
|
||
|
||
Decision: **PENDING**.
|
||
|
||
## P5 — Curated FK annotations in Git
|
||
|
||
**Status:** instructions to be finalized by P5 implementation; not yet runnable.
|
||
|
||
Manual goal: curate `<id>/schema/annotations.yaml` in an author clone, publish it,
|
||
pull the new revision, explicitly accept the reviewed blob, and prove atomic revision-correct sync
|
||
without changing `physical.yaml` in Git.
|
||
|
||
Checks to fill during P5:
|
||
|
||
1. candidate/export review;
|
||
2. Git commit and exact blob identity;
|
||
3. pull and controlled revision transition;
|
||
4. explicit acceptance record;
|
||
5. synchronized destination and ownership manifest;
|
||
6. malformed/oversized/symlink/cross-namespace refusal;
|
||
7. pinned historical revision isolation.
|
||
|
||
Decision: **PENDING**.
|
||
|
||
## P6 — Commit-addressed Evidence materialization
|
||
|
||
**Status:** instructions to be finalized by P6 implementation; not yet runnable.
|
||
|
||
Manual goal: materialize filesystem Evidence from the pinned Git commit, inspect its bounded
|
||
manifest, preprocess/index it, retrieve only the pinned revision, and exercise unsafe-tree and
|
||
aggregate-limit failures without partial publication.
|
||
|
||
Checks to fill during P6:
|
||
|
||
1. exact commit/tree/object identities;
|
||
2. successful atomic materialization;
|
||
3. manifest and file digest verification;
|
||
4. filesystem Evidence dry-run/run/idempotency;
|
||
5. revision-filtered Qdrant retrieval and corpus ACTIVE;
|
||
6. nested symlink/gitlink/traversal/special-file refusal;
|
||
7. file-count/total-byte/path/manifest limit refusal;
|
||
8. retention while pinned and owned cleanup after release.
|
||
|
||
Decision: **PENDING**.
|
||
|
||
## Final aggregate P2–P6 verification
|
||
|
||
**Status:** runnable only after P6.
|
||
|
||
The final manual pass will start with a new registry and two independent installations. It will
|
||
run the complete DWH → FK → schema → filesystem Evidence chain, prove idempotency and revision
|
||
isolation, confirm the second installation uses its own secrets/state, and compare its observations
|
||
to the retained aggregate automated report.
|
||
|
||
Decision: **PENDING**.
|