diff --git a/alembic/versions/0129_rule_deliveries.py b/alembic/versions/0129_rule_deliveries.py new file mode 100644 index 00000000..1261c430 --- /dev/null +++ b/alembic/versions/0129_rule_deliveries.py @@ -0,0 +1,42 @@ +"""rule deliveries — each rule line a session was shown, and whether it was opened after + +Revision ID: 0129 +Revises: 0128 +Create Date: 2026-11-22 + +One row per rule line delivered to a session, with the open stamped on the +delivery it followed. The open rate per rule and moment is read from it, both +for the ordering of what reaches a moment and for the adherence readout. +""" +import sqlalchemy as sa +from alembic import op + +revision = "0129" +down_revision = "0128" +branch_labels = None +depends_on = None + + +def upgrade() -> None: + op.create_table( + "rule_deliveries", + sa.Column("id", sa.BigInteger(), primary_key=True), + sa.Column("user_id", sa.BigInteger(), nullable=False), + sa.Column("session_id", sa.Text(), nullable=False), + sa.Column("rule_id", sa.BigInteger(), nullable=False), + sa.Column("source", sa.Text(), nullable=False), + sa.Column("at", sa.Text(), nullable=False), + sa.Column("form", sa.Text(), nullable=False), + sa.Column("delivered_at", sa.DateTime(timezone=True), nullable=False, + server_default=sa.func.now()), + sa.Column("opened_at", sa.DateTime(timezone=True), nullable=True), + sa.CheckConstraint("form IN ('full', 'repeat')", name="ck_rule_deliveries_form"), + ) + op.create_index("ix_rule_deliveries_session_rule", "rule_deliveries", + ["user_id", "session_id", "rule_id", "delivered_at"]) + op.create_index("ix_rule_deliveries_rule_at", "rule_deliveries", ["rule_id", "at"]) + op.create_index("ix_rule_deliveries_delivered_at", "rule_deliveries", ["delivered_at"]) + + +def downgrade() -> None: + op.drop_table("rule_deliveries") diff --git a/frontend/src/stores/rulebooks.ts b/frontend/src/stores/rulebooks.ts index 1eac4b60..fbb31d73 100644 --- a/frontend/src/stores/rulebooks.ts +++ b/frontend/src/stores/rulebooks.ts @@ -111,6 +111,9 @@ export const useRulebooksStore = defineStore("rulebooks", () => { // force as the same row re-fetched, or a preference the operator just // created would sit in the list looking like a rule until a reload. kind: rule.kind, + enforcement: rule.enforcement ?? "inform", + // Mirrors rule_brief: present only when raised or lowered. + salience: rule.salience && rule.salience !== "normal" ? rule.salience : undefined, updated_at: rule.updated_at, when_to_apply: rule.when_to_apply || undefined, arose_from_id: rule.arose_from_id ?? undefined, diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index ae191fa1..fd964e8f 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "grimoire", "description": "Grimoire for Claude Code: connects the grimoire MCP server, adds the hooks that deliver live project state and relevant records at the right moment, ships the shared client-neutral Grimoire skills (using-grimoire, writing-plans, reporting-back, systematic-debugging, verification, brainstorming, reusing-code, shape-accounting, family-canon), and syncs your saved Grimoire Processes as skills (/grimoire:sync).", - "version": "2026.11.05.0301", + "version": "2026.11.22.2312", "author": { "name": "Bryan Van Deusen" }, diff --git a/plugin/hooks/grimoire_autoinject.sh b/plugin/hooks/grimoire_autoinject.sh index c3da7c75..474d0334 100755 --- a/plugin/hooks/grimoire_autoinject.sh +++ b/plugin/hooks/grimoire_autoinject.sh @@ -125,6 +125,8 @@ if [ -n "$session_id" ]; then [ -n "$rule_seen" ] && exclude_q="${exclude_q}&exclude_rule_ids=${rule_seen}" # What the session actually OPENED, as against what it was shown. exclude_q="${exclude_q}$(grimoire_held_query "$rule_state_dir/${safe_sid}.opened.ids")" + # Which session the rule lines go to, so each is recorded as a delivery. + exclude_q="${exclude_q}&session_id=${safe_sid}" # Which reply shapes it already holds in full: the core is # sent whole once, and as its one-line reminder on every later turn. shapefile=$(grimoire_shapes_file "$safe_sid") diff --git a/plugin/hooks/grimoire_prior_art.sh b/plugin/hooks/grimoire_prior_art.sh index da8c9f79..5cf88fd1 100755 --- a/plugin/hooks/grimoire_prior_art.sh +++ b/plugin/hooks/grimoire_prior_art.sh @@ -240,6 +240,8 @@ if [ -n "$session_id" ]; then [ -n "$rule_seen" ] && rule_exclude_q="&exclude_rule_ids=${rule_seen}" # What the session actually OPENED, as against what it was shown. rule_exclude_q="${rule_exclude_q}$(grimoire_held_query "$state_dir/${safe_sid}.opened.ids")" + # Which session the rule lines go to, so each is recorded as a delivery. + rule_exclude_q="${rule_exclude_q}&session_id=${safe_sid}" fi # Not `|| exit 0`: an unreachable instance must not discard a local finding diff --git a/plugin/hooks/grimoire_record_opened.sh b/plugin/hooks/grimoire_record_opened.sh index a33b116a..6c338ee9 100644 --- a/plugin/hooks/grimoire_record_opened.sh +++ b/plugin/hooks/grimoire_record_opened.sh @@ -79,23 +79,30 @@ printf '%s\n' "$rule_id" | grimoire_rules_append "$state_dir/${safe_sid}.opened. # answers with one line putting the question to the reader. Nothing is # mounted by this. # -# An open of a rule a hook has just NAMED is not reported. A ranked arm or a -# moment line put it in front of the reader, and that explains the open; the -# moment beside it did not, so counting it would propose mounts on whatever -# moment happened to fire while search was surfacing the rule. The window is -# short for the same reason: a few minutes of agent work reaches many moments. +# EVERY OPEN IS REPORTED: the server stamps it on this session's latest +# delivery of the rule, which is how an open rate per delivery is measured. +# +# The acts go with it only when the rule was NOT just named by a hook. A +# ranked arm or a moment line put a named rule in front of the reader, and +# that explains the open; the moment beside it did not, so counting it would +# propose mounts on whatever moment happened to fire while search was +# surfacing the rule. The window is short for the same reason: a few minutes +# of agent work reaches many moments. command -v curl >/dev/null 2>&1 || exit 0 grimoire_config || exit 0 +acts="" case ",$(grimoire_rules_live "$state_dir/${safe_sid}.rules.ids")," in - *",${rule_id},"*) exit 0 ;; + *",${rule_id},"*) ;; + *) + acts_file="${TMPDIR:-/tmp}/grimoire-moment/${safe_sid}.acts" + now=$(date +%s 2>/dev/null) || now=0 + if [ -f "$acts_file" ] && [ "$now" -gt 0 ]; then + acts=$(awk -F '\t' -v since=$((now - 90)) \ + '$1 + 0 >= since { sub(/^[^\t]*\t/, ""); print }' "$acts_file" 2>/dev/null \ + | tail -n 3 | paste -sd ',' - 2>/dev/null) + fi + ;; esac -acts_file="${TMPDIR:-/tmp}/grimoire-moment/${safe_sid}.acts" -[ -f "$acts_file" ] || exit 0 -now=$(date +%s 2>/dev/null) || exit 0 -acts=$(awk -F '\t' -v since=$((now - 90)) \ - '$1 + 0 >= since { sub(/^[^\t]*\t/, ""); print }' "$acts_file" 2>/dev/null \ - | tail -n 3 | paste -sd ',' - 2>/dev/null) -[ -n "$acts" ] || exit 0 sid_esc=$(printf '%s' "$session_id" | grimoire_json_escape) || exit 0 event_cwd=$(grimoire_json_pick "$event_flat" '.cwd') diff --git a/plugin/hooks/grimoire_tool_rules.sh b/plugin/hooks/grimoire_tool_rules.sh index d53feb61..d12d2f2b 100644 --- a/plugin/hooks/grimoire_tool_rules.sh +++ b/plugin/hooks/grimoire_tool_rules.sh @@ -101,6 +101,8 @@ if [ -n "$session_id" ]; then [ -n "$rule_seen" ] && rule_exclude_q="&exclude_rule_ids=${rule_seen}" # What the session actually OPENED, as against what it was shown. rule_exclude_q="${rule_exclude_q}$(grimoire_held_query "$state_dir/${safe_sid}.opened.ids")" + # Which session the rule lines go to, so each is recorded as a delivery. + rule_exclude_q="${rule_exclude_q}&session_id=${safe_sid}" # The Systems whose rulings were shown in full — shared with the write-path # hook, for the reason the rule file is. rulingsfile="$state_dir/${safe_sid}.rulings.ids" diff --git a/src/grimoire/app.py b/src/grimoire/app.py index 51c54798..0835df91 100644 --- a/src/grimoire/app.py +++ b/src/grimoire/app.py @@ -198,9 +198,12 @@ def create_app() -> Quart: from grimoire.services.logging import start_log_retention_loop from grimoire.services.notifications import start_notification_loop + from grimoire.services.rule_deliveries import start_prune_loop as start_rule_delivery_prune + start_log_retention_loop() start_notification_loop() start_auth_token_retention_loop() + start_rule_delivery_prune() # The proxy hop count saved in Settings decides every request's client # address, so it is loaded before serving, under a deadline (a failed diff --git a/src/grimoire/models/__init__.py b/src/grimoire/models/__init__.py index bfe87230..71ae222c 100644 --- a/src/grimoire/models/__init__.py +++ b/src/grimoire/models/__init__.py @@ -60,6 +60,7 @@ from grimoire.models.retrieval_log import RetrievalLog # noqa: E402, F401 from grimoire.models.retrieval_tuning import RetrievalTuningEvent # noqa: E402, F401 from grimoire.models.note_usage import NoteUsageEvent # noqa: E402, F401 from grimoire.models.rule_usage import RuleUsageEvent # noqa: E402, F401 +from grimoire.models.rule_delivery import RuleDelivery # noqa: E402, F401 from grimoire.models.system_usage import SystemUsageEvent # noqa: E402, F401 from grimoire.models.retrieval_judgment import RetrievalJudgment # noqa: E402, F401 from grimoire.models.moment_mapping import MomentMapping # noqa: E402, F401 diff --git a/src/grimoire/models/rule_delivery.py b/src/grimoire/models/rule_delivery.py new file mode 100644 index 00000000..54144a67 --- /dev/null +++ b/src/grimoire/models/rule_delivery.py @@ -0,0 +1,69 @@ +from datetime import datetime + +from sqlalchemy import BigInteger, DateTime, Index, Text, func +from sqlalchemy.orm import Mapped, mapped_column + +from grimoire.models import Base +from grimoire.models.base import iso + +FULL = "full" +REPEAT = "repeat" +FORMS = (FULL, REPEAT) + + +class RuleDelivery(Base): + """One rule line put in front of one session, and whether it was opened after. + + WHAT IT ANSWERS that `rule_usage_events` cannot. A surfaced event and a + pulled event are counted separately, so "was THIS delivery opened" has no + answer there: a rule opened once in a session reads as pulled whether it + was delivered once or twenty times. Here each delivery is a row, and the + open is stamped on the delivery it followed — so the open rate per rule, + per moment and per arm is a count of rows, and the ordering function reads + it as the rule's history at that moment. + + `at` is where the rule was delivered: the moment it was mounted on + (`work.finish`) or the arm that found it (`pre_tool_rule`). `form` is + whether the line carried the rule's trigger (`full`) or only cited it + (`repeat`). Repeats are recorded too: they are deliveries a session can + open, and the case for retiring a rule rests on how rarely they are. + + FK-free on `rule_id` and `user_id`, like the other telemetry tables: the + evidence that a rule was delivered forty times and opened never outlives + the rule, because it is the case for having deleted it. + """ + + __tablename__ = "rule_deliveries" + + id: Mapped[int] = mapped_column(BigInteger, primary_key=True) + user_id: Mapped[int] = mapped_column(BigInteger, nullable=False) + session_id: Mapped[str] = mapped_column(Text, nullable=False) + rule_id: Mapped[int] = mapped_column(BigInteger, nullable=False) + source: Mapped[str] = mapped_column(Text, nullable=False) + at: Mapped[str] = mapped_column(Text, nullable=False) + form: Mapped[str] = mapped_column(Text, nullable=False) + delivered_at: Mapped[datetime] = mapped_column( + DateTime(timezone=True), nullable=False, server_default=func.now(), + ) + opened_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True) + + __table_args__ = ( + # Stamping an open: this session's latest delivery of this rule. + Index("ix_rule_deliveries_session_rule", "user_id", "session_id", "rule_id", "delivered_at"), + # History: a batch of rules at one moment. + Index("ix_rule_deliveries_rule_at", "rule_id", "at"), + Index("ix_rule_deliveries_delivered_at", "delivered_at"), + ) + + def to_dict(self) -> dict: + return { + "id": self.id, + "user_id": self.user_id, + "session_id": self.session_id, + "rule_id": self.rule_id, + "source": self.source, + "at": self.at, + "form": self.form, + "delivered_at": iso(self.delivered_at), + "opened_at": iso(self.opened_at), + } diff --git a/src/grimoire/routes/plugin.py b/src/grimoire/routes/plugin.py index 553b931e..4424c4b5 100644 --- a/src/grimoire/routes/plugin.py +++ b/src/grimoire/routes/plugin.py @@ -20,6 +20,7 @@ from grimoire.services import plugin_context as plugin_ctx_svc from grimoire.services import reply_shapes as reply_shapes_svc from grimoire.services import repo_bindings as repo_bindings_svc from grimoire.services import report_check as report_check_svc +from grimoire.services import rule_deliveries as rule_deliveries_svc from grimoire.services import rule_moment_judgments as judgments_svc from grimoire.services import shape_check as shape_check_svc from grimoire.services import task_claims as task_claims_svc @@ -36,6 +37,22 @@ plugin_bp = Blueprint("plugin", __name__, url_prefix="/api/plugin") _MARKETPLACE_KEY = "plugin_marketplace_url" +@plugin_bp.before_request +async def _bind_delivery_session() -> None: + """Bind the session this request delivers to, for the delivery record. + + A hook names it as `session_id` in the query, or carries it in the event + it posts (`/moment` sends the PreToolUse event whole). A request that + names none records no deliveries and reads no delivery history. + """ + sid = request.args.get("session_id") or "" + if not sid and request.method == "POST": + body = await request.get_json(silent=True) + if isinstance(body, dict): + sid = str(body.get("session_id") or "") + rule_deliveries_svc.bind_session(sid) + + def _int_list(raw: str | None) -> list[int]: """A comma-separated id list from the query string; non-ints dropped.""" return [int(p) for p in (raw or "").split(",") if p.strip().isdigit()] @@ -336,7 +353,10 @@ async def rule_opened(): """A session opened a rule shortly after these acts. Body: `{"rule_id", "session_id", "acts": [, ...]}` — - the calls the plugin saw in the window before the `get_rule`. Each is + the calls the plugin saw in the window before the `get_rule`. Every open + is first stamped on this session's latest delivery of the rule, which is + how the open rate per delivery is measured; `acts` is empty when the + rule was one a hook had just named, which explains the open by itself. Each is resolved to its moments, and the open is counted as evidence that the rule belongs on them; once a pair has repeated across enough distinct sessions, `context` carries the line asking the reader to offer the @@ -349,8 +369,13 @@ async def rule_opened(): rule_id = int(data.get("rule_id") or 0) except (TypeError, ValueError): rule_id = 0 + if rule_id > 0: + # The open, against the delivery it followed — whatever the acts say. + await rule_deliveries_svc.mark_opened( + g.user.id, str(data.get("session_id") or ""), rule_id, + ) acts = data.get("acts") - if rule_id <= 0 or not isinstance(acts, list): + if rule_id <= 0 or not isinstance(acts, list) or not acts: return jsonify({"moments": [], "context": ""}) project_id, _repo, _unbound = await _project_scope() return jsonify(await judgments_svc.opened_after( diff --git a/src/grimoire/services/backup.py b/src/grimoire/services/backup.py index e27bcc79..452065fc 100644 --- a/src/grimoire/services/backup.py +++ b/src/grimoire/services/backup.py @@ -183,6 +183,10 @@ _NOT_INCLUDED = [ "app_logs", "notifications", "invitation_tokens", "password_reset_tokens", "retrieval_logs", + # Per-session delivery rows, keyed by session ids that mean nothing on + # another instance and pruned after months anyway. The ordering reads + # them as history; a restored instance rebuilds it within weeks. + "rule_deliveries", # Verdicts on retrieval_logs rows, so they go where their subject # goes: a restore that carried a judgment of a call it did not carry would # leave a verdict on nothing. A sample, re-takeable by the review pass. diff --git a/src/grimoire/services/moment_delivery.py b/src/grimoire/services/moment_delivery.py index 29c480ef..047f1ec2 100644 --- a/src/grimoire/services/moment_delivery.py +++ b/src/grimoire/services/moment_delivery.py @@ -24,11 +24,14 @@ logger = logging.getLogger(__name__) def _io() -> rp.MomentIO: """Resolved at CALL time, so a test patching either module's name is seen.""" - from grimoire.services import rule_usage, rulebooks + from grimoire.services import rule_deliveries, rule_usage, rulebooks + bound = rule_deliveries.bound() return rp.MomentIO( lookup=rulebooks.rules_on_moments, record_rule_surfaced=rule_usage.record_rule_surfaced, + history=rule_deliveries.history if bound else None, + record_delivery=rule_deliveries.record if bound else None, ) diff --git a/src/grimoire/services/plugin_context.py b/src/grimoire/services/plugin_context.py index cd153ebf..6b7a17dd 100644 --- a/src/grimoire/services/plugin_context.py +++ b/src/grimoire/services/plugin_context.py @@ -974,10 +974,15 @@ def _rule_io() -> rp.RuleIO: the pipeline reports to whatever this module's `semantic_search_rules`, `record_retrieval` and `record_rule_surfaced` are at the moment it runs. """ + from grimoire.services import rule_deliveries + + bound = rule_deliveries.bound() return rp.RuleIO( search=semantic_search_rules, record_retrieval=record_retrieval, record_rule_surfaced=record_rule_surfaced, + history=rule_deliveries.history if bound else None, + record_delivery=rule_deliveries.record if bound else None, ) diff --git a/src/grimoire/services/retrieval_pipeline.py b/src/grimoire/services/retrieval_pipeline.py index 0b056805..559dc5bf 100644 --- a/src/grimoire/services/retrieval_pipeline.py +++ b/src/grimoire/services/retrieval_pipeline.py @@ -35,6 +35,7 @@ import time from dataclasses import dataclass, field from typing import Any, Callable +from grimoire.services import rule_order from grimoire.services.lessons import LESSON_NOTE_TYPE, claim_line logger = logging.getLogger(__name__) @@ -576,6 +577,12 @@ class RuleIO: record_retrieval: Callable[..., Any] record_rule_surfaced: Callable[..., Any] + history: Callable[..., Any] | None = None + """`rule_deliveries.history`: `{rule_id: open rate}` for (rule, at) pairs. + None leaves every rule's history unknown.""" + record_delivery: Callable[..., Any] | None = None + """`rule_deliveries.record`: each line shown, against the session the + door bound. None records nothing.""" @dataclass(frozen=True) @@ -773,6 +780,30 @@ async def _reserve_slot_for_preference( # ── The pipeline ───────────────────────────────────────────────────────── +def _record_delivery(io, moment: RuleMoment, source: str, shown: list[tuple[int, str, bool]]) -> None: + """Record each line shown — `(rule_id, at, was_a_repeat)` — as a delivery.""" + if io.record_delivery is None or not shown: + return + try: + io.record_delivery(moment.user_id, None, source, [ + (rid, at, "repeat" if repeat else "full") for rid, at, repeat in shown + ]) + except Exception: # noqa: BLE001 - observation never breaks the observed + _telemetry_failed(source) + + +async def _history(io, moment: RuleMoment, pairs: list[tuple[int, str]]) -> dict[int, float]: + """Each rule's open rate where it is about to be delivered; {} when the + door has no history to read or the read fails — unknown, never an error.""" + if io.history is None or not pairs: + return {} + try: + return await io.history(moment.user_id, pairs) or {} + except Exception: # noqa: BLE001 - history orders lines, it never withholds them + logger.debug("rule delivery history unreadable", exc_info=True) + return {} + + async def run_rule_arm( arm: RuleArm, moment: RuleMoment, *, floor: float, budget: int, io: RuleIO, checkpoint_floor: float = 0.0, @@ -801,6 +832,19 @@ async def run_rule_arm( # still has something to say, it just says it differently. if not shown: return RuleResult() + # Into the one delivery order: a rule that holds outranks one that + # informs whatever their scores, and score breaks the last tie. + history = await _history(io, moment, [(rule.id, arm.source) for _s, rule in shown]) + shown = [ + c.extra for c in rule_order.ordered( + rule_order.Candidate( + rule=rule, specificity=rule_order.BY_RESEMBLANCE, + opened_rate=history.get(rule.id), similarity=score, + seen=rule.id in moment.exclude, extra=(score, rule), + ) + for score, rule in shown + ) + ] lines = [ _rule_hint_line( @@ -836,6 +880,11 @@ async def run_rule_arm( ) except Exception: # noqa: BLE001 - observation never breaks the observed _telemetry_failed(source) + # A stop-only arm shows its lines to nobody: only a hold speaks. + if not arm.stop_only: + _record_delivery(io, moment, source, [ + (rule.id, source, rule.id in moment.exclude) for _s, rule in shown + ]) return RuleResult( lines=lines, rule_ids=rule_ids, shown_rule_ids=[rule.id for _score, rule in shown], @@ -1597,6 +1646,10 @@ class MomentIO: """`rulebooks.rules_on_moments`, or a stand-in with its signature.""" record_rule_surfaced: Callable[..., Any] + history: Callable[..., Any] | None = None + """As on `RuleIO`.""" + record_delivery: Callable[..., Any] | None = None + """As on `RuleIO`.""" def _reached_by(hit: dict) -> str: @@ -1626,8 +1679,20 @@ async def run_moment_arm( if not pairs: return RuleResult() by_moment = {hit["moment"]: hit for hit in reached} - # Stable: catalog order within each half, fresh half first. - shown = sorted(pairs, key=lambda pair: pair[0].id in moment.exclude)[:limit] + # The one delivery order (services/rule_order.py), then the cap — so + # what a crowded moment drops is the lowest-ranked, not the last + # mounted. Ties keep catalog order. + history = await _history(io, moment, [(rule.id, at) for rule, at in pairs]) + shown = [ + c.extra for c in rule_order.ordered( + rule_order.Candidate( + rule=rule, specificity=rule_order.BY_MOUNT, + opened_rate=history.get(rule.id), + seen=rule.id in moment.exclude, extra=(rule, at), + ) + for rule, at in pairs + ) + ][:limit] lines = [] for rule, at in shown: @@ -1651,6 +1716,9 @@ async def run_moment_arm( ) except Exception: # noqa: BLE001 - observation never breaks the observed _telemetry_failed(MOMENT_RULE_SOURCE) + _record_delivery(io, moment, MOMENT_RULE_SOURCE, [ + (rule.id, at, rule.id in moment.exclude) for rule, at in shown + ]) return RuleResult( lines=lines, rule_ids=rule_ids, shown_rule_ids=[rule.id for rule, _at in shown], diff --git a/src/grimoire/services/rule_deliveries.py b/src/grimoire/services/rule_deliveries.py new file mode 100644 index 00000000..e98bb2ab --- /dev/null +++ b/src/grimoire/services/rule_deliveries.py @@ -0,0 +1,180 @@ +"""Each rule line a session is shown, whether it was opened after, and what +that history says about where a rule is worth delivering. + +Three calls, one table (`rule_deliveries`): + +- `record` — fire-and-forget, from the plugin doors that know the session: + every line an arm put in front of it, full or repeat. +- `mark_opened` — the session opened a rule: the latest unopened delivery of + it in that session gets the stamp. An open with no delivery behind it (the + agent looked a rule up unprompted) stamps nothing. +- `history` — for the ordering function: each rule's smoothed open rate at + the place it is about to be delivered, over the last `HISTORY_DAYS`. + +Deliveries are kept `RETAIN_DAYS` and pruned daily: enough history to rank on +and to read adherence from, without a row per tool call accumulating forever. +""" +from __future__ import annotations + +import logging +import re +from contextvars import ContextVar +from datetime import datetime, timedelta, timezone + +from sqlalchemy import and_, case, delete, func, select, tuple_, update + +from grimoire.models import async_session +from grimoire.models.rule_delivery import FORMS, FULL, RuleDelivery +from grimoire.services import rule_order +from grimoire.services.background import spawn + +logger = logging.getLogger(__name__) + +HISTORY_DAYS = 90 +RETAIN_DAYS = 180 +# An open counts against a delivery made within this window before it; an +# older one was read by a context that is long gone. +OPEN_WINDOW = timedelta(hours=6) +_SESSION_MAX = 200 +_UNSAFE = re.compile(r"[^A-Za-z0-9._-]") + +# The session a plugin request is delivering to, bound once per request by the +# plugin routes so the arms several calls deep record against it without every +# signature between carrying it. Unbound (the MCP door, a test) records nothing. +_session: ContextVar[str] = ContextVar("rule_delivery_session", default="") + + +def bind_session(session_id: str | None) -> None: + _session.set(_clean_session(session_id)) + + +def bound() -> bool: + """Whether this request delivers to a known session — the doors that + record deliveries are the ones that read their history back.""" + return bool(_session.get()) + + +def _clean_session(session_id: str | None) -> str: + # The plugin's own filename-safe form of the id, so a hook that sends the + # raw id and one that sends the safe one name the same session. + return _UNSAFE.sub("_", (session_id or "").strip())[:_SESSION_MAX] + + +def record( + user_id: int, session_id: str | None, source: str, + lines: list[tuple[int, str, str]], +) -> None: + """Record delivered lines: `(rule_id, at, form)` each. Fire-and-forget, + and a no-op without a session, since an open could never be tied back. + `session_id` None means the one bound for this request.""" + sid = _clean_session(_session.get() if session_id is None else session_id) + if not sid or not lines: + return + try: + rows = [ + {"user_id": int(user_id), "session_id": sid, "rule_id": int(rid), + "source": source, "at": str(at or source), "form": form if form in FORMS else FULL} + for rid, at, form in lines + ] + except Exception: # noqa: BLE001 - observation never breaks the observed + logger.debug("rule delivery payload build failed", exc_info=True) + return + spawn(_insert(rows), site="rule_delivery_write") + + +async def _insert(rows: list[dict]) -> None: + async with async_session() as session: + session.add_all(RuleDelivery(**row) for row in rows) + await session.commit() + + +async def mark_opened(user_id: int, session_id: str | None, rule_id: int) -> bool: + """Stamp the latest unopened delivery of this rule in this session. + + Returns whether a delivery was stamped. Only that one: a rule delivered + five times and opened once was opened after the fifth line, and the four + before it were passed over. + """ + sid = _clean_session(session_id) + if not sid or not rule_id: + return False + now = datetime.now(timezone.utc) + async with async_session() as session: + latest = (await session.execute( + select(RuleDelivery.id) + .where( + RuleDelivery.user_id == user_id, + RuleDelivery.session_id == sid, + RuleDelivery.rule_id == rule_id, + RuleDelivery.opened_at.is_(None), + RuleDelivery.delivered_at >= now - OPEN_WINDOW, + ) + .order_by(RuleDelivery.delivered_at.desc(), RuleDelivery.id.desc()) + .limit(1) + )).scalar_one_or_none() + if latest is None: + return False + await session.execute( + update(RuleDelivery).where(RuleDelivery.id == latest).values(opened_at=now) + ) + await session.commit() + return True + + +async def history(user_id: int, pairs: list[tuple[int, str]]) -> dict[int, float]: + """`{rule_id: smoothed open rate}` at each pair's place, for this user. + + A rule with no delivery there is left out, which the ordering reads as + unknown rather than as never opened. + """ + wanted = list(dict.fromkeys((int(rid), str(at)) for rid, at in pairs)) + if not wanted: + return {} + since = datetime.now(timezone.utc) - timedelta(days=HISTORY_DAYS) + async with async_session() as session: + rows = (await session.execute( + select( + RuleDelivery.rule_id, RuleDelivery.at, + func.count(RuleDelivery.id), + func.sum(case((RuleDelivery.opened_at.is_not(None), 1), else_=0)), + ) + .where( + RuleDelivery.user_id == user_id, + RuleDelivery.delivered_at >= since, + tuple_(RuleDelivery.rule_id, RuleDelivery.at).in_(wanted), + ) + .group_by(RuleDelivery.rule_id, RuleDelivery.at) + )).all() + return { + int(rid): rule_order.opened_rate(int(delivered), int(opened or 0)) + for rid, _at, delivered, opened in rows + } + + +async def prune(retain_days: int = RETAIN_DAYS) -> int: + cutoff = datetime.now(timezone.utc) - timedelta(days=retain_days) + async with async_session() as session: + result = await session.execute( + delete(RuleDelivery).where(and_(RuleDelivery.delivered_at < cutoff)) + ) + await session.commit() + return int(result.rowcount or 0) + + +_prune_task = None + + +async def _prune_tick() -> None: + try: + removed = await prune() + if removed: + logger.info("Rule delivery retention: deleted %d row(s)", removed) + except Exception: + logger.exception("Rule delivery retention failed") + + +def start_prune_loop() -> None: + global _prune_task + if _prune_task is None or _prune_task.done(): + from grimoire.services.background import start_periodic + _prune_task = start_periodic(86400, _prune_tick, label="rule_delivery_retention") # daily diff --git a/src/grimoire/services/rule_order.py b/src/grimoire/services/rule_order.py new file mode 100644 index 00000000..2f99f672 --- /dev/null +++ b/src/grimoire/services/rule_order.py @@ -0,0 +1,80 @@ +"""The one order in which rules reach a moment. + +Every arm that puts rules in front of a session — the rules mounted on a +moment, the rules a typed trigger matched, the rules a semantic search found — +ranks what it has the same way, so a crowded moment drops the same rules +whichever arm brought them: + +1. **enforcement** — `enforce`, then `hold`, then `inform`. A rule that stops + the work is never the one cut to make room for a line beside it. +2. **salience** — `high`, `normal`, `low`, as the rule's author declared it. +3. **specificity** — how narrowly the rule was reached. A trigger that named + this command or this path says more than a mount on the whole moment, and a + mount says more than a resemblance. +4. **news** — at the same rank, a rule this session has not been shown yet + comes before one it has, so a cap cuts a reminder rather than a first + mention. +5. **history** — how often this rule was opened when delivered at this + moment before. A rule sessions keep opening here outranks one they keep + passing over. +6. **similarity** — the search score, when there is one. Last, because it is + the one signal that says what the work resembles rather than what it is. + +Each key is a declared or recorded fact, read in that order, so the outcome +can be explained line by line: "it outranked that one because it holds". +""" +from __future__ import annotations + +from collections.abc import Iterable +from dataclasses import dataclass +from typing import Any + +ENFORCEMENT_RANK = {"enforce": 0, "hold": 1, "inform": 2} +SALIENCE_RANK = {"high": 0, "normal": 1, "low": 2} + +# How narrowly a rule was reached, larger is narrower. +BY_RESEMBLANCE = 0 +BY_MOUNT = 1 +BY_TRIGGER = 2 + +# A rule with no delivery history at a moment ranks as if half its deliveries +# there were opened: unknown is neither proof of use nor of neglect. +UNKNOWN_HISTORY = 0.5 + + +@dataclass(frozen=True) +class Candidate: + """One rule an arm could deliver, with what it knows about how it got here.""" + + rule: Any + specificity: int = BY_RESEMBLANCE + opened_rate: float | None = None + """Share of this rule's earlier deliveries at this moment that were opened.""" + similarity: float | None = None + seen: bool = False + """Already shown to this session.""" + extra: Any = None + """Whatever the arm needs back with the rule — the moment it was mounted + on, its score pair — carried through the sort untouched.""" + + +def order_key(c: Candidate) -> tuple: + rule = c.rule + return ( + ENFORCEMENT_RANK.get(getattr(rule, "enforcement", None) or "inform", 2), + SALIENCE_RANK.get(getattr(rule, "salience", None) or "normal", 1), + -c.specificity, + c.seen, + -(UNKNOWN_HISTORY if c.opened_rate is None else c.opened_rate), + -(c.similarity or 0.0), + ) + + +def ordered(candidates: Iterable[Candidate]) -> list[Candidate]: + """The candidates in delivery order. Stable: ties keep the arm's own order.""" + return sorted(candidates, key=order_key) + + +def opened_rate(delivered: int, opened: int) -> float: + """A smoothed open rate, so one delivery opened once does not read as certainty.""" + return (opened + 1) / (delivered + 2) diff --git a/tests/test_integration_rule_deliveries.py b/tests/test_integration_rule_deliveries.py new file mode 100644 index 00000000..8d471147 --- /dev/null +++ b/tests/test_integration_rule_deliveries.py @@ -0,0 +1,107 @@ +"""Real-Postgres tests for `rule_deliveries`: a delivery recorded against a +session, the open stamped on the one it followed, and the history read back.""" +import asyncio +from datetime import datetime, timedelta, timezone + +import pytest +from sqlalchemy import delete, select, update + +from grimoire.models import async_session +from grimoire.models.rule_delivery import RuleDelivery +from grimoire.services import background, rule_deliveries +from tests.helpers import ensure_user + +pytestmark = [pytest.mark.integration, pytest.mark.usefixtures("_dispose_engine")] + +RULE = 9_100_001 +OTHER = 9_100_002 + + +async def _user() -> int: + async with async_session() as s: + user = await ensure_user(s, "rule_delivery_owner") + uid = user.id + await s.commit() + await s.execute(delete(RuleDelivery).where(RuleDelivery.user_id == uid)) + await s.commit() + return uid + + +async def _rows(uid: int) -> list[RuleDelivery]: + async with async_session() as s: + return list((await s.execute( + select(RuleDelivery).where(RuleDelivery.user_id == uid).order_by(RuleDelivery.id) + )).scalars().all()) + + +async def _record(uid, sid, source, lines): + rule_deliveries.record(uid, sid, source, lines) + await background.drain() + + +async def test_an_open_is_stamped_on_the_sessions_latest_delivery_only(): + uid = await _user() + await _record(uid, "s-1", "moment_rule", [(RULE, "work.finish", "full")]) + await asyncio.sleep(0.01) + await _record(uid, "s-1", "moment_rule", [(RULE, "work.finish", "repeat")]) + await _record(uid, "s-2", "moment_rule", [(RULE, "work.finish", "full")]) + + assert await rule_deliveries.mark_opened(uid, "s-1", RULE) is True + rows = await _rows(uid) + opened = [(r.session_id, r.form) for r in rows if r.opened_at is not None] + assert opened == [("s-1", "repeat")] + # A second open with nothing left unopened in the session stamps the earlier one. + assert await rule_deliveries.mark_opened(uid, "s-1", RULE) is True + assert await rule_deliveries.mark_opened(uid, "s-1", RULE) is False + + +async def test_an_open_with_no_delivery_behind_it_stamps_nothing(): + uid = await _user() + assert await rule_deliveries.mark_opened(uid, "s-1", OTHER) is False + assert await rule_deliveries.mark_opened(uid, "", RULE) is False + + +async def test_without_a_session_nothing_is_recorded(): + uid = await _user() + rule_deliveries.bind_session("") + await _record(uid, None, "prompt_rule", [(RULE, "prompt_rule", "full")]) + assert await _rows(uid) == [] + + +async def test_a_bound_session_is_the_one_recorded(): + uid = await _user() + rule_deliveries.bind_session("bound s/3") + await _record(uid, None, "prompt_rule", [(RULE, "prompt_rule", "full")]) + # The plugin's filename-safe form, so the raw and safe ids agree. + assert [r.session_id for r in await _rows(uid)] == ["bound_s_3"] + rule_deliveries.bind_session("") + + +async def test_history_is_the_smoothed_open_rate_at_each_place(): + uid = await _user() + await _record(uid, "s-1", "moment_rule", [(RULE, "work.finish", "full")] * 3 + + [(RULE, "work.deliver", "full"), (OTHER, "work.finish", "full")]) + await rule_deliveries.mark_opened(uid, "s-1", RULE) # one of the five RULE rows + + history = await rule_deliveries.history(uid, [(RULE, "work.finish"), (OTHER, "work.finish")]) + rows = await _rows(uid) + stamped_at = next(r.at for r in rows if r.opened_at is not None) + finish_opened = 1 if stamped_at == "work.finish" else 0 + assert history[RULE] == pytest.approx((finish_opened + 1) / (3 + 2)) + assert history[OTHER] == pytest.approx(1 / 3) + # A place with no delivery is unknown, not zero. + assert await rule_deliveries.history(uid, [(RULE, "reply.report")]) == {} + + +async def test_old_deliveries_are_pruned(): + uid = await _user() + await _record(uid, "s-1", "moment_rule", [(RULE, "work.finish", "full"), (OTHER, "work.finish", "full")]) + async with async_session() as s: + await s.execute( + update(RuleDelivery) + .where(RuleDelivery.user_id == uid, RuleDelivery.rule_id == RULE) + .values(delivered_at=datetime.now(timezone.utc) - timedelta(days=rule_deliveries.RETAIN_DAYS + 1)) + ) + await s.commit() + assert await rule_deliveries.prune() >= 1 + assert [r.rule_id for r in await _rows(uid)] == [OTHER] diff --git a/tests/test_rule_moment_signal_hooks.py b/tests/test_rule_moment_signal_hooks.py index c0371a4b..01994f02 100644 --- a/tests/test_rule_moment_signal_hooks.py +++ b/tests/test_rule_moment_signal_hooks.py @@ -166,7 +166,9 @@ def test_an_open_of_a_rule_a_hook_just_named_is_not_reported(sandbox): {"session_id": "s1", "tool_name": "mcp__grimoire__get_rule", "tool_input": {"rule_id": 11}}, env) assert out.stdout == "" - assert not (tmp / "curl.log").exists() + # The open is reported for the delivery record, with no acts to count. + assert json.loads((tmp / "curl.body").read_text()) == { + "rule_id": 11, "session_id": "s1", "acts": []} # The open itself is still recorded. assert (named / "s1.opened.ids").read_text().startswith("11\t") # A rule no hook named is still reported. @@ -176,7 +178,7 @@ def test_an_open_of_a_rule_a_hook_just_named_is_not_reported(sandbox): assert json.loads((tmp / "curl.body").read_text())["rule_id"] == 1 -def test_an_open_with_nothing_in_the_window_sends_nothing(sandbox): +def test_an_open_with_nothing_in_the_window_sends_only_the_open(sandbox): tmp, env = sandbox ledger = tmp / "grimoire-moment" ledger.mkdir() @@ -185,9 +187,9 @@ def test_an_open_with_nothing_in_the_window_sends_nothing(sandbox): ) out = _run("grimoire_record_opened.sh", {"session_id": "s1", "tool_name": "mcp__grimoire__get_rule", - "tool_input": {"rule_id": 11}}, env) + "tool_input": {"rule_id": 11}}, env, FAKE_CURL_REPLY='{"moments":[],"context":""}') assert out.stdout == "" - assert not (tmp / "curl.log").exists() + assert json.loads((tmp / "curl.body").read_text())["acts"] == [] def test_session_end_removes_the_sessions_moment_files_and_no_others(sandbox): diff --git a/tests/test_rule_order.py b/tests/test_rule_order.py new file mode 100644 index 00000000..773bf628 --- /dev/null +++ b/tests/test_rule_order.py @@ -0,0 +1,131 @@ +"""The one delivery order, key by key, and both rule arms reading it.""" +from types import SimpleNamespace +from unittest.mock import AsyncMock, MagicMock + +import pytest + +from grimoire.services import retrieval_pipeline as rp +from grimoire.services import rule_order as ro + + +def _r(rid, enforcement="inform", salience="normal"): + return SimpleNamespace(id=rid, title=f"rule {rid}", kind="rule", when_to_apply="when", + enforcement=enforcement, salience=salience) + + +def _ids(cands): + return [c.rule.id for c in ro.ordered(cands)] + + +def test_a_rule_that_stops_the_work_outranks_any_line_beside_it(): + cands = [ro.Candidate(_r(1), similarity=0.95), + ro.Candidate(_r(2, "hold"), similarity=0.71), + ro.Candidate(_r(3, "enforce"), similarity=0.70)] + assert _ids(cands) == [3, 2, 1] + + +def test_salience_decides_between_rules_of_the_same_enforcement(): + cands = [ro.Candidate(_r(1, salience="low")), ro.Candidate(_r(2)), + ro.Candidate(_r(3, salience="high"))] + assert _ids(cands) == [3, 2, 1] + + +def test_a_trigger_outranks_a_mount_and_a_mount_outranks_a_resemblance(): + cands = [ro.Candidate(_r(1), specificity=ro.BY_RESEMBLANCE, similarity=0.9), + ro.Candidate(_r(2), specificity=ro.BY_MOUNT), + ro.Candidate(_r(3), specificity=ro.BY_TRIGGER)] + assert _ids(cands) == [3, 2, 1] + + +def test_a_first_mention_outranks_a_reminder_at_the_same_rank(): + cands = [ro.Candidate(_r(1), seen=True), ro.Candidate(_r(2))] + assert _ids(cands) == [2, 1] + + +def test_history_breaks_the_tie_before_similarity_does(): + cands = [ro.Candidate(_r(1), opened_rate=0.1, similarity=0.9), + ro.Candidate(_r(2), opened_rate=0.8, similarity=0.7), + ro.Candidate(_r(3), similarity=0.99)] + # Unknown history ranks between them, as an even chance. + assert _ids(cands) == [2, 3, 1] + + +def test_ties_keep_the_arms_own_order(): + cands = [ro.Candidate(_r(i)) for i in (4, 2, 9)] + assert _ids(cands) == [4, 2, 9] + + +def test_a_rule_with_no_declared_fields_reads_as_inform_normal(): + bare = SimpleNamespace(id=1) + assert ro.order_key(ro.Candidate(bare))[:2] == (2, 1) + + +@pytest.mark.parametrize(("delivered", "opened", "rate"), [(0, 0, 0.5), (1, 1, 2 / 3), (10, 0, 1 / 12)]) +def test_the_open_rate_is_smoothed(delivered, opened, rate): + assert ro.opened_rate(delivered, opened) == pytest.approx(rate) + + +PUSH = [{"moment": "work.deliver", "tool": "Bash", "match": "git push", "via": "default"}] + + +@pytest.mark.asyncio +async def test_the_moment_arm_delivers_in_that_order_before_its_cap(): + pairs = [(_r(i), "work.deliver") for i in range(1, 11)] + [(_r(99, "hold"), "work.deliver")] + result = await rp.run_moment_arm( + PUSH, rp.RuleMoment(user_id=1, query="", project_id=2), + io=rp.MomentIO(lookup=AsyncMock(return_value=pairs), record_rule_surfaced=MagicMock()), + ) + # The holding rule was mounted last and still leads; the cap cut ordinary ones. + assert result.shown_rule_ids[0] == 99 + assert len(result.shown_rule_ids) == rp.MOMENT_RULE_LIMIT + + +@pytest.mark.asyncio +async def test_the_semantic_arm_delivers_in_that_order(): + hits = [(0.91, _r(1)), (0.74, _r(2, "hold"))] + io = rp.RuleIO(search=AsyncMock(return_value=hits), record_retrieval=MagicMock(), + record_rule_surfaced=MagicMock()) + result = await rp.run_rule_arm( + rp.PROMPT_RULE, rp.RuleMoment(user_id=1, query="q", project_id=2, where="here"), + floor=0.5, budget=5, io=io, + ) + assert result.shown_rule_ids[:2] == [2, 1] + + +@pytest.mark.asyncio +async def test_each_line_shown_is_recorded_as_a_delivery_with_its_form(): + recorded = MagicMock() + pairs = [(_r(5), "work.finish"), (_r(6), "work.finish")] + await rp.run_moment_arm( + PUSH, rp.RuleMoment(user_id=1, query="", project_id=2, exclude=frozenset({6})), + io=rp.MomentIO(lookup=AsyncMock(return_value=pairs), record_rule_surfaced=MagicMock(), + record_delivery=recorded), + ) + _uid, _sid, source, lines = recorded.call_args.args + assert source == rp.MOMENT_RULE_SOURCE + assert lines == [(5, "work.finish", "full"), (6, "work.finish", "repeat")] + + +@pytest.mark.asyncio +async def test_history_reorders_rules_of_equal_rank_and_a_failed_read_is_unknown(): + pairs = [(_r(5), "work.finish"), (_r(6), "work.finish")] + + async def history(_uid, _pairs): + return {6: 0.9, 5: 0.1} + + result = await rp.run_moment_arm( + PUSH, rp.RuleMoment(user_id=1, query="", project_id=2), + io=rp.MomentIO(lookup=AsyncMock(return_value=pairs), record_rule_surfaced=MagicMock(), + history=history), + ) + assert result.shown_rule_ids == [6, 5] + + async def broken(_uid, _pairs): + raise RuntimeError("no database") + + result = await rp.run_moment_arm( + PUSH, rp.RuleMoment(user_id=1, query="", project_id=2), + io=rp.MomentIO(lookup=AsyncMock(return_value=pairs), record_rule_surfaced=MagicMock(), + history=broken), + ) + assert result.shown_rule_ids == [5, 6]