User Journey: Withdraw or replace a published curve

Table of Contents

This page documents a user journey: A trader undoes or supersedes a published curve after an error, with the reason kept and the approver's decision where the kind asks for one.

A user journey describes what one person is trying to do, before anything is built. It is a design document that outlives any sprint, so it names the screens, the entity fields each screen shows, and the operations and messages each step needs.

1. Goal

"That curve is published and wrong. I want it taken back, or a corrected one in its place, and I want the record to say why." The journey is done when the published curve is withdrawn or superseded, the reason is kept against the act, and the consumers that read it have been told.

2. Actor and trigger

The actor is the trader who owns the published curve. Where the kind's approvals_required is one or more, an approver holding the kind's decide_permission_code is a second actor on the same act, exactly as in Decide a publish. The trigger is an error found after publication: a stale pillar, a wrong quote, a recipe changed after the fact. The journey starts at the published curve and ends when the withdrawal or the replacement is live. It undoes what Publish the approved set did.

Withdrawal and replacement are two answers to one problem. Withdrawal takes the curve out of use; replacement puts a corrected version in its place. The approval count for a withdrawal is configurable like a publish's: the kind carries approvals_required, so a tenant may let a trader withdraw alone (count zero) or require one or more approvals. A refusal is final and an approval is reversed rather than edited, as for every kind.

3. Steps

  1. Find the published curve. The trader opens the curve by its oresmd_uri or finds it in the curve list. The system shows the series and its latest points. The read that serves the curve states whether it is published, and an unpublished curve is the one to look at twice. No read lists the tenant's published curves; see What is missing.
  2. Read what is published. The trader reads the points the system is using. The snapshot read states the instant a person published the set, the account that published it, the as-of the set was built at, and the request that authorised it, so the trader reads the act and not only the values.
  3. Read the trail. The trader opens the curve's history and reads every version with the field-level difference from the one before, so the error and the version that introduced it are both visible.
  4. State the reason and choose. The trader writes why the curve must be undone and chooses Withdraw or Replace. For a replacement the trader names the corrected set or its as-of.
  5. Raise the request. The trader chooses Raise withdrawal request or Raise replacement request. The system raises an approval request for the signed-in trader, waiting, under the withdrawal kind. No market-data withdrawal kind is seeded; see What is missing.
  6. Watch for the decision, or publish at once. Where the kind's approvals_required is zero the withdrawal is immediate; where it is one or more, an approver decides in the queue. An approver who is also the asker is refused.
  7. Apply the withdrawal or the replacement. Once approved, the system makes the withdrawal or the replacement live: the withdrawn curve stops being the one pricing and reporting use, or the replacement becomes it. No such operation exists; see What is missing.
  8. See the consumers change. The consumers that read the curve pick up the change at their next read. The system tells them a published curve changed. No notification kind exists for this; see What is missing.
  9. Confirm the audit. The trader re-reads the history and sees the withdrawal or the replacement as a new version, with the reason and the decision attached. A withdrawal is not a deletion: the published version stays in the history.
  10. Leave. The trader goes back to the curve list.

Steps 5 to 7 are the ones that carry state: the request waits on a person between the ask and the act, and the act is applied by the component that owns the kind. Nothing here overwrites history; the withdrawal is a new version.

4. Screens and wireframes

One screen. The published curve sits at the top, its published versions and the proposed change sit in the middle, and the reason, the action and the effect on consumers sit at the bottom, so the trader reads what is live and what would replace it before the act.

wireframe_withdraw-or-replace-a-published-curve.png

Figure 1: Withdraw or replace: the published curve, its versions, the reason and the choice, the approvals, and the consumers affected.

The action controls are disabled while no withdrawal or replacement operation exists, and the panel says so, so the screen does not pretend the act succeeded.

5. Prototype

A static page at doc/prototypes/market_data/withdraw-or-replace-a-published-curve/index.html: mock data only, no backend, no build step and no session. It argues that a wrong publish is undone as an act with a reason, and the withdrawal can need its own approval.

Variants
a the withdraw form, b the replace form, c the retired version against its replacement
States
no-approval, approval, withdrawn
Source
doc/prototypes/market_data/withdraw-or-replace-a-published-curve/index.html
Open
/OreStudio/doc/prototypes/market_data/withdraw-or-replace-a-published-curve/ once the site is built, or the file directly

6. Entities composed

Entity What it contributes Model
market_series The published curve's identity and how it was derived ores.marketdata.market_series
market_observation The published points, and the replacement points that would supersede them ores.marketdata.market_observation
observation_lineage The recipe and source as-of behind the version being withdrawn, and behind its replacement ores.marketdata.observation_lineage
approval_request The withdrawal or replacement ask: who, which kind, why, and its state ores.inbox.approval_request
approval_kind How many approvals the withdrawal needs, and who may decide it ores.inbox.approval_kind
approval_decision Who approved or refused the withdrawal, when, and why ores.inbox.approval_decision
notification_kind What kind of notice a withdrawal sends to consumers ores.inbox.notification_kind
notification The notice itself: who it is for and where it points ores.inbox.notification

The published state a withdrawal would change is the curve_publish detail row of the request that authorised the publish: it holds published_at, published_by, the as-of the set was built at and the request. What it does not hold is a superseded link or a withdrawn marker; see What is missing.

7. Operations and messages

Step Operation Subject Status
Find the published curve List and read the series marketdata.v1.market_series.list, .get exists
Read what is published Read the latest snapshot of the curve marketdata.v1.curve_snapshot.get partial
Read the trail Read every version with its diff marketdata.v1.history.get exists
Raise the request List the approval kinds on offer inbox.v1.approval_kinds.list exists
Raise the request Raise the withdrawal or replacement request inbox.v1.ops.raise_approval exists
Watch for the decision Read the queue and decide inbox.v1.ops.list_approval_queue, inbox.v1.ops.decide_approval exists
Apply the withdrawal Take the published curve out of use marketdata.v1.curve_bootstrap.withdraw missing
Apply the replacement Publish a corrected version in its place, linked to the one it supersedes marketdata.v1.curve_bootstrap.replace missing
See the consumers change Announce the change on the series' own event marketdata.v1.events.market_series.updated, marketdata.v1.events.market_observations.updated partial
See the consumers change Raise a notice to the consumers inbox.v1.ops.raise_notification partial

The history read is the generic one, marketdata.v1.history.get, with entity_type ores.marketdata.market_series or ores.marketdata.observation_lineage; both register a history provider. The change events exist and fire on a write, but they carry an entity change and not the meaning "the published curve changed".

8. What is missing

  1. There is no withdrawal or replacement operation. A published curve cannot be taken out of use or superseded by a corrected one. The candidates are marketdata.v1.curve_bootstrap.withdraw and marketdata.v1.curve_bootstrap.replace. Until they exist the action controls are disabled, and the only write, marketdata.v1.ops.republish_curve, would silently write a new set with nothing withdrawn and nothing linked.
  2. There is no withdrawn state. A publish records the instant, the publisher, the as-of and the request, so a reader knows which set is live. Nothing marks a set withdrawn or superseded, so a withdrawal has no column to write and there is no read that excludes a withdrawn set. The candidate is a withdrawn instant and actor on the publish record, or a withdrawing record of its own. Until it exists a withdrawal would be a new publish, and the record would read as two live sets rather than one replaced by the other. The decision Withdrawal and supersession below states the state the record holds.
  3. There is no market-data withdrawal kind. One kind is seeded, iam.role_grant, and it does not withdraw a curve. The candidate is a kind, marketdata.curve_withdrawal, with decide_permission_code, comment_on_approve and a configurable approvals_required, so a tenant may allow a trader to withdraw alone or require approvals. Until then the raise cannot be given a kind and the controls are disabled. The decision below names the kind, its count and who may withdraw.
  4. Nothing links a replacement to the version it supersedes. A corrected curve written under the same oresmd_uri would be a new set of observations with no pointer from the old version to the new. The candidate is a superseded_by link or a valid_to on the published record. Until then the history shows two versions in time order and cannot say which one replaced the other.
  5. No notification kind tells consumers a curve changed. The consumers of a published curve are not told it was withdrawn or replaced. The candidate is an ores.inbox.notification_kind such as marketdata.curve_withdrawn, seeded beside the kind. Until then the consumers panel states that nobody is told, and the change is found only at the next read. The recipients and the trigger are stated under The publish notice in Publish the approved set.
  6. No read maps a published curve to its consumers. Nothing returns which people or services read a given published curve, so the screen cannot list who is affected. The candidate is a read over the party subscriptions. Until then the consumers panel names the roles that read curves in general, not the ones bound to this curve.
  7. There is no delta against the last published. A replacement is a change, and there is no baseline to show what it changes. The candidate is the delta read of the first journey. Until then the change panel is shown empty and the trader describes the change in the reason.

9. The decision

9.1. Withdrawal and supersession

9.1.1. The rule

A withdrawal is an act on the published set, and it is a new version of the publish record. It is not a deletion and not an edit. The act writes four facts on the record of the request that published the set: the withdrawing account, the instant, the reason, and the withdrawal request that authorised the act. The record keeps its values and its publisher, so the set a desk priced from is still readable afterwards.

A supersession is the same act with a successor. The corrected set is published by its own publish request, and the publish record of the set it replaces carries the link: the successor's request and its published instant. A reader therefore reads one live set and one superseded set, and never two live sets.

The state is on the publish record, and not on a separate entity:

State What the record holds What a reader sees
published A published instant, a publisher and an authorising request The set in use
superseded The published facts, and a successor request and instant A set that was in use and is not any more
withdrawn The published facts, a withdrawing account, an instant and a reason A set taken out of use, and its reason

The reader reads the state beside the values. A read of a withdrawn curve returns its last published values and the words that say it is withdrawn, with the instant and the reason. It does not return an empty series, because an empty series cannot be told from a curve that was never published.

9.1.2. Who may withdraw

The maker is the account that holds the kind's raise permission. The checker is an account that holds the kind's decide permission and did not raise the withdrawal. The publisher of the set has no special right to withdraw it: an account that did not publish the set may take it out of use, because the reason is the error and not the person. Any account that may raise a publish may raise a withdrawal.

A tenant sets the kind's approval count. The recommended value is one, so a second pair of eyes reads the reason before the set leaves use. The alternative is a count of zero, for a tenant whose operators act alone at night; the price is that the record then names one person for both the error and the act.

9.1.3. How a replacement differs from a withdrawal

A replacement puts a corrected set in place and keeps the curve in use. The corrected set is a candidate at a new as-of, it is raised as a publish request, and it is decided as every publish is. The replacement is not a second kind and not a second operation: it is a publish whose subject is the successor, and the link from the old record is what makes it a replacement.

A withdrawal takes the curve out of use and leaves it out until somebody publishes again. Pricing and reporting read a withdrawn curve as last-known, and they state the withdrawal. A curve that must resume needs a publish, and a publish needs a request.

The trader chooses between the two acts at step 4 of this journey. They are not two screens.

9.1.4. Why this answer

The publish record already holds the facts of the act: the request, the publisher and the instant. A withdrawal adds the end of the act to the same row, so the history of a curve is one stream of versions of one row and not a join of two tables. It also makes a list of published curves answer one question with one read: which set is in use for each series, and what ended it.

9.1.5. The alternative

A withdrawal is its own entity, ores.marketdata.curve_withdrawal, keyed by its own request and pointing at the publish record it ends. It carries the reason and the instant, and the publish record keeps the published facts alone. The screens then join the two reads. This is the answer if a tenant needs many withdrawals for one publish, which the model does not expect: a set leaves use once.

9.1.6. Open questions

  1. Does the withdrawal apply when the last decider approves, or does the trader apply it? The recommendation is that it applies on the decision. A publish waits for the trader because the trader owns the set that becomes live; a withdrawal takes a risk out of the book, and a second press adds a wait and no check. The alternative is the publish's path, with an apply call that names the approved withdrawal request.
  2. Which reasons may a withdrawal name? The recommendation is a lookup of its own, seeded with the reasons a curve leaves use: a wrong quote, a stale pillar, a recipe changed after the fact, a duplicate publish, and a correction. A withdrawal names a code and a comment, as a hold does.
  3. May a withdrawn set be published again unchanged? The recommendation is no: the route is a new candidate at a new as-of, so the record never reads as if the error never happened. A tenant that must restore exactly the same values raises a publish of that set, and the reason states the restoration.
  4. Does a withdrawal request expire? The recommendation is that it does not: a withdrawal that nobody answers leaves a wrong set in use, and the ask must stay visible rather than close in silence. The alternative is the two-week window the publish kind carries.

10. Related journeys

11. Related knowledge

12. See also

Emacs 29.3 (Org mode 9.6.15)