docs: protocol scope + trace-format design spike

[sepehr-safari]

Summary

Resolves all foundational design decisions before core implementation (Milestone 0.5 — Protocol & Trace-Format Design Phase).

This is a research/spike phase — no published packages. Only design documents, ADRs, synthetic fixtures, and the proposed type definitions.

Closes #18

Deliverables

Architecture Decision Records (docs/adr/)

9 ADRs covering every design decision from the M0.5 checklist:

ADR	Title
ADR-0001	OCPP Version Scope — 1.6 JSON Primary
ADR-0002	Input Trace Formats — JSON Object + JSONL
ADR-0003	Canonical Internal Event Model
ADR-0004	Message Direction Representation
ADR-0005	Timestamp Normalization
ADR-0006	Session Correlation Strategy
ADR-0007	Malformed Trace Handling
ADR-0008	Browser-Local Processing & Privacy
ADR-0009	Future Protocol-Version Extensibility

Trace Format Specification (docs/trace-format-spec.md)

Full specification of accepted trace formats (JSON Object, JSONL, bare array), OCPP 1.6 message structure, size/count limits, timestamp formats, and direction values.

Synthetic Trace Fixtures (packages/core/src/__fixtures__/)

3 fixtures — all fully synthetic (no real station IDs, transaction IDs, or idTags):

1. normal-session.json — complete charging session: boot → authorize → start transaction → meter values → stop transaction. No failures expected.
2. failed-auth.json — failed authorization: idTag rejected 3×, connector transitions to Faulted. Expects FAILED_AUTHORIZATION.
3. connector-fault.json — connector fault during active session: ConnectorLockFailure mid-charging, stop with Faulted reason. Expects CONNECTOR_FAULT.

Proposed Canonical Types (packages/core/src/types.ts)

Type definitions for Event, Trace, TraceEventInput, Session, Direction, MessageType, ParseResult, ParseWarning — the foundation for v0.1.0 implementation.

Validation Tests (packages/core/src/fixtures.test.ts)

28 tests proving all 3 fixtures conform to the proposed event model:

• Trace shape validation (events array, metadata)
• Per-event shape validation (message array, message type IDs, field types)
• Call/CallResult correlation by messageId
• Session flow validation (BootNotification → Authorize → StartTransaction → MeterValues → StopTransaction)
• Transaction ID consistency
• Chronological timestamp ordering
• Synthetic data policy enforcement (SYNTHETIC markers, no UUID patterns)
• OCPP version declaration

Design Decisions Summary

• OCPP 1.6 JSON primary; 2.0.1 deferred but architecturally supported
• Two trace formats: JSON Object (metadata + events) and JSONL (one event per line)
• Canonical Event with id, messageId, timestamp (epoch ms or null), direction, messageType, action, payload, rawMessage
• Direction inferred from OCPP action name when not explicitly provided
• Timestamps normalized to epoch ms; out-of-order events flagged, not silently reordered
• Sessions derived from transactionId correlation
• Malformed traces: structural errors fail-fast; event errors skip-and-flag; 10MB / 10K event limits
• Browser-local: all processing client-side, no auto-upload, no trace telemetry
• Extensibility: version-aware dispatch, no premature plugin abstraction

Verification

• ✅ pnpm lint — clean
• ✅ pnpm typecheck — clean
• ✅ pnpm test — 29 tests pass (1 smoke + 28 fixture validation)
• ✅ pnpm format:check — clean

Security Review

• No secrets, tokens, or credentials in committed files
• No real station IDs, transaction IDs, or idTags — all synthetic (CS-SYNTHETIC-*, SYNTHETIC-TAG-*)
• No eval(), Function(), or dynamic code execution
• No personal or sensitive information in committed artifacts
• .hermes/ directory is gitignored and not committed
• No maintainer email in any committed file

Checklist

• ADRs written for each design decision
• Trace format spec documented with examples
• 3 synthetic fixtures validate against the proposed event model
• No real station IDs, transaction IDs, or personal data in fixtures
• Living docs updated (CURRENT_STATE.md, AGENTS.md)
• CI expected green (lint, typecheck, test, format)
• Maintainer approves the design before core implementation begins