← Research archive
Technical note verified Sep 15, 2026

Signed Cross-Host Research Queue and Durable Handoff Architecture

KESPA split autonomous research across the application server and home research server using pull-based HTTPS, HMAC SHA-256 request authentication, nonce replay protection, durable filesystem queues, signed release handoff, and resumable delivery state. The design keeps the home server off the public inbound path while allowing queued research and completed releases to survive process restarts and host reboots.

distributed-systems research-queue hmac durability handoff
MARKDOWN

README.md

3,656 bytes SHA-256 e6bf14dd4f57cddd…

KESPA-NOTE-017 — Signed Cross-Host Research Queue and Durable Handoff Architecture

Date: 2026-09-15 Status: Verified — live distributed research transport operational Project: KESPA AI / NexLabs Studios

Purpose

KESPA's autonomous research system runs across multiple machines.

Rather than exposing the HOME research server directly to the public Internet, the system uses a pull-based control flow:

HOME -> HTTPS -> app-nexlabs

That keeps the public application server as the control-plane boundary while allowing the research server to retrieve work and return completed releases securely.

Logical host roles

Current roles are already separated:

  • app-nexlabs — application / control plane
  • DESKTOP-S16TRCC — HOME research plane
  • RYANDESKTOP — inference / retrieval plane

The HOME server does not need a public inbound research endpoint.

App-to-HOME work queue

The application exposes a research-request API supporting:

  • ping
  • poll
  • ack

Requests are authenticated with HMAC SHA-256.

The authentication contract includes:

  • timestamp;
  • nonce;
  • request-body hash;
  • signature.

The accepted timestamp window is five minutes, and nonce state is retained to prevent replay.

Durable HOME queue

The HOME poller runs every 5 minutes and stores incoming work in a filesystem queue:

``text pending/ processing/ done/ failed/ held/ receipts/ ``

This is deliberately durable.

If the HOME machine reboots, pending research does not disappear merely because an in-memory worker stopped.

Completed release handoff

Successful research produces a frozen release package under:

D:\forge\research\trusted-release\<release_id>\

A separate scanner runs every 5 minutes.

It maintains delivery state under:

D:\forge\research\handoff_state\

and skips unchanged packages that were already delivered successfully.

The package is then sent over signed HTTPS to the application-side receiver.

A successful live handoff returned:

Remote status: received

PASS

Application inbox

Accepted releases are stored under:

/var/www/forge/storage/groq_research/inbox/<release_id>/

Each accepted release contains:

  • handoff_receipt.json
  • manifest.json
  • verified_claims.jsonl
  • verified_evidence.jsonl

The app-side lifecycle can then process that frozen release independently of the HOME worker.

Failure behavior

The transport follows a useful durability rule:

  • polling failure -> request remains queued;
  • HOME reboot -> filesystem queue survives;
  • research failure -> request can move to failed or held;
  • handoff failure -> trusted release remains local for retry;
  • duplicate scan -> already delivered unchanged package is skipped.

Failure therefore does not require regenerating a successful research release.

Why this architecture matters

The design separates three different concerns:

control plane

research plane

inference / retrieval plane

That separation reduces coupling and makes later hardware migration easier.

Moving the research worker from a home PC into rack hardware should mostly mean moving the worker/state and changing endpoints or service scheduling — not redesigning the research protocol.

Scaling boundary

The current file-backed queues are intentionally simple.

They are appropriate at present scale.

If research volume eventually reaches hundreds or thousands of jobs per hour, the same lifecycle can move to database leasing, Redis, RabbitMQ, or another broker without changing the research trust model.

There is no reason to add that complexity before the workload requires it.

TEXT

SHA256SUMS.txt

393 bytes SHA-256 ce1a4dc6b599b96f… 
e6bf14dd4f57cdddc73bb17e9f0dbe197ba5006cf759bf7f1997950ddb82f181  README.md
741ac0fabe792e9528eead8850313d8e9be2539b13cc4d0f654c15d44c522d67  note.json
1740a650fbe6913cb74a9ac8220e67ccf1fa108181ab641024974e4df9073266  metrics.csv
ef673cf93531a7c16fed7893a0ee2960b12e6c05c658aa549b41b632b01fc97f  methodology.md
0007fd10ba0ca320aa9fb3aa363a1da2666e2781831ed640830f1fa01aad2eff  provenance.json
MARKDOWN

methodology.md

1,124 bytes SHA-256 ef673cf93531a7c1…

Methodology

Request authentication

The app-side request API authenticates HOME polling requests with HMAC SHA-256 over timestamp, nonce, and request-body identity.

Requests outside the timestamp window or using replayed nonces are rejected.

Queue durability

HOME persists each research request into a filesystem state machine rather than holding work only in memory.

Explicit queue directories represent pending, active, completed, failed, held, and receipt states.

Release handoff

Completed trusted-release packages are immutable handoff units.

A periodic scanner detects eligible releases and sends them through the signed HTTPS receiver.

Delivery state prevents unchanged successful packages from being resent indefinitely.

Application persistence

Accepted releases are written into an application inbox with a receipt and the exact release artifacts required by the isolated app-side lifecycle.

Resilience principle

Transport failures do not lower trust requirements and do not require successful research to be regenerated.

The system retains durable state and retries delivery instead.

CSV

metrics.csv

494 bytes SHA-256 1740a650fbe6913c… 
metric,value,unit_or_status
request_api_operations,3,ping_poll_ack
hmac_algorithm,SHA-256,authentication
timestamp_window,300,seconds
nonce_replay_protection,YES,control
home_poll_interval,5,minutes
home_queue_states,6,states
handoff_scan_interval,5,minutes
public_inbound_to_home_required,NO,architecture
queue_survives_home_reboot,YES,durability
failed_handoff_retains_release,YES,durability
unchanged_successful_release_redelivery,SKIPPED,dedupe
remote_received_status_proven,YES,validation
JSON

note.json

3,085 bytes SHA-256 741ac0fabe792e95… 
{
    "schema": "kespa.public_technical_note.v1",
    "id": "KESPA-NOTE-017",
    "title": "Signed Cross-Host Research Queue and Durable Handoff Architecture",
    "date": "2026-09-15",
    "status": "verified",
    "purpose": "Document the distributed queue, authentication, durability, and delivery boundaries used to move autonomous research work between app-nexlabs and the HOME research server without exposing HOME as a public inbound service.",
    "topology": {
        "app_control_plane": "app-nexlabs",
        "research_plane": "DESKTOP-S16TRCC / D:\\forge",
        "inference_retrieval_plane": "RYANDESKTOP / D:\\forge\\chroma_db",
        "public_inbound_to_home_required": false
    },
    "request_path": {
        "direction": "HOME -> HTTPS -> app-nexlabs",
        "api_version": "forge-groq-research-request-api-v0.1.0",
        "operations": [
            "ping",
            "poll",
            "ack"
        ],
        "authentication": "HMAC SHA-256",
        "signed_fields": [
            "timestamp",
            "nonce",
            "request body hash",
            "signature"
        ],
        "timestamp_window_seconds": 300,
        "nonce_replay_protection": true
    },
    "home_queue": {
        "poller_version": "forge-groq-research-request-poller-v0.1.0",
        "poll_interval_minutes": 5,
        "queue_root": "D:\\forge\\research\\request_queue\\",
        "states": [
            "pending",
            "processing",
            "done",
            "failed",
            "held",
            "receipts"
        ],
        "durable_across_reboot": true
    },
    "release_handoff": {
        "release_root": "D:\\forge\\research\\trusted-release\\",
        "sender_version": "forge-groq-research-handoff-sender-v0.1.0",
        "scanner_version": "forge-groq-research-handoff-scanner-v0.1.0",
        "scan_interval_minutes": 5,
        "delivery_state_root": "D:\\forge\\research\\handoff_state\\",
        "unchanged_successful_packages_skipped": true,
        "receiver": "app-side signed HTTPS research handoff",
        "remote_received_status_proven": true
    },
    "app_inbox": {
        "root": "/var/www/forge/storage/groq_research/inbox/<release_id>/",
        "files": [
            "handoff_receipt.json",
            "manifest.json",
            "verified_claims.jsonl",
            "verified_evidence.jsonl"
        ]
    },
    "resilience": {
        "pending_work_survives_home_reboot": true,
        "failed_handoff_retains_local_release": true,
        "delivery_deduplication_state": true,
        "research_state_is_file_backed": true,
        "in_memory_only_queue": false
    },
    "migration_characteristic": {
        "logical_roles_already_separated": true,
        "future_rack_migration_requires_redesign": false,
        "future_worker_host_change_expected": true,
        "endpoint_reconfiguration_expected": true
    },
    "limitations": [
        "The file-backed queue is appropriate at current scale but is not intended for hundreds or thousands of research jobs per hour.",
        "HMAC authentication depends on protecting the shared secret on both hosts.",
        "Five-minute polling introduces bounded delivery latency compared with push or broker-based systems.",
        "The architecture provides durable transport and handoff; it does not itself establish the factual quality of research payloads."
    ]
}
JSON

provenance.json

1,203 bytes SHA-256 0007fd10ba0ca320… 
{
    "schema": "kespa.public_provenance.v1",
    "research_id": "KESPA-NOTE-017",
    "source_basis": "KESPA Natural Research Lifecycle completion record supplied by the project owner.",
    "source_observations": [
        "The HOME server polls app-nexlabs over HTTPS rather than accepting public inbound research requests.",
        "The request API supports ping, poll, and ack and uses HMAC SHA-256 with timestamp, nonce, body hash, signature, a five-minute window, and replay protection.",
        "HOME persists requests in pending/processing/done/failed/held/receipts filesystem queues.",
        "The handoff scanner runs every five minutes, maintains persistent delivery state, and skips unchanged successfully delivered releases.",
        "Accepted releases land in the app-side groq_research inbox with a handoff receipt and frozen release files.",
        "A live Cuckoo-filter release handoff returned remote status received / PASS."
    ],
    "publication_note": "This public note describes transport, queue, authentication, and durability architecture. Shared secrets, signatures, nonce values, private endpoints beyond public architectural paths, credentials, and private payload contents are intentionally omitted."
}