Generated

Software map

The components of Oaken Core, the layers they sit in, what calls what, and which pieces exist yet.

Status

25 components in 8 layers: 25 built, 0 partial, 0 planned.

Status	Meaning
Built	Implemented and checked in the repository.
Partial	Exists, but only part of what is planned.
Planned	Designed; no code yet.

Generated from docs/softmap.toml by docs/tools/softmap.py, which refuses to build if the data breaks the layering rules or disagrees with the repository. Edit the data in the same change that builds or alters a component.

Map

Click a component to draw its relationships. Each separate piece of software is its own framed stack, with its layers top to bottom. The border shows status; a red dot marks components that handle untrusted input.

calls (selected component calls this)called bynotifies (event or callback, upward)notified by

Select a component on the map.

Conventions

Calls go down. A component may call its own layer or a lower one, never a higher one, and the call graph has no cycles.
Events go up. Lower layers reach higher ones only through events or a handler the higher layer registered.
Plugins meet core at a contract. Core never imports provider code, and a plugin never touches the databases.
Outside text is data. Anything that handles text from outside is marked untrusted, and its text reaches a model only as UntrustedText.
Mutations are gated in code. The operation registry's confirm gate, not a prompt, decides whether anything changes: a change is a proposal until a person confirms it.

Components

Oaken Core (one asyncio process)

Composition root

Core daemonBuiltsrc/oaken_core/daemon · map

Builds everything in dependency order, starts it as units, stops it in reverse, and rebuilds it on reload. The only place that knows all the parts.

Calls

Agents Local API Change log Console Events and log Intake Jobs Labels Operation registry Plugin host Queues Model router Scheduler Settings

Called by

none

Notifies (event or callback, upward)

none

Notified by

none

Types

Name	Kind	Meaning
`Core`	class	The composition root: settings, host and store, labels, queues, jobs, agents, scheduler, runner, services, registry, client, API and console.

External none

Notes

A reload rebuilds Core in the same process and keeps the API and console ports. It does not re-import Python modules: a code change needs a restart.

Doors

CLIBuiltsrc/oaken_core/cli · map

The oaken command. Built from the operation registry at plugin load, so a plugin's commands appear when it loads. Talks to the running core, or runs in process for the commands that need no core.

Calls

Local API Operation registry

Called by

none

Notifies (event or callback, upward)

none

Notified by

none

Inherits

Class	Bases	What it is
`ApiClient`	`ABC`	The thin-client contract. An implementation decides how it reaches core (HTTP to the
`CliError`	`Exception`	Any failure the CLI wants to report with a chosen exit code and a clean message (no
`CoreUnavailable`	`CliError`	Core could not be reached: no runtime file, a dead pid, or a refused connection. Exit 3 with
`AgentClient`	`_Base`	The agent job protocol, with an agent token. It can reach nothing but ``/v1/agent/``.
`HttpApiClient`	`_Base`, `ApiClient`	Talks to the running daemon over loopback HTTP.
`InProcessApiClient`	`ApiClient`	Drive ``CoreClient`` directly, as the CLI caller class.

External none

Notes

oaken plugins lists what could be added and reads each plugin's source without importing it.

Local APIBuilt untrusted inputsrc/oaken_core/api · map

HTTP and server-sent events on 127.0.0.1 with token auth. Routes are generated from the operation registry; a guard checks Host, Origin, content type, token, rate and size before any route runs. Also serves the MCP doors.

Calls

Agents Events and log Operation registry Untrusted text

Called by

CLI Core daemon

Notifies (event or callback, upward)

none

Notified by

none

Types

Name	Kind	Meaning
`Api`	class	The ASGI application: generated operation routes, events, the agent job routes and the MCP mount.
`Surface`	dataclass	A path prefix with its own token check, size and concurrency limits and caller class.

Inherits

Class	Bases	What it is
`CallRequest`	`_Body`
`_Body`	`BaseModel`

External none

Notes

Binds to loopback only; configuration cannot say otherwise.

ConsoleBuilt untrusted inputsrc/oaken_core/console · map

The local web console: settings and flow, never content. It draws every plugin's row, settings modal and New instance dialog from the plugin's declared UI, and calls the same operations the CLI does.

Calls

Operation registry Plugin host Queues Settings

Called by

Core daemon

Notifies (event or callback, upward)

none

Notified by

none

Types

Name	Kind	Meaning
`Console`	class	The Starlette app and its guard: pages for the pipeline, stages, schedules, labels, plugins and capabilities.
`Field`	dataclass	One setting as a form draws it, made from the config schema and overridden by the plugin's spec.

External none

Notes

Content views belong to product UIs, which run their own server against the API.

Operations

Operation registryBuiltsrc/oaken_core/operations · map

Every action core offers is one operation: typed input and output, a permission class, an MCP mode and an optional preview. The CLI, API, MCP and console are generated from it. A change is a proposal until a person confirms it.

Calls

Agents Change log Database Events and log Jobs Labels Plugin host Queues Model router Scheduler Settings

Called by

Local API CLI Console Core daemon

Notifies (event or callback, upward)

none

Notified by

Plugin host

Types

Name	Kind	Meaning
`Operation`	dataclass	Name, summary, permission, input and output models, mcp mode, preview, group.
`OperationRegistry`	class	Core's operations plus the ones loaded plugins offer.
`CoreClient`	class	Calls an operation as a caller: validates, gates mutations, audits.
`Services`	dataclass	What an operation may reach: the host, jobs, queues, scheduler, labels and more.

Inherits

Class	Bases	What it is
`AgentGrantIn`	`AgentRef`
`AgentRef`	`BaseModel`
`CompleteIn`	`JobRef`
`FailIn`	`JobRef`
`JobRef`	`BaseModel`
`ScheduleEditIn`	`ScheduleRef`
`ScheduleRef`	`BaseModel`
`SecretRef`	`BaseModel`
`SecretSetIn`	`SecretRef`

External none

Notes

pluginhost notifies this layer with the operations a plugin offers; the registry takes them.

Intake pipeline

IntakeBuilt untrusted inputsrc/oaken_core/intake.py · map

The front door: submit, format into parts, triage, store. Every step is a durable job. A reject keeps only a content-free log row.

Calls

Change log Formatters Items ingestor Jobs Labels Queues Triagers

Called by

Core daemon

Notifies (event or callback, upward)

none

Notified by

Jobs Providers

Types

Name	Kind	Meaning
`Intake`	class	Registers the format, triage, store and embed job kinds and runs them.
`IntakeItem`	dataclass	Subject, source, body, labels, key, the parts a formatter made, and what earlier triagers said.
`Verdict`	dataclass	accept, reject or unsure, with a reason and labels.

Inherits

Class	Bases	What it is
`IntakePayload`	`BaseModel`
`StorePayload`	`IntakePayload`

External none

Notes

Triage rule: any reject ends it; otherwise every triager answers and the last to answer decides. Each answering triager's labels are written under its own name.

TriagersBuilt untrusted inputsrc/oaken_core/triage · map

The built-in triagers: dedupe (a repeat from the same source), rules (the owner's ordered rules) and llm (a model asks about your criteria). Others, such as the signal triagers, ship in oaken-plugins.

Calls

Plugin contracts Plugin base classes Model router Untrusted text

Called by

Intake

Notifies (event or callback, upward)

none

Notified by

none

Types

Name	Kind	Meaning
`DedupeTriager`	class	Rank 1. Drops an item whose source and key (or body hash) it has seen.
`RulesTriager`	class	Rank 5. The first matching rule decides.
`LlmTriager`	template	One instance per set of criteria; asks a model backend.

Inherits

Class	Bases	What it is
`DedupeTriager`	`BaseTriager`
`LlmTriager`	`BaseMultitenant`, `BaseTemplatePlugin`, `BaseLLMAnalyzer`, `BaseTriager`
`RulesTriager`	`BaseTriager`	Runs before the models (rank 5): an item you have a rule for is never sent to one.

External none

Notes

Imports Verdict and IntakeItem from intake: shapes only, no call. Move them to the contracts to make the layering literal.

Model routerBuilt untrusted inputsrc/oaken_core/router · map

Picks a model backend and embedder for each call, caches answers by content, keeps a ledger of spend, and refuses a remote backend for a confidential item.

Calls

Plugin contracts Database Plugin base classes Settings Untrusted text

Called by

Core daemon Operation registry Triagers

Notifies (event or callback, upward)

none

Notified by

none

Types

Name	Kind	Meaning
`Router`	class	Resolves a call to a backend, applies locality and limits, caches, and records usage.
`NearJunk`	class	A triager that embeds an item and drops near copies of known junk.

Inherits

Class	Bases	What it is
`NearJunk`	`BaseVecAnalyzer`, `BaseTriager`
`MemoryVectors`	`BasePlugin`	Cosine similarity over lists. Fine for tests; a real store indexes.
`StubBackend`	`BasePlugin`	Answers with ``reply`` (a dict, or a function of the request and the model asked for). Records
`StubEmbedder`	`BasePlugin`	A bag-of-words hash into ``dimensions`` buckets: texts that share words are close.

External none

Notes

pluginbase imports the router for the LLM types: a lower layer reaching up. Untangle by moving those types to the contracts.

Plugins

Plugin hostBuiltsrc/oaken_core/plugins/host.py · map

Discovers plugins (entry points, extension directories, oaken-plugins), checks each against its kind's contract, starts them store-first, makes named instances of templates, and says what each is: template, instance or plain.

Calls

Catalog and extensions Plugin contracts Database Events and log Formatters Items ingestor Jobs Labels Plugin base classes Providers Scheduler Settings

Called by

Console Core daemon Operation registry

Notifies (event or callback, upward)

Operation registry

Notified by

Jobs

Types

Name	Kind	Meaning
`PluginHost`	class	Loads, starts, reloads, enables and disables plugins; builds each one's row and UI spec.
`PluginStatus`	dataclass	Kind, name, health, provider origin (core, plugins or local), API version and template state.
`AddPlan`	dataclass	What `plugin add` will write: an instance's table and, for a template not yet loaded, the template's too.

External none

Notes

Offers each plugin's operations, job handlers and scheduled tasks upward; it does not reach into the registry itself.
Today the host imports the operations package: a lower layer reaching up.

Plugin base classesBuiltsrc/oaken_core/plugins/base.py · map

BasePlugin and the base for each kind, plus the mixins: BaseTemplatePlugin (an instance is how it runs) and BaseMultitenant (several workers may run it). Each plugin writes its api_version and requires_core.

Calls

Plugin contracts Database Labels

Called by

Formatters Items ingestor Plugin host Providers Model router Triagers

Notifies (event or callback, upward)

none

Notified by

none

Types

Name	Kind	Meaning
`BasePlugin`	class	Config, labels, UI spec, row, job handlers, scheduled tasks, traced calls.
`BaseTemplatePlugin`	mixin	contextual settings, the template pill and the template part of the UI spec.
`BaseMultitenant`	mixin	Marks a plugin several workers may run at once.
`BaseProvider`	class	Brings items in with submit().
`BaseTriager`	class	Rates an item before it is stored; any reject ends it.

Inherits

Class	Bases	What it is
`BaseAction`	`BaseAnalyzer`
`BaseAnalyzer`	`BasePlugin`	What triagers, enrichers and actions share. Deterministic by default; a plugin that asks a
`BaseCache`	`BasePlugin`	The router's answer cache, swapped for another store. Override all five members. ``key`` may return
`BaseEmbedder`	`BasePlugin`	Turns text into vectors. Analyzers reach it only through the router (``embed``).
`BaseEnricher`	`BaseAnalyzer`
`BaseFormatter`	`BasePlugin`	Splits a raw item into named parts (``oaken_core.parts.Part) before triage.` `formats`` lists
`BaseFriendlyNames`	`BasePlugin`	Add to a plugin's bases to give the console and the API (the MCP endpoint) friendly host names, such as ``oaken.localhost``.
`BaseIngestor`	`BasePlugin`	Stores an item intake accepted and returns its real ``SubjectId``. The product's own: core
`BaseLLMAnalyzer`	`BaseAnalyzer`	Add to a kind's base for an analyzer that asks a model through the router:
`BaseLLMBackend`	`BasePlugin`	Runs a chat model. The router calls ``generate; where the model runs (locality``) is the
`BaseProvider`	`BasePlugin`	A source: it gets items from outside (a file, a socket, a service) and puts each into intake with
`BaseStore`	`BasePlugin`	A store hands core a ``Database``. Core and plugins write portable SQL against it.
`BaseTemplatePlugin`	`BasePlugin`	Add to a plugin's bases when it only runs as a named instance that is given what makes it what it is: an agent's
`BaseTriager`	`BaseAnalyzer`	Rates an intake item before it is stored. Lowest ``rank` `first. Any reject ends it; otherwise every triager answers and the last to answer decides.` `item.verdicts`` holds what the ones before said.
`BaseVecAnalyzer`	`BaseAnalyzer`	Add to a kind's base for an analyzer that uses the embedder and vector store, only through
`BaseVectorStore`	`BasePlugin`	Stores vectors under a collection and a key, and finds the nearest. A collection never mixes

External none

Notes

Imports the router for the LLM request types; see the router.

Plugin contractsBuiltsrc/oaken_core/plugins/contracts.py · map

The shapes a plugin and core exchange: context, health, operations, job handlers, scheduled tasks, and the UI spec (settings sections and field overrides, buttons, pages, the row and the template part).

Calls

Database Events and log Labels Untrusted text

Called by

Items ingestor Plugin base classes Plugin host Providers Model router Triagers

Notifies (event or callback, upward)

none

Notified by

none

Types

Name	Kind	Meaning
`PluginContext`	dataclass	What a plugin is given: name, config, clock, log, db, labels, submit.
`UiSpec`	dataclass	sections, buttons, pages, template, row and field overrides.
`UiRow`	dataclass	Status pills and actions (settings, reload, remove) for a plugin's row.
`UiTemplate`	dataclass	The settings an instance must be given; one of a\|b means one of them.

External none

Notes

PLUGIN_API_VERSION is 1. A plugin that speaks another is refused at load.

Catalog and extensionsBuiltsrc/oaken_core/plugins/catalog.py · map

What could be added: the oaken-plugins package and the extension directories, listed without importing anything. Reads each plugin's summary, api_version and requires_core from its source.

Calls

none

Called by

Plugin host

Notifies (event or callback, upward)

none

Notified by

none

Types

Name	Kind	Meaning
`Entry`	dataclass	A plugin in oaken-plugins: kind, name, module, summary, api, requires.

External none

FormattersBuiltsrc/oaken_core/formatters · map

Split a raw item into named parts before triage. Core ships json; others (ini, rfc822) live in oaken-plugins.

Calls

Plugin base classes

Called by

Intake Plugin host

Notifies (event or callback, upward)

none

Notified by

none

Types

Name	Kind	Meaning
`JsonFormatter`	class	One part per key of a JSON object.

Inherits

Class	Bases	What it is
`JsonFormatter`	`BaseFormatter`	A JSON object becomes one part per top-level key (the value is the part's content). Anything else

External none

ProvidersBuilt untrusted inputsrc/oaken_core/providers · map

Sources that bring items into intake. Core ships socket, the machine's door: a template, one instance per Unix path or loopback port, each with its own source and format.

Calls

Plugin contracts Plugin base classes

Called by

Plugin host

Notifies (event or callback, upward)

Intake

Notified by

none

Types

Name	Kind	Meaning
`SocketProvider`	template	Whatever is written to its socket is submitted to intake; replies OK or ERR per item.

Inherits

Class	Bases	What it is
`SocketProvider`	`BaseTemplatePlugin`, `BaseProvider`	A door for the machine: whatever is written to its Unix socket (or loopback port) is submitted to intake. A template: make an

External none

Notes

A provider reaches intake only through the submit callback it is given, never by import.

Items ingestorBuiltsrc/oaken_core/items.py · map

The built-in ingestor: stores each accepted item (body and parts) as a row. It steps aside when a product installs its own, and oaken items list filters it by label, part and date.

Calls

Plugin contracts Plugin base classes

Called by

Intake Plugin host

Notifies (event or callback, upward)

none

Notified by

none

Types

Name	Kind	Meaning
`ItemsIngestor`	class	The fallback ingestor.

Inherits

Class	Bases	What it is
`ItemsIngestor`	`BaseIngestor`

External none

Notes

The ingestor kind is exclusive: one is active at a time.

Runtime

JobsBuiltsrc/oaken_core/jobs.py · map

The durable job store and the runner. Jobs have a kind, a queue, a priority, retries and leases; a crash loses nothing. Handlers are registered by core and by plugins.

Calls

Agents Change log Database Events and log Labels Settings

Called by

Core daemon Intake Operation registry Plugin host Queues Scheduler

Notifies (event or callback, upward)

Intake Plugin host

Notified by

none

Types

Name	Kind	Meaning
`Jobs`	class	The store: enqueue, claim, complete, fail, requeue, stats.
`JobRunner`	class	Runs each queue's workers and calls the registered handler.
`JobSpec`	dataclass	Kind, payload, subject and priority.

Inherits

Class	Bases	What it is
`PermanentJobError`	`OakenError`	Raise from a handler to fail the job at once, without retries.

External none

Notes

Imports the queues for the default queue name: untangle by moving it to a shared constant.

QueuesBuiltsrc/oaken_core/queues.py · map

Named queues, each the stage for one kind of analyzer plugin, defined in config.toml. A queue submits jobs; pausing a queue stops it handing out work.

Calls

Jobs

Called by

Console Core daemon Intake Operation registry Scheduler

Notifies (event or callback, upward)

none

Notified by

none

Types

Name	Kind	Meaning
`Queue`	dataclass	Name, kind, label, workers and what is off in it.
`Queues`	class	The registry of queues.

External none

SchedulerBuiltsrc/oaken_core/scheduler.py · map

Recurring jobs by interval or cron (UTC). A due schedule enqueues its job and moves its next run in one transaction, so a crash neither repeats nor loses a run. Plugins seed their own tasks once.

Calls

Database Jobs Queues

Called by

Core daemon Operation registry Plugin host

Notifies (event or callback, upward)

none

Notified by

none

Types

Name	Kind	Meaning
`Scheduler`	class	add, remove, rows, run_now and the tick loop.

External none

Notes

Schedules live in the database. Create, change, remove and run-now are operations and a console tab.

AgentsBuilt untrusted inputsrc/oaken_core/agents.py · map

External workers with their own tokens that lease jobs over the API or MCP. Off unless enabled; each agent is bounded by the kinds, queues and quotas of its token.

Calls

Database Events and log Settings

Called by

Local API Core daemon Jobs Operation registry

Notifies (event or callback, upward)

none

Notified by

none

Types

Name	Kind	Meaning
`AgentRegistry`	class	Creates, authenticates and bounds agents.

External none

State

LabelsBuiltsrc/oaken_core/labels.py · map

Key and value tags on a subject, in two layers (machine and human). A key must be defined before it is written, by core, a plugin or the owner.

Calls

Change log Database

Called by

Plugin contracts Core daemon Intake Jobs Operation registry Plugin base classes Plugin host

Notifies (event or callback, upward)

none

Notified by

none

Types

Name	Kind	Meaning
`LabelMaker`	class	The registry of defined keys, with allowed values and who may write them.
`LabelStore`	class	Reads and writes labels, with the human value winning.

Inherits

Class	Bases	What it is
`LabelError`	`OakenError`
`ReservedLabel`	`BaseLabel`	A key core owns. Plugins can write it and cannot define it.

External none

Change logBuiltsrc/oaken_core/changelog.py · map

Who changed what and when, appended in the same transaction as the change. Content-free: a reject logs a hash and a reason.

Calls

Database

Called by

Core daemon Intake Jobs Labels Operation registry

Notifies (event or callback, upward)

none

Notified by

none

Types

Name	Kind	Meaning
`ChangeLog`	class	Append and read rows.

External none

Events and logBuiltsrc/oaken_core/events.py · map

The event bus for job state, plugin health and live updates, and the kept log file with its readers.

Calls

Database

Called by

Agents Local API Plugin contracts Core daemon Jobs Operation registry Plugin host

Notifies (event or callback, upward)

none

Notified by

none

Types

Name	Kind	Meaning
`EventBus`	class	Publishes events to streams.
`JobStateChanged`	dataclass	A job moved state.

Inherits

Class	Bases	What it is
`JobStateChanged`	`Event`	JobStateChanged(*, ts: datetime.datetime, event_id: str = <factory>, job_id: oaken_core.ids.JobId, kind: str, queue: str, status: str, subject: str \| None = None)
`LogEvent`	`Event`	One log line, as ``logging` `made it (already scrubbed). Published with` `publish_nowait``: only streams see it, so the
`PluginEvent`	`Event`	Base for events a plugin defines itself: subclass it, add plain-data fields, and publish
`PluginHealthChanged`	`Event`	PluginHealthChanged(*, ts: datetime.datetime, event_id: str = <factory>, plugin: str, healthy: bool, detail: str = '')
`QueueStateChanged`	`Event`	QueueStateChanged(*, ts: datetime.datetime, event_id: str = <factory>, queue: str, paused: bool)
`TraceEvent`	`Event`	One line of the trace, which holds private text. It is published with ``publish_nowait``, so

External none

DatabaseBuiltsrc/oaken_core/db.py · map

The portable-SQL handle every store provides: execute, fetch, transactions and one migration runner across core and plugin tables. SQLite ships as the default store plugin.

Calls

none

Called by

Agents Change log Plugin contracts Events and log Jobs Labels Operation registry Plugin base classes Plugin host Model router Scheduler

Notifies (event or callback, upward)

none

Notified by

none

Types

Name	Kind	Meaning
`Database`	class	execute, fetchone, fetchall, transaction, migrate.

External none

Notes

The store module defines the SQLite store plugin, so this package imports the plugin base classes.

Foundation

SettingsBuiltsrc/oaken_core/settings.py · map

config.toml loaded and checked, edited in place with a backup, and the paths and secrets it points at.

Calls

none

Called by

Agents Console Core daemon Jobs Operation registry Plugin host Model router

Notifies (event or callback, upward)

none

Notified by

none

Types

Name	Kind	Meaning
`Settings`	class	The validated configuration, including [plugins.<kind>.<name>] tables and [extensions].

External none

Untrusted textBuiltsrc/oaken_core/untrusted.py · map

Text from outside is data, never instructions. It reaches a model only wrapped as UntrustedText, between markers the model is told not to obey.

Calls

none

Called by

Local API Plugin contracts Model router Triagers

Notifies (event or callback, upward)

none

Notified by

none

Types

Name	Kind	Meaning
`UntrustedText`	class	A body or source wrapped for a model.

External none

Class relationships

Every class that takes part in an in-core inheritance, read from the live package by docs/tools/classmap.py into docs/softmap.classes.toml. Subclasses nest under their base; the arrow names a base from outside the package.

_Body ← BaseModel (Local API)
- CallRequest (Local API)
ApiClient ← ABC (CLI)
- HttpApiClient (CLI)
- InProcessApiClient (CLI)
CliError ← Exception (CLI)
- CoreUnavailable (CLI)
_Base (CLI)
- AgentClient (CLI)
- HttpApiClient (CLI)
OakenError ← Exception (no component)
- AIBackendError (no component)
- ConfigError (no component)
- Conflict (no component)
- InvalidInput (no component)
- InvalidResult (no component)
- NotFound (no component)
- PermissionDenied (no component)
  - ConfidentialRefused (no component)
  - ConfirmationInvalid (no component)
  - NotExposed (no component)
  - SendDisabled (no component)
- PluginError (no component)
- ProviderError (no component)
  - AuthError (no component)
- QuotaExceeded (no component)
- StorageError (no component)
  - IndexMismatch (no component)
- Unavailable (no component)
  - Deferred (no component)
- PermanentJobError (Jobs)
- LabelError (Labels)
EventLog (no component)
- Tracer (no component)
Event (Events and log)
- JobStateChanged (Events and log)
- LogEvent (Events and log)
- PluginEvent (Events and log)
- PluginHealthChanged (Events and log)
- QueueStateChanged (Events and log)
- TraceEvent (Events and log)
IntakePayload ← BaseModel (Intake)
- StorePayload (Intake)
BaseLabel (Labels)
- ReservedLabel (Labels)
_Quiet ← Handler (no component)
- _FileHandler ← RotatingFileHandler (no component)
- _StreamHandler ← StreamHandler (no component)
AgentRef ← BaseModel (Operation registry)
- AgentGrantIn (Operation registry)
JobRef ← BaseModel (Operation registry)
- CompleteIn (Operation registry)
- FailIn (Operation registry)
ScheduleRef ← BaseModel (Operation registry)
- ScheduleEditIn (Operation registry)
SecretRef ← BaseModel (Operation registry)
- SecretSetIn (Operation registry)
BaseMultitenant (Plugin base classes)
- LlmTriager (Triagers)
BasePlugin (Plugin base classes)
- BaseAnalyzer (Plugin base classes)
  - BaseAction (Plugin base classes)
  - BaseEnricher (Plugin base classes)
  - BaseLLMAnalyzer (Plugin base classes)
    - LlmTriager (Triagers)
  - BaseTriager (Plugin base classes)
    - NearJunk (Model router)
    - DedupeTriager (Triagers)
    - LlmTriager (Triagers)
    - RulesTriager (Triagers)
  - BaseVecAnalyzer (Plugin base classes)
    - NearJunk (Model router)
- BaseCache (Plugin base classes)
- BaseEmbedder (Plugin base classes)
- BaseFormatter (Plugin base classes)
  - JsonFormatter (Formatters)
- BaseFriendlyNames (Plugin base classes)
- BaseIngestor (Plugin base classes)
  - ItemsIngestor (Items ingestor)
- BaseLLMBackend (Plugin base classes)
- BaseProvider (Plugin base classes)
  - SocketProvider (Providers)
- BaseStore (Plugin base classes)
  - SqliteStore (no component)
- BaseTemplatePlugin (Plugin base classes)
  - SocketProvider (Providers)
  - LlmTriager (Triagers)
- BaseVectorStore (Plugin base classes)
  - SqliteVecStore (no component)
- MemoryVectors (Model router)
- StubBackend (Model router)
- StubEmbedder (Model router)

Call flows

Each step is one call from one component into another, checked against the declared relationships at build time.

An item arrives

#	From		To	What happens	Notes
1	Providers	→	Intake	submit(item) callback	The provider is handed a callback; it never imports intake.
2	Intake	→	Jobs	enqueue the format job	Durable, so a crash loses nothing.
3	Jobs	→	Intake	run the format job callback	A handler intake registered.
4	Intake	→	Formatters	split into parts	Deterministic; no model.
5	Intake	→	Triagers	ask each triager	Any reject ends it; the last to answer decides.
6	Intake	→	Labels	write each answering triager's labels	Under that triager's own name.
7	Intake	→	Jobs	enqueue the store job	Accepted items only.
8	Jobs	→	Intake	run the store job callback	A handler intake registered.
9	Intake	→	Items ingestor	ingest	The one active ingestor.
10	Intake	→	Change log	record the ingest	Content-free.

A scheduled task runs

#	From		To	What happens	Notes
1	Scheduler	→	Jobs	enqueue the task's job	The job carries a dedupe key naming the slot.
2	Jobs	→	Plugin host	run the plugin's job handler callback	Registered at start as plugin.NAME.KIND.
3	Plugin host	→	Providers	call the handler	For example an exec instance running a program.
4	Providers	→	Intake	submit(row) callback	One item per row it printed.

A person changes something

#	From		To	What happens	Notes
1	Console	→	Operation registry	call an operation	A mutation comes back as a proposal first.
2	Operation registry	→	Plugin host	for example plugin_add	Writes the instance, and the template if it is new.
3	Operation registry	→	Settings	edit config.toml	Written with a backup, then core reloads.
4	Operation registry	→	Change log	record who did it	Audited by the registry.

A plugin loads

#	From		To	What happens	Notes
1	Core daemon	→	Plugin host	start the host	Store first, then everything else.
2	Plugin host	→	Catalog and extensions	find the plugin	Entry points, extension directories, oaken-plugins.
3	Plugin host	→	Plugin base classes	check it against its kind's contract	A fault switches that plugin off, not core.
4	Plugin host	→	Labels	register its label keys	A bad definition switches it off.
5	Plugin host	→	Scheduler	seed its scheduled tasks	Only if absent: after that they are the owner's.

Dependency matrix

Row is the caller, column is the target. C is a direct call, B is an event or registered callback.

	Local API	Console	Operation registry	Intake	Triagers	Model router	Plugin host	Plugin base classes	Plugin contracts	Catalog and extensions	Formatters	Providers	Items ingestor	Jobs	Queues	Scheduler	Agents	Labels	Change log	Events and log	Database	Settings	Untrusted text
Core daemon	C	C	C	C		C	C							C	C	C	C	C	C	C		C
CLI	C		C
Local API			C														C			C			C
Console			C				C								C							C
Operation registry						C	C							C	C	C	C	C	C	C	C	C
Intake					C						C		C	C	C			C	C
Triagers						C		C	C														C
Model router								C	C												C	C	C
Plugin host			B					C	C	C	C	C	C	C		C		C		C	C	C
Plugin base classes									C									C			C
Plugin contracts																		C		C	C		C
Catalog and extensions
Formatters								C
Providers				B				C	C
Items ingestor								C	C
Jobs				B			B										C	C	C	C	C	C
Queues														C
Scheduler														C	C						C
Agents																				C	C	C
Labels																			C		C
Change log																					C
Events and log																					C
Database
Settings
Untrusted text

Checks

Run every time the docs are built; the build fails if any of these stops being true.

Result	Check	Detail
pass	Components	25 components, 0 documented functions
pass	Relationships	92 calls and 4 events or callbacks
pass	Layering	Every call goes to the same or a lower layer; every callback goes strictly upward
pass	Call graph	Acyclic
pass	Call flows	4 flows, 23 steps, each following a declared relationship
pass	Repository	Built and partial components point at paths that exist; planned ones have none yet

Entry points, which nothing else calls because the user or an event drives them: Core daemon, CLI.

Open points

Topic	Note