Skip to content
MSO CloudDocumentation

The learning loop

On this page

In short#

The learning loop carries a source event to a ranked proposal, a person's decision, a measured outcome and a label, and feeds the label back into the next ranking. ADR 0060 (docs/adr/0060-self-learning-seams.md, accepted on 7 November 2026) wired measured reward to the served policy; four parts of its seams are still open (see Where it stops).

1 · Source dataraw_events, silver, agg_*deduped per payloadS4: lineage ids; watermark open2 · Signal ledgersignal_events, append-onlyworker writes, 07:00 jobS1 open: catalog weights3 · Proposaldecisions, episode ledgerranked, or abstains4 · Approvalowner or org adminguardrails, audit log5 · Actionmanual steps by a personno marketplace write6 · Outcomedecision_outcomesdeclared conversion7 · Labelowner verdict, dismissalshit, partial or missS1: chat thumbs, alert triage8 · Learned statetrack records, weightspolicy models, versionsS2: 10 % held as controldismissals demoteS3: champion policy rankstrack record reorders (8+ confirmed)S2: confirmed lift fits the policyBlue: worker. Amber: a person. Purple: learned state, rebuilt from the ledgers. Numbers are the order of one pass.
Learning loop. Every arrow is wired. Purple labels name the ADR 0060 seam; "open" marks the part not built.

How it works#

Each stage writes one store under a re-run key, so a repeated pass writes nothing new. Every table named below is under per-organization row-level security, and a person stands between the machine's proposal and anything that happens outside the platform.

# Stage Store Writer, and who else may change a row Re-run key Gate
1 Source data raw_events, then silver tables and agg_* rollups Connector sync and the webhook route; the promoter sets processed_at Organization, connector, stream, id, payload hash verify:data on rollups
2 Signal ledger signal_events The worker only; the web runtime may set four feedback columns Organization, brand, idempotency key Append-only trigger, verify:rls
3 Proposal decisions, decision_episodes The worker's decision cycle, ranking with the champion policy; episodes are never updated Organization, brand, date, campaign / episode key verify:rls decision replay, verify:data
4 Approval decisions status, approver and time; experiment_assignments arm Owner or org admin, with an audit entry Update predicated on the current status, run first decision-mutation-rbac.py
5 Action action_commands Inserted in the approval's transaction; a control-arm decision's commands are written as held out; a person carries out the rest The approval claim: a repeated approve inserts none Marketplace connectors return manual steps
6 Outcome decision_outcomes; observed lift on experiment_assignments The worker measures on the declared conversion and writes the lift on both arms; a control-arm outcome abstains One row per decision verify:data #61
7 Label decision_outcomes verdict; signal_events feedback; alert_events status; chat_messages rating Owner or org admin confirms hit, partial or miss, marks a brief signal done, acknowledges or resolves an alert; a member rates their own assistant answers Same row as the outcome, signal, incident or message Owner check in the router
8 Learned state playbook_stats, signal_stats, policy_models, policy_versions The worker rebuilds the caches and fits lever posteriors on confirmed lift; promotion and rollback are human-only Natural key per organization and brand verify:data re-derives playbook_stats and #20

Current state per arrow#

Arrow in the figure Today Evidence Seam
1 to 2: source to ledger Orders and inventory snapshots carry their Bronze row and sync batch; webhook ingest and the event bus share one envelope. The data watermark column has no writer yet packages/platform-contract/src/event-envelope.ts:13, packages/schema/src/tables/orders.ts:90, packages/schema/src/tables/mso-episodes.ts:295 S4, open
2 to 3: ledger to proposal The episode carries the fired signal instance it stands on packages/schema/src/tables/mso-episodes.ts:341 none
4 to 5: approval to action The status claim runs first, then the commands and one arm row each, in one transaction; 10 % of decisions fall in a control arm keyed on the decision, so a re-approve keeps its arm apps/web/src/server/routers/offtake.ts:323, :349, :1155; packages/metrics/src/offtake.ts:697 S2
6 to 7: outcome to label Owner verdict on decisions, refused for a control decision; alert incidents are acknowledged or resolved; assistant answers carry a thumbs rating apps/web/src/server/routers/offtake.ts:408, :960; apps/web/src/server/routers/alerts.ts:513; apps/web/src/server/routers/chat.ts:145 S1
7 to 8: label to learned state Track records rebuild from owner-confirmed verdicts only packages/metrics/src/offtake-loop.ts:508 none
8 to 3: track record Reorders a rule once it has 8 confirmed outcomes; the set of eligible rules never changes packages/metrics/src/playbook-stats-rank.ts:96, packages/metrics/src/offtake-loop.ts:914 none
8 to 2: dismissals Demote, never promote; the dataset signal collector reads the weights, the catalog-measure collector does not, because the input is optional packages/metrics/src/dataset-signal-collect.ts:474, packages/metrics/src/signal-binding.ts:346 S1, open
6 to 8: reward Lift is the conversion after execution against the equal window before it; the lever posterior folds confirmed treatment-arm lifts from a 0 bp prior; without confirmed positive lift the policy abstains as cold start packages/metrics/src/offtake-loop.ts:4626, packages/metrics/src/policy-loop.ts:226, :451 S2
8 to 3: promoted policy The scan ranks with the champion's configuration when exactly one valid champion exists, else with the defaults; the receipt pins its id and version, and replay re-ranks with it packages/metrics/src/offtake-loop.ts:916, packages/metrics/src/decision-replay.ts:93, :237 S3
Outside the figure: prompts and eval CI runs the agent eval dry run against a committed baseline; chat records a hash of its system prompt; prompt templates carry a version and hash; a monthly chat token cap per organization .github/workflows/ci.yml:114, apps/web/src/app/api/chat/route.ts:457, packages/schema/src/tables/ai-prompt-templates.ts:69, packages/schema/src/tables/orgs.ts:48 S5

Field-level detail of the envelope and lineage columns is on Event contract.

Where it stops#

  • A machine never approves, executes or confirms a decision; approved decision actions are manual steps, and no connector writes to a marketplace or ad account.
  • Selection is deterministic, so off-policy evaluation refuses on today's logs. The holdout is a control arm per decision, not a randomized choice among playbooks.
  • The lift is before-and-after per decision and is not yet adjusted by the control arm.
  • Open parts of the seams: weights required on every signal collector and a feedback episode kind (S1), thumbs in the deck assistant (S1), a writer for the data watermark (S4).
  • No prior is pooled across organizations; a cross-organization prior needs a consent mechanism that does not exist.
  • A separate causal compute service stays out of scope (ADR 0009, deferred by ADR 0060).
  • Dated status per capability, including the evidence ladder: Project status.