HERALD Capability-String Registry

HERALD Capability-String Registry

Status: v0.2 skeleton and governance baseline.
Output path after review: learning/herald-protocol/registries/capabilities.md
Source: learning/herald-protocol/EXT.md §4.4, with context from SPEC §8.3 and THREATS §5.6.

This registry defines canonical strings for capability manifests. A manifest's capabilities[] and constraints[] values are not free text: they are registry identifiers. Verifiers reject manifests that cite unknown identifiers, or identifiers introduced after the manifest's ts.

The registry prevents manifest-squatting, makes discovery queries stable, and gives reviewers one place to attach schema, pricing-floor, and proof-of-service expectations.

Identifier Profile

Capability and constraint identifiers are lower-case ASCII strings:

<family>/<name>[/<jurisdiction-or-profile>]

Rules:

• Use a-z, 0-9, hyphen, and /.
• Do not use spaces, underscores, leading slash, trailing slash, or repeated slash.
• Keep identifiers stable once admitted.
• Prefer broad families over vendor names.
• Use jurisdiction/profile suffixes only when behavior, law, or schema changes materially.

Examples:

• legal-research/eu
• translation/ja-en
• constraint/no-pii
• constraint/no-medical-advice

Registry Entry Shape

Each entry has the fields required by EXT §4.4 plus governance metadata:

id: legal-research/eu
kind: capability
status: provisional
since: 2026-05-05T00:00:00Z
description: Legal research over EU law and institutions.
schema_ref: schemas/legal-research-eu.json
economic_floor:
  per_token_usd: null
service_proof:
  required: false
  accepted_refs: []
change_log:
  - ts: 2026-05-05T00:00:00Z
    action: added
    reason: seed example from SPEC §8.3

Field meanings:

Seed Entries

These entries are a skeleton, not an exhaustive taxonomy.

legal-research/eu

id: legal-research/eu
kind: capability
status: provisional
since: 2026-05-05T00:00:00Z
description: Research, retrieval, and synthesis over European Union law, institutions, regulations, and case-law references.
schema_ref: schemas/legal-research-eu.json
economic_floor:
  per_token_usd: null
service_proof:
  required: false
  accepted_refs: []
change_log:
  - ts: 2026-05-05T00:00:00Z
    action: added
    reason: Seed capability named by SPEC §8.3.

translation/ja-en

id: translation/ja-en
kind: capability
status: provisional
since: 2026-05-05T00:00:00Z
description: Translation from Japanese to English, including plain-text and structured-message payloads.
schema_ref: schemas/translation-ja-en.json
economic_floor:
  per_token_usd: null
service_proof:
  required: false
  accepted_refs: []
change_log:
  - ts: 2026-05-05T00:00:00Z
    action: added
    reason: Seed capability named by SPEC §8.3.

constraint/no-pii

id: constraint/no-pii
kind: constraint
status: provisional
since: 2026-05-05T00:00:00Z
description: The subject declares it will not intentionally process personally identifiable information for this manifest's advertised service.
schema_ref: none
economic_floor: null
service_proof: null
change_log:
  - ts: 2026-05-05T00:00:00Z
    action: added
    reason: Seed constraint named by SPEC §8.3.

constraint/no-medical-advice

id: constraint/no-medical-advice
kind: constraint
status: provisional
since: 2026-05-05T00:00:00Z
description: The subject declares it will not provide medical advice under this manifest.
schema_ref: none
economic_floor: null
service_proof: null
change_log:
  - ts: 2026-05-05T00:00:00Z
    action: added
    reason: Seed constraint named by SPEC §8.3 and replay example in EXT §4.2.

Governance

Admission

New entries require:

• A unique canonical id.
• A description precise enough that two implementers can decide whether a manifest matches it.
• A schema reference, or an explicit none if the entry carries no structured payload.
• A since timestamp.
• A squatting analysis: why the proposed identifier does not intercept a broader query it should not own.

Versioning

Entries are append-only:

• Do not change the meaning of an active entry in place.
• Use deprecated for entries that should no longer appear in new manifests.
• Add a replacement entry when behavior changes materially.
• Verifiers reject manifests citing an entry whose since is newer than the manifest's ts.

Publication

The registry should be published at a well-known URL and every change should be committed to a HERALD CT log once registry logging exists. Until then, reviewers should treat the file history and manthan receipts as the audit trail.

Economic Floors

If an entry defines an economic floor, a manifest with rates.per_token_usd below that floor MUST set subsidised: true. The floor is a transparency guard, not a price control.

Service Proofs

The service_proof field is a hook. Registry entries may require proof-of-service or proof-of-stake references, but the accepted proof shapes must be defined per entry before verifiers can enforce them.

Rejection Rules

Verifiers and discovery aggregators reject a capability manifest when:

• Any capabilities[] id is absent from this registry.
• Any constraints[] id is absent from this registry.
• Any cited id has status: reserved.
• Any cited id has since later than the manifest's ts.
• A below-floor rate omits subsidised: true.
• Application policy requires a service_proof and the manifest lacks one.

Reviewer Checklist

• Does the identifier use the canonical profile?
• Is the identifier narrower than the query space it would capture?
• Is the description precise enough for independent implementations?
• Is a schema attached where payload structure matters?
• Does this entry need an economic floor?
• Does this entry need proof-of-service-or-stake before discovery aggregators should surface it?
• Should this be a constraint instead of a capability, or vice versa?