@onlooker-community/ecosystem 0.34.0 → 0.43.0

package/plugins/librarian/scripts/lib/librarian-lesson-review.sh

@@ -0,0 +1,312 @@
+#!/usr/bin/env bash
+# Lesson confirmation — the human intent filter.
+#
+# The human picks which candidates go to the jury and their visibility, before
+# any expensive tokens are spent. Intent is cheap and only a human can supply
+# it; quality is expensive and only the jury can judge it. Splitting them here
+# means cost scales with intent rather than artifact volume.
+#
+# NOTHING in this file may invoke a model. That is what makes "no tokens spent
+# on unselected candidates" a property of the code rather than a promise.
+#
+# Requires librarian-lesson-storage.sh and librarian-lesson-validate.sh.
+
+librarian_lesson_passed_path() {
+	local key="$1"
+	printf '%s/passed.jsonl' "$(librarian_lessons_dir "$key")"
+}
+
+# Print proposals in the given status as a JSON array, oldest first. Prints []
+# when none.
+#
+# A malformed or racing file must shrink the result, never erase it: a
+# truncated write, a bare-value file, or a confirm/pass rewriting the file
+# mid-read all read as "that entry is missing" here, not as an error that
+# discards every proposal already gathered. `select(type == "object" and
+# ...)` folds the parse guard and the status check into a single read of
+# each file, the same shape librarian_lesson_seen uses for the same reason.
+#
+# Usage: librarian_lesson_list_by_status <key> <status>
+librarian_lesson_list_by_status() {
+	local key="$1"
+	local status="$2"
+	[[ -z "$key" || -z "$status" ]] && { printf '[]'; return 0; }
+
+	local dir
+	dir="$(librarian_lessons_dir "$key")/proposals"
+	[[ -d "$dir" ]] || { printf '[]'; return 0; }
+
+	local f out entry merged
+	out='[]'
+	for f in "$dir"/*.json; do
+		[[ -f "$f" ]] || continue
+		entry=$(jq -c --arg s "$status" 'select(type == "object" and .status == $s)' "$f" 2>/dev/null)
+		[[ -z "$entry" ]] && continue
+		# Merge into a separate variable, not directly into $out: `out=$(cmd)
+		# || continue` still assigns $out to cmd's (possibly empty) stdout
+		# before the `||` is ever evaluated, so a failed merge would silently
+		# wipe everything already gathered even with `continue` guarding it.
+		merged=$(jq -c --argjson e "$entry" '. + [$e]' <<<"$out" 2>/dev/null) || continue
+		out="$merged"
+	done
+	printf '%s' "$(jq -c 'sort_by(.created_at)' <<<"$out")"
+}
+
+# Pending is the queue the review walk drives, so it keeps its own name.
+#
+# Usage: librarian_lesson_list_pending <key>
+librarian_lesson_list_pending() {
+	librarian_lesson_list_by_status "${1:-}" "pending"
+}
+
+_librarian_lesson_valid_visibility() {
+	case "${1:-}" in
+		private | org | public) return 0 ;;
+		*) return 1 ;;
+	esac
+}
+
+# Confirm a candidate for the jury.
+#
+# Usage: librarian_lesson_confirm <key> <lesson_id> <visibility> [justification]
+#
+# With a justification, the candidate's scope is rewritten to
+# version_independent. That branch is refused at private visibility: private
+# lessons run no jury, so the justification would reach the pool with nothing
+# checking it — the same hole the transform closes by refusing the branch
+# outright. Requiring org or public means scope_accuracy actually tests it.
+librarian_lesson_confirm() {
+	local key="$1"
+	local lesson_id="$2"
+	local visibility="${3:-}"
+	local justification="${4:-}"
+	[[ -z "$key" || -z "$lesson_id" ]] && return 1
+
+	_librarian_lesson_valid_visibility "$visibility" || {
+		printf 'visibility must be one of: private, org, public\n' >&2
+		return 1
+	}
+
+	if [[ -n "$justification" && "$visibility" == "private" ]]; then
+		printf 'version_independent requires org or public visibility: a private lesson runs no jury, so its justification would go unchecked and the lesson would never expire\n' >&2
+		return 1
+	fi
+
+	local path
+	path="$(librarian_lessons_dir "$key")/proposals/${lesson_id}.json"
+	[[ -f "$path" ]] || { printf 'Lesson %s not found.\n' "$lesson_id" >&2; return 1; }
+
+	local proposal candidate current_status
+	proposal=$(jq '.' "$path" 2>/dev/null) || return 1
+	candidate=$(printf '%s' "$proposal" | jq -c '.candidate' 2>/dev/null) || return 1
+	current_status=$(printf '%s' "$proposal" | jq -r '.status // ""' 2>/dev/null)
+
+	# Snapshot the candidate before the rewrite, so unconfirm can put it back.
+	# Only when we actually rewrite: a plain confirm never touches .candidate,
+	# so a snapshot there would be dead weight that unconfirm has to reason
+	# about. Absence of the field means "nothing was mutated".
+	local candidate_before=""
+	if [[ -n "$justification" ]]; then
+		candidate_before="$candidate"
+		candidate=$(printf '%s' "$candidate" | jq -c \
+			--arg j "$justification" \
+			'.applies_to.scope = {kind: "version_independent", justification: $j}' 2>/dev/null) || return 1
+	fi
+
+	# Authoritative guard: check the RESULTING state, not just this call's
+	# input. The check above only catches a justification supplied on THIS
+	# invocation; a candidate that already carries version_independent scope
+	# (proposed that way, or confirmed non-private earlier and now being
+	# reconfirmed at private) would sail past it and write with no jury ever
+	# validating the justification. This check is the one that actually holds
+	# the invariant — the input check above is only a fast path that avoids
+	# reading the file for the common case.
+	if [[ "$visibility" == "private" ]] && printf '%s' "$candidate" \
+		| jq -e '.applies_to.scope.kind == "version_independent"' >/dev/null 2>&1; then
+		printf 'version_independent requires org or public visibility: a private lesson runs no jury, so its justification would go unchecked and the lesson would never expire\n' >&2
+		return 1
+	fi
+
+	# Guard the transition, not just the write. Each write below is already
+	# atomic (one merged jq expression, one write), but an unguarded SEQUENCE
+	# is where a passed candidate could be flipped back to confirmed while
+	# passed.jsonl still asserts the human declined it — the durable record
+	# of intent disagreeing with the candidate it describes.
+	case "$current_status" in
+		pending) ;;
+		confirmed)
+			# Idempotent only when the repeat asks for exactly what is
+			# already recorded; anything else is a contradictory flip.
+			if printf '%s' "$proposal" | jq -e \
+				--arg v "$visibility" --argjson c "$candidate" \
+				'.visibility == $v and .candidate == $c' >/dev/null 2>&1; then
+				return 0
+			fi
+			printf 'Lesson %s is already confirmed; visibility or scope differs from the request.\n' \
+				"$lesson_id" >&2
+			return 1
+			;;
+		passed)
+			printf 'Lesson %s was passed on; it cannot be confirmed.\n' "$lesson_id" >&2
+			return 1
+			;;
+		*)
+			printf 'Lesson %s has an unrecognized status: %s\n' "$lesson_id" "$current_status" >&2
+			return 1
+			;;
+	esac
+
+	librarian_lesson_validate_confirmed "$candidate" 2>/dev/null || {
+		printf 'Candidate does not validate; not confirmed.\n' >&2
+		return 1
+	}
+
+	local now updated
+	now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+	# `.candidate` is assigned, not merged into with `*`: `*` is a recursive
+	# merge, and merging the fresh candidate over the stored one leaves stale
+	# keys behind — a version_independent rewrite would keep the old
+	# versioned scope's `versions` key alongside the new `justification`,
+	# producing a candidate that fails its own validator's
+	# additionalProperties check on the way out the door.
+	if [[ -n "$candidate_before" ]]; then
+		updated=$(printf '%s' "$proposal" | jq \
+			--arg v "$visibility" --arg t "$now" \
+			--argjson c "$candidate" --argjson cb "$candidate_before" \
+			'. * {status: "confirmed", visibility: $v, confirmed_at: $t}
+			 | .candidate = $c
+			 | .candidate_before_confirm = $cb' 2>/dev/null) || return 1
+	else
+		# No rewrite happened, so there is nothing to snapshot — and any field
+		# already on the proposal is stale by definition. Deleting it holds the
+		# invariant unconfirm relies on ("absence means the candidate was never
+		# mutated") from both ends: without this, a proposal that arrives
+		# carrying the field keeps it through a plain confirm, and the next
+		# unconfirm silently replaces .candidate with a snapshot describing a
+		# rewrite this confirm never performed.
+		updated=$(printf '%s' "$proposal" | jq \
+			--arg v "$visibility" --arg t "$now" --argjson c "$candidate" \
+			'. * {status: "confirmed", visibility: $v, confirmed_at: $t}
+			 | .candidate = $c
+			 | del(.candidate_before_confirm)' 2>/dev/null) || return 1
+	fi
+	[[ -z "$updated" || "$updated" == "null" ]] && return 1
+	librarian_lesson_write_atomic "$path" "$updated"
+}
+
+# Take back a confirmation, before the jury has seen the lesson.
+#
+# `confirmed` is otherwise terminal: confirm refuses a differing repeat and
+# pass refuses a confirmed lesson. Those guards are correct — they are what
+# keeps passed.jsonl from contradicting the proposal it describes — but they
+# left no way back from confirming at the wrong visibility, and `public` is
+# the tier that leaves this machine.
+#
+# Proceeds ONLY from `confirmed`. Every other status is refused, which is also
+# what makes this forward-safe: when the jury stage introduces a status of its
+# own, this verb refuses it through the catch-all with no change here.
+#
+# Usage: librarian_lesson_unconfirm <key> <lesson_id>
+librarian_lesson_unconfirm() {
+	local key="$1"
+	local lesson_id="$2"
+	[[ -z "$key" || -z "$lesson_id" ]] && return 1
+
+	local path
+	path="$(librarian_lessons_dir "$key")/proposals/${lesson_id}.json"
+	[[ -f "$path" ]] || { printf 'Lesson %s not found.\n' "$lesson_id" >&2; return 1; }
+
+	local current_status
+	current_status=$(jq -r '.status // ""' "$path" 2>/dev/null)
+
+	case "$current_status" in
+		confirmed) ;;
+		pending) return 0 ;;
+		passed)
+			# Passing is a different decision with its own durable record.
+			# Silently moving it back to pending would leave passed.jsonl
+			# asserting a decision the proposal contradicts.
+			printf 'Lesson %s was passed on, not confirmed; unconfirm does not undo that.\n' "$lesson_id" >&2
+			return 1
+			;;
+		*)
+			printf 'Lesson %s has an unrecognized status: %s\n' "$lesson_id" "$current_status" >&2
+			return 1
+			;;
+	esac
+
+	# Restore the pre-confirm candidate when one was snapshotted, and delete
+	# the snapshot either way. A stale snapshot left on a pending proposal is
+	# indistinguishable from a live one at the next confirm, and would
+	# silently revert a later legitimate rewrite.
+	local updated
+	updated=$(jq '
+		(if has("candidate_before_confirm") then .candidate = .candidate_before_confirm else . end)
+		| del(.candidate_before_confirm, .visibility, .confirmed_at)
+		| .status = "pending"
+	' "$path" 2>/dev/null) || return 1
+	[[ -z "$updated" || "$updated" == "null" ]] && return 1
+	librarian_lesson_write_atomic "$path" "$updated"
+}
+
+# Decline to share a candidate.
+#
+# The file is KEPT. librarian_lesson_seen scans proposals/ by artifact_id, so
+# leaving it in place is what stops the artifact being re-proposed on the next
+# scan and re-paying for a transform whose answer the human already gave.
+#
+# The ledger is separate from declined.jsonl on purpose: that file records
+# machine verdicts and feeds rubric tuning, and folding human intent into it
+# would corrupt the signal it exists to carry.
+#
+# Usage: librarian_lesson_pass <key> <lesson_id> [reason]
+librarian_lesson_pass() {
+	local key="$1"
+	local lesson_id="$2"
+	local reason="${3:-}"
+	[[ -z "$key" || -z "$lesson_id" ]] && return 1
+
+	local path
+	path="$(librarian_lessons_dir "$key")/proposals/${lesson_id}.json"
+	[[ -f "$path" ]] || { printf 'Lesson %s not found.\n' "$lesson_id" >&2; return 1; }
+
+	local current_status
+	current_status=$(jq -r '.status // ""' "$path" 2>/dev/null)
+
+	# Same reasoning as confirm: guard the transition. Passing twice must not
+	# append a second ledger line, and a confirmed candidate must not be
+	# silently un-confirmed — that would leave stale visibility/confirmed_at
+	# behind and send a contradictory signal to the stages that select on
+	# status downstream.
+	case "$current_status" in
+		pending) ;;
+		passed) return 0 ;;
+		confirmed)
+			printf 'Lesson %s is confirmed for the jury; it cannot be passed on now.\n' "$lesson_id" >&2
+			return 1
+			;;
+		*)
+			printf 'Lesson %s has an unrecognized status: %s\n' "$lesson_id" "$current_status" >&2
+			return 1
+			;;
+	esac
+
+	local artifact_id now updated
+	artifact_id=$(jq -r '.artifact_id // ""' "$path" 2>/dev/null)
+	now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+	updated=$(jq --arg t "$now" '. * {status: "passed", passed_at: $t}' "$path" 2>/dev/null) || return 1
+	[[ -z "$updated" || "$updated" == "null" ]] && return 1
+	librarian_lesson_write_atomic "$path" "$updated" || return 1
+
+	local line
+	line=$(jq -cn \
+		--arg lesson_id "$lesson_id" \
+		--arg artifact_id "$artifact_id" \
+		--arg reason "$reason" \
+		--arg at "$now" \
+		'{lesson_id: $lesson_id, artifact_id: $artifact_id,
+		  reason: (if $reason == "" then null else $reason end), passed_at: $at}') || return 1
+
+	printf '%s\n' "$line" >> "$(librarian_lesson_passed_path "$key")"
+}

package/plugins/librarian/scripts/lib/librarian-lesson-rubric.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Rubric selection for lesson judging.
+#
+# Two builtins live in config.json under librarian.lesson_judging.rubrics,
+# mirroring tribunal's rubric.builtins shape so they stay legible to anyone who
+# knows tribunal. Librarian loads them itself rather than sourcing tribunal's
+# lib — see docs/adr/002-agent-definitions-are-shared-assets.md.
+#
+# The per-criterion weights and min_pass floors are LIVE as of ecosystem-pht:
+# librarian_lesson_aggregate weights them and librarian_lesson_gate blocks on
+# any criterion below its floor.
+#
+# `disclosure` at min_pass 0.9 is what makes the public tier stricter than org.
+# It replaces gate_policy `unanimous`, which was intended as a stand-in for
+# exactly this and turned out to be a no-op: at the configured two-judge panel,
+# `unanimous` and `majority` agree on every possible pass count. See
+# ecosystem-j74. Changing judge_types without re-reading that bead is how the
+# hole reopens.
+#
+# Exposes:
+#   librarian_lesson_rubric_id_for_visibility <visibility>
+#   librarian_lesson_rubric_get <rubric_id>
+
+# Map a confirmed lesson's visibility to the rubric that judges it.
+#
+# `private` maps to the empty string on purpose: that tier runs no jury at all,
+# which is what makes cost scale with intent rather than artifact volume.
+#
+# Usage: librarian_lesson_rubric_id_for_visibility <visibility>
+librarian_lesson_rubric_id_for_visibility() {
+	case "${1:-}" in
+		private) printf '' ;;
+		org)     printf 'lesson-promotion' ;;
+		public)  printf 'lesson-promotion-public' ;;
+		*)       return 1 ;;
+	esac
+	return 0
+}
+
+# Echo one rubric as compact JSON. Returns 1 and echoes nothing if unknown.
+#
+# Usage: librarian_lesson_rubric_get <rubric_id>
+librarian_lesson_rubric_get() {
+	local rubric_id="${1:-}"
+	[[ -z "$rubric_id" ]] && return 1
+
+	local rubrics found
+	rubrics=$(librarian_config_get '.librarian.lesson_judging.rubrics')
+	[[ -z "$rubrics" || "$rubrics" == "null" ]] && return 1
+
+	found=$(printf '%s' "$rubrics" | jq -c --arg id "$rubric_id" \
+		'map(select(.id == $id)) | first // empty' 2>/dev/null) || return 1
+	[[ -z "$found" || "$found" == "null" ]] && return 1
+
+	printf '%s' "$found"
+}

package/plugins/librarian/scripts/lib/librarian-lesson-storage.sh

@@ -25,6 +25,23 @@ librarian_lesson_storage_init() {
 	mkdir -p "$dir/proposals" "$dir/approved" 2>/dev/null
 }
 
+# Write a file atomically: temp in the same directory, then mv.
+#
+# `printf > "$path"` truncates before writing, so an interrupted write leaves
+# a zero-byte file. For a proposal that is permanently stuck: every verb
+# refuses it with "unrecognized status: " and list_pending hides it, so even
+# unconfirm — the recovery verb — cannot bring it back.
+#
+# Usage: librarian_lesson_write_atomic <path> <content>
+librarian_lesson_write_atomic() {
+	local path="$1"
+	local content="$2"
+	local tmp
+	tmp=$(mktemp "${path}.XXXXXX" 2>/dev/null) || return 1
+	printf '%s\n' "$content" > "$tmp" 2>/dev/null || { rm -f "$tmp" 2>/dev/null; return 1; }
+	mv "$tmp" "$path" 2>/dev/null || { rm -f "$tmp" 2>/dev/null; return 1; }
+}
+
 # Write one candidate. Prints the ULID on success.
 # Usage: librarian_lesson_write_proposal <key> <candidate_json> <artifact_id>
 librarian_lesson_write_proposal() {
@@ -61,29 +78,51 @@ librarian_lesson_write_proposal() {
 # bury a good artifact permanently, because the watermark has already moved
 # past it and declined entries are never re-read.
 #
-# Usage: librarian_lesson_append_declined <key> <artifact_id> <reason> [detail]
+# `verdict` is emitted with --argjson so it lands as a nested object, not a
+# serialized string: consumers read .verdict.judges[].score directly. Rows
+# written by the transform have no verdict and simply lack the key — a format
+# failure has no jury.
+#
+# Usage: librarian_lesson_append_declined <key> <artifact_id> <reason> [detail] [verdict_json]
 librarian_lesson_append_declined() {
 	local key="$1"
 	local artifact_id="$2"
 	local reason="$3"
 	local detail="${4:-}"
+	local verdict="${5:-}"
 	[[ -z "$key" || -z "$artifact_id" || -z "$reason" ]] && return 1
 
 	librarian_lesson_storage_init "$key" || return 1
 
 	local now line
 	now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-	line=$(jq -cn \
-		--arg artifact_id "$artifact_id" \
-		--arg reason "$reason" \
-		--arg detail "$detail" \
-		--arg at "$now" \
-		'{
-			artifact_id: $artifact_id,
-			reason: $reason,
-			detail: (if $detail == "" then null else $detail end),
-			declined_at: $at
-		}') || return 1
+	if [[ -n "$verdict" ]]; then
+		line=$(jq -cn \
+			--arg artifact_id "$artifact_id" \
+			--arg reason "$reason" \
+			--arg detail "$detail" \
+			--arg at "$now" \
+			--argjson verdict "$verdict" \
+			'{
+				artifact_id: $artifact_id,
+				reason: $reason,
+				detail: (if $detail == "" then null else $detail end),
+				declined_at: $at,
+				verdict: $verdict
+			}') || return 1
+	else
+		line=$(jq -cn \
+			--arg artifact_id "$artifact_id" \
+			--arg reason "$reason" \
+			--arg detail "$detail" \
+			--arg at "$now" \
+			'{
+				artifact_id: $artifact_id,
+				reason: $reason,
+				detail: (if $detail == "" then null else $detail end),
+				declined_at: $at
+			}') || return 1
+	fi
 
 	printf '%s\n' "$line" >> "$(librarian_lessons_dir "$key")/declined.jsonl"
 }
@@ -123,8 +162,38 @@ librarian_lesson_seen() {
 		return 0
 	fi
 
+	# ===================================================================
+	# proposals/ IS THE SOLE DEDUP SOURCE FOR AN APPROVED LESSON.
+	# PRUNING proposals/ SILENTLY BREAKS DEDUP. See ecosystem-d0m.
+	# ===================================================================
+	#
+	# A declined artifact is covered by declined.jsonl above — a terminal
+	# record keyed by artifact_id that outlives its proposal. An APPROVED one
+	# has no equivalent: the pool entry is ZLesson, a strictObject whose key
+	# set has no artifact_id and cannot gain one (an extra key fails ingest —
+	# see librarian-lesson-promote.sh's key-set comment). So nothing promote
+	# writes can answer "was this artifact already handled?"
+	#
+	# This loop used to scan approved/*.json too. That branch could never
+	# match, and the test covering it fabricated an {artifact_id: ...} file
+	# promote cannot produce — dead code with a green test in front of it,
+	# which is why it survived. Dropped rather than left as a decorative
+	# safety net that reads like coverage.
+	#
+	# The consequence, accepted deliberately: prune a promoted lesson's
+	# proposal and its artifact reads as unseen, so it is re-transformed
+	# (Haiku), re-confirmed BY THE HUMAN AGAIN, and re-judged (Opus),
+	# producing a duplicate pool entry for a lesson already promoted.
+	#
+	# The alternative was an artifact_id -> lesson id index (or a per-entry
+	# sidecar) to make the pool self-identifying. Neither buys anything until
+	# someone actually wants to prune, and both add a surface that can drift
+	# from the directory — so the requirement is stated instead of engineered
+	# around. Build the index FIRST if you ever need to prune; the tripwire
+	# test is "an approved lesson is NOT seen once its proposal is gone" in
+	# test/bats/librarian-lesson-promote.bats.
 	local f
-	for f in "$dir"/proposals/*.json "$dir"/approved/*.json; do
+	for f in "$dir"/proposals/*.json; do
 		[[ -f "$f" ]] || continue
 		if jq -e --arg a "$artifact_id" '.artifact_id == $a' "$f" >/dev/null 2>&1; then
 			return 0

package/plugins/librarian/scripts/lib/librarian-lesson-transform.sh

@@ -12,7 +12,12 @@
 #
 # Config inputs (read via librarian_config_get from librarian_lesson_call):
 #   librarian.lesson_transform.model              Anthropic model id
-#   librarian.lesson_transform.timeout_seconds    Hard wall-clock ceiling
+#   librarian.lesson_transform.timeout_seconds    Per-call wall-clock ceiling
+#
+# timeout_seconds bounds one call, not a scan. The aggregate ceiling across a
+# whole SessionEnd is librarian.lesson_transform.total_budget_ms, enforced by
+# the caller in librarian-session-end.sh — a per-call timeout alone leaves
+# KEPT_COUNT of them unbounded end to end (ecosystem-qwi).
 
 # Fallback when config hasn't been loaded or leaves the key unset.
 _LIBRARIAN_LESSON_DEFAULT_TIMEOUT_SECONDS=20