Dispute Registry v0.1

A minimal, append-only, portable, and auditable registry format for recording disputes, supersessions, revocations, reaffirmations, and related lifecycle actions against accountability artifacts.

Dispute Registry v0.1 defines how responsible claims remain governable over time.
It is designed as a governance layer for accountability artifacts such as Signed Impact Attestations, Impact Score Profiles, Existence Proofs, verification summaries, and related trace-linked records.

In short: accountability artifacts are not frozen truths; they are lifecycle-managed institutional objects.

---

Why this spec matters

A signed artifact is not enough by itself.

Even when an accountability artifact is cryptographically valid, real-world systems still need a way to answer questions such as:

• What if the artifact is disputed?
• What if it is replaced by a better or newer artifact?
• What if it should no longer be relied upon?
• What if a dispute is dismissed or formally resolved?
• What if confidence is later restored?

Dispute Registry v0.1 exists to record those lifecycle actions in a structured, auditable, and portable way.

It is not a truth engine.
It is an institutional memory for responsible disagreement and governance over time.

---

Core idea

Dispute Registry v0.1 treats accountability artifacts as governed objects.

That means an artifact may become:

• contested,
• reviewed,
• superseded,
• revoked,
• reaffirmed,
• dismissed,
• resolved,
• or escalated.

Instead of forcing those meanings into the target artifact itself, this specification keeps them in a separate append-only governance layer.

This separation is intentional.

• The target artifact remains minimal.
• The dispute and governance history remains traceable.
• Different governance systems can build on the same registry format.

---

Design goals

• Keep the registry entry minimal, append-only, portable, and auditable
• Treat accountability artifacts as lifecycle-managed institutional objects
• Support dispute, supersede, revoke, reaffirm, dismiss, resolve, and escalate actions
• Separate dispute history from the target artifact itself
• Support human, organization, AI agent, hybrid, and automated actors
• Enable downstream governance for Trust OS, Royalty OS, Gratitude OS, and related systems

---

Repository Structure

.
├── .github/
│   └── workflows/
│       └── validate-specs.yml
├── examples/
│   └── dispute-registry.sample.json
├── schemas/
│   └── dispute-registry-v0.1.schema.json
├── spec/
│   └── dispute-registry-v0.1.yaml
└── README.md
Start Here

Read the files in this order:

spec/dispute-registry-v0.1.yaml
Human-readable normative specification.
schemas/dispute-registry-v0.1.schema.json
Machine-readable validation schema.
examples/dispute-registry.sample.json
Valid example document for testing and implementation.
.github/workflows/validate-specs.yml
Automated validation workflow for this repository.
One-line definition

Dispute Registry v0.1 defines a portable, append-only, and auditable registry entry format for recording lifecycle governance actions against accountability artifacts.

Human meaning

This spec answers questions such as:

What artifact is being challenged or acted upon?
Who is asserting the dispute or lifecycle action?
What action is being asserted?
On what basis is the action being made?
What evidence or policy supports it?
What is the current status of that dispute or governance action?
Supported target artifact types

The schema currently supports the following target types:

signed-impact-attestation
impact-score-profile
existence-proof
verification-summary
dispute-registry-entry
other

This keeps the format reusable across multiple accountability systems.

Supported actor types

The schema currently supports the following actor categories:

human
organization
ai_agent
hybrid_agent
automated_system

This allows the registry to work across both present-day institutional systems and future AI-agent ecosystems.

Supported actions

Dispute Registry v0.1 supports the following lifecycle actions:

dispute
supersede
revoke
reaffirm
dismiss
resolve
escalate

These actions are intentionally separated from the target artifact itself so that governance can evolve without mutating the original object.

What the actions mean
dispute

Records a challenge to the validity, sufficiency, legitimacy, authority, or downstream use of the target artifact.

supersede

Records that the target artifact is replaced by a newer or more authoritative artifact.

revoke

Records that the target artifact should no longer be relied upon for its intended downstream use.

reaffirm

Records that the target artifact remains supported after review or challenge.

dismiss

Records that a dispute or challenge has been dismissed.

resolve

Records the formal resolution of a dispute, challenge, or review process.

escalate

Records that the matter has been moved to a higher or broader governance layer.

Append-only governance model

This specification is designed around an append-only registry model.

That means registry entries should normally be added, not rewritten.

Why this matters:

governance history remains auditable,
dispute lineage remains traceable,
institutional memory is preserved,
downstream systems can inspect how a conclusion was reached.

In other words, the registry is meant to preserve the path of disagreement, not just the final result.

Schema Usage
Validate locally

You can validate the specification and example document locally with Python.

Install dependencies:

python -m pip install --upgrade pip
pip install PyYAML jsonschema

Then run:

python - <<'PY'
import json
import sys
from pathlib import Path

import yaml
from jsonschema import Draft202012Validator


def fail(message: str) -> None:
    print(f"ERROR: {message}")
    sys.exit(1)


def load_yaml(path: Path):
    if not path.exists():
        fail(f"Spec file not found: {path}")
    try:
        with path.open("r", encoding="utf-8") as f:
            return yaml.safe_load(f)
    except yaml.YAMLError as e:
        fail(f"Invalid YAML in {path}: {e}")


def load_json(path: Path):
    if not path.exists():
        fail(f"JSON file not found: {path}")
    try:
        with path.open("r", encoding="utf-8") as f:
            return json.load(f)
    except json.JSONDecodeError as e:
        fail(f"Invalid JSON in {path}: {e}")


def main() -> None:
    spec_path = Path("spec/dispute-registry-v0.1.yaml")
    schema_path = Path("schemas/dispute-registry-v0.1.schema.json")
    sample_path = Path("examples/dispute-registry.sample.json")

    print("=== Validating Dispute Registry repository ===")
    print()

    print("=== Validating YAML specification ===")
    print(f"Spec: {spec_path}")
    spec = load_yaml(spec_path)

    if not isinstance(spec, dict):
        fail(f"YAML spec must be a mapping/object: {spec_path}")

    expected_spec_id = "dispute-registry-v0.1"
    actual_spec_id = spec.get("spec_id")
    if actual_spec_id != expected_spec_id:
        fail(
            f"Unexpected spec_id in {spec_path}: "
            f"expected '{expected_spec_id}', got '{actual_spec_id}'"
        )

    print("OK: YAML specification loaded successfully.")
    print()

    print("=== Validating JSON Schema ===")
    print(f"Schema: {schema_path}")
    schema = load_json(schema_path)

    try:
        Draft202012Validator.check_schema(schema)
    except Exception as e:
        fail(f"Invalid JSON Schema in {schema_path}: {e}")

    print("OK: JSON Schema is valid.")
    print()

    print("=== Validating example document ===")
    print(f"Sample: {sample_path}")
    sample = load_json(sample_path)

    validator = Draft202012Validator(schema)
    errors = sorted(validator.iter_errors(sample), key=lambda e: list(e.path))

    if errors:
        print("Validation errors found:")
        for error in errors:
            path = ".".join(str(p) for p in error.path) or "<root>"
            print(f" - {path}: {error.message}")
        sys.exit(1)

    print("OK: Dispute Registry v0.1 sample is valid.")
    print()
    print("Validation succeeded.")


if __name__ == "__main__":
    main()
PY
What this validation checks

The local validation flow checks:

that spec/dispute-registry-v0.1.yaml exists and loads correctly
that spec_id is dispute-registry-v0.1
that schemas/dispute-registry-v0.1.schema.json is valid Draft 2020-12 JSON Schema
that examples/dispute-registry.sample.json conforms to the schema
What JSON Schema does not fully enforce

JSON Schema is very strong for structure validation, but several important checks still require a separate verifier layer.

Examples include:

whether previous_entry_id actually exists
whether related_entry_ids form a coherent chain
whether target_hash really matches the referenced artifact
whether the actor truly has authority to assert the action
whether the signature is cryptographically valid
whether policy references are recognized by the consuming governance system

So the schema is necessary, but not sufficient, for full governance trust.

GitHub Actions

This repository includes an automated validation workflow:

.github/workflows/validate-specs.yml

It validates:

the YAML spec
the JSON Schema
the example document

on:

push
pull request
manual dispatch
Conformance levels
Minimal conformance

A document is minimally conformant when it includes the required structural fields:

version
registry entry ID
recorded timestamp
target block
actor block
action block
status block
signature block
integrity block
Governance-ready conformance

A stronger profile for institutional use includes additional fields such as:

actor authority basis
policy reference
target hash
entry hash
existence proof reference
evidence references
evidence hashes
review metadata
transparency log reference

This stronger profile is more suitable for:

Trust OS
Royalty OS
governance review
appeals panels
dispute-aware accountability systems
Security considerations

Implementers should pay special attention to the following risks.

1. Frivolous or malicious disputes

Attackers may file noise disputes to degrade trust or slow decision-making.

2. Unauthorized revocation

A revoke action asserted by an unqualified actor may cause improper withdrawal of reliance.

3. Chain tampering

If registry history is mutable without trace, dispute lineage can be falsified.

4. Target swapping

A target URI alone is not enough when integrity matters. Hash anchoring should be used.

5. Policy ambiguity

The same action may have different meanings under different governance regimes.

6. Actor impersonation

If actor identity is weak, lifecycle actions can be forged or misattributed.

Privacy considerations

This specification can support privacy-preserving implementations.

For example:

actors may use organizational or pseudonymous identifiers where policy allows
evidence may be partially confidential
systems may rely on hash references rather than public evidence disclosure

Still, enough information should remain available to verify:

actor traceability,
target binding,
action meaning,
and governance lineage.
Intended downstream integrations

Dispute Registry v0.1 is designed to serve as a governance layer for systems such as:

Signed Impact Attestation
Impact Score Profile
Existence Proof OS
Trust OS
Gratitude OS
Royalty OS
Communication Royalty OS
CTR-ID-linked trace infrastructures

It is intentionally small, so it can be reused across multiple accountability ecosystems.

Relationship to Signed Impact Attestation

This specification is especially compatible with Signed Impact Attestation v0.2.

A typical flow looks like this:

an impact evaluation is issued,
a responsible issuer signs it,
the issuer is bound to an existence proof,
a dispute or lifecycle event is later recorded in the dispute registry.

In that sense:

Signed Impact Attestation defines the accountable claim
Dispute Registry defines the governable afterlife of that claim

These two layers work well together, but they are intentionally kept separate.

Versioning

This repository currently defines:

dispute-registry-v0.1

Future versions may add:

richer dispute chains
stronger authority semantics
clearer appeal workflows
explicit resolution linkage
multi-signature governance support
verifier-oriented summaries
Status

Current status:

Version: 0.1
Specification state: draft
Document type: normative specification

This repository is intended as a foundational governance primitive for dispute-aware accountability infrastructures.

Philosophy in one sentence

If accountability creates a responsible claim, dispute registry keeps that claim governable over time.

License

Unless otherwise specified in repository files, the specification text is intended to be released under:

CC-BY-4.0

Check repository files for the final applicable license configuration.


---

## GitHub Description

**A minimal, append-only, portable, and auditable registry format for recording disputes, supersessions, revocations, reaffirmations, and related lifecycle actions against accountability artifacts.**

短めにするならこちらでもよいです。

**Dispute Registry v0.1: an append-only governance layer for disputes, revocations, supersessions, and resolutions across accountability artifacts.**

---

## Topics

```text
dispute-registry
accountability
governance
auditability
traceability
append-only
json-schema
yaml-spec
signed-impact-attestation
existence-proof
trust-os
royalty-os
gratitude-os
ai-governance
lifecycle-management