Index
Zeus (Rule Engine RPC)
Zeus exposes RPC endpoints to evaluate row selections and apply deterministic updates over Athena/PostgREST. It is backed by Postgres functions that translate JSON payloads into SQL safely with auditing.
Endpoints
POST /rpc/evaluate: select rows using JSON conditionsPOST /rpc/apply: update matched rows using an actor
Backed by functions:
- zeus_evaluate_query(payload jsonb)
- zeus_apply_actor(payload jsonb)
```typescript
### Concepts
- **resource_table**: target table (guarded by per-company allowlist)
- **conditions**: JSON expression for the WHERE clause
- **actor**: update instruction that sets a target column from a value source
- **mutation history**: before/after values are logged for undo/audit
### Configuration
```markdown
- Athena_URL, Athena_SERVICE_KEY
- ZEUS_SCHEMA (default public)
- ZEUS_ALLOWED_TABLES_COLUMN (default company_settings.allowed_accounting_rule_resource_tables)
- ZEUS_MAX_LIMIT (default 1000)
```typescript
### Payload schema
Send a JSON body with company context, target table, conditions, and optional actor. When calling PostgREST directly, wrap as `{ "payload": <body> }` to match function signatures.
```json
{
"company_id": "uuid",
"environment": "optional-string",
"resource_table": "table-name",
"conditions": [
{
"left": { "type": "column", "resource": "table-name", "column": "col" },
"operator": "=|!=|>|>=|<|<=|like|ilike|in|is_null|is_not_null",
"right": {
"type": "literal|column",
"valueType": "text|number|boolean|timestamp|array_text|array_number",
"value": "...",
"column": "other_col"
}
}
],
"limit": 100,
"actor": {
"type": "update",
"target_column": "col-to-update",
"value_source": {
"type": "static|column|table_lookup",
"value": "when type=static",
"column": "when type=column",
"table": "when type=table_lookup",
"return_column": "id",
"conditions": [
{ "leftColumn": "...", "operator": "=", "rightValue": "..." }
]
}
},
"force": false
}
```typescript
Notes:
- Supports both new `{ left/right }` and legacy `{ leftColumn/rightValue }` formats.
- Literal right values require `valueType`.
### Supported operators
`=, !=, >, >=, <, <=, like, ilike, in, is_null, is_not_null`
### Evaluate examples
Exact id:
```bash
curl -sS -X POST "https://zeus.suitsbooks.com/rpc/evaluate" \
-H "Content-Type: application/json" \
-d '{
"company_id": "2adf652d-0ed1-49f0-99e4-337b61b564df",
"resource_table": "transactions",
"conditions": [
{
"left": { "type": "column", "resource": "transactions", "column": "id" },
"operator": "=",
"right": { "type": "literal", "valueType": "text", "value": "1883335434511123011" }
}
],
"limit": 10
}'
```typescript
Pattern match:
```bash
curl -sS -X POST "https://zeus.suitsbooks.com/rpc/evaluate" \
-H "Content-Type: application/json" \
-d '{
"company_id": "2adf652d-0ed1-49f0-99e4-337b61b564df",
"resource_table": "transactions",
"conditions": [
{ "left": {"type":"column","resource":"transactions","column":"description"}, "operator":"ilike", "right": {"type":"literal","valueType":"text","value":"%fuel%"} }
]
}'
```typescript
Response:
```json
{
"rows": [{ "id": "...", "product": "...", "...": "..." }],
"row_count": 1,
"expression": "id=eq.1883335434511123011",
"duration_ms": 12
}
```typescript
### Apply examples
Static value:
```bash
curl -sS -X POST "https://zeus.suitsbooks.com/rpc/apply" \
-H "Content-Type: application/json" \
-d '{
"company_id": "2adf652d-0ed1-49f0-99e4-337b61b564df",
"resource_table": "transactions",
"conditions": [
{ "left": {"type":"column","resource":"transactions","column":"id"}, "operator":"=", "right": {"type":"literal","valueType":"text","value":"1883335434511123011"} }
],
"actor": { "type":"update", "target_column":"product", "value_source": {"type":"static","value":"my-product"} }
}'
```typescript
Copy from column:
```bash
curl -sS -X POST "https://zeus.suitsbooks.com/rpc/apply" \
-H "Content-Type: application/json" \
-d '{
"company_id": "2adf652d-0ed1-49f0-99e4-337b61b564df",
"resource_table": "transactions",
"conditions": [ { "left": {"type":"column","resource":"transactions","column":"category"}, "operator":"is_null" } ],
"actor": { "type":"update", "target_column":"category", "value_source": {"type":"column","column":"sub_category"} }
}'
```typescript
Lookup from another table:
```bash
curl -sS -X POST "https://zeus.suitsbooks.com/rpc/apply" \
-H "Content-Type: application/json" \
-d '{
"company_id": "2adf652d-0ed1-49f0-99e4-337b61b564df",
"resource_table": "transactions",
"conditions": [
{ "left": {"type":"column","resource":"transactions","column":"bank_name"}, "operator":"=", "right": {"type":"literal","valueType":"text","value":"ING"} }
],
"actor": {
"type": "update",
"target_column": "gl_account_id",
"value_source": {
"type": "table_lookup",
"table": "gl_accounts",
"return_column": "id",
"conditions": [
{ "leftColumn": "company_id", "operator": "=", "rightValue": "2adf652d-0ed1-49f0-99e4-337b61b564df" },
{ "leftColumn": "name", "operator": "=", "rightValue": "Bank" }
]
}
}
}'
```typescript
Success response:
```json
{
"affected_rows": 1,
"target_column": "product",
"resolved_value": "my-product",
"duration_ms": 18
}
```typescript
### Safety controls
- Allowlist: only tables in `company_settings.allowed_accounting_rule_resource_tables` can be targeted
- Per-mutation cap: `company_settings.max_rows_simultaneously_affected_per_mutation_accounting_engine`
- If matched rows exceed the cap and `force` != true, only the first 50 are processed
- Include `"force": true` to override (use with care)
- Mutation history: old/new values logged per-row; non-UUID ids are stored as NULL in `resource_id` (values still fully logged)
### Calling PostgREST directly (advanced)
Wrap the inner body as `{ "payload": ... }` to call the SQL function:
```bash
curl -sS -X POST "$Athena_URL/rest/v1/rpc/zeus_apply_actor" \
-H "Content-Type: application/json" \
-H "apikey: $SERVICE_ROLE_KEY" \
-H "Authorization: Bearer $SERVICE_ROLE_KEY" \
-d '{
"payload": {
"company_id": "...",
"resource_table": "transactions",
"conditions": [ { "left": {"type":"column","resource":"transactions","column":"id"}, "operator":"=", "right": {"type":"literal","valueType":"text","value":"..."} } ],
"actor": { "type":"update", "target_column":"product", "value_source": {"type":"static","value":"my-product"} }
}
}'
```typescript
### Deployment (SQL order)
1. Schema & audit tables → `packages/zeus/sql/20_tables_audit.sql`
2. Logging function → `packages/zeus/sql/30_fn_zeus_log.sql`
3. Undo functions → `packages/zeus/sql/40_fn_zeus_undo.sql`
4. Evaluator → `packages/zeus/sql/zeus_eval.sql`
5. Apply actor → `packages/zeus/sql/zeus_apply_actor.sql`
Grants:
```sql
GRANT EXECUTE ON FUNCTION zeus_evaluate_query(jsonb) TO anon, authenticated, service_role;
GRANT EXECUTE ON FUNCTION zeus_apply_actor(jsonb) TO anon, authenticated, service_role;
```typescript
### Pipelines & flows
See the full sequence and graph diagrams in the package doc for evaluation, mutation, multi-tenancy, audit, and example workflows:
```markdown
Below is a sequence of how a request flows through Zeus.
## Evaluation pipeline
sequenceDiagram
...
```typescript