SeenRelay

Cost preflight before repeated paid or slow source-backed validation, especially across an agent fleet. Use before paid web search, metered scraping, browser/extraction, rate-limited APIs or multi-step validation when the caller already has a known value. Returns SAME_OBSERVED, CHANGED_OBSERVED, CONTESTED, STALE or UNKNOWN. Only SAME_OBSERVED can be considered for caller-policy-gated reuse; every other status requires normal authoritative validation before OBSERVE. SeenRelay never browses or verifies externally.

{
  "type": "object",
  "properties": {
    "fact": {
      "type": "object",
      "properties": {
        "subject": {
          "type": "string",
          "minLength": 1,
          "maxLength": 256,
          "description": "Human-readable label; excluded from canonical fact identity."
        },
        "predicate": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "description": "Stable shared machine identifier; identity-bearing only when locator is absent."
        },
        "qualifiers": {
          "description": "Identity-bearing semantic qualifiers. Include only fields needed to distinguish otherwise identical source-backed facts.",
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        },
        "source": {
          "type": "string",
          "maxLength": 2048,
          "format": "uri",
          "description": "Stable credential-free absolute HTTP(S) source URL. Tracking parameters are removed; authentication or signature query parameters are rejected."
        },
        "locator": {
          "description": "Stable source-native locator. Prefer this when the source exposes one.",
          "type": "object",
          "properties": {
            "scheme": {
              "type": "string",
              "enum": [
                "json_pointer",
                "element_id",
                "source_key"
              ],
              "description": "Source-native locator type: RFC 6901-style JSON pointer, stable HTML element id, or stable source-native key."
            },
            "value": {
              "type": "string",
              "minLength": 1,
              "maxLength": 1024,
              "description": "Source-native locator value. json_pointer values must begin with /; locator bytes are otherwise preserved."
            }
          },
          "required": [
            "scheme",
            "value"
          ]
        }
      },
      "required": [
        "subject",
        "predicate",
        "source"
      ],
      "description": "Source-backed fact coordinate whose recent shared evidence should be checked."
    },
    "known_value": {
      "description": "Caller-known value to compare with recent observations. Mutable observed content is excluded from fact identity.",
      "$ref": "#/$defs/__schema0"
    },
    "max_age_seconds": {
      "description": "Maximum age, in seconds, of shared observations the caller is willing to consider. Omit to use the service default.",
      "type": "integer",
      "minimum": 1,
      "maximum": 604800
    }
  },
  "required": [
    "fact",
    "known_value"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "__schema0": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/__schema0"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        }
      ]
    }
  }
}

{
  "type": "object",
  "properties": {
    "status": {
      "description": "Decision status when CHECK succeeds. Only SAME_OBSERVED can be considered for reuse, and only under caller policy. CHANGED_OBSERVED, CONTESTED, STALE and UNKNOWN require normal authoritative validation before any OBSERVE.",
      "type": "string",
      "enum": [
        "SAME_OBSERVED",
        "CHANGED_OBSERVED",
        "CONTESTED",
        "STALE",
        "UNKNOWN"
      ]
    },
    "fact_key": {
      "description": "Canonical SeenRelay fact identity for this coordinate.",
      "type": "string"
    },
    "next_step": {
      "description": "Explicit cold/stale-path instruction: validate the authoritative source normally, then OBSERVE the independently obtained result.",
      "type": "string",
      "const": "VALIDATE_THEN_OBSERVE"
    },
    "error": {
      "description": "Present instead of a decision status when CHECK cannot be admitted or is controlled.",
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable service/admission error code."
        },
        "detail": {
          "type": "string",
          "description": "Human-readable error detail. A tool error is not evidence that the source value is unchanged."
        }
      },
      "required": [
        "code",
        "detail"
      ],
      "additionalProperties": {}
    },
    "hive": {
      "description": "Current bounded Hive admission/lease state.",
      "$ref": "#/$defs/__schema0"
    },
    "useful_reuse_awards": {
      "description": "Qualified reuse awards attributable to this CHECK under SeenRelay telemetry rules; not a truth or independence score.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": {},
  "description": "CHECK result. Exactly one of a decision status or an error is expected; additional evidence fields may be present.",
  "$defs": {
    "__schema0": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/__schema0"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        }
      ]
    }
  }
}

After independently performing a source-backed validation, deposit the observed result for later CHECKs. Returns accepted=true when a new observation is stored or deduplicated=true for a recognized retry/recent duplicate. Never OBSERVE hearsay. Optional Ed25519 proof establishes key possession and continuity, not truth or real-world independence.

{
  "type": "object",
  "properties": {
    "fact": {
      "type": "object",
      "properties": {
        "subject": {
          "type": "string",
          "minLength": 1,
          "maxLength": 256,
          "description": "Human-readable label; excluded from canonical fact identity."
        },
        "predicate": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "description": "Stable shared machine identifier; identity-bearing only when locator is absent."
        },
        "qualifiers": {
          "description": "Identity-bearing semantic qualifiers. Include only fields needed to distinguish otherwise identical source-backed facts.",
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        },
        "source": {
          "type": "string",
          "maxLength": 2048,
          "format": "uri",
          "description": "Stable credential-free absolute HTTP(S) source URL. Tracking parameters are removed; authentication or signature query parameters are rejected."
        },
        "locator": {
          "description": "Stable source-native locator. Prefer this when the source exposes one.",
          "type": "object",
          "properties": {
            "scheme": {
              "type": "string",
              "enum": [
                "json_pointer",
                "element_id",
                "source_key"
              ],
              "description": "Source-native locator type: RFC 6901-style JSON pointer, stable HTML element id, or stable source-native key."
            },
            "value": {
              "type": "string",
              "minLength": 1,
              "maxLength": 1024,
              "description": "Source-native locator value. json_pointer values must begin with /; locator bytes are otherwise preserved."
            }
          },
          "required": [
            "scheme",
            "value"
          ]
        }
      },
      "required": [
        "subject",
        "predicate",
        "source"
      ],
      "description": "Source-backed fact coordinate for the independently obtained observation."
    },
    "value": {
      "description": "Value independently obtained by the caller. Mutable observed content is excluded from fact identity.",
      "$ref": "#/$defs/__schema0"
    },
    "observed_at": {
      "description": "ISO-8601 time when the caller obtained the observation. Omit to use server receipt time.",
      "type": "string"
    },
    "observer_id": {
      "description": "Optional self-asserted continuity label. It is unverified unless accompanied by observer_proof.",
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "observer_proof": {
      "description": "Optional Ed25519 proof of key possession, continuity and payload integrity; not proof of truth or real-world independence.",
      "type": "object",
      "properties": {
        "scheme": {
          "type": "string",
          "const": "ed25519-v1",
          "description": "Observer proof contract version."
        },
        "public_key": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "description": "Raw 32-byte Ed25519 public key encoded as unpadded base64url."
        },
        "timestamp": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64,
          "description": "ISO-8601 signing time; it must fall within the configured proof-skew window."
        },
        "nonce": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "description": "16..64 random bytes encoded as unpadded base64url."
        },
        "signature": {
          "type": "string",
          "minLength": 1,
          "maxLength": 256,
          "description": "Raw 64-byte Ed25519 signature encoded as unpadded base64url."
        }
      },
      "required": [
        "scheme",
        "public_key",
        "timestamp",
        "nonce",
        "signature"
      ]
    },
    "evidence_fingerprint": {
      "description": "Optional caller-supplied fingerprint of the independently obtained evidence. SeenRelay stores it as provenance metadata and does not verify it against the source.",
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    },
    "source_validator": {
      "description": "Optional source-validator metadata from the independent validation. The caller decides whether a returned hint is sufficient for source confirmation.",
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "etag",
            "last_modified",
            "content_hash",
            "other"
          ],
          "description": "Type of observer-supplied source-validator metadata."
        },
        "value": {
          "type": "string",
          "minLength": 1,
          "maxLength": 512,
          "pattern": "^[^\\r\\n]+$",
          "description": "Observer-supplied validator value. Stored and returned only as a hint; SeenRelay does not verify it against the source."
        }
      },
      "required": [
        "kind",
        "value"
      ]
    },
    "idempotency_key": {
      "description": "Caller-chosen retry key for the same OBSERVE operation. Reusing it deduplicates an idempotent retry.",
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    }
  },
  "required": [
    "fact",
    "value"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "__schema0": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/__schema0"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        }
      ]
    }
  }
}

{
  "type": "object",
  "properties": {
    "accepted": {
      "description": "True when a new independently obtained observation was stored. Omitted when OBSERVE cannot be admitted.",
      "type": "boolean"
    },
    "deduplicated": {
      "description": "True when an idempotent/recent duplicate was recognized and no new observation row was needed.",
      "type": "boolean"
    },
    "fact_key": {
      "description": "Canonical SeenRelay fact identity for this coordinate.",
      "type": "string"
    },
    "future_check_eligible": {
      "description": "Whether the accepted or deduplicated observation is eligible to support later CHECKs under normal freshness rules.",
      "type": "boolean"
    },
    "reason": {
      "description": "Deduplication reason when accepted=false and deduplicated=true.",
      "type": "string"
    },
    "error": {
      "description": "Present when OBSERVE cannot be admitted or is controlled. This is not a statement about source truth.",
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable service/admission error code."
        },
        "detail": {
          "type": "string",
          "description": "Human-readable error detail. A tool error is not evidence that the source value is unchanged."
        }
      },
      "required": [
        "code",
        "detail"
      ],
      "additionalProperties": {}
    },
    "hive": {
      "description": "Current bounded Hive admission/lease state.",
      "$ref": "#/$defs/__schema0"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": {},
  "description": "OBSERVE result. accepted=true means a new observation was stored; deduplicated=true means the retry/recent duplicate was recognized.",
  "$defs": {
    "__schema0": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/__schema0"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        }
      ]
    }
  }
}