@onlooker-community/ecosystem 0.33.0 → 0.34.0

package/plugins/librarian/schema/lesson-applies-to.subschema.json

@@ -0,0 +1,74 @@
+{
+  "type": "object",
+  "properties": {
+    "stack": {
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "scope": {
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string",
+              "const": "versioned"
+            },
+            "versions": {
+              "type": "object",
+              "propertyNames": {
+                "type": "string",
+                "minLength": 1
+              },
+              "additionalProperties": {
+                "type": "string",
+                "pattern": "^((<|<=|=)\\d+(\\.\\d+)?(\\.\\d+)?|(>|>=)(\\d*[1-9]\\d*(\\.\\d+)?(\\.\\d+)?|0+\\.\\d*[1-9]\\d*(\\.\\d+)?|0+\\.0+\\.\\d*[1-9]\\d*)|(>|>=)\\d+(\\.\\d+)?(\\.\\d+)? (<|<=)\\d+(\\.\\d+)?(\\.\\d+)?)$"
+              },
+              "description": "Comparator-prefixed version ranges keyed by stack entry, for example {\"vite\": \"<6\"}. A two-sided range reads lower bound then upper bound. Multiple entries combine with AND: every entry must match for the lesson to still apply.",
+              "minProperties": 1
+            }
+          },
+          "required": ["kind", "versions"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string",
+              "const": "version_independent"
+            },
+            "justification": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Why this lesson holds regardless of version. Judged, not assumed."
+            }
+          },
+          "required": ["kind", "justification"],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "file_patterns": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "task_kinds": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    }
+  },
+  "required": ["stack", "scope", "file_patterns", "task_kinds"],
+  "additionalProperties": false,
+  "description": "Every key of scope.versions must name an entry in stack. That rule is enforced at ingest, not by this schema, because JSON Schema cannot express a constraint spanning two fields."
+}

package/plugins/librarian/schema/lesson-evidence.subschema.json

@@ -0,0 +1,36 @@
+{
+  "type": "object",
+  "properties": {
+    "artifact_ids": {
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
+      }
+    },
+    "session_ids": {
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "project_key": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{12}$"
+    },
+    "observed_at": {
+      "type": "string",
+      "format": "date-time",
+      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
+    },
+    "resolution": {
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "required": ["artifact_ids", "session_ids", "project_key", "observed_at", "resolution"],
+  "additionalProperties": false
+}

package/plugins/librarian/scripts/hooks/librarian-session-end.sh

@@ -59,6 +59,12 @@ source "${PLUGIN_ROOT}/scripts/lib/librarian-durability.sh"
 source "${PLUGIN_ROOT}/scripts/lib/librarian-classifier.sh"
 # shellcheck source=../lib/librarian-conflict-detector.sh
 source "${PLUGIN_ROOT}/scripts/lib/librarian-conflict-detector.sh"
+# shellcheck source=../lib/librarian-lesson-validate.sh
+source "${PLUGIN_ROOT}/scripts/lib/librarian-lesson-validate.sh"
+# shellcheck source=../lib/librarian-lesson-storage.sh
+source "${PLUGIN_ROOT}/scripts/lib/librarian-lesson-storage.sh"
+# shellcheck source=../lib/librarian-lesson-transform.sh
+source "${PLUGIN_ROOT}/scripts/lib/librarian-lesson-transform.sh"
 
 librarian_now_ms() {
 	local now_ms
@@ -424,6 +430,26 @@ for ((i = 0; i < KEPT_COUNT; i++)); do
 		}')"
 done
 
+# ---------------------------------------------------------------------------
+# Stage 5 — lesson transform.
+#
+# Runs over the same durability survivors the classifier saw. Each artifact is
+# independent: a decline or an outage on one never stops the rest.
+# ---------------------------------------------------------------------------
+LESSON_PROPOSED=0
+LESSON_DECLINED=0
+
+for ((li = 0; li < KEPT_COUNT; li++)); do
+	LESSON_ARTIFACT=$(printf '%s' "$KEPT" | jq -c ".[$li]")
+	[[ -z "$LESSON_ARTIFACT" || "$LESSON_ARTIFACT" == "null" ]] && continue
+
+	LESSON_RESULT=$(librarian_lesson_transform_one "$PROJECT_KEY" "$LESSON_ARTIFACT")
+	case "$LESSON_RESULT" in
+		proposed:*) LESSON_PROPOSED=$((LESSON_PROPOSED + 1)) ;;
+		declined:*) LESSON_DECLINED=$((LESSON_DECLINED + 1)) ;;
+	esac
+done
+
 # ----------------------------------------------------------------------------
 # Watermark advance + scan.complete.
 # ----------------------------------------------------------------------------

package/plugins/librarian/scripts/lib/librarian-config.sh

@@ -1,10 +1,12 @@
 #!/usr/bin/env bash
 # Config resolution for Librarian.
 #
-# Reads three layers, latest wins:
+# Uses the shared config loader from ecosystem. Reads five layers, latest wins:
 #   1. plugins/librarian/config.json (defaults shipped with the plugin)
 #   2. ~/.claude/settings.json
-#   3. <repo>/.claude/settings.json
+#   3. ~/.claude/settings.local.json (local overrides user)
+#   4. <repo>/.claude/settings.json
+#   5. <repo>/.claude/settings.local.json (local overrides project)
 #
 # Exposes:
 #   librarian_config_load <repo_root>    # populates _LIBRARIAN_CONFIG (JSON)
@@ -14,48 +16,22 @@
 # Settings overlay only touches the `librarian.*` subtree of settings.json so
 # it coexists with other plugins' configuration.
 
+# shellcheck source=../../../scripts/lib/config-loader.sh
+source "${PLUGIN_ROOT}/../../scripts/lib/config-loader.sh"
+
 _LIBRARIAN_CONFIG="{}"
 
 librarian_config_load() {
 	local repo_root="${1:-}"
-	local plugin_root="${CLAUDE_PLUGIN_ROOT:-}"
-	local home_dir="${HOME:-}"
-
-	local merged="{}"
-	local file
-
-	file="${plugin_root}/config.json"
-	if [[ -f "$file" ]]; then
-		local defaults
-		defaults=$(jq '.' "$file" 2>/dev/null) || defaults="{}"
-		merged=$(jq -n --argjson a "$merged" --argjson b "$defaults" '$a * $b' 2>/dev/null) \
-			|| merged="$defaults"
-	fi
-
-	for file in "${home_dir}/.claude/settings.json" "${repo_root}/.claude/settings.json"; do
-		[[ -n "$file" && -f "$file" ]] || continue
-		local overlay
-		overlay=$(jq '{ librarian: (.librarian // {}) }' "$file" 2>/dev/null) || continue
-		[[ -z "$overlay" ]] && continue
-		merged=$(jq -n --argjson a "$merged" --argjson b "$overlay" '
-			def deepmerge($a; $b):
-				if ($a|type) == "object" and ($b|type) == "object" then
-					reduce (($a|keys) + ($b|keys) | unique)[] as $k
-						({}; .[$k] = deepmerge($a[$k]; $b[$k]))
-				elif $b == null then $a
-				else $b end;
-			deepmerge($a; $b)
-		' 2>/dev/null) || true
-	done
-
-	_LIBRARIAN_CONFIG="$merged"
+	config_load_plugin "librarian" "$repo_root" "_LIBRARIAN_CONFIG"
+	return 0
 }
 
 # Read a value from the loaded config. Usage:
 #   librarian_config_get '.librarian.surfacer.max_pending_for_inject'
 librarian_config_get() {
 	local path="$1"
-	printf '%s' "$_LIBRARIAN_CONFIG" | jq -r "${path} // empty" 2>/dev/null
+	config_get "_LIBRARIAN_CONFIG" "${path}"
 }
 
 # Returns 0 if librarian.auto_promote is true, 1 otherwise.

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

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+# Storage for the lesson subtree.
+#
+#   <project_dir>/lessons/proposals/<ulid>.json   awaiting human confirmation
+#   <project_dir>/lessons/approved/<ulid>.json    jury passed (written by 4z8.4)
+#   <project_dir>/lessons/declined.jsonl          append-only, never re-judged
+#
+# Lessons live apart from librarian's memory `proposals/` on purpose: a memory
+# promotion writes to this machine, a lesson proposal is a step toward
+# publishing beyond it. Separate trees keep a confirmation surface from
+# merging the two by accident.
+#
+# Requires librarian-storage.sh (librarian_project_dir) and librarian-ulid.sh.
+
+librarian_lessons_dir() {
+	local key="$1"
+	printf '%s/lessons' "$(librarian_project_dir "$key")"
+}
+
+librarian_lesson_storage_init() {
+	local key="$1"
+	[[ -z "$key" ]] && return 1
+	local dir
+	dir=$(librarian_lessons_dir "$key")
+	mkdir -p "$dir/proposals" "$dir/approved" 2>/dev/null
+}
+
+# Write one candidate. Prints the ULID on success.
+# Usage: librarian_lesson_write_proposal <key> <candidate_json> <artifact_id>
+librarian_lesson_write_proposal() {
+	local key="$1"
+	local candidate="$2"
+	local artifact_id="$3"
+	[[ -z "$key" || -z "$candidate" || -z "$artifact_id" ]] && return 1
+
+	librarian_lesson_storage_init "$key" || return 1
+
+	local id now out
+	id=$(librarian_ulid) || return 1
+	now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+	out="$(librarian_lessons_dir "$key")/proposals/${id}.json"
+
+	jq -n \
+		--arg id "$id" \
+		--arg artifact_id "$artifact_id" \
+		--arg created "$now" \
+		--argjson candidate "$candidate" \
+		'{
+			id: $id,
+			artifact_id: $artifact_id,
+			created_at: $created,
+			status: "pending",
+			candidate: $candidate
+		}' > "$out" 2>/dev/null || return 1
+
+	printf '%s' "$id"
+}
+
+# Append one decline. Only ever called for real determinations — never for a
+# missing CLI, a timeout, or an empty response. Recording an outage here would
+# 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]
+librarian_lesson_append_declined() {
+	local key="$1"
+	local artifact_id="$2"
+	local reason="$3"
+	local detail="${4:-}"
+	[[ -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
+
+	printf '%s\n' "$line" >> "$(librarian_lessons_dir "$key")/declined.jsonl"
+}
+
+# Returns 0 when this artifact has already been handled.
+#
+# The watermark cannot answer this: last_scan.json records only *when* we
+# scanned, not which artifacts were considered. Idempotency is artifact-keyed
+# and permanent, unlike tombstones (body-hash keyed, TTL'd).
+#
+# Usage: librarian_lesson_seen <key> <artifact_id>
+librarian_lesson_seen() {
+	local key="$1"
+	local artifact_id="$2"
+	[[ -z "$key" || -z "$artifact_id" ]] && return 1
+
+	local dir
+	dir=$(librarian_lessons_dir "$key")
+
+	# -R reads each line as a raw string and fromjson? yields nothing for a
+	# line that fails to parse, instead of aborting the whole jq invocation.
+	# Without this, one truncated trailing line (e.g. a process killed
+	# mid-append) makes jq exit 5 for the entire file, and every artifact
+	# declined before that line reads back as "not seen."
+	#
+	# `objects` after fromjson? is load-bearing, not decorative: fromjson?
+	# only guards the *parse*, not what comes after it in the pipe. A line
+	# that is valid JSON but not an object (a bare `123`, `true`, `"str"`, or
+	# `[1,2,3]`) parses cleanly, then `.artifact_id` indexing on that
+	# non-object errors out the whole jq invocation — the same
+	# every-prior-decline-reads-as-unseen failure the -R/fromjson? guard
+	# above exists to prevent, just reached through a different door.
+	# `objects` filters those values out before `.artifact_id` ever runs.
+	if [[ -f "$dir/declined.jsonl" ]] \
+		&& jq -Re --arg a "$artifact_id" 'fromjson? | objects | select(.artifact_id == $a)' \
+			"$dir/declined.jsonl" >/dev/null 2>&1; then
+		return 0
+	fi
+
+	local f
+	for f in "$dir"/proposals/*.json "$dir"/approved/*.json; do
+		[[ -f "$f" ]] || continue
+		if jq -e --arg a "$artifact_id" '.artifact_id == $a' "$f" >/dev/null 2>&1; then
+			return 0
+		fi
+	done
+
+	return 1
+}

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

@@ -0,0 +1,311 @@
+#!/usr/bin/env bash
+# Lesson transform — librarian's fifth stage.
+#
+# Reads one durable, classified, deduped archivist artifact and emits a lesson
+# candidate: the four fields inferable from an artifact (claim, rationale,
+# evidence, applies_to). The other nine required Lesson fields belong to later
+# stages, so this never produces a schema-complete Lesson and cannot be
+# validated against the full lesson schema.
+#
+# Requires librarian-lesson-validate.sh, librarian-lesson-storage.sh, and
+# librarian-config.sh (librarian_config_get).
+#
+# 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
+
+# Fallback when config hasn't been loaded or leaves the key unset.
+_LIBRARIAN_LESSON_DEFAULT_TIMEOUT_SECONDS=20
+
+# Cap on how much of a response the JSON-object extractor will scan. The
+# scanner is a per-character bash loop — effectively O(n^2) on long input,
+# since bash string slicing on a long string isn't O(1) per call — and it
+# runs after the claude call, uncapped, inside a SessionEnd hook that must
+# not stall session end. `claude -p` has no output-size flag to bound the
+# response itself, so the bound is enforced here instead. A response that
+# exceeds this without yielding valid JSON in the scanned prefix has not
+# followed the "output ONLY a single JSON object on one line" instruction
+# anyway, so declining it is correct, not just expedient.
+_LIBRARIAN_LESSON_EXTRACT_MAX_CHARS=8192
+
+# Usage: librarian_lesson_build_prompt <artifact_json>
+librarian_lesson_build_prompt() {
+	local artifact="$1"
+	local summary detail files_list artifact_id session_id project_key created_at
+
+	summary=$(printf '%s' "$artifact" | jq -r '.summary // ""')
+	detail=$(printf '%s' "$artifact" | jq -r '.detail // ""')
+	files_list=$(printf '%s' "$artifact" | jq -r '(.files // []) | join(", ")')
+	artifact_id=$(printf '%s' "$artifact" | jq -r '.id // ""')
+	session_id=$(printf '%s' "$artifact" | jq -r '.session_id // ""')
+	project_key=$(printf '%s' "$artifact" | jq -r '.project_key // ""')
+	created_at=$(printf '%s' "$artifact" | jq -r '.created_at // ""')
+
+	cat <<EOF
+You are turning a session artifact into a shareable lesson, or refusing to.
+
+A lesson states something that was learned, why it follows, and the exact
+version range in which it holds. It is shared with other people, so a wrong
+lesson actively misleads. Refusing is the safe answer.
+
+Output ONLY one JSON object on one line. No markdown fences, no prose.
+
+REFUSE when either is true, by outputting exactly:
+  { "eligible": false, "reason": "no_resolution" }
+  { "eligible": false, "reason": "no_versions" }
+
+- "no_resolution": the artifact records a problem but not what resolved it.
+  "This breaks" without "and this fixed it" is a warning, not a lesson.
+  Never invent a resolution that is not in the artifact.
+- "no_versions": you cannot determine which versions the claim is bound to.
+
+Otherwise output:
+{
+  "claim": "<what was learned, one sentence>",
+  "rationale": "<why the claim follows from the evidence>",
+  "evidence": { "resolution": "<what actually resolved it, from the artifact>" },
+  "applies_to": {
+    "stack": ["<tool or package name>", "<another tool or package name>"],
+    "scope": { "kind": "versioned", "versions": { "<stack entry>": "<range>" } },
+    "file_patterns": [],
+    "task_kinds": []
+  }
+}
+
+VERSION RANGE RULES — these are strict and a violation is discarded:
+- Allowed: "<6", "<=6", "=6", ">4", ">=4", or two-sided ">=4 <6".
+- FORBIDDEN: npm syntax. Never "^5.4.21", "~5", "5.x", or a bare "5.4.21".
+- FORBIDDEN: ">=0", ">=0.0", ">=0.0.0". An unbounded lower bound matches
+  everything and would never expire.
+- Every key in versions MUST also appear in stack.
+- Generalize honestly. Observing a break on vite 5.4.21 with vitest 4.1.9
+  supports {"vite": "<6", "vitest": ">=4"} only if the cause is the missing
+  API rather than that exact build.
+
+There is no version-independent option. If the claim is not bound to a
+version range, refuse with "no_versions".
+
+<artifact>
+id: ${artifact_id}
+summary: ${summary}
+detail: ${detail}
+files: ${files_list}
+project_key: ${project_key}
+session_id: ${session_id}
+created_at: ${created_at}
+</artifact>
+EOF
+}
+
+# Extract the first balanced top-level JSON object from a string that may
+# carry surrounding prose ("Here is the JSON: {...}"). Prints the substring
+# on success, prints nothing and returns 1 on failure. Depth-tracks braces
+# while skipping ones inside string literals (honoring backslash escapes),
+# so a claim like `{"claim": "uses \"quotes\" and { in prose"}` still
+# extracts correctly.
+#
+# Prose wrapping is not the same failure as unparseable output: a model that
+# added a sentence around otherwise-valid JSON would very likely produce
+# clean JSON on a resample, so declining it as transform_invalid would bury
+# a good artifact over formatting noise rather than a real judgment problem.
+#
+# Usage: _librarian_lesson_extract_json_object <text>
+_librarian_lesson_extract_json_object() {
+	local text="$1"
+	local start=-1 depth=0 in_string=0 escape=0
+	local i len ch
+
+	len=${#text}
+	for (( i = 0; i < len; i++ )); do
+		ch="${text:i:1}"
+		if [[ $start -eq -1 ]]; then
+			[[ "$ch" == "{" ]] && { start=$i; depth=1; }
+			continue
+		fi
+		if [[ $escape -eq 1 ]]; then
+			escape=0
+			continue
+		fi
+		case "$ch" in
+			'\') [[ $in_string -eq 1 ]] && escape=1 ;;
+			'"') in_string=$((1 - in_string)) ;;
+			'{') [[ $in_string -eq 0 ]] && depth=$((depth + 1)) ;;
+			'}')
+				if [[ $in_string -eq 0 ]]; then
+					depth=$((depth - 1))
+					if [[ $depth -eq 0 ]]; then
+						printf '%s' "${text:start:i-start+1}"
+						return 0
+					fi
+				fi
+				;;
+		esac
+	done
+
+	return 1
+}
+
+# Call the model. Prints raw output, or empty string on ANY infrastructure
+# failure — missing CLI, timeout, empty response. Empty means "could not
+# judge", which is not a verdict.
+#
+# Usage: librarian_lesson_call <artifact_json> <model>
+librarian_lesson_call() {
+	local artifact="$1"
+	local model="${2:-}"
+
+	command -v claude >/dev/null 2>&1 || return 0
+	[[ -z "$artifact" ]] && return 0
+
+	local prompt_file
+	prompt_file=$(mktemp -t librarian-lesson.XXXXXX 2>/dev/null) \
+		|| prompt_file="/tmp/librarian-lesson.$$"
+	# shellcheck disable=SC2064
+	trap "rm -f '$prompt_file'" EXIT
+
+	librarian_lesson_build_prompt "$artifact" > "$prompt_file" || return 0
+
+	local args=(-p --max-turns 1)
+	[[ -n "$model" ]] && args+=(--model "$model")
+
+	local timeout_seconds
+	timeout_seconds=$(librarian_config_get '.librarian.lesson_transform.timeout_seconds' 2>/dev/null)
+	[[ -z "$timeout_seconds" || "$timeout_seconds" == "null" ]] \
+		&& timeout_seconds="$_LIBRARIAN_LESSON_DEFAULT_TIMEOUT_SECONDS"
+
+	local response=""
+	if command -v timeout >/dev/null 2>&1; then
+		response=$(timeout "$timeout_seconds" \
+			claude "${args[@]}" < "$prompt_file" 2>/dev/null) || response=""
+	elif command -v gtimeout >/dev/null 2>&1; then
+		response=$(gtimeout "$timeout_seconds" \
+			claude "${args[@]}" < "$prompt_file" 2>/dev/null) || response=""
+	else
+		response=$(claude "${args[@]}" < "$prompt_file" 2>/dev/null) || response=""
+	fi
+
+	rm -f "$prompt_file"
+	trap - EXIT
+
+	[[ -z "$response" ]] && return 0
+
+	local cleaned
+	cleaned=$(printf '%s' "$response" | sed -e 's/^```json//' -e 's/^```//' -e 's/```$//')
+
+	# Fast path: the response is already valid JSON on its own.
+	if printf '%s' "$cleaned" | jq -e . >/dev/null 2>&1; then
+		printf '%s' "$cleaned"
+		return 0
+	fi
+
+	# Slow path: pull the first balanced JSON object out of surrounding
+	# prose. Bounded to a fixed prefix (see _LIBRARIAN_LESSON_EXTRACT_MAX_CHARS)
+	# so a rambling, arbitrarily long response can't turn the O(n^2) scan
+	# into an unbounded stall. Only used when it actually recovers valid
+	# JSON — otherwise fall through to the original text so the
+	# unparseable case still declines.
+	local extracted
+	extracted=$(_librarian_lesson_extract_json_object \
+		"${cleaned:0:_LIBRARIAN_LESSON_EXTRACT_MAX_CHARS}")
+	if [[ -n "$extracted" ]] && printf '%s' "$extracted" | jq -e . >/dev/null 2>&1; then
+		printf '%s' "$extracted"
+		return 0
+	fi
+
+	printf '%s' "$cleaned"
+}
+
+# Transform one artifact. Always exits 0. Prints exactly one of:
+#   proposed:<ulid>       candidate written
+#   declined:<reason>     a real verdict, recorded in declined.jsonl
+#   skipped:pregate       no version token; free to redo, nothing recorded
+#   skipped:seen          already handled
+#   unavailable           infrastructure failure; nothing recorded
+#
+# Usage: librarian_lesson_transform_one <key> <artifact_json>
+librarian_lesson_transform_one() {
+	local key="$1"
+	local artifact="$2"
+	[[ -z "$key" || -z "$artifact" ]] && { printf 'unavailable'; return 0; }
+
+	local artifact_id session_id project_key created_at
+	artifact_id=$(printf '%s' "$artifact" | jq -r '.id // ""')
+	session_id=$(printf '%s' "$artifact" | jq -r '.session_id // ""')
+	project_key=$(printf '%s' "$artifact" | jq -r '.project_key // ""')
+	created_at=$(printf '%s' "$artifact" | jq -r '.created_at // ""')
+	[[ -z "$artifact_id" ]] && { printf 'unavailable'; return 0; }
+
+	if librarian_lesson_seen "$key" "$artifact_id"; then
+		printf 'skipped:seen'
+		return 0
+	fi
+
+	if ! librarian_lesson_pregate "$artifact"; then
+		printf 'skipped:pregate'
+		return 0
+	fi
+
+	local model raw
+	model=$(librarian_config_get '.librarian.lesson_transform.model')
+
+	raw=$(librarian_lesson_call "$artifact" "$model")
+
+	# Empty means infrastructure, not verdict. Leave the artifact untouched.
+	if [[ -z "$raw" ]]; then
+		printf 'unavailable'
+		return 0
+	fi
+
+	if ! printf '%s' "$raw" | jq -e . >/dev/null 2>&1; then
+		librarian_lesson_append_declined "$key" "$artifact_id" "transform_invalid"
+		printf 'declined:transform_invalid'
+		return 0
+	fi
+
+	# An explicit refusal is a real answer. Checked with jq -e rather than a
+	# `// empty` string capture: jq's // operator treats JSON `false` as
+	# falsy, same as null, so `.eligible // empty` silently discards a real
+	# `"eligible": false` refusal instead of reporting it.
+	local reason
+	if printf '%s' "$raw" | jq -e '.eligible == false' >/dev/null 2>&1; then
+		reason=$(printf '%s' "$raw" | jq -r '.reason // "transform_invalid"')
+		case "$reason" in
+			no_resolution|no_versions) ;;
+			*) reason="transform_invalid" ;;
+		esac
+		librarian_lesson_append_declined "$key" "$artifact_id" "$reason"
+		printf 'declined:%s' "$reason"
+		return 0
+	fi
+
+	# Stitch in the provenance the model is not asked to produce.
+	local candidate
+	candidate=$(printf '%s' "$raw" | jq -c \
+		--arg aid "$artifact_id" \
+		--arg sid "$session_id" \
+		--arg pk "$project_key" \
+		--arg at "$created_at" \
+		'.evidence.artifact_ids = [$aid]
+		 | .evidence.session_ids = [$sid]
+		 | .evidence.project_key = $pk
+		 | .evidence.observed_at = $at' 2>/dev/null) || candidate=""
+
+	if [[ -z "$candidate" ]]; then
+		librarian_lesson_append_declined "$key" "$artifact_id" "transform_invalid"
+		printf 'declined:transform_invalid'
+		return 0
+	fi
+
+	if ! librarian_lesson_validate_candidate "$candidate" 2>/dev/null; then
+		librarian_lesson_append_declined "$key" "$artifact_id" "schema_invalid"
+		printf 'declined:schema_invalid'
+		return 0
+	fi
+
+	local id
+	id=$(librarian_lesson_write_proposal "$key" "$candidate" "$artifact_id") || {
+		printf 'unavailable'
+		return 0
+	}
+	printf 'proposed:%s' "$id"
+}