Collaboration Contract v1.0 Ratification for Services, Interfaces, and RERUM

[cubap]

Summary

Adopt and ratify the websocket collaboration and deferred-persistence contract for cross-repository implementation.

Contract Source

• docs/collaboration/websocket-collaboration-contract.md

Required Decisions

• Event envelope and versioning
• Operation schema and idempotency requirements
• Deferred flush trigger windows
• Conflict payload and reconciliation responsibilities
• Reliability guarantees and limits

Exit Criteria

• Maintainers from TPEN-services, TPEN-interfaces, and RERUM confirm agreement
• Any deviations are tracked as follow-up issues
• Contract version marked approved for Phase 1 rollout

[cubap]

Dependency map for execution planning:

Depends on:

• Maintainer approval from services, interfaces, and RERUM teams

Blocks:

• Collab Phase 1: Websocket Server Skeleton, Auth, and Presence Rooms #509
• Collab Phase 3: Draft Buffer API and Operation Intake for Deferred Persistence #510
• Collab Phase 5: Durable Flush Worker from Drafts to RERUM with Conflict Acks #511
• Collab Phase 2: Realtime Client and Presence UI (No Save Behavior Change Yet) TPEN-interfaces#555
• Collab Phase 4: Deferred Commit Engine with Important-Moment and Long-Debounce Flush TPEN-interfaces#556
• Collab Phase 7: Conflict Resolution UX and Collaboration Observability Dashboards TPEN-interfaces#557
• Collab Phase 6: Idempotent Overwrite and Conflict Payload Enhancements for Deferred Commit Clients rerum_server_nodejs#266

Related to:

• docs/collaboration/websocket-collaboration-contract.md in TPEN-services repository

[cubap]

Cross-Repo Execution Order Checklist

Use this checklist to track rollout in dependency order.

• Phase 0 Contract Ratification: Collaboration Contract v1.0 Ratification for Services, Interfaces, and RERUM #512
• Phase 1 Services Websocket Skeleton: Collab Phase 1: Websocket Server Skeleton, Auth, and Presence Rooms #509
• Phase 2 Interfaces Presence Client: Collab Phase 2: Realtime Client and Presence UI (No Save Behavior Change Yet) TPEN-interfaces#555
• Phase 3 Services Draft Intake Buffer: Collab Phase 3: Draft Buffer API and Operation Intake for Deferred Persistence #510
• Phase 4 Interfaces Deferred Commit Engine: Collab Phase 4: Deferred Commit Engine with Important-Moment and Long-Debounce Flush TPEN-interfaces#556
• Phase 5 Services Durable Flush Worker: Collab Phase 5: Durable Flush Worker from Drafts to RERUM with Conflict Acks #511
• Phase 6 RERUM Idempotent Overwrite Enhancements: Collab Phase 6: Idempotent Overwrite and Conflict Payload Enhancements for Deferred Commit Clients rerum_server_nodejs#266
• Phase 7 Interfaces Conflict UX and Observability: Collab Phase 7: Conflict Resolution UX and Collaboration Observability Dashboards TPEN-interfaces#557

Definition of done:

• All phases complete with cross-repo dependency comments updated
• Contract decisions reflected in docs/collaboration/websocket-collaboration-contract.md

[cubap]

Canonical Planning Documentation (Moved from Repository Files)

This issue now serves as the canonical source for collaboration planning and contract governance.

Contract v1.0

Status: Draft for cross-repository implementation
Date: 2026-05-05
Owners: TPEN-services, TPEN-interfaces, and RERUM maintainers

1. Goals

• Enable real-time collaborative transcription editing.
• Reduce write pressure on RERUM by deferring persistence.
• Preserve correctness with optimistic concurrency and conflict recovery.
• Keep user-visible state clear: local draft, syncing, persisted, conflict.

2. Scope

In scope:

• Presence and cursor synchronization.
• Real-time operation intake and room fanout.
• Deferred commit pipeline from drafts to durable RERUM writes.
• Conflict handling and client reconciliation.

Out of scope:

• Full Conflict-free Replicated Data rollout in first phase.
• Binary payload collaboration.

3. Transport and Auth

• Transport: Websocket over TLS.
• Auth: Bearer token in websocket handshake.
• Server validates token and project-level authorization.
• Room join denied on failed auth or insufficient permission (at least edit on something onscreen, set by interface).

4. Room and Identity Model

Room IDs:

• project room: project:{projectId}
• page room: project:{projectId}:page:{pageId}

Actor identifiers:

• actorId: TPEN user id

5. Event Envelope

{
  "event": "string",
  "version": "1.0",
  "requestId": "uuid",
  "timestamp": "ISO-8601",
  "projectId": "string",
  "pageId": "string|null",
  "actorId": "string",
  "payload": {}
}

Rules:

• requestId must be unique per client operation attempt.
• version starts at 1.0 and changes only on contract revision.

6. Core Events

Presence:

• presence.join
• presence.leave
• presence.cursor
• presence.selection

Draft operations:

• draft.op.submit
• draft.op.accepted
• draft.op.rejected

Durability lifecycle:

• durable.flush.queued
• durable.flush.started
• durable.flush.persisted
• durable.flush.conflict
• durable.flush.failed

7. Draft Operation Schema

{
  "opId": "uuid",
  "opType": "line.text.patch|line.bounds.patch|line.create|line.delete",
  "lineId": "string",
  "baseRevision": "string",
  "idempotencyKey": "string",
  "patch": {
    "text": "string optional",
    "x": 0,
    "y": 0,
    "w": 0,
    "h": 0
  },
  "clientTime": "ISO-8601"
}

Validation:

• opId required and unique from client perspective.
• idempotencyKey required for retried submissions.
• baseRevision required for conflict detection at durable write.

8. Deferred Commit Policy

Client commit triggers:

• important moment: line change, page change, explicit save, user leave.
• long debounce idle: 8 to 15 seconds after last edit.
• max draft age: force flush every 45 to 60 seconds.
• unload or visibility hidden: best effort immediate flush.

Server behavior:

• Coalesce operations by line before durable flush.
• Preserve operation ordering per line.
• Deduplicate by idempotencyKey.

9. Durability and Concurrency

• Durable writes use optimistic locking against latest RERUM version metadata.
  • NOTE: Only some RERUM saves overwrite, others trigger versioning on RERUM and receive new ids, such as annotated lines.
• If overwrite precondition fails, server emits durable.flush.conflict.
• Conflict payload includes latest durable state and revision metadata.

Conflict payload:

{
  "lineId": "string",
  "submittedBaseRevision": "string",
  "currentRevision": "string",
  "currentDocument": {},
  "reason": "version_conflict"
}

10. Acknowledgement Contract

On accept:

{
  "event": "draft.op.accepted",
  "payload": {
    "opId": "uuid",
    "draftRevision": "string"
  }
}

On persisted:

{
  "event": "durable.flush.persisted",
  "payload": {
    "lineId": "string",
    "opIds": ["uuid"],
    "durableRevision": "string",
    "rerumId": "string"
  }
}

On conflict:

{
  "event": "durable.flush.conflict",
  "payload": {
    "lineId": "string",
    "opIds": ["uuid"],
    "conflict": {}
  }
}

11. Reliability

• At-least-once delivery from client to draft intake.
• Idempotency enforced server-side.
• Client retries exponential backoff with jitter.
• Server must support reconnect and room rejoin.

12. Limits and Backpressure

Defaults:

• max queued ops per user per page: 500
• max payload size per op: 32 KB
• max flush batch size: 100 ops

When limits exceed:

• return draft.op.rejected with reason code.
• emit telemetry counter for rejected operations.

13. Observability

Required metrics:

• ws_connections_active
• draft_ops_received_total
• durable_flush_attempt_total
• durable_flush_success_total
• durable_flush_conflict_total
• durable_flush_latency_ms
• draft_queue_depth

14. Security

• Enforce permission checks for all op types.
• Validate payload schema server-side.
• Reject suspicious content using existing screening middleware patterns.
• Avoid logging raw transcription content in error logs where possible.

15. Versioning and Change Control

• Contract version header is required in all events.
• Backward-incompatible changes require version bump and dual support window.
• Changes are approved only when all three repositories have matching issue updates.

Cross-Issue Implementation Order

1. Services websocket skeleton: Collab Phase 1: Websocket Server Skeleton, Auth, and Presence Rooms #509
2. Interfaces presence client: Collab Phase 2: Realtime Client and Presence UI (No Save Behavior Change Yet) TPEN-interfaces#555
3. Services draft intake: Collab Phase 3: Draft Buffer API and Operation Intake for Deferred Persistence #510
4. Interfaces deferred commit engine: Collab Phase 4: Deferred Commit Engine with Important-Moment and Long-Debounce Flush TPEN-interfaces#556
5. Services durable flush worker: Collab Phase 5: Durable Flush Worker from Drafts to RERUM with Conflict Acks #511
6. RERUM idempotency/conflict enhancements: Collab Phase 6: Idempotent Overwrite and Conflict Payload Enhancements for Deferred Commit Clients rerum_server_nodejs#266
7. Interfaces conflict UX/observability: Collab Phase 7: Conflict Resolution UX and Collaboration Observability Dashboards TPEN-interfaces#557