mptyl/ThothII
1
0
Fork 0
Code Issues 25 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

test: enforce the P1.1 registry install docs

Browse Source
This commit is contained in:
marcopan
2026-08-11 15:28:12 +02:00
parent c2f33e58d7
commit d9fd902d08
2 changed files with 203 additions and 112 deletions
Download Patch File Download Diff File Expand all files Collapse all files
scripts/test-verify-workspace-install-docs.sh
+90 -81
View File
@@ -401,7 +401,9 @@ expect_evidence_fixture_rejected() {
mkdir -p \
"$fixture_root/deploy/workspaces" \
"$fixture_root/docs/contracts" \
"$fixture_root/docs/install/examples"
"$fixture_root/docs/install/examples" \
"$fixture_root/docs/install" \
"$fixture_root/docs/migrations"
cp "$root/deploy/workspaces/example.yaml" "$fixture_root/deploy/workspaces/example.yaml"
cp "$root/deploy/workspaces/psd.yaml.example" "$fixture_root/deploy/workspaces/psd.yaml.example"
cp "$root/docs/contracts/workspace-evidence-v3.md" \
@@ -410,6 +412,9 @@ expect_evidence_fixture_rejected() {
"$fixture_root/docs/install/local-workspace-registry.md"
cp "$root/docs/install/server-workspace-registry.md" \
"$fixture_root/docs/install/server-workspace-registry.md"
cp "$root/README.md" "$fixture_root/README.md"
cp "$root/docs/migrations/p1-to-p1-1-registry-layout.md" \
"$fixture_root/docs/migrations/p1-to-p1-1-registry-layout.md"
cp "$root/docs/install/examples/workspace-bindings.env.example" \
"$fixture_root/docs/install/examples/workspace-bindings.env.example"
@@ -420,24 +425,45 @@ mutation = sys.argv[2]
original = path.read_text()
changed = original
if mutation == "layout-omitted":
changed = original.replace("│ ├── example/evidence/...\n", "", 1)
changed = original.replace("├── thoth-workspaces.yaml\n", "", 1)
elif mutation == "same-commit-omitted":
changed = original.replace(
"| Revision identity | The descriptor blob and filesystem Evidence root tree are checked at the same 40-hex Git commit. |\n",
"| Revision identity | The catalog blob, descriptor blob, and filesystem Evidence root tree are checked at the same 40-hex Git commit. |\n",
"",
1,
)
elif mutation in {"absolute-filesystem", "cross-workspace"}:
elif mutation == "flat-descriptor-path":
changed = original.replace("<id>/workspace.yaml", "workspaces/<id>.yaml", 1)
elif mutation in {"absolute-filesystem", "cross-workspace", "old-filesystem-layout"}:
document = yaml.safe_load(original)
document["evidence"]["source"]["uri"] = (
"/srv/evidence" if mutation == "absolute-filesystem"
else "workspace-content/example/evidence"
)
document["evidence"]["source"]["uri"] = {
"absolute-filesystem": "/srv/evidence",
"cross-workspace": "other-workspace/evidence",
"old-filesystem-layout": "workspace-content/example/evidence",
}[mutation]
changed = yaml.safe_dump(document, sort_keys=False)
elif mutation == "wrong-docs-directory":
changed = original.replace(
"workspace-docs/\n ├── example/{contract.env.example,README.md}\n └── another/{contract.env.example,README.md}",
"workspaces/<id>.env.example\nworkspaces/<id>.md",
"workspace-docs/<id>/{contract.env.example,README.md}",
"example/README.md and example/contract.env.example",
1,
)
elif mutation == "catalog-authority-omitted":
changed = original.replace(
"authoritative for workspace ID,",
"descriptor metadata may override workspace ID,",
1,
)
elif mutation == "bootstrap-omitted":
changed = original.replace(
"5. The API may create `<id>/workspace.yaml` only when the catalog slot already exists and no Git\n object exists at that path in the exact pulled base commit.\n",
"",
1,
)
elif mutation == "api-updates-existing":
changed = original.replace(
"6. After bootstrap, existing descriptors change only through curator Git commit/push and\n installation pull. The API never writes `thoth-workspaces.yaml` or `<id>/evidence/**`.\n",
"6. After bootstrap, use the API to update or delete existing descriptors directly from ThothII.\n",
1,
)
elif mutation == "public-http-mode-omitted":
@@ -494,8 +520,8 @@ elif mutation == "unsafe-placeholder":
)
elif mutation == "p1-scope-inversion":
changed = original.replace(
"P1 performs no acquisition, extraction, preprocessing/indexing, embeddings, Qdrant writes, `ACTIVE` publication, retention, or GC.",
"P1 materializes, extracts, and indexes Evidence before publication.",
"P1.1 performs no acquisition, extraction, preprocessing/indexing, embeddings, Qdrant writes,\n`ACTIVE` publication, retention, or GC.",
"P1.1 materializes, extracts, and indexes Evidence before publication.",
1,
)
elif mutation.startswith("p1-append-"):
@@ -529,16 +555,16 @@ elif mutation.startswith("p1-append-"):
raise SystemExit(f"unknown P1 append mutation: {mutation}")
base, third_person, ownership = operations[operation]
claims = {
"base": f"P1 does {base}.",
"third-person": f"P1 {third_person}.",
"can": f"P1 can {base}.",
"may": f"P1 may {base}.",
"must": f"P1 must {base}.",
"will": f"P1 will {base}.",
"should": f"P1 should {base}.",
"adverb-before-modal": f"P1 directly may {base}.",
"adverb-after-modal": f"P1 may directly {base}.",
"ownership": f"P1 owns {ownership}.",
"base": f"P1.1 does {base}.",
"third-person": f"P1.1 {third_person}.",
"can": f"P1.1 can {base}.",
"may": f"P1.1 may {base}.",
"must": f"P1.1 must {base}.",
"will": f"P1.1 will {base}.",
"should": f"P1.1 should {base}.",
"adverb-before-modal": f"P1.1 directly may {base}.",
"adverb-after-modal": f"P1.1 may directly {base}.",
"ownership": f"P1.1 owns {ownership}.",
}
changed = original + f"\n{claims[form]}\n"
elif mutation == "config-ordering":
@@ -548,9 +574,15 @@ elif mutation == "config-ordering":
elif mutation == "acceptance-conflation":
changed = original.replace("manual acceptance: PENDING\n", "", 1)
elif mutation == "curator-order":
second = "2. Add source bytes below `workspace-content/<id>/evidence`, then commit and push."
third = "3. Validate and publish the descriptor against that base commit."
second = "2. Keep `thoth-workspaces.yaml` curator-owned. It uses the `schema_version` value `1` and the ordered\n `workspaces` list of `{id, name, description?}` entries; it is authoritative for workspace ID,\n name, description, and display order."
third = "3. For an existing workspace, edit `<id>/workspace.yaml` and any embedded `<id>/evidence/**`, then\n commit and push."
changed = original.replace(second + "\n" + third, third + "\n" + second, 1)
elif mutation == "migration-commit-omitted":
changed = original.replace("git mv workspaces/<id>.yaml <id>/workspace.yaml\n", "", 1)
elif mutation == "migration-upgrade-omitted":
changed = original.replace("3. Upgrade ThothII only after that migration commit is pushed.\n", "", 1)
elif mutation == "migration-rollback-omitted":
changed = original.replace("Roll back the application revision and registry commit together.", "Roll back only the application revision.", 1)
else:
raise SystemExit(f"unknown Evidence mutation: {mutation}")
if changed == original:
@@ -581,7 +613,9 @@ expect_evidence_claim_accepted() {
mkdir -p \
"$fixture_root/deploy/workspaces" \
"$fixture_root/docs/contracts" \
"$fixture_root/docs/install/examples"
"$fixture_root/docs/install/examples" \
"$fixture_root/docs/install" \
"$fixture_root/docs/migrations"
cp "$root/deploy/workspaces/example.yaml" "$fixture_root/deploy/workspaces/example.yaml"
cp "$root/deploy/workspaces/psd.yaml.example" "$fixture_root/deploy/workspaces/psd.yaml.example"
cp "$root/docs/contracts/workspace-evidence-v3.md" \
@@ -590,6 +624,9 @@ expect_evidence_claim_accepted() {
"$fixture_root/docs/install/local-workspace-registry.md"
cp "$root/docs/install/server-workspace-registry.md" \
"$fixture_root/docs/install/server-workspace-registry.md"
cp "$root/README.md" "$fixture_root/README.md"
cp "$root/docs/migrations/p1-to-p1-1-registry-layout.md" \
"$fixture_root/docs/migrations/p1-to-p1-1-registry-layout.md"
cp "$root/docs/install/examples/workspace-bindings.env.example" \
"$fixture_root/docs/install/examples/workspace-bindings.env.example"
printf '\n%s\n' "$claim" >>"$fixture_root/docs/contracts/workspace-evidence-v3.md"
@@ -959,60 +996,32 @@ expect_guide_rejected \
"$root/docs/install/windows-line-endings.md" docs/install/windows-line-endings.md powershell-crlf-failure \
"PowerShell CRLF repair lacks failure propagation: Assert-NativeSuccess 'index export'"
expect_evidence_fixture_rejected \
"canonical Evidence layout omitted" docs/contracts/workspace-evidence-v3.md layout-omitted \
"missing canonical Evidence layout"
expect_evidence_fixture_rejected \
"same revision ownership omitted" docs/contracts/workspace-evidence-v3.md same-commit-omitted \
"missing same-revision ownership"
expect_evidence_fixture_rejected \
"absolute filesystem Evidence path" deploy/workspaces/example.yaml absolute-filesystem \
"noncanonical filesystem Evidence URI"
expect_evidence_fixture_rejected \
"cross-workspace Evidence path" deploy/workspaces/psd.yaml.example cross-workspace \
"Evidence namespace mismatch"
expect_evidence_fixture_rejected \
"generated docs in wrong directory" docs/contracts/workspace-evidence-v3.md wrong-docs-directory \
"generated docs path invalid"
expect_evidence_fixture_rejected \
"public HTTP mode omitted" docs/contracts/workspace-evidence-v3.md public-http-mode-omitted \
"missing public HTTP mode"
expect_evidence_fixture_rejected \
"ambient S3 mode omitted" docs/contracts/workspace-evidence-v3.md ambient-s3-mode-omitted \
"missing ambient S3 mode"
expect_evidence_fixture_rejected \
"strict Evidence numeric domains omitted" docs/contracts/workspace-evidence-v3.md numeric-domains-omitted \
"missing strict Evidence numeric domains"
expect_evidence_fixture_rejected \
"S3 endpoint policy without endpoint invariant omitted" docs/contracts/workspace-evidence-v3.md endpoint-without-url-invariant-omitted \
"missing S3 endpoint policy without endpoint invariant"
expect_evidence_fixture_rejected \
"signed HTTP file boundary omitted" docs/contracts/workspace-evidence-v3.md http-file-boundary-omitted \
"missing signed HTTP file boundary"
expect_evidence_fixture_rejected \
"static S3 pair boundary omitted" docs/contracts/workspace-evidence-v3.md s3-pair-boundary-omitted \
"missing static S3 file boundary"
expect_evidence_fixture_rejected \
"static S3 optional token boundary omitted" docs/contracts/workspace-evidence-v3.md s3-token-boundary-omitted \
"missing static S3 session-token boundary"
expect_evidence_fixture_rejected \
"credential literal in public bindings" docs/install/examples/workspace-bindings.env.example credential-literal \
"credential literal forbidden"
expect_evidence_fixture_rejected \
"credential literal in public prose" docs/contracts/workspace-evidence-v3.md credential-literal-public-prose \
"credential literal forbidden"
expect_evidence_fixture_rejected \
"credential literal in public YAML" deploy/workspaces/example.yaml credential-literal-public-yaml \
"credential literal forbidden"
expect_evidence_fixture_rejected \
"signed query in public bindings" docs/install/examples/workspace-bindings.env.example signed-query-example \
"query-bearing public URI forbidden"
expect_evidence_fixture_rejected \
"unsafe Evidence file placeholder" docs/install/examples/workspace-bindings.env.example unsafe-placeholder \
"unsafe file placeholder/path"
expect_evidence_fixture_rejected \
"P1 Evidence scope inversion" docs/contracts/workspace-evidence-v3.md p1-scope-inversion \
"P1 scope violation"
expect_evidence_fixture_rejected "root catalog omitted" docs/contracts/workspace-evidence-v3.md layout-omitted "missing canonical Evidence layout"
expect_evidence_fixture_rejected "same revision ownership omitted" docs/contracts/workspace-evidence-v3.md same-commit-omitted "missing same-revision ownership"
expect_evidence_fixture_rejected "flat descriptor path" docs/contracts/workspace-evidence-v3.md flat-descriptor-path 'The descriptor at `<id>/workspace.yaml` must match the'
expect_evidence_fixture_rejected "absolute filesystem Evidence path" deploy/workspaces/example.yaml absolute-filesystem "noncanonical filesystem Evidence URI"
expect_evidence_fixture_rejected "cross-workspace Evidence path" deploy/workspaces/psd.yaml.example cross-workspace "Evidence namespace mismatch"
expect_evidence_fixture_rejected "old filesystem Evidence layout" deploy/workspaces/example.yaml old-filesystem-layout "Evidence namespace mismatch"
expect_evidence_fixture_rejected "generated docs in workspace directory" docs/contracts/workspace-evidence-v3.md wrong-docs-directory "generated docs path invalid"
expect_evidence_fixture_rejected "catalog metadata not authoritative" docs/install/local-workspace-registry.md catalog-authority-omitted "missing catalog authority"
expect_evidence_fixture_rejected "bootstrap create-once rule omitted" docs/install/local-workspace-registry.md bootstrap-omitted "curator flow missing registry rule"
expect_evidence_fixture_rejected "API updates existing descriptors claim" docs/install/local-workspace-registry.md api-updates-existing "curator flow missing registry rule"
expect_evidence_fixture_rejected "public HTTP mode omitted" docs/contracts/workspace-evidence-v3.md public-http-mode-omitted "missing public HTTP mode"
expect_evidence_fixture_rejected "ambient S3 mode omitted" docs/contracts/workspace-evidence-v3.md ambient-s3-mode-omitted "missing ambient S3 mode"
expect_evidence_fixture_rejected "strict Evidence numeric domains omitted" docs/contracts/workspace-evidence-v3.md numeric-domains-omitted "missing strict Evidence numeric domains"
expect_evidence_fixture_rejected "S3 endpoint policy without endpoint invariant omitted" docs/contracts/workspace-evidence-v3.md endpoint-without-url-invariant-omitted "missing S3 endpoint policy without endpoint invariant"
expect_evidence_fixture_rejected "signed HTTP file boundary omitted" docs/contracts/workspace-evidence-v3.md http-file-boundary-omitted "missing signed HTTP file boundary"
expect_evidence_fixture_rejected "static S3 pair boundary omitted" docs/contracts/workspace-evidence-v3.md s3-pair-boundary-omitted "missing static S3 file boundary"
expect_evidence_fixture_rejected "static S3 optional token boundary omitted" docs/contracts/workspace-evidence-v3.md s3-token-boundary-omitted "missing static S3 session-token boundary"
expect_evidence_fixture_rejected "credential literal in public bindings" docs/install/examples/workspace-bindings.env.example credential-literal "credential literal forbidden"
expect_evidence_fixture_rejected "credential literal in public prose" docs/contracts/workspace-evidence-v3.md credential-literal-public-prose "credential literal forbidden"
expect_evidence_fixture_rejected "credential literal in public YAML" deploy/workspaces/example.yaml credential-literal-public-yaml "credential literal forbidden"
expect_evidence_fixture_rejected "signed query in public bindings" docs/install/examples/workspace-bindings.env.example signed-query-example "query-bearing public URI forbidden"
expect_evidence_fixture_rejected "unsafe Evidence file placeholder" docs/install/examples/workspace-bindings.env.example unsafe-placeholder "unsafe file placeholder/path"
expect_evidence_fixture_rejected "P1.1 Evidence scope inversion" docs/contracts/workspace-evidence-v3.md p1-scope-inversion "P1.1 scope violation"
expect_evidence_fixture_rejected "migration commit step omitted" docs/migrations/p1-to-p1-1-registry-layout.md migration-commit-omitted "migration guide missing commit step"
expect_evidence_fixture_rejected "migration upgrade ordering omitted" docs/migrations/p1-to-p1-1-registry-layout.md migration-upgrade-omitted "migration guide missing upgrade ordering"
expect_evidence_fixture_rejected "migration rollback rule omitted" docs/migrations/p1-to-p1-1-registry-layout.md migration-rollback-omitted "migration guide missing rollback rule"
p1_operations=(
acquisition materialization extraction preprocessing embeddings
qdrant-writes indexing active retention gc
@@ -1024,9 +1033,9 @@ p1_positive_forms=(
for operation in "${p1_operations[@]}"; do
for form in "${p1_positive_forms[@]}"; do
expect_evidence_fixture_rejected \
"appended P1 ${operation} ${form} claim" \
"appended P1.1 ${operation} ${form} claim" \
docs/contracts/workspace-evidence-v3.md "p1-append-${operation}-${form}" \
"P1 scope violation"
"P1.1 scope violation"
done
done
p1_safe_bases=(