# Processes and Data Structures
This document is the working place to define the key data structures for Rho.
The goal is to make the main manifests and core types explicit before implementation hardens them in Rust code.
In many senses this is the most important thing as this defines what data and steps matter at each level of abstraction.
### Identity
Represents a person, org, or agent owner.
Minimum v1 fields:
Suggested split:
Keep public identity separate from local key storage and peer trust state.
#### Identity
Public and portable.
See also:
- [url-schema.md](/Users/madhavajay/dev/rho/main/docs/architecture/url-schema.md)
Suggested fields:
- `version`
- `id`
- `kind`
- `handle`
- `display_name`
- `public_keys`
- `proofs`
- `created_at`
Example:
```yaml
version: 1
identity:
id: rho://id/github/madhavajay
kind: github
handle: madhavajay
display_name: Madhava Jay
public_keys:
- id: rho://key/github/madhavajay/ssh-ed25519-1
kind: ssh-signing
algorithm: ssh-ed25519
public_key: ssh-ed25519 AAAA...
fingerprint: SHA256:...
created_at: 2026-04-08T00:00:00Z
proofs:
- kind: github-profile-fragment-claim
provider_url: https://github.com/madhavajay
claim: rho.claim/id/github/madhavajay/key/ssh-ed25519/sha256-...
proof_url: https://github.com/madhavajay#rho.claim/id/github/madhavajay/key/ssh-ed25519/sha256-...
verified_at:
```
Notes:
- `id` identifies the actor, not a specific key.
- A single identity may have more than one public key.
- Proofs bind the identity to external systems such as GitHub.
#### Local Identity Profile
Local machine state for using an identity.
Suggested fields:
- `version`
- `identity_id`
- `profile_name`
- `key_ref`
- `resolver_hints`
- `storage_backend`
- `is_default`
Example:
```yaml
version: 1
local_identity_profile:
identity_id: rho://id/github/madhavajay
signing_key:
kind: ssh-signing
algorithm: ssh-ed25519
public_key_path: ~/.ssh/id_ed25519.pub
private_key_ref:
backend: ssh-file
path: ~/.ssh/id_ed25519
resolver_hints:
- ~/.ssh/
- ~/.rho/keys/github/madhavajay/
storage_backend: file
```
Notes:
- Do not treat `private key location` as part of the portable identity.
- Prefer `key_ref` plus resolver logic over one fixed path.
- Later backends may include keychain, TPM, Secure Enclave, agent process, or plugin-based auth.
#### Peer Identity Bundle
Imported or fetched public identity material.
Suggested fields:
- `version`
- `identity_id`
- `public_keys`
- `proofs`
- `claims`
- `fetched_from`
- `fetched_at`
Notes:
- This is what another user can share or what `rho id fetch` can resolve.
- Trust in this bundle should be handled by `rho auth`, not `rho id`.
### Crypto Key
Lets start with some reasonable cryptography
### Repo Layout
Root manifest:
```yaml
rho: 1
project:
id: rho://repo/github/org/project
name: example-project
owner: rho://id/github/rho-owner
transport:
kind: git
provider: github
repo:
owner: org
name: project
members:
file: rho/membership.yaml
participants:
path: rho/participants/
permissions:
file: rho/policy/permissions.yaml
crypto:
file: rho/policy/crypto.yaml
auth:
file: rho/policy/auth.yaml
tools:
path: rho/tools/
resources:
file: rho/resources.yaml
```
The root manifest is the discovery document. It should identify the logical
project and point to the rest of the protocol files without encoding each user's
local Git remote URL.
### Repo Permissions
```yaml
version: 1
permissions:
- id: direct_inbox
pattern: rho/messages/inbox/{member.handle}/**
expand: members
write:
allowed:
- members
read:
encrypted_to:
- "{member.id}"
- id: group_messages
pattern: rho/messages/groups/{group.id}/**
expand: groups
write:
allowed:
- "{group.members}"
read:
encrypted_to:
- "{group.members}"
- id: public_workspace
pattern: workspace/public/**
write:
allowed:
- members
read:
public: true
```
Permissions are the source of truth for normal read/write path semantics.
Private read permissions imply recipient encryption. Public read permissions do
not require encryption.
### Auth
- handshake
- tofu
### Tools
### Messages
My Data Structures
- run yaml template
- tools
Suggested fields:
- `id`
- `version`
- `description`
- `inputs`
- `outputs`
- `runner`
- `sandbox`
- `approval`
# Shared Model
## Purpose
This document defines the concepts that every `rho` command should share.
### Crypto Policy
Represents how artifacts are signed or encrypted.
Minimum v1 fields:
- policy id
- mode
- recipients
- signing requirement
- encryption requirement
### Auth Policy
Represents who may do what in a repo or interaction context.
Minimum v1 fields:
- policy id
- subject
- action
- resource
- decision
- conditions
### Repo
A collaboration space backed by Git.
Minimum v1 concerns:
- repo metadata
- participant list
- permissions policy
- crypto algorithm policy
- auth policy
- message roots
- tool roots
### Tool
A named contract for an allowed capability.
Minimum v1 fields:
- tool id
- version
- input schema
- output schema
- execution mode
- policy requirements
### Message
A file-backed communication artifact between participants or agents.
Minimum v1 fields:
- message id
- from
- to
- created_at
- type
- body
### Request
A structured ask for a protected action.
Examples:
- run a tool
- read a protected path
- release an output
- contact a human approver
### Approval
A structured decision attached to a request.
Minimum v1 fields:
- request id
- decision
- decided_by
- decided_at
- reason
### Trust Record
A structured record of trust or distrust toward a peer.
Minimum v1 fields:
- peer id
- key fingerprint
- trust state
- paired_at
- paired_by
- block state
- notes
### Run
A concrete execution of a tool or agent task.
Minimum v1 fields:
- run id
- subject
- command or tool ref
- sandbox profile
- status
- output refs
### Diagnostic Check
A structured environment or readiness check.
Minimum v1 fields:
- check id
- category
- status
- details
- suggested fix
## Default Repo Layout
V1 should use one obvious hidden root:
```text
rho/
repo.yaml
identities/
crypto/
auth/
tools/
messages/
inbox/
outbox/
requests/
approvals/
runs/
data/
mock/
private/
released/
middleware/
```
This is intentionally simpler than the older systems.
## State Transitions That Must Stay Explicit
Rho should make these transitions visible:
- local draft -> repo message
- plaintext artifact -> signed or encrypted artifact
- repo message -> interpreted action request
- actor identity and key -> trusted, pending, or blocked peer state
- action request -> approval pending
- approval pending -> approved or denied
- approved -> sandbox run
- sandbox output -> released output
- private input -> mock derivative
## Cross-Cutting Rules
- Every file-backed artifact should have a version field.
- Protected actions should have typed request manifests.
- Middleware should consume requests, not arbitrary free text.
- Agents should read prompts and messages, but protected execution should depend on structured manifests.
## How To Use This Doc
For each structure, capture:
- purpose
- owner command or layer
- canonical file path or storage location
- required fields
- optional fields
- validation rules
- notes on future migration
## Candidate Core Structures
### Identity
- purpose:
- owner:
- canonical path:
- required fields:
- optional fields:
- validation rules:
- migration notes:
### Peer Identity Bundle
- purpose:
- owner:
- canonical path:
- required fields:
- optional fields:
- validation rules:
- migration notes:
### Crypto Policy
- purpose:
- owner:
- canonical path:
- required fields:
- optional fields:
- validation rules:
- migration notes:
### Auth Policy
- purpose:
- owner:
- canonical path:
- required fields:
- optional fields:
- validation rules:
- migration notes:
### Trust Record
- purpose:
- owner:
- canonical path:
- required fields:
- optional fields:
- validation rules:
- migration notes:
### Block Record
- purpose:
- owner:
- canonical path:
- required fields:
- optional fields:
- validation rules:
- migration notes:
### Repo Manifest
- purpose:
- owner:
- canonical path:
- required fields:
- optional fields:
- validation rules:
- migration notes:
### Participant Record
- purpose:
- owner:
- canonical path:
- required fields:
- optional fields:
- validation rules:
- migration notes:
### Tool Manifest
- purpose:
- owner:
- canonical path:
- required fields:
- optional fields:
- validation rules:
- migration notes:
### Message
- purpose:
- owner:
- canonical path:
- required fields:
- optional fields:
- validation rules:
- migration notes:
### Request
- purpose:
- owner:
- canonical path:
- required fields:
- optional fields:
- validation rules:
- migration notes:
### Approval
- purpose:
- owner:
- canonical path:
- required fields:
- optional fields:
- validation rules:
- migration notes:
### Run Record
- purpose:
- owner:
- canonical path:
- required fields:
- optional fields:
- validation rules:
- migration notes:
### Data Registry Entry
- purpose:
- owner:
- canonical path:
- required fields:
- optional fields:
- validation rules:
- migration notes:
### Diagnostic Check Result
- purpose:
- owner:
- canonical path:
- required fields:
- optional fields:
- validation rules:
- migration notes:
## Notes
- Every file-backed structure should carry a version field.
- Structures that cross trust boundaries should be designed for deterministic validation.
- If a structure is only derived and never authoritative, note that explicitly.