Compare documents
POST /v1/brains/{handle}/corpus-analyses reads documents you select, discovers
the propositions they share, or compares a target with selected
references. Creating one answers 202 and runs in the background; poll
GET /corpus-analyses/{id} until status is complete or incomplete.
curl -X POST "$API/v1/brains/tenant:acme/corpus-analyses" \ -H "authorization: Bearer $NICIA_KEY" \ -H "idempotency-key: compare-1" \ -H "content-type: application/json" \ -d '{ "documents": [ { "source": "@record", "id": "rule-discount-cap", "role": "reference" }, { "source": "@observed", "id": "0192a3b4-c5d6-7e8f-9012-3456789abcde", "role": "target" } ], "targetComplete": true }'What can be compared
Section titled “What can be compared”source |
Names | Roles |
|---|---|---|
| a source name | a document the Brain serves, by id |
reference, target, corpus |
@record |
a native record page (a rule, a decision), by its slug | reference, target, corpus |
@observed |
an observed output, by its id | target only |
@observed as a reference or a corpus is a 400 with error.details.reason
observed_output_target_only: an output is evidence about behaviour, never a
standard to hold others to. An analysis compares one output at a time
(observed_output_single). You must be able to read the output, or the answer is
the 404 a missing one gets. The run pins the output by its id and content hash
and never copies its text into the analysis.
Adopting is refused. POST /corpus-analyses/{id}/adopt on an analysis whose
target is an output is a 409 (observed_output_not_adoptable), and none of its
statements is offered as adoptable. An output is never a source of knowledge.
Approved exceptions
Section titled “Approved exceptions”When a reference is a @record, the rules that are an exception_to it are read
beside it. Only a rule that is accepted and current counts (not one still
waiting in Review, withdrawn or replaced). They appear in the analysis’s
documents with exceptionTo naming the reference, and the reference’s own entry
reports what was found:
{ "id": "rule-discount-cap", "role": "reference", "exceptions": { "included": 1, "truncated": false } }A draft that follows an approved exception for the scope it states is not
reported as changes. At most 10 exceptions are read per reference, and within
the analysis’s 50-document and 500 KB bounds; when a bound cuts the list,
truncated is true and the comparison says so rather than reading as complete.
An exception added after the analysis ran does not make it stale: re-run it.
Who can read an analysis
Section titled “Who can read an analysis”A Brain key sees the analyses that key created. An analysis over an
observed output is also read by any key that holds review, and by a person
whose role may review now, because reviewing is how a finding gets confirmed and
the reviewer is rarely the one who ran the comparison. A key that holds only
read or write still sees none of them, and an analysis that reads no output
stays private to the key that created it.
Confirm a failure
Section titled “Confirm a failure”A reviewer who agrees a finding is a real failure confirms it:
POST /corpus-analyses/{id}/confirmed (needs review):
{ "fingerprint": "<the analysis result's fingerprint>", "findingFingerprint": "<the finding's fingerprint>", "correction": "Discounts above the cap need an approved exception on file.", "expectedRecordIds": ["rule-discount-cap"], "allowedExceptionRecordId": "rule-acme-exception"}The finding must be a supported changes or omits of an analysis whose target
is an observed output. The records you name must be ones the analysis read: the
expected references, and an exception read beside them. The answer is the
analysis, with the case in cases. Retry with the same Idempotency-Key to get
the same case; confirming the same finding again is a 409 (case_exists).
A confirmed case:
- keeps the output past its retention, so the failure can be replayed. While
the case stands the output cannot be deleted (
409, reasonobserved_output_kept_by_case); withdraw the case first. - is listed with
GET /corpus-analyses?confirmed=true. - opens no Review item and changes no knowledge.
- marks a repeat: a finding in a later analysis, over a different observed
output, that fails the same reference proposition carries
recurrenceOf: <case id>.
Withdraw a case
Section titled “Withdraw a case”A case that was wrong, or whose output holds customer data you now need to delete,
is withdrawn by a reviewer: POST /corpus-analyses/{id}/withdrawn (needs review)
with the finding’s fingerprint.
{ "findingFingerprint": "<the finding's fingerprint>" }The answer is the analysis, with the case still listed in cases and marked
withdrawnAt. Withdrawing does not delete anything. It stops the case keeping its
output, which returns to its normal retention, so deleting it with
DELETE /observed-outputs/{id} now works and clears its text; and it stops the
case marking later findings with recurrenceOf, and removes it from
GET /corpus-analyses?confirmed=true. If another standing case names the same
output, that case keeps it instead. It is idempotent, and the finding may be
confirmed again afterwards. A key without review is refused (403); a finding
no case holds is a 404.
How a repeat is recognised
Section titled “How a repeat is recognised”By a fingerprint of the reference side only: the normalized text, applicability, scope, conditions, value and terms of the proposition the output failed. It ignores the target’s text, and the record’s id, version and the quote offsets, so the same rule read from a newer version of its record still matches. It is exact: when the owner rewrites the rule it is a different proposition, and a case confirmed against the old wording does not mark a failure of the new one; a model that rewords the proposition between runs misses a repeat. It never marks a repeat that is not one. Only the newest 200 cases of a Brain are matched.
The regression signal needs no model
Section titled “The regression signal needs no model”Confirming a case does not enroll anything. To be told when what the case rested
on moves, enroll a watch on the receipt behind it:
GET /observed-outputs/{id} names it as output.receiptId, and
POST /watches with { "question": { "kind": "receipt", "receiptId": "…" } }
delivers answer.changed when anything that read served changes. Re-running the
agent and grading it stay yours.