org.json-kula.valem CLAUDE.md

Valem

Deterministic reactive computation runtime for AI-generated structured data models. A spreadsheet-like computation model for JSON-based agent systems.

Project layout

valem/                   ← parent POM (multi-module Maven)
├── valem-core/          ← pure-Java library, no Spring
│   src/main/java/org/json_kula/valem/core/
│   ├── model/                ← ModelSpec and sub-records (deserialized from JSON)
│   ├── graph/                ← DependencyGraph, ModelSpecCompiler, ModelSpecValidator,
│   │                            SpecEvolution, ExpressionPathExtractor, CompiledModel
│   ├── state/                ← ModelState, Snapshot, DirtyPropagator, PathConverter
│   ├── engine/               ← ModelRuntime, evaluators, EffectDispatcher,
│   │                            EffectiveSchemaBuilder, ExpressionCache,
│   │                            SchemaValidator, TestCaseRunner, ModelHistory
│   ├── blob/                 ← BlobStore interface + InMemoryBlobStore + FilesystemBlobStore
│   └── llm/                  ← LlmClient interface, SpecGenerator (feedback loop),
│                                SpecGenerationPrompt (prompt templates)
│
├── valem-service/       ← pure-Java business logic, no Spring
│   src/main/java/org/json_kula/valem/service/
│   ├── ModelService          ← orchestrates all use cases (mutate, snapshot, evolve, …)
│   ├── ModelRegistry         ← ConcurrentHashMap<id, ModelRuntime>
│   ├── ModelInfo             ← DTO: id, version, counts
│   ├── JsonPatchTranslator   ← RFC 6902 patch → mutations
│   └── *Exception            ← domain exceptions (Not Found, Already Exists, Access Denied, …)
│
├── valem-view/          ← pure-Java view evaluation, no Spring
│   src/main/java/org/json_kula/valem/view/
│   ├── model/                ← ViewDefinition, ViewSpec, ComponentSpec and sub-specs
│   └── engine/               ← ViewEvaluator, EvaluatedView, EvaluatedComponent subtypes
│
├── valem-api/           ← Spring Boot 3 REST + WebSocket layer — HEADLESS library (no main,
│   │                            no executable repackaging); embeddable in a host Boot app
│   src/main/java/org/json_kula/valem/api/
│   ├── controller/           ← ModelController, BlobController, ViewController,
│   │                            GenerateController, LlmLogController
│   ├── registry/             ← ModelRegistry (Spring wrapper), ModelLoader (ApplicationRunner)
│   ├── persistence/          ← legacy in-api ModelStore (Filesystem/InMemory); the supported
│   │                            multi-backend stores live in valem-persistence/* (below)
│   ├── config/               ← StorageConfig (per-concern backend wiring), SecurityConfig,
│   │                            ServiceConfig, WebSocketConfig, LlmConfig
│   ├── filter/               ← RateLimitFilter (optional per-IP, off by default)
│   ├── dto/                  ← CreateModelResponse, MutationResponse, ValidationErrorResponse
│   ├── llm/                  ← AnthropicLlmClient, OpenAiLlmClient, MockLlmClient,
│   │                            RecordingLlmClient, LlmInteractionLog, LlmInteractionRecord
│   ├── websocket/            ← ValemWebSocketHandler, ChangeEvent, TokenHandshakeInterceptor
│   └── error/                ← GlobalExceptionHandler (RFC 7807 Problem Detail)
│
├── valem-web/           ← the runnable open web deployable (executable Spring Boot jar): owns
│                                ValemWebApplication (main) + the repackaging + the deployer's
│                                chosen persistence adapter(s). = valem-api (headless) + memory
│                                + filesystem by default; add an adapter jar (or -Pweb-postgres|web-
│                                mongo|web-redis|web-s3) for other backends. Builds valem-ui (the
│                                management SPA) via frontend-maven-plugin and serves it at / (skip
│                                with -Dskip.frontend=true). Also hosts McpHttpController — the MCP
│                                surface over Streamable HTTP at /mcp (reuses valem-mcp's McpHttpSession;
│                                shared models, valem.api.key gate, valem.mcp.allowed-origins).
│
├── valem-effects-noop/  ← reference effect-kind plugin: ServiceLoader EffectKind + auto-configured
│                                EffectExecutor bean; proves the pluggable-effects SPI (drop-in jar, no
│                                core/api edits). Template for real custom effect kinds.
│
├── valem-persistence/   ← pluggable storage SPI + adapters (no Spring in the modules)
│   ├── valem-persistence-api/         ← SpecStore, StateStore, ModelStore, CompositeModelStore,
│   │                                          MutationLogReplay (create-as-you-go), BlobSpooler,
│   │                                          audit/ (AuditStore, AuditRecord, AuditQuery, DisabledAuditStore)
│   ├── valem-persistence-memory/      ← InMemoryModelStore + InMemoryBlobStore
│   ├── valem-persistence-filesystem/  ← FilesystemModelStore + FilesystemBlobStore
│   ├── valem-persistence-postgres/    ← Postgres Spec/State/Blob stores (spring-jdbc)
│   ├── valem-persistence-mongo/       ← Mongo Spec/State stores + GridFS blob store
│   ├── valem-persistence-redis/       ← Redis Spec/State stores (Lettuce)
│   └── valem-persistence-s3/          ← S3/MinIO blob store (AWS SDK v2)
│
├── valem-console/       ← standalone JSON REPL (no Spring)
│   src/main/java/org/json_kula/valem/console/
│   ├── ConsoleApp
│   └── CommandDispatcher
│
├── valem-mcp/           ← MCP server (Model Context Protocol over stdio, no Spring; same
│   src/main/java/org/json_kula/valem/mcp/   deps as console: service + jackson only)
│   ├── McpServer             ← JSON-RPC 2.0 stdio transport + protocol core (initialize/tools/resources/
│   │                            logging handshake; negotiates up to 2025-11-25; resources subscribe +
│   │                            templates/list; async pair_browser worker w/ progress+cancellation +
│   │                            URL-mode elicitation; swappable notification sink for reuse over HTTP)
│   ├── McpHttpSession        ← reuses McpServer's core for the Streamable-HTTP endpoint (see valem-web)
│   ├── ToolRegistry          ← 24 tools → ModelService: model CRUD (create/mutate/patch_model/
│   │                            get_state[paths,depth]/explain/snapshot/restore/get_effective_schema/
│   │                            get_audit/verify_audit/upload_blob/download_blob/evolve_spec/…) +
│   │                            authoring/verify (validate_spec/eval_expression/test_spec/dry_run) —
│   │                            the agent generates, Valem verifies; opt-in mutate traces, outputSchema
│   │                            decls, result-size guard, structured errors; + pair_browser in
│   │                            remote_with_browser mode (--url --browser)
│   └── ResourceRegistry      ← MCP resources: spec-format/jsonata-gotchas/spec-evolution/view-system
│                                guides + JSON schemas + bundled example specs + valem://state/{id}
│                                subscribable resource (+ examples/state uriTemplates)
│
├── valem-client/        ← thin Java SDK over REST/WS (jackson + JDK java.net.http only;
│                                ValemClient, reconnecting subscribe, audit; no engine dep)
│
├── valem-ui/            ← open management/DevTools SPA (Vite+React); built & served at / by
│                                valem-web. npm-workspace member alongside valem-view-react.
├── valem-view-react/    ← open EvaluatedView → React renderer library (workspace member)
│
└── clients/valem-sdk-ts/ ← isomorphic TypeScript/JS SDK (fetch + reconnecting WebSocket)