Added new extension to support versioning timestamps

Added new use-case for non-slewing time adjustments
Moved R1522 into new use-case.

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

@@ -64,17 +64,6 @@ NOTE: If possible, the priority of slewing adjustments starts applying once the
 ====
 ****
 
-.R1522
-[sdpi_requirement#r1522,sdpi_req_level=shall]
-****
-When the <<vol1_spec_sdpi_p_actor_somds_provider>> detects a stepping adjustment of its system clock, the <<vol1_spec_sdpi_p_actor_somds_provider>> shall initiate a new MDIB sequence by assigning a new MDIB sequence identifier.
-
-.Notes
-[%collapsible]
-====
-NOTE: Note: The <<term_manufacturer>> of the <<vol1_spec_sdpi_p_actor_somds_consumer>> considers the possibility of a stepping 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.
-====
-****
 
 ===== 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
 
@@ -236,6 +225,163 @@ 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. 
+
+====== 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 include 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>>: _An SDC BASE PARTICIPANT SHOULD log each non-slewing adjustment of the local clock._
+
+====
+****
+
+// 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 a step 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/@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`.
+
+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 "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 <<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`.
+
+====
+****