Part 012 — Catalog Publication, Version Identity, Effective Dates, and Retirement

Positioning

Catalog adalah temporal system.

Offering dan rules tidak hanya:

• ada;
• atau tidak ada.

Mereka memiliki:

• draft lifecycle;
• publication lifecycle;
• effective validity;
• market scope;
• deprecation;
• retirement;
• supersession;
• and historical obligations.

Kesalahan versioning dapat membuat:

• quote tidak dapat direproduksi;
• order memakai mapping baru;
• inventory kehilangan referensi;
• dan customer menerima price atau product yang tidak sesuai waktu.

Core thesis: catalog lifecycle harus memisahkan authoring state, publication state, dan business-effective time. Published content harus reproducible, historical references harus tetap resolvable, dan setiap change harus memiliki compatibility policy.

1. Three Temporal Dimensions

Catalog changes commonly have three time dimensions:

1. Authoring time.
2. Publication/activation time.
3. Business effective time.

They are not the same.

2. Authoring Time

When content is created or edited.

A draft may change many times before publication.

3. Publication Time

When a coherent catalog artifact is released to runtime.

4. Activation Time

When runtime begins using a publication.

Publication may be prepared before activation.

5. Effective Time

When a business definition or rule is considered valid.

Example:

• publication active today;
• price effective next month.

6. Transaction Time

When system recorded the change.

Useful for audit.

7. Valid Time

When the business fact is valid.

Temporal models may need both valid and transaction time.

8. Bitemporal Thinking

Bitemporal model distinguishes:

• what the system knew when;
• and what was considered true for the business period.

Useful for backdated correction.

9. Catalog Entity Lifecycle

Possible lifecycle:

Draft
-> InReview
-> Approved
-> Published
-> Active
-> Deprecated
-> Retired

Actual states should match business needs.

10. Draft

Draft is mutable and not available for normal runtime use.

It may support:

• collaboration;
• validation;
• and preview.

11. In Review

Content is being reviewed for:

• product semantics;
• price;
• compatibility;
• security;
• and operational impact.

12. Approved

Approved means ready for publication under governance.

It does not necessarily mean active.

13. Published

Published content has immutable identity and is available as an artifact.

14. Active

Runtime may select the entity for applicable context and effective date.

15. Deprecated

Deprecated means:

• still resolvable;
• possibly still usable for existing lifecycle;
• but discouraged or unavailable for new sales.

16. Retired

Retired means no longer available for selected new operations.

Historical resolution usually remains required.

17. Deleted

Hard deletion should be rare.

Only safe when:

• never published;
• no references;
• no legal/operational need;
• and governance permits.

18. Archived

Archived content is moved from active operational storage but remains retrievable.

19. Lifecycle per Entity Type

Different types may have different lifecycle:

• Specification;
• Offering;
• Price;
• Relationship;
• Rule;
• Template;
• Mapping.

A single generic lifecycle may be insufficient.

20. Specification Retirement

Before retirement, inspect:

• active offerings;
• open quotes;
• inventory;
• and migration paths.

21. Offering Retirement

May block:

• new quote creation;
• new add orders;
• or renewal.

But still allow:

• modify;
• support;
• terminate;
• and historical display.

22. Price Retirement

A price can expire while offering remains active.

Need replacement price or no-sale policy.

23. Rule Retirement

Removing a rule can change configuration behavior.

Historical transactions should preserve the old evaluation context.

24. Mapping Retirement

Order-transformation mappings must remain resolvable for:

• accepted quote;
• pending order;
• and recovery.

25. Version Identity

A version identifies a specific semantic state.

Possible components:

• entity ID;
• version number;
• publication ID;
• schema version;
• and effective period.

26. Entity Version

Tracks evolution of one catalog entity.

27. Publication Version

Identifies a coherent set of entities and rules.

28. Schema Version

Identifies structure of catalog metadata.

29. Engine Version

Identifies runtime interpretation implementation.

30. Rule Version

Identifies decision logic.

31. Mapping Version

Identifies transformation from product/quote to order/fulfillment.

32. Why One Version Is Not Enough

Reproduction may require:

Catalog publication
+ entity version
+ pricing rule version
+ engine version
+ mapping version

33. Mutable Version Anti-Pattern

If version 7 can be edited after publication, historical references are unreliable.

34. Immutable Version

Correction creates:

• version 8;
• or corrective publication.

35. Major/Minor Versioning

Semantic versioning may help but should reflect domain behavior.

Example:

• minor = additive;
• major = breaking.

Do not assume software SemVer maps perfectly to catalog.

36. Monotonic Sequence

Simple numeric sequence can work when semantics are captured elsewhere.

37. Content Hash

A checksum can prove artifact identity.

Useful for:

• cache;
• deployment;
• and audit.

38. Version Alias

Aliases like current or latest are convenient for runtime lookup.

Historical transactions should store immutable version, not alias.

39. Publication Boundary

A publication should be a coherent, validated set.

It may contain:

• offerings;
• specifications;
• prices;
• relationships;
• rules;
• mappings;
• and templates.

40. Partial Publication

Publishing only one entity can be safe if dependencies are versioned and compatible.

Otherwise use atomic publication set.

41. Atomic Activation

A coherent publication should activate atomically from consumer perspective.

Avoid half-old, half-new behavior.

42. Blue/Green Catalog Activation

Run two publications:

• current;
• candidate.

Switch selection by pointer, tenant, or feature flag.

43. Canary Catalog Activation

Activate for:

• one tenant;
• one market;
• one channel;
• or internal users.

44. Shadow Evaluation

Evaluate candidate catalog in parallel without affecting output.

Compare:

• configuration;
• price;
• validation;
• and order mapping.

45. Publication Manifest

A manifest may include:

publicationId
createdAt
approvedBy
contentHashes
entityVersions
schemaVersion
engineCompatibility
effectiveScope

46. Dependency Lock

Publication may pin:

• child versions;
• price versions;
• rule versions;
• and templates.

47. Version Range

Version range increases flexibility.

But runtime result may change without publication change.

Use cautiously.

48. Effective Period

A common interval:

validFor = [start, end)

Define inclusivity.

49. Open-Ended Validity

End may be absent.

Still define retirement behavior.

50. Overlapping Validity

Two versions may be valid simultaneously for different:

• markets;
• channels;
• tenants;
• or priorities.

Unintended overlap should be detected.

51. Gap in Validity

If no active price/offering exists for a period, quote creation may fail.

Publication validation should detect critical gaps.

52. Future-Dated Change

Useful for scheduled commercial launch.

Need:

• timezone;
• activation job;
• and rollback.

53. Backdated Change

Backdating can affect historical interpretation.

Use only with explicit correction policy.

54. Timezone

Business effective time may depend on market timezone.

Do not assume UTC midnight.

55. Daylight Saving

Where relevant, test ambiguous or missing local times.

56. Catalog Selection

Runtime selection may consider:

• publication;
• entity version;
• effective time;
• tenant;
• market;
• channel;
• and customer context.

57. Current Catalog

“Current” must mean current for:

• which tenant;
• which market;
• which time;
• and which channel.

58. Point-in-Time Query

Support query:

What catalog was valid for Tenant X on 2026-06-15 at 10:00 local time?

This is essential for audit.

59. Reproducible Quote

To reproduce a quote:

• resolve publication;
• entity versions;
• price/rule versions;
• and engine behavior.

60. Pinning Strategy

Transactions may pin:

• publication;
• individual entities;
• or snapshot.

Use hybrid for resilience.

61. Draft Configuration Pinning

A session may pin catalog at creation.

Benefits:

• stable behavior.

Risks:

• long-lived stale session.

62. Refreshable Draft

Allow explicit refresh with:

• diff;
• migration;
• revalidation;
• and user confirmation.

63. Quote Pinning

Draft quote may remain pinned or support controlled upgrade.

Accepted quote should normally remain immutable.

64. Order Pinning

Order conversion should use accepted quote context.

Do not resolve current mapping silently.

65. Inventory Resolution

Inventory should remain resolvable against historical catalog definitions.

66. Open Session Policy

Possible policies:

• expire session;
• continue old version;
• prompt upgrade;
• force migration;
• or invalidate.

67. Draft Quote Policy

Possible policies:

• preserve;
• reprice;
• migrate;
• or require manual review.

68. Approved Quote Policy

A change may invalidate:

• price;
• approval;
• terms;
• or configuration.

Use explicit invalidation triggers.

69. Presented Quote Policy

Customer-facing offer should not change silently.

70. Accepted Quote Policy

Accepted revision is historical commitment.

Catalog changes should not reinterpret it.

71. In-Flight Order Policy

Keep:

• decomposition/mapping version;
• and child plan lineage.

72. Retired Offering Policy

Define allowed operations:

73. Deprecation Window

Deprecation allows time for:

• migration;
• customer communication;
• and downstream preparation.

74. End-of-Sale

Offering no longer available for new sale.

75. End-of-Support

Support or modification capability may end later.

76. End-of-Life

Full retirement after obligations end.

77. Supersession

A successor relationship should include:

• target;
• reason;
• effective date;
• and migration policy.

78. Replacement Chain

Avoid long ambiguous chains:

A -> B -> C -> D

Provide resolved current successor and history.

79. Rollback

Rollback options:

• reactivate previous publication;
• shift pointer;
• disable scope;
• or publish correction.

80. Rollback Limitation

Transactions created under bad publication may require:

• revalidation;
• correction;
• customer communication;
• and data repair.

Rollback alone is not enough.

81. Roll-Forward

Often safer:

• publish corrected version;
• preserve bad version history;
• and migrate affected drafts.

82. Emergency Disable

An offering or rule may need immediate disable.

Need:

• scoped kill switch;
• audit;
• and impact handling.

83. Kill Switch Risk

A global kill switch may affect:

• unrelated tenants;
• open quotes;
• and orders.

Scope carefully.

84. Publication Validation

Validate:

• schema;
• references;
• rules;
• prices;
• dates;
• compatibility;
• and mappings.

85. Temporal Validation

Check:

• overlaps;
• gaps;
• invalid intervals;
• and timezone consistency.

86. Dependency Validation

Check all pinned dependencies exist and are active for intended period.

87. Consumer Compatibility

Validate consumers can read:

• new enum;
• new characteristic;
• and new structure.

88. Scenario Validation

Run critical journeys against effective dates.

89. Future-State Test

Test candidate publication as of future activation time.

90. Historical Regression

Ensure old quotes/orders remain interpretable.

91. Diff

A semantic diff should show:

• added/removed entity;
• changed lifecycle;
• changed effective date;
• changed price;
• changed relationship;
• changed mapping;
• and changed behavior.

92. Impact Analysis

Identify:

• tenants;
• markets;
• channels;
• open sessions;
• draft quotes;
• accepted quotes;
• in-flight orders;
• and inventory.

93. Change Classification

Possible classes:

• cosmetic;
• additive;
• behavior-changing;
• pricing;
• breaking;
• operational;
• and legal.

94. Approval Workflow

High-risk publication may require:

• Product;
• Pricing;
• Architecture;
• Legal;
• Security;
• and Operations.

Avoid unnecessary approvals for low-risk changes.

95. Separation of Duties

Author, reviewer, publisher, and activator may be distinct.

96. Publication Audit

Record:

• content;
• author;
• reviewer;
• approver;
• activation;
• and rollback.

97. Environment Promotion

Promote same artifact across:

• test;
• staging;
• production.

Avoid manual recreation.

98. Environment-Specific Overlay

Separate semantic content from:

• endpoint;
• credential;
• and environment IDs.

99. Tenant Promotion

Some tenants may adopt later.

Need multiple active publications by scope.

100. Compatibility Matrix

Track:

101. Engine Compatibility

New catalog schema may require new runtime engine.

Coordinate rollout.

102. Backward-Compatible Engine

Engine should ideally read current and prior supported schemas.

103. Forward Compatibility

Old engine usually cannot safely interpret unknown new semantics.

Block activation.

104. Catalog Migration

Migration may transform:

• draft definitions;
• open configurations;
• and runtime artifacts.

105. Data Migration

Catalog schema migration should preserve:

• IDs;
• versions;
• references;
• and audit.

106. Transaction Migration

Open quote migration is a business operation, not only data conversion.

107. Dry Run

Simulate:

• publication;
• activation;
• transaction migration;
• and rollback.

108. Migration Report

Include:

• migrated;
• unchanged;
• invalid;
• conflict;
• and manual review.

109. Observability

Track:

• active publication by scope;
• cache version;
• selection failures;
• stale transaction count;
• migration errors;
• and rollback events.

110. Publication SLI

Examples:

• publication activation success;
• propagation time;
• runtime consistency;
• and error rate.

111. Catalog Drift

Drift occurs when:

• nodes use different publication;
• cache stale;
• search index behind;
• or on-prem customer runs old version.

112. Drift Detection

Use:

• publication ID;
• checksums;
• heartbeat;
• and runtime diagnostics.

113. On-Prem Version Reality

On-prem customers may run different:

• product version;
• catalog publication;
• schema;
• and integrations.

Compatibility window matters.

114. Multi-Version Support

Support may require:

• N and N-1;
• per-customer branches;
• or migration adapters.

Avoid indefinite support without policy.

115. Customer-Specific Publication

A customer may have overlay/version.

Need:

• base relation;
• delta;
• and upgrade path.

116. Branching Risk

Long-lived customer catalog branches create:

• merge complexity;
• security drift;
• and upgrade cost.

117. Overlay Upgrade

When base changes, evaluate:

• conflict;
• inherited behavior;
• and customer-specific overrides.

118. Lifecycle Observability for Support

Support should answer:

• what publication was used;
• what is current;
• whether transaction is stale;
• and what migration is available.

119. Historical Query

Support and audit need point-in-time reconstruction.

120. Catalog Lifecycle Smells

• mutable published records;
• latest alias stored in quote;
• hard deletion;
• no effective timezone;
• direct production edit;
• no semantic diff;
• and open quote policy undefined.

121. Versioning Smells

• version is timestamp only;
• engine version ignored;
• rule versions unavailable;
• current mapping used for old quote;
• and child versions resolved dynamically.

122. Effective-Date Smells

• overlapping prices;
• midnight ambiguity;
• no gap detection;
• future change activated manually;
• and backdated changes without audit.

123. Retirement Smells

• retired entity deleted;
• no successor;
• inventory cannot resolve;
• existing customer modify path broken;
• and billing loses reference.

124. Anti-Patterns

Latest-is-best

Historical transactions always read current catalog.

Mutable publication

Version identity has no meaning.

Retirement equals delete

History and support break.

Rollback without transaction analysis

Affected quotes remain incorrect.

One global catalog

Tenant and market variation hidden in runtime conditionals.

125. Lifecycle Definition Template

## Entity Type

## States

## Allowed Transitions

## Authoring Policy

## Publication Policy

## Activation Policy

## Effective Period

## Deprecation Policy

## Retirement Policy

## Historical Resolution

## Rollback / Roll-Forward

## Ownership

126. Publication Manifest Template

Publication ID:
Schema version:
Created at:
Approved at:
Activated at:
Tenant/market/channel scope:
Entity versions:
Rule versions:
Mapping versions:
Checksums:
Engine compatibility:
Rollback target:

127. Effective-Dating Template

Business timezone:
Valid from:
Valid to:
Boundary convention:
Overlap policy:
Gap policy:
Backdate policy:
Late-event policy:

128. Transaction Compatibility Template

Transaction type:
Pinned version:
Refresh allowed:
Migration trigger:
Approval impact:
Price impact:
Customer communication:
Fallback:

129. Worked Example: Future Price

Current recurring price:

New price:

• 110 effective August 1.

Need:

• future-dated price version;
• overlap/gap validation;
• quote policy;
• accepted quote preservation;
• and cache activation.

130. Worked Example: Open Draft

Draft quote created on publication 20.

Publication 21 changes mandatory component.

Policy:

• draft remains pinned;
• user may upgrade explicitly;
• diff shown;
• configuration revalidated.

131. Worked Example: Accepted Quote

Accepted quote uses offering v7 and price v12.

Catalog moves to offering v8.

Order conversion uses accepted snapshot/version, not latest v8.

132. Worked Example: Retired Offering

Offering retired for new sale.

Installed products remain:

• visible;
• billable;
• supportable;
• and terminable.

Upgrade path points to successor.

133. Worked Example: Broken Publication

New relationship makes bundle unsatisfiable.

Canary metrics show validation spike.

Action:

• stop activation;
• switch back to prior publication;
• identify affected drafts;
• publish corrected version.

134. Worked Example: Engine Upgrade

Catalog schema v5 requires engine 3.2.

Activation blocked until all runtime nodes report compatible engine.

135. Worked Example: On-Prem Customer

Customer runs platform version older than current cloud.

Catalog publication must remain compatible or use customer-specific supported branch with explicit end-of-support.

136. Senior Engineer Operating Model

Separate lifecycle clocks

Authoring, publication, and effective time.

Protect immutability

Published versions must be stable.

Pin transactions

Do not store latest.

Design compatibility

Draft, accepted, order, and inventory policies.

Prefer semantic diff

Raw data diff is insufficient.

Plan retirement

Support and migration matter.

Treat rollback as partial response

Analyze affected transactions.

Make versions observable

Runtime and support tooling.

137. Internal Verification Checklist

Lifecycle

• What states exist for specifications, offerings, prices, rules, and mappings?
• Are published entities immutable?
• Who can transition lifecycle state?

Versioning

• What identifies entity version?
• Is there a publication version?
• Are engine, rule, and mapping versions recorded?
• Can exact historical content be retrieved?

Effective dating

• What timezone applies?
• What interval convention is used?
• Are overlaps and gaps validated?
• Are future-dated changes automated?

Transactions

• Are configuration sessions pinned?
• How do draft quotes refresh?
• Are accepted quotes immutable?
• Which mapping is used for order conversion?

Retirement

• What operations remain allowed?
• Are successors modeled?
• Can inventory and billing resolve retired entities?
• Is hard deletion possible?

Deployment

• Is publication promoted as immutable artifact?
• Is canary/shadow activation supported?
• How is rollback performed?
• How is drift detected?

On-prem

• How many versions are supported?
• How are customer-specific catalogs upgraded?
• What is the end-of-support policy?
• Are overlays rebased safely?

138. Practical Exercises

Exercise 1 — Three clocks

Map authoring, activation, and effective time for one price change.

Exercise 2 — Transaction pinning

Define policies for session, draft quote, accepted quote, order, and inventory.

Exercise 3 — Retirement plan

Retire one offering without breaking installed customers.

Exercise 4 — Semantic diff

Design a publication diff for business and technical reviewers.

Exercise 5 — Rollback analysis

List what rollback does and does not repair after bad activation.

Exercise 6 — On-prem compatibility

Create a support matrix for multiple platform/catalog versions.

139. Part Completion Checklist

You are done if you can:

• distinguish authoring, publication, activation, and effective time;
• design immutable catalog versions;
• separate entity, publication, schema, engine, rule, and mapping versions;
• perform point-in-time resolution;
• pin transactions safely;
• define draft and accepted-quote compatibility;
• manage deprecation and retirement;
• design canary, rollback, and roll-forward;
• detect catalog drift;
• and create an internal lifecycle verification backlog.

140. Key Takeaways

1. Catalog is a temporal system.
2. Authoring state and business effective time are different.
3. Published versions should be immutable.
4. Transactions must not store latest.
5. Reproduction requires multiple version dimensions.
6. Draft and accepted transactions need different policies.
7. Retirement is not deletion.
8. Rollback does not automatically repair created transactions.
9. Runtime version must be observable.
10. Internal lifecycle and version policy must be verified.

141. References

Conceptual baseline:

• General product-catalog lifecycle, immutable publication, and effective-dating practices.
• Temporal data, bitemporal modeling, versioning, and point-in-time queries.
• Continuous delivery, canary release, rollback, and compatibility concepts.
• TM Forum ProductOffering and ProductSpecification lifecycle vocabulary.

These references do not define internal CSG publication or versioning implementation.