feat(7728): one delivery order for rules, and each delivery recorded with whether it was opened
CI & Build / TypeScript typecheck (push) Successful in 41s
CI & Build / Plugin hooks (push) Successful in 17s
CI & Build / Python lint (push) Successful in 3s
CI & Build / Python tests (push) Failing after 1m41s
CI & Build / integration (push) Successful in 1m59s
CI & Build / Build & push image (push) Skipped

Every rule arm now ranks what it delivers with one function
(services/rule_order.py): enforcement, then salience, then how narrowly
the rule was reached, then first mention before reminder, then the
rule's own open rate at that moment, then similarity. A crowded moment
drops the same rules whichever arm brought them, and a rule that holds
is never cut for a line beside it.

The open rate comes from a new table, rule_deliveries (migration 0129):
one row per rule line a plugin session is shown, full or repeat, with the
open stamped on the latest delivery it followed. The plugin routes bind
the session per request; the prompt, pre-tool and write-path hooks now
send it, and the opened hook reports every open, with its acts only when
no hook had just named the rule. Rows are pruned daily after 180 days.

Also fixes the TypeScript check: the store's list row now carries the
new enforcement field.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-22 18:13:16 -05:00
co-authored by Claude Opus 5.5
parent 61077752b9
commit 61873b184b
20 changed files with 759 additions and 23 deletions
+42
View File
@@ -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")
+3
View File
@@ -111,6 +111,9 @@ export const useRulebooksStore = defineStore("rulebooks", () => {
// force as the same row re-fetched, or a preference the operator just // 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. // created would sit in the list looking like a rule until a reload.
kind: rule.kind, 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, updated_at: rule.updated_at,
when_to_apply: rule.when_to_apply || undefined, when_to_apply: rule.when_to_apply || undefined,
arose_from_id: rule.arose_from_id ?? undefined, arose_from_id: rule.arose_from_id ?? undefined,
+1 -1
View File
@@ -1,7 +1,7 @@
{ {
"name": "grimoire", "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).", "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": { "author": {
"name": "Bryan Van Deusen" "name": "Bryan Van Deusen"
}, },
+2
View File
@@ -125,6 +125,8 @@ if [ -n "$session_id" ]; then
[ -n "$rule_seen" ] && exclude_q="${exclude_q}&exclude_rule_ids=${rule_seen}" [ -n "$rule_seen" ] && exclude_q="${exclude_q}&exclude_rule_ids=${rule_seen}"
# What the session actually OPENED, as against what it was shown. # 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")" 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 # Which reply shapes it already holds in full: the core is
# sent whole once, and as its one-line reminder on every later turn. # sent whole once, and as its one-line reminder on every later turn.
shapefile=$(grimoire_shapes_file "$safe_sid") shapefile=$(grimoire_shapes_file "$safe_sid")
+2
View File
@@ -240,6 +240,8 @@ if [ -n "$session_id" ]; then
[ -n "$rule_seen" ] && rule_exclude_q="&exclude_rule_ids=${rule_seen}" [ -n "$rule_seen" ] && rule_exclude_q="&exclude_rule_ids=${rule_seen}"
# What the session actually OPENED, as against what it was shown. # 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")" 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 fi
# Not `|| exit 0`: an unreachable instance must not discard a local finding # Not `|| exit 0`: an unreachable instance must not discard a local finding
+20 -13
View File
@@ -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 # answers with one line putting the question to the reader. Nothing is
# mounted by this. # mounted by this.
# #
# An open of a rule a hook has just NAMED is not reported. A ranked arm or a # EVERY OPEN IS REPORTED: the server stamps it on this session's latest
# moment line put it in front of the reader, and that explains the open; the # delivery of the rule, which is how an open rate per delivery is measured.
# 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 # The acts go with it only when the rule was NOT just named by a hook. A
# short for the same reason: a few minutes of agent work reaches many moments. # 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 command -v curl >/dev/null 2>&1 || exit 0
grimoire_config || exit 0 grimoire_config || exit 0
acts=""
case ",$(grimoire_rules_live "$state_dir/${safe_sid}.rules.ids")," in 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 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 sid_esc=$(printf '%s' "$session_id" | grimoire_json_escape) || exit 0
event_cwd=$(grimoire_json_pick "$event_flat" '.cwd') event_cwd=$(grimoire_json_pick "$event_flat" '.cwd')
+2
View File
@@ -101,6 +101,8 @@ if [ -n "$session_id" ]; then
[ -n "$rule_seen" ] && rule_exclude_q="&exclude_rule_ids=${rule_seen}" [ -n "$rule_seen" ] && rule_exclude_q="&exclude_rule_ids=${rule_seen}"
# What the session actually OPENED, as against what it was shown. # 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")" 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 # The Systems whose rulings were shown in full — shared with the write-path
# hook, for the reason the rule file is. # hook, for the reason the rule file is.
rulingsfile="$state_dir/${safe_sid}.rulings.ids" rulingsfile="$state_dir/${safe_sid}.rulings.ids"
+3
View File
@@ -198,9 +198,12 @@ def create_app() -> Quart:
from grimoire.services.logging import start_log_retention_loop from grimoire.services.logging import start_log_retention_loop
from grimoire.services.notifications import start_notification_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_log_retention_loop()
start_notification_loop() start_notification_loop()
start_auth_token_retention_loop() start_auth_token_retention_loop()
start_rule_delivery_prune()
# The proxy hop count saved in Settings decides every request's client # The proxy hop count saved in Settings decides every request's client
# address, so it is loaded before serving, under a deadline (a failed # address, so it is loaded before serving, under a deadline (a failed
+1
View File
@@ -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.retrieval_tuning import RetrievalTuningEvent # noqa: E402, F401
from grimoire.models.note_usage import NoteUsageEvent # 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_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.system_usage import SystemUsageEvent # noqa: E402, F401
from grimoire.models.retrieval_judgment import RetrievalJudgment # noqa: E402, F401 from grimoire.models.retrieval_judgment import RetrievalJudgment # noqa: E402, F401
from grimoire.models.moment_mapping import MomentMapping # noqa: E402, F401 from grimoire.models.moment_mapping import MomentMapping # noqa: E402, F401
+69
View File
@@ -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),
}
+27 -2
View File
@@ -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 reply_shapes as reply_shapes_svc
from grimoire.services import repo_bindings as repo_bindings_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 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 rule_moment_judgments as judgments_svc
from grimoire.services import shape_check as shape_check_svc from grimoire.services import shape_check as shape_check_svc
from grimoire.services import task_claims as task_claims_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" _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]: def _int_list(raw: str | None) -> list[int]:
"""A comma-separated id list from the query string; non-ints dropped.""" """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()] 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. """A session opened a rule shortly after these acts.
Body: `{"rule_id", "session_id", "acts": [<PreToolUse event>, ...]}` — Body: `{"rule_id", "session_id", "acts": [<PreToolUse event>, ...]}` —
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 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 rule belongs on them; once a pair has repeated across enough distinct
sessions, `context` carries the line asking the reader to offer the 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) rule_id = int(data.get("rule_id") or 0)
except (TypeError, ValueError): except (TypeError, ValueError):
rule_id = 0 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") 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": ""}) return jsonify({"moments": [], "context": ""})
project_id, _repo, _unbound = await _project_scope() project_id, _repo, _unbound = await _project_scope()
return jsonify(await judgments_svc.opened_after( return jsonify(await judgments_svc.opened_after(
+4
View File
@@ -183,6 +183,10 @@ _NOT_INCLUDED = [
"app_logs", "notifications", "app_logs", "notifications",
"invitation_tokens", "password_reset_tokens", "invitation_tokens", "password_reset_tokens",
"retrieval_logs", "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 # 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 # 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. # leave a verdict on nothing. A sample, re-takeable by the review pass.
+4 -1
View File
@@ -24,11 +24,14 @@ logger = logging.getLogger(__name__)
def _io() -> rp.MomentIO: def _io() -> rp.MomentIO:
"""Resolved at CALL time, so a test patching either module's name is seen.""" """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( return rp.MomentIO(
lookup=rulebooks.rules_on_moments, lookup=rulebooks.rules_on_moments,
record_rule_surfaced=rule_usage.record_rule_surfaced, 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,
) )
+5
View File
@@ -974,10 +974,15 @@ def _rule_io() -> rp.RuleIO:
the pipeline reports to whatever this module's `semantic_search_rules`, the pipeline reports to whatever this module's `semantic_search_rules`,
`record_retrieval` and `record_rule_surfaced` are at the moment it runs. `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( return rp.RuleIO(
search=semantic_search_rules, search=semantic_search_rules,
record_retrieval=record_retrieval, record_retrieval=record_retrieval,
record_rule_surfaced=record_rule_surfaced, record_rule_surfaced=record_rule_surfaced,
history=rule_deliveries.history if bound else None,
record_delivery=rule_deliveries.record if bound else None,
) )
+70 -2
View File
@@ -35,6 +35,7 @@ import time
from dataclasses import dataclass, field from dataclasses import dataclass, field
from typing import Any, Callable from typing import Any, Callable
from grimoire.services import rule_order
from grimoire.services.lessons import LESSON_NOTE_TYPE, claim_line from grimoire.services.lessons import LESSON_NOTE_TYPE, claim_line
logger = logging.getLogger(__name__) logger = logging.getLogger(__name__)
@@ -576,6 +577,12 @@ class RuleIO:
record_retrieval: Callable[..., Any] record_retrieval: Callable[..., Any]
record_rule_surfaced: 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) @dataclass(frozen=True)
@@ -773,6 +780,30 @@ async def _reserve_slot_for_preference(
# ── The pipeline ───────────────────────────────────────────────────────── # ── 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( async def run_rule_arm(
arm: RuleArm, moment: RuleMoment, *, floor: float, budget: int, io: RuleIO, arm: RuleArm, moment: RuleMoment, *, floor: float, budget: int, io: RuleIO,
checkpoint_floor: float = 0.0, checkpoint_floor: float = 0.0,
@@ -801,6 +832,19 @@ async def run_rule_arm(
# still has something to say, it just says it differently. # still has something to say, it just says it differently.
if not shown: if not shown:
return RuleResult() 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 = [ lines = [
_rule_hint_line( _rule_hint_line(
@@ -836,6 +880,11 @@ async def run_rule_arm(
) )
except Exception: # noqa: BLE001 - observation never breaks the observed except Exception: # noqa: BLE001 - observation never breaks the observed
_telemetry_failed(source) _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( return RuleResult(
lines=lines, rule_ids=rule_ids, lines=lines, rule_ids=rule_ids,
shown_rule_ids=[rule.id for _score, rule in shown], 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.""" """`rulebooks.rules_on_moments`, or a stand-in with its signature."""
record_rule_surfaced: Callable[..., Any] 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: def _reached_by(hit: dict) -> str:
@@ -1626,8 +1679,20 @@ async def run_moment_arm(
if not pairs: if not pairs:
return RuleResult() return RuleResult()
by_moment = {hit["moment"]: hit for hit in reached} by_moment = {hit["moment"]: hit for hit in reached}
# Stable: catalog order within each half, fresh half first. # The one delivery order (services/rule_order.py), then the cap — so
shown = sorted(pairs, key=lambda pair: pair[0].id in moment.exclude)[:limit] # 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 = [] lines = []
for rule, at in shown: for rule, at in shown:
@@ -1651,6 +1716,9 @@ async def run_moment_arm(
) )
except Exception: # noqa: BLE001 - observation never breaks the observed except Exception: # noqa: BLE001 - observation never breaks the observed
_telemetry_failed(MOMENT_RULE_SOURCE) _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( return RuleResult(
lines=lines, rule_ids=rule_ids, lines=lines, rule_ids=rule_ids,
shown_rule_ids=[rule.id for rule, _at in shown], shown_rule_ids=[rule.id for rule, _at in shown],
+180
View File
@@ -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
+80
View File
@@ -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)
+107
View File
@@ -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]
+6 -4
View File
@@ -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", {"session_id": "s1", "tool_name": "mcp__grimoire__get_rule",
"tool_input": {"rule_id": 11}}, env) "tool_input": {"rule_id": 11}}, env)
assert out.stdout == "" 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. # The open itself is still recorded.
assert (named / "s1.opened.ids").read_text().startswith("11\t") assert (named / "s1.opened.ids").read_text().startswith("11\t")
# A rule no hook named is still reported. # 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 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 tmp, env = sandbox
ledger = tmp / "grimoire-moment" ledger = tmp / "grimoire-moment"
ledger.mkdir() ledger.mkdir()
@@ -185,9 +187,9 @@ def test_an_open_with_nothing_in_the_window_sends_nothing(sandbox):
) )
out = _run("grimoire_record_opened.sh", out = _run("grimoire_record_opened.sh",
{"session_id": "s1", "tool_name": "mcp__grimoire__get_rule", {"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 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): def test_session_end_removes_the_sessions_moment_files_and_no_others(sandbox):
+131
View File
@@ -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]