Doca collaboration

Read the full contract before changing collaboration behavior. It is a target contract plus a dated implementation inventory, not evidence that an API already exists. Inspect the current package README, exports, source and tests before using any proposed API.

Scope and maintenance

This contract governs every document-type editor subpackage — rich text, spreadsheet, Markdown, canvas, slides and future formats — not only slatetsx/exlsx. Format-specific rules (Excel baseline, stable row/column anchors) are the format's instances of the shared contract, not exceptions from it.

Subpackage developers and Doca host developers maintain this contract together: a change is only valid when both sides agree, and the project source documents (docs/collaboration-sdk-contract.md, docs/editor-file-exchange-contract.md) and every packaged skill copy (project skills/ and user skills directories) must be updated in the same change. Do not let the copies drift.

Core constraints

• Unify transport, authentication, durable ACK, outbox and reconnect behavior. Keep format-specific data models behind codec adapters; never convert a workbook into a text CRDT just for uniformity.
• Separate protocolVersion, codec/schemaVersion, epochId, seq, checkpointSeq, resource.version and business history IDs. Epoch identity is always carried as epochId.
• Initialize from a server-authoritative, atomically paired baseline and Yjs state, then mount one stable editor instance. Props, readonly, selection, save state and resize must not rebuild the document or mutate shared state.
• Only local content transactions enter the outbox. Remote/bootstrap/presence/focus/scroll changes must not generate writes or operation IDs. Do not introduce a second autosave transport.
• ACK only after database commit. Keep original bytes and message ID until the matching ACK; a sync response is not an ACK. Never infer dirty state from a nonempty vector diff: an already synchronized deletion set can still be returned.
• Replay unacknowledged updates on reconnect; refuse mismatched epochs and unknown schemas. Do not silently discard pending work or apply it to a replacement baseline. No offline-durability claims without persistent storage.
• Preserve CRDT identities in checkpoints. Excel restores immutable baseline plus commands of that epoch, never a latest workbook snapshot plus old commands.
• Session identity and color come from the server. Same account in two pages has two selections. Presence is temporary, permission checked and non-persistent. Text uses relative points; cells use sheet/range plus editing state; never transmit typed content through presence.
• Permanent comment anchors are distinct from presence coordinates. Excel needs stable row/column identities with deletion handling. Do not fake permanent anchors with A1 coordinates.
• Content changes, validation, ACL and persistence remain atomic. Recheck authorization on writes/broadcasts. Unknown/duplicate ACKs cannot clear other pending edits.

Package upgrade workflow

Read the new package's integration documentation and compare exported APIs/schema with the currently installed build. Build/pack and install the actual updated artifact; when versions are reused, use a new hash-qualified filename and lockfile entry to avoid stale caches. Keep the previous artifact and a rollback route. Do not modify upstream source just to force host compatibility without task authorization.

Adapt host bindings, codec validation and exact current-schema negotiation together. The normal host accepts only the exact current baseline and never automatically migrates data or adds codec adapters. The user-agreed history-storage change provides explicit offline upgrade/rollback commands for its immediately preceding host database baseline only; it does not authorize editor-schema conversion or upgrades from other baselines. Declare upstream gaps explicitly rather than silently approximating them.

Verification

Use isolated test data, not user documents. For affected paths verify:

• Idle open, selection, scroll and resize produce zero content updates for 60 seconds.
• Two replicas converge; remote application causes no echo. Same-user tabs show distinct presence; readonly does not publish/render editing selections.
• Pure deletions followed by repeated sync do not re-upload indefinitely.
• Lost/delayed/duplicate ACKs, reconnect and edits during remote reception do not lose data or show premature saved state.
• Snapshot plus log restoration and compaction preserve the online projection; mismatched epoch/schema is rejected.
• For Excel, test each changed operation class (row/column insertion/deletion, cells, formulas, merges, sorting/filtering, undo). Do not claim all operations converge from a cell-edit test.
• Revocation, disabled/anonymous users and spoofed identity/invalid ranges are handled.
• Format state drives both toolbars; no remount/focus loss on status updates.

In the handoff distinguish implemented behavior, verified tests, external-service verification, and still-proposed contract changes. A successful build alone is not collaboration verification.

For file import/export touching initialization or persistence, read file exchange. Default imports establish a new resource and lineage; exports are read-only projections. A converter must not clear an outbox, initialize an already-open document, or silently replace the active baseline.