Repository navigation
Expand file tree
/
Copy pathllms.txt
More file actions
58 lines (49 loc) · 5.99 KB
/
Copy pathllms.txt
File metadata and controls
58 lines (49 loc) · 5.99 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
# Papuma.Kernel
> Document-sourced CQRS kernel for .NET 10, shipped as two independent products
> sharing one model: `Papuma.Kernel` (PostgreSQL >= 18, for servers) and
> `Papuma.Kernel.Local` (SQLite, embedded, no server). JSON documents are the
> source of truth; both derive a reversible change feed automatically, apply
> privacy policies before anything is recorded, support schema evolution and an
> event log. Multi-tenancy is two-layer (predicates + row-level security) on
> Postgres, predicates-only on SQLite (single writer, nothing else to defend
> against). NOT an ORM, NOT event sourcing, NO query DSL. Optional additive
> facade: `Papuma.Kernel.FSharp` — `Result`-returning writes and a session
> runner for F# consumers of either kernel, no kernel change (Patch and keys take
> plain F# lambdas). Optional
> `Papuma.Kernel.Testing` — a PostgreSQL 18 test database with a non-superuser
> role (so tests exercise row-level security) and deterministic feed draining.
Reading order for coding agents: start with the playbook (mental model + binding
rules — includes a `Papuma.Kernel.Local` differences section and a
`Papuma.Kernel.FSharp` section), then getting-started (API), then concepts (the
why), then the ADRs (decisions; deviations are bugs). The AGENTS.md snippet has
one block per kernel plus an F# addendum — copy the kernel block matching the
consuming application, and the addendum too if it's F#. All canonical documents
are English; the implementation plan and the original design chat remain German
(historical project records), and `docs/legacy/concepts.de.md` is a frozen German
snapshot of the concepts document (not maintained).
These files ship inside every Papuma NuGet package under `docs/` — the same set
in each — so after `dotnet restore` they are readable locally from the global
packages folder, for exactly the version the application builds against (e.g.
`~/.nuget/packages/papuma.kernel/<version>/docs/`,
`~/.nuget/packages/papuma.kernel.local/<version>/docs/`). Pages describe the
PostgreSQL kernel unless they say otherwise; `Papuma.Kernel.Local` differences
are in the playbook.
## Docs
- [Agent playbook](https://raw.githubusercontent.com/papumabiz/Papuma.Kernel/master/docs/ai/papuma-kernel-playbook.md): mental model in 4 sentences, binding ADR rules, API quick map, decision tree, troubleshooting, `Papuma.Kernel.Local` differences, `Papuma.Kernel.FSharp` section
- [AGENTS.md snippet](https://raw.githubusercontent.com/papumabiz/Papuma.Kernel/master/docs/ai/papuma-kernel-agents-snippet.md): copy-paste block for AGENTS.md/CLAUDE.md of consuming applications — one variant per kernel, plus an F# addendum
- [`Papuma.Kernel.Local` design rationale](https://raw.githubusercontent.com/papumabiz/Papuma.Kernel/master/docs/analyses/local-kernel-sqlite-sibling.md): what's shared code vs. deliberately different per engine, and why
- [Slice conventions](https://raw.githubusercontent.com/papumabiz/Papuma.Kernel/master/docs/ai/papuma-kernel-slice-conventions.md): canonical shape of command/view/automation/translation slices — drives scaffolding and code generators; includes the F# translation
- [`Papuma.Kernel.FSharp` README](https://raw.githubusercontent.com/papumabiz/Papuma.Kernel/master/src/Papuma.Kernel.FSharp/README.md): the F# facade package itself — Patch and keys with F# lambdas, `trySaveAsync`/`tryPatchAsync`, `runSession` (`SetQ`/`RemoveQ`/`IncrementQ` deprecated)
- [Tutorial](https://raw.githubusercontent.com/papumabiz/Papuma.Kernel/master/docs/tutorial.md): learning-oriented, build one app from empty folder to a feed-driven read model (document → session → feed → handler), style-neutral
- [Getting started](https://raw.githubusercontent.com/papumabiz/Papuma.Kernel/master/docs/getting-started.md): bootstrap, write path, keys (incl. composite), handlers, schema evolution, use without a host, integration tests with `Papuma.Kernel.Testing`
- [Concepts](https://raw.githubusercontent.com/papumabiz/Papuma.Kernel/master/docs/concepts.md): 32 explanatory sections — the "why behind the how" (concurrency, feeds, checkpoints, snapshots, workflows, GDPR, the F# facade at §29, RLS for application tables §30, composite keys §31, testing support §32)
- [Architecture](https://raw.githubusercontent.com/papumabiz/Papuma.Kernel/master/docs/architecture.md): namespaces, SQL data model, write path, ADR index
## Guides
- [Observability](https://raw.githubusercontent.com/papumabiz/Papuma.Kernel/master/docs/observability.md): metrics, tracing, diagnostics APIs, MCP server
- [GDPR tooling](https://raw.githubusercontent.com/papumabiz/Papuma.Kernel/master/docs/gdpr.md): data inventory, subject export, history redaction, per-tenant erasure-vs-restriction pattern
- [Recipe: AI consumers](https://raw.githubusercontent.com/papumabiz/Papuma.Kernel/master/docs/recipes/ai-consumers.md): pgvector embeddings projection, natural-language audit, anomaly detection
- [Recipe: read models in the same database](https://raw.githubusercontent.com/papumabiz/Papuma.Kernel/master/docs/recipes/same-database-read-models.md): projection tables under row-level security via papuma.scope_visible/scope_writable
- [Recipe: schema for projection tables](https://raw.githubusercontent.com/papumabiz/Papuma.Kernel/master/docs/recipes/projection-schema.md): ISchemaContributor with idempotent DDL at startup, breaking changes as rebuild via a new handler name
- [Recipe: realtime UI notifications](https://raw.githubusercontent.com/papumabiz/Papuma.Kernel/master/docs/recipes/realtime-ui-notifications.md): NOTIFY-driven UI updates
## Decisions
- [ADR index](https://github.com/papumabiz/Papuma.Kernel/tree/master/docs/adr): 21 ADRs — PostgreSQL-18-only, derived change feed, write path with mandatory expectedVersion, reversible diffs, schema evolution, keys, privacy policies, rollback, projections as dumb handlers, feed consumption, event translation, patch primitive, event log, bulk operations, GDPR tooling, policy-projected reads, actor id, causation type, scope predicates for application tables (019), composite keys (020), testing package (021)