Add KERIA tock configuration with legacy compatibility

docs/keria_app.rst

@@ -1,5 +1,5 @@
-KERIA App API
-=============
+KERIA App API Documentation
+===========================
 
 keria.app.agenting
 ------------------
@@ -8,14 +8,23 @@ keria.app.agenting
     :members:
 
 Agency and Agent Configuration
-===================
+==============================
 
 A KERIA Agency can be configured with either environment variables or a configuration file.
-The configuration file is a JSON file. Both alternatives are shown here.
+The configuration file is a JSON file. Both alternatives are shown here. A subset of the options
+available in the config file may alternatively be set with environment variables. When both are
+defined the environment variables take precedence over config file properties.
+
+Configuration uses the following precedence strategy:
+
+* ``specific env > coarse env > specific config > coarse config > default``
 
 Environment Variables
 ---------------------
 
+KERIA may be configured with environment variables as shown below. A complete list of tock-level
+configuration options are shown in :ref:`scheduler-tock-config`.
+
 .. code-block:: bash
 
     # Service Endpoint Location URLs creating Endpoint Role Authorizations and Location Scheme records on startup
@@ -30,11 +39,16 @@ Environment Variables
 JSON Configuration File
 -----------------------
 
-To use the JSON configuration file option make sure to mount the JSON file to the directory you specify with the
-`--config-dir` option and name the JSON file the name specified by the `--config-dir` option to the `keria start` command like so.
+The JSON configuration is the default configuration source and 100% of the configuration options for
+KERIA are located in the config file.
 
-With the absolute path version the `--config-dir` argument does not have an affect since the
-`--config-file` argument specifies the absolute path to the JSON file.
+.. Warning::
+  When using JSON config with containers make sure to mount the JSON file to the directory specified in the
+  ``--config-dir`` option and use the JSON file name specified by the ``--config-dir`` option to the
+  ``keria start`` command as shown below.
+
+.. Note::
+    Using the absolute path variant for ``--config-file`` ignores the ``--config-dir`` argument.
 
 .. code-block:: bash
 
@@ -49,35 +63,171 @@ With the absolute path version the `--config-dir` argument does not have an affe
         --config-dir /path/to/config-dir/keria.json \
         --config-file /path/to/config-dir/keria.json
 
-The JSON file must have an object with the same name that you sent to the `keria start` command via the `--name` argument.
-The default is "keria" which is why the JSON file below shows a sub-object named "keria".
-Make sure to include the "dt" date timestamp field or the configuration will not be loaded.
+.. Warning::
+  The JSON file must have an object with the same name that you sent to the ``keria start`` command via the ``--name`` argument.
+  The default is ``"keria"`` which is why the JSON file below shows a sub-object named ``"keria"``.
+  Make sure to include the ``"dt"`` date timestamp field or the configuration will not be loaded.
+
+KERIA tocks in `tocks.signify`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-You can configure the cycle time, or tocks, of the escrower as well as the agent initializer.
+Configure KERIA Agent tocks in the JSON config file under ``tocks.signify``. KERIpy service settings
+remain directly under ``tocks``. Values are HIO Doist scheduler intervals in seconds as a float value.
 
 You can also configure the CURLs, IURLs, and DURLs of the agent.
-CURLs are Service Endpoint Location URLs creating Endpoint Role Authorizations and Location Scheme records on startup.
-IURLS are Introduction URLs resolved on startup (OOBIs).
-DURLS are Data OOBI URLs resolved on startup usually of things like ACDC credential schemas or ACDC credential CESR streams.
-
-.. code-block:: json
-
-    {
-      "dt": "2025-01-13T16:08:30.123456+00:00",
-      "keria": {
-        "dt": "2025-01-13T16:08:30.123457+00:00",
-        "curls": ["http://127.0.0.1:3902/"]
-      },
-      "iurls": [
-        "http://127.0.0.1:5642/oobi/BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha/controller?name=Wan&tag=witness",
-        "http://127.0.0.1:5643/oobi/BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM/controller?name=Wil&tag=witness",
-        "http://127.0.0.1:5644/oobi/BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX/controller?name=Wes&tag=witness"
-      ],
-      "tocks": {
-        "initer": 0.0,
-        "escrower": 1.0
-      }
-    }
+
+* ``CURLs`` are **Service Endpoint Location** URLs creating Endpoint Role Authorizations and Location Scheme records on startup.
+* ``IURLS`` are **Introduction** URLs resolved on startup (OOBIs).
+* ``DURLS`` are **Data OOBI** URLs resolved on startup usually of things like ACDC credential schemas or ACDC credential CESR streams.
+
+
+KERIA Configuration File Example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Note that the following configuration file uses the name ``keria`` for the Agency as it has a
+``"keria"`` top level section of the configuration JSON. This corresponds to using the ``keria``
+value for ``keria start --name "keria"`` when starting KERIA.
+
+The existing sample lists every KERIpy and KERIA component cadence explicitly.
+Coarse aliases are omitted because they are shortcuts for these same settings.
+
+.. literalinclude:: ../scripts/keri/cf/keria.json
+   :language: json
+
+.. _scheduler-tock-config:
+
+Scheduler Tock Configuration (HIO Doist scheduler)
+==================================================
+
+Except for the release scan described below, KERIA defaults its registered
+component cadences, including its KERIpy service settings, to ``0.03125`` seconds: one tick of its 32 Hz root scheduler. Explicit
+``0.0`` remains supported and schedules work on the next cycle. File and
+environment overrides retain their normal precedence; KERIpy's own defaults
+outside KERIA are unchanged.
+
+Delegation escrow processing uses ``tocks.anchorerEscrow`` throughout its
+runtime, without a separate half-second delay. Witness resubmission's outbound
+drain wait uses ``tocks.witnessReceiptorIdle`` and also defaults to one tick.
+
+The Agent release scan, ``tocks.signify.releaser``, is the housekeeping
+exception with a default of ``60.0`` seconds. It scans all open Agents for the default 24-hour inactivity
+timeout. Allowing up to one minute of additional cleanup delay avoids a full
+scan every tick without delaying active message processing. The release timeout
+itself is separate from scheduler cadence and is not shortened.
+
+.. list-table:: KERIA settings under tocks.signify
+   :header-rows: 1
+
+   * - File key
+     - Environment override
+   * - ``initer``
+     - ``KERIA_INITER_TOCK``
+   * - ``querier``
+     - ``KERIA_QUERIER_TOCK``
+   * - ``escrower``
+     - ``KERIA_ESCROWER_TOCK``
+   * - ``parser``
+     - ``KERIA_PARSER_TOCK``
+   * - ``witnesser``
+     - ``KERIA_WITNESSER_TOCK``
+   * - ``delegator``
+     - ``KERIA_DELEGATOR_TOCK``
+   * - ``exchangeSender``
+     - ``KERIA_EXCHANGE_SENDER_TOCK``
+   * - ``granter``
+     - ``KERIA_GRANTER_TOCK``
+   * - ``admitter``
+     - ``KERIA_ADMITTER_TOCK``
+   * - ``groupRequester``
+     - ``KERIA_GROUP_REQUESTER_TOCK``
+   * - ``seeker``
+     - ``KERIA_SEEKER_TOCK``
+   * - ``exchangecue``
+     - ``KERIA_EXCHANGE_CUE_TOCK``
+   * - ``submitter``
+     - ``KERIA_SUBMITTER_TOCK``
+   * - ``bootServer``
+     - ``KERIA_BOOT_SERVER_TOCK``
+   * - ``adminServer``
+     - ``KERIA_ADMIN_SERVER_TOCK``
+   * - ``httpServer``
+     - ``KERIA_HTTP_SERVER_TOCK``
+   * - ``shutdown``
+     - ``KERIA_SHUTDOWN_TOCK``
+   * - ``signalExpiry``
+     - ``KERIA_SIGNAL_EXPIRY_TOCK``
+   * - ``releaser``
+     - ``KERIA_RELEASER_TOCK``
+
+Parser waits and witness receipt/catch-up waits use their configured component
+cadences. The Agent owns a ``SignalExpirer`` for its Signaler; ``signalExpiry`` controls
+its scan cadence, not the ten-minute signal lifetime. Each scan uses a snapshot
+and does not yield during iteration, so notification pushes between scheduler
+cycles cannot invalidate a live deque iterator.
+
+Agency/Agent containers follow the root scheduler cadence. Habery lifecycle
+work and delegation containers inherit their owning container's cadence;
+delegation's escrow loop retains its independent ``anchorerEscrow`` setting.
+Transient grant workers, query workers, and delivery wrappers use their
+parent's cadence. KERIpy's internal Poster, Clienter, and transport scheduling
+is outside these KERIA settings. One-off CLI commands have no dedicated keys.
+
+The server, shutdown, and release settings bind at Agency startup. Agent-owned
+settings, including ``submitter`` and ``signalExpiry``, bind at creation or
+reopen using that Agent's configuration lifecycle.
+
+
+Configuration Precedence Strategy
+---------------------------------
+
+Resolution uses the same rule as KERIpy:
+
+``specific env > coarse env > specific config > coarse config > default``
+
+For example, ``KERIA_AGENT_TOCK=0.5`` overrides a file's
+``tocks.signify.escrower=1.0``, while ``KERIA_ESCROWER_TOCK=0.25`` overrides
+both. These KERIA environment variables do not alter KERIpy's independent
+``KERI_*_TOCK`` settings. KERIA's Registrar and Credentialer are processed by
+its central ``escrower``; KERIpy's separate registrar/credentialer escrow
+settings do not schedule those KERIA objects.
+
+All file values must be finite, nonnegative JSON numbers; booleans, strings,
+nulls, unknown keys, and malformed blocks are errors. Environment values must
+parse as finite, nonnegative numbers. Invalid supplied values are rejected even
+when another setting would override them. Errors identify the invalid setting or configuration structure.
+
+Coarse grained settings
+-----------------------
+
+The coarse grained ``tocks.signify.agent`` setting, or ``KERIA_AGENT_TOCK``, applies to
+the original twelve Agent-work settings plus ``submitter``. It excludes
+``bootServer``, ``adminServer``, ``httpServer``, ``shutdown``, ``signalExpiry``,
+and ``releaser`` so a work-loop override does not alter server or housekeeping
+cadences.
+
+Backwards compatibility with legacy flat tocks
+----------------------------------------------
+
+The existing names remain supported directly under ``tocks`` for backward
+compatibility. For example, ``{"tocks": {"escrower": 1.0}}`` is accepted but
+logs one deprecation warning per configuration load. Move it to
+``{"tocks": {"signify": {"escrower": 1.0}}}``. Identical old/new duplicates
+are accepted; conflicting duplicates fail instead of silently choosing a value.
+Legacy placement will remain available through a migration period; removal
+will be announced in a future release.
+
+The Agency resolves its configuration at load time and this is used as a template for any
+Agent provisioned by that Agency. Newly provisioned Agents receive a copy of the configured tocks
+from the Agency's JSON config file and do not persist environment overrides or defaults.
+
+.. Warning::
+  Existing Agents reopen their own persisted config files, including legacy files; those files are not automatically rewritten.
+  Updating the Agency JSON config file does not change existing Agent JSON config files.
+  Restart the Agency to load config changes for subsequently provisioned Agents.
+  Edit an existing Agent's individual config and restart to apply changes; environment overrides provide
+  process-wide tuning when services are reconstructed. There is no live reload.
+
+These settings configure the existing Doer constructors.
 
 keria.app.aiding
 ----------------

scripts/keri/cf/keria.json

@@ -2,15 +2,65 @@
   "dt": "2025-01-03T16:08:30.123456+00:00",
   "keria": {
     "dt": "2025-01-03T16:08:30.123457+00:00",
-    "curls": ["http://127.0.0.1:3902/"]
+    "curls": [
+      "http://127.0.0.1:3902/"
+    ]
   },
   "iurls": [
     "http://127.0.0.1:5642/oobi/BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha/controller?name=Wan&tag=witness",
     "http://127.0.0.1:5643/oobi/BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM/controller?name=Wil&tag=witness",
     "http://127.0.0.1:5644/oobi/BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX/controller?name=Wes&tag=witness"
   ],
   "tocks": {
-    "initer": 0.0,
-    "escrower": 1.0
+    "witnessMsg": 0.03125,
+    "witnessEscrow": 0.03125,
+    "witnessCue": 0.03125,
+    "indirectorMsg": 0.03125,
+    "indirectorCue": 0.03125,
+    "indirectorEscrow": 0.03125,
+    "mailboxPoll": 0.03125,
+    "mailboxMsg": 0.03125,
+    "mailboxEscrow": 0.03125,
+    "pollerEvent": 0.03125,
+    "pollerConnect": 0.03125,
+    "receiptIntercept": 0.03125,
+    "reactorMsg": 0.03125,
+    "reactorCue": 0.03125,
+    "reactorEscrow": 0.03125,
+    "reactantMsg": 0.03125,
+    "reactantCue": 0.03125,
+    "reactantEscrow": 0.03125,
+    "respondant": 0.03125,
+    "receiptor": 0.03125,
+    "oobi": 0.03125,
+    "witnessReceiptor": 0.03125,
+    "witnessReceiptorIdle": 0.03125,
+    "witnessInquisitor": 0.03125,
+    "witnessPublisher": 0.03125,
+    "registrarEscrow": 0.03125,
+    "credentialerEscrow": 0.03125,
+    "counselorEscrow": 0.03125,
+    "anchorerEscrow": 0.03125,
+    "signify": {
+      "initer": 0.03125,
+      "querier": 0.03125,
+      "escrower": 0.03125,
+      "parser": 0.03125,
+      "witnesser": 0.03125,
+      "delegator": 0.03125,
+      "exchangeSender": 0.03125,
+      "granter": 0.03125,
+      "admitter": 0.03125,
+      "groupRequester": 0.03125,
+      "seeker": 0.03125,
+      "exchangecue": 0.03125,
+      "submitter": 0.03125,
+      "bootServer": 0.03125,
+      "adminServer": 0.03125,
+      "httpServer": 0.03125,
+      "shutdown": 0.03125,
+      "signalExpiry": 0.03125,
+      "releaser": 60.0
+    }
   }
-}
+}

scripts/keria.json

@@ -2,15 +2,65 @@
   "dt": "2025-01-03T16:08:30.123456+00:00",
   "keria": {
     "dt": "2025-01-03T16:08:30.123457+00:00",
-    "curls": ["http://127.0.0.1:3902/"]
+    "curls": [
+      "http://127.0.0.1:3902/"
+    ]
   },
   "iurls": [
     "http://127.0.0.1:5642/oobi/BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha/controller?name=Wan&tag=witness",
     "http://127.0.0.1:5643/oobi/BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM/controller?name=Wil&tag=witness",
     "http://127.0.0.1:5644/oobi/BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX/controller?name=Wes&tag=witness"
   ],
   "tocks": {
-    "initer": 0.0,
-    "escrower": 1.0
+    "witnessMsg": 0.03125,
+    "witnessEscrow": 0.03125,
+    "witnessCue": 0.03125,
+    "indirectorMsg": 0.03125,
+    "indirectorCue": 0.03125,
+    "indirectorEscrow": 0.03125,
+    "mailboxPoll": 0.03125,
+    "mailboxMsg": 0.03125,
+    "mailboxEscrow": 0.03125,
+    "pollerEvent": 0.03125,
+    "pollerConnect": 0.03125,
+    "receiptIntercept": 0.03125,
+    "reactorMsg": 0.03125,
+    "reactorCue": 0.03125,
+    "reactorEscrow": 0.03125,
+    "reactantMsg": 0.03125,
+    "reactantCue": 0.03125,
+    "reactantEscrow": 0.03125,
+    "respondant": 0.03125,
+    "receiptor": 0.03125,
+    "oobi": 0.03125,
+    "witnessReceiptor": 0.03125,
+    "witnessReceiptorIdle": 0.03125,
+    "witnessInquisitor": 0.03125,
+    "witnessPublisher": 0.03125,
+    "registrarEscrow": 0.03125,
+    "credentialerEscrow": 0.03125,
+    "counselorEscrow": 0.03125,
+    "anchorerEscrow": 0.03125,
+    "signify": {
+      "initer": 0.03125,
+      "querier": 0.03125,
+      "escrower": 0.03125,
+      "parser": 0.03125,
+      "witnesser": 0.03125,
+      "delegator": 0.03125,
+      "exchangeSender": 0.03125,
+      "granter": 0.03125,
+      "admitter": 0.03125,
+      "groupRequester": 0.03125,
+      "seeker": 0.03125,
+      "exchangecue": 0.03125,
+      "submitter": 0.03125,
+      "bootServer": 0.03125,
+      "adminServer": 0.03125,
+      "httpServer": 0.03125,
+      "shutdown": 0.03125,
+      "signalExpiry": 0.03125,
+      "releaser": 60.0
+    }
   }
-}
+}