cloud-dog-vdb 0.5.4__tar.gz

cloud_dog_vdb-0.5.4/.docs-manifest.yml

@@ -0,0 +1,6 @@
+schema-version: 1.0
+project: platform-vdb
+canon-set: PACKAGE
+canon-template-baseline: 1.0
+conditional-docs: []
+additional-docs: []

cloud_dog_vdb-0.5.4/.gitignore

@@ -0,0 +1,16 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+working/
+private/
+archive/
+logs/
+*.db

cloud_dog_vdb-0.5.4/AGENT-INSTRUCTION-FIX-VDB-TESTS.md

@@ -0,0 +1,332 @@
+# Agent Instruction — Fix cloud_dog_vdb Test Infrastructure
+
+**Package:** `cloud_dog_vdb`
+**Version:** 0.3.0
+**Date:** 2026-02-20
+**Status:** OPEN — CRITICAL defects in test infrastructure
+**Scope:** Fix silent-skip test fraud, missing precondition checks, misclassified tests, env file gaps
+
+---
+
+## INTEGRITY WARRANTY — READ THIS FIRST
+
+This section is copied verbatim from the platform-wide `RULES.md` Section 1. It is **NON-NEGOTIABLE**.
+
+**I WILL NEVER:**
+- **LIE** about test results, implementation status, or compliance
+- **FUDGE** test data, configuration, or validation results
+- **HACK** around problems instead of fixing root causes
+- **FALSIFY** test outputs, logs, or status reports
+- **STUB** functionality in IT/AT tests when real implementation is required
+- **FAKE** success when there are errors, warnings, or failures
+- **HIDE** failures, warnings, or non-compliance
+- **PRETEND** tests pass when they fail
+- **SKIP** validation steps to claim completion
+- **BYPASS** rules or requirements for convenience
+
+**IF I CANNOT GUARANTEE 100% COMPLIANCE, I WILL STOP AND SAY SO EXPLICITLY.**
+
+**IF TESTS FAIL, I WILL REPORT FAILURES HONESTLY, NOT HIDE THEM.**
+
+**IF I DON'T KNOW, I WILL ASK, NOT GUESS.**
+
+**"ASK. DON'T GUESS. DON'T LIE. DON'T FUDGE."**
+
+---
+
+## ADDITIONAL RULES — ZERO TOLERANCE
+
+These rules supplement the Integrity Warranty. Violation of ANY rule invalidates all work.
+
+1. **100% REAL systems in IT/AT** — no mocks, no stubs, no `local_mode=True`, no `MockTransport`. If it says "Integration" it MUST integrate with a real external service.
+2. **Silent skip is a LIE** — `pytest.skip()` when a backend is unavailable makes the test report say "0 failed". This is indistinguishable from "all passed". A skipped IT/AT test is NOT a passed test. It is an UNTESTED test.
+3. **env files MUST be complete** — if a test tier requires `VAULT_TOKEN`, the env file for that tier MUST either contain it or the test MUST `pytest.fail()` (not skip) when it is absent.
+4. **Test type MUST match reality** — a test that calls pure functions with no external service is a **UT**, not an IT/AT/QT. A test that uses `local_mode=True` is a **ST** at best, not an IT/AT.
+5. **No decoration env files** — every variable in an env file MUST be consumed by the test code that loads it. If the test ignores the env file and hard-codes Vault, the env file is decoration and MUST be removed or the test MUST be fixed to use it.
+6. **Write-path precondition checks** — before attempting backend writes in IT tests, probe the backend with a lightweight write-then-delete operation. If the probe fails, `pytest.fail()` with a clear message identifying the backend and error. Do NOT just crash with an opaque 500.
+7. **Config delegation** — test fixtures MUST use the same config loading path as the application. If the app uses `cloud_dog_config` layered precedence, tests MUST NOT bypass it by shelling out to Vault directly.
+8. **Honest reporting** — when reporting test results, ALWAYS state the skip count. "76 passed, 0 failed, 11 skipped" is NOT the same as "76 passed". If skipped tests include IT tests that should have run against real backends, this MUST be flagged as a gap, not hidden.
+
+---
+
+## WHY THIS INSTRUCTION EXISTS
+
+### Audit Findings (2026-02-20)
+
+An audit of the `cloud_dog_vdb` test infrastructure found **5 critical defects**:
+
+| ID | Severity | Finding | Evidence |
+|----|----------|---------|----------|
+| **T-1** | CRITICAL | `env-IT` missing `VAULT_TOKEN` — all 11 real-backend IT tests silently skip | `tests/env-IT` has 3 of 4 required Vault vars. `conftest.py:59` calls `pytest.skip()` when `VAULT_TOKEN` is missing. Result: "0 failed, 11 skipped" reported as "PASS". |
+| **T-2** | CRITICAL | 10 tests misclassified as IT/AT/QT when they are actually UT/ST | See § Misclassified Tests below. |
+| **T-3** | HIGH | No write-path precondition check before backend operations | IT tests dive straight into `create_collection()` / `add_documents()`. When backend has resource exhaustion (e.g. Chroma FD limit), tests crash with opaque HTTP 500. |
+| **T-4** | HIGH | `pytest.skip()` used instead of `pytest.fail()` for mandatory IT preconditions | `conftest.py:59` and all 11 IT tests use `pytest.skip()` when config/backend is missing. For IT tests that MUST run against real backends, this should be `pytest.fail()`. |
+| **T-5** | MEDIUM | `env-UT`, `env-ST`, `env-AT` all contain identical Vault vars but no `VAULT_TOKEN` | All 4 env files have `VAULT_ADDR`, `VAULT_MOUNT_POINT`, `VAULT_CONFIG_PATH` but not `VAULT_TOKEN`. UT/ST don't need Vault (per RULES.md § 5.5). AT tests use `local_mode=True` so don't need it either. These Vault vars are decoration. |
+
+### Misclassified Tests (T-2)
+
+| Test | Claimed Type | Actual Type | Evidence |
+|------|-------------|-------------|----------|
+| IT1.11 CrossBackendPortable | Integration | ST (local) | Uses `local_mode=True` — no real backend |
+| IT1.13 LifecycleRealBackend | Integration | **UT** | Calls `mark_deleted()` / `mark_superseded()` — pure functions, no backend |
+| AT1.1 ServiceStartupPattern | Application | ST (local) | Uses `local_mode=True` — no real service |
+| AT1.2 FullIngestionFlow | Application | ST (local) | Uses `local_mode=True` — no real service |
+| AT1.3 SearchWithFilters | Application | ST (local) | Uses `local_mode=True` — no real service |
+| AT1.4 ConformanceSuite | Application | **UT** | Uses `mock_adapter()` — mock, not real |
+| AT1.5 ClientOnlyIntegration | Application | **UT** | Uses `httpx.MockTransport` — mock, not real |
+| QT1.1 TenantIsolation | Security | **UT** | Calls `enforce_tenant()` — pure function, 7 lines |
+| QT1.2 AccessControlEnforcement | Security | **UT** | Calls `can_admin()` — pure function, 7 lines |
+| QT1.4 PurgeRequiresAdmin | Security | **UT** | Calls `can_admin()` — pure function, 8 lines |
+
+**Correctly classified tests:** QT1.3 (static file scan — legitimate QT).
+
+---
+
+## HARD CONSTRAINTS
+
+- **DO NOT** delete any test. Reclassify by moving to the correct directory.
+- **DO NOT** add `os.environ`/`os.getenv` reads in library source code.
+- **DO NOT** weaken any existing test assertion.
+- **DO NOT** convert real-backend IT tests to use `local_mode=True`.
+- **DO NOT** claim completion without running the full verification chain AND reporting skip counts.
+- **UK English only.**
+
+---
+
+## PHASE 1 — Fix env-IT to include VAULT_TOKEN (T-1)
+
+### Step 1.1 — Decide: env-IT should NOT contain VAULT_TOKEN directly
+
+Per RULES.md § 5.5: *"NEVER save keys, passwords, tokens, or credentials into the repository."*
+
+`VAULT_TOKEN` is a credential. It MUST NOT be in `env-IT`.
+
+**Solution:** The test runner MUST source `env-vault` before running IT tests. The `conftest.py` fixture must enforce this by calling `pytest.fail()` (not `pytest.skip()`) when `VAULT_TOKEN` is missing for IT-tier tests.
+
+### Step 1.2 — Update `conftest.py`: fail instead of skip for IT/AT tests
+
+Change `conftest.py` `vault_config()` fixture:
+
+```python
+# BEFORE:
+if missing:
+    pytest.skip(f"Vault variables missing: {', '.join(missing)}")
+
+# AFTER:
+if missing:
+    tier = os.environ.get("TEST_ENV_TIER", "")
+    if tier in ("IT", "AT"):
+        pytest.fail(
+            f"VAULT_TOKEN and Vault variables are REQUIRED for {tier} tests. "
+            f"Missing: {', '.join(missing)}. "
+            f"Run: set -a; source /opt/iac/Development/cloud-dog-ai/env-vault; set +a"
+        )
+    pytest.skip(f"Vault variables missing (UT/ST may skip): {', '.join(missing)}")
+```
+
+### Step 1.3 — Add `TEST_ENV_TIER` to env files
+
+Add to each env file:
+
+| File | Add |
+|------|-----|
+| `env-UT` | `TEST_ENV_TIER=UT` |
+| `env-ST` | `TEST_ENV_TIER=ST` |
+| `env-IT` | `TEST_ENV_TIER=IT` |
+| `env-AT` | `TEST_ENV_TIER=AT` |
+
+### Step 1.4 — Remove decoration Vault vars from env-UT and env-ST
+
+UT and ST tests MUST NOT require Vault (RULES.md § 5.5). Remove `VAULT_ADDR`, `VAULT_MOUNT_POINT`, `VAULT_CONFIG_PATH` from `env-UT` and `env-ST`.
+
+---
+
+## PHASE 2 — Add write-path precondition checks (T-3)
+
+### Step 2.1 — Create a reusable backend probe fixture
+
+Add to `conftest.py`:
+
+```python
+@pytest.fixture(scope="session")
+def chroma_ready(vdbs: dict) -> dict:
+    """Verify Chroma can actually handle writes, not just heartbeat."""
+    cfg = vdbs.get("chroma", {})
+    if not cfg:
+        pytest.fail("dev.vdbs.chroma missing from Vault config")
+    from cloud_dog_vdb.adapters.chroma import ChromaAdapter
+    from cloud_dog_vdb.config.models import ProviderConfig
+    from cloud_dog_vdb.domain.models import CollectionSpec
+    import asyncio
+
+    a = ChromaAdapter(
+        ProviderConfig(provider_id="chroma", base_url=cfg.get("base_url", ""), api_key=cfg.get("auth_token", "")),
+        local_mode=False,
+    )
+    probe_name = "_cloud_dog_write_probe"
+    loop = asyncio.get_event_loop()
+    try:
+        loop.run_until_complete(a.delete_collection(probe_name))
+        loop.run_until_complete(a.create_collection(CollectionSpec(name=probe_name)))
+        loop.run_until_complete(a.delete_collection(probe_name))
+    except Exception as exc:
+        pytest.fail(f"Chroma write-path probe FAILED: {exc}")
+    return cfg
+```
+
+Create equivalent `qdrant_ready`, `weaviate_ready`, `opensearch_ready`, `pgvector_ready` fixtures.
+
+### Step 2.2 — Update IT tests to use `*_ready` fixtures instead of raw `vdbs`
+
+Replace `vdbs` parameter with the appropriate `*_ready` fixture in each IT test.
+
+---
+
+## PHASE 3 — Reclassify misclassified tests (T-2)
+
+### Step 3.1 — Move misclassified tests to correct directories
+
+| Current Location | Move To | Reason |
+|-----------------|---------|--------|
+| `integration/IT1.11_CrossBackendPortable/` | `system/ST1.9_CrossBackendPortableLocal/` | Uses `local_mode=True` |
+| `integration/IT1.13_LifecycleRealBackend/` | `unit/UT1.38_LifecycleFunctions/` | Pure function calls |
+| `application/AT1.1_ServiceStartupPattern/` | `system/ST1.10_ServiceStartupLocal/` | Uses `local_mode=True` |
+| `application/AT1.2_FullIngestionFlow/` | `system/ST1.11_FullIngestionLocal/` | Uses `local_mode=True` |
+| `application/AT1.3_SearchWithFilters/` | `system/ST1.12_SearchWithFiltersLocal/` | Uses `local_mode=True` |
+| `application/AT1.4_ConformanceSuite/` | `unit/UT1.39_ConformanceMock/` | Uses `mock_adapter()` |
+| `application/AT1.5_ClientOnlyIntegration/` | `unit/UT1.40_RemoteClientMock/` | Uses `MockTransport` |
+| `security/QT1.1_TenantIsolation/` | `unit/UT1.41_TenantIsolationLogic/` | Pure function |
+| `security/QT1.2_AccessControlEnforcement/` | `unit/UT1.42_AccessControlLogic/` | Pure function |
+| `security/QT1.4_PurgeRequiresAdmin/` | `unit/UT1.43_PurgeAdminLogic/` | Pure function |
+
+### Step 3.2 — Write REAL IT/AT/QT replacements
+
+For each reclassified test, write a NEW test at the original location that actually uses real backends:
+
+| New Test | What It Must Do |
+|----------|----------------|
+| IT1.11 CrossBackendPortable | Run the same portable contract against BOTH Chroma AND Qdrant real backends |
+| IT1.13 LifecycleRealBackend | Mark records as deleted/superseded IN a real Chroma collection, verify via query |
+| AT1.1 ServiceStartupPattern | Start a real VDB client against Chroma, verify `init_backend()` succeeds against real server |
+| AT1.2 FullIngestionFlow | Run full ingestion against real Chroma, not `local_mode` |
+| AT1.3 SearchWithFilters | Search with metadata filters against real Chroma |
+| AT1.4 ConformanceSuite | Run `adapter_conforms()` against a REAL adapter, not mock |
+| AT1.5 ClientOnlyIntegration | If `RemoteVDBClient` is meant for real remote use, test against a real endpoint. If no real endpoint exists, document this as a gap and leave it as UT until a remote VDB service is deployed. |
+| QT1.1 TenantIsolation | Ingest records with different `tenant_id` into real Chroma, verify isolation via search |
+| QT1.2 AccessControlEnforcement | Test access control against a real adapter operation |
+| QT1.4 PurgeRequiresAdmin | Attempt purge on a real collection, verify admin enforcement |
+
+---
+
+## PHASE 4 — Clean up env files (T-5)
+
+### Step 4.1 — env-UT contents
+
+```
+TEST_ENV_TIER=UT
+```
+
+UT tests MUST NOT need anything else. If they do, the test has a dependency problem.
+
+### Step 4.2 — env-ST contents
+
+```
+TEST_ENV_TIER=ST
+```
+
+ST tests use `local_mode=True` and in-memory backends. No external config needed.
+
+### Step 4.3 — env-IT contents
+
+```
+TEST_ENV_TIER=IT
+VAULT_ADDR=https://vault0.cloud-dog.net
+VAULT_MOUNT_POINT=cloud_dog_ai
+VAULT_CONFIG_PATH=config
+```
+
+`VAULT_TOKEN` comes from `env-vault` sourced before test run. The conftest will `pytest.fail()` if it is missing.
+
+### Step 4.4 — env-AT contents
+
+```
+TEST_ENV_TIER=AT
+VAULT_ADDR=https://vault0.cloud-dog.net
+VAULT_MOUNT_POINT=cloud_dog_ai
+VAULT_CONFIG_PATH=config
+```
+
+AT tests require real backends. Same Vault dependency as IT.
+
+---
+
+## PHASE 5 — Update TESTS.md
+
+### Step 5.1 — Update test directory structure to reflect reclassifications
+
+### Step 5.2 — Update test counts
+
+After reclassification, counts should be approximately:
+- **UT:** 37 (original) + 6 (reclassified from IT/AT/QT) = **43**
+- **ST:** 8 (original) + 4 (reclassified from IT/AT) = **12**
+- **IT:** 13 (original) - 2 (reclassified) + 2 (new real replacements) = **13**
+- **AT:** 5 (original) - 5 (reclassified) + 5 (new real replacements) = **5**
+- **QT:** 4 (original) - 3 (reclassified) + 3 (new real replacements) = **4**
+
+### Step 5.3 — Update Test Run History
+
+Record actual results with skip counts. Example:
+
+```
+| Date | Scope | Command | Passed | Failed | Skipped | Notes |
+```
+
+**NEVER write "PASS" without the skip count.**
+
+---
+
+## PHASE 6 — Verification
+
+### Step 6.1 — Run UT + ST (no Vault required)
+
+```bash
+cd /opt/iac/Development/cloud-dog-ai/cloud-dog-ai-platform-standards/packages/backend/platform-vdb
+.venv/bin/pytest tests/unit tests/system --env tests/env-UT --env tests/env-ST -v
+```
+
+**Expected:** All pass, 0 skipped.
+
+### Step 6.2 — Run IT + AT (Vault required)
+
+```bash
+set -a; source /opt/iac/Development/cloud-dog-ai/env-vault; set +a
+.venv/bin/pytest tests/integration tests/application --env tests/env-IT --env tests/env-AT -v
+```
+
+**Expected:** All pass against available backends. Any backend that is down should produce `pytest.fail()` with a clear error message, NOT a silent skip.
+
+### Step 6.3 — Run QT (Vault required for real-backend QT tests)
+
+```bash
+.venv/bin/pytest tests/security --env tests/env-IT -v
+```
+
+### Step 6.4 — Report honestly
+
+State exact counts: `N passed, N failed, N skipped`. If any IT/AT test skipped, explain WHY and which backend is unavailable.
+
+---
+
+## COMPLETION GATE
+
+This instruction is complete ONLY when:
+
+1. `env-IT` no longer causes silent skips — missing `VAULT_TOKEN` produces `pytest.fail()`
+2. All 10 misclassified tests are moved to correct directories
+3. Real-backend replacements exist for all reclassified IT/AT/QT tests
+4. Write-path probe fixtures exist for all 5 backends
+5. TESTS.md updated with correct classifications and honest run history
+6. Full test suite runs with `0 skipped` for UT/ST tier
+7. IT/AT tier runs against real backends with honest reporting
+
+**DO NOT claim completion without evidence for ALL 7 gates.**

cloud_dog_vdb-0.5.4/AGENT-INSTRUCTION-FIX-VDB.md

@@ -0,0 +1,188 @@
+# Agent Instruction — Fix cloud_dog_vdb (v0.2.0)
+
+**Package:** `cloud_dog_vdb`
+**Target version:** 0.2.0
+**Date:** 2026-02-18 (re-review with source verification)
+**Scope:** Config-delegation enforcement + adapter rewiring + test alignment + v0.2.0 features — **ALL DELIVERED AND VERIFIED**
+
+---
+
+## Status: ✅ COMPLETE (minor SA1 extra-files gap noted)
+
+All 6 issues from the original instruction have been resolved. This document is retained for reference and future maintenance.
+
+**Verified on 2026-02-18 (re-review):**
+- 91 source files across 20+ subpackages
+- 67 test directories present (37 UT + 8 ST + 13 IT + 5 AT + 4 QT)
+- Zero config-delegation violations: `os.environ`/`hvac`/`overlay_secrets`/`VAULT_JSON` grep returns zero hits
+- `secrets/` directory does NOT exist (deleted)
+- All 5 adapters use `self.config.*` directly (no `self._runtime`, no overlay)
+- Duplicate converter files removed (only `*_conv.py` versions remain)
+- Test directories renamed to match TESTS.md v0.2.0 (ConfigDelegation, ConfigDelegationVerification, ConfigDelegationE2E)
+- Old scaffold IT directories removed
+- All 3 v0.2.0 feature files present and substantive
+- Build produces `cloud_dog_vdb-0.2.0` wheel + sdist
+
+**Governing documents:**
+1. `platform-vdb/REQUIREMENTS.md` (v0.2.0) — FR1.31, FR1.33, FR1.34–FR1.36
+2. `platform-vdb/ARCHITECTURE.md` (v0.2.0) — SA1 module layout
+3. `platform-vdb/TESTS.md` (v0.2.0) — all test directories
+4. `packages/backend/AGENT-INSTRUCTION.md` — Integrity Warranty and Config Delegation — ZERO TOLERANCE (MANDATORY)
+
+---
+
+## Delivery Summary
+
+### Issue 1 — Config Delegation Enforcement ✅ RESOLVED
+
+| Sub-issue | Status | Evidence |
+|-----------|--------|----------|
+| 1A. Delete `secrets/` module | ✅ | Directory does not exist |
+| 1B. Rewire all 5 adapters | ✅ | Zero `overlay_secrets`, `self._runtime`, or `from cloud_dog_vdb.secrets` hits in source |
+| 1C. Fix `observability/otel.py` | ✅ | Zero `os.environ` hits in any source file |
+| 1D. Rename 3 test directories | ✅ | `UT1.31_ConfigDelegation`, `UT1.34_ConfigDelegationVerification`, `ST1.8_ConfigDelegationE2E` all present |
+
+Config delegation verification command returns clean:
+```bash
+grep -rn "os.environ\|import hvac\|overlay_secrets\|from cloud_dog_vdb.secrets" cloud_dog_vdb/ --include="*.py" | grep -v __pycache__
+# → zero results
+```
+
+---
+
+### Issue 2 — SA1 Module Alignment ✅ MOSTLY RESOLVED
+
+**Resolved items:**
+- `secrets/` directory deleted ✅
+- `registry/` duplicate directory removed ✅
+- Duplicate converter files (`deepdoc.py`, `mineru.py`, `pandas.py`) removed — only `*_conv.py` versions remain ✅
+
+**Remaining extra files (non-blocking — additive, not violations):**
+
+| File/Directory | Purpose | Recommendation |
+|----------------|---------|----------------|
+| `factory.py` (top-level) | `get_vdb_client()` factory imported by `__init__.py` | Add to SA1 or fold into `runtime/factory.py` |
+| `embeddings/` (3 files) | Standalone embedding provider helpers | Add to SA1 (supplements `ingestion/embed.py`) |
+| `adapters/vector_utils.py` | Deterministic vector generation for testing | Move to `testing/` or add to SA1 |
+| `runtime/` (3 files) | `VDBClient` and factory | Add to SA1 |
+
+**Recommendation:** Update ARCHITECTURE.md SA1 to include these files. This is documentation-only — the package is functionally complete.
+
+---
+
+### Issue 3 — Compatibility Normaliser (FR1.34) ✅ DELIVERED
+
+- `cloud_dog_vdb/compat/response_normaliser.py` — **178 lines**
+- Per-backend mappings for Chroma, Qdrant, Weaviate, OpenSearch, PGVector
+- Normalises backend responses to unified `SearchResult` / `Record` models
+- Test directory `UT1.35_ResponseNormaliser` present
+
+---
+
+### Issue 4 — Client-Only Integration Mode (FR1.35) ✅ DELIVERED
+
+- `cloud_dog_vdb/remote/client.py` — **86 lines**
+- `RemoteVDBClient` proxy delegating all ops to remote VDB via HTTP
+- No local backend dependency required
+- Test directories `UT1.36_RemoteProxy` and `AT1.5_ClientOnlyIntegration` present
+
+---
+
+### Issue 5 — Collection Schema Versioning (FR1.36) ✅ DELIVERED
+
+- `cloud_dog_vdb/versioning/schema_version.py` — **129 lines**
+- Tracks dimension count, metadata fields, embedding model, version number per collection
+- Version mismatch detection at query time
+- Migration utility for detecting dimension changes
+- Test directory `UT1.37_SchemaVersioning` present
+
+---
+
+### Issue 6 — Test Directory Alignment ✅ RESOLVED
+
+- Old scaffold IT directories (ChromaRemoteCollection, ChromaLocalCollection, QdrantCollection, WeaviateCollection, OpenSearchIndex, PGVectorTable, EmbeddingProviders) removed
+- All IT directories match TESTS.md v0.2.0 names (IT1.1_ChromaCRUD through IT1.13_IngestionPipelineEndToEnd)
+- Config delegation test directories renamed per v0.2.0 spec
+
+---
+
+## Verification — Full Suite
+
+```bash
+set -a; source /opt/iac/Development/cloud-dog-ai/env-vault-admin; set +a
+
+# 1. Config delegation check — MUST return zero hits
+grep -rn "os.environ\|import hvac\|overlay_secrets\|from cloud_dog_vdb.secrets" cloud_dog_vdb/ --include="*.py" | grep -v __pycache__
+
+# 2. secrets/ directory MUST NOT exist
+test ! -d cloud_dog_vdb/secrets && echo "PASS" || echo "FAIL"
+
+# 3. All tests pass
+.venv/bin/pytest tests --env tests/env-UT --env tests/env-ST --env tests/env-IT --env tests/env-AT -q
+
+# 4. Lint clean
+.venv/bin/ruff check cloud_dog_vdb tests
+.venv/bin/ruff format --check cloud_dog_vdb tests
+
+# 5. Build
+.venv/bin/python -m build --no-isolation
+```
+
+## pyproject.toml version
+
+```toml
+version = "0.2.0"
+```
+
+---
+
+## MANDATORY COMPLETION REPORT
+
+When finished, write your report to:
+**`/opt/iac/Development/cloud-dog-ai/cloud-dog-ai-platform-standards/packages/backend/platform-vdb/working/W28A-116-FIX-VDB-REPORT.md`**
+
+Your report MUST include ALL of the following:
+
+### 1. Run summary
+- List every file changed and what was changed
+- List every test fixed and how
+
+### 2. Test results (REAL counts from actual runs)
+```
+QT: Xp / Yf
+UT: Xp / Yf
+ST: Xp / Yf
+IT: Xp / Yf
+AT: Xp / Yf
+Ruff: X issues
+```
+
+### 3. Verdict
+State one of: **PASS** (100% green) / **PARTIAL** (some fixed, some remain) / **FAIL** (no improvement) / **BLOCKED** (cannot proceed)
+
+If not PASS, list every remaining failure with classification: `CODE_BUG`, `ENV_CONFIG`, `INFRA_MISSING`, `EXT_SERVICE`
+
+### 4. Evidence logs
+All logs MUST be saved to `working/` directory:
+```
+working/w28a-116-qt.log
+working/w28a-116-ut.log
+working/w28a-116-st.log
+working/w28a-116-it.log
+working/w28a-116-at.log
+working/w28a-116-ruff.log
+```
+
+### 5. RULES.md COMPLIANCE WARRANTY
+
+Copy this EXACTLY into your report:
+```
+I warrant that:
+1. I have read RULES.md IN FULL before starting work
+2. ALL code I produced is 100% compliant with RULES.md
+3. ALL test results reported are REAL — exact counts from actual runs
+4. I have NOT weakened any test
+5. I have NOT stored, copied, or exposed any credentials
+6. ALL credentials come from Vault or git-ignored env files
+7. I have NOT modified files outside this package
+```

cloud_dog_vdb-0.5.4/AGENTS.md

@@ -0,0 +1,94 @@
+# platform-vdb Agent Guidance
+
+This runbook is for agents implementing or validating `cloud_dog_vdb` changes.
+
+## Non-Negotiable Rules
+
+- Use real dependencies for `ST/IT/AT/PT/QT` tiers.
+- Do not add stubs, silent fallbacks, or fake success paths to satisfy tests.
+- Preserve backward compatibility:
+  - public API parity,
+  - default behavior parity,
+  - metadata identity parity,
+  - error/result envelope parity.
+- Load credentials from approved env/Vault sources only.
+
+## Required Inputs
+
+- Repository root: `/opt/iac/Development/cloud-dog-ai/cloud-dog-ai-platform-standards`
+- Package root: `packages/backend/platform-vdb`
+- Vault env file (not committed): `/opt/iac/Development/cloud-dog-ai/env-vault`
+- Corpus manifest: `test-data/corpus-manifest.yaml`
+
+## Service Configuration Expectations
+
+- `dev.services.mineru` must resolve to `MINERU_BASE_URL` for parser tests.
+- `dev.services.marker_mcp` (or `dev.services.markermcp`) is supported but currently held disabled when instructed.
+- `dev.vdbs.infinity` must exist for Infinity adapter integration tests.
+- Local parser command adapters are supported (no Vault required) for:
+  - `deepdoc` via `tests/tools/local_deepdoc_parser.py`
+  - `docling` via `tests/tools/local_docling_parser.py`
+  - `transformers` via `tests/tools/local_transformers_parser.py`
+
+## Local Parser Setup
+
+- Install local parser dependencies in package venv:
+  - `.venv/bin/pip install transformers==4.57.1 docling-parse==5.4.0`
+- Ensure env files used for IT/AT/PT/PT-PERF enable parser commands:
+  - `DEEPDOC_ENABLED=true`, `DOCLING_ENABLED=true`, `TRANSFORMERS_ENABLED=true`
+  - command values point to `.venv/bin/python tests/tools/local_*_parser.py`
+- For PT/PT-PERF MinerU stability on shared GPU hosts, keep low-VRAM flags explicit:
+  - `MINERU_FORMULA_ENABLE=false`
+  - `MINERU_TABLE_ENABLE=false`
+  - `MINERU_RETURN_MIDDLE_JSON=false`
+  - `MINERU_RETURN_IMAGES=false`
+
+## Standard Execution Order
+
+Run from `packages/backend/platform-vdb`:
+
+0. `.venv/bin/pip install transformers==4.57.1 docling-parse==5.4.0`
+1. `set -a; source /opt/iac/Development/cloud-dog-ai/env-vault; set +a; .venv/bin/pytest tests/integration/IT2.11_ParserProviderCoverageMatrix --env tests/env-IT --env tests/env-REQUIRE-ALL-PARSERS -q`
+2. `set -a; source /opt/iac/Development/cloud-dog-ai/env-vault; set +a; .venv/bin/pytest tests/application/AT2.2_ParserProviderCoverageMatrix --env tests/env-AT --env tests/env-REQUIRE-ALL-PARSERS -q`
+3. `.venv/bin/pytest tests/parser/PT1.2_DeepdocAdapter tests/parser/PT1.3_DoclingAdapter tests/parser/PT1.8_TransformersAdapter --env tests/env-PT --env tests/env-CORPUS-SMALL -q`
+4. `.venv/bin/ruff check`
+5. `.venv/bin/ruff format --check`
+6. `.venv/bin/pytest tests/unit tests/system --env tests/env-UT --env tests/env-ST -q`
+7. `.venv/bin/pytest tests/compatibility --env tests/env-CT -q`
+8. `set -a; source /opt/iac/Development/cloud-dog-ai/env-vault; set +a; .venv/bin/pytest tests/integration --env tests/env-IT -q`
+9. `set -a; source /opt/iac/Development/cloud-dog-ai/env-vault; set +a; timeout 1800 .venv/bin/pytest tests/parser --env tests/env-PT --env tests/env-CORPUS-LARGE -q`
+10. `set -a; source /opt/iac/Development/cloud-dog-ai/env-vault; set +a; timeout 1800 .venv/bin/pytest tests/parser_performance --env tests/env-PT-PERF --env tests/env-CORPUS-LARGE -q`
+11. `set -a; source /opt/iac/Development/cloud-dog-ai/env-vault; set +a; .venv/bin/pytest tests/application --env tests/env-AT -q`
+12. `set -a; source /opt/iac/Development/cloud-dog-ai/env-vault; set +a; .venv/bin/pytest tests/security --env tests/env-IT -q`
+13. `.venv/bin/python -m build`
+14. `.venv/bin/pip install --force-reinstall dist/cloud_dog_vdb-0.4.1-py3-none-any.whl`
+15. Smoke import: `.venv/bin/python -c "import cloud_dog_vdb; print(cloud_dog_vdb.__version__)"`
+
+For full evidence capture, mirror outputs to `/tmp/w13a_*.log` using `tee`.
+
+## Staged Parser Validation (Recommended)
+
+Use corpus slicing for deterministic progression:
+
+- Small: `--env tests/env-CORPUS-SMALL`
+- Medium: `--env tests/env-CORPUS-MEDIUM`
+- Large: `--env tests/env-CORPUS-LARGE`
+
+Recommended progression:
+
+1. `tests/parser` + small
+2. `tests/parser_performance` + small
+3. `tests/parser` + medium
+4. `tests/parser_performance` + medium
+5. Large slice under explicit timeout guard
+
+## Documentation Stage (Release Gate)
+
+After test/build execution, update:
+
+- `TESTS.md` run history (commands, date, pass/fail/skip, blockers).
+- `README.md` document links and runtime prerequisites.
+- `PROGRAMME-0.4.0-DEVELOPMENT-BUILD-TEST.md` if sequencing/gates changed.
+- `RELEASE_UPLIFT_PROPOSAL.md` if scope or constraints changed.
+
+Do not claim 100% completion if any parser-performance or provider enablement gate is still open.