extract-protocols-and-state

Extract Protocols And State

Treat every boundary as a protocol boundary.

Enumerate the boundaries first:

• process to process
• UI to core
• core to provider
• tool layer to runtime
• runtime to persistence
• local files to exported artifacts

Prefer type definitions, schemas, and docs before implementation code:

• Read event and message types first.
• Read file format docs next.
• Use source to fill ordering, retry, and recovery gaps.

For each protocol, record:

• producer
• consumer
• transport or carrier
• ordering guarantees
• required fields
• optional fields
• identifiers and timestamps
• error cases
• restart or resume behavior

Convert control flow into a state machine:

• Name the states.
• Name the transitions.
• Record guards and side effects.
• Separate synchronous barriers from observational events.

This phase owns the storage-format catalog: every on-disk and wire format the system reads or writes, with its shape, version markers, and reader/writer pairs. The contracts phase names the formats it saw as user-visible behavior; catalog them here once rather than asking contracts to.

Capture persistence semantics explicitly:

• append-only vs mutable
• branching vs linear history
• compaction or summarization
• replay or resume behavior
• locking, deduplication, or conflict handling

Look for these protocol-heavy areas:

• streamed assistant events
• tool call validation and execution
• session files
• JSONL or RPC framing
• queueing semantics
• background event scheduling
• transport fallbacks

Treat configuration propagation as a protocol when it crosses boundaries:

• How config values flow from files or env vars into runtime behavior.
• Whether config changes require a restart or are hot-reloaded.
• How config is validated and what happens on invalid input.
• If the config propagation model is complex, use the secondary output at findings/config-model/config-model.md.

Flag portability hazards that frequently break ports:

• ANSI terminal semantics
• IME or cursor positioning rules
• filesystem locking assumptions
• async ordering guarantees
• OAuth token refresh behavior
• shell quoting and OS differences
• encoding, width, or Unicode handling

Produce four outputs:

1. Event catalog
2. State machine
3. Persistent schema notes
4. Compatibility hazards

Mark every finding with one of these evidence levels:

• observed fact: direct statement from docs, tests, schemas, types, or code.
• strong inference: protocol conclusion drawn from multiple facts.
• external-behavior claim: a claim about what the peer or a system outside this source tree does with a message (how it parses, what it ignores, version-dependent behavior); unverifiable by reading this code, so it stays unsettled until a runtime capture or that system's own source confirms it.
• portability hazard: assumption tied to the source language, runtime, terminal, OS, or third-party SDKs.
• open question: missing or conflicting behavior that still needs evidence.

Do not copy the wire syntax blindly. Preserve the meaning of the interaction, then decide how the target language should encode it.

Use the output template at templates/protocols-and-state.md.

The source code to analyze is in the parent directory (../ relative to .codecarto/). This is the repository root.