📐 Spec

Spec-14-Batch-Assert

2 min readSpec contributor · SDK authorDraft · future hardened-core line

What this spec defines

The batch assertion operation targeted for a future hardened-core line. Lets a caller submit multiple fact assertions in one request while retaining fact-model validation, hook execution, auditability, and predictable failure behavior.

Extraction status

This file contains the ADR-010 prose extraction for ADR-006 batch assert semantics. Batch assert is not part of the v0.9.0a1 stable surface.

Purpose

Batch assert lets a caller submit multiple fact assertions in one request while retaining fact-model validation, hook execution, auditability, and predictable failure behavior.

Request shape

BatchAssertRequest {
  facts:          AssertRequest[]
  atomic:         boolean
  idempotency_key: string?
}

Each item in facts follows the single-fact assertion contract from Spec-01-Fact-Model and Spec-03-HTTP-API.

Atomicity modes

Mode

Semantics

Failure behavior

atomic: true

all-or-nothing

Node MUST commit all facts or none. Validation failure, authorization failure, hook denial, or storage failure for any item MUST abort the entire batch.

atomic: false

per-fact

Node MAY persist successful items and report failures per item.

Idempotency

Retrying with the same idempotency key MUST NOT duplicate persisted facts.

When an idempotency_key is supplied, retrying the same request with the same key SHOULD return the same logical result. Implementations MUST reject reuse of the same idempotency key for a different request body.

Hook and audit semantics

Batch assert MUST preserve the behavior of single-fact assertion hooks. Hooks may run per fact, per batch, or both, but the externally visible result MUST match the configured atomicity. Audit events SHOULD identify the batch and the per-fact outcomes.

Response shape

BatchAssertResponse {
  accepted: integer
  rejected: integer
  results:  BatchAssertItemResult[]
}

BatchAssertItemResult {
  index:   integer
  status:  "accepted" | "rejected"
  fact_id: string?
  error:   string?
}

Out of scope

This spec does not define bulk import tooling, streaming ingestion, or cross-node batch replication.