animus-subject-postgres

A dynamic, schema-driven Postgres subject store for Animus — a BaaS. This stdio JSON-RPC subject_backend plugin lets agents declare subject kinds at runtime (not hardcoded) and then run generic CRUD over any registered kind. Every subject of every kind is stored in one subjects table with a JSONB data column for the declared custom fields; the standard subject defaults (id, title, status, priority, timestamps) are managed by the plugin.

What it does

• Runtime kind registry. Kinds live in a subject_kind table and are managed with subject_kind/{declare,list,update,delete}. A kind declares a slug name, an id_prefix, an optional title_field, and a fields schema ([{name,type,required,default,description}]).
• One table for all subjects. subjects(id, kind, title, status, priority, data JSONB, created_at, updated_at). The managed columns are auto-filled; declared + ad-hoc custom fields live in data.
• Validated, defaulted writes. On create the kind is resolved from the registry, an id <PREFIX>-<n> is minted from an atomic per-kind counter, the request's custom fields are type-checked + defaulted against the kind's schema, and managed defaults are applied.
• Catch-all routing. Declares subject_kind:* so the kernel router forwards ANY kind not claimed by another backend here (plus explicit task/requirement/blog caps for clarity and the preflight-required subject_kind:task).

Wire surface

Kind management (the BaaS control surface):

Method	Shape
subject_kind/declare	{ name, id_prefix?, title_field?, fields? } → stored kind (upsert, idempotent)
subject_kind/list	→ { kinds: [KindDef + subject_count] }
subject_kind/update	{ name, fields?, title_field?, id_prefix? } → stored kind
subject_kind/delete	{ name, cascade? } → { name, deleted } (refuses if subjects exist unless cascade; never task/requirement)

Generic subject CRUD over ANY registered kind, via both <kind>/<verb> and the kind-agnostic subject/<verb> forms:

Verb	Notes
list / list_filtered	optional status, limit, cursor
list_prioritized	ordered by priority desc
next	highest-priority ready/in-progress subject
statistics	counts by status
get	by id (task:TASK-001 or bare TASK-001)
create	validates + defaults custom fields; mints id
update	merges + re-validates custom fields, bumps updated_at
status	sets native status
delete	removes the row
subject/{list,get,update,delete,schema,watch,unwatch}	protocol-canonical verbs

Field types

fields entries take a type of text, number, bool, timestamp, or json. required: true is enforced on create only (validate-on-write): adding a required field with no default to a kind that already has rows is allowed — existing rows simply lack it. A declared default is filled when the field is absent and must itself match the field type.

Built-in kinds (seeded on boot if absent)

• task (id_prefix TASK)
• requirement (id_prefix REQUIREMENT)
• blog (id_prefix BLOG, fields: author text, slug text, body_md text required, tags json)

knowledge is intentionally NOT seeded — the portal maps that to an existing table separately.

Data layout & migration

• Connection URL from DATABASE_URL (fallback ANIMUS_POSTGRES_URL).
• Schema (subject_kind + subjects, with indexes on (kind, status) and a GIN index on data) is auto-created on startup unless ANIMUS_POSTGRES_AUTO_MIGRATE is falsey.
• Back-compat: when a prior hardcoded-layout tasks table exists, its TASK-* / REQUIREMENT-* rows are migrated into subjects (ids, status, priority, and the full legacy json payload preserved under data, timestamps from the legacy metadata). The import guards on table existence and uses ON CONFLICT (id) DO NOTHING, so it is safe + idempotent.

Installation

animus plugin install launchapp-dev/animus-subject-postgres

Provide a Postgres URL via the environment (DATABASE_URL or ANIMUS_POSTGRES_URL) before starting the daemon.

Configuration

Env var	Default	Description
DATABASE_URL	—	Postgres connection URL
ANIMUS_POSTGRES_URL	—	Fallback Postgres URL when DATABASE_URL is unset
ANIMUS_POSTGRES_AUTO_MIGRATE	on	Set to 0/false/no/off to skip auto-migrate
ANIMUS_DEFAULT_TASK_ID_PAD	3	Zero-pad width (e.g. 3 → TASK-007)

Build & test

cargo build --release
cargo test                       # pure-logic unit tests
DATABASE_URL=postgres://localhost/animus_test cargo test -- --ignored

License

Elastic License 2.0. See LICENSE.