Spend showback and budgets

Project Synapse records the direct variable model cost of every agent run and attributes it to a cost center. Administrators see that spend per cost center and month on the Spend page, cost-center owners see their own centers on My spend, and every paid (real-model) request is checked against a monthly budget before any money is spent.

The numbers are showback: direct variable model cost, shown so teams can see what their work costs. This is not an invoice or chargeback, and it is not the full cost of running the platform. The page states this with the fixed line "Allocated platform cost: not configured".

What the spend pages show

Each row is one cost center in one UTC calendar month.

• Direct cost: estimated, reconciled and unknown usage for the month. Unknown usage is never shown as zero; it carries the reserved amount as an upper bound.
• Reserved open: money reserved for requests that have not settled yet.
• Window to date: direct cost plus reserved open. This is what the budget is compared against.
• Budget: how much of the governing hard cap is used, and the soft threshold. An Over cap badge means new paid work is refused. A Soft threshold crossed badge means spend passed the warning level this month; it never blocks work.
• Runs, succeeded and approved: with the cost per succeeded run and per approved outcome. When a count is zero the cost shows as "n/a".
• Projection: for the current month only, a linear projection to month end (month to date divided by completed days, times the days in the month). It shows "n/a" on the first day of the month. Past months show actuals.
• Anomaly: flagged when this month is more than twice the average of the three calendar months before it, counting a month without spend as zero. If those three months had no spend at all, any spend is flagged. Until the cost center's first month with spend is at least three months back, it reads "insufficient history".
• Reconciliation: how many runs are estimated, reconciled or unknown.

My spend shows only the cost centers you own, each with its burn against its own budget and the same over-cap and soft-threshold badges. If you own none, the page says so and shows nothing else. The unassigned pool is shown to administrators only.

The unassigned pool

Every new run is stamped with the cost center its user is mapped to at that moment. Users with no mapping are stamped unassigned.

The unassigned row is one pool. It covers runs stamped unassigned and the runs of every cost center that has no budget applying to the month. The unassigned budget governs that whole pool. Budgeting a cost center moves its runs to its own row from the next reservation on.

Out of the box the unassigned budget is zero, so paid work in the pool is refused. Mock (zero-cost) runs are never refused.

Mapping rules

1. Mappings cannot start in the past. Leave the start empty to map from now, or pick a future start.
2. A remap must start after the current mapping's start, including a future-dated mapping that has not begun yet.
3. Runs keep the cost center they were stamped with. Remapping a user changes new runs only.

Budgets and overrides

A budget is a monthly hard cap with a soft threshold (a share of the cap, 80 percent by default). It applies from its start month onward until a later budget replaces it. Budgets can be set for the organization, a cost center, or a single user, agent or workflow; a request must fit under every level that has one.

Budgets are never edited in place. Setting a new budget for the same scope and start month while one is active asks you to confirm the override; the new row supersedes the old one, and both stay on record.

Export and its audit record

Auditors and administrators can export the rows as a CSV file of up to 24 months and 5,000 rows. The columns are cost center code, month, provider, model, reconciliation status, direct cost, reserved open and run counts. The file never contains prompts, inputs, outputs, email addresses or user ids. Cells that a spreadsheet could read as a formula are prefixed with an apostrophe.

Every export is written to the audit ledger before the file is served, and the page shows its audit event id. Repeating the same export request returns the same audit event.

Operator step: turning on paid work

Until an administrator completes these three steps, paid (real-model) work is refused for unmapped users, and mock runs keep working. Each step is recorded in the audit ledger, and the settings page shows the audit event id.

1. Create a cost center on Spend, Budgets and cost centers. Give it a short lowercase code, a name and optionally an owner. The new center then appears in the page's cost-center list with its id.
2. Map the user to that cost center by choosing it in the map-user form.
3. Set a budget for the cost center: scope "Cost center", the center's id as the scope id (the form suggests it), the start month and a hard cap.

The next paid request from that user is then checked against the new cost center's budget instead of the zero-capped unassigned pool.

A deployment may instead budget the unassigned pool directly: set a budget with the unassigned center as its scope, and every user mapped to no other center reserves against that one cap. The demo site does this, and no user there is mapped to another center.