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

0 downloads

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
dbbasic-package.json · 11.5 KB · 98 lines
1{
2 "id": "app-runner",
3 "name": "Template Runner",
4 "version": "0.4.0",
5 "description": "Press Run on a template: hold the money, queue the job, execute it on the daemon, settle. The engine the predecessor's real product ran on -- its live workload was template execution and AI generation with a metered wallet, hand-built once per template kind; this is that as ONE engine with pluggable handlers, where claiming, charging, settling and reporting belong to the engine and a handler owns exactly one thing: turning a claimed run into an output or an error. TWO DECISIONS CARRY IT, BOTH ABOUT MONEY. FIRST: A RUN IS A COMMITMENT, AND THE CHARGE IS A HOLD THEN A SETTLEMENT. Charging after execution means a user with five cents queues four hundred runs and the provider bill arrives anyway -- the gate never fires because nothing has been spent at the moment it is asked. Charging before, as a plain debit, means every failure needs a refund path and a crash between charged and ran leaves money taken for nothing. So the hold is a wallet entry (negative, placed at queue time THROUGH hook_wallet_entries asked in process, the same act as action_checkout's gift-card debit), settlement releases it in full and charges an ORDINARY debit for the stamped price on success, or releases alone on failure. The charge being an ordinary debit is deliberate: every report that reads debits keeps working, and a released hold never masquerades as a refund -- a hold is not a debit that got undone, it is money that was never spent. Settlement is idempotent by provenance marker (template_run/<id>/release), checked against the ENTRIES and never against run status, because the crash worth designing for is the one between writing money and updating status; the runner and the sweeper can both reach settlement and the marker means at most one writes (doctrine #7). Money is written first, status second: replayed, the settle is a no-op and status catches up, where the other order leaves a run marked settled whose money never moved. SECOND: THE TERMS ARE STAMPED AT QUEUE TIME. Handler, rendered body, model, price -- copied onto the run when the user presses the button, because a template is edited constantly (that is what makes it a template) and last month's history must read what last month cost, not what this month's prices would have made it cost (doctrine #1). Even the rendered body is stamped rather than re-rendered, because rendering reads the template and by execution time the template may say something else. THE HARD PART IS NAMED RATHER THAN HANDLED CLEVERLY: the provider call is not idempotent and is not ours. A run interrupted between calling and recording may or may not have been billed, and nothing on this box can know which. So the sweeper marks a heartbeat-dead run abandoned -- a terminal status with no exits in the declared transition map -- releases its hold, and NEVER RETRIES; automatic retry of a paid non-idempotent call is an unbounded spend wearing a robustness costume, and a retry here is a new run, with a new hold, started by a person who can read provider_job_id and ask the provider what happened. Our idempotency key is minted at queue time and recorded BEFORE any call, so providers that honour one (OpenAI does) make even the crash case safe when those handlers arrive. Capability boundaries are refused at QUEUE time with a 409 naming what to configure -- an ai template with no model setting or no stored provider key refuses while the person who can fix it is looking at the screen, rather than failing on the daemon an hour later -- and re-checked at execution for the rare race where a key vanishes in between. Slice 1 ships two handlers: echo (free, no provider -- the handler that proves the money model without spending a cent) and ai_text (the rendered body to the stamped model through object_ai, provider cost computed from ai_prices where present and recorded on the run, never billed to the user -- price minus provider cost is margin, per run, as a fold). What a handler must never do is silently degrade: no placeholder output, ever -- a run that did not do the thing fails, releases its hold, and says why in words a person can act on. Deliberately NOT here, named so it reads as decisions: no update grant on template_runs for anybody (the only hands that move a run are the runner and the sweeper, in process, walking the declared transitions -- a person who could PUT abandoned back to queued would be re-running a paid call from a form field); no image/video/screenshot handlers yet (each is an afternoon once the engine holds, and each is a capability boundary behind a real provider); no output-as-provider-URL when those arrive (provider URLs expire, and a run whose output has vanished is a charge with nothing to show for it); and no automatic retry, which is worth saying twice. This version adds ASYNCHRONOUS execution, because a Sora job takes minutes and q9 budgets thirty: executing it inline would block the pass, stall the batch, and collide with the sweeper writing off a job that is legitimately still running. A run gains `running` between claimed and terminal -- submit, store provider_job_id, RETURN; later passes poll, and a poll that finds the job unfinished simply touches the heartbeat, which is what stops the sweeper writing it off (so runner.stale_seconds must exceed the POLL interval, not the job duration). Handlers declare their shape by which registry they appear in; echo and ai_text stay inline. THE MONEY RULE IS THE POINT, and it is the one place the original sweeper was actively wrong: a run carrying a provider_job_id is NEVER abandoned. Abandoning is what releases the hold, and a job the provider is already holding may already have cost everything, so handing the money back on a timer means paying for it ourselves -- while the mirror, charging a run whose outcome we never learned, bills a customer for something they may never have received. The box cannot tell which and refuses to guess: such a run is polled (the provider can simply be asked), and if polling never resolves it within runner.max_run_seconds it becomes `needs_review` with the hold STILL ON, for a person to decide. needs_review is deliberately absent from TERMINAL_STATUSES, because that tuple is exactly what drives the automatic release the escalation exists to prevent, and `running` can never reach `abandoned` in the transition map for the same reason. 0.3.0 adds action_resolve_run, which is the other half of needs_review: a machine that stops without a way to continue has not made a decision, it has abandoned a queue. This is the ONLY hand that moves a run out of needs_review and it is a person's. The two decisions are deliberately asymmetric. 'refund' is the ordinary failure settlement -- release the hold, charge nothing -- and what it cost US stays visible on the run as provider_cost_cents rather than becoming a silent write-off. 'charge' is the release-plus-debit a successful run gets, for when the operator has established by other means (the provider's dashboard, the file that landed) that the work arrived. Note what charge does NOT do: it never re-runs anything and never contacts the provider, because automatic retry of a paid non-idempotent call is the standing refusal and a resolution verb is not a loophole in it. It refuses any run not actually in needs_review -- a terminal run is already settled, and a running one may still be answered, where polling is cheaper and more truthful than a guess. It also declares an attention count, because this is the one queue on the box where doing nothing costs somebody money CONTINUOUSLY: a backorder makes a customer wait, while an unresolved run holds their balance down against a job nobody will ever settle. The detail leads with the amount held rather than the age for exactly that reason -- it is the same number the customer is looking at in their own balance. This version adds template_runs.task_id -- an OPTIONAL link from a run to the task it serves, and the one piece of q9's separate tasks.Work model this runner did not already have. It gets no second execution model: everything Work would have needed (a status machine, idempotent settlement, staleness detection, async submit/poll, an escalation path) already exists here, built and proven under real money, where Work had none of it and its billing lived in a THIRD, disconnected model kept in sync by hand. Multiple attempts against one task are just multiple runs sharing a task_id -- a fold, not a stored history, the same doctrine as everywhere else in this codebase. Ownership is checked at queue time (a caller may only link a run to a task they own, or as admin), and nothing here mutates the task's own status on success: a run succeeding is not the same claim as the task being finished, and that stays a person's call.",
6 "compatibility": {
7 "dbbasic_object_server": ">=0.1.0"
8 },
9 "dependencies": [
10 "app-templates",
11 "app-billing",
12 "app-views"
13 ],
14 "objects": [
15 {
16 "id": "action_run_template",
17 "path": "objects/action/run_template.py"
18 },
19 {
20 "id": "system_template_runner",
21 "path": "objects/system/template_runner.py"
22 },
23 {
24 "id": "system_run_sweeper",
25 "path": "objects/system/run_sweeper.py"
26 },
27 {
28 "id": "action_resolve_run",
29 "path": "objects/action/resolve_run.py"
30 },
31 {
32 "id": "system_review_attention",
33 "path": "objects/system/review_attention.py"
34 }
35 ],
36 "schemas": [
37 {
38 "collection": "template_runs",
39 "path": "schemas/template_runs.json"
40 }
41 ],
42 "permissions": [
43 {
44 "path": "permissions/rules.json"
45 }
46 ],
47 "seed": [
48 {
49 "collection": "template_runs",
50 "path": "seed/template_runs.tsv"
51 },
52 {
53 "collection": "site_routes",
54 "path": "seed/site_routes.tsv"
55 },
56 {
57 "collection": "views",
58 "path": "seed/views.tsv"
59 }
60 ],
61 "migrations": [],
62 "schedules": [
63 {
64 "id": "template_runner_minutely",
65 "object_id": "system_template_runner",
66 "schedule": "* * * * *",
67 "description": "Claim and execute queued template runs, a small batch per pass (runner.batch, default 3). Minutely because a run is a person waiting: they pressed Run, money went on hold, and every minute of queue time is a minute of held money doing nothing. The batch bound keeps one pass short rather than letting a burst of submissions turn a pass into a marathon the scheduler reads as a hang -- a burst drains over several passes instead. Costs one collection read when the queue is empty."
68 },
69 {
70 "id": "run_sweeper_ten_minutely",
71 "object_id": "system_run_sweeper",
72 "schedule": "*/10 * * * *",
73 "description": "Release the holds of claimed runs whose heartbeat stopped (runner.stale_seconds, default 900) and mark them abandoned -- never retried, because the provider call may already have been made and paid for. Ten-minutely with a fifteen-minute staleness floor errs long on purpose: this sweep is for processes that DIED, and sweeping a run that is merely slow abandons work the provider will finish and bill for. The pass that turns 'a runner crashed holding somebody's money' from a support ticket into a ten-minute inconvenience."
74 }
75 ],
76 "nav": [
77 {
78 "id": "template_runs",
79 "label": "Runs",
80 "path": "/runs",
81 "blurb": "Every template run: what it cost, what came back, what failed",
82 "surface": "operator",
83 "group": "Work",
84 "order": 335
85 }
86 ],
87 "attention": [
88 {
89 "id": "runs_needing_review",
90 "object_id": "system_review_attention",
91 "label": "Runs needing a decision",
92 "path": "/runs",
93 "group": "Money",
94 "severity": "warning",
95 "nav_id": "template_runs"
96 }
97 ]
98}