Skip to content

Add KERIA tock configuration with legacy compatibility - #465

Merged
kentbull merged 4 commits into
WebOfTrust:mainfrom
kentbull:feat/tocks-config-compat
Sep 22, 2026
Merged

kentbull merged 4 commits into
WebOfTrust:mainfrom
kentbull:feat/tocks-config-compat

Conversation

@kentbull

@kentbull kentbull commented Sep 15, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Fixes #258

KERIA previously read twelve flat Agent tock settings, but lacked consistent environment overrides, validation, and propagation into child tasks. This PR centralizes scheduling configuration in keria.app.scheduling, reuses KERIpy's resolver, and threads configured tock cadences through recurring Agency/Agent-managed work. It builds on #464 toward #258 and the 0.4.1 release.

Registered work defaults to 0.03125 seconds, one cycle of KERIA's existing 32 Hz scheduler. Explicit 0.0 remains supported for next-cycle scheduling. The only slower default is releaser at 60.0 seconds: scanning all open Agents for the default 24-hour inactivity timeout does not require a scan every scheduler cycle. The root scheduler cadence is unchanged.

Configuration and compatibility

  • Expose 19 KERIA settings under tocks.signify and 29 KERIpy settings directly under tocks. Apply KERIA's one-cycle defaults through a copied core registry without changing KERIpy's process-global defaults.
  • Preserve the twelve existing Agent settings and add submitter, bootServer, adminServer, httpServer, shutdown, signalExpiry, and releaser.
  • Accept legacy flat KERIA keys with a migration warning. For example, {"tocks":{"escrower":1.0}} remains valid; the canonical form is {"tocks":{"signify":{"escrower":1.0}}}. Removal is deferred to a future announced release.
  • Support specific environment overrides such as KERIA_ESCROWER_TOCK and the group override KERIA_AGENT_TOCK. The Agent group covers its 13 work settings and excludes servers, shutdown, signal expiry, and release scans. Core aliases remain within the KERIpy namespace.
  • Preserve precedence: specific environment > group environment > specific config > group config > default. Reject unknown keys, invalid values, and conflicting legacy/canonical duplicates, including invalid file values that environment overrides would otherwise mask.
Complete tocks configuration (all 48 defaults)

Merge this block into the Agency JSON config. Values are seconds; omitted settings use these defaults. Group aliases are omitted because every individual setting is shown.

{
  "tocks": {
    "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
    }
  }
}

Scheduling and lifecycle

  • Propagate worker cadences into transient query workers, witness catch-up/receipt generators, and exchange/grant delivery wrappers. Containers without independent settings inherit their parent's cadence.
  • Make parser waits, delegation escrow, and shutdown loops yield their configured cadences. Keep Anchorer's escrow cadence separate from its container cadence.
  • Resolve Agency settings at startup and Agent settings at creation/reopen. New Agents persist explicit canonical file values, excluding environment overrides and defaults. Existing Agents reopen their own files without rewriting legacy configurations; there is no live reload or automatic synchronization from a changed Agency template.
  • Align config-file lookup in Agency.get() with Agency.create() when Agent databases use a nonempty base.
  • Extend both existing sample configs with all 48 settings and document defaults, aliases, precedence, lifecycle, and deprecation. One-off CLI commands and KERIpy's internal Poster, Clienter, and transport scheduling remain outside this change.
  • Schedule an Agent-owned SignalExpirer against the notifier's signal queue. Expiry scans a snapshot without yielding during iteration, avoiding deque mutation across yields while preserving the existing expiration timeout.

Validation

Regression coverage includes configuration precedence and validation, legacy normalization and real-file reopening, database-base config lookup, independent Agent worker bindings, runtime cadence forwarding, signal expiry, and Agency service bindings. Sample-config tests check completeness and default values.

At commit 73fb151, Linux and macOS test jobs (including lint and formatting), coverage, Docker build/start, and both Codecov checks pass.

@codecov

codecov Bot commented Sep 15, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 99.24812% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 88.73%. Comparing base (8945173) to head (06ca59b).
⚠️ Report is 1 commits behind head on main.

Files with missing lines Patch % Lines
src/keria/app/agenting.py 97.67% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main     #465      +/-   ##
==========================================
+ Coverage   88.26%   88.73%   +0.46%     
==========================================
  Files          26       27       +1     
  Lines        5950     6056     +106     
==========================================
+ Hits         5252     5374     +122     
+ Misses        698      682      -16     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@kentbull
kentbull force-pushed the feat/tocks-config-compat branch 4 times, most recently from 3e2499f to 4da2e75 Compare September 16, 2026 22:21
Reuse the KERIpy resolver with a KERIA registry for the twelve existing Agent settings. Add the canonical tocks.signify namespace, environment overrides, strict validation, and deprecation warnings for compatible flat keys while preserving existing defaults.

Snapshot template settings at Agency startup and persist only explicit canonical values for new Agents. Reopen existing Agents from their own unchanged config files, including when database paths use a nonempty base.
@kentbull
kentbull force-pushed the feat/tocks-config-compat branch from 4da2e75 to f6b4bb0 Compare September 16, 2026 22:25
Comment thread src/keria/app/agenting.py
Comment thread src/keria/app/agenting.py
@kentbull
kentbull force-pushed the feat/tocks-config-compat branch 7 times, most recently from 8fb37e5 to a0f0916 Compare September 18, 2026 05:21
@kentbull
kentbull force-pushed the feat/tocks-config-compat branch from a0f0916 to 73fb151 Compare September 18, 2026 05:22
@kentbull
kentbull marked this pull request as ready for review September 18, 2026 05:25
@kentbull
kentbull requested a review from iFergal September 18, 2026 05:25
@kentbull

Copy link
Copy Markdown
Collaborator Author

@daidoji please review

Comment thread src/keria/app/delegating.py Outdated
Comment thread src/keria/app/agenting.py
Comment thread src/keria/app/agenting.py
Comment thread src/keria/app/agenting.py
Comment thread tests/scripts/keri/cf/main/keria.json
@kentbull
kentbull merged commit 9f38d06 into WebOfTrust:main Sep 22, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add support for configuration file entries for Agent Doer tocks

3 participants