Workers

A worker is any executable unit that a WCP Hall can dispatch. It might be a Python function, a subprocess, a containerized service, or a remote API call. What matters is not the implementation — it is the governance record: what capabilities does this worker claim, what controls does it implement, and what is its blast radius?

Worker ID Format

Every worker instance has a unique worker_id using org-namespaced dot notation:

org.<name>.<type>[.<qualifier>]

Three segments are required. A fourth qualifier is allowed for disambiguation:

org.acme.summarizer
org.acme.email-sender
org.acme.db-writer.postgres
org.fafolab.research-registrar

Note

Worker IDs use the org.<name>.* namespace, which is organization-private. Your org namespace does not conflict with WCP catalog IDs or other organizations. Register your namespace at pyhall.dev to claim it publicly.

Species vs Instance

WCP separates two concepts that are easily conflated:

Worker species (worker_species_id) is the type — the blueprint. It uses the wrk.* namespace from the WCP catalog:

wrk.doc.summarizer
wrk.mem.retriever
wrk.web.fetcher
wrk.research.registrar

Worker instance (worker_id) is a running deployment of that type. Multiple instances share one species. When the Hall dispatches cap.doc.summarize, it selects a species (wrk.doc.summarizer) and returns that species ID — the caller then dispatches whichever instance is available.

The naming convention enforces the relationship: cap.doc.summarize → wrk.doc.summarizer. The capability describes what must be possible; the species describes who implements it.

Registry Record

A worker enrolls in the Hall by submitting a registry record — a JSON document that declares everything the Hall needs to make governed dispatch decisions. All fields must be present before enrollment is accepted.

{
  "worker_id": "org.fafolab.doc-summarizer",
  "worker_species_id": "wrk.doc.summarizer",
  "capabilities": ["cap.doc.summarize"],
  "risk_tier": "low",
  "idempotency": "full",
  "determinism": "captured",
  "required_controls": ["ctrl.obs.audit-log-append-only"],
  "currently_implements": ["ctrl.obs.audit-log-append-only"],
  "allowed_environments": ["dev", "stage", "prod"],
  "privilege_envelope": {
    "secrets_access": [],
    "network_egress": "none",
    "filesystem_writes": ["/tmp/summaries/"],
    "tools": ["ollama-embed"]
  },
  "blast_radius": {
    "data": 1,
    "network": 0,
    "financial": 0,
    "time": 1,
    "reversibility": "reversible"
  },
  "owner": "org.fafolab",
  "contact": "rob@fafolab.ai",
  "artifact_hash": "sha256:a3f9c2...",
  "catalog_version_min": "1.0.0"
}

Key fields:

• capabilities — the WCP capability IDs this worker implements. The Hall uses this to match capability requests.
• required_controls — controls the worker requires in the environment before it will accept dispatch.
• currently_implements — controls the worker has actually implemented. The Hall verifies this matches required_controls. Missing controls → deny.
• privilege_envelope — declares the worker’s resource access. Secrets, network egress, filesystem paths, and tools are all enumerated explicitly.
• blast_radius — five-dimension risk declaration. Used for blast scoring and gate decisions.
• artifact_hash — SHA-256 of the record itself (excluding the hash field). Proves the record has not been tampered with after generation.

Full-package attestation — signing the entire worker package (code + deps + config) with build_manifest() and verifying at runtime with PackageAttestationVerifier — is covered in Attestation.

Risk Tiers

Every worker declares a risk_tier. The tier drives blast radius thresholds, policy gate behavior, and what profile is applied at dispatch time.

Tier	Blast radius range	Example workers
low	0–3	Document summarizer, text chunker, embedder
medium	4–6	Web fetcher with egress, local database reader
high	7–9	Database writer, notification sender, file system modifier
critical	10+	Payment processor, external API with write access, infrastructure modifier

A low-tier worker in a permissive dev profile dispatches automatically. The same request for a critical-tier worker in production triggers a STEWARD_HOLD and requires human approval before execution proceeds.

Worker Lifecycle

Workers follow a four-stage lifecycle:

Build. The developer generates a registry record using pyhall build (interactive wizard). Controls, capabilities, blast radius, and privilege envelope are declared. The artifact_hash is computed.

Enroll. The registry record is submitted to the Hall. The Hall verifies the artifact_hash, checks that currently_implements satisfies required_controls, and registers the worker as available for dispatch.

Dispatch loop. The Hall routes capability requests to enrolled workers. On each dispatch, the Hall re-verifies controls, re-scores blast radius, and re-evaluates the policy gate. Enrollment is not a one-time check — it is re-confirmed on every decision.

Retire. The worker is removed from the Hall registry. In-flight dispatches complete. The correlation_id chain in the evidence log preserves the full history of what the worker did during its lifetime.

Caution

Modifying a worker’s code after enrollment without re-computing the artifact_hash and re-enrolling will cause DENY_WORKER_TAMPERED on the next dispatch when worker code attestation is enabled. Always re-enroll after code changes.

Generating a Worker with the CLI

# Launch the interactive wizard to build a registry record
pyhall build

# Enroll
pyhall enroll my_summarizer/registry_record.json \
  --registry-dir enrolled/

# Check status
pyhall status --registry-dir enrolled/