Implementation Notes: neokapi Framework

Implementation notes contain tactical details for the neokapi framework (Apache-2.0): SQL schemas, wire protocols, algorithm pseudocode, Go interface signatures, and other reference material. They exist alongside the Architecture Decisions, which describe the design choices; notes describe the implementation.

The notes are grouped into the same series as the decisions (F foundations, E engine, C context, S surfaces, M multilingual), so a note sits under the heading of the AD it details. A final group holds the notes that describe this repository's own infrastructure rather than a subsystem of the engine.

F: Foundations

Note	Parent AD	Content
Content-Model Parity Across Wire Projections	F-04 · F-02	The lossless model↔proto↔store round-trip invariant, what must round-trip, and the extend-without-breaking checklist gated by a conformance test

E: Engine

Note	Parent AD	Content
Implementing Formats	E-02	Step-by-step guide for new format readers and writers
Skeleton store and streaming	E-02	The skeleton store, its backings and writer fallbacks, and how the whole-document readers stream through it
Content-Fidelity Surfacing	E-02	Surfacing non-translatable context: the inverted toggle, channels, parity force-off
Flow Steps Format	E-04 · E-03	YAML step list, fan-out, script steps
Session-Scoped Tool Authoring	E-03	Guide for writing tools against BlockStore
Plugin Model	E-05	In-process registry contract for plugin binaries
Plugin protocol v1	E-05	The versioned plugin contract: manifest rules, the three transports, the Mode-C gRPC surface and wire format, and the conformance suite

C: Context

Note	Parent AD	Content
kapi.yaml Project File	C-01	kapi.yaml recipe schema and examples
Terminology Data Model	C-08	Go structs, Terminology interface
Content Memory Matching Algorithm	C-09	Tiered matching, version chains, TMX mapping

S: Surfaces

Note	Parent AD	Content
CLI Conventions	S-01	Input/output/exit-code/project contracts, per-command surface table
MCP Tools Reference	S-03	Where the MCP tool handlers live, how a tool reaches the server, and what shape its result takes
WASM Engine ABI	S-01	The JS contract the browser build of the CLI exposes to @neokapi/engine, and its reverse bridges

M: Multilingual

Note	Parent AD	Content
Multimodal Content	M-03	The two axes of adaptation, and the timing/geometry/recognition annotations that carry them
OMML Math Conversion	M-04	core/math Exp AST, OMML reader, nor-splice algorithm, coverage ledger

Repo infrastructure

These two describe how this repository builds and presents itself rather than how the engine works, so they answer to no architecture decision.

Note	Content
CDN asset offloading	Why the large immutable docs assets are served from S3 + CloudFront, and how they are published
Markdown in the UI	Which metadata fields carry markdown, and the shared Markdown typeset primitive that renders them