Local collaborative API edits are accepted but not reliably persisted

[acstrtgy]

Summary

The local Proof SDK is currently not usable for reliable collaborative editing. API calls can return a successful response and increment the document revision, but the corresponding changes are not consistently reflected in the live page or in the persisted markdown projection.

This prevents using the self-hosted deployment for real work. Using the hosted Proof website is not an acceptable workaround because documents and files must remain inside our own infrastructure and must not leave the environment.

Environment

• Repository: https://github.com/EveryInc/proof-sdk
• Local checkout commit: fb2578758f1c62776301209131181643c5f4a19a
• The local commit matches the current upstream main branch at the time of testing.
• Local package version: 0.1.0
• Local server started with proof-start
• Server: http://localhost:4000
• Node.js: v25.5.0
• Embedded collaboration runtime enabled
• On-demand projection repair enabled
• The local server exposes the documented v2 edit surface. There is no /api/v3 route.

Tests performed

1. Server and document creation

1. Started the local server with proof-start.
2. Confirmed the health endpoint returned HTTP 200.
3. Created a document with POST /documents.
4. Opened the tokenized share URL in a browser.
5. Confirmed that the document loaded and that the browser showed the document as saved.

2. Read and presence APIs

The following operations worked:

• GET /api/agent/:slug/state
• GET /api/agent/:slug/snapshot
• POST /api/agent/:slug/presence
• POST /api/agent/:slug/ops with comment.add

The snapshot returned block references and a revision suitable for edit/v2.

3. Revision locking

Revision locking behaved correctly:

• An edit using an old baseRevision was rejected with STALE_REVISION.
• Re-reading the snapshot and retrying with the current revision returned success.

4. Structured edits and synchronization

The main problem appears during live collaboration:

1. Opened the document in a browser, creating an active collaborative session.
2. Read the current revision and block references.
3. Sent POST /api/agent/:slug/edit/v2 with replace_block and insert_after operations.
4. The API returned success: true and incremented the revision.
5. The browser did not show the new content.
6. Subsequent state and snapshot reads returned warnings such as:

{
  "projectionFresh": false,
  "warning": {
    "code": "PROJECTION_STALE",
    "error": "Canonical reads are serving Yjs fallback content while projection repair catches up."
  }
}

In some cases, the projection later returned projectionFresh: true, but the requested content was still missing from the document.

A simple direct browser edit did persist successfully, which suggests that the problem is specifically related to agent/API structured edits interacting with the live collaboration and projection layers.

The most problematic reproduction was a structured edit/v2 insertion containing multiple top-level blocks, including:

• headings
• paragraphs
• display formulas
• additional headings and paragraphs

The request returned success, but the headings, formulas, and paragraphs did not appear in the live page or persisted markdown. Retrying after the projection became fresh did not resolve the issue.

Expected behavior

After a successful edit/v2 response:

• the new blocks should appear in the live browser session
• GET /state and GET /snapshot should contain the new content
• projectionFresh should be true
• no stale projection warning should remain
• the API should not report success before the live document and persisted projection converge

Actual behavior

• The API reports successful edits.
• Revisions increment.
• The live browser page does not reliably update.
• The persisted markdown can remain unchanged.
• state and snapshot can report PROJECTION_STALE.
• Even after the projection reports fresh again, the requested structured content may still be absent.

Impact

This makes the local deployment unreliable for agent-driven editing and effectively unusable for production work. The hosted website cannot be used as a workaround because data must remain inside the local infrastructure.

Questions

1. Is this a known issue in the local collaboration, Yjs, or projection-repair path?
2. Are multi-block edit/v2 operations supported while a browser collaborator is connected?
3. Is there a required local configuration, runtime version, migration, or feature flag for reliable convergence?
4. Is the local API expected to remain on edit/v2, or is an API v3 planned for the self-hosted SDK?
5. What logs or diagnostic bundle should be attached to help reproduce this?
6. Is there a planned release that addresses this behavior, and is an approximate release timeframe available?

I can provide sanitized request/response payloads, revision timelines, and additional reproduction logs if needed.