omp-fabric 1.22.0 → 1.22.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.22.1
+
+### Documentation
+
+- Document `judgment.ask`, `judgment.stats`, and `judge.*` ergonomic helpers (`bool`, `choice`, `score`, `filter`, `classify`) in the `fabric-exec` model-facing skill.
+- Document dual-bounded batch chunking (at most 25 items and 48 KiB) and `onFail: "keep-all"` fail-open data retention in `docs/judgment.md`.
+- Update `README.md` capability overview and examples with batch semantic triage guidance.
+
 ## 1.22.0
 
 ### Added

package/README.md

@@ -34,7 +34,7 @@ Fabric gives OMP one programmable tool called `fabric_exec`, which composes core
 | 🧰 | **Capability routing** | Call OMP core tools, MCP servers, captured extension tools, or Fabric providers through one runtime. |
 | 🧑‍🤝‍🧑 | **Agent runtime** | One-shot workers, durable resident agents, persistent event-driven actors, councils, and bounded recursive queries. |
 | 🕸️ | **Workflows + mesh** | Phased progress plus durable topics, shared tasks, and compare-and-swap state. |
-| ⚖️ | **Typed judgment** | Calibrated choice, bool, and score answers about one state, batched into one backend request, with four optional gates that read them. |
+| ⚖️ | **Typed judgment** | Calibrated choice, bool, and score answers about one state, ergonomic guest helpers for batch semantic triage, and four optional gates. |
 | 🛡️ | **Guardrails** | Approvals, isolation, timeouts, concurrency, recursion depth, and shared cost budgets. |
 | 🎛️ | **Native TUI** | Live activity, an interactive dashboard, and settings without leaving OMP. |
 
@@ -58,7 +58,7 @@ return {
 };
 ```
 
-Independent calls run in parallel, and the returned object enters the model context. Known providers support concise direct calls such as `mcp.fal_ai.get_model_schema(...)`, `memory.recall(...)`, `state.get()`, `schema.status()`, `compact.status()`, and `judgment.ask(...)`. Refs found or computed at runtime use `tools.call({ ref, args })`.
+Independent calls run in parallel, and the returned object enters the model context. Known providers support concise direct calls such as `mcp.fal_ai.get_model_schema(...)`, `memory.recall(...)`, `state.get()`, `schema.status()`, `compact.status()`, and `judgment.ask(...)`, alongside `judge.filter(...)` for batch evaluation. Refs found or computed at runtime use `tools.call({ ref, args })`.
 
 ## Install
 

package/docs/judgment.md

@@ -97,6 +97,12 @@ Guest programs and batch scripts access the lane through `globalThis.judge`.
 - `judge.bool(state, instructions, options?)`: returns the probability of yes as a number, or the configured fallback when the backend fails.
 - `judge.choice(state, options, instructions, config?)`: returns the chosen label string from an array or criteria map.
 - `judge.score(state, criteria, instructions, config?)`: returns the score index from ordered levels.
-- `judge.filter(items, instructions, options?)`: evaluates an array in bounded chunks of up to 25 items per request. When a request fails, it preserves all chunk items under `onFail: "keep-all"`.
+- `judge.filter(items, instructions, options?)`: evaluates an array in bounded chunks. When a request fails, it preserves all chunk items under `onFail: "keep-all"`.
 - `judge.classify(items, categories, instructions, options?)`: assigns a category to each item across bounded chunks.
 - `judge.ask(state, questions)`: direct access for custom question maps.
+
+### Batch chunking and fail-open policy
+
+Batch helpers group items with two limits: at most 25 items and at most 48 KiB JSON payload per request. Items larger than 40 KiB are bounded in the evaluation state payload with a truncation notice, while the original item instances remain intact in returned collections.
+
+When a backend request fails or times out, `judge.filter` and `judge.classify` default to `onFail: "keep-all"`, returning all candidate items so failures do not discard data. Callers can also choose `onFail: "empty"` or `onFail: "throw"`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-fabric",
-  "version": "1.22.0",
+  "version": "1.22.1",
   "description": "A programmable tool and agent runtime for Oh My Pi (OMP)",
   "type": "module",
   "main": "./dist/index.js",

package/skills/fabric-exec/SKILL.md

@@ -84,6 +84,8 @@ All calls return promises. Fields ending in `?` are optional; `unknown` marks pr
 | `compact.request(args?)` | `{requested:true,intent:{reason?,instructions?,preserve?,requestedBy,requestedAt}}` |
 | `compact.status()` | `{pending?:CompactIntent,last?:{at,requestedBy,status,summary?,tokensBefore?,estimatedTokensAfter?,error?}}` |
 | `compact.cancel()` | `{cancelled:true}` |
+| `judgment.ask(args)` | `{ok:true,backend,answers:Record<string,Answer>}|{ok:false,reason,detail?}` |
+| `judgment.stats()` | `{enabled,requests,batched,questions,merged,failures,refusals,timeouts,lastBackend?,lastError?}` |
 
 `memory.recall` multi-term literal queries default to ranked `queryMatch: "any"` so wording differences do not hide evidence; use `"all"` to require every canonical term in one indexed entry, and `queryMode: "phrase"` when adjacency matters. Results are hard-bounded either way. Structural filters (`ref`, `provider`, `action`, `outcome`) use exact persisted trace fields. Use `tools.catalog()`/`tools.search()` only to choose a current action head—catalog descriptions are navigation metadata and never become session evidence.
 
@@ -93,6 +95,8 @@ Recall returns one bounded flat hit stream. Every hit has the same copy-ready `{
 
 Stable-provider arguments normalize near-miss spellings the way `omp.*` does: known aliases and casing/singular variants repair to the canonical key, numeric strings coerce for numeric fields, and scope spellings such as `cwd` repair to `project`. Unknown keys are never silently ignored—they fail validation with the offending property path named (e.g. `/befroe: must NOT have additional properties`).
 
+`judge.*` exposes ergonomic guest helpers over the judgment lane. `judge.bool(state, instructions, {fallback?})` returns probability of yes (`0..1`) or a fallback number. `judge.choice(state, options, instructions, {fallback?})` evaluates a choice label. `judge.score(state, criteria, instructions, {fallback?})` evaluates an ordered level index. `judge.filter(items, instructions, {threshold?,onFail?,maxItems?,maxBytes?})` and `judge.classify(items, categories, instructions, {onFail?,fallbackCategory?,maxItems?,maxBytes?})` evaluate collections with dual-bounded chunking (<=25 items, <=48 KiB) and fail-open preservation (`onFail: "keep-all"`). `judge.ask(state, questions)` provides direct access for custom question maps.
+
 `SessionInfo` is `{id,file,cwd,mtime,entryCount,tier:"hot"|"cold",branches,lineageFingerprint}`. Memory failures are returned in `error: {code,message,...}`; ambiguous-session failures may return only `{error}`. Check `error` before relying on optional success fields.
 
 ### Dynamic provider return shapes