@unifyplane/logsdk 1.0.0

package/contracts/specs/validation-rules.v1.md

@@ -0,0 +1,324 @@
+Proceeding with **4️⃣ Define Validation & Non-Compliance Rules**.
+
+This locks what it means to be **LogSDK v1.0 compliant** and what CI/validators must enforce.
+**No code. Language-neutral. Frozen once accepted.**
+
+---
+
+# 🧩 LogSDK Core — Validation & Non-Compliance Rules (v1.0)
+
+## Table of Contents
+
+- [0. Purpose (Non-Negotiable)](#section-0-purpose)
+- [1. Compliance Domains (What Must Be Validated)](#section-1-compliance-domains)
+- [2. API Surface Compliance (Hard Rules)](#section-2-api-surface-compliance)
+- [3. Canonical Step Record Compliance (Hard Rules)](#section-3-canonical-step-record-compliance)
+- [4. Sink / Emitter Compliance (Hard Rules)](#section-4-sink-emitter-compliance)
+- [5. Fan-Out Semantics Compliance (Hard Rules)](#section-5-fan-out-semantics-compliance)
+- [6. Compliance Artifacts (What CI Must Prove)](#section-6-compliance-artifacts)
+- [7. Non-Compliance Taxonomy (Standard Failure Reasons)](#section-7-non-compliance-taxonomy)
+- [8. Freeze Statement](#section-8-freeze-statement)
+- [✅ Closure](#section-closure)
+
+<a id="section-0-purpose"></a>
+## 0. Purpose (Non-Negotiable)
+
+Validation exists to ensure:
+
+* **the developer surface stays minimal**
+* **records remain canonical + bounded**
+* **fan-out semantics are deterministic**
+* **evidence ownership is preserved**
+* **no drift introduces “context injection” or payload logging**
+
+Validation is how the SDK remains governable across versions.
+
+---
+
+<a id="section-1-compliance-domains"></a>
+## 1. Compliance Domains (What Must Be Validated)
+
+Validation is divided into four domains:
+
+1. **API Surface Compliance**
+2. **Record Shape & Constraint Compliance**
+3. **Emitter/Sink Compliance**
+4. **Fan-Out Semantics Compliance**
+
+Each domain has explicit PASS/FAIL rules.
+
+---
+
+<a id="section-2-api-surface-compliance"></a>
+## 2. API Surface Compliance (Hard Rules)
+
+### 2.1 Allowed developer method
+
+✅ Only:
+
+* `step(message_string)`
+
+### 2.2 Forbidden API capabilities (FAIL if present)
+
+❌ Any of:
+
+* `step(message, anythingElse)`
+* `withContext`, `ctx`, `meta`, `attributes`, `tags`, `labels`
+* `log(event)`, `emit(payload)`, `metric()`, `span()`
+* `step({ ... })` object-based steps
+* any method that enables per-call enrichment
+
+### 2.3 Scope methods (Conditional allowance)
+
+If `child(scope)` exists:
+
+* scope must be from a **closed union** (request/job/component only)
+* scope must be **structural identity**, not metadata
+* no user-provided object blobs
+* no per-step override
+
+If this is not enforceable, `child()` is non-compliant.
+
+---
+
+<a id="section-3-canonical-step-record-compliance"></a>
+## 3. Canonical Step Record Compliance (Hard Rules)
+
+### 3.1 Record completeness
+
+✅ Every emitted record must include:
+
+* `record_version`
+* `record_id`
+* `sequence`
+* `timestamp_utc`
+* `monotonic_time`
+* system ownership fields (`institution`, `system_name`, `system_type`, `environment`, `system_version`)
+* `message`
+* `context_hash`
+* integrity fields (`record_hash`, `hash_algorithm`)
+
+### 3.2 Immutability
+
+✅ Record must be immutable at emission time.
+FAIL if:
+
+* any sink can mutate fields
+* per-sink copies differ in content (other than transport metadata outside record)
+
+### 3.3 Boundedness
+
+✅ `message` must satisfy bounded rules:
+
+* hard length limit (as configured but fixed per major version)
+* must not contain embedded JSON objects/arrays
+* must not contain base64-like blobs or raw payloads
+
+### 3.4 Context discipline
+
+✅ Context is **reference-only**.
+FAIL if:
+
+* context is embedded in record
+* context can be changed after init
+* per-step context exists in any form
+
+### 3.5 Evidence references
+
+✅ Evidence may appear only as `evidence_refs` (references).
+FAIL if:
+
+* raw evidence/payload is embedded
+* `evidence_refs` contains inline data rather than references
+
+---
+
+<a id="section-4-sink-emitter-compliance"></a>
+## 4. Sink / Emitter Compliance (Hard Rules)
+
+### 4.1 Contract adherence
+
+Each sink must support:
+
+* `emit(record)` (required)
+  Optional:
+* `flush()`, `close()`
+
+FAIL if sink:
+
+* requires mutating record
+* requires additional record fields not in canonical schema
+* rejects records based on semantics rather than transport
+
+### 4.2 Non-mutation guarantee
+
+FAIL if sink:
+
+* adds labels/tags into record
+* rewrites fields
+* strips fields
+* changes ordering within a single execution context
+
+Transport-level enrichment (headers, labels outside record) is allowed.
+
+### 4.3 Sink classification must be explicit
+
+Every sink must be configured as one of:
+
+* `authoritative`
+* `observability`
+
+FAIL if:
+
+* sink class is inferred dynamically
+* sink class is missing
+
+### 4.4 Evidence continuity requirement (system config rule)
+
+At runtime configuration level:
+
+* at least one `authoritative` sink must exist
+
+FAIL if:
+
+* only observability sinks exist (e.g., Loki-only setup)
+
+---
+
+<a id="section-5-fan-out-semantics-compliance"></a>
+## 5. Fan-Out Semantics Compliance (Hard Rules)
+
+### 5.1 Emit once
+
+FAIL if:
+
+* multiple canonical records are generated for one `step()` call
+* per-sink content differs
+
+### 5.2 Deterministic order
+
+PASS if:
+
+* sinks are invoked in declared order (or an explicitly declared concurrent mode that preserves deterministic semantics)
+
+FAIL if:
+
+* sink invocation order varies run-to-run without explicit config
+
+### 5.3 Failure classification
+
+Must produce one of:
+
+* `OK`
+* `DEGRADED`
+* `FAILED`
+
+Rules:
+
+* observability sink failure must not cause FAILED
+* authoritative sink failure must not be silently ignored
+
+### 5.4 Fail-open requires spool
+
+If fail-open mode is enabled:
+
+* emergency spool must exist
+* spool must be append-only + bounded
+* spool write must be acknowledged
+
+FAIL if:
+
+* fail-open occurs without spool
+* authoritative failure is swallowed
+
+### 5.5 Bounded resource behavior
+
+FAIL if:
+
+* unbounded buffering is possible
+* memory can grow without a hard cap
+
+---
+
+<a id="section-6-compliance-artifacts"></a>
+## 6. Compliance Artifacts (What CI Must Prove)
+
+A compliant implementation must be able to generate these proofs:
+
+1. **API surface report**
+
+   * lists exported methods and signatures
+   * asserts forbidden APIs absent
+
+2. **Schema conformance report**
+
+   * validates emitted record against canonical schema
+
+3. **Fan-out behavior report**
+
+   * demonstrates deterministic order
+   * demonstrates correct OK/DEGRADED/FAILED behavior
+
+4. **Sink classification report**
+
+   * confirms at least one authoritative sink exists
+
+5. **Negative tests**
+
+   * prove rejection of:
+
+     * payload-in-message
+     * JSON-in-message
+     * missing authoritative sink
+     * per-step context attempts
+
+These artifacts enable downstream governance validators to PASS.
+
+---
+
+<a id="section-7-non-compliance-taxonomy"></a>
+## 7. Non-Compliance Taxonomy (Standard Failure Reasons)
+
+When validation fails, it must classify failures into one of these reasons:
+
+* `API_SURFACE_VIOLATION`
+* `CONTEXT_INJECTION_VIOLATION`
+* `PAYLOAD_EMBEDDING_VIOLATION`
+* `CANONICAL_SCHEMA_VIOLATION`
+* `SINK_MUTATION_VIOLATION`
+* `NO_AUTHORITATIVE_SINK`
+* `FANOUT_NONDETERMINISM`
+* `AUTHORITATIVE_FAILURE_SWALLOWED`
+* `UNBOUNDED_BUFFER_RISK`
+
+This taxonomy is required for traceability.
+
+---
+
+<a id="section-8-freeze-statement"></a>
+## 8. Freeze Statement
+
+**LogSDK Core Validation Rules v1.0 are now locked.**
+
+Any change to:
+
+* canonical record fields
+* allowed API surface
+* sink compliance rules
+* fan-out failure semantics
+
+requires a **major version bump**.
+
+---
+
+<a id="section-closure"></a>
+## ✅ Closure
+
+At this point, you have **fully defined v1.0** of:
+
+1. Canonical Step Record
+2. Sink / Emitter Contract
+3. Fan-Out Semantics
+4. Validation Rules
+
+**You are now ready to implement LogSDK without rediscovery or design drift.**

package/docs/LogSDK-Unified-Execution-Logging-Framework.md

@@ -0,0 +1,93 @@
+# LogSDK — Unified Execution Logging Framework for UnifyPlane
+
+## Table of Contents
+- [1. What LogSDK Is](#section-1-what-logsdk-is)
+- [2. Why LogSDK Exists in UnifyPlane](#section-2-why-logsdk-exists-in-unifyplane)
+- [3. Core Capabilities (Evidence-Based)](#section-3-core-capabilities-evidence-based)
+- [4. LogSDK Usage Across the Repository](#section-4-logsdk-usage-across-the-repository)
+- [5. Executable vs Non-Executable Surfaces](#section-5-executable-vs-non-executable-surfaces)
+- [6. Execution Lifecycle and Logging Semantics](#section-6-execution-lifecycle-and-logging-semantics)
+- [7. Relationship to Events and CIA](#section-7-relationship-to-events-and-cia)
+- [8. Governance, Validation, and Evidence](#section-8-governance-validation-and-evidence)
+- [9. Benefits of Leveraging LogSDK Across UnifyPlane](#section-9-benefits-of-leveraging-logsdk-across-unifyplane)
+- [10. Future Considerations (Non-Binding)](#section-10-future-considerations-non-binding)
+- [11. Non-Goals and Explicit Exclusions](#section-11-non-goals-and-explicit-exclusions)
+
+## 1. What LogSDK Is
+<a id="section-1-what-logsdk-is"></a>
+- Precise definition: A TypeScript/Node library that produces immutable, canonical step records with integrity metadata and context capsule references, and delivers them to configured sinks with authoritative failure handling. Evidence: src/index.ts, src/core/record_builder.ts, src/core/fanout.ts, src/validate/schema_guard.ts.
+- Explicit scope: Provides `initLogSDK()` returning a `LogApi` with `step(message)` and optional `flush()`, enforces message constraints and API surface policies, and supports sink fanout with emergency spooling on authoritative failure. Evidence: src/index.ts, src/core/message_constraints.ts, src/validate/api_surface_guard.ts, src/core/spool.ts.
+- Explicit non-scope: No metrics/tracing collection, no external observability backends beyond provided file/stdout sinks, no per-step context injection, no arbitrary API exports beyond `step`, `flush`. Evidence: src/validate/api_surface_guard.ts, src/sinks/file_ndjson.ts, src/sinks/stdout_sink.ts, src/index.ts.
+
+## 2. Why LogSDK Exists in UnifyPlane
+<a id="section-2-why-logsdk-exists-in-unifyplane"></a>
+- Relationship to UnifyPlane Law and Governance Stack: Enforces canonical record schema, message discipline, and authoritative emission requirements to produce governance-grade execution evidence. Evidence: src/validate/schema_guard.ts, src/core/message_constraints.ts, src/core/record_builder.ts, src/core/fanout.ts.
+- Why execution logging is treated as governance evidence: Records include integrity fields (`record_hash`, `hash_algorithm`) over a canonicalized payload and a context capsule (`context_hash`, `context_version`), supporting auditability and tamper detection. Evidence: src/core/record_builder.ts, src/core/context.ts, src/core/types.ts.
+
+## 3. Core Capabilities (Evidence-Based)
+<a id="section-3-core-capabilities-evidence-based"></a>
+- `initLogSDK(config)`: Initializes context (once per process) and returns `step(message)`/`flush()`. Evidence: src/index.ts, src/core/context.ts.
+- Step record construction: `buildStepRecord()` enforces required fields, sets monotonic clocks, and computes a canonical hash over an ordered JSON representation. Evidence: src/core/record_builder.ts, src/core/clock.ts.
+- Message validation: Rejects empty, too-long, JSON-shaped, and base64-like payloads. Evidence: src/core/message_constraints.ts.
+- API surface validation: Only `step`, optional `flush`; forbids ambiguous exports and per-step context injection. Evidence: src/validate/api_surface_guard.ts.
+- Sink fanout with authoritative requirement: Emits to sinks; requires at least one authoritative sink; writes to emergency spool on authoritative failure; reports `OK`/`DEGRADED`/`FAILED`. Evidence: src/core/fanout.ts, src/validate/schema_guard.ts, src/core/spool.ts, src/core/outcomes.ts.
+- Provided sinks: NDJSON file sink (authoritative/observability variants) and stdout sink. Evidence: src/sinks/file_ndjson.ts, src/sinks/file_ndjson_sink.ts, src/sinks/stdout_sink.ts, src/index.ts.
+- Id generation and sequencing: Deterministic sequence starting at 0 per instance; record IDs include time-derived and instance components. Evidence: src/core/ids.ts, validated in tests/sequence_monotonic.test.ts.
+
+## 4. LogSDK Usage Across the Repository
+<a id="section-4-logsdk-usage-across-the-repository"></a>
+- Initialization site: External code calls `initLogSDK()` with `context`, `system`, and `sinks`. Tests demonstrate usage patterns. Evidence: src/index.ts, tests/step1_compliance.test.ts.
+- Components using it: Library clients construct sinks (file NDJSON, stdout) and call `log.step("...")`, optionally `log.flush()`. Evidence: tests/step1_compliance.test.ts.
+- Observed patterns:
+  - Authoritative sink enforced before emission. Evidence: src/validate/schema_guard.ts.
+  - Emergency spool path driven by `LOGSDK_EMERGENCY_SPOOL_PATH`. Evidence: src/core/spool.ts, tests/step1_compliance.test.ts.
+  - NDJSON line discipline (append-only). Evidence: src/sinks/file_ndjson.ts, src/sinks/file_ndjson_sink.ts.
+
+## 5. Executable vs Non-Executable Surfaces
+<a id="section-5-executable-vs-non-executable-surfaces"></a>
+- Formal definition of execution surface: Any file directly invocable (CLI/job/script/tool), a deterministic entrypoint, or performing side-effect-capable logic (filesystem, process, env, network). Basis: Task requirements; mapped to repo evidence in Part B.
+- Why this distinction exists: Governance mandates logging at operational boundaries and side-effect points to preserve execution evidence.
+- Governance implications: Execution surfaces carry logging obligations; declarative/spec-only assets do not. Evidence: CI/tooling orchestrations in tools/test_results/run-tests-then-prebuild.js and validator in validators/bootstrap/validate-repo-structure.ts.
+
+## 6. Execution Lifecycle and Logging Semantics
+<a id="section-6-execution-lifecycle-and-logging-semantics"></a>
+- Step-based logging: `log.step(message)` produces one immutable record per step; sequence increments monotonically. Evidence: src/index.ts, src/core/ids.ts.
+- Started/completed/error semantics: Errors occur at validation or sink emission; authoritative failure triggers emergency spooling and can escalate to `FAILED`. Evidence: src/core/fanout.ts, tests/step1_compliance.test.ts.
+- Bounded message discipline: 512-char max, no JSON-shaped or base64-like payloads; message is the sole human input. Evidence: src/core/message_constraints.ts, src/core/types.ts.
+
+## 7. Relationship to Events and CIA
+<a id="section-7-relationship-to-events-and-cia"></a>
+- Logs vs Events: LogSDK emits canonical step records to sinks; it does not implement an event bus or downstream event processing. Evidence: absence of event frameworks; presence of sink-only interfaces in src/sinks/sink_types.ts.
+- CIA readiness (Confidentiality, Integrity, Availability) without coupling:
+  - Integrity: Canonical hashing and immutability at emission. Evidence: src/core/record_builder.ts, src/validate/schema_guard.ts.
+  - Availability: Emergency spool on authoritative failure. Evidence: src/core/spool.ts, src/core/fanout.ts.
+  - Confidentiality: Not explicitly addressed in code; no encryption features observed.
+
+## 8. Governance, Validation, and Evidence
+<a id="section-8-governance-validation-and-evidence"></a>
+- Validators (runtime/API):
+  - API surface guard prohibits non-compliant exports and per-step context injection. Evidence: src/validate/api_surface_guard.ts.
+  - Schema guard enforces canonical record fields and authoritative sink presence. Evidence: src/validate/schema_guard.ts.
+  - Noncompliance codes used for precise error signaling. Evidence: src/validate/noncompliance.ts.
+- CI enforcement (tooling):
+  - Verification pipeline runs repo-structure validator, tests, normalization, and traceability generation. Evidence: tools/test_results/run-tests-then-prebuild.js.
+- Auditability guarantees:
+  - NDJSON sinks produce append-only lines; emergency spool preserves authoritative failures; canonical hashing ensures record integrity. Evidence: src/sinks/file_ndjson.ts, src/sinks/file_ndjson_sink.ts, src/core/spool.ts, src/core/record_builder.ts.
+
+## 9. Benefits of Leveraging LogSDK Across UnifyPlane
+<a id="section-9-benefits-of-leveraging-logsdk-across-unifyplane"></a>
+- Determinism: Sequence and monotonic clock, canonical hashing, immutable records. Evidence: src/core/ids.ts, src/core/clock.ts, src/core/record_builder.ts.
+- Traceability: Context capsule references and consistent schema across steps. Evidence: src/core/context.ts, src/core/types.ts.
+- Governance safety: Clear noncompliance paths, authoritative emission guarantees, and emergency spooling. Evidence: src/validate/noncompliance.ts, src/core/fanout.ts, src/core/spool.ts.
+
+## 10. Future Considerations (Non-Binding)
+<a id="section-10-future-considerations-non-binding"></a>
+- External sink integrations (e.g., exporting NDJSON to external systems such as Grafana/Loki) could be added via new sink implementations; not present in repo. Evidence: Only file/stdout sinks exist today in src/sinks.
+- Extended correlation (trace/span IDs) could be populated by callers; fields exist but no automatic propagation observed. Evidence: Optional fields in src/core/types.ts.
+- Policy-driven retention or rotation for NDJSON files may be desirable for production; not implemented here.
+
+## 11. Non-Goals and Explicit Exclusions
+<a id="section-11-non-goals-and-explicit-exclusions"></a>
+- No dynamic per-step context embedding; context is fixed at initialization and referenced by hash/version. Evidence: src/core/context.ts, src/validate/schema_guard.ts.
+- No metrics, spans, tags, or arbitrary API exports; guarded explicitly. Evidence: src/validate/api_surface_guard.ts.
+- No built-in network transports or databases for logs; sinks provided are file/stdout only. Evidence: src/sinks/file_ndjson.ts, src/sinks/stdout_sink.ts.

package/docs/log_sdk_test_cases_traceability_plan.md

@@ -0,0 +1,197 @@
+# 🧪 LogSDK — Test Cases, Execution & Traceability (Plan + Templates)
+
+**Status:** Proposed (Non-authoritative)  
+**Goal:** Define explicit **test cases**, execute existing tests against them, and produce **traceable results** suitable for audit and freeze-gate.
+
+---
+
+## 1. Model Overview
+
+We introduce a **3-layer traceability model** without changing runtime code:
+
+```
+Audit Objective
+   ↓
+Test Case (TC-*)  — declarative intent
+   ↓
+Test Implementation (existing *.test.ts)
+   ↓
+Execution Result (CI output / JSON)
+```
+
+This keeps tests intact while making **intent, coverage, and results explicit**.
+
+---
+
+## 2. Test Case Definition (Authoritative for Testing Only)
+
+Create a test-case registry:
+
+**Path:** `tools/audit/test-cases.md`
+
+### Test Case Schema (Human-Readable)
+
+Each test case MUST include:
+- **TC-ID** (stable)
+- **Objective** (what is proven)
+- **Preconditions** (if any)
+- **Assertions** (observable guarantees)
+- **Mapped Tests** (existing files / test names)
+- **Audit Objective Mapping**
+
+---
+
+## 3. Canonical Test Cases (Initial Set)
+
+### TC-SEQ-001 — Monotonic Sequence Start & Increment
+- **Objective:** Verify sequence numbering starts at baseline and increments strictly.
+- **Assertions:**
+  - First `step()` has sequence = 0
+  - Each subsequent `step()` increments by +1
+  - No duplicates or skips
+- **Mapped Tests:**
+  - `tests/sequence_monotonic.test.ts`
+- **Audit Mapping:** Determinism, Replay Safety
+
+---
+
+### TC-CLK-001 — Strict Monotonic Time
+- **Objective:** Verify `monotonic_time` strictly increases across rapid calls.
+- **Assertions:**
+  - `monotonic_time[n+1] > monotonic_time[n]`
+- **Mapped Tests:**
+  - `tests/sequence_monotonic.test.ts`
+- **Audit Mapping:** Determinism
+
+---
+
+### TC-REC-001 — Canonical Step Record Integrity
+- **Objective:** Verify Step Record shape, fields, and immutability.
+- **Assertions:**
+  - All required fields present
+  - No forbidden fields
+  - Record is immutable after creation
+- **Mapped Tests:**
+  - `tests/record_builder.test.ts`
+  - `tests/step1_compliance.test.ts`
+- **Audit Mapping:** Contract Fidelity
+
+---
+
+### TC-FAN-001 — Fan-out Isolation & Outcome Classification
+- **Objective:** Verify sink fan-out does not mutate records and isolates failures.
+- **Assertions:**
+  - All sinks receive identical records
+  - Secondary sink failure does not abort execution
+- **Mapped Tests:**
+  - `tests/fanout.test.ts`
+- **Audit Mapping:** Evidence Safety
+
+---
+
+### TC-SPL-001 — Degraded Mode & Emergency Spool
+- **Objective:** Verify evidence preservation on authoritative sink failure.
+- **Assertions:**
+  - Evidence is spooled
+  - Outcome = DEGRADED
+  - No silent loss
+- **Mapped Tests:**
+  - `tests/fanout_spool.test.ts`
+- **Audit Mapping:** Evidence Durability
+
+---
+
+### TC-MSG-001 — Message & Context Constraints
+- **Objective:** Verify payload and context limits are enforced deterministically.
+- **Assertions:**
+  - Oversized payloads rejected
+  - No implicit truncation
+- **Mapped Tests:**
+  - `tests/message_constraints.test.ts`
+- **Audit Mapping:** LLM Safety
+
+---
+
+### TC-SNK-001 — NDJSON Evidence Persistence
+- **Objective:** Verify file sink writes valid NDJSON evidence.
+- **Assertions:**
+  - One record per line
+  - No corruption across writes
+- **Mapped Tests:**
+  - `tests/sinks_file_ndjson.test.ts`
+- **Audit Mapping:** Evidence Storage
+
+---
+
+## 4. Execution & Result Capture
+
+### Command (example)
+
+```bash
+npm test -- --runInBand --json --outputFile=tools/audit/test-results.json
+```
+
+Produces a **machine-readable execution artifact**.
+
+---
+
+## 5. Traceability Matrix (Generated)
+
+Create a generated file:
+
+**Path:** `tools/audit/test-traceability.json`
+
+### Example Structure
+
+```json
+{
+  "TC-SEQ-001": {
+    "tests": ["sequence_monotonic.test.ts"],
+    "status": "PASS",
+    "run_id": "2026-01-18T10:22:11Z"
+  },
+  "TC-SPL-001": {
+    "tests": ["fanout_spool.test.ts"],
+    "status": "PASS",
+    "run_id": "2026-01-18T10:22:11Z"
+  }
+}
+```
+
+This can be produced by a **small parser** over the test runner JSON output.
+
+---
+
+## 6. Audit-Grade Outputs
+
+After execution, you have:
+
+1. `test-cases.md` — declarative intent
+2. `test-results.json` — raw execution evidence
+3. `test-traceability.json` — TC → Result mapping
+4. `test-coverage-report.md` — narrative coverage (already generated)
+
+Together, these form a **complete, defensible test evidence bundle**.
+
+---
+
+## 7. What This Enables
+
+- Freeze-gate validation with proof
+- Regression detection across runs
+- CI enforcement (fail if any TC fails)
+- External audit consumption
+
+---
+
+## 8. Next Steps (Optional)
+
+- Generate `test-cases.md` automatically from this doc
+- Add CI job to publish traceability artifacts
+- Extend model to validators/ tools
+
+---
+
+**Key Principle:**
+> Tests already prove behavior. This layer proves **what** they prove, **when**, and **with what result**.
+