Part 025 — Revision Identity, Optimistic Locking, Draft Branches, and Collaborative Editing

Positioning

Enterprise quote jarang selesai dalam satu sesi.

Sebuah deal dapat berubah karena:

• customer meminta konfigurasi alternatif;
• sales mengubah term;
• presales memperbarui design;
• pricing melakukan repricing;
• finance menolak discount;
• legal menambahkan term;
• product catalog berubah;
• feasibility result kedaluwarsa;
• atau stakeholder lain mengedit quote pada waktu yang sama.

Karena itu, Quote membutuhkan lebih dari satu kolom version.

Core thesis: commercial revision, technical aggregate version, working draft, published proposal, dan collaboration history adalah konsep berbeda. Semuanya harus memiliki identity, immutability, concurrency rules, dan lineage yang eksplisit.

1. Revision versus Version

Revision

A commercially meaningful snapshot of a quote.

A revision may be:

• reviewed;
• approved;
• presented;
• accepted;
• rejected;
• or superseded.

Version

A technical concurrency counter or persisted state version.

A version may increase for:

• autosave;
• comment;
• internal metadata;
• recalculated projection;
• or item edit.

Not every version should become a commercial revision.

2. Commercial Meaning

A revision should exist when a change materially affects:

• customer offer;
• price;
• term;
• scope;
• product configuration;
• requested date;
• approval evidence;
• or contractual representation.

3. Technical Mutation

A technical mutation may not justify a new commercial revision.

Examples:

• internal note;
• search-index refresh;
• audit record;
• assignment metadata;
• proposal delivery retry;
• or non-customer-visible formatting preference.

4. Quote Identity

The Quote has stable identity across all revisions.

Quote ID: QUO-123

5. Revision Identity

Each revision should have stable identity.

Quote ID: QUO-123
Revision Number: 7
Revision ID: QUO-123-R7

6. Aggregate Version

Each mutable aggregate or partition may use an integer or token.

aggregateVersion = 42

Used for optimistic concurrency.

7. Item Version

Large quotes may version individual item aggregates.

quoteItemVersion = 13

8. Snapshot Version

A serialized revision snapshot may have:

• schema version;
• content version;
• checksum;
• and publication timestamp.

9. Revision Number Is Not Database Row Version

Avoid using one field for:

• commercial revision;
• optimistic locking;
• and schema migration.

10. Revision Lifecycle

Possible lifecycle:

WORKING
-> FINALIZED
-> APPROVED
-> PRESENTED
-> ACCEPTED

Alternative outcomes:

REJECTED
SUPERSEDED
WITHDRAWN
EXPIRED

Exact states must align with internal Quote lifecycle.

11. Working Revision

A mutable commercial workspace.

It may be:

• incomplete;
• invalid;
• unpriced;
• stale;
• and collaborative.

12. Finalized Revision

A stable snapshot ready for:

• approval;
• document generation;
• presentation;
• or acceptance.

13. Approved Revision

Approval references exact revision and evidence.

14. Presented Revision

A proposal/document representing exact revision has been delivered.

15. Accepted Revision

The accepted revision is immutable commercial evidence.

16. Superseded Revision

A newer revision replaces an older revision for future commercial action.

The older revision remains historically resolvable.

17. Rejected Revision

A revision can be rejected by:

• internal approval;
• or customer.

Keep those semantics distinct.

18. Revision Immutability

Once a revision is:

• finalized;
• approved;
• presented;
• or accepted,

material edits should create a new revision.

19. Immutable Accepted Revision

An accepted revision must not be overwritten by:

• catalog refresh;
• repricing;
• term change;
• attachment replacement;
• or order conversion.

20. What Can Change after Acceptance

Only external/process state may continue:

• order conversion status;
• billing activation;
• document archive status;
• or support annotations.

The accepted commercial snapshot remains immutable.

21. Revision Parent

A new revision should reference its parent.

Revision 8
parentRevision = 7

22. Revision Lineage

Lineage supports:

• compare;
• audit;
• negotiation history;
• and root-cause analysis.

23. Linear Revision History

Simple model:

R1 -> R2 -> R3 -> R4

Works when only one active branch exists.

24. Branching History

Complex deal may branch:

R3
├── R4-FIBER
└── R4-WIRELESS

25. Branch Identity

Each branch should have:

• branch ID;
• parent revision;
• purpose;
• owner;
• and lifecycle.

26. Alternative versus Revision

Alternative

A different commercial option intended for comparison.

Revision

A newer version of an offer.

Do not represent alternatives as sequential revisions if they coexist.

27. Revision of an Alternative

Each alternative may have its own revision history.

28. Alternative Group

A group can indicate:

• mutually exclusive alternatives;
• selected alternative;
• and presentation policy.

29. Draft Branch

A draft branch allows independent work without overwriting main working revision.

30. Main Branch

The currently preferred working branch.

31. Branch Promotion

Selecting an alternative may promote it as current working revision.

The other branches remain history.

32. Branch Merge

Merging two branches is a domain operation.

It may combine:

• products;
• sites;
• terms;
• and comments.

33. Merge Is Not JSON Merge

A field-level merge can violate:

• bundle rules;
• pricing;
• approval;
• and cross-item invariants.

34. Semantic Merge

A semantic merge understands:

• item identity;
• configuration semantics;
• price relevance;
• and relationship graph.

35. Three-Way Merge

Uses:

• common ancestor;
• branch A;
• branch B.

Useful for detecting conflicting changes.

36. Merge Conflict

Examples:

• both branches change contract term;
• one removes item another modifies;
• one changes customer context;
• both replace same inventory product differently.

37. Conflict Classification

Possible categories:

• scalar conflict;
• item existence conflict;
• relationship conflict;
• pricing conflict;
• context conflict;
• term conflict;
• and attachment conflict.

38. Scalar Conflict

Two users modify same scalar field differently.

39. Structural Conflict

One branch changes product hierarchy.

40. Context Conflict

Customer, market, currency, or contract differs.

This often requires explicit branch separation rather than merge.

41. Price Conflict

Price snapshots from different context cannot be merged directly.

The merged revision must be repriced.

42. Approval Conflict

Approval from one branch does not transfer automatically.

43. Merge Resolution

Possible outcomes:

• choose A;
• choose B;
• manually construct target;
• reject merge;
• or create a new combined branch.

44. Merge Audit

Record:

• source revisions;
• target revision;
• conflicts;
• decisions;
• actor;
• and time.

45. Clone Quote

Cloning creates a new Quote identity.

46. Clone Revision

Creates a new working revision under same Quote identity.

47. Clone Alternative

Creates a branch for comparison.

48. Copy Policy

Decide what is copied:

• items;
• terms;
• attachments;
• customer context;
• pricing;
• approval;
• comments;
• and internal metadata.

49. Safe Clone Defaults

Usually do not carry forward:

• acceptance evidence;
• terminal lifecycle state;
• expired approval;
• stale qualification;
• order references;
• or mutable promotion reservation.

50. Price on Clone

Options:

• copy snapshot but mark stale;
• discard and reprice;
• preserve only for comparison;
• or copy if exact context remains valid.

51. Approval on Clone

Usually invalidated unless approval is explicitly reusable and scope-compatible.

52. Qualification on Clone

Mark stale unless context/version/validity proves reuse is safe.

53. Catalog Version on Clone

Options:

• preserve source publication;
• migrate to current;
• or let user choose.

54. Revision Creation Trigger

Possible triggers:

• material edit after finalization;
• customer change request;
• repricing of presented quote;
• approval rejection;
• proposal correction;
• or negotiation round.

55. Explicit Create Revision Command

Prefer:

CreateQuoteRevision

over implicit overwrite.

56. Revision Reason

Examples:

• CUSTOMER_CHANGE;
• PRICE_CHANGE;
• TERM_CHANGE;
• APPROVAL_REWORK;
• CATALOG_MIGRATION;
• CORRECTION;
• ALTERNATIVE_DESIGN;
• NEGOTIATION_ROUND.

57. Revision Metadata

Store:

• reason;
• createdBy;
• createdAt;
• parent revision;
• source branch;
• and change summary.

58. Automatic Revision Creation

May be valid for well-defined operations.

Example:

• material edit on Presented quote automatically creates new Draft revision.

The behavior must be visible.

59. User-Controlled Revision

User explicitly starts a new revision.

Useful when change is exploratory.

60. Revision Finalization

Finalization should:

• freeze content;
• assign revision number if needed;
• calculate checksum;
• validate readiness;
• and publish immutable snapshot.

61. Finalization Barrier

For partitioned quote:

• capture all item versions;
• recompute quote-level totals;
• validate cross-item rules;
• and atomically record revision manifest.

62. Revision Manifest

Possible contents:

quoteId
revisionId
revisionNumber
headerVersion
itemPartitionVersions
priceSnapshotIds
approvalEvidenceIds
termVersions
attachmentChecksums
contentChecksum

63. Content Checksum

A checksum helps detect accidental mutation.

64. Revision Schema Version

Allows historical readers to interpret old snapshot.

65. Revision Storage

Options:

• full snapshot;
• delta chain;
• event sourcing;
• or hybrid.

66. Full Snapshot

Stores complete revision.

Benefits:

• easy read;
• independent history;
• simple document generation.

Costs:

• storage duplication.

67. Delta Revision

Stores change from parent.

Benefits:

• smaller storage.

Risks:

• slow reconstruction;
• parent corruption;
• and complex schema evolution.

68. Event-Sourced Revision

Reconstructs from events.

Benefits:

• complete change history.

Risks:

• complex replay;
• event schema evolution;
• and slower ad hoc historical read.

69. Hybrid Revision Storage

Store:

• full materialized immutable revision;
• plus command/audit history;
• plus semantic diff.

Often practical.

70. Revision Reconstruction

Historical revision must be reconstructable without current catalog or current mutable price.

71. Revision Retention

Retention may depend on:

• customer presentation;
• acceptance;
• legal rules;
• and tenant policy.

72. Revision Deletion

Hard deletion of presented/accepted revisions is usually unsafe.

73. Redaction

Privacy redaction should preserve:

• identity;
• monetary evidence;
• and audit integrity

as legally required.

74. Optimistic Concurrency

A client sends expected version.

The server commits only if current version matches.

75. Compare-and-Set

Concept:

update quote
where id = ?
and version = expectedVersion

If no row changes, return conflict.

76. ETag

HTTP APIs can expose version through ETag.

Example:

ETag: "quote-123-v42"
If-Match: "quote-123-v42"

Internal API governance must be verified.

77. Version Field

A simple integer is often enough for aggregate concurrency.

78. Timestamp as Version

Timestamps can collide or have precision ambiguity.

Prefer monotonic version/token.

79. Pessimistic Locking

Locks resource before edit.

Useful for:

• short critical operation;
• and strict single-editor workflow.

Poor for long-running quote editing.

80. Long-Lived Lock Risk

• abandoned lock;
• poor collaboration;
• low availability;
• and operational cleanup.

81. Soft Lock

Signals active editor but does not enforce database exclusion.

Useful for awareness.

82. Lease Lock

Lock expires unless renewed.

Still risky for long deals.

83. Optimistic versus Pessimistic

84. Hybrid Concurrency

Use optimistic editing plus short locks for:

• finalization;
• acceptance;
• or exclusive document publish.

85. Concurrency Scope

Possible scope:

• quote;
• revision;
• item;
• item partition;
• price snapshot;
• or term section.

86. Whole-Quote Version

Simple, but unrelated edits conflict.

87. Item-Level Version

Improves collaboration.

Requires stronger final consistency process.

88. Section-Level Version

Sections:

• commercial header;
• product configuration;
• pricing;
• legal terms;
• attachments.

Can support specialist ownership.

89. Version Vector

A revision manifest can capture versions of multiple partitions.

90. Concurrency Token

Opaque token can encode or reference version state.

91. Concurrent Different-Item Edit

Should ideally succeed independently.

92. Concurrent Same-Item Edit

Requires conflict detection.

93. Concurrent Parent/Child Edit

One user removes parent while another edits child.

The child update must fail or be rebased.

94. Concurrent Context Change

Changing customer, currency, or contract can invalidate many parallel item edits.

Use a context epoch or global quote version.

95. Context Epoch

Increment whenever quote-wide pricing/validation context changes.

Item updates reference expected epoch.

96. Price Epoch

Can identify pricing-context generation.

97. Catalog Epoch

Can identify working catalog publication.

98. Stale Write

A command based on older version.

Return a conflict with enough information to recover.

99. Conflict Response

Should include:

• current version;
• conflicting fields/items;
• latest state reference;
• and available recovery options.

100. Last-Write-Wins

Easy but dangerous for commercial data.

It can silently lose:

• product selection;
• term;
• discount;
• or customer change.

101. Field-Level Last-Write-Wins

May be acceptable for low-risk metadata.

Example:

• internal draft note title.

Not for customer commitment.

102. Automatic Merge

Safe for independent, non-semantic changes only.

103. Manual Merge

Required for material conflicts.

104. Rebase

Apply user changes on top of latest revision.

Need semantic revalidation.

105. Conflict Preview

Show:

• your change;
• latest change;
• resulting impact;
• and merge options.

106. Lost Update Detection

Optimistic versioning is the basic protection.

107. Write Skew

Two concurrent changes each pass local validation but jointly violate invariant.

Example:

• each adds a discount under cap;
• combined total exceeds cap.

Finalization or aggregate-level conditional update must catch it.

108. Phantom Conflict

New item inserted between validation and commit affects quote-level rule.

109. Aggregate Invariant under Partitioning

Use:

• serializable finalization;
• invariant reservation;
• compare all partition versions;
• or retry.

110. Autosave

Autosave supports long editing.

It should use:

• command identity;
• expected version;
• retry;
• and visible failure state.

111. Debounce

Avoid save per keystroke.

112. Save Draft

A draft save does not necessarily create commercial revision.

113. Autosave Conflict

Options:

• pause and notify;
• rebase safe changes;
• create branch;
• or ask user to merge.

114. Offline Edit

Requires:

• local version;
• queued commands;
• conflict resolution;
• and secure local storage.

115. Resume after Disconnect

Client reloads latest version and reconciles unsent changes.

116. Idempotent Save

Retries should not duplicate:

• items;
• comments;
• or revisions.

117. Command Identity

Each client mutation can carry:

commandId
clientSessionId
expectedVersion

118. Collaboration Model

Possible models:

1. Single editor.
2. Single writer, multiple reviewers.
3. Section ownership.
4. Multi-user optimistic editing.
5. Branch-based collaboration.
6. Real-time collaborative editing.

119. Single Editor

Simple but bottlenecked.

120. Multiple Reviewers

Reviewers comment without changing core quote.

121. Section Ownership

Examples:

• sales owns commercial context;
• presales owns configuration;
• pricing owns adjustment requests;
• legal owns term changes.

Authority still enforced server-side.

122. Multi-User Optimistic Editing

Each actor can edit allowed areas.

Conflicts are detected at commit.

123. Real-Time Collaboration

Requires:

• presence;
• operation stream;
• ordering;
• conflict-free or transformed operations;
• and complex authorization.

Often unnecessary for core commercial fields.

124. Operational Transformation

Suitable for collaborative text.

Less natural for product graph and pricing semantics.

125. CRDT

Useful for some shared structures.

Not a replacement for commercial invariants.

126. Presence

Show active users and sections.

Presence is advisory, not authority.

127. Cursor/Section Indicator

Can reduce conflicts.

128. Comment

A comment is collaboration data, not commercial revision by default.

129. Mention

Can notify another stakeholder.

130. Review Request

Asks another role to review a section.

131. Task

A collaboration task can track:

• owner;
• due date;
• state;
• and resolution.

132. Comment Thread

Should reference:

• quote;
• revision;
• item/field;
• and optional snapshot.

133. Comment on Mutable Draft

A field may change after comment.

Store referenced version.

134. Resolved Comment

Resolution is collaboration state, not proof of domain validity.

135. Internal versus External Comment

Keep customer-visible comments separated.

136. Sensitive Comment

May contain cost, margin, or legal advice.

Apply access and retention.

137. Review Gate

A quote section may require review before finalization.

This is separate from formal commercial approval.

138. Collaboration Audit

Record meaningful:

• edits;
• comments;
• assignments;
• reviews;
• and merges.

139. Author Attribution

Each revision and material change needs author identity.

140. Co-Authoring

A revision can have:

• creator;
• contributors;
• finalizer;
• and approvers.

141. Change Set

A Change Set groups related edits.

Example:

Change Set CS-44
- update 20 site bandwidths
- replace router model
- recalculate price

142. Change Set Identity

Useful for:

• undo;
• review;
• audit;
• and merge.

143. Semantic Diff

Compare revisions by domain meaning.

144. Header Diff

Changes:

• customer;
• account;
• currency;
• term;
• and validity.

145. Item Diff

Changes:

• added;
• removed;
• replaced;
• moved;
• quantity;
• action;
• and relationship.

146. Configuration Diff

Changes:

• characteristic;
• source/provenance;
• and derived effects.

147. Price Diff

Changes:

• component;
• rate;
• adjustment;
• tax;
• total;
• validity;
• and provenance.

148. Term Diff

Changes exact structured and textual terms.

149. Approval Diff

Shows:

• required;
• added;
• expired;
• superseded;
• and invalidated decisions.

150. Document Diff

Proposal text/layout changes can be compared separately from commercial semantic diff.

151. Diff Noise

Avoid showing:

• generated IDs;
• timestamps;
• sort order;
• and technical metadata

as business changes.

152. Materiality Classification

A change may be:

• cosmetic;
• informational;
• configuration;
• pricing;
• contractual;
• approval-impacting;
• or order-impacting.

153. Change Impact

For each change identify:

• revalidation;
• repricing;
• requalification;
• reapproval;
• re-presentation;
• reacceptance;
• and order impact.

154. Compare Revisions

A comparison should support:

• summary;
• item tree;
• monetary delta;
• term delta;
• and issue delta.

155. Compare Alternatives

May include:

• price;
• feasibility;
• lead time;
• margin band;
• and risk.

156. Revision Changelog

Human-readable summary generated from semantic diff.

157. User-Edited Summary

Allow human refinement while retaining machine diff.

158. Revision Lineage API

Possible response:

revisionId
revisionNumber
parentRevision
branch
state
createdBy
createdAt
reason
checksum

159. Revision Read API

Fetch exact immutable snapshot.

160. Working Draft API

Returns mutable current state with concurrency token.

161. Compare API

Inputs:

• left revision;
• right revision;
• scope;
• and visibility role.

162. Merge API

A command with:

• source revisions;
• common ancestor;
• conflict resolutions;
• expected target version;
• and idempotency key.

163. Finalize API

Should reference expected partition versions and readiness result.

164. Generic PUT Risk

Replacing entire quote can overwrite concurrent work.

165. Patch Risk

Generic JSON Patch does not understand domain invariants.

166. Domain Commands

Examples:

• ChangeQuoteTerm;
• AddConfiguredItem;
• RemoveQuoteItem;
• SetCustomerContext;
• ApplyPriceAdjustment;
• CreateRevision;
• MergeQuoteBranches;
• FinalizeRevision.

167. Event Model

Representative events:

• QuoteRevisionCreated;
• QuoteRevisionFinalized;
• QuoteBranchCreated;
• QuoteBranchMerged;
• QuoteEditConflictDetected;
• QuoteRevisionSuperseded.

168. Event Payload

Include:

• quote;
• revision;
• parent;
• branch;
• reason;
• actor;
• and version.

Do not publish full confidential snapshot broadly.

169. Outbox

State and event intent should be atomic.

170. Event Ordering

Use quote identity and revision sequence.

171. Duplicate Event

Consumers must be idempotent.

172. Search Projection

Search may index current/latest revision.

Historical revisions need explicit query.

173. Latest Revision Ambiguity

Define:

• latest created;
• latest finalized;
• latest presented;
• latest accepted;
• or current working.

Never use generic latest without semantics.

174. Current Revision

Could mean current working branch.

175. Active Presented Revision

Could differ from current working revision.

176. Accepted Revision

May differ from newest draft if post-acceptance amendment is being prepared.

177. Downstream Identity

Order conversion must reference exact accepted revision.

178. Approval Identity

Approval references exact revision and snapshots.

179. Document Identity

Proposal references exact revision.

180. CRM Identity

CRM may only store quote ID and current business summary.

Do not let CRM “latest version” overwrite authoritative revision semantics.

181. Cache Key

Cache by:

• quote ID;
• revision ID;
• working version;
• and tenant.

182. Immutable Revision Cache

Safe to cache long because content is immutable.

183. Working Draft Cache

Requires version-aware invalidation.

184. Stale Cache Write

Never overwrite current store from stale cached draft.

185. Security

Revision history may expose:

• previous customer prices;
• internal negotiation;
• rejected terms;
• and confidential comments.

186. Revision Visibility

Roles may see:

• current revision only;
• all commercial revisions;
• internal branches;
• or accepted evidence only.

187. Customer Visibility

Customer portal should not expose internal alternatives or rejected internal drafts unless intended.

188. Branch Authorization

Only authorized users may view or edit strategic alternatives.

189. Cross-Tenant Clone Risk

Never allow quote copy to cross tenant without explicit migration/export process.

190. Audit Read Access

Access to historical pricing and approvals may itself be audited.

191. Metrics

Useful metrics:

• revisions per quote;
• conflicts per 100 edits;
• merge rate;
• abandoned branch count;
• and autosave failures.

192. Negotiation Metrics

• number of presented revisions;
• price delta by round;
• term changes;
• and time between revisions.

193. Collaboration Metrics

• active contributors;
• review wait time;
• conflict resolution time;
• and section bottlenecks.

194. Concurrency SLI

Examples:

• zero silent lost updates;
• conflict response within target latency;
• and all accepted revisions immutable.

Internal targets must be verified.

195. Stuck Branch

A branch may remain open after another alternative is accepted.

Need cleanup/retention policy.

196. Orphan Draft

A working revision with no owner or active process.

197. Revision Reconciliation

Detect:

• multiple active presented revisions when prohibited;
• accepted revision not terminal;
• proposal pointing to wrong checksum;
• and order referencing non-accepted revision.

198. Recovery

Explicit operations:

• RestoreWorkingRevision;
• RebuildRevisionSnapshot;
• SupersedeBranch;
• ResolveMergeConflict;
• CorrectRevisionMetadata.

199. Direct Data Repair

Must preserve:

• original revision;
• audit;
• checksum;
• and downstream references.

200. Revision Incident

Examples:

• accepted revision overwritten;
• concurrent edit lost;
• branch merge combines wrong customer context;
• proposal uses stale revision;
• and order uses current draft instead of accepted revision.

201. Incident Containment

Possible:

• freeze quote;
• block presentation/acceptance;
• block conversion;
• restore immutable snapshot;
• and identify affected downstream objects.

202. Revision Smells

• one mutable quote row;
• revision number increments on every autosave;
• and accepted quote remains editable.

203. Concurrency Smells

• last-write-wins;
• timestamp version;
• whole-quote lock for days;
• and no conflict response.

204. Collaboration Smells

• comments detached from revision;
• hidden ownership;
• and merge done outside system.

205. Branching Smells

• alternatives represented by duplicate unrelated quotes;
• no parent lineage;
• and approval copied blindly.

206. Diff Smells

• raw JSON diff;
• technical IDs dominate;
• and no impact classification.

207. Anti-Patterns

Revision Equals Every Save

Commercial history becomes noisy.

Version Equals Revision

Concurrency and business meaning are conflated.

Edit Accepted Quote

Historical evidence is destroyed.

Whole-Quote Last-Write-Wins

Silent data loss.

Copy Approval on Clone

Authority and evidence no longer match.

Merge Price Snapshots

Merged revision is not repriced.

Generic Latest Revision

Downstream may use wrong commercial artifact.

208. Revision Definition Template

## Quote Identity

## Revision Identity and Number

## Parent Revision

## Branch / Alternative Group

## Reason

## State

## Created By / At

## Content Manifest

## Price Snapshot

## Terms

## Attachments

## Readiness Evidence

## Approval References

## Proposal References

## Checksum

## Schema Version

## Supersession

209. Concurrency Contract Template

Resource:
Concurrency scope:
Version/token:
Expected version:
Conflict behavior:
Merge support:
Idempotency:
Lock/lease:
Recovery:

210. Branch Template

Branch ID:
Quote:
Base revision:
Purpose:
Owner:
Alternative group:
Current head:
Visibility:
Merge policy:
Closure policy:

211. Merge Conflict Template

Conflict ID:
Common ancestor:
Source A:
Source B:
Scope:
Type:
A value/change:
B value/change:
Recommended resolution:
Resolved by:
Result:

212. Semantic Diff Template

## Revisions Compared

## Context Changes

## Item Changes

## Configuration Changes

## Price Changes

## Term Changes

## Approval Changes

## Document Changes

## Readiness Changes

## Required Follow-Up

213. Finalization Manifest Template

Quote/revision:
Header version:
Context epoch:
Item partition versions:
Price snapshot IDs:
Term versions:
Attachment checksums:
Readiness result:
Content checksum:
Finalized by:
Finalized at:

214. Worked Example: Sales and Presales Concurrent Edit

Sales changes:

• contract term 24 -> 36 months.

Presales changes:

• router model.

If section/item versions are independent:

• both changes can commit;
• pricing/readiness become stale;
• finalization recalculates and validates.

215. Worked Example: Same Field Conflict

Two users change recurring discount.

First commits version 31.

Second sends expected version 30.

Server returns conflict with:

• current value;
• user value;
• required merge action.

216. Worked Example: Parent Removal Race

User A removes bundle parent.

User B edits child.

Child command fails because:

• parent relationship no longer exists;
• or expected context epoch changed.

217. Worked Example: Alternative Branches

Revision 3 creates:

• Fiber branch;
• Wireless branch.

Both are independently configured and priced.

Customer chooses Fiber.

Wireless branch becomes closed alternative, not deleted.

218. Worked Example: Presented Revision Change

Revision 5 is presented.

Customer requests lower quantity.

System creates Revision 6.

Revision 5 remains immutable and is superseded after Revision 6 presentation.

219. Worked Example: Clone for New Customer

Quote copied to another customer.

System:

• creates new Quote ID;
• removes approvals and acceptance;
• resets contract/account context;
• marks qualification and pricing stale;
• records source quote lineage.

220. Worked Example: Merge Branches

Customer wants Fiber design from branch A and support package from branch B.

System creates branch C from common ancestor and applies selected semantic changes.

Branch C is fully revalidated and repriced.

221. Worked Example: Autosave Conflict

Offline user submits queued change after another user finalized revision.

System does not overwrite finalized revision.

It offers:

• rebase to new draft;
• create branch;
• or discard.

222. Worked Example: Accepted Revision Downstream

Quote has:

• current working Revision 9;
• active amendment draft.

Original order conversion references Accepted Revision 8.

Generic “latest revision” would be incorrect.

223. Senior Engineer Operating Model

Separate revision and version

Commercial history and concurrency are different.

Make accepted evidence immutable

No exception through ordinary edit path.

Design branch semantics

Alternatives, negotiation rounds, and merges.

Use optimistic concurrency by default

With narrow locks for critical transitions.

Detect write skew

Finalization must protect quote-level invariants.

Build semantic diff

Raw JSON diff is not operationally useful.

Preserve downstream identity

Approval, proposal, order, and billing reference exact revision.

Support large-quote collaboration

Item/section versions plus finalization manifest.

Operate conflict and branch lifecycle

Metrics, recovery, and reconciliation.

224. Internal Verification Checklist

Revision model

• Is revision a first-class entity or just a number?
• What changes create a new commercial revision?
• Are finalized, presented, and accepted revisions immutable?
• Is parent/branch lineage retained?

Versioning

• What is used for optimistic concurrency?
• Is aggregate version separate from revision number?
• Are item/section versions supported?
• Is there a context epoch for quote-wide changes?

Collaboration

• Is editing single-user, section-owned, optimistic multi-user, or branch-based?
• Are comments tied to exact revisions/fields?
• Can users see active editors?
• How are reviews and tasks represented?

Conflict handling

• Are lost updates prevented?
• Are semantic conflicts classified?
• Is automatic merge limited to safe cases?
• Can users rebase or create a branch?

Branch and clone

• Are alternatives first-class?
• What data is copied?
• Are approval, qualification, pricing, and promotion reservations invalidated?
• Can branches merge?

Diff and history

• Can users compare revisions semantically?
• Are monetary, configuration, term, and approval deltas separated?
• Can every historical revision be reconstructed?
• Are checksums/schema versions stored?

Downstream identity

• Which revision does proposal reference?
• Which revision does approval reference?
• Which revision does order conversion use?
• Is “latest” semantics avoided?

Operations

• Are conflict, branch, and autosave metrics available?
• Can accepted revision mutation be detected?
• What recovery commands exist?
• What historical incidents expose concurrency gaps?

225. Practical Exercises

Exercise 1 — Revision policy

Classify 30 quote changes as autosave, technical version, commercial revision, or new Quote.

Exercise 2 — Concurrency scope

Choose whole-quote, item, section, or hybrid versioning for a 1,000-item quote.

Exercise 3 — Branching

Model two alternatives and a semantic merge.

Exercise 4 — Conflict response

Design API response and UI workflow for same-field conflict.

Exercise 5 — Semantic diff

Compare two quote revisions across context, products, price, terms, and readiness.

Exercise 6 — Downstream identity

Trace exact revision references through approval, proposal, acceptance, order, and billing.

226. Part Completion Checklist

You are done if you can:

• distinguish commercial revision and technical version;
• define immutable revision states;
• preserve revision lineage;
• model alternatives and branches;
• design semantic merge/conflict handling;
• use optimistic concurrency;
• prevent lost updates and write skew;
• support autosave and offline retry;
• create useful semantic diffs;
• bind downstream artifacts to exact revision;
• and create an internal revision/concurrency verification backlog.

227. Key Takeaways

1. Revision and version are different.
2. Not every save creates a commercial revision.
3. Accepted revisions are immutable.
4. Alternatives need branch semantics.
5. Merge must be domain-aware.
6. Optimistic concurrency fits long-running deals.
7. Partitioned editing needs a finalization barrier.
8. Semantic diff is more valuable than raw JSON diff.
9. Downstream systems must reference exact revision.
10. Internal CSG revision and collaboration behavior must be verified.

228. References

Conceptual baseline:

• General CPQ revision, negotiation, alternative, clone, and collaborative editing practices.
• Optimistic concurrency, ETag, compare-and-set, idempotent commands, and semantic conflict handling.
• Branching, three-way merge, immutable snapshots, event sourcing, and audit-history concepts.
• Domain-Driven Design aggregate boundaries, invariants, and versioned domain operations.

These references do not define internal CSG quote revision or collaboration implementation.