Milestone 4.5.A.3 — Fingerprint Trigger & Scheduling

Status: Planned
Goal: Track A — Behavioral Fingerprinting
Phase: 4.5 — Intelligence Layer
Estimated effort: 2 days
Track: Track A — Behavioral Fingerprinting
ADR required: None

Why This Milestone Exists

The original design triggers fingerprint computation every 10 inference calls. This is a pure count-based trigger, which means a low-traffic agent that receives one call every 3 days might go weeks without a fingerprint — silently disabling drift detection for exactly the agents an operator is least likely to be actively watching. The fix is a time-boxed trigger with a count floor: compute whenever max(10 calls, 1 hour elapsed) is true, whichever comes first.

Non-Goals

• Feature extraction and statistical computation (4.5.A.1)
• Schema storage (4.5.A.2)
• Drift detection itself (Track B)

Orientation (indicative)

Named paths, package layouts, libraries, schemas, env vars, and commands anywhere on this page are rough sketches for orientation — inspiration and a baseline, not a required change list.

During implementation, expect to:

• open the live tree and follow existing patterns before inventing new ones
• research current constraints (latency, tenancy, deploy shape, libraries) more deeply than this page can
• advance the design beyond the sketch where measurement or code reality says so
• land work in different filenames, merged packages, deferred docs, or new surfaces when the situation calls for it

Prefer outcomes over matching any particular file tree or command sequence.

Areas that may be involved (situational — not a checklist):

• Fingerprinting / drift
• Workers / task runtime

Suggested naming (provisional)

Rename freely to match the change that actually lands.

• Branch: feature/m4-5-a3-fingerprint-trigger-scheduling
• PR title: feat(worker/fingerprint): time-boxed trigger scheduling with count floor (m4.5.A.3)

Deliverables

Target outcomes for the milestone; concrete artifacts may differ from any sketch above.

Trigger logic

Two complementary trigger paths:

1. Count-based trigger: After each inference trace write, check if the agent has accumulated ≥10 new traces since the last fingerprint computation. If yes, enqueue compute_fingerprint Celery task.

2. Time-based trigger (Celery beat): A periodic beat task runs every 30 minutes and finds all agents where last_fingerprint_computed_at < NOW() - INTERVAL '1 hour' AND at least 1 new trace exists since the last fingerprint. Enqueues compute_fingerprint for each.

Together these implement max(10 calls, 1 hour elapsed).

Celery beat schedule addition

# Illustrative — exact path may differ
CELERYBEAT_SCHEDULE = {
 # ... existing schedule entries ...
 "fingerprint-time-trigger": {
 "task": "fingerprint.tasks.trigger_time_based_fingerprints",
 "schedule": crontab(minute="*/30"),
 },
}

Deduplication guard

Celery task IDs are derived from agent_id + window_start to prevent double-enqueue if both triggers fire simultaneously for the same agent.

Opt-out support

agents table flag fingerprinting_enabled BOOLEAN NOT NULL DEFAULT TRUE. Count-based and time-based triggers both check this flag before enqueuing. Required for INT-4.5.7 (fingerprinting disabled for an org).

Success signals

Outcome-oriented signals that the milestone is in good shape. Exact filenames, package layouts, and commands may differ from any sketches above.

• Low-traffic agent (≥1 trace per hour, < 10 per hour) receives a fingerprint at least hourly
• High-traffic agent (≥10 traces since last fingerprint) triggers within one poll cycle
• Double-enqueue protection: two simultaneous triggers for the same agent produce exactly one task execution
• fingerprinting_enabled = FALSE on an org's agents suppresses all fingerprint task enqueues — verified by direct table scan (INT-4.5.7 requirement)
• Metrics: ibex_fingerprint_trigger_total{trigger_type: "count|time"} counter emitted

Prerequisites

• 4.5.A.1 and 4.5.A.2 merged
• Celery beat schedule infrastructure present (pre-existing)