Architecture

Lc is built as a layered runtime system with strict boundaries between parsing, dispatch, execution state, and output generation.

Layer model

1) Construction layer

• EngineBuilder in builder.go.
• Assembles parser, pipeline, context, logger, scope, default events, and endianness.

2) Unified runtime layer

• EngineUniversal in engine.go.
• Stable API for both engines: process input, register commands, access shared params.

3) Engine execution layer

• engine/stringEngine.go for text command dispatch.
• engine/byteEngine.go for opcode dispatch and pointer control.

4) Core runtime layer (engine/core)

• Generator: deterministic pipeline output.
• Events: ordered event bus.
• Logger: thread-safe structured log storage/printing.
• UniversalEngineParams: shared runtime container.

5) Default lifecycle handlers

• events/stringEngine.go
• events/byteEngine.go

6) Parsing layer

• stringParsing/*
• byteParsing/*

Determinism contracts

• Event handlers execute in registration order.
• Output is resolved in configured pipeline order.
• Scope state is shared intentionally across parser/event/handler stages.

Default execution lifecycle

String Engine

1. INPUT string scope injection.
2. parse to PARSED []ParsedNode.
3. command dispatch by node switch.
4. output emission to generator points.

Byte Engine

1. INPUT []byte scope injection.
2. parse to PARSED []ParsedBytes.
3. opcode dispatch by decoded switch.
4. instruction pointer movement via auto/manual policy.

Concurrency profile

Mutex-guarded internals exist in:

• engine command maps,
• generator storage,
• event registry access,
• logger write paths.

This supports service-level embedding where concurrent operations and state integrity matter.

Context and cancellation

Both engines support context-aware processing:

• ProcessStringWithCtx
• ProcessBytesWithCtx

Default call events check context and stop on cancellation.