# jkigozi/hip-tp architecture

> Architecture diagram of the GitHub repository jkigozi/hip-tp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jkigozi/hip-tp
- Repository: https://github.com/jkigozi/hip-tp

## Overview

HiP is a proposed institutional architecture for preserving non-winning machine-generated candidates and reopening them when their viability conditions change. Its principal workflow records why pursuit stopped, retains the candidate and its closure rationale, monitors later signals, and governs possible re-entry across projects and institutions. The repository also includes an executable historical replay that validates archived objects, applies deterministic reopening rules to event streams, and compares computed decisions with outcomes. The replay code was sampled; the broader institutional stages are represented as documented capabilities, not inspected implementations.

Main entry points: [`replay/v0.3.2/run_historical_replay_v0.3.2.py`](https://github.com/jkigozi/hip-tp/blob/main/replay/v0.3.2/run_historical_replay_v0.3.2.py) (Replay harness), [`docs/architecture/security_and_custody.md`](https://github.com/jkigozi/hip-tp/blob/main/docs/architecture/security_and_custody.md) (Candidate custody), [`docs/architecture/temporal_engines.md`](https://github.com/jkigozi/hip-tp/blob/main/docs/architecture/temporal_engines.md) (Prospective engine), [`replay/v0.3.2/check_multidecade_custody_conformance_v0.3.2.py`](https://github.com/jkigozi/hip-tp/blob/main/replay/v0.3.2/check_multidecade_custody_conformance_v0.3.2.py) (Custody conformance check)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_custody["Candidate custody"]
  node_disposition["Disposition record"]
  node_closure["Causal closure"]
  node_candidate[("Candidate custody")]
end

subgraph group_discovery["Temporal discovery"]
  node_viability["Viability environments"]
  node_retrospective["Retrospective engine"]
  node_monitoring["Change monitoring"]
  node_prospective["Prospective engine"]
  node_reentry["Re-entry decision"]
end

subgraph group_governance["Governance and federation"]
  node_governance["Governance envelope"]
  node_federation["Institutional federation"]
end

subgraph group_replay["Historical replay"]
  node_replay_runner["Replay harness"]
  node_replay_rules["Replay rules"]
  node_replay_objects["Historical objects"]
  node_replay_events["Historical events"]
  node_replay_outcomes["Historical outcomes"]
  node_replay_schemas["Replay schemas<br/>[schemas]"]
  node_custody_check["Custody conformance check"]
end

node_initiators(("Models and projects"))

node_initiators -->|"records stopping"| node_disposition
node_disposition -->|"preserves rationale"| node_closure
node_closure -->|"retains candidate"| node_candidate
node_candidate -->|"monitors conditions"| node_monitoring
node_viability -->|"sets conditions"| node_prospective
node_monitoring -->|"prospects changes"| node_prospective
node_prospective -->|"assesses reopening"| node_reentry
node_governance -->|"governs re-entry"| node_reentry
node_candidate -->|"custodies across institutions"| node_federation
node_replay_runner -->|"imports rules"| node_replay_rules
node_replay_runner -->|"loads objects"| node_replay_objects
node_replay_runner -->|"loads events"| node_replay_events
node_replay_runner -->|"loads outcomes"| node_replay_outcomes
node_replay_runner -->|"validates against"| node_replay_schemas
node_replay_runner -->|"applies reopening rules"| node_replay_rules
node_custody_check -->|"loads objects"| node_replay_objects
node_custody_check -->|"validates against"| node_replay_schemas

click node_disposition "https://github.com/jkigozi/hip-tp/tree/main/schemas"
click node_closure "https://github.com/jkigozi/hip-tp/tree/main/schemas"
click node_candidate "https://github.com/jkigozi/hip-tp/blob/main/docs/architecture/security_and_custody.md"
click node_viability "https://github.com/jkigozi/hip-tp/blob/main/docs/architecture/canonical_hypothesis_object.md"
click node_retrospective "https://github.com/jkigozi/hip-tp/blob/main/docs/architecture/temporal_engines.md"
click node_monitoring "https://github.com/jkigozi/hip-tp/tree/main/docs/architecture"
click node_prospective "https://github.com/jkigozi/hip-tp/blob/main/docs/architecture/temporal_engines.md"
click node_reentry "https://github.com/jkigozi/hip-tp/blob/main/docs/architecture/temporal_engines.md"
click node_governance "https://github.com/jkigozi/hip-tp/blob/main/schemas/HiP_Governance_Envelope.schema.json"
click node_federation "https://github.com/jkigozi/hip-tp/blob/main/docs/architecture/institutional_discovery_architecture.md"
click node_replay_runner "https://github.com/jkigozi/hip-tp/blob/main/replay/v0.3.2/run_historical_replay_v0.3.2.py"
click node_replay_rules "https://github.com/jkigozi/hip-tp/blob/main/replay/v0.3.2/hip_replay_rules_v0_3_2.py"
click node_replay_objects "https://github.com/jkigozi/hip-tp/blob/main/replay/v0.3.2/objects/HiP_Historical_Objects_v0.3.2.json"
click node_replay_events "https://github.com/jkigozi/hip-tp/blob/main/replay/v0.3.2/events/HiP_Historical_Events_v0.3.2.json"
click node_replay_outcomes "https://github.com/jkigozi/hip-tp/blob/main/replay/v0.3.2/outcomes/HiP_Historical_Outcomes_v0.3.2.json"
click node_replay_schemas "https://github.com/jkigozi/hip-tp/tree/main/replay/v0.3.2/schemas"
click node_custody_check "https://github.com/jkigozi/hip-tp/blob/main/replay/v0.3.2/check_multidecade_custody_conformance_v0.3.2.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_disposition,node_closure,node_candidate toneBlue
class node_viability,node_retrospective,node_monitoring,node_prospective,node_reentry toneAmber
class node_governance,node_federation toneMint
class node_replay_runner,node_replay_rules,node_replay_objects,node_replay_events,node_replay_outcomes,node_replay_schemas,node_custody_check toneRose
class node_initiators toneIndigo
```

## Components

### Candidate custody

- [Disposition record](https://github.com/jkigozi/hip-tp/tree/main/schemas): `schemas`
- [Causal closure](https://github.com/jkigozi/hip-tp/tree/main/schemas): `schemas`
- [Candidate custody](https://github.com/jkigozi/hip-tp/blob/main/docs/architecture/security_and_custody.md): `docs/architecture/security_and_custody.md`

### Temporal discovery

- [Viability environments](https://github.com/jkigozi/hip-tp/blob/main/docs/architecture/canonical_hypothesis_object.md): `docs/architecture/canonical_hypothesis_object.md`
- [Retrospective engine](https://github.com/jkigozi/hip-tp/blob/main/docs/architecture/temporal_engines.md): `docs/architecture/temporal_engines.md`
- [Change monitoring](https://github.com/jkigozi/hip-tp/tree/main/docs/architecture): `docs/architecture`
- [Prospective engine](https://github.com/jkigozi/hip-tp/blob/main/docs/architecture/temporal_engines.md): `docs/architecture/temporal_engines.md`
- [Re-entry decision](https://github.com/jkigozi/hip-tp/blob/main/docs/architecture/temporal_engines.md): `docs/architecture/temporal_engines.md`

### Governance and federation

- [Governance envelope](https://github.com/jkigozi/hip-tp/blob/main/schemas/HiP_Governance_Envelope.schema.json): `schemas/HiP_Governance_Envelope.schema.json`
- [Institutional federation](https://github.com/jkigozi/hip-tp/blob/main/docs/architecture/institutional_discovery_architecture.md): `docs/architecture/institutional_discovery_architecture.md`

### Historical replay

- [Replay harness](https://github.com/jkigozi/hip-tp/blob/main/replay/v0.3.2/run_historical_replay_v0.3.2.py): `replay/v0.3.2/run_historical_replay_v0.3.2.py`
- [Replay rules](https://github.com/jkigozi/hip-tp/blob/main/replay/v0.3.2/hip_replay_rules_v0_3_2.py): `replay/v0.3.2/hip_replay_rules_v0_3_2.py`
- [Historical objects](https://github.com/jkigozi/hip-tp/blob/main/replay/v0.3.2/objects/HiP_Historical_Objects_v0.3.2.json): `replay/v0.3.2/objects/HiP_Historical_Objects_v0.3.2.json`
- [Historical events](https://github.com/jkigozi/hip-tp/blob/main/replay/v0.3.2/events/HiP_Historical_Events_v0.3.2.json): `replay/v0.3.2/events/HiP_Historical_Events_v0.3.2.json`
- [Historical outcomes](https://github.com/jkigozi/hip-tp/blob/main/replay/v0.3.2/outcomes/HiP_Historical_Outcomes_v0.3.2.json): `replay/v0.3.2/outcomes/HiP_Historical_Outcomes_v0.3.2.json`
- [Replay schemas](https://github.com/jkigozi/hip-tp/tree/main/replay/v0.3.2/schemas): `replay/v0.3.2/schemas`
- [Custody conformance check](https://github.com/jkigozi/hip-tp/blob/main/replay/v0.3.2/check_multidecade_custody_conformance_v0.3.2.py): `replay/v0.3.2/check_multidecade_custody_conformance_v0.3.2.py`

### Other components

- **Models and projects**

## Connections

- Models and projects → Disposition record: records stopping (evidence: `README.md`)
- Disposition record → Causal closure: preserves rationale (evidence: `README.md`)
- Causal closure → Candidate custody: retains candidate (evidence: `README.md`)
- Candidate custody → Change monitoring: monitors conditions (evidence: `README.md`)
- Viability environments → Prospective engine: sets conditions (evidence: `README.md`)
- Change monitoring → Prospective engine: prospects changes (evidence: `README.md`)
- Prospective engine → Re-entry decision: assesses reopening (evidence: `README.md`)
- Governance envelope → Re-entry decision: governs re-entry (evidence: `README.md`)
- Candidate custody → Institutional federation: custodies across institutions (evidence: `README.md`)
- Replay harness → Replay rules: imports rules (evidence: `replay/v0.3.2/run_historical_replay_v0.3.2.py`)
- Replay harness → Historical objects: loads objects (evidence: `replay/v0.3.2/run_historical_replay_v0.3.2.py`)
- Replay harness → Historical events: loads events (evidence: `replay/v0.3.2/run_historical_replay_v0.3.2.py`)
- Replay harness → Historical outcomes: loads outcomes (evidence: `replay/v0.3.2/run_historical_replay_v0.3.2.py`)
- Replay harness → Replay schemas: validates against (evidence: `replay/v0.3.2/run_historical_replay_v0.3.2.py`)
- Replay harness → Replay rules: applies reopening rules (evidence: `replay/v0.3.2/run_historical_replay_v0.3.2.py`)
- Custody conformance check → Historical objects: loads objects (evidence: `replay/v0.3.2/check_multidecade_custody_conformance_v0.3.2.py`)
- Custody conformance check → Replay schemas: validates against (evidence: `replay/v0.3.2/check_multidecade_custody_conformance_v0.3.2.py`)
