bijotel 1.0.0__tar.gz

bijotel-1.0.0/.audit_tmp/01_STATE.md

@@ -0,0 +1,536 @@
+# DOC 01 — STATE | BIJOTEL Audit T+7d | 2026-05-17
+
+Generated-at (UTC): 2026-05-17T07:30:41Z
+Repo: C:\Users\User\Desktop\AGENTY 2026\BIJUTERII S3\BIJUTERII IMPLEMENT\BIJOTEL
+HEAD: 0bffb6cc32ef1dc6d383090024a904578412d9be (F11, v0.5.0)
+Working tree: clean (`git status -s -uno` empty)
+Interpreter: .venv/Scripts/python — Python 3.12.10
+
+All numbers below are empirical. Each subsection carries a `Method:` line with
+the exact command. Language is restricted to "is" / "unknown". Claimed-vs-actual
+mismatches are marked **REFRAMING**.
+
+---
+
+## A. CODEBASE INVENTORY
+
+**Method:** `find src -name "*.py" -exec wc -l {} \;`,
+`find tests -name "*.py" -exec wc -l {} \;`,
+project total: `find . -name "*.py" -not -path "./.venv/*" -not -path "./.git/*" | xargs wc -l`.
+Module purpose: first docstring line via `head -1 src/bijotel/<f>.py`.
+
+### LOC totals
+
+| Scope | LOC | Method |
+|---|---|---|
+| `src/` (all .py) | 3625 | `find src -name "*.py" -exec cat {} \; | wc -l` |
+| `tests/` (all .py) | 3807 | `find tests -name "*.py" -exec cat {} \; | wc -l` |
+| Whole project (.py, excl .venv/.git; incl scripts/) | 13826 | `find . -name "*.py" ... | xargs wc -l | tail -1` |
+
+Note: project total (13826) includes `src/` + `tests/` + `scripts/` (F0–F5
+capture scripts + `gena_deploy/`). `src/`+`tests/` alone = 7432.
+
+### src/bijotel — LOC per module, grouped by subpackage
+
+Top-level
+| File | LOC | Purpose (from docstring) |
+|---|---|---|
+| `__init__.py` | 59 | Package root; re-exports public API; `__version__ = "0.5.0"` |
+
+adapters (F7/F9)
+| File | LOC | Purpose |
+|---|---|---|
+| `__init__.py` | 12 | Subpackage exports (Provider, ProviderResponse, AnthropicAdapter, OpenAIAdapter) |
+| `base.py` | 123 | Provider Protocol — base contract for LLM provider adapters (F7) |
+| `anthropic_adapter.py` | 109 | AnthropicAdapter — Provider implementation for Anthropic Claude (F7) |
+| `openai_adapter.py` | 135 | OpenAIAdapter — Provider implementation for OpenAI (F9, v0.4.0) |
+| `openai_extractors.py` | 112 | Request/response extractors for OpenAI SDK (F9) |
+
+cli (F6)
+| File | LOC | Purpose |
+|---|---|---|
+| `__init__.py` | 11 | CLI subpackage marker |
+| `main.py` | 152 | BIJOTEL CLI entry point (argparse dispatch) |
+| `commands.py` | 480 | CLI subcommand handlers (verify/inspect/stats/list/export/verify-export/regression) |
+
+core
+| File | LOC | Purpose |
+|---|---|---|
+| `__init__.py` | 1 | Core subpackage marker |
+| `init.py` | 59 | Core initialization: TracerProvider + ConsoleExporter for F1 schema discovery |
+
+decorators (F5) — *not in the prompt's subpackage list but present in code*
+| File | LOC | Purpose |
+|---|---|---|
+| `__init__.py` | 18 | Exports trace_genai, wrap |
+| `extractors.py` | 104 | Default request/response extractors for common LLM call patterns |
+| `trace_genai.py` | 272 | @trace_genai decorator + wrap() runtime alternative |
+
+exporters
+| File | LOC | Purpose |
+|---|---|---|
+| `__init__.py` | 1 | Empty namespace marker (no implementation; export logic lives in processors/export.py) |
+
+processors (F2/F3/F8)
+| File | LOC | Purpose |
+|---|---|---|
+| `__init__.py` | 15 | Exports export_chain, verify_export |
+| `canonical.py` | 127 | Canonicalization: span -> deterministic JSON bytes via JCS (RFC 8785) |
+| `cas.py` | 139 | CasSpanProcessor: content-addressable storage, dedup on input-only body |
+| `hmac_chain.py` | 202 | HmacChainSpanProcessor: tamper-evident audit chain over GenAI spans |
+| `export.py` | 228 | Portable signed JSON export of HMAC chain (F8) |
+
+policy (F4/F8/F11)
+| File | LOC | Purpose |
+|---|---|---|
+| `__init__.py` | 24 | Exports Decision, PolicyDeniedError, PolicyEngine, guard, 5 rule factories |
+| `decision.py` | 69 | Decision: 3-state (allow/warn/deny) result of policy rule evaluation |
+| `engine.py` | 42 | PolicyEngine: evaluate list of rules against a request |
+| `guard.py` | 131 | guard(): decorator wrapping callable with policy gate |
+| `prices.py` | 45 | Anthropic price snapshot, USD per 1k tokens |
+| `prompt_patterns.py` | 101 | Default prompt patterns for jailbreak / prompt-injection detection (F11) |
+| `rules.py` | 386 | Built-in policy rules; each rule is callable (request_dict) -> Decision |
+
+regression (F12)
+| File | LOC | Purpose |
+|---|---|---|
+| `__init__.py` | 20 | Exports RegressionDetector, Anomaly, AnomalyMethod, DimensionStats, compute_baseline |
+| `baseline.py` | 197 | Rolling baseline aggregation for regression detection (F12) |
+| `detector.py` | 251 | Anomaly detection via z-score + IQR thresholds (F12, Bijuteria #16) |
+
+### Feature-to-code cross-check (CHANGELOG v0.1.0–v0.5.0)
+
+**Method:** map each CHANGELOG feature ID to source paths confirmed present by
+`find src`.
+
+| Feature | CHANGELOG ref | Code present | Evidence path |
+|---|---|---|---|
+| F0 skeleton | v0.1.0 | yes | package tree + `__init__.py` |
+| F1 TracerProvider/semconv | v0.1.0 | yes | `core/init.py` |
+| F2 HMAC chain | v0.1.0 | yes | `processors/hmac_chain.py`, `processors/canonical.py` |
+| F3 CAS | v0.1.0 | yes | `processors/cas.py` |
+| F4 Policy gate | v0.1.0 | yes | `policy/decision.py`, `engine.py`, `guard.py`, `rules.py`, `prices.py` |
+| F5 @trace_genai/wrap | v0.1.0 | yes | `decorators/trace_genai.py`, `decorators/extractors.py` |
+| F6 CLI | v0.1.0 | yes | `cli/main.py`, `cli/commands.py` |
+| F7 Provider Protocol + AnthropicAdapter | v0.1.0 | yes | `adapters/base.py`, `adapters/anthropic_adapter.py` |
+| F8 Portable export + rate_limit rule | v0.2.0 | yes | `processors/export.py`, `rate_limit_calls_per_minute` in `policy/rules.py` |
+| F12 Regression Detection | v0.3.0 | yes | `regression/baseline.py`, `regression/detector.py` |
+| F9 OpenAIAdapter | v0.4.0 | yes | `adapters/openai_adapter.py`, `adapters/openai_extractors.py` |
+| F11 prompt_pattern_deny | v0.5.0 | yes | `policy/prompt_patterns.py`, `prompt_pattern_deny` in `policy/rules.py` |
+
+All 12 claimed features (F0–F9, F11, F12) have corresponding code present. No
+feature is claimed-but-missing. Note: feature numbering is non-contiguous in the
+CHANGELOG itself (F10 is never referenced; F12 ships in v0.3.0 before F9 in
+v0.4.0 and F11 in v0.5.0 — the F-numbers are not chronological). This is a
+CHANGELOG numbering style, not a code gap.
+
+**REFRAMING (prompt scope vs reality):** The audit prompt enumerates
+subpackages "adapters, cli, core, exporters, processors, policy, regression,
+plus top-level". Reality adds an 8th subpackage `decorators/` (3 files, 394 LOC,
+houses F5 `@trace_genai`/`wrap`). `exporters/` is an empty namespace marker
+(1 LOC, no implementation) — F8 export logic actually lives in
+`processors/export.py`, not `exporters/`.
+
+---
+
+## B. TESTS
+
+**Method (collection):** `.venv/Scripts/python -m pytest --co -q | tail -5`.
+**Method (run):** `.venv/Scripts/python -m pytest -q`.
+**Method (coverage):** `.venv/Scripts/python -m pytest --cov=bijotel --cov-report=term-missing -q`.
+
+### Totals (raw evidence)
+
+- Collected: `211 tests collected in 0.36s`
+- Run result: `209 passed, 2 skipped in 12.93s`
+  (a second independent run: `209 passed, 2 skipped in 12.63s`;
+  coverage run: `209 passed, 2 skipped in 14.61s`)
+- Wall time: ~12.6–14.6 s depending on coverage instrumentation
+  (non-coverage runs ~12.6–12.9 s).
+
+CHANGELOG v0.5.0 claim "209 passed, 2 skipped" — **VERIFIED, matches exactly.**
+Collected count is 211 (= 209 run + 2 skipped, consistent).
+
+### Per-file test count
+
+**Method:** `pytest --co -q | grep "::" | sed 's/::.*//' | sort | uniq -c | sort -rn`.
+
+| Test file | Count |
+|---|---|
+| test_openai_adapter.py | 18 |
+| test_regression.py | 17 |
+| test_prompt_pattern_deny.py | 16 |
+| test_cli.py | 16 |
+| test_policy_rules.py | 13 |
+| test_processors_export.py | 12 |
+| test_hmac_chain.py | 12 |
+| test_canonical.py | 12 |
+| test_decorators_trace_genai.py | 10 |
+| test_policy_rate_limit.py | 9 |
+| test_cli_cost_calc.py | 9 |
+| test_anthropic_adapter.py | 9 |
+| test_cli_export.py | 8 |
+| test_cli_helpers.py | 7 |
+| test_provider_base.py | 6 |
+| test_policy_decision.py | 6 |
+| test_decorators_extractors.py | 6 |
+| test_cas.py | 6 |
+| test_trace_genai_provider_integration.py | 5 |
+| test_policy_guard.py | 5 |
+| test_policy_engine.py | 4 |
+| test_core_init.py | 3 |
+| test_smoke.py | 2 |
+| **Sum** | **211** |
+
+### Coverage
+
+**Method:** `.venv/Scripts/python -m pytest --cov=bijotel --cov-report=term-missing -q` (term-missing TOTAL line).
+
+Raw evidence (exact TOTAL line):
+```
+TOTAL                                        1340     74    94%
+```
+
+- Overall coverage: **94%** (1340 statements, 74 missed).
+- Modules <90% (the only one): `regression/baseline.py` = **91%**
+  (90 stmts, 8 miss; missing 83, 87, 93, 96, 140, 160-161, 171).
+- Lowest-but-≥90% cluster: `cli/commands.py` 90%, `regression/detector.py` 93%,
+  `adapters/anthropic_adapter.py` 93%, `processors/export.py` 93%,
+  `decorators/trace_genai.py` 93%.
+- `policy/prices.py` 92%, all other modules ≥94%; 16 modules at 100%.
+
+CHANGELOG v0.5.0 claim "coverage maintained ≥92%" — actual TOTAL is **94%**,
+which satisfies "≥92%" at the package level. **However**, one module
+(`regression/baseline.py`) is at 91%, below 92%. The CHANGELOG sentence is true
+as a package-level statement, false if read as a per-module floor.
+
+**REFRAMING (CHANGELOG v0.3.0 claim vs current):** v0.3.0 entry states
+"Coverage maintained at 94% overall (regression module: 91% baseline.py, 91%
+detector.py)". Current measured: overall 94% (matches), `baseline.py` 91%
+(matches), but `detector.py` is now **93%**, not 91% — improved since v0.3.0,
+CHANGELOG not updated. Direction is favorable (drift is an improvement, not a
+regression).
+
+### Skipped tests (2) — identities + reasons
+
+**Method:** `.venv/Scripts/python -m pytest -q -rs`.
+
+| Test | File:line | Skip reason (verbatim from `@pytest.mark.skipif`) |
+|---|---|---|
+| `test_adapter_complete_smoke_real_call` | tests/test_anthropic_adapter.py:127 (marker @123) | "ANTHROPIC_API_KEY not set — skipping smoke" |
+| `test_openai_adapter_complete_smoke_real_call` | tests/test_openai_adapter.py:306 (marker @302) | "OPENAI_API_KEY not set — skipping real OpenAI smoke" |
+
+Both skips are conditional on absence of provider API keys (live-network smoke
+tests). They are expected skips in a no-credentials environment, not failures.
+A third conditional skip exists in `tests/test_cli.py:271`
+(`pytest.skip` if the `bijotel` console-script is not found in the venv) — it
+did NOT trigger here (the entry point is installed), so the count is 2.
+
+### Test classification (unit / integration / smoke)
+
+**Method:** read test files; classify by whether a test exercises a single
+unit in-process (unit), composes multiple components / spawns a subprocess
+(integration), or makes a real network LLM call (smoke).
+
+- **Smoke (real external API): 2** — `test_adapter_complete_smoke_real_call`,
+  `test_openai_adapter_complete_smoke_real_call`. Both skipped without keys.
+- **Integration (multi-component / subprocess, in-process or local): ~7**
+  - `tests/test_trace_genai_provider_integration.py` (5) — decorator + provider
+    adapter end-to-end through OTel.
+  - `tests/test_prompt_pattern_deny.py::test_prompt_pattern_deny_integration_with_policy_engine` (1)
+    — rule composed into `PolicyEngine`.
+  - `tests/test_cli.py::test_cli_entry_point_via_subprocess` (1) — spawns the
+    real `bijotel` binary via `subprocess.run`.
+- **Unit: remaining ~202** — single-module, in-process assertions
+  (canonical, cas, hmac_chain, policy rules/decision/engine/guard, extractors,
+  regression baseline/detector, CLI command handlers invoked as
+  `main(argv)` directly, etc.). `tests/test_smoke.py` (2) is named "smoke" but
+  is an import/packaging unit check (no network), counted as unit.
+
+---
+
+## C. CI/CD
+
+**Method:** read `.github/workflows/ci.yml`; `gh run list --limit 10`.
+
+### Workflows
+
+Only one workflow file: `.github/workflows/ci.yml` (job name `test`).
+
+Triggers (from yaml):
+- `push` to branch `main`
+- `pull_request` targeting `main`
+- No `schedule` / cron. No manual `workflow_dispatch`.
+
+Pipeline steps: checkout@v4 → setup-python@v5 (Python **3.11**) →
+`pip install -e ".[dev,anthropic]"` → `ruff check .` → `pytest -v`.
+Note: CI installs `[dev,anthropic]` but NOT `[openai]`; CI runs on Python 3.11
+whereas this audit's local venv is Python 3.12.10.
+
+### Last 10 CI runs
+
+**Method:** `gh run list --limit 10` (account octavuntila-prog).
+
+| Date (UTC) | Trigger | Branch | Conclusion | Duration | Commit subject |
+|---|---|---|---|---|---|
+| 2026-05-14T09:22:09Z | push | main | success | 30s | F11 (v0.5.0) prompt_pattern_deny |
+| 2026-05-11T10:47:59Z | push | main | success | 33s | F9 (v0.4.0) OpenAIAdapter |
+| 2026-05-10T12:49:52Z | push | main | success | 23s | F12 (v0.3.0) Regression Detection |
+| 2026-05-10T11:46:04Z | push | main | success | 22s | fix(test) rename loop var (ruff B007) |
+| 2026-05-10T11:45:28Z | push | main | **failure** | 21s | v0.2.1 cost fix + docs + coverage |
+| 2026-05-10T11:16:24Z | push | main | success | 29s | F8 export + rate_limit (v0.2.0) |
+| 2026-05-10T10:20:45Z | push | main | success | 19s | docs: CHANGELOG for v0.1.0 |
+| 2026-05-10T10:01:08Z | push | main | success | 29s | F7 Provider Protocol + AnthropicAdapter |
+| 2026-05-10T07:59:48Z | push | main | success | 26s | validation: e2e smoke test |
+| 2026-05-07T21:57:34Z | push | main | success | 30s | F5 @trace_genai + wrap |
+
+- Pass/fail: **9 success / 1 failure** over last 10 → **pass rate 90.0%**.
+- All 10 triggered by `push` to `main` (0 pull_request runs in the window).
+- Mean duration: (30+33+23+22+21+29+19+29+26+30)/10 = **26.2 s**.
+- The single failure (v0.2.1, 2026-05-10T11:45:28Z) is followed by an
+  immediate fix run (`fix(test): rename unused loop var i -> _i (ruff B007)`,
+  +18 min, success) — the failure was a ruff B007 lint error, remediated in the
+  next push. Current HEAD (F11) CI is green.
+
+---
+
+## D. VERSIONS
+
+**Method:** `git log --oneline -30`, `git tag -l`,
+`git for-each-ref --format='%(refname:short) %(objectname:short) %(*objectname:short)' refs/tags`,
+`git rev-list -n 1 v0.5.0`, `git show --no-patch --format=... v0.5.0`.
+
+### Tags
+
+`git tag -l`: v0.1.0, v0.2.0, v0.2.1, v0.3.0, v0.4.0, v0.5.0 (6 tags).
+All six are **annotated** tags (tagger: Octavian Untilă).
+
+### Tag → commit mapping (dereferenced)
+
+| Tag | Tag-object SHA | Target commit | Commit subject |
+|---|---|---|---|
+| v0.1.0 | 04e3894 | 29e655d | docs: CHANGELOG for v0.1.0 |
+| v0.2.0 | ef3606d | 4855e6b | F8 Portable export + rate_limit (v0.2.0) |
+| v0.2.1 | d465d01 | cc16d45 | v0.2.1 cost field fix + README + CLI coverage |
+| v0.3.0 | e2238c0 | af2dbca | F12 Regression Detection (Bijuteria #16) |
+| v0.4.0 | 5f4416b | 889b4ab | F9 OpenAIAdapter |
+| v0.5.0 | a99a99d | **0bffb6c** | F11 prompt_pattern_deny |
+
+### v0.5.0 → F11 commit verification
+
+- `git rev-list -n 1 v0.5.0` → `0bffb6cc32ef1dc6d383090024a904578412d9be`.
+- `git show --no-patch --format` on v0.5.0 → `commit=0bffb6c...`,
+  `subject=F11 (v0.5.0): prompt_pattern_deny rule`.
+- **VERIFIED: v0.5.0 resolves to commit `0bffb6c` = the F11 commit.** Match.
+
+**REFRAMING (audit-method nuance, NOT a repo defect):** The exact command in
+the audit brief, `git for-each-ref --format='%(refname:short) %(objectname:short)' refs/tags`,
+prints `v0.5.0 a99a99d`. `a99a99d` is the **annotated-tag object** SHA, not the
+commit. Reading that line literally would falsely conclude "v0.5.0 does NOT
+point at 0bffb6c". The correct resolution requires dereferencing with
+`%(*objectname:short)` (or `git rev-list -n 1`), which yields `0bffb6c`. Claimed
+target (0bffb6c) and actual target (0bffb6c) **agree**. No tag drift.
+
+### Version-string consistency
+
+| Source | Value | Method |
+|---|---|---|
+| `pyproject.toml` `[project].version` | 0.5.0 | read line 3 |
+| `src/bijotel/__init__.py` `__version__` | 0.5.0 | read line 31 |
+| `tests/test_smoke.py` assertion | `== "0.5.0"` | read line 8 |
+| CHANGELOG latest entry | `[0.5.0] — 2026-05-14` | read line 8 |
+| Latest git tag | v0.5.0 | `git tag -l` |
+
+All five agree on `0.5.0`. No version drift. CHANGELOG version entries
+([0.1.0]..[0.5.0]) map 1:1 onto the six git tags — no missing tag, no
+untagged CHANGELOG entry, no extra tag.
+
+---
+
+## E. DEPENDENCIES
+
+**Method:** read `pyproject.toml`; `.venv/Scripts/python -m pip_audit --version`
+(unavailable); `.venv/Scripts/python -m pip check`;
+`.venv/Scripts/python -m pip list --outdated`. No installs performed
+(read-only constraint honored).
+
+### Declared dependencies (pyproject.toml)
+
+Required (`[project].dependencies`) — all `>=` (unpinned lower bound, no upper cap):
+- `opentelemetry-api>=1.27.0`
+- `opentelemetry-sdk>=1.27.0`
+- `opentelemetry-semantic-conventions>=0.48b0`
+- `rfc8785>=0.1.4`
+
+Optional extras:
+- `[anthropic]`: `anthropic>=0.40.0`, `opentelemetry-instrumentation-anthropic>=0.40.0`
+- `[openai]`: `openai>=1.0`
+- `[all]`: union of `[anthropic]` + `[openai]`
+- `[dev]`: `pytest>=8.0`, `ruff>=0.6.0`, `python-dotenv>=1.0.0`
+
+### Pinned vs unpinned
+
+100% of declared deps use `>=` (minimum-version) constraints. **Zero `==`
+pins** and **zero upper bounds** anywhere in `pyproject.toml`. There is no
+lockfile (no `requirements.txt`, no `uv.lock`/`poetry.lock` in repo root).
+
+### Audit tooling results
+
+- `pip_audit`: NOT installed in venv (`No module named pip_audit`); install
+  disallowed by audit constraint. Known-CVE scan: **unknown** (tool absent).
+- `pip check`: **"No broken requirements found."** (dependency graph
+  internally consistent).
+- `pip list --outdated` (installed venv vs latest PyPI):
+
+| Package | Installed | Latest | Type |
+|---|---|---|---|
+| anthropic | 0.100.0 | 0.102.0 | wheel |
+| coverage | 7.13.5 | 7.14.0 | wheel |
+| idna | 3.13 | 3.15 | wheel |
+| importlib_metadata | 8.7.1 | 9.0.0 | wheel |
+| openai | 2.36.0 | 2.37.0 | wheel |
+| ruff | 0.15.12 | 0.15.13 | wheel |
+
+Six packages are behind latest; all are minor/patch deltas. None is a core
+runtime dep of bijotel with a security advisory known to this audit (CVE
+verification is **unknown** without pip_audit).
+
+### Risk flags
+
+- The four **core runtime deps are unpinned with no upper bound**
+  (`opentelemetry-*`, `rfc8785`). OpenTelemetry has historically shipped
+  breaking changes in `0.x` semantic-conventions (`>=0.48b0` is a beta
+  pre-release spec); an unbounded `>=` allows a future incompatible OTel
+  semconv release to be resolved at install time. This is the single
+  highest-risk dependency posture finding. `rfc8785>=0.1.4` is also a `0.x`
+  package (no API-stability guarantee) consumed for canonicalization that the
+  HMAC chain integrity depends on.
+- No lockfile means CI (which does a fresh `pip install -e ".[dev,anthropic]"`
+  on every push) is not reproducible across time — the green/red history in
+  section C is against floating dependency versions.
+
+---
+
+## F. PUBLIC API
+
+**Method:** read `src/bijotel/__init__.py` `__all__` and
+`src/bijotel/policy/__init__.py` `__all__`; per symbol
+`grep -c -w "<sym>" README.md` plus plain `grep -n` verification for
+zero-hit symbols; `git show v0.4.0:src/bijotel/__init__.py` vs current.
+
+### Exported symbols and README documentation status
+
+`bijotel.__all__` has 25 entries (24 symbols + `__version__`).
+`bijotel.policy.__all__` has 9 entries (all re-exported at top level).
+
+| Symbol | Exported from | In README? |
+|---|---|---|
+| `__version__` | bijotel | n/a (dunder, not user-facing API) |
+| Anomaly | bijotel ← regression | **NO** |
+| AnomalyMethod | bijotel ← regression | yes |
+| AnthropicAdapter | bijotel ← adapters | yes |
+| Decision | bijotel ← policy | yes |
+| DimensionStats | bijotel ← regression | **NO** |
+| OpenAIAdapter | bijotel ← adapters | yes |
+| PolicyDeniedError | bijotel ← policy | yes |
+| PolicyEngine | bijotel ← policy | yes |
+| Provider | bijotel ← adapters | yes |
+| ProviderResponse | bijotel ← adapters | yes |
+| RegressionDetector | bijotel ← regression | yes |
+| compute_baseline | bijotel ← regression | **NO** |
+| cost_per_call_max | bijotel ← policy | yes |
+| daily_token_budget | bijotel ← policy | yes |
+| export_chain | bijotel ← processors | yes |
+| guard | bijotel ← policy | yes |
+| init | bijotel ← core | yes |
+| model_allowlist | bijotel ← policy | yes |
+| prompt_pattern_deny | bijotel ← policy | yes |
+| rate_limit_calls_per_minute | bijotel ← policy | yes |
+| shutdown | bijotel ← core | yes |
+| trace_genai | bijotel ← decorators | yes |
+| verify_export | bijotel ← processors | yes |
+| wrap | bijotel ← decorators | yes |
+
+`bijotel.policy.__all__` (Decision, PolicyDeniedError, PolicyEngine,
+cost_per_call_max, daily_token_budget, guard, model_allowlist,
+prompt_pattern_deny, rate_limit_calls_per_minute) — all 9 are documented in
+README (same symbols, re-exported at top level).
+
+### Undocumented exports — flagged
+
+**Method:** `grep -n "<sym>" README.md` (plain, not word-bounded) confirms zero
+standalone occurrences.
+
+- **`Anomaly`** — README contains `AnomalyMethod` but NO standalone `Anomaly`
+  dataclass mention. The public `Anomaly` record type (single detection record
+  returned by `RegressionDetector`) is undocumented.
+- **`DimensionStats`** — zero occurrences in README. Undocumented (it is the
+  return type of `compute_baseline()` and is in `__all__`).
+- **`compute_baseline`** — zero occurrences in README. Undocumented public
+  function.
+
+3 of 24 user-facing exports (all in the F12 regression surface) are absent from
+README. README documents `RegressionDetector`/`AnomalyMethod`/`bijotel
+regression` CLI but omits the `Anomaly`, `DimensionStats`, `compute_baseline`
+symbols it also exports.
+
+**REFRAMING (CHANGELOG v0.2.1 vs reality):** The v0.2.1 CHANGELOG entry claims
+"README sections added for 6 previously-undocumented public API exports"
+and frames documentation as caught up. As of current HEAD, **3 exported symbols
+(`Anomaly`, `DimensionStats`, `compute_baseline`, all added later in F12/v0.3.0)
+remain undocumented in README**. The "all public exports documented" posture
+implied by v0.2.1 does not hold at v0.5.0; the F12 export surface regressed
+documentation parity.
+
+### Breaking-change / `__all__` growth across releases
+
+**Method:** `git show v0.4.0:src/bijotel/__init__.py` diffed against working
+tree `src/bijotel/__init__.py`.
+
+- v0.4.0 `__all__`: 24 entries. v0.5.0 `__all__`: 25 entries.
+- Sole delta: **`prompt_pattern_deny` added** (top-level + `policy.__all__`).
+  This is an **additive** change — no symbol removed, no signature change to
+  existing exports. CHANGELOG v0.5.0 "Changed" explicitly documents this
+  addition.
+- Therefore v0.4.0 → v0.5.0 is backward-compatible at the `__all__` boundary;
+  the minor-version bump (0.4.0 → 0.5.0) is correct under SemVer. **No
+  undocumented breaking change found** in the v0.4.0 → v0.5.0 transition.
+- Earlier growth per CHANGELOG (each documented in its release's "Changed"):
+  v0.2.0 +`export_chain`/`verify_export`/`rate_limit_calls_per_minute`;
+  v0.3.0 +`RegressionDetector`/`Anomaly`/`AnomalyMethod`/`DimensionStats`/`compute_baseline`;
+  v0.4.0 +`OpenAIAdapter`; v0.5.0 +`prompt_pattern_deny`. All `__all__` changes
+  across the tagged history are additive — no export was ever removed or
+  renamed across v0.1.0→v0.5.0, so there is no silent breaking change in the
+  public surface.
+
+---
+
+## SUMMARY OF REFRAMINGS
+
+1. **Subpackage scope** — prompt's subpackage list omits the real
+   `decorators/` subpackage (394 LOC, F5); `exporters/` is an empty 1-LOC
+   marker, F8 export code is in `processors/export.py`.
+2. **Coverage per-module floor** — CHANGELOG "coverage maintained ≥92%" holds
+   at package level (94%) but `regression/baseline.py` is 91% (<92%).
+3. **CHANGELOG v0.3.0 detector.py coverage** — claimed 91%, actual 93%
+   (improved, CHANGELOG stale; favorable drift).
+4. **v0.5.0 tag resolution method** — the brief's `for-each-ref` command prints
+   the annotated-tag object SHA `a99a99d`, not the commit; correct dereferenced
+   target is `0bffb6c` (= F11). Tag is correct; the audit *method* needs
+   dereferencing. No actual drift.
+5. **Undocumented exports vs v0.2.1 "docs caught up" framing** — `Anomaly`,
+   `DimensionStats`, `compute_baseline` (F12 surface) are in `__all__` but
+   absent from README; v0.2.1's documentation-parity posture does not hold at
+   v0.5.0.
+
+## VERIFIED CRITICAL NUMBERS (raw)
+
+- pytest total: `209 passed, 2 skipped in 12.93s` (collected `211 tests collected`)
+- coverage TOTAL: `TOTAL                                        1340     74    94%`
+- CI pass rate (last 10): 9/10 = 90.0%; mean duration 26.2 s; all push-triggered
+- v0.5.0 tag → commit `0bffb6c` (F11) — VERIFIED via `git rev-list -n 1 v0.5.0`
+- LOC: src/ = 3625, tests/ = 3807, whole project (.py, excl .venv/.git) = 13826
+- 2 skips: ANTHROPIC_API_KEY missing (test_anthropic_adapter.py:127),
+  OPENAI_API_KEY missing (test_openai_adapter.py:306)
+
+— end DOC 01 —

bijotel-1.0.0/.audit_tmp/03_GAPS.md

@@ -0,0 +1,104 @@
+# DOC 03 — GAPS | BIJOTEL Production-Readiness Audit T+7d | 2026-05-17
+
+Generated-at (UTC): 2026-05-17T07:40:00Z
+Scope: what is missing for BIJOTEL to be production-ready for a *different* consumer (ARA-class: on-demand + concurrent + multi-provider + policy-enforcing). GENA empirical behavior is in DOC 02; codebase state in DOC 01.
+Method note: every gap below carries how it was established. No speculative language — "is" or "unknown" only.
+
+---
+
+## CENTRAL NARRATIVE
+
+BIJOTEL is **empirically excellent as a passive low-concurrency Anthropic observer** (DOC 02: 0/2776 chain mismatches, exact in-window dual-observer match, zero added cost, flat memory over ~166 h). It is **not yet proven production-ready for an ARA-class consumer**, for seven concrete reasons documented below. The single most important fact: **the artifact running in production is `bijotel 0.0.1`, not the audited v0.5.0** — "shipped" never became "deployed."
+
+---
+
+## A. KNOWN BUGS / FIXMES / TODOs
+
+Method: `Grep "TODO|FIXME|XXX|HACK|NotImplementedError|deferred to F"` over `src/`.
+
+- **Zero** dangling code markers in `src/` — no TODO/FIXME/XXX/HACK/NotImplementedError. Positive finding: the codebase carries no acknowledged in-code debt.
+- All deferrals (streaming, tool-use, vision, multi-provider) live **only** in CHANGELOG "Known Limitations" / README prose — **not surfaced in code** (no `warnings.warn`, no guard on the streaming path). A caller using an unsupported path gets silent partial behavior, not a signal.
+- Severity: LOW (no code-level bug markers); the doc-only-deferral is a documentation/ergonomics gap, not a bug.
+
+## B. MISSING FEATURES PROMISED
+
+Method: README Roadmap vs DOC 01 code-presence verification vs DOC 02 deployed-version check.
+
+- **CRITICAL — deploy gap:** README/CHANGELOG mark F0–F12 + F11 done; DOC 01 confirms code present for all; **DOC 02 confirms production runs 0.0.1**. F8 (export), F9 (OpenAIAdapter), F11 (prompt_pattern_deny), F12 (regression) **exist in repo + wheel but were never deployed**. The implicit "v0.5.0 in production 7 d" premise is false.
+- Documented-deferred (still open since v0.1.0, honestly listed, not silently missing): streaming responses, tool-use handling, vision/multimodal, concrete adapters beyond Anthropic/OpenAI (Gemini/Bedrock/Mistral), `registry.py` adapter lookup.
+
+## C. DOCUMENTATION GAPS
+
+Method: DOC 01 README cross-check; new-developer read-through.
+
+- 3 public exports undocumented in README: `Anomaly`, `DimensionStats`, `compute_baseline` (F12 surface in `__all__`). Contradicts v0.2.1 CHANGELOG "docs caught up."
+- No deployment / version-pinning guidance anywhere. Production silently drifted to 0.0.1 and **nothing in the project documents how a host installs/upgrades the wheel** (the `/opt/substrate-v2/` wheel-install pattern is undocumented).
+- New-dev sticking points (where a fresh integrator gets stuck): (i) SpanProcessor failure semantics — what happens if `on_end` throws? (undocumented); (ii) shared-db multi-process safety (undocumented, see F); (iii) HMAC secret rotation (no procedure).
+
+## D. TEST GAPS
+
+Method: DOC 01 coverage run + `Grep` test inventory.
+
+- Package coverage 94%, but `regression/baseline.py` = **91% (below the CHANGELOG-claimed ≥92% floor)**.
+- **Zero** tests for: streaming responses; concurrent / multi-thread writes; **multi-process writers on one shared chain.db** (the exact GENA topology — 4 processes, 1 db — is untested); SpanProcessor exception injection; sqlite-locked / disk-full error paths.
+- No real-traffic integration test; no stress test (≥1000 calls/min). GENA peak ≈ 432/day ≈ 0.3/min, so **neither tests nor production have ever exercised concurrency**.
+- 2 skipped tests = API-key-gated smoke (expected, benign).
+
+## E. SECURITY POSTURE
+
+Method: code read (`hmac_chain.py`) + GENA `stat`/`printenv` (read-only).
+
+- HMAC secret: min-16-byte enforced (`ValueError`); deployed via container env `BIJOTEL_HMAC_SECRET` (32 bytes). Exposed to `printenv` / `docker inspect` (standard); **no rotation mechanism** in the library.
+- **chain.db is mode 644 (world-readable)**, root:root, ~33 MB, on a shared docker volume. `canonical_body` BLOB holds full span payloads (prompts/responses). Any user/container with volume access can read audit content. The library does **not** set restrictive (0600) permissions on db creation.
+- No secrets-in-logs issue: the processor logs nothing (`on_end` is silent).
+- **Dependency CVE exposure: UNKNOWN** — `pip-audit` not installed and installs were disallowed for this read-only audit. Core deps (`opentelemetry-*`, `rfc8785`) are unpinned `>=` with no upper bound and **no lockfile** → supply-chain drift risk + unaudited CVE surface.
+
+## F. OPERATIONAL READINESS
+
+Method: code read of `HmacChainSpanProcessor.on_end` + DOC 02 empirical contiguity.
+
+- **CRITICAL (latent) — no crash isolation.** `on_end()` has **no try/except**. A sqlite failure (lock/disk/permission) or canonicalization error raises into the OTel span-processor path. In GENA this never triggered (low rate, healthy disk). For a higher-volume consumer an `on_end` exception can disrupt the host's LLM call path. No defensive boundary, no degraded mode. Empirically un-hit ≠ safe.
+- **CRITICAL (latent) — multi-writer race.** One shared chain.db is written by 4 container processes; concurrency is guarded **only by a per-process `threading.Lock`**. The `SELECT prev_hash → INSERT` sequence is **not atomic across processes**; SQLite serializes commits but the stale-read window permits a chain fork. **Empirically NOT manifested in GENA** (DOC 02: seq 1..2776 contiguous, `verify_chain`=VALID, 0/100 manual HMAC mismatch) because GENA's cron-driven workload is effectively serialized and low-rate. An ARA-class on-demand concurrent pattern is precisely the trigger. Unguarded + untested = unproven.
+- **No backup / DR.** Single SQLite file on one docker volume; no replication, rotation, or backup. Tamper-evident ≠ durable — disk loss = total audit-trail loss. No documented recovery.
+- **No self-observability.** The library emits no health signal; "is the chain advancing / intact?" is answerable only by an external query (as this audit did). No heartbeat/metric.
+
+## G. CROSS-CONSUMER GENERALIZATION
+
+Method: GENA profile from DOC 02; ARA profile from task brief.
+
+| Dimension | GENA (validated in prod) | ARA (assumed target) |
+|---|---|---|
+| Trigger | cron-driven, serialized | on-demand |
+| Concurrency | ~0.3 calls/min, effectively 1 writer at a time | potentially concurrent, multi-writer |
+| Provider | Anthropic only | multi-provider |
+| Policy | unwired (observer-only, 0 denies ever) | likely enforcing |
+| Streaming | not used | unknown |
+
+**Tested (in prod):** Anthropic request/response extraction (2776/2776), passive chain integrity at low rate, flat memory, zero added cost.
+**Untested anywhere:** concurrent writers, live policy enforcement, OpenAI adapter in prod (0.0.1 lacks it), streaming, crash recovery, multi-provider, high rate.
+**Honest verdict:** BIJOTEL is proven *only* for the passive / low-concurrency / Anthropic / observer pattern. Every ARA-distinct dimension is unproven.
+
+## H. PYPI READINESS
+
+Method: local `python -m build` + wheel METADATA inspection + `pip check`.
+
+- Wheel builds clean: `bijotel-0.5.0-py3-none-any.whl`. METADATA valid (Metadata-Version 2.4, `Description-Content-Type: text/markdown` → README renders on PyPI, `Requires-Python: >=3.11`, deps + 4 extras correct). `pip check` clean.
+- Gaps: **zero `Classifier`** (no Development Status / Python 3.11–3.12 / License::OSI::MIT / Topic / Intended Audience), **zero `Project-URL`** (no Homepage/Repo/Changelog/Issues), no `Keywords`. Not install-blocking; poor public listing + no discoverability.
+- `twine` absent from toolchain → no pre-publish validation step in CI.
+- Verdict: technically publishable, not polished. Metadata completeness ≈ 30-min fix.
+
+---
+
+## GAP SEVERITY ROLLUP
+
+| # | Gap | Severity | Blocks ARA? |
+|---|---|---|---|
+| F1 | `on_end` no crash isolation | CRITICAL (latent) | YES |
+| F2 | Multi-writer race on shared db | CRITICAL (latent) | YES (if concurrent) |
+| B1 | Prod = 0.0.1, not v0.5.0; no deploy pipeline/alarm | CRITICAL (process) | YES |
+| D1 | Zero concurrency/streaming/crash tests | HIGH | YES |
+| E1 | Deps unpinned, no lockfile, CVE status unknown | HIGH | YES |
+| F3 | No backup/DR for audit chain | MEDIUM | depends on retention need |
+| E2 | chain.db world-readable (644) | MEDIUM | depends on threat model |
+| C1 | Undocumented exports + no deploy docs | LOW | NO |
+| H1 | Thin PyPI metadata | LOW | NO (publish-only) |