Resolution of issue "Non slewing time adjustments #203" V2

asciidoc/listings/vol3-clause-biceps-content-example-timestamp-version.xml

@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<msg:GetMdibResponse
+        SequenceId="urn:uuid:09578906-7efd-43a7-8344-8bf37b674524"
+        xmlns:ext="http://standards.ieee.org/downloads/11073/11073-10207-2017/extension"
+        xmlns:pm="http://standards.ieee.org/downloads/11073/11073-10207-2017/participant"
+        xmlns:msg="http://standards.ieee.org/downloads/11073/11073-10207-2017/message"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xmlns:sdpi="urn:oid:1.3.6.1.4.1.19376.1.6.2.10.1.1.1">
+    <msg:Mdib SequenceId="urn:uuid:09578906-7efd-43a7-8344-8bf37b674524">
+        <pm:MdDescription>
+            <pm:Mds Handle="mds0">
+              <pm:Clock Handle="clk"/>
+              <pm:Vmd Handle="vmd">
+                <pm:Channel Handle="ch">
+                  <pm:Metric Handle="m1" MetricAvailability="Intr" MetricCategory="Msrmt">
+                    <pm:Type Code="67108871"/>
+                    <pm:Unit Code="262656" />
+                  </pm:Metric>
+                  <pm:Metric Handle="m2" MetricAvailability="Intr" MetricCategory="Msrmt">
+                    <pm:Type Code="67108871"/>
+                    <pm:Unit Code="262656" />
+                  </pm:Metric>
+                </pm:Channel>
+              </pm:Vmd>
+            </pm:Mds>
+        </pm:MdDescription>
+        <pm:MdState>
+          <pm:State LastSet="1733270400" DateAndTime="1733268600" DescriptorHandle="clk" StateVersion="15" RemoteSync="1" xsi:type="pm:ClockState">
+            <ext:Extension>
+              <sdpi:Epochs Version="5">
+                <!-- non-slewing adjustment at 11 am -->
+                <sdpi:Epoch Version="4" Timestamp="1733270400" Offset="-PT3H" />
+                <!-- non-slewing adjustment at 7 am -->
+                <sdpi:Epoch Version="3" Timestamp="1733248800" Offset="PT4H" />
+              </sdpi:Epochs>
+            </ext:Extension>
+          </pm:State>
+
+          <pm:State DescriptorHandle="m1" xsi:type="pm:NumericMetricState" StateVersion="123">
+            <!-- determination time = 3 am, epoch 3 clock -->
+            <pm:MetricValue Value="0" DeterminationTime="1733238000" StartTime="1733237090" StopTime="1733237097">
+              <ext:Extension>
+                <sdpi:MetricEpoch Clock="clk" DeterminationTime="3" StartTime="3" StopTime="3" />
+              </ext:Extension>
+              <pm:MetricQuality Validity="Vld" Qi="1.00"/>
+            </pm:MetricValue>
+          </pm:State>
+
+          <pm:State DescriptorHandle="m2" xsi:type="pm:NumericMetricState" StateVersion="321">
+            <!-- determination time = 12 am, epoch 4 clock -->
+            <pm:MetricValue Value="0" DeterminationTime="1733266800" >
+              <pm:MetricQuality Validity="Vld" Qi="1.00"/>
+            </pm:MetricValue>
+          </pm:State>
+
+        </pm:MdState>
+    </msg:Mdib>
+</msg:GetMdibResponse>

asciidoc/volume1/tf1-ch-b-ref-standards-conformance.adoc

@@ -66,6 +66,8 @@ No content from those three standards - including their requirements -  is norma
 
 * [[[ref_rfc_3986, RFC 3986]]] T. Berners-Lee et al., RFC 3986, Uniform Resource Identifier (URI): Generic Syntax, January 2005, available at https://www.rfc-editor.org/rfc/rfc3986
 
+* [[[ref_rfc_5905, RFC 5905]]] D. Mills et al., RFC 5905, Network Time Protocol Version 4: Protocol And Algorithms Specification, June 2010, available at https://www.rfc-editor.org/rfc/rfc5905
+
 * [[[ref_oasis_dpws_2009,OASIS DPWS:2009]]] OASIS Standard, Devices Profile for Web Services Version 1.1, OASIS Standard, 1 July 2009, available at http://docs.oasis-open.org/ws-dd/dpws/wsdd-dpws-1.1-spec.html
 
 * [[[ref_oasis_soap_over_udp_v1_1, OASIS SOAP-over-UDP Version 1.1]]] OASIS Standard, SOAP-over-UDP Version 1.1, July 2009, available at http://docs.oasis-open.org/ws-dd/soapoverudp/1.1/os/wsdd-soapoverudp-1.1-spec-os.docx.

asciidoc/volume1/use-cases/tf1-ch-c-use-case-stad.adoc

@@ -52,6 +52,22 @@ NOTE: The 50ms target accuracy is suitable for highly demanding use cases like r
 ====
 ****
 
+.R1521
+[sdpi_requirement#r1521,sdpi_req_level=should]
+****
+The <<term_manufacturer>> of a <<vol1_spec_sdpi_p_actor_somds_participant>> should configure its <<acronym_ts_service>> client to prioritize smooth, monotonic, changes to the system clock. 
+
+.Notes
+[%collapsible]
+====
+NOTE: <<vol1_spec_sdpi_p_actor_somds_participant>>s using, for example, <<ref_rfc_5905, NTP>> to syncronize their device clock with the <<acronym_ts_service>> could satisfy this requirement by following the cold and warm startup algoriths and clock discipline algorithms with tuning parameters described in <<ref_rfc_5905>>.
+
+NOTE: <<vol1_spec_sdpi_p_actor_somds_participant>>s using other synchronization standards
+should similarly strongly favour slewing (adjusting clock frequency) over non-slewing (large changes forward 
+or backward in time) adjustments, and supress non-slewing adjustments for a period during initialization. 
+
+====
+****
 
 
 ===== Scenario: <<acronym_stad>> {var_use_case_id}.2 - Device is connected to the MD LAN network and a user wants to change the device's time
@@ -214,6 +230,199 @@ NOTE: This requirement supplements RR1162 in <<ref_ieee_11073_10700_2022>>: _The
 ====
 ****
 
+[#vol1_clause_appendix_c_use_case_stad_non_slew]
+===== Scenario: <<acronym_stad>> {var_use_case_id}.6 - A device, operational in the MD LAN network, determines a non-slewing time adjustment is required
+
+*Given* The device is operational on the <<acronym_md_lan>> network,
+
+*When* The device's clock-discipline algorithm determines a non-slewing time adjustment is required,
+
+*Then* The device will create a log entry that includes at least a time-stamp for the adjustment in both the time-reference frame before and after the non-slewing adjustment was made,
+
+*And* The <<vol1_spec_sdpi_p_actor_somds_provider>> will notify <<vol1_spec_sdpi_p_actor_somds_consumer>>s, using its system function contributions (<<acronym_sfc>>), of the change to the provider's time-reference frame,  
+
+*Or* The <<vol1_spec_sdpi_p_actor_somds_provider>> will initiate a new MDIB sequence.
+
+NOTE: a device's time-reference frame may jump forward or backward in time in a single, large, step (from the perspective of an external observer) following a non-slewing time adjustment. 
+
+NOTE: two distinct epochs are created by a non-slewing time adjustment, each with a distinct time-reference frame. Both the rate of the passage of time and the determination time assigned to a single event may differ significantly between epochs (from the perspective of an external observer). 
+
+NOTE: non-slewing time adjustments may occur, for example, when a device rejoins a network, an absent <<acronym_ts_service>> returns to operation or be caused by hardware failure or operator error (e.g., making non-slewing adjustments to the <<acronym_ts_service>> time-reference frame while it is being used by one or more <<vol1_spec_sdpi_p_actor_somds_participant>>s). 
+
+NOTE: non-slewing time adjustments may result in a constant or variable offset between epochs. For constant offsets, the difference (to an unbiased observer) between any two timestamps obtained in different epochs is constant. For variable offsets, the difference (to an unbiased observer) between any two timestamps obtained in different epochs depends on when, within each epoch, the timestamp was obtained. 
+
+====== Terms
+// figure out where to put this. 
+
+[%autowidth]
+[cols="^1,<3"]
+|===
+|Term |Definition 
+
+| time-reference frame
+| A device-specific context for measuring and assigning timestamps to events defined by its rate of passage of time (which may vary over time) and alignment to some external temporal standard (e.g., provided by a <<acronym_ts_service>>). Changes to the time-reference frame, such as non-slewing adjustments, can create distinct epochs with different temporal properties.
+
+| epoch
+| A disctinct period of time characterized by a consistent temporal properties; a single time-reference frame.
+
+| timestamp
+| A point in time obtained from a system clock; while a timestamp is obtained within the context of a time-reference frame, timestamps do not have an intrinsic reference to time-reference frame. 
+
+| timestamp version
+| A unique identifier, within the scope of a MDIB sequence, of a time-reference frame epoc.
+
+| slewing time adjustment
+| Adjustments made to a system clock's frequency. Generally so that the time reported by a system clock matches that of a <<acronym_ts_service>> at some point in the future, within the statistical uncertaintity of the synchronization algorithm.
+
+| non-slewing time adjustment, abrupt time adjustment
+| An abrubt change to a system clock's time-reference frame to match the time reported by a system clock with that from a <<acronym_ts_service>>, within the statistical uncertaintity of the synchronization algorithm, as quickly as possible.
+
+| smooth time adjustments
+| A gradual adjustment to the temporal properites of a time-refernece frame, characterised by a continuous and monotonically increasing progression of timestamps without abrupt jumps or disruptions to the passage of time. Generally so that the time reported by a system clock matches that of a <<acronym_ts_service>> at some point in the future, within the statistical uncertaintity of the synchronization algorithm.
+
+| clock-discipline algorithm
+| The algorithm employed by a <<acronym_ts_service>> client to minimize the error between a reference time source. It main include smooth (e.g., slewing) and, in some cases, abrupt (e.g., non-slewing) corrections. 
+
+|===
+
+
+====== Safety, Effectiveness & Security Considerations and Requirements
+
+// This provides information for auditing. 
+.R1560
+[sdpi_requirement#r1560,sdpi_req_level=shall]
+****
+The <<vol1_spec_sdpi_p_actor_somds_participant>> shall log each non-slewing adjustment of the local system clock with an entry that includes the determination time of the log entry in both the time-reference frame before, and after, each non-slewing clock adjustment. 
+
+.Notes
+[%collapsible]
+====
+
+NOTE: This requirement supplements TR1340 in <<ref_ieee_11073_10700_2022>>&mdash;_An SDC BASE PARTICIPANT SHOULD log each non-slewing adjustment of the local clock._&mdash; requiring specific information in the log to support post incident analysis
+
+====
+****
+
+// This is for providers to inform consumers of the non-slewing adjustment.
+// It is necessary to have a version here for providers that don't use NTP clock-discipline to smoothly adjust clocks and just set the clock (hopefully not going back in time).
+// Using `ClockState/@LastSet` like this avoids having to extend everything that needs a timestamp to support versioning (because any timestamp in the MDIB before the LastSet
+// is questionable following a transition to a new epoch). Epoch versioning is then an extension that lets the consumer determine how questionable a timestamp is. 
+// If we have a `Epochs/@Current` and update `ClockState/@LastSet` I don't think we need to also include a "Questionable" flag or change `ClockState/@ActiviationState` as proposed
+// during the workshop. Using `ClockState/@LastSet` seems better than just changing the @Activation state because the consumer could determine which timestamps are questionable.
+.R1522
+[sdpi_requirement#r1522,sdpi_req_level=shall]
+****
+When the <<vol1_spec_sdpi_p_actor_somds_provider>> detects an abrupt time adjustment of a system clock, used in making its System Function Contribution (<<acronym_sfc>>), the <<vol1_spec_sdpi_p_actor_somds_provider>> shall either:
+
+* initiate a new MDIB sequence by assigning a new MDIB sequence identifier, or
+* set `pm:ClockState/@ActivationState` to `StndBy` when any timestamp in a <<acronym_mdib>> version was not obtained from the time-reference frame of the active clock in the same version, or 
+* set `pm:ClockState/@LastSet` to the earliest time that is unambiguously in the current epoch and increment `sdpi:Epochs/@Version`.
+
+.Notes
+[%collapsible]
+====
+NOTE: The <<term_manufacturer>> of the <<vol1_spec_sdpi_p_actor_somds_consumer>> considers the risks arising from timestamps spanning time-reference frames from a non-slewing clock adjustment having occurred at the <<vol1_spec_sdpi_p_actor_somds_provider>> when the <<vol1_spec_sdpi_p_actor_somds_consumer>> receives a changed value in the <<vol1_spec_sdpi_p_actor_somds_provider>>'s MDIB sequence identifier or `pm:ClockState/@LastSet` and `sdpi:Epochs/@Version` or when the `pm:ClockState/@ActivationState` is `StndBy`.
+
+NOTE: This clarifies the ambiguity in <<ref_ieee_11073_10207_2017>>, section B.182 when slewing is used to smoothly adjust the time-reference frame (using, for example, the <<ref_rfc_5905, NTPv4>> clock-discipline algorithm) where information from one or more <<acronym_ts_service>>s is used to maintain clock-discipline and does not (generally) "set" the clock.
+
+NOTE: Any timestamps in the MDIB prior to `pm:ClockState/@LastSet` may not have been obtained from the current time-reference.
+
+====
+****
+
+Timestamps obtained in an ealier epoch may be treated with greater suspicion than those obtained in the current epoch by a <<vol1_spec_sdpi_p_actor_somds_participant>>. `pm:ClockState/@LastSet` provides the unambiguous begining of the current epoch in the time-reference frame of the current epoch. For example, when a non-slewing adjustment moves the device's time-reference frame forward, any timestamps in the MDIB greater than start of the new epoch are unambiguously in the new epoch. In contrast, when the device's time-reference frame moves backward, only timestamps greater than the latest timestamp obtained from the epoch before the time-reference frame moved backward are unambiguously in the current epoch. That is, the timestamps obtained from the new time-reference frame may overlap timestamps obtained from the prior time-reference frame. These examples are illustrated below:
+
+There is no overlap in timestamps when a non-slewing adjustment shifts the device clock forward in time. 
+
+image::vol1-diagram-use-case-stad-ns-forward.svg[align=center]
+
+When a non-slewing adjustment shifts the device's time-reference frame back in time, only timestamps before the last timestamp recorded in the MDIB from epoch 0 belong unambiguously to the new time-reference frame.
+
+image::vol1-diagram-use-case-stad-ns-back.svg[align=center]
+
+When a device experiences multiple non-slewing adjustments in a short period of time, the earliest timestamp unambiguously in the current time-reference frame may be from an earlier epoch. 
+
+image::vol1-diagram-use-case-stad-ns-back-forth.svg[align=center]
+
+// This is to introduce versioning epochs. 
+.R1561
+[sdpi_requirement#r1561,sdpi_req_level=may]
+****
+The <<vol1_spec_sdpi_p_actor_somds_provider>> may indicate a timestamp belongs to a specific epoch using the SDPi epoch extension. 
+
+.Notes
+[NOTE]
+[%collapsible]
+====
+Binding timestamps in the <<acronym_mdib>> to a specific epoch may be useful for states that are not updated frequently. 
+
+====
+****
+
+.R1562
+[sdpi_requirement#r1562,sdpi_req_level=shall]
+****
+The <<term_manufacturer>> of a <<vol1_spec_sdpi_p_actor_somds_consumer>> shall consider the risks arising from relying on timestamps obtained from different epochs.  
 
+.Notes
+[NOTE]
+[%collapsible]
+====
+It may not be possible to reliably determine the relationship between timestamps obtained from different time-reference frames without addition information regarding the cause of the non-slewing adjustment. For example, if a non-slewing adjustment arises because the device clock was running faster (or slower) than the reference clock then the arithmetic difference between two events spanning the adjustment (even when combined with the step adjustment duration) may not match the elapsed time experienced by an unbiased observer.  
+
+====
+****
 
 
+// This is for the sledge hammer approach. I can't figure out what a universal rule could be or how to communicate epoch changes
+// across MdibVersionGroup/@SequenceId since it seems that any information inside the MDS implicitly is scoped to the 
+// sequence id. 
+.R1566
+[sdpi_requirement#r1566,sdpi_req_level=shall]
+****
+The <<term_manufacturer>> of a <<vol1_spec_sdpi_p_actor_somds_provider>> that changes the MDIB sequence identifier when it can no longer make smooth adjustments to its time-reference frame shall consider the risks arising from gaps in continuous data. 
+
+.Notes
+[NOTE]
+[%collapsible]
+====
+Non-slewing time-adjustments may indicate a serious error that impacts data that has already been:
+
+ * displayed on a chart to the user,
+ * exported to other systems.
+
+====
+****
+
+// This may be unneccessary since it applies to all participants from 10700:§5.2.2,RR1162. It does make it clear
+// that epoch versions aren't required though. 
+.R1568
+[sdpi_requirement#r1568,sdpi_req_level=shall]
+****
+The <<term_manufacturer>> of a <<vol1_spec_sdpi_p_actor_somds_provider>> that chooses to omit epoch versions from any timestamp shall consider the risks arising from erroneous timestamps. 
+
+[NOTE]
+[%collapsible]
+====
+Epoch versions may not be required for timestamps on items that update frequently. 
+
+====
+****
+
+// This may be unnecessary as the device could fault at any time. However, perhaps it is useful as a way
+// to surface behaviours as part of conformity statements. And it emphasises the myriad of problems with
+// time steps. 
+.R1569
+[sdpi_requirement#r1569,sdpi_req_level=may]
+****
+A <<vol1_spec_sdpi_p_actor_somds_participant>> may enter a fault state by, for example, setting the `MdsState/@ActivationState` to `Fail` upon detecting a non-slewing time adjustment that it otherwise cannot recover from. 
+
+[NOTE]
+[%collapsible]
+====
+
+* A sudden change in a participant's time-reference frame may require intervention by the OPERATOR or RESPONSIBLE ORGANIZATION.  
+* A <<vol1_spec_sdpi_p_actor_somds_participant>> may continue delivery with a subset one or more of its nominal System Function Contribution (<<acronym_sfc>>) following a non-slewing adjustment reporting the activation state of components using `AbstractDeviceComponentState/@ActivationState`.
+
+====
+****