* fix(environment): keep read-only POSTs out of the write list A POST that repeats the latest read of its path, tunnels only read operations, names a lookup in its path's last meaningful word, or renews a session no longer counts as a state write: it is replayed, does not cut initial windows, and does not end observation searches. A tool stays a write when a related read line changes across one of its calls. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(environment): take an entity an unplanned write made when a read first shows it A successful item read of an entity the gate's copy never held, after a write no built plan models, puts the entity into the copy instead of failing the read, so later writes to it are checked as usual. An entity a modelled write touched is never taken back. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(environment): plan a create into the type its returned id is read under A POST whose path names no state type becomes a create into the type whose item read first names an id its response returned, when the id is new to the state; serving creates in that read's collection. A successful POST that returned an id a type's reads only show after it also ends that type's initial window, so entities a capture created stay out of the initial state. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(environment): end a type's initial reads at the write its reads disagree across When a type's reads disagree across a write under another root, the type's initial window now ends at the earliest write within that change and the state is extracted again, instead of leaving every view of the type replayed. The cut composes with the creation cut; the earlier wins. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(environment): replay request lines that show entities in another form A read line that shows the same entities in another form, by an extra query parameter that adds or drops members, or conflicts with a base line on a shared entity, is a variant: it leaves the view's checks and the entity observations, the view names it with the query keys that pick it out, and a call matching those keys replays its recording. A filter role whose name matches no field needs two agreeing values. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(environment): specify and record the state-target changes Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(environment): keep a read-only POST a write when its evidence is incomplete Body-level container operations are skipped like query ones, a lookup is named only by the path's last literal segment and never alongside a write word, a tool with a redirected or unanswered call is not reclassified, and the mutation veto is resolved over all candidates at once so another read-only call cannot explain a read change. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(environment): answer a field selection only when the state shows it exactly Serving tests a field selection before any variant key: a projection value a replayed read gave, or one no checked line gave other than `*`, replays. A list sets aside a line asking for some fields only before the identity proof, and a dropped variant's membership change no longer rewrites the type. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(environment): hold adopted entities and linked creates to what the recording shows An adopted entity is charged against the view's budget like a created one. A linked create holds only for its exemplar's path arguments: serving refuses others and the gate counts such a call as unmodelled. A response's identity-named id links at any length, but a short one only to a type read before the call. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(environment): record the review fixes' measurements Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(environment): release a discarded planning pass before planning again A rewrite cut clears the first pass, so the budget rewinds to a checkpoint taken after the write cutoffs and created ids before the state is extracted again. Rewrite spans are charged and appended without spreading them into an argument list. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(environment): link no create whose id an earlier read showed, and read only whole batches A linked create is rejected when an earlier list of its type or read of its collection showed the returned id. Body ids are walked without spreading children into an argument list. An RPC call reads only when every operations entry names an operation of its own. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(environment): let the gate skip exactly the reads serving replays Serving's replay decision moves to the domain as replayReason, and the write gate uses it: a read serving replays can neither approve nor veto a write, and a read of every field beside a replayed selection is checked. A selection read missing a required field is still skipped, since part of an entity can neither confirm nor check it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(environment): record the second review round's checks Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(environment): read writes, links and creation cuts only from evidence that rules out other causes - A read-only POST repeats only a read that finished before it began; the veto compares the latest read finished before a call with the first begun after it, and counts a recorded absence on one side as a change. `modify` and `replace` are write words. - A redirected or unanswered write lets a later item read adopt the entity it may have made. - A creation cut counts a read still running when the POST began as after it, and a list read shows its listed entities' own ids, not those they nest. - A linked create's item read must come before any other tool's write. - Line shapes are charged to the budget as they are built. - A `fields=*` list line is whole, not a field selection. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(environment): record the third review round's checks Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(environment): tie linked creates to their returned ids and order state by the lines left - A linked create is observed only in a read of an id its response returned, envelopes included, and serving takes its recorded path values in either spelling. - A list read shows a suffix-named identity (`projectId`) distinct across its entities. - A read-only POST compares the read that finished last before it began. - An entity's first sighting comes from the lines left after variant lines are dropped. - The pairwise variant pass stops at a work limit, leaving every line checked. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(environment): record the fourth review round's checks Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(environment): keep foreign keys, stale reads and double decoding out of write evidence - A list read counts a suffix-named field as its entities' ids only when no id-named field identifies them, so an `ownerId` beside `id` cuts no window. - A read-only POST is compared with the read that finished last among those no other write follows, so a consuming call stays a write. - A linked create's source path values compare as spelled on both sides, so no spelling is decoded twice. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(environment): record the fifth review round's checks Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(environment): compare linked sources by position, decode path fields once and bound read and variant scans - A linked create's source values compare segment by segment, so a template naming two parameters alike cannot accept a changed first one. - Serving fills a linked create's path fields with its arguments decoded once, as the gate learned them. - The read-only check reads each related line's records once per call, between the nearest other writes. - Member signatures are JSON arrays, so a name holding the separator still conflicts; the variant work limit counts line pairs as well as entities. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(environment): record the sixth review round's checks Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(environment): replay late and variant-only items, fill linked path fields from the exemplar and charge membership spans - An item line first recorded after the initial window that names a new shaping parameter and shows other members is a replayed variant, like an initial one. - An item only a replayed line showed, which the state never started with, answers with its own recording; one the state held and lost stays missing. - A linked create fills its path fields from its exemplar's path decoded once, whichever accepted spelling the call sends. - Each membership change span is charged against the budget before it is kept. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(environment): record the seventh review round's checks Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(environment): decide late item lines against the lines left, charge replay keys and bisect rewrite cuts - Item lines first recorded after the initial reads are decided once variants are dropped, against the lines left: a new shaping parameter showing other members, or a selection of some fields leaving members out, replays. - Each replay key is charged against the budget before it is kept. - A rewrite span's earliest write is found by bisection over the writes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(environment): record the eighth review round's checks Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(environment): count only reads finished before a linked create began as showing its id held A list still running when the call began may show what the call made, as the creation cut already decides, so it no longer refuses the link. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(environment): keep served creates' items missing, check same-type earlier reads, and bound late lines and read-only stretches - An item only a replayed line showed replays only while no served create has added to its type, so a created and deleted item stays missing. - A linked create's earlier item-read veto checks only reads of the candidate's type or collection that show the item, so another type's id does not hide it. - An item read answered with JSON null shows no id to a creation cut. - Late lines' member names are charged before they are kept. - The read-only check precomputes nearest writes and passes once over each write-free stretch per path, skipping lines whose reads all agree. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(environment): record the ninth review round's checks Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(environment): link creates past empty item reads, sweep repeated reads once and keep only returned ids for creation cuts - A linked create passes over a later item read naming its id whose body shows no item, such as JSON null, and links the next one. - Read-only repeated reads are found in one sweep: each path's reads wait by end time until a call's start passes them, and a write clears them. - A creation cut keeps, and charges, only the shown ids some creation returned. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(environment): record the tenth review round's checks Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * perf(environment): compare variant lines through shared entities and parse each compared body once The variant pass indexes a tool's lines by the entities they show and compares only lines that share one, charging the index to the budget while it is held; the pairwise work limit still decides when a tool keeps every line checked. Read-only decisions keep each response body's canonical digest, taken once while its parse is charged, across calls and veto passes. The creation cut no longer parses reads at or after the write that ends the initial reads, and reads the ids a body shows inside its lease. Adoption looks up a read's target only after an unplanned write before it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(environment): record the eleventh review round's checks Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * perf(environment): list a type's collections only when the path's own holds no id, and parse variant base lines once The write gate's item target lists the type's held collections, and the removed targets', only when the path's own collection holds none of its ids, so a served item view's reads no longer walk every entity of the type. The variant pass parses the base lines' queries once for all the variants they key, and not at all when it found none. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(environment): record the twelfth review round's checks and the sweep's cost Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com>
31 KiB
Apply write effects to the served state
Issue: https://github.com/morluto/rea/issues/4933
Outcome
An environment served from its state also serves the write tools whose effects the capture itself confirms:
- a create adds an entity;
- an update changes the fields the call sends;
- a delete removes the entity;
- a document write changes a document.
Later reads, list membership and data/get show the change, and data/reset
undoes it.
The environment-state view decides which write tools are served. It replays
the capture's own timeline on the extracted initial state: each recorded write
applies its modelled effect, and each later read that the state answers is
rendered and compared with the recorded response. A write tool is served only
when at least one later read reproduces after its effect and none contradicts
it. Every other write tool stays unserved, listed with the reason.
Values the application generates are deterministic: identities, sequences and clock values follow the formats the capture recorded, so the same calls after a reset give the same state.
Write plans
The view adds two members to its result:
writes: one plan per manifest tool whose method may change state (changesState), less thePOSTtools the capture shows only reading (below);write_clock: the instant the served clock starts from.
Calls that only read. A POST tool whose calls read state is no write: it
gets no plan, stays a recorded view with the reason query-body, is served by
replay, and its calls bound no initial-recording window and end no observation
search. The capture shows it by the first of these that applies:
- every successful call answers as the successful
GETof its path that finished last before the call began, of those with no write between, did (a status lookup posting the jobs it names); - every call names read operations only, in its body's
operationoroperations[].operation, else its query'soperation,oporaction(batchand similar only wrap them, in either place, so a call needs at least one other, and everyoperationsentry must name one of its own, so an entry with no string operation or another container keeps the call a write); an operation reads when its words name one oflist,get,count,aggregate,info,search,find,read,query,schema,describe,fetchorlookup, and none ofcreate,insert,update,modify,replace,delete,remove,upsert,add,set,saveand similar, sofindAndModifyandfindOneAndReplacestay writes; - the path's last literal segment has a query word as its last meaningful
word, split on
_,-,.and case and skipping trailingdata,infoandresults(search,query,list,find,lookup,count,aggregate,stats,ids,selection,discover, …), and no write word:selection_datanames a lookup, whilequery-historynames a history,create_lookupa create andselection_data/importan import, and each stays a write; - the path's last literal segment renews or opens a session:
auth-refresh,auth-with-password,login,logout,refreshortoken.
A tool stays a write when one of its calls was redirected or went unanswered,
since nothing shows what it did. It also stays a write when a GET line whose
path its call's path relates to (segment by segment, a parameter matching any
value) reads differently just before and just after one of its calls, or finds
its entity on one side only (a 400, 404 or 410 on the other), with no other
write between; the other read-only tools' calls are no writes there, so the
tools are dropped until none is vetoed. Those reads are the one that finished
last before the call began, of those no other write follows, and the first that
began after it ended, since one overlapping the call may show either state. Reads of unrelated paths do not
count, so a session renewal stays read-only although an endpoint under the
same root regenerates values on every read.
Effects. Each plan classifies its tool:
| Effect | Tool | Target |
|---|---|---|
create |
POST to a state type's collection_template |
an entity of that type |
update |
PUT, PATCH or POST to that template plus one trailing parameter |
the entity the path names |
delete |
DELETE to that same item template |
the entity the path names |
document |
PUT, PATCH or POST to a document view's path |
that document |
none |
anything else | reason no-state-target |
A POST whose path gives it no target is a create into the type its returned
id is read under: its exemplar's response names an id (an identity member of the
body or of an object member, or a scalar body or sole member of four characters
or more), and the first later successful item read naming that id, whose body
shows the item (a JSON null read is passed over), belongs to a state type. That read must come before any other tool's write, which may have
made what it shows, as a publish call makes a note from a draft. The entity must
be new: neither the initial state nor any read finished before the call began
holds that id (one still running may show what the call made): an item read of
it under the item read's type or collection whose body shows the item (a JSON
null is an absence), a list read of its type, or any read of that collection, whether an
item read of it, a list read of its type, or any read of the item read's
collection, with or without a query, that lists it under an identity member of
its own (a body with no list counts an identity member at any depth). An id shorter than four characters may be any type's,
so it links only to a type a successful read showed before the call. The plan
records that read's collection, and serving creates there, since the call's own
path names no collection of the type. That collection holds only for the
exemplar's path arguments, compared segment by segment, each as recorded or in
the other spelling once percent-decoded: serving refuses a call with others, and the gate counts such a
recorded call as a write no built plan models. Its path fields take the
exemplar's path values decoded once, the source it accepts, whichever spelling
the call sends. A linked create's call is
observed only in a read of an id its response returned, at the top or in an
envelope member, so another unseen item's read is never taken for it.
Exemplar. A plan is built from its first successful (2xx) recorded call, the exemplar.
- Request body. The exemplar's request body must be a JSON object that
could enter the state: a JSON-like media type, complete UTF-8 text within
256 KiB, exact numbers, no
__proto__member. Otherwise the reason isbody-unusable. ADELETEtakes no body. - The written entity. The entity is observed in the exemplar's response,
located by its identity value at the root, in one member, or in a
one-element array, as item views locate it. When the response does not carry
it, the entity is observed in the first later read that shows it: an item
read of that entity, or for a create, the one entity a collection read newly
lists. A create whose response names its id alone (a scalar, the identity
field, or one member) is observed only through a read of that id. With
neither, the reason is
no-observation.
Field rules for creates. Each field of the observed entity gets the first rule that explains its value. Rules that read the call come first, so an identity the client sends is an echo:
- Echo. A body member of the same name with an equal value.
- Copy. A body string of 8 or more characters, found at a JSON pointer of the body (the shallowest match).
- Path. The value of a path parameter of the call, percent-decoded. Serving decodes it from the collection the call names, whichever spelling the call uses, and the gate fills a recorded call's path fields from that collection too.
- Slug. The slug of a body string member: lower case, runs of other
characters joined by
-. - Identity. The type's
id_fieldis generated. A sequence when it is an integer (or a string of digits); otherwise a UUID when it has the8-4-4-4-12hex shape; otherwise a token of the same length and character classes. - Clock. A timestamp within 10 minutes of the exemplar's start time. The format is kept: ISO-8601 with its separator, fraction digits and zone, or epoch seconds or milliseconds.
- Sequence. An integer one greater than the largest value of the field in
the collection, else in the type. The integer may be written as
--separated digit groups of one width of at least two digits (an asset number000-005; not a date, version or address); a served value keeps the recorded value's groups and zero padding, and digits that outgrow them lead. A later call must record the value spelled that way. - Unique. A UUID-shaped string that no other entity of the type shares.
- Template. A string containing a generated value, or else a copied value, as a delimited token (for example a URL that ends in the new id or in a slug the call sent under another name). It is rebuilt around the new value. An echoed value is not a token, nor is a copy of one: it may recur in unrelated text. A copied member whose value also sits in text no template rebuilds around it (beside another source in one template, or in a constant) is accepted only with its recorded value.
- Constant. Otherwise the exemplar's value.
When a constant, or the text a template keeps, contains a path value of the exemplar's call as a delimited token, the create is served only for calls naming the exemplar's collection.
Body members of a create. A member is either accepted or not:
- Accepted. An echoed member, a member copied whole into a field of another name and stored under none of its own, or the identity field's value. A member copied whole must have the JSON type of the field it is copied into. Every member the exemplar sent is required.
- Not accepted. A member the application stored with a different value (transformed), or one it did not show. A call that sends such a member is a tool error naming the accepted members.
Updates. Body members follow the same accepted and not-accepted rules,
except that a member the application stored differently is accepted only with
the value a recorded call sent it with, and then stores the value that call
recorded (its constant rule carries it). The type's identity field never
takes a rule: sent as the path's id it is the identity member, sent as another
value the application ignored it is accepted with that value and stores
nothing, and a stored id that changed is unexplained-change. A plan whose
calls use a member both as the identity and as a fixed member, or fix it at
different values, is unexplained-change, as serving could not take every
recorded call. So is an update a later read shows dropped a field the
entity held, since serving keeps every field an update does not write; a write's
own response may leave fields out. A member the application replaced
with a fresh UUID (unique, below) is accepted with any value; a UUID stored
as sent in another letter case is the sent value, not a fresh one. A member a later call is the first to store,
which the plan's observation does not show, keeps the JSON type that call stored
it as (the body's kinds), as an exemplar's member keeps the observation's.
PUT requires every member the exemplar sent; PATCH and POST require at
least one. A field the exemplar's update changed without sending it is
explained as one of:
- clock;
- an increment by one;
- a slug of an echoed member;
unique: a UUID in place of another UUID, that no other entity of the type holds and the call sent nowhere in its body (a version the application assigns on every update);renewed: an array or object whose only changes are UUIDs replaced by ones that neither it nor another entity of the type held, as child rows an update rewrites are. The rule names the pointers it renewed at (*for any array index): every UUID at them is new, each old UUID by a single new one, and UUIDs elsewhere, such as a row's references, are kept. One call renews a UUID alike in every field and in either letter case, and never two old UUIDs into one new one.
A field the entity lacked before is a change too when the view that observed
the update had shown the entity, so a field the application fills in on update
follows its rule. Any other change is unexplained-change. An increment or a slug applies to
every call that could take it, and unique and renewed to every call, so the
plan is also unexplained-change when such a rule would give a call of the
tool another value than the one it recorded, a recorded call kept a unique or
renewed field, or a later call treats a member otherwise than the plan: one
call echoes it and another stores something else, or the two rule it
differently.
Deletes. A delete removes the entity. Its response is the exemplar's response, with the entity re-rendered when the response carries it.
Documents. A document write merges the body's members (replaces them, for
PUT) into the document object that holds most of them: the root or one
member. Later calls write at the exemplar's object. Document reads answer only on their recorded line, so a write is
served only at the path the state holds the document at, each segment verbatim
or either spelling once percent-decoded, and the gate treats a recorded write
at another path as an unmodelled write. A recorded write whose
body serving would refuse (a member of another JSON type than the document
holds) is unexplained-change.
Responses. A write answers with the status and content type of one recorded response:
| Response | Body |
|---|---|
entity |
the written entity, rendered into the recorded envelope at the plan's pointer through the recorded fields |
identity |
the recorded body with the new identity at the plan's pointer |
empty |
no body |
recorded |
the recorded body |
A rendered body missing a field the recorded response carried is a tool error, and the state is left unchanged.
List position. A create's insert rule places the new entity in its
collection's order: sorted by the identity field or a clock field (ascending
or descending), first or last. The rule is the first candidate consistent
with both the initial all-membership recordings and the position a later
recorded list shows. With no evidence, the rule is last.
The gate
The view replays every primary-origin record in timeline order on a copy of the initial state.
Writes. Only a 2xx write is modelled. A modelled write applies its effect, using the values it recorded
for generated fields and the stored values for fields it transformed. A
modelled write whose call the plan does not explain brings its entity to the
recorded outcome instead, without attribution. So does an update of an unknown
entity (below): its call cannot be checked, so it adds nothing to a built plan.
A later create whose generated
values take another form than serving gives them (a sequence value out of
order, a clock in another format, a non-UUID unique value) makes the plan
unexplained-change; integer identities are left to the id mapping. A later
create outside the collection a tied plan permits is unmodelled, as serving
refuses that call, so a read of what it recorded does not confirm the plan. The
gate picks that collection among equal spellings in serving's order (below). An update or
delete names its entity as an item read does (below). A later update that does
not answer with its entity is observed only by a read whose view shows every
clock the plan learned, since serving stamps them; without one it is unmodelled.
Any other write that may have changed state, including a redirected or unanswered one, is unmodelled, and what it may have changed depends on where its path lies relative to each type's collection paths (segment-prefix related, parameters matching any segment):
- Below an item path: the named entity is unknown until a read shows it again. When the path names no held entity, every entity of that collection is unknown.
- At a collection path: that collection is not checked again.
- Above collection paths: everything under the path is not checked again.
The path names its entity as an update's does and its collection as a create's does, so a plain spelling reaches a collection held under an encoded one; a path above collections covers each collection whose segments are its own verbatim or once percent-decoded.
An item read of an unknown entity shows it again: the copy takes its recorded values. A failed read that is no absence shows nothing, and the entity stays unknown. Writes that changed it since its last check are checked only on the members they sent, less those the view treats as volatile, which show nothing of a write.
A write no built plan models can also make an entity the copy never held, such as a row an import or a nested create added: a write of a tool with no create, update, delete or document plan, a call of a tool whose plan was never built, a linked create's call that serving would refuse, or any write redirected or left unanswered. A successful item read of an entity the copy has never held (no initial entity, and none a modelled write created, changed or removed) that names it by the type's identity, when such a write ran since that entity or its collection was last checked, shows that entity: the copy takes its recorded values instead of failing the read, and later writes to it are modelled and checked as usual. The taken entity counts against the view's budget as a created one does. An entity a modelled write touched is never taken back this way, and a built plan's call that serving would not apply, such as a create outside its tied collection, keeps its evidence.
Reads. A read is checked when the served environment would answer it from the state:
- an item read of a state-backed item view, of the entity serving would name: in a held collection the read's path matches, each segment verbatim or either spelling once percent-decoded and verbatim spellings first, the id percent-decoded once, then as written;
- a list or document read on one of its view's checked request lines,
chosen as replay chooses the line for the read's call: each path parameter
the read's value verbatim or either spelling once percent-decoded, preferring verbatim
spellings, then recorded order, and the query values decoded, in any order.
A read with no query on a whole list falls back, as serving does, on a
checked line that only pages it. A line whose query repeats a name with
different values is never chosen, since no call's arguments can name it; one
repeating a name with one value is, as a call naming it matches both. A list
is compared as served from the collection of that line. A read on a page
(
limit,size,per_pageand the like, or a_start–_endrange; a size of zero is no bound on a line whose recording listed items under it, while its other sizes and range still bound the page) of a whole list checks nothing once the collection holds more entities than the page, which serving then answers from its recording. A line without proof of whole membership lists its recorded members still held, unless a learned query evaluates the read over the state. An empty later page therefore does not contradict a create outside that page. - A read made while a modelled write to its entity or collection was still running, starting before that write ended, checks nothing: it may show the state before or after the write. Nor does such a read show an unknown entity again.
- A read a write's effect was learned from checks nothing of that write, but still contradicts the other writes it exercises.
Comparison. The read's answer is the full response serving would give from
the copy: an item read's entity rendered into its item view's base recording,
or a list read's members as serving would list them (so a member the copy no
longer holds fails the check) rendered into its line's base recording. It is
compared with the recording, as the read gate compares, with volatile fields taking the
observed values. A recorded 400, 404 or 410, or a 2xx with a JSON null
body, for an entity the copy does not hold agrees with it. A successful read
whose usable body no longer holds the entity or the list fails, as does one of
an entity lacking a field every recording of its view carried, which serving
refuses to answer with.
Attribution.
- A check exercises the write tools that changed its entity or collection since the previous check of it, less those whose effect later writes erased. An update's effect is the fields it sent or changed, derived ones included. A later update overwrites the fields it sets (an increment adds to its field instead), a recorded outcome every field, and a create or delete the whole entity. A document write's effect is the members it merged at its object, or everything under the object it replaces, the whole document at the root; an entity's fields match by name only, whatever their names look like. A write with nothing left on an entity no longer counts there, nor in a collection where no entity it changed keeps any of its effect. A mismatch contradicts them. A pass confirms those it shows something of: a create's or delete's membership, or a changed field the read's view shows and does not treat as volatile; a read that shows none of an update's changes confirms nothing of it, and leaves it for a later check of that entity or collection.
- A mismatch contradicts each exercised write that no unmodelled write came after its latest call on any of the read's entities or collections where its effect survives, whatever earlier write is still pending. For a failed list read the unmodelled write must also follow the last check and pending writes of each member that differs, so an older change elsewhere does not excuse a newer write the list shows undone. An item read checks the writes an unmodelled write did follow only on the members they sent, and a list with such a write is not checked again: the unmodelled write may explain the rest.
- A mismatch on an entity or collection that no write changed contradicts,
as
side-effect, the modelled writes since that previous check whose paths are segment-prefix related to the read's path. - After a failed item check, the copy takes the read's recorded values (or drops the entity on a recorded absence). A list whose check failed is not checked again.
- A list that fails only for where one create placed its entity passes when another of that create's insert candidates reproduces it, which then becomes the plan's rule, unless an earlier list check relied on the rule (an item read's confirmation does not fix it).
- The read that supplied a create's or update's observation does not check it, but checks the other writes it exercises.
Verdicts. A plan is served when at least one check confirms it and none contradicts it. Otherwise the reason, in this precedence, is:
- the first build reason;
contradicted, withcontradicted_bynaming the first contradicting read;side-effect;unconfirmed;incomplete-entities: an update or delete that answers with the entity, when no initial entity holds every field its recorded answer shows (for example a delete that answers with an edit view of the entity the reads never showed), so it could answer only for entities the environment itself created. An update's answer renders the entity it wrote, so a field one of its rules writes counts as held, except an increment's, which adds only to a held value.
checked_record_ordinals lists the confirming reads.
Serving
Catalog. In state mode, the catalog adds the write tools whose plan is served. Their descriptions say the tool:
- applies its effect to the served state;
- names its target type;
- lists its required and accepted body members, quoted and sampled within the description budget as response fields are.
The discovery budget charges them. --replay-only and the replay fallback are
unchanged.
Calls. A served write answers synchronously against the live store and
changes it atomically, so every MCP session and data/get see one state.
Refusals. These are tool errors that leave the state unchanged:
- a body that is not an object;
- a missing required member;
- a member that is not accepted;
- a value of another JSON type than the exemplar's (for a member only a later update stored, that call's), for documents as well as entities;
- an update or delete of an entity the state does not hold;
- a create in another collection when the plan is tied to its own;
- a document write at a path other than the one the state holds it at;
- a body member or a resulting value
data/addwould refuse (a number not exact asdata/getwrites it, a__proto__member, nesting past the limit), increments included, sodata/getalways loads back; - a create, update or document write that would take what
data/getreports past the 32 MiBdata/addintake limit, as aresource_constrainterror; - a rendered response missing a recorded field.
When the tool, or else an item view of the type, recorded a 400, 404 or 410 response, an update or delete of a missing entity answers with the latest such recording instead.
A create in a collection held under more than one spelling (acme1 and
%61cme1) goes to the one the call spells verbatim, as item calls choose their
entity; a collection keeps its spelling after its last entity is deleted. A
reset or load knows the spellings of the Evidence's state, of the state it
installs and of the type's checked list lines (so a collection the capture
listed empty keeps its spelling), never those of a state it replaced. When two
spellings fit a call equally, the one holding entities wins, the earlier first
entity in state order among held ones and the earlier known among emptied ones. data/add refuses a document that data/get would write back past the
32 MiB intake limit once it adds the members a document may omit, such as
types and the state Evidence id. A derived state data/get would write
past that limit is not served: the environment serves replay and reports the
state unavailable.
Clock and generators. The store's clock starts at write_clock and
advances one second before each served write; clock fields take its value in
their recorded format.
- Sequences: one more than the largest current value in their scope, the largest the state started with at its last reset or load, and the largest value they generated, so a deleted entity's value is not reused, as database sequences do not reuse values.
- UUIDs and tokens: derived from a SHA-256 of the state Evidence id, the tool, the field and a write counter, skipping values the type already holds.
- Renewed fields: the entity's current value with each UUID at the rule's pointers replaced by one derived from a SHA-256 of the state Evidence id, the tool, the write counter and the UUID's order in the call, the same replacement wherever the call renews that UUID in either letter case, spelled in each place's case; held values are not skipped. An entity without the field is left without it.
data/reset and data/add restart the clock, the counter and the
sequences.
Missing entities. An item read of an entity the state does not hold
answers with the tool's latest recorded 400, 404 or 410 response, or 2xx JSON
null response, the absences the gate accepts, when it has one, labelled
state.view: "missing". Otherwise it stays a tool error.
Lists of a whole collection. Written entities matter only if lists show
them, so the read gate's membership: "all" also covers a line that only pages
its list (limit, offset, page, per_page, perpage, page_size,
pagesize, size, start, _start, _end) when its recording listed the
whole collection at a proved zero start. Positive page values do not prove
the beginning, because their base is unknown. Whole membership is per line:
all_record_ordinals can name whole lines within a recorded-membership view.
A learned query can filter, search, sort and page the state; otherwise a later
page lists its recorded members still held. A list call with no query argument
answers from a whole line of the collection its path arguments name, with
replay.exact_match false; a collection with no such line answers from its
recording. A call that asks for a page evaluates a learned query when one
covers its arguments; otherwise it keeps the recorded page members.
Provenance. Write answers carry state: {source: "state", view: "create" | "update" | "delete", type, collection, id}, or {source: "state", view: "document-write", path}.
Data plane and export.
data/getreports written entities without record citations; they load back throughdata/addunchanged.environment-exportcounts served write tools in the bundle's tool count and README. Its check stays a read tool.
Not modelled
These stay unserved, or are labelled in the description:
- side effects on counters, relations and copies of entities in other collections;
- inputs the application transforms;
- members the capture never sent;
- reordering after an update;
- membership of filtered or paged lists, which answer their recorded members;
- write paths the manifest left literal;
- writes whose request body the capture did not retain;
- referential rules on delete: a delete removes the entity alone, so an application that refuses to delete a referenced entity, or deletes its dependents with it, is not modelled;
- authorization.
Acceptance
- Domain tests: classification, every field rule, request-body admission, observation from a later read, the insert rules, every verdict and reason, attribution and resynchronisation, and taint by an unmodelled write.
- Services tests:
- store mutations and their atomicity;
- every refusal;
- generated values and their determinism across reset;
data/getround trips of written entities;- the recorded 404 for missing entities;
- the catalog and descriptions in each mode.
- Boundary test: a write tool changes the next read over MCP.
Real captures.
- The view runs over every showcase capture within its budget, and the verification reports, per capture, the write tools served and the reasons for the rest.
- One environment, chosen at random among those serving a write tool, is
exported, run in the AgentEnv framework, and graded from
data/getafter an agent's create, update and delete. - The served model is compared with that application running live on the same calls.
No test reaches an external network.