Fix docs regarding deduplication periods [KVL-1194] (#11738)

CHANGELOG_BEGIN
CHANGELOG_END

docs/source/app-dev/app-arch.rst

@@ -139,14 +139,18 @@ If you want to make sure that a command is not executed twice, your application
 Daml ledgers provide a mechanism for :ref:`command deduplication <command-submission-service-deduplication>` to help deal with this problem.
 
 For each command the application provides a command ID and an optional parameter that specifies the deduplication period. If the latter parameter is not specified in the command submission itself, the ledger will fall back to using the configured maximum deduplication period.
-The ledger will then guarantee that commands with the same :ref:`change ID <change-id>` will be ignored within the deduplication period.
+The ledger will then guarantee that commands with the same :ref:`change ID <change-id>` will generate a rejection within the effective deduplication period.
 
 To use command deduplication, you should:
 
-- Use generous values for the deduplication duration. It should be large enough such that you can assume the command was permanently lost if the deduplication period has passed and you still don’t observe any effect of the command on the ledger (i.e. you don't see a transaction with the command ID via the :ref:`transaction service <transaction-service>`).
+- Use generous values for the deduplication duration. It should be large enough such that you can assume the command was permanently lost if the effective deduplication period has passed and you still don’t observe any effect of the command on the ledger (i.e. you don't see a transaction with the command ID via the :ref:`transaction service <transaction-service>`).
 - Make sure you set command IDs deterministically, that is to say: the "same" command must use the same command ID. This is useful for the recovery procedure after an application crash/restart, in which the application inspects the state of the ledger (e.g. via the :ref:`Active contracts service <active-contract-service>`) and sends commands to the ledger. When using deterministic command IDs, any commands that had been sent before the application restart will be discarded by the ledger to avoid duplicate submissions.
-- If you are not sure whether a command was submitted successfully, just resubmit it with the same deduplication duration. If the new command was submitted within the deduplication period, the duplicate submission will safely be ignored. If the deduplication period has passed, you can assume the command was lost or rejected and a new submission is justified.
+- If you are not sure whether a command was submitted successfully, just resubmit it with the same deduplication duration. If the new command was submitted within the effective deduplication period, the duplicate submission will anyway generate a rejection. If the effective deduplication period has passed, you can assume the command was lost or rejected and a new submission is justified.
 
+.. note:: Effective deduplication period
+
+  The effective deduplication period may be longer than the one specified in the command, but it never is shorter.
+  To learn more, see the :ref:`Ledger API Services <command-submission-service-deduplication>` documentation.
 
 For more details on command deduplication, see the :ref:`Ledger API Services <command-submission-service-deduplication>` documentation.
 

docs/source/app-dev/services.rst

@@ -83,7 +83,7 @@ The command submission service deduplicates submitted commands based on their :r
 
 - Applications can provide a :ref:`deduplication duration <com.daml.ledger.api.v1.Commands.deduplication_duration>` for each command. If this parameter is not set, the default maximum deduplication period is used.
 - A command submission is considered a duplicate submission if the ledger API server is aware of another command within the deduplication period and with the same :ref:`change ID <change-id>`.
-- Duplicate command submissions will be ignored until either the deduplication period of the original command has passed or the original submission was rejected (i.e. the command failed and resulted in a rejected transaction), whichever comes first.
+- A command resubmission will generate a rejection until the original submission was rejected (i.e. the command failed and resulted in a rejected transaction) or until the effective deduplication period has elapsed since the completion of the original command, whichever comes first.
 - Command deduplication is only *guaranteed* to work if all commands are submitted to the same participant. Ledgers are free to perform additional command deduplication across participants. Consult the respective ledger's manual for more details.
 - A command submission will return:
 
@@ -92,8 +92,25 @@ The command submission service deduplicates submitted commands based on their :r
 
 - If the ledger provides additional command deduplication across participants, the initial command submission might be successful, but ultimately the command can be rejected if the deduplication check fails on the ledger.
 
+  - At this time, only `Daml Driver for VMware Blockchain <https://www.digitalasset.com/daml-for-vmware-blockchain/>`__ supports command deduplication across participants.
+
 For details on how to use command deduplication, see the :ref:`Application Architecture Guide <command-deduplication>`.
 
+.. note::
+
+  - The ledger may extend the deduplication period specified in the request arbitrarily, even beyond the maximum deduplication duration specified in the :ref:`ledger configuration <ledger-configuration-service>`.
+    The deduplication period chosen by the ledger is the *effective deduplication period*.
+
+  - Regardless, the deduplication period specified in the request is always checked against the configured maximum deduplication duration.
+
+  - A command submission is considered a duplicate submission if the ledger is aware of another command within the *effective* deduplication period and with the same :ref:`change ID <change-id>`.
+
+  - The following ledger integrations always extend the deduplication period to the configured maximum deduplication duration:
+
+    - `Daml Driver for VMware Blockchain <https://www.digitalasset.com/daml-for-vmware-blockchain/>`__
+
+    - :ref:`Daml Sandbox <sandbox-manual>`
+
 .. _command-completion-service:
 
 Command completion service

ledger-api/grpc-definitions/com/daml/ledger/api/v1/commands.proto

@@ -64,13 +64,15 @@ message Commands {
     // Specifies the length of the deduplication period.
     // Same semantics apply as for `deduplication_duration`.
     //
-    // Must be non-negative.
+    // Must be non-negative. Must not exceed the maximum deduplication time (see
+    // ``ledger_configuration_service.proto``).
     google.protobuf.Duration deduplication_time = 9 [deprecated = true];
 
     // Specifies the length of the deduplication period.
     // It is interpreted relative to the local clock at some point during the submission's processing.
     //
-    // Must be non-negative.
+    // Must be non-negative. Must not exceed the maximum deduplication time (see
+    // ``ledger_configuration_service.proto``).
     google.protobuf.Duration deduplication_duration = 15;
   }