epic-12: after epic audit and init commit
This commit is contained in:
@@ -0,0 +1,361 @@
|
||||
---
|
||||
name: "Lang Framewok Missing Pieces"
|
||||
description: "Language/framework recommendations and missing subsystems"
|
||||
depth: 1
|
||||
links: ["../index.md", "./spec-v0.1.md"]
|
||||
---
|
||||
|
||||
language:
|
||||
use Kotlin.
|
||||
|
||||
not because it’s trendy, but because architecture is inherently:
|
||||
|
||||
* state-heavy
|
||||
* concurrency-heavy
|
||||
* schema-heavy
|
||||
* event-heavy
|
||||
* validation-heavy
|
||||
|
||||
that maps extremely well to:
|
||||
|
||||
* sealed hierarchies
|
||||
* coroutines
|
||||
* structured concurrency
|
||||
* immutable data classes
|
||||
* serialization
|
||||
* type-safe DSLs
|
||||
|
||||
avoid:
|
||||
* Python as primary runtime
|
||||
* TypeScript as orchestration core
|
||||
|
||||
they’re excellent glue languages, but this system is closer to:
|
||||
* a workflow engine
|
||||
* an orchestration runtime
|
||||
* a distributed state machine
|
||||
than an app backend.
|
||||
|
||||
kotlin gives:
|
||||
* better long-term maintainability
|
||||
* safer concurrency
|
||||
* better event typing
|
||||
* cleaner DSLs
|
||||
* stronger replay guarantees
|
||||
|
||||
framework stack
|
||||
core runtime:
|
||||
* plain kotlin first
|
||||
* minimal framework dependence
|
||||
|
||||
web/api:
|
||||
* [Ktor](https://ktor.io?utm_source=chatgpt.com)
|
||||
|
||||
reasons:
|
||||
* coroutine-native
|
||||
* lightweight
|
||||
* excellent websocket support
|
||||
* no spring complexity
|
||||
* easy embedding
|
||||
* modular
|
||||
|
||||
do NOT use:
|
||||
* [Spring Boot](https://spring.io/projects/spring-boot?utm_source=chatgpt.com)
|
||||
spring will slowly eat the architecture:
|
||||
* hidden lifecycle
|
||||
* implicit DI magic
|
||||
* reflection-heavy
|
||||
* runtime complexity
|
||||
* startup overhead
|
||||
* difficult deterministic control
|
||||
system wants explicit orchestration.
|
||||
|
||||
persistence:
|
||||
* [Exposed](https://github.com/JetBrains/Exposed?utm_source=chatgpt.com) OR plain SQL
|
||||
* [SQLite](https://www.sqlite.org/index.html?utm_source=chatgpt.com) initially
|
||||
* migrate later to [PostgreSQL](https://www.postgresql.org/?utm_source=chatgpt.com)
|
||||
|
||||
serialization:
|
||||
* [kotlinx.serialization](https://github.com/Kotlin/kotlinx.serialization?utm_source=chatgpt.com)
|
||||
|
||||
config:
|
||||
* [Hoplite](https://github.com/sksamuel/hoplite?utm_source=chatgpt.com)
|
||||
or
|
||||
* [Typesafe Config](https://github.com/lightbend/config?utm_source=chatgpt.com)
|
||||
|
||||
logging:
|
||||
* structured logging ONLY
|
||||
* json logs
|
||||
* correlation ids everywhere
|
||||
|
||||
CLI:
|
||||
* [Clikt](https://ajalt.github.io/clikt/?utm_source=chatgpt.com)
|
||||
|
||||
TUI:
|
||||
* honestly optional initially.
|
||||
* if needed later:
|
||||
|
||||
* [Mordant](https://github.com/ajalt/mordant?utm_source=chatgpt.com)
|
||||
* or web dashboard instead
|
||||
|
||||
web UI:
|
||||
frontend:
|
||||
* [SvelteKit](https://svelte.dev/docs/kit/introduction?utm_source=chatgpt.com)
|
||||
|
||||
not react.
|
||||
|
||||
reasons:
|
||||
* simpler state model
|
||||
* less boilerplate
|
||||
* lower memory
|
||||
* faster iteration
|
||||
* easier websocket/event-stream integration
|
||||
|
||||
ui should behave like:
|
||||
* workflow inspector
|
||||
* event debugger
|
||||
* replay console
|
||||
* orchestration monitor
|
||||
|
||||
NOT “chatgpt clone ui”.
|
||||
|
||||
transport:
|
||||
* websocket first
|
||||
* event-stream oriented
|
||||
|
||||
REST only for:
|
||||
* management
|
||||
* configs
|
||||
* health
|
||||
* exports
|
||||
|
||||
real-time state should be event-driven.
|
||||
|
||||
architecture split
|
||||
important:
|
||||
core MUST NOT depend on infrastructure.
|
||||
only interfaces/ports.
|
||||
hexagonal architecture fits this system very well.
|
||||
|
||||
recommended internal layering
|
||||
domain layer
|
||||
pure logic:
|
||||
* events
|
||||
* transitions
|
||||
* policies
|
||||
* approvals
|
||||
* artifacts
|
||||
* projections
|
||||
* session state
|
||||
|
||||
NO IO.
|
||||
|
||||
application/service layer
|
||||
orchestration:
|
||||
* stage execution
|
||||
* replay coordination
|
||||
* context synthesis
|
||||
* validation pipeline
|
||||
* routing
|
||||
|
||||
infrastructure layer
|
||||
actual implementations:
|
||||
* sqlite
|
||||
* llama.cpp
|
||||
* shell execution
|
||||
* websocket
|
||||
* filesystem
|
||||
|
||||
interface layer
|
||||
external access:
|
||||
* cli
|
||||
* api
|
||||
* ui
|
||||
* websocket
|
||||
|
||||
plugin layer
|
||||
dynamic extensibility.
|
||||
missing pieces in the spec
|
||||
|
||||
1. scheduler subsystem
|
||||
|
||||
* queueing
|
||||
* prioritization
|
||||
* cancellation
|
||||
* starvation prevention
|
||||
* concurrency caps
|
||||
* backpressure
|
||||
|
||||
eventually:
|
||||
```text id="on4q1p"
|
||||
StageScheduled
|
||||
StageDeferred
|
||||
StageBlocked
|
||||
StagePreempted
|
||||
```
|
||||
|
||||
2. capability negotiation
|
||||
currently:
|
||||
stage requests capabilities.
|
||||
|
||||
but models/tools/providers should advertise:
|
||||
|
||||
* hard capabilities
|
||||
* soft capabilities
|
||||
* confidence
|
||||
* limits
|
||||
|
||||
example:
|
||||
|
||||
```yaml id="w4h8b4"
|
||||
coding:
|
||||
score: 0.92
|
||||
reasoning:
|
||||
score: 0.61
|
||||
tool_calling:
|
||||
score: 0.74
|
||||
```
|
||||
|
||||
otherwise routing becomes binary and crude.
|
||||
|
||||
3. deterministic tool contracts
|
||||
|
||||
VERY important.
|
||||
|
||||
tools should never return freeform text internally.
|
||||
|
||||
tool outputs must be typed.
|
||||
|
||||
bad:
|
||||
|
||||
```json id="v4g2pr"
|
||||
"pytest failed due to auth issue"
|
||||
```
|
||||
|
||||
good:
|
||||
|
||||
```json id="i08vuj"
|
||||
{
|
||||
"failed_tests": [
|
||||
{
|
||||
"file": "auth_test.py",
|
||||
"reason": "timeout"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
models can consume summaries.
|
||||
harness consumes structure.
|
||||
|
||||
4. model sandboxing
|
||||
|
||||
define explicitly:
|
||||
|
||||
* max execution time
|
||||
* max tokens
|
||||
* max context
|
||||
* max retries
|
||||
* cancellation semantics
|
||||
* kill signals
|
||||
* watchdogs
|
||||
|
||||
otherwise local models WILL hang eventually.
|
||||
|
||||
5. config versioning/migrations
|
||||
|
||||
absolutely need:
|
||||
|
||||
```yaml id="v0i3qf"
|
||||
config_version: 1
|
||||
```
|
||||
|
||||
plus migration system.
|
||||
|
||||
6. projection snapshots
|
||||
|
||||
replaying 100k events eventually becomes painful.
|
||||
|
||||
need:
|
||||
|
||||
* periodic snapshots
|
||||
* projection checkpoints
|
||||
* replay cursors
|
||||
|
||||
classic event sourcing problem.
|
||||
|
||||
7. artifact lineage graph
|
||||
|
||||
this one is important and often missed.
|
||||
|
||||
artifacts should track:
|
||||
|
||||
* parent artifacts
|
||||
* originating events
|
||||
* tool receipts
|
||||
* approvals
|
||||
* validator passes
|
||||
|
||||
this enables:
|
||||
|
||||
* blame tracing
|
||||
* replay diffing
|
||||
* synthetic training extraction
|
||||
|
||||
8. state machine formalization
|
||||
|
||||
session lifecycle should become an explicit finite state machine.
|
||||
|
||||
not enums.
|
||||
|
||||
otherwise invalid transitions creep in later.
|
||||
|
||||
9. policy engine
|
||||
|
||||
currently mixed into approvals/validation.
|
||||
|
||||
should probably become its own subsystem.
|
||||
|
||||
because eventually policies will govern:
|
||||
|
||||
* tools
|
||||
* providers
|
||||
* models
|
||||
* routing
|
||||
* retries
|
||||
* approvals
|
||||
* networking
|
||||
* secrets
|
||||
* filesystem access
|
||||
|
||||
10. trust boundaries
|
||||
|
||||
* model boundary
|
||||
* tool boundary
|
||||
* plugin boundary
|
||||
* provider boundary
|
||||
* ui boundary
|
||||
|
||||
especially if third-party plugins become possible later.
|
||||
|
||||
big recommendation
|
||||
```text
|
||||
everything important is append-only
|
||||
```
|
||||
|
||||
events:
|
||||
append-only
|
||||
|
||||
artifacts:
|
||||
immutable
|
||||
|
||||
receipts:
|
||||
immutable
|
||||
|
||||
approvals:
|
||||
immutable
|
||||
|
||||
summaries:
|
||||
versioned
|
||||
|
||||
projections:
|
||||
rebuildable
|
||||
Reference in New Issue
Block a user