schemaVersion: requirement-record.v1
revision: R2
status: in-progress
priority: P0
productOwner: "@PeterGuy326"
technicalOwner: "unassigned"
userOutcome: "API clients and digital employees can mutate document content, create and list versions, and restore safely through an active-room-aware gateway with stable identifiers, idempotency, and execution-time authorization."
requirements:
- REQ-001
- REQ-002
- REQ-003
- REQ-004
acceptanceCriteria:
- AC-001
- AC-002
- AC-003
- AC-004
- AC-005
- AC-006
parent: "https://github.com/fullstack-ai-infra/doc/issues/2"
dependencies: []
supersedes:
- "R1 unnumbered scope/acceptance draft"
lastDecisionAt: "2026-08-23T06:15:12Z"
Context
The public API intentionally blocks generic content replacement because direct database writes would bypass active Yjs rooms. Digital employees also need stable version/read/proposal contracts rather than storage access. The outcome is to add an active-room-aware gateway for content mutation, version creation/listing, and safe restore. This is a prerequisite for agent commit flows. Parent: trustworthy document-plane epic (#2).
Contract requirements in R1
- Serialize mutations through the collaboration/Yjs authority.
- Use optimistic preconditions or base-version identifiers.
- Return stable document/revision identifiers.
- Preserve the current snapshot before restore.
- Define idempotency and retry behavior.
- Perform authorization at execution time, not only request creation time.
R1 acceptance checklist
Requirements
REQ-001 — Active-room-aware mutation gateway
Serialize content mutations through the collaboration/Yjs authority so the API cannot bypass an active room by writing the persistence row directly.
REQ-002 — Optimistic concurrency and stable identifiers
Use optimistic preconditions or base-version identifiers, and return stable document/revision identifiers.
REQ-003 — Safe restore
Preserve the current snapshot before restore; restore creates an audit/version record and remains recoverable.
REQ-004 — Idempotency and execution-time authorization
Define idempotency and retry behavior. Perform authorization at execution time, not only request creation time.
Acceptance Criteria
AC-001 — No bypass of active rooms
The API cannot mutate content by writing the persistence row behind an active room.
AC-002 — Convergent multi-client updates
Concurrent clients observe a convergent update after an API mutation.
AC-003 — Structured conflict on stale base
Stale base versions produce a structured conflict instead of overwriting newer work.
AC-004 — Recoverable, recorded restore
Restore creates an audit/version record and remains recoverable.
AC-005 — Idempotent retry
Repeating an idempotent request does not duplicate the mutation.
AC-006 — End-to-end contract coverage
Contract and multi-client end-to-end tests cover success, conflict, revocation, retry, and restore.
Non-goals
None stated in R1.
Decisions
- DEC-DOC-4-001 (2026-08-23T06:15:12Z): requirement record formalized to requirement-record.v1 with numbered REQ/AC, owners, and ledger; R1 scope and acceptance content unchanged.
Status and evidence
- Status: in-progress; Priority: P0
- Baseline: the public API currently blocks generic content replacement; no active-room-aware mutation, version, or restore gateway exists yet.
- Latest accepted implementation ledger: none
Change history
| Revision |
Effective time |
Decision |
Superseding comment |
| R1 |
2026-08-01T06:54:17Z |
Initial unnumbered scope and acceptance |
Initial body |
| R2 |
2026-08-23T06:15:12Z |
Formalize requirement-record.v1 with numbered REQ/AC, owners, and ledger |
This edit |
Context
The public API intentionally blocks generic content replacement because direct database writes would bypass active Yjs rooms. Digital employees also need stable version/read/proposal contracts rather than storage access. The outcome is to add an active-room-aware gateway for content mutation, version creation/listing, and safe restore. This is a prerequisite for agent commit flows. Parent: trustworthy document-plane epic (#2).
Contract requirements in R1
R1 acceptance checklist
Requirements
REQ-001 — Active-room-aware mutation gateway
Serialize content mutations through the collaboration/Yjs authority so the API cannot bypass an active room by writing the persistence row directly.
REQ-002 — Optimistic concurrency and stable identifiers
Use optimistic preconditions or base-version identifiers, and return stable document/revision identifiers.
REQ-003 — Safe restore
Preserve the current snapshot before restore; restore creates an audit/version record and remains recoverable.
REQ-004 — Idempotency and execution-time authorization
Define idempotency and retry behavior. Perform authorization at execution time, not only request creation time.
Acceptance Criteria
AC-001 — No bypass of active rooms
The API cannot mutate content by writing the persistence row behind an active room.
AC-002 — Convergent multi-client updates
Concurrent clients observe a convergent update after an API mutation.
AC-003 — Structured conflict on stale base
Stale base versions produce a structured conflict instead of overwriting newer work.
AC-004 — Recoverable, recorded restore
Restore creates an audit/version record and remains recoverable.
AC-005 — Idempotent retry
Repeating an idempotent request does not duplicate the mutation.
AC-006 — End-to-end contract coverage
Contract and multi-client end-to-end tests cover success, conflict, revocation, retry, and restore.
Non-goals
None stated in R1.
Decisions
Status and evidence
Change history