# 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.
