Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

dbbasic-object-server/docs/write-pipeline.md
Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

danq9 signup: the person chooses the password and name on the confirm page 83c7aa6 2 weeks, 5 days ago History
write-pipeline.md · 6.3 KB · 107 lines

The Write Pipeline: What Happens, In What Order, And What Can Stop It

zero-to-code.md says where each kind of logic lives. This page is its runtime twin: when a record is written, every stage that runs, in order, with its failure semantics — because "code working with code, signals going around" is exactly where frameworks went dark. Django signals and Rails callbacks earned their reputation not because reactions are wrong but because nobody could answer why did my record change? without a debugger. Here the pipeline is fixed, short, and this page is its single description. Verified against object_server.py and object_records.py; if this page and the code disagree, fix one of them — that disagreement is a bug.

The synchronous path (inside the request)

Everything here happens before the client gets its response, in this order:

#stageon failurelives in
1permission check (collection + row rules)403, nothing ranpolicy
2field-write denial (schema field permissions)403, names the fieldsschema
3owner stamp — sessions get owner_id written server-side; clients cannot spoof it (admin tokens skip this: seeding and migration set ownership deliberately)—server
4pre-write hook (hooks.before_write) — may reject (its own 4xx) or transform (stamp fields; id/owner/read-only/computed protected)fails CLOSED: a broken hook is a 500 and no writehook/ object
5auto created_at, then computed fields materialize — rollups first, then formulas, so a formula may read a rollupa broken formula stores "" — fails SOFT, the write proceedsobject_computed
6schema validation — types, required, enums, relations-exist, integer-cents; runs on the final record, so a hook's transform is validated too400, no writeschema
7transition check — is this status move declared, and may this subject make it (when guards)403/409, no writeschema
8persist under the file lock, then the change-log entry (actor, before/after, changed fields)write errors surface as 4xx/5xxobject_records

Two asymmetries in there are doctrine, not accident: gates fail closed, derivations fail soft (a validation gate that silently passes on error is not a gate; a caption that blanks on error is just a blank caption), and hooks run before validation so that what a hook stamps is still checked like any client input.

The fan-out (after the write, same request, best-effort)

Once the record is durably written, the server fans out — in this order, each stage isolated so one failing never blocks the next, and none of them can un-write the record:

  1. rollup re-triggers — a payment write recomputes its invoice's rollup

fields (single-hop by design: a thread-local guard stops A→B→A cascades; a chain that needs more hops is a design smell, not a setting)

  1. realtime push — permission-filtered signal (collection, id, action);

subscribers re-fetch through the enforced API, so the socket never leaks record bodies

  1. event handlers (HANDLES objects) — the reaction layer: composers,

status flips. Payload carries the raw verb (create) while the event name uses the participle (…created) — accept both

  1. durable event log (when enabled) — for pollers and webhooks

The asynchronous tail (the daemon, seconds later)

Independent passes over the change log and collections, each with its own cursor, each at-least-once: notify (rules → in-app/email intents), email outbox drain, change dispatch (off by default — replays handlers for storage-level writes so reactions stop depending on which path wrote), auto-transitions (the 48h approve), scheduled runners (aging, dunning, recurring journals, matcher, escalation — every run's outcome a scheduler_runs record), queue messages (delay, retry, backoff).

How chains work without becoming Django signals

The reaction graph is real: a payment triggers the books composer, which writes a journal, whose lines re-trigger the journal's rollups. What keeps it legible instead of haunted:

  • One hop is synchronous, everything else is a record. A handler's

write does not re-enter the dispatcher (storage-level writes don't dispatch), so there is no unbounded cascade — a deeper chain must go through the change-dispatch pass, which has a cursor, markers, and a log.

  • Everything generated says who generated it: generated_from

provenance on composed records, actor on every change-log entry. "Why did my record change?" is a query, not a debugging session: record_changes names the actor; a composed journal names its source.

  • Idempotency by provenance means redelivery is safe by construction —

a replayed event composes nothing, so at-least-once is a guarantee, not a hazard.

  • Reactions may not gate and gates may not react

(logic-decisions.md #6). The moment a reaction can block a write, or a gate can send an email, the pipeline above stops being a truthful description — that boundary is what makes this page possible.

Multi-collection workflows

An order becomes an invoice becomes a payment becomes a journal; a task is claimed, submitted, approved, settled. There is deliberately no workflow engine — a business process here is a chain of (transition on one record) → (reaction that writes the next record), and each link is individually visible in the table above. The process's state is not hidden in an engine: it IS the records, their statuses, and their provenance stamps, which is why an AI operator can answer "where is this order stuck?" by reading collections. If a real orchestration need repeats (sagas, compensation across many collections), that is a doctrine-#4 moment — extract it then, from the concrete chains that exist.

Reading a live system

  • record_changes — who did what, before/after, per record
  • generated_from — what machine wrote this, from what source
  • /scheduler — what the clock did and what each run returned
  • execution logs — every hook and handler run, observable like any object
  • boot lines — the daemon prints every pass's posture (Books: NOT READY…,

Queue: enabled, Change dispatch: disabled) so a disabled layer is announced, not discovered