@curatelabs/graphforge-agent-skills 0.5.1 → 0.6.0-rc.4

package/README.md

@@ -68,6 +68,15 @@ Input, output, and error-detail payloads enforce the same recursive value
 budgets in the dependency-free validator; the checked-in schemas additionally
 bound every nested string, array, and object.
 
+For an external decision call, place the complete request contract under the
+normal input envelope and validate that value with the separately exported
+`decision-batch-v1.json` schema. The schema carries the Rust validator's typed
+choices, rubric order, uncertainty, producer confidence meaning, input
+identity, and row limits. The adapter remains transport only: application code
+passes the batch to the native `validateDecisionBatch` method and owns any
+clarification, review, or action policy. It does not execute a producer or
+drop fields to fit its recursive payload budget.
+
 ## Local offline smoke
 
 From the repository root, create the local artifact and run the deterministic
@@ -86,7 +95,7 @@ npx --offline --no-install graphforge-agent-skills compatibility --json
 ```
 
 The compatibility response is machine-readable and currently declares support
-for GraphForge `>=0.5.0 <0.6.0`.
+for GraphForge `>=0.6.0-dev <0.7.0`.
 
 ## Bootstrap, build knowledge, and resolve belief
 
@@ -102,8 +111,8 @@ conflicts.
 Build knowledge accepts caller-keyed nodes and edges plus caller-supplied UUIDv7
 operation and ledger identities. It enables the public provenance/knowledge
 capabilities, uses native UUID handles for graph references, and uses the atomic
-assertion-plus-nonempty-evidence API, then appends the required explicit M20
-confidence assessment. M21 reasoning and first status are appended only when
+assertion-plus-nonempty-evidence API, then appends the required explicit knowledge
+confidence assessment. epistemic reasoning and first status are appended only when
 their explicit input blocks are supplied. A domain property named `confidence`
 remains an ordinary graph property.
 
@@ -124,20 +133,20 @@ fingerprints. Native ambiguity remains a structured error; confidence is never
 used to choose an alternative. The returned opaque `projection` is reserved for
 later recorded dispatch through the native resolved-projection API.
 
-`narrateBeliefRecords` pages every public scoped M20/M21 history family for the
+`narrateBeliefRecords` pages every public scoped knowledge/epistemic history family for the
 resolved assertion set within an explicit `record_budget`, keeps competing and
 superseded records distinguishable, and returns project-level pagination
 descriptors rather than truncating broader collections.
 
 `dispatchRecordedNeutralAnalysis` forwards one caller-prepared descriptor to
 `invokeResolvedRecorded`, returns the Arrow result with independent run and
-attachment state, and leaves completed M20 runs queryable when attachment fails.
+attachment state, and leaves completed knowledge runs queryable when attachment fails.
 
 `exploreGraph` dispatches bounded neighborhood, traversal, path, and
 reachability requests through the public paths/descriptor facade, fails closed
 without finite bounds, and opens only the graph capability.
 
-`retrieveAnalyze` reaches public M19 find modes and every live M18 family with
+`retrieveAnalyze` reaches public search find modes and every live algorithm family with
 explicit caller-selected algorithms/inputs, finite `result_limit`, and
 graph-only capability opens.
 

package/compatibility.json

@@ -1,9 +1,9 @@
 {
   "schema_version": 1,
   "package": "@curatelabs/graphforge-agent-skills",
-  "package_version": "0.5.1",
-  "graphforge_release": "0.5.1",
-  "graphforge_version_range": ">=0.5.0 <0.6.0",
+  "package_version": "0.6.0-rc.4",
+  "graphforge_release": "0.6.0-rc.4",
+  "graphforge_version_range": ">=0.6.0-dev <0.7.0",
   "security_contract": {
     "subprocess": "unsupported",
     "project_symlinks": "rejected",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@curatelabs/graphforge-agent-skills",
-  "version": "0.5.1",
+  "version": "0.6.0-rc.4",
   "description": "NPX-distributed agent skills and adapters for GraphForge",
   "license": "Apache-2.0",
   "homepage": "https://docs.graphforge.sh/",
@@ -39,6 +39,7 @@
     "./workflows": "./workflows/index.js",
     "./schemas": "./schemas/validator.js",
     "./schemas/input-envelope-v1.json": "./schemas/input-envelope-v1.json",
+    "./schemas/decision-batch-v1.json": "./schemas/decision-batch-v1.json",
     "./schemas/output-envelope-v1.json": "./schemas/output-envelope-v1.json",
     "./schemas/skill-manifest-v1.json": "./schemas/skill-manifest-v1.json",
     "./compatibility.json": "./compatibility.json"
@@ -48,8 +49,8 @@
   },
   "graphforgeCompatibility": {
     "schemaVersion": 1,
-    "release": "0.5.1",
-    "range": ">=0.5.0 <0.6.0"
+    "release": "0.6.0-rc.4",
+    "range": ">=0.6.0-dev <0.7.0"
   },
   "publishConfig": {
     "access": "public",

package/schemas/README.md

@@ -9,6 +9,10 @@ is closed (`additionalProperties: false`) and carries the exact integer
 - `input-envelope-v1.json` carries one skill invocation.
 - `output-envelope-v1.json` carries either a successful result or a structured
   error.
+- `decision-batch-v1.json` describes the provider-neutral input accepted by
+  the native Rust decision validator, including finite choices, ordered
+  rubric levels, explicit result status, confidence meaning and the 256-row
+  result bound.
 
 Import `validateSkillManifest`, `validateSkillInput`, or `validateSkillOutput`
 from `@curatelabs/graphforge-agent-skills/schemas`. Validation is local and deterministic;

package/schemas/decision-batch-v1.json

@@ -0,0 +1,199 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://graphforge.dev/schemas/decision-batch-v1.json",
+  "title": "GraphForge provider-neutral decision batch v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["input", "producer", "questions", "results"],
+  "properties": {
+    "input": { "$ref": "#/$defs/input" },
+    "producer": { "$ref": "#/$defs/producer" },
+    "questions": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 256,
+      "items": { "$ref": "#/$defs/question" }
+    },
+    "results": {
+      "type": "array",
+      "maxItems": 256,
+      "items": { "$ref": "#/$defs/result" }
+    }
+  },
+  "$defs": {
+    "uuid": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+    },
+    "digest": {
+      "type": "array",
+      "minItems": 32,
+      "maxItems": 32,
+      "items": { "type": "integer", "minimum": 0, "maximum": 255 }
+    },
+    "label": { "type": "string", "minLength": 1, "maxLength": 256 },
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "generation_uuid",
+        "projection_sha256",
+        "selection_sha256",
+        "selected_item_uuids"
+      ],
+      "properties": {
+        "generation_uuid": { "$ref": "#/$defs/uuid" },
+        "version_uuid": {
+          "anyOf": [{ "$ref": "#/$defs/uuid" }, { "type": "null" }]
+        },
+        "projection_sha256": { "$ref": "#/$defs/digest" },
+        "selection_sha256": { "$ref": "#/$defs/digest" },
+        "selected_item_uuids": {
+          "type": "array",
+          "maxItems": 4096,
+          "items": { "$ref": "#/$defs/uuid" }
+        }
+      }
+    },
+    "producer": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name"],
+      "properties": {
+        "name": { "$ref": "#/$defs/label" },
+        "model": { "anyOf": [{ "$ref": "#/$defs/label" }, { "type": "null" }] },
+        "revision": {
+          "anyOf": [{ "$ref": "#/$defs/label" }, { "type": "null" }]
+        }
+      }
+    },
+    "question": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["question_uuid", "text", "item_uuids", "kind"],
+      "properties": {
+        "question_uuid": { "$ref": "#/$defs/uuid" },
+        "text": { "type": "string", "minLength": 1, "maxLength": 4096 },
+        "item_uuids": {
+          "type": "array",
+          "maxItems": 256,
+          "items": { "$ref": "#/$defs/uuid" }
+        },
+        "kind": {
+          "oneOf": [
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["kind", "allowed_choices"],
+              "properties": {
+                "kind": { "const": "choice" },
+                "allowed_choices": {
+                  "type": "array",
+                  "minItems": 1,
+                  "maxItems": 256,
+                  "items": { "$ref": "#/$defs/label" }
+                }
+              }
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["kind", "ordered_levels"],
+              "properties": {
+                "kind": { "const": "rubric_score" },
+                "ordered_levels": {
+                  "type": "array",
+                  "minItems": 2,
+                  "maxItems": 256,
+                  "items": { "$ref": "#/$defs/label" }
+                }
+              }
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["kind"],
+              "properties": { "kind": { "const": "yes_no_probability" } }
+            }
+          ]
+        }
+      }
+    },
+    "confidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["value", "minimum", "maximum", "domain", "meaning"],
+      "properties": {
+        "value": { "type": "number" },
+        "minimum": { "type": "number" },
+        "maximum": { "type": "number" },
+        "domain": { "$ref": "#/$defs/label" },
+        "meaning": { "type": "string", "minLength": 1, "maxLength": 4096 }
+      }
+    },
+    "result": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["question_uuid", "status"],
+      "properties": {
+        "question_uuid": { "$ref": "#/$defs/uuid" },
+        "item_uuid": {
+          "anyOf": [{ "$ref": "#/$defs/uuid" }, { "type": "null" }]
+        },
+        "status": {
+          "enum": ["answered", "uncertain", "unavailable", "missing"]
+        },
+        "value": {
+          "oneOf": [
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["kind", "value"],
+              "properties": {
+                "kind": { "const": "choice" },
+                "value": { "$ref": "#/$defs/label" }
+              }
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["kind", "value"],
+              "properties": {
+                "kind": { "const": "rubric_score" },
+                "value": { "$ref": "#/$defs/label" }
+              }
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["kind", "value"],
+              "properties": {
+                "kind": { "const": "yes_no_probability" },
+                "value": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["yes_probability"],
+                  "properties": {
+                    "yes_probability": {
+                      "type": "number",
+                      "minimum": 0,
+                      "maximum": 1
+                    },
+                    "no_probability": {
+                      "type": ["number", "null"],
+                      "minimum": 0,
+                      "maximum": 1
+                    }
+                  }
+                }
+              }
+            }
+          ]
+        },
+        "confidence": {
+          "anyOf": [{ "$ref": "#/$defs/confidence" }, { "type": "null" }]
+        }
+      }
+    }
+  }
+}

package/skills/README.md

@@ -2,7 +2,7 @@
 
 `bootstrap` creates or reopens a local project and verifies a real
 create/reopen/query cycle. `build-knowledge` appends caller-specified graph and
-M20 records, with optional explicit M21 reasoning and first status. Both use the
+knowledge records, with optional explicit epistemic reasoning and first status. Both use the
 shared adapter and injected shipped Node/Arrow surfaces; neither contains a
 runtime, fallback backend, inference, search, traversal, or algorithm behavior.
 

package/skills/build-knowledge/manifest.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "id": "build-knowledge",
   "title": "Build GraphForge graph and knowledge records",
-  "description": "Append UUID-backed graph records and required M20 provenance, assertion, confidence, and evidence records, with optional additional M21 status and reasoning, without inference or overwrite.",
+  "description": "Append UUID-backed graph records and required knowledge provenance, assertion, confidence, and evidence records, with optional additional epistemic status and reasoning, without inference or overwrite.",
   "input_schema": "graphforge-agent-skill-input/v1",
   "output_schema": "graphforge-agent-skill-output/v1",
   "required_capabilities": {

package/workflows/index.js

@@ -542,8 +542,8 @@ export async function narrateBeliefRecords({
 }
 
 /**
- * Optionally dispatch one caller-prepared neutral M18 analysis on a resolved
- * belief projection, preserving completed M20 runs when M21 attachment fails.
+ * Optionally dispatch one caller-prepared neutral algorithm analysis on a resolved
+ * belief projection, preserving completed knowledge runs when epistemic attachment fails.
  */
 export async function dispatchRecordedNeutralAnalysis({
   GraphForge,
@@ -810,7 +810,7 @@ const RETRIEVE_SURFACES = new Set(["find", "rank", "cluster", "paths", "analyze"
 const MAX_RETRIEVE_RESULT_LIMIT = 10_000;
 
 /**
- * Bounded retrieve/analyze over public M19 find and live M18 descriptor families.
+ * Bounded retrieve/analyze over public search find and live algorithm descriptor families.
  *
  * Caller-selected modes and descriptor fields pass through unchanged. Rust owns
  * algorithm/search semantics; this workflow only enforces finite bounds and
@@ -922,7 +922,7 @@ function validateRetrieveInput(input) {
   if (typeof input.algorithm !== "string" || input.algorithm.length === 0) {
     throw new AgentAdapterError(
       "GF_AGENT_RETRIEVE_ALGORITHM_REQUIRED",
-      "M18 surfaces require an explicit algorithm catalog value",
+      "algorithm surfaces require an explicit algorithm catalog value",
     );
   }
   if (surface !== "analyze" && (typeof input.label !== "string" || input.label.length === 0)) {
@@ -935,7 +935,7 @@ function validateRetrieveInput(input) {
   }
   return {
     echo: {
-      m18: {
+      algorithm: {
         algorithm: input.algorithm,
         directed: input.directed === undefined ? null : Boolean(input.directed),
         label: input.label ?? null,
@@ -945,7 +945,7 @@ function validateRetrieveInput(input) {
         via: input.via ?? null,
       },
     },
-    m18: {
+    algorithm: {
       algorithm: input.algorithm,
       directed: input.directed,
       label: input.label,
@@ -973,57 +973,91 @@ function invokeRetrieve(graph, request) {
       request.find.forceStale,
     );
   }
-  const { m18, surface } = request;
+  const { algorithm, surface } = request;
   if (surface === "rank") {
     if (typeof graph.prepareRankInvocation === "function") {
       return graph.invokeDescriptor(
-        graph.prepareRankInvocation(m18.label, m18.algorithm, m18.via, m18.directed),
+        graph.prepareRankInvocation(
+          algorithm.label,
+          algorithm.algorithm,
+          algorithm.via,
+          algorithm.directed,
+        ),
       );
     }
-    return graph.rank(m18.label, m18.algorithm, m18.via, m18.directed);
+    return graph.rank(algorithm.label, algorithm.algorithm, algorithm.via, algorithm.directed);
   }
   if (surface === "cluster") {
     if (typeof graph.prepareClusterInvocation === "function") {
       return graph.invokeDescriptor(
         graph.prepareClusterInvocation(
-          m18.label,
-          m18.algorithm,
-          m18.via,
-          m18.directed,
-          m18.vectorProperty,
+          algorithm.label,
+          algorithm.algorithm,
+          algorithm.via,
+          algorithm.directed,
+          algorithm.vectorProperty,
         ),
       );
     }
-    return graph.cluster(m18.label, m18.algorithm, m18.via, m18.directed, m18.vectorProperty);
+    return graph.cluster(
+      algorithm.label,
+      algorithm.algorithm,
+      algorithm.via,
+      algorithm.directed,
+      algorithm.vectorProperty,
+    );
   }
   if (surface === "paths") {
     if (typeof graph.preparePathsInvocation === "function") {
       return graph.invokeDescriptor(
-        graph.preparePathsInvocation(m18.source, m18.target, m18.algorithm, m18.via, m18.directed),
+        graph.preparePathsInvocation(
+          algorithm.source,
+          algorithm.target,
+          algorithm.algorithm,
+          algorithm.via,
+          algorithm.directed,
+        ),
       );
     }
-    return graph.paths(m18.source, m18.target, m18.algorithm, m18.via, m18.directed);
+    return graph.paths(
+      algorithm.source,
+      algorithm.target,
+      algorithm.algorithm,
+      algorithm.via,
+      algorithm.directed,
+    );
   }
   if (surface === "analyze") {
     if (typeof graph.prepareAnalyzeInvocation === "function") {
       return graph.invokeDescriptor(
-        graph.prepareAnalyzeInvocation(m18.algorithm, m18.label, m18.via, m18.directed),
+        graph.prepareAnalyzeInvocation(
+          algorithm.algorithm,
+          algorithm.label,
+          algorithm.via,
+          algorithm.directed,
+        ),
       );
     }
-    return graph.analyze(m18.algorithm, m18.label, m18.via, m18.directed);
+    return graph.analyze(algorithm.algorithm, algorithm.label, algorithm.via, algorithm.directed);
   }
   if (typeof graph.prepareSimilarInvocation === "function") {
     return graph.invokeDescriptor(
       graph.prepareSimilarInvocation(
-        m18.label,
-        m18.algorithm,
+        algorithm.label,
+        algorithm.algorithm,
         request.resultLimit,
-        m18.vectorProperty,
-        m18.via,
+        algorithm.vectorProperty,
+        algorithm.via,
       ),
     );
   }
-  return graph.similar(m18.label, m18.algorithm, request.resultLimit, m18.vectorProperty, m18.via);
+  return graph.similar(
+    algorithm.label,
+    algorithm.algorithm,
+    request.resultLimit,
+    algorithm.vectorProperty,
+    algorithm.via,
+  );
 }
 
 function configuredSurfaces(GraphForge, tableFromIPC) {