Data Model: Rules Engine

On this page

Overview

The rules engine stores JDM (JSON Decision Model) rule sets and a full audit trail of every evaluation. Rule sets are cached in memory at startup; at runtime the cache converges on the database through identity-aware conditional applies keyed on the trigger-enforced (id, revision) pair (#1188 / the ADR-006 #1188 amendment) — driven by RabbitMQ rules.cache_invalidated events from peers AND a periodic reconcile sweep (CRAIG_RULES__DECISION_REFRESH_SECONDS) that bounds staleness when an event is lost.

The fleet-standard platform tables also live in this schema and are documented centrally: event_outbox / event_inbox / event_inbox_collisions (ADR-022 and the ADR-062 §A attempt machine), request_claims (ADR-062 §B), and schema_compat_floor (ADR-063).

Tables

Table Purpose

rule_sets

JDM rule set definitions — content stored as JSONB, soft-deleted via active flag

rule_evaluations

Audit trail — every evaluation recorded with input, output, context, and evaluator (the #1130 SINGLE copy; past the archive hot window rows move COLD via #1129/ADR-058 — resolvable forever through archive_ledger + cargo xtask archive-fetch)

archive_ledger

#1129 (ADR-058 D8): rules' OWN durable archive ledger — one row per archived batch (object keys, sha256, D9 store identity, the [min, max] id range per D17), written inside the prune transaction; the authority orphan GC consults (the event to security is secondary bookkeeping)

rule_set_snapshots

#1556 (D2): insert-only content history — one row per API-path mutation, same-tx, keyed UNIQUE(rule_set_id, revision) (the cache CAS token), opened by a migration-time baseline row per pre-existing set. Records operation (baseline|create|update|import|promote|rollback|delete), mandatory reason for the consequential three (CHECK), the zen compile vintage, the canonical content sha256, and (promote) the persisted canary report. Audit-class, keep-forever-hot.

rule_set_promotion_previews

#1556 (D2): the promote two-step’s DB-backed evidence — candidate hash + from_revision binding, corpus fingerprint, thin-corpus flag, the categorical diff report. Never burned (a successful execute bumps the live revision, so replays 409 on the CAS). Audit-class, keep-forever-hot.

ER Diagram

rule_setsuuididPKtextnameUKunique rule set nametextversionbigintrevisiontrigger-bumped per-row counter — the (id, revision) cache token (#1188)textdescriptionjsonbcontentJDM decision modelbooleanactivesoft-delete flagtimestamptzcreated_attextcreated_bytimestamptzupdated_attextupdated_byrule_evaluationsuuididPKuuidrule_set_idFKtextrule_set_nametextrule_set_versionbigintrule_set_revisionnullable — the revision that ran (ؔ NULL = pre-D2)booleanpinnedsnapshot replay (#1556) — non-operative, no rules.evaluated stagedjsonbinputjsonboutputtimestamptzevaluated_attextevaluated_bytextcontext_typenullableuuidcontext_idnullablerule_set_snapshotsuuididPKuuidrule_set_idFKbigintrevisionUNIQUE with rule_set_id — the CAS tokenbigintfrom_revisionnullable — promote/rollback provenancetextnametextversionjsonbcontenttextengine_versionnullable — zen compile vintage (NULL = baseline)textoperationbaseline|create|update|import|promote|rollback|deletetextreasonmandatory for promote/rollback/delete (CHECK)textcontent_sha256nullable — canonical hash (NULL = baseline)jsonbcanary_reportnullable — the promote evidencetextactor_subtimestamptzrecorded_atrule_set_promotion_previewsuuididPKuuidrule_set_idFKbigintfrom_revisiontextcandidate_versiontextcandidate_sha256textcorpus_fingerprintbooleanthin_corpusjsonbreporttextreasontextactor_subtimestamptzcreated_atevaluated ashistory ofpreviewed against

Key Indexes

  • idx_rule_evaluations_rule_set_id — FK lookup

  • idx_rule_evaluations_context — composite on (context_type, context_id) for audit queries

  • idx_rule_evaluations_evaluated_at — time-range queries

Edit this page · latest