Score memory state without sending memory content.

What it does

The zero-knowledge variant of POST /v1/preflight accepts a commitment hash and a small set of public metadata fields (memory entry types, ages, source-trust scores, hop counts) instead of the underlying memory content. The scoring engine runs over the public fields and the commitment; the engine never sees the entry text, the user prompt, or any tool output.

The response includes a zk_proof object containing a proof hash, a validity flag, a proof-type tag, and a verifiable_without_content flag. The same response shape that /v1/preflight returns (decision band, omega risk score, attack-surface composite, detection-layer states) is preserved.

The four-band decision contract is unchanged: USE_MEMORY / WARN / ASK_USER / BLOCK. Content-dependent detections that require text inspection are surfaced as insufficient_signal rather than silently downgrading the score.

When to use

Use the zero-knowledge endpoint when contractual or regulatory constraints prohibit sending memory content off-host. Common contexts:

• GDPR data-minimization. When the lawful basis for processing does not extend to a third-party preflight scorer, the commitment-only flow keeps personal data inside your boundary.
• HIPAA covered-entity workloads. When PHI may appear in memory entries and your Business Associate Agreement does not cover the preflight scorer.
• Data-residency requirements. When customer contracts require all content to remain in a specific jurisdiction.
• Internal trade-secret protection. When memory entries may include proprietary code, prompts, or business logic that should not be transmitted.

If none of the above apply, the standard POST /v1/preflight endpoint is recommended — it exercises every content-dependent detection and produces a fuller risk picture.

Request

The request body mirrors POST /v1/preflight with two differences: each memory_state entry carries a content_hash field (SHA-256 over the local content) in place of the content string, and the request carries a top-level zk_commitment field summarizing the entry set.

curl -sS https://api.sgraal.com/v1/preflight/zk \
  -H "Authorization: Bearer $SGRAAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

request.json:

{
  "tenant_id": "acme-prod",
  "agent_id": "support-bot-7",
  "action_type": "reversible",
  "domain": "customer_support",
  "zk_commitment": "sha256:6f3c...e1ab",
  "memory_state": [
    {
      "id": "m1",
      "type": "tool_state",
      "age_seconds": 42,
      "source_trust": 0.91,
      "hop_count": 1,
      "content_hash": "sha256:9b8d...77c2"
    },
    {
      "id": "m2",
      "type": "identity",
      "age_seconds": 86400,
      "source_trust": 0.97,
      "hop_count": 0,
      "content_hash": "sha256:42af...10de"
    }
  ]
}

Required public fields per entry: id, type, age_seconds, source_trust, hop_count, content_hash. Optional public fields (when available without revealing content): provenance_chain_length, distinct_sources, corroboration_count. The content field, if present, is rejected with 422.

Response

The response uses the same decision contract as the standard endpoint, with a zk_proof object appended and content-dependent fields set to null or "insufficient_signal".

{
  "recommended_action": "USE_MEMORY",
  "omega_mem": 18.4,
  "attack_surface_score": 0.06,
  "decision_zone": "safe",
  "detection_layers": {
    "timestamp_integrity": "PASS",
    "identity_drift": "PASS",
    "consensus_collapse": "PASS",
    "provenance_chain": "PASS",
    "sync_bleed": "PASS",
    "confidence_calibration": "insufficient_signal"
  },
  "zk_commitment": "sha256:6f3c...e1ab",
  "zk_proof": {
    "proof_hash": "sha256:8a21...4f7c",
    "proof_valid": true,
    "proof_type": "zk_sheaf_v1",
    "verifiable_without_content": true
  }
}

The recommended_action, omega_mem, attack_surface_score, and decision_zone fields carry the same semantics as the standard endpoint. The zk_proof object is verifiable client-side against the original commitment without re-transmitting content. See API reference for the standard endpoint contract.

What this does not replace