Constructive Events

Constructive Events

Event tracking, gamification, progressive trust, and achievement-based rewards. Configured through blueprints (EventTracker nodes + achievements[]) and module options (trust_ladder), and managed via the ORM.

When to Apply

Use this skill when:

• Adding event tracking to tables (EventTracker node)
• Defining achievements with requirements and credit rewards
• Building invite virality chains (EventReferral with max_depth)
• Implementing period-aware recurring achievements
• Tracking analytics events on row changes
• Turning evidence into access — trust ladders, earned levels, capability rewards

Architecture

Table row change
  → EventTracker trigger (compound conditions evaluated)
    → record_event(event_name, actor_id)
      → app_events log (partitioned, time-based retention)
      → upsert_achievement() → event_aggregates updated
        → tg_check_achievements
          → level_achieved() → level_grants created
            → tg_achievement_reward → credits granted
            → tg_invitee_achievement → record_event for inviter

Features

Trust Ladders

A trust ladder is a set of rungs that turn recorded evidence into access — the same levels/requirements/rewards machinery as achievements[], with rungs that reward a capability rather than a credit. Request one by slug when the events module is provisioned:

["events_module", { "scope": "app", "trust_ladder": "humanity" }]

Humans, bots and agents climb identically — nothing in a ladder asserts humanity, it accumulates evidence that costs something to fake. No shipped module preset requests a ladder yet, so it must be named explicitly today. Full rung tables, rung fields, and the metered limit baseline: trust-ladders.md.

Levels and Capabilities

A level reached through events can project into the access-control system: the reward attached to a rung sets a capability with kind = 'level' on the member's row, so an RLS policy can require it exactly like a granted capability (levels: ["level.reachable"]). This is how earned trust becomes enforceable access rather than a display badge — a rung with no capability reward is a badge and grants nothing.

Two things to know before designing around it:

• Owners and admins hold every level automatically. Their membership is given the complete capability set, so a level requirement never constrains them inside their own entity. See constructive-access-control → admin-owner-member.md.
• Levels are earned, never granted. Do not expose kind = 'level' rows in a grant or profile picker; filter capability lists by kind.

See constructive-access-control → named-capabilities.md for the capability model itself.

EventTracker

{
  "tables": [{
    "table_name": "user_profiles",
    "nodes": [
      { "$type": "EventTracker", "data": {
        "event_name": "avatar_uploaded",
        "events": ["UPDATE"],
        "watch_fields": ["avatar_url"],
        "conditions": { "field": "avatar_url", "op": "IS NOT NULL" }
      }}
    ]
  }]
}

EventReferral (Multi-Level Referral)

{ "$type": "EventReferral", "data": {
  "event_name": "purchase_completed",
  "max_depth": 3
}}

max_depth (1–10) walks up the claimed_invites chain N levels, crediting each ancestor inviter.

References

Cross-References

• Limits and credits: constructive-billing
• Entity types and invites: constructive-entities
• Background jobs (shared conditions system): constructive-jobs
• Blueprint definitions: constructive-blueprints