Documents

Two devices open Alice's marketplace profile. The phone shows her biography, “Front-row regular,” and the laptop shows the same text a moment later. Reading agrees; editing is where trouble starts. What does it mean to read the profile, and which device is allowed to change it?

The profile is a document, an application record stored as part of Platform state. Its shape comes from the data contract described earlier; the contract lab that would publish one is currently a placeholder, so this profile is hypothetical. Alice creates it first with the biography “Front-row regular.” Only after that create is accepted can either device query it. Nothing below claims that a contract or document already exists.

Start with the answer a read gives

When the phone queries for the profile, Platform returns a document from committed state: the version the network has accepted and stored. A read observes that state. It doesn't sign a request or change the profile, and the laptop can ask the same question without receiving a private copy owned by the phone.

That distinction matters when the app displays an edit button. Showing a document proves that the app can read it; it doesn't prove that the current user may write it.

Four moves through one record

The profile's lifecycle has four useful application-level moves:

• Create adds a new document that satisfies the contract's rules.
• Query reads documents already committed to Platform.
• Replace changes an existing document while keeping it as the same record and advancing its revision.
• Delete removes an existing document from the current state.

Create, replace, and delete change shared state, so Platform validates and authorizes them before later queries can see the result. Query is the odd one out: it asks what exists rather than proposing a change.

Ownership can change later through protocol actions such as transfer or purchase; that's how a ticket reaches its buyer. Those are ways a document can acquire a new owner, not alternate names for replacing its contents; their rules belong elsewhere. A profile stays with the identity that created it, so for this example the owner never changes.

Reading isn't permission

The profile belongs to an identity, meaning the Platform account recorded as its owner. That ownership is the authorization boundary for ordinary mutation: the owning identity may replace the profile, or delete it when the document type permits deletion, while an identity that can only read it may do neither.

The marketplace can display Alice's profile to Bob. Bob can learn the current biography, but he can't submit a valid replacement just because the query succeeded. Alice's identity owns the profile, so an authorized change must come from Alice's identity. Credits pay for Platform work, but funding an identity doesn't give it ownership or editing authority.

The same boundary explains resale. When Alice sells her ticket to Bob, the ticket document acquires a new owner only through a mechanism its document type supports, such as transfer or purchase. An ordinary edit cannot smuggle a new owner into the record.

Two edits, one winner

Now Alice opens her profile on both devices. Each reads revision 3. She edits the phone copy to “Front-row regular. Ask me about the Thursday show,” while the laptop copy becomes “Front-row regular since 2019.” Both edits are authorized, but authorization alone can't tell Platform which copy included the newer thought.

The safe replacement rule supplies that missing check: fetch the current document, then submit the next revision. The phone's accepted replacement moves revision 3 to revision 4. When the laptop later submits its replacement based on revision 3, Platform rejects it as stale instead of silently overwriting the phone's accepted text.

The laptop must read again, inspect revision 4, incorporate its intended change, and submit the next revision. This is optimistic concurrency: the app proceeds as if its copy is current, but the network refuses the write when that assumption is no longer true.

Some document types are immutable. They can be created and queried, but they don't support replacement, so there is no revision to advance. That choice fits records that should stand as originally written, such as the receipt for a completed ticket sale; it doesn't turn a mutable profile into a conflict-free record.

What deletion gives back

Eventually Alice deletes the profile. The document disappears from the current state, but deletion doesn't rewind every cost associated with storing and changing it.

When an app stores data, it prepays the storage fee, and Platform gradually allocates that value over time. Deleting the document can return the unused portion of that prepaid storage cost. The longer the record has occupied storage, the less unused allocation remains. The processing work for the original write, and the work of processing the deletion, stays paid.

So an early delete may produce a partial storage refund, not a full reversal of the record's costs. That is the useful accounting rule to carry into an app's cleanup design.

Check your understanding

Restoring your progress…

4 correct to pass