Implement opt-in persistent MCP interaction observability

docs/plans/mcp-observability/execution-ledger.md

@@ -0,0 +1,70 @@
+# Execution ledger
+
+2026-10-14: Read issue #3 and all comments (none) via authorized GitHub access.
+Cloned Coding-Standards separately; baseline 188beda1fa477d21d576c233dd8c7f4c4c267d23.
+Core/Router, selected owners, MCP/catalog/runtime identity, contract discovery,
+input feedback and observer-v3 qualification/reconciliation inspected.
+Python 3.12.14 is inside the declared >=3.11,<3.13 range.
+User subsequently explicitly authorized push + PR after testing and review;
+merge and deployment remain excluded. No other repository modified.
+
+2026-10-14: Implemented one recorder boundary and operator report;22 focused
+synthetic tests passed on Python 3.12.14 in 27.628 s. Independent GPT-6.1 Sol High
+review accepted exact source hashes after resolving seven findings, including
+rejection of prior private SQLite remnants. Observer-v3 suites passed 39 tests
+in 19.044 s. Contract projection check passed. Verifier initially exposed stale
+README/source input digests; refreshed through public verify_repository debug
+transport, then 73 suites/121 checks passed. Generated suite-inputs manifest added
+to allowed adjacent write set. Full Engine run remains active; baseline fixture
+failure I1 reproduced on a clean independent baseline clone, unchanged by this
+feature. Four-mode cold baseline/candidate comparison preserved counts, outputs
+and exact serialized byte totals. No raw traces or databases are deliverables.
+
+2026-10-14: Final focused recorder+MCP+runtime-identity run passed 40 tests in 42.362 s
+(23 recorder,13 MCP,4 runtime identity). Final constants use one owner with the
+same defaults; reviewer accepted and rebound exact source hashes. Repeated
+four-configuration baseline/candidate response comparison passed on final source.
+The broad Engine run completed 93 tests (one known baseline failure), then was
+interrupted during the next owner module to parallelize remaining independent
+modules in four isolated Python processes. The interrupted case is re-run in full
+with its module; only completed prior modules count toward aggregate coverage.
+No interrupted case is counted as passed. All test stores are private temporary
+resources. Generated inputs refreshed after staging new module membership;
+verify_repository returned 73 suites/121 checks passed. Source, docs, synthetic
+tests, staged scope and sensitive-file risk reviewed before the implementation
+commit; no database, raw interaction log, secret or personal configuration staged.
+
+2026-10-14: Accepted local implementation boundary at e2334869. Broad aggregate
+coverage completed 636 cases (93 completed serial prefix +543 remaining),635
+qualified passes and the unchanged baseline I1 failure. Initial efficiency child
+launch without CI's PYTHONPATH=. failed equally on baseline/candidate; both passed
+with that declared environment. No additional feature failure remained. Final
+contract projection and73-suite/121-check verifier passed. Exact independent
+review bindings still match committed sources. CLI GitHub authentication reports
+invalid GH_TOKEN (I2); no push/PR or fallback credential/connection attempted.
+Local scope is complete, publication externally blocked. Final evidence commit
+retains clean source/branch and sanitized reports for parent; bundle outside repo
+preserves exact committed ref. Parent owns subsequent publication/merge.
+
+2026-10-14: Parent approved bounded I1 repair for PR #4 after prior service failures.
+Verified real checkout read/write/fsync, clean branch/head and remote PR head
+4887b7af; no workspace recovery or duplicate push needed. Revisited I1 disposition
+under explicit follow-up authority. Fixture now resolves POLICY from its immutable
+compiled snapshot, asserts existence and selects semantic_revision and its single
+successor before the existing counting mocks. Production validator, normative
+content and both count assertions are unchanged. Failing case, analysis module,
+full Engine suite and independent review are required before the next commit/push.
+
+2026-10-15: Fixture repair qualified. Owner targeted case passed 1 test in 3.748 s;
+independent targeted case passed in 3.676 s. Refreshed the registered test input
+through public Engine verify_repository; staged the new review report membership
+and refreshed again before freezing inputs. The initial analysis/full attempts
+with stale generated input were interrupted and are not acceptance evidence.
+Final analysis module passed 23 tests in 113.275 s. One uninterrupted full serial
+Engine invocation passed all 636 tests in 2161.675 s under PYTHONPATH=.; the formerly
+failing case and all observer-v3 tests passed in that run. Independent review bound
+test_analysis.py SHA256 7f51e403f03f5c57be8b1ca5736a79bcf139c87dd9eb4703ce3f7e59f1ba3d01.
+No production, validator or normative edits; both call-count assertions unchanged.
+Final evidence retains the historical I1 failure and resolves prior I2 transport
+confusion. Reviewed bounded staged scope before committing for approved PR #4
+branch push; publication identity is the Git ref, merge remains parent-owned.

docs/plans/mcp-observability/issues.md

@@ -0,0 +1,39 @@
+# Findings
+
+## I1 — baseline proposal-analysis fixture (medium, resolved)
+
+`test_analysis.AnalysisWorkflowTest.test_proposal_analysis_uses_one_projection_and_one_verified_base`
+originally hardcoded accepted semantic revision 1/proposed 2. Both the candidate and a clean
+Git clone of baseline `188beda1fa477d21d576c233dd8c7f4c4c267d23` return
+`AUTHORING.INVALID_SEMANTIC_REVISION` before the test reaches its projection-count
+assertions. Independent one-test baseline run:1 test, 1 failure, 1.397 s; candidate:
+1 test, 1 failure, 1.606 s. At initial handoff head 4887b7af this source test was unchanged by issue3.
+
+Owner: analysis fixture maintainers. Parent explicitly authorized this bounded
+follow-up for PR #4. Disposition: resolved by deriving the accepted semantic
+revision and its successor from the same immutable snapshot used for the proposal,
+before the counting mocks. Policy existence, real proposal/analysis results and
+both count assertions remain required. Validator and normative content unchanged.
+The targeted case passed (3.748 s), all 23 analysis tests passed (113.275 s), and
+the full serial Engine suite passed all 636 tests (2161.675 s). Independent fixture
+review passed; see reports/fixture-review.md. Historical baseline failure evidence
+above remains retained rather than relabeled as a baseline pass.
+
+## Resolved review findings
+
+Independent reviewer found and verified resolution of R1–R7: diagnostic field
+binding, malformed-envelope coverage, measurement failure, normal retention loss,
+report scope/bounds, pre-migration capability checks and residual private SQLite
+content. See reports/independent-review.md for source-bound evidence.
+
+Actual model/client traces are outside this task: synthetic process evidence does
+not certify model intent or acquisition. No new model qualification is claimed.
+
+## I2 — publication authentication (resolved)
+
+The GitHub CLI reported an invalid configured `GH_TOKEN`, initially treated as a
+publication blocker. A later explicitly authorized attempt through the existing
+Git remote succeeded without inspecting/copying tokens or changing authentication.
+Remote head 4887b7af was verified and the parent opened draft PR #4. The CLI failure
+did not establish failure of the separate Git transport. Existing bundle and
+checkout were preserved; subsequent publication uses the approved Git branch.

docs/plans/mcp-observability/plan.md

@@ -0,0 +1,144 @@
+# Persistent MCP interaction observability (issue 3)
+
+Status: Accepted (local fixture qualification). Acceptance: satisfied. Operation: verify. Owner: implementation agent;
+publication and merge authority remain with the parent/operator. Baseline:
+`188beda1fa477d21d576c233dd8c7f4c4c267d23` (interface 46).
+Canonical plan: `docs/plans/mcp-observability/plan.md`.
+
+## Objective and authority
+
+Implement opt-in, local, agent-invisible SQLite observations at the existing MCP
+boundary. Keep domain transactions, tools, outcomes, protocol, retries, generated
+contracts, normative standards and observer-v3 qualification unchanged. No model
+calls, Tuldok changes, installation configuration or live telemetry collection.
+The subsequent user approval permits pushing the verified feature branch and
+opening a PR containing only code, synthetic tests and sanitized documentation.
+Parent owns merge. No deployment or enabling on existing installations.
+
+Private feature branch `feat/issue3-mcp-observability` in the separate clone
+`/workspace/Coding-Standards`; target `main`, integration owner parent. Retain
+branch/checkout for publication decision and review; no cleanup or history rewrite.
+No writes to Nearwork or other mounted repositories.
+
+## Routed owners and decisions
+
+Core and Router select implementation, verification/oracles, planning/discovery,
+proportionality, commit, documentation; library application, IPC and persistence; diagnostics,
+architecture, code-design, contracts/evolution/protocols, concurrency, security,
+resilience, performance and cross-platform. Python has no language profile.
+No normative or generated contract changes: no generated-contract profile,
+standards-authoring workflow, release or framework profile is needed.
+No AGENTS.md exists in this clone or its workspace ancestors. Runtime identity
+uses process UUID and exact catalog/schema/implementation digests, independent
+of Git/content authority. Observer v3 remains qualification evidence and retains
+its independent exact-source replay. No production dependency on test code.
+
+## Binding design
+
+- MCP owns request execution and response delivery. Recorder owns only sanitized
+  observations, SQLite transactions, retention and health. Operator CLI reads
+  that separate database; Engine stores and authorization remain untouched.
+- Explicit operator CLI configuration supplies a database in an existing trusted
+  directory and a deployment label. Omission creates no recorder/file. POSIX local
+  regular files only; reject symlinks, nonprivate files, unrelated databases and
+  unsupported schemas. The trusted directory must exclude concurrent hostile
+  path replacement. Same-user agents can read files: filesystem modes are damage
+  reduction, never an agent authorization boundary. Store no secrets regardless.
+- Schema v1: immutable interaction starts plus independent terminal events, joined
+  by generated UUID; process/session UUID and ordinal establish local chronology.
+  Sessions bind runtime metadata, deployment label and per-operation schema
+  digests. No client-supplied request IDs, names or paths are stored verbatim.
+- Pair end/error with begin only after response write/flush in stdio. Direct
+  dispatch records a constructed response (distinct delivery evidence). Parsing,
+  validation, typed rejection, tool exceptions and interruption are classified
+  without raw messages. Unmatched starts remain incomplete/unknown, including
+  process kill and response delivery failure; never infer completion on restart.
+- Bounded input shape: fixed schema-derived property names, scalar type markers,
+  depth/node/array caps; redact sensitive subtrees and unknown member names.
+  Never retain scalar values, arbitrary map keys, prompts, bodies, tokens,
+  credentials, outputs, exception messages or client metadata. Static schema
+  selector/operation names are admitted only by exact installed-catalog membership.
+  Feedback retains sanitized field pointers and fixed constraint keywords only.
+- No raw input digests (dictionary attacks). Shape digests identify structural
+  variants only. Catalog and implementation digests identify exact source material.
+  MCP has no legitimate cross-process session/task continuation in this server;
+  do not invent one from prompts or domain handles. Reports state that limitation.
+- Serial synchronous recorder, no queue/thread/retry. SQLite `BEGIN IMMEDIATE`
+  owns each mutation and rollback. Finite busy timeout and page quota; rollback
+  journal rather than unbounded WAL. Maximum retained interactions and age are
+  operator policies with bounded defaults; prune starts and events atomically.
+  Retention may evict unmatched observations and is explicitly reported.
+- Version 0 is accepted only for a zero-length new database and migrates transactionally
+  to v1. Existing v1 reopens intact; future/corrupt/unrelated databases fail open
+  without replacement. No inferred migration or automatic destructive recovery.
+- Recorder failure degrades once, disables further recording for that process,
+  and reports a fixed nonsensitive reason plus counters on operator stderr.
+  It never retries domain work or changes its return. Operator fixes storage and
+  restarts to recover recording. Health is independent of the failing database.
+- Read-only bounded JSON report: operation/error/shape counts, observed latency
+  and bytes, incomplete counts, discovery/failed-attempt sequences before a
+  later success in the same process/operation, catalog comparisons. Denominators
+  and delivery scope explicit. Correlation cannot prove intent, actual repair,
+  client acquisition, token usage or billing. Retained traces cannot reconstruct
+  redacted requests; observer v3 remains the source-backed replay authority.
+
+## Composed-design admission: applicable
+
+1. Independent concerns: MCP owns execution/delivery; recorder owns privacy,
+   observations and local retention; operator report owns read-only interpretation;
+   RuntimeIdentity/catalog own source/contract attribution. No observer-v3 coupling.
+2. Necessary interleaving: begin before dispatch, terminal after delivery, metadata
+   captured at recorder construction. Accidental coupling avoided: no Engine SQL,
+   tool registration, hidden model work or telemetry-driven domain decisions.
+3. Composition root knows configuration, immutable runtime/catalog and close;
+   dispatch/stdio know begin/finish lifecycle. Callers never own SQL or redaction.
+4. Privacy changes touch recorder/tests/docs; schema revisions flow through existing
+   catalog identity; delivery changes touch MCP integration; storage revisions
+   touch recorder migration and CLI together. Domain changes need no recorder edits.
+5. Stable runtime metadata crosses the seam; no store handles or validator internals.
+   Schema property vocabulary is diagnostic disclosure authority, not validation.
+6. Recorder can fail and be disabled independently; CLI reads across restart.
+   MCP remains independently usable. Tests exercise both enabled and omitted paths.
+7. Deleting recorder moves necessary privacy/storage/retention/lifecycle complexity
+   back into MCP, so retain it. No generic adapter registry, background worker,
+   second protocol, exported observer tool or migration framework is admitted.
+8. Inherent complexity is bounded evidence, privacy and SQLite lifecycle; keep it
+   in one production module plus its read-only reporting entrypoint, not harnesses.
+
+## Milestones and evidence
+
+A Accepted: design/source/privacy review; write set this plan directory only.
+B Accepted: recorder and MCP integration; write set
+`tools/standards_engine/standards_engine/{interaction_observer.py,mcp.py}`,
+`tools/standards_engine/tests/test_interaction_observer.py`. Gate: focused
+privacy, failure and outcome-preservation tests.
+C Accepted: operator report, configuration and operational documentation; same
+module plus `tools/standards_engine/MCP-OBSERVABILITY.md` and README link.
+Gate: bounded read-only report, catalog changes, accurate denominators.
+D Accepted: cold stdio/process replacement, exceptions/interruption, real unavailable,
+locked/full SQLite, concurrent processes, migration/retention/privacy. Existing MCP,
+runtime identity, discovery and observer-v3 tests plus full Engine suite and
+contract projection check. Synthetic baseline/candidate call and byte comparison.
+E Accepted: independent GPT-6.1 Sol High design/source/privacy review accepted with all seven findings resolved; staged and full branch review, local commits, authorized push and PR.
+No real logs or confidential artifacts in Git. Parent owns merge. The generated
+`evaluation/standards-effectiveness/generated/suite-inputs.json` is an allowed
+adjacent write: refresh through the Engine after staging declared inputs; it
+tracks source/README digests and is not a normative standards change.
+
+F Accepted: repair I1 using the actual policy semantic revision from the immutable
+snapshot, before entering the existing counting mocks. Write set:
+`tools/standards_engine/tests/test_analysis.py`, this plan/ledger/issues, a bounded
+fixture-review report and current verification evidence; generated verifier input
+manifest only if its compiler requires a refresh. Gate: failing case, analysis
+module and full Engine suite pass; independent review; reviewed commit/push to
+existing approved PR #4 branch. Validator, normative content and both count
+assertions remain unchanged. No telemetry activation or raw log publication.
+
+Current phase: complete local qualification. Next slice: none. Blockers: none.
+F evidence: targeted case passed; analysis module 23/23; full serial Engine suite
+636/636; independent fixture review satisfied. I1 is resolved without changing
+validator, normative content or either count assertion; historical baseline failure
+remains in issues/evidence. I2 resolved through the existing Git transport; parent
+opened PR #4. The verified follow-up is packaged for the explicitly approved branch
+push; Git/PR refs own publication identity and parent owns hosted CI/merge.
+See [verification](reports/verification.md), [fixture review](reports/fixture-review.md), [independent source/privacy review](reports/independent-review.md), [ledger](execution-ledger.md) and [issues](issues.md).

docs/plans/mcp-observability/reports/baseline-comparison.md

@@ -0,0 +1,18 @@
+# Synthetic baseline/candidate comparison
+
+Baseline: `188beda1fa477d21d576c233dd8c7f4c4c267d23`, extracted with `git archive` into an isolated temporary directory. Candidate: reviewed source hashes in [independent review](independent-review.md). Python 3.12.14; SQLite 3.53.1; locked dependency versions matched. No model/client session or real interaction log was collected.
+
+Each cold process received initialize, initialized notification, tools/list, describe_input(runtime_info), an invalid runtime_info request, a valid runtime_info request and ping. Six requests, one notification, three tool calls, six replies ; 688 sent stdio bytes. The operator recorder created only temporary synthetic databases, removed after the comparison.
+
+| Purpose | Output schemas | Baseline bytes | Candidate off | Candidate on | Replies equal |
+| --- | --- | ---: | ---: | ---: | --- |
+| authoring | eager | 753498 | 753498 | 753498 | yes |
+| authoring | on-demand | 115030 | 115030 | 115030 | yes |
+| application | eager | 89041 | 89041 | 89041 | yes |
+| application | on-demand | 22115 | 22115 | 22115 | yes |
+
+Comparison parsed every reply, including schema catalog, typed rejection, text content and runtime observations. Only process UUID and implementation digest were normalized: these must differ for distinct loaded sources/processes. Full JSON response byte totals matched without normalization. No tools, protocol messages, operation retries or domain results were added.
+
+One sample per configuration is outcome/byte preservation evidence, not a latency benchmark. Observed cold process times ranged from 852.56 ms to 1193.81 ms with other tests active. No throughput/overhead, token or billing claim is made.
+
+Reproduction: extract the named baseline with git archive; start the baseline MCP and candidate MCP with --purpose authoring/application and --output-schemas eager/on-demand. Send the seven listed JSON-RPC messages, compare parsed replies after replacing instance_id/implementation_digest (including JSON text blocks), and count UTF-8 bytes of the actual stdio streams. Repeat the candidate with --observe-database pointing at a fresh private temporary path and --observe-deployment synthetic-comparison.