fix: enforce exact record_fact fields and validate asset anchors

This commit is contained in:
Chubboy Ren
2026-11-18 01:51:41 +00:00
parent c0c568b31f
commit c833130c28
6 changed files with 274 additions and 27 deletions
+53 -1
View File
@@ -91,7 +91,7 @@ func TestRecordFactAssetAliases(t *testing.T) {
t.Fatal("invalid asset lists wrote facts")
}
out := callGuardTool(t, tools.recordFact(), fmt.Sprintf(`{"tested_asset_ids":[%d],"facts":[{"summary":"batch alias","tested_asset_ids":[%d]},{"summary":"batch conflict","asset_ids":[%d],"tested_asset_ids":[%d]},{"summary":"no inherited assets"}]}`, second, first, first, second))
out := callGuardTool(t, tools.recordFact(), fmt.Sprintf(`{"facts":[{"summary":"batch alias","tested_asset_ids":[%d]},{"summary":"batch conflict","asset_ids":[%d],"tested_asset_ids":[%d]},{"summary":"no inherited assets"}]}`, first, first, second))
var batch struct {
IDs []int64 `json:"ids"`
Errors map[string]string `json:"errors"`
@@ -128,3 +128,55 @@ func TestRecordFactAssetAliasSchema(t *testing.T) {
}
}
}
func TestRecordFactRejectsMissingAssets(t *testing.T) {
d := testDB(t)
defer d.Close()
task, err := d.CreateTask("missing fact anchors", "test", nil, 0, 0)
if err != nil {
t.Fatal(err)
}
defer d.DeleteTask(task.ID)
assets := d.Assets()
var ids []int64
for _, name := range []string{"missing-fact-one.example", "missing-fact-two.example", "existing-fact.example"} {
id, err := assets.UpsertRootDomain(db.UpsertRootDomainReq{Domain: name, TaskID: task.ID})
if err != nil {
t.Fatal(err)
}
ids = append(ids, id)
}
defer assets.DeleteByIDs(ids)
if _, err := assets.DeleteByIDs(ids[:2]); err != nil {
t.Fatal(err)
}
tools := NewToolSet(d.Exploration(task.ExplorationID), "worker")
var beforeFacts int
if err := d.QueryRow("SELECT count(*) FROM exploration_nodes WHERE exploration_id=$1 AND kind='fact'", task.ExplorationID).Scan(&beforeFacts); err != nil {
t.Fatal(err)
}
for _, field := range []string{"asset_ids", "tested_asset_ids"} {
out := callGuardTool(t, tools.recordFact(), fmt.Sprintf(`{"summary":"missing anchors","%s":[%d,%d,%d]}`, field, ids[0], ids[1], ids[2]))
if !out.IsError || !strings.Contains(out.Flatten(), "do not exist") ||
!strings.Contains(out.Flatten(), strconv.FormatInt(ids[0], 10)) ||
!strings.Contains(out.Flatten(), strconv.FormatInt(ids[1], 10)) ||
strings.Contains(out.Flatten(), "23503") || strings.Contains(out.Flatten(), "foreign key") {
t.Fatalf("missing assets did not produce an actionable error: %s", out.Flatten())
}
}
var count int
if err := d.QueryRow("SELECT count(*) FROM exploration_nodes WHERE exploration_id=$1 AND kind='fact'", task.ExplorationID).Scan(&count); err != nil || count != beforeFacts || tools.Writes().Facts != 0 {
t.Fatalf("failed anchors left facts: count=%d err=%v", count, err)
}
out := callGuardTool(t, tools.recordFact(), fmt.Sprintf(`{"facts":[{"summary":"valid","asset_ids":[%d]},{"summary":"missing","tested_asset_ids":[%d]}]}`, ids[2], ids[0]))
var batch struct {
IDs []int64 `json:"ids"`
Errors map[string]string `json:"errors"`
}
if err := json.Unmarshal([]byte(out.Flatten()), &batch); err != nil {
t.Fatal(out.Flatten(), err)
}
if !out.IsError || len(batch.IDs) != 2 || batch.IDs[0] <= 0 || batch.IDs[1] != 0 || !strings.Contains(batch.Errors["1"], "do not exist") || tools.Writes().Facts != 1 {
t.Fatal("missing asset batch handling:", out.Flatten())
}
}
+102 -9
View File
@@ -1,6 +1,20 @@
package agent
import "encoding/json"
import (
"bytes"
"encoding/json"
"fmt"
)
// Match strings.TrimSpace, including Unicode whitespace, in the published schema.
const factWhitespace = "\t\n\v\f\r \u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000"
func factAssetIDSchema() map[string]any {
return map[string]any{
"type": []string{"integer", "string"}, "minimum": 1,
"pattern": "^[" + factWhitespace + "]*\\+?0*[1-9][0-9]*[" + factWhitespace + "]*$",
}
}
func factItemSchema() map[string]any {
schema := obj(map[string]any{
@@ -10,10 +24,13 @@ func factItemSchema() map[string]any {
"evidence": str("One line of key evidence: the command and the most proving output lines. Put longer output in detail."),
"confidence": str("observed (seen directly in output) | inferred (inferred from phenomena). Label negative conclusions honestly."),
"source": map[string]any{"type": "string", "enum": factSources, "description": "where the content came from: target_response | tool_output | third_party_intel | operator_input | inference (default when omitted)"},
"asset_ids": map[string]any{"type": "array", "items": map[string]any{"type": "integer", "minimum": 1}, "description": "Asset IDs explicitly involved in this fact. Use asset_ids as the canonical field; tested_asset_ids is accepted as an alias. If both are provided, they must name the same set. Do not infer IDs from the intent."},
"tested_asset_ids": map[string]any{"type": "array", "items": map[string]any{"type": "integer", "minimum": 1}, "description": "Compatibility alias for asset_ids, not an additional list. When both are provided their sets must match. Only include assets actually involved in this conclusion."},
"asset_ids": map[string]any{"type": "array", "items": factAssetIDSchema(), "description": "Asset IDs explicitly involved in this fact. Use asset_ids as the canonical field; tested_asset_ids is accepted as an alias. If both are provided, they must name the same set. Do not infer IDs from the intent."},
"tested_asset_ids": map[string]any{"type": "array", "items": factAssetIDSchema(), "description": "Compatibility alias for asset_ids, not an additional list. When both are provided their sets must match. Only include assets actually involved in this conclusion."},
}, "summary")
schema["properties"].(map[string]any)["summary"].(map[string]any)["minLength"] = 1
summary := schema["properties"].(map[string]any)["summary"].(map[string]any)
summary["minLength"] = 1
summary["pattern"] = "[^" + factWhitespace + "]"
schema["additionalProperties"] = false
return schema
}
@@ -24,15 +41,13 @@ func recordFactSchema() map[string]any {
"description": "A non-empty batch of complete facts. Every item needs its own summary. Only intent_id inherits from the top level. Returned ids match item order; retry only failed indices.",
}
schema := obj(props)
schema["anyOf"] = []any{
map[string]any{"required": []string{"summary"}},
map[string]any{"required": []string{"facts"}},
}
// Providers reject root-level anyOf. The handler enforces single/batch mode.
schema["additionalProperties"] = false
return schema
}
// RepairRecordFactSchema restores the single/batch input contract in stored or
// cached schemas without changing operator descriptions, defaults or extra fields.
// cached schemas, preserving annotations only on fields the handler accepts.
func RepairRecordFactSchema(stored map[string]any) map[string]any {
raw, _ := json.Marshal(stored)
var out map[string]any
@@ -43,6 +58,21 @@ func RepairRecordFactSchema(stored map[string]any) map[string]any {
mergeFactContract(out, recordFactSchema())
// A batch requires summaries on its items, never a redundant top-level one.
delete(out, "required")
delete(out, "anyOf")
canonical := recordFactSchema()["properties"].(map[string]any)
props := out["properties"].(map[string]any)
for name := range props {
if _, known := canonical[name]; !known {
delete(props, name)
}
}
items := props["facts"].(map[string]any)["items"].(map[string]any)
itemProps := items["properties"].(map[string]any)
for name := range itemProps {
if _, known := canonical[name]; !known || name == "facts" {
delete(itemProps, name)
}
}
return out
}
@@ -65,3 +95,66 @@ func mergeFactContract(dst, src map[string]any) {
}
}
}
type recordFactInput struct {
Facts []factItem `json:"facts"`
factItem
}
// Validate exact field names before decoding: encoding/json otherwise treats
// Summary, SUMMARY, etc. as aliases even with DisallowUnknownFields enabled.
func decodeRecordFactInput(in json.RawMessage) (recordFactInput, bool, error) {
var out recordFactInput
fields, err := exactFactFields(in, true)
if err != nil {
return out, false, err
}
_, batch := fields["facts"]
if batch {
for name := range fields {
if name != "intent_id" && name != "facts" {
return out, true, fmt.Errorf("field %q is not allowed at the top level in batch mode; only intent_id and facts are accepted", name)
}
}
var items []json.RawMessage
if err := json.Unmarshal(fields["facts"], &items); err != nil {
return out, true, fmt.Errorf("facts must be an array: %w", err)
}
if len(items) == 0 {
return out, true, fmt.Errorf("facts must be a non-empty array of complete facts, each with its own summary")
}
for i, item := range items {
if _, err := exactFactFields(item, false); err != nil {
return out, true, fmt.Errorf("facts[%d]: %w", i, err)
}
}
}
decoder := json.NewDecoder(bytes.NewReader(in))
decoder.DisallowUnknownFields() // Also applies recursively to every factItem.
if err := decoder.Decode(&out); err != nil {
return out, batch, err
}
return out, batch, nil
}
func exactFactFields(in json.RawMessage, topLevel bool) (map[string]json.RawMessage, error) {
var fields map[string]json.RawMessage
if err := json.Unmarshal(in, &fields); err != nil {
return nil, err
}
if fields == nil {
return nil, fmt.Errorf("record_fact input and each fact must be objects")
}
for name := range fields {
switch name {
case "summary", "detail", "evidence", "confidence", "source", "intent_id", "asset_ids", "tested_asset_ids":
case "facts":
if !topLevel {
return nil, fmt.Errorf("unknown field %q", name)
}
default:
return nil, fmt.Errorf("unknown field %q (field names are case-sensitive)", name)
}
}
return fields, nil
}
+68 -3
View File
@@ -2,6 +2,7 @@ package agent
import (
"encoding/json"
"regexp"
"strings"
"testing"
@@ -49,6 +50,7 @@ func TestRecordFactSummaryContract(t *testing.T) {
func TestRecordFactStoredContractRepair(t *testing.T) {
old := map[string]any{
"type": "object", "required": []any{"summary"},
"anyOf": []any{map[string]any{"required": []string{"summary"}}},
"properties": map[string]any{
"summary": map[string]any{"type": "string", "description": "operator summary"},
"confidence": map[string]any{"type": "string", "default": "inferred"},
@@ -62,8 +64,8 @@ func TestRecordFactStoredContractRepair(t *testing.T) {
if _, required := schema["required"]; required {
t.Fatal("batch still requires a top-level summary")
}
if len(schema["anyOf"].([]any)) != 2 {
t.Fatal("single/batch alternatives missing")
if _, exists := schema["anyOf"]; exists {
t.Fatal("root anyOf reaches the provider")
}
props := schema["properties"].(map[string]any)
item := props["facts"].(map[string]any)["items"].(map[string]any)
@@ -77,7 +79,7 @@ func TestRecordFactStoredContractRepair(t *testing.T) {
}
if repaired.Description() != "operator tool" ||
props["summary"].(map[string]any)["description"] != "operator summary" ||
props["confidence"].(map[string]any)["default"] != "inferred" || props["custom_field"] == nil {
props["confidence"].(map[string]any)["default"] != "inferred" || props["custom_field"] != nil {
t.Fatal("operator annotations lost")
}
if _, ok := old["properties"].(map[string]any)["tested_asset_ids"]; ok {
@@ -98,3 +100,66 @@ func TestRecordFactStoredContractRepair(t *testing.T) {
}
}
}
func TestRecordFactStrictFields(t *testing.T) {
tools := NewToolSet(guardTaskStore(t), "worker")
for _, tc := range []struct{ input, field string }{
{`{"summary":"valid","typo":1}`, "typo"},
{`{"Summary":"case alias"}`, "Summary"},
{`{"summary":"valid","Facts":[]}`, "Facts"},
{`{"facts":[{"summary":"first"},{"summary":"second","typo":1}]}`, "typo"},
{`{"facts":[{"summary":"first"},{"Summary":"case alias"}]}`, "Summary"},
{`{"facts":[{"summary":"first"},{"summary":"second","ASSET_IDS":[]}]}`, "ASSET_IDS"},
{`{"facts":[{"summary":"nested","facts":[]}]}`, "facts"},
{`{"summary":"ignored","facts":[{"summary":"batch"}]}`, "summary"},
{`{"detail":"ignored","facts":[{"summary":"batch"}]}`, "detail"},
{`{"evidence":"ignored","facts":[{"summary":"batch"}]}`, "evidence"},
{`{"source":"inference","facts":[{"summary":"batch"}]}`, "source"},
{`{"confidence":"inferred","facts":[{"summary":"batch"}]}`, "confidence"},
{`{"asset_ids":[],"facts":[{"summary":"batch"}]}`, "asset_ids"},
{`{"tested_asset_ids":[],"facts":[{"summary":"batch"}]}`, "tested_asset_ids"},
} {
out := callGuardTool(t, tools.recordFact(), tc.input)
if !out.IsError || !strings.Contains(out.Flatten(), tc.field) {
t.Errorf("input %s: want named rejection for %s, got %s", tc.input, tc.field, out.Flatten())
}
}
if tools.Writes().Facts != 0 {
t.Fatal("malformed fields caused partial writes")
}
for _, input := range []string{
`{"facts":[null]}`, `{"facts":[[]]}`, `{"summary":"valid"} {"summary":"extra object"}`,
} {
if _, _, err := decodeRecordFactInput(json.RawMessage(input)); err == nil {
t.Errorf("accepted %s", input)
}
}
if _, batch, err := decodeRecordFactInput(json.RawMessage(`{"intent_id":1,"facts":[{"summary":"valid","intent_id":2}]}`)); err != nil || !batch {
t.Fatalf("valid batch: %v %v", batch, err)
}
}
func TestRecordFactSchemaMatchesStrings(t *testing.T) {
props := recordFactSchema()["properties"].(map[string]any)
summary := regexp.MustCompile(props["summary"].(map[string]any)["pattern"].(string))
for _, value := range []string{"", " ", "\t\r\n", "\u00a0\u0085", "\u2003\u3000", "conclusion", " observed "} {
if got, want := summary.MatchString(value), strings.TrimSpace(value) != ""; got != want {
t.Errorf("summary %q: schema=%v runtime=%v", value, got, want)
}
}
id := regexp.MustCompile(factAssetIDSchema()["pattern"].(string))
for _, value := range []string{"1", "001", "+1", " +001 ", "\u200312\u3000", "", "0", "-1", "1.5", "a"} {
raw, _ := json.Marshal(value)
if got, want := id.MatchString(value), pid(raw) > 0; got != want {
t.Errorf("asset ID %q: schema=%v runtime=%v", value, got, want)
}
}
for _, input := range []string{
`{"summary":"single","asset_ids":["1",2]}`,
`{"facts":[{"summary":"batch","tested_asset_ids":["1",2]}]}`,
} {
if err := actool.ValidateInput(recordFactSchema(), json.RawMessage(input)); err != nil {
t.Errorf("numeric-string compatibility rejected: %v", err)
}
}
}
+2 -13
View File
@@ -1591,21 +1591,10 @@ func (t *ToolSet) recordFact() actool.CoreTool {
" · **Negative conclusions** (not injectable / port closed / no entry found, etc.) state only \"observation + tentative reading\" — state what you actually saw; whether to abandon the direction is for the planner to decide globally; always provide evidence, mark inferred when the means weren't exhausted or the evidence is weak (including probed only once, looks-like), and mark observed only when truly exhausted and directly seen.",
recordFactSchema(),
func(_ context.Context, in json.RawMessage) (actool.Result, error) {
var a struct {
Facts []factItem `json:"facts"`
factItem // single mode + batch default intent_id
}
if err := json.Unmarshal(in, &a); err != nil {
a, batch, err := decodeRecordFactInput(in)
if err != nil {
return actool.Errorf("invalid record_fact input: " + err.Error() + "; no facts were written"), nil
}
var fields map[string]json.RawMessage
if err := json.Unmarshal(in, &fields); err != nil || fields == nil {
return actool.Errorf("record_fact input must be an object; no facts were written"), nil
}
_, batch := fields["facts"]
if batch && len(a.Facts) == 0 {
return actool.Errorf("facts must be a non-empty array of complete facts, each with its own summary; for a single fact omit facts and provide summary. No facts were written"), nil
}
items := a.Facts
if !batch {
items = []factItem{a.factItem}
+41
View File
@@ -230,6 +230,13 @@ func (s *ExplorationStore) AddNode(kind string, payload map[string]any, priority
return 0, err
}
defer tx.Rollback()
// Validate fact anchors before creating a node. Key-share locks retain the
// checked assets through commit, closing the check/insert deletion race.
if kind == KindFact && len(anchors) > 0 {
if err := checkFactAnchorAssets(tx, anchors); err != nil {
return 0, err
}
}
var id int64
if err := tx.QueryRow(`
INSERT INTO exploration_nodes(exploration_id, kind, payload, priority, state, origin)
@@ -245,6 +252,40 @@ VALUES ($1, $2, $3, $4, $5, $6) RETURNING id`,
return id, tx.Commit()
}
func checkFactAnchorAssets(tx *sql.Tx, ids []int64) error {
rows, err := tx.Query("SELECT id FROM assets WHERE id = ANY($1::bigint[]) ORDER BY id FOR KEY SHARE", ids)
if err != nil {
return err
}
found := make(map[int64]bool, len(ids))
for rows.Next() {
var id int64
if err := rows.Scan(&id); err != nil {
rows.Close()
return err
}
found[id] = true
}
err = rows.Err()
closeErr := rows.Close()
if err != nil {
return err
}
if closeErr != nil {
return closeErr
}
var missing []int64
for _, id := range ids {
if !found[id] {
missing = append(missing, id)
}
}
if len(missing) != 0 {
return fmt.Errorf("asset IDs do not exist: %v; use existing IDs or register the assets first", missing)
}
return nil
}
// AddIntent is a convenience: an open intent.
func (s *ExplorationStore) AddIntent(payload map[string]any, priority int, anchors []int64, origin string) (int64, error) {
if origin == "" {
+8 -1
View File
@@ -30,6 +30,7 @@ func TestRecordFactInputSchemaUpgrade(t *testing.T) {
t.Cleanup(func() { pg.UpdateTool(old.Key, old.Description, old.Schema, bindings, old.Enabled) })
legacy := map[string]any{
"type": "object", "required": []string{"summary"},
"anyOf": []any{map[string]any{"required": []string{"summary"}}},
"properties": map[string]any{
"summary": map[string]any{"type": "string", "description": "operator summary"},
"confidence": map[string]any{"type": "string", "default": "inferred"},
@@ -46,6 +47,12 @@ func TestRecordFactInputSchemaUpgrade(t *testing.T) {
if _, ok := schema["required"]; ok {
t.Fatal("top-level summary still required for batches")
}
if _, ok := schema["anyOf"]; ok {
t.Fatal("root anyOf still present")
}
if schema["additionalProperties"] != false {
t.Fatal("unknown fields allowed")
}
props := schema["properties"].(map[string]any)
items := props["facts"].(map[string]any)["items"].(map[string]any)
itemProps := items["properties"].(map[string]any)
@@ -53,7 +60,7 @@ func TestRecordFactInputSchemaUpgrade(t *testing.T) {
t.Fatal("repaired schema missing alias or batch summary")
}
if props["summary"].(map[string]any)["description"] != "operator summary" ||
props["confidence"].(map[string]any)["default"] != "inferred" || props["custom"] == nil {
props["confidence"].(map[string]any)["default"] != "inferred" || props["custom"] != nil {
t.Fatal("operator annotations lost")
}
if err := actool.ValidateInput(schema, json.RawMessage(`{"facts":[{"summary":"complete batch item"}]}`)); err != nil {