@rulemetric/hooks 0.7.44 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulemetric/hooks",
-  "version": "0.7.44",
+  "version": "0.8.0",
   "publishConfig": {
     "access": "public"
   },

package/scripts/session-start.sh

@@ -136,49 +136,64 @@ _rulemetric_suggest_instructions() {
   # week of grooming would evict every adoption proposal and the additive feed
   # would silently go to zero. Over-fetch, then cap each direction separately
   # below so neither can starve the other.
+  # renderFor=session-start asks the API for the RENDER SET — already capped per
+  # direction, already ordered adopt-first, with counts that describe itself. The
+  # caps used to live in this script as jq slices, which meant the server could
+  # not tell a row it showed from a row it merely sent: `surfaced` events were
+  # logged for rows the caps never displayed, inflating the denominator of the
+  # acceptance rate this feed exists to measure.
+  #
+  # groupByKind is still sent so an API that predates renderFor degrades to the
+  # old mixed-pool response rather than to a score-ordered page that buries the
+  # subtractive directions.
+  #
+  # sessionId carries HOOK_SESSION_ID so the server can assign this session an
+  # ARM for any instruction under test — inject it, or deliberately withhold it —
+  # and record that decision BEFORE deciding what to return. The hook stays a
+  # dumb renderer: it never learns which arm it is in, and must not, or the
+  # decision would be re-derivable client-side and therefore forgeable.
+  #
+  # An API that predates arms ignores the parameter and returns the same render
+  # set as before, so an older server degrades to "always inject" rather than to
+  # a silently empty feed.
   response="$(curl -s --noproxy '*' --max-time 4 \
-    "${api_url}/api/instruction-suggestions?projectPath=${encoded_path}&limit=10&includeContent=true&groupByKind=true" \
+    "${api_url}/api/instruction-suggestions?projectPath=${encoded_path}&limit=10&includeContent=true&groupByKind=true&renderFor=session-start&sessionId=${HOOK_SESSION_ID}" \
     -H "Authorization: Bearer ${auth_token}" 2>/dev/null)" || return 0
 
   local count
   count="$(printf '%s' "$response" | jq -r '.suggestions | length' 2>/dev/null)" || return 0
   [ "$count" != "0" ] && [ "$count" != "null" ] && [ -n "$count" ] || return 0
 
-  # Per-direction index lists, capped independently. `kind` is absent on an older
-  # API, so an untagged row is an adoption proposal — the historical behaviour.
-  local add_idx rem_idx trim_idx render_idx
-  add_idx="$(printf '%s' "$response" | jq -r \
-    '[.suggestions | to_entries[] | select((.value.kind // "add") == "add") | .key][0:3] | .[]' 2>/dev/null)" || add_idx=""
-  rem_idx="$(printf '%s' "$response" | jq -r \
-    '[.suggestions | to_entries[] | select(.value.kind == "remove") | .key][0:2] | .[]' 2>/dev/null)" || rem_idx=""
-  trim_idx="$(printf '%s' "$response" | jq -r \
-    '[.suggestions | to_entries[] | select(.value.kind == "trim") | .key][0:1] | .[]' 2>/dev/null)" || trim_idx=""
-  render_idx="$(printf '%s\n%s\n%s\n' "$add_idx" "$rem_idx" "$trim_idx" | grep -v '^$' || true)"
+  local add_count cost_count high_count render_idx
+  add_count="$(printf '%s' "$response" | jq -r '.render.addCount // empty' 2>/dev/null)" || add_count=""
+
+  if [ -n "$add_count" ]; then
+    # Render-set response: print what we were given, in the order given.
+    cost_count="$(printf '%s' "$response" | jq -r '.render.costCount // 0' 2>/dev/null)" || cost_count=0
+    high_count="$(printf '%s' "$response" | jq -r '.render.highConfidenceCount // 0' 2>/dev/null)" || high_count=0
+    render_idx="$(seq 0 "$((count - 1))" 2>/dev/null)" || return 0
+  else
+    # COMPATIBILITY SHIM — an API older than renderFor returned a mixed pool, so
+    # the caps have to be applied here. This is a second copy of a policy that
+    # now lives on the server, and a forked policy is one that eventually drifts:
+    # delete this branch once the minimum supported API understands renderFor.
+    local add_idx rem_idx trim_idx rem_count trim_count
+    add_idx="$(printf '%s' "$response" | jq -r \
+      '[.suggestions | to_entries[] | select((.value.kind // "add") == "add") | .key][0:3] | .[]' 2>/dev/null)" || add_idx=""
+    rem_idx="$(printf '%s' "$response" | jq -r \
+      '[.suggestions | to_entries[] | select(.value.kind == "remove") | .key][0:2] | .[]' 2>/dev/null)" || rem_idx=""
+    trim_idx="$(printf '%s' "$response" | jq -r \
+      '[.suggestions | to_entries[] | select(.value.kind == "trim") | .key][0:1] | .[]' 2>/dev/null)" || trim_idx=""
+    render_idx="$(printf '%s\n%s\n%s\n' "$add_idx" "$rem_idx" "$trim_idx" | grep -v '^$' || true)"
+    high_count="$(printf '%s' "$response" | jq -r \
+      '[[.suggestions | to_entries[] | select((.value.kind // "add") == "add")][0:3][] | select(.value.content != null)] | length' 2>/dev/null)" || high_count="0"
+    rem_count="$(printf '%s\n' "$rem_idx" | grep -c '[0-9]' 2>/dev/null)" || rem_count=0
+    trim_count="$(printf '%s\n' "$trim_idx" | grep -c '[0-9]' 2>/dev/null)" || trim_count=0
+    cost_count=$((rem_count + trim_count))
+    add_count="$(printf '%s\n' "$add_idx" | grep -c '[0-9]' 2>/dev/null)" || add_count=0
+  fi
   [ -n "$render_idx" ] || return 0
 
-  # Count high-confidence rows among the ADDS WE WILL ACTUALLY RENDER. Counting
-  # the whole response over-counts now that the fetch pulls 6 to cap 3+2: the
-  # header announced "5 high-confidence instruction(s) included below" with 3
-  # below it. A header that miscounts what follows it is how a reader stops
-  # trusting the block.
-  local high_count
-  high_count="$(printf '%s' "$response" | jq -r \
-    '[[.suggestions | to_entries[] | select((.value.kind // "add") == "add")][0:3][] | select(.value.content != null)] | length' 2>/dev/null)" || high_count="0"
-  # ONE count for the shared "costing you" header. Counting only removals would
-  # under-report the moment a trim renders beneath the same heading — the same
-  # header-miscounts-its-own-list bug just fixed above, reintroduced by a third
-  # direction.
-  local rem_count trim_count cost_count
-  rem_count="$(printf '%s\n' "$rem_idx" | grep -c '[0-9]' 2>/dev/null)" || rem_count=0
-  trim_count="$(printf '%s\n' "$trim_idx" | grep -c '[0-9]' 2>/dev/null)" || trim_count=0
-  cost_count=$((rem_count + trim_count))
-
-  # The header describes the ADDITIVE rows only. `count` is now a mixed total, so
-  # using it here would announce "N instructions may help with this project" and
-  # then list retirements underneath it.
-  local add_count
-  add_count="$(printf '%s\n' "$add_idx" | grep -c '[0-9]' 2>/dev/null)" || add_count=0
-
   printf '\n---\n'
   if [ "$high_count" != "0" ] && [ -n "$high_count" ]; then
     printf '[rulemetric] %s high-confidence instruction(s) included below as session context.\n' "$high_count"
@@ -253,6 +268,11 @@ _rulemetric_suggest_instructions() {
     # reader (human or model) could act without going to look an id up. With
     # several suggestions on screen one shared CTA is ambiguous even once it
     # carries an id, so the command belongs to the row it accepts.
+    #
+    # A `graduated:`-prefixed id is a RULE, not a proposal (ticket 04): its
+    # question is settled by measurement, so there is nothing to accept and the
+    # CTA would be an instruction to act on a decision already made.
+    case "$sid" in graduated:*|experiment:*) continue ;; esac
     if [ -n "$sid" ] && [ "$sid" != "null" ]; then
       printf '    Accept: rulemetric suggestions accept %s\n' "$sid"
     fi
@@ -270,6 +290,11 @@ _rulemetric_suggest_instructions() {
   for i in $render_idx; do
     local sid has_content event_type
     sid="$(printf '%s' "$response" | jq -r ".suggestions[$i].id" 2>/dev/null)" || break
+    # A graduated rule (ticket 04) has no suggestion row — its id is synthetic
+    # — and its surfacing is not a funnel event: the budget and acceptance
+    # metrics both measure QUESTIONS, and a rule is an answer. Posting would
+    # 404 anyway; skipping keeps the log clean and the denominators honest.
+    case "$sid" in graduated:*|experiment:*) continue ;; esac
     has_content="$(printf '%s' "$response" | jq -r ".suggestions[$i].content // \"null\"" 2>/dev/null)" || has_content="null"
     if [ "$has_content" != "null" ] && [ -n "$has_content" ]; then
       event_type="surfaced_with_content"