First draft of use case and extension to version timestamps through n…

…on-slewing clock adjustments.

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

@@ -57,6 +57,8 @@ Ultimately, the content of this appendix may be rearranged and even relocated; h
 
 * [[[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

@@ -63,17 +63,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
 
@@ -221,5 +210,161 @@ NOTE: This requirement supplements RR1162 in <<ref_ieee_11073_10700_2022>>: _The
 ****
 
 
+===== 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 <<vol1_spec_sdpi_p_actor_somds_participant>> is operational on the <<acronym_md_lan>> network,
+
+*When* The <<vol1_spec_sdpi_p_actor_somds_participant>>'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 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: during a non-slewing time adjustment the device's time-reference frame may jump forward or backward in time, from the perspective of an external observer, in a single, large, step. 
+
+NOTE: a non-slewing time adjustment creates two distinct epochs, each with their own time-reference frames. Both the rate of the passage of time and the determination time assigned to a single event may differ significantly between epochs. 
+
+NOTE: non-slewing time adjustments may occur, for example, when a <<vol1_spec_sdpi_p_actor_somds_participant>> rejoin a network, an absent TS Service returns to operation or be caused by hardware failure or operator error (e.g., making non-slewing adjustments to the TS Service time-reference frame while it is being used by one or more <<vol1_spec_sdpi_p_actor_somds_participant>>s).
+
+====== Safety, Effectiveness & Security Considerations and Requirements
+
+// This provides information for auditing. 
+.R1560
+[sdpi_requirement#r1560,sdpi_req_level=should]
+****
+The <<vol1_spec_sdpi_p_actor_somds_participant>> should include the determination time in the log entry for each non-slewing time adjustment in both the time-reference frame before, and after, the non-slewing adjustment was made.
+
+.Notes
+[%collapsible]
+====
+
+NOTE: The determination time, recorded in each time-reference frame, should represent, as near as practical, the same point in time to an external observer unaffected by the change in time-reference frames. 
+
+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 stepping adjustment of its system clock, the <<vol1_spec_sdpi_p_actor_somds_provider>> shall either:
+
+* initiate a new MDIB sequence by assigning a new MDIB sequence identifier, or
+* set `ClockState/@LastSet` to the earliest time that is unambiguously in the current epoch and increment `Epochs/@Current` by exactly 1.
+
+.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 `ClockState/@LastSet` and `Epochs/@Current`.
+
+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 NTPv4 clock-discipline algorithm) where information from one or more TS Services is used to maintain clock-discipline and does not "set" the clock.
+
+NOTE: Any timestamps in the MDIB prior to `ClockState/@LastSet` may not have been obtained from the current time-reference.
+
+====
+****
+
+Any time-stamps 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>>. `ClockState/@LastSet` may be used to determine if an unversioned timestamp was unambiguously obtained in the current epoch. For example, when a non-slewing adjustment moves the device's time-frame reference forward, any states in the MDIB with timestamps greater than the first timestamp available from the new epoch are unambiguously in the new epoch. In contrast, when the device's time-frame reference moves backward, only timestamps greater than a timestamp obtained from the old epoch's time-frame reference when the non-slewing adjustment occurred are unambiguously in the current epoch. That is, the first timestamps obtained from the new time-frame reference may overlap timestamps obtained from the prior time-frame reference. 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-frame reference back in time, only timestamps before the last timestamp recorded in the MDIB from epoch 0 belong unambiguously to the new time-frame reference.
+
+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-frame reference may be from an earlier epoch. 
+
+image::vol1-diagram-use-case-stad-ns-back-forth.svg[align=center]
+
+.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]
+====
+Timestamps for states that are not updated frequently may be versioned with a specific epoch. 
+
+====
+****
+
+.R1562
+[sdpi_requirement#r1562,sdpi_req_level=shall]
+****
+The <<vol1_spec_sdpi_p_actor_somds_provider>> shall report epoch adjustments from the earliest versioned timestamp's time-frame referenced in the MDIB to the current time-frame reference.  
+
+.Notes
+[NOTE]
+[%collapsible]
+====
+Epoch adjustments are optionally provided for <<vol1_spec_sdpi_p_actor_somds_participant>>s to adjust historic data. All relevant adjustments must be provided when versioned timestamps are included in an MDIB. 
+
+====
+****
 
+// This is for the sledge hammer approach. I 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 <<vol1_spec_sdpi_p_actor_somds_provider>> that changes the MDIB sequence identifier when it can no longer make smooth adjustments to its time-frame reference shall consider the risks arising from gaps in continuous data. 
 
+.Notes
+[NOTE]
+[%collapsible]
+====
+Non-slewing time-adjustments may be 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 the <<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-frame reference may require intervention by the OPERATOR or RESPONSIBLE ORGANIZATION.  
+* A <<vol1_spec_sdpi_p_actor_somds_participant>> may continue delivery with a subset of its nominal SYSTEM FUNCTION CONTRIBUTION following a non-slewing adjustment reporting the activation state of components using `AbstractDeviceComponentState/@ActivationState`.
+
+====
+****